feat(ludic.lab): the visual lab as a package - a scene on a plate, never a world

A scene is an entry in the open registry LabScenes, shown on a plate: a
flat lit disc, the package's own small sky with the sun at one hour, and
a frame clock. Headless each camera (lab_shot, lab_shot_at) settles and
is written as build/lab/<scene>/<shot>.png (a stored PNG, written here);
in a window N and P step through them. tools/lab/run.sh and sheet.py
make the contact sheet; tools/lab/plate_build.py makes plate/.
ludic.render3d gains r3d_plate_mode (no terrain, grass or water is made)
and r3d_sky_path. quit() in a program with no frame loop links. The
example takes ~120 MB resident, 417 MiB peak footprint. Reseed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

packages/README.md

@@ -37,6 +37,7 @@ section. The rules are in [ludic.base](ludic.base/README.md).
 | --- | --- |
 | [ludic.render3d](ludic.render3d/) | the physically based 3D renderer over OpenGL and Vulkan (named `ludic_render3d` under `uses`) |
 | [ludic.ui](ludic.ui/) | components: templates, stylesheets, layout, input and focus (`module ludic_ui`) |
+| [ludic.lab](ludic.lab/README.md) | the visual lab: a scene on a lit plate, fixed cameras, PNG shots and a contact sheet |
 | [ludic.core](ludic.core/) | the canonical engine-ABI components |
 | [ludic.prefs](ludic.prefs/) | a small `key=value` store for preferences and records |
 

packages/ludic.lab/README.md

@@ -0,0 +1,73 @@
+# ludic.lab
+
+The visual lab: one model or one mechanic on a **plate**, photographed from fixed cameras. A lab
+scene is a minimal, isolated, reproducible piece of a game - never the whole world. The plate is a
+flat, lit disc 40 m across with a line every metre, a small sky of its own with the sun 40 degrees
+up (one fixed hour), and a clock of frames: 60 a second, whatever the machine. Nothing else is
+loaded - no terrain, no grass, no water (`r3d_plate_mode` in ludic.render3d) - so a scene starts in
+about a second and takes about 120 MB resident (420 MB peak footprint with the GPU driver's share)
+where a lab on a whole valley took 7.8 GB.
+
+`module ludic_lab uses ludic_render3d, ludic_base`.
+
+## A lab program
+
+```ludic
+import "ludic.lab"
+program Lab {
+  numbers float
+  function probe_setup() -> void {
+    lab_model(lab_plate_dir(), "probe.gltf", "probe", 0.0, 0.0, 0.5)
+    lab_shot_at("front", 0.0, 0.7, 0.0, 4.0, 0.0, 12.0)
+    lab_shot_at("above", 0.0, 0.5, 0.0, 7.0, 30.0, 55.0)
+  }
+  def LabScenes probe { setup: fn probe_setup }
+  handler Boot phase Start { lab_boot() }
+  handler Look phase Input { lab_input() }
+  handler Draw phase Render { lab_render() }
+}
+```
+
+`example/plate.ludic` is this program. Scenes are an open registry, so a game - or a package
+showing its own models - adds them from its own module with `def LabScenes <name> { ... }`:
+
+| field | |
+| --- | --- |
+| `setup: fn()` | build what the scene shows and name its cameras |
+| `tick: fn(float)` | move it, by the lab's fixed step (1/60 s) |
+| `draw: fn()` | draw what is not an actor or a scatter layer (actors and layers are drawn already) |
+
+`R3D_SCENE=<name>` picks the scene (the first one added otherwise); an unknown name lists them.
+
+## Running it
+
+- **Headless** (`ludic build ... --headless`): every shot is held `lab_settle` frames (45), written
+  to `build/lab/<scene>/<shot>.png`, and after the last the program quits. The headless loop reads a
+  line of stdin a frame: `yes '' | head -n 20000 | R3D_SCENE=probe ./lab`.
+- **In a window**: N and P step through the shots.
+- `tools/lab/run.sh <lab.ludic> <scene> ...` (in the toolchain's checkout) builds the program, runs
+  each scene and makes `build/lab/<scene>/sheet.png`, a contact sheet (`tools/lab/sheet.py`).
+
+## API
+
+| | |
+| --- | --- |
+| `lab_boot()`, `lab_input()`, `lab_render()` | the program's Start, Input and Render handlers |
+| `lab_shot(name, x, y, z, yaw_deg, pitch_deg)` | a camera at a point, looking along yaw and pitch (degrees) |
+| `lab_shot_at(name, tx, ty, tz, dist, from_deg, up_deg)` | a camera `dist` metres from a point, from a bearing (0 = from +z), `up_deg` above it, looking at it |
+| `lab_shot_count()` | the cameras named so far |
+| `lab_model(dir, file, node, x, z, yaw) -> Actor`, `lab_stand(a, x, z, yaw)`, `lab_ground_y(x, z)` | a glTF node stood on the plate; the plate is flat at y = 0 |
+| `lab_plate_dir()` | the package's `plate/`: the disc, its sky and the probe model |
+| `lab_settle(frames)`, `lab_font(dir)`, `lab_title(s)`, `lab_note(s)` | how long a shot settles; the overlay font for captions (none by default); the window's title; a line under the caption |
+| `lab_scene()`, `lab_frame()`, `lab_time()` | the scene, and the lab's clock |
+| `lab_ppm_to_png(ppm, png)` | a frame as a PNG (stored, not compressed) |
+
+## The plate's files
+
+`plate/` is built by `tools/lab/plate_build.py` in the toolchain's checkout and is deterministic:
+`plate.gltf` (the disc), `probe.gltf` (a box with a ball on it, for looking at the light), and
+`sky.hdr` (512 x 256, the sun at 40 degrees). Change the script and run it again; never edit them.
+
+## Not here yet
+
+- A heightfield patch for a scene that needs a slope: the plate is flat.

packages/ludic.lab/boot.ludic

@@ -0,0 +1,56 @@
+# boot.ludic - the window, the renderer on a plate (no terrain, no grass, no water), the plate and
+# its sky, then the scene named by R3D_SCENE (else the first one added)
+function lab_draw() -> void {
+  actor_draw()
+  scatter_draw()
+  if lb_draw != null { lb_draw() }
+}
+function lab_casters(light_vp: floats) -> void {
+  actor_draw_casters(light_vp)
+  scatter_draw_casters(light_vp)
+}
+function lab_pick_scene() -> int {
+  if LAB_COUNT == 0 { return -1 }
+  lb_scene = LabScenes[0].key
+  if Os.has_env("R3D_SCENE") { lb_scene = Os.env("R3D_SCENE") }
+  return labscenes_find(lb_scene)
+}
+# once, from the program's Start handler
+export function lab_boot() -> void {
+  lb_windowed = is_windowed()
+  let k = lab_pick_scene()
+  if k < 0 {
+    print(`lab: no scene called '{lb_scene}' - {lab_scene_names()}`)
+    quit()
+    return
+  }
+  var ww = 1920
+  var wh = 1080
+  if lb_windowed {
+    ww = 960
+    wh = 540
+  }
+  r3d_plate_mode(true)
+  r3d_sky_path = `{lab_plate_dir()}/sky.hdr`
+  if not r3d_init(ww, wh, lb_title) {
+    quit()
+    return
+  }
+  if lb_font != "" { overlay_init(lb_font) }
+  r3d_on_draw(fn lab_draw)
+  r3d_on_casters(fn lab_casters)
+  lab_plate_load()
+  lab_shots_reset()
+  lb_out = `build/lab/{lb_scene}`
+  let sc = LabScenes[k]
+  lb_draw = sc.draw
+  if sc.setup != null { sc.setup() }
+  if lab_shot_count() == 0 { lab_shot_at("plate", 0.0, 1.0, 0.0, 8.0, 0.0, 15.0) }
+  lab_shot_apply(0)
+  if not lb_windowed {
+    Fs.mkdir("build")
+    Fs.mkdir("build/lab")
+    Fs.mkdir(lb_out)
+  }
+  print(`lab: scene {lb_scene}, {lab_shot_count()} shots`)
+}

packages/ludic.lab/example/plate.ludic

@@ -0,0 +1,20 @@
+# plate.ludic - the lab's example: one model on the plate, photographed from three cameras.
+#   ludic build packages/ludic.lab/example/plate.ludic --headless -o build/lab_plate
+#   yes '' | head -300 | ./build/lab_plate      -> build/lab/probe/{front,side,above}.png
+# The model is the package's own probe (a box with a ball on it), so the example needs nothing
+# from any game.
+import "ludic.lab"
+program LabPlate {
+  numbers float
+  function probe_setup() -> void {
+    lab_model(lab_plate_dir(), "probe.gltf", "probe", 0.0, 0.0, 0.5)
+    lab_note("a box and a ball, in the plate's light")
+    lab_shot_at("front", 0.0, 0.7, 0.0, 4.0, 0.0, 12.0)
+    lab_shot_at("side", 0.0, 0.7, 0.0, 4.0, 90.0, 12.0)
+    lab_shot_at("above", 0.0, 0.5, 0.0, 7.0, 30.0, 55.0)
+  }
+  def LabScenes probe { setup: fn probe_setup }
+  handler Boot phase Start { lab_boot() }
+  handler Look phase Input { lab_input() }
+  handler Draw phase Render { lab_render() }
+}

packages/ludic.lab/index.ludic

@@ -0,0 +1,12 @@
+# ludic.lab - a scene on a plate (a lit disc, a sky, a sun at one hour, a clock of frames) and the
+# cameras that photograph it; a game or a package adds scenes to LabScenes. See README.md.
+module ludic_lab uses ludic_render3d, ludic_base
+numbers float
+import "ludic.render3d/r3d.ludic"
+import "state.ludic"
+import "scenes.ludic"
+import "plate.ludic"
+import "shots.ludic"
+import "png.ludic"
+import "boot.ludic"
+import "loop.ludic"

packages/ludic.lab/loop.ludic

@@ -0,0 +1,50 @@
+# loop.ludic - each frame: the scene's tick by a fixed step, the shot's camera, its caption, and -
+# headless - the picture once the shot has settled, then the next shot, then quit. In a window
+# N and P step through the shots.
+export function lab_input() -> void {
+  if not lb_windowed { return }
+  Input.poll()
+  let n = lab_shot_count()
+  if n > 0 and Input.key_pressed(key: 'n') {
+    lb_shot = (lb_shot + 1) % n
+    lab_shot_apply(lb_shot)
+  }
+  if n > 0 and Input.key_pressed(key: 'p') {
+    lb_shot = (lb_shot + n - 1) % n
+    lab_shot_apply(lb_shot)
+  }
+}
+export function lab_render() -> void {
+  lb_frame += 1
+  let k = labscenes_find(lb_scene)
+  if k >= 0 and LabScenes[k].tick != null { LabScenes[k].tick(1.0 / 60.0) }
+  r3d_frame(lab_time())
+  lab_caption()
+  if not lb_windowed { lab_take() }
+  r3d_present()
+}
+function lab_caption() -> void {
+  if lb_font == "" { return }
+  ov_begin()
+  var name = ""
+  if lb_shot < lab_shot_count() { name = lb_shot_names[lb_shot] }
+  ov_rect(0, 0, 900, 64, 0.0, 0.0, 0.0, 0.55)
+  ov_text(20, 10, 30, `{lb_scene} / {name}   ({lb_shot + 1} of {lab_shot_count()})`, 1.0, 1.0, 1.0, 1.0)
+  if len(lb_note) > 0 { ov_text(20, 42, 18, lb_note, 0.8, 0.8, 0.8, 1.0) }
+  ov_end()
+}
+function lab_take() -> void {
+  lb_wait += 1
+  if lb_wait < lb_settle { return }
+  let base = `{lb_out}/{lb_shot_names[lb_shot]}`
+  r3d_screenshot(`{base}.ppm`)
+  if lab_ppm_to_png(`{base}.ppm`, `{base}.png`) { print(`lab: shot {base}.png`) } else { print(`lab: shot {base}.ppm`) }
+  lb_shots_taken += 1
+  lb_wait = 0
+  lb_shot += 1
+  if lb_shot >= lab_shot_count() {
+    quit()
+    return
+  }
+  lab_shot_apply(lb_shot)
+}

packages/ludic.lab/package.ludic

@@ -0,0 +1,5 @@
+# ludic.lab - the visual lab: one model or one mechanic on a plate, photographed from fixed
+# cameras, never a whole game world. See README.md.
+package "ludic.lab"
+version "0.1.0"
+kind source

packages/ludic.lab/plate.ludic

@@ -0,0 +1,36 @@
+# plate.ludic - the stage: a flat disc 40 m across at y = 0 with a line every metre, lit by the
+# package's own small sky (a sun 40 degrees up), and nothing else. Its files are in plate/.
+var lb_plate: Actor = null
+var lb_plate_dir: string = ""
+
+# the package's plate/ directory: beside the project (a checkout of the toolchain) or installed
+export function lab_plate_dir() -> string {
+  if lb_plate_dir != "" { return lb_plate_dir }
+  lb_plate_dir = "packages/ludic.lab/plate"
+  if not Fs.exists(`{lb_plate_dir}/plate.gltf`) { lb_plate_dir = `{r3d_home()}/packages/ludic.lab/plate` }
+  return lb_plate_dir
+}
+function lab_plate_load() -> void {
+  let m = gltf_load(lab_plate_dir(), "plate.gltf", "plate")
+  if m == null { return }
+  lb_plate = actor_new(m)
+  lb_plate.casts = false
+  lb_plate.cull = 0.0
+  lb_plate.radius = 0.0
+  actor_place(lb_plate, 0.0, 0.0, 0.0, 0.0)
+}
+# the ground under (x, z): the plate is flat at 0
+export function lab_ground_y(x: float, z: float) -> float { return 0.0 }
+# an actor stood on the plate at (x, z), facing yaw (radians)
+export function lab_stand(a: Actor, x: float, z: float, yaw: float) -> void {
+  if a == null { return }
+  actor_place(a, x, lab_ground_y(x, z), z, yaw)
+}
+# a model from a glTF file stood on the plate: the one call a scene usually needs
+export function lab_model(dir: string, file: string, node: string, x: float, z: float, yaw: float) -> Actor {
+  let m = gltf_load(dir, file, node)
+  if m == null { return null }
+  let a = actor_new(m)
+  lab_stand(a, x, z, yaw)
+  return a
+}

packages/ludic.lab/plate/plate.gltf

@@ -0,0 +1,129 @@
+{
+ "asset": {
+  "version": "2.0",
+  "generator": "ludic tools/lab/plate_build.py"
+ },
+ "scene": 0,
+ "scenes": [
+  {
+   "nodes": [
+    0
+   ]
+  }
+ ],
+ "nodes": [
+  {
+   "name": "plate",
+   "mesh": 0
+  }
+ ],
+ "meshes": [
+  {
+   "name": "plate",
+   "primitives": [
+    {
+     "attributes": {
+      "POSITION": 0,
+      "NORMAL": 1,
+      "TEXCOORD_0": 2
+     },
+     "indices": 3,
+     "material": 0
+    }
+   ]
+  }
+ ],
+ "materials": [
+  {
+   "name": "plate",
+   "pbrMetallicRoughness": {
+    "baseColorTexture": {
+     "index": 0
+    },
+    "metallicRoughnessTexture": {
+     "index": 1
+    }
+   }
+  }
+ ],
+ "textures": [
+  {
+   "source": 0
+  },
+  {
+   "source": 1
+  }
+ ],
+ "images": [
+  {
+   "uri": "plate_diff.png"
+  },
+  {
+   "uri": "plate_arm.png"
+  }
+ ],
+ "buffers": [
+  {
+   "uri": "plate.bin",
+   "byteLength": 4256
+  }
+ ],
+ "bufferViews": [
+  {
+   "buffer": 0,
+   "byteOffset": 0,
+   "byteLength": 1164
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 1164,
+   "byteLength": 1164
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 2328,
+   "byteLength": 776
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 3104,
+   "byteLength": 1152
+  }
+ ],
+ "accessors": [
+  {
+   "bufferView": 0,
+   "componentType": 5126,
+   "count": 97,
+   "type": "VEC3",
+   "min": [
+    -20.0,
+    0.0,
+    -20.0
+   ],
+   "max": [
+    20.0,
+    0.0,
+    20.0
+   ]
+  },
+  {
+   "bufferView": 1,
+   "componentType": 5126,
+   "count": 97,
+   "type": "VEC3"
+  },
+  {
+   "bufferView": 2,
+   "componentType": 5126,
+   "count": 97,
+   "type": "VEC2"
+  },
+  {
+   "bufferView": 3,
+   "componentType": 5125,
+   "count": 288,
+   "type": "SCALAR"
+  }
+ ]
+}

packages/ludic.lab/plate/probe.gltf

@@ -0,0 +1,209 @@
+{
+ "asset": {
+  "version": "2.0",
+  "generator": "ludic tools/lab/plate_build.py"
+ },
+ "scene": 0,
+ "scenes": [
+  {
+   "nodes": [
+    0
+   ]
+  }
+ ],
+ "nodes": [
+  {
+   "name": "probe",
+   "mesh": 0
+  }
+ ],
+ "meshes": [
+  {
+   "name": "probe",
+   "primitives": [
+    {
+     "attributes": {
+      "POSITION": 0,
+      "NORMAL": 1,
+      "TEXCOORD_0": 2
+     },
+     "indices": 3,
+     "material": 0
+    },
+    {
+     "attributes": {
+      "POSITION": 4,
+      "NORMAL": 5,
+      "TEXCOORD_0": 6
+     },
+     "indices": 7,
+     "material": 1
+    }
+   ]
+  }
+ ],
+ "materials": [
+  {
+   "name": "probe_box",
+   "pbrMetallicRoughness": {
+    "baseColorTexture": {
+     "index": 0
+    },
+    "metallicRoughnessTexture": {
+     "index": 2
+    }
+   }
+  },
+  {
+   "name": "probe_ball",
+   "pbrMetallicRoughness": {
+    "baseColorTexture": {
+     "index": 1
+    },
+    "metallicRoughnessTexture": {
+     "index": 2
+    }
+   }
+  }
+ ],
+ "textures": [
+  {
+   "source": 0
+  },
+  {
+   "source": 1
+  },
+  {
+   "source": 2
+  }
+ ],
+ "images": [
+  {
+   "uri": "probe_box.png"
+  },
+  {
+   "uri": "probe_ball.png"
+  },
+  {
+   "uri": "probe_arm.png"
+  }
+ ],
+ "buffers": [
+  {
+   "uri": "probe.bin",
+   "byteLength": 31152
+  }
+ ],
+ "bufferViews": [
+  {
+   "buffer": 0,
+   "byteOffset": 0,
+   "byteLength": 288
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 288,
+   "byteLength": 288
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 576,
+   "byteLength": 192
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 768,
+   "byteLength": 144
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 912,
+   "byteLength": 6732
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 7644,
+   "byteLength": 6732
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 14376,
+   "byteLength": 4488
+  },
+  {
+   "buffer": 0,
+   "byteOffset": 18864,
+   "byteLength": 12288
+  }
+ ],
+ "accessors": [
+  {
+   "bufferView": 0,
+   "componentType": 5126,
+   "count": 24,
+   "type": "VEC3",
+   "min": [
+    -0.4,
+    0.0,
+    -0.4
+   ],
+   "max": [
+    0.4,
+    0.8,
+    0.4
+   ]
+  },
+  {
+   "bufferView": 1,
+   "componentType": 5126,
+   "count": 24,
+   "type": "VEC3"
+  },
+  {
+   "bufferView": 2,
+   "componentType": 5126,
+   "count": 24,
+   "type": "VEC2"
+  },
+  {
+   "bufferView": 3,
+   "componentType": 5125,
+   "count": 36,
+   "type": "SCALAR"
+  },
+  {
+   "bufferView": 4,
+   "componentType": 5126,
+   "count": 561,
+   "type": "VEC3",
+   "min": [
+    -0.3,
+    0.8,
+    -0.3
+   ],
+   "max": [
+    0.3,
+    1.4000000000000001,
+    0.3
+   ]
+  },
+  {
+   "bufferView": 5,
+   "componentType": 5126,
+   "count": 561,
+   "type": "VEC3"
+  },
+  {
+   "bufferView": 6,
+   "componentType": 5126,
+   "count": 561,
+   "type": "VEC2"
+  },
+  {
+   "bufferView": 7,
+   "componentType": 5125,
+   "count": 3072,
+   "type": "SCALAR"
+  }
+ ]
+}

packages/ludic.lab/png.ludic

@@ -0,0 +1,131 @@
+# png.ludic - the renderer writes a frame as a PPM; the lab keeps it as a PNG, stored rather than
+# compressed (a PNG anything opens, with no zlib here): the shot is the PPM's pixels, filter 0
+# on every row, in deflate's stored blocks, with its CRCs and its Adler-32.
+var lp_table: []long = null
+
+function lp_u32(hi: int, lo: int) -> long { return long(hi) * long(65536) + long(lo) }
+function lp_table_init() -> void {
+  if lp_table != null { return }
+  lp_table = new []long
+  let poly = lp_u32(60856, 33568)          # 0xEDB88320
+  for n in 0 .. 256 {
+    var c = long(n)
+    for k in 0 .. 8 {
+      if (c & long(1)) != long(0) { c = (c >> long(1)) ^ poly } else { c = c >> long(1) }
+    }
+    push(lp_table, c)
+  }
+}
+# CRC-32 of out[from .. from + n)
+function lp_crc(out: []byte, from: int, n: int) -> long {
+  lp_table_init()
+  let mask = lp_u32(65535, 65535)
+  var c = mask
+  for i in from .. from + n {
+    let k = int((c ^ long(out[i])) & long(255))
+    c = lp_table[k] ^ (c >> long(8))
+  }
+  return c ^ mask
+}
+function lp_put32(out: []byte, at: int, v: long) -> void {
+  out[at] = int((v >> long(24)) & long(255))
+  out[at + 1] = int((v >> long(16)) & long(255))
+  out[at + 2] = int((v >> long(8)) & long(255))
+  out[at + 3] = int(v & long(255))
+}
+function lp_tag(out: []byte, at: int, tag: string) -> void {
+  for i in 0 .. 4 { out[at + i] = tag[i] }
+}
+# a PPM's header: "P6", width, height, maxval, each after white space; returns the pixel offset
+var lp_w: int = 0
+var lp_h: int = 0
+function lp_ppm_header(d: []byte) -> int {
+  var i = 2
+  var got = 0
+  var vals = new []int
+  while got < 3 and i < len(d) {
+    while i < len(d) and (d[i] == 32 or d[i] == 10 or d[i] == 13 or d[i] == 9) { i += 1 }
+    var v = 0
+    while i < len(d) and d[i] >= 48 and d[i] <= 57 {
+      v = v * 10 + (d[i] - 48)
+      i += 1
+    }
+    push(vals, v)
+    got += 1
+  }
+  lp_w = vals[0]
+  lp_h = vals[1]
+  return i + 1
+}
+# the PPM at `ppm` as a PNG at `png`; the PPM is removed
+export function lab_ppm_to_png(ppm: string, png: string) -> bool {
+  let d = Fs.read_bytes(ppm)
+  if d == null or len(d) < 8 { return false }
+  let px = lp_ppm_header(d)
+  let w = lp_w
+  let h = lp_h
+  let row = w * 3 + 1
+  let raw = row * h
+  let blocks = (raw + 65534) / 65535
+  let idat = 2 + blocks * 5 + raw + 4
+  let total = 8 + 25 + 12 + idat + 12
+  let out = buffer(total)
+  let sig = [137, 80, 78, 71, 13, 10, 26, 10]
+  for i in 0 .. 8 { out[i] = sig[i] }
+  var at = 8
+  lp_put32(out, at, long(13))
+  lp_tag(out, at + 4, "IHDR")
+  lp_put32(out, at + 8, long(w))
+  lp_put32(out, at + 12, long(h))
+  out[at + 16] = 8
+  out[at + 17] = 2
+  out[at + 18] = 0
+  out[at + 19] = 0
+  out[at + 20] = 0
+  lp_put32(out, at + 21, lp_crc(out, at + 4, 17))
+  at += 25
+  lp_put32(out, at, long(idat))
+  lp_tag(out, at + 4, "IDAT")
+  var o = at + 8
+  out[o] = 120
+  out[o + 1] = 1
+  o += 2
+  var a = 1
+  var b = 0
+  var left = raw
+  var k = 0                                # the byte of the raw stream being written
+  while left > 0 {
+    let n = Math.min(left, 65535)
+    left -= n
+    var fin = 0
+    if left == 0 { fin = 1 }
+    out[o] = fin
+    out[o + 1] = n & 255
+    out[o + 2] = (n >> 8) & 255
+    out[o + 3] = (~n) & 255
+    out[o + 4] = ((~n) >> 8) & 255
+    o += 5
+    for j in 0 .. n {
+      let y = k / row
+      let x = k % row
+      var v = 0
+      if x > 0 { v = d[px + y * w * 3 + x - 1] }
+      out[o] = v
+      a = (a + v) % 65521
+      b = (b + a) % 65521
+      o += 1
+      k += 1
+    }
+  }
+  lp_put32(out, o, long(b) * long(65536) + long(a))
+  o += 4
+  lp_put32(out, o, lp_crc(out, at + 4, o - at - 4))
+  o += 4
+  lp_put32(out, o, long(0))
+  lp_tag(out, o + 4, "IEND")
+  lp_put32(out, o + 8, lp_crc(out, o + 4, 4))
+  o += 12
+  if not Fs.write_bytes(png, out, o) { return false }
+  Fs.remove(ppm)
+  return true
+}

packages/ludic.lab/scenes.ludic

@@ -0,0 +1,20 @@
+# scenes.ludic - every scene the lab can show, added by whoever has something to look at:
+#   def LabScenes deer { setup: fn deer_setup, tick: fn deer_tick }
+# setup builds what the scene shows and names its cameras (lab_shot); tick, if any, moves it each
+# frame by the lab's fixed step; draw, if any, draws what is not an actor or a scatter layer.
+export property LabScene {
+  key: string = ""
+  setup: fn() -> void = null
+  tick: fn(float) -> void = null
+  draw: fn() -> void = null
+}
+export open registry LabScenes of LabScene as LAB
+
+export function lab_scene_names() -> string {
+  var s = ""
+  for i in 0 .. LAB_COUNT {
+    if i > 0 { s = s + ", " }
+    s = s + LabScenes[i].key
+  }
+  return s
+}

packages/ludic.lab/shots.ludic

@@ -0,0 +1,35 @@
+# shots.ludic - a scene names its cameras; the loop takes them in order
+function lab_shots_reset() -> void {
+  lb_shot_names = new []string
+  lb_shot_pose = new []float
+}
+# a camera at (x, y, z) looking along yaw / pitch, both in DEGREES (cam_set's units)
+export function lab_shot(name: string, x: float, y: float, z: float, yaw_deg: float, pitch_deg: float) -> void {
+  push(lb_shot_names, name)
+  push(lb_shot_pose, x)
+  push(lb_shot_pose, y)
+  push(lb_shot_pose, z)
+  push(lb_shot_pose, yaw_deg)
+  push(lb_shot_pose, pitch_deg)
+}
+# a camera `dist` metres from the point (tx, ty, tz), from bearing `from_deg` (0 = from +z),
+# `up_deg` above the horizontal, looking at the point
+export function lab_shot_at(name: string, tx: float, ty: float, tz: float, dist: float, from_deg: float, up_deg: float) -> void {
+  let b = Math.deg_to_rad(from_deg)
+  let e = Math.deg_to_rad(up_deg)
+  let hd = dist * Math.cos(e)
+  let cx = tx + Math.sin(b) * hd
+  let cz = tz + Math.cos(b) * hd
+  let cy = ty + dist * Math.sin(e)
+  let yaw = Math.atan2(cx - tx, cz - tz) * (180.0 / PI)
+  lab_shot(name, cx, cy, cz, yaw, -up_deg)
+}
+export function lab_shot_count() -> int {
+  if lb_shot_names == null { return 0 }
+  return len(lb_shot_names)
+}
+function lab_shot_apply(i: int) -> void {
+  if i < 0 or i >= lab_shot_count() { return }
+  let o = i * 5
+  cam_set(lb_shot_pose[o], lb_shot_pose[o + 1], lb_shot_pose[o + 2], lb_shot_pose[o + 3], lb_shot_pose[o + 4])
+}

packages/ludic.lab/state.ludic

@@ -0,0 +1,27 @@
+# state.ludic - which scene, its shots, and where the loop is in them
+var lb_scene: string = ""
+var lb_frame: int = 0
+var lb_shot_names: []string = null
+var lb_shot_pose: []float = null    # 5 per shot: x, y, z, yaw and pitch in degrees
+var lb_shot: int = 0                # the shot being taken or looked at
+var lb_wait: int = 0                # frames held on it so far
+var lb_settle: int = 45             # frames a shot is held before it is taken
+var lb_out: string = ""             # build/lab/<scene>
+var lb_windowed: bool = false
+var lb_note: string = ""            # one line a scene may show under its title
+var lb_font: string = ""            # an overlay font atlas directory; "" draws no captions
+var lb_title: string = "Ludic Lab"
+var lb_draw: fn() = null            # the scene's own drawing, beside the actors
+var lb_shots_taken: int = 0
+
+# frames a shot settles before it is taken (streaming, auto-exposure); 45 by default
+export function lab_settle(frames: int) -> void { lb_settle = Math.max(1, frames) }
+# the overlay's font atlas (a directory with font.json and font.png) for the captions
+export function lab_font(dir: string) -> void { lb_font = dir }
+export function lab_title(title: string) -> void { lb_title = title }
+# one line under the scene's title in a window
+export function lab_note(s: string) -> void { lb_note = s }
+# the scene being shown, and the frame the clock is on (60 a second, whatever the machine)
+export function lab_scene() -> string { return lb_scene }
+export function lab_frame() -> int { return lb_frame }
+export function lab_time() -> float { return float(lb_frame) / 60.0 }

packages/ludic.lab/tests/lab_test.ludic

@@ -0,0 +1,54 @@
+# lab_test.ludic - what the lab computes without a window: the PNG it keeps a shot as, the cameras
+# a scene names, and the scenes a program adds
+import "ludic.lab"
+program LabTest {
+  numbers float
+  friend module lab_test of ludic_lab
+  function nothing() -> void { }
+  def LabScenes one { setup: fn nothing }
+  def LabScenes two { setup: fn nothing }
+
+  function ppm(path: string) -> void {
+    let hdr = "P6\n2 2\n255\n"
+    let b = buffer(len(hdr) + 12)
+    for i in 0 .. len(hdr) { b[i] = hdr[i] }
+    for i in 0 .. 12 { b[len(hdr) + i] = i * 20 }
+    Fs.write_bytes(path, b, len(hdr) + 12)
+  }
+
+  test "a PPM becomes a PNG with its signature, its size and a valid IEND" {
+    let dir = Os.temp_dir()
+    ppm(`{dir}/lab_test.ppm`)
+    expect(lab_ppm_to_png(`{dir}/lab_test.ppm`, `{dir}/lab_test.png`))
+    let p = Fs.read_bytes(`{dir}/lab_test.png`)
+    expect(p != null)
+    expect_eq(p[0], 137)
+    expect_eq(p[1], 80)
+    expect_eq(p[19], 2)                        # IHDR width, low byte
+    expect_eq(p[23], 2)                        # height
+    let n = len(p)
+    # the IEND chunk's CRC is always AE 42 60 82
+    expect_eq(p[n - 4], 174)
+    expect_eq(p[n - 3], 66)
+    expect_eq(p[n - 2], 96)
+    expect_eq(p[n - 1], 130)
+    expect(not Fs.exists(`{dir}/lab_test.ppm`))
+  }
+
+  test "a camera at a point looks back at it" {
+    lab_shots_reset()
+    lab_shot_at("front", 0.0, 1.0, 0.0, 10.0, 0.0, 0.0)
+    lab_shot_at("side", 0.0, 1.0, 0.0, 10.0, 90.0, 30.0)
+    expect_eq(lab_shot_count(), 2)
+    expect_near(lb_shot_pose[2], 10.0, 0.001)           # front: 10 m out along +z
+    expect_near(lb_shot_pose[5 + 0], 8.660, 0.01)       # side: along +x, 30 degrees up
+    expect_near(lb_shot_pose[5 + 1], 6.0, 0.01)
+    expect_near(lb_shot_pose[5 + 4], -30.0, 0.001)
+  }
+
+  test "scenes are what the program added, in its order" {
+    expect_eq(LAB_COUNT, 2)
+    expect(lab_scene_names() == "one, two")
+    expect_eq(labscenes_find("two"), LAB_TWO)
+  }
+}

packages/ludic.render3d/render.ludic

@@ -37,6 +37,13 @@ var r3d_dem_base: float = 0.0
 var r3d_dem_ox: float = 0.0
 var r3d_dem_oz: float = 0.0
 var r3d_ortho_path: string = null
+# A plate: no terrain, no grass, no water - the sky, the sun, the shadows and whatever the scene
+# draws (a lab's stage, ludic.lab). Set before the load; nothing of the landscape is made, so
+# its hundreds of megabytes of height field, materials and grass never exist.
+var r3d_plate: bool = false
+function r3d_plate_mode(on: bool) -> void { r3d_plate = on }
+# the sky's HDR image, when it is not the default photograph under r3d_assets
+var r3d_sky_path: string = null
 var r3d_debug: bool = false
 var r3d_debug_shadow: bool = false
 var r3d_debug_max: bool = false
@@ -123,9 +130,12 @@ function r3d_load_count() -> int { return 4 + TERRAIN_INIT_STEPS }
 function r3d_load_step(i: int) -> bool {
   let t = i - 1
   if i == 0 {
-    if not sky_load(r3d_assets + "/hdri/kloofendal_48d_partly_cloudy_puresky_4k.hdr") { return false }
+    var sky = r3d_assets + "/hdri/kloofendal_48d_partly_cloudy_puresky_4k.hdr"
+    if r3d_sky_path != null { sky = r3d_sky_path }
+    if not sky_load(sky) { return false }
     daylight_init()
   } else if t >= 0 and t < TERRAIN_INIT_STEPS {
+    if r3d_plate { return true }
     if t == 0 {
       if r3d_dem_path != null { terrain_use_dem(r3d_dem_path, r3d_dem_min, r3d_dem_max, r3d_dem_base, r3d_dem_ox, r3d_dem_oz) }
       if r3d_ortho_path != null { terrain_use_ortho(r3d_ortho_path) }
@@ -138,7 +148,7 @@ function r3d_load_step(i: int) -> bool {
     scatter_init()
     actor_init()
   } else if i == 3 + TERRAIN_INIT_STEPS {
-    grass_init()
+    if not r3d_plate { grass_init() }
     r3d_sky_prog = r3d_program("fullscreen.vert", "sky.frag", "")
     # The base is NOON's air, and it was tuned when nothing desaturated with distance - so it
     # was doing its whole job through colour and could not be raised without the valley going
@@ -221,7 +231,7 @@ function r3d_frame(time: float) -> void {
     print(`cam {r3d_test_frame} pos {int(cam_pos[0] * 1000.0)} {int(cam_pos[1] * 1000.0)} {int(cam_pos[2] * 1000.0)} yaw {int(cam_yaw * 1000.0)} pitch {int(cam_pitch * 1000.0)} jitter {int(gsl_jitter_x * 1000000.0)} {int(gsl_jitter_y * 1000000.0)} render {post_w}x{post_h} reset {gsl_reset} evalok {gsl_eval_ok} fresh {gsl_fresh}`)
   }
   # the height-field shadow rebakes as the light moves in steps (daylight), or with the sky yaw when there is no clock
-  if (not day_on and ter_shadow_yaw != sky_yaw) or ter_shadow_gen != day_gen {
+  if not r3d_plate and ((not day_on and ter_shadow_yaw != sky_yaw) or ter_shadow_gen != day_gen) {
     ter_shadow_gen = day_gen
     let t_bk = gl_now_us()
     terrain_bake_shadow()
@@ -249,12 +259,14 @@ function r3d_frame(time: float) -> void {
     sc_prepass = true
   }
   prof_cpu_mark("foliage prepass")
-  prof_begin("terrain sun")
-  terrain_sun_prepare()
-  prof_end()
-  prof_begin("terrain")
-  terrain_draw()
-  prof_end()
+  if not r3d_plate {
+    prof_begin("terrain sun")
+    terrain_sun_prepare()
+    prof_end()
+    prof_begin("terrain")
+    terrain_draw()
+    prof_end()
+  }
   prof_cpu_mark("terrain")
   prof_begin("scene (vegetation)")
   r3d_scene_draw()

packages/ludic.render3d/terrain.ludic

@@ -317,6 +317,7 @@ var ter_h_scale: float = 0.0
 var ter_o_scale: float = 0.0
 
 function terrain_height(x: float, z: float) -> float {
+  if ter_heights == null { return 0.0 }          # a plate (r3d_plate_mode): flat at y = 0
   if ter_h_scale == 0.0 { ter_h_scale = float(TERRAIN_RES) / float(TERRAIN_HALF * 2) }
   let scale = ter_h_scale
   let fx = (x - ter_ox + float(TERRAIN_HALF)) * scale
@@ -342,6 +343,7 @@ function terrain_height_fx(x: fixed, z: fixed) -> fixed { return fixed(terrain_h
 # thousands of placement queries a chunk makes.
 var ter_bw: floats = null
 function terrain_height_smooth(x: float, z: float) -> float {
+  if ter_heights == null { return 0.0 }
   if ter_h_scale == 0.0 { ter_h_scale = float(TERRAIN_RES) / float(TERRAIN_HALF * 2) }
   if ter_bw == null { ter_bw = floats(8) }
   let scale = ter_h_scale