Buildings have no doors, no windows and little detail: add openings, eaves, chimneys and variety

[mgcronin]

Description

The realistic world's buildings have no doors, no windows and almost no detail. On the owner's Pixel Tablet, during validation 0002 Part Z step Z9 (2026-09-23, main at 0530883), the first farmstead on the soak route (about 1,050 m) showed a house that is a brick box under a clay-tile gable and a barn that is a board box under corrugated iron. Neither has an opening on any face. The surfaces themselves passed Z9: brick, board, tile and iron all read correctly, the brick is the same scale on every wall, and the hedge reads as a hedge. What fails is the shape. A road user reads a building by its openings, and a brick box with no door looks like a store or a pumping station, not a farmhouse. The owner's verdict: "the buildings need more detail."

Parent Epic: #429 · related to #475 (layer 3) and #460 (settlements) · Component: apps/web/src/game/three-renderer.ts §STRUCTURE_STYLE, realistic-assets.ts §REALISTIC_STRUCTURE_SURFACES, realistic-budget.ts · Story Points: 8

What the code does today

• Every structure kind is built from numbers in three-renderer.ts §STRUCTURE_STYLE, as a block and a gable, set FOUNDATION_METRES into the ground. On the realistic rungs, each part wears one surface from REALISTIC_STRUCTURE_SURFACES:
  • house: brick + roof tiles
  • barn: planks + corrugated iron
  • church: stone + slate
  • shop row: brick + planks + slate
  • shed: corrugated iron twice
• The shapes are this repository's own because no ADR 0026 D-4 source publishes a whole country building. Poly Haven's "buildings" are urban facade kits of 118,000–175,000 triangles (Part Z, §"The realistic world on the tablet").
• ⚠️ The stylised house is not built from numbers: it is the Kenney pack model models/building-type-h.glb, whose own atlas may already carry openings. So this defect is mainly a realistic-world one, and the stylised barn, church, shop row and shed have the same bareness.
• ⚠️ Why there are no openings: nobody decided either way. settlements.ts and realistic-assets.ts mention neither doors nor windows, and no issue tracked them. They were not considered, not ruled out.
• Budget: the realistic structures are 15 meshes, one per surface per kind (REALISTIC_STRUCTURE_MESHES = 15, held by three-renderer.test.ts §"Quality ladder: shed resolution and scenery at 60 fps before dropping to 30 (owner ruling), plus #481's review follow-ups #482"). The realistic frame cap is REALISTIC_FRAME_TRIANGLES = 300 000, and REALISTIC_TRIANGLES' structure entry notes that a realistic structure is no heavier than the stylised one at the same place.
• Headroom, measured on the tablet the same day: the 20-minute soak (Z7) held the top realistic rung at 60 fps for all 20 minutes. It used 32–37 draw calls, GPU p90 8 ms, and thermal status stayed 0. So there is room, but not unlimited room: Z8 found the driver holding 310 MiB of GL memory against the 136 MiB texture estimate.

Research — how to add detail without buying an asset

1. Openings built from numbers, not photographed. ADR 0026 D-4's CC0 sources publish materials (brick, plank, glass-like surfaces), not window or door objects that fit this repository's shapes. So an opening is geometry:

• Window: a dark glass pane recessed about 8–10 cm into the wall, with a frame of four thin boxes, a sill that projects about 5 cm, and a lintel. That is about 60–80 triangles per window.
• Door: a recessed panel with a frame and a step. A barn gets a pair of large boarded doors. The church gets tall windows with arched heads (a few segments are enough at road distance). The shop row gets a shopfront: a wide pane at ground level with a fascia board above it, which the current shop-row block already approximates with its darker band.
• Glass: a MeshStandardMaterial with low roughness and a little metalness. In the realistic world that reflects the HDRI environment the scene already has (realistic-light.ts) at no texture cost. In the stylised world it is a flat dark colour.
• Frames and doors wear the existing planks surface, or a painted tint of it, which adds no texture.

2. Laid out in metres, facing the road. settlements.ts turns each building's +z face to the road. Openings go on that face first, with the long sides next and the gable end last. Use a grid in metres (for example, windows at 2.5–3 m spacing, sill at 0.9 m, second-floor sill at 3.6 m), the way the photographs are laid out in metres, so a window is the same size on every house. Vary which slots are filled from the same seeded hash settlements.ts already uses (seeded.ts), so a house keeps its windows from frame to frame and ride to ride. That keeps it deterministic and stateless, like everything else placed in the world.

3. The cheap detail that reads at road distance. These help as much as the openings do:

• Eaves and barge boards that overhang. The roof currently overhangs the walls by only 0.3 m, which reads as a lid on a box.
• A chimney on the house, and a ridge line on every roof.
• A plinth course (a darker band at the base) and fascia and gutters under the eaves.
• A porch or door canopy on some houses.
• Varied proportions: one storey or two, a lean-to on some barns, a slightly different pitch. Today every house is identical.
• Grounding: a darker ambient-occlusion band where the wall meets the ground, baked into vertex colour or as a gradient in the material. Without it a building looks placed rather than built. This is The riders float: ground them with contact shadows, and measure a real shadow map #426's contact-shadow argument applied to a wall.

4. Draw calls and triangles. Instance the openings like the parts already are. The recommendation is two new realistic belts, glass and frame/door timber, with doors wearing planks through its existing belt where possible. That takes REALISTIC_STRUCTURE_MESHES from 15 to at most 17, edited in the same PR as that test requires. It adds about 1,000–1,500 triangles per house, measured against REALISTIC_FRAME_TRIANGLES at the worst case the caps allow. If the far view needs it, draw openings only within the near band (as REALISTIC_NEAR_MESHES already caps trees), and state that distance.

5. Both worlds. The same openings go on the stylised built kinds (barn, church, shop row, shed) with vertex colour instead of materials, so the stylised world is not left behind. Whether the stylised house (the Kenney model) needs anything is for the owner to judge by eye.

Acceptance Criteria

• Every building has openings on its road-facing side: a house has a door and windows; a barn has large doors; a church has tall windows; a shop row has a shopfront. The shed may stay plain, stated as a decision. A test builds each kind's geometry and asserts openings exist on the +z face.
• Openings are recessed and framed: glass sits behind the wall plane, and frame and sill project from it. A test pins the recess and projection, so a flat decal that reads as a painted-on window is a red test.
• Openings are laid out in metres: the same window size on every house, sills at one height, and no opening crossing a wall edge, a floor line or the ground. A test checks every opening lies inside its wall.
• Which windows a house has is seeded and stateless: the same house shows the same windows every frame and every ride, using seeded.ts. Tested the way scatter.ts's hash is.
• Detail beyond openings: eaves that overhang, a chimney on the house, a ridge, a plinth, grounding at the base, and at least two proportions per kind, so the three farmsteads are not one house repeated.
• Budget: REALISTIC_STRUCTURE_MESHES and REALISTIC_TRIANGLES' structure entry are updated in this PR with the new counts. The worst-case frame stays under REALISTIC_FRAME_TRIANGLES. Glass adds no texture.
• The arrangement does not move: arrangement-unchanged.test.ts's digest is unchanged, because this changes what a building looks like, not where it stands.
• Browser gate: game.browser.spec.ts §"the realistic world" reads back a window's glass on a house's road-facing wall, and has a control: the same probe on a build with openings switched off must read brick.
• The stylised world gets openings on its built kinds too, and test:a11y and contrast gates are unchanged.
• Validation 0002 Part Z step Z9 is re-run on the tablet: does a farmstead read as a farmstead at 9 m/s; do the openings shimmer at a grazing angle; and a 30-second Z6 row with the new draw calls and GPU percentiles against today's (GPU p90 8 ms, 33–37 draw calls).

Out of scope

• Interiors, lit windows at night, or animated doors.
• Downloaded building models. ADR 0026 D-4 would need a source that publishes one, and none does; a new source is an ADR amendment, not this issue.
• Stone field walls: this route produces none, which is a Part Z coverage gap to record, not a building defect.