Blueprint AI Assistant — Complete Plugin Documentation

Version: 1.0.0
Engine Compatibility: Unreal Engine 5.7
Platform: Win64 (Editor only)
Loading Phase: PostEngineInit

Overview
Installation & Setup
Architecture Overview
Plugin Module Lifecycle
Settings Reference
AI Providers
Conversation Manager (Agentic Loop)
Action System (Tools)
User Interface (Slate Chat Panel)
Logging System
Memory System
Node & Blueprint Tracking
File Structure Reference
Module Dependencies
Workflow Reference for AI
Troubleshooting

1. Overview

Blueprint AI Assistant is an Unreal Engine 5 editor plugin that provides AI-powered Blueprint creation and manipulation directly within the Unreal Editor. It functions as an agentic AI system that can:

Create new Blueprints from natural language descriptions
Add nodes (events, functions, flow control, variables, etc.) to Blueprint graphs
Connect nodes with fuzzy pin name matching
Add and configure variables, components, and functions
Compile Blueprints and report errors
Inspect existing Blueprints, project assets, and class functions
Remember user preferences across sessions via a persistent memory system

The plugin supports multiple AI providers — Anthropic Claude, OpenAI (Chat Completions & Responses API), OpenRouter, and Custom endpoints — allowing users to choose their preferred LLM. It uses a text-based tool-calling approach with <tool_call> XML tags for maximum compatibility across different providers, bridges, and proxies.

Key Differentiators

Agentic loop: The AI can chain multiple tool calls autonomously, creating complex Blueprints across many iterations without user intervention.
Provider-agnostic: Works with any OpenAI-compatible or Claude-compatible API endpoint, including bridges like CopilotAPI and local LLM servers like LM Studio.
Self-correcting: Detects error loops, duplicate calls, narration without action, and automatically nudges the AI to course-correct.
Context-aware: Tracks created Blueprints and nodes across the session, manages token budgets, and auto-summarizes conversation when context fills up.

2. Installation & Setup

Installation

Place the BlueprintAIAssistant folder inside your project's Plugins/ directory.
Restart the Unreal Editor.
The plugin loads automatically (LoadingPhase: PostEngineInit).
Or just install it from FAB.

Initial Configuration

Go to Project Settings → Plugins → Blueprint AI Assistant.
Select your Active Provider (Claude, OpenAI, OpenRouter, or Custom).
Enter your API Key for the selected provider.
(Optional) Change the Model name, temperature, or other settings.
Open the assistant via Tools → Blueprint AI Assistant in the Level Editor menu, or through the "Blueprint AI Assistant" tab in the tab spawner.

Quick Start

Open the AI chat panel.
Type a natural language request, e.g., "Create a Blueprint called BP_Enemy that is an Actor with a StaticMesh component and moves forward every tick."
The AI will autonomously create the Blueprint, add nodes, connect them, and compile — all in real time.

3. Architecture Overview

The plugin follows a modular architecture with clear separation of concerns:

┌─────────────────────────────────────────────────────────────┐
│                    FBlueprintAIAssistantModule               │
│  (Plugin entry point — registers tab, menu, core systems)   │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  IAIProvider    FConversationMgr    FActionRegistry            │
│  (Claude,       (Agentic loop,      (27 tools,                 │
│   OpenAI,        system prompt,      node tracking,             │
│   OpenRouter,    tool execution,     BP tracking)               │
│   Custom)        summarization)                                 │
│                                                              │
│  SBlueprintAIChat    IBlueprintAction (25 actions)             │
│  (Slate UI panel)                                              │
│                                                              │
│  FBlueprintAILogger       FBlueprintAIMemory                   │
│  (Desktop .txt log)      (memories.json)                       │
└─────────────────────────────────────────────────────────────┘

Data Flow

User types a message in the Slate chat panel (SBlueprintAIChat).
The ConversationManager builds a system prompt (tools, project state, memory), appends the user message to history, and sends it to the AI Provider.
The AI Provider (Claude, OpenAI, etc.) sends an HTTP POST request and parses the response.
The ConversationManager extracts tool calls from the response (structured or text-based <tool_call> tags).
Each tool call is dispatched to the matching IBlueprintAction via the ActionRegistry.
The action executes on the game thread (creating nodes, connecting pins, etc.) and returns a result.
Results are aggregated and sent back to the AI for the next iteration (agentic loop).
The loop continues until the AI responds with pure text (no tool calls) or max iterations are reached.

4. Plugin Module Lifecycle

File: `BlueprintAIAssistantModule.h / .cpp`

The module class FBlueprintAIAssistantModule implements IModuleInterface and manages:

StartupModule()

Initialize Logger — Creates a timestamped debug log file on the Desktop.
Create ActionRegistry — Registers all 27 built-in actions (tools).
Create ConversationManager — Initializes the agentic loop, linked to the ActionRegistry.
RefreshAIProvider() — Creates the initial AI provider based on settings.
RegisterTab() — Registers a Nomad tab spawner (BlueprintAIAssistantTab) under the Tools category.
RegisterMenus() — Adds "Blueprint AI Assistant" to the Level Editor → Tools menu (deferred via UToolMenus::RegisterStartupCallback).

ShutdownModule()

Unregisters startup callbacks and menu owner.
Unregisters the tab spawner.
Resets ConversationManager, ActionRegistry, and CurrentProvider.
Shuts down the Logger (flushes and closes the file).

RefreshAIProvider()

Creates a new provider instance based on UBlueprintAISettings::ActiveProvider:

Claude → FClaudeProvider(ApiKey, Model, ApiVersion)
OpenAI → FOpenAIProvider(ApiKey, Model, Endpoint)
OpenRouter → FOpenRouterProvider(ApiKey, Model)
Custom → FCustomProvider(Endpoint, ApiKey, Model, Format)

Also calls ConversationManager->SetProvider() to wire it up.

Tab & Menu

Tab ID: BlueprintAIAssistantTab
Tab Role: NomadTab (can be docked anywhere)
Menu Location: Level Editor → Tools → "Blueprint AI Assistant"
Icon: Icons.Help from the default app style

5. Settings Reference

File: `BlueprintAISettings.h / .cpp`

Settings are stored as UDeveloperSettings and appear in Project Settings → Plugins → Blueprint AI Assistant. The config file is BlueprintAIAssistant.ini (saved in Saved/Config/).

Setting	Type	Default	Description
ActiveProvider	`EAIProviderType`	`Claude`	Which AI provider to use (Claude, OpenAI, OpenRouter, Custom)
ClaudeApiKey	`FString`	`""`	Anthropic API key (password field)
ClaudeModel	`FString`	`claude-sonnet-4-20250514`	Claude model ID
ClaudeApiVersion	`FString`	`2023-06-01`	Anthropic API version header
OpenAIApiKey	`FString`	`""`	OpenAI API key (password field)
OpenAIModel	`FString`	`gpt-4o`	OpenAI model ID
OpenAIEndpoint	`FString`	`https://api.openai.com/v1/responses`	OpenAI endpoint URL (auto-detects Chat Completions vs Responses API)
OpenRouterApiKey	`FString`	`""`	OpenRouter API key (password field)
OpenRouterModel	`FString`	`anthropic/claude-sonnet-4-20250514`	OpenRouter model ID
CustomEndpoint	`FString`	`""`	Custom API endpoint URL
CustomApiKey	`FString`	`""`	Custom API key
CustomModel	`FString`	`""`	Custom model name
CustomApiFormat	`EAIProviderType`	`OpenAI`	Whether custom endpoint uses Claude or OpenAI request format
Temperature	`float`	`0.3`	Generation temperature (0.0–2.0)
MaxTokens	`int32`	`8192`	Max output tokens per response (256–65536)
bAutoCompile	`bool`	`true`	Auto-compile Blueprints after modification
MaxToolIterations	`int32`	`200`	Max agentic tool-call iterations per user turn (1–500)
MaxMessageChars	`int32`	`8000`	Max characters per individual message (500–100000)
MaxToolResultChars	`int32`	`12000`	Max characters per tool result (500–50000)
MaxTotalPayloadChars	`int32`	`32000`	Max total characters across all messages in one request (0=unlimited, 0–500000)
bEnableFileLogging	`bool`	`true`	Enable debug log file on Desktop
HttpRequestTimeoutSeconds	`int32`	`180`	HTTP request timeout in seconds (30–600)

Endpoint Reference (built-in)

The settings include a read-only "Endpoint Reference" field showing:

OpenAI Chat (GPT-4o, o3, o4-mini): https://api.openai.com/v1/chat/completions
OpenAI Codex / Responses API (gpt-5.3-codex): https://api.openai.com/v1/responses
Anthropic Claude (direct): https://api.anthropic.com/v1/messages
OpenRouter (any model): https://openrouter.ai/api/v1/chat/completions

Auto-Refresh

When any setting is changed via the Project Settings UI, PostEditChangeProperty() automatically:

Saves the config to disk (SaveConfig())
Calls FBlueprintAIAssistantModule::Get().RefreshAIProvider() so changes take effect immediately without restarting the editor.

6. AI Providers

The plugin uses a clean provider abstraction layer to support multiple AI APIs.

6.1 Provider Interface (IAIProvider)

File: Public/AI/IAIProvider.h

Defines the abstract interface all providers must implement:

IAIProvider (abstract)
├── GetProviderName() → FString
├── SendRequest(Request, OnResponse, OnError) → void
├── CancelRequest() → void
├── SupportsToolCalling() → bool
├── FormatToolDefinition(Name, Desc, Schema) → FJsonObject
└── FetchAvailableModels(OnSuccess, OnError) → void

Key Data Structures

Structure	Purpose
`FAIToolCall`	Represents a single tool call: `Id`, `Name`, `Parameters` (JSON)
`EAIMessageRole`	Message roles: System, User, Assistant, ToolResult
`FAIMessage`	One conversation message with role, content, optional tool calls
`FAICompletionRequest`	Full request payload: messages, tools, temperature, max tokens, model
`FAICompletionResponse`	Parsed response: success flag, text content, tool calls, token usage, raw JSON
`FModelInfo`	Model metadata: ID, display name, pricing (per 1M tokens), free flag, context length

Delegates

FOnAIResponse — Called with parsed response on success
FOnAIError — Called with error string on failure
FOnModelsReceived — Called with model list when fetching available models

6.2 Base Provider (FAIProviderBase)

File: Public/AI/AIProviderBase.h / Private/AI/AIProviderBase.cpp

Abstract base class implementing shared HTTP logic:

HTTP Request Management

SendHttpRequest() — Builds and sends HTTP POST requests with JSON body
- Sets configurable timeout (HttpRequestTimeoutSeconds)
- Sets ActivityTimeout for reasoning models that send 0 bytes while "thinking"
- Logs full request/response bodies via FBlueprintAILogger
- Automatic retry: On connection failure, retries once automatically (copies headers, re-sends same payload)
- Uses TWeakPtr<IAIProvider> to prevent dangling captures in lambda callbacks
SendHttpGetRequest() — For model listing (GET requests)
- Returns empty data on 404 (graceful degradation for endpoints without model listing)
CancelRequest() — Unbinds the completion delegate BEFORE cancelling to prevent stale callbacks from corrupting state

Model List Parsing

Default parser handles OpenAI-style { "data": [ { "id": "..." }, ... ] }
Extracts OpenRouter pricing: { "pricing": { "prompt": "0.000003", "completion": "0.000015" } }
Filters out non-chat models: embeddings, TTS, DALL-E, Whisper, Moderation, Realtime, legacy (davinci/babbage/curie/ada)
Sorts: free models first, then alphabetically by ID

JSON Helpers (Static)

JsonToString() / StringToJson() — Serialize/deserialize JSON objects
MakeStringProp() / MakeIntProp() / MakeBoolProp() / MakeArrayProp() — Build JSON Schema properties

6.3 Claude Provider

File: Public/AI/ClaudeProvider.h / Private/AI/ClaudeProvider.cpp

Endpoint: https://api.anthropic.com/v1/messages

Request Format

System message → top-level "system" field (not in messages array)
Auth headers: x-api-key, anthropic-version
Tools → "tools" array in Claude format
Temperature and max_tokens at top level

Claude Tool Format

{
  "name": "tool_name",
  "description": "What it does",
  "input_schema": { /* JSON Schema */ }
}

Response Parsing

Content blocks: "text" (text) and "tool_use" (tool calls)
Tool call parameters from "input" field
Usage: input_tokens, output_tokens
Error detection via "error" field

Message Building

User messages → { "role": "user", "content": "..." }
Assistant messages → content blocks array with text + tool_use blocks
Tool results → user role with "tool_result" content block and "tool_use_id"

Model Listing

Endpoint: https://api.anthropic.com/v1/models
Uses base class's OpenAI-style parser

6.4 OpenAI Provider

File: Public/AI/OpenAIProvider.h / Private/AI/OpenAIProvider.cpp

Supports two API formats, auto-detected from the endpoint URL:

Chat Completions API (`/v1/chat/completions`)

Default endpoint: https://api.openai.com/v1/chat/completions
Uses max_completion_tokens (not max_tokens) for newer models
Omits temperature entirely to avoid HTTP 400 errors with models that reject custom temperature (o1, o3, o4, etc.)
Auth: Authorization: Bearer <key>

Responses API (`/v1/responses`)

Auto-detected when endpoint URL contains "/responses"
System message → top-level "instructions" field
Messages → "input" array with:
- { "role": "user", "content": "..." }
- { "role": "assistant", "content": "..." }
- { "type": "function_call", "name": "...", "arguments": "...", "call_id": "..." }
- { "type": "function_call_output", "call_id": "...", "output": "..." }
Uses max_output_tokens instead of max_completion_tokens

OpenAI Tool Format

{
  "type": "function",
  "function": {
    "name": "tool_name",
    "description": "What it does",
    "parameters": { /* JSON Schema */ }
  }
}

Response Parsing (Chat Completions)

Text from choices[0].message.content
Tool calls from choices[0].message.tool_calls[] with function.name and function.arguments
Usage: prompt_tokens, completion_tokens

Response Parsing (Responses API)

Output array with "message" (containing "output_text") and "function_call" items
Usage: input_tokens, output_tokens

Smart Error Messages

When a model is incompatible with the selected API format, the provider returns a user-friendly error suggesting the correct endpoint URL.

Model Listing

Derives endpoint from chat completions URL: …/v1/chat/completions → …/v1/models
Fallback: https://api.openai.com/v1/models

6.5 OpenRouter Provider

File: Public/AI/OpenRouterProvider.h / Private/AI/OpenRouterProvider.cpp

Inherits from FOpenAIProvider but overrides request building:

Endpoint: https://openrouter.ai/api/v1/chat/completions
Uses max_tokens (not max_completion_tokens) for broad upstream compatibility
Includes temperature in requests (unlike direct OpenAI)
Models endpoint: https://openrouter.ai/api/v1/models
Model list includes pricing information (per-token costs converted to per-1M)

6.6 Custom Provider

File: Public/AI/CustomProvider.h / Private/AI/CustomProvider.cpp

Wraps either a FClaudeProvider or FOpenAIProvider internally based on CustomApiFormat setting.

Endpoint Normalization

Automatically normalizes user-entered URLs:

http://host:port/v1/models → http://host:port/v1/chat/completions
http://host:port/v1 → http://host:port/v1/chat/completions
http://host:port → http://host:port/v1/chat/completions
Already correct URLs pass through unchanged

Model Listing

Derives models endpoint from the configured URL by finding /v1/ and appending /models.

7. Conversation Manager (Agentic Loop)

File: Public/AI/ConversationManager.h / Private/AI/ConversationManager.cpp
Lines: ~1700 (implementation)

The FConversationManager is the brain of the plugin. It orchestrates the entire conversation flow, tool execution, and AI guidance.

7.1 System Prompt Construction

The system prompt is rebuilt every iteration and includes:

Role & Format Instructions — Tells the AI to use <tool_call> XML tags
Workflow Rules — Strict 4-step workflow:
- Step 1: Create ALL nodes (add_node) — no wiring in the same response
- Step 2: Read the NODE ID REFERENCE from results
- Step 3: Issue connect_nodes and set_pin_value using returned IDs
- Step 4: Compile
Pin Name Reference — Detailed guide for exec pins, branch conditions, loops, events, etc.
Collision Configuration Guide — How to use set_component_property for physics/collision
Function Name Reference — K2_ prefix mapping for common UE5 functions
Behavioral Rules —
- Act immediately, never describe without calling tools
- Never ask for confirmation
- Never re-call with same parameters
- Use memory for persistent facts
AI Memory Section — Persistent memories from memories.json
Tool Documentation — Ultra-compact one-line-per-tool format
Working State — Created Blueprints and tracked nodes this session
Project Snapshot — Asset counts by type, Blueprint names in the project

7.2 Tool Call Parsing

The plugin supports three tool call formats with fallback parsing:

1. Structured Tool Calls (Primary)

Standard OpenAI/Claude tool_calls array in the response JSON. Used when the provider returns structured tool calls.

2. Text-Based `<tool_call>` Tags (Primary Fallback)

<tool_call>{"name":"add_node","parameters":{"blueprint":"BP_Enemy","node_type":"Event","event_name":"BeginPlay"}}</tool_call>

This is the primary format used by the system prompt. It works with any provider/bridge.

3. XML Function Format (Secondary Fallback)

<function=add_node>
<parameter=blueprint>BP_Enemy</parameter>
<parameter=node_type>Event</parameter>
</function>

Supports free models (Gemma, Llama) that use this XML-style format.

4. Code Block Fallback

```tool_call
{"name":"add_node","parameters":{...}}
```

JSON Repair

The TryParseJsonWithRepair() function handles malformed JSON from AI:

Attempt 1: Parse as-is
Attempt 2: Fix unbalanced braces (count { vs }, trim trailing extras)
Attempt 3: Trim trailing non-JSON characters

7.3 Agent Loop Flow

User message
    |
    v
SendUserMessage()
    | ← Reset counters, set bIsBusy=true
    v
SendToProvider()
    | ← Build system prompt + sanitize history
    | ← Apply payload limits (sliding window)
    | ← Hard safety cap at 60K chars
    v
HTTP Request → AI Provider
    |
    v
HandleResponse()
    |
    |--- Structured tool calls? --> ExecuteToolCalls() --> append results --> SendToProvider()
    |
    |--- Text <tool_call> tags? --> ExecuteTextToolCalls() --> append results --> SendToProvider()
    |
    |--- Deferred wiring pending? --> Inject wiring nudge --> SendToProvider()
    |
    |--- Narration without action? --> Inject action nudge --> SendToProvider()
    |
    '--- Pure text (end of turn) --> Display to user --> Summarize if needed --> bIsBusy=false

History Sanitization (SendToProvider)

Before sending, the conversation history is sanitized for maximum compatibility:

ToolResult → User role: Converts tool results to user messages (bridges don't support "tool" role)
Strip tool_calls from assistant messages: Clean text only
Skip empty content: Never send blank messages
Merge consecutive same-role messages: Ensures strict alternation (user/assistant/user/assistant)
Truncate oversized messages: Caps individual messages at MaxMessageChars
Preserve NODE ID REFERENCE: When truncating, keeps the node ID block intact
Sliding window: Drops oldest messages (after system prompt) when total exceeds MaxTotalPayloadChars
Hard safety cap: Non-configurable 60K char limit to prevent HTTP connection drops

7.4 Context Management & Summarization

Token Tracking

Tracks cumulative InputTokens and OutputTokens from provider responses
For providers returning 0 tokens (bridges/proxies), estimates ~4 chars per token
Broadcasts OnContextUsageUpdated for the UI status bar

Summarization Trigger

Summarization is triggered when:

Token-based: LastRequestInputTokens > 75% of ModelContextWindow
Char-based: TotalHistoryChars > 75% of EffectiveMaxPayloadChars (fallback when tokens unavailable)

Summarization Process

Builds conversation text (first 500 chars of each message)
Saves the last real user message (not tool results)
Sends a summarization request to the same AI provider:
- Temperature: 0.2
- MaxTokens: 1024
- Asks for: created Blueprints, added components, connected nodes, remaining work, user preferences
Replaces entire history with: summary message + last user message
Gracefully handles summarization failures (keeps original history)

7.5 Safety Mechanisms

The ConversationManager includes multiple safety mechanisms to prevent infinite loops and wasted API calls:

1. Max Iterations

Configurable limit (default: 200). Stops the loop when reached.

2. Duplicate Call Detection

Caches results keyed by "toolName|serializedParams"
Duplicate calls return immediately with a "DUPLICATE" message
Cache invalidation: After any state-changing action, stale observation caches (compile, get_blueprint_info, etc.) AND state-changing caches are cleared
compile_blueprint is never deduped (always re-executed)

3. Error Loop Detection

Tracks ConsecutiveFailedIterations (batches where all calls fail)
Per-tool failure counter (RecentErrorCounts)
At 5 failures of the same tool: Injects guidance to try a different approach
At 3 consecutive all-fail iterations: Injects "CRITICAL" guidance to inspect Blueprint state

4. Success Loop Detection

Computes a deterministic BatchSignature (sorted tool names + params)
Tracks ConsecutiveIdenticalBatches
At 3 identical batches: Injects strong guidance to stop repeating or try a different approach

5. Narration Nudge

Detects when AI describes intent without calling tools (e.g., "I'll create...", "Let me add...")
Only triggers in first 2 iterations, max 5 nudges per turn
Skips nudging if AI is asking a question
Injects a forceful user message demanding <tool_call> tags

6. Wiring Deferral Enforcement

Detects when AI mixes add_node with connect_nodes/set_pin_value in the same batch
Defers the wiring calls (skips execution, logs the deferral)
Appends a NODE ID REFERENCE block and deferral notice in results
Sends a separate short wiring message (guaranteed not to be truncated) with node IDs
If AI still doesn't follow up: Injects wiring nudge messages (up to 3 times)

7. Stale Response Guard

Both HandleResponse() and HandleError() check bIsBusy before processing. If false (user stopped generation), the response is silently ignored.

8. Poisoned History Cleanup

On error, walks backwards through history and removes:

ToolResult messages
Assistant messages with tool_calls
Aggregated text-tool-call results
Empty assistant messages

This prevents a corrupted state from poisoning subsequent requests.

8. Action System (Tools)

8.1 Action Interface (IBlueprintAction)

File: Public/Actions/IBlueprintAction.h

Every tool implements this interface:

class IBlueprintAction
{
    virtual FString GetName() const = 0;           // e.g. "create_blueprint"
    virtual FString GetDescription() const = 0;     // Human-readable
    virtual TSharedPtr<FJsonObject> GetParameterSchema() const = 0;  // JSON Schema
    virtual FBlueprintActionResult Execute(const TSharedPtr<FJsonObject>& Params) = 0;
};

FBlueprintActionResult

struct FBlueprintActionResult
{
    bool bSuccess;
    FString Message;
    TSharedPtr<FJsonObject> Data;  // Optional structured data

    FString ToJsonString() const;  // Serializes to {"success":true,"message":"...","data":{...}}
};

8.2 Action Registry

File: Public/Actions/ActionRegistry.h / Private/Actions/ActionRegistry.cpp

The FActionRegistry manages all registered actions and provides:

Action Registration: RegisterAction() — adds to both array and name-indexed map
Action Lookup: FindAction(Name) — O(1) hash map lookup
Tool Definitions: BuildToolDefinitions(Provider) — generates provider-specific tool JSON using each provider's FormatToolDefinition()
Tool Documentation: GenerateToolDocumentation() — ultra-compact one-liner format: - tool_name(required, optional?) - description
Node Tracking: Short IDs (N1, N2, ...) mapped to TWeakObjectPtr<UEdGraphNode>
- TrackNode() — registers a node, returns ID, prevents duplicate tracking of same pointer
- FindTrackedNode() — lookup by ID, validates weak pointer
- GetTrackedNodesInfo() — grouped by owning Blueprint, format: BPName: N1=NodeTitle, N2=NodeTitle
Blueprint Tracking: TrackCreatedBlueprint(Name, Path) with duplicate prevention
Session Reset: ClearSessionState() — resets node IDs back to N1, clears all tracking

8.3 Complete Tool Reference

Below is every tool available to the AI, with its parameters (required marked with *), behavior, and special notes.

`create_blueprint`

Creates a new Blueprint asset.

Parameter	Type	Required	Description
`name`	string	*	Blueprint name (e.g., "BP_Enemy")
`path`	string		Content path (default: "/Game")
`parent_class`	string		Parent class: Actor, Pawn, Character, GameModeBase, HUD, PlayerController, PlayerState, GameStateBase, WidgetBlueprint (default: Actor)

Idempotent: If a Blueprint with the same name exists, returns success with existing path.
Uses UBlueprintFactory for creation.
Tracks created Blueprint via ActionRegistry::TrackCreatedBlueprint().
Returns the full asset path.

`add_node`

Adds a node to a Blueprint graph. 645 lines — the most complex action.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`node_type`	string	*	Type of node (see below)
`function_name`	string		For CallFunction: function to call
`target_class`	string		For CallFunction: owning class
`variable_name`	string		For GetVariable/SetVariable
`event_name`	string		For Event node type
`x`	integer		X position in graph
`y`	integer		Y position in graph
`graph_name`	string		Target graph name (default: EventGraph)

Supported node_type values:

Node Type	Description
`CallFunction`	Call any UFunction by class + name
`Event`	Custom or built-in event (BeginPlay, Tick, BeginOverlap, etc.)
`Branch`	If/else flow control
`Sequence`	Sequential execution (then_0, then_1, ...)
`ForLoop`	For loop with index
`ForEachLoop`	Array iteration
`WhileLoop`	While loop
`DoOnce`	Fire once, with reset
`FlipFlop`	Alternating execution (A/B)
`Gate`	Enter/Open/Close/Toggle gate
`Delay`	Delay execution node
`PrintString`	Print debug string
`GetVariable`	Variable getter (pure)
`SetVariable`	Variable setter
`MakeArray`	Create array
`Self`	Self reference
`SpawnActor`	Spawn actor from class
`SetTimer`	Set timer by function name
`GetPlayerController`	Get player controller (index 0)
`Cast`	Cast to type
`IsValid`	Validity check
`MakeTransform`	Create transform from components

Special behaviors:

Function alias resolution: Automatically adds K2_ prefix for known UE functions (GetActorLocation → K2_GetActorLocation, etc.)
Tracks created node via ActionRegistry::TrackNode() and returns the assigned ID (N1, N2, ...)
Returns all pins with their names, types, and directions (input/output)

`connect_nodes`

Connects two node pins together.

Parameter	Type	Required	Description
`source_node`	string	*	Source node ID (e.g., "N1")
`source_pin`	string	*	Source pin name
`target_node`	string	*	Target node ID
`target_pin`	string	*	Target pin name

Fuzzy pin matching — The plugin tries multiple strategies to find the correct pin:

Exact match
Alias mapping: true ↔ then, false ↔ else, A ↔ boolean, etc.
Remove "b" prefix (boolean convention)
Case-insensitive match
Normalized match (remove spaces, underscores)
Single-pin fallback: if a direction has only one pin, use it automatically

Safety: Cross-Blueprint connections are blocked with a clear error message. Uses K2Schema->TryCreateConnection().

`disconnect_nodes`

Disconnects two connected node pins.

Parameter	Type	Required	Description
`source_node`	string	*	Source node ID
`source_pin`	string	*	Source pin name
`target_node`	string	*	Target node ID
`target_pin`	string	*	Target pin name

Uses the same fuzzy pin matching as connect_nodes. Verifies the connection exists before breaking it.

`add_variable`

Adds a variable to a Blueprint.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`variable_name`	string	*	Variable name
`variable_type`	string	*	Type string (see below)
`category`	string		Category for organization
`tooltip`	string		Variable tooltip
`default_value`	string		Default value

Supported types (15+): bool, int, float, double, string, text, name, vector, rotator, transform, color, linearcolor, class, object:ClassName, array:ElementType

Idempotent: If variable already exists, returns success.
Sets CPF_BlueprintVisible and CPF_Edit flags.
For object references, resolves class name via FindObject<UClass>.

`rename_variable`

Renames an existing variable.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`old_name`	string	*	Current variable name
`new_name`	string	*	New variable name

Uses FBlueprintEditorUtils::RenameMemberVariable. Validates the old variable exists.

`set_variable_defaults`

Sets variable default value and flags.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`variable_name`	string	*	Variable name
`default_value`	string		New default value
`expose_on_spawn`	boolean		Set CPF_ExposeOnSpawn flag
`read_only`	boolean		Set CPF_BlueprintReadOnly flag

`add_function`

Creates a new function graph in a Blueprint.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`function_name`	string	*	Function name
`is_pure`	boolean		Pure function (no exec pins)
`access_specifier`	string		"Public", "Protected", or "Private"
`category`	string		Function category

Creates a new UEdGraph for the function.
Tracks the entry node and returns its ID with pin information.
The AI should connect the entry node's "then" output to the first functional node.

`compile_blueprint`

Compiles a Blueprint and reports errors.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name

Uses FKismetEditorUtilities::CompileBlueprint.
Returns up to 10 compilation errors with node/pin details.
Never deduplicated — always re-executed even if called with same parameters.

`get_blueprint_info`

Returns detailed information about a Blueprint.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`include_nodes`	boolean		Include node details (default: false)

Returns:

Blueprint name, path, parent class
All variables (name, type)
All graphs (name, type)
All functions (name)
If include_nodes=true: First 20 nodes per graph with pins, connections (using tracked IDs like N1.pinName), position, and comments

`delete_node`

Deletes a node from a Blueprint graph.

Parameter	Type	Required	Description
`node_id`	string	*	Tracked node ID (e.g., "N5")

Breaks all pin links before removing the node from its graph.

`set_pin_value`

Sets the default value of a node's input pin.

Parameter	Type	Required	Description
`node_id`	string	*	Tracked node ID
`pin_name`	string	*	Pin name
`value`	string	*	Value to set

Uses the same fuzzy pin matching as connect_nodes. Applies value via K2Schema->TrySetDefaultValue.

`list_assets`

Lists assets in the project.

Parameter	Type	Description
`path`	string	Content path filter (default: "/Game")
`type`	string	Asset type filter (e.g., "Blueprint")
`name_filter`	string	Name substring filter

Returns up to 50 matching assets with name, path, and type.

`get_project_structure`

Returns folder tree and asset type counts from AssetRegistry.

Parameter	Type	Required	Description
`path`	string		Root path (default: "/Game")

`open_blueprint`

Opens a Blueprint in the Blueprint Editor.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name

Uses UAssetEditorSubsystem to open the asset editor.

`add_component`

Adds a component to a Blueprint's Simple Construction Script (SCS).

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`component_type`	string	*	Component class name (e.g., "StaticMesh", "SphereCollision")
`component_name`	string	*	Name for the component
`parent_component`	string		Parent component name for attachment
`is_root`	boolean		Replace the default scene root

Class resolution: Automatically appends "Component" suffix if needed (e.g., "StaticMesh" → "StaticMeshComponent")
Idempotent: Returns success if component already exists
When is_root=true, replaces the existing scene root

`set_component_property`

Sets a property on a Blueprint component. 415 lines — extensive property handling.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`component_name`	string	*	Component name
`property_name`	string	*	Property name
`value`	string	*	Property value

Special collision property handlers:

Property	Values
`CollisionProfileName`	NoCollision, OverlapAll, BlockAll, Projectile, etc.
`CollisionEnabled`	NoCollision, QueryOnly, PhysicsOnly, QueryAndPhysics
`bSimulatePhysics (SimulatePhysics)`	true/false
`bGenerateOverlapEvents (OverlapEvents)`	true/false
`CollisionResponseToAllChannels`	Block, Overlap, Ignore
`bNotifyRigidBodyCollision (NotifyRigidBody)`	true/false

For non-special properties: Uses UE reflection (FindFProperty) and ImportText for struct values (vectors, colors, etc.).

`remove_component`

Removes a component from a Blueprint.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`component_name`	string	*	Component to remove

Uses SCS->RemoveNode(). On failure, lists all available component names.

`get_class_functions`

Lists callable functions for a given class.

Parameter	Type	Required	Description
`class_name`	string	*	UClass name (e.g., "Actor", "CharacterMovementComponent")
`name_filter`	string		Filter by name substring
`include_inherited`	boolean		Include inherited functions (default: false)
`max_results`	integer		Maximum results (default: 30)

Uses TFieldIterator<UFunction>. Filters to BlueprintCallable and Pure functions. Returns function name, return type, and parameter list.

`save_memory`

Saves a persistent memory entry.

Parameter	Type	Required	Description
`content`	string	*	The fact/preference to remember

Returns the assigned memory ID (e.g., "M1"). Saved to memories.json.

`remove_memory`

Removes a persistent memory entry.

Parameter	Type	Required	Description
`memory_id`	string	*	Memory ID to remove (e.g., "M3")

`get_open_blueprint`

Gets currently open Blueprints in the editor.

No parameters required.

Returns a list of all edited assets via UAssetEditorSubsystem->GetAllEditedAssets() with name, path, and parent class.

`get_selected_nodes`

Gets currently selected nodes in the active Blueprint Editor.

No parameters required.

Uses FBlueprintEditor->GetSelectedNodes(). For each selected node:

Tracks the node and returns its ID
Serializes all pins (name, type, direction, default value, connections)
Includes position and comment info

`set_node_comment`

Sets or updates a comment on a node.

Parameter	Type	Required	Description
`node_id`	string	*	Tracked node ID
`comment`	string	*	Comment text

Sets NodeComment string and enables bCommentBubblePinned and bCommentBubbleVisible.

`add_comment_box`

Adds a comment box (grouping box) to a Blueprint graph.

Parameter	Type	Required	Description
`blueprint`	string	*	Blueprint name
`comment`	string	*	Comment text
`node_ids`	array		Array of node IDs to enclose
`x`	integer		Explicit X position
`y`	integer		Explicit Y position
`width`	integer		Explicit width
`height`	integer		Explicit height
`color`	string		Color name (red, green, blue, yellow, etc.) or R,G,B,A
`font_size`	integer		Font size (default: 18)
`group_movement`	boolean		Move enclosed nodes with the comment box (default: true)

When node_ids is provided: Auto-calculates position and size to enclose all specified nodes with 100px padding. When explicit position/size is provided, uses those values instead.

Creates a UEdGraphNode_Comment and configures its visual properties.

9. User Interface (Slate Chat Panel)

File: Public/UI/SBlueprintAIChat.h / Private/UI/SBlueprintAIChat.cpp

The SBlueprintAIChat widget is a Slate compound widget providing the chat interface:

Layout

┌──────────────────────────────────────────────────────────────┐
│ Provider: [Claude]  Model: [claude-sonnet-4] [↻] [Clear] [Stop] [Save] [Settings] │
├──────────────────────────────────────────────────────────────┤
│ [System] Blueprint AI Assistant ready...                     │
│ [User] Create a BP_Enemy actor with health variable         │
│ [AI] I'll create that Blueprint now.                        │
│ [add_node] OK: Created EventGraph node 'ReceiveBeginPlay'   │
│ [connect_nodes] OK: Connected N1.then → N2.execute          │
├──────────────────────────────────────────────────────────────┤
│ Describe what Blueprint to create or modify...     [Send]    │
├──────────────────────────────────────────────────────────────┤
│ Ready | Context: 12.5K / 200K tokens (6.3%)                 │
│        AI can make mistakes. Always verify results.          │
└──────────────────────────────────────────────────────────────┘

Features

Message Display

Color-coded by sender:

User — Blue (0.3, 0.7, 1.0)
AI — Green (0.3, 1.0, 0.5)
Error — Red (1.0, 0.3, 0.3)
System — Gray (0.7, 0.7, 0.7)
Tool actions — Yellow (1.0, 0.8, 0.2) with italic font

Read-only SEditableText for each message (allows copy/paste). Auto-scrolls to bottom on new messages.

Provider Dropdown

Four options: Claude, OpenAI, OpenRouter, Custom. Changing provider:

Updates ActiveProvider in settings
Saves config
Refreshes the AI provider
Updates model display

Model Dropdown

Populated by fetching models from the provider API
Shows pricing info: "model-id ($2.50/$10.00)" or "[FREE]"
Free models highlighted in green
Refresh button (↻) to re-fetch model list

Selecting a model:

Updates the model setting for the active provider
Passes context window size to ConversationManager
Refreshes the provider

Input Area

Multi-line editable text box (40-120px height)
Enter sends the message
Shift+Enter inserts a newline
Send button disabled while AI is busy

Control Buttons

Clear — Empties message list and clears conversation history
Stop — Cancels the current AI generation
Save Chat — Exports entire chat log as timestamped .txt file to Desktop
Settings — Opens Project Settings → Plugins → Blueprint AI Assistant

Status Bar

Shows "AI is thinking..." when busy, "Ready" otherwise
Displays context usage: 12.5K / 200K tokens (6.3%)
Color-coded: Green (<50%), Yellow (50-80%), Red (>80%)

Disclaimer

Fixed footer text: "AI can make mistakes. Always verify results and use the latest models."

ChatMessageEntry Structure

struct FChatMessageEntry {
    FString Sender;         // "User", "AI", "System", "Error", or tool name
    FString Message;        // Message content
    FDateTime Timestamp;    // When the message was created
    bool bIsToolAction;     // If true, renders with italic font
};

10. Logging System

File: Public/Logging/BlueprintAILogger.h / Private/Logging/BlueprintAILogger.cpp

Overview

A singleton file logger that creates a comprehensive debug log on the user's Desktop for each editor session.

File Location

Primary: C:\Users\{Name}\Desktop\BlueprintAI_FullLog_{timestamp}.txt
Fallback (if Desktop doesn't exist): {ProjectDir}/Saved/Logs/BlueprintAI_FullLog_{timestamp}.txt

What Gets Logged

Category Tag	Content
`INIT`	Session start, engine version, project path, provider settings
`SHUTDOWN`	Session end
`USER`	User chat messages
`AI`	End-of-turn markers
`AI-RAW`	Response metadata (char count, tool call count)
`AI-TEXT`	Full AI text responses
`AI-JSON`	Raw JSON responses (first 5000 chars)
`HTTP-REQ`	Outgoing HTTP request URL and size
`HTTP-REQ-BODY`	Full request payload (first 10000 chars)
`HTTP-RESP`	Response status code and size
`HTTP-RESP-BODY`	Full response body (first 10000 chars)
`HTTP-ERR`	HTTP connection failures
`HTTP-RETRY`	Retry attempts
`HTTP-OUT`	Message breakdown before sending
`TOOL`	Tool call detection and counting
`TOOL-EXEC`	Individual tool execution with parameters
`TOOL-RESULT`	Tool execution results
`TOOL-DEDUP`	Duplicate call detection
`CONTEXT`	Token usage and context window tracking
`TRUNCATE`	Message/result truncation events
`AGENT`	Agent loop start with max iterations
`NUDGE`	Narration nudge events
`WIRING-NUDGE`	Wiring deferral nudge events
`WORKFLOW`	Wiring deferral events
`ERROR`	General errors
`ERROR-LOOP`	Error loop detection
`SUCCESS-LOOP`	Success loop (identical batch repetition) detection
`SUMMARIZE`	Conversation summarization
`WARN`	Warnings (stale responses, hard safety cap)
`SYSTEM`	System events (stop generation, etc.)

Implementation Details

Thread-safe: Uses FCriticalSection for write locking
Flush-on-write: Flushes after every write to prevent data loss on crash
UTF-8 encoding: Converts from TCHAR to UTF-8 for file writing
Configurable: Toggle via bEnableFileLogging setting
Format: [HH:MM:SS.mmm] [CATEGORY] message
Logf(): Printf-style convenience (4096 char buffer)

Session Header

Each log starts with:

Plugin name and session timestamp
Engine version and project path
Active provider name
Temperature, MaxTokens, MaxIterations
MaxMessageChars, MaxTotalPayloadChars
HttpRequestTimeoutSeconds

11. Memory System

File: Public/Memory/BlueprintAIMemory.h / Private/Memory/BlueprintAIMemory.cpp

Overview

The memory system allows the AI to persist facts, preferences, and conventions across editor sessions. This enables the AI to "remember" things like:

User's preferred naming conventions
Project architecture decisions
Common patterns the user likes to use

Storage

File: {ProjectDir}/Saved/BlueprintAI/memories.json

Format:

{
  "memories": [
    {
      "id": "M1",
      "content": "User prefers Hungarian notation for variables",
      "created_at": "2026-02-27T14:30:00Z"
    },
    {
      "id": "M2",
      "content": "Project uses BP_ prefix for all Blueprint actors",
      "created_at": "2026-02-27T15:00:00Z"
    }
  ]
}

API

Method	Description
`FBlueprintAIMemory::Get()`	Singleton access (auto-loads on first call)
`AddMemory(Content)`	Creates entry with next available ID (M1, M2, ...), saves to disk
`RemoveMemory(Id)`	Removes by ID, saves to disk
`GetMemories()`	Returns all entries
`BuildMemoryPromptSection()`	Generates system prompt section: `[M1] fact one\n[M2] fact two\n...`
`Load()`	Parses `memories.json` from disk
`Save()`	Serializes to JSON and writes to disk (creates directory if needed)

ID Management

IDs are sequential: M1, M2, M3, ...
On load, scans existing IDs to find the highest number and sets NextMemoryId accordingly (prevents collisions)

Integration

System Prompt: Memory section is always included between behavioral rules and tool documentation
AI Tools: save_memory and remove_memory tools let the AI manage memories during conversation
The section header says "=== AI MEMORY (persistent across sessions) ===" with instructions to use save/remove_memory

12. Node & Blueprint Tracking

The tracking system is critical for the agentic loop — it provides a stable, short reference system for nodes created across multiple AI iterations.

Node Tracking

Every node created by add_node, discovered by get_blueprint_info, or selected by get_selected_nodes is assigned a short ID: N1, N2, N3, etc.

Storage: TMap<FString, TWeakObjectPtr<UEdGraphNode>> in FActionRegistry
Deduplication: If the same node pointer is tracked again, returns the existing ID
Validation: FindTrackedNode() checks if the weak pointer is still valid

Display: GetTrackedNodesInfo() groups nodes by owning Blueprint:

BP_Enemy: N1=ReceiveBeginPlay, N2=PrintString, N3=K2_SetActorLocation
BP_Player: N4=ReceiveBeginPlay, N5=InputAction

Blueprint Tracking

Created Blueprints are tracked as TArray<TPair<FString, FString>> (Name → Path):

Used in the system prompt's Working State section
Prevents the AI from re-creating existing Blueprints
Duplicate-checked by name (case-insensitive)

Session Reset

ClearSessionState() resets:

Node counter back to N1
All tracked nodes cleared
All tracked Blueprints cleared
Called when user clicks "Clear" in the chat

13. File Structure Reference

BlueprintAIAssistant/
├── BlueprintAIAssistant.uplugin              # Plugin manifest
├── Config/
│   └── FilterPlugin.ini                      # Package filter (empty)
├── Binaries/Win64/
│   ├── UnrealEditor-BlueprintAIAssistant.dll # Compiled module
│   ├── UnrealEditor-BlueprintAIAssistant.pdb # Debug symbols
│   └── UnrealEditor.modules                  # Module metadata
└── Source/BlueprintAIAssistant/
    ├── BlueprintAIAssistant.Build.cs          # Module build rules
    ├── Public/
    │   ├── BlueprintAIAssistantModule.h       # Module interface
    │   ├── Actions/
    │   │   ├── IBlueprintAction.h             # Action interface + result struct
    │   │   ├── ActionRegistry.h               # Registry + node/BP tracking
    │   │   ├── CreateBlueprintAction.h
    │   │   ├── AddNodeAction.h                 # 20+ node types
    │   │   ├── ConnectNodesAction.h            # Fuzzy pin matching
    │   │   ├── DisconnectNodesAction.h
    │   │   ├── AddVariableAction.h             # 15+ type resolution
    │   │   ├── RenameVariableAction.h
    │   │   ├── SetVariableDefaultsAction.h
    │   │   ├── AddFunctionAction.h
    │   │   ├── CompileBlueprintAction.h
    │   │   ├── GetBlueprintInfoAction.h
    │   │   ├── DeleteNodeAction.h
    │   │   ├── SetPinValueAction.h
    │   │   ├── ListAssetsAction.h
    │   │   ├── GetProjectStructureAction.h
    │   │   ├── OpenBlueprintAction.h
    │   │   ├── AddComponentAction.h
    │   │   ├── SetComponentPropertyAction.h    # Collision property handlers
    │   │   ├── RemoveComponentAction.h
    │   │   ├── GetClassFunctionsAction.h
    │   │   ├── SaveMemoryAction.h
    │   │   ├── RemoveMemoryAction.h
    │   │   ├── GetOpenBlueprintAction.h
    │   │   ├── GetSelectedNodesAction.h
    │   │   ├── SetNodeCommentAction.h
    │   │   └── AddCommentBoxAction.h
    │   ├── AI/
    │   │   ├── IAIProvider.h                  # Provider interface + data types
    │   │   ├── AIProviderBase.h               # HTTP base class
    │   │   ├── ClaudeProvider.h
    │   │   ├── OpenAIProvider.h               # Chat Completions + Responses API
    │   │   ├── OpenRouterProvider.h
    │   │   ├── CustomProvider.h
    │   │   └── ConversationManager.h          # Agentic loop
    │   ├── Logging/
    │   │   └── BlueprintAILogger.h            # File logger
    │   ├── Memory/
    │   │   └── BlueprintAIMemory.h            # Persistent memory
    │   ├── Settings/
    │   │   └── BlueprintAISettings.h          # UDeveloperSettings
    │   └── UI/
    │       └── SBlueprintAIChat.h             # Slate chat widget
    └── Private/
        ├── BlueprintAIAssistantModule.cpp     # Module lifecycle
        ├── Actions/ (25 .cpp files)           # Action implementations
        ├── AI/ (6 .cpp files)                 # Provider + conversation implementations
        ├── Logging/BlueprintAILogger.cpp
        ├── Memory/BlueprintAIMemory.cpp
        ├── Settings/BlueprintAISettings.cpp
        └── UI/SBlueprintAIChat.cpp

Total: 35 headers + 33 .cpp + 3 config files = 71 files

14. Module Dependencies

Public Dependencies

Core
CoreUObject
Engine
InputCore

Private Dependencies

Category	Modules
Settings	DeveloperSettings
Editor	UnrealEd, BlueprintGraph, KismetCompiler, Kismet, GraphEditor, AssetTools, AssetRegistry
HTTP & JSON	HTTP, Json, JsonUtilities
UI	Slate, SlateCore, EditorFramework, ToolMenus, WorkspaceMenuStructure, Projects, EditorWidgets, PropertyEditor

15. Workflow Reference for AI

The system prompt enforces a strict workflow to ensure reliable Blueprint creation:

Step 1: Create Nodes

Issue all add_node calls in one response
Do NOT mix with connect_nodes or set_pin_value
If mixed, wiring calls are automatically deferred (not executed)

Step 2: Read Node IDs

Every add_node returns a tracked ID (N1, N2, ...)
The AI must use these EXACT IDs — never predict or assume IDs

Step 3: Wire Nodes

In the NEXT response, issue all connect_nodes and set_pin_value calls
Use the IDs from Step 2
This step is critical — nodes remain unconnected if skipped

Step 4: Compile

Call compile_blueprint to check for errors
Fix any errors reported

Pin Name Conventions

Situation	Pin Names
Exec output	`then`
Exec input	`execute`
Branch true	`then`
Branch false	`else`
Branch condition	`Condition`
Variable getter output	Variable name (e.g., `Health`)
Variable setter input	Variable name
Sequence outputs	`then_0`, `then_1`, ...
ForLoop	`FirstIndex`, `LastIndex`, `LoopBody`, `Completed`, `Index`
ForEachLoop	`Array`, `LoopBody`, `Completed`, `ArrayElement`, `ArrayIndex`
SpawnActor	`SpawnTransform`, `Class`
IsValid	`ReturnValue` (bool), `then` (exec)
Events	`ReceiveBeginPlay`, `ReceiveTick`, `ReceiveActorBeginOverlap`
Pure nodes	NO exec pins (math, getters, IsValid, etc.)

16. Troubleshooting

Common Issues

Issue	Cause	Solution
"No AI provider configured"	Missing API key	Set your API key in Project Settings → Plugins → Blueprint AI Assistant
HTTP 401	Invalid API key	Verify your API key is correct and has the right permissions
HTTP 400	Incompatible model/endpoint	Check the endpoint URL matches your model (Chat Completions vs Responses API)
"HTTP connection failed"	Network issues or timeout	Increase `HttpRequestTimeoutSeconds`; check firewall/proxy
AI describes actions without doing them	Model doesn't follow `<tool_call>` format well	Use a more capable model (Claude Sonnet 4, GPT-4o, etc.)
"Reached maximum tool iterations"	Complex task exceeded iteration limit	Increase `MaxToolIterations` in settings
Nodes remain unconnected	AI mixed add_node with connect_nodes	The plugin auto-defers and nudges — usually self-corrects. If not, manually instruct the AI to connect nodes.
Context limit errors	Long conversation filling up context	Clear conversation, or increase `MaxTotalPayloadChars`. The plugin auto-summarizes at 75% usage.
Compilation errors after AI work	AI connected incompatible pins	Instruct the AI to call `get_blueprint_info` with `include_nodes=true` and fix connections

Debug Log

Enable bEnableFileLogging (on by default) to get a comprehensive log file on your Desktop. This log captures:

Every HTTP request and response
Every tool call and its result
Token usage and context tracking
Error loop detection events
The full system prompt sent each iteration

The log file name follows the pattern: BlueprintAI_FullLog_YYYYMMDD_HHMMSS.txt

Performance Tips

Use a capable model: Claude Sonnet 4 and GPT-4o produce the best results. Free/small models often fail to follow the <tool_call> format.
Keep MaxToolIterations reasonable: Default of 200 is generous. For simple tasks, 50 is usually enough.
Adjust payload limits for bridges: If using CopilotAPI or similar bridges, lower MaxTotalPayloadChars and MaxMessageChars to prevent oversized payloads.
Use memory: Save frequently-used conventions with save_memory so the AI doesn't need repeated instructions.

Plugin by CelestiaDominance — Fab Marketplace — Discord Support

Blueprint AI Assistant — Complete Plugin Documentation

Table of Contents

1. Overview

Key Differentiators

2. Installation & Setup

Installation

Initial Configuration

Quick Start

3. Architecture Overview

Data Flow

4. Plugin Module Lifecycle

File: BlueprintAIAssistantModule.h / .cpp

StartupModule()

ShutdownModule()

RefreshAIProvider()

Tab & Menu

5. Settings Reference

File: BlueprintAISettings.h / .cpp

Endpoint Reference (built-in)

Auto-Refresh

6. AI Providers

6.1 Provider Interface (IAIProvider)

Key Data Structures

Delegates

6.2 Base Provider (FAIProviderBase)

HTTP Request Management

Model List Parsing

JSON Helpers (Static)

6.3 Claude Provider

Request Format

Claude Tool Format

Response Parsing

Message Building

Model Listing

6.4 OpenAI Provider

Chat Completions API (/v1/chat/completions)

Responses API (/v1/responses)

OpenAI Tool Format

Response Parsing (Chat Completions)

Response Parsing (Responses API)

Smart Error Messages

Model Listing

6.5 OpenRouter Provider

6.6 Custom Provider

Endpoint Normalization

Model Listing

7. Conversation Manager (Agentic Loop)

7.1 System Prompt Construction

7.2 Tool Call Parsing

1. Structured Tool Calls (Primary)

2. Text-Based <tool_call> Tags (Primary Fallback)

3. XML Function Format (Secondary Fallback)

4. Code Block Fallback

JSON Repair

7.3 Agent Loop Flow

History Sanitization (SendToProvider)

7.4 Context Management & Summarization

Token Tracking

Summarization Trigger

Summarization Process

7.5 Safety Mechanisms

1. Max Iterations

2. Duplicate Call Detection

3. Error Loop Detection

4. Success Loop Detection

5. Narration Nudge

6. Wiring Deferral Enforcement

7. Stale Response Guard

8. Poisoned History Cleanup

8. Action System (Tools)

8.1 Action Interface (IBlueprintAction)

FBlueprintActionResult

8.2 Action Registry

8.3 Complete Tool Reference

create_blueprint

add_node

connect_nodes

disconnect_nodes

add_variable

rename_variable

File: `BlueprintAIAssistantModule.h / .cpp`

File: `BlueprintAISettings.h / .cpp`

Chat Completions API (`/v1/chat/completions`)

Responses API (`/v1/responses`)

2. Text-Based `<tool_call>` Tags (Primary Fallback)

`create_blueprint`

`add_node`

`connect_nodes`

`disconnect_nodes`

`add_variable`

`rename_variable`

`set_variable_defaults`

`add_function`

`compile_blueprint`

`get_blueprint_info`

`delete_node`

`set_pin_value`

`list_assets`

`get_project_structure`

`open_blueprint`

`add_component`

`set_component_property`

`remove_component`

`get_class_functions`

`save_memory`

`remove_memory`

`get_open_blueprint`

`get_selected_nodes`

`set_node_comment`

`add_comment_box`