mario-jev
Python prototype where Jev answers focused movement and jump questions from NES RAM state and code turns them into button presses.
Overview
mario-jev is a uv-managed Python prototype that plays NES Super Mario Bros., level 1-1 by default with any world and stage selectable. Jev receives structured observations read from game RAM and answers focused questions about movement, starting a jump, sustaining a jump, and timing hops under low ceilings; code composes the answers into controller buttons. The emulator pauses while Jev responds, then advances up to four frames by default, stopping early on landing.
It is careful about cost and reproducibility: every decision is a paid request, so a decisions flag caps calls per episode, API errors stop gameplay rather than retrying, and a scripted policy and state dump need no key. Runs are logged to JSONL and can be replayed with no API calls, using the recorded seed, actions and frames, checking positions against the log and stopping on divergence. A dump-state option shows exactly what Jev will see. It suits people exploring typed decisions for real-time game control.
What the decision model decides
| Type | Question | Answers |
|---|---|---|
| Choice | Which way should Mario move?(inferred) | — |
| Yes / no | Should Mario start a jump now? / Keep holding the jump? | — |
| Yes / no | Is this the right moment for a hop under a low ceiling? | — |
How it works
- Read structured state from NES RAM
- Pause and ask Jev movement and jump questions
- Compose answers into controller buttons
- Advance up to four frames, stopping on landing
- Log decisions for deterministic replay
Strengths
- Explicit cost controls on API calls
- Deterministic replay without a key
- Inspectable state sent to Jev
Caveats
- Each decision is a paid call
- Game pauses during calls, so not real time
- Prototype
Getting started
uv sync --locked, put TYPESAFE_API_KEY in .env, then uv run mario-jev --decisions 25.At a glance
- Type
- Project
- Status
- prototype
- Language
- Python
- Runtime
- NES emulator with Python control loop
- Has code
- yes
Use cases and integrations
How curated lists describe it
Python prototype that plays NES Super Mario Bros. from structured RAM observations, with Jev answering focused movement and jump questions.
hellogumbo/awesome-jev
Frequently asked questions
What does Jev decide?
Movement direction, when to start and sustain jumps, and hop timing under low ceilings.
Can I try it without a key?
Yes, with the scripted policy, state dump or replay.
How do I limit cost?
Use --decisions to cap API calls per episode.
Related projects
Real-time bot battles where you write a fighter's strategy in plain English and a System One model pilots it several times a second.
ProjectbetaTypeScriptBot that plays Red Alert 2 web skirmishes, with code handling mechanics and a decision model making stance, threat and timing calls.
ServicebetaPythonMultiplayer 3D science-fantasy version of Houston's River Oaks District with Jev-powered NPC companion, chauffeur and smart drive.
ProjectbetaTypeScriptBrowser 3D planetary rover sandbox where a TypeSafe controller chooses the next action from complete candidates, versus a baseline.
ProjectbetaTypeScriptDoom runs as a spacecraft payload over real flight software; Jev pilots from the ground every half second while Claude reviews.
ProjectprototypePythonMinecraft agent where Hermes plans, Jev picks one bounded action at a time and a Mineflayer harness validates and executes.
ProjectprototypeJavaScript