NES CPU Compiled into Qwen Weights to Run Games In-Model

Original title: A Working Nintendo in ~1GB of Qwen Weights
78AI Score

The nesformer project compiles the NES 6502 CPU, RAM, and ROM logic directly into standard Qwen3.5 model weights without training, enabling in-model simulation. By leveraging Gated DeltaNet states as machine memory, the LLM predicts CPU execution logs token-by-token, allowing classic games like Super Mario Bros. to run entirely within approximately 1GB of weight space.

Full Report

Contents7 sections

nesformer

将 NES CPU 编译进标准 Qwen3.5 模型的权重中。

NES 的 6502 CPU(其 2A03 芯片的核心)、2 KB 的工作 RAM 以及卡带的程序 ROM,均运行在标准的 Qwen3_5ForCausalLM 检查点内。这些权重并非经过训练得到,而是由编译器计算生成的。当你玩游戏时,模型会逐个 token 地预测 CPU 的执行日志。一个小型宿主程序负责处理控制台的其他部分:绘制画面、读取控制器输入并触发 vblank 中断。

nesformer 基于 Divyansh Agrawal 开发的 Qwenputer 构建,后者曾将 CHIP-8 和 RISC-V CPU 编译进 Qwen3.5-4B 模型。它复用了 Qwenputer 的编译器及其核心技巧:模型的 Gated DeltaNet 状态即为机器的内存。

Super Mario Bros. (World 1-1)Doug Fraker 制作的完整游戏(标题画面及第一关)
Super Mario Bros., played by the weightsFull Game, played by the weights

在这些运行过程中,每一个 CPU token 均由模型生成。对于捆绑的测试游戏,每一帧也与传统 6502 模拟器的输出完全匹配(参见如何验证)。

快速开始

1. 文件夹布局

将 nesformer.zip 和 nesformer-weights.zip 解压到同一文件夹中。权重文件应位于 nesformer/ 包旁边,而不是在其内部:

Text
nesformer/              <- 在此处运行命令
├── nesformer/          <- Python 包
├── chipformer/         <- Qwenputer 的编译器
├── roms/               <- 测试 ROM(也可放入你自己的 ROM)
├── examples/           <- 示例 GIF 和帧表
├── tests/
├── LICENSE
├── LICENSE.chipformer
├── README.md
├── pyproject.toml
└── weights/            <- 来自 nesformer-weights.zip
    ├── config.json
    ├── generation_config.json
    ├── model.safetensors
    ├── nesformer.json
    └── SHA256SUMS

CLI 会在 nesformer/ 包旁边查找 weights/ 目录。若要将权重存放在其他位置,请在执行 run、check 或 trace 时传入 --weights /path/to/weights,或在执行 info 时提供该路径。

要确认权重解压是否正确,请从顶层文件夹运行 shasum -a 256 -c weights/SHA256SUMS。

2. 安装

你需要 Python 3.11 或更高版本。

BASH
python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install numpy scipy numba pillow

3. 玩游戏

BASH
python -m nesformer run roms/thwaite.nes --frames 600 --show \
  --buttons "start@90-95+200-205,a@230-233+250-253+270-273+290-293+310-313+330-333+350-353+370-373+390-393+410-413+430-433+450-453+470-473+490-493+510-513+530-533+550-553+570-573+590-593"

--show 会在模型生成每一帧时,在终端中绘制该帧。运行结束后,CLI 会在当前文件夹中保存一个以 ROM 命名的动画 GIF(此处为 thwaite.gif)。

预期速度较慢。首次运行会使用 numba 编译引擎,耗时约 20 秒。此后,每帧需要 1–6 秒,因此 600 帧(相当于 NES 时间中的 10 秒)大约需要 25 分钟。

运行你自己的 ROM

将 run 指向任何使用 NROM 板卡(iNES mapper 0)的 .nes 文件,例如《超级马里奥兄弟》、《大金刚》或《越野摩托》。你需要提供 ROM;nesformer 仅在 roms/ 目录中附带三个自由许可的测试 ROM。

BASH
python -m nesformer run roms/smb.nes --frames 600 --show \
  --buttons "start@60-65,right@200-600,a@250-265+300-315+360-375+420-435+480-495+540-555"

该脚本会启动游戏,然后让马里奥向右行走并大约每秒跳跃一次。CLI 在启动时将 ROM 加载到模型的状态中,因此相同的权重可以在无需重新构建的情况下运行任何 NROM 游戏。其他板卡上的游戏会停止并显示一条消息:参见 局限性。

控制器脚本

--buttons 接受一个逗号分隔的条目列表。每个条目指定一个或多个由 + 连接的按钮,然后是 @,再后是一个或多个由 + 连接的帧范围:

Text
start@60-65                 在第 60 到 65 帧期间按下 Start
right@200-600               从第 200 帧到第 600 帧按住 Right
a@250-265+300-315           按两次 A
right+b@200-600             同时按住 Right 和 B(在《超级马里奥兄弟》中即为奔跑)

按钮包括 a、b、select、start、up、down、left 和 right。帧数从开机开始计算,每秒 60 帧,因此第 600 帧对应开机后的 10 秒。游戏在无法移动的画面中会忽略输入,因此稍早按住按钮不会造成问题。在《超级马里奥兄弟》中,更长的 A 键按压会使跳跃高度更高。

命令

命令功能说明
python -m nesformer run ROM在权重上运行 ROM 并保存为 GIF
python -m nesformer check ROM并行运行模型权重与参考 CPU,并在出现首个差异时停止
python -m nesformer trace ROM打印模型的 token 流(默认 40 个 token)
python -m nesformer build编译电路并写入 weights/(约需 10 秒)
python -m nesformer info描述检查点信息

run 的选项:

选项默认值含义
--frames N120在 N 帧后停止
--buttons SCRIPT无控制器输入(见上文)
--show关闭在终端中绘制帧(需要 24 位色支持,例如 iTerm2 或 Windows Terminal)
--gif PATHROM 名称指定动画 GIF 的保存路径
--png DIR关闭将每个保留的帧以 PNG 格式保存到 DIR。若仅使用 --png,则不保存 GIF。添加 --gif 可同时生成两者。
--every N1每第 N 帧保留一帧
--scale N2将保存的帧放大 N 倍
--enginefast可选 fast (numba)、numpy 或 hf (标准 transformers;需要 torch,约 10 tokens/s)
--no-skip关闭运行空闲等待循环的每次迭代(速度较慢;生成的帧相同)
--max-tokens N无在 N 个 token 后停止
--trace FILE无保存 token ID

run、check 和 trace 均接受 --weights、--engine、--buttons 和 --no-skip 参数。 check --tokens N 设置比较的深度(默认 50,000)。trace --tokens N 设置打印的 token 数量(默认 40)。build --out DIR 将检查点写入除 weights/ 以外的其他目录。

(注:更多技术实现细节与完整 API 文档请查阅原项目 README)