English model card aligned with gamescaling.github.io

README.md

@@ -1,70 +1,104 @@
 ---
+library_name: transformers
+pipeline_tag: image-text-to-text
 tags:
 - gamescaling
+- game-agent
+- embodied-agent
+- keyboard-mouse
 - qwen3_5
 ---
 
-# GameScaling 推理模板
+# Scaling in Games: Continued Pre-Training for Embodied Agents in Diverse Virtual Worlds
 
-用 GameScaling checkpoint 玩游戏、或把它当 baseline 所需的全部**推理侧**代码：系统提示词
-规范、多轮消息构造、vLLM 请求参数、动作反解，以及论文三个 benchmark（ViZDoom、
-OmniGameArena、GameWorld）的接入。不含任何训练代码。
+[Project page](https://gamescaling.github.io) · [Citation](#citation)
+
+GameScaling models are Qwen3.5 vision-language models with continued pre-training (CPT) on
+keyboard-and-mouse gameplay. Each call reads the current game frame (plus a short history of past
+frames and actions) and outputs the next **200 ms of keyboard and mouse actions**: 6 steps of
+33 ms each, plus one mouse movement and scroll for the whole chunk. The model can optionally
+think first.
+
+This repository releases eight checkpoints (four model sizes × two data mixtures, all trained on
+1,600 h of gameplay), the inference client, and the standard system-prompt template.
+
+## Checkpoints
+
+| Model | Folder | Mixture |
+|---|---|---|
+| GameScaling-0.8B-S1 | `models/0p8b_s1_1600h_gs6736` | S1 |
+| GameScaling-0.8B-S3 | `models/0p8b_s3_1600h_gs6760` | S3 |
+| GameScaling-2B-S1 | `models/2b_s1_1600h_gs6736` | S1 |
+| GameScaling-2B-S3 | `models/2b_s3_1600h_gs6760` | S3 |
+| GameScaling-9B-S1 | `models/9b_s1_1600h_gs6736` | S1 |
+| GameScaling-9B-S3 | `models/9b_s3_1600h_gs6760` | S3 |
+| GameScaling-27B-S1 | `models/27b_s1_1600h_gs6995` | S1 |
+| GameScaling-27B-S3 | `models/27b_s3_1600h_gs7020` | S3 |
+
+- **S1**: trained on Minecraft gameplay only.
+- **S3**: a balanced mixture. Minecraft is cut to 27%, and the rest comes from other games in an
+  80-game, mostly 3D corpus.
+- Folder names: `<size>_<mixture>_<hours of gameplay>_gs<training steps>`.
+- All weights are bfloat16. Every folder has its own `chat_template.jinja`; keep it (see below).
+
+In the paper, more data helps most in worlds that are in the training corpus. More diversity (S3)
+helps most in unseen 3D worlds whose actions resemble training. See the
+[project page](https://gamescaling.github.io) for the full results.
+
+## Repository layout
 
 ```
-gamescaling/                核心包，只依赖 requests + Pillow
-  prompt.py                 系统提示词（标准 build_system_prompt + GameWorld 版式）
-  policy.py                 多轮客户端：历史窗口、图像编码、请求体
-  action.py                 动作格式与反解（200 ms chunk -> 6 x 33 ms 键鼠）
-  keymaps.py                训练词表 <-> 浏览器/Playwright 键名
+models/                      eight checkpoints (Qwen3.5 architecture)
 prompts/
-  system_prompt_template.txt  标准系统提示词骨架，填三个占位符即可用于任意游戏
-  example_doom_battle1.txt    填好的示例
-models/                     8 个 Qwen3.5 checkpoint，各自带 chat_template.jinja
-scripts/serve_vllm.sh       起 OpenAI 兼容服务
-tests/test_core.py          离线单测（不需要 GPU）
+  system_prompt_template.txt standard system prompt; fill in three placeholders for any game
+  example_doom_battle1.txt   a filled-in example
+gamescaling/                 inference client; depends only on requests + Pillow
+  prompt.py                  system prompts
+  policy.py                  multi-turn client: history window, image encoding, request body
+  action.py                  action format and parser (200 ms chunk -> 6 x 33 ms key/mouse)
+  keymaps.py                 training key vocabulary <-> browser / Playwright key names
+scripts/serve_vllm.sh        OpenAI-compatible server
+tests/test_core.py           offline unit tests (no GPU or server needed)
 ```
 
-默认推理：系统提示词用 `build_system_prompt` 标准格式，每轮 user 是 `current game screen` 加一帧
-游戏画面，assistant 预填 `<think>`。checkpoint 目录：
+## 1. Download and serve
 
-| 目录 | 规模 |
-|---|---|
-| `models/0p8b_s1_1600h_gs6736` | 0.8B，stage 1 |
-| `models/0p8b_s3_1600h_gs6760` | 0.8B，stage 3 |
-| `models/2b_s1_1600h_gs6736` | 2B，stage 1 |
-| `models/2b_s3_1600h_gs6760` | 2B，stage 3 |
-| `models/9b_s1_1600h_gs6736` | 9B，stage 1 |
-| `models/9b_s3_1600h_gs6760` | 9B，stage 3 |
-| `models/27b_s1_1600h_gs6995` | 27B，stage 1 |
-| `models/27b_s3_1600h_gs7020` | 27B，stage 3 |
+Download only the checkpoint you need:
 
-`27b_s3` 的权重按约 30GB 切成多片，并带 `model.safetensors.index.json`。请用该 checkpoint
-目录里的 `chat_template.jinja`，不要换成原版 Qwen 模板。
+```bash
+pip install -U huggingface_hub
+huggingface-cli download THUSI-Lab/GameScaling \
+    --include "models/9b_s1_1600h_gs6736/*" "gamescaling/*" "prompts/*" "scripts/*" \
+    --local-dir ./GameScaling
+cd GameScaling
+```
 
-## 1. 部署模型
+Serve it with vLLM (tested with 0.17.0):
 
 ```bash
-pip install "vllm>=0.17"          # checkpoint 是 Qwen3.5 架构；测试版本 0.17.0
-bash scripts/serve_vllm.sh /path/to/checkpoint 8000      # 单卡即可跑 0.8B-9B
+pip install "vllm>=0.17"
+bash scripts/serve_vllm.sh models/9b_s1_1600h_gs6736 8000        # 0.8B-9B fit on one GPU
+bash scripts/serve_vllm.sh models/27b_s1_1600h_gs6995 8000 2      # 27B: tensor parallel 2
 ```
 
-脚本以 `--served-model-name gamescaling` 起服务，本仓库所有客户端默认连
-`http://127.0.0.1:8000/v1`、模型名 `gamescaling`。请使用 checkpoint 目录里自带的
-`chat_template.jinja`（vLLM 默认就会用），**不要**换成原版 Qwen 模板：自带模板会把没有
-思维链的历史轮渲染成 `<think>\n\n</think>\n\n<|action_start|>...`，与训练样本逐 token 一致。
+The script serves the model as `gamescaling`. The client connects to `http://127.0.0.1:8000/v1`
+by default. Use the `chat_template.jinja` in the checkpoint folder (vLLM loads it by default). **Do
+not** replace it with the stock Qwen template: this one renders past turns without reasoning as
+`<think>\n\n</think>\n\n<|action_start|>...`, which is token-for-token what training used.
 
-## 2. 系统提示词骨架
+## 2. System prompt template
 
-`prompts/system_prompt_template.txt` 是标准系统提示词，只有三处要按游戏填写，其余部分**原样保留**
-（checkpoint 依赖 Output Format 那一段的精确文本来决定输出标签）：
+`prompts/system_prompt_template.txt` is the standard system prompt. Fill in three placeholders
+and keep everything else **exactly as written**: the model decides its output tags from the
+exact text of the Output Format section.
 
-| 占位符 | 填什么 | 示例 |
+| Placeholder | What to write | Example |
 |---|---|---|
-| `{GAME_NAME}` | 游戏名，出现两次（开场白和键位标题） | `Doom Battle-1` |
-| `{GAME_RULES}` | 游戏是什么、目标、怎么计分，一段英文 | `Kill as many monsters as possible; collect health and ammo.` |
-| `{KEY_BINDINGS}` | 每行一个 `- <键> -> <作用>`，键名必须用训练词表（见 §5） | 见下 |
+| `{GAME_NAME}` | The game's name. It appears twice: in the opening and the key-list heading. | `Doom Battle-1` |
+| `{GAME_RULES}` | One English paragraph: what the game is, the goal, and how it is scored. | `Kill as many monsters as possible; collect health and ammo.` |
+| `{KEY_BINDINGS}` | One `- <key> -> <effect>` line per key. Use training key names (§5). | see below |
 
-`{KEY_BINDINGS}` 的写法：
+Example `{KEY_BINDINGS}`:
 
 ```text
 - W -> Move forward
@@ -75,11 +109,12 @@ bash scripts/serve_vllm.sh /path/to/checkpoint 8000      # 单卡即可跑 0.8B-
 - Mouse X Y -> aim / rotate the camera (X>0 right, Y>0 down)
 ```
 
-最后一行只在鼠标控制视角的游戏里加，并且必须原样照抄。键名规则：字母大写（`W`），数字键写
-`zero`..`nine`，F1-F12 写 `One`..`Twelve`，鼠标键写 `LB` / `RB` / `MB`，方向键写
-`Up` / `Down` / `Left` / `Right`。填好的完整示例见 `prompts/example_doom_battle1.txt`。
+Add the last line only for games where the mouse controls the camera, and copy it verbatim. Key
+names: uppercase letters (`W`); digits as `zero`..`nine`; F1-F12 as `One`..`Twelve`; mouse
+buttons as `LB` / `RB` / `MB`; arrows as `Up` / `Down` / `Left` / `Right`. A complete filled-in
+prompt is in `prompts/example_doom_battle1.txt`.
 
-直接用文本文件：
+Using the text file directly:
 
 ```python
 tpl = open("prompts/system_prompt_template.txt").read().rstrip("\n")
@@ -89,218 +124,173 @@ system = (tpl.replace("{GAME_NAME}", "Doom Battle-1")
                       "- Mouse X Y -> aim / rotate the camera (X>0 right, Y>0 down)"))
 ```
 
-和下面 `build_system_prompt(...)` 生成的结果逐字节相同（`tests/test_core.py` 会检查）。
+The result is byte-identical to what `build_system_prompt(...)` below produces;
+`tests/test_core.py` checks this.
 
-## 3. 最小用法
+## 3. Minimal usage
 
 ```python
 from PIL import Image
 from gamescaling import GameScalingPolicy, PolicyConfig, build_system_prompt
 
-# 任意游戏：标准系统提示词（游戏名 + 规则 + 训练词表键位 + think/action 输出格式）
 system = build_system_prompt(
     "Doom Battle-1",
     rules="Kill as many monsters as possible; collect health and ammo.",
     key_bindings={"W": "Move forward", "S": "Move backward", "A": "Strafe left",
                   "D": "Strafe right", "LB": "Fire"},
-    mouse_aim=True,               # 鼠标控视角的游戏
-)                                 # reasoning 默认 True，与默认的 <think> 预填一致
-policy = GameScalingPolicy(system, PolicyConfig())   # 预填 <think>，画面按原尺寸送入
-policy.reset()                                       # 每局开始调用
-decision = policy.act(Image.open("frame.png"))       # 一次调用 = 一个 200 ms 决策
+    mouse_aim=True,               # the mouse controls the camera
+)                                 # reasoning=True by default, matching the <think> prefill
+policy = GameScalingPolicy(system, PolicyConfig())   # prefills <think>; frame sent at native size
+policy.reset()                                       # call at the start of every episode
+decision = policy.act(Image.open("frame.png"))       # one call = one 200 ms decision
 a = decision.action
-a.mouse      # (X, Y, Z)：本 chunk 鼠标位移（千分比屏幕）+ 滚轮
-a.steps      # 6 组，每组是这 33 ms 内按住的键
-a.parsed     # False = 无法解析，按 no-op 执行
+a.mouse      # (X, Y, Z): mouse movement for this chunk (per-mille of the screen) + scroll
+a.steps      # 6 groups: the keys held during each 33 ms step
+a.parsed     # False = could not be parsed; execute as a no-op
 ```
 
-之后把 `a` 交给你的执行器：6 个 33 ms 子步，每步按住该组的键（相邻两组都有的键保持按住，
-不重新按下）；鼠标位移 `X/1000*屏宽`、`Y/1000*屏高` 在 200 ms 内分摊或一次性下发均可，
-三个集成各自的做法见下文。
+Pass `a` to your executor. Run 6 steps of 33 ms, holding that step's keys during each one. Keys
+that appear in two consecutive groups stay held rather than being pressed again. Mouse movement
+is `X/1000 * screen width` and `Y/1000 * screen height`. You can spread it over the 200 ms or
+send it at once.
 
-默认口径不绑定某个 benchmark：任意游戏画面 + `build_system_prompt` 标准格式 + 预填 `<think>`。
-`TRAINING_SYSTEM_PROMPT` 是预训练的通用提示词，只有 action-only 输出格式，和 `<think>` 预填
-不匹配，只用于消融。复现论文三张表时再改用
-`PolicyConfig.preset("omnigamearena" | "vizdoom" | "gameworld")`：前两档把画面缩到 854×480；
-`gameworld` 不预填 `<think>`，提示词要用 `build_gameworld_system_prompt(..., reasoning=False)`。
+Defaults are not tied to any benchmark: any game frame, the standard system prompt, and a
+`<think>` prefill. To reproduce a paper table, use
+`PolicyConfig.preset("omnigamearena" | "vizdoom" | "gameworld")` instead (§6).
+`TRAINING_SYSTEM_PROMPT` is the generic pre-training prompt. Its Output Format is action-only and
+does not match a `<think>` prefill, so use it only for ablations.
 
-## 4. 系统提示词规范
+## 4. Prompt and message structure
 
-所有 benchmark 用同一骨架，顺序固定（`gamescaling/prompt.py`）：
+Every benchmark uses the same skeleton in a fixed order (`gamescaling/prompt.py`):
 
-1. **开场白**：游戏专家 + 游戏名 + "规划接下来 200ms、6 步、每步 33ms" 的契约；
-2. `**Game Rules**`：游戏是什么、怎么计分；
-3. **操作说明**：本游戏用到的键，**必须写成训练词表**（见 §5）；
-4. `**Task Instruction**`：仅 GameWorld（一个游戏有多个任务）；
-5. `**Output Format**`：模型据此决定输出格式；
-6. `**Explanation**` + `**Key Naming Rules**`。
+1. **Opening**: gaming expert + game name + the contract "plan the next 200 ms as 6 steps of
+   33 ms";
+2. `**Game Rules**`: what the game is and how it is scored;
+3. **Controls**: the keys the game uses, **written in the training vocabulary** (§5);
+4. `**Task Instruction**`: GameWorld only (one game can have several tasks);
+5. `**Output Format**`: how the model picks its output format;
+6. `**Explanation**` + `**Key Naming Rules**`.
 
-两种版式只在第 3 节和分隔符上不同：
+There are two layouts. They differ only in section 3 and the separators:
 
-- `build_system_prompt(...)`：键位列表版（`**Common Keys in <game>**` + `- W -> Move
-  forward`），ViZDoom、OmniGameArena 和**接入新游戏**都用它；鼠标控制视角的游戏加
-  `mouse_aim=True`。
-- `build_gameworld_system_prompt(...)`：自由段落版（`**Role and Controls**`），用于
-  GameWorld 那种自带文字说明的游戏；浏览器键名用 `translate_controls` 转成训练词表
-  （`ArrowLeft` -> `Left`，`a/d` -> `A/D`，`1-9:` -> `one-nine:`）。
+- `build_system_prompt(...)`: key list (`**Common Keys in <game>**` + `- W -> Move forward`).
+  Used for ViZDoom, OmniGameArena and **any new game**. Add `mouse_aim=True` for games where the
+  mouse controls the camera.
+- `build_gameworld_system_prompt(...)`: free-text paragraphs (`**Role and Controls**`), for
+  games that come with their own written controls, as in GameWorld. `translate_controls`
+  rewrites browser key names into the training vocabulary (`ArrowLeft` -> `Left`, `a/d` ->
+  `A/D`, `1-9:` -> `one-nine:`).
 
-`Output Format` 有两种，**必须与客户端是否 prefill `<think>` 保持一致**：
+The Output Format **must match whether the client prefills `<think>`**:
 
-| `reasoning` | 客户端 | 模型输出 |
+| `reasoning` | Client | Model output |
 |---|---|---|
-| `True` | `think_prefill=True`，assistant 以 `<think>` 开头续写 | 自己决定想不想、想多久，然后闭合 `</think>` 输出动作 |
-| `False` | 不 prefill | 直接输出 `<|action_start|>...<|action_end|>` |
-
-提示词请原样拷贝，不要改写：checkpoint 是按这段 Output Format 的精确文本来决定输出标签的。
-每轮 user 消息的���本固定为 `current game screen`，后接当前帧。
+| `True` (default) | `think_prefill=True`: the assistant turn starts with `<think>` | Decides whether and how long to think, closes `</think>`, then outputs the action |
+| `False` | no prefill | Outputs `<|action_start|>...<|action_end|>` directly |
 
-多轮消息（`policy.py`）：
+Each user turn is the text `current game screen` followed by the frame. Multi-turn messages
+(`policy.py`):
 
 ```
-system     系统提示词
-user       "current game screen" + 第 t-k 帧        ┐ 最近 history_len 轮
-assistant  第 t-k 轮执行的动作（默认不带思维链）      ┘
+system     system prompt
+user       "current game screen" + frame t-k          ┐ last history_len turns (default 5)
+assistant  action taken at t-k (no reasoning)          ┘
 ...
-user       "current game screen" + 当前帧
-assistant  "<think>"（仅 think_prefill 时，continue_final_message=True）
+user       "current game screen" + current frame
+assistant  "<think>"   (prefill; continue_final_message=True)
 ```
 
-历史轮只放动作（`history_think=0`，论文口径）。解析失败的轮在历史里存成显式 no-op
-`<|action_start|>0 0 0 ; ; ; ; ; ; <|action_end|>`，而不是模型的原始坏输出。
+Past turns keep only the action (`history_think=0`, as in the paper). A turn that failed to parse
+is stored as an explicit no-op, `<|action_start|>0 0 0 ; ; ; ; ; ; <|action_end|>`, not as the
+raw bad output.
 
-## 5. 动作格式与反解
+Default request: `temperature=1.0`, `max_tokens=2048`, `stop=["<|action_end|>"]`,
+`skip_special_tokens=false`, JPEG frames (quality 90) at native resolution.
+
+## 5. Action format
 
 ```
 <|action_start|>X Y Z ; g1 ; g2 ; g3 ; g4 ; g5 ; g6<|action_end|>
 ```
 
-- `X Y`：整个 200 ms 的鼠标位移，千分比屏幕（`X = Σdx / 屏宽 × 1000`），截断到 ±1000；
-  X>0 向右，Y>0 向下。
-- `Z`：滚轮格数，截断到 ±5，Z>0 向上。
-- `g1..g6`：六个 33 ms 子步，每组列出这段时间内**按住**的键，最多 4 个；空组 = 全部松开，
-  但 `;` 要保留。
-- `<|action_start|>` / `<|action_end|>` 是 special token，请求里必须带
-  `skip_special_tokens: false`（`build_request` 已设置），否则服务端会把标签吃掉
-  （`parse_action` 对裸 `X Y Z ; ...` 也能兜底）。
-- 动作**只从最后一个 `</think>` 之后**读取：会思考的模型常在思维链里复述格式，从全文搜会执行
-  那段引用。`<think>` 没闭合 = 生成被截断，按 no-op 处理（`Action.truncated=True`）。
-
-训练词表（74 个，大小写敏感，`gamescaling.action.KEY_VOCAB`）：
-
-| 类别 | token |
+- `X Y`: mouse movement over the whole 200 ms, in per-mille of the screen
+  (`X = Σdx / screen width × 1000`), clipped to ±1000. X>0 is right, Y>0 is down.
+- `Z`: scroll notches, clipped to ±5. Z>0 is up.
+- `g1..g6`: six 33 ms steps. Each group lists the keys **held** during that step, at most 4. An
+  empty group releases all keys, but the `;` must stay.
+- `<|action_start|>` / `<|action_end|>` are special tokens. Requests must set
+  `skip_special_tokens: false` (`build_request` does), or the server strips the tags.
+  `parse_action` also accepts a bare `X Y Z ; ...` as a fallback.
+- The action is read **only after the last `</think>`**: a model that thinks often quotes the
+  format inside its reasoning. An unclosed `<think>` means the generation was cut off; it is
+  executed as a no-op (`Action.truncated=True`).
+
+Training key vocabulary (74 tokens, case-sensitive, `gamescaling.action.KEY_VOCAB`):
+
+| Group | Tokens |
 |---|---|
-| 字母 | `A`..`Z` |
-| 数字行 | `zero` `one` .. `nine` |
-| F1-F12 | `One` `Two` .. `Twelve`（**首字母大写** = F 键） |
-| 鼠标键 | `LB` `RB` `MB` |
-| 方向 | `Up` `Down` `Left` `Right` |
-| 其他 | `Shift` `Ctrl` `Alt` `Tab` `Caps` `Esc` `Space` `Enter` `Back` `Delete` `Insert` `Home` `End` `Pause` `Equal` `Minus` `Period` `Slash` `Quote` |
-
-不在词表里的 token 被丢弃（记在 `Action.dropped`）。`keymaps.TO_PLAYWRIGHT` 给出到浏览器
-键名的映射。
-
-## 6. 三个 benchmark
+| Letters | `A`..`Z` |
+| Number row | `zero` `one` .. `nine` |
+| F1-F12 | `One` `Two` .. `Twelve` (**capitalized** = function key) |
+| Mouse buttons | `LB` `RB` `MB` |
+| Arrows | `Up` `Down` `Left` `Right` |
+| Other | `Shift` `Ctrl` `Alt` `Tab` `Caps` `Esc` `Space` `Enter` `Back` `Delete` `Insert` `Home` `End` `Pause` `Equal` `Minus` `Period` `Slash` `Quote` |
 
-三者都是**暂停时钟（pdq）**：模型思考时游戏冻结，只在执行 chunk 时前进。论文所有主表都是这个
-口径；不同时钟之间的分数不可比。
+Tokens outside the vocabulary are dropped and recorded in `Action.dropped`.
+`keymaps.TO_PLAYWRIGHT` maps them to browser key names.
 
-### 6.1 ViZDoom（自包含）
+## 6. Paper evaluation settings
 
-```bash
-pip install -r requirements.txt vizdoom==1.2.4
-python -m integrations.vizdoom.run --maps battle1 battle2 defend_the_center defend_the_line \
-    --episodes 10 --out runs/vizdoom
-```
-
-四张图、每图 10 局、每局最多 350 个 chunk（= 2100 tic 的地图超时）。一个 33 ms 子步 = 一个
-tic（35 tic/s），每个子步单独 `make_action(vec, 1)`。鼠标按 Doom 的投影换算成转向角
-（`atan((X/1000) / focal)`，即把屏幕上偏移 X 处的目标转到准星；focal 为实测值），转角在
-6 个 tic 上均分；HUD 开。计分：battle 图数击杀，defend 图击杀减死亡；`overall` 是四图均值的均值。
-场景文件来源见 `integrations/vizdoom/scenarios/PROVENANCE.md`。
-
-### 6.2 OmniGameArena
+The paper evaluates on MCU (Minecraft), ViZDoom, OmniGameArena and GameWorld. The main tables use
+a **time-paused** clock: the game freezes while the model thinks and advances only while a chunk
+executes. The project page also reports a real-time setting, where the game keeps running during
+inference. Scores from different clocks are not comparable.
 
-在 [OmniGameArena](https://github.com/mxlin043/OmniGameArena)（测于 `f3a4057`）里注册
-agent kind `gamescaling`：
-
-```bash
-bash integrations/omnigamearena/install.sh /path/to/OmniGameArena
-export PYTHONPATH=$PWD:$PWD/integrations/omnigamearena:$PYTHONPATH
-cd /path/to/OmniGameArena
-# 按 OmniGameArena README 启动 UE5（默认端口 12345）
-python scripts/run_benchmark.py --config configs/gamescaling/monster_shoot.yaml
-```
+Client presets for reproducing the paper:
 
-补丁只做两件事：在 `factory.py` 注册 `gamescaling`；把 `runner.py` 对 `tkinter`
-的导入改成只在 `--live` 时加载（无显示器的服务器上原版会直接 ImportError）。
+| Preset | Frame | `<think>` prefill | Other |
+|---|---|---|---|
+| `omnigamearena` | resized to 854×480, JPEG | yes | 300 steps per episode (500 for `scene_escape` and `cue_chase`), 3 episodes |
+| `vizdoom` | resized to 854×480, JPEG | yes | no stop string; 4 maps × 10 episodes, at most 350 chunks each |
+| `gameworld` | height 480, PNG (Lanczos) | no | `max_tokens=4096`, lenient parsing; use `build_gameworld_system_prompt(..., reasoning=False)` |
 
-七个 solo 游戏配置在 `configs/gamescaling/`：pdq、每局 300 步（`scene_escape`、
-`cue_chase` 为 500）、3 局、温度 1.0、自由思考、历史 5 帧只留动作、画面缩到 854x480。
-论文的计分约定：`solo_craft` 分数为 `min(V/50, 1)`（V 为 UE 返回的原始点数），其余游戏直接用
-benchmark 分数；OVERALL 是七个游戏的均值。
+All presets keep 5 history turns (frame + action) at temperature 1.0. On OmniGameArena,
+`solo_craft` is scored as `min(V/50, 1)` from the raw points `V`, and the overall score is the
+mean over the seven games.
 
-两个实际部署时的注意点：
+When running OmniGameArena, use **one UE5 instance per GPU**. Actions are executed in wall-clock
+time (6 × 33 ms), and instances sharing a GPU's renderer barely move. Scores drop sharply with no
+error message.
 
-- **一张 GPU 只跑一个 UE5 实例。** 动作按墙钟 6×33 ms 执行，多个实例抢一张卡的渲染时，按住
-  前进 0.2 s 几乎不动，分数会大幅下降且不报错。
-- `solo_craft` 的后续 episode 请换一个新的 UE5 进程；复用实例时第 2、3 局会立即结束并复报
-  第 1 局分数。
+## 7. Adding a new game
 
-### 6.3 GameWorld
+1. Fill in `prompts/system_prompt_template.txt` (§2), or call `build_system_prompt` with the game
+   name, rules and `key_bindings` in the training vocabulary. Add `mouse_aim=True` if the mouse
+   controls the camera.
+2. Capture one frame every 200 ms (or at every decision under a paused clock) and call
+   `policy.act(frame)`.
+3. Execute the returned `Action` as in §5: held keys for 6 steps of 33 ms, plus mouse movement and
+   scroll.
+4. Keep the default client (native frame size, `<think>` prefill, standard prompt). Switch to a
+   preset (§6) only to match a paper table.
 
-在 [GameWorld](https://github.com/gameworld-project/gameworld)（测于 `e236a39`）里注册模型
-id `gamescaling`：
+## 8. Tests
 
 ```bash
-bash integrations/gameworld/install.sh /path/to/gameworld
-export PYTHONPATH=$PWD:$PYTHONPATH
-cd /path/to/gameworld
-# 上游仓库只带 2 个游戏；完整游戏库的游戏在该库的 benchmark/ 子目录下
-git clone --depth 1 https://github.com/gameworld-dev/gameworld-games.git /tmp/gameworld-games
-rm -rf games/benchmark && mv /tmp/gameworld-games/benchmark games/benchmark
-pip install -r requirements.txt && python -m playwright install --with-deps chromium
-python main.py --config 01_2048+01_01+gamescaling --headless
-python run_suite.py --suite <your_suite.yaml>          # 批量：suite 里 model 写 gamescaling
+python tests/test_core.py      # or: python -m pytest tests/
 ```
 
-补丁新增一种 `key_timeline` 动作：六个 33 ms 槽位的按住键（跨窗口保持），加一次鼠标移动和
-滚轮。鼠标是千分比屏幕空间里的虚拟光标，从中心出发、每个 chunk 移动 (X, Y) 并截断到屏幕内。
-系统提示词走 `gamescaling_template.j2`（自由段落版），控制说明经 `translate_controls`
-转成训练词表。
+Offline checks of prompts, request bodies and action parsing; no GPU or server needed.
 
-口径（`catalog/models/gamescaling.yaml`）：历史 5 轮（截图 + 动作）、截图缩放到高 480
-（PNG、Lanczos）、不 prefill `<think>`、`max_tokens=4096`、温度 1.0、停在
-`<|action_end|>`、宽松解析。`wasd_remap`：只在某游戏 WASD 非法而方向键合法时，把模型输出
-的 WASD 映射成方向键（模型主要在 PC 游戏上训练，习惯用 WASD 移动）。环境变量
-`GAMESCALING_ENDPOINT` 可覆盖服务地址，`GAMESCALING_THINK=1` 可打开 think prefill（非论文口径）。
+## Citation
 
-## 7. 接入新游戏
-
-1. 填 `prompts/system_prompt_template.txt`（§2），或用 `build_system_prompt` 写提示词：游戏名、规则、`key_bindings` 用训练词表；鼠标控视角
-   时加 `mouse_aim=True`；`reasoning` 与 `think_prefill` 一致。
-2. 每 200 ms（或暂停时钟下每次决策）截一帧，调用 `policy.act(frame)`。
-3. 按 §5 执行 `Action`：6 个 33 ms 子步的按住键 + 鼠标位移 + 滚轮。
-4. 新游戏沿用默认客户端（原尺寸画面、预填 `<think>`、`build_system_prompt` 标准格式）。
-   要对齐论文某一张表时，再改用
-   `PolicyConfig.preset("omnigamearena" | "vizdoom" | "gameworld")`。
-
-## 8. 与论文评测代码的差异
-
-发布代码与论文内部评测代码逐项对拍过：三个 benchmark 的全部系统提示词逐字节相同
-（ViZDoom 4 图、OmniGameArena 12 游戏 44 个 prompt、GameWorld 170 个任务），历史 trace
-中各 4000 条左右的模型回复反解结果完全相同。以下几处有意改动只在边缘情况下有区别：
-
-- OmniGameArena 的动作只从最后一个 `</think>` 之后读取（内部代码搜全文，思维链里复述格式时
-  会误执行那段引用）。
-- GameWorld 中解析失败的轮在历史里存为显式 no-op（内部代码存原始输出）。
-- GameWorld 槽位时长用 200/6 = 33.33 ms（内部为 33.0 ms）。
-- ViZDoom 历史轮保存动作原文（内部去掉首尾空白），episode 种子用 `crc32`（内部用 Python
-  `hash`，跨进程不稳定）。
-- OmniGameArena 的 `map_wait` 用上游默认 3 s。内部评测等 60 s，但前 3 s 之后世界是冻结的，
-  所以两者进入第一步时的游戏时间一致。
-
-## 9. 测试
-
-```bash
-python tests/test_core.py      # 或 python -m pytest tests/；离线：提示词、请求体、动作反解，不需要 GPU / 服务
+```bibtex
+@article{zhang2026scaling,
+  title   = {Scaling in Games: Continued Pre-Training for Embodied Agents in Diverse Virtual Worlds},
+  author  = {Zhang, Kuan and Chen, Yukun and Yang, Zhihao and Su, Yue and Wu, Xiangnan and
+             Chen, Zirong and Luo, Run and Hou, Jinkun and Tan, Tao and Zheng, Yinhe and Li, Yiming},
+  journal = {arXiv preprint},
+  year    = {2026}
+}
 ```