TypeSafe Mario

How we reviewed this: TypeSafe Mario needs a Super Mario Bros. game file, which is copyrighted, so we didn’t run the game. We read the code at commit ca22449, ran its lint and test suite (all 10 tests passed), and ran the built-in state-demo command, which shows the exact JSON sent to TypeSafe without a ROM or an API call.

What it does

TypeSafe Mario lets Jev choose the controller input for World 1-1 of the original Super Mario Bros. The model never sees a screenshot. Instead, the harness reads the emulator’s telemetry and memory and turns them into a compact JSON object describing Mario’s position and velocity, jump phase, up to three upcoming enemies with projected positions, nearby terrain, how stale the last observation was, what the previous action achieved, and overall episode progress.

On each decision, one request asks Jev three independent questions about that state:

• a Choice among seven controller actions (no-op, right, run, jump, and combinations),
• a Noul for whether a forward jump should start or stay held now, and
• a Score for how dangerous the immediate situation is, used for the on-screen dashboard.

The design principle is stated clearly in the README and followed in the code: exact timing math stays in code. For example, the parser combines measured response delay, enemy motion, and the frames a jump needs to clear an enemy into a single jump_must_start_this_decision fact. Jev interprets these facts and makes the call, with no scripted override.

Setup

The documented setup uses Python 3.13 and PowerShell:

.venv\Scripts\python -m pip install -e ".[mario,dev]"
$env:TYPESAFE_API_KEY = "your-key"
.venv\Scripts\typesafe-mario state-demo
.venv\Scripts\typesafe-mario play --env SuperMarioBros-1-1-v0 --frames-per-decision 8

The mario extra installs the emulator stack: gym-super-mario-bros, nes-py, Gymnasium, NumPy, and Pygame. The README states that the repository contains no Nintendo ROM and that you’re responsible for obtaining and using your emulator and game files lawfully. Be aware that the upstream gym-super-mario-bros project’s source tree includes .nes files, so installing that dependency may bring game data onto your machine. Check the legal position where you live before running it.

What we could check

• Offline state inspection works. typesafe-mario state-demo printed the full model-facing JSON and the human-readable debug view using a built-in sample, with no game and no network call. It’s the best way to understand the project, and the right thing to run before trusting any tool with your API key.
• The code is tidy. Formatting and lint checks pass, and the 10 tests covering the state parser and dashboard pass on Python 3.13. CI runs the same checks on every push.
• The loop doesn’t block the game. Jev requests run on a background thread. The emulator keeps advancing with the previous action while a decision is in flight, and the next request reports how many frames that took, so the model can account for its own delay.
• Errors aren’t handled. If a Jev request fails, for example because of rate limiting, the exception propagates and ends the run. That’s acceptable for a demo but worth knowing if you build on it.
• There’s a no-API mode. --policy heuristic runs a simple built-in controller for smoke-testing the emulator setup without spending API calls. The code labels it a test policy, not a baseline.

Permissions and data

• Only game state goes to TypeSafe. Each request contains the parsed JSON state and the three questions. It uses TypeSafe’s official Python SDK, which reads TYPESAFE_API_KEY from the environment. We found no other network destinations in the project’s code.
• Runs are logged locally. Every decision is written to artifacts/run-<timestamp>.jsonl, including the model’s action probabilities, confidence, latency, and the full state. Keep those files private if you’re bound by TypeSafe’s terms on publishing performance information.
• No license. The repository doesn’t include a license file, which under default copyright means you can view and fork it on GitHub but have no permission to reuse the code elsewhere. Ask the author before building on it.

Maintenance

The project was published as a single commit on September 16, around Jev’s launch, and hasn’t changed since. There are no open issues. The dependencies it relies on for emulation are community projects, and the nes-py emulator is MIT licensed.

Verdict

TypeSafe Mario is a compact, readable example of the pattern that makes Jev useful in real-time settings: parse the world into facts, do the arithmetic in code, and ask the model only for the judgment. Even if you never run it, state.py and the question design in policy.py are worth reading. To run it, you’ll need your own lawfully obtained game file, and to reuse it, you’ll need the author’s permission.

For another game driven the same way, see Jev Plays StarCraft. For a lighter demo you can run without game files, try Jev Pong. Our best Jev tools roundup covers the projects we’ve tested hands-on.

See how it compares with other tools in Best Jev tools, tested hands-on.

Review updated Sep 19, 2026. Numbers quoted from the project are its author's own; we don't publish our own measurements of Jev.