mirror of
https://github.com/RetroPortingToolKit/psxrecomp
synced 2026-10-28 10:59:16 -04:00
Matthew Stanley
e6ce5006b4
The repository root carried seven markdown files that were not onboarding
material, plus two that had been superseded by the code they described. This
sorts them: reader-facing docs to docs/, working notes to docs/internal/, and
the two superseded ones merged into the docs that replaced them.
Moved to docs/: WIDESCREEN.md, ENHANCEMENTS.md, TCP_COMMANDS.md
Moved to docs/internal/: PRINCIPLES.md, ISSUES.md, DEBUG.md, GTE_LM_FIX.md,
and from docs/: bios-hardening.md, overlay-status.md,
overlay-plan.md, overlay-recompilation-design.md,
overlay-discovery.md, TOMBA2_EXC_CONSULT_RESPONSE.md,
CASE_A_AOT_GAP.md, audit_inventory.md
Moved to docs/internal/upstream/: UPSTREAM_2026-08-20.md
The root keeps only what belongs there: README.md, CONTRIBUTING.md, LICENSE,
CLAUDE.md, THIRD_PARTY_ATTRIBUTION.md, RELEASE_NOTES.md, the dotfiles and
psxrecomp_cli.py.
MERGES
SPLITGEN_MIGRATION.md folded into docs/BUILDING.md as "Split generated C". Its
migration instructions were stale in a way that mattered: it told every game
repo to hand-edit its CMakeLists and add a file(GLOB ...) over
<serial>_full*.c, but runtime/runtime.cmake now does that itself. GEN_FULL_GLOB
is a multi-value argument of psxrecomp_add_game_runtime(); the loop at
runtime.cmake:1985 makes each pattern absolute against CMAKE_CURRENT_SOURCE_DIR,
expands it with file(GLOB), and concatenates the hits into
GAME_GENERATED_FULL_C. So a title names the pattern and gets however many shards
a regeneration produced. The rewritten section describes that, the two-step
fallback when the globs match nothing (GEN_FULL_FALLBACK, else <serial>_full.c
derived from the dispatch marker by substituting _dispatch.c), and the one
caveat the code actually has: that file(GLOB) is plain, not CONFIGURE_DEPENDS,
so a regeneration which changes the shard COUNT needs a re-configure to be seen.
psxrecomp-toml-readme.md folded into docs/GAME_PROJECT_SETUP.md as "EXE-only
autofill (psxrecomp-toml)", placed after "Disc autofill (probe_disc.py)" and
before "Project Studio" so the two autofill paths sit together. Its documented
flags were checked against the usage text in recompiler/src/main_toml.cpp:28-42
and against the argument parser at :150-165 -- all seven options match with no
drift, so the flag list is reproduced as-is. Added a pointer that probe_disc.py
is preferable when a cue exists, since that tool does the same EXE-header work
plus disc identity and netplay gates.
FUNCTIONAL FIXES
tools/gen_tcp_commands.py wrote to REPO/"TCP_COMMANDS.md". After the move that
path does not exist, so the generator would have created a new stray root file
and --check would have failed against it forever. Retargeted to
REPO/"docs"/"TCP_COMMANDS.md", along with the seven docstring and message
strings that name the path.
Running it surfaced two further problems, both fixed here:
* The doc was genuinely stale -- pre-existing drift, not introduced by this
commit (the moved file is byte-identical to origin/master, and no
debug-server command table is touched here). Four commands registered since
the last regeneration were missing from the index -- cdrom_timing_dump,
savestate_status, ws_ui_groups, xprobe_watch -- and scanline had gained a
backend. Regenerated: 307 -> 311 commands, and the change is confined to the
AUTOGEN block (the hand-written head and tail are byte-identical to master).
tools/gen_tcp_commands.py --check now exits 0.
* DOC.write_text() has no newline argument, so Python translated every newline
to os.linesep. On Windows that rewrote all 585 lines of the file to CRLF and
turned a four-line index update into a whole-file diff -- measured: 589 CRLF
/ 0 LF after a run, against 0 CRLF / 585 LF in the repo. Now written through
an explicit newline="" handle, verified to leave the file at 0 CRLF.
runtime/include/debug_server.h:9 and runtime/src/debug_server.c:8 cited "TCP.md
and DEBUG.md". TCP.md has never existed in this repo under that name; both now
name docs/TCP_COMMANDS.md and docs/internal/DEBUG.md.
LINK AND REFERENCE FIXES
Every inbound reference to a moved file was located by grepping each basename
across the whole tracked tree, not just the markdown. Markdown hrefs in
README.md, CONTRIBUTING.md, docs/ARCHITECTURE.md, docs/COMPILING_OVERLAYS.md,
docs/AOT_OVERLAY_PLAN.md, docs/RELOCATION_MANIFEST_FORMAT.md,
docs/config_schema.md, docs/OVERLAY_XREF.md, docs/TCP_COMMANDS.md and several
docs/internal/ files now point at the new locations; where two files became
siblings under docs/internal/ the path was shortened rather than lengthened
(bios-hardening.md's reference to overlay-discovery.md, for instance).
docs/COMPILING_OVERLAYS.md's "in this folder" phrasing was wrong once two of the
three files it listed moved, so it now names internal/ explicitly.
24 source-comment mentions of ENHANCEMENTS.md sections G1.x across 19 files
(recompiler, runtime, cmake) were retargeted to docs/ENHANCEMENTS.md with the
section numbers untouched. docs/SHADOW_ENHANCEMENTS.md is a DIFFERENT file and
was deliberately excluded.
20 rationale strings citing docs/CASE_A_AOT_GAP.md across the four
recompiler/seeds/*.json files were updated. Done as a byte-level substring
replacement rather than a JSON round-trip: two of those files are stored with
CRLF endings and two with LF, and re-serializing them reformatted 5,700 lines.
The byte-level version changes exactly 20 lines and each file still parses.
References that look similar but point elsewhere were deliberately left alone,
and are worth naming so a future pass does not "fix" them:
* "recomp-template PRINCIPLES.md" / "NES recomp template PRINCIPLES.md" in
CLAUDE.md:43, docs/SHADOW_ENHANCEMENTS.md:28,
docs/internal/HLE_SCHEDULER_CARVEOUT_PLAN.md:5,
runtime/src/debug_server.c:4934 and tools/parity_diff.py:8 are a different
repository's file. Only the five that mean this repo's PRINCIPLES.md were
updated.
* Every remaining bare ISSUES.md mention is a GAME repo's tracker
(MegaManX6Recomp 2/7/8/9, TombaRecomp 6), not this repo's.
* docs/disc-speed.md:4,54,56 and docs/internal/bios-hardening.md:5 name
overlay-discovery as a BRANCH, not a file, so no path applies.
INDEXES
README.md's "New here?" table gains rows for docs/WIDESCREEN.md,
docs/ENHANCEMENTS.md and docs/TCP_COMMANDS.md. docs/internal/README.md gains
sections indexing all fourteen documents that moved in, plus an "Upstream
contributor reviews" section describing upstream/ and the new sweep file, plus a
"Removed" bullet for CYCLE_TIMING_ARCH.md (deleted in the previous commit)
pointing at FAITHFUL_TIMING_PLAN.md, CYCLE_MODEL_BEETLE.md and
PRECISE_IRQ_SLICE.md -- following the SLJIT_PERSIST_CACHE.md precedent already
in that file.
docs/ENHANCEMENTS.md:7 claimed framework bugs live in "game repos' ISSUES.md
until a framework tracker exists". A framework tracker does exist; it now says
so and names the Beads epic.
VERIFICATION
A link checker was written to scan every tracked *.md for relative links,
resolving each against the tree being scanned. Baseline at origin/master: 129
files, 137 relative links, 3 broken. After both commits: 127 files, 159 relative
links, 3 broken -- the SAME three, all pre-existing and untouched here:
docs/DATA_SHARDS.md -> INSTANT_LOADS_PARKED.md (never existed)
docs/DATA_SHARDS.md -> INSTANT_LOADS_SPIKE2.md (never existed)
docs/NETPLAY.md -> ../lib/recomp-net/README.md (inside a submodule)
Zero new broken links. The checker's own coverage was checked against a raw grep
for markdown link openers: the 3-link difference is C++ lambdas inside code
blocks, correctly not treated as links.
Also verified: py_compile over all 113 tracked tools/*.py plus psxrecomp_cli.py;
all four seed JSONs still parse; the test-registration guard still reports 123
test files all registered; recompiler/tests/test_coverage_vault.py still passes;
and no file in this commit had its line endings flipped (checked mechanically
across all 50 modified files, after two files were caught and redone).
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
107 lines
5.0 KiB
Markdown
107 lines
5.0 KiB
Markdown
# GTE `lm`/`sf` fix in the depth-cue & lighting family
|
||
|
||
**Branch:** `feat/crashbash-fw-fixes` — commit `c4474b9`
|
||
**Fixes:** Crash Bash (SCUS-94570) menu-character 30 Hz strobe + in-game
|
||
character flattening. Root-caused and verified 2026-07-09.
|
||
|
||
## What was wrong
|
||
|
||
The runtime GTE hardcoded `lm = 1` (clamp IR results to `[0, 0x7FFF]`) on
|
||
every IR write-back in the shared lighting/depth-cue helpers
|
||
(`light_transform`, `light_color`, `color_output`, `depth_cue_from_ir`).
|
||
Real hardware takes `lm` from **bit 10 of the instruction word** — `lm = 0`
|
||
clamps to `[-0x8000, 0x7FFF]` and preserves negative results.
|
||
|
||
`depth_cue_from_ir` also ignored `sf` (bit 19) and skipped the hardware's
|
||
intermediate step clamp.
|
||
|
||
Affected ops: `INTPL`, `DPCS`, `DPCT`, `DPCL`, `NCDS`, `NCDT`, `NCS`, `NCT`,
|
||
`NCCS`, `NCCT`, `CDP`, `CC`. (`RTPS`/`RTPT`/`MVMVA`/`OP`/`SQR`/`GPF`/`GPL`
|
||
already honored the instruction word and are untouched.)
|
||
|
||
## Why it broke Crash Bash
|
||
|
||
Crash Bash tweens its 10 fps keyframe vertex animation to the 30 fps render
|
||
rate through **INTPL with `lm = 0`** — an off-label, signed-vector use of the
|
||
color-interpolation op:
|
||
|
||
- pose-A vertex → IR1–3
|
||
- pose-B vertex → far-color regs (FC) via `ctc2`
|
||
- blend factor → IR0
|
||
- `INTPL` (`0x0980011`) → lerped vertex read back from IR1–3 (`mfc2`)
|
||
|
||
With `lm` forced on, every **negative component** of a tweened vertex clamped
|
||
to 0, collapsing the character mesh onto its anchor point on tween frames.
|
||
Keyframe frames (no INTPL) stayed healthy, so with alternating draw buffers
|
||
exactly one display buffer ever held a healthy pose → the character strobed
|
||
at 30 Hz on menus and rendered flattened/half-visible in-game. Beetle and
|
||
real hardware honor per-instruction `lm`, so they never showed it.
|
||
|
||
## What changed
|
||
|
||
- `light_transform` / `light_color` / `color_output`: `lm` read from the
|
||
instruction word and passed to every `saturate_ir` write-back.
|
||
- `depth_cue_from_ir`: rewritten to the faithful hardware formula —
|
||
`base = IR << 12`; `step = lim±0x8000(((FC << 12) − base) >> sf·12)`
|
||
(intermediate clamp with `lm` forced OFF, per hardware); `MAC = (base +
|
||
IR0·step) >> sf·12`; final `IR = lim(MAC, lm)` with `lm` from the
|
||
instruction. MAC overflow flags checked.
|
||
- Always-on GTE observability rings (build-dbg debug-server commands):
|
||
`gte_ring_dump` (per-RTPS/RTPT inputs+outputs), `gte_intpl_dump`
|
||
(per-INTPL inputs+outputs, frame filter + offset paging),
|
||
`gte_frame_stats` (per-frame `nproj`/`nsat`/`nflat`/`nintpl`/
|
||
`nintpl_tiny`), `gte_latch_dump` (retained saturated projections).
|
||
|
||
## Regression risk
|
||
|
||
Low, and skewed toward correctness:
|
||
|
||
- Standard libgte **lighting** calls encode `lm = 1`, so games using the
|
||
ops as designed see identical clamping to before.
|
||
- The two real behavior changes are (a) `lm = 0` callers now keep negative
|
||
results — the bug being fixed — and (b) the depth-cue step is now clamped
|
||
to ±0x8000 before the IR0 multiply, which only matters when
|
||
`|FC − IR| > 0x7FFF` (far color very distant from the lit color). Both
|
||
changes move us **toward** hardware/Beetle behavior, so the only regression
|
||
class is a game that accidentally depended on our old inaccuracy.
|
||
- `sf` handling: all common libgte encodings of these ops use `sf = 1`,
|
||
which reproduces the old shift exactly.
|
||
|
||
## Cross-game validation — REQUIRED, all titles, before merge
|
||
|
||
This branch does not merge to master until every supported title has been
|
||
validated against this change. No subset, no sampling.
|
||
|
||
**Validated:**
|
||
|
||
**Crash Bash (SCUS-94570)** — the fix target. Menu strobe gone;
|
||
`nintpl_tiny` 335–352/473 → 0–3; character present in both VRAM
|
||
double-buffers and in all frames of a jittered screenshot burst;
|
||
menus/animation healthy.
|
||
|
||
**Ape Escape (SCUS-94423)** — 2026-07-10. Full branch-flavor rebuild
|
||
(BIOS + game regen, `build-crashbash-fw/`). Booted to title; lit title
|
||
models healthy (Ape was the highest-risk title — heavy GTE user, most
|
||
likely to exercise the depth-cue step clamp). User-validated in play.
|
||
|
||
**Tomba 2 (SCUS-94454)** — 2026-07-10. Full branch-flavor rebuild. Attract
|
||
gameplay healthy; `gte_frame_stats` over the attract scene: `nintpl = 0`
|
||
(no INTPL use), steady `nsat`/`nflat`, `nintpl_tiny = 0`. User-validated.
|
||
|
||
**Mega Man X6 (SLUS-01395)** — 2026-07-10. Full branch-flavor rebuild.
|
||
Attract gameplay demo healthy (standard `lm = 1` lighting path).
|
||
|
||
All four titles validated → merged to master `e4145d7` on 2026-07-10.
|
||
Post-merge gate: Tomba rebuilt clean against merged master; Crash Bash
|
||
junction re-pointed to master, regenerated, rebuilt — SELECT GAME TYPE
|
||
character present, `nintpl_tiny = 0` across the sampled frames.
|
||
|
||
**Per-title procedure (same for all):**
|
||
|
||
1. Boot to gameplay through the title's existing verify flow on this branch.
|
||
2. Capture `gte_frame_stats` over a representative scene and diff
|
||
`nsat`/`nflat` against a pre-fix baseline built from master + this
|
||
branch's parent commit — any shift is a stop-and-investigate, not a note.
|
||
3. Eyeball lit and fogged/depth-cued scenes side-by-side with the Beetle
|
||
oracle; the oracle is ground truth, not the pre-fix recomp.
|