@plasius/gpu-world-generator 0.0.11 → 0.0.12

package/README.md

@@ -81,6 +81,30 @@ console.log(bake.jobs.find((job) => job.key === "assetSerialize"));
   debug allocation tags for integration with `@plasius/gpu-performance` and
   `@plasius/gpu-debug`.
 
+## Render Representation Plans
+
+`@plasius/gpu-world-generator` now also publishes explicit chunk
+representation-tier plans so renderer and worker packages can coordinate near,
+mid, far, and horizon outputs without guessing from distance alone.
+
+```js
+import { createWorldGeneratorRepresentationPlan } from "@plasius/gpu-world-generator";
+
+const plan = createWorldGeneratorRepresentationPlan({
+  chunkId: "hex-12-9",
+  profile: "streaming",
+  gameplayImportance: "critical",
+});
+
+console.log(plan.bands);
+console.log(plan.representations.find((entry) => entry.output === "rtProxy"));
+```
+
+Each plan exposes raster-facing and RT-facing outputs separately, plus refresh
+cadence, shadow relevance, chunk-identity preservation, and scheduling metadata
+that downstream renderer and worker packages can prioritize by band and
+importance.
+
 ## Demo
 The WebGPU mixed-forest demo lives in `demo/`. Run it with:
 

package/dist/index.cjs

@@ -57,6 +57,7 @@ __export(index_exports, {
   createFractalPrepassRunner: () => createFractalPrepassRunner,
   createMeshBuilder: () => createMeshBuilder,
   createPerfMonitor: () => createPerfMonitor,
+  createWorldGeneratorRepresentationPlan: () => createWorldGeneratorRepresentationPlan,
   defaultFieldParams: () => defaultFieldParams,
   defaultFractalMandelSettings: () => defaultFractalMandelSettings,
   defaultWorldGeneratorWorkerProfile: () => defaultWorldGeneratorWorkerProfile,
@@ -94,6 +95,8 @@ __export(index_exports, {
   unpackTerrain: () => unpackTerrain,
   validateTileAssetPayload: () => validateTileAssetPayload,
   worldGeneratorDebugOwner: () => worldGeneratorDebugOwner,
+  worldGeneratorRepresentationBands: () => worldGeneratorRepresentationBands,
+  worldGeneratorRepresentationOutputs: () => worldGeneratorRepresentationOutputs,
   worldGeneratorWorkerManifests: () => worldGeneratorWorkerManifests,
   worldGeneratorWorkerProfileNames: () => worldGeneratorWorkerProfileNames,
   worldGeneratorWorkerProfiles: () => worldGeneratorWorkerProfiles,
@@ -1890,6 +1893,64 @@ function createMeshBuilder(sizeOrOptions = 1) {
 var worldGeneratorDebugOwner = "world-generator";
 var worldGeneratorWorkerQueueClass = "voxel";
 var defaultWorldGeneratorWorkerProfile = "streaming";
+var worldGeneratorRepresentationBands = Object.freeze([
+  "near",
+  "mid",
+  "far",
+  "horizon"
+]);
+var worldGeneratorRepresentationOutputs = Object.freeze([
+  "liveGeometry",
+  "simplifiedGeometry",
+  "rtProxy",
+  "mergedProxy",
+  "horizonShell"
+]);
+var worldGeneratorRepresentationBandPriorityHints = Object.freeze({
+  near: 400,
+  mid: 300,
+  far: 200,
+  horizon: 100
+});
+function assertWorldGeneratorIdentifier(name, value) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+function normalizeWorldGeneratorImportance(name, value) {
+  if (value === "medium" || value === "high" || value === "critical") {
+    return value;
+  }
+  throw new Error(`${name} must be one of: medium, high, critical.`);
+}
+function buildWorldGeneratorRepresentationDescriptor(options) {
+  return Object.freeze({
+    id: `${options.chunkId}.${options.band}.${options.output}`,
+    chunkId: options.chunkId,
+    profile: options.profile,
+    band: options.band,
+    output: options.output,
+    rasterMode: options.rasterMode,
+    rtParticipation: options.rtParticipation,
+    shadowRelevance: options.shadowRelevance,
+    refreshCadence: Object.freeze({
+      kind: options.refreshCadence.kind,
+      divisor: options.refreshCadence.divisor
+    }),
+    preservesChunkIdentity: options.preservesChunkIdentity,
+    sourceChunkIds: Object.freeze([options.chunkId]),
+    sourceJobKeys: Object.freeze([...options.sourceJobKeys]),
+    suggestedAllocationIds: Object.freeze([...options.suggestedAllocationIds]),
+    scheduling: Object.freeze({
+      owner: "renderer",
+      queueClass: worldGeneratorWorkerQueueClass,
+      priorityHint: worldGeneratorRepresentationBandPriorityHints[options.band],
+      gameplayImportance: options.gameplayImportance,
+      representationBand: options.band
+    })
+  });
+}
 function buildBudgetLevels(jobType, queueClass, levels) {
   return Object.freeze(
     levels.map(
@@ -2470,6 +2531,108 @@ function getWorldGeneratorWorkerManifest(name = defaultWorldGeneratorWorkerProfi
   }
   return manifest;
 }
+function createWorldGeneratorRepresentationPlan(options) {
+  const profile = options.profile ?? defaultWorldGeneratorWorkerProfile;
+  const spec = worldGeneratorWorkerProfileSpecs[profile];
+  if (!spec) {
+    const available = worldGeneratorWorkerProfileNames.join(", ");
+    throw new Error(
+      `Unknown world-generator worker profile "${profile}". Available: ${available}.`
+    );
+  }
+  const chunkId = assertWorldGeneratorIdentifier("chunkId", options.chunkId);
+  const gameplayImportance = normalizeWorldGeneratorImportance(
+    "gameplayImportance",
+    options.gameplayImportance ?? "high"
+  );
+  const highValueAllocations = spec.suggestedAllocationIds;
+  const farFieldAllocations = spec.suggestedAllocationIds.filter(
+    (allocationId) => allocationId.includes("mesh") || allocationId.includes("asset") || allocationId.includes("tile")
+  );
+  const bakeSourceJobKeys = profile === "bake" ? ["meshBuild", "tileBake", "assetSerialize"] : ["meshBuild", "tileBake"];
+  const representations = Object.freeze([
+    buildWorldGeneratorRepresentationDescriptor({
+      profile,
+      chunkId,
+      band: "near",
+      output: "liveGeometry",
+      rasterMode: "full-live",
+      rtParticipation: "full",
+      shadowRelevance: "ray-traced-primary",
+      refreshCadence: { kind: "per-frame", divisor: 1 },
+      preservesChunkIdentity: true,
+      sourceJobKeys: ["meshBuild"],
+      gameplayImportance: gameplayImportance === "medium" ? "high" : gameplayImportance,
+      suggestedAllocationIds: highValueAllocations
+    }),
+    buildWorldGeneratorRepresentationDescriptor({
+      profile,
+      chunkId,
+      band: "mid",
+      output: "simplifiedGeometry",
+      rasterMode: "simplified-live",
+      rtParticipation: "selective",
+      shadowRelevance: "selective-raster",
+      refreshCadence: { kind: "interval", divisor: 2 },
+      preservesChunkIdentity: true,
+      sourceJobKeys: ["meshBuild"],
+      gameplayImportance,
+      suggestedAllocationIds: highValueAllocations
+    }),
+    buildWorldGeneratorRepresentationDescriptor({
+      profile,
+      chunkId,
+      band: "mid",
+      output: "rtProxy",
+      rasterMode: "not-rendered",
+      rtParticipation: "proxy",
+      shadowRelevance: "selective-raster",
+      refreshCadence: { kind: "interval", divisor: 2 },
+      preservesChunkIdentity: true,
+      sourceJobKeys: ["meshBuild", "tileBake"],
+      gameplayImportance,
+      suggestedAllocationIds: highValueAllocations
+    }),
+    buildWorldGeneratorRepresentationDescriptor({
+      profile,
+      chunkId,
+      band: "far",
+      output: "mergedProxy",
+      rasterMode: "proxy",
+      rtParticipation: "proxy",
+      shadowRelevance: "proxy-caster",
+      refreshCadence: { kind: "interval", divisor: 8 },
+      preservesChunkIdentity: true,
+      sourceJobKeys: bakeSourceJobKeys,
+      gameplayImportance: "medium",
+      suggestedAllocationIds: farFieldAllocations.length > 0 ? farFieldAllocations : highValueAllocations
+    }),
+    buildWorldGeneratorRepresentationDescriptor({
+      profile,
+      chunkId,
+      band: "horizon",
+      output: "horizonShell",
+      rasterMode: "horizon-shell",
+      rtParticipation: "disabled",
+      shadowRelevance: "baked-impression",
+      refreshCadence: { kind: "interval", divisor: 60 },
+      preservesChunkIdentity: true,
+      sourceJobKeys: profile === "bake" ? ["tileBake", "assetSerialize"] : ["tileBake"],
+      gameplayImportance: "medium",
+      suggestedAllocationIds: farFieldAllocations.length > 0 ? farFieldAllocations : highValueAllocations
+    })
+  ]);
+  return Object.freeze({
+    schemaVersion: 1,
+    owner: worldGeneratorDebugOwner,
+    profile,
+    chunkId,
+    representations,
+    bands: Object.freeze(
+      [...new Set(representations.map((representation) => representation.band))]
+    )
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   DEFAULT_TILE_SIZE_WORLD,
@@ -2498,6 +2661,7 @@ function getWorldGeneratorWorkerManifest(name = defaultWorldGeneratorWorkerProfi
   createFractalPrepassRunner,
   createMeshBuilder,
   createPerfMonitor,
+  createWorldGeneratorRepresentationPlan,
   defaultFieldParams,
   defaultFractalMandelSettings,
   defaultWorldGeneratorWorkerProfile,
@@ -2535,6 +2699,8 @@ function getWorldGeneratorWorkerManifest(name = defaultWorldGeneratorWorkerProfi
   unpackTerrain,
   validateTileAssetPayload,
   worldGeneratorDebugOwner,
+  worldGeneratorRepresentationBands,
+  worldGeneratorRepresentationOutputs,
   worldGeneratorWorkerManifests,
   worldGeneratorWorkerProfileNames,
   worldGeneratorWorkerProfiles,