# Design This file fixes the parts that are easy to get wrong: the layout, the people, the motion, the camera and the picking maths. Use TypeScript, Vite and three.js. Units are metres. `y` is up. The sea is to the north, at negative `z`. ## Random numbers Use one small seeded generator everywhere, such as mulberry32, so a seed always gives the same result. Never call `Math.random` for anything a test checks. - The town uses the fixed seed 20261114, so it is the same on every visit. - The crowd uses the visit's seed: the number in `?seed=` if given, otherwise `crypto.getRandomValues` once at load. The start view, Santa's spot and every other person come from it, in that order. ## The town The town fills `x` from -150 to 150 and `z` from -100 to 100. | Zone | Where | Holds | | --- | --- | --- | | Sea | `z` < -62 | One plane, 120 by 60 segments, waves moved in its vertex shader, a lighter band near the shore. | | Beach | -62 to -48 | Sand, deck chairs, parasols with striped tops, a lifeguard hut. | | Promenade | -48 to -40 | Paving, lamp posts every 12 m, benches, a row of stalls with striped awnings. | | Pier | `x` 36 to 44, `z` -48 to -96 | Planks on posts, a kiosk at the end. People may stand on it. | | Streets | `z` -40 to 100 | Streets 8 m wide centred on `x` = -132, -88, -44, 0, 44, 88, 132 and on `z` = -36, 8, 52, 96. Between them are blocks 36 m square. | | Square | `x` -40 to 40, `z` -32 to 4 (two blocks and the street between) | Open plaza, a round fountain 8 m wide at `(0, -14)`, a stage, stalls round the edge, bunting across. | | Fairground | `x` 48 to 128, `z` 12 to 48 (two blocks and the street between) | A big wheel 26 m high that turns once every 60 s, a carousel 10 m wide that spins, a helter-skelter, stalls, bunting. | | Houses | every other block, and the blocks west and east of the town's edge streets | Houses 6 to 10 m wide and 5 to 9 m to the eaves along the block's four edges, with a pitched roof each; an open courtyard with trees in the middle. | Trees, benches and lamp posts are scattered on open ground with a gap of at least 2 m from paths people walk. Bunting is strung between poles: a sagging line with small triangles of the palette's bright colours. ### Drawing the town cheaply - Houses are two instanced meshes: walls (a box) and roofs (a triangular prism), each with a colour per instance. Trees are a trunk mesh and a crown mesh, both instanced. Stalls, parasols, chairs, benches and lamps are instanced too. - Stripes on awnings and parasols are vertex colours in the geometry. - All bunting is one merged geometry with vertex colours. - Ground zones are one merged mesh with vertex colours. ### The walkable map Build a grid of 1 m cells over the town. A cell is walkable if it is street, square, fairground, beach, promenade, pier or courtyard, and nothing stands on it: no house, ride, stall, fountain, tree trunk, bench or lamp. People only stand on walkable cells, and a walker's whole path stays on them. ## Palette | Use | Colours | | --- | --- | | Grass and courtyards | `#b9d7a8` | | Streets | `#e8dccb` | | Square | `#f1d9c6` | | Promenade | `#e6c9b0` | | Sand | `#f3e3b5` | | Sea, deep to shallow | `#6fa8c9`, `#a9d6e5` | | Walls | `#f6efe3`, `#f2e2cf`, `#e9d8c4`, `#dde6ea`, `#f4dede` | | Roofs | `#d98c7a`, `#c97b63`, `#8fa9c9`, `#e0b26a`, `#9fb7a0` | | Tree crowns | `#8fc08a`, `#7cae79`, `#a9cf8f`; trunks `#9c7b5d` | | Bright (awnings, bunting, rides) | `#e76f51`, `#f4a261`, `#2a9d8f`, `#8ecae6`, `#ffffff`, `#cdb4db` | | Clothes | `#e57373`, `#f4a261`, `#8ecae6`, `#219ebc`, `#90be6d`, `#ffffff`, `#cdb4db`, `#b5838d`, `#6d6875`, `#457b9d`, `#2a9d8f`, `#f28482`, `#84a59d`, `#3d405b`, `#e9c46a`, `#c1121f` | | Trousers | `#3d405b`, `#2f3b52`, `#6d6875`, `#84a59d`, `#b08968`, `#1d3557` | | Skin | `#f1c27d`, `#e0ac69`, `#c68642`, `#8d5524`, `#ffdbac`, `#a0662f` | | Hair | `#2b1d14`, `#4a3426`, `#7a5230`, `#c9a66b`, `#d9d9d9`, `#a33b20` | Background and fog: `#f7efe6`. Sun: warm white from the south-west, high. ## Santa Santa is drawn in the same simple blocky style as everyone else, at the same size. His look: - A coat, trousers and a pointed hat in `target_coat` (default `#c62828`, red). - The pointed hat has a band round the bottom and a bobble at the tip in `target_trim` (default `#ffffff`, white). - A beard in `target_trim`, and hair in `target_trim`. - No bag, no sun hat, no skirt. Any skin colour. - Scale between 0.92 and 1.05, the middle of the adult range below. Never a child's size and never taller than the tallest adults. The challenge is the crowd, not a tiny target. Before choosing anyone's clothes, drop every clothes colour within 60 (straight distance in 0-255 RGB) of `target_coat`. Then make decoys, so no single feature gives Santa away: - 2% of people wear exactly `target_coat`, with no pointed hat in it and no beard. - 1.5% wear a pointed hat in `target_coat`, with a coat of another colour and no beard. - 1.5% have a beard in `target_trim` (grandads), with a coat of another colour. - 0.5% wear `target_coat` and the pointed hat in it, with no beard. - About 6% of everyone else wear a pointed hat in an ordinary clothes colour, and 6% have a beard in a hair colour. Nobody but Santa has all three: the coat, the pointed hat in the coat's colour, and the trim-coloured beard. ## People ### Parts One instanced mesh per part, each shared by all people, with `frustumCulled` off. A person faces `+z` in their own space before turning. | Part | Shape | Where (own space, before scaling) | Colour | | --- | --- | --- | --- | | Legs | two boxes 0.14 x 0.8 x 0.16 in one geometry, at `x` ±0.09 | hip at `y` 0.8 | trousers | | Skirt | cone frustum, 0.5 high, radius 0.28 at the bottom | `y` 0.35 to 0.85 | clothes | | Torso | box 0.42 x 0.62 x 0.24 | `y` 0.8 to 1.42 | coat | | Left arm, right arm | box 0.1 x 0.55 x 0.12 | shoulders at `x` ±0.27, `y` 1.38 | coat | | Head | sphere radius 0.13 | `y` 1.56 | skin | | Hair | half sphere radius 0.14 | `y` 1.58 | hair | | Hat | brim and crown in one geometry | `y` 1.66 | clothes | | Bag | box 0.3 x 0.36 x 0.14 | `y` 1.1, `z` -0.19 | bag | | Pointed hat | cone radius 0.135, 0.34 high, tipped back 0.45 rad, with a band (cylinder radius 0.155, 0.06 high, at `y` 1.64) and a bobble (radius 0.05) at the tip, in one geometry | base at `y` 1.62 | hat; band and bobble in `target_trim`, from a per-vertex `aTrim` attribute mixed in the fragment shader | | Beard | front half of a sphere radius 0.12, lower part only, stretched 1.25 high | centre `y` 1.5, `z` 0.05 | beard | | Shadow | flat disc radius 0.35, 25% dark, no depth write | `y` 0.02 | - | A part a person does not have (skirt, hat, bag, pointed hat, beard) is scaled to zero for them. About 30% wear a skirt instead of showing legs below 0.35 m, 25% a hat, 18% a bag. Scale is 0.85 to 1.12; children are 1% at 0.6 to 0.7. That is 12 draw calls for the crowd, the limit. ### Per-person data Leave `instanceMatrix` as identity and give each mesh two instanced attributes, the same buffers shared by every part: - `aPlace` (vec4): `x`, `z`, heading in radians, scale. - `aMotion` (vec4): kind, phase (0 to 1), speed (m/s), path length (m). Colours go in `instanceColor`. Inject the motion into the material with `onBeforeCompile` on a `MeshLambertMaterial`, with a uniform `uTime` and an integer uniform naming the part. ### Motion Write it once in GLSL and once in TypeScript, and test that they agree. `t` is seconds since load. `P = phase * 2π`. | Kind | Share | Where the person is | Pose | | --- | --- | --- | --- | | 0 stand | 40% | at `(x, z)`; the whole body leans `0.05 sin(1.3t + P)` about its forward axis | arms hang | | 1 walk | 35% | `u = fract(t·speed/(2·len) + phase)`, `s = u < 0.5 ? 2u : 2 - 2u`; at `(x, z) + (s - 0.5)·len·(sin h, cos h)`; facing `h` while `u < 0.5`, else `h + π`; bob `0.03 abs(sin(4·speed·t + P))` | legs swing `±0.5 sin(4·speed·t + P)`, arms the other way at 0.4 | | 2 wave | 15% | at `(x, z)` | right arm raised sideways to `2.6 + 0.3 sin(6t + P)` radians | | 3 hop | 10% | at `(x, z)`, raised `0.25 max(0, sin(5t + P))` | both arms up at 2.8 radians | Walkers have speed 0.8 to 1.4 and path length 3 to 14. A walker's path is chosen so both ends and every metre between are walkable. The body centre, used by the test hook and the miss mark, is the person's position raised `1.1 × scale`, plus any bob or hop. ## Where Santa stands Pick a random walkable cell, and try again until all of these hold: - No house within 2 m. - Nothing hides Santa from the camera. Keep a list of everything tall, each as a footprint and a height: houses (to the ridge), trees (the crown's width), stalls, parasols, the fountain, the stage, the big wheel (26 m, its whole width), the carousel, the helter-skelter, the kiosk and the lifeguard hut. Walk from Santa toward the camera, `d` = 0 to 45 m in 0.5 m steps along `+z`; the sight line is at height `1.8 + d × tan 55°`. If any footprint within 0.4 m of that point is taller than the line, try another spot. (Testing only the 55° line is enough: the camera glides to Santa on a win, so Santa is in the middle of the screen then.) - No tree within 3 m, and no ride, stall or parasol within 4 m. - Not on the pier's last 10 m (too easy) and not in the sea. - At least 50 m from the start view's centre. No other person is placed within 1 m of Santa's spot, and no walker's path comes within 1 m of it. Santa is kind 0, or kind 1 with speed 0.7 and length 3; the seed chooses. ## The camera - A `PerspectiveCamera` with a 30° vertical field of view, looking north, tilted 55° below the horizon. It never turns. - It looks at a point `(tx, 0, tz)` on the ground from distance `D` along its view direction. `D` runs from 20 (a person about 120 px tall on an 800 px high screen) to 380 (the whole town). The start view is `D = 70` at a random walkable spot. - Panning moves `(tx, tz)` so the ground under the pointer stays under it. Clamp `tx` to -150..150 and `tz` to -100..100. - Zooming changes `D` by a factor of `1.0015^deltaY` for the wheel, or the ratio of finger spread for a pinch, then moves `(tx, tz)` so the ground point under the pointer, or between the fingers, stays put. - The canvas has `touch-action: none` and every pointer is handled with Pointer Events, so mouse, pen and touch share one path. ## Picking On a pick at canvas point `(px, py)`, at the `t` of the last drawn frame: 1. Make a ray from the camera through the point (`Raycaster.setFromCamera`). 2. For every person, find their position now by the motion table. Treat them as an upright cylinder of radius `0.3 × scale` from `y = 0` to `1.7 × scale`. Test the ray against it: in the ground plane, the ray's closest approach to the cylinder's axis must be within the radius, at a height within the cylinder. Keep the hit with the smallest distance along the ray. 3. If nothing is hit, take the person whose body centre projects nearest to `(px, py)`, if it is within 14 CSS px for a mouse or 24 for touch. 4. Nobody hit is a pick on empty ground. This is a loop over ten thousand people once per click, which takes well under a millisecond. Do not use three.js's instanced mesh raycast: it does not know about the motion in the shader. ## Win - Stop the timer at the pick's time. - Glide `(tx, tz)` to Santa and `D` to 24 over 1.2 s with an ease-out. - Draw a pulsing ring, radius 0.8, on the ground at Santa's feet. - `elapsedMs` is the time since Start plus `miss_penalty × 1000` for each miss. ## Frame rate - `renderer.setPixelRatio(Math.min(devicePixelRatio, 2))`, lowered by 0.25 at a time, to no lower than 1, after three seconds below 30 fps. - Shadows, when `shadows` is on: one directional light, a 2048 shadow map covering the camera's view, cast by houses, trees and rides, received by the ground. People never cast map shadows; they have the disc. - Count draw calls with `renderer.info.render.calls` with `autoReset` off, reset once a frame.