ue-mcp-plugin-voxel-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Lyon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# ue-mcp-plugin-voxel-plugin
+
+[Voxel Plugin](https://voxelplugin.com) actions for [ue-mcp](https://github.com/db-lyon/ue-mcp).
+
+Injects three actions into the existing built-in categories:
+
+| Category    | Action                    | What it does                                                          |
+|-------------|---------------------------|-----------------------------------------------------------------------|
+| `pcg`       | `voxel_scatter_meshes`    | Builds a PCG graph that scatters static meshes on a voxel terrain.    |
+| `pcg`       | `voxel_spawn_stamps`      | Builds a PCG graph that places voxel stamp assets.                    |
+| `landscape` | `voxel_bake_heightmap`    | Bakes a region of a voxel terrain into a standard Landscape heightmap.|
+
+Plus two ready-to-run flows: `voxel_scatter_setup` and `voxel_stamps_setup`.
+
+## Install
+
+In your project directory:
+
+```bash
+ue-mcp plugin install ue-mcp-plugin-voxel-plugin
+```
+
+The CLI runs `npm install --save`, validates the plugin manifest, adds an entry under `plugins:` in your `ue-mcp.yml`, and prints a restart instruction. Injected actions appear on the next ue-mcp server start.
+
+## Requirements
+
+- ue-mcp `>= 1.0.15`.
+- Voxel Plugin enabled in your `.uproject` (`Plugins[].Name == "Voxel"`). The installer warns at install time if it's missing.
+- An active Voxel Plugin Pro subscription if your project's use case requires it - the upstream source repo is public-readable but commercial use is gated by the upstream license.
+
+## Usage
+
+The actions appear natively inside their host categories - no new tool to learn:
+
+```text
+pcg(action="voxel_scatter_meshes",
+    graphPath="/Game/PCG/Scatter",
+    mesh="/Game/Foliage/Rock.Rock",
+    density=0.25)
+
+pcg(action="execute", graphPath="/Game/PCG/Scatter")
+```
+
+Or via the bundled flow:
+
+```text
+flow(action="run", flowName="voxel_scatter_setup", params={
+  graphPath: "/Game/PCG/Scatter",
+  mesh: "/Game/Foliage/Rock.Rock"
+})
+```
+
+See `knowledge/pcg.md` and `knowledge/landscape.md` for the full parameter reference. The same content is attached to the host category's AI-facing docs at server start so MCP agents see it natively.
+
+## Develop
+
+```bash
+git clone https://github.com/db-lyon/ue-mcp-plugin-voxel-plugin.git
+cd ue-mcp-plugin-voxel-plugin
+npm install
+npm run build
+```
+
+The plugin compiles to `dist/`. To test against a local checkout of ue-mcp, `npm link` this package and `npm link ue-mcp-plugin-voxel-plugin` from your project directory.
+
+## Why a plugin?
+
+ue-mcp's plugin model injects new actions into existing built-in categories rather than creating a separate tool. The agent already working in `pcg` discovers `voxel_scatter_meshes` exactly when it's relevant - it does not need to know there is a separate Voxel surface to open. See the [ue-mcp plugin docs](https://db-lyon.github.io/ue-mcp/plugins/) for the full author contract.
+
+## License
+
+MIT - see `LICENSE`.

package/dist/shared/voxelGraph.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-task helpers for building Voxel-Plugin-flavoured PCG graphs. None of
+ * these are referenced by ue-mcp.plugin.yml directly - task files import them.
+ *
+ * The exact PCG node-type names depend on the Voxel Plugin version installed.
+ * They are intentionally string constants so they can be updated in one
+ * place when the plugin's exposed nodes shift.
+ */
+export declare const VOXEL_NODES: {
+    /** Samples the active voxel volume in PCG space. */
+    readonly voxelSampler: "VoxelSampler";
+    /** Surface sampler that filters points to voxel-terrain surface positions. */
+    readonly surfaceSampler: "PCGSurfaceSampler";
+    /** Static-mesh spawner consuming the points from the surface sampler. */
+    readonly staticMeshSpawner: "PCGStaticMeshSpawner";
+    /** Stamp-spawner specific to Voxel Plugin's stamp asset format. */
+    readonly voxelStamp: "VoxelStamp";
+    /** Density filter for thinning out sampled points. */
+    readonly densityFilter: "PCGDensityFilter";
+    /** Transform-randomiser for scale/rotation jitter. */
+    readonly transformPoints: "PCGTransformPoints";
+};
+export type VoxelNodeKey = keyof typeof VOXEL_NODES;
+/**
+ * Type-safe wrapper around `this.call('pcg.add_node', ...)`. Returns the
+ * caller-visible node id reported by the bridge, or throws so the task gets
+ * a meaningful error.
+ */
+export declare function addNode(task: unknown, graphPath: string, nodeKey: VoxelNodeKey): Promise<string>;
+export declare function connectNodes(task: unknown, graphPath: string, sourceId: string, targetId: string): Promise<void>;
+export declare function setNodeSettings(task: unknown, graphPath: string, nodeId: string, settings: Record<string, unknown>): Promise<void>;

package/dist/shared/voxelGraph.js

@@ -0,0 +1,65 @@
+/**
+ * Cross-task helpers for building Voxel-Plugin-flavoured PCG graphs. None of
+ * these are referenced by ue-mcp.plugin.yml directly - task files import them.
+ *
+ * The exact PCG node-type names depend on the Voxel Plugin version installed.
+ * They are intentionally string constants so they can be updated in one
+ * place when the plugin's exposed nodes shift.
+ */
+export const VOXEL_NODES = {
+    /** Samples the active voxel volume in PCG space. */
+    voxelSampler: "VoxelSampler",
+    /** Surface sampler that filters points to voxel-terrain surface positions. */
+    surfaceSampler: "PCGSurfaceSampler",
+    /** Static-mesh spawner consuming the points from the surface sampler. */
+    staticMeshSpawner: "PCGStaticMeshSpawner",
+    /** Stamp-spawner specific to Voxel Plugin's stamp asset format. */
+    voxelStamp: "VoxelStamp",
+    /** Density filter for thinning out sampled points. */
+    densityFilter: "PCGDensityFilter",
+    /** Transform-randomiser for scale/rotation jitter. */
+    transformPoints: "PCGTransformPoints",
+};
+function callable(task) {
+    return task;
+}
+/**
+ * Type-safe wrapper around `this.call('pcg.add_node', ...)`. Returns the
+ * caller-visible node id reported by the bridge, or throws so the task gets
+ * a meaningful error.
+ */
+export async function addNode(task, graphPath, nodeKey) {
+    const r = await callable(task).call("pcg.add_node", {
+        graphPath,
+        nodeType: VOXEL_NODES[nodeKey],
+    });
+    if (!r.success) {
+        throw new Error(`pcg.add_node ${nodeKey} failed: ${r.error?.message ?? "unknown"}`);
+    }
+    const id = (r.data?.nodeId ?? r.data?.id);
+    if (!id) {
+        throw new Error(`pcg.add_node ${nodeKey} did not return a node id`);
+    }
+    return id;
+}
+export async function connectNodes(task, graphPath, sourceId, targetId) {
+    const r = await callable(task).call("pcg.connect_nodes", {
+        graphPath,
+        sourceNodeId: sourceId,
+        targetNodeId: targetId,
+    });
+    if (!r.success) {
+        throw new Error(`pcg.connect_nodes failed: ${r.error?.message ?? "unknown"}`);
+    }
+}
+export async function setNodeSettings(task, graphPath, nodeId, settings) {
+    const r = await callable(task).call("pcg.set_node_settings", {
+        graphPath,
+        nodeId,
+        settings,
+    });
+    if (!r.success) {
+        throw new Error(`pcg.set_node_settings failed: ${r.error?.message ?? "unknown"}`);
+    }
+}
+//# sourceMappingURL=voxelGraph.js.map

package/dist/shared/voxelGraph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voxelGraph.js","sourceRoot":"","sources":["../../src/shared/voxelGraph.ts"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,oDAAoD;IACpD,YAAY,EAAE,cAAc;IAC5B,8EAA8E;IAC9E,cAAc,EAAE,mBAAmB;IACnC,yEAAyE;IACzE,iBAAiB,EAAE,sBAAsB;IACzC,mEAAmE;IACnE,UAAU,EAAE,YAAY;IACxB,sDAAsD;IACtD,aAAa,EAAE,kBAAkB;IACjC,sDAAsD;IACtD,eAAe,EAAE,oBAAoB;CAC7B,CAAC;AAaX,SAAS,QAAQ,CAAC,IAAa;IAC7B,OAAO,IAAmB,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,OAAO,CAC3B,IAAa,EACb,SAAiB,EACjB,OAAqB;IAErB,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,cAAc,EAAE;QAClD,SAAS;QACT,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC;KAC/B,CAAC,CAAC;IACH,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,gBAAgB,OAAO,YAAY,CAAC,CAAC,KAAK,EAAE,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC;IACtF,CAAC;IACD,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,MAAM,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAuB,CAAC;IAChE,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,gBAAgB,OAAO,2BAA2B,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAa,EACb,SAAiB,EACjB,QAAgB,EAChB,QAAgB;IAEhB,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,mBAAmB,EAAE;QACvD,SAAS;QACT,YAAY,EAAE,QAAQ;QACtB,YAAY,EAAE,QAAQ;KACvB,CAAC,CAAC;IACH,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC,KAAK,EAAE,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC;IAChF,CAAC;AACH,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,IAAa,EACb,SAAiB,EACjB,MAAc,EACd,QAAiC;IAEjC,MAAM,CAAC,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,uBAAuB,EAAE;QAC3D,SAAS;QACT,MAAM;QACN,QAAQ;KACT,CAAC,CAAC;IACH,IAAI,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC,KAAK,EAAE,OAAO,IAAI,SAAS,EAAE,CAAC,CAAC;IACpF,CAAC;AACH,CAAC"}

package/dist/tasks/BakeHeightmap.d.ts

@@ -0,0 +1,37 @@
+import { BaseTask, type TaskResult } from "@db-lyon/flowkit";
+interface Bounds {
+    min: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+    max: {
+        x: number;
+        y: number;
+        z?: number;
+    };
+}
+interface Options {
+    landscapeLabel: string;
+    bounds: Bounds;
+    /** Heightmap side length in samples. Default 1009 (UE landscape-friendly). */
+    resolution?: number;
+}
+/**
+ * Bakes a region of a Voxel Plugin terrain to a Landscape heightmap.
+ *
+ * Pipeline:
+ *  1. Sample the voxel surface at a grid resolution by issuing Python through
+ *     the editor (the C++ bridge has no direct Voxel Plugin API surface).
+ *  2. Pipe the resulting heightfield into `landscape.import_heightmap`.
+ *
+ * The Python step is the escape hatch documented in CLAUDE.md and is
+ * acceptable here because Voxel Plugin exposes no native PCG-side way to
+ * extract raw voxel heights into the engine's landscape format.
+ */
+export default class BakeHeightmap extends BaseTask<Options> {
+    get taskName(): string;
+    protected validate(): void;
+    execute(): Promise<TaskResult>;
+}
+export {};

package/dist/tasks/BakeHeightmap.js

@@ -0,0 +1,101 @@
+import { BaseTask } from "@db-lyon/flowkit";
+/**
+ * Bakes a region of a Voxel Plugin terrain to a Landscape heightmap.
+ *
+ * Pipeline:
+ *  1. Sample the voxel surface at a grid resolution by issuing Python through
+ *     the editor (the C++ bridge has no direct Voxel Plugin API surface).
+ *  2. Pipe the resulting heightfield into `landscape.import_heightmap`.
+ *
+ * The Python step is the escape hatch documented in CLAUDE.md and is
+ * acceptable here because Voxel Plugin exposes no native PCG-side way to
+ * extract raw voxel heights into the engine's landscape format.
+ */
+export default class BakeHeightmap extends BaseTask {
+    get taskName() { return "voxel.bake_heightmap"; }
+    validate() {
+        if (!this.options.landscapeLabel)
+            throw new Error("landscapeLabel is required");
+        if (!this.options.bounds?.min || !this.options.bounds?.max) {
+            throw new Error("bounds.min and bounds.max are required");
+        }
+    }
+    async execute() {
+        const { landscapeLabel, bounds, resolution = 1009 } = this.options;
+        // 1. Sample voxel heights via Python. The script writes a raw uint16
+        //    heightmap to the project's intermediate dir and returns its path.
+        const sample = await this.call("editor.execute_python", {
+            script: buildVoxelSampleScript(bounds, resolution),
+        });
+        if (!sample.success)
+            return sample;
+        const heightmapPath = (sample.data?.result ?? sample.data?.output ?? sample.data?.heightmapPath);
+        if (!heightmapPath) {
+            return {
+                success: false,
+                error: new Error("voxel sample script did not return a heightmap path"),
+            };
+        }
+        // 2. Import the heightmap into the target landscape actor.
+        const imported = await this.call("landscape.import_heightmap", {
+            actorLabel: landscapeLabel,
+            heightmapPath,
+            resolution,
+        });
+        if (!imported.success)
+            return imported;
+        return {
+            success: true,
+            data: {
+                landscapeLabel,
+                heightmapPath,
+                resolution,
+                bounds,
+            },
+        };
+    }
+}
+function buildVoxelSampleScript(bounds, resolution) {
+    // The script is kept in a single string so the bridge ships it verbatim to
+    // Python. It is intentionally defensive: any Voxel Plugin API the host
+    // installation may not have is caught and reported as a clear error rather
+    // than a traceback.
+    return `
+import unreal, os, struct
+
+bounds_min = (${bounds.min.x}, ${bounds.min.y})
+bounds_max = (${bounds.max.x}, ${bounds.max.y})
+res = ${resolution}
+
+try:
+    voxel_lib = unreal.VoxelBlueprintLibrary  # exposed by Voxel Plugin at runtime
+except AttributeError:
+    raise RuntimeError("Voxel Plugin not loaded - voxel.bake_heightmap requires the Voxel plugin")
+
+dx = (bounds_max[0] - bounds_min[0]) / float(res - 1)
+dy = (bounds_max[1] - bounds_min[1]) / float(res - 1)
+
+samples = bytearray()
+for j in range(res):
+    for i in range(res):
+        x = bounds_min[0] + i * dx
+        y = bounds_min[1] + j * dy
+        try:
+            h = voxel_lib.get_voxel_height_at(x, y)
+        except Exception:
+            h = 0.0
+        # Map [-32768, 32767] cm into uint16. Adjust per project needs.
+        sample = max(0, min(65535, int(h + 32768)))
+        samples += struct.pack("<H", sample)
+
+out_dir = os.path.join(unreal.Paths.project_intermediate_dir(), "Voxel")
+os.makedirs(out_dir, exist_ok=True)
+out_path = os.path.join(out_dir, "voxel_heightmap.r16")
+with open(out_path, "wb") as f:
+    f.write(samples)
+
+# The bridge serialises whatever we print as the script result.
+print(out_path)
+`.trim();
+}
+//# sourceMappingURL=BakeHeightmap.js.map

package/dist/tasks/BakeHeightmap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BakeHeightmap.js","sourceRoot":"","sources":["../../src/tasks/BakeHeightmap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,MAAM,kBAAkB,CAAC;AAc7D;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,QAAiB;IAC1D,IAAI,QAAQ,KAAa,OAAO,sBAAsB,CAAC,CAAC,CAAC;IAE/C,QAAQ;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,cAAc;YAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChF,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC;YAC3D,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAEnE,qEAAqE;QACrE,uEAAuE;QACvE,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,uBAAuB,EAAE;YACtD,MAAM,EAAE,sBAAsB,CAAC,MAAM,EAAE,UAAU,CAAC;SACnD,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC,OAAO;YAAE,OAAO,MAAM,CAAC;QAEnC,MAAM,aAAa,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,MAAM,CAAC,IAAI,EAAE,aAAa,CAAuB,CAAC;QACvH,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,IAAI,KAAK,CAAC,qDAAqD,CAAC;aACxE,CAAC;QACJ,CAAC;QAED,2DAA2D;QAC3D,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,4BAA4B,EAAE;YAC7D,UAAU,EAAE,cAAc;YAC1B,aAAa;YACb,UAAU;SACX,CAAC,CAAC;QACH,IAAI,CAAC,QAAQ,CAAC,OAAO;YAAE,OAAO,QAAQ,CAAC;QAEvC,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE;gBACJ,cAAc;gBACd,aAAa;gBACb,UAAU;gBACV,MAAM;aACP;SACF,CAAC;IACJ,CAAC;CACF;AAED,SAAS,sBAAsB,CAAC,MAAc,EAAE,UAAkB;IAChE,2EAA2E;IAC3E,uEAAuE;IACvE,2EAA2E;IAC3E,oBAAoB;IACpB,OAAO;;;gBAGO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC;gBAC7B,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,MAAM,CAAC,GAAG,CAAC,CAAC;QACrC,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BjB,CAAC,IAAI,EAAE,CAAC;AACT,CAAC"}

package/dist/tasks/ScatterMeshes.d.ts

@@ -0,0 +1,25 @@
+import { BaseTask, type TaskResult } from "@db-lyon/flowkit";
+interface Options {
+    graphPath: string;
+    mesh: string;
+    density?: number;
+    minScale?: number;
+    maxScale?: number;
+    seed?: number;
+}
+/**
+ * Builds a PCG graph that scatters static meshes on a Voxel Plugin
+ * terrain. Pipeline: VoxelSampler → SurfaceSampler → DensityFilter →
+ * TransformPoints → StaticMeshSpawner.
+ *
+ * Idempotency: if the graph already exists, the task assumes the caller
+ * wants a fresh build and will append nodes. Callers expecting strict
+ * idempotency should delete the graph first via `pcg(action="delete_graph")`
+ * (or skip the call entirely when no rebuild is needed).
+ */
+export default class ScatterMeshes extends BaseTask<Options> {
+    get taskName(): string;
+    protected validate(): void;
+    execute(): Promise<TaskResult>;
+}
+export {};

package/dist/tasks/ScatterMeshes.js

@@ -0,0 +1,52 @@
+import { BaseTask } from "@db-lyon/flowkit";
+import { addNode, connectNodes, setNodeSettings } from "../shared/voxelGraph.js";
+/**
+ * Builds a PCG graph that scatters static meshes on a Voxel Plugin
+ * terrain. Pipeline: VoxelSampler → SurfaceSampler → DensityFilter →
+ * TransformPoints → StaticMeshSpawner.
+ *
+ * Idempotency: if the graph already exists, the task assumes the caller
+ * wants a fresh build and will append nodes. Callers expecting strict
+ * idempotency should delete the graph first via `pcg(action="delete_graph")`
+ * (or skip the call entirely when no rebuild is needed).
+ */
+export default class ScatterMeshes extends BaseTask {
+    get taskName() { return "voxel.scatter_meshes"; }
+    validate() {
+        if (!this.options.graphPath)
+            throw new Error("graphPath is required");
+        if (!this.options.mesh)
+            throw new Error("mesh is required");
+    }
+    async execute() {
+        const { graphPath, mesh, density = 0.25, minScale = 0.8, maxScale = 1.4, seed = 1 } = this.options;
+        // Create the graph (no-op if pcg.create_graph rejects an existing one;
+        // we proceed regardless so add_node can land on a pre-existing graph).
+        await this.call("pcg.create_graph", { path: graphPath });
+        const sampler = await addNode(this, graphPath, "voxelSampler");
+        const surface = await addNode(this, graphPath, "surfaceSampler");
+        const density_ = await addNode(this, graphPath, "densityFilter");
+        const transform = await addNode(this, graphPath, "transformPoints");
+        const spawner = await addNode(this, graphPath, "staticMeshSpawner");
+        await setNodeSettings(this, graphPath, surface, { PointsPerSquaredMeter: density });
+        await setNodeSettings(this, graphPath, density_, { LowerBound: 0.0, UpperBound: 1.0, Seed: seed });
+        await setNodeSettings(this, graphPath, transform, { MinScale: minScale, MaxScale: maxScale, Seed: seed });
+        await setNodeSettings(this, graphPath, spawner, { StaticMesh: mesh });
+        await connectNodes(this, graphPath, sampler, surface);
+        await connectNodes(this, graphPath, surface, density_);
+        await connectNodes(this, graphPath, density_, transform);
+        await connectNodes(this, graphPath, transform, spawner);
+        return {
+            success: true,
+            data: {
+                graphPath,
+                nodes: { sampler, surface, density: density_, transform, spawner },
+                mesh,
+            },
+            // No automatic rollback - PCG node creation/connection has no inverse
+            // exposed by the bridge. Callers wanting safety should run inside a
+            // flow with git_snapshot enabled.
+        };
+    }
+}
+//# sourceMappingURL=ScatterMeshes.js.map

package/dist/tasks/ScatterMeshes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ScatterMeshes.js","sourceRoot":"","sources":["../../src/tasks/ScatterMeshes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAWjF;;;;;;;;;GASG;AACH,MAAM,CAAC,OAAO,OAAO,aAAc,SAAQ,QAAiB;IAC1D,IAAI,QAAQ,KAAa,OAAO,sBAAsB,CAAC,CAAC,CAAC;IAE/C,QAAQ;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,EAAE,QAAQ,GAAG,GAAG,EAAE,QAAQ,GAAG,GAAG,EAAE,IAAI,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAEnG,uEAAuE;QACvE,uEAAuE;QACvE,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAEzD,MAAM,OAAO,GAAK,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;QACjE,MAAM,OAAO,GAAK,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAC;QACnE,MAAM,QAAQ,GAAI,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;QAClE,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,iBAAiB,CAAC,CAAC;QACpE,MAAM,OAAO,GAAK,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,mBAAmB,CAAC,CAAC;QAEtE,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,CAAC,CAAC;QACtF,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAG,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACpG,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1G,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;QAExE,MAAM,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAI,OAAO,CAAC,CAAC;QACxD,MAAM,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAI,QAAQ,CAAC,CAAC;QACzD,MAAM,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAG,SAAS,CAAC,CAAC;QAC1D,MAAM,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC;QAExD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE;gBACJ,SAAS;gBACT,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE;gBAClE,IAAI;aACL;YACD,sEAAsE;YACtE,oEAAoE;YACpE,kCAAkC;SACnC,CAAC;IACJ,CAAC;CACF"}

package/dist/tasks/SpawnStamps.d.ts

@@ -0,0 +1,23 @@
+import { BaseTask, type TaskResult } from "@db-lyon/flowkit";
+interface Options {
+    graphPath: string;
+    stampAsset: string;
+    count?: number;
+    radius?: number;
+    seed?: number;
+}
+/**
+ * Builds a PCG graph that places voxel stamp assets across a terrain. Pipeline:
+ * VoxelSampler → SurfaceSampler → DensityFilter (thinning by `count`) →
+ * VoxelStamp.
+ *
+ * `count` is a soft cap - the density filter approximates it from the sampled
+ * point cloud, so the final placement count varies with the underlying voxel
+ * volume density.
+ */
+export default class SpawnStamps extends BaseTask<Options> {
+    get taskName(): string;
+    protected validate(): void;
+    execute(): Promise<TaskResult>;
+}
+export {};

package/dist/tasks/SpawnStamps.js

@@ -0,0 +1,51 @@
+import { BaseTask } from "@db-lyon/flowkit";
+import { addNode, connectNodes, setNodeSettings } from "../shared/voxelGraph.js";
+/**
+ * Builds a PCG graph that places voxel stamp assets across a terrain. Pipeline:
+ * VoxelSampler → SurfaceSampler → DensityFilter (thinning by `count`) →
+ * VoxelStamp.
+ *
+ * `count` is a soft cap - the density filter approximates it from the sampled
+ * point cloud, so the final placement count varies with the underlying voxel
+ * volume density.
+ */
+export default class SpawnStamps extends BaseTask {
+    get taskName() { return "voxel.spawn_stamps"; }
+    validate() {
+        if (!this.options.graphPath)
+            throw new Error("graphPath is required");
+        if (!this.options.stampAsset)
+            throw new Error("stampAsset is required");
+    }
+    async execute() {
+        const { graphPath, stampAsset, count = 50, radius = 500, seed = 1 } = this.options;
+        await this.call("pcg.create_graph", { path: graphPath });
+        const sampler = await addNode(this, graphPath, "voxelSampler");
+        const surface = await addNode(this, graphPath, "surfaceSampler");
+        const density_ = await addNode(this, graphPath, "densityFilter");
+        const stamp = await addNode(this, graphPath, "voxelStamp");
+        // PointsPerSquaredMeter is approximated from count/radius² to give the
+        // surface sampler a sensible density for the desired stamp count.
+        const pointsPerSqM = Math.max(0.0001, count / (Math.PI * radius * radius));
+        await setNodeSettings(this, graphPath, surface, {
+            PointsPerSquaredMeter: pointsPerSqM,
+            Radius: radius,
+            Seed: seed,
+        });
+        await setNodeSettings(this, graphPath, density_, { LowerBound: 0.5, UpperBound: 1.0, Seed: seed });
+        await setNodeSettings(this, graphPath, stamp, { StampAsset: stampAsset });
+        await connectNodes(this, graphPath, sampler, surface);
+        await connectNodes(this, graphPath, surface, density_);
+        await connectNodes(this, graphPath, density_, stamp);
+        return {
+            success: true,
+            data: {
+                graphPath,
+                nodes: { sampler, surface, density: density_, stamp },
+                stampAsset,
+                countEstimate: count,
+            },
+        };
+    }
+}
+//# sourceMappingURL=SpawnStamps.js.map

package/dist/tasks/SpawnStamps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SpawnStamps.js","sourceRoot":"","sources":["../../src/tasks/SpawnStamps.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAmB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAUjF;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,OAAO,WAAY,SAAQ,QAAiB;IACxD,IAAI,QAAQ,KAAa,OAAO,oBAAoB,CAAC,CAAC,CAAC;IAE7C,QAAQ;QAChB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;QACtE,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,UAAU;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,GAAG,EAAE,EAAE,MAAM,GAAG,GAAG,EAAE,IAAI,GAAG,CAAC,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC;QAEnF,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC;QAEzD,MAAM,OAAO,GAAI,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,cAAc,CAAC,CAAC;QAChE,MAAM,OAAO,GAAI,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,gBAAgB,CAAC,CAAC;QAClE,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,eAAe,CAAC,CAAC;QACjE,MAAM,KAAK,GAAM,MAAM,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,YAAY,CAAC,CAAC;QAE9D,uEAAuE;QACvE,kEAAkE;QAClE,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,KAAK,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;QAE3E,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE;YAC9C,qBAAqB,EAAE,YAAY;YACnC,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,IAAI;SACX,CAAC,CAAC;QACH,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACnG,MAAM,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAK,EAAE,UAAU,EAAE,UAAU,EAAE,CAAC,CAAC;QAE7E,MAAM,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAG,OAAO,CAAC,CAAC;QACvD,MAAM,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAG,QAAQ,CAAC,CAAC;QACxD,MAAM,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC;QAErD,OAAO;YACL,OAAO,EAAE,IAAI;YACb,IAAI,EAAE;gBACJ,SAAS;gBACT,KAAK,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE;gBACrD,UAAU;gBACV,aAAa,EAAE,KAAK;aACrB;SACF,CAAC;IACJ,CAAC;CACF"}

package/knowledge/landscape.md

@@ -0,0 +1,34 @@
+# Voxel Plugin - Landscape actions
+
+This plugin contributes one landscape-side action for [Voxel Plugin](https://voxelplugin.com):
+
+- `landscape(action="voxel_bake_heightmap", ...)` - bake a region of a voxel terrain into a standard UE Landscape heightmap.
+
+## When to use
+
+Use it when the user wants to convert a voxel terrain (or a region of it) into a standard Landscape actor for the parts of the workflow that need it: high-quality runtime LOD, foliage painting, landscape materials, etc.
+
+The reverse conversion (Landscape → voxel) is not part of this plugin.
+
+## Typical sequence
+
+```
+landscape(action="voxel_bake_heightmap",
+          landscapeLabel="Landscape",
+          bounds={ min: {x: 0,    y: 0},
+                   max: {x: 8064, y: 8064} },
+          resolution=1009)
+```
+
+The action samples voxel heights on a `resolution x resolution` grid spanning `bounds`, writes a raw uint16 heightmap to `Intermediate/Voxel/voxel_heightmap.r16`, then imports it into the target landscape via the built-in `landscape.import_heightmap` action.
+
+## Parameters
+
+- `landscapeLabel` (required) - the in-editor label of the target Landscape actor.
+- `bounds` (required) - `{ min: {x, y}, max: {x, y} }` in world centimetres.
+- `resolution` (optional, default 1009) - heightmap side length in samples. Use a UE-friendly value: 127, 253, 505, 1009, 2017, 4033, 8129.
+
+## Notes
+
+- The Python escape hatch is used here because Voxel Plugin exposes its voxel heights to Python but not to PCG or the C++ bridge directly. The script is defensive: if `VoxelBlueprintLibrary` is not loaded it returns a clear error rather than a traceback.
+- Height mapping uses a centred uint16 range (offset +32768). If your voxel volume uses a different scale, adjust the script or wrap this action.

package/knowledge/pcg.md

@@ -0,0 +1,50 @@
+# Voxel Plugin - PCG actions
+
+This plugin contributes two PCG-side actions for [Voxel Plugin](https://voxelplugin.com) terrains:
+
+- `pcg(action="voxel_scatter_meshes", ...)` - build a graph that scatters static meshes on a voxel terrain via Voxel Sampler.
+- `pcg(action="voxel_spawn_stamps", ...)` - build a graph that places voxel stamp assets across a voxel terrain.
+
+## When to use
+
+Reach for these when the user wants procedural placement on a **voxel** terrain. For standard UE Landscape, use the built-in PCG nodes directly.
+
+## Typical sequence
+
+```
+pcg(action="create_graph", path="/Game/PCG/MyScatter")    # if no graph exists
+pcg(action="voxel_scatter_meshes",
+    graphPath="/Game/PCG/MyScatter",
+    mesh="/Game/Foliage/Rock01.Rock01",
+    density=0.25)
+pcg(action="execute", graphPath="/Game/PCG/MyScatter")    # materialise
+```
+
+The full setup is also available as a flow:
+
+```
+flow(action="run", flowName="voxel_scatter_setup", params={
+  graphPath: "/Game/PCG/MyScatter",
+  mesh: "/Game/Foliage/Rock01.Rock01"
+})
+```
+
+## Parameters
+
+`voxel_scatter_meshes`:
+- `graphPath` (required) - asset path of the PCG graph to build (created if missing).
+- `mesh` (required) - StaticMesh asset path to scatter.
+- `density` (optional, default 0.25) - points per square metre at the surface sampler.
+- `minScale` / `maxScale` (optional) - uniform scale jitter, default 0.8 .. 1.4.
+- `seed` (optional) - deterministic seed for the density filter and transform jitter.
+
+`voxel_spawn_stamps`:
+- `graphPath` (required).
+- `stampAsset` (required) - Voxel stamp asset path.
+- `count` (optional, default 50) - target stamp count; approximated via density.
+- `radius` (optional, default 500) - radius of the scatter region in cm.
+- `seed` (optional).
+
+## Requirements
+
+The host project must have the Voxel Plugin enabled in its `.uproject` as `Voxel` (the `.uplugin` filename). The plugin installer warns at install time if `Voxel` is missing; the actions themselves will fail with a clear error if the runtime types aren't loaded.

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "ue-mcp-plugin-voxel-plugin",
+  "version": "0.1.0",
+  "description": "Voxel Plugin actions for ue-mcp - voxel terrain scatter, stamps, and heightmap baking via PCG and Landscape.",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "ue-mcp.plugin.yml",
+    "knowledge",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ue-mcp-plugin",
+    "unreal-engine",
+    "ue5",
+    "voxel",
+    "voxel-plugin",
+    "pcg",
+    "landscape"
+  ],
+  "author": "David Lyon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/db-lyon/ue-mcp-plugin-voxel-plugin.git"
+  },
+  "peerDependencies": {
+    "@db-lyon/flowkit": "~0.5.2"
+  },
+  "devDependencies": {
+    "@db-lyon/flowkit": "~0.5.2",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/ue-mcp.plugin.yml

@@ -0,0 +1,64 @@
+actionPrefix: voxel
+minServerVersion: 1.0.15
+uePluginDependency: Voxel
+
+inject:
+  pcg:
+    scatter_meshes:
+      task: voxel.scatter_meshes
+      description: "Build a PCG graph that scatters static meshes on a voxel terrain via Voxel Sampler. Params: graphPath, mesh, density?, minScale?, maxScale?, seed?"
+      schema:
+        graphPath: { type: string, required: true }
+        mesh:      { type: string, required: true }
+        density:   { type: number }
+        minScale:  { type: number }
+        maxScale:  { type: number }
+        seed:      { type: number }
+    spawn_stamps:
+      task: voxel.spawn_stamps
+      description: "Build a PCG graph that places voxel stamp assets on a voxel terrain. Params: graphPath, stampAsset, count?, radius?, seed?"
+      schema:
+        graphPath:  { type: string, required: true }
+        stampAsset: { type: string, required: true }
+        count:      { type: number }
+        radius:     { type: number }
+        seed:       { type: number }
+
+  landscape:
+    bake_heightmap:
+      task: voxel.bake_heightmap
+      description: "Bake a region of a voxel terrain into a standard Landscape heightmap. Params: landscapeLabel, bounds, resolution?"
+      schema:
+        landscapeLabel: { type: string, required: true }
+        bounds:         { type: object, required: true }
+        resolution:     { type: number }
+
+knowledge:
+  pcg: knowledge/pcg.md
+  landscape: knowledge/landscape.md
+
+tasks:
+  voxel.scatter_meshes:
+    class_path: tasks/ScatterMeshes
+    description: "Build the PCG graph for voxel-terrain mesh scatter"
+  voxel.spawn_stamps:
+    class_path: tasks/SpawnStamps
+    description: "Build the PCG graph for voxel stamps"
+  voxel.bake_heightmap:
+    class_path: tasks/BakeHeightmap
+    description: "Bake a voxel-terrain region into a Landscape heightmap"
+
+flows:
+  voxel_scatter_setup:
+    description: "Create a PCG mesh-scatter graph on a voxel terrain and execute it"
+    rollback_on_failure: true
+    steps:
+      1: { task: voxel.scatter_meshes }
+      2: { task: pcg.execute }
+
+  voxel_stamps_setup:
+    description: "Create a PCG voxel-stamp graph and execute it"
+    rollback_on_failure: true
+    steps:
+      1: { task: voxel.spawn_stamps }
+      2: { task: pcg.execute }