mirror of https://github.com/RetroPortingToolKit/psxrecomp synced 2026-10-26 02:11:36 -04:00

Files

T

Matthew Stanley e6ce5006b4 docs: move root and stale docs into docs/ and docs/internal/

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>

2026-09-03 07:39:07 -07:00

5.0 KiB

Raw Permalink Blame History

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):

Boot to gameplay through the title's existing verify flow on this branch.
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.
Eyeball lit and fogged/depth-cued scenes side-by-side with the Beetle oracle; the oracle is ground truth, not the pre-fix recomp.

5.0 KiB Raw Permalink Blame History Unescape Escape

GTE lm/sf fix in the depth-cue & lighting family