# 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

```bash
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:
```bash
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:

```bash
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:
```kotlin
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.