Start here

01 No setup required

Report visual bugs from inside the game

Both playable demos have a built-in reporting mode. Spot a misplaced, misoriented, glitched or broken-looking model? Click it in-game and file a report — the game records exactly which asset it is, where it sits in the level, and where you were standing. No guessing about which “weird brown thing” you meant.

1. Play normally until you see something wrong (WASD to walk, N for noclip flying if you want a closer look).
2. Press B (think “bug”) or tap the QA: Off button in the top bar — it flips to QA: On. Your mouse now inspects instead of steering the camera.
3. Hover over any model: it lights up yellow and a label shows its name (e.g. labshak · placement or 3JIM [JIM1] · entity).
4. Click the broken model. It turns orange and a report dialog opens.
5. Pick a category:

   Code	Meaning
   PLC	wrong position
   ORI	wrong orientation / rotation
   SCL	wrong size
   ANI	animation wrong or missing
   TEX	texture wrong or missing
   MIS	model missing entirely
   GFX	other visual glitch
   OTH	anything else

6. Describe it in a sentence — “rotated 90° vs original”, “floats above the ground”, “texture is the fence instead of bark” — and hit OK. (Cancel or Esc discards.)
7. A tag appears top-right. Reports stack up as you play and survive switching levels. Hover a tag’s ✕ to re-read its note, click to delete. Press B again to return to normal play.
8. When you’re done, hit export at the top of the tag stack — it copies the full report (a readable table plus machine-readable data) to your clipboard.

This is genuinely the highest-value thing a newcomer can do. Two of the project’s worst rendering bugs — a rotation sign error and a back-face culling default — were caught by someone playing and noticing that a sign read backwards.

Want to see where your report ends up? The QA ticket resolution log shows how community tickets get diagnosed and fixed — before/after shots and the evidence trail for each root cause.

02 Code

Get a checkout that builds

Unzip it and run:

bash update.sh --clone jn-engine
cd jn-engine
./scripts/bootstrap.sh   # SDL2, GL, zlib, xvfb
make && make check

Or skip the bundle entirely and clone straight from GitHub — the bundle is just a convenient offline copy of the docs plus a bootstrap script.

Re-run ./scripts/update.sh from inside the checkout any time. It pulls, then re-verifies everything downstream: assets present, your game-file copies still matching their checksums, and the spec gate. It refuses to touch a dirty tree, and on a feature branch it tells you what’s upstream rather than merging behind your back.

What you get, and what you supply

The repository already contains the level data and every derived catalog — 8,116 asset files. You do not need the game to build, run, or work on most tasks.

python3 tools/extract_game_exes.py --source <install dir | disc | .iso>

It takes an installed game directory (no dependencies), a mounted disc, or a .iso — it walks ISO 9660 itself to pull the installer archive out without mounting anything. On Windows, drag a folder or .iso onto tools\extract-game-files.cmd. Full detail in docs/GAME_FILES.md.

Working on asset formats?

Two things worth knowing about before you start. The parsers in tools/contrib_awefan/ are the authoritative reading of the OMT formats — improve them upstream rather than reimplementing. And there’s a headless extraction library and CLI for the game’s asset formats at the OMT asset toolkit (access-gated to current collaborators — ask in the Discord).

Pick something

docs/audit/TASKS.md in your checkout, or read it in the bundle. Every task names the files, how to verify, and what “done” means. A few to start with:

How work gets accepted

Four gates, and they’re the part of this project that demonstrably works. Nothing here is bureaucracy — each one exists because something got through without it.

• Linkage certificates. A class reaches linked only when a headless oracle proves the ported behaviour matches the recovered decompiled body. No green oracle, no linked. linked-blocked is a first-class, respectable outcome. A review pass once mutation-tested every certified oracle and all eight went red under a native-side perturbation — that’s why they’re worth trusting.
• Determinism and goldens. Byte-identical output across runs. Regenerate deliberately, never to make a diff go away.
• The faithfulness sweep. Every past QA root cause becomes a permanent assertion across all 35 levels.
• The spec check. New, and the audit’s own recommendation. tools/audit/spec_check.py compares all 208 class specs against three independent generated sources and fails on any disagreement not in the recorded baseline. Fixing a spec means deleting its baseline entry — that’s how a fix gets locked in.

03 Agents

Point Claude or ChatGPT at the repository

A bounded MCP surface exposing a reviewed, commit-pinned snapshot — search and fetch source, look up recovered symbols, claim a task, open a pull request. No shell, no git, no host access.

Nine tools: search, fetch, list_tasks, project_context, claim_task, release_task, lookup_symbol, check_status, open_pr. Search IDs include the active commit and expire on snapshot refresh, so a client can’t silently mix content from two revisions.

Setup, the tool surface, the write guards, and what the service records: the MCP guide →

04 Landing it

Submitting your work

1. Branch from master. Run make check before you push — that’s the same gate CI runs.
2. Open a PR against alexscott2718-gif/jn-engine. Say which task you’re closing, and how you verified it.
3. If you changed a spec, delete its entry from docs/audit/spec_check_baseline.json in the same PR.
4. If something turned out to be unresolvable, say so and add it to the ground-truth queue. That’s a complete contribution, not a failed one.

Questions, claims on tasks, and bug-report pastes all go to the Discord. If you’re not in it, ask scotty.

05 Credit

Who built what

awefan4524 is the project’s main contributor and triager, and maintains the Hot Wheels: Mechanix and Operation Krabby Patty efforts. The 3DSP parsers covering v0–v5 with endianness auto-detect and extra-pass-set support, the bidirectional Canvas RLE, and the independent decoder that settled the 32-bit canvas byte order and the 8-bit palette layout are theirs — that last one caught this project having both wrong. Those parsers are vendored here with credit, and improvements that generalise should go upstream to their repos, not just here.

Everyone who has ever pasted a bug report from the QA mode is in the fix queue’s history. The rotation-sign bug and the culling default both came from someone noticing a sign read backwards.