ue-mcp-plugin-voxel-plugin 0.2.0 → 0.3.1

package/README.md

@@ -4,13 +4,16 @@
 
 ## What ships
 
-One injected action in v0.2.0, cited to its source:
+Each action is cited to the C++ header it wraps. Full API reference under [`docs/`](docs/).
 
-| Category | Action                       | Wraps |
-|----------|------------------------------|-------|
-| `pcg`    | `voxel_build_scatter_graph`  | `UPCGVoxelSamplerSettings` (`VoxelPCG/Public/PCGVoxelSampler.h`) feeding `UPCGStaticMeshSpawnerSettings` |
+| Category | Action                          | Wraps |
+|----------|---------------------------------|-------|
+| `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 |
 
-More tools are tracked in [`TODO.md`](TODO.md) — each entry cites the header and class it would wrap. 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.
+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.
 
 ## Install
 
@@ -20,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=[
@@ -31,14 +49,22 @@ pcg(action="voxel_build_scatter_graph",
     ],
     pointsPerSquaredMeter=0.05,
     seed=42)
+
+# Attach the graph to a PCG component, then materialize:
+pcg(action="execute", actorLabel="MyPCGActor")
 ```
 
-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:
+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
-pcg(action="execute", actorLabel="MyPCGActor")
+pcg(action="voxel_ensure_wait_for_world",
+    assetPath="/Game/PCG/RockScatter",
+    beforeNode="PCGStaticMeshSpawner")
+# => { waitNode, inserted: true, rewiredEdges: N }   # or inserted:false if already gated
 ```
 
+`beforeNode` is whichever node you want to gate — almost always your spawner.
+
 ## Requirements
 
 - ue-mcp `>= 1.0.15`

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/GetWorldStatus.d.ts

@@ -0,0 +1,27 @@
+import { BaseTask, type TaskResult } from "@db-lyon/flowkit";
+interface Options {
+    actorLabel: string;
+    world?: "editor" | "pie";
+}
+/**
+ * One-call snapshot of an `AVoxelWorld`'s lifecycle state.
+ *
+ * Composes 5x `editor.invoke_function` against the zero-arg lifecycle
+ * UFUNCTIONs on `AVoxelWorld` (`Voxel/Public/VoxelWorld.h`):
+ *
+ *   bool  IsRuntimeCreated()
+ *   bool  IsVoxelWorldReady()
+ *   bool  IsProcessingNewState()
+ *   float GetProgress()
+ *   int32 GetNumPendingTasks()
+ *
+ * Use it before any operation that requires the voxel runtime to be live —
+ * scattering meshes / placing stamps into a half-built world produces empty
+ * or stale output. The five calls fan out in parallel.
+ */
+export default class GetWorldStatus extends BaseTask<Options> {
+    get taskName(): string;
+    protected validate(): void;
+    execute(): Promise<TaskResult>;
+}
+export {};

package/dist/tasks/GetWorldStatus.js

@@ -0,0 +1,57 @@
+import { BaseTask } from "@db-lyon/flowkit";
+/**
+ * One-call snapshot of an `AVoxelWorld`'s lifecycle state.
+ *
+ * Composes 5x `editor.invoke_function` against the zero-arg lifecycle
+ * UFUNCTIONs on `AVoxelWorld` (`Voxel/Public/VoxelWorld.h`):
+ *
+ *   bool  IsRuntimeCreated()
+ *   bool  IsVoxelWorldReady()
+ *   bool  IsProcessingNewState()
+ *   float GetProgress()
+ *   int32 GetNumPendingTasks()
+ *
+ * Use it before any operation that requires the voxel runtime to be live —
+ * scattering meshes / placing stamps into a half-built world produces empty
+ * or stale output. The five calls fan out in parallel.
+ */
+export default class GetWorldStatus extends BaseTask {
+    get taskName() { return "voxel.get_world_status"; }
+    validate() {
+        if (!this.options.actorLabel)
+            throw new Error("actorLabel is required");
+    }
+    async execute() {
+        const { actorLabel, world } = this.options;
+        const baseParams = { actorLabel };
+        if (world)
+            baseParams.world = world;
+        const fns = [
+            "IsRuntimeCreated",
+            "IsVoxelWorldReady",
+            "IsProcessingNewState",
+            "GetProgress",
+            "GetNumPendingTasks",
+        ];
+        const results = await Promise.all(fns.map(functionName => this.call("editor.invoke_function", { ...baseParams, functionName })));
+        for (let i = 0; i < results.length; i++) {
+            if (!results[i].success)
+                return results[i];
+        }
+        const ret = (r) => r.data?.returnValues?.ReturnValue;
+        const asBool = (s) => s === "true" || s === "True";
+        const asNum = (s) => (s == null ? NaN : Number(s));
+        return {
+            success: true,
+            data: {
+                actorLabel,
+                isRuntimeCreated: asBool(ret(results[0])),
+                isVoxelWorldReady: asBool(ret(results[1])),
+                isProcessingNewState: asBool(ret(results[2])),
+                progress: asNum(ret(results[3])),
+                numPendingTasks: asNum(ret(results[4])),
+            },
+        };
+    }
+}
+//# sourceMappingURL=GetWorldStatus.js.map

package/dist/tasks/GetWorldStatus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GetWorldStatus.js","sourceRoot":"","sources":["../../src/tasks/GetWorldStatus.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,MAAM,kBAAkB,CAAC;AAW7D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,OAAO,OAAO,cAAe,SAAQ,QAAiB;IAC3D,IAAI,QAAQ,KAAa,OAAO,wBAAwB,CAAC,CAAC,CAAC;IAEjD,QAAQ;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAC3C,MAAM,UAAU,GAA4B,EAAE,UAAU,EAAE,CAAC;QAC3D,IAAI,KAAK;YAAE,UAAU,CAAC,KAAK,GAAG,KAAK,CAAC;QAEpC,MAAM,GAAG,GAAG;YACV,kBAAkB;YAClB,mBAAmB;YACnB,sBAAsB;YACtB,aAAa;YACb,oBAAoB;SACZ,CAAC;QAEX,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,GAAG,CAC/B,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CACrB,IAAI,CAAC,IAAI,CAAC,wBAAwB,EAAE,EAAE,GAAG,UAAU,EAAE,YAAY,EAAE,CAAC,CACrE,CACF,CAAC;QAEF,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO;gBAAE,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC;QAC7C,CAAC;QAED,MAAM,GAAG,GAAG,CAAC,CAAa,EAAsB,EAAE,CAC/C,CAAC,CAAC,IAA+B,EAAE,YAAY,EAAE,WAAW,CAAC;QAChE,MAAM,MAAM,GAAG,CAAC,CAAqB,EAAW,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,MAAM,CAAC;QAChF,MAAM,KAAK,GAAG,CAAC,CAAqB,EAAU,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAE/E,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE;gBACJ,UAAU;gBACV,gBAAgB,EAAM,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC7C,iBAAiB,EAAK,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC7C,oBAAoB,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC7C,QAAQ,EAAc,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC5C,eAAe,EAAO,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;aAC7C;SACF,CAAC;IACJ,CAAC;CACF"}

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/docs/Modules.md

@@ -0,0 +1,107 @@
+# Voxel Plugin — Module Map
+
+The plugin ships **twelve modules** plus a UHT (UnrealHeaderTool) extension. Every module funnels through a single `VoxelGlobalMethods.SetupVoxelModule` shim defined in `VoxelCore/VoxelCore.Build.cs`, which standardizes C++20, IWYU=None, unity builds, the shared PCH (`VoxelPCH.h` for runtime, `VoxelCoreEditorPCH.h` for editor), and `FPSemanticsMode.Precise` (so PCG point output is identical on client and server).
+
+## Module list
+
+| Module | Type | Loading phase | Public headers? | Role |
+|---|---|---|---|---|
+| `VoxelCore` | Runtime | `PostConfigInit` | yes | Foundational containers, math, threading, messaging, ISPC bridge, dependency tracking. No voxel concepts. |
+| `VoxelCoreEditor` | Editor | `Default` | yes | Slate widgets, detail customizations, asset wizards used by every other editor module. |
+| `VoxelGraph` | Runtime | `Default` | yes | Visual-graph asset, compilation pipeline, typed buffers, function-library nodes. |
+| `VoxelGraphEditor` | Editor | `Default` | yes | Graph editor UI, node panels, preview viewport, message log. |
+| `Voxel` | Runtime | `PostConfigInit` | yes | The gameplay-facing module: `AVoxelWorld`, stamps, layers, mega-material, render/collision/navigation, sculpt/spline/shape/scatter. |
+| `VoxelEditor` | Editor | `Default` | yes | World/stamp/layer detail panels, interactive sculpt tools, placement mode integration. |
+| `VoxelBlueprint` | UncookedOnly | `PostConfigInit` | yes | Kismet (BP) K2 nodes that expose voxel-graph parameters and the make/break pin-value flow. Editor-time only. |
+| `VoxelBlueprintEditor` | Editor | `Default` | no (private only) | Slate pieces specific to the BP K2 nodes. |
+| `VoxelPCG` | Runtime | `Default` | yes | Bridge to Epic's PCG framework. PCG nodes that read/write voxel state plus voxel-graph nodes that operate on point sets. |
+| `VoxelPCGEditor` | Editor | `Default` | no (private only) | PCG node UI/customizations. |
+| `VoxelTests` | Runtime | `Default` | no | Automation tests; include-correctness checks when `VoxelDevWorkflow.txt` is present. |
+| `VoxelUHT` | UBT plugin | n/a | n/a | Custom UnrealHeaderTool exporter (`*.generated.voxel.cpp`) that codegens function-library wrappers around `UVoxelFunctionLibrary` and `FVoxelRuntimePinValue`. |
+
+`UncookedOnly` means `VoxelBlueprint` is built into editor/uncooked targets only — it ships nothing in packaged builds, because BP K2 node classes only exist to extend the Kismet compiler.
+
+## Loading phases
+
+Two modules load at `PostConfigInit` (very early, before most engine systems):
+
+- `VoxelCore` — needed early so `FVoxelMessageManager`, the `FVoxelDeveloperSettings` CDO, and the ISPC runtime are available before subsystems initialize.
+- `Voxel` — needs early load so `AVoxelWorld` subsystems can register themselves before the world begins streaming.
+
+`VoxelBlueprint` also loads `PostConfigInit` (but as `UncookedOnly`) so its K2 node factories are registered before the Blueprint editor opens any assets.
+
+Everything else loads at the `Default` phase.
+
+## Dependency graph
+
+```
+                              VoxelCore  ←─────────────────────────┐
+                                  ▲                                │
+                  ┌───────────────┼───────────────┐                │
+                  │               │               │                │
+              VoxelGraph        Voxel         VoxelPCG ───→ Voxel + VoxelGraph
+                  ▲               ▲               ▲                │
+                  │               │               │                │
+                  │               │               │                │
+            VoxelGraphEditor   VoxelEditor   VoxelPCGEditor        │
+                  ▲                                                │
+                  │                                                │
+            VoxelBlueprint ──→ Voxel + VoxelGraph + VoxelEditor + VoxelGraphEditor + VoxelCoreEditor
+                  ▲
+                  │
+            VoxelBlueprintEditor
+```
+
+(Arrow direction: A → B means A depends on B.)
+
+Concrete declarations from the `*.Build.cs` files:
+
+- `VoxelCore` adds engine deps `Chaos`, `Renderer`, `Projects`, `ApplicationCore`, `TraceLog`. Private deps include `zlib`, `UElibPNG`, `Json`, `HTTP`, `Landscape`, `EventLoop`, `MoviePlayer`. Editor builds pull in `MaterialEditor`, `UATHelper`, `GraphEditor`, `DesktopPlatform`.
+- `Voxel` depends on `VoxelGraph`, plus `Chaos`, `Renderer`, `PhysicsCore`, `Landscape`, `NavigationSystem`, `PCG`, `MeshDescription`, `StaticMeshDescription`.
+- `VoxelGraph` depends only on the standard set plus `TraceLog`, `Chaos`, `PhysicsCore`, `Json` (and `MessageLog` in editor).
+- `VoxelPCG` depends on `Voxel`, `VoxelGraph`, `PCG`.
+- `VoxelBlueprint` depends on `VoxelCoreEditor`, `Voxel`, `VoxelEditor`, `VoxelGraph`, `VoxelGraphEditor`, plus `BlueprintGraph` and `KismetCompiler` for K2 node integration.
+- `VoxelEditor` is the heaviest editor module — it depends on `Voxel`, `VoxelPCG`, `VoxelGraph`, `VoxelGraphEditor`, plus the full editor surface (`LevelEditor`, `AssetTools`, `PlacementMode`, `InteractiveToolsFramework`, `SceneOutliner`, `DetailCustomizations`, etc.).
+- `VoxelTests` depends only on `Json` and `NavigationSystem`.
+
+## ISPC and the build script
+
+`VoxelCore.Build.cs` defines `VoxelISPCCompiler`, which scans every module's `Source/<Module>/**.ispc` and `**.isph` files and generates a per-platform build script (`Intermediate/ISPC/<Platform>/<Arch>/<Editor>/<Config>/Build.ps1` or `Build.sh`). On Windows it downloads the same ISPC binary Unreal uses (`UnrealEngine-28863921/...`) if the engine copy is missing. ISPC is built into per-module static libraries (`libVoxel.a`, `libVoxelCore.a`, etc.) linked via `PublicAdditionalLibraries`.
+
+The cross-platform target matrix is hard-coded to:
+
+- `Win64` / `Linux` / `Mac (x64)` / `Android (x64)`: `avx512skx-i32x8`, `avx2`, `avx`, `sse4`
+- `LinuxArm64` / `Mac (arm64)` / `Android (arm64)` / `iOS` / `VisionOS`: `neon`
+
+## Build toggles
+
+Two opt-in flags live as marker files in the plugin's parent `Plugins/` directory:
+
+- `VoxelDevWorkflow.txt` — disables unity builds for `Win64` and `Mac` and switches off forced code optimization so iteration with a debugger is bearable. Also installs the IDE-friendly include-path that lets ReSharper/Rider see ISPC generated headers.
+- `VoxelDebug.txt` — forces the `VOXEL_DEBUG=1` define regardless of build configuration. Equivalently, building `Debug` (or `DebugGame` with dev workflow on) flips this on automatically.
+
+There's also `CheckPackaging.txt`: if present, all optimization is disabled (build-only sanity pass).
+
+## UHT extension
+
+`VoxelUHT/Program.cs` defines a single `[UhtExporter]` named `"VoxelGraph"` that:
+
+1. Locates `UVoxelFunctionLibrary` and `FVoxelRuntimePinValue` in the parsed metadata.
+2. Walks every header in the `VoxelGraph` module.
+3. For every class deriving from `UVoxelFunctionLibrary`, emits a `*.generated.voxel.cpp` file with the C++ glue that turns `UFUNCTION`-tagged static methods into compute-graph nodes.
+
+This is why writing a new voxel-graph function library node only requires a `UFUNCTION` declaration — the boilerplate that wires it into the graph system is generated by this UHT plugin at build time.
+
+## What's in each module's `Public/`
+
+| Module | Subfolders under `Public/` |
+|---|---|
+| `VoxelCore` | `VoxelMinimal/`, `VoxelMinimal/Containers/`, `VoxelMinimal/Utilities/`, root |
+| `Voxel` | `Collision/`, `Graphs/`, `Heightmap/`, `MegaMaterial/`, `Nanite/`, `Navigation/`, `Render/`, `Scatter/`, `Sculpt/`, `Shape/`, `Spline/`, `StaticMesh/`, `Surface/`, `Texture/`, root |
+| `VoxelGraph` | `Buffer/`, `FunctionLibrary/`, `Nodes/`, `Preview/`, `Utilities/`, root |
+| `VoxelPCG` | flat (no subfolders) |
+| `VoxelBlueprint` | flat (five K2 node headers) |
+| `VoxelCoreEditor`, `VoxelEditor`, `VoxelGraphEditor` | each has a `Public/`, but most concrete UI lives in `Private/` |
+| `VoxelBlueprintEditor`, `VoxelPCGEditor`, `VoxelTests` | private-only, no `Public/` |
+
+For per-module API detail see [VoxelCore](VoxelCore.md), [Voxel](Voxel.md), [VoxelGraph](VoxelGraph.md), [VoxelPCG](VoxelPCG.md), [VoxelBlueprint](VoxelBlueprint.md).

package/docs/README.md

@@ -0,0 +1,47 @@
+# Voxel Plugin — Reference Docs
+
+Reference docs for the [Voxel Plugin](https://voxelplugin.com) (Phyronnaz) — module map, public C++ surface per module, how the pieces fit together. They live in this repo because this is the ue-mcp wrapper for the Voxel Plugin, and the same reference material that helps wrapper-action authors also helps anyone building against the plugin from C++ or Blueprint.
+
+These docs are **API-level reference** — what's in each module, what the public types do, how the pieces relate. They complement, not replace, the official knowledgebase at <https://docs.voxelplugin.com/knowledgebase>, which covers task-oriented "how do I do X" workflows.
+
+## When to read what
+
+| You want… | Go here |
+|---|---|
+| "How do I author a stamp / use the graph editor / set up PCG?" | [Official KB](https://docs.voxelplugin.com/knowledgebase) — those pages exist and are decent. |
+| "What modules does this plugin actually ship, and how do they depend on each other?" | [Modules.md](Modules.md) |
+| "What's in the foundation module — containers, math, threading, ISPC?" | [VoxelCore.md](VoxelCore.md) |
+| "What's `AVoxelWorld`? What are stamps, layers, the runtime, sampling?" | [Voxel.md](Voxel.md) |
+| "How does the graph compile pipeline work? What's a buffer? What nodes ship?" | [VoxelGraph.md](VoxelGraph.md) |
+| "How do PCG and Voxel talk to each other?" | [VoxelPCG.md](VoxelPCG.md) |
+| "What K2 nodes does the plugin add to Blueprint?" | [VoxelBlueprint.md](VoxelBlueprint.md) |
+| "Is the test suite worth borrowing patterns from?" | [Tests.md](Tests.md) |
+
+## Doc scope
+
+These docs cover the **runtime + Blueprint** public API. Editor modules (`VoxelCoreEditor`, `VoxelEditor`, `VoxelGraphEditor`, `VoxelBlueprintEditor`, `VoxelPCGEditor`) are mentioned in [Modules.md](Modules.md) but not given their own reference pages — most of their public surface is detail customizations and Slate widgets that aren't useful to call from game code.
+
+The plugin's `Tests/` content and `VoxelTests` module are covered as a *pattern-mining* exercise in [Tests.md](Tests.md), not as exhaustive reference.
+
+## Conventions
+
+- File paths are written relative to the plugin source root (`Plugins/Voxel/Source/...`) unless they're inside a code block.
+- C++ type names use their actual prefixes (`F`, `U`, `A`, `T`, `S`, `I`) — `AVoxelWorld`, `UVoxelGraph`, `FVoxelBox`, `TVoxelArray<T>`.
+- Where the official KB has a corresponding page, the module doc links out to it.
+- Cross-doc links between these pages use relative paths so they work on disk and on a wiki host.
+
+## Plugin metadata
+
+- Source: <https://voxelplugin.com>
+- Docs (official, task-focused): <https://docs.voxelplugin.com/knowledgebase>
+- Discord (support): <https://discord.voxelplugin.com>
+- License: see `Plugins/Voxel/LICENSES.txt` in the plugin itself. Note in particular the Transvoxel attribution requirement called out in [VoxelCore.md](VoxelCore.md#transvoxel-data).
+- Loaded by default (`EnabledByDefault: true` in `Voxel.uplugin`).
+
+## Doc maintenance
+
+When the upstream plugin is bumped to a new version, this is what to refresh:
+
+1. [Modules.md](Modules.md) — re-read every `*.Build.cs`; phases and module-name changes happen at major version bumps.
+2. Per-module docs — `Glob` `Public/**/*.h` and reconcile against the listings here. New top-level types deserve a row; deleted ones should be removed.
+3. [Tests.md](Tests.md) — re-run the include-test count and check `VoxelTests.Build.cs` for new infrastructure files.