MassBattleEditorMCP

# MassBattleEditorMCP During my university days, I was introduced to RTS games, which helped me develop a more comprehensive perspective, focusing on the overall situation rather than just individual details. Later, in the AI era, I made a practical judgment: RTS thinking is more suitable for understanding human-machine relationships. Humans are responsible for strategic planning, while AI handles tactical execution, with clear division of labor, controllable goals, and higher efficiency. If we consider the real world as a complex simplified simulation, then the game world of Mass Battle is a good approximation. When the unit scale reaches tens of thousands, this conclusion becomes even more apparent: the higher the level of strategic thinking, the more important it is, and the lower-level tactical details are more suitable for systematic processing by tool chains. ## Plugin Positioning: Large-scale Battle Plugin for Mass Battle The Mass Battle plugin aims to simulate RTS on a scale of "tens of thousands of units," requiring both high performance and universality. This means that its implementation cannot be directly mixed with traditional gameplay logic for low-scale and low-complexity scenarios, and many processes need to be "translated." Common translation scenarios include: unit creator translation configuration table translation special effect batch processing translation performance link translation (animation, material, Mesh, FX) These translations are often time-consuming, prone to errors, and can introduce regressions due to minor changes. Therefore, we need a tool layer to automate repetitive, tedious, and rule-based tasks, allowing developers to focus on higher-level issues such as strategy design, gameplay balance, and verification. MassBattleEditorMCP's role is to create a callable, reviewable, and batch-executable mechanism for "tactical layer material and configuration translation" in the Mass Battle workflow. Developers no longer need to spend a significant amount of time on manual adaptation of individual units and special effects, but can quickly confirm whether rules comply with established strategy goals. ## Currently Available Core Capabilities The plugin operates on a "check before modification, plan before application, and review after modification" rhythm, emphasizing repeatability and traceability. You can use it to complete differentiated modifications of unit performance and numerical values, or quickly adapt non-batch processing materials to an extensible batch processing system. ## Usage Entrance Online documentation: `https://winyunq.github.io/MassBattleEditorMCP/` Local documentation entrance: `Document/index.html` (`Document` worktree / `Document` branch) ## AI Skills The repository has built-in Codex skills that can be directly used by other AI tools, located in `skills/`: `skills/massbattle-unit-authoring`: guides AI to create, read, plan, merge, delete, and verify MassBattle unit configurations using Unit MCP. `skills/massbattle-effect-mcp`: guides AI to query, read, export, copy, and configure batch processing special effects using Niagara / Effect MCP, and link with Unit MCP. Installation to local Codex: ```powershell Copy-Item -Recurse -Force .\skills\massbattle-unit-authoring $env:USERPROFILE\.codex\skills\ Copy-Item -Recurse -Force .\skills\massbattle-effect-mcp $env:USERPROFILE\.codex\skills\ ``` If `CODEX_HOME` is set, copy to `$env:CODEX_HOME\skills\`. MCP is an editor tool interface, and skills only describe how to combine these tools, without writing workflows into a single large button. ### Codex MCP Server Installation MassBattleEditorMCP's Codex entrance consists of two layers: 1. Local TCP bridge within the UE editor plugin: listens to `127.0.0.1:55558` by default. 2. `Resources/Python/MassBattleMcpServer.py`: STDIO MCP server that forwards Codex tool calls to the UE bridge. Installation to Codex: ```powershell .\Scripts\Install-CodexMassBattleMCP.ps1 ``` Quick check of installation and UE bridge: ```powershell .\Scripts\QuickStart-CodexMassBattleMCP.ps1 ``` After installation, you need to restart Codex or open a new session; the UE editor also needs to load this plugin for the bridge to start listening. After successful installation, you should see `massbattle-editor-mcp` and can call primitive tools such as `unit_get`, `unit_plan_merge_update`, `unit_apply_plan`, `effect_asset_read_summary`, `niagara_set_module_pin`, `batch_fx_read_renderer_defaults`, and `batch_fx_set_renderer_defaults`. Note: `FFxConfig.AgentBehaviorState` uses `EAgentBehaviorState`, writable values include `None`, `Appearing`, `Sleeping`, `Patrolling`, `Attacking`, `Hit`, `Dying`. Hit FX should write `Hit`, not the runtime flag name `BeingHit` into this field. ## MCP Function List | Category | MCP Tool | Status | Purpose | | --- | --- | :---: | --- | | Connection and Diagnosis | `massbattle_ping` | Available | Confirm if Codex MCP server can connect to UE editor bridge. | | Connection and Diagnosis | `unit_get_api_status` | Available | Read Unit MCP capability table. | | Connection and Diagnosis | `effect_asset_get_api_status` | Available | Read Effect Asset / Batch FX MCP capability table. | | Connection and Diagnosis | `niagara_get_api_status` | Available | Read Niagara MCP capability table. | | Unit MCP | `unit_list` | Available | List `MassBattleAgentConfigDataAsset` unit configuration assets. | | Unit MCP | `unit_get` | Available | Read a unit configuration, supporting simple/full views and default filtering. | | Unit MCP | `unit_get_schema` | Available | Read editable fields, types, roles, and tooltips for units. | | Unit MCP | `unit_export` | Available | Export compact unit numerical tables for balance analysis or batch review. | | Unit MCP | `unit_find_assets` | Available | Find SkeletalMesh, Renderer, Niagara, and other candidate assets by unit production scene. | | Unit MCP | `unit_plan_merge_update` | Available | Generate and write a unit configuration merge plan, producing only diff, not directly writing assets. | | Unit MCP | `unit_preview_diff` | Available | Read the diff of a saved plan. | | Unit MCP | `unit_apply_plan` | Available | Apply an audited plan and save assets. | | Style MCP | `style_summarize_units` | Available | Summarize unit assets by style, unit family, and path category. | | Style MCP | `style_plan_organize_units` | Available | Generate a plan to organize units by default style, not directly moving assets. | | Unit Editor MCP | `editor_get_status` | Available | Read unit editing workflow capabilities. | | Unit Editor MCP | `editor_list_profiles` | Available | List style profiles and authoring recipes. | | Unit Editor MCP | `editor_get_profile` | Available | Read a specified profile or recipe. | | Unit Editor MCP | `editor_plan_organize_unit_assets` | Available | Plan to move a unit and associated generated assets to a stylized directory. | | Unit Editor MCP | `editor_apply_organize_unit_assets` | Available | Apply an audited unit asset organization plan; defaults to dry-run. | | Effect Asset MCP | `effect_asset_query` | Available | Find Niagara, Cascade, Blueprint, Material, Texture, Sound, and other visual-related assets by `query/root/classes/limit`. | | Effect Asset MCP | `effect_asset_read_summary` | Available | Read summaries of unknown type special effect assets; Cascade returns emitter, LOD, module, and dependencies. | | Effect Asset MCP | `effect_asset_export_text` | Available | Export deterministic text for AI to read and review. | | Effect Asset MCP | `effect_asset_soft_delete` | Available | Read references and soft-move unused assets to `_Trash`; defaults to dry-run. | | Effect Asset MCP | `effect_duplicate_asset` | Available | Additively replicate assets, not deleting or overwriting source assets. | | Niagara MCP | `niagara_query` | Available | Find Niagara System by path or name. | | Niagara MCP | `niagara_read_summary` | Available | Read summaries of Niagara system, emitter, renderer, user parameter, and module. | | Niagara MCP | `niagara_read_module` | Available | Precisely read a specified Niagara module node and pin. | | Niagara MCP | `niagara_export_text` | Available | Export deterministic Niagara text. | | Niagara MCP | `niagara_merge_write` | Available | Merge and write Niagara properties, not responsible for deletion. | | Niagara MCP | `niagara_set_module_pin` | Available | Write a Niagara FunctionCall module input pin's default value; defaults to rejecting connected pins. | | Niagara MCP | `niagara_set_emitter_enabled` | Available | Explicitly enable or disable a Niagara emitter handle. | | Niagara MCP | `niagara_delete` | Available | Explicitly delete renderer, user parameter, disable emitter, etc. | | Batch FX MCP | `batch_fx_read_renderer_defaults` | Available | Read `AMassBattleFxRenderer` blueprint default values; these defaults are inherited by new Actor instances dragged into the level. | | Batch FX MCP | `batch_fx_set_renderer_defaults` | Available | Set `AMassBattleFxRenderer` blueprint default values, including `NiagaraSystemAsset`, `NDC_BurstFx`, `SubType`, batch size, and pooling cooldown. | The closed loop of batch processing FX is: read/copy reference special effect assets, prepare batched Niagara/NDC/Renderer blueprints, MCP write and verify renderer blueprint default values, and users put renderer actors into the test level, then use Unit MCP to write `FFxConfig` into `Hit.SpawnFx`, `Death.SpawnFx`, `Attack.SpawnFx`, etc. arrays. MCP is not responsible for automatically modifying the current level layout; as long as users do not override instance parameters in the level, dragged actors should inherit asset default values. ## Default Style and Template-based Workflow The default style profile is located at `Resources/UnitManagementStyles/default.massbattle_unit_style.json`. It is not a runtime function but a production context for AI and MCP tools: scanning root directories, unit organization rules, unit authoring default values, and batch processing FX templates. Batch processing FX should not start from blank assets. The recommended process is: 1. Read `style/default` using `editor_get_profile`. 2. Choose a template closest to the target from `batch_fx_templates`, such as `mesh_burst_hit`, `sprite_explosion_burst`, `projectile_muzzle_burst`. 3. Replicate the template Niagara and renderer Blueprint using `effect_duplicate_asset`. 4. Close unnecessary emitters using `niagara_set_emitter_enabled` / `niagara_delete`. 5. Write UObject properties such as renderer, emitter data, and bounds using `niagara_merge_write`. 6. Fine-tune module input pins, such as Lifetime, Scale, Spawn Count, or random ranges, using `niagara_set_module_pin`. 7. Write renderer CDO's Niagara, NDC, SubType, and batch size using `batch_fx_set_renderer_defaults`. 8. Point the unit's `FFxConfig` to the corresponding `SubType` using `unit_plan_merge_update` / `unit_apply_plan`. This pattern is similar to code diff: templates express most structures, and MCP only makes small, reviewable modifications.