The controller map had no l3/r3 rows at all, so pad bits 1/2 could never
be produced by a gamepad — DualShock-only games (Ape Escape) were
unplayable. Keyboard slots existed but shipped unbound.
- main.cpp: PAD_L3/PAD_R3 bits; controller_map 14->16 entries; defaults
l3=leftstick, r3=rightstick; input.ini template + doc comment updated.
- psx_keybinds.c: keyboard defaults L3=T, R3=Y (continue the Q/W/E/R
shoulder row). Launcher Controls page picks them up automatically.
- beetle_main.cpp: same T/Y keys on the oracle so psx-beetle stays
drivable for L3/R3 games.
- tools/package_release.ps1: shipped input.ini template gains l3/r3.
- README: keyboard + controller map tables.
Wire is unchanged: sio.c transmits the button word verbatim, matching
Beetle's dualshock.cpp. Validated in-game on Ape Escape (user-confirmed
R3/L3 inputs on a real pad).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Fold the best of a generic CONTRIBUTING draft into the architecture-aware
one: AI-assisted-and-human contribution rules, a concrete cross-game
regression checklist (boot/attract/save/load/gameplay), an expanded
no-copyrighted-assets list, and bug-report/PR templates tuned to this
project's execution paths (LLE / HLE / dirty-RAM interp; SW/GL/VK).
Add a "Framework changes and the pin" section describing how a framework
fix reaches a game through its submodule pointer (source of truth; some
older repos still carry psxrecomp-v4.pin as a human-readable record), and
whether consuming it needs a pin bump / regen.
Add a dedicated Contributing section to the README linking CONTRIBUTING.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Make the repo approachable for outside contributors and an IDE integrator:
- New contributor docs:
- docs/EXECUTION_MODEL.md — semi-technical tour of the static / native-overlay
/ interpreter execution model and how coverage gaps get plugged.
- docs/ARCHITECTURE.md — component-level view (recompiler, runtime, LLE+HLE
BIOS, overlay backend static->gcc->tcc, renderers, oracle model).
- docs/BUILDING.md — accurate dependency table, per-platform prereqs, build
steps, and the submodule + local-junction framework-linking setup.
- CONTRIBUTING.md — distilled core rules, verification expectations, PR flow.
- Declutter root: move ~14 internal dev-logs into docs/internal/ (history
preserved via rename) with an index README; repoint CLAUDE.md references.
- README: correct build recipe, LLE+HLE + overlay-backend summary, links to the
new docs.
- code_provider.c: update the stale backend comment to the real static->gcc->tcc
resolution (dead SLJIT.md reference removed).
- config_schema.md: drop the obsolete "once Phase A2/A3 ships --config" note.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Games live in their own repositories in this project (TombaRecomp,
MegaManX6Recomp, ...); the framework holds only the shared recompiler +
runtime, never a game's config/assets. A contributor PR landed Kula World
(SCES-01000) game files directly in the framework, which is inconsistent
with that layout — that content belongs in the contributor's own game
repo. Remove it:
- games/kula/{game.toml,seeds.txt}
- docs/kula-world-findings.md, docs/{MACOS,WINDOWS}_BUILD_KULA.md
- docs/assets/kula-world-*.png
- README "This fork — Kula World" + macOS branding sections
- runtime/CMakeLists.txt kula-runtime target
The general framework improvements those commits also carried are KEPT
(they benefit every game): KUSEG-addressed PS-X EXE header acceptance,
dirty-RAM interpreter interrupt-poll-at-entry, main-RAM 4x mirror /
GetID-from-serial / CD-status / CD-version fixes, and the Linux/macOS
POSIX ports. Source comments citing Kula as the motivating case are left
in place as provenance.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Replace absolute F:/C: paths with repo-relative (../TombaRecomp, bios/, beetle-psx/)
or placeholders (<desktop>/<psxref>/<nesrecomp>/<psxrecomp-v4>) across accuracy docs,
WIDESCREEN/SHADOW/RECURSION_BUG/config_schema/ISSUES/README, and tools/*.py|.ps1.
Removed a personal C:\Users\Matthew\Desktop path (ISSUES.md). Left CLAUDE.md/PLAN.md
sibling-project + version-history paths intact (intentional layout documentation).
The Windows->Linux POSIX port left the recompiler and runtime almost
portable; two small platform gaps remained on macOS (AppleClang, arm64),
both guarded so Windows/Linux are unaffected:
- runtime/src/autocompile.c: add #include <stdlib.h> for getenv. glibc and
windows.h leak that declaration transitively; the macOS SDK does not, so
AppleClang errored on the implicit declaration.
- recompiler/src/main_bios.cpp: the C-compiler probe used ">NUL" (Windows
null device). On POSIX that misdirects the redirect and drops a stray
"NUL" file in the cwd; now #ifdef'd to /dev/null.
The ucontext fiber backend already carried the _XOPEN_SOURCE/_DARWIN_C_SOURCE
guards it needs; SDL2 (Homebrew) selects the Metal backend automatically.
Verified end to end on macOS 15.5 / Apple Silicon: BIOS -> KULA WORLD title
-> menu -> 1 Player -> a 3D level that rolls under control.
Adds docs/MACOS_BUILD_KULA.md and a macOS gameplay screenshot; README notes
the port. Ignores the local dist/ .app bundle (recompiled-BIOS derivative).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Adds this fork's Kula World (SCES-01000) end-to-end target to the README with
a title-screen screenshot and a summary of the five runtime bugs fixed during
bring-up (four of them game-agnostic framework improvements): the dirty-RAM
interpreter interrupt-latency fix, the main-RAM mirror, GetID region
derivation, CD status bits, and the SCPH-1001 CD controller version.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BdjxoRB1f9VQsNzZayCgGS
Add MegaManX6Recomp alongside TombaRecomp in the framework intro, and
correct the status note: neither game is fully validated end to end yet
(Tomba has more coverage; MMX6 is playable).
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The cache file contains verbatim copyrighted game code read from the user's
disc, so the README no longer asks players to attach it to GitHub issues.
Discoveries persist locally (cache rebuilt from the file automatically); a
metadata-only contribution format is planned. Also clarifies the
distribution model (statically recompiled builds, no BIOS/disc/assets).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Layman explanation of overlays (streamed code chunks we can only convert
once someone visits the area), the automatic play-to-discover/cache loop
(step 2.8), and how to share overlay_captures.json so discoveries become
permanent for everyone in the next release.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds a Philosophy section near the top: the goal is native execution (no
interpreter on the hot path, no HLE), overlays are the frontier, and the project
is an alpha/beta where a MAJORITY of a supported game runs statically recompiled
but not yet 100%. Documents how gaps are closed (static-first; capture -> compile
-> cache for overlays; interpreter failover only for not-yet-static code;
precision-over-recall so under-coverage self-heals and mis-compiles can't
corrupt) and the honest bounds.
Explicitly notates the known corner case: genuinely self-modifying / per-load-
relocated code is not static by definition, REMAINS INTERPRETED (a correct,
accepted outcome — only speed is lost), and may someday be covered (detect-and-
bake relocation, or load-time compilation) but with no promise. Aspiration is
100% static coverage with the interpreter idle.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
The recompiler and runtime now build and run natively on macOS (Apple
Silicon & Intel) and Linux, alongside Windows. The recompiled BIOS boots to
the PlayStation logo, and Tomba boots into gameplay with working memory-card
save/load — the previously Windows-only path.
Core change — the BIOS thread scheduler:
- runtime/src/psx_fiber.{h,c} (new): one cooperative-fiber API, backed by
Win32 Fibers on Windows and ucontext (makecontext/swapcontext) on POSIX,
with a GetCurrentFiber analog (psx_fiber_current).
- traps.c: the BIOS thread switcher now uses psx_fiber_* on every platform.
The old non-Windows setjmp/longjmp fallback is removed — it ran target
threads nested on the caller's C stack and so couldn't resume an arbitrary
suspended thread, which hung the BIOS CD-boot WaitEvent handoff. Real
per-thread stacks (fibers/ucontext) fix it.
- interrupts.c: the exception-deferral path (g_exception_owner_fiber,
deferred_exception_longjmp) is now fiber-based on all platforms via the
same abstraction, instead of #ifdef _WIN32.
Cross-platform build fixes:
- recompiler/CMakeLists.txt: vendored fmt 9.1.0 force-enables consteval on
Apple clang (the __cpp_consteval clause overrides its own Apple exclusion),
which clang 21 then rejects; force FMT_CONSTEVAL empty on non-MSVC.
- runtime.cmake: add psx_fiber.c; add pkg-config's SDL2_LIBRARY_DIRS so
-lSDL2 resolves outside default paths (Homebrew /opt/homebrew/lib).
- crash_trace.c: include <stdarg.h> (not pulled in transitively off Windows).
- main.cpp: the forced "opengl" render-driver hint (a Windows-GDI-freeze
workaround) is now Windows-only so macOS uses Metal; create the renderer
with PRESENTVSYNC; SDL_RenderSetLogicalSize(640,480) so fullscreen
letterboxes; add an F11 / Alt+Enter / Cmd+F fullscreen toggle.
Verified: SCPH1001 BIOS boots to the Sony logo on Apple Silicon, and Tomba!
(SCUS-94236) boots into gameplay with memory-card saves persisting across
relaunches. Gamepad (SDL_GameController) was already cross-platform.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Tight-crop (1031x315) so the header isn't dominated by empty grey
above/below the logo.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Config loader (recompiler/src/config_loader.{h,cpp}): single source of
truth for both BIOS and game runtime settings (debug_port, window_title,
memcard_dir, disc path). psxrecomp-bios and psxrecomp-game both accept
--config <toml>; runtime takes --game <toml> (no more CLI overrides).
- runtime/src/main.cpp: replaced --disc/--memcard-dir/--game-root CLI
overrides with --game <toml>; game.toml is the single source of truth.
Discless launch (no args) goes to BIOS shell.
- runtime/src/dma.c: fixed update_master_irq() re-asserting I_STAT bit 3
on every DICR read. BIOS shell DMA handler at 0x80058628 only clears
DICR bit 27 (ch3 flag), so level-sensitive re-assert pinned the kernel
in the exception loop. Bit 3 is now edge-triggered (one assert per DMA
completion). Discless boot now reaches MAIN MENU / MEMORY CARD / CD
PLAYER. With-disc Tomba boots through to Whoopee Camp splash.
- Audit tooling: codegen_audit.py (BIOS), codegen_audit_game.py (game),
audit_config.py (config loader for tools), verify_audit_schema.py.
Replaces older tools/_codegen_audit.py probe.
- Docs: CURRENT_STATE.md (project state), UNIFICATION_PLAN.md (Phase C
translator merge plan), docs/config_schema.md (TOML schema reference),
docs/audit_inventory.md (audit tier inventory).
- .gitignore: tools/_*.py convention for ad-hoc scratch probes.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Replaces the Phase-1-internal milestone notes with a user-facing README
suitable for the GitHub repo's new role: in-place v2 of mstan/psxrecomp.
Calls out explicitly:
- CD-ROM / disc-based game loading is untested and likely non-functional
in psx-runtime today. BIOS-only memcard management is the supported
use case.
- MDEC video decode is slow / partial.
- SPU/GPU/GTE coverage is partial.
Includes setup (release binary path + build-from-source path), keyboard
map, memcard-management walkthrough, and v1 reference (legacy-2026-05-11
branch).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Matthew Stanley