mirror of
https://github.com/jkdansereau/goldeneye-pc-port.git
synced 2026-10-23 15:52:42 +02:00
Dan Turner
498be832c2
- tools_pc/bundle-mac.sh: a signed, double-clickable GoldenEye.app. Homebrew's libstdc++/libgcc_s and SDL2 are not system libraries, so they are bundled and rewritten to @executable_path/@loader_path. Note sdl2-compat (Homebrew's `sdl2`) finds its SDL3 backend through a RELATIVE rpath baked into the dylib, so SDL3 ships too and that rpath is repointed — copy it without that and sdl2-compat raises a modal error dialog from its initialiser and the app hangs before main(). prepare-assets/ goes in Contents/Resources/: codesign treats a directory under Contents/MacOS/ as nested code and fails the bundle. - tools_pc/level_sweep_mac.sh: per-level crash-log sweep, symbolicated with atos, with a rendered-pixel check so "runs but renders nothing" is caught. - D299: sndPlaySfx() rejected EVERY sound on arm64 — all in-level SFX were silent, while music played (separate player). Its guard predated the shifted window: `sp >= 0x400000000ULL` (16 GiB) is correct on x86_64 (DRAM at 0x70000000) and rejects everything on arm64 (DRAM at ~0x1000_707b_5740). Fixed with a portAddrIsInWindow() helper rather than absolute bounds. - D300: cleanupObjects() did `u32 *obj = (u32)g_CurrentSetup.propDefs`, truncating a host pointer to 32 bits. Crashed at stage unload — only reachable once a level actually ends. Verified: 21/21 on both the no-input and full-control sweeps; SFX voices allocate on every level.
tools_pc/ — PC-port dev & test scripts
Index for the ~60 scripts here (speed-ups plan Step 4 / N2). None of these are part of the build; they are converters, verification tooling, and investigation artifacts.
Marker:
living— kept and re-run; part of the verification ritual, the release flow, or a converter the build depends on (via the sidecars it emits).artifact— added to chase one finding. Safe to move totools_pc/archive/<dxx>/once that finding is closed and the technique is captured indocs/dev/findings.md/docs/porting-notes.md.
Living — converters the sidecars depend on
| Script | Role |
|---|---|
d43_emit.py |
Offline N64→PC model-file converter → RZ sidecar + manifest.csv (D50 / Plan B). Regen after any model-format change. |
d43_convert.py |
Reference single-file model converter + full-512 layout/pointer validator (D43). |
d69_emit.py |
Offline converter for stage bg/*.seg + Tbg_*_stanZ → concatenated sidecar (D69/D78–D82). |
d88_emit.py |
Offline converter for per-level Usetup*Z stage-setup files → appended to the pccg.bin sidecar (D88). |
d88_propdefs.py |
The propDefs polymorphic-record stream N64→PC converter used by d88_emit.py (D88.4). |
d69_emit.py / d88_emit.py / d43_emit.py |
Run all three (+ d88_propdefs) to rebuild data/ sidecars from the ROM. |
Living — verification & release
| Script | Role |
|---|---|
verify.sh |
Speed-ups plan Step 2. One command → one verdict: build-if-stale, headless GE_PCDUMP/GE_INPUTSCRIPT capture, crash-detect + symbolication (via crash_brief.py), pixcount, framediff vs golden, --json. verify.sh <level>, verify.sh sweep [subset], verify.sh parity <level> --against <dir>. |
crash_brief.py |
Speed-ups plan Step 9 / R5. ge007.crash.log → symbolicated frames + a dev-process.md-shaped dispatch-ready brief: matches porting-notes.md sections / findings-index.csv entries by resolved function/file, flags known parked-crash signatures (Cuba credits, D188 va_list, D189 stack overrun) so agents stop re-investigating them. Called automatically by verify.sh on CRASH; also runnable standalone. |
framediff.py |
Visual regression: candidate GE_PCDUMP frames vs tools_pc/golden/, per-region divergence. Structural/tolerant by default; --exact after GE_DETERM. |
pixcount.py |
Count non-black pixels in a PPM dump — "did the scene render anything" as a number. |
level_sweep.sh |
Bare -level_XX boot of all 21 solo levels → PASS / NO-FRAMES / CRASH. Predates verify.sh sweep; kept as the battle-tested full-21-level runner until verify.sh sweep has done an equivalent soak. |
playtest.sh |
Launch a level for docs/dev/LEVEL-PLAYTEST.md human validation (WS6). |
audiodebug.ps1 |
Audio counterpart to debug.ps1 (that one is for crashes; this one is for audio behaviour). Drives the GE_D204 health monitor + GE_AUDIOTRACE/GE_AUDIODUMP and prints a pass/fail verdict: real-time ratio, queue starvation, dropped blocks, oversized blocks, plus a soundIndex histogram. -AB runs the same binary twice (with and without GE_D204_OLD) and prints a before/after table — how D204 was measured. -Play for an instrumented interactive playtest (the D202 workflow), -Soak for a 5-min stability run, -SyncData to mirror ./data first. |
debug.ps1 / repro_gdb.sh / attach_animgen.sh |
Launch (or attach to) the game under gdb so a crash always leaves a backtrace. |
bundle-win.sh / bundle-linux.sh / bundle-mac.sh |
Package a built tree as a distributable archive (exe + licenses + prepare-assets/). bundle-mac.sh produces a signed, double-clickable dist/GoldenEye.app with SDL2 + libstdc++/libgcc_s bundled (Homebrew libs are not system libs) and prepare-assets/ in Contents/Resources/ — it cannot go in Contents/MacOS/, where codesign treats the directory as nested code and fails the bundle. |
level_sweep_mac.sh |
macOS/arm64 sweep: bare -level_XX boot of all 21 solo levels, crash-log detection (symbolicated via atos), and a GE_PCDUMP frame that must be non-near-black (PIX_MIN, default 2%), so "runs but renders nothing" is caught too. SWEEP_SECS (default 18). |
romverify.c |
One-shot .z64 integrity check against the repo's ground truths. |
dump_objectives.py |
Dump per-level objectives + win/fail criteria from the ROM (playtest validation; Step 10 / N8 acceptance oracle). |
disasm.py |
Minimal MIPS disassembler for the BE ROM (RAM-addr → file offset). |
ppm2bmp.py |
PPM → 24-bit BMP, no deps — eyeball GE_PCDUMP frames without PIL. |
gen_findings_index.py |
Regenerate docs/dev/findings-index.csv (grep-before-you-read aid for the 200 KB finding log). --check in CI-style use. |
gen_env_probes.py |
Drift check for docs/dev/GE-ENV-PROBES.md — re-greps live getenv("GE_*") sites, reports NEW/GONE. |
Living — compiler-verified layout probes (kept: re-run when structs change)
| Script | Role |
|---|---|
d43_layoutprobe.c |
Prints sizeof/offsetof for every struct d43_emit.py must reproduce, built with the port toolchain. |
d88_layoutprobe.c |
Same, for the PROPDEF_* record structs d88_emit.py converts. |
mtxtest.c |
Standalone numerical test of the fast3d matrix pipeline conventions (GE swapped-perspective, packing, MUL order). |
Investigation artifacts — D43 model-file format (finding closed; archive candidates)
d43_chainbound.py, d43_cover.py, d43_decode.py, d43_fullwalk.py,
d43_gdldump.py, d43_gdlhist.py, d43_gdlorder.py, d43_gdlseq.py,
d43_invariants.py, d43_layout.py, d43_layout1.py, d43_lutscan.py,
d43_pointusage.py, d43_seg5.py, d43_seg5ops.py, d43_seg5vtx.py,
d43_seg5vtx2.py, d43_sizes.py, d43_sizes2.py, d43_tree_dump.py,
d43_vtxfmt.py, d43_walk.py — layout/pointer/GDL-order analysis passes that
derived the D43 converter spec. d43_sizes.py is still exec()'d by a couple
of the others.
Investigation artifacts — other closed/parked findings
| Script | Finding |
|---|---|
d125_check.py |
D125 — is the emitted propDefs blob byte-identical to d88_propdefs.convert_stream()? |
d88_propdef_scan.py |
D88.4 — histogram of PROPDEF_* record types across shipped levels. |
d51_gdb.py / dump_animgen.cmd |
D51 texture-tile crash capture / Facility-outro-hang anim-state dump (gdb scripts). |
Other
dist/— staged bundle README template (README.md.in) + tokens.golden/— per-level golden frames forframediff.py(Step 3 fills this out).__pycache__/— ignored.