---
license: apache-2.0
library_name: coreml
pipeline_tag: reinforcement-learning
tags:
- coreml
- apple-neural-engine
- super-mario-bros
- imitation-learning
- dagger
- game-playing
---

# MarioStudent (Core ML)

A 9.0M-parameter pixel policy that plays Super Mario Bros. (NES) on the Apple Neural Engine.

It is a MobileNetV3-Large that looks at the screen around Mario (now and 4 frames earlier) and picks one of 11
eight-frame moves: run, walk, hold, jump, hop, up, left, leftjump, wait, swim, down. It was trained by imitation on
a save-state beam-search solver that clears all 32 levels, plus DAgger rounds, with auxiliary tile and enemy grid
targets. It was not distilled from JEV.

- `MarioStudent.mlpackage`: fp16, 17 MB, all 185 ops on the Neural Engine, about 0.5 ms per decision (M5 Pro). Its
  move choice matches PyTorch on CPU, GPU and ANE.
- `mario-student.pt`: the PyTorch checkpoint.
- `config.json`: inputs, outputs and move order.

## Results

32 levels × 3 start offsets:

| | Flags | Levels cleared at least once | Cleared every time |
|---|---|---|---|
| Model alone | 53/96 | 23 | 12 |
| Model + lookahead | 78/96 | 30 | 21 |

Lookahead: before each move, candidate moves are simulated on an emulator save state, each followed by the model's
next 6 moves, and the first that survives and gains ground is played. With lookahead the result is the model plus
emulator simulation, not the network alone. The maze castles 4-4 and 8-4 are not cleared.

## Input / output

- Input `crop`: [1, 6, 120, 96] fp16 in [0, 1]. RGB now, then RGB 4 frames earlier, covering 32 px behind Mario to
  160 px ahead, every 2nd pixel of the 256×240 NES frame.
- Output `logits`: 11 move logits (order in `config.json`), then 11 survival logits.
- Moves are 8-frame button macros. The last input is held while the game has control, e.g. during a pipe entry.
- Mario's on-screen x, which places the crop, is read from emulator RAM.

## Demo

[FluidUse `Sources/JevMarioDemo`](https://github.com/FluidInference/FluidUse/tree/main/Sources/JevMarioDemo) is a
SwiftUI app that runs this model on the Neural Engine, with or without lookahead, next to
[JEV-9B on Core ML](https://huggingface.co/FluidInference/jev-9b-coreml).

You need your own copy of the game. No ROM, frames or gameplay video are included here.