# Blueprint Creation and Editing via Python

All Blueprint operations use `execute_python` with `import unreal`. Always verify results with print().

## API Discovery — ALWAYS start with query_ue_api

Before writing Python code, discover exact API names via `query_ue_api` tool. Use these keywords:

| Operation | query_ue_api keyword |
|-----------|---------------------|
| Create Blueprint | `"create Blueprint asset parent"` |
| Create non-BP asset | `"create asset factory"` |
| Add variable | `"add member variable Blueprint"` |
| Type descriptor | `"get basic type by name"` |
| Check variable exists | `"has member variable"` |
| Add dispatcher | `"add event dispatcher"` |
| Compile | `"compile blueprint"` |
| Save | `"save asset editor"` |
| Build graph | `"build graph from spec"` |
| Validate | `"validate blueprint graphs"` |
| Describe | `"describe graph logic"` |

Use the function signatures returned by `query_ue_api` directly in Python code. If a Python call fails with `AttributeError`, the error message will include auto-discovered API suggestions — use them.

## CRITICAL RULES
- **NEVER call `open_editor_for_asset()` or `open_editor_for_assets()`** — CRASHES the editor (FMRUList null dereference). All asset modifications are done directly via Python API without opening any editor windows.
- ALWAYS check asset existence before creating — never create duplicates
- ALWAYS save after creation/modification
- ALWAYS print results so the output confirms success
- Fix in place — NEVER create BP_v2, BP_Fixed, BP_Copy
- Use `compile_and_check` tool after all Blueprint changes
- Fix all fixable warnings (deprecated API, wrong types, unused vars). Only skip engine-level warnings you cannot control.

## Architecture best practices

### Component-based design
- Extract reusable logic into `UActorComponent` or `USceneComponent` — NOT into monolithic Actors
- One component = one responsibility (e.g., HealthComponent, InventoryComponent, InteractionComponent)
- Actors compose components; avoid deep Actor inheritance chains
- Example: instead of ACharacterWithHealthAndInventory, make ABaseCharacter + UHealthComponent + UInventoryComponent

### Blueprint Interface vs inheritance
- Use Blueprint Interface (`UBlueprintFunctionLibrary` + `IInterface`) for polymorphic calls between UNRELATED classes (e.g., IDamageable on Actor, Destructible, Vehicle)
- Use inheritance only when classes share actual implementation, not just an API contract
- Never create a base class just to share one function — use an Interface

### Folder organization
- Before creating assets, use `list_files` to check the project's existing folder structure and follow it
- Common conventions: `/Game/Blueprints/`, `/Game/Characters/`, `/Game/UI/`, `/Game/Effects/`
- Keep related assets together (e.g., a character BP + its animations + its data assets in one folder)
- NEVER create a new top-level folder without checking existing conventions first

### Variables and exposure
- Only mark variables as `Instance Editable` if a designer needs to tweak them per-instance
- Use `Expose on Spawn` sparingly — only for parameters needed at construction time
- Internal state variables should be private (not editable, not exposed)
- Use Categories to group related properties in the Details panel

### Event-driven communication
- Use Event Dispatchers (multicast delegates) for actor-to-actor communication — NOT direct references
- Pattern: Actor A binds to Actor B's dispatcher → Actor B fires dispatcher → Actor A reacts
- This avoids tight coupling: Actor A doesn't need to know Actor B's class, only the event signature
- For global events, consider a GameInstance subsystem with dispatchers

### C++ vs Blueprint decision
- All logic in C++, no designer-tunable defaults → C++ class only, no Blueprint needed
- Need event graphs, visual scripting, asset references, or designer defaults → create Blueprint
- Blueprint inheriting from C++ MUST add value: overridden defaults, event graph logic, components, or asset references. An empty Blueprint inheritor is wrong — use the C++ class directly
