Actions & Interactions

1. Getting a Value (No Arguments, Complex Return)

Because callFunction automatically serializes Unreal Engine structs and primitives, you can easily pull data like FVector directly into TypeScript.

// Calls Unreal's K2_GetActorLocation and automatically parses the FVector return
const location = await actor.callFunction("K2_GetActorLocation");
console.log(`Actor is at X: ${location.X}, Y: ${location.Y}, Z: ${location.Z}`);

2. Setting a Value (With Arguments, No Return)

You can pass arguments exactly matching the Blueprint parameter names (including structs like FVector and FRotator).

// Calls K2_SetActorLocation, passing in a struct and boolean parameters
await actor.callFunction("K2_SetActorLocation", {
    NewLocation: { X: 0, Y: 0, Z: 1000 },
    bSweep: false,
    bTeleport: true,
    SweepHitResult: {} // Required by Unreal's signature
});

3. The Best of Both Worlds (Custom Functions)

This is where the API shines. You can pass inputs in, and read the calculated returnValue or out parameters back out in a single call.

// Suppose you have a custom BP function: CalculateDamage(float BaseDamage, bool bIsCritical) -> float
const damageAmount = await actor.callFunction("CalculateDamage", {
    BaseDamage: 50.0,
    bIsCritical: true
});
console.log(`The final parsed damage is: ${damageAmount}`);

4. Reading Object References

If a function returns an Unreal Engine Object or Actor reference (like an AActor*), callFunction automatically extracts the exact runtime Name of the object and returns it as a string. You can use this to dynamically chain locators!

// 1. Call the Blueprint function to get the equipped weapon.
// Under the hood, C++ sees the AActor* return type, grabs its Name, and passes it to TS.
const weaponName = await actor.callFunction("GetEquippedWeapon");

// 2. Use the returned exact name to create a new Specter ActorLocator
const weapon = world.actor(weaponName);

// 3. Now you have full automation control over the equipped weapon!
const ammo = await weapon.callFunction("GetCurrentAmmo");
await expect(ammo).toBeGreaterThan(0);

5. Passing Object References (Locators)

If a Blueprint function requires an Actor or Object pointer (e.g., FObjectProperty or FClassProperty), you don't have to extract and pass internal string names. Specter natively accepts Locators (like ActorLocator or WidgetLocator) directly into the arguments! Specter serializes the locator's query pipeline and evaluates it against the live game world, piping the exact UObject* pointer directly into the Blueprint virtual machine.

import { test, expect } from '@specter-automation/test';

test('Can assign target actor via Blueprint function', async ({ world }) => {
    // 1. Resolve your actors using locators
    const enemy = world.actor('BP_EnemyBase');
    const player = world.actor('BP_Hero_Steel');

    // 2. Pass the locator natively into the strongly-typed callFunction arguments!
    await enemy.callFunction('SetCurrentTarget', {
        TargetActor: player 
    });
});

Note: The "Generate Specter TS Types" tool automatically types these Blueprint properties as SpecterLocator | string, ensuring full compile-time validation.

6. Passing Static Assets (Textures, Materials, etc.)

If a Blueprint function requires an Asset pointer (e.g., UTexture2D* or UDataAsset*), you cannot use a Locator because the asset is not a live object in the world. Instead, you can pass its string path.

import { test, expect } from '@specter-automation/test';

test('Can update terrain weightmap via Blueprint function', async ({ world }) => {
    const terrain = world.actor('BP_DynamicTerrain');

    // Pass the exact string from Unreal's "Copy Reference" action!
    // Specter will automatically strip the prefix, dynamically load the asset, 
    // and pass the correct UTexture* to the Blueprint VM.
    await terrain.callFunction('SetWeightmap', {
        Weightmap_RT: "Texture2D'/Game/Environment/Textures/RT_Weightmap.RT_Weightmap'"
    });
});

Note: Just like locators, the "Generate Specter TS Types" tool types these properties as SpecterLocator | string to support this pattern.

7. Type-Safe Blueprint Reflection & Overloaded callFunction

Specter's reflection engine extracts UFUNCTION metadata directly from Unreal Engine reflection tables, generating TypeScript overloads that enforce compile-time verification across all actor components and sub-objects (such as HotsHeroComponent).

import { test, expect } from '@specter-automation/test';

test('Select talent via type-safe Blueprint reflection', async ({ world, playerActor }) => {
    // 1. Query the specific actor component
    const heroComponent = playerActor.getComponent('HotsHeroComponent');

    // 2. Type-safe callFunction with autocomplete on function names, argument objects, and return types
    await heroComponent.callFunction('SelectTalent', {
        TalentTier: 1,
        TalentIndex: 0
    });

    // 3. Query return value with full compile-time type inference
    const selectedTalent = await heroComponent.callFunction('GetSelectedTalent', {
        TalentTier: 1
    });
    expect(selectedTalent).toBe('Talent_ShieldBash_Cooldown');
});

Key Benefit: Typos in function names or argument payloads fail immediately at compile time via tsc before running a single frame in Unreal Engine.