@plasius/gpu-world-generator 0.0.11 → 0.0.13

package/docs/adrs/adr-0005-render-representation-tiers-and-proxy-outputs.md

@@ -0,0 +1,51 @@
+# ADR-0005: Render Representation Tiers and Proxy Outputs
+
+## Status
+
+Accepted
+
+## Context
+
+The world architecture no longer assumes that every chunk is rendered from the
+same live representation. Near, mid, far, and horizon content should be able to
+use different visual and ray-tracing representations so the world scales in a
+predictable way.
+
+`@plasius/gpu-world-generator` already owns chunk and voxel generation, so it is
+the natural package to plan how world chunks will expose render-oriented
+representation tiers and proxy outputs before implementation begins.
+
+## Decision
+
+`@plasius/gpu-world-generator` will plan around formal representation tiers for
+rendering and RT preparation:
+
+- `near`: full live chunk output
+- `mid`: simplified live chunk output
+- `far`: HLOD, impostor, or proxy-driven chunk output
+- `horizon`: shell, skyline, or large-scale background representation
+
+The package should eventually be able to provide metadata or assets for:
+
+- chunk-local full geometry
+- simplified geometry or material reductions
+- RT proxy or reduced-fidelity instance data
+- merged or impostor-oriented distant proxies
+- low-refresh far-field or horizon assets
+
+## Consequences
+
+- Positive: distant rendering becomes a formal output tier instead of an
+  ad-hoc optimization.
+- Positive: renderer and world packages can coordinate around explicit chunk
+  representation bands.
+- Positive: RT proxy planning can start from generated world assets instead of
+  being recreated in a later stage.
+- Neutral: this ADR does not yet prescribe the final file format or buffer
+  layout for each proxy type.
+
+## Follow-On Work
+
+- Define the technical contract for chunk representation metadata and proxy
+  refresh policy.
+- Add test-first contract and unit specs before implementing new proxy outputs.

package/docs/adrs/index.md

@@ -2,5 +2,6 @@
 
 - [ADR-0001: GPU World Generator Package Scope](./adr-0001-package-scope.md)
 - [ADR-0002: Tiled World Generation, LOD, and Stitching](./adr-0002-world-tiling-lod-stitching.md)
-- [ADR-0004: Worker DAG Manifests for Chunk and Voxel Generation](./adr-0004-worker-dag-manifests-for-chunk-and-voxel-generation.md)
 - [ADR-0003: Terrain Generation Style Mixing (Shader-Based)](./adr-0003-terrain-generation-style-mixing.md)
+- [ADR-0004: Worker DAG Manifests for Chunk and Voxel Generation](./adr-0004-worker-dag-manifests-for-chunk-and-voxel-generation.md)
+- [ADR-0005: Render Representation Tiers and Proxy Outputs](./adr-0005-render-representation-tiers-and-proxy-outputs.md)

package/docs/tdrs/index.md

@@ -1,3 +1,4 @@
 # TDR Index
 
 - [TDR-0001: World-Generator Worker Manifest Contract](./tdr-0001-world-generator-worker-manifest-contract.md)
+- [TDR-0002: Render Representation Tier Contract](./tdr-0002-render-representation-tier-contract.md)

package/docs/tdrs/tdr-0002-render-representation-tier-contract.md

@@ -0,0 +1,60 @@
+# TDR-0002: Render Representation Tier Contract
+
+## Status
+
+Accepted
+
+## Goal
+
+Define the future contract for render and RT-oriented chunk representation tiers
+in `@plasius/gpu-world-generator`.
+
+## Planned Tier Outputs
+
+Each chunk or region should eventually be able to describe one or more of:
+
+- full live geometry output
+- simplified live geometry output
+- RT proxy output
+- merged HLOD or impostor output
+- horizon-shell or skyline output
+
+## Planned Metadata
+
+Representation descriptors should be able to carry:
+
+- chunk or region identifier
+- representation tier:
+  - `near`
+  - `mid`
+  - `far`
+  - `horizon`
+- refresh policy or expected update cadence
+- RT participation policy
+- shadow relevance policy
+- suggested ownership for renderer and worker scheduling
+
+## Planned Tests
+
+Contract tests should prove that:
+
+- chunk descriptors can distinguish near, mid, far, and horizon output tiers
+- proxy outputs can declare RT and shadow participation separately from the
+  live geometry output
+- refresh expectations are explicit for far and horizon content
+
+Unit tests should prove that:
+
+- world-generation manifests can describe merged or impostor-driven far-field
+  outputs without losing chunk identity
+- horizon representations can be low-frequency and still remain valid render
+  products
+- RT proxy descriptors can differ from the raster-facing representation tier
+
+## Implementation Notes
+
+The first public implementation now ships as
+`createWorldGeneratorRepresentationPlan(...)`. It publishes explicit near, mid,
+far, and horizon descriptors, exposes distinct raster and RT proxy outputs,
+retains chunk identity for proxy products, and includes refresh cadence,
+shadow-source relevance, and scheduling metadata for downstream packages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/gpu-world-generator",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "GPU-assisted world generation with hex-grid terrain synthesis.",
   "type": "module",
   "sideEffects": false,
@@ -38,15 +38,15 @@
     "prepublishOnly": "npm run build && npm run pack:check"
   },
   "dependencies": {
-    "@plasius/gpu-worker": "^0.1.10"
+    "@plasius/gpu-worker": "^0.1.11"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.1",
-    "@types/node": "^22.10.0",
-    "@typescript-eslint/eslint-plugin": "^8.46.2",
-    "@typescript-eslint/parser": "^8.46.2",
-    "c8": "^10.1.3",
-    "eslint": "^9.39.1",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.12.0",
+    "@typescript-eslint/eslint-plugin": "^8.57.1",
+    "@typescript-eslint/parser": "^8.57.1",
+    "c8": "^11.0.0",
+    "eslint": "^10.1.0",
     "globals": "^17.3.0",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3"

package/src/tiles.ts

@@ -270,7 +270,6 @@ export function serializeTileAssetBinary(asset: TileAsset): ArrayBuffer {
   view.setUint32(cursor, materialStride >>> 0, true);
   cursor += 4;
   view.setUint32(cursor, featureStride >>> 0, true);
-  cursor += 4;
 
   let writeOffset = HEADER_BYTES;
   new Float32Array(buffer, writeOffset, heightCount).set(asset.height);
@@ -351,7 +350,6 @@ export function parseTileAssetBinary(input: ArrayBuffer | ArrayBufferView): Tile
   const materialStride = view.getUint32(cursor, true);
   cursor += 4;
   const featureStride = view.getUint32(cursor, true);
-  cursor += 4;
 
   const heightBytes = heightCount * 4;
   const fieldBytes = fieldCount * 4;

package/src/worker.ts

@@ -6,6 +6,69 @@ export type WorldGeneratorWorkerAuthority =
   | "non-authoritative-simulation"
   | "authoritative";
 export type WorldGeneratorWorkerImportance = "medium" | "high" | "critical";
+export type WorldGeneratorRepresentationBand =
+  | "near"
+  | "mid"
+  | "far"
+  | "horizon";
+export type WorldGeneratorRepresentationOutput =
+  | "liveGeometry"
+  | "simplifiedGeometry"
+  | "rtProxy"
+  | "mergedProxy"
+  | "horizonShell";
+export type WorldGeneratorRepresentationRtParticipation =
+  | "full"
+  | "selective"
+  | "proxy"
+  | "disabled";
+export type WorldGeneratorRepresentationShadowRelevance =
+  | "ray-traced-primary"
+  | "selective-raster"
+  | "proxy-caster"
+  | "baked-impression";
+
+export interface WorldGeneratorRepresentationCadence {
+  readonly kind: "per-frame" | "interval";
+  readonly divisor: number;
+}
+
+export interface WorldGeneratorRepresentationDescriptor {
+  readonly id: string;
+  readonly chunkId: string;
+  readonly profile: WorldGeneratorWorkerProfileName;
+  readonly band: WorldGeneratorRepresentationBand;
+  readonly output: WorldGeneratorRepresentationOutput;
+  readonly rasterMode:
+    | "full-live"
+    | "simplified-live"
+    | "proxy"
+    | "not-rendered"
+    | "horizon-shell";
+  readonly rtParticipation: WorldGeneratorRepresentationRtParticipation;
+  readonly shadowRelevance: WorldGeneratorRepresentationShadowRelevance;
+  readonly refreshCadence: WorldGeneratorRepresentationCadence;
+  readonly preservesChunkIdentity: boolean;
+  readonly sourceChunkIds: readonly string[];
+  readonly sourceJobKeys: readonly string[];
+  readonly suggestedAllocationIds: readonly string[];
+  readonly scheduling: Readonly<{
+    owner: "renderer";
+    queueClass: typeof worldGeneratorWorkerQueueClass;
+    priorityHint: number;
+    gameplayImportance: WorldGeneratorWorkerImportance;
+    representationBand: WorldGeneratorRepresentationBand;
+  }>;
+}
+
+export interface WorldGeneratorRepresentationPlan {
+  readonly schemaVersion: 1;
+  readonly owner: typeof worldGeneratorDebugOwner;
+  readonly profile: WorldGeneratorWorkerProfileName;
+  readonly chunkId: string;
+  readonly representations: readonly WorldGeneratorRepresentationDescriptor[];
+  readonly bands: readonly WorldGeneratorRepresentationBand[];
+}
 
 export interface WorldGeneratorWorkerBudgetLevelConfig {
   maxDispatchesPerFrame: number;
@@ -75,6 +138,28 @@ export interface WorldGeneratorWorkerManifest {
 export const worldGeneratorDebugOwner = "world-generator";
 export const worldGeneratorWorkerQueueClass = "voxel";
 export const defaultWorldGeneratorWorkerProfile = "streaming";
+export const worldGeneratorRepresentationBands = Object.freeze([
+  "near",
+  "mid",
+  "far",
+  "horizon",
+]) as readonly WorldGeneratorRepresentationBand[];
+export const worldGeneratorRepresentationOutputs = Object.freeze([
+  "liveGeometry",
+  "simplifiedGeometry",
+  "rtProxy",
+  "mergedProxy",
+  "horizonShell",
+]) as readonly WorldGeneratorRepresentationOutput[];
+
+const worldGeneratorRepresentationBandPriorityHints: Readonly<
+  Record<WorldGeneratorRepresentationBand, number>
+> = Object.freeze({
+  near: 400,
+  mid: 300,
+  far: 200,
+  horizon: 100,
+});
 
 type WorkerLevelSpec = Omit<WorldGeneratorWorkerBudgetLevel, "config"> & {
   config: Omit<WorldGeneratorWorkerBudgetLevelConfig, "metadata">;
@@ -96,6 +181,66 @@ type WorkerProfileSpec = {
   jobs: Readonly<Record<string, WorkerJobSpec>>;
 };
 
+function assertWorldGeneratorIdentifier(name: string, value: unknown) {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${name} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+
+function normalizeWorldGeneratorImportance(
+  name: string,
+  value: unknown
+): WorldGeneratorWorkerImportance {
+  if (value === "medium" || value === "high" || value === "critical") {
+    return value;
+  }
+  throw new Error(`${name} must be one of: medium, high, critical.`);
+}
+
+function buildWorldGeneratorRepresentationDescriptor(
+  options: {
+    profile: WorldGeneratorWorkerProfileName;
+    chunkId: string;
+    band: WorldGeneratorRepresentationBand;
+    output: WorldGeneratorRepresentationOutput;
+    rasterMode: WorldGeneratorRepresentationDescriptor["rasterMode"];
+    rtParticipation: WorldGeneratorRepresentationRtParticipation;
+    shadowRelevance: WorldGeneratorRepresentationShadowRelevance;
+    refreshCadence: WorldGeneratorRepresentationCadence;
+    preservesChunkIdentity: boolean;
+    sourceJobKeys: readonly string[];
+    gameplayImportance: WorldGeneratorWorkerImportance;
+    suggestedAllocationIds: readonly string[];
+  }
+): WorldGeneratorRepresentationDescriptor {
+  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: string,
   queueClass: WorldGeneratorWorkerQueueClass,
@@ -708,3 +853,126 @@ export function getWorldGeneratorWorkerManifest(
   }
   return manifest;
 }
+
+export function createWorldGeneratorRepresentationPlan(options: {
+  profile?: WorldGeneratorWorkerProfileName;
+  chunkId: string;
+  gameplayImportance?: WorldGeneratorWorkerImportance;
+}): WorldGeneratorRepresentationPlan {
+  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,
+    }),
+  ] satisfies readonly WorldGeneratorRepresentationDescriptor[]);
+
+  return Object.freeze({
+    schemaVersion: 1,
+    owner: worldGeneratorDebugOwner,
+    profile,
+    chunkId,
+    representations,
+    bands: Object.freeze(
+      [...new Set(representations.map((representation) => representation.band))]
+    ),
+  });
+}