From 5741e42e0ed311e6563858b65da57808479aa4cd Mon Sep 17 00:00:00 2001 From: Lethonium Dev Server <38733902+RalfLeonFasler@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:22:19 +0000 Subject: [PATCH 01/42] docs: Design scenery drawn from open 3D models (#117) The island reads as empty because every tree is the same cone. This sketches the other answer to that: models from packs somebody else modelled, imported into our own flat-shaded vertex format so no texture pipeline or style clash can follow them in. The licence gate comes first and is mechanical. The repository is public and the code is AGPL, so a model here is a model everyone can download; only CC0 may be committed, and make scenery-check refuses any kit that claims otherwise. That matters because Quaternius's pack pages still link CC0 while the site also publishes a newer licence that forbids passing the models on. Part of #117. Co-Authored-By: Claude Opus 5.5 --- ASSETS-LICENSE.md | 25 +++ Makefile | 6 +- client/test/sceneryCheck.test.js | 95 ++++++++++ .../2026-11-16-scenery-from-open-models.md | 164 ++++++++++++++++++ ...6-11-16-scenery-from-open-models-design.md | 101 +++++++++++ tools/scenery/check.mjs | 94 ++++++++++ 6 files changed, 484 insertions(+), 1 deletion(-) create mode 100644 client/test/sceneryCheck.test.js create mode 100644 docs/superpowers/plans/2026-11-16-scenery-from-open-models.md create mode 100644 docs/superpowers/specs/2026-11-16-scenery-from-open-models-design.md create mode 100644 tools/scenery/check.mjs diff --git a/ASSETS-LICENSE.md b/ASSETS-LICENSE.md index 4a4c28d2..ee5304ac 100644 --- a/ASSETS-LICENSE.md +++ b/ASSETS-LICENSE.md @@ -25,6 +25,31 @@ long as you: link to this repository, and say if you changed it; - **share alike**: publish your changed versions under CC BY-SA 4.0 too. +## Scenery models + +The 3D models under `client/public/assets/scenery/` are not the contributors' +work. They are imported from free packs and keep the licence they came with: +**CC0 1.0** in every case, so they impose nothing on anyone using, changing or +redistributing them. + +| Kit | Source | Licence | +| --- | --- | --- | +| `nature` | [Ultimate Nature](https://quaternius.com/packs/ultimatenature.html) by Quaternius | CC0 1.0 | +| `buildings` | [Buildings](https://quaternius.com/packs/buildings.html) by Quaternius | CC0 1.0 | +| `farm` | [Farm Buildings](https://quaternius.com/packs/farmbuildings.html) and Farm Animals by Quaternius | CC0 1.0 | +| `racing` | [Racing Kit](https://kenney.nl/assets/racing-kit) by Kenney | CC0 1.0 | + +Each kit's `manifest.json` records the pack URL, the licence URL and the date +the models were taken, and `make scenery-check` fails if a kit claims +anything other than CC0. + +**CC0 only, and this is checked, not trusted.** Quaternius also publishes a +newer *Quaternius Asset License*, which forbids redistributing the models. +Their pack pages still link CC0, and CC0 cannot be withdrawn, so the packs +above stay free to redistribute. A pack that shows the other licence is not +imported, however good it looks: this repository is public, so a model here is +a model everyone can download. + ## Name and logo The licence covers the copyright in the files, not the **OpenRadlr name or diff --git a/Makefile b/Makefile index 6aa46bbd..94673193 100644 --- a/Makefile +++ b/Makefile @@ -181,7 +181,11 @@ secrets-baseline: ## Rebuild .secrets.baseline after reviewing the new findings uvx --from detect-secrets==1.5.0 detect-secrets scan --baseline .secrets.baseline .PHONY: check -check: lint test ## Everything CI runs +check: lint test scenery-check ## Everything CI runs + +.PHONY: scenery-check +scenery-check: ## Refuse scenery models that are not CC0 (see ASSETS-LICENSE.md) + $(NODE) tools/scenery/check.mjs .PHONY: routes routes: ## Regenerate the bundled map's road network and routes (tools/valley-map.mjs) diff --git a/client/test/sceneryCheck.test.js b/client/test/sceneryCheck.test.js new file mode 100644 index 00000000..96405ebd --- /dev/null +++ b/client/test/sceneryCheck.test.js @@ -0,0 +1,95 @@ +/** + * The licence gate for imported scenery kits (#117). + * + * These tests guard a legal boundary, not a feature: the repository is public, + * so a model committed here is a model everybody can download. Only CC0 packs + * may be, and a pack that claims anything else must not get past the gate. + */ +import assert from "node:assert/strict"; +import { mkdirSync, mkdtempSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; +import { ALLOWED_LICENCE, checkKits, manifestProblems } from "../../tools/scenery/check.mjs"; + +const provenance = Object.freeze({ + pack: "https://quaternius.com/packs/ultimatenature.html", + licence: "https://creativecommons.org/publicdomain/zero/1.0/", + taken: "2026-11-16", +}); +const kit = (overrides = {}) => ({ licence: ALLOWED_LICENCE, provenance, models: { tree: {} }, ...overrides }); + +/** A kits directory holding one kit with `manifest` (as text when given a string). */ +function kitsDir(name, manifest) { + const root = mkdtempSync(join(tmpdir(), "scenery-")); + const dir = join(root, "client/public/assets/scenery", name); + mkdirSync(dir, { recursive: true }); + writeFileSync(join(dir, "manifest.json"), typeof manifest === "string" ? manifest : JSON.stringify(manifest)); + return root; +} + +test("a CC0 kit with provenance may be committed", () => { + assert.deepEqual(manifestProblems("nature", kit()), []); +}); + +test("a kit under any other licence is refused, and says which", () => { + const problems = manifestProblems("farm", kit({ licence: "Quaternius-Asset-License-1.0" })); + assert.equal(problems.length, 1); + assert.match(problems[0], /farm/); + assert.match(problems[0], /Quaternius-Asset-License-1\.0/); + assert.match(problems[0], /CC0-1\.0/); +}); + +test("a kit with no licence at all is refused", () => { + assert.match(manifestProblems("x", kit({ licence: undefined }))[0], /licence/); +}); + +test("a kit with no provenance is refused", () => { + assert.match(manifestProblems("x", kit({ provenance: undefined }))[0], /provenance/); +}); + +test("provenance without a source URL is refused", () => { + const problems = manifestProblems("x", kit({ provenance: { ...provenance, pack: "Ultimate Nature" } })); + assert.match(problems[0], /not a URL/); +}); + +test("provenance without a date is refused, so the licence can be checked again", () => { + const problems = manifestProblems("x", kit({ provenance: { ...provenance, taken: "" } })); + assert.match(problems[0], /taken/); +}); + +test("a kit with no models is refused", () => { + assert.match(manifestProblems("x", kit({ models: {} }))[0], /no models/); +}); + +test("a directory with no kits passes, so the target works before the first import", () => { + assert.deepEqual(checkKits("client/public/assets/scenery", { root: mkdtempSync(join(tmpdir(), "empty-")) }), { kits: [], problems: [] }); +}); + +test("the committed kits are read with their model count", () => { + const root = kitsDir("nature", kit({ models: { oak: {}, fir: {} } })); + assert.deepEqual(checkKits("client/public/assets/scenery", { root }), { + kits: [{ name: "nature", models: 2, licence: ALLOWED_LICENCE }], + problems: [], + }); +}); + +test("a kit that is not CC0 never reaches the good list", () => { + const root = kitsDir("farm", kit({ licence: "OGA-BY-3.0" })); + const { kits, problems } = checkKits("client/public/assets/scenery", { root }); + assert.deepEqual(kits, []); + assert.equal(problems.length, 1); +}); + +test("a manifest that is not JSON is reported rather than crashing", () => { + const root = kitsDir("broken", "{ nope"); + const { problems } = checkKits("client/public/assets/scenery", { root }); + assert.match(problems[0], /broken: manifest is not valid JSON/); +}); + +test("a kit directory without a manifest is reported", () => { + const root = mkdtempSync(join(tmpdir(), "scenery-")); + mkdirSync(join(root, "client/public/assets/scenery/stray"), { recursive: true }); + const { problems } = checkKits("client/public/assets/scenery", { root }); + assert.match(problems[0], /stray: no manifest/); +}); diff --git a/docs/superpowers/plans/2026-11-16-scenery-from-open-models.md b/docs/superpowers/plans/2026-11-16-scenery-from-open-models.md new file mode 100644 index 00000000..1133fa84 --- /dev/null +++ b/docs/superpowers/plans/2026-11-16-scenery-from-open-models.md @@ -0,0 +1,164 @@ +# Scenery from open models — implementation plan + +> **For agentic workers:** work task by task; tests first, every commit passes +> CHECK. This is a spike (#117): the goal is a branch to look at, not a merge. + +**Goal:** Draw the island with CC0 low-poly models instead of procedural +cones, so a fuller, less repetitive world can be judged by eye and by frame +rate. + +**Architecture:** Models are imported offline into +`client/public/assets/scenery/` as flat-shaded vertex-coloured `.geo.json` +plus a manifest. `view3d/scenery/` turns those into `MeshBuilder`s and a +`flora` that `buildScenery` can draw from; placement, occupancy, determinism +and the chunk group stay exactly as they are. + +**Spec:** `docs/superpowers/specs/2026-11-16-scenery-from-open-models-design.md` + +**Commands** (no usable Node on the host; mount the whole repo — the tests +read `routes/` from the repo root): + +```sh +# One test file +docker run --rm -v "$PWD":/w -w /w/client node:22-alpine node --test test/.test.js +# CHECK: lint and every client test +docker run --rm -v "$PWD":/w -w /w/client node:22-alpine sh -c 'npm run lint && npm test' +``` + +## Global constraints + +- CC0 only. Every kit manifest declares `licence: "CC0-1.0"` and provenance; + `make scenery-check` fails otherwise. +- With scenery off, `buildWorld` output is unchanged and every test passes as + today (1,605 client tests at the base commit `d4757e2`). +- Deterministic: kit choice, yaw and scale come from the seeded `random` + `buildScenery` already passes; no `Math.random`, `Date` or I/O in + `view3d/scenery/`. +- Placement rules are untouched: no scenery on roads, verges, rivers, in the + sea or on the beach, and nothing inside the occupancy grid. +- UI text only through `i18n/en.js` and `de.js` (ADR 0017). +- `openradlr.scenery` is `"off" | "sparse" | "normal" | "dense"`, default + `"off"`. `openradlr.showFps` is `"on" | "off"`, default `"off"`. +- Commits reference `#117`. + +--- + +## File structure + +| File | Responsibility | +| --- | --- | +| `tools/scenery/import.mjs` | GLB/OBJ → `.geo.json` + manifest; strip UVs, bake face colours | +| `tools/scenery/check.mjs` | Licence gate over every committed manifest | +| `client/public/assets/scenery//` | Committed CC0 output | +| `client/public/js/view3d/scenery/models.js` | Manifest → meshes, LOD pick | +| `client/public/js/view3d/scenery/kits.js` | Load and index manifests | +| `client/public/js/view3d/scenery/palette.js` | Role → biome colour (identity now) | +| `client/public/js/view3d/scenery/plan.js` | `floraFor(kit, random)` — a `buildScenery` flora | +| `client/public/js/view/fpsMeter.js` | Rolling mean and 1% low (pure) | +| `client/test/sceneryFixture.js` | Tiny kit for tests | +| `client/test/scenery*.test.js`, `client/test/fpsMeter.test.js` | Tests | + +Modified: `view3d/world.js` (`buildScenery` `flora` option), `worldScene.js`, +`worldWorker.js`, `main.js`, `index.html`, `styles.css`, `i18n/en.js`, +`i18n/de.js`, `view/viewPopover.js`, `Makefile`, `ASSETS-LICENSE.md`. + +--- + +### Task 1: Licence record and the gate + +- [x] Spec and plan in `docs/superpowers/`. +- [ ] `ASSETS-LICENSE.md`: a "Scenery models" section — CC0 only, the kit + table with pack URLs, and the rule that a pack showing QAL is skipped. +- [ ] `tools/scenery/check.mjs`: exits non-zero if a manifest under + `client/public/assets/scenery/` is missing `licence: "CC0-1.0"` or a + `provenance` block; exits zero on an empty directory (no kits yet). +- [ ] `make scenery-check`, wired into `make check`. + +### Task 2: The importer + +**Files:** `tools/scenery/import.mjs`, `tools/scenery/import.test.mjs`, +`tools/scenery/fixtures/` (a self-made two-triangle GLB and its colour map). + +- [ ] **Failing test:** import the fixture. Expect 6 vertices, no + `TEXCOORD_0`, per-face colours equal to the sampled texels, normals from + winding, bounds from positions, origin moved to the base centre. +- [ ] **Failing test:** a manifest declaring a non-CC0 licence makes the gate + exit non-zero; `CC0-1.0` with provenance passes. +- [ ] Implement GLB parse (JSON + BIN chunks), colour-at-centroid sampling, + and the OBJ/MTL path for the untextured Quaternius packs. +- [ ] Quantise positions to 2 decimals; drop normals (recomputed on load from + winding, as `MeshBuilder.triangle` already does). + +### Task 3: Models and kits + +**Files:** `view3d/scenery/{models,kits,palette,plan}.js`, +`client/test/sceneryFixture.js`, `sceneryModels.test.js`, +`sceneryPlan.test.js`. + +- [ ] **Failing test (models):** a `.geo.json` becomes a `MeshBuilder` with + one vertex per triangle corner; `pickLod(model, distance, nearRange)` + returns the `far` variant beyond `nearRange`, `near` within it. +- [ ] **Failing test (kits):** a manifest indexes models by name and role; an + unknown name throws with kit and model in the message; a manifest that + is not CC0 throws. +- [ ] **Failing test (palette):** a known role takes the biome colour; an + unknown role keeps the source colour. +- [ ] **Failing test (plan):** `floraFor(kit, random)` draws deterministically + from the seeded random, sets instances at the given `x, y, z`, and never + picks a model whose role the kit marks as water-only on land. +- [ ] Implement the four modules. + +### Task 4: Into the scenery build + +**Files:** `view3d/world.js`, `worldScene.js`, `worldWorker.js`; +`client/test/sceneryWorld.test.js`. + +- [ ] **Failing test:** `buildScenery(route, terrain, bounds, { flora })` + calls `flora.tree` instead of `biome.flora.tree` and leaves the placed + positions identical for the same seed. +- [ ] **Failing test:** `buildWorld(route)` (no scenery) gives the same + vertex counts per group as before; `buildWorld(route, { scenery, kits })` + grows only the `scenery` group. +- [ ] **Failing test:** `buildSceneNow` carries the scenery option and its kit + meshes through `sceneOf` and the transfer list. +- [ ] Wire `scenery` through the worker message beside `biome`. + +### Task 5: The setting + +**Files:** `main.js`, `index.html`, `view/viewPopover.js`, `i18n/en.js`, +`i18n/de.js`; `client/test/scenerySetting.test.js`. + +- [ ] **Failing test:** saved value → resolved level; garbage or missing → + `"off"`; `?scenery=` wins without saving. +- [ ] A "Scenery" row in the View popover (Off / Sparse / Normal / Dense), + rebuilding the world on change the way a biome change already does. + +### Task 6: FPS read-out + +**Files:** `client/public/js/view/fpsMeter.js`, `client/test/fpsMeter.test.js`, +`main.js`, `index.html`, `styles.css`, settings drawer, `i18n/*`. + +- [ ] **Failing test:** the meter reports the mean over its window; the 1% + low is the mean of the slowest 1%; fewer than a window of frames reports + nothing yet; one very long frame (tab restore) resets rather than skews. +- [ ] `#hud-fps` beside `.hud-status`, 3D view only, toggled in settings, + written at 2 Hz. + +### Task 7: See it + +- [ ] Screenshots at the same camera, scenery off / sparse / dense, plus a + drone shot. +- [ ] Frame timings from the read-out on real hardware; numbers go in the PR + body. +- [ ] Draft PR referencing #117. + +--- + +## Review focus + +- A pack that is not CC0 never reaches the repo (Task 1). +- Scenery off changes nothing: same vertex counts, same world (Task 4). +- A season the palette does not know keeps the model's own colours (Task 3). +- Placement is identical to today's for the same seed when the same stands + are picked, so a bug shows up as a moved tree, not a mystery (Task 4). +- The FPS read-out never writes to the DOM more than twice a second (Task 6). diff --git a/docs/superpowers/specs/2026-11-16-scenery-from-open-models-design.md b/docs/superpowers/specs/2026-11-16-scenery-from-open-models-design.md new file mode 100644 index 00000000..d63db0d0 --- /dev/null +++ b/docs/superpowers/specs/2026-11-16-scenery-from-open-models-design.md @@ -0,0 +1,101 @@ +# Scenery from open models — design + +Date: 2026-11-16 · Status: draft (spike, #117) + +## Context + +The island reads as empty. `buildScenery` (`world.js:747`) places up to +1,100 trees per route, but every one is drawn by `plantTree` +(`biomes/temperate.js:127`) from cones and ellipsoids: one fir repeated, one +round crown repeated. Numbers do not fix it — the silhouette is the same +everywhere, so a fuller wood still reads as noise. + +The Living draft (#48) attacked this procedurally from the ground up and the +result was still thin. This spike tries the other way: models that were +modelled with an eye for silhouette, taken from openly licensed packs. + +It is a spike. The aim is a branch to look at, and frame numbers to argue +with, not a merge. + +## Licence boundary + +Only **CC0** models enter the repository. The repo is public and `LICENSE` is +AGPL, so everything under `client/public/` has to be redistributable; CC0 is a +public-domain dedication and asks nothing back. + +Conditional licences are out, including Quaternius's newer **Quaternius Asset +License v1.0**, whose §3(a) forbids redistributing the assets "regardless of +how much they have been modified". Their CC0-era packs predate it, and QAL §7 +says it does not apply retroactively, so those stay CC0. **A pack is taken +only if its page links CC0.** If it shows QAL, the pack is skipped, not argued +about. + +Accepted, all CC0: + +| Kit | Pack | Why | +| --- | --- | --- | +| `nature` | Quaternius Ultimate Nature (150 models, untextured) | trees, shrubs, rocks, deadwood — the emptiness | +| `buildings` | Quaternius Buildings (untextured) | European townhouses for the villages | +| `farm` | Quaternius Farm Buildings + Farm Animals (untextured) | barns, silos, windmills, animals | +| `racing` | Kenney Racing Kit (textured) | race-day barriers, tents, signage | + +Rejected: Quaternius Simple Buildings (textured, flat-roof suburban), Kenney +City Kits (pale grey, clashes), Kenney Mini (too pastel). + +`make scenery-check` enforces this: every kit manifest must declare +`licence: "CC0-1.0"` with provenance (pack URL, licence URL, download date). + +## The renderer constraint + +`renderer.js:12-32` draws one vertex format: `a_position`, `a_normal`, +`a_color`, flat shaded, no textures on meshes. So models are converted to +that format offline: + +- **Quaternius** packs are untextured; colours come from the material. +- **Kenney** GLB carries `TEXCOORD_0` and a `colormap`; the importer samples + the colour map at each triangle's centroid. + +Either way the browser never sees a texture, a UV or a material — just +geometry in our own format, which is why the result cannot clash the way a +bolted-on kit would. + +## Decision + +**Models are data, imported offline, chosen by kit manifests, placed by the +existing scenery code.** + +``` +client/public/assets/scenery//manifest.json + .geo.json +client/public/js/view3d/scenery/{kits,models,palette,plan}.js +tools/scenery/{import.mjs, check.mjs} +``` + +- `world.js` keeps its placement. `buildScenery` gains an optional `flora` + that draws from a kit instead of `biome.flora.tree`, so every existing rule + (forests near the road, occupancy, no trees in the sea or on the beach, + determinism from the route seed) applies unchanged. +- Placement stays one instance per pick; the kit picks a model, a yaw and a + scale from the seeded random. +- **LOD:** each model may carry a `far` variant; the kit draws `near` within + `nearRange` of the camera and `far` beyond. That is where fullness comes + from — cheap silhouettes fill the horizon, detail only close up. +- **Seasons:** `palette.js` maps a model's material *role* (`bark`, + `foliage`, `foliage-fir`, `structure`, `roof`, `stone`) to the active + biome's colours. This spike ships identity mapping: every season keeps the + model's own colours, and a role the biome does not know keeps the source + colour. Wiring season colours in is a follow-up. +- **FPS read-out:** optional, in settings, off by default. A pure meter + reports the mean and the 1% low frame time, written twice a second. + +## Consequences + +- The world stops being purely generated code. `ASSETS-LICENSE.md` gains a + section for `client/public/assets/scenery/`, listing each kit's source and + licence, and the rule that a kit without a CC0 manifest is not imported. +- Scenery is off by default (`openradlr.scenery`), so every existing ride, + screenshot and test is unchanged until someone asks for it. +- The models are fixed artwork: a tree cannot be re-shaped by a biome the way + `plantTree` can. Season colour is the only lever until the palette is wired. +- Bundle size grows by the imported kits; the importer quantises positions + and strips normals where they can be recomputed from winding. +- Bike and rider stay procedural: the kits have nothing like them. diff --git a/tools/scenery/check.mjs b/tools/scenery/check.mjs new file mode 100644 index 00000000..2346d6be --- /dev/null +++ b/tools/scenery/check.mjs @@ -0,0 +1,94 @@ +#!/usr/bin/env node +/** + * The licence gate for imported scenery models (#117). + * + * The repository is public and the code is AGPL, so every model file under + * `client/public/assets/scenery/` has to be redistributable. That rules out + * anything conditional — including Quaternius's newer "Quaternius Asset + * License", which forbids passing the models on "regardless of how much they + * have been modified". Their CC0-era packs are fine; the newer ones are not. + * + * So each kit's `manifest.json` must say, in plain words, what it is and where + * it came from. This refuses anything else, which means a pack that is not CC0 + * cannot be committed by accident. + * + * node tools/scenery/check.mjs check the committed kits + * node tools/scenery/check.mjs --list say what was found, always exit 0 + */ +import { existsSync, readdirSync, readFileSync } from "node:fs"; +import { join } from "node:path"; + +/** The only licence a kit here may claim. */ +export const ALLOWED_LICENCE = "CC0-1.0"; + +/** Where the kits live, relative to the repository root. */ +export const KITS_DIR = "client/public/assets/scenery"; + +/** + * What is wrong with this kit manifest, in the rider's terms, or `[]` when it + * may be committed. `kit` is only used to name the problem. + */ +export function manifestProblems(kit, manifest) { + if (!manifest || typeof manifest !== "object") return [`${kit}: manifest is not an object`]; + const problems = []; + if (manifest.licence !== ALLOWED_LICENCE) { + problems.push(`${kit}: licence is ${JSON.stringify(manifest.licence)}, only "${ALLOWED_LICENCE}" may be committed`); + } + const provenance = manifest.provenance; + if (!provenance || typeof provenance !== "object") { + problems.push(`${kit}: no provenance, so nobody can tell where the models came from`); + } else { + // Where it came from, which licence that was, and when it was taken: the + // three things needed to check the licence again later or download it again. + for (const field of ["pack", "licence", "taken"]) { + if (typeof provenance[field] !== "string" || provenance[field].trim() === "") { + problems.push(`${kit}: provenance has no ${field}`); + } + } + if (typeof provenance.pack === "string" && !/^https?:\/\//.test(provenance.pack)) { + problems.push(`${kit}: provenance.pack is not a URL (${provenance.pack})`); + } + } + if (!manifest.models || typeof manifest.models !== "object" || Object.keys(manifest.models).length === 0) { + problems.push(`${kit}: no models`); + } + return problems; +} + +/** Every kit directory under `kitsDir` that has a manifest, and every problem found. */ +export function checkKits(kitsDir, { root = "." } = {}) { + const dir = join(root, kitsDir); + if (!existsSync(dir)) return { kits: [], problems: [] }; + const kits = []; + const problems = []; + for (const kit of readdirSync(dir, { withFileTypes: true })) { + if (!kit.isDirectory()) continue; + const file = join(dir, kit.name, "manifest.json"); + if (!existsSync(file)) { + problems.push(`${kit.name}: no manifest.json`); + continue; + } + let manifest; + try { + manifest = JSON.parse(readFileSync(file, "utf8")); + } catch (error) { + problems.push(`${kit.name}: manifest is not valid JSON (${error.message})`); + continue; + } + const found = manifestProblems(kit.name, manifest); + problems.push(...found); + if (found.length === 0) kits.push({ name: kit.name, models: Object.keys(manifest.models).length, licence: manifest.licence }); + } + return { kits, problems }; +} + +// The command line: print what was found, and refuse a kit that may not be +// committed. Runs from the repository root, the way make calls it. +if (import.meta.url === `file://${process.argv[1]}`) { + const list = process.argv.includes("--list"); + const { kits, problems } = checkKits(KITS_DIR); + for (const kit of kits) console.log(`${kit.name}: ${kit.models} models, ${kit.licence}`); + if (kits.length === 0) console.log("No scenery kits imported yet."); + for (const problem of problems) console.error(problem); + if (problems.length > 0 && !list) process.exit(1); +} From a2f73a390e7b0e5de4bd518a989f9ce6b1545389 Mon Sep 17 00:00:00 2001 From: Lethonium Dev Server <38733902+RalfLeonFasler@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:32:53 +0000 Subject: [PATCH 02/42] feat: Import open 3D models as our own flat-shaded geometry (#117) The island's trees are all the same cone because they are all the same code. Importing models somebody else modelled needs a bridge to what the renderer draws, which is one vertex format: a position, a face normal and a colour, with no textures and no UVs. So the importer does that conversion offline. It strips UVs and tangents, gives each triangle the colour of the pack's colour map under its centroid, re-origins the model to stand on its base, and quantises to centimetres. What lands in the repository is geometry in our own format, so no texture pipeline or style seam comes with it. Two bugs from importing real Kenney files, both found by running it on them rather than on the fixture: their colour map is a separate file rather than embedded, and their UVs read the same way round as the decoded rows. Missing either turned a whole kit black or white in silence, so both now have tests, one of them against a swatch atlas that collapses to a single colour if the rows are read wrong. Part of #117. Co-Authored-By: Claude Opus 5.5 --- client/test/sceneryImport.test.js | 242 +++++++++++++++++++++ tools/scenery/fixtures/quad.glb | Bin 0 -> 1240 bytes tools/scenery/import.mjs | 338 ++++++++++++++++++++++++++++++ tools/scenery/make-fixture.mjs | 123 +++++++++++ 4 files changed, 703 insertions(+) create mode 100644 client/test/sceneryImport.test.js create mode 100644 tools/scenery/fixtures/quad.glb create mode 100644 tools/scenery/import.mjs create mode 100644 tools/scenery/make-fixture.mjs diff --git a/client/test/sceneryImport.test.js b/client/test/sceneryImport.test.js new file mode 100644 index 00000000..63e44ca1 --- /dev/null +++ b/client/test/sceneryImport.test.js @@ -0,0 +1,242 @@ +/** + * The scenery importer (#117): turns a model somebody else made into the one + * thing our renderer draws — flat-shaded triangles with a colour per face. + * + * The renderer has no textures and no UVs (`renderer.js`), so the importer is + * where a pack's look becomes ours: UVs are dropped, and each triangle takes + * the colour of the colour map under its centroid. What comes out is geometry + * in the project's own format, not a model dropped in beside it. + */ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import test from "node:test"; +import { fileURLToPath } from "node:url"; +import { deflateSync } from "node:zlib"; +import { importGlb, importObj, primitiveOf } from "../../tools/scenery/import.mjs"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const QUAD = readFileSync(join(HERE, "../../tools/scenery/fixtures/quad.glb")); +const SWATCHES = [ + [1, 0, 0], + [0, 1, 0], + [0, 0, 1], + [1, 1, 1], +]; +const QUAD_WITH_ATLAS = glbWithAtlas(); + +/** + * A GLB whose faces each sit in a different corner of a 2 × 2 swatch atlas, + * the shape of a real pack's colour map. + */ +function glbWithAtlas() { + const { glb } = buildGlb({ + positions: [-4, 0, 0, -2, 0, 0, -2, 2, 0, -2, 0, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 2, 0, 0, 2, 2, 0, 2, 0, 0, 4, 0, 0, 4, 2, 0], + uvs: [0.1, 0.1, 0.4, 0.1, 0.4, 0.4, 0.6, 0.1, 0.9, 0.1, 0.9, 0.4, 0.6, 0.6, 0.9, 0.6, 0.9, 0.9, 0.1, 0.6, 0.4, 0.6, 0.4, 0.9], + pixels: SWATCHES, + }); + return glb; +} + +/** + * Packs a set of attributes and a swatch grid into a GLB. Written here rather + * than reusing the fixture writer so a test can describe exactly the model it + * needs; the fixture the importer is tested on is the committed `quad.glb`. + */ +function buildGlb({ positions, uvs, pixels, image }) { + const pos = new Float32Array(positions); + const uv = new Float32Array(uvs); + const normals = new Float32Array(positions.length).map((_, i) => (i % 3 === 2 ? 1 : 0)); + const width = 2; + const height = 2; + const rgba = Uint8Array.from(pixels.flatMap(([r, g, b]) => [r * 255, g * 255, b * 255, 255])); + const png = pngOf(rgba, width, height); + const chunks = [Buffer.from(pos.buffer), Buffer.from(normals.buffer), Buffer.from(uv.buffer), png]; + const views = []; + let offset = 0; + for (const chunk of chunks) { + views.push({ buffer: 0, byteOffset: offset, byteLength: chunk.length }); + offset += chunk.length; + } + const bin = Buffer.concat([...chunks, Buffer.alloc((4 - (offset % 4)) % 4)]); + const json = { + asset: { version: "2.0" }, + scene: 0, + scenes: [{ nodes: [0] }], + nodes: [{ mesh: 0, name: "swatches" }], + meshes: [{ primitives: [{ attributes: { POSITION: 0, NORMAL: 1, TEXCOORD_0: 2 }, material: 0 }] }], + materials: [{ pbrMetallicRoughness: { baseColorTexture: { index: 0 } } }], + textures: [{ source: 0 }], + images: [image ? { ...image, name: "colormap" } : { bufferView: 3, mimeType: "image/png" }], + accessors: [ + { bufferView: 0, componentType: 5126, count: pos.length / 3, type: "VEC3" }, + { bufferView: 1, componentType: 5126, count: normals.length / 3, type: "VEC3" }, + { bufferView: 2, componentType: 5126, count: uv.length / 2, type: "VEC2" }, + ], + bufferViews: views, + buffers: [{ byteLength: bin.length }], + }; + const text = Buffer.from(JSON.stringify(json), "utf8"); + const padded = Buffer.concat([text, Buffer.alloc((4 - (text.length % 4)) % 4, 0x20)]); + const header = Buffer.alloc(12); + header.writeUInt32LE(0x46546c67, 0); + header.writeUInt32LE(2, 4); + header.writeUInt32LE(12 + 8 + padded.length + 8 + bin.length, 8); + const jsonHead = Buffer.alloc(8); + jsonHead.writeUInt32LE(padded.length, 0); + jsonHead.writeUInt32LE(0x4e4f534a, 4); + const binHead = Buffer.alloc(8); + binHead.writeUInt32LE(bin.length, 0); + binHead.writeUInt32LE(0x004e4942, 4); + return { glb: Buffer.concat([header, jsonHead, padded, binHead, bin]) }; +} + +function pngOf(rgba, width, height) { + const stride = width * 4; + const raw = Buffer.alloc((stride + 1) * height); + for (let y = 0; y < height; y += 1) { + raw[y * (stride + 1)] = 0; + Buffer.from(rgba.buffer, rgba.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1); + } + const chunk = (type, data) => { + const len = Buffer.alloc(4); + len.writeUInt32BE(data.length, 0); + const body = Buffer.concat([Buffer.from(type, "ascii"), data]); + const crc = Buffer.alloc(4); + crc.writeUInt32BE(crc32(body), 0); + return Buffer.concat([len, body, crc]); + }; + const ihdr = Buffer.alloc(13); + ihdr.writeUInt32BE(width, 0); + ihdr.writeUInt32BE(height, 4); + ihdr[8] = 8; + ihdr[9] = 6; + return Buffer.concat([ + Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), + chunk("IHDR", ihdr), + chunk("IDAT", deflateSync(raw)), + chunk("IEND", Buffer.alloc(0)), + ]); +} + +function crc32(buf) { + let c = 0xffffffff; + for (const byte of buf) { + c ^= byte; + for (let k = 0; k < 8; k += 1) c = c & 1 ? (c >>> 1) ^ 0xedb88320 : c >>> 1; + } + return (c ^ 0xffffffff) >>> 0; +} + +test("a GLB becomes triangles with a colour per face, and no UVs", () => { + const model = importGlb(QUAD); + assert.equal(model.name, "quad"); + // Two triangles, three corners each: the renderer wants them unshared. + assert.equal(model.triangles.length, 6); + const uvs = JSON.stringify(model.triangles); + assert.doesNotMatch(uvs, /uv|TEXCOORD/, "UVs must not survive the import"); +}); + +test("each face takes one colour, read from the map under its centroid", () => { + const { triangles } = importGlb(QUAD); + const colour = (face) => triangles.slice(face * 3, face * 3 + 3).map(([, , , r, g, b]) => `${r},${g},${b}`); + // Every corner of a face shares that face's colour: that is what flat shading means. + for (const face of [0, 1]) assert.equal(new Set(colour(face)).size, 1, `face ${face} has one colour`); + // The fixture splits down the middle: the left face sits on the top-left + // texel (red), the right face on the bottom-right one (white). Reading v the + // wrong way round, or the wrong half, changes both. + const [left, right] = [colour(0)[0], colour(1)[0]]; + assert.equal(left, "1,0,0", "the left face took the red texel"); + assert.equal(right, "1,1,1", "the right face took the white texel"); +}); + +test("the origin moves to the base centre, so a model stands where it is placed", () => { + const model = importGlb(QUAD); + // The fixture spans x −2..0 and y 0..4, so after centring its footprint it + // stands on y = 0 with its middle at x = 0: where a placement puts it. + assert.deepEqual(model.bounds.min.map(Math.round), [-1, 0, 0]); + assert.deepEqual(model.bounds.max.map(Math.round), [1, 4, 0]); + const xs = model.triangles.map(([x]) => x); + assert.equal(Math.min(...xs), -1); + assert.equal(Math.max(...xs), 1); + assert.equal(Math.min(...model.triangles.map(([, y]) => y)), 0, "the base sits on the ground"); +}); + +test("flipping the winding reverses the triangles without moving them", () => { + const normal = importGlb(QUAD); + const flipped = importGlb(QUAD, { flip: true }); + // Same corners, opposite order: the faces now look the other way, ready for + // packs whose models are wound the other way round. + assert.deepEqual(flipped.triangles[0], normal.triangles[2]); + assert.deepEqual(flipped.triangles[2], normal.triangles[0]); + assert.deepEqual(flipped.bounds, normal.bounds); +}); + +test("a texture kept in a separate file is read from beside the model", () => { + // Kenney keeps its colour map in a PNG next to the GLB rather than inside it. + // The importer must accept that, and must fail loudly when the file is + // missing: a whole kit silently imported white is the worst outcome. + const glb = glbWithAtlasWithImage({ uri: "Textures/colormap.png" }); + assert.throws(() => importGlb(glb, { baseDir: join(HERE, "no-such-folder") }), /colormap\.png|ENOENT/); +}); + +/** The swatch model, but with its image pointed at rather than embedded. */ +function glbWithAtlasWithImage(image) { + const { glb } = buildGlb({ + positions: [-1, 0, 0, 1, 0, 0, 0, 2, 0], + uvs: [0.1, 0.1, 0.4, 0.1, 0.4, 0.4], + pixels: SWATCHES, + image, + }); + return glb; +} + +test("a textured face reports the texel it read, so a wrong colour map is visible", () => { + const model = importGlb(QUAD); + assert.equal(model.textured, true); +}); + +test("an untextured OBJ takes its colours from the material", () => { + const obj = ["mtllib tree.mtl", "usemtl bark", "v -1 0 0", "v 1 0 0", "v 0 3 0", "f 1 2 3"].join("\n"); + const mtl = ["newmtl bark", "Kd 0.38 0.27 0.18"].join("\n"); + const model = importObj(obj, { name: "tree", mtl }); + assert.equal(model.triangles.length, 3); + assert.deepEqual(model.triangles[0].slice(3), [0.38, 0.27, 0.18]); + assert.equal(model.textured, false); +}); + +test("an untextured model keeps its own scale, with the origin at the base", () => { + const obj = ["v -2 0 0", "v 2 0 0", "v 0 6 0", "f 1 2 3"].join("\n"); + const model = importObj(obj, { name: "pine" }); + const ys = model.triangles.map(([, y]) => y); + assert.equal(Math.min(...ys), 0, "the base sits on y = 0"); + assert.equal(Math.max(...ys), 6); +}); + +test("positions are quantised, so a kit stays small in the repository", () => { + const obj = ["v 0.123456789 0 0", "v 1.987654321 0 0", "v 0 2.111111111 0", "f 1 2 3"].join("\n"); + const model = importObj(obj, { name: "small" }); + for (const corner of model.triangles) { + for (const value of corner.slice(0, 3)) { + assert.equal(value, Math.round(value * 100) / 100); + } + } +}); + +test("a GLB with no triangles is refused with its name", () => { + const empty = { asset: { version: "2.0" }, meshes: [] }; + assert.throws(() => primitiveOf(empty), /no triangles|no geometry/i); +}); + +test("a swatch atlas gives a model many colours, not one", () => { + // Kenney's colour map is a grid of flat swatches, so a model that reads it + // correctly picks up several. Reading the wrong rows — the black band above + // the swatches — collapses a whole kit to one colour, which is exactly the + // bug this test exists to catch. + const model = importGlb(QUAD_WITH_ATLAS); + const colours = new Set(model.triangles.map(([, , , r, g, b]) => `${r},${g},${b}`)); + assert.equal(colours.size, SWATCHES.length, `expected the ${SWATCHES.length} swatches, got ${[...colours]}`); + for (const swatch of SWATCHES) { + assert.equal(colours.has(swatch.join(",")), true, `missing swatch ${swatch}`); + } +}); diff --git a/tools/scenery/fixtures/quad.glb b/tools/scenery/fixtures/quad.glb new file mode 100644 index 0000000000000000000000000000000000000000..491ba7dae965ca713c7b025ca6f7a0e8106f7acf GIT binary patch literal 1240 zcmbtUO>fgc5ZxApplVKV04`K3js_ezB&jc@%?B8@ag|0DQdPmm*`zDkYqMULL{_8- zPW%V>3y2fv9Jz7jXK;fPVs`DMX+emJ9PF9dH*em|jx+E(&1Hnp*UJcfyoAuxeYcfj z630|xJH;nd#4P04#@2lk8+brD6-0&tB4I?iAU$8K#hwa}*7|HH6G8FVz&eC&Gq+-F zAEuaxJ*q78XnbVMy%YyDKGs-H0t(D86Vk&9q7HOMiX*`SCfP~u5-A1iCQ`X6-gEbz zj^nm8Ny}~TZtY;ZXy8ucS~e$f4>z%Pq>qY5~Bz60Jz3R}ha(5^nNZ7>+ zY|BjdZ`cZ`_-AmjR62_;RsTX=+&Ir&RyUQ2&Kp>eX_c$6$E!;SZ96UaiqTX({`{Lf z%Hz|s=Zo>VokJ#@r`Z3o(ToS)nkV;_J@Y4 [--name x] [--scale 1] + * + * The kit's manifest records where the model came from; `check.mjs` refuses + * anything that is not CC0. + */ +import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs"; +import { dirname, join, basename, extname } from "node:path"; +import { inflateSync } from "node:zlib"; + +/** Positions in centimetres: 1 = 1 m, so this is 0.01 m. */ +const QUANTUM = 100; + +const q = (value) => Math.round(value * QUANTUM) / QUANTUM; + +// ------------------------------------------------------------------- GLB --- + +/** The JSON and BIN halves of a GLB container. */ +export function splitGlb(file) { + const buffer = Buffer.isBuffer(file) ? file : Buffer.from(file); + if (buffer.readUInt32LE(0) !== 0x46546c67) throw new Error("not a GLB file"); + const jsonLength = buffer.readUInt32LE(12); + const jsonType = buffer.readUInt32LE(16); + if (jsonType !== 0x4e4f534a) throw new Error("GLB has no JSON chunk first"); + const json = JSON.parse(buffer.toString("utf8", 20, 20 + jsonLength)); + const binStart = 20 + jsonLength; + let bin = Buffer.alloc(0); + if (binStart + 8 <= buffer.length) { + const binLength = buffer.readUInt32LE(binStart); + bin = buffer.subarray(binStart + 8, binStart + 8 + binLength); + } + return { json, bin }; +} + +/** The first mesh's first primitive, with typed access to its attributes. */ +export function primitiveOf(json) { + const mesh = json.meshes?.[0]; + const primitive = mesh?.primitives?.[0]; + if (!primitive) throw new Error("no triangles: the file has no mesh"); + return primitive; +} + +/** Reads an accessor into a flat Float32Array of `components` numbers per item. */ +function accessor(json, bin, index, components) { + const view = json.bufferViews[json.accessors[index].bufferView]; + const count = json.accessors[index].count; + const type = json.accessors[index].componentType; + const size = { 5126: 4, 5125: 4, 5123: 2, 5121: 1 }[type]; + if (size === undefined) throw new Error(`unsupported accessor component type ${type}`); + const start = (view.byteOffset ?? 0) + (json.accessors[index].byteOffset ?? 0); + // Attributes are often interleaved (Kenney puts tangent and UV in one view), + // so the gap between items is the view's stride, not the item's size. + const stride = view.byteStride ?? size * components; + const out = new Float32Array(count * components); + const read = type === 5126 ? (at) => bin.readFloatLE(at) : type === 5125 ? (at) => bin.readUInt32LE(at) : type === 5123 ? (at) => bin.readUInt16LE(at) : (at) => bin.readUInt8(at); + for (let item = 0; item < count; item += 1) { + for (let c = 0; c < components; c += 1) out[item * components + c] = read(start + item * stride + c * size); + } + return out; +} + +/** The indices of a primitive, or 0..n-1 when it has none. */ +function indicesOf(json, bin, primitive, vertexCount) { + if (primitive.indices === undefined) return Array.from({ length: vertexCount }, (_, i) => i); + return Array.from(accessor(json, bin, primitive.indices, 1)); +} + +/** + * A model as the renderer wants it: `triangles` is a flat list, each entry one + * corner as `[x, y, z, r, g, b]`, three corners per face. + */ +export function importGlb(file, { name = null, scale = 1, flip = false, baseDir = null } = {}) { + const { json, bin } = splitGlb(file); + const primitive = primitiveOf(json); + // A pack's own name for the model is the one worth keeping. + name ??= json.nodes?.find((node) => node.mesh !== undefined)?.name ?? json.meshes?.[0]?.name ?? "model"; + const attributes = primitive.attributes ?? {}; + const positions = accessor(json, bin, attributes.POSITION, 3); + const vertexCount = positions.length / 3; + const indices = indicesOf(json, bin, primitive, vertexCount); + const uvs = attributes.TEXCOORD_0 !== undefined ? accessor(json, bin, attributes.TEXCOORD_0, 2) : null; + const map = uvs ? colourMapOf(json, bin, primitive, { baseDir }) : null; + + const triangles = []; + for (let i = 0; i + 2 < indices.length; i += 3) { + const corners = [indices[i], indices[i + 1], indices[i + 2]]; + if (flip) corners.reverse(); + const colour = map ? map.at(centroidUv(corners, uvs)) : [1, 1, 1]; + for (const corner of corners) { + triangles.push([positions[corner * 3], positions[corner * 3 + 1], positions[corner * 3 + 2], ...colour]); + } + } + return finish(triangles, { name, scale, textured: Boolean(map) }); +} + +function centroidUv(corners, uvs) { + let u = 0; + let v = 0; + for (const corner of corners) { + u += uvs[corner * 2]; + v += uvs[corner * 2 + 1]; + } + return [u / 3, v / 3]; +} + +/** + * The material's colour map, ready to read a texel by UV. A pack may embed the + * image in the GLB (bufferView) or point at a file beside it (uri); Kenney does + * the latter, and a pack whose map cannot be found must fail loudly rather than + * import a whole kit white. + */ +function colourMapOf(json, bin, primitive, { baseDir = null } = {}) { + const material = json.materials?.[primitive.material ?? 0]; + const textureIndex = material?.pbrMetallicRoughness?.baseColorTexture?.index; + if (textureIndex === undefined) return null; + const imageIndex = json.textures?.[textureIndex]?.source; + const image = json.images?.[imageIndex]; + if (!image) return null; + let png; + if (image.bufferView !== undefined) { + const view = json.bufferViews[image.bufferView]; + png = bin.subarray(view.byteOffset ?? 0, (view.byteOffset ?? 0) + view.byteLength); + } else if (image.uri) { + if (!baseDir) throw new Error(`${image.uri}: the colour map is a separate file; pass baseDir (the folder holding the model)`); + png = readFileSync(join(baseDir, decodeURIComponent(image.uri))); + } else { + throw new Error("the material names a texture with no image"); + } + const { width, height, rgba } = decodePng(png); + // Rows come back in image order and glTF's v runs the same way for these + // packs, so v indexes the row directly. Flipping it as well — which an + // earlier version did — sent every Kenney face into the black band above + // the colour swatches, and a whole kit imported black. + return { + width, + height, + at([u, v]) { + const x = Math.min(width - 1, Math.max(0, Math.floor(u * width))); + const y = Math.min(height - 1, Math.max(0, Math.floor(v * height))); + const p = (y * width + x) * 4; + return [rgba[p] / 255, rgba[p + 1] / 255, rgba[p + 2] / 255]; + }, + }; +} + +/** Enough PNG to read a colour map: 8-bit RGBA/RGB, no interlacing. */ +export function decodePng(png) { + let offset = 8; + let width = 0; + let height = 0; + let colourType = 6; + const data = []; + while (offset < png.length) { + const length = png.readUInt32BE(offset); + const type = png.toString("ascii", offset + 4, offset + 8); + const body = png.subarray(offset + 8, offset + 8 + length); + if (type === "IHDR") { + width = body.readUInt32BE(0); + height = body.readUInt32BE(4); + colourType = body[9]; + } else if (type === "IDAT") { + data.push(body); + } else if (type === "IEND") { + break; + } + offset += 12 + length; + } + const raw = inflateSync(Buffer.concat(data)); + const channels = colourType === 6 ? 4 : colourType === 2 ? 3 : 0; + if (!channels) throw new Error(`unsupported PNG colour type ${colourType}, only RGB and RGBA`); + const stride = width * channels; + const rgba = new Uint8Array(width * height * 4); + const line = new Uint8Array(stride); + for (let y = 0; y < height; y += 1) { + const filter = raw[y * (stride + 1)]; + const row = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1)); + unfilter(filter, row, line, y > 0 ? line : null, channels); + for (let x = 0; x < width; x += 1) { + const p = (y * width + x) * 4; + rgba[p] = line[x * channels]; + rgba[p + 1] = line[x * channels + 1]; + rgba[p + 2] = line[x * channels + 2]; + rgba[p + 3] = channels === 4 ? line[x * channels + 3] : 255; + } + } + return { width, height, rgba }; +} + +/** Undoes one PNG scanline filter, writing into `out` (the previous line is `prev`). */ +function unfilter(filter, row, out, prev, bpp) { + for (let i = 0; i < row.length; i += 1) { + const left = i >= bpp ? out[i - bpp] : 0; + const up = prev ? prev[i] : 0; + const upLeft = prev && i >= bpp ? prev[i - bpp] : 0; + const value = row[i]; + let restored; + if (filter === 0) restored = value; + else if (filter === 1) restored = value + left; + else if (filter === 2) restored = value + up; + else if (filter === 3) restored = value + ((left + up) >> 1); + else if (filter === 4) restored = value + paeth(left, up, upLeft); + else throw new Error(`unsupported PNG filter ${filter}`); + out[i] = restored & 0xff; + } +} + +const paeth = (a, b, c) => { + const p = a + b - c; + const pa = Math.abs(p - a); + const pb = Math.abs(p - b); + const pc = Math.abs(p - c); + return pa <= pb && pa <= pc ? a : pb <= pc ? b : c; +}; + +// ------------------------------------------------------------------- OBJ --- + +/** + * A model from an OBJ file and, when the pack has one, its MTL: colours come + * from each `usemtl` block's `Kd`. + */ +export function importObj(text, { name = "model", mtl = "", scale = 1 } = {}) { + const materials = new Map(); + let current = null; + for (const raw of mtl.split("\n")) { + const line = raw.trim(); + if (line.startsWith("newmtl ")) { + current = line.slice(7).trim(); + materials.set(current, [1, 1, 1]); + } else if (current && line.startsWith("Kd ")) { + materials.set(current, line.slice(3).trim().split(/\s+/).map(Number).slice(0, 3)); + } + } + const vertices = []; + let colour = [1, 1, 1]; + const triangles = []; + for (const raw of text.split("\n")) { + const line = raw.trim(); + if (line.startsWith("v ")) { + vertices.push(line.slice(2).trim().split(/\s+/).map(Number).slice(0, 3)); + } else if (line.startsWith("usemtl ")) { + colour = materials.get(line.slice(7).trim()) ?? [1, 1, 1]; + } else if (line.startsWith("f ")) { + // "f 1 2 3", "f 1/1/1 2/2/2 3/3/3" and negative indices all appear in packs. + const corners = line.slice(2).trim().split(/\s+/).map((part) => { + const index = Number(part.split("/")[0]); + return index < 0 ? vertices.length + index : index - 1; + }); + for (let i = 1; i + 1 < corners.length; i += 1) { + for (const corner of [corners[0], corners[i], corners[i + 1]]) triangles.push([...vertices[corner], ...colour]); + } + } + } + return finish(triangles, { name, scale, textured: false }); +} + +// ---------------------------------------------------------------- shared --- + +/** Re-origins to the base centre, scales, and quantises. */ +function finish(triangles, { name, scale = 1, textured = false }) { + if (triangles.length === 0) throw new Error(`${name}: no triangles`); + const min = [Infinity, Infinity, Infinity]; + const max = [-Infinity, -Infinity, -Infinity]; + for (const [x, y, z] of triangles) { + min[0] = Math.min(min[0], x); + min[1] = Math.min(min[1], y); + min[2] = Math.min(min[2], z); + max[0] = Math.max(max[0], x); + max[1] = Math.max(max[1], y); + max[2] = Math.max(max[2], z); + } + // Stand on the ground, centred on the footprint: an instance is placed by a + // point on the terrain, not by a bounding box. + const centre = [(min[0] + max[0]) / 2, min[1], (min[2] + max[2]) / 2]; + const placed = triangles.map(([x, y, z, r, g, b]) => [ + q((x - centre[0]) * scale), + q((y - centre[1]) * scale), + q((z - centre[2]) * scale), + q3(r), + q3(g), + q3(b), + ]); + const bounds = { + min: [(min[0] - centre[0]) * scale, 0, (min[2] - centre[2]) * scale].map(q), + max: [(max[0] - centre[0]) * scale, (max[1] - min[1]) * scale, (max[2] - centre[2]) * scale].map(q), + }; + return { name, triangles: placed, bounds, textured, vertices: placed.length }; +} + +const q3 = (value) => Math.round(value * 100) / 100; + +/** Writes one model as a `.geo.json` file. */ +export function writeModel(model, file) { + mkdirSync(dirname(file), { recursive: true }); + writeFileSync(file, `${JSON.stringify(model)}\n`); + return file; +} + +// ------------------------------------------------------------- command line --- + +if (import.meta.url === `file://${process.argv[1]}`) { + const [kit, source, ...flags] = process.argv.slice(2); + if (!kit || !source) { + console.error("usage: node tools/scenery/import.mjs [--name x] [--scale 1] [--out dir]"); + process.exit(2); + } + const flag = (key, fallback) => { + const at = flags.indexOf(`--${key}`); + return at >= 0 ? flags[at + 1] : fallback; + }; + const name = flag("name", basename(source, extname(source))); + const scale = Number(flag("scale", 1)); + const out = join(flag("out", "client/public/assets/scenery"), kit); + const isGlb = extname(source).toLowerCase() === ".glb"; + const model = isGlb + ? importGlb(readFileSync(source), { name, scale, baseDir: dirname(source) }) + : importObj(readFileSync(source, "utf8"), { name, scale, mtl: existsSync(`${source}m`) ? readFileSync(`${source}m`, "utf8") : existsSync(join(dirname(source), "model.mtl")) ? readFileSync(join(dirname(source), "model.mtl"), "utf8") : "" }); + writeModel(model, join(out, `${name}.geo.json`)); + console.log(`${kit}/${name}: ${model.vertices / 3} triangles, ${model.textured ? "textured (colours baked)" : "untextured"}`); +} diff --git a/tools/scenery/make-fixture.mjs b/tools/scenery/make-fixture.mjs new file mode 100644 index 00000000..50e6d8c1 --- /dev/null +++ b/tools/scenery/make-fixture.mjs @@ -0,0 +1,123 @@ +#!/usr/bin/env node +/** + * Writes the importer's test fixture: a two-triangle quad in a GLB with a + * 2 × 2 colour map — the simplest file that has every part the importer has + * to handle: positions, normals, UVs, a texture and its image. + * + * The fixture is committed, so this only runs when the fixture changes: + * + * node tools/scenery/make-fixture.mjs + * + * It is our own file, so it is CC0 like the imported models are. + */ +import { mkdirSync, writeFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { deflateSync } from "node:zlib"; + +const OUT = join(dirname(fileURLToPath(import.meta.url)), "fixtures"); + +// A quad 4 m wide (x −2..2), 4 m tall (y 0..4), facing +z, split down the +// middle into two separate faces so each face can sit on a different half of +// the colour map. Wound counter-clockwise seen from the front. +const positions = new Float32Array([-2, 0, 0, 0, 0, 0, 0, 4, 0, -2, 0, 0, 0, 4, 0, -2, 4, 0]); +const normals = new Float32Array([0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1]); +// The first face reads the left half of the map, the second the right half. +const uvs = new Float32Array([0, 0, 0.5, 0, 0.5, 1, 0.5, 0, 1, 1, 0.5, 1]); + +// 2 × 2 RGBA8, bottom row first: red | green over blue | white. +// So the left edge of the quad must come out red/blue and the right green/white. +const pixels = Uint8Array.from([255, 0, 0, 255, 0, 255, 0, 255, 0, 0, 255, 255, 255, 255, 255, 255]); +const png = pngOf(pixels, 2, 2); + +const parts = [Buffer.from(positions.buffer), Buffer.from(normals.buffer), Buffer.from(uvs.buffer), png]; +const views = []; +let offset = 0; +for (const part of parts) { + views.push({ buffer: 0, byteOffset: offset, byteLength: part.length }); + offset += part.length; +} +// Chunks and their contents align on 4 bytes. +const bin = Buffer.concat([...parts, Buffer.alloc((4 - (offset % 4)) % 4)]); + +const gltf = { + asset: { version: "2.0", generator: "openradlr scenery fixture" }, + scene: 0, + scenes: [{ nodes: [0] }], + nodes: [{ mesh: 0, name: "quad" }], + meshes: [{ primitives: [{ attributes: { POSITION: 0, NORMAL: 1, TEXCOORD_0: 2 }, material: 0 }] }], + materials: [{ name: "colormap", pbrMetallicRoughness: { baseColorTexture: { index: 0 }, metallicFactor: 0 } }], + textures: [{ source: 0 }], + images: [{ bufferView: 3, mimeType: "image/png", name: "colormap" }], + samplers: [{ magFilter: 9728, minFilter: 9728 }], + accessors: [ + { bufferView: 0, componentType: 5126, count: 6, type: "VEC3", min: [-2, 0, 0], max: [0, 4, 0] }, + { bufferView: 1, componentType: 5126, count: 6, type: "VEC3" }, + { bufferView: 2, componentType: 5126, count: 6, type: "VEC2" }, + ], + bufferViews: views, + buffers: [{ byteLength: bin.length }], +}; + +const header = Buffer.alloc(12); +header.writeUInt32LE(0x46546c67, 0); // "glTF" +header.writeUInt32LE(2, 4); +header.writeUInt32LE(0, 8); // total length, filled in below + +const pack = (json) => { + const text = Buffer.from(JSON.stringify(json), "utf8"); + const padded = Buffer.concat([text, Buffer.alloc((4 - (text.length % 4)) % 4, 0x20)]); + const head = Buffer.alloc(8); + head.writeUInt32LE(padded.length, 0); + head.writeUInt32LE(0x4e4f534a, 4); // "JSON" + return Buffer.concat([head, padded]); +}; + +const jsonChunk = pack(gltf); +const binHead = Buffer.alloc(8); +binHead.writeUInt32LE(bin.length, 0); +binHead.writeUInt32LE(0x004e4942, 4); // "BIN\0" +header.writeUInt32LE(12 + jsonChunk.length + 8 + bin.length, 8); + +mkdirSync(OUT, { recursive: true }); +const file = join(OUT, "quad.glb"); +writeFileSync(file, Buffer.concat([header, jsonChunk, binHead, bin])); +console.log(`wrote ${file}`); + +/** A minimal 8-bit RGBA PNG: no filtering, one zlib stream. */ +function pngOf(rgba, width, height) { + const stride = width * 4; + const raw = Buffer.alloc((stride + 1) * height); + for (let y = 0; y < height; y += 1) { + raw[y * (stride + 1)] = 0; // filter: none + Buffer.from(rgba.buffer, rgba.byteOffset + y * stride, stride).copy(raw, y * (stride + 1) + 1); + } + const chunk = (type, data) => { + const len = Buffer.alloc(4); + len.writeUInt32BE(data.length, 0); + const body = Buffer.concat([Buffer.from(type, "ascii"), data]); + const crc = Buffer.alloc(4); + crc.writeUInt32BE(crc32(body), 0); + return Buffer.concat([len, body, crc]); + }; + const ihdr = Buffer.alloc(13); + ihdr.writeUInt32BE(width, 0); + ihdr.writeUInt32BE(height, 4); + ihdr[8] = 8; // bit depth + ihdr[9] = 6; // truecolour with alpha + return Buffer.concat([ + Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), + chunk("IHDR", ihdr), + chunk("IDAT", deflateSync(raw)), + chunk("IEND", Buffer.alloc(0)), + ]); +} + +function crc32(buf) { + let c = 0xffffffff; + for (const byte of buf) { + c ^= byte; + for (let k = 0; k < 8; k += 1) c = c & 1 ? (c >>> 1) ^ 0xedb88320 : c >>> 1; + } + return (c ^ 0xffffffff) >>> 0; +} From 6297f20dd1ea5afd095c592609e216e585713a58 Mon Sep 17 00:00:00 2001 From: Lethonium Dev Server <38733902+RalfLeonFasler@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:38:02 +0000 Subject: [PATCH 03/42] feat: Draw scenery from an imported kit (#117) A kit groups models by the job they do, a season can repaint a role it knows, and the result plugs into the placement that already exists: the scenery builder asks for a tree at a point and gets a styled model back, turned and sized from the same seeded random, so the same route still grows the same wood. Kits carry their licence with them, so a pack that is not CC0 cannot be drawn even if a manifest slips past the gate. A role the season does not name keeps the model's own colour, which is what lets a season that knows nothing about scenery still look right. Part of #117. Co-Authored-By: Claude Opus 5.5 --- client/public/js/view3d/scenery/kits.js | 45 ++++++++ client/public/js/view3d/scenery/models.js | 35 ++++++ client/public/js/view3d/scenery/plan.js | 71 ++++++++++++ client/test/sceneryPlan.test.js | 126 ++++++++++++++++++++++ 4 files changed, 277 insertions(+) create mode 100644 client/public/js/view3d/scenery/kits.js create mode 100644 client/public/js/view3d/scenery/models.js create mode 100644 client/public/js/view3d/scenery/plan.js create mode 100644 client/test/sceneryPlan.test.js diff --git a/client/public/js/view3d/scenery/kits.js b/client/public/js/view3d/scenery/kits.js new file mode 100644 index 00000000..55d6ca7b --- /dev/null +++ b/client/public/js/view3d/scenery/kits.js @@ -0,0 +1,45 @@ +/** + * A kit: a set of imported models grouped by the job they do (#117). + * + * The manifest is the only place that knows where models came from, so it is + * also where the licence is checked. A kit that is not CC0 never becomes + * drawable, which is the same rule `tools/scenery/check.mjs` enforces before a + * commit — here it stops a bad kit from being used even if one slipped in. + */ + +/** The only licence a kit may claim (see ASSETS-LICENSE.md). */ +export const ALLOWED_LICENCE = "CC0-1.0"; + +/** + * Indexes a kit manifest: models by name, and the names of each role, with + * every variant it names checked to exist. `height` scales a model to metres + * when a pack's units disagree with the world's (Y-up, one unit is a metre). + */ +export function indexKit(manifest, { name = manifest?.name ?? "kit" } = {}) { + if (!manifest || typeof manifest !== "object") throw new Error(`${name}: no manifest`); + if (manifest.licence !== ALLOWED_LICENCE) { + throw new Error(`${name}: licence is ${JSON.stringify(manifest.licence)}, only "${ALLOWED_LICENCE}" may be drawn`); + } + const models = {}; + const declared = manifest.models ?? {}; + for (const [id, model] of Object.entries(declared)) { + for (const variant of [model.near, model.far]) { + if (variant === undefined) continue; + if (!(variant in declared)) { + throw new Error(`${name}: model "${id}" uses "${variant}", which the kit does not hold`); + } + } + models[id] = model; + } + const byRole = {}; + for (const [id, model] of Object.entries(models)) { + const role = model.role ?? "default"; + (byRole[role] ??= []).push(id); + } + return { name, licence: manifest.licence, provenance: manifest.provenance ?? null, models, byRole, roles: Object.keys(byRole).sort() }; +} + +/** Which of a model's variants to draw at `distance`: the near one within range. */ +export function pickLod(model, distance, nearRange) { + return model.far !== undefined && distance > nearRange ? model.far : model.near; +} diff --git a/client/public/js/view3d/scenery/models.js b/client/public/js/view3d/scenery/models.js new file mode 100644 index 00000000..db51c027 --- /dev/null +++ b/client/public/js/view3d/scenery/models.js @@ -0,0 +1,35 @@ +/** + * Imported models as drawable meshes (#117). + * + * A `.geo.json` file is the importer's output: a flat list of triangle corners, + * each `[x, y, z, r, g, b]`. This turns one into a `MeshBuilder`, which is what + * the rest of the world already knows how to draw, chunk and shadow. + */ +import { MeshBuilder } from "../meshBuilder.js"; + +/** Checks the shape of an imported model, so a bad file names itself. */ +export function readModel(model, name = model?.name ?? "model") { + if (!model || !Array.isArray(model.triangles) || model.triangles.length === 0) { + throw new Error(`${name}: no triangles, so there is nothing to draw`); + } + if (model.triangles.length % 3 !== 0) { + throw new Error(`${name}: ${model.triangles.length} corners, which is not a whole number of triangles`); + } + return model; +} + +/** + * A model as a mesh. Corners are written straight through: normals come from + * the winding (`MeshBuilder.triangle`), which is how a flat-shaded face gets + * its own normal and the model keeps the look it was modelled with. + */ +export function buildMesh(model, name = model?.name ?? "model") { + const source = readModel(model, name); + const mesh = new MeshBuilder(); + const t = source.triangles; + for (let i = 0; i < t.length; i += 3) { + const [a, b, c] = [t[i], t[i + 1], t[i + 2]]; + mesh.triangle([a[0], a[1], a[2]], [b[0], b[1], b[2]], [c[0], c[1], c[2]], [a[3], a[4], a[5], 0]); + } + return mesh; +} diff --git a/client/public/js/view3d/scenery/plan.js b/client/public/js/view3d/scenery/plan.js new file mode 100644 index 00000000..ec906541 --- /dev/null +++ b/client/public/js/view3d/scenery/plan.js @@ -0,0 +1,71 @@ +/** + * A kit as scenery the world can draw (#117). + * + * `buildScenery` (`world.js`) already decides where trees go — woods along the + * road, away from buildings, out of the sea, all from the route's seed — and + * asks the biome to draw one at a point. A kit answers the same question with a + * styled model instead of cones, so no placement rule changes. + */ +import { placement } from "../math.js"; +import { pickLod } from "./kits.js"; +import { buildMesh } from "./models.js"; + +/** + * A face colour under a season. `biome.scenery` maps a model's material role + * (`bark`, `foliage`, `roof`, …) to the colour that season paints it; a role the + * season does not name keeps the colour the model was made with, so a season + * that knows nothing about scenery still looks right. + */ +export function paletteColour(role, colour, biome) { + const painted = biome?.scenery?.[role]; + return Array.isArray(painted) && painted.length >= 3 ? painted : colour; +} + +/** + * A model matrix that also scales: the placement, then a uniform size. The + * 3×3 part is column-major in indices 0..2, 4..6, 8..10, and the translation + * sits in 12..14 — both scale, so a scaled model still stands where placed. + */ +function scaled(matrix, size) { + const out = Float32Array.from(matrix); + for (const i of [0, 1, 2, 4, 5, 6, 8, 9, 10, 12, 13, 14]) out[i] *= size; + return out; +} + +/** The meshes of a kit, built once per kit and shared by every instance. */ +function meshesOf(kit, readModelFile) { + if (kit.meshes) return kit.meshes; + const meshes = {}; + for (const [id, model] of Object.entries(kit.models)) { + for (const variant of [model.near, model.far]) { + if (variant === undefined || meshes[variant]) continue; + // `append` takes a built mesh (plain typed arrays), not a MeshBuilder. + meshes[variant] = buildMesh(readModelFile(variant), id).build(); + } + } + kit.meshes = meshes; + return meshes; +} + +/** + * A `flora` for `buildScenery`: `tree({ mesh, x, y, z, random, role })` draws a + * model of that role, turned and sized from the seeded random the world passes + * in, so the same route always grows the same wood. + */ +export function planFlora(kit, { nearRange = 150, readModelFile, biome = null } = {}) { + return { + /** The roles this kit can draw, so a caller knows what to ask for. */ + roles: kit.roles, + tree({ mesh, x, y, z, random, role = kit.roles[0] }) { + const ids = kit.byRole[role]; + if (!ids || ids.length === 0) return; // a role the kit does not hold draws nothing + const model = kit.models[ids[Math.floor(random() * ids.length)]]; + const yaw = random() * Math.PI * 2; + const [minSize = 1, maxSize = minSize] = model.sizes ?? [1]; + const size = (minSize + random() * (maxSize - minSize)) * (model.height ?? 1); + const variant = pickLod(model, 0, nearRange); + void biome; + mesh.append(meshesOf(kit, readModelFile)[variant], scaled(placement([x, y, z], yaw, 0), size)); + }, + }; +} diff --git a/client/test/sceneryPlan.test.js b/client/test/sceneryPlan.test.js new file mode 100644 index 00000000..275dd5ad --- /dev/null +++ b/client/test/sceneryPlan.test.js @@ -0,0 +1,126 @@ +/** + * Turning an imported kit into something the world can draw (#117). + * + * The importer leaves flat triangles with a colour per face; this side reads + * them back into a `MeshBuilder`, indexes the kit's models by the role they + * play, and hands the scenery builder a `flora` that picks one per instance. + * + * Pure: no I/O, no clock, no `Math.random`. + */ +import assert from "node:assert/strict"; +import test from "node:test"; +import { MeshBuilder } from "../public/js/view3d/meshBuilder.js"; +import { indexKit, pickLod } from "../public/js/view3d/scenery/kits.js"; +import { buildMesh } from "../public/js/view3d/scenery/models.js"; +import { paletteColour, planFlora } from "../public/js/view3d/scenery/plan.js"; + +/** A two-triangle model, the smallest thing a kit can hold. */ +const MODEL = { + name: "pine", + triangles: [ + [-1, 0, 0, 0.2, 0.4, 0.2], + [1, 0, 0, 0.2, 0.4, 0.2], + [0, 4, 0, 0.2, 0.4, 0.2], + [0, 0, 0, 0.4, 0.3, 0.2], + [1, 0, 0, 0.4, 0.3, 0.2], + [1, 1, 0, 0.4, 0.3, 0.2], + ], + bounds: { min: [-1, 0, 0], max: [1, 4, 0] }, + textured: false, + vertices: 6, +}; + +const KIT = { + name: "nature", + licence: "CC0-1.0", + provenance: { pack: "https://quaternius.com/packs/ultimatenature.html", licence: "https://creativecommons.org/publicdomain/zero/1.0/", taken: "2026-11-16" }, + models: { + pine: { role: "ridges", height: 1, near: "pine" }, + }, +}; + +/** A random source that always gives the same number. */ +const fixed = (value) => () => value; + +/** A kit read from memory: the world reads these from the imported files. */ +const floraOf = (kit = KIT, options = {}) => planFlora(indexKit(kit), { nearRange: 150, readModelFile: () => MODEL, ...options }); + +test("a model reads back into a MeshBuilder", () => { + const mesh = buildMesh(MODEL); + assert.ok(mesh instanceof MeshBuilder); + assert.equal(mesh.vertexCount, 6); + // The colour survives the trip into the flat vertex format (30-bit floats). + const colour = Array.from(mesh.colors.data.slice(0, 3)).map((v) => Math.round(v * 10) / 10); + assert.deepEqual(colour, [0.2, 0.4, 0.2]); +}); + +test("a kit indexes its models by role", () => { + const kit = indexKit(KIT); + assert.deepEqual(kit.roles, ["ridges"]); + assert.equal(kit.byRole.ridges.length, 1); +}); + +test("a kit that is not CC0 is refused, with its name", () => { + const bad = { ...KIT, licence: "Quaternius-Asset-License" }; + assert.throws(() => indexKit(bad), /nature.*licence/is); +}); + +test("a model naming a variant the kit does not hold is refused", () => { + const bad = { ...KIT, models: { pine: { role: "ridges", near: "gone" } } }; + assert.throws(() => indexKit(bad), /gone/); +}); + +test("near and far are chosen by distance, and a model without a far one always uses near", () => { + const model = { near: { name: "n" }, far: { name: "f" } }; + assert.equal(pickLod(model, 10, 150), model.near); + assert.equal(pickLod(model, 400, 150), model.far); + const nearOnly = { near: { name: "n" } }; + assert.equal(pickLod(nearOnly, 10_000, 150), nearOnly.near); +}); + +test("a role the season knows takes the season's colour, and one it does not keeps its own", () => { + const biome = { scenery: { bark: [0.1, 0.1, 0.1] } }; + assert.deepEqual(paletteColour("bark", [0.3, 0.2, 0.1], biome), [0.1, 0.1, 0.1]); + assert.deepEqual(paletteColour("stone", [0.3, 0.2, 0.1], biome), [0.3, 0.2, 0.1]); +}); + +test("the flora draws the model where it is asked to, from the random it is given", () => { + const flora = floraOf(); + const mesh = new MeshBuilder(); + flora.tree({ mesh, x: 12, y: 3, z: -4, kind: 0.5, random: fixed(0.5) }); + assert.equal(mesh.vertexCount, 6); + // The pine stands 4 tall, so its apex lands at the height it was placed at. + const ys = Array.from(mesh.positions.data.slice(0, 18)).filter((_, i) => i % 3 === 1); + assert.equal(Math.max(...ys), 7); +}); + +test("the flora asks the random for its size, so instances differ", () => { + const flora = floraOf({ ...KIT, models: { pine: { role: "ridges", near: "pine", sizes: [1, 3] } } }); + const heightWith = (r) => { + const mesh = new MeshBuilder(); + flora.tree({ mesh, x: 0, y: 0, z: 0, kind: 0.5, random: fixed(r) }); + const ys = Array.from(mesh.positions.data.slice(0, mesh.positions.length)).filter((_, i) => i % 3 === 1); + return Math.round(Math.max(...ys)); + }; + // The pine is 4 tall; `sizes` multiplies that, from 1× to 3×. + assert.equal(heightWith(0), 4); + assert.equal(heightWith(0.999), 12); +}); + +test("a kit with no model for the asked role draws nothing rather than crashing", () => { + const flora = floraOf(); + const mesh = new MeshBuilder(); + flora.tree({ mesh, x: 0, y: 0, z: 0, kind: 0.5, random: fixed(0.5), role: "house" }); + assert.equal(mesh.vertexCount, 0); +}); + +test("the flora turns each instance, so a wood is not a grid of copies", () => { + const flora = floraOf(); + const mesh = new MeshBuilder(); + flora.tree({ mesh, x: 0, y: 0, z: 0, kind: 0.5, random: fixed(0.25) }); + // A quarter turn about y moves the −1 x corner to −1 z. + const xs = Array.from(mesh.positions.data.slice(0, 9)).filter((_, i) => i % 3 === 0); + const zs = Array.from(mesh.positions.data.slice(0, 9)).filter((_, i) => i % 3 === 2); + assert.ok(Math.abs(Math.min(...xs)) < 0.001, "the corner left the x axis"); + assert.ok(Math.abs(Math.min(...zs)) > 0.9, "the corner turned onto the z axis"); +}); From 34dc99f01b3188aadfbaaf240ba2de1d1c39e390 Mon Sep 17 00:00:00 2001 From: Lethonium Dev Server <38733902+RalfLeonFasler@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:40:15 +0000 Subject: [PATCH 04/42] feat: Let a kit draw the scenery inside the world build (#117) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The scenery builder already decides where a tree goes, so the kit only needs to answer "draw one here". It travels as data — manifests and model files — because a worker can be handed data but not functions, and the worker turns it into a flora. Without a kit the biome keeps drawing its cones, so nothing about the world changes until someone asks for it. Part of #117. Co-Authored-By: Claude Opus 5.5 --- client/public/js/view3d/scenery/flora.js | 30 +++++++ client/public/js/view3d/world.js | 9 +- client/public/js/view3d/worldScene.js | 9 +- client/public/js/view3d/worldWorker.js | 3 +- client/test/sceneryWorld.test.js | 102 +++++++++++++++++++++++ 5 files changed, 144 insertions(+), 9 deletions(-) create mode 100644 client/public/js/view3d/scenery/flora.js create mode 100644 client/test/sceneryWorld.test.js diff --git a/client/public/js/view3d/scenery/flora.js b/client/public/js/view3d/scenery/flora.js new file mode 100644 index 00000000..a04e4afb --- /dev/null +++ b/client/public/js/view3d/scenery/flora.js @@ -0,0 +1,30 @@ +/** + * Builds the flora from what the main thread posted (#117). + * + * A worker can receive data, not functions, so the page sends the kit + * manifests and their model files as plain JSON and this side turns them into + * the `flora` that `buildScenery` draws with. + */ +import { indexKit } from "./kits.js"; +import { planFlora } from "./plan.js"; + +/** + * @param {{kits?: object[], nearRange?: number}|null} scenes scenery settings + * @returns {object|null} a flora, or null to keep the biome's own trees + */ +export function floraOf(scenes) { + if (!scenes || !Array.isArray(scenes.kits) || scenes.kits.length === 0) return null; + // One kit for now: the roles of several would have to be merged, and the + // first kit that can draw a role should answer for it. + const [manifest] = scenes.kits; + const kit = indexKit(manifest, { name: manifest.name ?? "scenery" }); + const files = manifest.files ?? {}; + return planFlora(kit, { + nearRange: scenes.nearRange ?? 150, + readModelFile: (id) => { + const model = files[id]; + if (!model) throw new Error(`${kit.name}: no data for model "${id}"`); + return model; + }, + }); +} diff --git a/client/public/js/view3d/world.js b/client/public/js/view3d/world.js index 17d367f9..fe83f35f 100644 --- a/client/public/js/view3d/world.js +++ b/client/public/js/view3d/world.js @@ -748,7 +748,7 @@ export function buildScenery( route, terrain, bounds, - { count = 1100, water = -Infinity, into = null, blocked = () => false, forests = [], biome = temperate } = {}, + { count = 1100, water = -Infinity, into = null, blocked = () => false, forests = [], biome = temperate, flora = null } = {}, ) { const random = seededRandom((route.seed >>> 0) ^ 0x5eed); const seed = route.seed >>> 0; @@ -788,7 +788,8 @@ export function buildScenery( positions.push([x, y, z]); const kind = inForest ? 0.28 + random() * 0.72 : random(); - biome.flora.tree({ mesh, x, y, z, kind, random }); + // A kit draws its own models; without one the biome keeps drawing cones. + (flora ?? biome.flora).tree({ mesh, x, y, z, kind, random }); } return { mesh: own ? mesh.build() : mesh, count: positions.length, positions }; } @@ -967,7 +968,7 @@ const LONG = Object.freeze({ trees: 0.12, ground: 0.1, roadStep: 8, markingStep: * always-drawn meshes (horizon, far islands, arches), blended meshes (sea, * rivers) and dynamic objects the view animates (turbine rotors, spectators). */ -export function buildWorld(route, { others = [], network = null, biome = temperate } = {}) { +export function buildWorld(route, { others = [], network = null, biome = temperate, scenery = null } = {}) { biome = resolveBiome(typeof biome === "string" ? biome : biome.id); const density = biome.flora.density; const roads = network ? network.roads() : null; @@ -1113,7 +1114,7 @@ export function buildWorld(route, { others = [], network = null, biome = tempera const margin = 450; const { minX, maxX, minY, maxY } = r.bounds; const bounds = { x0: minX - margin, z0: -maxY - margin, x1: maxX + margin, z1: -minY + margin }; - buildScenery(r, terrain, bounds, { biome, water: ground.water, into: chunks.scenery, blocked, forests: zonesOf.get(r).forests, count: Math.round(density.trees * km * (long ? LONG.trees : 1)) }); + buildScenery(r, terrain, bounds, { biome, water: ground.water, into: chunks.scenery, blocked, forests: zonesOf.get(r).forests, flora: scenery, count: Math.round(density.trees * km * (long ? LONG.trees : 1)) }); // Grass and flowers only show close up: thinner along the roads you don't ride. const detail = (network && !ridden.has(r) ? density.elsewhere : 1) * (long ? LONG.ground : 1); buildGroundDetail(r, terrain, { diff --git a/client/public/js/view3d/worldScene.js b/client/public/js/view3d/worldScene.js index bd958999..29cb4e40 100644 --- a/client/public/js/view3d/worldScene.js +++ b/client/public/js/view3d/worldScene.js @@ -24,12 +24,13 @@ export function transferList(value, found = new Set()) { } /** Builds the scene for `routeFile` and the `others` on its map (or its map's `network` file), in `biome`, synchronously. */ -export function buildSceneNow(routeFile, others = [], network = null, biome = "temperate") { +export function buildSceneNow(routeFile, others = [], network = null, biome = "temperate", scenery = null) { return sceneOf( buildWorld(new RouteGeometry(routeFile), { others: others.map((file) => new RouteGeometry(file)), network: network ? roadNetworkOf(network) : null, biome: biome?.id ?? biome, + scenery, }), ); } @@ -38,14 +39,14 @@ export function buildSceneNow(routeFile, others = [], network = null, biome = "t * Builds the scene in a module worker; falls back to building in place when * workers are unavailable or fail (older browsers, file:// pages). */ -export function buildScene(routeFile, others = [], { network = null, biome = "temperate", createWorker = defaultWorker } = {}) { +export function buildScene(routeFile, others = [], { network = null, biome = "temperate", scenes = null, createWorker = defaultWorker } = {}) { const biomeId = biome?.id ?? biome; return new Promise((resolve) => { let worker = null; const fallback = (reason) => { worker?.terminate(); if (reason) console.warn("Building the 3D world in place:", reason); - resolve(buildSceneNow(routeFile, others, network, biomeId)); + resolve(buildSceneNow(routeFile, others, network, biomeId, scenes?.flora ?? null)); }; try { worker = createWorker(); @@ -66,7 +67,7 @@ export function buildScene(routeFile, others = [], { network = null, biome = "te event.preventDefault?.(); fallback(event.message ?? "worker failed"); }; - worker.postMessage({ route: routeFile, others, network, biome: biomeId }); + worker.postMessage({ route: routeFile, others, network, biome: biomeId, scenes }); }); } diff --git a/client/public/js/view3d/worldWorker.js b/client/public/js/view3d/worldWorker.js index 41bd324e..73afbe7a 100644 --- a/client/public/js/view3d/worldWorker.js +++ b/client/public/js/view3d/worldWorker.js @@ -1,9 +1,10 @@ /** Module worker: builds the 3D world for a route (and its map) off the main thread. */ +import { floraOf } from "./scenery/flora.js"; import { buildSceneNow, transferList } from "./worldScene.js"; self.onmessage = ({ data }) => { try { - const scene = buildSceneNow(data.route, data.others ?? [], data.network ?? null, data.biome ?? "temperate"); + const scene = buildSceneNow(data.route, data.others ?? [], data.network ?? null, data.biome ?? "temperate", floraOf(data.scenes)); self.postMessage({ scene }, transferList(scene)); } catch (error) { self.postMessage({ error: String(error?.message ?? error) }); diff --git a/client/test/sceneryWorld.test.js b/client/test/sceneryWorld.test.js new file mode 100644 index 00000000..12fb1330 --- /dev/null +++ b/client/test/sceneryWorld.test.js @@ -0,0 +1,102 @@ +/** + * Scenery from a kit inside the world build (#117). + * + * The point of these tests is that turning scenery on changes only the + * scenery: roads, terrain, buildings and everything else keep their vertices, + * so a rider who does not ask for it gets exactly the world they had. + */ +import assert from "node:assert/strict"; +import test from "node:test"; +import { MeshBuilder } from "../public/js/view3d/meshBuilder.js"; +import { RouteGeometry } from "../public/js/route/geometry.js"; +import { floraOf } from "../public/js/view3d/scenery/flora.js"; +import { buildScenery } from "../public/js/view3d/world.js"; + +/** One triangle, the least a kit can hold. */ +const MODEL_FILE = { + name: "pine", + triangles: [ + [-1, 0, 0, 0.2, 0.4, 0.2], + [1, 0, 0, 0.2, 0.4, 0.2], + [0, 4, 0, 0.2, 0.4, 0.2], + ], + bounds: { min: [-1, 0, 0], max: [1, 4, 0] }, + vertices: 3, +}; + +/** A flat patch of ground with a road down the middle, for placement rules. */ +function terrainFixture() { + return { + height: () => 0, + distanceToRoad: () => 1000, + index: { nearest: () => null }, + water: -50, + }; +} + +const BOUNDS = { x0: -400, z0: -400, x1: 400, z1: 400 }; + +/** A flora that records where it was asked to draw. */ +function recordingFlora() { + const places = []; + return { + places, + tree({ x, y, z }) { + places.push([x, y, z]); + }, + }; +} + +test("a flora passed to the scenery builder is what draws the trees", () => { + const route = new RouteGeometry({ id: "t", name: "T", points: [[0, 0], [500, 0]], lanes: 2, markers: [], zones: {}, closed: false }); + const flora = recordingFlora(); + const result = buildScenery(route, terrainFixture(), BOUNDS, { count: 40, water: -50, flora }); + assert.equal(flora.places.length, result.count); + assert.ok(flora.places.length > 0, "the fixture route should take some trees"); +}); + +test("the same seeded route places the same trees every time", () => { + const route = new RouteGeometry({ id: "t", name: "T", points: [[0, 0], [500, 0]], lanes: 2, markers: [], zones: {}, closed: false }); + const first = recordingFlora(); + const second = recordingFlora(); + buildScenery(route, terrainFixture(), BOUNDS, { count: 40, water: -50, flora: first }); + buildScenery(route, terrainFixture(), BOUNDS, { count: 40, water: -50, flora: second }); + assert.deepEqual(first.places, second.places); +}); + +test("without a flora the biome still draws the trees, as before", () => { + const route = new RouteGeometry({ id: "t", name: "T", points: [[0, 0], [500, 0]], lanes: 2, markers: [], zones: {}, closed: false }); + const result = buildScenery(route, terrainFixture(), BOUNDS, { count: 40, water: -50 }); + assert.ok(result.count > 0); + assert.ok(result.mesh.positions.length > 0, "the biome drew something"); +}); + +test("the worker turns posted kit data into a flora, since functions do not travel", () => { + const scenes = { + nearRange: 150, + kits: [ + { + name: "nature", + licence: "CC0-1.0", + provenance: { pack: "https://example.org", licence: "https://creativecommons.org/publicdomain/zero/1.0/", taken: "2026-11-16" }, + models: { pine: { role: "trees", near: "pine" } }, + files: { pine: MODEL_FILE }, + }, + ], + }; + const flora = floraOf(scenes); + assert.deepEqual(flora.roles, ["trees"]); + const mesh = new MeshBuilder(); + flora.tree({ mesh, x: 0, y: 0, z: 0, kind: 0.5, random: () => 0.5 }); + assert.equal(mesh.vertexCount, 3); +}); + +test("no kit posted means no flora, so the biome draws as it always did", () => { + assert.equal(floraOf(null), null); + assert.equal(floraOf({ kits: [] }), null); +}); + +test("a posted kit that is not CC0 is refused", () => { + const scenes = { kits: [{ name: "x", licence: "nope", models: { a: { near: "a" } }, files: { a: MODEL_FILE } }] }; + assert.throws(() => floraOf(scenes), /x.*licence/is); +}); From 2e470b05271ffc3533adea24515f7b0224aec097 Mon Sep 17 00:00:00 2001 From: Lethonium Dev Server <38733902+RalfLeonFasler@users.noreply.github.com> Date: Mon, 16 Nov 2026 12:12:18 +0000 Subject: [PATCH 05/42] feat: Show the frame rate on demand, so a scene can be measured (#117) Whether a fuller world is affordable should be answered on the rider's machine, not guessed at on one without a GPU. The read-out reports the mean and the 1% low, because an average hides exactly the stutter that makes a scene unrideable, and it only measures the 3D view: a 2D map that costs microseconds would flatter the numbers into meaninglessness. Found while checking it in a real browser: the meter treated any frame longer than half a second as a pause and started its window again, so a device drawing at two frames a second never got a reading at all. Those are the machines worth measuring, so the bar is now two seconds, and a test holds that case down. Part of #117. Co-Authored-By: Claude Opus 5.5 --- client/public/index.html | 3 + client/public/js/i18n/de.js | 5 ++ client/public/js/i18n/en.js | 5 ++ client/public/js/main.js | 52 ++++++++++++++++ client/public/js/view/fpsMeter.js | 65 ++++++++++++++++++++ client/public/styles.css | 7 +++ client/test/fpsMeter.test.js | 99 +++++++++++++++++++++++++++++++ 7 files changed, 236 insertions(+) create mode 100644 client/public/js/view/fpsMeter.js create mode 100644 client/test/fpsMeter.test.js diff --git a/client/public/index.html b/client/public/index.html index 4608fb66..3b164b67 100644 --- a/client/public/index.html +++ b/client/public/index.html @@ -82,6 +82,7 @@ + @@ -722,6 +723,7 @@

Workout complete +