@plasius/gpu-world-generator 0.0.10 → 0.0.11

package/README.md

@@ -59,6 +59,28 @@ const { levelSpec, cells, terrain } = generateTemperateMixedForest({
 import terrainWgsl from "@plasius/gpu-world-generator/terrain.wgsl?raw";
 ```
 
+## Worker DAG Manifests
+
+`@plasius/gpu-world-generator` now publishes worker-first generation manifests
+so chunk and voxel work can be scheduled as a multi-root DAG instead of a flat
+queue.
+
+```js
+import { getWorldGeneratorWorkerManifest } from "@plasius/gpu-world-generator";
+
+const streaming = getWorldGeneratorWorkerManifest();
+const bake = getWorldGeneratorWorkerManifest("bake");
+
+console.log(streaming.jobs.map((job) => job.worker.jobType));
+console.log(bake.jobs.find((job) => job.key === "assetSerialize"));
+```
+
+- `streaming` models runtime chunk generation and mesh materialization.
+- `bake` extends the DAG with asset serialization for background/offline output.
+- Jobs include queue class, priority, dependencies, adaptive budget ladders, and
+  debug allocation tags for integration with `@plasius/gpu-performance` and
+  `@plasius/gpu-debug`.
+
 ## Demo
 The WebGPU mixed-forest demo lives in `demo/`. Run it with:
 
@@ -81,3 +103,5 @@ npm run pack:check
 ## Notes
 - For Vite/Pnpm setups, raw WGSL import is the most reliable.
 - See `docs/plan.md` for hierarchy and biome rules.
+- See `docs/design/worker-manifest-integration.md` for the chunk/voxel DAG
+  contract.

package/dist/index.cjs

@@ -59,11 +59,14 @@ __export(index_exports, {
   createPerfMonitor: () => createPerfMonitor,
   defaultFieldParams: () => defaultFieldParams,
   defaultFractalMandelSettings: () => defaultFractalMandelSettings,
+  defaultWorldGeneratorWorkerProfile: () => defaultWorldGeneratorWorkerProfile,
   encodeTerrainParams: () => encodeTerrainParams,
   fieldWgslUrl: () => fieldWgslUrl,
   fractalPrepassWgslUrl: () => fractalPrepassWgslUrl,
   generateHexGrid: () => generateHexGrid,
   generateTemperateMixedForest: () => generateTemperateMixedForest,
+  getWorldGeneratorWorkerManifest: () => getWorldGeneratorWorkerManifest,
+  getWorldGeneratorWorkerProfile: () => getWorldGeneratorWorkerProfile,
   hexAreaFromSide: () => hexAreaFromSide,
   hexSideFromArea: () => hexSideFromArea,
   loadFieldWgsl: () => loadFieldWgsl,
@@ -89,7 +92,12 @@ __export(index_exports, {
   tileKeyFromWorldPosition: () => tileKeyFromWorldPosition,
   tileKeyToString: () => tileKeyToString,
   unpackTerrain: () => unpackTerrain,
-  validateTileAssetPayload: () => validateTileAssetPayload
+  validateTileAssetPayload: () => validateTileAssetPayload,
+  worldGeneratorDebugOwner: () => worldGeneratorDebugOwner,
+  worldGeneratorWorkerManifests: () => worldGeneratorWorkerManifests,
+  worldGeneratorWorkerProfileNames: () => worldGeneratorWorkerProfileNames,
+  worldGeneratorWorkerProfiles: () => worldGeneratorWorkerProfiles,
+  worldGeneratorWorkerQueueClass: () => worldGeneratorWorkerQueueClass
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -1877,6 +1885,591 @@ function createMeshBuilder(sizeOrOptions = 1) {
     }
   };
 }
+
+// src/worker.ts
+var worldGeneratorDebugOwner = "world-generator";
+var worldGeneratorWorkerQueueClass = "voxel";
+var defaultWorldGeneratorWorkerProfile = "streaming";
+function buildBudgetLevels(jobType, queueClass, levels) {
+  return Object.freeze(
+    levels.map(
+      (level) => Object.freeze({
+        id: level.id,
+        estimatedCostMs: level.estimatedCostMs,
+        config: Object.freeze({
+          maxDispatchesPerFrame: level.config.maxDispatchesPerFrame,
+          maxJobsPerDispatch: level.config.maxJobsPerDispatch,
+          cadenceDivisor: level.config.cadenceDivisor,
+          workgroupScale: level.config.workgroupScale,
+          maxQueueDepth: level.config.maxQueueDepth,
+          metadata: Object.freeze({
+            owner: worldGeneratorDebugOwner,
+            queueClass,
+            jobType,
+            quality: level.id
+          })
+        })
+      })
+    )
+  );
+}
+var worldGeneratorWorkerProfileSpecs = {
+  streaming: {
+    description: "Runtime chunk generation DAG for fractal prepass, terrain synthesis, voxel materialization, mesh build, and tile bake.",
+    suggestedAllocationIds: [
+      "world.chunk.field.scratch",
+      "world.chunk.height.buffer",
+      "world.chunk.voxel.buffer",
+      "world.chunk.mesh.buffer"
+    ],
+    jobs: {
+      fractalPrepass: {
+        priority: 4,
+        dependencies: [],
+        domain: "custom",
+        authority: "authoritative",
+        importance: "high",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.6,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.chunk.field.scratch"]
+      },
+      fieldSynthesis: {
+        priority: 4,
+        dependencies: [],
+        domain: "custom",
+        authority: "authoritative",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 48
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.chunk.field.scratch"]
+      },
+      terrainSynthesis: {
+        priority: 5,
+        dependencies: ["fractalPrepass", "fieldSynthesis"],
+        domain: "custom",
+        authority: "authoritative",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 1.4,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.chunk.height.buffer"]
+      },
+      voxelMaterialize: {
+        priority: 3,
+        dependencies: ["terrainSynthesis"],
+        domain: "custom",
+        authority: "non-authoritative-simulation",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.8,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 2,
+              workgroupScale: 0.6,
+              maxQueueDepth: 24
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 1.2,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 32
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.8,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 40
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.chunk.voxel.buffer"]
+      },
+      meshBuild: {
+        priority: 2,
+        dependencies: ["terrainSynthesis", "voxelMaterialize"],
+        domain: "geometry",
+        authority: "visual",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.7,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 2,
+              workgroupScale: 0.6,
+              maxQueueDepth: 16
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 1.1,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 24
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.6,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.chunk.mesh.buffer"]
+      },
+      tileBake: {
+        priority: 2,
+        dependencies: ["terrainSynthesis"],
+        domain: "textures",
+        authority: "non-authoritative-simulation",
+        importance: "medium",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.6,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 3,
+              workgroupScale: 0.5,
+              maxQueueDepth: 16
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 2,
+              workgroupScale: 0.75,
+              maxQueueDepth: 24
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.3,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.chunk.height.buffer"]
+      }
+    }
+  },
+  bake: {
+    description: "Offline tile bake DAG for terrain generation, voxel materialization, mesh build, and asset serialization.",
+    suggestedAllocationIds: [
+      "world.bake.field.scratch",
+      "world.bake.height.buffer",
+      "world.bake.mesh.buffer",
+      "world.bake.asset.binary"
+    ],
+    jobs: {
+      fractalPrepass: {
+        priority: 4,
+        dependencies: [],
+        domain: "custom",
+        authority: "authoritative",
+        importance: "high",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 0.7,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.bake.field.scratch"]
+      },
+      fieldSynthesis: {
+        priority: 4,
+        dependencies: [],
+        domain: "custom",
+        authority: "authoritative",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 1,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 48
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.bake.field.scratch"]
+      },
+      terrainSynthesis: {
+        priority: 5,
+        dependencies: ["fractalPrepass", "fieldSynthesis"],
+        domain: "custom",
+        authority: "authoritative",
+        importance: "critical",
+        levels: [
+          {
+            id: "fixed",
+            estimatedCostMs: 1.6,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.bake.height.buffer"]
+      },
+      voxelMaterialize: {
+        priority: 3,
+        dependencies: ["terrainSynthesis"],
+        domain: "custom",
+        authority: "non-authoritative-simulation",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 2,
+              workgroupScale: 0.6,
+              maxQueueDepth: 24
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 1.4,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 32
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 2,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 48
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.bake.height.buffer"]
+      },
+      meshBuild: {
+        priority: 2,
+        dependencies: ["terrainSynthesis", "voxelMaterialize"],
+        domain: "geometry",
+        authority: "visual",
+        importance: "high",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.9,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 2,
+              workgroupScale: 0.6,
+              maxQueueDepth: 16
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 1.3,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 1,
+              workgroupScale: 0.8,
+              maxQueueDepth: 24
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.9,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.bake.mesh.buffer"]
+      },
+      tileBake: {
+        priority: 2,
+        dependencies: ["terrainSynthesis"],
+        domain: "textures",
+        authority: "non-authoritative-simulation",
+        importance: "medium",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.8,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 3,
+              workgroupScale: 0.5,
+              maxQueueDepth: 16
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 1.1,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 2,
+              workgroupScale: 0.75,
+              maxQueueDepth: 24
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1.5,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 32
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.bake.height.buffer"]
+      },
+      assetSerialize: {
+        priority: 1,
+        dependencies: ["meshBuild", "tileBake"],
+        domain: "custom",
+        authority: "non-authoritative-simulation",
+        importance: "medium",
+        levels: [
+          {
+            id: "low",
+            estimatedCostMs: 0.4,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 4,
+              workgroupScale: 0.5,
+              maxQueueDepth: 8
+            }
+          },
+          {
+            id: "medium",
+            estimatedCostMs: 0.7,
+            config: {
+              maxDispatchesPerFrame: 1,
+              maxJobsPerDispatch: 1,
+              cadenceDivisor: 2,
+              workgroupScale: 0.75,
+              maxQueueDepth: 12
+            }
+          },
+          {
+            id: "high",
+            estimatedCostMs: 1,
+            config: {
+              maxDispatchesPerFrame: 2,
+              maxJobsPerDispatch: 2,
+              cadenceDivisor: 1,
+              workgroupScale: 1,
+              maxQueueDepth: 16
+            }
+          }
+        ],
+        suggestedAllocationIds: ["world.bake.asset.binary"]
+      }
+    }
+  }
+};
+function buildWorldGeneratorWorkerProfile(name, spec) {
+  return Object.freeze({
+    name,
+    description: spec.description,
+    jobs: Object.freeze(Object.keys(spec.jobs))
+  });
+}
+function buildWorldGeneratorWorkerManifestJob(profileName, jobName, spec) {
+  const label = `world-generator.${profileName}.${jobName}`;
+  return Object.freeze({
+    key: jobName,
+    label,
+    worker: Object.freeze({
+      jobType: label,
+      queueClass: worldGeneratorWorkerQueueClass,
+      priority: spec.priority,
+      dependencies: Object.freeze(
+        spec.dependencies.map(
+          (dependency) => `world-generator.${profileName}.${dependency}`
+        )
+      ),
+      schedulerMode: "dag"
+    }),
+    performance: Object.freeze({
+      id: label,
+      jobType: label,
+      queueClass: worldGeneratorWorkerQueueClass,
+      domain: spec.domain,
+      authority: spec.authority,
+      importance: spec.importance,
+      levels: buildBudgetLevels(
+        label,
+        worldGeneratorWorkerQueueClass,
+        spec.levels
+      )
+    }),
+    debug: Object.freeze({
+      owner: worldGeneratorDebugOwner,
+      queueClass: worldGeneratorWorkerQueueClass,
+      jobType: label,
+      tags: Object.freeze(["world-generator", profileName, jobName, spec.domain]),
+      suggestedAllocationIds: Object.freeze([...spec.suggestedAllocationIds])
+    })
+  });
+}
+function buildWorldGeneratorWorkerManifest(name, spec) {
+  return Object.freeze({
+    schemaVersion: 1,
+    owner: worldGeneratorDebugOwner,
+    profile: name,
+    description: spec.description,
+    queueClass: worldGeneratorWorkerQueueClass,
+    schedulerMode: "dag",
+    suggestedAllocationIds: Object.freeze([...spec.suggestedAllocationIds]),
+    jobs: Object.freeze(
+      Object.entries(spec.jobs).map(
+        ([jobName, jobSpec]) => buildWorldGeneratorWorkerManifestJob(name, jobName, jobSpec)
+      )
+    )
+  });
+}
+var worldGeneratorWorkerProfiles = Object.freeze(
+  Object.fromEntries(
+    Object.entries(worldGeneratorWorkerProfileSpecs).map(([name, spec]) => [
+      name,
+      buildWorldGeneratorWorkerProfile(
+        name,
+        spec
+      )
+    ])
+  )
+);
+var worldGeneratorWorkerProfileNames = Object.freeze(
+  Object.keys(worldGeneratorWorkerProfiles)
+);
+var worldGeneratorWorkerManifests = Object.freeze(
+  Object.fromEntries(
+    Object.entries(worldGeneratorWorkerProfileSpecs).map(([name, spec]) => [
+      name,
+      buildWorldGeneratorWorkerManifest(
+        name,
+        spec
+      )
+    ])
+  )
+);
+function getWorldGeneratorWorkerProfile(name = defaultWorldGeneratorWorkerProfile) {
+  const profile = worldGeneratorWorkerProfiles[name];
+  if (!profile) {
+    const available = worldGeneratorWorkerProfileNames.join(", ");
+    throw new Error(
+      `Unknown world-generator worker profile "${name}". Available: ${available}.`
+    );
+  }
+  return profile;
+}
+function getWorldGeneratorWorkerManifest(name = defaultWorldGeneratorWorkerProfile) {
+  const manifest = worldGeneratorWorkerManifests[name];
+  if (!manifest) {
+    const available = worldGeneratorWorkerProfileNames.join(", ");
+    throw new Error(
+      `Unknown world-generator worker profile "${name}". Available: ${available}.`
+    );
+  }
+  return manifest;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_TILE_SIZE_WORLD,
@@ -1907,11 +2500,14 @@ function createMeshBuilder(sizeOrOptions = 1) {
   createPerfMonitor,
   defaultFieldParams,
   defaultFractalMandelSettings,
+  defaultWorldGeneratorWorkerProfile,
   encodeTerrainParams,
   fieldWgslUrl,
   fractalPrepassWgslUrl,
   generateHexGrid,
   generateTemperateMixedForest,
+  getWorldGeneratorWorkerManifest,
+  getWorldGeneratorWorkerProfile,
   hexAreaFromSide,
   hexSideFromArea,
   loadFieldWgsl,
@@ -1937,6 +2533,11 @@ function createMeshBuilder(sizeOrOptions = 1) {
   tileKeyFromWorldPosition,
   tileKeyToString,
   unpackTerrain,
-  validateTileAssetPayload
+  validateTileAssetPayload,
+  worldGeneratorDebugOwner,
+  worldGeneratorWorkerManifests,
+  worldGeneratorWorkerProfileNames,
+  worldGeneratorWorkerProfiles,
+  worldGeneratorWorkerQueueClass
 });
 //# sourceMappingURL=index.cjs.map