SF
STS Forge

Blueprint Core

Core verbs: list, export, read-graph, read-var, read-cdo, read-components, compile, save, batch.

Part of the BlueprintAIAssistant documentation suite. These are the foundational verbs for discovering, reading, writing, and managing Blueprint assets. For graph editing verbs (add-node, connect, disconnect, set-pin-default, remove-node), see Graph Editing.

All verbs return JSON to stdout. On success: "success": true. On failure: "success": false with "error", "errorCode", "suggestion", and "details" fields.

Global optional flags (apply to any verb):

  • -timing: include timing data in the response
  • -compile: also compile the Blueprint after a write operation
  • -save: also save the Blueprint to disk after a write operation

list#

Find assets by path, class, name, or asset type.

Category: Discovery

Args:

Arg Required Description
-asset= No Not used by list
-assettype= No Non-Blueprint asset class (e.g., DataTable, CurveFloat, SoundCue). When set, queries non-Blueprint assets instead of Blueprints
-path= No Package path prefix filter (e.g., /Game/Blueprints). Limits results to assets under this content path
-class= No Asset class filter (e.g., Blueprint, WidgetBlueprint, AnimBlueprint). Used for Blueprint-type queries
-name= No Wildcard name pattern with * and ? support (case-insensitive)

At least one filter (assettype, path, class, or name) should be provided. When assettype is set, the query targets non-Blueprint assets (DataTables, Curves, SoundCues, etc.). Otherwise the query targets Blueprint assets.

Examples:

# List all Blueprints in a folder
-verb=list -path=/Game/Blueprints

# List only WidgetBlueprints
-verb=list -class=WidgetBlueprint

# Find Blueprints matching a name pattern
-verb=list -name=BP_Enemy*

# Find all DataTables in the project
-verb=list -assettype=DataTable

# Combine filters: DataTables under a specific path
-verb=list -assettype=DataTable -path=/Game/Data/Weapons

# Find all SoundCues matching a pattern
-verb=list -assettype=SoundCue -name=SFX_Footstep*

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"list","args":{"path":"/Game/Blueprints","class":"Blueprint"}}'

Output:

{
    "success": true,
    "count": 3,
    "assets": [
        {
            "assetPath": "/Game/Blueprints/BP_Player",
            "className": "Blueprint",
            "parentClass": "Character"
        },
        {
            "assetPath": "/Game/Blueprints/BP_Enemy",
            "className": "Blueprint",
            "parentClass": "Character"
        }
    ]
}

export#

Export any UObject asset as structured text. Works on Blueprints, DataTables, Materials, SoundCues, NiagaraSystems, GameplayEffects, AnimMontages, and any other UObject-derived asset.

Category: Read (full)

Args:

Arg Required Description
-asset= Yes Asset content path (e.g., /Game/BP/BP_Player)
--format= No Output format: overview, summary (default), detail, or backup. See Output Formats for full descriptions
-out= No Write output to a file path instead of stdout. Use for large Blueprints to avoid truncation

Use detail format when you need node GUIDs for subsequent write operations (connect, disconnect, set-pin-default, remove-node). See Output Formats for format comparison and examples.

Examples:

# Default summary export
-verb=export -asset=/Game/BP/BP_Player

# Quick overview (minimal output)
-verb=export -asset=/Game/BP/BP_Player --format=overview

# Detail format for write operations (includes node GUIDs)
-verb=export -asset=/Game/BP/BP_Player --format=detail

# Full backup to file
-verb=export -asset=/Game/BP/BP_Player --format=backup -out=C:\Temp\export.json

# Export a non-Blueprint asset (GameplayEffect)
-verb=export -asset=/Game/GAS/GE_Damage_Fire

# Export a DataTable
-verb=export -asset=/Game/Data/DT_WeaponStats

# Export a SoundCue
-verb=export -asset=/Game/Audio/SFX_Gunshot

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"export","args":{"asset":"/Game/BP/BP_Player","format":"detail"}}'

Output (summary):

{
    "success": true,
    "asset": "/Game/BP/BP_Player",
    "class": "Blueprint",
    "parentClass": "HYCharacterBase",
    "variables": [...],
    "components": [...],
    "graphs": [...]
}

read-graph#

Read a single graph's structure: nodes, pins, connections.

Category: Read (focused)

Args:

Arg Required Description
-asset= Yes Blueprint asset path
-graph= No Graph name (defaults to first EventGraph / UbergraphPage)
--format= No Output format: overview, summary (default), detail, backup. Use detail to get 8-char node GUIDs needed for connect, disconnect, set-pin-default, remove-node

Examples:

# Read the default EventGraph
-verb=read-graph -asset=/Game/BP/BP_Player

# Read a specific function graph
-verb=read-graph -asset=/Game/BP/BP_Player -graph=CalculateDamage

# Read with detail format for node GUIDs
-verb=read-graph -asset=/Game/BP/BP_Player --format=detail

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"read-graph","args":{"asset":"/Game/BP/BP_Player","graph":"EventGraph","format":"detail"}}'

Output:

{
    "success": true,
    "graph": {
        "name": "EventGraph",
        "graphType": "Ubergraph",
        "nodes": [...]
    }
}

On graph not found: error response lists available graph names so you can retry with the correct name.

read-cdo#

Read Class Default Object properties that differ from the parent class defaults. Critical for data-driven Blueprints (GameplayEffects, DataAssets) where all configuration lives on the CDO rather than in graphs.

Category: Read (focused)

Args:

Arg Required Description
-asset= Yes Blueprint asset path
--format= No Output format: summary (default), backup

Examples:

# Read CDO for a GameplayEffect
-verb=read-cdo -asset=/Game/GAS/GE_Damage_Fire

# Read CDO for a character Blueprint
-verb=read-cdo -asset=/Game/BP/BP_Player

# Full structured output
-verb=read-cdo -asset=/Game/GAS/GE_Damage_Fire --format=backup

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"read-cdo","args":{"asset":"/Game/GAS/GE_Damage_Fire"}}'

Output:

{
    "success": true,
    "classDefaults": {
        "DurationPolicy": "Instant",
        "Period": {"Value": 0.0}
    }
}

read-components#

Read the component hierarchy tree (SimpleConstructionScript).

Category: Read (focused)

Args:

Arg Required Description
-asset= Yes Blueprint asset path

Examples:

# Read component tree
-verb=read-components -asset=/Game/BP/BP_Player

# Read components of a pickup Blueprint
-verb=read-components -asset=/Game/BP/BP_Pickup_Health

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"read-components","args":{"asset":"/Game/BP/BP_Player"}}'

Output:

{
    "success": true,
    "components": [
        {
            "name": "DefaultSceneRoot",
            "class": "SceneComponent",
            "children": [
                {
                    "name": "Mesh",
                    "class": "SkeletalMeshComponent",
                    "children": []
                },
                {
                    "name": "CameraBoom",
                    "class": "SpringArmComponent",
                    "children": [
                        {
                            "name": "FollowCamera",
                            "class": "CameraComponent",
                            "children": []
                        }
                    ]
                }
            ]
        }
    ]
}

Notes:

  • Returns an empty tree for Blueprints with no components (no error).

find-nodes#

Search Blueprint graphs for nodes matching criteria.

Category: Discovery

Args:

Arg Required Description
-asset= Yes Blueprint asset path
-nodeClass= No Filter by node class name (e.g., K2Node_CallFunction, K2Node_Event)
-function= No Filter by function name (for CallFunction nodes)
-variable= No Filter by variable name (for Get/Set variable nodes)
-text= No Free-text search across node titles and properties
-graph= No Limit search to a specific graph (omit to search all graphs)

At least one search criterion (nodeClass, function, variable, or text) should be provided.

Examples:

# Find all CallFunction nodes that call "ApplyDamage"
-verb=find-nodes -asset=/Game/BP/BP_Player -function=ApplyDamage

# Find all Event nodes
-verb=find-nodes -asset=/Game/BP/BP_Player -nodeClass=K2Node_Event

# Find all nodes referencing a variable
-verb=find-nodes -asset=/Game/BP/BP_Player -variable=Health

# Free-text search for anything mentioning "damage"
-verb=find-nodes -asset=/Game/BP/BP_Player -text=damage

# Search only within a specific function graph
-verb=find-nodes -asset=/Game/BP/BP_Player -function=PrintString -graph=EventGraph

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"find-nodes","args":{"asset":"/Game/BP/BP_Player","function":"ApplyDamage"}}'

Output:

{
    "success": true,
    "matches": [
        {
            "graph": "EventGraph",
            "nodeId": "A1B2C3D4",
            "nodeClass": "K2Node_CallFunction",
            "title": "Apply Damage",
            "function": "ApplyDamage"
        }
    ],
    "count": 1
}

create#

Create a new Blueprint asset. Idempotent: returns the existing asset if the path already exists without error.

Category: Asset lifecycle

Args:

Arg Required Description
-asset= Yes Content path for the new Blueprint (e.g., /Game/Blueprints/BP_NewEnemy)
-parent= Yes Parent class: short name (e.g., Actor, Character), full path (e.g., /Script/Engine.Actor), or Blueprint path (e.g., /Game/BP/BP_BaseEnemy)
-type= No Blueprint type: Normal (default), Const, MacroLibrary, Interface, FunctionLibrary

Examples:

# Create a Blueprint based on Actor
-verb=create -asset=/Game/Blueprints/BP_NewPickup -parent=Actor

# Create based on Character
-verb=create -asset=/Game/Blueprints/BP_NewEnemy -parent=Character

# Create based on an existing Blueprint parent
-verb=create -asset=/Game/Blueprints/BP_SpecialEnemy -parent=/Game/Blueprints/BP_BaseEnemy

# Create a Blueprint Interface
-verb=create -asset=/Game/Interfaces/BPI_Interactable -parent=Interface -type=Interface

# Create a Function Library
-verb=create -asset=/Game/Libraries/BPFL_MathHelpers -parent=BlueprintFunctionLibrary -type=FunctionLibrary

# Create using a full class path
-verb=create -asset=/Game/BP/BP_CustomWidget -parent=/Script/UMG.UserWidget

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"create","args":{"asset":"/Game/Blueprints/BP_NewPickup","parent":"Actor"}}'

Output (new asset):

{
    "success": true,
    "action": "created",
    "asset": "/Game/Blueprints/BP_NewPickup",
    "parentClass": "Actor"
}

Output (already exists):

{
    "success": true,
    "action": "already_exists",
    "asset": "/Game/Blueprints/BP_NewPickup",
    "parentClass": "Actor"
}

compile#

Compile a Blueprint and report success, warnings, or errors.

Category: Lifecycle

Args:

Arg Required Description
-asset= Yes Blueprint asset path

Examples:

# Compile a single Blueprint
-verb=compile -asset=/Game/BP/BP_Player

# Compile after manual graph edits
-verb=compile -asset=/Game/GAS/GA_FireAbility

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"compile","args":{"asset":"/Game/BP/BP_Player"}}'

Output:

{
    "success": true,
    "compilationResult": "Success",
    "status": "BS_UpToDate",
    "messages": []
}

On compilation error:

{
    "success": false,
    "errorCode": "COMPILE_ERROR",
    "error": "Blueprint compilation failed with 1 error(s)",
    "messages": [
        {
            "severity": "error",
            "message": "Pin 'Target' on node 'Apply Damage' has no connection and no default value"
        }
    ]
}

save#

Save an asset package to disk.

Category: Lifecycle

Args:

Arg Required Description
-asset= Yes Asset path

Examples:

# Save after modifications
-verb=save -asset=/Game/BP/BP_Player

# Save a DataTable after edits
-verb=save -asset=/Game/Data/DT_WeaponStats

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"save","args":{"asset":"/Game/BP/BP_Player"}}'

Output:

{
    "success": true,
    "savedPath": "C:/Project/Content/BP/BP_Player.uasset",
    "packageName": "/Game/BP/BP_Player"
}

validate#

Run Blueprint validation checks without modifying anything. Reports issues across five categories.

Category: Diagnostics

Checks performed:

  1. Unconnected exec output pins (dead execution paths)
  2. Orphaned nodes (no connections at all)
  3. Compiler warnings/errors (compiles if needed, reports status)
  4. Unused variables (defined but never referenced by any node)
  5. Missing required input pins (no link and no default value)

Args:

Arg Required Description
-asset= Yes Blueprint asset path
-graph= No Limit validation to a specific graph (omit to validate all graphs)

Examples:

# Validate entire Blueprint
-verb=validate -asset=/Game/BP/BP_Player

# Validate only the EventGraph
-verb=validate -asset=/Game/BP/BP_Player -graph=EventGraph

# Validate a GameplayAbility Blueprint
-verb=validate -asset=/Game/GAS/GA_FireAbility

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"validate","args":{"asset":"/Game/BP/BP_Player"}}'

Output:

{
    "success": true,
    "asset": "/Game/BP/BP_Player",
    "issues": [
        {
            "severity": "warning",
            "check": "UnconnectedExecOut",
            "message": "Node 'Branch' has unconnected exec pin 'False'",
            "graph": "EventGraph",
            "nodeId": "A1B2C3D4"
        },
        {
            "severity": "info",
            "check": "UnusedVariable",
            "message": "Variable 'OldHealth' is defined but never referenced",
            "graph": null,
            "nodeId": null
        }
    ],
    "summary": {
        "errors": 0,
        "warnings": 1,
        "info": 1
    }
}

help#

Show structured JSON documentation for all verbs or detailed help for a specific verb.

Category: Diagnostics

Args:

Arg Required Description
-about= No Specific verb name to get detailed help for (e.g., add-node). Omit to list all verbs with summaries

Examples:

# List all available verbs
-verb=help

# Detailed help for a specific verb
-verb=help -about=add-node

# Help for batch operations
-verb=help -about=batch

# Help for export
-verb=help -about=export

HTTP:

curl -X POST http://localhost:7850/baa/v1/execute \
  -H "Content-Type: application/json" \
  -d '{"verb":"help","args":{"about":"add-node"}}'

Output (all verbs):

{
    "success": true,
    "verbs": [
        {"name": "list", "category": "Discovery", "description": "Find assets by path, class, name", "args": [...]},
        {"name": "export", "category": "Read", "description": "Export any UObject asset", "args": [...]},
        ...
    ]
}

Output (single verb):

{
    "success": true,
    "verb": {
        "name": "add-node",
        "category": "Write (graph)",
        "description": "Create a graph node in a Blueprint",
        "args": [
            {"name": "asset", "required": true, "description": "Blueprint asset path"},
            {"name": "type", "required": true, "description": "Node type"},
            ...
        ],
        "examples": [
            "-verb=add-node -asset=/Game/BP/BP_Test -type=Branch"
        ]
    }
}

batch#

Execute multiple operations from a JSON manifest in a single commandlet invocation. Each commandlet launch costs 10-30 seconds of engine startup, so batching all changes into one invocation is essential for efficiency.

Category: Efficiency

Args:

Arg Required Description
-input= Yes Path to JSON batch file, or - to read from stdin
-asset= No Default asset path for operations that omit their own -asset=

JSON input format:

{
    "defaultAsset": "/Game/BP/BP_Enemy",
    "operations": [
        {"verb": "add-var", "name": "Speed", "type": "Float"},
        {"verb": "set-var-default", "name": "Speed", "value": "500.0"},
        {"verb": "add-node", "type": "CustomEvent", "eventName": "OnSpawn", "posX": 0, "posY": 0},
        {"verb": "add-node", "type": "CallFunction", "function": "PrintString", "class": "KismetSystemLibrary", "posX": 300, "posY": 0},
        {"verb": "connect", "srcNode": "$3", "srcPin": "then", "dstNode": "$4", "dstPin": "execute"},
        {"verb": "compile"},
        {"verb": "save"}
    ]
}

Result references ($N):

Use $N syntax to reference the output of a previous operation (1-indexed):

  • For add-node results: resolves to the node's GUID
  • For add-var results: resolves to the variable name
  • For other verbs: resolves to a stringified summary

This enables chaining: create nodes first, then connect them by referencing their GUIDs via $N.

Examples:

# Execute from a file
-verb=batch -input=C:\Temp\my_changes.json

# Execute from stdin
echo '{"operations":[{"verb":"compile"}]}' | UnrealEditor-Cmd.exe ... -verb=batch -input=- -asset=/Game/BP/BP_Test

# With a default asset on the command line
-verb=batch -input=C:\Temp\ops.json -asset=/Game/BP/BP_Player

HTTP:

curl -X POST http://localhost:7850/baa/v1/batch \
  -H "Content-Type: application/json" \
  -d '{
    "defaultAsset": "/Game/BP/BP_Enemy",
    "operations": [
        {"verb": "add-var", "name": "Health", "type": "Float"},
        {"verb": "set-var-default", "name": "Health", "value": "100.0"},
        {"verb": "compile"},
        {"verb": "save"}
    ]
}'

Error handling:

If an operation fails, the error is logged in the results array and subsequent operations continue (best effort). The batch is marked as partial success. Check the failed count and individual results[].success to identify failures.

Output:

{
    "success": true,
    "totalOperations": 7,
    "succeeded": 7,
    "failed": 0,
    "results": [
        {"index": 1, "verb": "add-var", "success": true, "result": {"action": "created", "variable": {"name": "Speed"}}},
        {"index": 2, "verb": "set-var-default", "success": true, "result": {}},
        {"index": 3, "verb": "add-node", "success": true, "result": {"nodeId": "A1B2C3D4"}},
        {"index": 4, "verb": "add-node", "success": true, "result": {"nodeId": "E5F6G7H8"}},
        {"index": 5, "verb": "connect", "success": true, "result": {"action": "connected"}},
        {"index": 6, "verb": "compile", "success": true, "result": {}},
        {"index": 7, "verb": "save", "success": true, "result": {}}
    ]
}

See Batch Operations for the full batch reference including advanced patterns and error handling strategies.

Common Patterns#

Read-then-write workflow#

Most write operations require node GUIDs. The typical pattern is:

  1. export or read-graph with --format=detail to get node GUIDs
  2. Use the GUIDs in connect, disconnect, set-pin-default, or remove-node

Compile-and-save#

Add -compile -save flags to any write verb to compile and save in one step:

-verb=add-var -asset=/Game/BP/BP_Test -name=Health -type=Float -compile -save

Or in batch, add compile and save as the final operations:

{
    "operations": [
        {"verb": "add-var", "name": "Health", "type": "Float"},
        {"verb": "compile"},
        {"verb": "save"}
    ]
}

Asset discovery pipeline#

  1. list to find assets matching a pattern
  2. export with overview to scan candidates
  3. export with summary or detail for the assets you need
  4. find-nodes to locate specific nodes within a Blueprint
  5. Perform write operations using the discovered GUIDs

Error Codes#

Errors relevant to these verbs:

Code Description
ASSET_NOT_FOUND Asset path does not exist or could not be loaded
GRAPH_NOT_FOUND Named graph not found in Blueprint
NODE_NOT_FOUND Node GUID or title not found in graph
COMPILE_ERROR Blueprint compilation failed
SAVE_ERROR Package save to disk failed
INVALID_ARGS Missing or malformed required arguments
UNKNOWN_VERB Verb name not recognized
BATCH_ERROR Batch JSON parse or input file error
NO_EVENT_GRAPH Blueprint has no EventGraph (ubergraph page)

All error responses include:

  • "error": human-readable message
  • "errorCode": one of the codes above
  • "suggestion": actionable fix hint (e.g., available graph or property names)
  • "details": structured data when applicable