Quick start

Clone the repo, install Pillow, point the gates at a game. The harness is a set of small Node and Python scripts; it does not import your game, it drives a page in headless Chrome.

terminal
git clone https://github.com/NorwinYu/photoreal-game.git
cd photoreal-game
python3 -m pip install -r requirements.txt

# the skill: copy it into a skills directory, or use SKILL.md as AGENTS.md
./install.sh ~/.agents/skills

# the gates: --dir is the project root served by the static server
node harness/verify.mjs --dir ../my-game --page index.html

Run the command from anywhere. The tool paths are resolved from the harness directory; --dir and --out are resolved from your current directory. A run writes its screenshots and logs to shots/.

Requirements

NeedWhyCheck
Node.js 22+global WebSocket for the Chrome DevTools Protocolnode --version
Python 3.10+image statistics and calibrationpython3 --version
PillowPNG decode and image filterspython3 -c "import PIL; print(PIL.__version__)"
Chrome / Chromiumheadless rendering and CDPset CHROME_PATH if it is not in a standard place

There is no npm install, no bundler and no API key. The games themselves should be single-file and make no network requests; the harness does not need the network either.

Install

DeepSeek Harness (DSH)

DSH discovers skills at <workspace>/.dsh/skills/<name>/SKILL.md. Install there and start a new session; the skill catalog is read at session start.

DSH / workspace skill directory
./install.sh /path/to/your-workspace/.dsh/skills
# result: <workspace>/.dsh/skills/photoreal-game/SKILL.md + harness/

Then ask for photoreal-game in a new session. Update with git pull and the same install command; uninstall by removing that one directory. Full notes: INSTALL.md.

Generic skill directory

If your agent discovers skills as <dir>/<name>/SKILL.md, install the directory:

skill directory
./install.sh ~/.agents/skills
# or a project-local skills directory
./install.sh .agent/skills

If your agent reads a single instruction file, copy the skill as AGENTS.md (or the equivalent):

instruction file
cp SKILL.md ../my-game/AGENTS.md

The harness is copied with the skill. It is not loaded into the model's context; the agent runs it from the shell. A skill that cannot see its output is a procedure without eyes.

Page contract

The gates do not read your source. They read a small set of globals and URL parameters. Implement only what your page can support; a missing hook fails the gate that needs it, with a message that names the hook.

HookUsed byPurpose
window.__READY = trueshaders, every renderset after a few frames; a page that never becomes ready fails the shader gate
window.__STATSproduct, qa{ calls, triangles, fps, lights } after the last frame
window.__SCENEcensus, collide, lightsthe scene graph; every rendered mesh and light is reachable
window.__COLLIDERScollidearray of { x0, z0, x1, z1, y0?, y1? }
window.__BOUNDScollide{ x0, z0, x1, z1, playerRadius }
window.__TESTMOVE(x, z, dx, dz)collidereturns the resolved [x, z] after a step; used for penetration and walk-through
window.__TEST(action, arg)playtest, productscripted actions; see the protocol below
window.__GAMEoptional{ state, actions, reset } for a human or a second driver
window.__PRODUCTproduct, mobile, lookshell, content, persistence, touch, audio, budgets, cameras
window.__AUDITauditoptional per-object budget manifest
?shot=1all stillshide chrome, freeze the clock, keep the DOM inspectable
?cam=x,y,z,tx,ty,tzlook, qafixed camera for comparable frames
?seed=Nallfixed random seed, so a frame is reproducible

Do not remove debug chrome in still mode. Use display:none; the headless product and playtest gates read the same DOM. Removing it makes the still clean and the game untestable.

Acceptance command

terminal
node harness/verify.mjs \
  --dir ../my-game \
  --page index.html \
  [--profile refs/profile.json] \
  [--target 0.85]

The command runs the gates in failure-class order and stops at the verdict, not at the first failure. A red verdict is a build failure. The process exits non-zero, so CI can consume it.

the shape of a pass
  shaders   PASS
  census    PASS
  collide   PASS
  lights    PASS
  playtest  PASS
  product   PASS
  mobile    PASS
  look      PASS

look mode: FALLBACK (tone + emptiness; no profile at refs/profile.json)
VERDICT: PASS (8/8)

The eight gates

GateReadsFails when
shadersconsole, __READYa GLSL compile/link error is logged, or the page never becomes ready
census__SCENEa visible mesh is missing radial segments, surface maps or declared identity
collide__SCENE, __COLLIDERS, __BOUNDS, __TESTMOVEa blocker has no collider, the boundary is bare, a tall object is walk-through, or the mover penetrates
lights__SCENEa point/spot light has no fixture within 0.4 m
playtest__TESTwin, loss, named cause, visible consequence or restart fails
product__PRODUCT, __TEST, DOMa screen, setting, persistence key, touch element, content role, HUD group, audio event, camera or budget is missing
mobile__PRODUCT, DOM390×844 overflows, the title is unusable, or touch is declared without controls
look__PRODUCT.cameras, screenshotthe worst declared camera misses the profile, or tone fails; without a profile, tone or emptiness fails

The look gate is deliberately last. A beautiful frame does not rescue a missing product, and a look score is a compass for one reference look, not a finished-game score.

Calibration

Capture 2–3 frames of the project's own target — the reference build, a still, concept art — at the same resolution and framing class as your output. Then generate a profile:

terminal
python3 harness/calibrate.py refs/target-a.png refs/target-b.png \
  --out refs/profile.json

node harness/verify.mjs --dir ../my-game --page index.html \
  --profile refs/profile.json

The profile stores median band energies, spatial p10, contrast, flat-tile share and colourfulness. The scorer compares ratios, not absolutes, and adds binary tone checks that are independent of style.

A profile captured from another subject ranks similarity to that look, not finished-ness. A stylised scene can score below a photographic one even when it is the more finished game. Use the project's own profile, or use the declared fallback and say so.

If no profile exists, verify prints look mode: FALLBACK and checks tone and emptiness only: clipped highlights ≤ 1%, crushed blacks ≤ 3%, midtones 45–80%, flat tiles ≤ 12%, mean luma between 0.10 and 0.62.

Playtest protocols

playtest.mjs knows two protocols and no coordinates. A page that implements neither fails with an instruction, not with a project-specific crash.

1. The page owns the script: __TEST('selftest')

Best for racing, puzzles, management and any loop whose success is not a list of points. Run the win, the loss and the restart, then return a JSON-safe report:

page / selftest
window.__TEST = (action) => {
  if (action === 'selftest') {
    reset();
    const win = runScriptedWin();      // drive the real loop
    const loss = runScriptedLoss();
    const restart = resetAndCheck();
    return {
      win: win.done === true,
      fail: loss.failed === true,
      restart: restart.health === 100,
      cause: loss.cause,              // never empty
      steps: ['win', 'loss', 'restart'],
    };
  }
  // start / pause / resume / openSettings / closeSettings / save / state ...
};

2. The page declares a plan: __TEST('plan')

Best for an interaction contract: walk to each target, check the prompt in both directions, interact, compare progress with the visible world, then test lethal damage and reset.

page / plan
window.__TEST = (action, arg) => {
  if (action === 'plan') return {
    key: 'E',
    farPoint: [30, 30],
    targets: [
      { id: 'relay-a', pos: [0, 10] },
      { id: 'relay-b', pos: [8, 4] },
      { id: 'relay-c', pos: [-6, 2] },
    ],
    required: 3,
  };
  // reset / goto / step / interact / hurt / state / visual ...
};

The gate checks the negative half (no key prompt when out of range), the positive half (prompt, interact, progress, a visible world change), lethal damage with a named cause, the end screen and reset. The damage action is __TEST('hurt', n); the visual trace is __TEST('visual').

Product manifest

__PRODUCT is a claim; the gate checks DOM behaviour and the declared counts. Do not declare what the page does not do. A minimal manifest:

page / __PRODUCT
window.__PRODUCT = {
  title: { name: 'Game title', start: '#start', hud: '#hud', hudHiddenOnTitle: true },
  screens: ['menu', 'playing', 'paused', 'settings', 'lost', 'won'],
  ui: { start: '#start', hud: '#hud', pause: '#pause', settings: '#settings', end: '#end', touch: '#touch' },
  settings: ['sensitivity', 'volume', 'fov', 'invertY', 'quality'],
  persistence: ['game.best'],
  input: { keyboard: true, mouse: true, touch: true },
  content: {
    objectives: [{ id: 'objective-1', title: 'Objective', steps: 3 }],
    roles: ['role-a', 'role-b'],
    tools: ['tool-a', 'tool-b'],
    beats: ['intro', 'contact', 'mid', 'climax', 'win'],
  },
  hud: ['objective', 'compass', 'health', 'ammo', 'prompt', 'subtitles'],
  audio: { events: 10, mute: true },
  perf: { maxCalls: 700, maxTris: 400000, maxLights: 14 },
  cameras: [
    { name: 'hero', cam: [0.5, 1.7, 10, -2.6, 1.3, -10] },
    { name: 'close', cam: [-6.4, 1.4, 5.2, -9.9, 1.0, 2.2] },
  ],
  test: { start: 'start', pause: 'pause', resume: 'resume', settings: 'openSettings', save: 'save' },
};

The declaration is checked against the DOM: the title must be visible on load, the HUD hidden; start must reveal the HUD; pause, settings and end must be inspectable; the persistence keys must exist after save; touch must exist if declared; the content counts must meet the minimum; __STATS must be within the declared budgets; and two still cameras must be present.

Troubleshooting

SymptomCauseFix
render: Chrome/Chromium not foundnot in a standard pathCHROME_PATH=/path/to/chrome node harness/render.mjs ...
needs Node.js 22+no global WebSocketupgrade Node, or run the harness with a Node 22 binary
ready=false, white or black framepage never sets __READY, or a shader failedread the console errors in the render output; fix the compile error before exposure
Gate output ends at a blank linea render is waiting for a page that never becomes readythe gate has its own timeout; check ?shot=1 and the page error
no __TESTthe page does not expose the contractadd window.__TEST; see the protocol above
profile not foundno refs/profile.jsoncalibrate, or run without --profile and accept the fallback
Look score is low but tone is finethe frame is under-detailedadd mid-scale objects and material variation; do not raise contrast or bloom

For a per-object judgement, use harness/objectbox.py on a crop. For duplicate symbols and blocks in a generated file, use harness/structcheck.mjs. For a fixed-camera table with thresholds, use harness/qa.mjs.

CI

github actions
- uses: actions/setup-node@v4
  with: { node-version: 22 }
- uses: actions/setup-python@v5
  with: { python-version: '3.12' }
- run: python3 -m pip install -r requirements.txt
- run: node harness/verify.mjs --dir ./game --page index.html

The repo's own CI runs syntax checks and a site link/asset check. A game project should run its acceptance command, not just a syntax check. A gate that is not in CI is a gate that stops being run.

Privacy and licence

The site has no analytics, cookies or third-party requests. The games are single-file and make no network requests while playing. Settings and best runs use localStorage on the player's machine.

Code, harness and prose are MIT. The game builds under site/play/ and the screenshots remain © Norwin Yu; they are evidence, not a grant of rights to the games. Third-party names and the Saltline reference frame remain with their owners.

Something is missing

A gate that fails for the wrong reason is a bug.

Open an issue ↗