game.toml

[game]
name = "Mega Man X5"
id = "SLUS-01334"
exe = "mmx5/SLUS_013.34"
disc = "mmx5/Mega Man X5 (USA).cue"
load_address = "0x80010000"
entry_pc = "0x8005894C"
text_size = "0x00082000"
stack_base = "0x801FFFF0"

[recompiler]
seeds = "seeds/ghidra_funcs.txt"
out_dir = "generated"
strict = true

[runtime]
debug_port = 4520
window_title = "MegaManX5Recomp"
memcard_dir = "saves"
# Disc speed + fast loads — the architecturally-correct model (see MMX6 game.toml
# for the full rationale). Keep AUTHENTIC guest CD timing (disc_speed="1x") so
# nothing breaks, and get fast loads by fast-forwarding the whole guest timeline
# during loads (turbo_loads). Speeding the guest-visible CD device is unsafe for
# timing-sensitive Psy-Q titles like the Mega Man X engine.
disc_speed   = "1x"     # authentic guest CD timing (never breaks game timing)
turbo_loads  = false    # keep the guest timeline at normal speed by default
# Load acceleration is mod-owned: players use "Fast Loading (host pacing)" /
# "CD Speed" under Mods -> Quality of Life, both default-off. The generic switch
# is retired in the framework, but this title still pins a framework that
# predates that, where offer_turbo_loads IS honoured — without it, a turbo value
# left in a stale settings.toml is restored on every launch and cannot be turned
# off from any UI (the launcher draws no Turbo row). Remove once the pin moves.
offer_turbo_loads = false
# HLE BIOS tier, DEFAULT-ON for X5 (2026-07-02): kernel B0 event family served
# host-side + the boot shell-skip — boots straight past the PSX logo into the
# game (kernel init still runs the real recompiled BIOS; unimplemented services
# fall through to LLE). The launcher's old "Skip PSX BIOS" fast_boot toggle is
# retired; boot behavior is this per-game decision now. Set false (or
# PSX_BIOS_HLE=0) to compare against the authentic LLE boot.
bios_hle = true
# Overlay acceleration: compile the dirty-RAM overlay (ROCK_X5.DAT / ROCK_X5.BIN)
# to native instead of interpreting it. Same pipeline as MMX6: capture overlay
# candidates -> compile_overlays.py spawns the toolchain -> DLLs in
# <exe>/cache/SLUS-01334/ -> loader rescans + loads. Priority: static > gcc shard
# > tcc shard > interp. backend "auto" = gcc if a gcc toolchain is present, else
# the bundled toolchain-free tcc.
overlay_cache = true
overlay_backend = "auto"
# Compile RECIPE only (compiler + tool paths). The WRITE cache + READ captures are
# injected by the runtime (PSX_OVERLAY_CACHE_DIR / PSX_OVERLAY_CAPTURES) so they
# can never drift from the loader's canonical <exe>/cache + <exe>/overlay_captures.json.
overlay_autocompile_cmd = "py -3 psxrecomp-v4/tools/compile_overlays.py --game-toml game.toml --recompiler psxrecomp-v4/recompiler/build/psxrecomp-game.exe --runtime-include psxrecomp-v4/runtime/include --cps"

[video]
# Native presentation. X5 ships 4:3 (authentic). Widescreen is owned by the
# default-off mmx5.enhancement.widescreen package rather than a generic
# launcher setting; its trusted plugin selects 16:9 after the mod plan commits.
aspect_ratio = "4:3"
renderer = "opengl"

# Presentation-only interpolation is likewise owned by the default-off
# mmx5.enhancement.frame-interpolation package. Hide the generic Settings row
# and ignore values persisted by older builds so there is one activation path.
offer_frame_interpolation = false

# auto_skip_fmv: auto-skip full-motion videos (XA audio + MDEC). Off for the
# initial bring-up baseline; enabled during the enhancement-porting phase once the
# X5 MDEC player loop is understood (X5 ships CAPLOGO.STR / X5OP.STR opening movies).
auto_skip_fmv = false

# Experimental 16:9 for the pure-2D sprite engine — same mechanism as MMX6:
# full_2d treats every game frame as gameplay so the native-wide present path
# engages when [video] aspect_ratio is flipped to "16:9" by the launcher's
# Widescreen toggle (settings.toml). Inert at 4:3.
# The background and object-cull hooks below are identity transforms at 4:3,
# so the launcher aspect toggle remains the single opt-in control.
[widescreen]
full_2d = true
offer = false
offer_ultrawide = false
nw_left_hud_packet_lo = "0x000E8500"
nw_left_hud_packet_hi = "0x000E9300"

# True wider FOV for the Capcom 2D background engine. X5 draws 21 tile columns
# into a 32x32 ring. Widescreen prepends/appends four columns, moves the start X
# left by 64 pixels, widens both streamer edges, and refreshes the full widened
# ring window once per frame. The RAM layout values are verified against
# FUN_80028328; see annotations/widescreen_bg2d_sites.md. Regen required.
[widescreen.bg2d]
count_site        = "0x80028218" # sltiu v0,t7,0x15
startcol_site     = "0x80028040" # andi v1,v1,0x1f
startx_site       = "0x80028058" # sra s6,v0,0x10
stream_left_site  = "0x800282B8" # addiu a1,s0,-0x10
stream_right_site = "0x800282CC" # addiu a1,s0,0x150 (320+16)
cap_site          = "0x8002810C" # slti v0,v1,0x3e8
layer_base        = "0x8009A1F8"
ring_base         = "0x800A51A8"
map_size_addr     = "0x800D1DBC"
layer_stride_addr = "0x80091D58"
ring_cols          = 32
layer_count        = 3
layer_struct_stride = 84
packet_cap         = 1024

# Expand both object activation windows and qualified primitive render culls by
# the per-side 16:9 reveal margin. The explicit pairs keep their original
# offscreen lead while making enemies activate before entering either wide edge.
# auto_screen_x covers FUN_80032CEC's four 320x240 quad tests.
[widescreen.cull]
auto_screen_x = true
screen_x_sites = [
  "0x80032D90",
  "0x80032E20",
  "0x80032EB4",
  "0x80032F48",
]
bias_sites = [
  "0x8002D86C",
  "0x8002D908",
  "0x8002DB0C",
]
range_sites = [
  "0x8002D874",
  "0x8002D910",
  "0x8002DB14",
]
a1_sites = [
  "0x8002D948", # FUN_8002D938: move t0,a1
  "0x8002D9F4", # FUN_8002D9EC: move t0,a1
]

# Controller defaults. The Mega Man X engine probes the pad with the DualShock
# config command (0x43) at init; MMX6 will not poll buttons (0x42) until it detects
# an analog-capable pad. Present a DualShock (analog) by default to be safe; revisit
# once X5 input is characterized. The launcher's per-player controller-mode selector
# overrides this (persisted to settings.toml).
[controller]
default_analog = true
deadzone       = 12000
allow_hybrid   = false

# ── Audit-specific config (consumed by psxrecomp tools/*.py and tests) ──
[audit]
# Dynamic discovery — functions are found by walking control flow from entry_pc.

# Code region: text segment is contiguous from load_address for text_size bytes.
[[audit.regions]]
name        = "Text"
rom_start   = "0x800"          # offset within the PS-X EXE file (skip header)
rom_end     = "0x82800"        # rom_start + text_size
vaddr_base  = "0x80010000"

# Address normalization: KSEG masking only (game loads contiguously, no remaps).
[audit.normalize]
kseg_mask = "0x1FFFFFFF"