GitHub · by fhshaik

TypeSafe Mario

Jev picks NES controller inputs from telemetry, never from pixels.

An experimental controller that lets Jev choose the buttons for the original Super Mario Bros. The model never sees a screenshot. The harness turns emulator telemetry and RAM into compact, object-centric JSON — Mario’s motion, his jump trajectory, upcoming enemies, terrain, the measured response delay, recent control results and episode progress — and Jev picks one legal action from a short list.

The action set is deliberately small: noop, right, right_jump, right_run, right_run_jump, jump and left. Jev makes a decision every eight emulator steps, the emulator advances, and the loop repeats. The raw local tile grid stays available in the debug logs and the interface but is not duplicated into the model input, which is the difference between a state description a decision model can act on and a dump it has to wade through.

Feeding measured response delay back into the state is the detail worth copying. A real control loop has latency, and a model told what that latency currently is can commit to a jump early instead of reacting late. The repository ships a state-demo command that prints the exact JSON and text that would be sent, without launching the game or spending a call — the cheapest way to see what a Jev state actually looks like. It needs Python 3.13 and your own legal copy of the game; no ROM is included.