Add a Doom test frame with the model's reply and an end-to-end example script

.gitattributes

@@ -43,3 +43,4 @@ models/9b_s1_1600h_gs6736/tokenizer.json filter=lfs diff=lfs merge=lfs -text
 models/9b_s3_1600h_gs6760/tokenizer.json filter=lfs diff=lfs merge=lfs -text
 assets/teaser.jpg filter=lfs diff=lfs merge=lfs -text
 assets/logos/affiliations.png filter=lfs diff=lfs merge=lfs -text
+examples/doom_battle1.jpg filter=lfs diff=lfs merge=lfs -text

README.md

@@ -106,6 +106,10 @@ THUSI-Lab/GameScaling
 ├── 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
@@ -126,7 +130,7 @@ Download only the checkpoint you need:
 pip install -U huggingface_hub
 huggingface-cli download THUSI-Lab/GameScaling \
     --include "models/9b_s1_1600h_gs6736/*" "gamescaling/*" "prompts/*" "scripts/*" \
-              "tests/*" "requirements.txt" \
+              "examples/*" "tests/*" "requirements.txt" \
     --local-dir ./GameScaling
 cd GameScaling
 ```
@@ -294,6 +298,37 @@ is `X/1000 * screen width` and `Y/1000 * screen height`. You can spread it over
 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>\n\n</think>\n\n<|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        # parse the reference reply, no server
+python examples/run_example.py                  # default: prefill <think>
+python examples/run_example.py --no-reasoning   # prefill <think>\n\n</think>
+```
+
+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

examples/doom_battle1_action.txt

@@ -0,0 +1,5 @@
+<think>
+
+</think>
+
+<|action_start|>-37 -3 0 ; LB S ; LB ; LB ; LB ; LB ; LB<|action_end|>

examples/run_example.py

@@ -0,0 +1,74 @@
+"""One Doom frame in, one action out.
+
+`examples/doom_battle1.jpg` is a frame from a Doom Battle-1 episode played by
+GameScaling-9B-S3, and `examples/doom_battle1_action.txt` is the reply the model
+gave on that frame (a monster just left of the crosshair: turn left and fire).
+
+    python examples/run_example.py --offline            # parse the reference reply only
+    bash scripts/serve_vllm.sh models/9b_s3_1600h_gs6760 8000
+    python examples/run_example.py                      # prefill <think>
+    python examples/run_example.py --no-reasoning       # prefill <think>\\n\\n</think>
+
+Sampling is at temperature 1.0 and the reference came with five earlier frames
+in context, so a live reply will differ in detail. The check is that every
+reply parses into a valid action chunk; the script also reports whether it
+fires (LB), as the reference does.
+"""
+
+import argparse
+import os
+import sys
+
+ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+sys.path.insert(0, ROOT)
+
+from PIL import Image  # noqa: E402
+
+from gamescaling import GameScalingPolicy, PolicyConfig, parse_action  # noqa: E402
+
+EXAMPLES = os.path.join(ROOT, "examples")
+
+
+def describe(action) -> str:
+    fires = any("LB" in g for g in action.steps)
+    return f"parsed={action.parsed}  mouse={action.mouse}  steps={action.steps}  fires={fires}"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--base-url", default="http://127.0.0.1:8000/v1")
+    ap.add_argument("--image", default=os.path.join(EXAMPLES, "doom_battle1.jpg"))
+    ap.add_argument("--prompt", default=os.path.join(ROOT, "prompts", "example_doom_battle1.txt"))
+    ap.add_argument("--no-reasoning", action="store_true")
+    ap.add_argument("--trials", type=int, default=3)
+    ap.add_argument("--offline", action="store_true", help="only parse the reference reply")
+    args = ap.parse_args()
+
+    reference = open(os.path.join(EXAMPLES, "doom_battle1_action.txt")).read()
+    print("reference reply:", repr(reference))
+    print("reference action:", describe(parse_action(reference)))
+    if args.offline:
+        return 0
+
+    system = open(args.prompt).read().rstrip("\n")
+    policy = GameScalingPolicy(system, PolicyConfig(base_url=args.base_url,
+                                                    reasoning=not args.no_reasoning))
+    if not policy.health_check():
+        print(f"server not reachable at {args.base_url}")
+        return 2
+
+    frame = Image.open(args.image)
+    ok = 0
+    for i in range(args.trials):
+        policy.reset()
+        d = policy.act(frame)
+        print(f"--- trial {i + 1}  ({d.latency_ms:.0f} ms, {d.completion_tokens} tokens)")
+        print(repr(d.text))
+        print(describe(d.action))
+        ok += d.action.parsed and not d.action.truncated
+    print(f"{ok}/{args.trials} replies parsed")
+    return 0 if ok == args.trials else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

tests/test_core.py

@@ -115,6 +115,15 @@ def test_doom_example_matches_builder():
     assert example == build_system_prompt("Doom Battle-1", rules=rules, key_bindings=bindings)
 
 
+def test_example_pair():
+    root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+    assert Image.open(os.path.join(root, "examples", "doom_battle1.jpg")).size == (1280, 720)
+    with open(os.path.join(root, "examples", "doom_battle1_action.txt")) as f:
+        a = parse_action(f.read())
+    assert a.parsed and a.mouse == (-37.0, -3.0, 0.0)
+    assert all("LB" in g for g in a.steps)
+
+
 def test_translate_controls():
     text = "- ArrowLeft: move left\n- a/d: strafe\n- 1-9: pick item\nPress Escape to pause."
     out = translate_controls(text)