@bornengine/engine 0.4.16

package/src/world/render.ts

@@ -0,0 +1,172 @@
+// Shared spawn helpers for the parts of a world that are not entities: water
+// volumes and rivers.
+//
+// Both the runtime loader (`instantiateWorld`, used by games) and the world
+// editor call these, so a river looks the same in the editor as it does in the
+// game. Anything that renders world data belongs here rather than in either
+// consumer — the editor previously drew its own translucent debug cubes, which
+// is exactly how the two drift apart.
+//
+// Colour convention: the world schema stores RGBA as 0-1 floats, while the
+// scene API takes 0-255. The conversion lives here, once.
+
+import {
+  createSceneNode, setSceneNodeVisible, setSceneNodeWaterMaterial,
+  attachModelToNode, setSceneNodeColor, addPointLight,
+  SceneNodeHandle,
+} from '../scene/index';
+import {
+  genMeshCube, genMeshSplineRibbon, setAmbientLight, setDirectionalLight,
+} from '../models/index';
+import { setFog } from '../core/index';
+import { vec3 } from '../math/index';
+import { setSceneNodeTransform } from '../scene/index';
+import { WorldData, WaterVolume, RiverSpline } from './types';
+
+// Re-submit the world's point lights.
+//
+// MUST be called every frame, not once at load: the renderer clears its
+// lighting block in begin_frame (the same reason games re-apply sun and ambient
+// each frame). Calling it once at startup produces a world that is lit for
+// exactly one frame and then goes dark.
+//
+// Colour components are 0-1 in both the schema and `addPointLight`.
+export function applyWorldLights(world: WorldData): void {
+  for (let i = 0; i < world.lights.length; i++) {
+    const l = world.lights[i];
+    addPointLight(
+      l.position[0], l.position[1], l.position[2],
+      l.range,
+      l.color[0], l.color[1], l.color[2],
+      l.intensity,
+    );
+  }
+}
+
+// Re-apply the world's ambient light, sun, and fog.
+//
+// MUST be called every frame, for the same reason as `applyWorldLights`: the
+// renderer clears its lighting block in begin_frame. `instantiateWorld` applies
+// the environment once so the FIRST frame is right, but a consumer that never
+// calls this per frame gets a world that goes dark on frame two. (Shadows are
+// deliberately NOT here — enabling/disabling swaps render passes and belongs
+// at load or on explicit change, which instantiateWorld already handles.)
+//
+// The world editor and the world-viewer example both drive their frames with
+// exactly this call, so lighting cannot look different in-game than in-editor.
+export function applyWorldEnvironment(world: WorldData): void {
+  const env = world.environment;
+  if (!env) return;
+
+  setAmbientLight(
+    {
+      r: Math.floor(env.ambientColor[0] * 255),
+      g: Math.floor(env.ambientColor[1] * 255),
+      b: Math.floor(env.ambientColor[2] * 255),
+      a: 255,
+    },
+    env.ambientIntensity,
+  );
+
+  setDirectionalLight(
+    vec3(env.sunDirection[0], env.sunDirection[1], env.sunDirection[2]),
+    {
+      r: Math.floor(env.sunColor[0] * 255),
+      g: Math.floor(env.sunColor[1] * 255),
+      b: Math.floor(env.sunColor[2] * 255),
+      a: 255,
+    },
+    env.sunIntensity,
+  );
+
+  applyWorldLights(world);
+
+  // The engine's fog is exponential height fog; the schema stores a linear
+  // start/end pair. Approximate with a density reaching ~95% extinction at
+  // fogEnd, near-uniform over height.
+  if (env.fogEnd > 0.0001) {
+    setFog(env.fogColor[0], env.fogColor[1], env.fogColor[2], 3.0 / env.fogEnd, 0, 0.02);
+  } else {
+    setFog(env.fogColor[0], env.fogColor[1], env.fogColor[2], 0, 0, 0.02);
+  }
+}
+
+// A water volume renders as a box whose *top face* sits at `surfaceHeight`
+// (the schema's `center.y` positions the body of water; the surface is what the
+// player sees and what the wave shader animates).
+export function spawnWaterVolume(volume: WaterVolume): SceneNodeHandle {
+  const node = createSceneNode();
+  const cube = genMeshCube(1, 1, 1);
+  attachModelToNode(node, cube.handle, 0);
+
+  const sx = volume.size[0];
+  const sy = volume.size[1];
+  const sz = volume.size[2];
+
+  // Column-major TRS: scale on the diagonal, translation in the last column.
+  // Y is placed so the top face lands on surfaceHeight.
+  const cy = volume.surfaceHeight - sy / 2;
+  setSceneNodeTransform(node, [
+    sx, 0, 0, 0,
+    0, sy, 0, 0,
+    0, 0, sz, 0,
+    volume.center[0], cy, volume.center[2], 1,
+  ]);
+
+  const c = volume.color;
+  setSceneNodeWaterMaterial(
+    node,
+    volume.waveAmplitude, volume.waveSpeed,
+    c[0] * 255, c[1] * 255, c[2] * 255, c[3] * 255,
+  );
+  setSceneNodeVisible(node, true);
+  return node;
+}
+
+// A river renders as a ribbon mesh swept along its control points, dropped by
+// `depth` so it sits in its channel rather than on top of the terrain. Widths
+// are per control point; a river with fewer widths than points repeats the last.
+export function spawnRiver(river: RiverSpline): SceneNodeHandle {
+  const pointCount = river.controlPoints.length;
+  if (pointCount < 2) return 0;
+
+  const points: number[] = [];
+  for (let i = 0; i < pointCount; i++) {
+    const p = river.controlPoints[i];
+    points.push(p[0]);
+    points.push(p[1] - river.depth);
+    points.push(p[2]);
+  }
+
+  const widths: number[] = [];
+  for (let i = 0; i < pointCount; i++) {
+    const w = i < river.widths.length
+      ? river.widths[i]
+      : (river.widths.length > 0 ? river.widths[river.widths.length - 1] : 1);
+    widths.push(w);
+  }
+
+  const ribbon = genMeshSplineRibbon(points, widths);
+  if (ribbon.handle === 0) return 0;
+
+  const node = createSceneNode();
+  attachModelToNode(node, ribbon.handle, 0);
+
+  const c = river.color;
+  // Flow speed drives the same wave animation as a water volume; a river with
+  // no flow still ripples gently rather than reading as a flat plastic strip.
+  setSceneNodeWaterMaterial(
+    node,
+    0.05, river.flowSpeed,
+    c[0] * 255, c[1] * 255, c[2] * 255, c[3] * 255,
+  );
+  setSceneNodeVisible(node, true);
+  return node;
+}
+
+// Editor-only: tint a water/river node to show selection. Games never call this.
+export function setWaterHighlight(handle: SceneNodeHandle, selected: boolean): void {
+  if (selected) {
+    setSceneNodeColor(handle, 255, 220, 120, 255);
+  }
+}

package/src/world/saver.ts

@@ -0,0 +1,108 @@
+// 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.
+//
+// CRASH SAFETY (2026-07-17): a save is a user's level — the one file that
+// must never be half-written. There is no rename FFI, so true atomic replace
+// isn't available; instead every save goes through `safeWrite`:
+//
+//   1. write `<path>.tmp` and READ IT BACK — a byte mismatch fails the save
+//      before the real file is touched (this is the check that would have
+//      caught the era when writeFile wrote 0 bytes and reported success);
+//   2. snapshot the current `<path>` to `<path>.bak`;
+//   3. write `<path>`.
+//
+// A crash at any point leaves a good copy in `.bak` (the previous save) or
+// `.tmp` (the new one, already verified) — losing data requires the disk to
+// fail three times in a row. The `.tmp`/`.bak` siblings are cheap litter;
+// gitignore them in game repos.
+
+import { readFile, writeFile, fileExists } from '../core/index';
+import { WORLD_SCHEMA_VERSION, WorldData, PrefabData } from './types';
+import { validateWorld, validatePrefab, formatValidationErrors } from './validate';
+import { serializeWorld, serializePrefab } from './serialize';
+
+export interface SaveResult {
+  ok: boolean;
+  errors: string[];
+}
+
+// Verified, backup-keeping write. Returns an error string, or null on success.
+function safeWrite(path: string, json: string): string | null {
+  const tmpPath = path + '.tmp';
+  if (!writeFile(tmpPath, json)) {
+    return 'could not write ' + tmpPath;
+  }
+  const readBack = readFile(tmpPath);
+  if (readBack !== json) {
+    return 'readback mismatch on ' + tmpPath + ' (wrote ' + json.length +
+      ' chars, read ' + (readBack ? readBack.length : 0) + ') — disk or FFI fault, original untouched';
+  }
+
+  if (fileExists(path)) {
+    const prev = readFile(path);
+    if (prev && prev.length > 0) {
+      // Best-effort: a failed backup shouldn't block the save itself.
+      writeFile(path + '.bak', prev);
+    }
+  }
+
+  if (!writeFile(path, json)) {
+    return 'could not write ' + path + ' — previous version is in ' + path +
+      '.bak, the new one in ' + tmpPath;
+  }
+  return null;
+}
+
+// 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 };
+  }
+
+  // NOT JSON.stringify — see serialize.ts. On Perry 0.5.x it corrupts a large object
+  // graph that came from JSON.parse, the corrupt string fails the FFI's UTF-8 check,
+  // and writeFile then wrote a ZERO-BYTE FILE AND RETURNED SUCCESS. Saving a world
+  // destroyed it, silently.
+  const json = serializeWorld(world);
+  const err = safeWrite(path, json);
+  if (err !== null) {
+    return { ok: false, errors: ['saveWorld: ' + err] };
+  }
+  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 = serializePrefab(prefab);
+  const err = safeWrite(path, json);
+  if (err !== null) {
+    return { ok: false, errors: ['savePrefab: ' + err] };
+  }
+  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/serialize.ts

@@ -0,0 +1,301 @@
+// Hand-written JSON emitter for WorldData / PrefabData.
+//
+// WHY THIS EXISTS, AND WHY IT IS NOT `JSON.stringify`.
+//
+// `JSON.stringify` CORRUPTS a large object graph that came from `JSON.parse` on
+// Perry 0.5.x. Minimal repro, no engine code involved:
+//
+//   const text = readFile('assets/worlds/arena_02.world.json');  // 324 KB, fine
+//   const o    = JSON.parse(text);                                // fine
+//   const re   = JSON.stringify(o, null, 2);
+//   // -> `re` contains 5,296 characters above U+00FF, in a JSON document whose
+//   //    source is almost pure ASCII. It is garbage.
+//
+// The corruption is invisible until the string crosses the FFI: the engine's
+// `str_from_header` fails its UTF-8 check, returns "", and `writeFile` then writes
+// a ZERO-BYTE FILE AND REPORTS SUCCESS.
+//
+// So `saveWorld` did not save. It emptied the file and said "ok". Every world the
+// editor has ever "saved" was destroyed by saving it — which is why the editor has
+// only ever been used to look at worlds that some other tool produced.
+//
+// It is not size (a fresh 1 MB world-shaped object stringifies fine), not floats,
+// not nulls, not `Record` keys, not non-ASCII — every one of those was ruled out by
+// probe. It is specifically the parsed graph. A manual deep clone does not escape it.
+//
+// So the save path does not get to use `JSON.stringify`. This emitter walks the
+// schema by LITERAL KEY and builds the document by concatenation, which is the same
+// discipline the shooter's `settings.ts` already adopted ("Perry's object handling
+// is only trustworthy with literal keys") and which the probes show is reliable.
+//
+// Being schema-explicit is not only a workaround, it is a feature: an unknown field
+// cannot be silently dropped by a serializer that never knew about it — the schema
+// and the writer change together, or validation fails.
+
+import {
+  WorldData, PrefabData, PrefabChild, EntityData, LightData,
+  WaterVolume, RiverSpline, TerrainData, TerrainLayer, EnvironmentData,
+  TransformData, Vec3Lit, Vec4Lit,
+} from './types';
+
+// --- primitives --------------------------------------------------------------
+
+/// JSON string escaping. Control characters must be escaped or the document is
+/// invalid; everything else is emitted as-is (the file is UTF-8).
+function str(s: string): string {
+  let out = '"';
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c === 34) out = out + '\\"';
+    else if (c === 92) out = out + '\\\\';
+    else if (c === 10) out = out + '\\n';
+    else if (c === 13) out = out + '\\r';
+    else if (c === 9) out = out + '\\t';
+    else if (c === 8) out = out + '\\b';
+    else if (c === 12) out = out + '\\f';
+    else if (c < 32) {
+      // \u00XX — the only escapes JSON *requires*.
+      let h = c.toString(16);
+      while (h.length < 4) h = '0' + h;
+      out = out + '\\u' + h;
+    } else {
+      out = out + s.charAt(i);
+    }
+  }
+  return out + '"';
+}
+
+/// Numbers. NaN and Infinity are not JSON; emitting them produces a file that will
+/// not parse, so they become 0 rather than a document nobody can open.
+function num(n: number): string {
+  if (n !== n) return '0';                       // NaN
+  if (n === Infinity || n === -Infinity) return '0';
+  // Integers stay integers — `1` not `1.0` — so a hand-written world file and a
+  // round-tripped one look the same in a diff.
+  if (n === Math.floor(n) && Math.abs(n) < 1e15) return '' + n;
+  return '' + n;
+}
+
+// Written with `if` as a precaution, not a fix for an observed bug: a helper whose
+// entire body is one ternary return is a shape Perry has miscompiled elsewhere
+// (perry-quirks #8). `bool()` itself was verified CORRECT in both forms — a world
+// saved with `shadowsEnabled: false` does write `false`.
+function bool(b: boolean): string {
+  if (b) return 'true';
+  return 'false';
+}
+
+function vec3(v: Vec3Lit): string {
+  return '[' + num(v[0]) + ', ' + num(v[1]) + ', ' + num(v[2]) + ']';
+}
+function vec4(v: Vec4Lit): string {
+  return '[' + num(v[0]) + ', ' + num(v[1]) + ', ' + num(v[2]) + ', ' + num(v[3]) + ']';
+}
+function nums(a: number[]): string {
+  let out = '[';
+  for (let i = 0; i < a.length; i++) {
+    if (i > 0) out = out + ', ';
+    out = out + num(a[i]);
+  }
+  return out + ']';
+}
+function strs(a: string[]): string {
+  let out = '[';
+  for (let i = 0; i < a.length; i++) {
+    if (i > 0) out = out + ', ';
+    out = out + str(a[i]);
+  }
+  return out + ']';
+}
+
+function ind(n: number): string {
+  let s = '';
+  for (let i = 0; i < n; i++) s = s + '  ';
+  return s;
+}
+
+/// A `Record<string, string>`. Keys come from the data, so this is the one place we
+/// cannot use literal keys — but `Object.keys` on a *fresh* object is sound, and
+/// callers hand us the parsed map directly.
+function record(r: Record<string, string>, depth: number): string {
+  const keys = Object.keys(r);
+  if (keys.length === 0) return '{}';
+  let out = '{\n';
+  for (let i = 0; i < keys.length; i++) {
+    const k = keys[i];
+    out = out + ind(depth + 1) + str(k) + ': ' + str(r[k]);
+    if (i < keys.length - 1) out = out + ',';
+    out = out + '\n';
+  }
+  return out + ind(depth) + '}';
+}
+
+// --- schema ------------------------------------------------------------------
+
+function transform(t: TransformData, d: number): string {
+  return '{\n'
+    + ind(d + 1) + '"position": ' + vec3(t.position) + ',\n'
+    + ind(d + 1) + '"rotation": ' + vec3(t.rotation) + ',\n'
+    + ind(d + 1) + '"scale": ' + vec3(t.scale) + '\n'
+    + ind(d) + '}';
+}
+
+function entity(e: EntityData, d: number): string {
+  let s = '{\n';
+  s = s + ind(d + 1) + '"id": ' + str(e.id) + ',\n';
+  s = s + ind(d + 1) + '"name": ' + str(e.name) + ',\n';
+  s = s + ind(d + 1) + '"modelRef": ' + (e.modelRef === null ? 'null' : str(e.modelRef)) + ',\n';
+  s = s + ind(d + 1) + '"prefabRef": ' + (e.prefabRef === null ? 'null' : str(e.prefabRef)) + ',\n';
+  s = s + ind(d + 1) + '"transform": ' + transform(e.transform, d + 1) + ',\n';
+  s = s + ind(d + 1) + '"tint": ' + (e.tint === null ? 'null' : vec4(e.tint)) + ',\n';
+  s = s + ind(d + 1) + '"tags": ' + strs(e.tags) + ',\n';
+  s = s + ind(d + 1) + '"userData": ' + record(e.userData, d + 1) + '\n';
+  return s + ind(d) + '}';
+}
+
+function light(l: LightData, d: number): string {
+  return '{\n'
+    + ind(d + 1) + '"id": ' + str(l.id) + ',\n'
+    + ind(d + 1) + '"name": ' + str(l.name) + ',\n'
+    + ind(d + 1) + '"kind": ' + str(l.kind) + ',\n'
+    + ind(d + 1) + '"position": ' + vec3(l.position) + ',\n'
+    + ind(d + 1) + '"color": ' + vec3(l.color) + ',\n'
+    + ind(d + 1) + '"intensity": ' + num(l.intensity) + ',\n'
+    + ind(d + 1) + '"range": ' + num(l.range) + '\n'
+    + ind(d) + '}';
+}
+
+function water(w: WaterVolume, d: number): string {
+  return '{\n'
+    + ind(d + 1) + '"id": ' + str(w.id) + ',\n'
+    + ind(d + 1) + '"kind": ' + str(w.kind) + ',\n'
+    + ind(d + 1) + '"center": ' + vec3(w.center) + ',\n'
+    + ind(d + 1) + '"size": ' + vec3(w.size) + ',\n'
+    + ind(d + 1) + '"surfaceHeight": ' + num(w.surfaceHeight) + ',\n'
+    + ind(d + 1) + '"color": ' + vec4(w.color) + ',\n'
+    + ind(d + 1) + '"waveAmplitude": ' + num(w.waveAmplitude) + ',\n'
+    + ind(d + 1) + '"waveSpeed": ' + num(w.waveSpeed) + '\n'
+    + ind(d) + '}';
+}
+
+function river(r: RiverSpline, d: number): string {
+  let pts = '[';
+  for (let i = 0; i < r.controlPoints.length; i++) {
+    if (i > 0) pts = pts + ', ';
+    pts = pts + vec3(r.controlPoints[i]);
+  }
+  pts = pts + ']';
+  return '{\n'
+    + ind(d + 1) + '"id": ' + str(r.id) + ',\n'
+    + ind(d + 1) + '"controlPoints": ' + pts + ',\n'
+    + ind(d + 1) + '"widths": ' + nums(r.widths) + ',\n'
+    + ind(d + 1) + '"depth": ' + num(r.depth) + ',\n'
+    + ind(d + 1) + '"flowSpeed": ' + num(r.flowSpeed) + ',\n'
+    + ind(d + 1) + '"color": ' + vec4(r.color) + '\n'
+    + ind(d) + '}';
+}
+
+function terrainLayer(l: TerrainLayer, d: number): string {
+  return '{\n'
+    + ind(d + 1) + '"id": ' + str(l.id) + ',\n'
+    + ind(d + 1) + '"textureRef": ' + str(l.textureRef) + ',\n'
+    + ind(d + 1) + '"weights": ' + nums(l.weights) + ',\n'
+    + ind(d + 1) + '"tileScale": ' + num(l.tileScale) + '\n'
+    + ind(d) + '}';
+}
+
+function terrain(t: TerrainData, d: number): string {
+  let layers = '[]';
+  if (t.layers.length > 0) {
+    layers = '[\n';
+    for (let i = 0; i < t.layers.length; i++) {
+      layers = layers + ind(d + 2) + terrainLayer(t.layers[i], d + 2);
+      if (i < t.layers.length - 1) layers = layers + ',';
+      layers = layers + '\n';
+    }
+    layers = layers + ind(d + 1) + ']';
+  }
+  return '{\n'
+    + ind(d + 1) + '"width": ' + num(t.width) + ',\n'
+    + ind(d + 1) + '"depth": ' + num(t.depth) + ',\n'
+    + ind(d + 1) + '"cellSize": ' + num(t.cellSize) + ',\n'
+    + ind(d + 1) + '"origin": ' + vec3(t.origin) + ',\n'
+    + ind(d + 1) + '"heights": ' + nums(t.heights) + ',\n'
+    + ind(d + 1) + '"layers": ' + layers + '\n'
+    + ind(d) + '}';
+}
+
+function environment(e: EnvironmentData, d: number): string {
+  return '{\n'
+    + ind(d + 1) + '"skyColor": ' + vec3(e.skyColor) + ',\n'
+    + ind(d + 1) + '"ambientColor": ' + vec3(e.ambientColor) + ',\n'
+    + ind(d + 1) + '"ambientIntensity": ' + num(e.ambientIntensity) + ',\n'
+    + ind(d + 1) + '"sunDirection": ' + vec3(e.sunDirection) + ',\n'
+    + ind(d + 1) + '"sunColor": ' + vec3(e.sunColor) + ',\n'
+    + ind(d + 1) + '"sunIntensity": ' + num(e.sunIntensity) + ',\n'
+    + ind(d + 1) + '"fogStart": ' + num(e.fogStart) + ',\n'
+    + ind(d + 1) + '"fogEnd": ' + num(e.fogEnd) + ',\n'
+    + ind(d + 1) + '"fogColor": ' + vec3(e.fogColor) + ',\n'
+    + ind(d + 1) + '"shadowsEnabled": ' + bool(e.shadowsEnabled) + '\n'
+    + ind(d) + '}';
+}
+
+function arr<T>(items: T[], d: number, fn: (x: T, d: number) => string): string {
+  if (items.length === 0) return '[]';
+  let out = '[\n';
+  for (let i = 0; i < items.length; i++) {
+    out = out + ind(d + 1) + fn(items[i], d + 1);
+    if (i < items.length - 1) out = out + ',';
+    out = out + '\n';
+  }
+  return out + ind(d) + ']';
+}
+
+// --- entry points ------------------------------------------------------------
+
+export function serializeWorld(w: WorldData): string {
+  let s = '{\n';
+  s = s + ind(1) + '"schemaVersion": ' + num(w.schemaVersion) + ',\n';
+  s = s + ind(1) + '"name": ' + str(w.name) + ',\n';
+  s = s + ind(1) + '"id": ' + str(w.id) + ',\n';
+  s = s + ind(1) + '"bounds": {\n'
+        + ind(2) + '"min": ' + vec3(w.bounds.min) + ',\n'
+        + ind(2) + '"max": ' + vec3(w.bounds.max) + '\n'
+        + ind(1) + '},\n';
+  s = s + ind(1) + '"environment": ' + environment(w.environment, 1) + ',\n';
+  s = s + ind(1) + '"terrain": ' + (w.terrain === null ? 'null' : terrain(w.terrain, 1)) + ',\n';
+  s = s + ind(1) + '"entities": ' + arr(w.entities, 1, entity) + ',\n';
+  s = s + ind(1) + '"lights": ' + arr(w.lights, 1, light) + ',\n';
+  s = s + ind(1) + '"water": ' + arr(w.water, 1, water) + ',\n';
+  s = s + ind(1) + '"rivers": ' + arr(w.rivers, 1, river) + ',\n';
+  s = s + ind(1) + '"metadata": ' + record(w.metadata, 1) + '\n';
+  return s + '}\n';
+}
+
+function prefabChild(c: PrefabChild, d: number): string {
+  let s = '{\n';
+  s = s + ind(d + 1) + '"id": ' + str(c.id) + ',\n';
+  s = s + ind(d + 1) + '"modelRef": ' + (c.modelRef === null ? 'null' : str(c.modelRef)) + ',\n';
+  s = s + ind(d + 1) + '"prefabRef": ' + (c.prefabRef === null ? 'null' : str(c.prefabRef)) + ',\n';
+  s = s + ind(d + 1) + '"transform": ' + transform(c.transform, d + 1) + ',\n';
+  s = s + ind(d + 1) + '"tint": ' + (c.tint === null ? 'null' : vec4(c.tint)) + ',\n';
+  s = s + ind(d + 1) + '"tags": ' + strs(c.tags) + '\n';
+  return s + ind(d) + '}';
+}
+
+export function serializePrefab(p: PrefabData): string {
+  // schemaVersion and bounds were MISSING here until 2026-07-15 — every prefab
+  // ever saved lost both (schemaVersion was silently backfilled by migration on
+  // reload; bounds came back as undefined). If you add a field to PrefabData,
+  // it must be added here too, or savePrefab drops it.
+  let s = '{\n';
+  s = s + ind(1) + '"schemaVersion": ' + num(p.schemaVersion) + ',\n';
+  s = s + ind(1) + '"id": ' + str(p.id) + ',\n';
+  s = s + ind(1) + '"name": ' + str(p.name) + ',\n';
+  s = s + ind(1) + '"children": ' + arr(p.children, 1, prefabChild) + ',\n';
+  s = s + ind(1) + '"bounds": {\n'
+        + ind(2) + '"min": ' + vec3(p.bounds.min) + ',\n'
+        + ind(2) + '"max": ' + vec3(p.bounds.max) + '\n'
+        + ind(1) + '}\n';
+  return s + '}\n';
+}