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.
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
| Need | Why | Check |
|---|---|---|
| Node.js 22+ | global WebSocket for the Chrome DevTools Protocol | node --version |
| Python 3.10+ | image statistics and calibration | python3 --version |
| Pillow | PNG decode and image filters | python3 -c "import PIL; print(PIL.__version__)" |
| Chrome / Chromium | headless rendering and CDP | set 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.
./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:
./install.sh ~/.agents/skills
# or a project-local skills directory
./install.sh .agent/skillsIf your agent reads a single instruction file, copy the skill as AGENTS.md (or the equivalent):
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.
| Hook | Used by | Purpose |
|---|---|---|
window.__READY = true | shaders, every render | set after a few frames; a page that never becomes ready fails the shader gate |
window.__STATS | product, qa | { calls, triangles, fps, lights } after the last frame |
window.__SCENE | census, collide, lights | the scene graph; every rendered mesh and light is reachable |
window.__COLLIDERS | collide | array of { x0, z0, x1, z1, y0?, y1? } |
window.__BOUNDS | collide | { x0, z0, x1, z1, playerRadius } |
window.__TESTMOVE(x, z, dx, dz) | collide | returns the resolved [x, z] after a step; used for penetration and walk-through |
window.__TEST(action, arg) | playtest, product | scripted actions; see the protocol below |
window.__GAME | optional | { state, actions, reset } for a human or a second driver |
window.__PRODUCT | product, mobile, look | shell, content, persistence, touch, audio, budgets, cameras |
window.__AUDIT | audit | optional per-object budget manifest |
?shot=1 | all stills | hide chrome, freeze the clock, keep the DOM inspectable |
?cam=x,y,z,tx,ty,tz | look, qa | fixed camera for comparable frames |
?seed=N | all | fixed 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
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.
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
| Gate | Reads | Fails when |
|---|---|---|
shaders | console, __READY | a GLSL compile/link error is logged, or the page never becomes ready |
census | __SCENE | a visible mesh is missing radial segments, surface maps or declared identity |
collide | __SCENE, __COLLIDERS, __BOUNDS, __TESTMOVE | a blocker has no collider, the boundary is bare, a tall object is walk-through, or the mover penetrates |
lights | __SCENE | a point/spot light has no fixture within 0.4 m |
playtest | __TEST | win, loss, named cause, visible consequence or restart fails |
product | __PRODUCT, __TEST, DOM | a screen, setting, persistence key, touch element, content role, HUD group, audio event, camera or budget is missing |
mobile | __PRODUCT, DOM | 390×844 overflows, the title is unusable, or touch is declared without controls |
look | __PRODUCT.cameras, screenshot | the 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:
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:
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.
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:
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
| Symptom | Cause | Fix |
|---|---|---|
render: Chrome/Chromium not found | not in a standard path | CHROME_PATH=/path/to/chrome node harness/render.mjs ... |
needs Node.js 22+ | no global WebSocket | upgrade Node, or run the harness with a Node 22 binary |
ready=false, white or black frame | page never sets __READY, or a shader failed | read the console errors in the render output; fix the compile error before exposure |
| Gate output ends at a blank line | a render is waiting for a page that never becomes ready | the gate has its own timeout; check ?shot=1 and the page error |
no __TEST | the page does not expose the contract | add window.__TEST; see the protocol above |
profile not found | no refs/profile.json | calibrate, or run without --profile and accept the fallback |
| Look score is low but tone is fine | the frame is under-detailed | add 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
- 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.