fhshaik/typesafe-mario

What it solves

TypeSafe Mario is an experimental controller that allows an AI model (Jev) to play Super Mario Bros. on the NES. It replaces traditional human input with model-driven decisions based on game state data rather than visual screenshots.

How it works

The system uses a harness that parses emulator telemetry and RAM to create a structured, object-centric JSON object. This JSON contains data on Mario's motion, jump trajectories, enemy positions, and terrain geometry. The AI model receives this structured data and selects one of several predefined controller macros (such as right_run_jump or jump). The emulator then advances several frames before the model makes its next decision.

Who it’s for

Developers and AI researchers interested in game AI, emulator telemetry parsing, and the use of structured data as model inputs for decision-making.

Highlights

• Structured Input: Uses JSON instead of raw pixels, providing the model with high-level concepts like "danger scores" and "jump deadlines."
• Telemetry Parsing: Translates raw NES RAM into meaningful game state objects (player, hazard, terrain, and episode progress).
• Real-time Dashboard: Includes a visualization tool that displays action probabilities, confidence, and model latency.
• Decision Logging: Records every decision and its associated game state to JSONL files for later analysis or social clips.