# 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.