schwert_und_magie_on_pebble/docs/architecture.md

Architecture

This document describes the current runtime architecture of the two apps in this repo: the Pebble watch app and the Android companion app. For build/install commands, see CLAUDE.md.

1. System overview

Three processes cooperate across two devices. Core for Pebble is a separate app on the phone (not part of this repo) that bridges Bluetooth AppMessage traffic to a JS runtime; our companion app talks to it only via loopback HTTP.

2. Pebble watch app

SchwertUndMagieOnPebbleWatchApp/src/c/SchwertUndMagieOnPebbleFrontend.c is a single-file C watchapp built around three Windows on a shared stack, plus src/pkjs/index.js running inside Core for Pebble.

• Splash — BitmapLayer showing resources/splash.png, centered, black backdrop. Pushed on top of the already-pushed Main window at startup (not in place of an empty stack — removing the last window on the stack kills the app), then removed by an AppTimer after 1.8s.
• Main — a ScrollLayer wrapping a TextLayer that mirrors the C64 text screen. UP/DOWN are claimed entirely by the ScrollLayer's built-in click config (pan only); SELECT is added via scroll_layer_set_callbacks()'s click_config_provider hook and opens the wheel. Content height is recomputed via graphics_text_layout_get_content_size() every time new screen text arrives, since wrapped height varies frame to frame.
• Wheel — a single large TextLayer cycling through a curated, navigation-only key set: 1–9, 0, RETURN, SPACE (movement in this game is mostly done with number keys). UP/DOWN rotate the index, SELECT sends the highlighted label and pops back to Main, BACK cancels for free (default window-pop behavior, left unsubscribed).

AppMessage protocol

Key	Value	Direction	Payload
TIME	0	—	Unused (legacy; originally the clock, replaced by SCREEN)
COMMAND	1	watch → phone	Wheel item label: one of 1..9, 0, RETURN, SPACE
SCREEN	2	phone → watch	UTF-8 C64 screen text, 40×25 cells, \n per row

Numeric keys are hardcoded identically in the C app and index.js — symbolic key resolution from package.json's messageKeys is unreliable with Core for Pebble. The watch's AppMessage inbox is opened at 2200 bytes to fit the worst-case screen payload (40×25 cells × up to 2 UTF-8 bytes for umlaut overrides, + 25 newlines).

3. Android companion app

• Main/UI thread — MainActivity's Choreographer.postFrameCallback loop drives rendering: on every hardware vsync it calls display.captureFrame(engine) (copies VICE's 320×200 ARGB framebuffer into a Bitmap) and invalidate(). VICE itself runs continuously and asynchronously in its own thread, decoupled from this vsync sampling. Touch input (C64KeyboardView, disk drawer buttons) and NanoHTTPD callbacks (marshaled via mainHandler) also run here.
• VICE thread (vice_thread in vice_jni.c) — runs main_program() → maincpu_mainloop(), VICE's own CPU/VICII loop. video_canvas_refresh() is our hook into this loop, called once per rendered region: it drains mutex-guarded pending-operation queues (disk autostart/attach, hard reset, snapshot save/load) written from the UI or HTTP threads, then renders into g_framebuf.
• NanoHTTPD worker thread(s) — CompanionServer (in MainActivity.kt) serves /time, /key?cmd=, /screen to Core for Pebble's JS. onKey and getScreenText call directly into the JNI layer from this thread (see §5 on tolerated races).
• stdout/stderr reader threads — pipe VICE's redirected stdout/stderr to Logcat under tag ViceJNI, prefixed VICE: .
• OpenSL ES callback thread — pulls PCM samples from a ring buffer filled by VICE's registered android sound driver.

Key source files

File	Role
MainActivity.kt	UI, Choreographer render loop, NanoHTTPD server, disk drawer, watch key wheel → injectKey mapping
C64Engine.kt	JNI external-function declarations + C64 keyboard matrix constants
C64DisplayView.kt	Double-buffered View blitting the 320×200 ARGB framebuffer
C64KeyboardView.kt	On-screen virtual C64 keyboard (multi-touch, sticky shift)
vice_jni.c	VICE integration: thread management, video/sound drivers, pending-op queues, snapshot CPU-trap dispatch, getScreenText()

4. Data flows

4.1 Screen mirror (VICE → watch)

getScreenText() reads C64 screen RAM at the fixed default address $0400 (same assumption autostart.c makes when checking for KERNAL "READY." text — this game never relocates the VIC-II screen pointer) and converts each screencode → PETSCII → ASCII via VICE's own charset.c tables. The game uploads a custom character set that redefines a consecutive run of otherwise-unused screencodes to draw German umlauts; a small override table in getScreenText() catches these and emits proper UTF-8 before falling through to the standard conversion:

Screencode	Stock glyph	Overridden to
0x1B	[	ä
0x1C	£	ö
0x1D	]	ü
0x1E	↑	ß

4.2 On-screen keyboard input (phone touch → VICE)

Composite keys (e.g. ↑ = LSHIFT + CUR_UD) carry a list of codes; all are pressed/released together.

4.3 Watch key wheel input (watch → VICE)

4.4 Snapshot save/load (CPU-trap register sync)

Both save and load must run inside a CPU trap. maincpu_mainloop() keeps CPU registers as stack-local variables (reg_pc, reg_a, ...), syncing them with the global maincpu_regs struct only via EXPORT_REGISTERS() / IMPORT_REGISTERS() inside DO_INTERRUPT. Calling machine_write_snapshot/ machine_read_snapshot directly from video_canvas_refresh() (outside a trap) would read/write a stale maincpu_regs.pc — the snapshot would record (or restore) the wrong program counter, leaving the CPU executing from the wrong address after a load even though screen/CIA/SID state all looked correct.

4.5 Disk load / attach / reset

loadDisk() (full reset + autostart, used for A-side episode disks) and attachDisk() (hot-swap, used for B-side/hero disks) both just write a path into a mutex-guarded pending buffer; video_canvas_refresh() drains it on the VICE thread and calls autostart_disk() or file_system_attach_disk() accordingly — disk and reset APIs, like snapshot APIs, must only be called from the VICE thread.

5. Tolerated cross-thread races

Two JNI calls are invoked directly from non-VICE threads with no locking: injectKey() (writes the keyboard matrix from the UI thread or an HTTP worker thread) and getScreenText() (reads screen RAM from an HTTP worker thread). Both are deliberate: a keyboard matrix write or a screen-text read racing with the VICE thread can produce at most one stale byte for one frame, which self-corrects on the next poll/keypress — acceptable for display and input purposes. This is a different category from §4.4: snapshot register sync is correctness-critical (a wrong PC corrupts execution permanently), so it goes through the CPU trap; keyboard/display reads are not, so they don't.

---

Diagrams are rendered PNGs under diagrams/; each has a matching .mmd Mermaid source in the same folder. To regenerate one after editing its source:

npx @mermaid-js/mermaid-cli -i diagrams/<name>.mmd -o diagrams/<name>.png -b white -s 3