Spot Santa
A 3D find-the-person game in the browser: a seaside festival town of 10,000+ animated people, all made from code. Spot Santa fast.
This is a browser game spec on Spekkr, published by dwrtz. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.
- Spec
dwrtz/spot-santa- Version
- 0.1.0
- Published by
- dwrtz
- Updated
- 14 Nov 2026
Build this spec
Build the spec at https://spekkr.com/dwrtz/spot-santa/start.md.
Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.
Published by dwrtz.
What does the result look like?
What can I customize?
Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.
What do I get?
-
spec.mdRequirements and acceptance checks.Spot Santa
What this builds
A 3D hidden-person game that runs in a web browser. A seaside town is holding a festival, and more than ten thousand people are out in it: walking the promenade, queueing at stalls, dancing in the square, waving from the beach. One of them is Santa, the same size as everyone else. The player drags and zooms around the town, spots Santa, clicks or taps him, and gets their time.
Everything is made from code when the page loads: the town, the people, the sea and the portrait of Santa. The build ships no image, model, texture or font files.
Read
spekkr.inputs.jsonfirst.target_nameis the name shown everywhere the spec says Santa.target_coatis the colour of his coat, trousers and pointed hat, andtarget_trimthe colour of his beard and the hat's band and bobble.crowd_sizeis how many people there are.miss_penaltyis the seconds added for a wrong pick.shadowsturns the sun's shadows on or off.design.mdgives the town, the people, the camera and the picking maths.tasks.mdgives the order to build in.Out of scope
- Accounts, a server, or a shared leaderboard. The best time is kept in the browser.
- Sound.
- Levels or more than one person to find.
- Any character from another game or book, or a copy of one's look. Santa is drawn in this spec's own simple style: see "Santa" in
design.md.
Requirements
Each requirement has an id. Tests name the id they cover.
R1. A page with no asset files
- A static site: one HTML page and the JavaScript built from TypeScript. It runs from any static host and from a local server.
- The built site holds no image, model, texture, audio or font files. Shapes are made from three.js geometry or from vertices written in code. Patterns, such as stripes on an awning, are vertex colours or made in a shader.
- The page needs WebGL. Without it, it shows one sentence saying so.
Accept when: the built folder holds only
.html,.jsand.cssfiles (and source maps if the bundler writes them), and the game runs from it.R2. The town
- A seaside festival town, made from a fixed seed so it is the same every visit and a player can learn it. The layout is in
design.md. - It holds at least: the sea with moving waves, a beach, a promenade along the shore, a pier, streets of houses with pitched roofs, a central square with a fountain, a fairground with a big wheel that turns and a carousel that spins, rows of stalls with striped awnings, bunting strung between poles, trees, benches and lamp posts.
- Colours are soft and warm (see the palette in
design.md), lit by one sun and a sky light.
Accept when: a screenshot at the start view shows houses, people and at least one festival structure, and one at full zoom-out shows the sea, the beach, the pier, the square and the fairground.
R3. The crowd
crowd_sizepeople. If the input is below 10,000 or is not a whole number, use 10,000.- Every person is drawn with instancing: one instanced mesh per body part, shared by all people. Drawing the crowd takes at most 12 draw calls however many people there are.
- People differ in height, build, skin, hair, hat, top, trousers or skirt, and whether they carry a bag, wear a pointed hat or have a beard.
- Every person moves. Some walk back and forth along a short path, some stand and sway, some wave, some dance or hop. The motion runs on the GPU from a time value; the CPU does not update ten thousand matrices a frame.
- People stand on open ground only: never inside a building, in the sea or on a roof.
Accept when: the test hook in R9 reports a person count of at least 10,000, the crowd's draw calls are 12 or fewer, and two screenshots a second apart show people in different poses.
R4. Santa hides somewhere new every visit
- Each visit picks a new random seed for the crowd. Santa's spot, the people around him and the start view come from it.
- Santa stands on open ground where the camera can see him: rules in
design.md. - Santa sways or walks slowly, like a normal person, so he does not stand out by keeping still.
- Santa is normal-sized: the same height as the adults around him, never shrunk and never a giant. The difficulty comes from the crowd.
- No other person has Santa's full look. Some wear the coat colour, some a pointed hat in it, some a beard in the trim colour, and a few the coat and the hat, but never all three together.
- The page accepts
?seed=with a whole number, to replay a crowd exactly.
Accept when: ten loads without
?seed=put Santa in at least eight different places, two loads with the same?seed=put Santa in the same place, a check of every person's look finds Santa's full look exactly once, and Santa's scale is within the adult range.R5. The camera
- The camera looks down on the town at a fixed slant (see
design.md) and never turns. The player pans and zooms. - Desktop: drag with the mouse to pan, the wheel or a trackpad pinch to zoom toward the pointer, and the arrow keys or WASD to pan, plus and minus to zoom.
- Phone and tablet: one finger to pan, two fingers to pinch-zoom around the point between them. The page does not scroll or zoom as a page.
- Panning stops at the town's edges. Zoom runs from close enough that a person is about 120 pixels tall on a 800 pixel high screen, out to the whole town.
- A press that moves less than 6 pixels and lasts under 500 ms is a pick (R6). Anything else is a pan and picks no one.
Accept when: a drag moves the view and picks no one, a wheel turn zooms around the pointer, a pinch zooms on a touch screen emulated in the browser, and the view cannot be dragged off the town.
R6. Picking a person
- A click or tap picks the person under it. The pick uses where each person is at that moment, after their animation, so a walking person is picked where they are drawn. The maths is in
design.md. - If the pick is Santa, the player wins (R8).
- If the pick is someone else, a small mark pops up there with "Not
target_name", the timer jumps forward bymiss_penaltyseconds, and the game goes on. - A pick on empty ground does nothing.
Accept when: a click at Santa's projected screen position wins, a click on another person shows the miss mark and adds the penalty, and a click on empty sea does neither.
R7. Start and timer
- First an intro card: the game's title, "Find
target_name", a portrait of Santa drawn live from the same model code, and a Start button. The town shows behind it. - Start hides the card and starts the timer. The timer shows minutes, seconds and tenths, such as
1:07.4, in a corner. - A small portrait of Santa stays in another corner while playing, so the player remembers who to look for.
Accept when: the timer reads
0:00.0until Start, counts after it, and a penalty adds exactlymiss_penaltyseconds.R8. Winning
- The timer stops. The camera glides to Santa and zooms in, and a ring marks him.
- A card shows "You found
target_name" and the time, the best time on this browser, and "New best" when it is one. - The best time is kept in
localStorageunder the keyspotsanta.bestas milliseconds. Only a lower time replaces it. - A share line, such as
I found Santa in 0:42.3 among 10,000 people at the seaside festival. Can you beat me? https://..., with a Copy button. Where the browser offers the share sheet, a Share button uses it too. - "Play again" starts a new visit with a new seed.
Accept when: after a win the card shows the time,
spotsanta.bestholds it, a slower second win leaves it, a faster one replaces it, and the share line holds the time, the person count and the page's address.R9. A test hook
When the address holds
?test=1, the page setswindow.__spotsantato an object with:ready: true once the first frame of the town has been drawn.seed: the crowd seed.personCount: how many people there are.crowdDrawCalls: draw calls used for the crowd in the last frame.fps: frames a second, averaged over the last two seconds.state:"intro","playing"or"won".elapsedMs: the timer's value, penalties included.targetIndex: Santa's index among the people.scaleOf(index): that person's scale, so a test can check Santa's height.targetWorld(): Santa's current position,{x, y, z}, centre of the body.screenOf(index): where that person's body centre is now on the page, as{x, y}in CSS pixels from the canvas's top left.start(): the same as pressing Start.setView({tx, tz, D}): moves the camera asdesign.mddescribes, with the same clamping as R5. Any field left out keeps its value.view(): the camera's current{tx, tz, D}.holdTime(seconds): holds the animation clock at that time, so a test can take a screenshot and know where everyone is drawn;holdTime(null)lets it run again. The game timer is not affected.looks(): every person's look as an array of{coat, hat, beard}:coatas#rrggbb,hatas the pointed hat's#rrggbb,"sun"for a sun hat ornull, andbeardtrue for a beard intarget_trim, so a test can check R4.
- Without
?test=1,window.__spotsantais not set.
Accept when: a Playwright test uses the hook to check R3, R4, R5, R6 and R8, and, with the clock held, the pixel at
screenOf(targetIndex)in a screenshot is close totarget_coat(which shows the shader and the TypeScript agree on where Santa is).R10. Speed
- On a mid-range laptop (integrated graphics from 2022 or later) the game holds at least 45 frames a second at 1280 by 800, and at least 30 on a mid-range phone, with
crowd_sizeat 10,000. - The device pixel ratio is capped at 2. If the frame rate stays under 30 for three seconds, the page lowers the pixel ratio by a quarter step, down to 1.
- The whole scene, crowd and town together, takes at most 80 draw calls a frame with
shadowsoff, and 160 with it on. - The page is playable within 3 seconds of loading on such a laptop.
Accept when: the hook's draw counts are under the limits, and the hook's
fpson the test machine is recorded in the README. A software renderer, such as headless Chromium with SwiftShader, is far slower than any real laptop; there the check is only that the game runs and every frame finishes.Definition of done
- A Playwright test, run against the built site in headless Chromium, checks every "Accept when" that a browser can check, and passes.
- A README says how to run it locally, how to build, how to run the tests, and the frame rate measured on a real machine.
- The page's title and copy never name any other game or character.
# Spot Santa ## What this builds A 3D hidden-person game that runs in a web browser. A seaside town is holding a festival, and more than ten thousand people are out in it: walking the promenade, queueing at stalls, dancing in the square, waving from the beach. One of them is Santa, the same size as everyone else. The player drags and zooms around the town, spots Santa, clicks or taps him, and gets their time. Everything is made from code when the page loads: the town, the people, the sea and the portrait of Santa. The build ships no image, model, texture or font files. Read `spekkr.inputs.json` first. `target_name` is the name shown everywhere the spec says Santa. `target_coat` is the colour of his coat, trousers and pointed hat, and `target_trim` the colour of his beard and the hat's band and bobble. `crowd_size` is how many people there are. `miss_penalty` is the seconds added for a wrong pick. `shadows` turns the sun's shadows on or off. `design.md` gives the town, the people, the camera and the picking maths. `tasks.md` gives the order to build in. ## Out of scope - Accounts, a server, or a shared leaderboard. The best time is kept in the browser. - Sound. - Levels or more than one person to find. - Any character from another game or book, or a copy of one's look. Santa is drawn in this spec's own simple style: see "Santa" in `design.md`. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. A page with no asset files - A static site: one HTML page and the JavaScript built from TypeScript. It runs from any static host and from a local server. - The built site holds no image, model, texture, audio or font files. Shapes are made from three.js geometry or from vertices written in code. Patterns, such as stripes on an awning, are vertex colours or made in a shader. - The page needs WebGL. Without it, it shows one sentence saying so. Accept when: the built folder holds only `.html`, `.js` and `.css` files (and source maps if the bundler writes them), and the game runs from it. ### R2. The town - A seaside festival town, made from a fixed seed so it is the same every visit and a player can learn it. The layout is in `design.md`. - It holds at least: the sea with moving waves, a beach, a promenade along the shore, a pier, streets of houses with pitched roofs, a central square with a fountain, a fairground with a big wheel that turns and a carousel that spins, rows of stalls with striped awnings, bunting strung between poles, trees, benches and lamp posts. - Colours are soft and warm (see the palette in `design.md`), lit by one sun and a sky light. Accept when: a screenshot at the start view shows houses, people and at least one festival structure, and one at full zoom-out shows the sea, the beach, the pier, the square and the fairground. ### R3. The crowd - `crowd_size` people. If the input is below 10,000 or is not a whole number, use 10,000. - Every person is drawn with instancing: one instanced mesh per body part, shared by all people. Drawing the crowd takes at most 12 draw calls however many people there are. - People differ in height, build, skin, hair, hat, top, trousers or skirt, and whether they carry a bag, wear a pointed hat or have a beard. - Every person moves. Some walk back and forth along a short path, some stand and sway, some wave, some dance or hop. The motion runs on the GPU from a time value; the CPU does not update ten thousand matrices a frame. - People stand on open ground only: never inside a building, in the sea or on a roof. Accept when: the test hook in R9 reports a person count of at least 10,000, the crowd's draw calls are 12 or fewer, and two screenshots a second apart show people in different poses. ### R4. Santa hides somewhere new every visit - Each visit picks a new random seed for the crowd. Santa's spot, the people around him and the start view come from it. - Santa stands on open ground where the camera can see him: rules in `design.md`. - Santa sways or walks slowly, like a normal person, so he does not stand out by keeping still. - Santa is normal-sized: the same height as the adults around him, never shrunk and never a giant. The difficulty comes from the crowd. - No other person has Santa's full look. Some wear the coat colour, some a pointed hat in it, some a beard in the trim colour, and a few the coat and the hat, but never all three together. - The page accepts `?seed=` with a whole number, to replay a crowd exactly. Accept when: ten loads without `?seed=` put Santa in at least eight different places, two loads with the same `?seed=` put Santa in the same place, a check of every person's look finds Santa's full look exactly once, and Santa's scale is within the adult range. ### R5. The camera - The camera looks down on the town at a fixed slant (see `design.md`) and never turns. The player pans and zooms. - Desktop: drag with the mouse to pan, the wheel or a trackpad pinch to zoom toward the pointer, and the arrow keys or WASD to pan, plus and minus to zoom. - Phone and tablet: one finger to pan, two fingers to pinch-zoom around the point between them. The page does not scroll or zoom as a page. - Panning stops at the town's edges. Zoom runs from close enough that a person is about 120 pixels tall on a 800 pixel high screen, out to the whole town. - A press that moves less than 6 pixels and lasts under 500 ms is a pick (R6). Anything else is a pan and picks no one. Accept when: a drag moves the view and picks no one, a wheel turn zooms around the pointer, a pinch zooms on a touch screen emulated in the browser, and the view cannot be dragged off the town. ### R6. Picking a person - A click or tap picks the person under it. The pick uses where each person is at that moment, after their animation, so a walking person is picked where they are drawn. The maths is in `design.md`. - If the pick is Santa, the player wins (R8). - If the pick is someone else, a small mark pops up there with "Not `target_name`", the timer jumps forward by `miss_penalty` seconds, and the game goes on. - A pick on empty ground does nothing. Accept when: a click at Santa's projected screen position wins, a click on another person shows the miss mark and adds the penalty, and a click on empty sea does neither. ### R7. Start and timer - First an intro card: the game's title, "Find `target_name`", a portrait of Santa drawn live from the same model code, and a Start button. The town shows behind it. - Start hides the card and starts the timer. The timer shows minutes, seconds and tenths, such as `1:07.4`, in a corner. - A small portrait of Santa stays in another corner while playing, so the player remembers who to look for. Accept when: the timer reads `0:00.0` until Start, counts after it, and a penalty adds exactly `miss_penalty` seconds. ### R8. Winning - The timer stops. The camera glides to Santa and zooms in, and a ring marks him. - A card shows "You found `target_name`" and the time, the best time on this browser, and "New best" when it is one. - The best time is kept in `localStorage` under the key `spotsanta.best` as milliseconds. Only a lower time replaces it. - A share line, such as `I found Santa in 0:42.3 among 10,000 people at the seaside festival. Can you beat me? https://...`, with a Copy button. Where the browser offers the share sheet, a Share button uses it too. - "Play again" starts a new visit with a new seed. Accept when: after a win the card shows the time, `spotsanta.best` holds it, a slower second win leaves it, a faster one replaces it, and the share line holds the time, the person count and the page's address. ### R9. A test hook - When the address holds `?test=1`, the page sets `window.__spotsanta` to an object with: - `ready`: true once the first frame of the town has been drawn. - `seed`: the crowd seed. - `personCount`: how many people there are. - `crowdDrawCalls`: draw calls used for the crowd in the last frame. - `fps`: frames a second, averaged over the last two seconds. - `state`: `"intro"`, `"playing"` or `"won"`. - `elapsedMs`: the timer's value, penalties included. - `targetIndex`: Santa's index among the people. - `scaleOf(index)`: that person's scale, so a test can check Santa's height. - `targetWorld()`: Santa's current position, `{x, y, z}`, centre of the body. - `screenOf(index)`: where that person's body centre is now on the page, as `{x, y}` in CSS pixels from the canvas's top left. - `start()`: the same as pressing Start. - `setView({tx, tz, D})`: moves the camera as `design.md` describes, with the same clamping as R5. Any field left out keeps its value. - `view()`: the camera's current `{tx, tz, D}`. - `holdTime(seconds)`: holds the animation clock at that time, so a test can take a screenshot and know where everyone is drawn; `holdTime(null)` lets it run again. The game timer is not affected. - `looks()`: every person's look as an array of `{coat, hat, beard}`: `coat` as `#rrggbb`, `hat` as the pointed hat's `#rrggbb`, `"sun"` for a sun hat or `null`, and `beard` true for a beard in `target_trim`, so a test can check R4. - Without `?test=1`, `window.__spotsanta` is not set. Accept when: a Playwright test uses the hook to check R3, R4, R5, R6 and R8, and, with the clock held, the pixel at `screenOf(targetIndex)` in a screenshot is close to `target_coat` (which shows the shader and the TypeScript agree on where Santa is). ### R10. Speed - On a mid-range laptop (integrated graphics from 2022 or later) the game holds at least 45 frames a second at 1280 by 800, and at least 30 on a mid-range phone, with `crowd_size` at 10,000. - The device pixel ratio is capped at 2. If the frame rate stays under 30 for three seconds, the page lowers the pixel ratio by a quarter step, down to 1. - The whole scene, crowd and town together, takes at most 80 draw calls a frame with `shadows` off, and 160 with it on. - The page is playable within 3 seconds of loading on such a laptop. Accept when: the hook's draw counts are under the limits, and the hook's `fps` on the test machine is recorded in the README. A software renderer, such as headless Chromium with SwiftShader, is far slower than any real laptop; there the check is only that the game runs and every frame finishes. ## Definition of done - A Playwright test, run against the built site in headless Chromium, checks every "Accept when" that a browser can check, and passes. - A README says how to run it locally, how to build, how to run the tests, and the frame rate measured on a real machine. - The page's title and copy never name any other game or character. -
design.mdThe town, the people, the motion, the camera and the picking maths.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.
yis up. The sea is to the north, at negativez.Random numbers
Use one small seeded generator everywhere, such as mulberry32, so a seed always gives the same result. Never call
Math.randomfor 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, otherwisecrypto.getRandomValuesonce at load. The start view, Santa's spot and every other person come from it, in that order.
The town
The town fills
xfrom -150 to 150 andzfrom -100 to 100.Zone Where Holds Sea z< -62One 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 x36 to 44,z-48 to -96Planks on posts, a kiosk at the end. People may stand on it. Streets z-40 to 100Streets 8 m wide centred on x= -132, -88, -44, 0, 44, 88, 132 and onz= -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 x48 to 128,z12 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 #b9d7a8Streets #e8dccbSquare #f1d9c6Promenade #e6c9b0Sand #f3e3b5Sea, deep to shallow #6fa8c9,#a9d6e5Walls #f6efe3,#f2e2cf,#e9d8c4,#dde6ea,#f4dedeRoofs #d98c7a,#c97b63,#8fa9c9,#e0b26a,#9fb7a0Tree crowns #8fc08a,#7cae79,#a9cf8f; trunks#9c7b5dBright (awnings, bunting, rides) #e76f51,#f4a261,#2a9d8f,#8ecae6,#ffffff,#cdb4dbClothes #e57373,#f4a261,#8ecae6,#219ebc,#90be6d,#ffffff,#cdb4db,#b5838d,#6d6875,#457b9d,#2a9d8f,#f28482,#84a59d,#3d405b,#e9c46a,#c1121fTrousers #3d405b,#2f3b52,#6d6875,#84a59d,#b08968,#1d3557Skin #f1c27d,#e0ac69,#c68642,#8d5524,#ffdbac,#a0662fHair #2b1d14,#4a3426,#7a5230,#c9a66b,#d9d9d9,#a33b20Background 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 intarget_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_coatand 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
frustumCulledoff. A person faces+zin 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.09hip at y0.8trousers Skirt cone frustum, 0.5 high, radius 0.28 at the bottom y0.35 to 0.85clothes Torso box 0.42 x 0.62 x 0.24 y0.8 to 1.42coat Left arm, right arm box 0.1 x 0.55 x 0.12 shoulders at x±0.27,y1.38coat Head sphere radius 0.13 y1.56skin Hair half sphere radius 0.14 y1.58hair Hat brim and crown in one geometry y1.66clothes Bag box 0.3 x 0.36 x 0.14 y1.1,z-0.19bag 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 y1.64) and a bobble (radius 0.05) at the tip, in one geometrybase at y1.62hat; band and bobble in target_trim, from a per-vertexaTrimattribute mixed in the fragment shaderBeard front half of a sphere radius 0.12, lower part only, stretched 1.25 high centre y1.5,z0.05beard Shadow flat disc radius 0.35, 25% dark, no depth write y0.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
instanceMatrixas 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 withonBeforeCompileon aMeshLambertMaterial, with a uniformuTimeand an integer uniform naming the part.Motion
Write it once in GLSL and once in TypeScript, and test that they agree.
tis seconds since load.P = phase * 2π.Kind Share Where the person is Pose 0 stand 40% at (x, z); the whole body leans0.05 sin(1.3t + P)about its forward axisarms 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); facinghwhileu < 0.5, elseh + π; bob0.03 abs(sin(4·speed·t + P))legs swing ±0.5 sin(4·speed·t + P), arms the other way at 0.42 wave 15% at (x, z)right arm raised sideways to 2.6 + 0.3 sin(6t + P)radians3 hop 10% at (x, z), raised0.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 height1.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
PerspectiveCamerawith 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 distanceDalong its view direction.Druns from 20 (a person about 120 px tall on an 800 px high screen) to 380 (the whole town). The start view isD = 70at a random walkable spot. - Panning moves
(tx, tz)so the ground under the pointer stays under it. Clamptxto -150..150 andtzto -100..100. - Zooming changes
Dby a factor of1.0015^deltaYfor 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: noneand 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 thetof the last drawn frame:- Make a ray from the camera through the point (
Raycaster.setFromCamera). - For every person, find their position now by the motion table. Treat them as an upright cylinder of radius
0.3 × scalefromy = 0to1.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. - 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. - 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 andDto 24 over 1.2 s with an ease-out. - Draw a pulsing ring, radius 0.8, on the ground at Santa's feet.
elapsedMsis the time since Start plusmiss_penalty × 1000for 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
shadowsis 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.callswithautoResetoff, reset once a frame.
# 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.
-
tasks.mdBuild tasks in order, each with a check.Tasks
Work in this order. Finish a task's check before starting the next.
- Set up. A Vite project in TypeScript with three.js and Playwright. Read
spekkr.inputs.jsoninto one settings module. Add the seeded generator. Check:npm run buildwrites a folder with only.html,.jsand.cssfiles (R1). - The town (R2). Ground zones, sea, beach, promenade, pier, houses, square, fairground, stalls, bunting, trees, lamps and benches, and the walkable map, from the fixed seed, drawn as in "Drawing the town cheaply". Check: a screenshot at
D = 380shows every zone, and the scene's draw calls are within R10's limit before any people are added. - The camera (R5). Pan, zoom toward the pointer, pinch, keys, clamping. Check: a Playwright test drags, wheels and pinches (with an emulated touch screen) and the view moves as R5 says.
- The crowd (R3). The parts, the per-person data, the motion in GLSL and in TypeScript. Use
crowd_size. Check: the hook reports at least 10,000 people and 12 or fewer crowd draw calls; a unit test checks that the TypeScript motion matches the shader's formulas at several times for every kind. - Santa (R4). The look, the decoys, the spot rules,
?seed=. Check:looks()finds Santa's full look once, his scale is in the adult range, ten loads give at least eight spots, and one seed gives one spot. - Picking (R6). The ray against cylinders, the fallback, the miss mark, the penalty. Check: clicking
screenOf(targetIndex)wins; clicking another person'sscreenOfshows the miss mark and addsmiss_penalty; clicking the sea does nothing. - Intro, timer, win, best time and share (R7, R8). The portrait is drawn live with the same parts, from the front, with no image file. Check: the R7 and R8 acceptance tests pass.
- Speed (R10). Pixel ratio cap and step-down, shadows option, draw counts. Check: the hook's draw counts are within the limits; record
fpson a real machine in the README. - Finish. README, the whole Playwright suite against
npm run buildandnpm run preview. Check: every item under "Definition of done" inspec.mdis true.
# Tasks Work in this order. Finish a task's check before starting the next. 1. **Set up.** A Vite project in TypeScript with three.js and Playwright. Read `spekkr.inputs.json` into one settings module. Add the seeded generator. Check: `npm run build` writes a folder with only `.html`, `.js` and `.css` files (R1). 2. **The town (R2).** Ground zones, sea, beach, promenade, pier, houses, square, fairground, stalls, bunting, trees, lamps and benches, and the walkable map, from the fixed seed, drawn as in "Drawing the town cheaply". Check: a screenshot at `D = 380` shows every zone, and the scene's draw calls are within R10's limit before any people are added. 3. **The camera (R5).** Pan, zoom toward the pointer, pinch, keys, clamping. Check: a Playwright test drags, wheels and pinches (with an emulated touch screen) and the view moves as R5 says. 4. **The crowd (R3).** The parts, the per-person data, the motion in GLSL and in TypeScript. Use `crowd_size`. Check: the hook reports at least 10,000 people and 12 or fewer crowd draw calls; a unit test checks that the TypeScript motion matches the shader's formulas at several times for every kind. 5. **Santa (R4).** The look, the decoys, the spot rules, `?seed=`. Check: `looks()` finds Santa's full look once, his scale is in the adult range, ten loads give at least eight spots, and one seed gives one spot. 6. **Picking (R6).** The ray against cylinders, the fallback, the miss mark, the penalty. Check: clicking `screenOf(targetIndex)` wins; clicking another person's `screenOf` shows the miss mark and adds `miss_penalty`; clicking the sea does nothing. 7. **Intro, timer, win, best time and share (R7, R8).** The portrait is drawn live with the same parts, from the front, with no image file. Check: the R7 and R8 acceptance tests pass. 8. **Speed (R10).** Pixel ratio cap and step-down, shadows option, draw counts. Check: the hook's draw counts are within the limits; record `fps` on a real machine in the README. 9. **Finish.** README, the whole Playwright suite against `npm run build` and `npm run preview`. Check: every item under "Definition of done" in `spec.md` is true.
- Set up. A Vite project in TypeScript with three.js and Playwright. Read
Is it for me?
- Kind
- browser game
- Platforms
- web
- Tools
- TypeScript, Vite, three.js, Playwright
What does it need?
- Agent permissions
- shell, network
- Commands it runs
npx playwright install chromium
What changed?
- 0.1.014 Nov 2026First version.
For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.