Skip to content

feat: Fill the island with woods, a high country and a market city - #119

Draft
RalfLeonFasler wants to merge 42 commits into
mainfrom
feat/scenery-kit
Draft

RalfLeonFasler wants to merge 42 commits into
mainfrom
feat/scenery-kit

Conversation

@RalfLeonFasler

@RalfLeonFasler RalfLeonFasler commented Nov 16, 2026 •

Copy link
Copy Markdown
Contributor

Scenery kit: a fuller island, a high country and a real market city

Part of #117. Draft while the art direction and real-hardware costs are
reviewed.

This PR adds a CC0 scenery pipeline and uses it to give the island more
variety: imported nature and farm models, a dense forest, a high country with
rock and permanent snow, a top-down land-use map, and a market city at the
Hilltop Café with a street grid, junctions and a square.

Everything below is current unless it says planned or history. The
history at the bottom records how the PR got here; it is not a list of current
features.

Try it

make dev

Open the app, choose Quaternius in the scenery level (or Kenney for the
comparison), and ride Rolling Hills from the start: the Hilltop Café is the
city square. The scenery level is in the View popover. Scenery off keeps
the old world exactly as it was.

What is in this PR now

1. CC0 scenery kits

  • Quaternius nature (17 models) and Quaternius farm (13 models), both
    CC0-1.0, committed with provenance and a far twin for each model.
  • The existing Kenney nature + fantasy-town level stays as the comparison.
  • make scenery-check verifies the licence and the model counts.
  • The quaternius level is a separate choice beside models, so both can be
    compared in the app.

2. Forest density, corrected

The first density pass had a bug: distanceToRoad only searched the road's own
verge (~170 m), so the canopy's 60–420 m band was really a 60–170 m belt.
RoadIndex.distance now searches far enough, and the canopy uses it. The wood
behind the first trees is fuller; the far belt is still cheap crowns.

  • canopy behind the modelled belt;
  • bushes and rocks on the verge;
  • land-aware ground: dark forest floor, crop greens, meadow;
  • 100 m near chunks for a kit with far twins, so the camera's chunk is not a
    whole wood.

Dense forest, off

Dense forest, Kenney

Dense forest, Quaternius

Forest behind the first trees

3. High country: rock, treeline and permanent snow

The map and the 3D now use the same height and slope rules:

  • treeline at 205 m — no trees, grass tufts or flowers above it;
  • bare rock on steep faces;
  • permanent snow on the highest peaks (330 m+), broken by noise and slope
    so rock and alpine grass show through;
  • farms stay below the treeline, so there is no farmyard in the snow.

High country at the pass

4. The Hilltop market city

The east cluster is no longer a strip. A new settlement layer builds the
city once, from the map seed, whichever route is ridden:

  • 12 streets (the main road plus parallel and cross streets), 35
    junctions
    , 188 plots, 190 lamps on the real valley terrain;
  • a market square at the Hilltop Café, with a fountain, stalls, benches, a
    church and a windmill;
  • houses on both sides of every street, with front gardens, fences and a few
    garden trees;
  • the old village zones around the café are skipped when scenery is on, so the
    city does not get a second strip;
  • scenery off keeps the old procedural villages exactly as before.

The city is a place in routes/maps/valley.json (settlements), not a route
zone. A settlement can span several roads; the city looks the same from every
approach.

City from the saddle

City from the drone

The layout itself, drawn from the same data (streets black, the ridden road
orange, plots brown, the square pale):

City layout

5. Top-down land-use and proposal maps

The map uses the same seeded land, height and slope rules as the 3D. Deep green
is dense wood, mid green sparse wood, yellow field, light green open, grey
rock/scree, white snow, blue water; white roads, orange rolling-hills, orange
circles villages, yellow squares farms.

Valley land use

The annotated proposal map adds the eight regions for the next rounds:

Valley proposal

Generated by client/worldMap.mjs:

node worldMap.mjs --out valley-landuse.png
node worldMap.mjs --proposal --out valley-proposal.png

Performance

Measured in the headless world build, not yet on real hardware.

Scene Visible vertices Draw calls
Dense wood at 5675 m, Quaternius 4.0M 839
Dense wood at 5675 m, Kenney 2.28M 841
Dense wood at 5675 m, off 1.06M 239
Hilltop city, Quaternius, near 1.00M —
Hilltop city, Quaternius, far 8k —
Hilltop city, street/pavement mesh 27k —
Hilltop city, garden trees 72k —
Hilltop city, lamp heads 7k —

The city is the new worst case for buildings: 188 detailed houses are ~1.0M
near vertices. The far twins are 8k. If that is too much on real hardware, the
first lever is the village near range (350 m) and the house count; the city is
one place, not the whole island.

Planned, not in this PR

These are designed and planned but not implemented yet:

  • Southwest village as a settlement (green, church, farm lane, cross lane,
    stone walls).
  • Southeast harbour (new lane to the bay, quay, boats, fish market, dunes).
  • Town light: lit windows, additive ground pools under lanterns, up to 8
    nearest point lights on High, market string lights. The design is in
    docs/superpowers/specs/2026-11-17-towns-and-lighting-design.md; the plan is
    docs/superpowers/plans/2026-11-17-towns-and-lighting.md.
  • Variety pass: the eight regions of the proposal map, borrowing the
    Living island's groundGrid, road-distance field, height bands and parcel
    layout — but not its flat ground texture.
  • Density/life pass from the Cykelapp brief: zone style tables, verge
    bands, near-only ground cover, far silhouettes, reserved sightlines, a
    summer-life layer and per-instance wind phase.

Current open questions

  • Real laptop/phone frame-time and memory for the city; the near-house count is
    the first thing to tune.
  • Whether the city wants a wall or a gate, or stays an open market town.
  • Whether dusk is dark enough for the town light, or a real night is needed.
  • Whether the city should be wider than the hilltop ridge allows; the terrain
    currently makes it a long ridge town.

History

  • 2026-11-16 — scenery kit spike: imported CC0 nature/farm models, a
    quaternius level beside Kenney, provenance and make scenery-check.
  • 2026-11-17 — farmsteads from the farm kit; forest density pass; top-down
    land-use map.
  • 2026-11-17 — high country: treeline, rock, permanent snow; canopy
    road-distance fix; farms kept off the high ground.
  • 2026-11-17 — annotated proposal map; town and lighting design; settlement
    layer; the Hilltop market city with 12 streets, 35 junctions and 188 plots.

Still open

  • Real laptop/phone frame-time and memory measurements before assuming a
    frame-rate win.
  • Whether compact/indexed vertices are worth another benchmarked renderer
    change; instancing alone is not a reason to add them.
  • Re-evaluate the remaining CC0 packs against the new budgets once the density
    pass exists.

Part of #117.

RalfLeonFasler and others added 10 commits November 16, 2026 11:22
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
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 <noreply@anthropic.com>
Ten models from Kenney's Racing Kit: trees, fences and barriers. The
pack ships its own License.txt saying CC0 1.0 Universal, which is the
evidence the gate wants, and 136 KB is the cost of proving the pipeline
works on real files rather than on a fixture.

Two things importing real files taught the importer. Most low-poly packs
colour each material with a plain factor rather than a map, so 101 of the
112 models here came out white until it read baseColorFactor. And a model
is usually several primitives, one per material, so reading only the
first drew every tree in a single colour with no bark.

The kit's own trees are decorative props a metre and a half tall beside
one-unit figures, not woodland, so the manifest scales them to stand
beside our eight-metre houses. That is the lever a kit gets.

Part of #117.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Scenery row beside the camera, layout, view and time of day: Off for
the woods every rider has had, Models for the imported ones. Off by
default, since it is a look to choose rather than a change to impose.

The kits are fetched once and kept, and a kit that will not load leaves
the ride as it was rather than half-built: scenery is an extra, never a
requirement for the world to work.

Part of #117.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Racing Kit proved the pipeline but not the look: its trees are
decorative props a metre and a half tall, so a wood of them was thinner
than the cones they replaced. Nature Kit 2.1 is what the scenery was
for — 61 trees, bushes, grass and rocks, all untextured and flat-shaded,
and its own License.txt says CC0 1.0.

Twenty-six models are imported under `assets/scenery/nature`, grouped by
the job they do: firs, leafies, bushes, rocks, tufts and flowers. The
world already asks for a tree at a point and says what kind it is, so a
kit now answers by kind, and a kit that does not hold a role hands that
spot back to the biome rather than leaving it bare.

Getting it to look like this island took three things the pack could not
know. Its palette is its own — a tropical teal for leaves and a bright
orange bark — so each face is painted to the season's green or brown by
how green or warm it already is, keeping the model's shading. Its units
are its own too, so the manifest scales each model into the height band
the procedural trees occupy. And ground detail is budgeted: a modelled
tuft is twelve times the triangles of three blades, so the kit asks for
fewer of them.

Four bugs found by looking at the result rather than the tests:

- The start menu builds the world the ride goes on to use, and it was
  built without scenery, so a saved setting never reached the ride at
  all. It is now built with the scenery the rider picked.
- `scaled()` multiplied the placement matrix's translation by the model's
  size, so a tree at 800 m was drawn 7 km away: 96% of the scenery
  vertices were scattered outside the island and the woods were empty.
- The kit drew one model per kind of tree, so a wood was all firs. It now
  keeps the biome's mix of firs, leafies, bushes and rocks.
- Racing Kit's manifest called its trees "trees", a role nothing asks
  for, so that kit drew nothing at all once kinds were used.

A rider draws about 110k vertices where they drew 47k before. That is
the cost of the wood, measured, not estimated.

Part of #117.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
A screenshot of the scenery needed a rider at a particular wood, and
riding there took minutes of simulated pedalling and landed wherever
the ride happened to be. The server already supports joining part-way
along a route — a join's `resume` point, which the autosave uses — so
`?at=<metres>` exposes it: the rider starts at that distance, the camera
follows, and the shot is the same every time.

`sceneryShot.mjs` drives it with the settings a shot needs, so a before
and after can be taken at the same spot with the same camera.

Part of #117.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@RalfLeonFasler RalfLeonFasler changed the title feat: Draw the island's scenery from imported CC0 models feat: Fill the island's woods with imported CC0 models Nov 16, 2026
RalfLeonFasler and others added 10 commits November 16, 2026 14:24
#117)

Two silent failures in the importer, neither of which any test noticed:

The MTL beside an OBJ was looked for as `${source}m` — `tree.objm` — so it
was never found and every material-coloured OBJ imported pure white. The
test passed its MTL in by hand, so the path was never exercised. A model
that names materials it was not given now fails with their names
instead, since a white kit is the kind of mistake that ships.

`Kd` is a linear colour, the way a renderer multiplies it against light,
and the world draws in sRGB. Quaternius's leaf green is
`Kd 0.07 0.12 0.05`: believable once converted, almost black if taken as
sRGB. Colours are now converted on the way in.

`kitSheet.mjs` draws every model in a folder on one page, shaded with a
single sun, so a candidate pack can be judged by eye before any of it is
wired into the game.

Part of #117.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Fine packs are authored for a hero shot: Quaternius's trees are 1,400 to
2,900 triangles each, most of it branch tubes hidden inside the canopy.
A route places about 1,100 trees, so at full detail that is 1.5 million
triangles — thirteen times what the scenery costs now.

Grid-clustering merges every vertex within a cell into one, which keeps
the silhouette and the material colours and drops the detail that does
not show at range: 2,888 triangles become 486 at an 8% cell. It is pure
geometry, so it knows nothing about trees and works for any pack.

Part of #117.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…117)

A fine pack is authored for a hero shot. Quaternius's trees run to 2,900
triangles each, and a route places about 1,100 of them: 10.7 million
vertices for the near wood alone, which is enough to crash a browser
before the world has finished building.

So a kit may now ship a cheap twin per model, and the world builds the
wood twice: properly up close, and once more from the twins. The renderer
draws the near copy within the kit's `nearRange` and the far one beyond,
so a chunk crossing the split swaps one for the other in place.

The far pass runs `buildScenery` on the same seed, so it places the same
trees in the same spots at the same sizes; only the model drawn differs.
A test pins that down, because a far copy that drifted would make a wood
shimmer as it went past.

`build-kit.mjs` writes both files for a pack, and `decimate.mjs` makes
the twin by merging vertices within a grid cell — geometry only, so it
works for any pack. `indexKit` now treats `near` as a model reference
and `file`/`far` as file names, which is what they are: naming a file
as `far` used to be refused, and the kit silently fell back to the
biome's own trees.

Part of #117.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The island was one even scatter: trees thinned by a noise field, a village
rowed along the road. Riding it read as "trees on grass", not a forest.

`land/land.js` now decides what the land is for, as a pure function of the
map seed: where the woods stand (dense, trunks close enough to hide the
country), where the fields are (mown, hedged at the edge), and how a
village is laid out (short rows on both sides of the street, a lane
behind, and a green in the middle kept clear of houses).

`buildScenery` gathers the trees into the woods instead of scattering them
evenly: the same number of trees, in places that look like woods and not
like an orchard. A field keeps only its hedge, so there are open stretches
to ride through between the woods.

The village houses stand on lots rather than in a single row along the
road, so a village has a street front, back lanes and a square with the
church on it. Lots the ground cannot hold a house on —river bank, foot of
a hill, another road — are left empty, the way a real street has gaps.

Which woods, fields and villages a map has is the map's, not the view's:
the server can copy `land/land.js` and get the same answers, which is why
it holds no geometry and no randomness but the seed.

The valley world's triangle budget is raised from ~309k to under 620k and
the long-route budget from 12k to 18k triangles per km, with the tests
saying why: a wood is worth some triangles.

Part of #117.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…#117)

Kenney's town kit is a one-unit grid: a wall panel stands on the edge of
its tile, and a door is a child node moved into its wall. The importer
re-centred every model on its own footprint and ignored node transforms,
so assembled cottages came out as walls scattered round their middle and
doors standing in the room.

`importGlb` now places each mesh by its node's translation, rotation and
scale (after its parents'), and `origin: "keep"` leaves a part at the
pack's own origin. `build-kit.mjs` imports GLB packs as well as OBJ, and
`kitSheet.mjs` can draw each model from two sides.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…n kit (#117)

`tools/scenery/assemble.mjs` lays the Fantasy Town Kit's wall and roof
parts out tile by tile: eight cottages (one and two storeys, eaves or a
steep gable to the street, render or timber), a church with a tower and
a windmill, recoloured from the pack's teal and lavender to tile, slate
and cream. The pack's fountain, stalls, benches, lanterns, fences, hedges
and cart come as they are.

Every building also gets a far twin of 14 faces in its own colours, for
distance. The kit is CC0 like the pack; ASSETS-LICENSE.md lists it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Models scenery level now loads both kits. The first kit holding a
role answers for it, and every kit after the first has its model and
file names prefixed, so two packs' "tree" never read each other's file.
A kit's cheap twins are downloaded with its models, and a flora hands
out a building or prop by role, with its twin and its size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A village with the town kit has a street front of cottages behind front
gardens with fences or hedges, a lane of houses behind with trees in the
gardens, a paved square with a fountain, benches, market stalls and
lanterns, the church on its far side, and a windmill past the last house.
`scenery/village.js` lays it out in road coordinates from the seed; on
the inside of a bend a house that would stand in its neighbour is left
out with its garden.

Buildings are drawn from their models within 350 m and from their twins
beyond (`lod.js`). Scenery off builds the village exactly as before.

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

`buildCanopy` grows five-sided firs and small leafy blobs in the season's
greens on a jittered grid wherever the land says wood, between 60 and
420 m from a road. It is tested but not wired into the world build yet:
the next step is to call it when scenery is on and measure the cost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RalfLeonFasler added a commit that referenced this pull request Nov 16, 2026
RalfLeonFasler added a commit that referenced this pull request Nov 16, 2026
RalfLeonFasler added a commit that referenced this pull request Nov 16, 2026
RalfLeonFasler added a commit that referenced this pull request Nov 16, 2026
@RalfLeonFasler RalfLeonFasler changed the title feat: Fill the island's woods with imported CC0 models feat: Fill the island with woods, a high country and a market city Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant