typesafe-mario

Typesafe-mario is a controller for the original Super Mario Bros. that hands every input decision to Jev. It does not show the model screenshots. Instead, the harness reads the emulator’s telemetry and RAM and turns it into compact JSON: Mario’s motion, jump trajectory, upcoming enemies, terrain, measured response delay, recent control results, and how far into the level the run has gotten. The raw local tile grid stays in debug logs and the UI but is not sent to the model.

Each request asks Jev three questions about the same state. A choice question picks the next controller input from a small, fixed action set (noop, right, right_jump, right_run, right_run_jump, jump, left). A noul (yes/no) question asks whether a forward jump should start or stay held now, and a score question rates immediate danger for the live display. Timing arithmetic stays in code: the parser works out facts such as whether a jump must start on this decision, and Jev still owns the controller choice. The emulator then advances several frames, eight in the example command, before asking again.

A live dashboard shows the chosen action, the full probability distribution, confidence, latency, jump probability, danger score and the parsed game state. Every decision is logged to a JSONL file with the same fields plus the outcome. It can run headless for benchmarking or as a single recordable window. It ships no Nintendo ROM; running it requires a lawfully obtained copy of the game.

How it uses Jev

started = time.perf_counter()
response = self._client.system_one(state=snapshot.to_state(), questions=questions)
latency_ms = (time.perf_counter() - started) * 1000

action_answer = self._answer(response, "next_action", "choices")
jump_answer = self._answer(response, "jump_needed", "nouls")
danger_answer = self._answer(response, "danger", "scores")
action = Action(str(action_answer.choice))
probabilities = {
    str(key): float(value) for key, value in dict(action_answer.probabilities).items()
}

View in src/typesafe_mario/policy.py

Open on GitHub