@bornengine/engine 0.4.16

package/src/world/terrain.ts

@@ -0,0 +1,355 @@
+// 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, TerrainLayer, Vec3Lit } from './types';
+
+// Vertex stride in floats (matches scene graph expectation).
+// See `bloom/engine/src/scene/index.ts` updateSceneNodeGeometry docs.
+const STRIDE = 12;
+
+
+// ---- splat mask preview -----------------------------------------------------
+
+// Mask colours for the first eight splat layers, used to tint the heightmap
+// mesh's vertex colours so a painted layer is VISIBLE while you paint it.
+//
+// This is a MASK preview, not a material preview: it shows you *where* layer 2
+// is, not what layer 2's texture looks like. A game renders the real textures
+// from `TerrainLayer.textureRef` (the shooter samples them triplanar, blended by
+// exactly these weights); nothing but the editor viewport ever sees these
+// colours. They are ordered to read naturally for the common
+// grass/dry/dirt/rock set, so the preview is not actively misleading.
+const MASK_PALETTE: number[] = [
+  0.36, 0.60, 0.24,   // 0 — green      (lush grass)
+  0.72, 0.68, 0.30,   // 1 — olive      (dry grass)
+  0.55, 0.40, 0.26,   // 2 — brown      (dirt)
+  0.58, 0.58, 0.60,   // 3 — grey       (rock)
+  0.80, 0.74, 0.55,   // 4 — sand
+  0.90, 0.92, 0.95,   // 5 — snow
+  0.30, 0.34, 0.42,   // 6 — slate
+  0.62, 0.30, 0.28,   // 7 — clay
+];
+
+// Unpainted ground. Also the colour of a terrain with no layers at all, which
+// is every terrain until someone opens the paint tool.
+const BARE_R = 0.55;
+const BARE_G = 0.60;
+const BARE_B = 0.50;
+
+/// The mask colour the editor viewport uses for splat layer `i`. Wraps past 8.
+export function terrainLayerMaskColor(i: number): Vec3Lit {
+  const k = (i % 8) * 3;
+  return [MASK_PALETTE[k], MASK_PALETTE[k + 1], MASK_PALETTE[k + 2]];
+}
+
+// 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);
+
+  // Splat preview. Vertex colour = the bare-ground grey, with each painted
+  // layer's mask colour mixed in by its weight at this cell. A cell nobody has
+  // painted keeps the grey exactly, so an unpainted terrain looks precisely as
+  // it did before painting existed.
+  //
+  // Hoisted out of the vertex loop: `layers` is up to eight parallel arrays and
+  // resolving `t.layers[l].weights` 16,384 times is 16,384 property chains.
+  const layerCount = t.layers.length;
+  const layerWeights = new Array<number[]>(layerCount);
+  const layerColor = new Array<Vec3Lit>(layerCount);
+  for (let l = 0; l < layerCount; l++) {
+    layerWeights[l] = t.layers[l].weights;
+    layerColor[l] = terrainLayerMaskColor(l);
+  }
+  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];
+
+      let cr = BARE_R;
+      let cg = BARE_G;
+      let cb = BARE_B;
+      for (let l = 0; l < layerCount; l++) {
+        const ws = layerWeights[l];
+        // A layer whose weights array is short (hand-edited file, or a layer
+        // added before the grid was resized) contributes nothing rather than
+        // reading undefined and poisoning the whole vertex with NaN.
+        if (idx >= ws.length) continue;
+        const wgt = ws[idx];
+        if (wgt <= 0.0) continue;
+        const c = layerColor[l];
+        cr = cr + (c[0] - cr) * wgt;
+        cg = cg + (c[1] - cg) * wgt;
+        cb = cb + (c[2] - cb) * wgt;
+      }
+
+      // 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: [],
+  };
+}
+
+/// A new, fully-unpainted splat layer sized to `t`'s grid.
+///
+/// Weights start at zero everywhere, which means "this layer is nowhere" — the
+/// terrain keeps whatever it looked like before the layer was added. Adding a
+/// layer is therefore always a no-op until you paint with it, which is the only
+/// behaviour that makes "add layer" a safe button to press.
+export function createTerrainLayer(t: TerrainData, id: string, textureRef: string, tileScale: number): TerrainLayer {
+  const n = t.width * t.depth;
+  const w = new Array<number>(n);
+  for (let i = 0; i < n; i++) w[i] = 0;
+  return { id: id, textureRef: textureRef, weights: w, tileScale: tileScale };
+}
+
+/// Quantize a splat weight for storage.
+///
+/// Weights are consumed as an 8-bit texture, so anything past ~3 decimals is
+/// precision that cannot survive the trip to the GPU — but it CAN survive the
+/// trip to the JSON file, where `0.5019607843137255` costs 18 bytes and there
+/// are `width * depth * layers` of them. A 128² four-layer terrain is 65,536
+/// weights; at full precision that is a megabyte of noise in the diff.
+export function quantizeWeight(w: number): number {
+  const c = clamp(w, 0, 1);
+  return Math.round(c * 1000) / 1000;
+}
+
+// Written with `if` statements, NOT the obvious `v < lo ? lo : (v > hi ? hi : v)`.
+//
+// Perry miscompiles a module-private helper whose body is a single nested-ternary
+// return: called from another function in the same module it evaluates to the
+// FIRST branch regardless of the condition — `clamp(0.5, 0, 1)` returns 0. The
+// same helper written with `if` statements is correct, and so is the same ternary
+// inlined at the call site. See the shooter's docs/perry-quirks.md #8.
+//
+// Pinned by the editor self-test `testSplatPaintPartition` ("weights quantize to
+// 3dp"), which fails outright if this is "simplified" back to a ternary — at
+// which point every splat weight silently becomes 0 and every painted terrain
+// loads unpainted.
+function clamp(v: number, lo: number, hi: number): number {
+  if (v < lo) return lo;
+  if (v > hi) return hi;
+  return v;
+}

package/src/world/types.ts

@@ -0,0 +1,160 @@
+// 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.
+
+// v2 (2026-07-11) — lights became a first-class top-level array. Before that,
+// games carried them as entities tagged `userData.kind === "point_light"`, so
+// only the game knew they were lights: the editor could not light its preview,
+// and every game re-invented the same convention. Sun/ambient/fog were already
+// first-class in `environment`; point lights now sit beside them.
+// `migrateWorldData` converts v1 point_light entities automatically.
+export const WORLD_SCHEMA_VERSION = 2;
+
+// 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[];
+  lights: LightData[];              // Point lights. Sun/ambient live in `environment`.
+  water: WaterVolume[];
+  rivers: RiverSpline[];
+  metadata: Record<string, string>; // Game-specific extensibility (e.g. "gameId").
+}
+
+// A placed light. Only point lights for now — the sun and ambient are
+// environment-wide and live in `EnvironmentData`, and spot lights are not yet
+// in the renderer.
+//
+// Lights are engine-universal (every renderer knows what a point light is),
+// which is why they are schema rather than `userData`: a spawner or a wave plan
+// means nothing without the game, but a light means the same thing everywhere.
+export interface LightData {
+  id: string;                 // Stable within the world file, e.g. "light_0001".
+  name: string;               // Display name.
+  kind: "point";
+  position: Vec3Lit;
+  color: Vec3Lit;             // 0..1 RGB (the runtime API takes 0-255; loader converts).
+  intensity: number;
+  range: number;              // World units; beyond this the light contributes nothing.
+}
+
+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[];
+}