MarioStudent: 9M Core ML Mario policy (53/96; 78/96 with lookahead)

MarioStudent.mlpackage/Data/com.apple.CoreML/model.mlmodel

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4a22158159e530052908185b361db50a417e68e8e4767e11a787700ba8d74b2b
+size 118244

MarioStudent.mlpackage/Data/com.apple.CoreML/weights/weight.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:924f70024936e3789389561b13e0e6c837f6cdaf1fa515668892417feba934ae
+size 17750358

MarioStudent.mlpackage/Manifest.json

@@ -0,0 +1,18 @@
+{
+    "fileFormatVersion": "1.0.0",
+    "itemInfoEntries": {
+        "28F6376E-BAFE-449B-8819-62D398130CDB": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Weights",
+            "name": "weights",
+            "path": "com.apple.CoreML/weights"
+        },
+        "A8D5A8BF-9CB6-4A44-89C2-7B460ED934CC": {
+            "author": "com.apple.CoreML",
+            "description": "CoreML Model Specification",
+            "name": "model.mlmodel",
+            "path": "com.apple.CoreML/model.mlmodel"
+        }
+    },
+    "rootModelIdentifier": "A8D5A8BF-9CB6-4A44-89C2-7B460ED934CC"
+}

README.md

@@ -0,0 +1,55 @@
+---
+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.

config.json

@@ -0,0 +1,40 @@
+{
+  "model": "MarioStudent",
+  "architecture": "MobileNetV3-Large (ImageNet init) + heads: move (11), survival (11), tile grid 13x12, enemy grid 13x12",
+  "parameters": 9035296,
+  "input": {
+    "name": "crop",
+    "shape": [
+      1,
+      6,
+      120,
+      96
+    ],
+    "dtype": "float16",
+    "range": [
+      0,
+      1
+    ],
+    "layout": "RGB now, then RGB 4 frames earlier; screen from 32 px behind Mario to 160 px ahead, every 2nd pixel"
+  },
+  "output": {
+    "name": "logits",
+    "meaning": "11 move logits (order in `moves`) then 11 survival logits"
+  },
+  "moves": [
+    "run",
+    "walk",
+    "hold",
+    "jump",
+    "hop",
+    "up",
+    "left",
+    "leftjump",
+    "wait",
+    "swim",
+    "down"
+  ],
+  "macro_frames": 8,
+  "coreml": "MarioStudent.mlpackage (fp16, 185/185 ops on the Neural Engine)",
+  "pytorch": "mario-student.pt (model-lab mario-tiny student_retro.py, arch retro-aux, view half2)"
+}

mario-student.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:021def4eef37994701d23b93e9fcb4ded4b67da90d550e63493f8558f65369bb
+size 36374091