Orbit Arcade Stage C: review fixes and verification

- Back on an Arcade page returns to Play Games; on Play Games it goes back to Orbit.
- A game opening while How to Play is still closing isn't paused at once; only
  going out of sight pauses.
- Lint: remember no longer returns Unit; the repo singleton's application
  context is marked as intended.
- docs/arcade-stage-c.md and docs/VERIFICATION-arcade-stage-c.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-08 19:20:16 +00:00
co-authored by Claude Opus 5.5
parent 11a9a57687
commit 07dd4b62a2
6 changed files with 247 additions and 3 deletions
@@ -88,7 +88,7 @@ internal fun OrbitArcade(modifier: Modifier, onPlaying: (Boolean) -> Unit, onExi
val context = LocalContext.current
val profile = Profiles.current ?: return
val repo = remember { ArcadeRepo.get(context) }
remember { ArcadeLook.load(OrbitSettings(context)) }
remember { OrbitSettings(context).also(ArcadeLook::load) }
var data by remember(profile.id) { mutableStateOf(repo.store.load(profile.id)) }
val latestData by rememberUpdatedState(data)
val household = remember { repo.household }
@@ -140,6 +140,8 @@ internal fun OrbitArcade(modifier: Modifier, onPlaying: (Boolean) -> Unit, onExi
}
}
// Back on one of the Arcade's pages goes to Play Games; on Play Games it goes back to Orbit TV (MainActivity).
androidx.activity.compose.BackHandler(page != ArcadePage.Play) { page = ArcadePage.Play }
val pick = remember(visible) { arcadePick(visible) }
val recent = recentVisible(data.recent, visible)
var chosen by remember { mutableStateOf(recent.firstOrNull() ?: pick ?: visible.firstOrNull()) }
@@ -24,6 +24,8 @@ internal class ArcadeRepo private constructor(context: Context) {
fun legacyFlag(key: String, default: Boolean) = runCatching { legacy.getBoolean(key, default) }.getOrDefault(default)
companion object {
// Holds only the application context, which lives as long as the app.
@android.annotation.SuppressLint("StaticFieldLeak")
@Volatile private var made: ArcadeRepo? = null
fun get(context: Context): ArcadeRepo = made ?: synchronized(this) { made ?: ArcadeRepo(context).also { made = it } }
}
@@ -22,14 +22,25 @@ internal fun rememberArcadeShown(): Boolean {
return focused && state.isAtLeast(Lifecycle.State.RESUMED)
}
/** Pauses a running game when the Arcade goes out of sight or loses the remote, so nobody loses a game to a pop-up. */
/**
* Pauses a running game when the Arcade goes out of sight or loses the remote, so nobody loses a game to a pop-up.
* Only a change from shown to hidden pauses: a game that opens while a closing dialog (How to Play) still holds the
* window's focus isn't paused at once; its loop simply waits ([ArcadeGameLoop]) until the focus comes back.
*/
@Composable
internal fun PauseWhenHidden(alive: Boolean, pause: () -> Unit) {
val shown = rememberArcadeShown()
val latest by rememberUpdatedState(pause)
LaunchedEffect(shown) { if (!shown && alive) latest() }
val wasShown = androidx.compose.runtime.remember { booleanArrayOf(false) }
LaunchedEffect(shown) {
if (shouldPauseOnHide(wasShown[0], shown, alive)) latest()
if (shown) wasShown[0] = true
}
}
/** Pause only when a game that was on screen goes out of sight while it's still going. */
internal fun shouldPauseOnHide(wasShown: Boolean, shown: Boolean, alive: Boolean) = wasShown && !shown && alive
/**
* The shared frame loop: [onFrame] gets each frame's time and the time since the previous one, from the second frame of
* each run (the first only sets the clock, so time spent paused or hidden never arrives as one big step). [onStart] runs
@@ -45,4 +45,11 @@ class ArcadeInputTest {
assertTrue(loopRuns(paused = false, alive = true, shown = true))
assertFalse(loopRuns(true, true, true)); assertFalse(loopRuns(false, false, true)); assertFalse(loopRuns(false, true, false))
}
@Test fun onlyGoingOutOfSightPausesNotStartingBehindADialog() {
assertFalse(shouldPauseOnHide(wasShown = false, shown = false, alive = true))
assertTrue(shouldPauseOnHide(wasShown = true, shown = false, alive = true))
assertFalse(shouldPauseOnHide(wasShown = true, shown = false, alive = false))
assertFalse(shouldPauseOnHide(wasShown = true, shown = true, alive = true))
}
}
+78
View File
@@ -0,0 +1,78 @@
# Orbit Arcade Stage C: verification (8 November 2026)
Branch `arcade-stage-c` from `release-0.108` (0.110.5, `84b28b6`), worktree `/home/pauljd/Documents/OrbitTV/orbit-arcade`.
Version name and code are unchanged (0.110.5-own-issues, 280): this is a foundation for review, not a release.
Nothing was pushed or installed, and no TV was touched. What changed and why: `docs/arcade-stage-c.md`.
## Checks
The same Gradle run (`assembleDebug assembleRelease testDebugUnitTest lintDebug`, with orbit-tv's `.tooling`) was done on
untouched `release-0.108` first, then on this branch.
| | release-0.108 | arcade-stage-c |
|---|---|---|
| Build (debug and release) | passed | passed |
| Kotlin unit tests | 723 run, 24 skipped, 0 failed | **772 run, 24 skipped, 0 failed** (49 new) |
| BumbleHive tests (`tools/test-bumblehive.sh`, Node 24) | none | **23 passed, 0 failed** |
| Lint | 0 errors, 77 warnings | **0 errors, 76 warnings** (one fewer: the Arcade logo is now used; no new warning types) |
| Debug APK | 51,622,213 bytes | 51,885,071 bytes (**+262,858**) |
| Release APK | 47,527,828 bytes | 47,646,299 bytes (**+118,471**, +0.25%) |
The same 24 tests are skipped as before (the hand-run replays).
### New tests
- `ArcadeStoreTest` (9): round trip with schema 1; top 10 best first; a left run still counts; moves, wins and solves
only when finished; separate files per profile and nothing `.writing` left; missing, unreadable, schema-less and
empty files start afresh without throwing (unreadable kept as `.unreadable`); partly damaged saves keep what they
can; each reset clears only its part and records when; recent list; safe file names.
- `HouseholdRecordsTest` (5): copy with source key and date; the old values only read; taken once and never rewritten
(same bytes and modified time); an unreadable snapshot left alone; empty box; **a source scan proves no app code
writes the old score keys any more**.
- `ArcadeSessionTest` (8): first-run How to Play; Back pauses and never leaves mid-game; pause choices; result; reset
flow with Cancel chosen first; the four actions separate; who may reset what (never someone else's, Kids included;
BumbleHive levels only with profile saves on).
- `ArcadeInputTest` (6): key map; held OK acts once, including a second "down" without a release; moves still repeat;
focus loss forgets held keys; loop gating; pause only on going out of sight, not on starting behind a dialog.
- `ArcadeAudioTest` (4): the ceiling matrix (quiet .4, Wind Down .25); nothing ever louder than the ceiling across
every combination; mute, music, effects and the game's own switch.
- `KidsArcadeTest` (7): grown-ups see all 13; Off / Kids-suitable / Chosen matrix (Blast Off and Skydoku hidden for
Kids-suitable); older profiles keep their meaning; profile JSON round trip and pre-Stage C JSON; pick and recent
follow the filter; the Family line says what Kids really sees.
- `BestOnExitTest` (4): each wrapped game from a real mid-game state to its save on Leave (Comet Trail, Star Chase,
Brick Break, Block Drop, Blast Off keep their points; Pairs, Patience, Skydoku count only when finished); a run is
reported once.
- `ArcadeWordsTest` (6): score wording, nameless Household lines, "Played" labels, top 3, reset wording, settings
starting from the old box-wide choice.
- `hive-save.test.js` (11): **the migration test plan**: flag off writes nothing new; flag on offers without touching;
copy equals the household save; the household save's SHA-256 is unchanged after every operation; copy idempotent;
start fresh; fallback when the copy is deleted; corrupt, empty and partial input; no household save; a profile's
level reset clears only its own save, once; odd profile ids; failing storage never throws.
- `hive-game.test.js` (12): the real `game.js`, headless: title and safe area (info line at y 672 of 720, limit 684);
pause menu with How to Play returning to pause; run start, score and end reports, including leaving and restarting;
a lost level reported finished; Daily Bonus with Not today keeping the spin; Reduce motion (wheel stops at once, no
shake); sound ceiling (0.02 → 0.008 at 0.4, silent at 0); hidden stops frames and pauses; focus ring yellow over
navy; flag off uses the old save only; flag on offers, copies and never touches the old save; runs with no bridge.
## Not checked
- **No emulator or AVD on this PC**, so no instrumented test ran and **no screen of the new Arcade has been seen
running**. The home, pages, dialogs and remote focus order are checked only by the compiler and against the frames.
- Nothing ran on the Xiaomi: no frame times, memory or sound levels. Proposed commands for Paul are below.
## Proposed Xiaomi baseline (for Paul to approve; not run)
Read-only `dumpsys` captures while Paul drives the remote; nothing is installed or pressed by adb. To be run on this
build once installed and, for comparison, on 0.110.5.
```bash
ADB=/opt/android-sdk/platform-tools/adb; D=192.168.0.252:5555; P=tv.orbit.classic; OUT=~/Documents/OrbitTV/audits/arcade-baseline-$(date +%Y%m%d-%H%M); mkdir -p "$OUT"
$ADB connect $D
# Each point: reset frame stats, Paul uses the screen for about 60 s (5 min for the late level), then capture.
snap() { $ADB -s $D shell dumpsys meminfo $P > "$OUT/$1-meminfo.txt"; $ADB -s $D shell "dumpsys meminfo | grep -iE 'orbit|webview|sandboxed'" > "$OUT/$1-processes.txt"; $ADB -s $D shell dumpsys gfxinfo $P framestats > "$OUT/$1-gfxinfo.txt"; }
$ADB -s $D shell dumpsys gfxinfo $P reset; snap 0-before-arcade # Orbit Home, before opening the Arcade
$ADB -s $D shell dumpsys gfxinfo $P reset; snap 1-hive-title # BumbleHive title
$ADB -s $D shell dumpsys gfxinfo $P reset; snap 2-hive-level1 # playing level 1
$ADB -s $D shell dumpsys gfxinfo $P reset; snap 3-hive-late-5min # 5 minutes at the latest unlocked level
$ADB -s $D shell dumpsys gfxinfo $P reset; snap 4-after-exit # back on Orbit Home, 30 s after leaving the Arcade
```
+144
View File
@@ -0,0 +1,144 @@
# 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:
```json
{ "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`)
- `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).