ue-mcp-plugin-voxel-plugin 0.3.0 → 0.3.1

package/README.md

@@ -8,8 +8,10 @@ Each action is cited to the C++ header it wraps. Full API reference under [`docs
 
 | Category | Action                          | Wraps |
 |----------|---------------------------------|-------|
-| `pcg`    | `voxel_build_scatter_graph`     | `UPCGVoxelSamplerSettings` (`VoxelPCG/Public/PCGVoxelSampler.h`) feeding `UPCGStaticMeshSpawnerSettings` |
+| `level`  | `voxel_spawn_voxel_world`       | `level.place_actor` for `AVoxelWorld` (`Voxel/Public/VoxelWorld.h`) + property defaults so the world renders |
 | `level`  | `voxel_get_voxel_world_status`  | 5 zero-arg lifecycle UFUNCTIONs on `AVoxelWorld` (`Voxel/Public/VoxelWorld.h`) |
+| `pcg`    | `voxel_build_scatter_graph`     | `UPCGVoxelSamplerSettings` (`VoxelPCG/Public/PCGVoxelSampler.h`) feeding `UPCGStaticMeshSpawnerSettings` |
+| `pcg`    | `voxel_ensure_wait_for_world`   | Splices `UPCGWaitForVoxelWorldSettings` (`VoxelPCG/Public/PCGWaitForVoxelWorld.h`) into an existing graph |
 
 The v0.1.0 release shipped three actions that called ue-mcp tasks with wrong parameter names and passed PCG node-type strings that did not exist; v0.1.1 removed them.
 
@@ -21,9 +23,24 @@ ue-mcp plugin install ue-mcp-plugin-voxel-plugin
 
 The CLI adds an entry under `plugins:` in your `ue-mcp.yml`. Restart ue-mcp; the injected action shows up under `pcg`.
 
-## Usage
+## 0-to-1 workflow
+
+```text
+# 1. drop a voxel world into the level
+level(action="voxel_spawn_voxel_world", label="MyVoxelWorld")
+
+# 2. poll until the runtime finishes its first generation pass
+level(action="voxel_get_voxel_world_status", actorLabel="MyVoxelWorld")
+# => { isRuntimeCreated, isVoxelWorldReady, isProcessingNewState, progress, numPendingTasks }
+# wait for isVoxelWorldReady && !isProcessingNewState before doing anything else.
+```
+
+That's the hello-world. `spawn_voxel_world` defaults `LayerStack` to the plugin-bundled `/Voxel/Default/DefaultStack.DefaultStack` so the actor renders without further setup.
+
+## PCG actions (once a world is live)
 
 ```text
+# Build a scatter graph that drops weighted meshes on the voxel surface.
 pcg(action="voxel_build_scatter_graph",
     assetPath="/Game/PCG/RockScatter",
     meshes=[
@@ -32,21 +49,21 @@ pcg(action="voxel_build_scatter_graph",
     ],
     pointsPerSquaredMeter=0.05,
     seed=42)
-```
-
-The call creates a `UPCGGraph` at `assetPath`, adds a Voxel Sampler → Static Mesh Spawner pipeline, and populates the weighted mesh table. Attach the resulting graph to a PCG component on or near your `AVoxelWorld`, then:
 
-```text
+# Attach the graph to a PCG component, then materialize:
 pcg(action="execute", actorLabel="MyPCGActor")
 ```
 
-Check the voxel world is actually live before scattering / stamping into it:
+If a PCG graph scatters before the voxel runtime finishes generating, you get empty / stale output. The gate is a `WaitForVoxelWorld` node — splice one into any graph idempotently:
 
 ```text
-level(action="voxel_get_voxel_world_status", actorLabel="MyVoxelWorld")
+pcg(action="voxel_ensure_wait_for_world",
+    assetPath="/Game/PCG/RockScatter",
+    beforeNode="PCGStaticMeshSpawner")
+# => { waitNode, inserted: true, rewiredEdges: N }   # or inserted:false if already gated
 ```
 
-Returns `{ isRuntimeCreated, isVoxelWorldReady, isProcessingNewState, progress, numPendingTasks }`. The runtime can be mid-regeneration even after `IsRuntimeCreated` flips true — wait for `isVoxelWorldReady && !isProcessingNewState` before pipelines that depend on stable terrain.
+`beforeNode` is whichever node you want to gate — almost always your spawner.
 
 ## Requirements
 

package/dist/tasks/EnsureWaitForWorld.d.ts

@@ -0,0 +1,32 @@
+import { BaseTask, type TaskResult } from "@db-lyon/flowkit";
+interface Options {
+    assetPath: string;
+    /**
+     * The PCG node you want to gate on the voxel world being ready —
+     * almost always the spawner that materializes the final result
+     * (PCGStaticMeshSpawner, PCGVoxelStampSpawner, etc.). Whichever
+     * nodes currently feed `beforeNode` get rerouted through a new
+     * `WaitForVoxelWorld` node.
+     */
+    beforeNode: string;
+}
+/**
+ * Insert a `WaitForVoxelWorld` node immediately upstream of `beforeNode`
+ * in an existing PCG graph. Idempotent: if any node already feeding
+ * `beforeNode` is a Wait node, returns `inserted: false` and changes
+ * nothing.
+ *
+ * Header: `VoxelPCG/Public/PCGWaitForVoxelWorld.h`
+ * (`UPCGWaitForVoxelWorldSettings`, control-flow node, no settings).
+ *
+ * Fixes the most common PCG-on-voxel footgun documented in
+ * `docs/VoxelPCG.md`: pipelines that scatter / stamp before the voxel
+ * runtime finishes generating produce empty or stale output. The Wait
+ * node blocks downstream execution until the voxel world is ready.
+ */
+export default class EnsureWaitForWorld extends BaseTask<Options> {
+    get taskName(): string;
+    protected validate(): void;
+    execute(): Promise<TaskResult>;
+}
+export {};

package/dist/tasks/EnsureWaitForWorld.js

@@ -0,0 +1,91 @@
+import { BaseTask } from "@db-lyon/flowkit";
+const WAIT_NODE_TITLE = "Wait For Voxel World";
+const WAIT_NODE_TYPE = "/Script/VoxelPCG.PCGWaitForVoxelWorldSettings";
+/**
+ * Insert a `WaitForVoxelWorld` node immediately upstream of `beforeNode`
+ * in an existing PCG graph. Idempotent: if any node already feeding
+ * `beforeNode` is a Wait node, returns `inserted: false` and changes
+ * nothing.
+ *
+ * Header: `VoxelPCG/Public/PCGWaitForVoxelWorld.h`
+ * (`UPCGWaitForVoxelWorldSettings`, control-flow node, no settings).
+ *
+ * Fixes the most common PCG-on-voxel footgun documented in
+ * `docs/VoxelPCG.md`: pipelines that scatter / stamp before the voxel
+ * runtime finishes generating produce empty or stale output. The Wait
+ * node blocks downstream execution until the voxel world is ready.
+ */
+export default class EnsureWaitForWorld extends BaseTask {
+    get taskName() { return "voxel.ensure_wait_for_world"; }
+    validate() {
+        if (!this.options.assetPath)
+            throw new Error("assetPath is required");
+        if (!this.options.beforeNode)
+            throw new Error("beforeNode is required");
+    }
+    async execute() {
+        const { assetPath, beforeNode } = this.options;
+        const graphR = await this.call("pcg.read_graph", { assetPath });
+        if (!graphR.success)
+            return graphR;
+        const graph = (graphR.data ?? {});
+        const nodes = graph.nodes ?? [];
+        const edges = graph.edges ?? [];
+        if (!nodes.some(n => n.name === beforeNode)) {
+            return { success: false, error: new Error(`node '${beforeNode}' not found in ${assetPath}`) };
+        }
+        const inbound = edges.filter(e => e.to === beforeNode);
+        if (inbound.length === 0) {
+            return { success: false, error: new Error(`no edges flow into '${beforeNode}' in ${assetPath} — nothing to gate`) };
+        }
+        const nodesByName = new Map(nodes.map(n => [n.name, n]));
+        const alreadyGated = inbound
+            .map(e => nodesByName.get(e.from))
+            .find(n => n?.title === WAIT_NODE_TITLE);
+        if (alreadyGated) {
+            return {
+                success: true,
+                data: { assetPath, beforeNode, waitNode: alreadyGated.name, inserted: false, rewiredEdges: 0 },
+            };
+        }
+        const waitR = await this.call("pcg.add_node", { assetPath, nodeType: WAIT_NODE_TYPE });
+        if (!waitR.success)
+            return waitR;
+        const waitName = waitR.data?.nodeName;
+        if (!waitName) {
+            return { success: false, error: new Error("pcg.add_node WaitForVoxelWorld returned no nodeName") };
+        }
+        for (const e of inbound) {
+            const dis = await this.call("pcg.disconnect_nodes", {
+                assetPath,
+                sourceNode: e.from,
+                sourcePin: e.fromPin,
+                targetNode: e.to,
+                targetPin: e.toPin,
+            });
+            if (!dis.success)
+                return dis;
+            const c1 = await this.call("pcg.connect_nodes", {
+                assetPath,
+                sourceNode: e.from,
+                sourcePin: e.fromPin,
+                targetNode: waitName,
+            });
+            if (!c1.success)
+                return c1;
+            const c2 = await this.call("pcg.connect_nodes", {
+                assetPath,
+                sourceNode: waitName,
+                targetNode: beforeNode,
+                targetPin: e.toPin,
+            });
+            if (!c2.success)
+                return c2;
+        }
+        return {
+            success: true,
+            data: { assetPath, beforeNode, waitNode: waitName, inserted: true, rewiredEdges: inbound.length },
+        };
+    }
+}
+//# sourceMappingURL=EnsureWaitForWorld.js.map

package/dist/tasks/EnsureWaitForWorld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EnsureWaitForWorld.js","sourceRoot":"","sources":["../../src/tasks/EnsureWaitForWorld.ts"],"names":[],"mappings":"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"}

package/dist/tasks/SpawnWorld.d.ts

@@ -0,0 +1,37 @@
+import { BaseTask, type TaskResult } from "@db-lyon/flowkit";
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface Options {
+    label?: string;
+    location?: Vec3;
+    voxelSize?: number;
+    /**
+     * Asset path of a UVoxelLayerStack. Defaults to the plugin-bundled
+     * `/Voxel/Default/DefaultStack.DefaultStack`. Pass an empty string to
+     * leave the property unset (the world will load but render nothing
+     * until you assign a stack yourself).
+     */
+    layerStack?: string;
+    /** Optional UVoxelMegaMaterial asset path. */
+    megaMaterial?: string;
+}
+/**
+ * Drop an `AVoxelWorld` actor into the active level — the first thing
+ * any Voxel-Plugin workflow needs. Wraps `level.place_actor` with the
+ * Voxel-Plugin class path, then applies `voxelSize` / `LayerStack` /
+ * `MegaMaterial` via `level.set_actor_property` so the resulting actor
+ * is renderable out of the box.
+ *
+ * Header: `Voxel/Public/VoxelWorld.h` (`AVoxelWorld`).
+ *
+ * Pair with `level.voxel_get_voxel_world_status` to poll the runtime
+ * until `isVoxelWorldReady` flips true before scattering / stamping.
+ */
+export default class SpawnWorld extends BaseTask<Options> {
+    get taskName(): string;
+    execute(): Promise<TaskResult>;
+}
+export {};

package/dist/tasks/SpawnWorld.js

@@ -0,0 +1,72 @@
+import { BaseTask } from "@db-lyon/flowkit";
+const DEFAULT_LAYER_STACK = "/Voxel/Default/DefaultStack.DefaultStack";
+/**
+ * Drop an `AVoxelWorld` actor into the active level — the first thing
+ * any Voxel-Plugin workflow needs. Wraps `level.place_actor` with the
+ * Voxel-Plugin class path, then applies `voxelSize` / `LayerStack` /
+ * `MegaMaterial` via `level.set_actor_property` so the resulting actor
+ * is renderable out of the box.
+ *
+ * Header: `Voxel/Public/VoxelWorld.h` (`AVoxelWorld`).
+ *
+ * Pair with `level.voxel_get_voxel_world_status` to poll the runtime
+ * until `isVoxelWorldReady` flips true before scattering / stamping.
+ */
+export default class SpawnWorld extends BaseTask {
+    get taskName() { return "voxel.spawn_world"; }
+    async execute() {
+        const { label, location, voxelSize, layerStack, megaMaterial } = this.options;
+        const placeParams = {
+            actorClass: "/Script/Voxel.VoxelWorld",
+        };
+        if (label)
+            placeParams.label = label;
+        if (location)
+            placeParams.location = location;
+        const placed = await this.call("level.place_actor", placeParams);
+        if (!placed.success)
+            return placed;
+        const actorLabel = placed.data?.actorLabel
+            ?? placed.data?.label
+            ?? label;
+        if (!actorLabel) {
+            return { success: false, error: new Error("level.place_actor did not return an actorLabel") };
+        }
+        const applied = {};
+        // Default the LayerStack so a bare AVoxelWorld actually renders.
+        // Explicit empty string opts out.
+        const resolvedLayerStack = layerStack === "" ? undefined
+            : (layerStack ?? DEFAULT_LAYER_STACK);
+        const setProp = async (propertyName, value) => {
+            const r = await this.call("level.set_actor_property", { actorLabel, propertyName, value });
+            if (!r.success)
+                return r;
+            applied[propertyName] = value;
+            return r;
+        };
+        if (typeof voxelSize === "number") {
+            const r = await setProp("VoxelSize", voxelSize);
+            if (!r.success)
+                return r;
+        }
+        if (resolvedLayerStack) {
+            const r = await setProp("LayerStack", resolvedLayerStack);
+            if (!r.success)
+                return r;
+        }
+        if (megaMaterial) {
+            const r = await setProp("MegaMaterial", megaMaterial);
+            if (!r.success)
+                return r;
+        }
+        return {
+            success: true,
+            data: {
+                actorLabel,
+                actorClass: "/Script/Voxel.VoxelWorld",
+                applied,
+            },
+        };
+    }
+}
+//# sourceMappingURL=SpawnWorld.js.map

package/dist/tasks/SpawnWorld.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpawnWorld.js","sourceRoot":"","sources":["../../src/tasks/SpawnWorld.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,MAAM,kBAAkB,CAAC;AAmB7D,MAAM,mBAAmB,GAAG,0CAA0C,CAAC;AAEvE;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,UAAW,SAAQ,QAAiB;IACvD,IAAI,QAAQ,KAAa,OAAO,mBAAmB,CAAC,CAAC,CAAC;IAEtD,KAAK,CAAC,OAAO;QACX,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAE9E,MAAM,WAAW,GAA4B;YAC3C,UAAU,EAAE,0BAA0B;SACvC,CAAC;QACF,IAAI,KAAK;YAAE,WAAW,CAAC,KAAK,GAAG,KAAK,CAAC;QACrC,IAAI,QAAQ;YAAE,WAAW,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAE9C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,WAAW,CAAC,CAAC;QACjE,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC;QAEnC,MAAM,UAAU,GAAI,MAAM,CAAC,IAA4D,EAAE,UAAU;eAC/E,MAAM,CAAC,IAAuC,EAAE,KAAK;eACtD,KAAK,CAAC;QACzB,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,KAAK,CAAC,gDAAgD,CAAC,EAAE,CAAC;QAChG,CAAC;QAED,MAAM,OAAO,GAA4B,EAAE,CAAC;QAE5C,iEAAiE;QACjE,kCAAkC;QAClC,MAAM,kBAAkB,GAAG,UAAU,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS;YAC/B,CAAC,CAAC,CAAC,UAAU,IAAI,mBAAmB,CAAC,CAAC;QAE/D,MAAM,OAAO,GAAG,KAAK,EAAE,YAAoB,EAAE,KAAc,EAAE,EAAE;YAC7D,MAAM,CAAC,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,0BAA0B,EAAE,EAAE,UAAU,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;YAC3F,IAAI,CAAC,CAAC,CAAC,OAAO;gBAAE,OAAO,CAAC,CAAC;YACzB,OAAO,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC;YAC9B,OAAO,CAAC,CAAC;QACX,CAAC,CAAC;QAEF,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;YAClC,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;YAChD,IAAI,CAAC,CAAC,CAAC,OAAO;gBAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,kBAAkB,EAAE,CAAC;YACvB,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,YAAY,EAAE,kBAAkB,CAAC,CAAC;YAC1D,IAAI,CAAC,CAAC,CAAC,OAAO;gBAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QACD,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC;YACtD,IAAI,CAAC,CAAC,CAAC,OAAO;gBAAE,OAAO,CAAC,CAAC;QAC3B,CAAC;QAED,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE;gBACJ,UAAU;gBACV,UAAU,EAAE,0BAA0B;gBACtC,OAAO;aACR;SACF,CAAC;IACJ,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ue-mcp-plugin-voxel-plugin",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Voxel Plugin actions for ue-mcp. Cited to the C++ headers each action wraps; full reference under docs/.",
   "type": "module",
   "main": "dist/index.js",

package/ue-mcp.plugin.yml

@@ -13,6 +13,13 @@ inject:
         pointsPerSquaredMeter: { type: number }
         seed:                  { type: number }
 
+    ensure_wait_for_world:
+      task: voxel.ensure_wait_for_world
+      description: "Insert a WaitForVoxelWorld node immediately upstream of beforeNode in an existing PCG graph. Idempotent — if a Wait node is already gating beforeNode, returns inserted:false. Fixes the standard PCG-on-voxel footgun: pipelines that run before the voxel runtime finishes generating produce empty/stale output. Wraps UPCGWaitForVoxelWorldSettings (VoxelPCG/Public/PCGWaitForVoxelWorld.h). Params: assetPath, beforeNode (the node to gate — typically your spawner)."
+      schema:
+        assetPath:  { type: string, required: true }
+        beforeNode: { type: string, required: true }
+
   level:
     get_voxel_world_status:
       task: voxel.get_world_status
@@ -21,14 +28,30 @@ inject:
         actorLabel: { type: string, required: true }
         world:      { type: string }
 
+    spawn_voxel_world:
+      task: voxel.spawn_world
+      description: "Drop an AVoxelWorld actor into the active level - the prerequisite for every other Voxel-Plugin operation. Wraps level.place_actor with actorClass=/Script/Voxel.VoxelWorld, then applies VoxelSize / LayerStack / MegaMaterial via level.set_actor_property. LayerStack defaults to the plugin-bundled /Voxel/Default/DefaultStack.DefaultStack so the world renders out of the box; pass empty string to opt out. Header: Voxel/Public/VoxelWorld.h. Params: label?, location? ({x,y,z}), voxelSize? (cm, default 100), layerStack? (asset path or '' to skip), megaMaterial? (asset path)."
+      schema:
+        label:        { type: string }
+        location:     { type: object }
+        voxelSize:    { type: number }
+        layerStack:   { type: string }
+        megaMaterial: { type: string }
+
 knowledge: {}
 
 tasks:
   voxel.build_scatter_graph:
     class_path: tasks/BuildScatterGraph
     description: "Build a Voxel-Sampler-driven PCG mesh scatter graph"
+  voxel.ensure_wait_for_world:
+    class_path: tasks/EnsureWaitForWorld
+    description: "Splice WaitForVoxelWorld into an existing PCG graph"
   voxel.get_world_status:
     class_path: tasks/GetWorldStatus
     description: "Snapshot AVoxelWorld lifecycle state in one call"
+  voxel.spawn_world:
+    class_path: tasks/SpawnWorld
+    description: "Spawn an AVoxelWorld actor with sane defaults"
 
 flows: {}