Card: aligned with THUSI-Lab/GameScaling

LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

README.md

@@ -15,46 +15,428 @@ tags:
 - qwen3_5
 ---
 
+<div align="center">
+
 <p align="center">
   <img src="https://huggingface.co/THUSI-Lab/GameScaling/resolve/main/assets/logos/affiliations.png" alt="miHoYo · Tsinghua University · University of Chinese Academy of Sciences · The University of Hong Kong" width="100%" style="width:100%;max-width:100%;">
 </p>
 
-# GameScaling-0.8B-S3
+<h1 align="center" style="font-size:3.2em;line-height:1.1;margin:0.2em 0 0.15em;">Scaling in Games</h1>
 
-One of the eight checkpoints of **Scaling in Games: Continued Pre-Training for Embodied Agents in
-Diverse Virtual Worlds**. Qwen3.5-0.8B with continued pre-training on a balanced mixture: 27% Minecraft, the rest from other games, 1,600 h of
-keyboard-and-mouse gameplay, 6,760 training steps. Each call takes the current game frame (plus
-a short history) and returns the next 200 ms of keyboard and mouse actions.
+<h2 align="center" style="font-size:1.1em;line-height:1.3;font-weight:600;margin:0 0 0.9em;border:none;white-space:nowrap;">Continued Pre-Training for Embodied Agents in Diverse Virtual Worlds</h2>
 
-**The inference client, system prompt, action format and usage guide are in
-[THUSI-Lab/GameScaling](https://huggingface.co/THUSI-Lab/GameScaling).** Project page:
-[gamescaling.github.io](https://gamescaling.github.io).
+<p align="center" style="line-height:1.5;margin:0.4em 0 0.3em;">
+<span style="white-space:nowrap;"><b>Kuan Zhang</b><sup>1,2,*,‡</sup></span>, <span style="white-space:nowrap;"><b>Yukun Chen</b><sup>1,3,*,‡</sup></span>, <span style="white-space:nowrap;"><b>Zhihao Yang</b><sup>1,3,*,‡</sup></span>, <span style="white-space:nowrap;">Yue Su<sup>4</sup></span>, <span style="white-space:nowrap;">Xiangnan Wu<sup>3</sup></span>, <span style="white-space:nowrap;">Zirong Chen<sup>2</sup></span>, <span style="white-space:nowrap;">Run Luo<sup>1,5,‡</sup></span>, <span style="white-space:nowrap;">Jinkun Hou<sup>6</sup></span>, <span style="white-space:nowrap;">Tao Tan<sup>1</sup></span>, <span style="white-space:nowrap;"><b>Yinhe Zheng</b><sup>1,†</sup></span>, <span style="white-space:nowrap;"><b>Yiming Li</b><sup>2,†</sup></span>
+</p>
 
-| | |
-|---|---|
-| Backbone | [Qwen/Qwen3.5-0.8B](https://huggingface.co/Qwen/Qwen3.5-0.8B) |
-| Mixture | S3 (a balanced mixture: 27% Minecraft, the rest from other games) |
-| Weights | 2.2 GB, bfloat16 |
-| GPUs (bf16) | 1 |
-| All checkpoints | [GameScaling collection](https://huggingface.co/collections/THUSI-Lab/gamescaling-model-6acf7c0c6500ebee61a7f872) |
+<p align="center" style="font-size:0.85em;line-height:1.5;margin:0 0 0.6em;">
+<span style="white-space:nowrap;"><sup>1</sup>miHoYo Honkai AI R&amp;D Team</span> &nbsp; <span style="white-space:nowrap;"><sup>2</sup>College AI, Tsinghua University</span> &nbsp; <span style="white-space:nowrap;"><sup>3</sup>University of Chinese Academy of Sciences</span> &nbsp; <span style="white-space:nowrap;"><sup>4</sup>MMLab, The University of Hong Kong</span> &nbsp; <span style="white-space:nowrap;"><sup>5</sup>National University of Singapore</span> &nbsp; <span style="white-space:nowrap;"><sup>6</sup>Peking University</span><br>
+<span style="white-space:nowrap;"><sup>*</sup>Equal contribution</span> &nbsp; <span style="white-space:nowrap;"><sup>†</sup>Corresponding author</span> &nbsp; <span style="white-space:nowrap;"><sup>‡</sup>Work done while interning at miHoYo</span>
+</p>
+
+<p align="center">
+  <a href="https://gamescaling.github.io" style="display:inline-block;margin:2px;"><img src="https://img.shields.io/badge/Project-Page-1f6feb?style=for-the-badge&logo=googlechrome&logoColor=white" alt="Project Page" style="display:inline-block;vertical-align:middle;margin:0;"></a>
+  <a href="https://gamescaling.github.io" style="display:inline-block;margin:2px;"><img src="https://img.shields.io/badge/arXiv-coming%20soon-lightgrey?style=for-the-badge&logo=arxiv&logoColor=white" alt="arXiv (coming soon)" style="display:inline-block;vertical-align:middle;margin:0;"></a>
+  <a href="https://github.com/THUSI-Lab/GameScaling" style="display:inline-block;margin:2px;"><img src="https://img.shields.io/badge/Code-GitHub-181717?style=for-the-badge&logo=github&logoColor=white" alt="Code" style="display:inline-block;vertical-align:middle;margin:0;"></a>
+  <a href="https://huggingface.co/collections/THUSI-Lab/gamescaling-model-6acf7c0c6500ebee61a7f872" style="display:inline-block;margin:2px;"><img src="https://img.shields.io/badge/%F0%9F%A4%97%20Models-GameScaling%20collection-ffcc4d?style=for-the-badge" alt="Models" style="display:inline-block;vertical-align:middle;margin:0;"></a>
+  <a href="https://www.apache.org/licenses/LICENSE-2.0" style="display:inline-block;margin:2px;"><img src="https://img.shields.io/badge/License-Apache%202.0-2ea44f?style=for-the-badge" alt="License: Apache 2.0" style="display:inline-block;vertical-align:middle;margin:0;"></a>
+</p>
+
+</div>
+
+<p align="center">
+  <img src="https://huggingface.co/THUSI-Lab/GameScaling/resolve/main/assets/teaser.jpg" alt="From one physical world to diverse virtual worlds" width="100%">
+</p>
+
+> **This repository: GameScaling-0.8B-S3.** Qwen3.5-0.8B continued pre-trained on a balanced mixture of 27% Minecraft and other games
+> (S3), 1,600 h of gameplay, 6,760 training steps; 2.2 GB of bfloat16 weights on
+> 1 GPU. Serve it with
+> `bash scripts/serve_vllm.sh THUSI-Lab/GameScaling-0.8B-S3 8000` (§1). The inference client, prompts and
+> scripts are in [THUSI-Lab/GameScaling](https://huggingface.co/THUSI-Lab/GameScaling); all eight checkpoints are in the
+> [GameScaling collection](https://huggingface.co/collections/THUSI-Lab/gamescaling-model-6acf7c0c6500ebee61a7f872).
+
+## Overview
+
+GameScaling models are Qwen3.5 vision-language models with continued pre-training on
+keyboard-and-mouse gameplay. Each call takes the current game frame (plus a short history of past
+frames and actions) and returns 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 may think before it
+acts.
 
-## Serve
+This repository holds the GameScaling-0.8B-S3 weights. The inference client and the standard system-prompt
+template are in [THUSI-Lab/GameScaling](https://huggingface.co/THUSI-Lab/GameScaling); each of the eight checkpoints is its own repository (below, and in the [GameScaling collection](https://huggingface.co/collections/THUSI-Lab/gamescaling-model-6acf7c0c6500ebee61a7f872)). Together they are everything needed to serve a
+checkpoint and run it in a game; there is no training code. Paper results and analysis are on the [project page](https://gamescaling.github.io).
+
+## Checkpoints
+
+| Model | Training steps | Weights | GPUs (bf16) |
+|---|---:|---:|:---:|
+| [GameScaling-0.8B-S1](https://huggingface.co/THUSI-Lab/GameScaling-0.8B-S1) | 6,736 | 2.2 GB | 1 |
+| **[GameScaling-0.8B-S3](https://huggingface.co/THUSI-Lab/GameScaling-0.8B-S3)** | **6,760** | **2.2 GB** | **1** |
+| [GameScaling-2B-S1](https://huggingface.co/THUSI-Lab/GameScaling-2B-S1) | 6,736 | 5.4 GB | 1 |
+| [GameScaling-2B-S3](https://huggingface.co/THUSI-Lab/GameScaling-2B-S3) | 6,760 | 5.4 GB | 1 |
+| [GameScaling-9B-S1](https://huggingface.co/THUSI-Lab/GameScaling-9B-S1) | 6,736 | 18.8 GB | 1 |
+| [GameScaling-9B-S3](https://huggingface.co/THUSI-Lab/GameScaling-9B-S3) | 6,760 | 18.8 GB | 1 |
+| [GameScaling-27B-S1](https://huggingface.co/THUSI-Lab/GameScaling-27B-S1) | 6,995 | 54.7 GB | 2 (tensor parallel) |
+| [GameScaling-27B-S3](https://huggingface.co/THUSI-Lab/GameScaling-27B-S3) | 7,020 | 54.7 GB | 2 (tensor parallel) |
+
+- **S1** is trained on Minecraft gameplay only. **S3** is a balanced mixture: 27% Minecraft, the
+  rest from other games. All checkpoints use 1,600 h of gameplay.
+- Weights are bfloat16, from the Qwen3.5-0.8B / 2B / 9B / 27B backbones.
+
+## File tree
+
+```text
+THUSI-Lab/GameScaling-<size>-<mixture>   one repository per checkpoint
+├── config.json                 Qwen3.5 architecture, bfloat16
+├── model.safetensors           weights (27B: 2 shards + index)
+├── chat_template.jinja         required, renders history turns
+├── tokenizer.json
+├── tokenizer_config.json
+├── generation_config.json
+├── preprocessor_config.json
+├── processor_config.json
+└── video_preprocessor_config.json
+
+THUSI-Lab/GameScaling
+├── config.json                 index of the eight checkpoint repositories (no weights)
+├── prompts/
+│   ├── system_prompt_template.txt  standard prompt, 3 slots (§2)
+│   └── example_doom_battle1.txt    complete Doom prompt (§2)
+├── examples/
+│   ├── doom_battle1.jpg        test frame (1280x720)
+│   ├── doom_battle1_action.txt the model's reply on that frame
+│   └── run_example.py          frame in, action out (§3)
+├── gamescaling/                inference client
+│   ├── prompt.py               system prompt builders
+│   ├── policy.py               client and request body
+│   ├── action.py               action format and parser
+│   └── keymaps.py              key names <-> browser keys
+├── scripts/serve_vllm.sh       start a vLLM server
+├── tests/test_core.py          offline tests (no GPU)
+├── assets/                     images for this card
+├── requirements.txt            client deps: requests, Pillow
+└── LICENSE                     Apache 2.0
+```
+
+## 1. Download and serve
+
+Download the client and scripts from [THUSI-Lab/GameScaling](https://huggingface.co/THUSI-Lab/GameScaling):
 
 ```bash
-huggingface-cli download THUSI-Lab/GameScaling --local-dir ./GameScaling   # client + scripts
+pip install -U huggingface_hub
+huggingface-cli download THUSI-Lab/GameScaling --exclude "assets/*" --local-dir ./GameScaling
 cd GameScaling
+```
+
+Serve a checkpoint with vLLM (tested with 0.17.0); vLLM fetches the weights from its repository:
+
+```bash
 pip install "vllm>=0.17"
-bash scripts/serve_vllm.sh THUSI-Lab/GameScaling-0.8B-S3 8000
+bash scripts/serve_vllm.sh THUSI-Lab/GameScaling-9B-S1 8000        # 0.8B-9B fit on one GPU
+bash scripts/serve_vllm.sh THUSI-Lab/GameScaling-27B-S1 8000 2     # 27B: tensor parallel 2
 ```
 
-Keep the shipped `chat_template.jinja` (vLLM loads it by default) and send requests with
-`skip_special_tokens: false`; see the main card for why.
+To keep the weights in a local folder instead, download the checkpoint repository and pass its path:
+
+```bash
+huggingface-cli download THUSI-Lab/GameScaling-9B-S1 --local-dir ./GameScaling-9B-S1
+bash scripts/serve_vllm.sh ./GameScaling-9B-S1 8000
+```
+
+`serve_vllm.sh CKPT [PORT] [TP]` starts vLLM with `--served-model-name gamescaling`, bfloat16,
+`--max-model-len 32768` (system prompt + 5 history frames + reasoning budget) and
+`--limit-mm-per-prompt '{"image": 8}'` (5 history frames + the current one, with headroom). Set
+`GPU_MEM_UTIL` to change the memory fraction (default 0.85).
+
+Check that the server is up and the client can reach it:
+
+```bash
+curl -s http://127.0.0.1:8000/v1/models          # should list "gamescaling"
+pip install -r requirements.txt
+python tests/test_core.py                         # offline checks, no server needed
+```
+
+Things to keep as shipped:
+
+- **Chat template.** Use the `chat_template.jinja` in the checkpoint repository (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|>...`, token-for-token as in training.
+- **Special tokens.** Requests must set `skip_special_tokens: false`, or the server strips the
+  `<|action_start|>` / `<|action_end|>` tags. `build_request` already does this.
+- **One server per GPU group.** One vLLM replica can serve several games at once, but long
+  prefills (one image per history turn) make each step slower when many games share it.
+
+## 2. System prompt
+
+`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 |
+|---|---|
+| `{GAME_NAME}` | The game's name. It appears twice: in the opening and in the key-list heading. |
+| `{GAME_RULES}` | What the game is, what is on screen, the goal and how it is scored. Plain text; several lines are fine. |
+| `{KEY_BINDINGS}` | One `- <key> -> <effect>` line per key, in training key names (§5). End with the mouse line below if the mouse turns the camera. |
+
+The mouse line, copied verbatim:
+
+```text
+- Mouse X Y -> aim / rotate the camera (X>0 right, Y>0 down)
+```
+
+**Note.** Lines such as `**Game Rules**`, `**Output Format**` and
+`**Explanation**` are plain-text section headers that the model saw in training. They are part
+of the prompt, not Markdown formatting: send them to the model unchanged, including the
+asterisks.
+
+### Complete example: Doom Battle-1
+
+This is the full system prompt for the ViZDoom Battle-1 map, as in
+`prompts/example_doom_battle1.txt`. It is the same text in both reasoning modes (§4). Long
+lines scroll horizontally; each line break below is a real `\n` in the prompt.
+
+```text
+You are a gaming expert, and you are currently playing Doom Battle-1. You are proficient in keyboard and mouse operations. You understand game mechanics and combat pacing, can quickly extract key information from the current screen, and can think and make precise decisions at critical moments. Based on the current screen, plan the next 200ms of actions, consisting of 6 steps spaced 33ms apart. Each step lasts 33ms, until the next step begins. If the current situation continues the previous strategy, output the action directly. Think only when the situation changes significantly, the previous analysis is no longer valid, or a new objective appears.
+**Game Rules**
+You are playing Doom, a first-person shooter, in an arena full of monsters. Survive and kill as many monsters as you can.
+
+## What you see on screen
+- First-person view.
+- The crosshair at screen centre marks where shots land.
+- The status bar along the bottom shows HEALTH on the left and AMMO on the right.
+- Monsters keep arriving for the whole episode; some throw fireballs from range.
+
+## Rules
+- Score is the number of monsters you kill in the episode.
+- Firing costs ammo, and the episode ends as soon as your health reaches 0, so dodging matters as much as shooting: standing still in the open is how most episodes end early.
+- Health packs and ammo boxes lie around the map; walk over one to pick it up. Running out of either is fatal, so collect them while fighting.
+- A target is hit when it is under the crosshair, so turn with the mouse until the monster is centred before firing.
+- The map is one large open arena, so monsters can close in from any direction.
+**Common Keys in Doom Battle-1**
+- W -> Move forward
+- A -> Strafe left
+- S -> Move backward
+- D -> Strafe right
+- LB -> Fire weapon
+- Ctrl -> Fire weapon (keyboard alternative)
+- Shift -> Run
+- Space -> Open doors / use switches
+- one -> Select weapon slot 1
+- two -> Select weapon slot 2
+- three -> Select weapon slot 3
+- Mouse X Y -> aim / rotate the camera (X>0 right, Y>0 down)
+**Output Format**
+**Action only (usual)**
+<think></think><|action_start|>X Y Z ; k1 k2 k3 ; k4 k5 ; k6 ; k7 ; k8 ; k9 k10<|action_end|>
+**Thinking + action (when necessary)**
+<think>reasoning</think><|action_start|>X Y Z ; k1 k2 k3 ; k4 k5 ; k6 ; k7 ; k8 ; k9 k10<|action_end|>
+**Explanation**
+1. **Mouse Movement**: First, specify the relative displacement X, Y (X>0 means move right, Y>0 means move down) and scroll amount Z (Z>0 means scroll up).
+2. **Key Sequence**: Then list 6 groups of keys; within each group, keys are separated by spaces, and groups are separated by semicolons.
+- Each group can contain up to 4 keys.
+- If a group has no keys, leave it empty but keep the `;`.
+3. Only output a plain string that conforms to the above format — no line breaks and no quotation marks.
+**Key Naming Rules**
+- Number keys `0-9`: use lowercase English words, e.g., `zero` for `0`, `one` for `1`, ... `nine` for `9`.
+- Function keys `F1-F12`: use capitalized English words, e.g., `One` represents `F1`, `Two` represents `F2`, and so on.
+- Mouse buttons: use `LB`, `RB`, `MB` for the left, right, and middle mouse button.
+- Letters: use the uppercase letter, e.g., `A`, `D`, `W`, `S`.
+- Arrow keys: use `Up`, `Down`, `Left`, `Right`.
+- Modifier/special keys: `Shift`, `Ctrl`, `Alt`, `Tab`, `Caps`, `Esc`, `Space`, `Enter`, `Back` (backspace), `Delete`, `Insert`, `Home`, `End`, `Pause`.
+```
+
+The same prompt from code (`tests/test_core.py` checks that it matches the file byte for byte):
+
+```python
+from gamescaling import build_system_prompt
+
+DOOM_RULES = open("prompts/example_doom_battle1.txt").read() \
+    .split("**Game Rules**\n", 1)[1].split("\n**Common Keys in", 1)[0]
+
+system = build_system_prompt(
+    "Doom Battle-1",
+    rules=DOOM_RULES,
+    key_bindings=[
+        ("W", "Move forward"), ("A", "Strafe left"), ("S", "Move backward"), ("D", "Strafe right"),
+        ("LB", "Fire weapon"), ("Ctrl", "Fire weapon (keyboard alternative)"), ("Shift", "Run"),
+        ("Space", "Open doors / use switches"), ("one", "Select weapon slot 1"),
+        ("two", "Select weapon slot 2"), ("three", "Select weapon slot 3"),
+    ],
+    mouse_aim=True,   # appends the "Mouse X Y -> ..." line
+)
+```
+
+Filling the text file directly gives the same result:
+
+```python
+tpl = open("prompts/system_prompt_template.txt").read().rstrip("\n")
+system = (tpl.replace("{GAME_NAME}", "Doom Battle-1")
+             .replace("{GAME_RULES}", DOOM_RULES)
+             .replace("{KEY_BINDINGS}", "- W -> Move forward\n- A -> Strafe left\n..."
+                      "\n- Mouse X Y -> aim / rotate the camera (X>0 right, Y>0 down)"))
+```
+
+## 3. Minimal usage
+
+```python
+from PIL import Image
+from gamescaling import GameScalingPolicy, PolicyConfig
+
+policy = GameScalingPolicy(system, PolicyConfig())   # system prompt from §2; prefills <think>
+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): 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
+decision.reasoning   # the model's thinking for this step ("" if it acted directly)
+```
+
+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. The frame is sent at its native size; set `PolicyConfig(image_size=(w, h))` to
+resize it first.
+
+### Test frame
+
+`examples/doom_battle1.jpg` is a frame from a Doom Battle-1 episode played by GameScaling-9B-S3.
+A monster stands just left of the crosshair.
+
+<p align="center">
+  <img src="https://huggingface.co/THUSI-Lab/GameScaling/resolve/main/examples/doom_battle1.jpg" alt="Doom Battle-1 test frame" width="100%">
+</p>
+
+The model's reply on this frame (`examples/doom_battle1_action.txt`), with the system prompt from
+§2:
+
+```text
+<think>
+
+</think>
+
+<|action_start|>-37 -3 0 ; LB S ; LB ; LB ; LB ; LB ; LB<|action_end|>
+```
+
+It acts without thinking, turns left by 37/1000 of the screen width, and holds fire for the
+whole 200 ms (with a short step back in the first 33 ms). The shot killed the monster.
+
+Run the same frame against your server:
+
+```bash
+python examples/run_example.py --offline       # no server
+python examples/run_example.py                 # prefill <think>
+python examples/run_example.py --no-reasoning  # no thinking
+```
+
+Each reply should parse into a valid action chunk (`parsed=True`); the script exits non-zero
+otherwise. Sampling is at temperature 1.0 and the reference reply had five earlier frames in
+context, so live replies differ in detail.
+
+## 4. Reasoning modes and message structure
+
+The assistant turn is always prefilled, and the request continues it
+(`continue_final_message=True`). The system prompt is the same in both modes.
+
+| Mode | Prefill | What the model does |
+|---|---|---|
+| `PolicyConfig()` (default, `reasoning=True`) | `<think>` | Decides whether and how long to think, closes `</think>`, then outputs the action |
+| `PolicyConfig(reasoning=False)` | `<think>\n\n</think>` | Thinking is closed and empty; the model outputs the action chunk directly |
+
+`<think>\n\n</think>` is exactly how the chat template renders a turn without reasoning, so the
+no-reasoning mode stays in the training format. Do not send the request without a prefill.
+
+Each user turn is the text `current game screen` followed by the frame. Multi-turn messages
+(`policy.py`):
+
+```text
+system     system prompt (§2)
+user       "current game screen" + frame t-k
+assistant  action taken at t-k (no reasoning)
+...        (last history_len turns, default 5)
+user       "current game screen" + current frame
+assistant  "<think>"  or  "<think>\n\n</think>"
+```
+
+Past turns keep only the action (`history_think=0`). 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.
+
+Client defaults: `temperature=1.0`, `max_tokens=2048`, `stop=["<|action_end|>"]`,
+`skip_special_tokens=false`, JPEG frames (quality 90) at native resolution.
+
+## 5. Action format
+
+```text
+<|action_start|>X Y Z ; g1 ; g2 ; g3 ; g4 ; g5 ; g6<|action_end|>
+```
+
+- `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 |
+|---|---|
+| 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` |
+
+Tokens outside the vocabulary are dropped and recorded in `Action.dropped`.
+`keymaps.TO_PLAYWRIGHT` and `keymaps.TO_UE5` map them to browser and Unreal Engine key names;
+`translate_controls` rewrites browser key names in a text into training tokens.
+
+## 6. Running it in a game
+
+1. Write the system prompt for your game (§2).
+2. Capture the current frame and call `policy.act(frame)` once per decision.
+3. Execute the returned `Action` as in §5: held keys for 6 steps of 33 ms, plus mouse movement
+   and scroll.
+4. Call `policy.reset()` when an episode ends.
+
+Before trusting the results, check:
+
+- **Parse rate.** `Decision.action.parsed` should almost always be `True`. Many failures, or many
+  `Action.truncated`, usually mean a replaced chat template, stripped special tokens, a missing
+  prefill, or a too-small `max_tokens`.
+- **Actions take effect.** Each chunk runs in wall-clock time (6 × 33 ms). If the game renders
+  slowly, for example several game instances sharing one GPU, held keys barely move the
+  character and nothing reports an error. Watch a recording before reading any numbers.
+- **Several episodes.** Single episodes vary a lot at `temperature=1.0`.
+
+## 7. Tests
+
+```bash
+python tests/test_core.py      # or: python -m pytest tests/
+```
+
+Offline checks of prompts, request bodies and action parsing; no GPU or server needed.
 
 ## License
 
-Weights: Apache-2.0. GameScaling is a purely scientific research project; see
-[THUSI-Lab/GameScaling](https://huggingface.co/THUSI-Lab/GameScaling#license). Game titles and
-footage belong to their publishers.
+GameScaling is a **purely scientific research** project. We carry out **no commercial activity** of
+any kind with it: nothing here is sold, licensed for a fee, or used in any product or service.
+
+- **Models and code: Apache-2.0.** The weights and the inference code are released under the
+  [Apache License 2.0](LICENSE). The models are continued pre-trained from
+  [Qwen3.5](https://huggingface.co/Qwen/Qwen3.5-9B), which is also Apache 2.0.
+- **Gameplay data is not released.** The training corpus stays private; game frames in
+  [THUSI-Lab/GameScaling](https://huggingface.co/THUSI-Lab/GameScaling) (e.g. `examples/doom_battle1.jpg`) only illustrate how to use the model.
+- **Game copyright belongs to the publishers.** All game titles, footage, copyrights, trademarks and
+  other game assets referenced here belong to their respective publishers and owners. The Apache
+  2.0 licence covers our weights and code only and grants no right to any game content.
 
 ## Citation