unreal_animation

The unreal_animation tool provides programmatic access to Animation Blueprints — inspecting their structure, building state machines, adding states and transitions, assigning animation sequences, tuning blend durations, and validating the result. It exposes 8 operations.

Operations at a Glance

Operation	Hint	Description
`get_info`	readOnly	Get metadata and state list for an Animation Blueprint
`create_state_machine`	—	Create a new state machine inside an Animation Blueprint
`add_state`	—	Add a state node to a state machine
`add_transition`	—	Add a transition between two states
`set_state_animation`	idempotent	Assign a sequence or blend space to a state
`set_transition_duration`	idempotent	Set the blend duration of a transition
`batch`	—	Execute multiple animation operations in one call
`validate_blueprint`	—	Compile and validate an Animation Blueprint

Warning: Never call set_state_animation on states in the MainStates state machine on ABP_Player (Locomotion, Jump, Fall Loop, Land). Those states use ALI_Player Linked Anim Layers. Only use set_state_animation on state machines you created yourself (e.g., CombatStates: HitReact, Death, Stunned, KnockBack, Dodge).

get_info

Returns full metadata for an Animation Blueprint — its state machines, states, transitions, and linked anim layers.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint

{
  "operation": "get_info",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin"
  }
}

Response

{
  "name": "ABP_Enemy_Goblin",
  "skeleton": "/Game/Characters/Enemies/SK_Goblin_Skeleton",
  "state_machines": [
    {
      "name": "MainStates",
      "states": ["Idle", "Walk", "Run", "Attack", "Death"],
      "transitions": [
        { "from": "Idle", "to": "Walk",   "duration": 0.2 },
        { "from": "Walk", "to": "Run",    "duration": 0.15 },
        { "from": "Walk", "to": "Idle",   "duration": 0.25 },
        { "from": "Run",  "to": "Idle",   "duration": 0.3 },
        { "from": "Idle", "to": "Attack", "duration": 0.1 },
        { "from": "Idle", "to": "Death",  "duration": 0.0 }
      ]
    }
  ],
  "linked_anim_layers": [],
  "variables": [
    { "name": "Speed",     "type": "float" },
    { "name": "bIsInAir",  "type": "bool" },
    { "name": "bIsDead",   "type": "bool" }
  ]
}

create_state_machine

Creates a new state machine graph inside an Animation Blueprint.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint
`name`	string	yes	Name for the new state machine

{
  "operation": "create_state_machine",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "name": "CombatStates"
  }
}

Response

{
  "state_machine": "CombatStates",
  "created": true
}

add_state

Adds a state node to an existing state machine.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint
`state_machine`	string	yes	Name of the target state machine
`name`	string	yes	Name for the new state
`position`	object	no	`{ x, y }` position in the state machine graph canvas

{
  "operation": "add_state",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "state_machine": "CombatStates",
    "name": "HitReact",
    "position": { "x": 200, "y": 0 }
  }
}

{
  "operation": "add_state",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "state_machine": "CombatStates",
    "name": "Death",
    "position": { "x": 400, "y": 200 }
  }
}

Response

{
  "state": "HitReact",
  "state_machine": "CombatStates",
  "created": true
}

add_transition

Creates a transition arrow between two states in a state machine.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint
`state_machine`	string	yes	Name of the state machine
`from`	string	yes	Source state name
`to`	string	yes	Destination state name
`duration`	float	no	Blend duration in seconds. Default: 0.2.
`bidirectional`	boolean	no	If true, also creates the reverse transition. Default: false.

{
  "operation": "add_transition",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "state_machine": "CombatStates",
    "from": "Idle",
    "to": "HitReact",
    "duration": 0.1
  }
}

{
  "operation": "add_transition",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "state_machine": "CombatStates",
    "from": "HitReact",
    "to": "Idle",
    "duration": 0.25,
    "bidirectional": false
  }
}

Note: Transitions are one-directional by default. Use bidirectional: true to create both directions in a single call, or call add_transition twice with from and to swapped.

set_state_animation

Assigns an animation asset (sequence, blend space, or montage) to a state. The animation plays while the character is in that state.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint
`state_machine`	string	yes	Name of the state machine
`state`	string	yes	Name of the target state
`animation`	string	yes	Full content path of the animation asset
`loop`	boolean	no	Whether the animation loops. Default: true.
`play_rate`	float	no	Playback rate multiplier. Default: 1.0.

{
  "operation": "set_state_animation",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "state_machine": "CombatStates",
    "state": "HitReact",
    "animation": "/Game/Characters/Enemies/Animations/AS_Goblin_HitReact",
    "loop": false
  }
}

{
  "operation": "set_state_animation",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "state_machine": "CombatStates",
    "state": "Death",
    "animation": "/Game/Characters/Enemies/Animations/AS_Goblin_Death",
    "loop": false,
    "play_rate": 1.0
  }
}

set_transition_duration

Updates the blend duration on an existing transition without rebuilding the transition.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint
`state_machine`	string	yes	Name of the state machine
`from`	string	yes	Source state name
`to`	string	yes	Destination state name
`duration`	float	yes	New blend duration in seconds

{
  "operation": "set_transition_duration",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "state_machine": "CombatStates",
    "from": "HitReact",
    "to": "Idle",
    "duration": 0.15
  }
}

batch

Executes multiple animation operations in a single call. Reduces round-trip overhead when building complex state machines. Operations within a batch run sequentially in order.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint (applied to all ops)
`operations`	array	yes	Ordered list of operation objects. Each has `operation` and `params` (without the `path`).

{
  "operation": "batch",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin",
    "operations": [
      {
        "operation": "create_state_machine",
        "params": { "name": "CombatStates" }
      },
      {
        "operation": "add_state",
        "params": { "state_machine": "CombatStates", "name": "Idle", "position": { "x": 0, "y": 0 } }
      },
      {
        "operation": "add_state",
        "params": { "state_machine": "CombatStates", "name": "HitReact", "position": { "x": 300, "y": 0 } }
      },
      {
        "operation": "add_state",
        "params": { "state_machine": "CombatStates", "name": "Death", "position": { "x": 600, "y": 0 } }
      },
      {
        "operation": "add_transition",
        "params": { "state_machine": "CombatStates", "from": "Idle", "to": "HitReact", "duration": 0.1 }
      },
      {
        "operation": "add_transition",
        "params": { "state_machine": "CombatStates", "from": "HitReact", "to": "Idle", "duration": 0.25 }
      },
      {
        "operation": "add_transition",
        "params": { "state_machine": "CombatStates", "from": "Idle", "to": "Death", "duration": 0.0 }
      }
    ]
  }
}

Response

{
  "results": [
    { "operation": "create_state_machine", "success": true },
    { "operation": "add_state", "state": "Idle",     "success": true },
    { "operation": "add_state", "state": "HitReact", "success": true },
    { "operation": "add_state", "state": "Death",    "success": true },
    { "operation": "add_transition", "from": "Idle",     "to": "HitReact", "success": true },
    { "operation": "add_transition", "from": "HitReact", "to": "Idle",     "success": true },
    { "operation": "add_transition", "from": "Idle",     "to": "Death",    "success": true }
  ],
  "total": 7,
  "succeeded": 7,
  "failed": 0
}

Tip: Use batch when building a complete state machine from scratch. It is significantly faster than individual calls because the Blueprint is only compiled once at the end rather than after each operation.

validate_blueprint

Compiles the Animation Blueprint and returns any compile errors or warnings. Always run this after making structural changes.

Parameters

Parameter	Type	Required	Description
`path`	string	yes	Full content path of the Animation Blueprint

{
  "operation": "validate_blueprint",
  "params": {
    "path": "/Game/Characters/Enemies/ABP_Enemy_Goblin"
  }
}

Response — Success

{
  "compiled": true,
  "errors": [],
  "warnings": [],
  "message": "Compile successful"
}

Response — Failure

{
  "compiled": false,
  "errors": [
    {
      "message": "State 'HitReact' has no animation assigned",
      "state_machine": "CombatStates",
      "state": "HitReact"
    }
  ],
  "warnings": [
    {
      "message": "Transition 'Death -> Idle' will never be taken — Death is a terminal state",
      "state_machine": "CombatStates"
    }
  ]
}

Complete Workflow: Building a Combat State Machine

// 1. Inspect the existing ABP to see what's already there
const info = await get_info({ path: "/Game/Characters/Enemies/ABP_Enemy_Goblin" })

// 2. Build the whole CombatStates machine in one batch call
await batch({
  path: "/Game/Characters/Enemies/ABP_Enemy_Goblin",
  operations: [
    { operation: "create_state_machine", params: { name: "CombatStates" } },
    { operation: "add_state", params: { state_machine: "CombatStates", name: "Idle",      position: { x: 0,   y: 0   } } },
    { operation: "add_state", params: { state_machine: "CombatStates", name: "HitReact",  position: { x: 300, y: 0   } } },
    { operation: "add_state", params: { state_machine: "CombatStates", name: "Stunned",   position: { x: 300, y: 200 } } },
    { operation: "add_state", params: { state_machine: "CombatStates", name: "KnockBack", position: { x: 300, y: 400 } } },
    { operation: "add_state", params: { state_machine: "CombatStates", name: "Dodge",     position: { x: 600, y: 0   } } },
    { operation: "add_state", params: { state_machine: "CombatStates", name: "Death",     position: { x: 600, y: 300 } } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "Idle",      to: "HitReact",  duration: 0.1  } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "HitReact",  to: "Idle",      duration: 0.25 } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "Idle",      to: "Stunned",   duration: 0.15 } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "Stunned",   to: "Idle",      duration: 0.3  } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "Idle",      to: "KnockBack", duration: 0.1  } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "KnockBack", to: "Idle",      duration: 0.35 } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "Idle",      to: "Dodge",     duration: 0.05 } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "Dodge",     to: "Idle",      duration: 0.2  } },
    { operation: "add_transition", params: { state_machine: "CombatStates", from: "Idle",      to: "Death",     duration: 0.0  } }
  ]
})

// 3. Assign animations — parallelize since these target different states
await parallel([
  set_state_animation({ path: "...", state_machine: "CombatStates", state: "HitReact",  animation: "/Game/.../AS_Goblin_HitReact",  loop: false }),
  set_state_animation({ path: "...", state_machine: "CombatStates", state: "Stunned",   animation: "/Game/.../AS_Goblin_Stunned",   loop: true  }),
  set_state_animation({ path: "...", state_machine: "CombatStates", state: "KnockBack", animation: "/Game/.../AS_Goblin_KnockBack", loop: false }),
  set_state_animation({ path: "...", state_machine: "CombatStates", state: "Dodge",     animation: "/Game/.../AS_Goblin_Dodge",     loop: false }),
  set_state_animation({ path: "...", state_machine: "CombatStates", state: "Death",     animation: "/Game/.../AS_Goblin_Death",     loop: false }),
])

// 4. Validate
const result = await validate_blueprint({ path: "/Game/Characters/Enemies/ABP_Enemy_Goblin" })
if (!result.compiled) {
  console.error("Compile errors:", result.errors)
}