Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion docs/booth-runbook.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ The setup does the following:
- It keeps the Mac awake and turns it back on after a power cut.
- It turns off the screen saver, automatic updates and crash dialogs.

Booth mode itself runs fullscreen and ignores the menu's **Quit Game**. A game nobody has touched for 90 seconds goes back to the hub's attract screen, and so does a lost game, after a thank-you card for the player ([details](builds.md#run-it-at-a-booth)).
Booth mode itself runs fullscreen and ignores the menu's **Quit Game**. A game nobody has touched for 90 seconds goes back to the hub's attract screen (an idle hub drops whatever the last visitor had selected), and so does a lost game, after a thank-you card for the player ([details](builds.md#run-it-at-a-booth)).

## Every morning

Expand Down
8 changes: 5 additions & 3 deletions docs/builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,9 @@ open -a "Hoppy’s Adventure Arcade.app" --args -- --booth --route=heroes_vs_vil
- **Fullscreen.** The game starts fullscreen without changing the saved settings.
- **Booth QR code.** A scannable, branded CodeRabbit link stays in the top-right corner on every route in booth mode. The provided code points to `https://coderabbit.link/ato26-ad?qr=1`, which identifies QR scans for attribution. To change the destination, regenerate `hoppys-adventure-arcade/Assets/booth/booth_qr.png` from the repository root with `swift hoppys-adventure-arcade/tools/booth/generate_qr.swift` and pass the output path and URL as optional arguments, then rebuild the game.
- **How-to-play cards.** Each visitor's first entry into a game opens its how-to-play card. Its pages turn by themselves every 7 seconds (28 seconds at most), so it starts play on its own and never holds off the idle reset. A new visitor starts whenever the attract route opens. See [main-menu.md](main-menu.md#how-to-play-cards).
- **Idle reset.** After 90 seconds with no keyboard, mouse, touch or controller input, any game returns to the attract route. That is the hub, whose rotating previews act as the attract screen, unless `--attract=` names `beatem_up` or `runner`, the other menus that start their own music.
- **Idle reset.** After 90 seconds with no keyboard, mouse, touch or controller input, any game returns to the attract route. That is the hub, whose rotating previews act as the attract screen, unless `--attract=` names `beatem_up` or `runner`, the other menus that start their own music. An idle hub drops the selection the last visitor left (a focused **Endless Runner** button keeps Hoppy's 3D portrait rendering), so it sits as a fresh hub would.
- **Endless Runner warm-up.** The runner compiles every shader it will draw before play, and macOS keeps no shader cache between launches, so that used to happen behind the black veil when the runner opened: seconds on a fast GPU, minutes on a slow one, with the main loop (and the heartbeat) stopped. It now runs on the hub, after 5 seconds with no input, one small step per frame (`scenes/runner/warmup/background_warm.gd`), so the hub keeps drawing and beating while it compiles and the runner then opens in about two seconds. Any input pauses the pass; it resumes on the next idle hub. `game.log` gets a `RUNNER WARMUP` line per pass with the time each stage took.
- **Frame rate.** A rendered game caps itself at 60 fps (`AppRouter.MAX_FPS`); physics already ticks at 60. On a 60 Hz display nothing changes; a 120 or 144 Hz panel no longer draws, and spins for vsync, twice as often for the same picture.
- **Game over.** A lost game doesn't offer unlimited retries. A player gets `--retries=<n>` retries (default 0); after that, the game shows no retry screen. Instead a **GAME OVER** card thanks the player, shows their score and counts down six seconds, then the attract route opens for the next player. The count starts again whenever the attract route opens. Every game takes part: Heroes vs. Villains, Code City Brawl, the platformer levels and the Endless Runner. Without `--booth`, every game keeps its own retry screen.
- **No quitting from the menu.** The menu's **Quit Game** does nothing in booth mode; staff close the window (Cmd+Q, Alt+F4).
- **Launch route.** `--route=<name>` opens a route at launch (`heroes_vs_villains`, `code_city_brawl`, `bay_area_blitz`, `orbital_ops`, `enchanted_repo`, `runner`, `platformer`, `beatem_up`, `hub`), with or without `--booth`. An unknown name logs an error and opens the hub.
Expand All @@ -59,7 +61,7 @@ python3 tools/booth/soak.py --minutes 10 --godot "$GODOT" # a quick run of t
```

- **The soak.** The game runs with `--soak=<minutes>` (wall-clock time). It visits every route in turn and stays `--soak-dwell=<seconds>` (default 30) on each with nobody playing, counted from when the route has opened. `--soak-routes=hub,heroes_vs_villains` keeps it to those routes; the hub is always included. `--soak-cycles=<n>` ends it after n full passes, if that comes first: `--soak=30 --soak-cycles=1` is a quick frame-rate probe of every route. A soak turns off the idle return and the game-over card, ignores `--route`, and writes no session log, so its visits never count as booth sessions.
- **Frame rate.** Every 5 seconds the game appends a CSV row for the current route: frames per second, median, 99th-percentile and worst frame times, and the engine's memory and object counts. At the end it prints a table per route: the share of frames slower than 16.7 ms (60 fps) and 33.3 ms (30 fps), percentiles capped at the worst frame, and the worst loading hitch. Run it fullscreen (`--booth`) on the booth hardware to measure at the booth resolution; headless frame times mean nothing.
- **Frame rate.** Every 5 seconds the game appends a CSV row for the current route: frames per second (at most the game's 60 fps cap), median, 99th-percentile and worst frame times, and the engine's memory and object counts. At the end it prints a table per route: the share of frames slower than 16.7 ms (60 fps) and 33.3 ms (30 fps), percentiles capped at the worst frame, and the worst loading hitch. Run it fullscreen (`--booth`) on the booth hardware to measure at the booth resolution; headless frame times mean nothing.
- **Leak check.** At the end of each hub visit the game records its object, node, orphan-node and resource counts and prints `SOAK hub <n>`. It compares the second visit with the last, since the first warms caches. Debug builds also compare static memory, which release builds don't report. Growth beyond small limits makes the game exit 1. A route that won't open, or results that can't be written, make it exit 2.
- **Resident memory.** `soak.py` samples the process's memory with `ps` every 30 seconds (`--rss-every`) into `rss.csv`, and again at each `SOAK hub <n>` line. It compares the second hub visit with the last, once there are three, and fails above 25% growth (`--max-rss-growth`). It also fails a game that exits without a verdict, and stops a run that outlasts its time by 10 minutes (`--grace`). Each run gets its own folder under `soak-results/` (`--out`), holding the game's CSV and summary, `game.log` and `rss.csv`. macOS and Linux.

Expand Down Expand Up @@ -93,4 +95,4 @@ python3 tools/build/export_game.py --preset macOS --smoke

## What the exports leave out

`tests/`, every `*/dev/*` preview scene and the `capture_*.gd` screenshot scripts. JSON manifests are included explicitly because the game reads them with `FileAccess`. Upgrading Godot means updating `godot.lock.json` (version, SHA-512 values from the release's `SHA512-SUMS.txt`) along with `project.godot`.
`tests/`, every `*/dev/*` preview scene and the `capture_*.gd` screenshot scripts; the repo-only art and audio nothing loads: every pack's `sources/` masters and `frames/` renders (also `.gdignore`d, so Godot never imports them), the pack preview and clip-sheet PNGs (except `bay-area-preview.png`, which the platformer menu shows), duplicate `.wav`/`.mp3`/`.ogg` encodings of music and sounds the game plays from other files, and the Blender kit self-test model. All four presets share one `exclude_filter`; `tools/build/test_exports.py` checks they stay identical and keep what the game loads. JSON manifests are included explicitly because the game reads them with `FileAccess`. Upgrading Godot means updating `godot.lock.json` (version, SHA-512 values from the release's `SHA512-SUMS.txt`) along with `project.godot`.
2 changes: 2 additions & 0 deletions docs/endless-runner.md
Original file line number Diff line number Diff line change
Expand Up @@ -986,6 +986,8 @@ The standard backend smoke reported `RUNNER SMOKE: FAIL (3 failures / 127 checks
- **Nothing finalizes during play.** `Prewarm.finish()` joins every worker and runs every deferred package (boss art, glyph atlas, texture installs). `RunnerAudio.bind()` calls it inside `runner_game`'s `_ready`, behind the route veil. After the runner menu it is a no-op (`finish_ms` 0); a directly launched run pays about 1.4 s there instead of one package per frame after the run starts.
- **GPU warm-up.** `scenes/runner/warmup/gpu_warmup.gd` runs once per process in each context: from the runner menu's `_ready`, and from `bind()` in the first game (the menu's lights and Hoppy are not the game's). It mounts every runtime visual in batches, using the contract scene paths and hooks: pickups and tools with the collected state and bursts, each hazard kind with every variant plus hit and clear, bosses with FX, the pursuer, Hoppy's roll and hurt, the HUD canvas shaders, and the corridor mid-turn. The live Hoppy also wears every aura and the shield for the character batch. Copies sit at Hoppy and 5-55 m down the track, so every light combination an item meets on its way in is drawn. Each batch is drawn with `RenderingServer.force_draw(false)`, once under the live lights and once with a corridor-wide omni light. The frames are never presented; headless skips it.
- gl_compatibility compiles a variant on first draw and another when an object is first omni-lit. Those compiles caused first-sight and first-grab stalls (about 40-80 ms each).
- The warm-up is stepped (`GpuWarmup.begin()` + `step()`: one batch copy build or one forced draw per step; `run()` spends every step at once). `scenes/runner/warmup/background_warm.gd`, added by AppRouter, spends one step per rendered frame on a 256x144 offscreen viewport with the runner's environment and light types while the hub has had no input for 5 s, so the booth's heartbeat keeps beating between compiles and the runner menu then opens in about 2 s instead of 10 (M5 Max; macOS has no shader cache across launches, so this is every launch). The menu and the game still run their own pass as the safety net; with the programs already compiled theirs is mostly the stage build. Each pass prints one `RUNNER WARMUP` line with build, draw and the slowest batches.
- Per frame, the corridor skips its legacy scroll/clock uniforms and the 36 rack and pillar instance transforms while the starship hides that geometry (`legacy_visible`); a hazard rewrites its batch poses only when a piece is animated or a pivot was shown or hidden (`_batches_dirty`); the pursuer visual does not animate while hidden; Hoppy's orbit glyphs and data trail are written only while visible, with the bone indices and billboard basis cached per frame; `PanelFinish` finds its game host once; the pursuit alert looks for `RunnerAudio` twice a second rather than every frame.
- BaseMaterial3D, ParticleProcessMaterial and code-built shaders free their program with their last user, so a new spark system recompiled every time (75 ms) once earlier ones were gone. The warm-up keeps every material it drew for the process lifetime, and its state lives in Engine metadata so it survives the menu script unloading. It is released at application exit.
- RunnerGame `queue_free()`s its graybox environment in the same frame as `bind()`. Its fog-less, glow-less WorldEnvironment and second Sun would make every warm draw compile variants play never uses, so the warm-up detaches that doomed node first.
- Nothing between the forced draws runs the frame's transform flush or its deferred calls. Before each batch is drawn, the warm-up calls `force_update_transform()` on every Node3D under the host. Without that, parts a hook moved after mounting (hazard pieces, boss FX, the posed corridor, Hoppy's shells) are drawn at stale, often off-screen, positions. After it shows the live Hoppy's auras, the warm-up runs one process tick on Hoppy so the orbit glyphs become visible, as they do in play. Label3D builds its mesh in a deferred call, so the batch labels are drawn empty. The warm-up keeps one copy of each distinct label setup, placed before it enters the tree. It draws those copies in a call deferred behind their own mesh updates. That call runs in the same message-queue flush, before the next frame is presented. Measured before this fix: the first pickup tag and the first aura each cost about 8 ms of compile in a run, and 35-50 ms under load.
Expand Down
2 changes: 1 addition & 1 deletion docs/main-menu.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ The hub shows every game as a tile, three columns by two rows, so a visitor star

- Scene-local showcase, behind the grid: idle previews 0–12 every 9 seconds; 1.2-second fades. Focusing or hovering a tile shows that game's previews, cycling every 3 seconds with 0.6-second fades where it has more than one: each platformer level holds its own plate, the Endless Runner cycles four in-game stills (corridor, power-ups, a jump over a hazard, boss), Code City Brawl its three districts and Heroes vs. Villains its three stages. The groups come from the catalog (`showcase_controller.GROUPS`).
- Focus exit waits 2 seconds, then restores the idle index and remaining dwell. Modals pause showcase timing. Parallax continues behind overlays.
- At most two preview nodes exist. During a fade, requests coalesce to the latest selection; the outgoing node is freed before another fade begins. Each preview is a `CanvasGroup`, so a fade blends the flattened scene instead of letting its parallax layers show through each other. Preview textures are loaded once and kept, so transitions never read from disk.
- At most two preview nodes exist. During a fade, requests coalesce to the latest selection; the outgoing node is freed before another fade begins. A preview with two plates (Orbital Ops, Enchanted Repo) is a `CanvasGroup`, so a fade blends the flattened scene instead of letting its parallax layers show through each other; a single opaque plate cannot ghost, so the other previews are plain `Node2D`s and skip the group's full-screen offscreen pass. A preview's slow drift ends after 9 s and its `_process` stops with it. Preview textures are loaded once and kept, so transitions never read from disk.
- Layout recenters on viewport resize (not every frame). Tiles and menu buttons grow 5% around their centre on hover/focus and keep that scale when their container re-sorts; the grid's 20 px gaps are wider than that growth, so grown tiles never cover their neighbours. Modals draw above a grown tile.
- The UI uses a 1280×720 reference with expanding viewport coverage and centered composition. Backgrounds fill taller and wider windows. Pixel scenery uses nearest filtering.
- AppRouter validates known routes and prevents duplicate transitions. Tiles open their games directly. The menu does not modify gameplay.
Expand Down

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

This file was deleted.

Loading
Loading