Game Performance skill for Claude Code

#!/usr/bin/env python3
"""Frame-time statistics and spike finder for game captures (stdlib only).

Input: a CSV with a frame-time column in milliseconds (PresentMon/CapFrameX style
"MsBetweenPresents" or "FrameTime", or any column named via --column), or a plain text
file with one frame time per line. Use - for stdin.

  python3 frame_stats.py capture.csv --target-fps 60
  python3 frame_stats.py frames.txt --target-fps 30 --column ms
  python3 frame_stats.py capture.csv --target-fps 60 --fps-input   # column holds FPS, not ms

Reports average FPS, p50/p95/p99 frame time, 1% and 0.1% lows, share of frames over
budget, the worst spikes, and whether spikes recur at a regular interval (a common
signature of garbage collection, streaming, or a periodic system).

Exit status: 0 = p95 within budget and 1% low >= 90% of target, 1 = budget missed,
2 = bad input.
"""
from __future__ import annotations

import argparse
import csv
import io
import statistics
import sys

KNOWN = ["msbetweenpresents", "frametime", "frame_time_ms", "frame_time", "frametime_ms", "ms", "cpu_ms", "gpu_ms"]


def load(text: str, column: str | None, fps_input: bool) -> list[float]:
    lines = [l for l in text.splitlines() if l.strip() and not l.lstrip().startswith("//")]
    if not lines:
        raise ValueError("no data")
    try:
        float(lines[0].split(",")[0])
        has_header = False
    except ValueError:
        has_header = True
    values: list[float] = []
    if has_header:
        reader = csv.DictReader(io.StringIO("\n".join(lines)))
        fields = {f.strip().lower(): f for f in (reader.fieldnames or [])}
        key = None
        if column:
            key = fields.get(column.lower())
            if key is None:
                raise ValueError(f"column '{column}' not found; have: {', '.join(reader.fieldnames or [])}")
        else:
            for k in KNOWN:
                if k in fields:
                    key = fields[k]
                    break
            if key is None:
                raise ValueError(f"no frame-time column found; pass --column. Columns: {', '.join(reader.fieldnames or [])}")
        for row in reader:
            v = (row.get(key) or "").strip()
            if v:
                values.append(float(v))
    else:
        values = [float(l.split(",")[0]) for l in lines]
    if fps_input:
        values = [1000.0 / v for v in values if v > 0]
    values = [v for v in values if v > 0]
    if len(values) < 10:
        raise ValueError(f"only {len(values)} frames; capture at least a few hundred")
    return values


def pct(sorted_vals: list[float], p: float) -> float:
    idx = min(len(sorted_vals) - 1, max(0, round(p / 100 * (len(sorted_vals) - 1))))
    return sorted_vals[idx]


def low_fps(sorted_vals: list[float], fraction: float) -> float:
    n = max(1, int(len(sorted_vals) * fraction))
    worst = sorted_vals[-n:]
    return 1000.0 / statistics.fmean(worst)


def main() -> int:
    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
    p.add_argument("file", help="CSV or text file, or - for stdin")
    p.add_argument("--target-fps", type=float, default=60.0)
    p.add_argument("--column", help="frame-time column name (case-insensitive)")
    p.add_argument("--fps-input", action="store_true", help="values are FPS instead of milliseconds")
    p.add_argument("--spike-factor", type=float, default=2.0, help="spike = frame > factor x median (default 2)")
    p.add_argument("--top", type=int, default=5, help="number of worst frames to list")
    a = p.parse_args()
    try:
        text = sys.stdin.read() if a.file == "-" else open(a.file, encoding="utf-8-sig").read()
        ft = load(text, a.column, a.fps_input)
    except (OSError, ValueError) as e:
        print(f"error: {e}", file=sys.stderr)
        return 2

    budget = 1000.0 / a.target_fps
    s = sorted(ft)
    total_s = sum(ft) / 1000.0
    median = statistics.median(ft)
    over = sum(1 for v in ft if v > budget)
    spikes = [i for i, v in enumerate(ft) if v > a.spike_factor * median]
    p95, p99 = pct(s, 95), pct(s, 99)
    low1, low01 = low_fps(s, 0.01), low_fps(s, 0.001)

    print(f"Frames: {len(ft)} over {total_s:.1f} s | target {a.target_fps:g} fps = {budget:.2f} ms budget")
    print(f"Average FPS: {len(ft) / total_s:.1f}   (mean frame {statistics.fmean(ft):.2f} ms)")
    print(f"Frame time p50 {median:.2f} ms | p95 {p95:.2f} ms | p99 {p99:.2f} ms | max {s[-1]:.2f} ms")
    print(f"1% low {low1:.1f} fps | 0.1% low {low01:.1f} fps")
    print(f"Over budget: {over} frames ({over / len(ft):.1%})")
    print(f"Spikes (> {a.spike_factor:g}x median = {a.spike_factor * median:.2f} ms): {len(spikes)}")
    worst = sorted(range(len(ft)), key=lambda i: ft[i], reverse=True)[: a.top]
    for i in sorted(worst):
        t = sum(ft[:i]) / 1000.0
        print(f"  frame {i:>6} at {t:7.2f} s: {ft[i]:.2f} ms")

    if len(spikes) >= 4:
        times, acc = [], 0.0
        idx = set(spikes)
        for i, v in enumerate(ft):
            if i in idx:
                times.append(acc)
            acc += v
        gaps = [b - a2 for a2, b in zip(times, times[1:])]
        mean_gap = statistics.fmean(gaps)
        cv = statistics.pstdev(gaps) / mean_gap if mean_gap else 1
        if cv < 0.25:
            print(f"Pattern: spikes recur every ~{mean_gap / 1000:.2f} s (low variance) -> suspect GC, "
                  f"periodic save/autosave, streaming tick, or a timer-driven system")
        else:
            print("Pattern: spikes are irregular -> suspect content-triggered work (spawns, loads, shader compiles)")
    jumps = sum(1 for x, y in zip(ft, ft[1:]) if abs(y - x) > budget)
    print(f"Frame-to-frame jumps > one budget: {jumps} (perceived stutter even when average FPS is fine)")

    ok = p95 <= budget and low1 >= 0.9 * a.target_fps
    print("RESULT: " + ("PASS" if ok else "FAIL") +
          f" (p95 {'<=' if p95 <= budget else '>'} budget, 1% low {low1:.1f} vs {0.9 * a.target_fps:.1f} required)")
    return 0 if ok else 1


if __name__ == "__main__":
    sys.exit(main())