feat: add passive GAMELOG event logger for Spike 2 King Kong LE 0.97
Snapshot of the stern-event-agent work (as of 2026-10-12): - gamelog.c: passive PAD mode logging bus events (game/ball/bonus/tilt), all named shots and all-players' scores to /dump/mode.log - pad_mode_runtime.c: the SDK runtime + a GAMELOG section (passive stock-mode and award watching, gl_award_seq()/gl_last_award_id()), a per-edge switch logger to /dump/switch.log (switch_names.inc), and a passive Insider Connected gate; docs/runtime-patch.diff shows the exact changes vs the upstream runtime - event_probe.c / event_read.py: event-bus measurement tooling for identifying bus event ids on another game - ports/king_kong_le-0.97.port: 121 verified sites, 55 named shots, 6 bus events (emulator-proven by the SDK repo authors) Deployed and verified on the machine: events, shots, stock modes and awards. The /dump/switch.log feature is implemented but NOT yet deployed or verified, and the extra-ball award id (default 13) is unconfirmed. See README.md for build/install/log usage and unfinished work. Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
Claude Code
@@ -1,2 +1,210 @@
|
||||
# stern-event-agent
|
||||
|
||||
A passive gameplay-event logger for Stern Spike 2 pinball, developed against
|
||||
**King Kong LE 0.97**. It records the game's own events with millisecond
|
||||
timestamps — the game is not modified, nothing scores, nothing blocks.
|
||||
|
||||
The logger is a PAD mode: a small shared object (`mode.so`) that the game
|
||||
process loads via `LD_PRELOAD`. It hooks function sites inside the game, and
|
||||
every hook is verified against the first two machine instructions of that
|
||||
function before it is touched — a wrong or missing port hooks nothing, logs
|
||||
why, and the game runs stock.
|
||||
|
||||
## Status (as of 2026-10-12)
|
||||
|
||||
| Part | State |
|
||||
|---|---|
|
||||
| Bus events (`EV`): game/ball/bonus start/end, tilt, all players' scores at bonus end | **deployed on the machine, verified in play** |
|
||||
| Shots (`SHOT`): every named shot dispatched while a ball is up | **deployed on the machine, verified in play** |
|
||||
| Stock modes (`gamelog: MODE START/END`): the game's own 22 modes with score delta | **deployed on the machine, verified in play** (`mode_score` is approximate) |
|
||||
| Award screens (`AWARD id=…`): every award the game shows, extra-ball tracking | **deployed on the machine, verified in play** — except the extra-ball award id is not yet confirmed (below) |
|
||||
| Switch/button log (`/dump/switch.log`, `SW` lines with generated names) | **implemented in this tree, NOT yet deployed or verified** — the deployed `mode.so` (built 2026-10-12 10:46) predates it |
|
||||
|
||||
The machine currently runs the v2 build (events, shots, modes, awards). The
|
||||
switch logger (v3) is in this tree and needs a rebuild + redeploy before it can
|
||||
be relied on.
|
||||
|
||||
## Files
|
||||
|
||||
| File | What it is |
|
||||
|---|---|
|
||||
| `gamelog.c` | the logger: a passive PAD mode. It never `pm_begin()s`, never blocks, allocates nothing — it only watches and writes `[GAMELOG]` lines |
|
||||
| `pad_mode_runtime.c` | the PAD Modes SDK runtime, **patched**: (a) a GAMELOG section — passive stock-mode and award watching, exporting `gl_award_seq()` / `gl_last_award_id()` to modes; (b) the per-edge switch logger to `/dump/switch.log`; (c) the Insider Connected gate made passive. Our exact changes vs upstream: `docs/runtime-patch.diff` |
|
||||
| `switch_names.inc` | King Kong LE 0.97 switch id → name table (103 entries), `#include`d by the runtime's switch logger. Generated from the game's own data (method: `swnames.py` in the decryptor repo); fix names here if any are wrong |
|
||||
| `pad_mode.h`, `pad_stock.h` | unmodified SDK headers (needed by the build) |
|
||||
| `build_mode.sh` | unmodified SDK build script: compiles the runtime + your mode into one `-nostdlib` shared object and refuses banned libc calls |
|
||||
| `event_probe.c`, `event_read.py` | the event-bus measurement instrument and its log reader — how bus event ids are identified for another game (MODE_SDK.md, "Measuring events on another game") |
|
||||
| `ports/king_kong_le-0.97.port` | the King Kong LE 0.97 port: 121 verified sites, 55 named shots, 6 bus events. Installed on the machine as `/usr/local/padmode/game.port` |
|
||||
| `docs/runtime-patch.diff` | this project's changes to the upstream runtime (base: `pinball-asset-decryptor` commit `7faf8f08`, the last upstream change to that file) |
|
||||
|
||||
## What gets logged
|
||||
|
||||
### `/dump/mode.log` (deployed)
|
||||
|
||||
Append-only, millisecond stamps relative to the runtime loading, survives
|
||||
reboots:
|
||||
|
||||
```
|
||||
[pad] port ...: king_kong_le 0.97, 121 sites, 55 shots <- runtime armed (all hook words verified)
|
||||
[GAMELOG] up: game king_kong_le 0.97, 55 named shots; event ids 77/37/52/40/200/198; extra_ball_award=13
|
||||
[GAMELOG] +2408751ms EV game_start - GAME START
|
||||
[GAMELOG] +2408751ms EV ball_start player=1 ball=1 score=0
|
||||
[GAMELOG] +2424007ms SHOT X1 player=1 ball=1 score=7,349,830 <- all 55 named shots
|
||||
[GAMELOG] +2644003ms EV ball_end player=1 ball=1 score=91,153,090
|
||||
[GAMELOG] +2644003ms EV bonus_end
|
||||
[GAMELOG] +2644003ms SCORES P1=95,421,190 P2=0 P3=0 P4=0
|
||||
[GAMELOG] +...ms EV tilt_warning player=1
|
||||
[GAMELOG] +...ms EV tilt player=1 ball=2
|
||||
[pad] gamelog: MODE START 5 (Island Scene Escape the Swamp) player=1 score=...
|
||||
[pad] gamelog: MODE END 5 (Island Scene Escape the Swamp) player=1 score=... mode_score=... dur=...ms
|
||||
[GAMELOG] +...ms AWARD EXTRA BALL (id=13) player=1 <- next ball logs as "ball N (EXTRA BALL)"
|
||||
[GAMELOG] +...ms AWARD id=<n> player=1 score=... <- every award screen
|
||||
```
|
||||
|
||||
Bus event ids (King Kong 0.97): `game_start`=0x4d, `ball_start`=0x25,
|
||||
`ball_end`=0x34, `bonus_end`=0x28, `tilt_warning`=0xc8, `tilt`=0xc6. This build
|
||||
has **no** bus id for game over (the last `ball_end`/`bonus_end` is the close)
|
||||
or for bonus start.
|
||||
|
||||
**Extra balls**: the game re-fires `ball_start` for an extra ball. The runtime's
|
||||
award-screen hook counts the awards, and one whose id matches
|
||||
`extra_ball_award` (default **13**, overridable with a `value extra_ball_award`
|
||||
line in the port file) makes the replayed ball log as `ball N (EXTRA BALL)`
|
||||
instead of advancing the count.
|
||||
|
||||
**Mode detail**: the runtime polls each of the game's 22 mode objects' ACTIVE
|
||||
state per tick and logs START/END with the player's score at each edge —
|
||||
`mode_score=` is the score delta across the mode (approximate when other
|
||||
scoring runs simultaneously).
|
||||
|
||||
**Insider Connected**: stock. The upstream runtime vetoes score/session reports
|
||||
whenever modes are installed; this build makes that gate **passive** — reports
|
||||
flow exactly as stock (and are logged once), and the logger adds no scores of
|
||||
its own. Known cosmetic issue: the boot banner still prints the upstream "score
|
||||
reports stay on this machine" line — the later `passive gate` line is the truth.
|
||||
|
||||
### `/dump/switch.log` (implemented, not yet deployed)
|
||||
|
||||
The runtime's switch-edge handler writes **every edge of every switch** to
|
||||
`/dump/switch.log` — buttons included, attract included:
|
||||
|
||||
```
|
||||
<ms> SW <id> <NAME> level=<0|1> hit=<0|1> game=<0|1>
|
||||
```
|
||||
|
||||
`level` is the switch's raw state after the edge, `hit` is the game's own
|
||||
"counts as a hit" verdict, `game` whether a player is up. Names come from
|
||||
`switch_names.inc`; an id not in the table logs `?`.
|
||||
|
||||
## Build
|
||||
|
||||
Cross-compile on macOS in a Debian container (armhf, hard-float, `-nostdlib`):
|
||||
|
||||
```bash
|
||||
docker run --rm --platform linux/arm64 -v "$PWD:/work" -w /work debian:12 \
|
||||
sh -c 'apt-get update -qq && apt-get install -y -qq gcc-arm-linux-gnueabihf >/dev/null \
|
||||
&& bash build_mode.sh -o mode.so gamelog.c'
|
||||
```
|
||||
|
||||
`build_mode.sh` compiles `pad_mode_runtime.c` + `gamelog.c` into one object
|
||||
(~228 KB) and fails the build if any `pm_` symbol does not exist or any banned
|
||||
libc call is made (allocation, threads, sleeping, stdio, processes). The few
|
||||
libc calls that are used (`clock_gettime`, `open`, `write`, `close`, …) resolve
|
||||
from the game's own libc when the object loads.
|
||||
|
||||
The event probe builds without the runtime:
|
||||
`build_mode.sh -p -o event_probe.so event_probe.c`
|
||||
|
||||
## Install / deploy (the machine)
|
||||
|
||||
The machine (hostname `stern-spike2`) has root SSH (key-only, port 22). The
|
||||
logger lives on the rootfs, which is normally read-only:
|
||||
|
||||
| Path on the machine | From this repo |
|
||||
|---|---|
|
||||
| `/usr/local/padmode/mode.so` | the built `mode.so` |
|
||||
| `/usr/local/padmode/game.port` | `ports/king_kong_le-0.97.port` |
|
||||
| `/etc/init.d/game_monitor` | boot hook: preloads `mode.so` into the game **only if it exists** (stock script kept at `game_monitor.stock`) |
|
||||
|
||||
Deploy a new build:
|
||||
|
||||
```bash
|
||||
scp mode.so root@stern-spike2:/tmp/
|
||||
ssh root@stern-spike2 'mount -o remount,rw /; cp /tmp/mode.so /usr/local/padmode/mode.so;
|
||||
chmod 755 /usr/local/padmode/mode.so; sync; mount -o remount,ro / || true; reboot'
|
||||
```
|
||||
|
||||
Live view: `ssh root@stern-spike2 'tail -f /dump/mode.log'`
|
||||
|
||||
Housekeeping: `/dump` is a 532 MiB rw partition shared with crash dumps and
|
||||
connectivity logs; `mode.log` grows a few MB per long session (a few hundred
|
||||
`SHOT` lines per ball is normal). Pull it over SSH and rotate as needed;
|
||||
`: > /dump/mode.log` truncates it safely while running (same for `switch.log`
|
||||
once deployed).
|
||||
|
||||
Rollback: `rm -rf /usr/local/padmode`, restore `/etc/init.d/game_monitor.stock`,
|
||||
reboot — the machine is stock again (SSH remains).
|
||||
|
||||
## Measuring events for another game
|
||||
|
||||
`event_probe.c` hooks the game's event bus (`subscribe` / `dispatch`) and its
|
||||
tick, and logs every registration and per-window dispatch counts to
|
||||
`/dump/event.log`. Procedure (the full version is MODE_SDK.md, "Measuring
|
||||
events on another game"):
|
||||
|
||||
1. `build_mode.sh -p -o event_probe.so event_probe.c`
|
||||
2. Put the target's `subscribe` / `dispatch` / `tick` sites (address + first two
|
||||
instruction words) in `/dump/event.sites` — the SDK's `port_words.py`
|
||||
(in the decryptor repo) fills and checks those words from the game's ELF.
|
||||
3. Preload `event_probe.so` with `PAD_MODE_SO` (beside the stock runtime — its
|
||||
trampoline keeps the moved words where the runtime still verifies them).
|
||||
4. Play; at interesting moments `echo <label> > /dump/event.mark` to close a
|
||||
window (and open the next); `echo <id> > /dump/event.force` starts/stops a
|
||||
stock mode the way a rule does.
|
||||
5. `event_read.py /dump/event.log` — which ids fired in which window, with
|
||||
handlers, priorities and callers.
|
||||
|
||||
The ids you name that way become the `event` lines of a port (the six in
|
||||
`king_kong_le-0.97.port` were found this way, in the SDK's emulator).
|
||||
|
||||
## Unfinished work / known issues
|
||||
|
||||
- **The switch logger is not on the machine yet.** The deployed `mode.so` is the
|
||||
2026-10-12 10:46 build (events/shots/modes/awards). The `/dump/switch.log`
|
||||
feature (runtime patch + `switch_names.inc`) was written later the same day:
|
||||
it needs a rebuild, a redeploy, and verification that the log appears and the
|
||||
names are right.
|
||||
- **The extra-ball award id is unconfirmed.** Default 13 is a static guess from
|
||||
the game's object-name tables; every award id is logged, so earn an extra
|
||||
ball, read the `AWARD` line, and pin it down (or override it in the port).
|
||||
- **The master SD image does not contain the logger** — it was installed over
|
||||
SSH onto the card in the machine. Making it survive a re-flash needs a
|
||||
debugfs inject of `mode.so` + `game.port` + the hooked `game_monitor` into
|
||||
the master image.
|
||||
- **No network streaming yet.** Logs are pulled over SSH; the plan is for the
|
||||
mode to ship them itself (`socket()` is not on the build's banned list).
|
||||
- **Cosmetic**: the boot banner still prints the upstream "score reports stay
|
||||
on this machine" line (see Insider Connected above).
|
||||
- `mode_score` is an approximation (see above).
|
||||
|
||||
## Provenance
|
||||
|
||||
Built on the PAD Modes SDK
|
||||
(`pinball-asset-decryptor/tools/spike2_emu/modes/sdk/` — the
|
||||
`mattlqx/pinball-asset-decryptor` Gitea repo, itself a fork of
|
||||
`davidvanderburgh/pinball-asset-decryptor`; the SDK docs there — `MODE_SDK.md`,
|
||||
`MODE_PARAMETERS.md`, `MODE_LIMITS.md` — apply to everything in this repo).
|
||||
Everything in this repo is unmodified SDK content except:
|
||||
|
||||
- `gamelog.c` (new)
|
||||
- `switch_names.inc` (new)
|
||||
- `pad_mode_runtime.c` (upstream runtime + the patch in `docs/runtime-patch.diff`)
|
||||
- `README.md`
|
||||
|
||||
`ports/king_kong_le-0.97.port`, `event_probe.c`, `event_read.py`,
|
||||
`build_mode.sh` and the headers are the SDK's, unmodified (the port is
|
||||
emulator-proven by the SDK repo authors).
|
||||
|
||||
The machine's SSH setup (dropbear + sftp-server on the Spike 2) is documented
|
||||
separately in the local `pinball-assets/README.md` and is **not** part of this
|
||||
project — this logger uses that SSH, it does not provide it.
|
||||
|
||||
Reference in New Issue
Block a user