From 07dd4b62a233f39b1eb36476b8a6fb10b3e457aa Mon Sep 17 00:00:00 2001 From: Pauljd Date: Sun, 8 Nov 2026 19:20:16 +0000 Subject: [PATCH] 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 --- .../tv/orbit/classic/arcade/ArcadeHome.kt | 4 +- .../tv/orbit/classic/arcade/ArcadeRepo.kt | 2 + .../java/tv/orbit/classic/arcade/GameLoop.kt | 15 +- .../orbit/classic/arcade/ArcadeInputTest.kt | 7 + docs/VERIFICATION-arcade-stage-c.md | 78 ++++++++++ docs/arcade-stage-c.md | 144 ++++++++++++++++++ 6 files changed, 247 insertions(+), 3 deletions(-) create mode 100644 docs/VERIFICATION-arcade-stage-c.md create mode 100644 docs/arcade-stage-c.md diff --git a/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeHome.kt b/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeHome.kt index b53652a4..46c795c8 100644 --- a/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeHome.kt +++ b/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeHome.kt @@ -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()) } diff --git a/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeRepo.kt b/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeRepo.kt index 29df5ac7..e13c9c17 100644 --- a/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeRepo.kt +++ b/android/app/src/main/java/tv/orbit/classic/arcade/ArcadeRepo.kt @@ -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 } } } diff --git a/android/app/src/main/java/tv/orbit/classic/arcade/GameLoop.kt b/android/app/src/main/java/tv/orbit/classic/arcade/GameLoop.kt index aa51b4ab..b20f1c69 100644 --- a/android/app/src/main/java/tv/orbit/classic/arcade/GameLoop.kt +++ b/android/app/src/main/java/tv/orbit/classic/arcade/GameLoop.kt @@ -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 diff --git a/android/app/src/test/java/tv/orbit/classic/arcade/ArcadeInputTest.kt b/android/app/src/test/java/tv/orbit/classic/arcade/ArcadeInputTest.kt index 529aa14d..c14cdcff 100644 --- a/android/app/src/test/java/tv/orbit/classic/arcade/ArcadeInputTest.kt +++ b/android/app/src/test/java/tv/orbit/classic/arcade/ArcadeInputTest.kt @@ -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)) + } } diff --git a/docs/VERIFICATION-arcade-stage-c.md b/docs/VERIFICATION-arcade-stage-c.md new file mode 100644 index 00000000..5a06290e --- /dev/null +++ b/docs/VERIFICATION-arcade-stage-c.md @@ -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 +``` diff --git a/docs/arcade-stage-c.md b/docs/arcade-stage-c.md new file mode 100644 index 00000000..ce983c35 --- /dev/null +++ b/docs/arcade-stage-c.md @@ -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:`), 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/.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 `.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:`. + - **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).