ue-mcp-plugin-voxel-plugin 0.1.1 → 0.2.0

package/README.md

@@ -2,21 +2,44 @@
 
 [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.
+One injected action in v0.2.0, cited to its source:
 
-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` |
 
-Do not depend on this package yet — it intentionally exposes nothing.
+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.
 
-## 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")
+```
+
+## 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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ue-mcp-plugin-voxel-plugin",
-  "version": "0.1.1",
-  "description": "Voxel Plugin actions for ue-mcp. Scaffold only at this version - real tools tracked in TODO.md.",
+  "version": "0.2.0",
+  "description": "Voxel Plugin actions for ue-mcp. One real PCG action in 0.2.0 - rest tracked in TODO.md.",
   "type": "module",
   "main": "dist/index.js",
   "files": [

package/ue-mcp.plugin.yml

@@ -2,14 +2,22 @@ actionPrefix: voxel
 minServerVersion: 1.0.15
 uePluginDependency: Voxel
 
-# No actions ship in this version. The 0.1.0 release injected three
-# placeholder actions (voxel_scatter_meshes, voxel_spawn_stamps,
-# voxel_bake_heightmap) that called ue-mcp tasks with the wrong parameter
-# names and passed fabricated PCG node-type strings - none of them worked.
-# They have been removed. See TODO.md in the repo for the real API surface
-# and the prioritized list of tools being built against it.
-
-inject: {}
+inject:
+  pcg:
+    build_scatter_graph:
+      task: voxel.build_scatter_graph
+      description: "Build a PCG graph that scatters weighted static meshes on a voxel terrain. Wraps UPCGVoxelSamplerSettings (VoxelPCG/Public/PCGVoxelSampler.h) feeding the stock PCGStaticMeshSpawner. After creation, attach the graph to a PCG component (usually near an AVoxelWorld) and call pcg.execute. Params: assetPath (e.g. /Game/PCG/MyScatter), meshes=[{mesh, weight?}], pointsPerSquaredMeter? (default 0.1), seed? (default 1)."
+      schema:
+        assetPath:             { type: string, required: true }
+        meshes:                { type: array,  required: true }
+        pointsPerSquaredMeter: { type: number }
+        seed:                  { type: number }
+
 knowledge: {}
-tasks: {}
+
+tasks:
+  voxel.build_scatter_graph:
+    class_path: tasks/BuildScatterGraph
+    description: "Build a Voxel-Sampler-driven PCG mesh scatter graph"
+
 flows: {}