Mr. Pong interactive demo: browser-side play + server-side match video & benchmark

README.md

@@ -1,13 +1,42 @@
 ---
-title: Mr Pong Rl Demo
-emoji: 🌖
-colorFrom: purple
-colorTo: blue
+title: Mr. Pong
+emoji: 🏓
+colorFrom: blue
+colorTo: gray
 sdk: gradio
 sdk_version: 6.24.0
-python_version: '3.13'
 app_file: app.py
-pinned: false
+short_description: Play table tennis against a PPO agent
+python_version: "3.12"
+startup_duration_timeout: 30m
+models:
+  - fromziro/MrPong
+tags:
+  - reinforcement-learning
+  - ppo
+  - game
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# 🏓 Mr. Pong
+
+An interactive demo for [**fromziro/MrPong**](https://huggingface.co/fromziro/MrPong) —
+a 28,484-parameter actor–critic MLP trained with PPO and self-play for 10M steps to
+play 2D table tennis.
+
+Three tabs:
+
+- **Play Mr. Pong** — the policy is exported from the checkpoint and evaluated in your
+  browser (plain JavaScript, ~26K MACs per decision), so the agent's paddle reacts at
+  the same 40 sub-steps/second the physics runs at, with no network latency. The
+  critic's value estimate `V(s)` is shown live.
+- **Watch a match** — the real PyTorch checkpoint plays a full match against one of the
+  scripted baselines from the model card, rendered to video server-side.
+- **Benchmark** — replays the model card's evaluation protocol over N matches.
+
+The physics environment (`pong_engine.py`) and the baseline opponents are a 1:1 port of
+the author's reference `inference.py`, so behaviour matches the reported numbers.
+
+Runs entirely on CPU: a policy forward pass is a 12→160→160→3 MLP.
+
+Model, environment and baselines by [FromZero](https://huggingface.co/fromziro),
+Apache-2.0.

app.py

@@ -0,0 +1,394 @@
+"""
+🏓 Mr. Pong — an interactive demo for fromziro/MrPong.
+
+Two ways to meet the agent:
+  1. Play against it live in the browser. The 28K-parameter policy is exported
+     from the checkpoint and evaluated client-side at 40 physics steps/second,
+     so the paddle reacts with zero network latency.
+  2. Watch / benchmark the real PyTorch checkpoint playing full matches against
+     the baseline opponents from the model card, rendered to video on the server.
+"""
+
+import base64
+import html as html_lib
+import math
+import os
+import random
+import tempfile
+import time
+from pathlib import Path
+
+import gradio as gr
+import numpy as np
+import torch
+from PIL import Image, ImageDraw, ImageFont
+from transformers import AutoConfig, AutoModel
+
+from pong_engine import (
+    OPPONENTS,
+    PhysicsConfig,
+    StandalonePongEnv,
+)
+
+MODEL_ID = "fromziro/MrPong"
+HERE = Path(__file__).parent
+
+# ----------------------------------------------------------------------------
+# Model (28,484 params — pure CPU, a forward pass costs microseconds)
+# ----------------------------------------------------------------------------
+config = AutoConfig.from_pretrained(MODEL_ID, trust_remote_code=True)
+model = AutoModel.from_pretrained(MODEL_ID, trust_remote_code=True)
+model.eval()
+OBS_DIM = int(getattr(config, "obs_dim", 12))
+N_PARAMS = sum(p.numel() for p in model.parameters())
+print(f"[OK] {MODEL_ID} loaded — {N_PARAMS:,} params, obs_dim={OBS_DIM}, "
+      f"hidden_dims={config.hidden_dims}")
+
+
+@torch.no_grad()
+def policy_action(obs: np.ndarray, deterministic: bool = True) -> int:
+    """Greedy action from the Mr. Pong policy (0 stay, 1 up, 2 down)."""
+    x = obs[:OBS_DIM] if len(obs) >= OBS_DIM else np.pad(obs, (0, OBS_DIM - len(obs)))
+    return int(model.act(x, deterministic=deterministic))
+
+
+# ----------------------------------------------------------------------------
+# Export the checkpoint for the in-browser copy of the policy
+# ----------------------------------------------------------------------------
+def _export_weights_b64() -> str:
+    sd = model.state_dict()
+    order = ["trunk.0.weight", "trunk.0.bias", "trunk.2.weight", "trunk.2.bias",
+             "actor.weight", "actor.bias", "critic.weight", "critic.bias"]
+    flat = np.concatenate([sd[k].detach().cpu().numpy().astype("<f4").ravel()
+                           for k in order])
+    assert flat.size == N_PARAMS, (flat.size, N_PARAMS)
+    return base64.b64encode(flat.tobytes()).decode("ascii")
+
+
+GAME_HTML = (HERE / "game_template.html").read_text().replace(
+    "__WEIGHTS_B64__", _export_weights_b64()
+)
+GAME_IFRAME = (
+    '<iframe title="Play Mr. Pong" srcdoc="{}" '
+    'style="width:100%;height:700px;border:0;border-radius:12px;overflow:hidden" '
+    'scrolling="no"></iframe>'
+).format(html_lib.escape(GAME_HTML, quote=True))
+
+
+# ----------------------------------------------------------------------------
+# Server-side match rendering (real PyTorch checkpoint)
+# ----------------------------------------------------------------------------
+SC = 0.8                      # render scale: 800x500 table -> 640x400 video
+VW, VH = int(800 * SC), int(500 * SC)
+FPS = 40                      # one frame per physics sub-step == real time
+MAX_FRAMES = 1100             # hard cap on video length (~27 s)
+POINT_SUBSTEP_CAP = 420       # a single point is called a draw after this
+MAX_POINTS = 12               # safety net against endless draw sequences
+
+
+def _font(size: int):
+    for p in ("/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+              "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf"):
+        if os.path.exists(p):
+            return ImageFont.truetype(p, size)
+    try:
+        return ImageFont.load_default(size=size)
+    except TypeError:
+        return ImageFont.load_default()
+
+
+F_BIG, F_MED, F_SMALL = _font(34), _font(15), _font(13)
+
+
+def _render_frame(env, score_a, score_b, opp_name, trail, banner=""):
+    img = Image.new("RGB", (VW, VH), (15, 22, 38))
+    d = ImageDraw.Draw(img)
+
+    for y in range(0, VH, 26):
+        d.line([(VW // 2, y), (VW // 2, min(VH, y + 12))], fill=(38, 48, 70), width=2)
+    d.rectangle([0, 0, VW - 1, VH - 1], outline=(28, 36, 54), width=2)
+
+    for i, (tx, ty) in enumerate(trail):
+        a = (i + 1) / (len(trail) + 1)
+        c = int(60 + 150 * a)
+        r = 8 * SC * (0.35 + 0.6 * a)
+        d.ellipse([tx * SC - r, ty * SC - r, tx * SC + r, ty * SC + r], fill=(c, c, c))
+
+    pw = 14 * SC
+    eh = env.ego_paddle_h * SC / 2
+    oh = env.opp_paddle_h * SC / 2
+    d.rounded_rectangle([2, env.ego_y * SC - eh, 2 + pw, env.ego_y * SC + eh],
+                        radius=5, fill=(79, 140, 255))          # Mr. Pong (blue)
+    d.rounded_rectangle([VW - pw - 2, env.opp_y * SC - oh, VW - 2, env.opp_y * SC + oh],
+                        radius=5, fill=(249, 115, 22))          # baseline (orange)
+
+    r = 8 * SC
+    d.ellipse([env.ball_x * SC - r, env.ball_y * SC - r,
+               env.ball_x * SC + r, env.ball_y * SC + r], fill=(255, 255, 255))
+
+    d.text((VW // 2 - 46, 16), str(score_a), font=F_BIG, fill=(79, 140, 255), anchor="ma")
+    d.text((VW // 2 + 46, 16), str(score_b), font=F_BIG, fill=(249, 115, 22), anchor="ma")
+    d.text((20, 20), "MR. PONG", font=F_MED, fill=(120, 150, 200))
+    d.text((VW - 20, 20), opp_name.upper(), font=F_MED, fill=(190, 130, 80), anchor="ra")
+
+    speed = math.hypot(env.ball_vx, env.ball_vy)
+    d.text((20, VH - 26),
+           f"rally {env.rally_count} hits   ball {speed:4.1f} px/f", font=F_SMALL,
+           fill=(120, 135, 160))
+
+    if banner:
+        d.rectangle([0, VH // 2 - 34, VW, VH // 2 + 34], fill=(11, 15, 25))
+        d.text((VW // 2, VH // 2), banner, font=F_BIG, fill=(249, 115, 22), anchor="mm")
+    return np.asarray(img)
+
+
+def _play_point(env, opponent, frames, opp_name, score_a, score_b, serve_dir, record):
+    """Run one point sub-step by sub-step; returns the winner string."""
+    env.reset(serve_direction=serve_dir)
+    trail = []
+    ai_act = 0
+    opp_act = 0
+    for i in range(POINT_SUBSTEP_CAP):
+        # Both policies are re-queried every `frame_skip` sub-steps, exactly as
+        # StandalonePongEnv.step() does in the author's simulate() loop.
+        if i % env.phys.frame_skip == 0:
+            ai_act = policy_action(env.get_ego_observation())
+            opp_act = opponent.act(env)
+        trail.append((env.ball_x, env.ball_y))
+        if len(trail) > 8:
+            trail.pop(0)
+        done, info = env.physics_substep(ego_action=ai_act, opp_action=opp_act)
+        if record and len(frames) < MAX_FRAMES:
+            frames.append(_render_frame(env, score_a, score_b, opp_name, trail))
+        if done:
+            return info.get("winner")
+    return "draw"
+
+
+def watch_match(opponent_name: str, points_to_win: int = 3,
+                randomize_seed: bool = True, seed: int = 0):
+    """Simulate and render a Mr. Pong match against a baseline opponent.
+
+    Args:
+        opponent_name: which scripted baseline to face (from the model card).
+        points_to_win: number of points needed to take the match.
+        randomize_seed: draw a fresh random seed for this match.
+        seed: RNG seed used when randomize_seed is off.
+
+    Returns:
+        An MP4 of the match, a markdown scoreline, and the seed actually used.
+    """
+    import imageio.v2 as imageio
+
+    if randomize_seed:
+        seed = random.randint(0, 2**31 - 1)
+    seed = int(seed)
+    rng = random.Random(seed)
+    random.seed(seed)
+    np.random.seed(seed % (2**32))
+
+    points_to_win = int(points_to_win)
+    opp_cls = OPPONENTS[opponent_name]
+    opponent = opp_cls(rng=rng)
+
+    env = StandalonePongEnv(PhysicsConfig(), seed=seed)
+    frames = []
+    score_a = score_b = 0
+    serve_dir = 1
+    rallies = []
+    t0 = time.perf_counter()
+
+    while (score_a < points_to_win and score_b < points_to_win
+           and len(rallies) < MAX_POINTS):
+        winner = _play_point(env, opponent, frames, opponent_name,
+                             score_a, score_b, serve_dir,
+                             record=len(frames) < MAX_FRAMES)
+        rallies.append(env.rally_count)
+        if winner == "ego":
+            score_a += 1
+            serve_dir = 1
+        elif winner == "opponent":
+            score_b += 1
+            serve_dir = -1
+        else:
+            serve_dir = -serve_dir
+        if len(frames) >= MAX_FRAMES:
+            break
+
+    banner = ("MR. PONG WINS %d-%d" % (score_a, score_b) if score_a > score_b
+              else ("%s WINS %d-%d" % (opponent_name.upper(), score_b, score_a)
+                    if score_b > score_a else "TIME LIMIT"))
+    for _ in range(FPS * 2):
+        if len(frames) < MAX_FRAMES + FPS * 2:
+            frames.append(_render_frame(env, score_a, score_b, opponent_name,
+                                        [], banner=banner))
+
+    sim_s = time.perf_counter() - t0
+    out = tempfile.NamedTemporaryFile(suffix=".mp4", delete=False).name
+    with imageio.get_writer(out, fps=FPS, codec="libx264", quality=7,
+                            macro_block_size=1, pixelformat="yuv420p") as w:
+        for f in frames:
+            w.append_data(f)
+
+    stats = (
+        f"### Mr. Pong **{score_a} – {score_b}** {opponent_name}\n"
+        f"| | |\n|---|---|\n"
+        f"| Points played | {len(rallies)} |\n"
+        f"| Longest rally | {max(rallies)} hits |\n"
+        f"| Average rally | {np.mean(rallies):.1f} hits |\n"
+        f"| Video length | {len(frames) / FPS:.1f} s ({len(frames)} frames) |\n"
+        f"| Simulation time | {sim_s:.2f} s |\n"
+        f"| Seed | `{seed}` |\n"
+    )
+    return out, stats, seed
+
+
+def benchmark(opponent_name: str, num_matches: int = 25, seed: int = 0):
+    """Replay the model card's evaluation: N single-point matches, no rendering.
+
+    Args:
+        opponent_name: which scripted baseline to face.
+        num_matches: how many matches to simulate.
+        seed: RNG seed for reproducibility.
+
+    Returns:
+        A markdown summary of the win / draw / loss record.
+    """
+    seed = int(seed)
+    rng = random.Random(seed)
+    random.seed(seed)
+    num_matches = int(num_matches)
+
+    opponent = OPPONENTS[opponent_name](rng=rng)
+    env = StandalonePongEnv(PhysicsConfig(), seed=seed)
+
+    wins = draws = losses = 0
+    rallies = []
+    t0 = time.perf_counter()
+
+    for i in range(1, num_matches + 1):
+        obs = env.reset(serve_direction=1 if i % 2 == 0 else -1)
+        done = False
+        info = {}
+        while not done:
+            ego_act = policy_action(obs)
+            opp_act = opponent.act(env)
+            obs, done, info = env.step(ego_action=ego_act, opp_action=opp_act)
+        rallies.append(env.rally_count)
+        w = info.get("winner")
+        if w == "ego":
+            wins += 1
+        elif w == "opponent":
+            losses += 1
+        else:
+            draws += 1
+
+    el = time.perf_counter() - t0
+    n = max(1, num_matches)
+    return (
+        f"### Mr. Pong vs **{opponent_name}** — {num_matches} matches\n\n"
+        f"| Metric | Value |\n|---|---|\n"
+        f"| Win rate | **{wins / n * 100:.1f}%** |\n"
+        f"| Draw rate | {draws / n * 100:.1f}% |\n"
+        f"| Loss rate | {losses / n * 100:.1f}% |\n"
+        f"| Record (W/D/L) | {wins}W / {draws}D / {losses}L |\n"
+        f"| Average rally | {np.mean(rallies):.1f} hits (max {max(rallies)}) |\n"
+        f"| Wall time | {el:.2f} s ({num_matches / max(el, 1e-6):.1f} matches/s) |\n\n"
+        f"*A draw means the rally hit the {env.phys.max_rally_steps}-step limit "
+        f"without either side scoring.*"
+    )
+
+
+# ----------------------------------------------------------------------------
+# UI
+# ----------------------------------------------------------------------------
+CSS = """
+#col-container { max-width: 1000px; margin: 0 auto; }
+.dark .gradio-container { color: var(--body-text-color); }
+"""
+
+INTRO = f"""# 🏓 Mr. Pong
+
+[**fromziro/MrPong**](https://huggingface.co/{MODEL_ID}) is a {N_PARAMS:,}-parameter
+actor–critic MLP trained with PPO and self-play for 10M steps to play 2D table tennis.
+It wins ~87% of its matches against the strongest scripted baseline it was trained on.
+
+**Play it yourself below** — the policy runs in your browser, so the paddle answers
+in real time. Or watch the real PyTorch checkpoint take on the model-card opponents.
+"""
+
+with gr.Blocks(theme=gr.themes.Citrus(), css=CSS, title="Mr. Pong") as demo:
+    with gr.Column(elem_id="col-container"):
+        gr.Markdown(INTRO)
+
+        with gr.Tabs():
+            with gr.Tab("🎮 Play Mr. Pong"):
+                gr.HTML(GAME_IFRAME)
+                gr.Markdown(
+                    "Click the court to start. Hold **W** / **↑** and **S** / **↓** "
+                    "(or switch to mouse / touch control). First to 5 points.  \n"
+                    "*V(s) is the critic's value estimate from Mr. Pong's point of "
+                    "view — it climbs when the agent thinks it is about to win the point.*"
+                )
+
+            with gr.Tab("🎬 Watch a match"):
+                with gr.Row():
+                    opponent = gr.Dropdown(
+                        list(OPPONENTS.keys()), value="Realistic Hard",
+                        label="Opponent", scale=3)
+                    watch_btn = gr.Button("Play match", variant="primary", scale=1)
+                video_out = gr.Video(label="Match replay", autoplay=True,
+                                     height=430, format="mp4")
+                stats_out = gr.Markdown()
+                with gr.Accordion("Advanced settings", open=False):
+                    points = gr.Slider(1, 5, value=3, step=1, label="Points to win")
+                    rand_seed = gr.Checkbox(value=True, label="Randomize seed")
+                    seed_num = gr.Number(value=0, precision=0, label="Seed")
+                gr.Examples(
+                    examples=[["Realistic Hard"], ["Impossible Hard"],
+                              ["Medium Logic"], ["Random Agent"]],
+                    inputs=[opponent],
+                    outputs=[video_out, stats_out, seed_num],
+                    fn=watch_match,
+                    cache_examples=True,
+                    cache_mode="lazy",
+                    label="Opponents from the model card",
+                )
+                watch_btn.click(
+                    watch_match,
+                    inputs=[opponent, points, rand_seed, seed_num],
+                    outputs=[video_out, stats_out, seed_num],
+                    api_name="watch_match",
+                )
+
+            with gr.Tab("📊 Benchmark"):
+                with gr.Row():
+                    bench_opp = gr.Dropdown(
+                        list(OPPONENTS.keys()), value="Realistic Hard",
+                        label="Opponent", scale=3)
+                    bench_btn = gr.Button("Run benchmark", variant="primary", scale=1)
+                bench_out = gr.Markdown()
+                with gr.Accordion("Advanced settings", open=False):
+                    n_matches = gr.Slider(5, 200, value=25, step=5, label="Matches")
+                    bench_seed = gr.Number(value=0, precision=0, label="Seed")
+                gr.Markdown(
+                    "Reference numbers reported by the author over 1000 matches:  \n"
+                    "Easy 99.7% · Medium 99.0% · Realistic Hard 86.6% · "
+                    "Random 100% · Impossible Hard 0% W / 98.4% D."
+                )
+                bench_btn.click(
+                    benchmark,
+                    inputs=[bench_opp, n_matches, bench_seed],
+                    outputs=[bench_out],
+                    api_name="benchmark",
+                )
+
+        gr.Markdown(
+            "Model, physics environment and baseline opponents by "
+            "[FromZero](https://huggingface.co/fromziro) (Apache-2.0). "
+            "The in-browser policy is the exact checkpoint re-evaluated in JavaScript; "
+            "the *Watch* and *Benchmark* tabs run the PyTorch model itself."
+        )
+
+if __name__ == "__main__":
+    demo.launch(mcp_server=True)

game_template.html

@@ -0,0 +1,418 @@
+<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<style>
+  * { box-sizing: border-box; }
+  html, body {
+    margin: 0; padding: 0; background: #0b0f19; color: #e6edf3;
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    overflow: hidden;
+  }
+  #wrap { padding: 8px 10px 10px 10px; max-width: 900px; margin: 0 auto; }
+  #bar { display: flex; flex-wrap: wrap; gap: 8px; align-items: center; margin-bottom: 8px; }
+  .btn {
+    background: #1b2438; color: #e6edf3;
+    border: 1px solid #2b3550; border-radius: 8px; padding: 6px 12px; cursor: pointer;
+    font-size: 13px; font-weight: 600; transition: all .12s;
+  }
+  .btn:hover { background: #26314a; }
+  .btn.active { background: #f97316; border-color: #f97316; color: #0b0f19; }
+  .btn.primary { background: #4f8cff; border-color: #4f8cff; color: #08111f; }
+  .btn.primary:hover { background: #6ba0ff; }
+  .lab { font-size: 12px; color: #8b98ac; text-transform: uppercase; letter-spacing: .06em; margin-right: 2px; }
+  #stage { position: relative; width: 100%; }
+  canvas { width: 100%; height: auto; display: block; border-radius: 10px; background: #0f1626; }
+  #overlay {
+    position: absolute; inset: 0; display: flex; flex-direction: column;
+    align-items: center; justify-content: center; text-align: center;
+    background: rgba(8,12,22,.82); border-radius: 10px; cursor: pointer;
+  }
+  #overlay h2 { margin: 0 0 6px 0; font-size: 22px; }
+  #overlay p { margin: 2px 0; font-size: 13px; color: #b6c2d4; }
+  #hud { display: flex; gap: 14px; align-items: center; margin-top: 8px; font-size: 12px; color: #8b98ac; flex-wrap: wrap; }
+  #vbar { flex: 1; min-width: 120px; height: 8px; background: #1b2438; border-radius: 4px; overflow: hidden; position: relative; }
+  #vfill { position: absolute; top: 0; bottom: 0; left: 50%; width: 0%; background: #4f8cff; transition: width .1s linear, left .1s linear; }
+  kbd { background:#1b2438; border:1px solid #2b3550; border-bottom-width:2px; border-radius:5px; padding:1px 6px; font-size:12px; }
+</style>
+</head>
+<body>
+<div id="wrap">
+  <div id="bar">
+    <span class="lab">Difficulty</span>
+    <button class="btn diff" data-d="easy">Easy</button>
+    <button class="btn diff active" data-d="normal">Normal</button>
+    <button class="btn diff" data-d="hard">Hard</button>
+    <span style="flex:1"></span>
+    <span class="lab">Control</span>
+    <button class="btn ctrl active" data-c="key">Keyboard</button>
+    <button class="btn ctrl" data-c="mouse">Mouse / Touch</button>
+    <button class="btn primary" id="restart">Restart</button>
+  </div>
+
+  <div id="stage">
+    <canvas id="cv" width="800" height="500"></canvas>
+    <div id="overlay">
+      <h2>🏓 Click here to play Mr. Pong</h2>
+      <p>Hold <kbd>W</kbd>/<kbd>&uarr;</kbd> to move up, <kbd>S</kbd>/<kbd>&darr;</kbd> to move down &mdash; release to stop.</p>
+      <p>First to 5 points. You are the <b style="color:#22d3ee">cyan</b> paddle on the left.</p>
+    </div>
+  </div>
+
+  <div id="hud">
+    <span>Mr.&nbsp;Pong action: <b id="act" style="color:#e6edf3">STAY</b></span>
+    <span>V(s):&nbsp;<b id="vtxt" style="color:#e6edf3">0.00</b></span>
+    <div id="vbar"><div id="vfill"></div></div>
+  </div>
+</div>
+
+<script>
+// ---------------------------------------------------------------------------
+// Mr. Pong policy network (fromziro/MrPong) — 28,484 params, exported from the
+// checkpoint shipped on the Hub and evaluated here in the browser.
+// trunk: Linear(12,160) -> Tanh -> Linear(160,160) -> Tanh
+// actor: Linear(160,3)  (argmax => stay / up / down)   critic: Linear(160,1)
+// ---------------------------------------------------------------------------
+const B64 = "__WEIGHTS_B64__";
+const WB = (function () {
+  const bin = atob(B64);
+  const buf = new ArrayBuffer(bin.length);
+  const u8 = new Uint8Array(buf);
+  for (let i = 0; i < bin.length; i++) u8[i] = bin.charCodeAt(i);
+  return new Float32Array(buf);
+})();
+const OBS = 12, HID = 160, ACT = 3;
+const O_L0W = 0,                 O_L0B = O_L0W + HID * OBS;
+const O_L2W = O_L0B + HID,       O_L2B = O_L2W + HID * HID;
+const O_AW  = O_L2B + HID,       O_AB  = O_AW + ACT * HID;
+const O_CW  = O_AB + ACT,        O_CB  = O_CW + HID;
+
+const h1 = new Float32Array(HID), h2 = new Float32Array(HID);
+function policy(x) {
+  for (let i = 0; i < HID; i++) {
+    let s = WB[O_L0B + i], b = O_L0W + i * OBS;
+    for (let j = 0; j < OBS; j++) s += WB[b + j] * x[j];
+    h1[i] = Math.tanh(s);
+  }
+  for (let i = 0; i < HID; i++) {
+    let s = WB[O_L2B + i], b = O_L2W + i * HID;
+    for (let j = 0; j < HID; j++) s += WB[b + j] * h1[j];
+    h2[i] = Math.tanh(s);
+  }
+  let best = 0, bv = -1e30;
+  for (let i = 0; i < ACT; i++) {
+    let s = WB[O_AB + i], b = O_AW + i * HID;
+    for (let j = 0; j < HID; j++) s += WB[b + j] * h2[j];
+    if (s > bv) { bv = s; best = i; }
+  }
+  let v = WB[O_CB];
+  for (let j = 0; j < HID; j++) v += WB[O_CW + j] * h2[j];
+  return [best, v];
+}
+
+// ---------------------------------------------------------------------------
+// Physics — 1:1 port of StandalonePongEnv from the author's inference.py
+// ---------------------------------------------------------------------------
+const W = 800, H = 500, PW = 14, R = 8, SMOOTH = 0.70, VMAX = 16, ACCEL = 1.035, SKIP = 3;
+const PRESETS = {
+  easy:   { pspeed: 9.0, serve: 3.5, egoH: 110, dt: 28 },
+  normal: { pspeed: 8.5, serve: 4.2, egoH:  95, dt: 25 },
+  hard:   { pspeed: 8.0, serve: 6.0, egoH:  80, dt: 22 }
+};
+
+let P = PRESETS.normal;
+let egoY, oppY, egoVy, oppVy, ballX, ballY, ballVx, ballVy, rally, egoH = 95, oppH = 80;
+let scoreH = 0, scoreA = 0, maxRally = 0, aiAct = 0, aiVal = 0;
+let running = false, phase = "idle", phaseT = 0, banner = "", serveDir = 1, sub = 0;
+let trail = [];
+
+function resetPoint(dir) {
+  egoY = H / 2; oppY = H / 2; egoVy = 0; oppVy = 0;
+  ballX = W / 2; ballY = H / 2;
+  const ang = (Math.random() * 2 - 1) * (Math.PI / 7);
+  ballVx = dir * P.serve * Math.cos(ang);
+  ballVy = P.serve * Math.sin(ang);
+  rally = 0; sub = 0; trail = [];
+}
+
+function interceptY(targetX, bx, by, bvx, bvy) {
+  if ((targetX > bx && bvx <= 0) || (targetX < bx && bvx >= 0)) return H / 2;
+  for (let k = 0; k < 10; k++) {
+    const dtx = bvx !== 0 ? (targetX - bx) / bvx : Infinity;
+    if (dtx <= 0) break;
+    let dty;
+    if (bvy > 0) dty = (H - R - by) / bvy;
+    else if (bvy < 0) dty = (R - by) / bvy;
+    else dty = Infinity;
+    if (dtx <= dty) { by += bvy * dtx; break; }
+    bx += bvx * dty; by += bvy * dty; bvy = -bvy;
+  }
+  return Math.min(H - R, Math.max(R, by));
+}
+
+const obsBuf = new Float32Array(OBS);
+function oppObservation() {
+  const oppX = W - PW;
+  const pred = interceptY(oppX, ballX, ballY, ballVx, ballVy);
+  obsBuf[0] = (ballY - oppY) / H;
+  obsBuf[1] = (oppX - ballX) / W;
+  obsBuf[2] = -ballVx / VMAX;
+  obsBuf[3] = ballVy / VMAX;
+  obsBuf[4] = oppY / H;
+  obsBuf[5] = oppVy / P.pspeed;
+  obsBuf[6] = (egoY - oppY) / H;
+  obsBuf[7] = egoVy / P.pspeed;
+  obsBuf[8] = ballY / H;
+  obsBuf[9] = (W - ballX) / W;
+  obsBuf[10] = (pred - oppY) / H;
+  obsBuf[11] = pred / H;
+  return obsBuf;
+}
+
+function actionVel(a) { return a === 1 ? -P.pspeed : (a === 2 ? P.pspeed : 0); }
+
+function substep(egoAct, oppAct) {
+  const pEgoY = egoY, pOppY = oppY;
+  egoVy = SMOOTH * egoVy + (1 - SMOOTH) * actionVel(egoAct);
+  oppVy = SMOOTH * oppVy + (1 - SMOOTH) * actionVel(oppAct);
+  const eh = egoH / 2, oh = oppH / 2;
+  egoY = Math.min(H - eh, Math.max(eh, egoY + egoVy));
+  oppY = Math.min(H - oh, Math.max(oh, oppY + oppVy));
+
+  const pbx = ballX, pby = ballY;
+  const egoPlane = PW + R, oppPlane = (W - PW) - R;
+  const nbx = pbx + ballVx, nby = pby + ballVy;
+  let hit = false;
+
+  if (ballVx < 0 && pbx >= egoPlane && nbx <= egoPlane) {
+    const t = Math.min(1, Math.max(0, (pbx - egoPlane) / Math.max(1e-6, -ballVx)));
+    const yb = pby + t * ballVy, yp = pEgoY + t * (egoY - pEgoY);
+    if (Math.abs(yb - yp) <= eh + R * 0.6) {
+      hit = true; rally++;
+      const off = Math.min(1, Math.max(-1, (yb - yp) / eh));
+      const ang = off * (Math.PI / 3);
+      const sp = Math.min(Math.hypot(ballVx, ballVy) * ACCEL, VMAX);
+      const nvx = sp * Math.cos(ang), nvy = sp * Math.sin(ang) + 0.25 * egoVy;
+      const rem = 1 - t;
+      ballX = egoPlane + rem * nvx; ballY = yb + rem * nvy; ballVx = nvx; ballVy = nvy;
+    }
+  } else if (ballVx > 0 && pbx <= oppPlane && nbx >= oppPlane) {
+    const t = Math.min(1, Math.max(0, (oppPlane - pbx) / Math.max(1e-6, ballVx)));
+    const yb = pby + t * ballVy, yp = pOppY + t * (oppY - pOppY);
+    if (Math.abs(yb - yp) <= oh + R * 0.6) {
+      hit = true; rally++;
+      const off = Math.min(1, Math.max(-1, (yb - yp) / oh));
+      const ang = off * (Math.PI / 3);
+      const sp = Math.min(Math.hypot(ballVx, ballVy) * ACCEL, VMAX);
+      const nvx = -sp * Math.cos(ang), nvy = sp * Math.sin(ang) + 0.25 * oppVy;
+      const rem = 1 - t;
+      ballX = oppPlane + rem * nvx; ballY = yb + rem * nvy; ballVx = nvx; ballVy = nvy;
+    }
+  }
+  if (!hit) { ballX = nbx; ballY = nby; }
+
+  if (ballY - R <= 0) { ballY = R + Math.abs(R - ballY); ballVy = Math.abs(ballVy); }
+  else if (ballY + R >= H) { ballY = (H - R) - Math.abs(ballY + R - H); ballVy = -Math.abs(ballVy); }
+
+  if (ballX - R < 0) return "opponent";
+  if (ballX + R > W) return "ego";
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Input
+// ---------------------------------------------------------------------------
+let keyUp = false, keyDown = false, ctrlMode = "key", pointerY = null;
+const KUP = ["w", "W", "ArrowUp"], KDN = ["s", "S", "ArrowDown"];
+document.addEventListener("keydown", e => {
+  if (KUP.includes(e.key)) { keyUp = true; e.preventDefault(); }
+  else if (KDN.includes(e.key)) { keyDown = true; e.preventDefault(); }
+});
+document.addEventListener("keyup", e => {
+  if (KUP.includes(e.key)) { keyUp = false; e.preventDefault(); }
+  else if (KDN.includes(e.key)) { keyDown = false; e.preventDefault(); }
+});
+window.addEventListener("blur", () => { keyUp = false; keyDown = false; });
+
+const cv = document.getElementById("cv");
+function pointerFromEvent(e) {
+  const r = cv.getBoundingClientRect();
+  const cy = (e.touches ? e.touches[0].clientY : e.clientY) - r.top;
+  pointerY = Math.min(H, Math.max(0, cy * (H / r.height)));
+}
+cv.addEventListener("mousemove", pointerFromEvent);
+cv.addEventListener("touchmove", e => { pointerFromEvent(e); e.preventDefault(); }, { passive: false });
+cv.addEventListener("touchstart", pointerFromEvent, { passive: true });
+
+function humanAction() {
+  if (ctrlMode === "mouse" && pointerY !== null) {
+    const d = pointerY - egoY;
+    if (Math.abs(d) < 6) return 0;
+    return d > 0 ? 2 : 1;
+  }
+  if (keyUp && !keyDown) return 1;
+  if (keyDown && !keyUp) return 2;
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Render
+// ---------------------------------------------------------------------------
+const ctx = cv.getContext("2d");
+const ACTNAMES = ["STAY", "UP", "DOWN"];
+function draw() {
+  ctx.fillStyle = "#0f1626";
+  ctx.fillRect(0, 0, W, H);
+
+  ctx.strokeStyle = "rgba(255,255,255,.10)";
+  ctx.lineWidth = 3; ctx.setLineDash([12, 14]);
+  ctx.beginPath(); ctx.moveTo(W / 2, 0); ctx.lineTo(W / 2, H); ctx.stroke();
+  ctx.setLineDash([]);
+  ctx.lineWidth = 2; ctx.strokeStyle = "rgba(255,255,255,.07)";
+  ctx.strokeRect(1, 1, W - 2, H - 2);
+
+  for (let i = 0; i < trail.length; i++) {
+    const p = trail[i], a = (i + 1) / (trail.length + 1);
+    ctx.globalAlpha = a * 0.35;
+    ctx.fillStyle = "#e6edf3";
+    ctx.beginPath(); ctx.arc(p[0], p[1], R * (0.35 + 0.6 * a), 0, 6.2832); ctx.fill();
+  }
+  ctx.globalAlpha = 1;
+
+  ctx.fillStyle = "#22d3ee";
+  roundRect(2, egoY - egoH / 2, PW, egoH, 6);
+  ctx.fillStyle = "#4f8cff";
+  roundRect(W - PW - 2, oppY - oppH / 2, PW, oppH, 6);
+
+  ctx.fillStyle = "#ffffff";
+  ctx.beginPath(); ctx.arc(ballX, ballY, R, 0, 6.2832); ctx.fill();
+
+  ctx.font = "700 46px ui-sans-serif, system-ui, sans-serif";
+  ctx.textAlign = "center";
+  ctx.fillStyle = "rgba(34,211,238,.55)";
+  ctx.fillText(String(scoreH), W / 2 - 60, 58);
+  ctx.fillStyle = "rgba(79,140,255,.55)";
+  ctx.fillText(String(scoreA), W / 2 + 60, 58);
+
+  ctx.font = "600 13px ui-sans-serif, system-ui, sans-serif";
+  ctx.fillStyle = "rgba(230,237,243,.45)";
+  ctx.textAlign = "left";
+  ctx.fillText("YOU", 26, 34);
+  ctx.textAlign = "right";
+  ctx.fillText("MR. PONG", W - 26, 34);
+  ctx.textAlign = "left";
+  ctx.fillText("Rally " + rally + " hits   ·   Ball " + Math.hypot(ballVx, ballVy).toFixed(1) + " px/f   ·   Longest " + maxRally, 26, H - 20);
+
+  if (banner) {
+    ctx.textAlign = "center";
+    ctx.font = "800 40px ui-sans-serif, system-ui, sans-serif";
+    ctx.fillStyle = "rgba(11,15,25,.72)";
+    ctx.fillRect(0, H / 2 - 46, W, 92);
+    ctx.fillStyle = "#f97316";
+    ctx.fillText(banner, W / 2, H / 2 + 14);
+  }
+}
+function roundRect(x, y, w, h, r) {
+  ctx.beginPath();
+  ctx.moveTo(x + r, y);
+  ctx.arcTo(x + w, y, x + w, y + h, r);
+  ctx.arcTo(x + w, y + h, x, y + h, r);
+  ctx.arcTo(x, y + h, x, y, r);
+  ctx.arcTo(x, y, x + w, y, r);
+  ctx.closePath(); ctx.fill();
+}
+
+// ---------------------------------------------------------------------------
+// Loop
+// ---------------------------------------------------------------------------
+const actEl = document.getElementById("act");
+const vtxtEl = document.getElementById("vtxt");
+const vfillEl = document.getElementById("vfill");
+let acc = 0, last = 0;
+
+function tick(ts) {
+  if (!last) last = ts;
+  let dt = ts - last; last = ts;
+  if (dt > 200) dt = 200;
+
+  if (running) {
+    if (phase === "count") {
+      phaseT -= dt;
+      const n = Math.ceil(phaseT / 600);
+      banner = n > 0 ? "SERVING IN " + n : "GO!";
+      if (phaseT <= 0) { banner = ""; phase = "rally"; acc = 0; }
+    } else if (phase === "rally") {
+      acc += dt;
+      let guard = 0;
+      while (acc >= P.dt && guard < 12) {
+        acc -= P.dt; guard++;
+        if (sub % SKIP === 0) {
+          const out = policy(oppObservation());
+          aiAct = out[0]; aiVal = out[1];
+        }
+        sub++;
+        trail.push([ballX, ballY]);
+        if (trail.length > 9) trail.shift();
+        const winner = substep(humanAction(), aiAct);
+        if (rally > maxRally) maxRally = rally;
+        if (winner) {
+          if (winner === "ego") { scoreH++; serveDir = 1; banner = "POINT — YOU!"; }
+          else { scoreA++; serveDir = -1; banner = "POINT — MR. PONG"; }
+          if (scoreH >= 5 || scoreA >= 5) {
+            banner = scoreH >= 5 ? "🏆 YOU WIN " + scoreH + "–" + scoreA : "🤖 MR. PONG WINS " + scoreA + "–" + scoreH;
+            phase = "over"; running = false;
+            document.getElementById("overlay").style.display = "flex";
+            document.getElementById("overlay").innerHTML =
+              "<h2>" + banner + "</h2><p>Longest rally: " + maxRally + " hits</p><p>Click to play again</p>";
+          } else {
+            phase = "pause"; phaseT = 1100;
+          }
+          break;
+        }
+      }
+    } else if (phase === "pause") {
+      phaseT -= dt;
+      if (phaseT <= 0) { resetPoint(serveDir); phase = "count"; phaseT = 1900; }
+    }
+  }
+
+  actEl.textContent = ACTNAMES[aiAct];
+  vtxtEl.textContent = aiVal.toFixed(2);
+  const v = Math.max(-1, Math.min(1, aiVal / 3));
+  vfillEl.style.left = (v >= 0 ? 50 : 50 + v * 50) + "%";
+  vfillEl.style.width = Math.abs(v) * 50 + "%";
+  vfillEl.style.background = v >= 0 ? "#4f8cff" : "#f97316";
+
+  draw();
+  requestAnimationFrame(tick);
+}
+
+function startMatch() {
+  scoreH = 0; scoreA = 0; maxRally = 0; serveDir = 1;
+  resetPoint(serveDir);
+  banner = ""; phase = "count"; phaseT = 1900; running = true; last = 0; acc = 0;
+  document.getElementById("overlay").style.display = "none";
+  window.focus();
+}
+
+document.getElementById("overlay").addEventListener("click", startMatch);
+document.getElementById("restart").addEventListener("click", startMatch);
+document.querySelectorAll(".diff").forEach(b => b.addEventListener("click", () => {
+  document.querySelectorAll(".diff").forEach(x => x.classList.remove("active"));
+  b.classList.add("active");
+  P = PRESETS[b.dataset.d]; egoH = P.egoH;
+  startMatch();
+}));
+document.querySelectorAll(".ctrl").forEach(b => b.addEventListener("click", () => {
+  document.querySelectorAll(".ctrl").forEach(x => x.classList.remove("active"));
+  b.classList.add("active");
+  ctrlMode = b.dataset.c;
+}));
+
+egoH = P.egoH;
+resetPoint(1);
+requestAnimationFrame(tick);
+</script>
+</body>
+</html>

pong_engine.py

@@ -0,0 +1,403 @@
+"""
+Standalone table-tennis physics environment + baseline opponents for Mr. Pong.
+
+This is a faithful port of the reference implementation shipped by the model
+author in `inference.py` at https://huggingface.co/fromziro/MrPong (Apache-2.0).
+Physics constants, collision handling, observation layout and the baseline
+opponent policies are kept 1:1 with the original so that the behaviour shown in
+this Space matches the numbers reported on the model card.
+"""
+
+import math
+import random
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Tuple
+
+import numpy as np
+
+
+@dataclass
+class PhysicsConfig:
+    table_width: float = 800.0
+    table_height: float = 500.0
+    paddle_width: float = 14.0
+    paddle_height: float = 80.0
+    paddle_speed: float = 8.0
+    paddle_smoothing: float = 0.70
+    ball_radius: float = 8.0
+    ball_speed_initial: float = 8.0
+    ball_speed_max: float = 16.0
+    ball_acceleration: float = 1.035
+    frame_skip: int = 3
+    max_rally_steps: int = 1500
+
+
+class StandalonePongEnv:
+    """Self-contained table tennis physics environment (port of the author's env)."""
+
+    def __init__(self, phys: Optional[PhysicsConfig] = None, seed: Optional[int] = None):
+        self.phys = phys or PhysicsConfig()
+        self.rng = random.Random(seed)
+        self.ego_paddle_h = self.phys.paddle_height
+        self.opp_paddle_h = self.phys.paddle_height
+        self.reset()
+
+    def reset(self, serve_direction: Optional[int] = None,
+              initial_speed: Optional[float] = None) -> np.ndarray:
+        self.ego_y = self.phys.table_height / 2.0
+        self.opp_y = self.phys.table_height / 2.0
+        self.ego_vy = 0.0
+        self.opp_vy = 0.0
+        self.prev_ego_action = 0
+
+        self.ball_x = self.phys.table_width / 2.0
+        self.ball_y = self.phys.table_height / 2.0
+
+        if serve_direction is None:
+            serve_direction = 1 if self.rng.random() < 0.5 else -1
+
+        serve_angle = self.rng.uniform(-math.pi / 7.0, math.pi / 7.0)
+        speed = initial_speed or self.phys.ball_speed_initial
+        self.ball_vx = serve_direction * speed * math.cos(serve_angle)
+        self.ball_vy = speed * math.sin(serve_angle)
+        self.rally_count = 0
+        self.step_count = 0
+
+        return self.get_ego_observation()
+
+    def _get_action_velocity(self, action: int) -> float:
+        if action == 1:
+            return -self.phys.paddle_speed
+        elif action == 2:
+            return self.phys.paddle_speed
+        return 0.0
+
+    def physics_substep(self, ego_action: int, opp_action: int) -> Tuple[bool, Dict[str, Any]]:
+        info = {"winner": None}
+        done = False
+
+        prev_ego_y = self.ego_y
+        prev_opp_y = self.opp_y
+
+        ego_target_v = self._get_action_velocity(ego_action)
+        opp_target_v = self._get_action_velocity(opp_action)
+
+        alpha = self.phys.paddle_smoothing
+        self.ego_vy = alpha * self.ego_vy + (1.0 - alpha) * ego_target_v
+        self.opp_vy = alpha * self.opp_vy + (1.0 - alpha) * opp_target_v
+
+        ego_half_h = self.ego_paddle_h / 2.0
+        opp_half_h = self.opp_paddle_h / 2.0
+
+        self.ego_y = float(np.clip(self.ego_y + self.ego_vy, ego_half_h,
+                                   self.phys.table_height - ego_half_h))
+        self.opp_y = float(np.clip(self.opp_y + self.opp_vy, opp_half_h,
+                                   self.phys.table_height - opp_half_h))
+
+        prev_ball_x = self.ball_x
+        prev_ball_y = self.ball_y
+        r = self.phys.ball_radius
+
+        ego_paddle_x = self.phys.paddle_width
+        opp_paddle_x = self.phys.table_width - self.phys.paddle_width
+        ego_impact_plane = ego_paddle_x + r
+        opp_impact_plane = opp_paddle_x - r
+
+        next_ball_x = prev_ball_x + self.ball_vx
+        next_ball_y = prev_ball_y + self.ball_vy
+
+        hit_occurred = False
+
+        # Left (ego) paddle — continuous collision detection
+        if self.ball_vx < 0 and prev_ball_x >= ego_impact_plane and next_ball_x <= ego_impact_plane:
+            t = float(np.clip((prev_ball_x - ego_impact_plane) / max(1e-6, -self.ball_vx), 0.0, 1.0))
+            y_ball_at_impact = prev_ball_y + t * self.ball_vy
+            y_ego_at_impact = prev_ego_y + t * (self.ego_y - prev_ego_y)
+
+            if abs(y_ball_at_impact - y_ego_at_impact) <= (ego_half_h + r * 0.6):
+                hit_occurred = True
+                self.rally_count += 1
+                offset = float(np.clip((y_ball_at_impact - y_ego_at_impact) / ego_half_h, -1.0, 1.0))
+                bounce_angle = offset * (math.pi / 3.0)
+                current_speed = math.hypot(self.ball_vx, self.ball_vy)
+                new_speed = min(current_speed * self.phys.ball_acceleration, self.phys.ball_speed_max)
+                new_vx = new_speed * math.cos(bounce_angle)
+                new_vy = new_speed * math.sin(bounce_angle) + 0.25 * self.ego_vy
+
+                rem_dt = 1.0 - t
+                self.ball_x = ego_impact_plane + rem_dt * new_vx
+                self.ball_y = y_ball_at_impact + rem_dt * new_vy
+                self.ball_vx = new_vx
+                self.ball_vy = new_vy
+
+        # Right (opponent) paddle
+        elif self.ball_vx > 0 and prev_ball_x <= opp_impact_plane and next_ball_x >= opp_impact_plane:
+            t = float(np.clip((opp_impact_plane - prev_ball_x) / max(1e-6, self.ball_vx), 0.0, 1.0))
+            y_ball_at_impact = prev_ball_y + t * self.ball_vy
+            y_opp_at_impact = prev_opp_y + t * (self.opp_y - prev_opp_y)
+
+            if abs(y_ball_at_impact - y_opp_at_impact) <= (opp_half_h + r * 0.6):
+                hit_occurred = True
+                self.rally_count += 1
+                offset = float(np.clip((y_ball_at_impact - y_opp_at_impact) / opp_half_h, -1.0, 1.0))
+                bounce_angle = offset * (math.pi / 3.0)
+                current_speed = math.hypot(self.ball_vx, self.ball_vy)
+                new_speed = min(current_speed * self.phys.ball_acceleration, self.phys.ball_speed_max)
+                new_vx = -new_speed * math.cos(bounce_angle)
+                new_vy = new_speed * math.sin(bounce_angle) + 0.25 * self.opp_vy
+
+                rem_dt = 1.0 - t
+                self.ball_x = opp_impact_plane + rem_dt * new_vx
+                self.ball_y = y_ball_at_impact + rem_dt * new_vy
+                self.ball_vx = new_vx
+                self.ball_vy = new_vy
+
+        if not hit_occurred:
+            self.ball_x = next_ball_x
+            self.ball_y = next_ball_y
+
+        # Wall collisions
+        if self.ball_y - r <= 0:
+            self.ball_y = r + abs(r - self.ball_y)
+            self.ball_vy = abs(self.ball_vy)
+        elif self.ball_y + r >= self.phys.table_height:
+            self.ball_y = (self.phys.table_height - r) - abs(self.ball_y + r - self.phys.table_height)
+            self.ball_vy = -abs(self.ball_vy)
+
+        # Goal boundaries
+        if self.ball_x - r < 0:
+            done = True
+            info["winner"] = "opponent"
+        elif self.ball_x + r > self.phys.table_width:
+            done = True
+            info["winner"] = "ego"
+
+        self.prev_ego_action = ego_action
+        return done, info
+
+    def step(self, ego_action: int, opp_action: int) -> Tuple[np.ndarray, bool, Dict[str, Any]]:
+        self.step_count += 1
+        done = False
+        info = {"winner": None}
+
+        for _ in range(self.phys.frame_skip):
+            d, sub_info = self.physics_substep(ego_action, opp_action)
+            if d:
+                done = True
+                info = sub_info
+                break
+
+        if not done and self.step_count >= self.phys.max_rally_steps:
+            done = True
+            info["winner"] = "draw"
+
+        return self.get_ego_observation(), done, info
+
+    def calculate_intercept_y(self, target_x: float, ball_x: float, ball_y: float,
+                              ball_vx: float, ball_vy: float) -> float:
+        if (target_x > ball_x and ball_vx <= 0) or (target_x < ball_x and ball_vx >= 0):
+            return self.phys.table_height / 2.0
+
+        bx, by = float(ball_x), float(ball_y)
+        bvx, bvy = float(ball_vx), float(ball_vy)
+        h = self.phys.table_height
+        r = self.phys.ball_radius
+
+        for _ in range(10):
+            dt_x = (target_x - bx) / bvx if bvx != 0 else float("inf")
+            if dt_x <= 0:
+                break
+            if bvy > 0:
+                dt_y = (h - r - by) / bvy
+            elif bvy < 0:
+                dt_y = (r - by) / bvy
+            else:
+                dt_y = float("inf")
+
+            if dt_x <= dt_y:
+                by += bvy * dt_x
+                break
+            else:
+                bx += bvx * dt_y
+                by += bvy * dt_y
+                bvy = -bvy
+
+        return float(np.clip(by, r, h - r))
+
+    def get_ego_observation(self) -> np.ndarray:
+        w, h = self.phys.table_width, self.phys.table_height
+        v_max = self.phys.ball_speed_max
+        pv_max = self.phys.paddle_speed
+        half_h = self.ego_paddle_h / 2.0
+        ego_x = self.phys.paddle_width
+
+        pred_intercept_y = self.calculate_intercept_y(ego_x, self.ball_x, self.ball_y,
+                                                      self.ball_vx, self.ball_vy)
+        rel_pred_y = (pred_intercept_y - self.ego_y) / h
+        pred_norm_y = pred_intercept_y / h
+
+        opp_y_norm = self.opp_y / h
+        opp_open_top = (self.opp_y - half_h) / h
+        opp_open_bottom = (h - (self.opp_y + half_h)) / h
+        speed_norm = math.hypot(self.ball_vx, self.ball_vy) / v_max
+
+        return np.array([
+            (self.ball_y - self.ego_y) / h,
+            (self.ball_x - ego_x) / w,
+            self.ball_vx / v_max,
+            self.ball_vy / v_max,
+            self.ego_y / h,
+            self.ego_vy / pv_max,
+            (self.opp_y - self.ego_y) / h,
+            self.opp_vy / pv_max,
+            self.ball_y / h,
+            self.ball_x / w,
+            rel_pred_y,
+            pred_norm_y,
+            opp_y_norm,
+            opp_open_top,
+            opp_open_bottom,
+            speed_norm,
+        ], dtype=np.float32)
+
+    def get_opp_observation(self) -> np.ndarray:
+        w, h = self.phys.table_width, self.phys.table_height
+        v_max = self.phys.ball_speed_max
+        pv_max = self.phys.paddle_speed
+        half_h = self.opp_paddle_h / 2.0
+        opp_x = self.phys.table_width - self.phys.paddle_width
+
+        pred_intercept_y = self.calculate_intercept_y(opp_x, self.ball_x, self.ball_y,
+                                                      self.ball_vx, self.ball_vy)
+        rel_pred_y = (pred_intercept_y - self.opp_y) / h
+        pred_norm_y = pred_intercept_y / h
+
+        ego_y_norm = self.ego_y / h
+        ego_open_top = (self.ego_y - half_h) / h
+        ego_open_bottom = (h - (self.ego_y + half_h)) / h
+        speed_norm = math.hypot(self.ball_vx, self.ball_vy) / v_max
+
+        return np.array([
+            (self.ball_y - self.opp_y) / h,
+            (opp_x - self.ball_x) / w,
+            -self.ball_vx / v_max,
+            self.ball_vy / v_max,
+            self.opp_y / h,
+            self.opp_vy / pv_max,
+            (self.ego_y - self.opp_y) / h,
+            self.ego_vy / pv_max,
+            self.ball_y / h,
+            (w - self.ball_x) / w,
+            rel_pred_y,
+            pred_norm_y,
+            ego_y_norm,
+            ego_open_top,
+            ego_open_bottom,
+            speed_norm,
+        ], dtype=np.float32)
+
+
+# ==================================================================================
+# Baseline opponents (ported from the author's inference.py)
+# ==================================================================================
+
+def smooth_aim_action(current_y: float, target_y: float, prev_action: int,
+                      deadzone: float = 6.0) -> int:
+    diff = target_y - current_y
+    if abs(diff) < deadzone:
+        return 0
+    return 2 if diff > 0 else 1
+
+
+class RealisticHardOpponent:
+    def __init__(self, commit_x_ratio: float = 0.60, rng: Optional[random.Random] = None):
+        self.commit_x_ratio = commit_x_ratio
+        self.prev_action = 0
+        self.perceptual_noise = 0.0
+        self.rng = rng or random.Random()
+
+    def act(self, env: StandalonePongEnv) -> int:
+        if env.ball_vx <= 0:
+            target_y = env.phys.table_height / 2.0
+            self.perceptual_noise = self.rng.uniform(-12.0, 12.0)
+        elif env.ball_x < env.phys.table_width * self.commit_x_ratio:
+            target_y = env.phys.table_height / 2.0 + (env.ball_y - env.phys.table_height / 2.0) * 0.40
+        else:
+            target_x = env.phys.table_width - env.phys.paddle_width
+            exact_y = env.calculate_intercept_y(target_x, env.ball_x, env.ball_y,
+                                                env.ball_vx, env.ball_vy)
+            target_y = float(np.clip(exact_y + self.perceptual_noise, 8.0,
+                                     env.phys.table_height - 8.0))
+
+        action = smooth_aim_action(env.opp_y, target_y, self.prev_action, deadzone=7.0)
+        self.prev_action = action
+        return action
+
+
+class MediumOpponent:
+    def __init__(self, rng: Optional[random.Random] = None):
+        self.prev_action = 0
+        self.rng = rng or random.Random()
+
+    def act(self, env: StandalonePongEnv) -> int:
+        if env.ball_vx <= 0:
+            target_y = env.phys.table_height / 2.0
+        else:
+            dt = (env.phys.table_width - env.phys.paddle_width - env.ball_x) / max(1.0, env.ball_vx)
+            target_y = env.ball_y + env.ball_vy * dt
+            target_y = float(np.clip(target_y, 0, env.phys.table_height))
+
+        action = smooth_aim_action(env.opp_y, target_y, self.prev_action, deadzone=14.0)
+        self.prev_action = action
+        return action
+
+
+class EasyOpponent:
+    def __init__(self, rng: Optional[random.Random] = None):
+        self.prev_action = 0
+        self.rng = rng or random.Random()
+
+    def act(self, env: StandalonePongEnv) -> int:
+        if env.ball_vx <= 0 or env.ball_x < env.phys.table_width * 0.45:
+            target_y = env.phys.table_height / 2.0
+        else:
+            target_y = env.ball_y + self.rng.uniform(-30.0, 30.0)
+
+        action = smooth_aim_action(env.opp_y, target_y, self.prev_action, deadzone=25.0)
+        self.prev_action = action
+        return action
+
+
+class ImpossibleHardOpponent:
+    def __init__(self, rng: Optional[random.Random] = None):
+        self.prev_action = 0
+        self.rng = rng or random.Random()
+
+    def act(self, env: StandalonePongEnv) -> int:
+        if env.ball_vx <= 0:
+            target_y = env.phys.table_height / 2.0
+        else:
+            target_x = env.phys.table_width - env.phys.paddle_width
+            target_y = env.calculate_intercept_y(target_x, env.ball_x, env.ball_y,
+                                                 env.ball_vx, env.ball_vy)
+
+        action = smooth_aim_action(env.opp_y, target_y, self.prev_action, deadzone=2.0)
+        self.prev_action = action
+        return action
+
+
+class RandomOpponent:
+    def __init__(self, rng: Optional[random.Random] = None):
+        self.rng = rng or random.Random()
+
+    def act(self, env: StandalonePongEnv) -> int:
+        return self.rng.randint(0, 2)
+
+
+OPPONENTS = {
+    "Realistic Hard": RealisticHardOpponent,
+    "Medium Logic": MediumOpponent,
+    "Easy Logic": EasyOpponent,
+    "Impossible Hard": ImpossibleHardOpponent,
+    "Random Agent": RandomOpponent,
+}

requirements.txt

@@ -0,0 +1,6 @@
+torch
+transformers
+numpy
+pillow
+imageio
+imageio-ffmpeg