typesafe-mario：用结构化仿真器状态玩超级马里奥的智能体

TypeSafe Mario：一个实验性控制器，让 TypeSafe 的 Jev 模型为原版《Super Mario Bros.》直接选择 NES 手柄输入

模型不会接收游戏截图。适配层（harness）把模拟器遥测（telemetry）和内存（RAM）翻译成紧凑的、以对象为中心的 JSON，里面有马里奥的动作、跳跃轨迹、前方敌人、地形、测得的响应延迟、最近的控制结果以及关卡进度。Jev 从合法的控制器动作里挑一个，模拟器推进若干帧，然后循环重复。原始的本地瓦片网格（tile grid）仍然可以在调试日志和界面里查看，但不会复制到模型输入中。

架构
NES 模拟器 -> 遥测/RAM 解析器 -> 结构化 JSON -> Jev Choice（选择）-> 控制器输入初始动作集刻意做得很小：
noop
right
right_jump
right_run
right_run_jump
jump
left环境要求
Python 3.13 或更新版本
在环境变量 TYPESAFE_API_KEY 中配置的 TypeSafe API key
《Super Mario Bros.》的合法本地安装本仓库不包含任何任天堂 ROM 或其他受版权保护的游戏数据。你需要自行确保模拟器和游戏文件的来源合法、使用合规。

安装

py -3.13 -m venv .venv
.venv\Scripts\python -m pip install -e ".[mario,dev]"
$env:TYPESAFE_API_KEY="your-key"

在不启动游戏也不调用 API 的情况下，检视将发送给 TypeSafe 的确切 JSON 和文本：

.venv\Scripts\typesafe mario state demo

在 World 1-1 中运行，让 Jev 每八个模拟器步做一次决策。默认显示是一个可录制的单窗口，里面有实时游戏画面和模型遥测：

.venv\Scripts\typesafe mario play --env SuperMarioBros-v0 --frames-per-decision 8

仪表盘会展示所选动作、Choice 的完整概率分布、置信度、Jev 延迟、跳跃概率、危险分数、奖励以及解析后的游戏状态。按 R 键或点击 Restart 重开一局，死亡或通关后仪表盘依然保持打开。按 Esc 或 Q 退出。用 --display game 只显示模拟器窗口，用 --display none 则进入无界面基准测试。

每次决策都会写入 artifacts/run-<timestamp>.jsonl。这些记录包含延迟、动作概率、置信度、规范的模型状态、原始调试状态以及游戏结果，可以为实时叠加层或渲染后的社交短片提供数据。

解析器会生成什么
TypeSafe 直接接受 JSON，所以不必把遥测拍平成自然语言。

面向模型的对象按语义对观测分组：
player：位置、速度、是否着地、跳跃阶段、强化状态
trajectory：滞空时间、起跳后已飞过的距离，以及是否已锁定缺口跨越
hazard：最多三个敌人、其投影位置、接触时机、起跳截止时间
terrain：障碍/缺口几何形状、观测可靠性、上一次着地点的地形预览
reaction_timing：动作持续时间，以及测得的从观测到动作的延迟
recent_control：所选动作、持续时间、已取得的推进、观察到的结果
episode：生命数、计时器、进度、停滞次数、死亡、通关对人类来说，更完整的调试快照仍能渲染成紧凑文本：

Goal: Reach the flag in World 1-1 without dying.
Mario: x=172 y=79, moving right, airborne=False, status=small
Progress: 172 (best 172), time=387, lives=2
Nearby enemies: goomba 42px ahead
Local grid (# solid, . empty, E enemy, M Mario):
...........
...........
...........
..M..E.....
###########

结构化对象是规范的，文本视图只用于调试和界面。

TypeSafe 判定
每次请求会基于同一状态给出三个相互独立的判定。Choice 选出下一个控制器宏动作；Noul 估计此刻前跳是否有用；Score 度量即时危险程度，用于实时可视化。

精确的时间计算留在代码里。比如，解析器会把测得的响应耗时、敌人动作、动作节奏以及跳起越障时间组合成一个带类型的 jump_must_start_this_decision（本轮决策必须起跳）事实。Jev 解读这些事实，控制器选择权依然在它手里，没有脚本式的恢复动作覆盖。

开发

.venv\Scripts\ruff format --check src tests
.venv\Scripts\ruff check src tests
.venv\Scripts\python -m pytest -q