ue-mcp-plugin-voxel-plugin 0.1.1 → 0.3.0

package/README.md

@@ -2,21 +2,53 @@
 
 [Voxel Plugin](https://voxelplugin.com) actions for [ue-mcp](https://github.com/db-lyon/ue-mcp).
 
-## Status
+## What ships
 
-**v0.1.1 ships no actions.** The `0.1.0` release injected three placeholder
-actions (`voxel_scatter_meshes`, `voxel_spawn_stamps`, `voxel_bake_heightmap`)
-that called ue-mcp tasks with wrong parameter names and passed PCG node-type
-strings that do not exist. They have been removed rather than left as broken
-surface.
+Each action is cited to the C++ header it wraps. Full API reference under [`docs/`](docs/).
 
-Real tools, grounded in the actual Voxel Plugin C++ API, are tracked in
-[`TODO.md`](TODO.md). Every entry there cites the header file and class it
-wraps.
+| Category | Action                          | Wraps |
+|----------|---------------------------------|-------|
+| `pcg`    | `voxel_build_scatter_graph`     | `UPCGVoxelSamplerSettings` (`VoxelPCG/Public/PCGVoxelSampler.h`) feeding `UPCGStaticMeshSpawnerSettings` |
+| `level`  | `voxel_get_voxel_world_status`  | 5 zero-arg lifecycle UFUNCTIONs on `AVoxelWorld` (`Voxel/Public/VoxelWorld.h`) |
 
-Do not depend on this package yet — it intentionally exposes nothing.
+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.
 
-## Requirements (for future versions)
+## Install
+
+```bash
+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
+
+```text
+pcg(action="voxel_build_scatter_graph",
+    assetPath="/Game/PCG/RockScatter",
+    meshes=[
+      {mesh: "/Game/Foliage/Rock_A.Rock_A", weight: 2},
+      {mesh: "/Game/Foliage/Rock_B.Rock_B"}
+    ],
+    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
+pcg(action="execute", actorLabel="MyPCGActor")
+```
+
+Check the voxel world is actually live before scattering / stamping into it:
+
+```text
+level(action="voxel_get_voxel_world_status", actorLabel="MyVoxelWorld")
+```
+
+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.
+
+## Requirements
 
 - ue-mcp `>= 1.0.15`
 - Voxel Plugin enabled in your `.uproject` (`Plugins[].Name == "Voxel"`)

package/dist/tasks/BuildScatterGraph.d.ts

@@ -0,0 +1,29 @@
+import { BaseTask, type TaskResult } from "@db-lyon/flowkit";
+interface MeshEntry {
+    mesh: string;
+    weight?: number;
+}
+interface Options {
+    assetPath: string;
+    meshes: MeshEntry[];
+    pointsPerSquaredMeter?: number;
+    seed?: number;
+}
+/**
+ * Build a PCG graph that scatters weighted static meshes on a voxel terrain.
+ *
+ * Wraps `UPCGVoxelSamplerSettings` (VoxelPCG/Public/PCGVoxelSampler.h) feeding
+ * `UPCGStaticMeshSpawnerSettings`. The output asset is a UPCGGraph that the
+ * caller attaches to a PCG component (typically on or near an AVoxelWorld)
+ * before calling `pcg.execute`.
+ *
+ * Layer wiring (FVoxelStackLayer struct) is intentionally not exposed in v1.
+ * The sampler defaults to the UE-side default stack/layer, which is what an
+ * out-of-the-box voxel world uses.
+ */
+export default class BuildScatterGraph extends BaseTask<Options> {
+    get taskName(): string;
+    protected validate(): void;
+    execute(): Promise<TaskResult>;
+}
+export {};

package/dist/tasks/BuildScatterGraph.js

@@ -0,0 +1,102 @@
+import { BaseTask } from "@db-lyon/flowkit";
+/**
+ * Build a PCG graph that scatters weighted static meshes on a voxel terrain.
+ *
+ * Wraps `UPCGVoxelSamplerSettings` (VoxelPCG/Public/PCGVoxelSampler.h) feeding
+ * `UPCGStaticMeshSpawnerSettings`. The output asset is a UPCGGraph that the
+ * caller attaches to a PCG component (typically on or near an AVoxelWorld)
+ * before calling `pcg.execute`.
+ *
+ * Layer wiring (FVoxelStackLayer struct) is intentionally not exposed in v1.
+ * The sampler defaults to the UE-side default stack/layer, which is what an
+ * out-of-the-box voxel world uses.
+ */
+export default class BuildScatterGraph extends BaseTask {
+    get taskName() { return "voxel.build_scatter_graph"; }
+    validate() {
+        if (!this.options.assetPath)
+            throw new Error("assetPath is required");
+        if (!Array.isArray(this.options.meshes) || this.options.meshes.length === 0) {
+            throw new Error("meshes must be a non-empty array of { mesh, weight? } entries");
+        }
+        for (const m of this.options.meshes) {
+            if (!m?.mesh)
+                throw new Error("each meshes[] entry must include a `mesh` asset path");
+        }
+    }
+    async execute() {
+        const { assetPath, meshes, pointsPerSquaredMeter = 0.1, seed = 1 } = this.options;
+        const slash = assetPath.lastIndexOf("/");
+        if (slash <= 0) {
+            return { success: false, error: new Error(`assetPath must be a content path like /Game/Folder/Name, got: ${assetPath}`) };
+        }
+        const packagePath = assetPath.slice(0, slash);
+        const name = assetPath.slice(slash + 1);
+        const create = await this.call("pcg.create_graph", { name, packagePath });
+        if (!create.success) {
+            // Re-running over an existing graph is a supported workflow; only abort
+            // on hard failures, not on the "asset already exists" path.
+            const msg = create.error?.message ?? "";
+            if (!/exist|already/i.test(msg))
+                return create;
+        }
+        // Bridge's nodeType resolver only falls back to /Script/PCG.* — for
+        // VoxelPCG classes we pass the absolute object path so the first
+        // FindObject lookup hits.
+        const samplerR = await this.call("pcg.add_node", {
+            assetPath,
+            nodeType: "/Script/VoxelPCG.PCGVoxelSamplerSettings",
+        });
+        if (!samplerR.success)
+            return samplerR;
+        const samplerName = samplerR.data?.nodeName;
+        if (!samplerName)
+            return { success: false, error: new Error("pcg.add_node sampler returned no nodeName") };
+        const spawnerR = await this.call("pcg.add_node", {
+            assetPath,
+            nodeType: "/Script/PCG.PCGStaticMeshSpawnerSettings",
+        });
+        if (!spawnerR.success)
+            return spawnerR;
+        const spawnerName = spawnerR.data?.nodeName;
+        if (!spawnerName)
+            return { success: false, error: new Error("pcg.add_node spawner returned no nodeName") };
+        const settingsR = await this.call("pcg.set_node_settings", {
+            assetPath,
+            nodeName: samplerName,
+            settings: {
+                PointsPerSquaredMeter: pointsPerSquaredMeter,
+                Seed: seed,
+            },
+        });
+        if (!settingsR.success)
+            return settingsR;
+        const connectR = await this.call("pcg.connect_nodes", {
+            assetPath,
+            sourceNode: samplerName,
+            targetNode: spawnerName,
+        });
+        if (!connectR.success)
+            return connectR;
+        const meshesR = await this.call("pcg.set_static_mesh_spawner_meshes", {
+            assetPath,
+            nodeName: spawnerName,
+            entries: meshes,
+            replace: true,
+        });
+        if (!meshesR.success)
+            return meshesR;
+        return {
+            success: true,
+            data: {
+                assetPath,
+                samplerNode: samplerName,
+                spawnerNode: spawnerName,
+                meshCount: meshes.length,
+                pointsPerSquaredMeter,
+                seed,
+            },
+        };
+    }
+}
+//# sourceMappingURL=BuildScatterGraph.js.map

package/dist/tasks/BuildScatterGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuildScatterGraph.js","sourceRoot":"","sources":["../../src/tasks/BuildScatterGraph.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/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.