Docs Menu
class: ActorLocator
Specialized locators for querying and interacting with spatial 3D objects in the Unreal world. Extends the base SpecterLocator and features native Gameplay Ability System (GAS) integration.
actor.getLocation
Retrieves the current 3D world coordinates of the actor.
const startPos = await enemy.getLocation();Returns:Promise<Vector3>
actor.waitForGameplayTag
Waits until the actor possesses the specified Gameplay Tag. Useful for verifying status effects like stuns or buffs.
await player.waitForGameplayTag("Status.Stunned");Arguments
| Name | Type | Description |
|---|---|---|
| tag | string | The exact Gameplay Tag string to wait for. |
Returns:Promise<void>
actor.triggerAbilityByTag
Locates an ability on the actor's Ability System Component that matches the tag and explicitly triggers it.
await player.triggerAbilityByTag("Ability.Slot.Q");Arguments
| Name | Type | Description |
|---|---|---|
| tag | string | The tag identifying the ability (e.g. Ability.Slot.Q). |
Returns:Promise<void>
Transform & Spatial
Methods for interacting with the actor's 3D position and rotation in the world.
actor.getLocation
Retrieves the actor's current 3D world location.
const pos = await player.getLocation();
console.log(pos.x, pos.y, pos.z);Returns:Promise<Vector3>
actor.getForwardVector
Retrieves the actor's normalized forward directional vector.
const forward = await player.getForwardVector();Returns:Promise<Vector3>
actor.setLocation
Teleports the actor to a new 3D world location.
await player.setLocation({ x: 0, y: 0, z: 1000 });Arguments
| Name | Type | Description |
|---|---|---|
| location | Vector3 | The target {x, y, z} coordinate. |
Returns:Promise<void>
actor.setRotation
Teleports the actor to a new rotation.
await player.setRotation({ pitch: 0, yaw: 90, roll: 0 });Arguments
| Name | Type | Description |
|---|---|---|
| rotation | Rotator | The target {pitch, yaw, roll} rotation. |
Returns:Promise<void>
actor.setTransform
Teleports the actor to a new full transform (location, rotation, and scale).
await player.setTransform({ location: { x: 0, y: 0, z: 0 }, rotation: { pitch: 0, yaw: 0, roll: 0 }, scale: { x: 1, y: 1, z: 1 } });Arguments
| Name | Type | Description |
|---|---|---|
| transform | Transform | The target transform object. |
Returns:Promise<void>
State & Testing
actor.highlight
Visually highlights the actor in the engine using a debug wireframe and floating text. Extremely useful for debugging tests visually!
await boss.highlight("Target Acquired!");Arguments
| Name | Type | Description |
|---|---|---|
| stateInfo optional | string | Text to float above the actor. |
Returns:Promise<void>
actor.checkVisibility
Checks if the actor's mesh is actively rendering. If checkOnScreen is true, verifies it is within the camera frustum.
const isVisible = await boss.checkVisibility(true);Arguments
| Name | Type | Description |
|---|---|---|
| checkOnScreen optional | boolean | Whether to require it to be on-screen. |
Returns:Promise<boolean>
actor.isLocallyControlled
Returns a new narrowed locator that filters the current set of actors down to only those possessed by the local human player. Perfect for filtering out AI Bots in Lyra!
const localPlayer = world.actor('BP_Hero_Shooter').isLocallyControlled(true);Arguments
| Name | Type | Description |
|---|---|---|
| locallyControlled optional | boolean | Whether to filter for locally controlled (true) or non-locally controlled (false). |
Returns:ActorLocator
actor.getPlayerId
Retrieves the unique Player ID associated with the actor's PlayerState.
const id = await player.getPlayerId();Returns:Promise<number>
actor.getByComponent
Traverses down the hierarchy to find a specific component on this actor, returning a strongly-typed specialized locator (e.g. SkeletonLocator or MovementLocator).
const skeleton = player.getByComponent("Skeleton");
await expect(skeleton).toHaveBoneRotation("head", { pitch: 0, yaw: 90, roll: 0 });Arguments
| Name | Type | Description |
|---|---|---|
| componentType | string | The component type key (e.g. 'Skeleton', 'CharacterMovement'). |
| options optional | object | Filters like name or exact UE class. |
Returns:ComponentLocator
Gameplay Ability System (GAS)
actor.getAttributeValue
Reads the current float value of a GAS Attribute.
const health = await player.getAttributeValue("HealthSet", "Health");Arguments
| Name | Type | Description |
|---|---|---|
| attributeSet | string | The Attribute Set class name. |
| attributeName | string | The specific attribute name. |
Returns:Promise<number>
actor.hasGameplayTag
Checks if the actor's Ability System Component currently possesses the specified Gameplay Tag.
const isStunned = await player.hasGameplayTag("Status.Stunned");Arguments
| Name | Type | Description |
|---|---|---|
| tag | string | The tag to check. |
Returns:Promise<boolean>
actor.getGameplayTags
Returns all Gameplay Tags currently owned by the actor's Ability System Component via IGameplayTagAssetInterface.
const tags = await enemy.getGameplayTags();
console.log(tags); // ['Status.Stunned', 'Status.Burning']Returns:Promise<string[]>
actor.waitForGameplayTag
Waits asynchronously for a Gameplay Tag to be added or removed from the actor.
// Wait for the stun tag to be applied
await boss.waitForGameplayTag("Status.Stunned", true);Arguments
| Name | Type | Description |
|---|---|---|
| tag | string | The tag to wait for. |
| expectedState | boolean | True to wait for addition, false to wait for removal. |
| timeout optional | number | Timeout in milliseconds (Default: 5000). |
Returns:Promise<boolean>
actor.waitForAttributeValue
Waits for a Gameplay Attribute to reach a specific value, tracking its history.
const result = await player.waitForAttributeValue("HealthSet", "Health", 0);
console.log("Health dropped to 0! History:", result.history);Arguments
| Name | Type | Description |
|---|---|---|
| attributeSet | string | The Attribute Set class name. |
| attributeName | string | The specific attribute name. |
| expectedValue | number | The value to wait for. |
| timeout optional | number | Timeout in milliseconds (Default: 5000). |
Returns:Promise<{ finalValue: number, history: number[] }>
actor.triggerAbilityByTag
Triggers a Gameplay Ability on the actor by its input tag.
await player.triggerAbilityByTag("Ability.Attack.Melee");Arguments
| Name | Type | Description |
|---|---|---|
| inputTag | string | The ability input tag. |
Returns:Promise<void>
actor.triggerAbilityWithTarget
Triggers a Gameplay Ability and passes a target data payload (either an ActorLocator or a Vector3 location).
await player.triggerAbilityWithTarget("Ability.Spell.Fireball", boss);Arguments
| Name | Type | Description |
|---|---|---|
| abilityTag | string | The ability tag. |
| target | SpecterLocator | Vector3 | The target locator or 3D coordinate. |
Returns:Promise<void>
actor.applyGameplayEffect
Directly applies a Gameplay Effect class to the actor's Ability System Component.
await player.applyGameplayEffect("/Game/Effects/GE_Damage_Poison.GE_Damage_Poison_C");Arguments
| Name | Type | Description |
|---|---|---|
| effectClassPath | string | The class path of the Gameplay Effect. |
| level optional | number | The effect level (Default: 1.0). |
Returns:Promise<void>
actor.hasActiveGameplayEffect
Checks if a specific Gameplay Effect class is currently active on the actor.
const isPoisoned = await player.hasActiveGameplayEffect("/Game/Effects/GE_Damage_Poison.GE_Damage_Poison_C");Arguments
| Name | Type | Description |
|---|---|---|
| effectClassPath | string | The class path of the Gameplay Effect. |
Returns:Promise<boolean>
Input Simulation
actor.playSequence
Plays a mathematically accurate frame-by-frame SpecterInputSequence directed at this actor's input component.
import { SpecterInputSequence } from '@specter/test';
const accelerate = new SpecterInputSequence()
.addAxisSweep('Gamepad_RightTrigger', 0.0, 1.0, 0, 2000);
await playerCar.playSequence(accelerate);Arguments
| Name | Type | Description |
|---|---|---|
| sequence | SpecterInputSequence | The input sequence to play. |
| options optional | Object | { loops?: number } The number of times to loop the sequence. |
Returns:Promise<void>
actor.pressKey
Simulates a raw hardware key press directed at this actor's input component.
// Quick press
await player.pressKey("SpaceBar");
// Hold the button for 500ms
await player.pressKey("Gamepad_FaceButton_Bottom", { holdMs: 500 });Arguments
| Name | Type | Description |
|---|---|---|
| key | UnrealKey | The UE key name (e.g. 'SpaceBar', 'Gamepad_FaceButton_Bottom'). |
| options optional | Object | { holdMs?: number } How long to hold the key before releasing it. |
Returns:Promise<void>
actor.injectAxis
Injects a raw analog value directly into this specific actor's Input Component. Ideal for simulating fine analog movements like slightly tilting a gamepad thumbstick or partially pulling a trigger.
// Pull the right trigger 10% on a specific player's controller
await playerActor.injectAxis('Gamepad_RightTrigger', 0.1);Arguments
| Name | Type | Description |
|---|---|---|
| axisName | string | The name of the axis binding (e.g. 'Gamepad_RightTrigger'). |
| value | number | The float value to inject (typically -1.0 to 1.0). |
Returns:Promise<void>
actor.type
Simulates typing a string of text sequentially by sending Pressed and Released events for each character.
await player.type("Hello Specter!");Arguments
| Name | Type | Description |
|---|---|---|
| text | string | The string of text to type. |
| delayMs optional | number | Optional delay between keystrokes. |
Returns:Promise<void>
Enhanced Input (UE5)
Methods for querying and triggering UE5 Enhanced Input Subsystem actions and mapping contexts.
actor.triggerInputAction
Triggers a UE5 Enhanced Input Action (UInputAction) on the actor's Enhanced Input Local Player Subsystem.
// Trigger a digital jump action
await player.triggerInputAction('IA_Jump', true);
// Trigger a 2D analog movement vector payload
await player.triggerInputAction('IA_Move', { x: 0.0, y: 1.0, z: 0.0 });Arguments
| Name | Type | Description |
|---|---|---|
| action | string | The Input Action asset name or path (e.g. 'IA_Jump', 'IA_Move'). |
| value | boolean | number | Vector3 | The input action value payload. |
Returns:Promise<void>
actor.hasInputMappingContext
Checks whether a UE5 Input Mapping Context (UInputMappingContext) is actively applied to the player's Enhanced Input Subsystem.
const hasIMC = await player.hasInputMappingContext("IMC_DefaultPlayer");Arguments
| Name | Type | Description |
|---|---|---|
| context | string | Short context asset name (e.g. 'IMC_DefaultPlayer') or full asset path. |
Returns:Promise<boolean>
actor.getInputActionValue
Retrieves the current evaluated value of a UE5 Enhanced Input Action.
const info = await player.getInputActionValue("IA_Sprint");
console.log("Bool state:", info.boolValue);Arguments
| Name | Type | Description |
|---|---|---|
| action | string | Short action asset name (e.g. 'IA_Sprint') or asset path. |
Returns:Promise<{ value: number, boolValue: boolean, vector: Vector3 }>
Camera & FOV
Methods for querying and controlling camera properties, field of view, and camera shakes.
actor.getCameraFOV
Retrieves the current Field of View angle from the actor's camera component, player camera manager, or the actor's own camera.
const fov = await player.getCameraFOV(); // default: 90Returns:Promise<number>
actor.setCameraFOV
Sets the Field of View angle on the actor's camera component, camera manager, or the actor's own camera.
await player.setCameraFOV(110);Arguments
| Name | Type | Description |
|---|---|---|
| fov | number | The FOV angle in degrees. |
Returns:Promise<void>
actor.isCameraShaking
Checks whether the actor's PlayerCameraManager currently has any active camera shakes playing.
const shaking = await player.isCameraShaking();Returns:Promise<boolean>
actor.getCameraViewTarget
Returns the name of the actor currently being viewed through this actor's camera.
const target = await player.getCameraViewTarget();Returns:Promise<string>
AI & Navigation
Methods for querying AI pathfinding state and navigation goals.
Team System
Methods for querying the Generic Team Agent Interface (IGenericTeamAgentInterface).
actor.getTeamId
Returns the Generic Team ID of the actor. Checks the actor first, then the pawn's controller. Returns 255 for NoTeam.
const teamId = await player.getTeamId(); // 255 = NoTeamReturns:Promise<number>
actor.getTeamAttitudeTowards
Evaluates this actor's team attitude towards another actor using the Generic Team Agent Interface.
const attitude = await player.getTeamAttitudeTowards(enemy);
// Returns: 'Friendly' | 'Hostile' | 'Neutral'Arguments
| Name | Type | Description |
|---|---|---|
| otherActor | ActorLocator | The other actor to evaluate attitude towards. |
Returns:Promise<string>
Interfaces
Vector3
interface Vector3 {
x: number;
y: number;
z: number;
}Rotator
interface Rotator {
pitch: number;
yaw: number;
roll: number;
}Transform
interface Transform {
location: Vector3;
rotation?: Rotator;
scale?: Vector3;
}