SF
STS Forge

FAQ & Troubleshooting

Common questions and troubleshooting guide for Blueprint AI Assistant.

Full verb reference: AI Guide

General Questions#

What engine versions are supported?#

UE 5.7 and later. The plugin uses editor-only APIs that may not be available in earlier versions.

Does this plugin ship with my packaged game?#

No. It is an editor-only plugin (Module Type: Editor). It is not included in any packaged build.

Does this require an AI subscription or API key?#

No. The plugin runs entirely locally. AI integration is optional. You can use the export and commandlet features without any AI tool.

Can I use this for C++ classes?#

The plugin works with Blueprint assets (.uasset). It can read CDO properties of C++ classes that have Blueprint wrappers, but it cannot edit C++ source files.

Is the export output stable between versions?#

JSON key names and structure are stable. The exact wording of overview/summary/detail/backup format output may change between versions, but the sections and overall structure remain consistent.

Can multiple team members use the plugin at the same time?#

Yes. The plugin runs locally on each machine. Export settings are stored per-user in EditorPerProjectUserSettings.ini and are not shared. Write operations modify local copies of assets, which are then submitted through your normal version control workflow.

Does the plugin modify my Blueprints on install?#

No. The plugin only reads or modifies Blueprints when you explicitly run an export, batch, or write verb. Installing or enabling the plugin has no effect on existing assets.

Does the plugin support Verse?#

Currently not. I plan to add support if Verse becomes a feature in UE6 that is not UEFN specific.

Troubleshooting#

"Asset not found" error#

  • Verify the path starts with /Game/ (not the filesystem path).
  • Use -verb=list -path=/Game/ -name=YourBP to search for the asset.
  • Blueprint paths do not include the .uasset extension.
  • The path is case-sensitive.

Commandlet is very slow#

  • Each invocation costs 10-30 seconds for engine startup. This is normal.
  • Use batch mode for multiple operations. A single batch invocation with 20 operations is much faster than 20 separate invocations.
  • Use the editor right-click menu for instant exports (no startup cost).

Export file is empty or missing#

  • Check if you specified -out= with a valid writable path.
  • Without -out=, output goes to stdout (the terminal).
  • When using the editor export, check Saved/BlueprintAIAssistant/Exports/.

"Unknown verb" error#

  • Check spelling: verbs use lowercase with hyphens (e.g., add-var, not addVar).
  • Run -verb=help for a complete list of available verbs.
  • Run -verb=help -about=<verb> for detailed usage of a specific verb.

Compile errors after batch changes#

  • Make sure your batch includes a compile operation after write operations.
  • Check the batch results for any failed operations before the compile step.
  • Some operations (like reparent) may invalidate existing nodes. Run validate after reparenting.

Changes don't appear in the editor#

  • Make sure the batch includes both compile and save operations.
  • If the Blueprint is open in the editor, close and reopen it.
  • The editor may need to refresh the Content Browser (Ctrl+Space).

"Permission denied" on file write#

  • Check that the output directory exists and is writable.
  • On Windows, long paths (>260 chars) may fail. Use a shorter output path.
  • If using Perforce, verify the file is not read-only and is checked out for edit.

Batch $N reference returns unexpected value#

  • $N is 1-indexed (the first operation is $1).
  • Comment objects (no verb field) still count for $N indexing.
  • Check the results array in the batch output to see what each $N resolved to.

Export output is truncated in the terminal#

  • Some terminals have output buffer limits. Use -out=<path> to write to a file instead.
  • If piping output, ensure the receiving process does not close the pipe early.

Node connections fail with "Pin not found"#

  • Pin names are case-sensitive and must match exactly.
  • Use -verb=read-graph -asset=<path> to see all nodes with their pin names, types, and connections.
  • Execution pins are typically named execute (input) and then (output).

Batch fails with "invalid JSON"#

  • Validate your JSON with an external tool before running the batch.
  • Ensure all strings are double-quoted (JSON does not allow single quotes).
  • Check for trailing commas after the last item in arrays or objects.

Known Limitations#

Event nodes for BlueprintImplementableEvent overrides#

BAA's add-node with type=Event creates a K2Node_Event but does not set the internal FunctionReference / EventReference that binds the node to a C++ parent class's BlueprintImplementableEvent. Without this binding, the Blueprint compiler does not generate an override function. The node appears in the graph and compiles without errors, but FindFunction() at runtime returns the base class stub (which does nothing) instead of a Blueprint override.

Symptoms:

  • Event node exists in the graph with correct name and connections
  • Blueprint compiles successfully (no warnings or errors)
  • At runtime, the event never fires (C++ calls the base class stub)
  • FindFunction("EventName") reports the function's outer class as the C++ class (e.g., ClassSelection) rather than the Blueprint subclass (e.g., WBP_ClassSelection_C)

Workaround: Override events for BlueprintImplementableEvent must be added manually in the editor:

  1. Delete the BAA-created event node (via BAA remove-node or in the editor)
  2. In the Blueprint editor, right-click the graph → search for the event name
  3. Add the event from the override list (shown under the parent C++ class category, e.g., "Character Assets")
  4. Reconnect pins and compile

This sets the FunctionReference correctly, causing the compiler to generate a proper override that ProcessEvent dispatches to at runtime.

Affected scope: Only BlueprintImplementableEvent overrides from C++ parent classes. CustomEvent nodes (user-defined events with no C++ backing) work correctly via BAA.

Performance#

How large can exports get?#

Output size scales with Blueprint complexity. Overview is the most compact (metadata

  • condensed graph only). Summary includes all metadata sections and full tree-walk graphs. Detail adds 8-char GUIDs to every node in the summary. Backup is full JSON with all nodes and pins. For very large Blueprints, use -out=<filepath> to write to a file instead of stdout.

How fast are operations?#

  • Engine startup: 10-30 seconds (once per invocation)
  • Individual operations: milliseconds to low seconds
  • Export of a typical Blueprint: <1 second
  • Batch of 20 operations: 2-5 seconds (after startup)
  • Editor exports: instant (no startup needed)

How can I minimize total execution time?#

  • Group all operations into a single batch file to pay the engine startup cost only once.
  • Use defaultAsset in batch files so you do not repeat the asset path on every operation.
  • Place compile and save at the end of the batch rather than after every write operation.