Files
OrbitTv/docs/arcade-stage-c.md
T
pauljdandClaude Opus 5.5 38986efda9 BumbleHive: native Kotlin game, Hard mode, one-time save carry-over
BumbleHive is rebuilt natively (arcade/hive), drawn on a Compose Canvas and
playing exactly as assets/orbithive/game.js did: the 200 levels, shooting,
bounces, landing, bursts and falls, swaps, Honeybombs, the ceiling timer,
scoring and stars, weighted aim, level pages, help and settings, Bumble's
Daily Bonus, both skins, the bee and flowers, the same beeps as tones and the
Barlow font. It uses the Arcade's pause menu, How to Play, result card,
Reduce motion, quiet ceiling and per-profile saves. The WebView game path and
ArcadeFlags.hiveProfileSaves are gone; assets/orbithive stays for the import
and a safe rollback.

Parity with game.js run under Node: 200/200 levels, 469/469 scripted
landings and 26/26 shot paths identical.

The old WebView save (localStorage orbithive-save-v1) is read once by a
hidden WebView on the same URL and kept as a read-only Household save any
profile can continue from as a copy; the key and the WebView data are never
written. Hard mode (on the title): ceiling x0.6 (min 5 s), 3 swaps, colours
every 10 levels, its own save.

33 Kotlin and 5 Node tests; 0 bytes allocated per frame in steady play.
Docs: docs/bumblehive-native.md, docs/VERIFICATION-bumblehive-native.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 21:29:33 +00:00

10 KiB

Orbit Arcade Stage C: the shared foundation

8 November 2026. Branch arcade-stage-c, from release-0.108 (0.110.5, 84b28b6), in its own worktree at /home/pauljd/Documents/OrbitTV/orbit-arcade. Local commits only: nothing pushed, nothing installed, no TV touched.

Built from the approved Stage B frames (orbit-tv/design/arcade/stage-b, frames 01-05, 20-23, 60-62), the Arcade code audit (audits/2026-11-08/ARCADE-CODE-AUDIT.md) and the cast rules (design/arcade/orbit-cast.md). No game engine and no new libraries were added.

What changed, in one list

  • Every profile has its own Arcade. Scores, settings, level progress and How to Play are saved per profile. The old box-wide scores become Household Records: a one-time, read-only copy with no name on it.
  • A run is saved however it ends. Game over, Leave, Exit, the sleep timer or switching profile: the score is kept (audit finding 3: Leave used to throw a record run away).
  • Holding OK acts once in Block Drop (hard drop) and Blast Off (place) (audit finding 8).
  • Pairs and Patience pause on Back with the shared pause menu instead of leaving at once.
  • Reduce motion now also covers the Comet Trail backdrop crossfade, the Pairs card turn, the Arcade's card zoom and BumbleHive (no shake or bobbing, and the daily wheel stops on its result).
  • Sound has one service and one ceiling. Orbit Quiet ident sound, night-quiet (11pm-7am) and Wind Down now hold every Arcade sound down, whatever the Arcade's own settings say (frame 05).
  • The new Arcade home (frames 01-05): Orbit Originals row, Classics shelf, left menu, the chosen game's panel with your top 3 and the Household record, High Scores, How to Play, Arcade Settings and Reset Progress.
  • Arcade for Kids in Family: Off, Kids-suitable games, or Choose games, behind the PIN. Kids see only the games allowed, hidden rather than greyed out. The old line "On: the games chosen for Kids" promised a choice that didn't exist (audit finding 1); it now says exactly what Kids sees.
  • BumbleHive is unchanged in play and in its 200 levels. It reads who's playing and their settings, reports each level to High Scores, stops its frame loop while hidden, has How to Play in its pause menu, Orbit's focus ring, its title line inside the TV-safe area, and Bumble's Daily Bonus with Not today.

Behind flags (off)

Flag Where What it does when on
ArcadeFlags.hiveProfileSaves arcade/ArcadeFlags.kt BumbleHive saves per profile (orbithive-save-v1:<profileId>), offers the old box-wide save as a copy to continue from, and lets Reset Progress clear a profile's BumbleHive levels.

Off (as built), BumbleHive keeps its one box-wide save exactly as before, and its level progress can't be reset from the Arcade (the Reset screen says why). Its scores still go to each profile's High Scores.

How saves work

Per-profile Arcade saves

  • File: filesDir/arcade/<profileId>.json, one per profile. The id is reduced to letters, digits, - and _.
  • Written whole through writeSafely (SafeWrite.kt): a temp file, flushed, then renamed over the old one. Writes run in order on one background thread; the screens use the in-memory copy straight away.
  • Schema version 1:
{ "schema": 1, "profileId": "p2abc9",
  "settings": { "music": true, "effects": true, "muteAll": false },
  "recent": ["Snake", "OrbMan"],
  "games": { "Snake": {
      "runs": [ { "score": 140, "at": 1762620000000, "detail": "Level 2" } ],
      "count": 0, "level": {}, "unlocks": [], "settings": { "music": false },
      "firstRunSeen": true, "howToEveryTime": false, "lastPlayed": 1762620000000,
      "resets": { "scores": 0, "levels": 0, "settings": 0 } } } }
  • Bounded: the top 10 runs per game (best first, by the game's own measure), recent games capped at 6.
  • How each game counts: Points (most): Star Chase, Comet Trail, Block Drop, Brick Break, Blast Off, BumbleHive. Fewest moves: Pairs (only a cleared board counts). Wins: Patience. Solved: Skydoku (and today's daily, per profile).
  • A per-game setting a profile hasn't chosen yet starts from the old box-wide one (snake_music, orb_man_sound, arcade_sounds), read only.
  • Missing file: the profile starts with an empty Arcade. Unreadable file: it is copied to <id>.json.unreadable for a look later, never read again, and the profile starts afresh. Nothing is ever thrown at the screen.
  • Reset Progress records when each reset happened (resets.scores, resets.levels, resets.settings).

Household Records

  • File: filesDir/arcade/household-records.json, taken once, the first time the new Arcade opens.
  • It copies these orbit_settings keys, each with its source key and the copy date: snake_best, block_drop_best, brick_break_best, pairs_best, patience_wins, orb_man_best, blast_best, skydoku_solved, skydoku_daily.
  • It belongs to no profile and shows no name: "from before profiles · read-only".
  • Once the file exists it is only ever read, even if it can't be (then the records show as "—"). It is never rewritten.
  • The old keys are never modified or deleted. No app code writes them any more: a unit test scans the sources for the old setters. (Rooms' one-time "Bring in from another room" bundle still carries those keys between boxes, as it did; it doesn't change Household Records, which were copied once.)

BumbleHive saves (behind hiveProfileSaves)

Superseded on branch arcade-bumblehive-native (8 November 2026): BumbleHive is native, saves are always per profile, the flag is gone, and the old box-wide save is carried over once as a read-only Household save. See docs/bumblehive-native.md.

  • assets/orbithive/hive-save.js decides which save the game plays with:
    • Flag off: orbithive-save-v1, as always.
    • Flag on, profile has a save: orbithive-save-v1:<profileId>.
    • Flag on, no save yet and the box-wide save has progress: the game opens on "Carry on from this TV's hive?" with Continue from it (a deep copy becomes the profile's own save, marked copiedFrom, copiedAt) or Start fresh (level 1, and it isn't asked again).
  • On that path the box-wide save is only ever read. Any profile can choose to continue from it, at any time their own save doesn't exist (for example after it was removed).
  • A profile's Reset level progress reaches BumbleHive as levelsResetAt; the page clears that profile's levels, stars and bests once and remembers it did. Honeybombs and the sound, guide and skin choices stay.

The shared framework (package tv.orbit.classic.arcade)

File What it holds
ArcadeStore.kt The save format, ranking, run recording, resets, the file store and Household Records
ArcadeRepo.kt The box's store (filesDir/arcade), its background writer, the Household snapshot, old-setting reads
ArcadeGames.kt ArcadeGame (id, title, mascot, kidsSuitable, settings, controls, content) and the 13 games; the Kids filter, pick and recent
ArcadeSession.kt The session state machine (Title, Play, Pause, Result) and the Reset screen's (four actions, Cancel first, who may reset what)
ArcadeInput.kt Remote key mapping, Back = pause, the OK (or Down) hold-repeat guard
ArcadeAudio.kt The one sound service (SoundPool cues, one MediaPlayer for music) and the quiet ceiling
GameLoop.kt ArcadeGameLoop (withFrameNanos, gated by pause, lifecycle and window focus) and PauseWhenHidden
ArcadePlay.kt What a game gets from the Arcade, and RunTracker (each run reported once, also when the screen goes away)
ArcadeHome.kt, ArcadePages.kt, ArcadeShared.kt, ArcadeArt.kt The home and its pages, the shared pause menu, How to Play card, confirm dialog, key caps, and card art from the cast library
ArcadeFlags.kt The off-by-default switch above

Changed elsewhere: OrbitArcade.kt (old menu removed; Comet Trail and the BumbleHive host), the seven other game files (thin wiring only), Profiles.kt (KidsArcade, arcadeMode, arcadeGames, travelling with Rooms sync), FamilySettings.kt (Arcade for Kids), MainActivity.kt (the Arcade full screen, Kids gate), EmbyConnectionScreen.kt (Wind Down state for the ceiling), assets/orbithive/ (game.js, hive-save.js, index.html).

Tests

See docs/VERIFICATION-arcade-stage-c.md for the numbers.

  • Kotlin (src/test/java/tv/orbit/classic/arcade): store, Household Records, session and reset, input guard, audio ceiling, Kids filter matrix, best-on-exit for each wrapped game, words and numbers.
  • JavaScript (src/test/js, run with tools/test-bumblehive.sh, Node 18+): the BumbleHive migration test plan and the real game.js run headless against a stub canvas.

Known gaps

  • No screen of the new Arcade has been seen running. There is no emulator or AVD on this PC and no TV was to be used, so the home, pages, dialogs and focus order are checked by the compiler and by reading the code against the frames, not by eye. The first look should be Paul's, on the box, before anything else.
  • No instrumented test ran (no emulator). The migration plan runs as Node tests instead, against the real hive-save.js and game.js.
  • The six real-time Classics keep their own pause and game-over panels; only Pairs and Patience use the shared pause menu. Moving them onto the shared Pause/Result components (frames 20, 21) is for Stage D.
  • Arcade Settings shows only what works today (Music, Effects, Mute all, Reduce motion, Backdrop). Frame 05's difficulty, auto-fire, aim help, hints, reduced impact sounds, reduce flashing, high contrast, larger text and calm mode wait for games that use them.
  • Each profile can reset only its own data, Kids included; there is no grown-up "reset someone else's" yet.
  • Restart level is in the pause menus (Pairs, Patience, BumbleHive's own), not on the Reset Progress page.
  • The four Originals other than BumbleHive are "Coming soon" cards.
  • Star Chase still synthesises its sounds with AudioTrack (now under the same ceiling); folding them into the SoundPool would mean rendering them to files.
  • Wind Down's ceiling follows Orbit's own windingDown state, which updates when the schedules do; it lifts at the next schedule refresh after Wind Down ends, not to the second.
  • Rooms' "Bring in" still overwrites the old box-wide score keys (audit finding 4). Household Records aren't affected because they were copied once; carrying per-profile Arcade saves between rooms is not built.
  • Skydoku's puzzle generation still runs on the main thread (audit, unmeasured on the box).