@uemcp/server 1.4.0 → 1.6.0

package/README.md

@@ -472,6 +472,137 @@ This is intended to let an MCP client resolve the canonical Unreal project ident
 - MetaSound documents are **never written directly**. The document format is versioned and migrated by the engine, so everything goes through `UMetaSoundBuilderSubsystem`, which is the only supported way to author one from code
 - `set_metasound_graph` declares interface members, adds nodes by their registered class name and connects them. A connection whose data types do not match is reported with the builder's own refusal rather than left as a silently dead edge
 
+### `generate_lods` / `generate_collision` / `convert_to_nanite`
+
+- Static mesh optimization, all three through `UStaticMeshEditorSubsystem` so the mesh's render data is rebuilt and every component already placed in a level refreshes with it
+- A mesh that is still compiling is refused rather than queued, because reduction settings written mid-build are overwritten by the build that was already running
+- Triangle counts live in a mesh's render data, and reading that from the game thread finishes an in-flight build synchronously — which would spend the whole rebuild inside the request the editor is blocked on. `generate_lods` and `convert_to_nanite` therefore ask whether the mesh is still compiling first and report `rebuildPending` instead of counts: LOD triangle counts come back empty and the Nanite counts zero while it is true
+- `generate_lods` takes one entry per LOD to build **below** the source mesh. LOD 0 is the mesh as authored and is never one of them, because the engine's own LOD array starts at the source mesh and reducing entry 0 would halve the full-detail mesh rather than add a level. `screenSize` goes on every entry or on none: the engine computes the whole ramp or takes all of it from the request
+- `generate_collision` takes one of the engine's own simple shapes, or `convex` for a decomposition. `primitiveCount` reports the shapes the body setup actually holds afterwards, which for a convex decomposition is the hulls it produced — `hullCount` is what was asked for, not what came back. `convex` with `replaceExisting: false` is **refused**, because the engine's decomposition clears the existing simple collision whatever it is asked to do
+- `convert_to_nanite` writes `fallbackPercentTriangles` and `keepPercentTriangles` separately, because they are different knobs: one is the non-Nanite fallback mesh, the other is what Nanite itself keeps. Supplying the fallback percentage also switches the mesh's fallback target to Percent Triangles, without which the builder resets it — so it is written only when the request carries it, and a call that only toggles Nanite leaves a hand-tuned fallback alone. `rebuildPending` is true where the mesh went back to compiling, so a caller knows the triangle counts it just read are provisional
+
+### `create_material_instance` / `list_material_params` / `set_material_params` / `assign_material`
+
+- Material instance authoring. Parameter writes go through `UMaterialEditingLibrary`, which also recompiles the instance's shader map — writing the override arrays by hand leaves the instance rendering with its old values
+- `list_material_params` reports `overridden` per parameter, which is the difference between a value the instance sets and one it inherits from its parent. A caller that cannot see that difference cannot tell a deliberate override from a default
+- `set_material_params` refuses a base material and says to make an instance first. Parameters on a base material belong to its graph, and writing them there changes every instance at once
+- A parameter name is checked against the ones the material declares, and a wrong one is answered with the names it does expose. The engine's own `Set*ParameterValue` helpers always report failure, so their answer cannot be the test
+- `assign_material` with no `componentName` writes to the actor's **root** mesh component, and refuses rather than guessing where the root is not a mesh and several mesh components are below it
+- `assign_material` targets either an actor component or a mesh asset. A slot name that does not exist is answered with the slot names that do, rather than with a silent no-op on an out-of-range index
+
+### `create_post_process_volume` / `set_post_process_settings` / `add_post_process_material`
+
+- Post process authoring. Every setting in `FPostProcessSettings` is ignored unless its sibling `bOverride_<Name>` bool is true, so each write sets both and reports the override flags it turned on in `overridesSet`
+- The same tool writes a volume's settings or a camera component's, because the settings struct is the same one; only the property prefix differs
+- `add_post_process_material` verifies the material's domain is Post Process and **refuses a blendable-location mismatch rather than changing the material**: the blendable location lives on the material asset, so silently rewriting it would change every volume already using it. The location it compares against is read through the material interface, so a material instance that overrides its parent's location is judged on the one it actually renders at
+- A bounded volume is given a cube brush sized by `extent`, because `AddActor` alone spawns the actor and no geometry: without a brush the volume encompasses nothing and affects no view. Every axis has to be positive and defaults to 200: the engine's cube builder refuses a non-positive dimension and returns nothing a caller can see, so the volume would come back shapeless under a response claiming it was applied
+
+### `create_input_action` / `create_input_mapping_context` / `add_input_mapping`
+
+- Enhanced Input authoring. An action's value type decides what triggers and modifiers make sense on it, so it is required rather than defaulted
+- A key name is validated against the engine's registered key list, and an unknown one is answered with the closest matches rather than with a mapping that never fires
+- Triggers and modifiers are instanced objects configured by class path plus params, which is the same shape the Enhanced Input details panel writes. A stack the engine refuses removes the mapping again rather than leaving a half-configured one
+
+### `create_gameplay_effect` / `set_effect_modifiers` / `create_gameplay_cue`
+
+- Gameplay Ability System effects, authored as **Blueprint classes** the way the content browser creates them, so they are editable afterwards by a person
+- Effect tags go on the engine's tag components (`UAssetTagsGameplayEffectComponent`, `UTargetTagsGameplayEffectComponent`) rather than on the deprecated inline containers, which are ignored at runtime on every engine this plugin supports
+- A tag that is not registered is refused with the tool that registers it (`create_gameplay_tag`) named, because an unregistered tag on an effect is silently inert
+- `set_effect_modifiers` names attributes as `Set.Attribute`, and a modifier op maps onto the engine's own `EGameplayModOp` — `multiply` is `MultiplyAdditive`, which is what the effect editor means by it
+
+### `create_attribute_set` / `create_gameplay_ability`
+
+- `create_attribute_set` writes C++, because an attribute set has to be a native class: the accessor macros and the replication callbacks have no Blueprint equivalent. It writes a header and a source file, refuses to overwrite either, and reports `trigger_live_compile` as the tool that makes them real
+- The generated class carries the target module's `_API` macro, without which another module that references the attribute accessors links against nothing. Its header includes `AbilitySystemComponent.h`, so a module whose `Build.cs` does not already depend on `GameplayAbilities` is told to add it — the compile fails on the first include otherwise, and a retry is refused because the generated files are already on disk
+- A `className` that already names a loaded class is refused up front, for the same reason: the build would fail on a duplicate and leave the files behind
+- `create_gameplay_ability` writes a Blueprint class under `UGameplayAbility` and configures its policies, tags and cost/cooldown effects through reflection. Those members are protected on the engine class, and reflection reaches them without this plugin splitting on engine version
+
+### `create_behavior_tree` / `add_bt_node` / `add_bt_decorator` / `add_bt_service`
+
+- Behaviour tree authoring. A behaviour tree's runtime is **generated from its editor graph**, so authoring one means authoring the graph — writing the runtime nodes directly produces a tree the editor immediately overwrites
+- Child order is positional in the graph, so `childIndex` becomes a node position and the graph's own child ordering is rebuilt from it. That is the same thing dragging a node left or right in the editor does
+- Decorators and services are subnodes of the node they guard, not siblings. `inverse` on a decorator sets `bInverseCondition`, which is the editor's "Not" checkbox
+- Every successful batch ends with the graph regenerating the runtime tree, reported as `runtimeTreeRebuilt`, because a tree whose graph and runtime disagree runs the old behaviour
+
+### `create_montage` / `set_montage_sections` / `add_anim_notify`
+
+- Montage and notify authoring. A montage slot the skeleton does not declare is refused up front: the montage would be created, look correct in the editor and play nothing
+- `set_montage_sections` refuses a section past the end of the montage, and reports `sectionCount` afterwards, because a section that never plays is indistinguishable from one that does until something tries to trigger it. A name the montage already has is refused too, because a jump to a name resolves to the first match and a second one would be unreachable
+- Sections are sorted by time and given a section at 0 once written, the way Persona does after any section edit: the engine's own position lookups walk the array assuming ascending time
+- `add_anim_notify` creates the notify track if it is missing and reports which tracks it created. A notify object, a notify state with a duration, and a bare named notify are all supported, because the three reach a graph in different ways
+- Each notify is stamped with the trigger-time offset and a GUID the same way the engine's own notify paths are, because the offset decides which side of a frame boundary a notify at 0 or at play length fires on and the notify panel matches events by GUID
+
+### `create_blend_space` / `set_blend_space_samples`
+
+- Blend space authoring, one or two dimensional. The axis ranges are written through the asset's reflected `BlendParameters`, which is the only route the engine leaves open
+- A sample outside an axis range, or one whose coordinates do not match the asset's dimensionality, is refused **before** the asset sees it: `UBlendSpace::AddSample` widens the axis to fit a sample before it validates one, which would quietly undo the ranges `create_blend_space` set
+- A sample the asset refuses — a duplicate position, a skeleton or additive mismatch — is reported in `validationIssues` **with its coordinates**, because the coordinate is what has to change for the sample to land
+- Every accepted batch re-runs the asset's triangulation, which is what the runtime samples: without it the samples are saved and `GetSamplesFromBlendInput` finds nothing until someone opens the asset
+
+### `create_anim_blueprint` / `add_anim_state_machine` / `add_anim_state` / `add_anim_transition`
+
+- Animation Blueprint authoring. A state machine is an editor graph like any other, so these tools place graph nodes and let the Blueprint compiler turn them into something that runs
+- `add_anim_state_machine` renames the nested graph to the caller's machine name and reports it, because that name is what `add_anim_state` and `add_anim_transition` address
+- A state with an `animationPath` gets a sequence player, or a blend space player where the path names a blend space, wired to its result pose; a state without one is left empty for the graph tools to fill
+- The machine node is wired into the AnimGraph's output pose and the first state added becomes the machine's entry state, because a state machine that reaches neither compiles to the reference pose
+- A transition with rule fields gets the comparison generated into its rule graph — a variable get, the matching Kismet comparison and the constant on its other pin, driving `bCanEnterTransition`. The comparison is chosen for the variable's own type, so an integer is not compared through the float overload. A transition with no rule has an empty rule graph, which never fires, and the response says so
+
+### `create_ik_rig` / `create_ik_retargeter`
+
+- IK rig and retargeter authoring, both through the engine's controllers so the assets are the same ones the IK editors produce
+- A retarget chain whose bones are not on the mesh, or whose start bone is not an ancestor of its end bone, is refused with that rule stated rather than accepted and then ignored — the rig itself only checks that the two bones exist
+- A chain name the rig already has is refused rather than silently renamed, because retargeting pairs chains by name and a renamed chain never pairs
+- A chain's `goalName` creates a real IK goal on its end bone and connects it to the solver, since the chain field only records a name and nothing would otherwise exist for a solver to reach for
+- `create_ik_retargeter` seeds the retargeter's op stack the way the engine's own factory does — both rigs first, then the default ops, because an op reads the rigs when it is added and assigning one afterwards does not revisit it. On 5.6+ the chain mappings live on those ops, and without them every mapping is refused. The mapping report is read back from the retargeter, so chains it auto-mapped are listed as mapped
+- A mapping's `sourceChain` is checked against the source rig's own chains. The retargeter validates only the target side, so a misspelled source name is stored, echoed back as mapped, and leaves that limb in its reference pose
+- `create_ik_retargeter` reports `unmappedSourceChains` and `unmappedTargetChains`. A chain with nothing mapped to it leaves that limb in its reference pose, which reads as a broken animation rather than an incomplete setup
+
+### `create_widget_blueprint` / `add_widget` / `set_widget_slot` / `bind_widget_event`
+
+- UMG authoring. A widget's slot type is decided by whichever panel took it, so `add_widget` and `set_widget_slot` **report the slot class** rather than taking it from the caller
+- A name collision is refused rather than renamed: a caller who asked for `HealthBar` and silently got `HealthBar_1` would bind its events to the wrong widget. Anything under the widget tree counts, not just the widgets the designer lists: a discarded widget's move out of the tree is undoable, and an undone one back under the old name would otherwise be hit by the next construction — fatally where the classes differ
+- A widget whose properties were refused is taken back out of the tree **and renamed into the transient package**, the way the designer's own delete path does: taking it out of its parent alone leaves the name taken under the widget tree, and the next attempt at the same name collides with the orphan
+- `create_widget_blueprint` replaces a root panel the factory built from the project's Default Root Widget setting when it is not the `rootPanelClass` that was asked for
+- Every widget is registered in the Blueprint's widget-GUID map, variable or not, because the 5.6+ widget compiler walks all of them and ensures on any that is missing
+- `bind_widget_event` promotes the widget to a variable if it is not one, since a bound event node has nothing to point at otherwise, and reports that as `markedAsVariable`
+- It spawns the event node itself rather than through the engine's bind helper, whose last act is to bring the Blueprint editor to focus: that would open the widget editor and build its designer preview inside the request, and steal the person's focus while it did it
+
+### `render_sequence` / `get_render_job_status`
+
+- Movie Render Queue rendering. A render takes minutes, so `render_sequence` **accepts the job and returns an id** rather than holding the bridge connection open, and `get_render_job_status` is where the outcome shows up
+- A second render is refused while an executor exists, not merely while one reports rendering: the PIE executor only raises that flag once PIE has finished starting, and a second accept inside that window would delete the queue the first one has not read yet
+- The editor's own Movie Render Queue is the one the MRQ window shows, so whatever a person left in it is copied aside before this job replaces it and put back when the render ends. "When it ends" means when the executor actually goes idle, not when it first reports finished: a failed pipeline raises that same event mid-render and the render keeps reading the queue afterwards
+- `headless: true` renders in a separate process so the editor stays usable; otherwise the render runs through PIE in this editor, which is what the Movie Render Queue window does. A headless render with unsaved packages is refused up front, because the new-process executor asks to save first and that prompt would block the request
+- `endFrame` is **exclusive**, which is how the Movie Render Queue builds its playback range: 0 to 100 renders frames 0 through 99
+- EXR and ProRes output are resolved at runtime and their absence is reported, because ProRes ships in its own optional plugin
+- Status reports the files **actually written under the output directory since the job started**, which is the only per-frame progress the pipeline exposes without owning the render. The list is capped at 50 paths while `writtenFileCount` stays the real total, because an image sequence writes one file per frame
+
+### `spawn_niagara_system` / `set_niagara_params`
+
+- Niagara placement and its user-exposed parameters. Placing into the level spawns a Niagara actor; attaching adds an instanced component to an existing actor, which is what survives a level save
+- A socket the actor's root component does not have is refused before the component exists, because attaching to a missing socket silently places the effect at the component origin
+- `set_niagara_params` reports **every user parameter the system has**. Niagara stores an override for a name the system does not declare and nothing ever reads it, so a misspelled parameter has to be refused here to be visible at all — and so does a `paramKind` that does not match the parameter's declared type, because Niagara resolves a user parameter by name and type together
+- `object` writes go through the setter for the parameter's **declared** type — texture, render target, material, static mesh or plain object — since each setter builds its own typed variable and the wrong one lands an override the system never looks up. A data interface parameter is refused: it is configured on the system rather than assigned an asset
+
+### `create_pcg_graph` / `run_pcg_generate`
+
+- PCG graph authoring and generation. Nodes are addressed by caller-supplied ids so connections can name them before the graph exists, and `input` / `output` name the graph's own nodes
+- An omitted pin name takes the default of the node it is on, not a fixed 'Out'/'In'. The graph's own Input and Output nodes carry the labels of the side they face inwards from — the Input node's only output pin is `In` and the Output node's only input pin is `Out` — so a fixed default would make the documented sampler wiring unreachable
+- A connection the graph refuses is answered with the pins each node actually has, rather than with a graph that is missing an edge
+- A graph whose nodes or edges were refused is taken back out, because a partially connected PCG graph runs as something other than what was asked for
+- `run_pcg_generate` drives the PCG subsystem for up to `waitMs`, since a PCG graph executes across editor frames. That wait happens inside the blocking game-thread task the bridge abandons after 5 s, so `waitMs` is bounded at 3000: a longer wait would lose the response and leave the editor frozen for the remainder. `timedOut` says the counts are a snapshot; the generation keeps running in the editor either way
+- `generatedActorCount` and `generatedInstanceCount` are reported because a caller that saw only `applied` with an empty-looking level would read a working graph as a failure
+
+### `set_project_settings` / `set_default_gamemode`
+
+- Project settings writes. Settings live on settings objects rather than in the config files, so every write goes through the settings object and is saved to whichever file that object declares — which is the part a raw ini edit gets wrong
+- Which file that is comes from the settings class's own config flags, the way the editor's Settings panel picks it, and `configFilePath` reports the one actually used. A section that declares itself local to the project user, such as Rendering Overrides (Local), belongs in `Config/UserEngine.ini`: written into `DefaultEngine.ini` instead, the user layer loads after it and the change is silently gone on the next start
+- The sections come from the engine's own settings registry rather than from a scan of `UDeveloperSettings` subclasses, because the core pages — Maps & Modes, Description, Input — are plain config objects that a class scan cannot see
+- Only the **Project** container is writable. The Editor container holds a person's own preferences, which a tool has no business changing on their behalf
+- Omitting `sectionName` lists the writable sections; omitting `properties` reports one section's current values. That is how a caller finds a property name instead of guessing an ini key
+- `restartProperties` names the settings the engine reads once at startup. They are written correctly and still inert until the editor restarts, which is worth saying rather than leaving the caller to wonder
+- `set_default_gamemode` writes the project default through `GameMapsSettings`, or a level override through that level's world settings. The pawn, controller, state and HUD classes are not settings — they live on the game mode class — so they are written onto its defaults and the Blueprint is recompiled. A **C++ game mode refuses them**: its class defaults are rebuilt from its constructor on every start, so the write would live only until the editor closed
+
 ## MCP Resources
 
 Resources carry context a client can attach without spending a tool call and a model turn. Every one of them is served from in-memory state or the local filesystem: **a resource read never opens a bridge socket and never waits on the editor**, so an unreachable or absent editor produces a structured payload rather than a timeout.