Repository Tour

Repository Tour

Maintained docs in the repository are authoritative; this page is a summary. Last reviewed 2026-09-16.

The public tree separates offline translation, native runtime behavior, player UI, reference execution, verification, and project governance.

Area	Purpose	Editing boundary
tools/	ELF/PRX loading, import reconstruction, analysis, code generation, tests, audits, and verification gates.	Human-authored Python and fixtures; add focused tests with behavior changes.
src/core/	Shared native library, manifest-derived title catalog, and launch session services.	Portable C services shared by runtime and player.
src/player/	Native SDL3 desktop player UI, ISO9660 reader, XB extraction, setup staging, and library management.	Clean-room C99 UI layer; compiles via mingw32-make player.
src/rt/	Native runtime, HLE, scheduler, memory helpers, filesystem, media, and renderer backends.	Human-authored C; preserve the shared ABI and fail-closed behavior.
src/ref/	Separate C++ reference interpreter and selftests for differential/local-consistency work.	Verification/reference implementation, not the normal game executable.
fixtures/	Source-owned synthetic and PSPDEV probe inputs that can be redistributed with the public source.	Keep fixtures public-safe; never substitute proprietary title inputs.
assets/vfpu/	Pinned VFPU lookup tables with upstream provenance.	Preserve provenance and notices.
font/	Replacement-font material and its provenance boundary.	Payloads excluded pending review; do not infer redistribution clearance.
interface/	Optional Next.js prototype dashboard.	Separate local-only web tooling; not part of native runtime.
docs/	Maintained setup, architecture, debugging, verification, governance, and provenance records.	Prefer maintained guides over dated investigations.
Makefile, nk_manager.ps1, nk.ps1	Build, doctor, test, and run orchestration.	nk_manager.ps1 and nk.ps1 are canonical; hst_manager.ps1 and hst.ps1 are deprecated wrappers.
build/	Generated local output created by local builds; it is Git-ignored.	Never edit or publish generated output.

Where to start a change

• Translation behavior: tools/codegen.py, tools/analyze.py, tools/imports.py, or tools/prxload.py, plus a focused synthetic regression.
• Native player: src/player/ and src/core/, verified with mingw32-make player and python tools/test_nk_core.py.
• Runtime behavior: the relevant file under src/rt/, its public header, and a production-path or source-owned selftest.
• Verification: the matching gate under tools/, src/ref/, or the renderer/audio selftest route.
• Documentation and governance: the maintained page listed by docs/README.md.

Generated files are outputs, not source ownership boundaries. If a generated artifact disagrees with source, regenerate from a clean/known-complete pipeline and inspect the source/tooling change.