@bloomengine/engine 0.3.1

package/src/world/prefab.ts

@@ -0,0 +1,205 @@
+// Prefab expansion and registry.
+//
+// A prefab is a reusable composite object — e.g. a house made of 4 walls + a
+// roof + a door. Prefabs are authored in the editor and stored as individual
+// `*.prefab.json` files on disk. When a world places a prefab (via an entity
+// with `prefabRef` set), the runtime expands the prefab tree into a flat list
+// of leaf glb placements with world-space transforms, and the loader spawns
+// one scene node per leaf.
+//
+// Prefabs can nest: one prefab's child can reference another prefab. Cycles
+// are detected at expansion time (A -> B -> A) and reported as errors; the
+// offending child is treated as empty so the rest of the world still loads.
+
+import { readFile } from '../core/index';
+import {
+  mat4Identity,
+  mat4Multiply,
+  mat4Translate,
+  mat4RotateX,
+  mat4RotateY,
+  mat4RotateZ,
+  mat4Scale,
+} from '../math/index';
+import { Mat4, Vec3 } from '../core/types';
+import {
+  PrefabData,
+  PrefabChild,
+  TransformData,
+  Vec4Lit,
+} from './types';
+import { migratePrefabData } from './version';
+import { validatePrefab, formatValidationErrors } from './validate';
+
+// One leaf of an expanded prefab — a single glb to spawn at a world-space
+// matrix. The loader turns each of these into one scene node.
+export interface PrefabLeaf {
+  modelRef: string;        // Always a glb path; prefabs are fully flattened.
+  worldMatrix: Mat4;       // Column-major 4x4 in world space.
+  tint: Vec4Lit | null;    // Inherited from ancestor unless a child overrides.
+  tags: string[];          // Union of the leaf's own tags and ancestor tags.
+  sourcePath: string;      // Dotted path for debugging: "small_house.wall_0".
+}
+
+// Registry of all prefabs known to a project. The editor populates it at
+// startup by scanning `project.prefabsDir`; games populate it from their
+// asset bundle. Keyed by `PrefabData.id`.
+export interface PrefabRegistry {
+  byId: Map<string, PrefabData>;
+  getPrefab: (id: string) => PrefabData | null;
+}
+
+export function createPrefabRegistry(): PrefabRegistry {
+  const byId = new Map<string, PrefabData>();
+  return {
+    byId: byId,
+    getPrefab: function(id: string): PrefabData | null {
+      const found = byId.get(id);
+      return found ? found : null;
+    },
+  };
+}
+
+// Register a prefab in the registry. Overwrites any existing entry with the
+// same id (hot-reload friendly).
+export function registerPrefab(registry: PrefabRegistry, prefab: PrefabData): void {
+  registry.byId.set(prefab.id, prefab);
+}
+
+// Load a single prefab file from disk, validate, migrate, and return it.
+// Throws on parse or validation error.
+export function loadPrefab(path: string): PrefabData {
+  const text = readFile(path);
+  if (!text || text.length === 0) {
+    throw new Error('loadPrefab: file is empty or missing: ' + path);
+  }
+
+  let raw: PrefabData;
+  try {
+    raw = JSON.parse(text) as PrefabData;
+  } catch (e) {
+    throw new Error('loadPrefab: invalid JSON in ' + path + ': ' + (e as Error).message);
+  }
+
+  const migrated = migratePrefabData(raw);
+  const check = validatePrefab(migrated);
+  if (!check.ok) {
+    throw new Error('loadPrefab: ' + path + '\n' + formatValidationErrors(check.errors));
+  }
+  return migrated;
+}
+
+// Recursively flatten a prefab into its leaf glb placements.
+//
+// @param registry       Registry to look up child prefab references.
+// @param prefabId       Id of the prefab to expand.
+// @param parentMatrix   World-space matrix to apply to all children.
+// @param parentTint     Tint inherited from the placing entity (null if none).
+// @param parentTags     Tags to propagate to each leaf.
+// @param out            Output array of flattened leaves. Caller supplies.
+// @param errors         Output error list (cycles, missing references).
+// @param visited        Set of ancestor prefab ids, used for cycle detection.
+// @param pathPrefix     Debug path for error messages, e.g. "world_root".
+export function expandPrefab(
+  registry: PrefabRegistry,
+  prefabId: string,
+  parentMatrix: Mat4,
+  parentTint: Vec4Lit | null,
+  parentTags: ReadonlyArray<string>,
+  out: PrefabLeaf[],
+  errors: string[],
+  visited: Set<string>,
+  pathPrefix: string,
+): void {
+  if (visited.has(prefabId)) {
+    errors.push(
+      'prefab cycle detected: ' + pathPrefix + ' -> ' + prefabId +
+        ' (already in chain)',
+    );
+    return;
+  }
+
+  const prefab = registry.getPrefab(prefabId);
+  if (!prefab) {
+    errors.push('prefab not found: "' + prefabId + '" (referenced by ' + pathPrefix + ')');
+    return;
+  }
+
+  visited.add(prefabId);
+
+  for (let i = 0; i < prefab.children.length; i++) {
+    const child = prefab.children[i];
+    const childMatrix = mat4Multiply(parentMatrix, trsToMat4(child.transform));
+    const childTint = child.tint !== null ? child.tint : parentTint;
+    const childTags = mergeTags(parentTags, child.tags);
+    const childPath = pathPrefix + '.' + child.id;
+
+    if (child.modelRef !== null && child.modelRef.length > 0) {
+      out.push({
+        modelRef: child.modelRef,
+        worldMatrix: childMatrix,
+        tint: childTint,
+        tags: childTags,
+        sourcePath: childPath,
+      });
+    } else if (child.prefabRef !== null && child.prefabRef.length > 0) {
+      expandPrefab(
+        registry,
+        child.prefabRef,
+        childMatrix,
+        childTint,
+        childTags,
+        out,
+        errors,
+        visited,
+        childPath,
+      );
+    } else {
+      errors.push('prefab child ' + childPath + ' has neither modelRef nor prefabRef');
+    }
+  }
+
+  visited.delete(prefabId);
+}
+
+// Build a column-major 4x4 from TRS components. Duplicated here (rather than
+// imported from `./loader.ts`) to keep the dependency graph flat — prefab is
+// used *by* the loader, not the other way around.
+function trsToMat4(t: TransformData): Mat4 {
+  const pos: Vec3 = { x: t.position[0], y: t.position[1], z: t.position[2] };
+  const scl: Vec3 = { x: t.scale[0], y: t.scale[1], z: t.scale[2] };
+
+  let m = mat4Identity();
+  m = mat4Translate(m, pos);
+  m = mat4RotateZ(m, t.rotation[2]);
+  m = mat4RotateY(m, t.rotation[1]);
+  m = mat4RotateX(m, t.rotation[0]);
+  m = mat4Scale(m, scl);
+  return m;
+}
+
+function mergeTags(parent: ReadonlyArray<string>, child: ReadonlyArray<string>): string[] {
+  if (parent.length === 0) return [...child];
+  if (child.length === 0) return [...parent];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (let i = 0; i < parent.length; i++) {
+    if (!seen.has(parent[i])) { seen.add(parent[i]); out.push(parent[i]); }
+  }
+  for (let i = 0; i < child.length; i++) {
+    if (!seen.has(child[i])) { seen.add(child[i]); out.push(child[i]); }
+  }
+  return out;
+}
+
+// Build an empty prefab with sensible defaults. Editor calls this from
+// "New Prefab".
+export function createEmptyPrefab(id: string, name: string): PrefabData {
+  return {
+    schemaVersion: 1,
+    id: id,
+    name: name,
+    children: [],
+    bounds: { min: [0, 0, 0], max: [0, 0, 0] },
+  };
+}

package/src/world/saver.ts

@@ -0,0 +1,61 @@
+// World saver — serializes a `WorldData` to disk as pretty-printed JSON.
+// Called by the editor's File -> Save / Save As commands and by any tooling
+// that programmatically generates worlds.
+//
+// The saver always validates before writing so the editor can't produce
+// corrupt files. On validation failure, returns false and populates the
+// `errors` array; on success, writes the file and returns true.
+
+import { writeFile } from '../core/index';
+import { WORLD_SCHEMA_VERSION, WorldData, PrefabData } from './types';
+import { validateWorld, validatePrefab, formatValidationErrors } from './validate';
+
+export interface SaveResult {
+  ok: boolean;
+  errors: string[];
+}
+
+// Write a world file. On success, returns `{ ok: true, errors: [] }`.
+// On validation failure, returns the errors without touching the filesystem.
+// On write failure (disk full, permissions), returns `{ ok: false, errors: [...] }`.
+export function saveWorld(path: string, world: WorldData): SaveResult {
+  // Always stamp the current schema version on save so stale copies don't
+  // drift across editor sessions.
+  world.schemaVersion = WORLD_SCHEMA_VERSION;
+
+  const check = validateWorld(world);
+  if (!check.ok) {
+    return { ok: false, errors: check.errors };
+  }
+
+  const json = JSON.stringify(world, null, 2);
+  const ok = writeFile(path, json);
+  if (!ok) {
+    return { ok: false, errors: ['writeFile failed for path: ' + path] };
+  }
+  return { ok: true, errors: [] };
+}
+
+// Write a prefab file. Same semantics as `saveWorld` but for prefabs.
+export function savePrefab(path: string, prefab: PrefabData): SaveResult {
+  prefab.schemaVersion = WORLD_SCHEMA_VERSION;
+
+  const check = validatePrefab(prefab);
+  if (!check.ok) {
+    return { ok: false, errors: check.errors };
+  }
+
+  const json = JSON.stringify(prefab, null, 2);
+  const ok = writeFile(path, json);
+  if (!ok) {
+    return { ok: false, errors: ['writeFile failed for path: ' + path] };
+  }
+  return { ok: true, errors: [] };
+}
+
+// Convenience: format a SaveResult's errors as a single human-readable string.
+// The editor uses this for status bar / dialog messages.
+export function formatSaveError(result: SaveResult): string {
+  if (result.ok) return '';
+  return formatValidationErrors(result.errors);
+}

package/src/world/terrain.ts

@@ -0,0 +1,254 @@
+// Terrain helpers for the shared world module.
+//
+// Terrain in a `WorldData` is a uniform grid heightmap: `width * depth` float
+// heights, row-major with `z*width + x`. This file provides the operations
+// that both the editor (to sculpt / display) and games (to render / sample)
+// need:
+//
+//   buildHeightmapMesh  — grid floats -> flat vertex/index arrays suitable
+//                         for `updateSceneNodeGeometry`. Vertex layout matches
+//                         the scene graph's expected 12-float stride:
+//                         [x, y, z, nx, ny, nz, r, g, b, a, u, v].
+//   sampleHeight         — bilinear interpolation at arbitrary world-space xz.
+//                          Used by character controllers and the place tool
+//                          to drop entities onto the terrain.
+//   raycastTerrain       — mouse ray -> terrain hit point + cell indices. Used
+//                          by the brush tool to find where the user is painting.
+//   defaultTerrain       — a flat 128x128 terrain centered at origin.
+
+import { TerrainData, Vec3Lit } from './types';
+
+// Vertex stride in floats (matches scene graph expectation).
+// See `bloom/engine/src/scene/index.ts` updateSceneNodeGeometry docs.
+const STRIDE = 12;
+
+// Default grid size for new worlds. Large enough for meaningful terrain,
+// small enough to rebuild in <1ms on any modern CPU.
+const DEFAULT_WIDTH = 128;
+const DEFAULT_DEPTH = 128;
+
+// Build a flat-shaded triangle mesh from a heightmap. Returns two number
+// arrays that can be passed directly to `updateSceneNodeGeometry`. Computes
+// per-vertex normals from finite differences of the 4 neighbouring heights.
+//
+// Vertex count: width * depth
+// Triangle count: (width - 1) * (depth - 1) * 2
+//
+// For a 128x128 grid that's 16,384 vertices and 32,258 triangles — well
+// within what one scene node can hold.
+export function buildHeightmapMesh(t: TerrainData): { vertices: number[]; indices: number[] } {
+  const width = t.width;
+  const depth = t.depth;
+  const cellSize = t.cellSize;
+  const originX = t.origin[0];
+  const originY = t.origin[1];
+  const originZ = t.origin[2];
+  const heights = t.heights;
+
+  const vertexCount = width * depth;
+  const vertices: number[] = new Array<number>(vertexCount * STRIDE);
+  const indices: number[] = new Array<number>((width - 1) * (depth - 1) * 6);
+
+  // Default vertex color (grayscale stone). Editor / game can tint per-layer
+  // via the splat weights once that pipeline lands.
+  const cr = 0.55;
+  const cg = 0.60;
+  const cb = 0.50;
+  const ca = 1.0;
+
+  // Vertex pass.
+  for (let z = 0; z < depth; z++) {
+    for (let x = 0; x < width; x++) {
+      const idx = z * width + x;
+      const h = heights[idx];
+
+      // World-space position.
+      const wx = originX + x * cellSize;
+      const wy = originY + h;
+      const wz = originZ + z * cellSize;
+
+      // Finite-difference normal (central differences, clamped at edges).
+      const xm = x > 0 ? heights[z * width + (x - 1)] : h;
+      const xp = x < width - 1 ? heights[z * width + (x + 1)] : h;
+      const zm = z > 0 ? heights[(z - 1) * width + x] : h;
+      const zp = z < depth - 1 ? heights[(z + 1) * width + x] : h;
+
+      const dx = (xp - xm) / (2 * cellSize);
+      const dz = (zp - zm) / (2 * cellSize);
+      // Normal of y = f(x, z) is (-df/dx, 1, -df/dz), normalized.
+      const nx = -dx;
+      const ny = 1.0;
+      const nz = -dz;
+      const invLen = 1.0 / Math.sqrt(nx * nx + ny * ny + nz * nz);
+
+      const base = idx * STRIDE;
+      vertices[base + 0] = wx;
+      vertices[base + 1] = wy;
+      vertices[base + 2] = wz;
+      vertices[base + 3] = nx * invLen;
+      vertices[base + 4] = ny * invLen;
+      vertices[base + 5] = nz * invLen;
+      vertices[base + 6] = cr;
+      vertices[base + 7] = cg;
+      vertices[base + 8] = cb;
+      vertices[base + 9] = ca;
+      vertices[base + 10] = x / (width - 1);
+      vertices[base + 11] = z / (depth - 1);
+    }
+  }
+
+  // Index pass — two triangles per cell, wound counter-clockwise when looking
+  // down the -Y axis.
+  let idxWrite = 0;
+  for (let z = 0; z < depth - 1; z++) {
+    for (let x = 0; x < width - 1; x++) {
+      const i00 = z * width + x;
+      const i10 = i00 + 1;
+      const i01 = i00 + width;
+      const i11 = i01 + 1;
+
+      indices[idxWrite++] = i00;
+      indices[idxWrite++] = i01;
+      indices[idxWrite++] = i11;
+
+      indices[idxWrite++] = i00;
+      indices[idxWrite++] = i11;
+      indices[idxWrite++] = i10;
+    }
+  }
+
+  return { vertices: vertices, indices: indices };
+}
+
+// Bilinear sample of the terrain at world-space (wx, wz). Returns the world
+// Y of the surface at that point, including the terrain's origin offset.
+// Points outside the grid clamp to the nearest edge cell.
+//
+// Used by:
+//   - character controllers ("what height is the player standing on?")
+//   - the place tool (drop an entity onto the terrain surface)
+//   - the brush tool (show a cursor ring at the correct height)
+export function sampleHeight(t: TerrainData, wx: number, wz: number): number {
+  const fx = (wx - t.origin[0]) / t.cellSize;
+  const fz = (wz - t.origin[2]) / t.cellSize;
+
+  const x0 = clamp(Math.floor(fx), 0, t.width - 1);
+  const z0 = clamp(Math.floor(fz), 0, t.depth - 1);
+  const x1 = clamp(x0 + 1, 0, t.width - 1);
+  const z1 = clamp(z0 + 1, 0, t.depth - 1);
+
+  const tx = clamp(fx - x0, 0, 1);
+  const tz = clamp(fz - z0, 0, 1);
+
+  const h00 = t.heights[z0 * t.width + x0];
+  const h10 = t.heights[z0 * t.width + x1];
+  const h01 = t.heights[z1 * t.width + x0];
+  const h11 = t.heights[z1 * t.width + x1];
+
+  const h0 = h00 * (1 - tx) + h10 * tx;
+  const h1 = h01 * (1 - tx) + h11 * tx;
+  return t.origin[1] + h0 * (1 - tz) + h1 * tz;
+}
+
+export interface TerrainRaycastHit {
+  hit: boolean;
+  point: Vec3Lit;
+  // Grid cell the hit falls into. -1 when there is no hit.
+  cellX: number;
+  cellZ: number;
+  distance: number;
+}
+
+// March a ray through the terrain looking for the first intersection with the
+// surface. This is not a closed-form solution — it's a simple iterative
+// marcher that steps along the ray in small increments and samples the height
+// at each step. Good enough for the brush tool, where the player is always
+// looking at the ground from above.
+//
+// @param origin  Ray origin in world space.
+// @param dir     Ray direction (should be normalized for accurate distances).
+// @param maxDist Maximum distance to march before giving up.
+// @param step    Step size. Smaller = more accurate, larger = faster.
+export function raycastTerrain(
+  t: TerrainData,
+  origin: Vec3Lit,
+  dir: Vec3Lit,
+  maxDist: number,
+  step: number,
+): TerrainRaycastHit {
+  // Early-out: ray must be pointing roughly downward (negative Y component)
+  // for the heightmap to be visible from above.
+  if (dir[1] >= 0) {
+    // Still allow it in case origin is below terrain, but clamp iterations.
+  }
+
+  let d = 0;
+  let prevAbove = origin[1] > sampleHeight(t, origin[0], origin[2]);
+
+  while (d < maxDist) {
+    const px = origin[0] + dir[0] * d;
+    const py = origin[1] + dir[1] * d;
+    const pz = origin[2] + dir[2] * d;
+
+    const h = sampleHeight(t, px, pz);
+    const above = py > h;
+
+    if (above !== prevAbove) {
+      // Crossed the surface. Refine with one binary-search step for accuracy.
+      let lo = d - step;
+      let hi = d;
+      for (let i = 0; i < 6; i++) {
+        const mid = (lo + hi) * 0.5;
+        const mx = origin[0] + dir[0] * mid;
+        const my = origin[1] + dir[1] * mid;
+        const mz = origin[2] + dir[2] * mid;
+        const mh = sampleHeight(t, mx, mz);
+        if ((my > mh) === prevAbove) {
+          lo = mid;
+        } else {
+          hi = mid;
+        }
+      }
+      const finalD = (lo + hi) * 0.5;
+      const hitX = origin[0] + dir[0] * finalD;
+      const hitY = origin[1] + dir[1] * finalD;
+      const hitZ = origin[2] + dir[2] * finalD;
+      const cellX = clamp(Math.floor((hitX - t.origin[0]) / t.cellSize), 0, t.width - 1);
+      const cellZ = clamp(Math.floor((hitZ - t.origin[2]) / t.cellSize), 0, t.depth - 1);
+      return {
+        hit: true,
+        point: [hitX, hitY, hitZ],
+        cellX: cellX,
+        cellZ: cellZ,
+        distance: finalD,
+      };
+    }
+
+    d += step;
+  }
+
+  return { hit: false, point: [0, 0, 0], cellX: -1, cellZ: -1, distance: 0 };
+}
+
+// Build a flat 128x128 terrain centered at the origin. Used by the editor's
+// "New World" command when the user chooses a terrain-backed template.
+export function defaultTerrain(): TerrainData {
+  const width = DEFAULT_WIDTH;
+  const depth = DEFAULT_DEPTH;
+  const cellSize = 1.0;
+  const heights: number[] = new Array<number>(width * depth);
+  for (let i = 0; i < heights.length; i++) heights[i] = 0;
+
+  return {
+    width: width,
+    depth: depth,
+    cellSize: cellSize,
+    origin: [-(width * cellSize) / 2, 0, -(depth * cellSize) / 2],
+    heights: heights,
+    layers: [],
+  };
+}
+
+function clamp(v: number, lo: number, hi: number): number {
+  return v < lo ? lo : (v > hi ? hi : v);
+}

package/src/world/types.ts

@@ -0,0 +1,136 @@
+// Shared world schema — consumed by the Bloom world editor and by every game
+// that loads `*.world.json` files. All fields are chosen to round-trip cleanly
+// through `JSON.stringify` / `JSON.parse`, so positions, rotations, colors, and
+// matrices are stored as plain number arrays rather than `{x,y,z}` objects.
+// The engine's runtime `Vec3` / `Mat4` / `BoundingBox` types (in `core/types.ts`)
+// use a different shape; the loader in `./loader.ts` does the conversion.
+
+export const WORLD_SCHEMA_VERSION = 1;
+
+// Literal types for JSON-friendly serialization.
+// Use `Vec3Lit` in serialized data; convert to engine `Vec3` at load time.
+export type Vec3Lit = [number, number, number];
+export type Vec4Lit = [number, number, number, number];
+
+// Column-major 4x4 matrix, same convention as `engine/src/core/types.ts` Mat4.
+// Stored as a flat length-16 number array so it serializes as JSON.
+export type Mat4Lit = number[];
+
+// Top-level world document. One `*.world.json` file holds exactly one of these.
+export interface WorldData {
+  schemaVersion: number;            // Must equal WORLD_SCHEMA_VERSION on save.
+  name: string;                     // Human-readable display name.
+  id: string;                       // Stable slug, e.g. "garden_main".
+  bounds: Bounds;                   // Axis-aligned bounding box in world space.
+  environment: EnvironmentData;
+  terrain: TerrainData | null;      // null for games that don't use terrain.
+  entities: EntityData[];
+  water: WaterVolume[];
+  rivers: RiverSpline[];
+  metadata: Record<string, string>; // Game-specific extensibility (e.g. "gameId").
+}
+
+export interface Bounds {
+  min: Vec3Lit;
+  max: Vec3Lit;
+}
+
+// Sky, lighting, and atmospheric settings applied when the world is loaded.
+export interface EnvironmentData {
+  skyColor: Vec3Lit;          // 0..1 RGB, used as clear color.
+  ambientColor: Vec3Lit;      // 0..1 RGB.
+  ambientIntensity: number;   // 0..1.
+  sunDirection: Vec3Lit;      // Unit vector pointing from the sun.
+  sunColor: Vec3Lit;          // 0..1 RGB.
+  sunIntensity: number;
+  fogStart: number;           // World-space distance where fog begins.
+  fogEnd: number;             // World-space distance of full fog.
+  fogColor: Vec3Lit;
+  shadowsEnabled: boolean;
+}
+
+// Heightmap terrain. Row-major grid of float heights, indexed as z*width + x.
+// Runtime consumers build a mesh via `buildHeightmapMesh` in `./terrain.ts`
+// and sample via `sampleHeight` (bilinear).
+export interface TerrainData {
+  width: number;              // Grid cells along X (e.g. 128).
+  depth: number;              // Grid cells along Z.
+  cellSize: number;           // World units per cell, e.g. 1.0.
+  origin: Vec3Lit;            // World-space position of the (0,0) corner.
+  heights: number[];          // Length == width*depth, row-major, z*width + x.
+  layers: TerrainLayer[];     // Splat texture layers; empty array if unused.
+}
+
+export interface TerrainLayer {
+  id: string;                 // "grass", "dirt", "rock".
+  textureRef: string;         // Relative asset path.
+  weights: number[];          // Length == width*depth, 0..1 per cell.
+  tileScale: number;          // UV tiling factor.
+}
+
+// A placed instance in the world. Exactly one of `modelRef` / `prefabRef` is
+// non-null; the other is null. The editor enforces this invariant.
+export interface EntityData {
+  id: string;                 // Stable within the world file, e.g. "ent_0001".
+  name: string;               // Display name; defaults to model basename.
+  modelRef: string | null;    // Relative path, e.g. "models/tree_oak.glb".
+  prefabRef: string | null;   // Prefab id, e.g. "small_house".
+  transform: TransformData;
+  tint: Vec4Lit | null;       // Optional per-instance RGBA color override.
+  tags: string[];             // Game-defined, e.g. "climbable", "zone_marker".
+  userData: Record<string, string>;  // Arbitrary game-specific key/value data.
+}
+
+// Transform expressed as TRS with Euler rotation for diffable JSON.
+// The loader converts Euler -> quaternion / matrix as needed.
+export interface TransformData {
+  position: Vec3Lit;
+  rotation: Vec3Lit;          // Euler radians, XYZ order.
+  scale: Vec3Lit;             // Uniform scale is [s, s, s].
+}
+
+// Axis-aligned water volume with a wave-animated surface.
+// M1 supports only `kind: "box"`; future: "mesh" for arbitrary shapes.
+export interface WaterVolume {
+  id: string;
+  kind: "box";
+  center: Vec3Lit;
+  size: Vec3Lit;              // Full extents (not half-extents).
+  surfaceHeight: number;      // World Y of the water surface.
+  color: Vec4Lit;             // RGBA tint.
+  waveAmplitude: number;
+  waveSpeed: number;
+}
+
+// Catmull-Rom spline river with per-point width.
+export interface RiverSpline {
+  id: string;
+  controlPoints: Vec3Lit[];   // At least 2 points.
+  widths: number[];           // Same length as controlPoints.
+  depth: number;              // Below the surface.
+  flowSpeed: number;
+  color: Vec4Lit;
+}
+
+// ---- Prefabs ----------------------------------------------------------------
+
+// A prefab is a reusable composite object saved as its own `*.prefab.json`.
+// Each child references either a raw .glb model or another prefab (nested).
+// Cycles are detected at load time and rejected.
+export interface PrefabData {
+  schemaVersion: number;      // Must equal WORLD_SCHEMA_VERSION.
+  id: string;                 // Stable slug, e.g. "small_house".
+  name: string;               // Display name.
+  children: PrefabChild[];
+  bounds: Bounds;             // Cached AABB of the expanded prefab for previews.
+}
+
+// One child of a prefab. Exactly one of `modelRef` / `prefabRef` is non-null.
+export interface PrefabChild {
+  id: string;                 // Local id within the prefab, e.g. "wall_0".
+  modelRef: string | null;
+  prefabRef: string | null;   // Reference to another prefab (nested).
+  transform: TransformData;
+  tint: Vec4Lit | null;
+  tags: string[];
+}