schwert_und_magie_on_pebble/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project goal

Port the classic German C64 RPG series Schwert und Magie (8 episodes, German Design Group, 1989–1992) to a Pebble Time 2 smartwatch. The phone runs a VICE C64 emulator as a companion app; the watch displays the game and sends button presses back.

Repository layout

SchwertUndMagieOnPebbleWatchApp/   Pebble watchapp (C + PebbleKit JS)
SchwertUndMagieOnPebbleCompanionApp/  Android companion app (Kotlin + NDK)
versions/                          Original .d64 disk images (4 disks, 8 episodes)
docs/                              Background notes

Watch app

Build & install

cd SchwertUndMagieOnPebbleWatchApp
pebble build                          # all platforms
pebble install --phone <phone-ip>     # sideload via Pebble/Core app on the phone
pebble logs --phone <phone-ip>        # stream JS + C app logs

In headless / CI environments, add --vnc to every emulator command:

pebble install --emulator emery --vnc
pebble screenshot --vnc --scale 6 --no-open screenshot.png
pebble emu-button --emulator emery --vnc click select

Key files

File	Purpose
src/c/SchwertUndMagieOnPebbleFrontend.c	Single-file C watchapp
src/pkjs/index.js	PebbleKit JS — runs inside Core for Pebble on the phone
package.json	UUID, target platforms, messageKeys

Communication protocol

AppMessage keys (defined in both C and JS):

Key	Direction	Value
0 (TIME)	phone → watch	"HH:mm:ss" string (later: C64 framebuffer)
1 (COMMAND)	watch → phone	button name string ("UP", "DOWN", "SELECT")

The watch UUID is 8039ba8c-f1e8-4620-838d-650fa35335b7.

PebbleKit JS notes (Core for Pebble quirks)

• Use 127.0.0.1 not localhost — Core for Pebble's JS runtime does not resolve localhost.
• Use numeric keys in sendAppMessage ({ 0: value } not { 'TIME': value }) — symbolic key resolution from package.json messageKeys is unreliable with Core for Pebble.
• PebbleKit Android (com.getpebble.android.*) does not work with Core for Pebble; all phone↔watch communication goes through PebbleKit JS + the HTTP server.

Android companion app

Build

Open SchwertUndMagieOnPebbleCompanionApp/ in Android Studio, or:

cd SchwertUndMagieOnPebbleCompanionApp
./gradlew assembleDebug
./gradlew installDebug

Android SDK is at /opt/android-sdk.

Communication architecture

Watch (AppMessage BT)
  ↕
PebbleKit JS — index.js runs inside Core for Pebble
  ↕  HTTP on 127.0.0.1:8888
Android companion app — NanoHTTPD server
  GET /time  →  {"time":"HH:mm:ss"}
  GET /key?cmd=UP  →  logs keystroke

MainActivity starts both the NanoHTTPD server and the VICE emulator loop thread. All HTTP callbacks marshal to the main thread via mainHandler.

VICE integration (NDK)

VICE 3.8 tarball is at SchwertUndMagieOnPebbleCompanionApp/res/vice-3.8.tar.gz.

Without VICE built (first state): vice_jni.c fills the framebuffer with a placeholder blue screen; the app builds and runs normally.

VICE compilation is automatic. The Gradle buildVice task runs before every native CMake build. On the first build it:

1. Calls app/src/main/jni/build_vice.sh with $NDK set from the Android Studio SDK config
2. The script unpacks the tarball, cross-compiles VICE headless for ARM64 and x86_64, and produces vice-libs/<abi>/libvice.a
3. CMakeLists.txt auto-detects the library via EXISTS and links it in — no manual flags needed

The NDK must be installed: Android Studio → SDK Manager → SDK Tools → NDK (Side by side).

After the first successful build, subsequent builds skip the VICE compilation step entirely (outputs are up-to-date).

C64 ROM files (kernal, basic, chargen, 1541) are copyrighted and are not bundled in the APK. On first launch, MainActivity checks the app's external files dir for these four files; if any are missing, it shows a blocking dialog that lets the user import their own legally-obtained ROM dump via the system file picker (see docs/publish.md §0). res/extract_roms.sh can pull the ROMs out of res/vice-3.8.tar.gz into res/roms/ for local sideloading during development, but nothing in the Gradle build copies them into the APK.

Key Kotlin/C files

File	Purpose
MainActivity.kt	Emulator loop thread (50 fps), NanoHTTPD server, keyboard event logging
C64Engine.kt	JNI interface to VICE — init, runFrame, getVideoBuffer, injectKey, loadDisk
C64DisplayView.kt	SurfaceView — blits 320×200 ARGB framebuffer, scaled with correct aspect ratio
C64KeyboardView.kt	Multi-touch virtual C64 keyboard; fires KeyEventListener on press/release
jni/vice_jni.c	JNI wrapper — custom VICE video canvas writes frames to g_framebuf[320×200]
jni/nibconv_jni.c	JNI wrapper around nibtools' nibconv — converts downloaded NIB/NBZ dumps to G64
jni/CMakeLists.txt	NDK build; conditionally links libvice.a/libnibtools.a when their HAVE_* flags are set

Disk images

The four original .d64 disk images are in versions/. Copy the relevant image to the same external files directory as the ROMs (via USB or adb), then load via:

engine.loadDisk(getExternalFilesDir(null)!!.absolutePath + "/schwert_und_magie_1.d64")

Alternatively, the in-app Download Disks button (next to Import Disks) fetches all 8 episode disks from the Internet Archive's C64 Preservation Project and converts them to G64 automatically — see "Disk download (nibtools)" below.

Disk download (nibtools)

The Internet Archive's C64 Preservation Project only has these disks as .nbz (nibtools' compressed raw-GCR NIB format) — not .d64. MainActivity.downloadDisks() fetches each of the 8 .nbz files (one per disk side) and runs them through nibtools' nibconv to produce G64 images (VICE attaches G64 exactly like D64, detecting the format from file content, not the extension). G64 was chosen over the lossy D64 reconstruction nibconv also supports, since these old dumps aren't always cleanly sector-readable — G64 preserves whatever the original drive actually saw.

Only nibconv's pure file-format conversion code is built (gcr.c prot.c fileio.c crc.c md5.c lz.c nibconv.c) — nibtools' hardware-access tools (nibread/nibwrite, which talk to a real 1541 over OpenCBM) are not needed and not built. jni/nibtools_android/ stubs out the OpenCBM header so the unused declarations that pull it in still compile.

nibtools compilation is automatic, the same way as VICE:

1. The Gradle buildNibtools task runs before every native CMake build
2. It calls app/src/main/jni/build_nibtools.sh, which unpacks res/nibtools-<rev>.tar.gz and cross-compiles the files above into nibtools-libs/<abi>/libnibtools.a
3. CMakeLists.txt auto-detects the library via EXISTS and links it in

nibconv's main() is renamed to nibtools_nibconv_main at compile time (-Dmain=...) so it can coexist in the same shared library as the JNI entry points. It's invoked from nibconv_jni.c on a throwaway pthread — nibconv calls exit() on malformed input, which is wrapped (-Wl,--wrap=exit) to pthread_exit() so a bad conversion only kills that disposable thread, never the app process or the calling JNI thread.