Architecture
Dice Chess TV has three layers: a TypeScript core with no platform dependencies, the React Native for Vega app, and Fortemate’s open-source rules engine.
flowchart TB
subgraph shell ["native/"]
input("<b>useRemoteInput.ts</b><br/>D-pad · OK · Back · Menu")
screen("<b>screen.ts</b><br/>screen reducer")
store[("<b>mmkvStore.ts</b><br/>synchronous saves")]
board("<b>Board.tsx</b><br/>draws the board")
audio("<b>sound.ts · music.ts</b><br/>effects, music")
end
subgraph core ["src/core/"]
nav("<b>boardInput.ts</b><br/>cursor jumps")
game("<b>game.ts · bot.ts · snapshotStore.ts</b><br/>turns, opponents, saves")
view("<b>boardView.ts · moveAnimation.ts</b><br/>squares, slides")
cues("<b>cues.ts · danger.ts</b><br/>cues, king danger")
end
engine[["<b>@fortemate/dicechess-engine</b><br/>legal turn tree · applyMove · playable dice"]]
input --> screen
screen --> nav & game
store --> game
board --> view
audio --> cues
game & cues --> engine
class core accent
Remote keys enter at the top, through useRemoteInput.ts. Every other arrow points from a module to the one it relies on, and all of them point down: the shell relies on the core and the core on the engine, and nothing in src/core/ reaches back into native/.
The Three Layers
Section titled “The Three Layers”1. The Pure TypeScript Core (src/core/)
Section titled “1. The Pure TypeScript Core (src/core/)”The shared game logic lives at the repository root under src/core/. It contains no React components, no JSX, no DOM APIs, and no platform dependencies.
The core is kept pure by a check, not by convention. A second TypeScript configuration, tsconfig.core.json, typechecks it alone with lib: ["ES2022"] and types: [], so a reference to a browser global (window, document) or a Node global (process, Buffer) fails npm run check, which CI runs on every pull request.
Because the core needs nothing from a platform, the same turn controller runs in the Vega app, in the browser test bench (which draws native/src/ through react-native-web) and directly under Node in the unit tests and scripts/cursor-presses.ts. No rule is written twice.
2. The React Native for Vega Shell (native/)
Section titled “2. The React Native for Vega Shell (native/)”The native application under native/ holds the screen flow, the drawing, the remote input, local saves, sound, and the random source and timers the screen flow uses:
- Screen flow:
screen.tsis a reducer over the menus, the overlays, starting a game, the bot’s steps and the settings.App.tsxgives it a random source for the dice and its timers. - Board and screens: draws the 8x8 board, the dice, the menus, the dialogs, the tutorial, the rules guide and the opponent cards with React Native views. The pieces, on the board and on the dice, are drawn with
@amazon-devices/react-native-svg, and so are the opponents’ emoji faces, which a build without the portrait images shows in their place. - Remote input: turns the D-pad, OK and Menu keys from
useTVEventHandler, and Back fromuseKeplerBackHandler, into the board’s own keys. - Synchronous persistence: reads the saved game, the completed-game ledger and the settings from
@amazon-devices/react-native-mmkvduring the first render, so the first frame already has them. - Opponent search:
botWorker.tsqueues requests for a custom Hermes worklet runtime. It runs the unchanged canonicalbotReplywhile the interactive runtime keeps serving keys. The native entry point supplies this runtime; the browser bench supplies a Web Worker. Key handling during a slow search was checked on a physical Fire TV Stick 4K Select with Release 1.0.3/build 51 on October 21, 2026, using automated D-pad, OK and Back events; this is not a key-latency measurement (validation record). - Sound: plays the sound effects, the spoken lines and the music with
AudioPlayerfrom@amazon-devices/react-native-w3cmedia. The music follows one of four themes, crossfading when it changes: the menu theme, or over a game the theme for the danger to the king.
The real sound and music objects are created after React’s first commit, behind stable references in lateAudio.ts. Settings and suspension state survive attachment, and the current first-launch speech request waits for its player unless stopped or silenced. Effect channels release their players while the app is away and reacquire them on return. Node component tests in native/test/firstFrame.test.tsx, native/test/tutorialOffer.test.tsx and native/test/soundApp.test.tsx check these contracts using Vega and audio stubs.
On a physical Fire TV Stick, local QA builds 53 and 54 built in Release mode checked first/cold launches and Home returns; build 53 also recorded native events across a music loop seam. These checks do not establish what was heard from the TV speakers. Building on Vega and the linked validation record separate the test and hardware evidence.
The native app makes no decisions about move legality, dice spending or how a game ends; those come from src/core/ and the engine. The board it draws is the grid src/core/boardView.ts describes. Remote keys go straight to the screen reducer, except while the tutorial, the rules guide or About is open: those screens take the remote themselves.
3. The Canonical Engine (@fortemate/dicechess-engine)
Section titled “3. The Canonical Engine (@fortemate/dicechess-engine)”Which actions and turns are legal is decided by Fortemate’s open-source rules engine, published on npm as @fortemate/dicechess-engine. How a game ends is decided in src/core/game.ts. Besides a resignation or a draw agreed in a game between two people (Hot Seat in the code), it ends on its own as in Fortemate’s game service: when a king is taken, after 100 halfmoves without a capture or a pawn move, checked at the end of a turn, or at turn 5,000.
The engine provides:
- Every legal turn of a roll, as a prefix tree of actions (
getLegalTurnTree, engine 0.13.0). - State transitions via
applyMove, returning the remaining dice and board position. - The dice some legal turn can still spend, via
getPlayableDice(engine 0.14.0), so the others can be dimmed.src/core/game.tsanswers from the turn tree where it can and asks the engine only when the tree does not settle it.
The app pins engine 0.14.6 (#382), which computes exact threat weights for up to three actions in the engine. Version 0.14.4 (October 6, 2026) builds the engine’s move tables faster, which cut a cool start on a Fire TV Stick from 6.05 s to 2.65 s (Performance).
The Data Flow
Section titled “The Data Flow”A key press that plays a step goes through these stages. The bot’s steps start at stage 2, from a timer.
- Remote Input:
useRemoteInputturns Vega’s key events into the board’s keys. The arrows, OK and Menu arrive throughuseTVEventHandler. OK is accepted under three names:enter(the Virtual Device’s keyboard, and what Amazon staff say Vega OS 1.2 sends for a remote’s OK, in forum topic 28945 on August 31, 2026),kpenter(the Virtual Device’s on-screen remote) andselect(the name a future Vega OS release will use). Back arrives throughuseKeplerBackHandler, the only channel that can claim it. The arrows, OK (asenterandkpenter) and Back were checked on the Vega Virtual Device, and Menu only by tests. On a Fire TV Stick 4K Select, a game has been played with the Stick’s own remote (Performance), and the arrows, OK and Back were checked with keys sent throughinputd-cli(Board selection algorithm); which of the three names the Stick sends for OK has not been recorded. - Screen Reducer:
screenReducerinnative/src/screen.tstakes the screen state and one action, such as a key or the bot’s step, and returns the next state. It is not pure: it rolls the dice, makes game ids and draws a side through functions the app injects (a test injects fixed ones), and applies the bot’s reply after the background worker resolvesoptions.reply. A reply is matched to the game ID, revision and full DFEN, then its complete path is checked byapplyBotReplybefore any move is shown. Directions move through menus, or jump the cursor between the pieces that can move and then between the chosen piece’s destinations (src/core/boardInput.ts,src/core/cursor.ts). - Turn Controller:
src/core/game.tschecks a roll for its phase and for three dice from 1 to 6, then has the engine build the turn tree for it. An action is accepted only if it is a next step in that tree, so a turn is checked as a whole. The bot’s whole path is checked the same way before its first move is shown (applyBotReply). - Engine Evaluation: the engine’s
applyMovegives the new position with the dice still unspent, and the turn tree says which actions may follow. When none may, the turn is over. A roll that leaves no legal action goes straight to the handoff, and the screen says there are no legal moves. After each step,game.tschecks whether the game has ended. - View Projection:
Board.tsxcallsboardView()with the position’s board field, the cursor, the selection, the legal actions, the last move, the movable pieces and which side the board is seen from. It returns an 8 x 8 grid ofSquareViewrecords: for each square, its piece, whether it is dark, and whether it is the cursor, the selected piece, a legal destination, an end of the last move or a piece that can move. - Native Rendering & Motion:
Board.tsxdraws the grid. When the position changed by one action,src/core/moveAnimation.tsworks out which piece went from which square to which (two pieces for castling), andBoard.tsxslides it there in 220 ms with React Native’sAnimatedon the native driver. Nothing slides until React Native’sAccessibilityInfohas answered whether reduced motion is on; where it cannot answer, pieces slide. Slides were checked frame by frame on the Vega Virtual Device; their smoothness on a Fire TV Stick has not been checked. - Synchronous Persistence: After React commits the render, an effect in
GameScreen.tsxpasses the new game toonCommitinApp.tsx, which saves it throughmmkvStore.ts: the snapshot is validated and written synchronously to MMKV. The save does not wait for the slide to finish. - Audio Cues: in the same effect,
cues()names the step’s sounds (a move, a capture, a roll, a win, and so on) andsound.tsplays them. Separately,useDanger.tsmeasures danger for the turn’s starting position throughsrc/core/danger.ts. The app queues its synchronous callback withsetTimeout(0)through the activity gate; this does not establish a rendered-frame boundary. Its answer (calm, tense or critical) is reused during the turn and sets the music theme, which rises at once and falls one level per turn. The measure uses the engine’sthreatWeightfor the first-action check and, when needed, the three-action check. Without music it only checks for critical, for the opponent’s threat line, and in Hot Seat it does not run. Performance names the implementation and its Node-test evidence.
Hackathon Scope vs Existing Foundation
Section titled “Hackathon Scope vs Existing Foundation”What was built during the hackathon, and what existed before it:
| Component | Status | Origin |
|---|---|---|
Rules Engine (@fortemate/dicechess-engine) |
Pre-existing | Open-source npm package that existed before the hackathon. The legal turn tree for JavaScript clients and applyMove keeping unspent dice (0.13.0, September 26, 2026) and getPlayableDice (0.14.0, September 29, 2026), which this app relies on, were added to it during the hackathon, and so was a faster start (0.14.4) and exact threat weights up to three actions (0.14.6). |
Fire TV Application (native/) |
New | Written during the hackathon, starting from the Vega SDK’s helloWorld project template, in a repository started on September 21, 2026. |
Pure TypeScript Core (src/core/) |
New | Written during the hackathon for this app. It served the WebView probe and the native app until the probe was removed on September 23, 2026; now the native app, the browser test bench and the Node tests run it. |
Remote Navigation Model (src/core/cursor.ts) |
New | Directional jumps between the pieces that can move, then between the chosen piece’s destinations: 61% fewer presses than square by square, over 200 simulated games in Node (npm run presses). |
Local Bot Opponents (src/core/bot.ts) |
New | Rolly, Grabby and Rampage as TV opponents, with cards showing each one’s level and how it plays. Their moves come from the engine’s existing algorithms (random, greedy, aggressive). |
| Interactive Tutorial & Rules Guide | New | 6-lesson interactive tutorial taught by Thinkle the wizard and 9-topic remote-friendly rules guide. |
| Animations & Audio | New | New code: a 220 ms piece slide, a 260 ms roll tumble, 10 sound cues, and music that follows the danger to the king (a menu theme and one theme for each of three danger levels). The sound effects (Kenney, JDSherbert) and the four music themes (pepka-prygni) are third-party work, used under their licenses or with their authors’ permission. |
Virtual Device driver (vega-vvd-driver) |
New | A separate, MIT-licensed repository started on September 27, 2026: a command, a Node library and an MCP server that press remote keys, take screenshots, record video and capture frames on the Vega Virtual Device through the Android emulator’s gRPC API and console. It does not work with a Fire TV Stick, and this repository’s CI does not use it. |
Opponent Runtime on Vega
Section titled “Opponent Runtime on Vega”The app uses Amazon’s React Native Worklets API, supported on React Native 0.83. createWorkletRuntime creates an isolated Hermes runtime and runOnRuntime schedules its work on a separate queue. scheduleOnRN brings the serialized result back to the interactive runtime. The worklet does not import React Native views, storage or audio.
scripts/botBundle.mjs bundles the pure botJob.ts request handler and the canonical engine into assets/raw/bot-engine.js. The asset comes from the signed application package. On its first request, the worker evaluates this bundled code in its own runtime and retains that engine for later requests. It never evaluates code from a network response or player input. The build retains the engine source map alongside the app’s debugging artifacts.
The worker calls the same DiceChess.getBestMove with the same algorithm. It changes where computation runs; it introduces no search deadline or weaker fallback. The client counts only foreground time toward its transport timeout for a missing response. A suspended app retains its remaining time when focus returns. That failure reaches the existing recovery screen and preserves the save. The client blocks another search until the old transport has settled; a late result is discarded, after which the player can return to the menu and resume or start a new game without relaunching the app. A transport that never settles remains blocked and requires an app restart. It never retries the search on the UI thread. The deadline, late-settlement and recovery contracts are checked by native/test/botWorker.test.ts and native/test/recovery.test.tsx.
Requests run one at a time. The client owns a bounded pair of namespaced default-MMKV keys; only the interactive runtime reads or writes them. The worklet receives and returns JSON strings. A callback checks that its request still owns the mailbox before publishing. Leaving the game for a menu retains its pending reply and presentation wait. A response received while the app is away cannot move the board until focus returns. Starting another game discards the old game’s answer. Completion and disposal remove the mailbox without changing the game, ledger or settings keys.
A single setTimeout(0) around a synchronous search only postpones the freeze. Slicing would require a resumable engine API and a defined work budget across slices; the engine currently offers a complete synchronous call. Worklets use that existing API, at the cost of a second runtime and an engine asset. The browser bench uses a Web Worker with the same pure request handler. Browser evidence is separate from Vega evidence. Physical build 51 and the final build 52 follow-up checked Menu/resume, cold restart during a search, a 180-second Home interval and replacement of a pending game. Build 52 also exercised both Recovery choices with a delayed callback in a separate diagnostic package; those forced failures are not ordinary Release evidence. The worklet ran on the Vega Virtual Device in build 48; aarch64 and x86_64 were built but not run in the final follow-up. The validation record separates these runs and their limits.