Skip to content

Commit 47c9429

Browse files
aadeshrao123aadeshrao123
committed
README: document Niagara, StateTree, and Mass Config trait commands
Update README to reflect the current 238-command surface area (was 163). The new sections cover features that have landed since v1.1.x: - Niagara VFX (54 commands): full system/emitter/module/renderer authoring, scratch pad HLSL, parameter linking, event handlers, simulation stages, level spawning, and discovery helpers. Built on Niagara's ViewModel API for safe asset modification. - StateTree (33 commands): read + author StateTree assets including states, tasks, evaluators, transitions, conditions, parameters, and property bindings. Schema-aware (works with Mass schema variants). Includes get_statetree_full_info and search_statetree_nodes for large-tree introspection. - Mass Config trait surgical editing (3 new commands under Data Assets): add_mass_config_trait, set_mass_config_trait_property, and remove_mass_config_trait. These edit individual traits in-place without destructively replacing the Traits array, fixing the long-standing footgun where set_data_asset_property("Config", ...) would reset every unspecified trait to C++ defaults. Other updates: - Added a category-summary table at the top of the command reference - CLI examples for Niagara, StateTree, and Mass Config trait editing - Materials count corrected 34 -> 35 - Data Assets count 9 -> 12 with surgical trait commands documented - Architecture diagram + intro text updated to reference 238 commands - Release example updated to v1.2.2 and mentions PyPI alongside npm
1 parent e504dee commit 47c9429

1 file changed

Lines changed: 219 additions & 14 deletions

File tree

‎README.md‎

Lines changed: 219 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# UnrealMCP — AI Bridge for Unreal Engine 5
22

3-
Control Unreal Engine 5 editor from AI coding assistants (Claude Code, Cursor, Windsurf, etc.). Create materials, blueprints, spawn actors, manage data tables, profile performance, and more — all without leaving your terminal.
3+
Control Unreal Engine 5 editor from AI coding assistants (Claude Code, Cursor, Windsurf, etc.). Create materials, blueprints, Niagara VFX, StateTrees, spawn actors, manage data tables, profile performance, and more — **238 commands** across 13 categories, all without leaving your terminal.
44

55
**Two ways to use it:**
66

@@ -55,8 +55,9 @@ pip install unrealmcp
5555
│ │
5656
│ C++ Plugin (UnrealMCPBridge) │
5757
│ TCP server on localhost:55557 │
58-
│ 163 commands: materials, blueprints, │
59-
│ actors, data tables, profiling, etc. │
58+
│ 238 commands: materials, blueprints, │
59+
│ niagara, statetree, actors, data │
60+
│ tables, profiling, and more │
6061
└──────────────┬───────────────────────────┘
6162
│ TCP/JSON
6263
┌──────────────┴───────────────────────────┐
@@ -71,7 +72,7 @@ pip install unrealmcp
7172
└───────────────────┘ └────────────────────┘
7273
```
7374

74-
The C++ plugin runs inside the editor and exposes 163 commands over TCP. The CLI and MCP server are two different front doors to the same plugin.
75+
The C++ plugin runs inside the editor and exposes 238 commands over TCP. The CLI and MCP server are two different front doors to the same plugin.
7576

7677
---
7778

@@ -215,6 +216,41 @@ ue-cli create_input_mapping_context --asset-path /Game/Input/IMC_Default
215216
ue-cli add_key_mapping --context-path /Game/Input/IMC_Default --action-path /Game/Input/IA_Jump --key SpaceBar
216217
```
217218

219+
#### Niagara VFX
220+
```bash
221+
# Create a system from an emitter template, then tweak it
222+
ue-cli create_niagara_system --asset-path /Game/VFX/NS_Sparks \
223+
--template "/Niagara/DefaultAssets/FX_Sparks.FX_Sparks"
224+
ue-cli get_niagara_system_info --asset-path /Game/VFX/NS_Sparks
225+
ue-cli set_niagara_module_input --asset-path /Game/VFX/NS_Sparks \
226+
--emitter-name Sparks --stack SpawnStack \
227+
--module-name "Spawn Rate" --input-name SpawnRate --value 250
228+
ue-cli compile_niagara_system --asset-path /Game/VFX/NS_Sparks
229+
230+
# Spawn it in the level
231+
ue-cli spawn_niagara_effect --asset-path /Game/VFX/NS_Sparks --location "[0,0,200]"
232+
```
233+
234+
#### StateTree
235+
```bash
236+
# Create a StateTree, add a state with a task, compile
237+
ue-cli create_statetree --asset-path /Game/AI/ST_Enemy
238+
ue-cli add_statetree_state --asset-path /Game/AI/ST_Enemy --state-name Patrol
239+
ue-cli add_statetree_task --asset-path /Game/AI/ST_Enemy \
240+
--state-name Patrol --task-type "MassEnemyNestPatrolTask"
241+
ue-cli add_statetree_transition --asset-path /Game/AI/ST_Enemy \
242+
--from-state Patrol --trigger OnEvent --event-tag "Enemy.SeePlayer"
243+
ue-cli compile_statetree --asset-path /Game/AI/ST_Enemy
244+
```
245+
246+
#### Mass Config Traits (Surgical Editing)
247+
```bash
248+
# Modify a single trait property without touching the rest of the trait array
249+
ue-cli get_mass_config_traits --asset-path /Game/Mass/Enemy_Config
250+
ue-cli set_mass_config_trait_property --asset-path /Game/Mass/Enemy_Config \
251+
--trait-class MassMovementTrait --property-name MaxSpeed --property-value 600
252+
```
253+
218254
#### Widgets (UMG)
219255
```bash
220256
ue-cli get_widget_tree --widget-blueprint-path /Game/UI/WBP_HUD
@@ -403,7 +439,23 @@ The script asks where to create the MCP config:
403439

404440
---
405441

406-
## All 163 Commands
442+
## All 238 Commands
443+
444+
| Category | Count | Highlights |
445+
|----------|------:|-----------|
446+
| [Core](#core-2) | 2 | health_check, execute_python |
447+
| [Asset Management](#asset-management-16) | 16 | find/list/import/duplicate/rename/delete/save |
448+
| [Blueprints](#blueprints-22) | 22 | create, compile, variables, functions, graph nodes |
449+
| [Materials](#materials-35) | 35 | create, build_material_graph, material functions, Substrate |
450+
| [Data Tables](#data-tables-8) | 8 | full CRUD on rows + schema introspection |
451+
| [Data Assets](#data-assets-12) | 12 | data assets + **surgical Mass Config trait editing** |
452+
| [Actors & Level](#actors--level-19) | 19 | spawn, transform, properties, screenshot |
453+
| [Enhanced Input](#enhanced-input-21) | 21 | actions, mapping contexts, triggers, modifiers |
454+
| [Widgets — UMG](#widgets--umg-11) | 11 | widget tree, add/move/rename, slot props |
455+
| [**Niagara VFX**](#niagara-vfx-54-new) | **54** | systems, emitters, modules, renderers, scratch pad, parameters |
456+
| [**StateTree**](#statetree-33-new) | **33** | states, tasks, evaluators, transitions, conditions, bindings |
457+
| [Performance Profiling](#performance-profiling-3) | 3 | record .utrace + smart analysis (diagnose/spikes/flame) |
458+
| [Debug](#debug-2) | 2 | token tracking, debug toggle |
407459

408460
### Core (2)
409461
| Command | Description |
@@ -451,7 +503,7 @@ The script asks where to create the MCP config:
451503
| `delete_blueprint_node` | Remove node |
452504
| `set_blueprint_node_property` | Edit node properties |
453505

454-
### Materials (34)
506+
### Materials (35)
455507
| Command | Description |
456508
|---------|-------------|
457509
| `create_material` | Create with blend/shading mode |
@@ -493,16 +545,19 @@ The script asks where to create the MCP config:
493545
| `duplicate_data_table_row` | Copy row |
494546
| `rename_data_table_row` | Rename row |
495547

496-
### Data Assets (9)
548+
### Data Assets (12)
497549
| Command | Description |
498550
|---------|-------------|
499551
| `create_data_asset` | Create any UDataAsset subclass |
500-
| `get/set_data_asset_property(ies)` | Read/write properties |
552+
| `get/set_data_asset_property(ies)` | Read/write properties (single or batch) |
501553
| `list_data_assets` | Browse by path/class |
502-
| `list_data_asset_classes` | Discover classes |
503-
| `get_property_valid_types` | Valid dropdown values |
554+
| `list_data_asset_classes` | Discover all loaded UDataAsset subclasses |
555+
| `get_property_valid_types` | Valid dropdown values for a property slot |
504556
| `search_class_paths` | Find class paths |
505-
| `get_mass_config_traits` | Mass Entity traits |
557+
| `get_mass_config_traits` | Inspect all traits on a Mass Entity Config asset |
558+
| `add_mass_config_trait` | Append a new trait to a Mass Config (non-destructive) |
559+
| `set_mass_config_trait_property` | **Surgical** in-place edit of a single trait property — never replaces the Traits array |
560+
| `remove_mass_config_trait` | Remove a single trait by index or class without affecting siblings |
506561

507562
### Actors & Level (19)
508563
| Command | Description |
@@ -551,6 +606,156 @@ The script asks where to create the MCP config:
551606
| `get/set_slot_properties` | Layout slot properties |
552607
| `list_widget_types` | Available widget classes |
553608

609+
### Niagara VFX (54, NEW)
610+
611+
Full coverage of the Niagara editor — create systems from templates, add and configure emitters, manage modules and renderers, write scratch pad HLSL, and spawn effects in the level. Built on Niagara's ViewModel API for safe asset modification.
612+
613+
#### Systems
614+
| Command | Description |
615+
|---------|-------------|
616+
| `create_niagara_system` | Create from emitter template or empty |
617+
| `get_niagara_system_info` | System metadata, emitters, parameters |
618+
| `list_niagara_systems` | Browse Niagara systems by path |
619+
| `delete_niagara_system` | Delete a system |
620+
| `compile_niagara_system` | Force recompile |
621+
| `set_niagara_system_property` | Set top-level system property |
622+
| `get_niagara_system_errors` | Compilation errors / warnings |
623+
| `get_niagara_particle_stats` | Per-emitter particle stats |
624+
| `get/set_niagara_playback_range` | Preview playback range |
625+
626+
#### Emitters
627+
| Command | Description |
628+
|---------|-------------|
629+
| `get_niagara_emitters` | List emitters in a system |
630+
| `add_niagara_emitter` | Add from template |
631+
| `remove_niagara_emitter` | Remove an emitter |
632+
| `duplicate_niagara_emitter` | Copy emitter with new name |
633+
| `reorder_niagara_emitter` | Change emitter index |
634+
| `set_niagara_emitter_property` | Set emitter property |
635+
| `get_niagara_emitter_attributes` | Particle attributes (Position, Velocity, etc.) |
636+
637+
#### Modules (Spawn / Update / Render stacks)
638+
| Command | Description |
639+
|---------|-------------|
640+
| `get_niagara_modules` | List modules in any stack |
641+
| `add_niagara_module` | Add module from script asset |
642+
| `remove_niagara_module` | Remove a module |
643+
| `set_niagara_module_enabled` | Enable/disable a module |
644+
| `reorder_niagara_module` | Reorder within stack |
645+
| `get_niagara_module_inputs` | Inspect module inputs with current values |
646+
| `set_niagara_module_input` | Set static value on a module input |
647+
| `set_niagara_dynamic_input` | Replace input with a dynamic input function |
648+
| `set_niagara_curve` | Set curve points on a curve input |
649+
| `get_niagara_module_versions` | List script versions |
650+
651+
#### Parameters & Bindings
652+
| Command | Description |
653+
|---------|-------------|
654+
| `get_niagara_user_parameters` | List User-namespace parameters |
655+
| `add_niagara_user_parameter` | Add a User parameter |
656+
| `set_niagara_user_parameter` | Set a User parameter value |
657+
| `remove_niagara_user_parameter` | Remove a User parameter |
658+
| `link_niagara_parameter` | Bind module input to a parameter |
659+
| `get_niagara_rapid_iteration_parameters` | RI param introspection |
660+
| `set_niagara_rapid_iteration_parameter` | Set RI param value |
661+
662+
#### Renderers
663+
| Command | Description |
664+
|---------|-------------|
665+
| `add_niagara_renderer` | Add Sprite/Mesh/Ribbon/Light renderer |
666+
| `remove_niagara_renderer` | Remove a renderer |
667+
| `get_niagara_renderer_info` | Renderer summary |
668+
| `get_niagara_renderer_properties` | Full renderer property dump |
669+
| `set_niagara_renderer_property` | Set renderer property |
670+
| `set_niagara_renderer_binding` | Bind renderer attribute to particle data |
671+
672+
#### Scratch Pad & Custom Modules
673+
| Command | Description |
674+
|---------|-------------|
675+
| `create_niagara_scratch_pad_module` | Create per-emitter scratch module |
676+
| `set_niagara_scratch_pad_hlsl` | Write HLSL into scratch pad |
677+
| `create_niagara_module_asset` | Create reusable Niagara Module Script asset |
678+
679+
#### Events & Simulation Stages
680+
| Command | Description |
681+
|---------|-------------|
682+
| `add_niagara_event_handler` | Add event handler stage |
683+
| `add_niagara_simulation_stage` | Add simulation stage |
684+
| `get_niagara_event_handlers` | Inspect handlers on emitter |
685+
686+
#### Level Spawning
687+
| Command | Description |
688+
|---------|-------------|
689+
| `spawn_niagara_effect` | Spawn at world location |
690+
| `control_niagara_effect` | Activate / deactivate / restart |
691+
| `add_niagara_component` | Add NiagaraComponent to a Blueprint |
692+
| `get_niagara_actors` | Find spawned Niagara actors |
693+
694+
#### Discovery
695+
| Command | Description |
696+
|---------|-------------|
697+
| `list_niagara_modules` | List all available Niagara module scripts |
698+
| `list_niagara_emitter_templates` | List emitter templates |
699+
| `list_niagara_data_interfaces` | Available data interfaces (DI_*) |
700+
| `list_niagara_parameter_types` | Parameter type registry |
701+
702+
### StateTree (33, NEW)
703+
704+
Read and author StateTree assets — states, tasks, evaluators, transitions, conditions, parameters, and bindings. Schema-aware: works with both `StateTreeSchemaBase` and Mass schema variants.
705+
706+
#### Reading
707+
| Command | Description |
708+
|---------|-------------|
709+
| `get_statetree_info` | Asset summary (schema, states, evaluators) |
710+
| `get_statetree_full_info` | Full recursive dump (states + tasks + transitions + bindings) |
711+
| `get_statetree_states` | List all states (flat) |
712+
| `get_statetree_state` | Single state details by ID/name |
713+
| `get_statetree_node` | Inspect any node (task/evaluator/condition) |
714+
| `get_statetree_evaluators` | Global evaluators |
715+
| `get_statetree_global_tasks` | Global tasks |
716+
| `get_statetree_parameters` | Tree parameters |
717+
| `get_statetree_bindings` | All property bindings |
718+
| `get_statetree_transition_targets` | Valid transition targets for a state |
719+
| `search_statetree_nodes` | Search nodes by name / type |
720+
721+
#### Authoring
722+
| Command | Description |
723+
|---------|-------------|
724+
| `create_statetree` | Create new StateTree asset |
725+
| `set_statetree_schema` | Set schema (e.g. Mass schema) |
726+
| `add_statetree_state` | Add a state (parent or root) |
727+
| `add_statetree_task` | Add task to a state |
728+
| `add_statetree_evaluator` | Add global evaluator |
729+
| `add_statetree_global_task` | Add global task |
730+
| `add_statetree_condition` | Add enter / transition condition |
731+
| `add_statetree_transition` | Add transition (event / completed / delegate) |
732+
| `add_statetree_parameter` | Add tree parameter |
733+
| `add_statetree_binding` | Bind property between nodes |
734+
| `compile_statetree` | Compile after edits |
735+
736+
#### Modification
737+
| Command | Description |
738+
|---------|-------------|
739+
| `set_statetree_state_property` | Edit state property |
740+
| `set_statetree_node_property` | Edit task / evaluator / condition property |
741+
| `set_statetree_transition_property` | Edit transition property |
742+
| `set_statetree_color` | Set state color |
743+
744+
#### Removal
745+
| Command | Description |
746+
|---------|-------------|
747+
| `remove_statetree_state` | Remove a state |
748+
| `remove_statetree_node` | Remove a task / evaluator / condition |
749+
| `remove_statetree_transition` | Remove a transition |
750+
| `remove_statetree_binding` | Remove a binding |
751+
| `remove_statetree_parameter` | Remove a parameter |
752+
753+
#### Discovery
754+
| Command | Description |
755+
|---------|-------------|
756+
| `list_statetree_node_types` | All available task / evaluator / condition types |
757+
| `list_statetree_enum_values` | Enum values for property dropdowns |
758+
554759
### Performance Profiling (3)
555760
| Command | Description |
556761
|---------|-------------|
@@ -648,7 +853,7 @@ Each editor picks a unique port automatically. The CLI and MCP server read the p
648853
Plugins/UnrealMCP/
649854
├── UnrealMCP.uplugin # Plugin manifest
650855
├── cli/ # Go CLI source (ue-cli)
651-
│ ├── cmd/ # Command definitions (163 commands)
856+
│ ├── cmd/ # Command definitions (238 commands)
652857
│ ├── internal/bridge/ # TCP client
653858
│ ├── internal/project/ # Plugin embedding & project detection
654859
│ └── npm/ # npm package wrapper
@@ -758,10 +963,10 @@ Add a command handler in `Source/UnrealMCPBridge/Private/Commands/` and register
758963

759964
Releases are automated via GitHub Actions. Push a tag to trigger:
760965
```bash
761-
git tag v1.1.0 && git push origin v1.1.0
966+
git tag v1.2.2 && git push origin v1.2.2
762967
# → Builds 5 platform binaries
763968
# → Creates GitHub Release
764-
# → Publishes to npm
969+
# → Publishes to npm + PyPI
765970
```
766971

767972
---

0 commit comments

Comments
 (0)