psxrecomp/docs/RUNTIME_FLAGS.csv

1	type	flag_or_field	default	description
2	CLI	--bios <path>	(compile-time default)	Override the BIOS ROM path (SCPH1001.BIN). CLI wins over game.toml and settings.toml.
3	CLI	--game <toml>	(auto-detect)	Load a game config TOML (single source of truth for disc / memcard / title / debug port). Relative paths resolve against exe dir.
4	CLI	--disc <path>	(from game.toml)	Override the game config disc path (CUE/BIN).
5	CLI	--debug-port <n>	4370	Override the TCP debug-server port (multi-instance soak fleet). Wins over game.toml.
6	CLI	--renderer <name>	software	Override renderer: software | opengl | vulkan.
7	CLI	--window-title <str>	(from game.toml)	Override SDL window title (fleet labeling).
8	CLI	--launcher	off	Force the GUI launcher on (overrides skip_launcher in settings.toml).
9	CLI	--no-launcher	off	Skip the GUI launcher (boot straight in). Same as PSX_NO_LAUNCHER=1.
10	CLI	--headless	off	Skip SDL window + audio; TCP screenshots/state only. Same as PSX_HEADLESS=1.
11	CLI	<positional>	(none)	Deprecated alias for --bios.
12	ENV	PSX_BIOS_HLE	from game.toml	Enable HLE BIOS tier (1=on	0=off). When on: instant boot-skip	kernel services computed in-runtime. 0 for pure LLE.
13	ENV	PSX_BIOS_HLE_KEEP_INTRO	0	When HLE BIOS is on	keep the intro boot animation (don't skip to game).
14	ENV	PSX_HLE_SCHEDULER	1	Enable deterministic HLE TCB scheduler (1=on	0=off). Works under both BIOS backends.
15	ENV	PSX_HEADLESS	0	Boot without SDL window/audio (1=on). Use TCP for all I/O.
16	ENV	PSX_NO_LAUNCHER	0	Skip the GUI launcher window (1=on). Boots straight into game.
17	ENV	PSX_DEV_INPUT	0	Merge all controllers to P1 for debugging (1=on).
18	ENV	PSX_EXIT_HALT	0	Halt-and-serve on PC=0 exit (1=on). Keeps TCP server alive after game ends.
19	ENV	PSX_FAIL_FAST_UNKNOWN_DISPATCH	1	Abort on unknown dispatch target (1=on). 0 = log and continue.
20	ENV	PSX_FAIL_FAST_UNIMPLEMENTED	1	Abort on unimplemented opcode (1=on). 0 = log and continue.
21	ENV	PSX_FAIL_FAST_UNSUPPORTED	1	Abort on unsupported instruction (1=on). 0 = log and continue.
22	ENV	PSX_FORCE_INTERP	0	Route ALL RAM through dirty-RAM interpreter (1=on). Debug: disables compiled native code entirely.
23	ENV	PSX_SHELLWIN_INTERP	0	Route BIOS shell window [0x30000	0x5AFFF] through dirty-RAM interpreter (1=on).
24	ENV	PSX_MMIO_WAIT	1	Enable device-region read-cycle waits (1=on). 0 = no waits (fast but breaks timing).
25	ENV	PSX_POLL_PROOF	0	Extra cycle cost for low-RAM reads (0=off	>0=cycles added). Timing correction factor.
26	ENV	PSX_LOAD_DELAY	1	Enable R3000A load-delay interlock timing (1=on	0=off). 0 = no load-delay modeling.
27	ENV	PSX_ICACHE	1	Enable I-cache simulation (1=on	0=off).
28	ENV	PSX_IDLE_SKIP	0	Skip pacing in idle loops (1=on). Runs at host speed during BIOS idle polling.
29	ENV	PSX_RECURSION_LIMIT	256	Max dispatch recursion depth before abort.
30	ENV	PSX_MIXED_OWNER	1	Enable mixed-mode stack watermark (1=on	0=off). Controls compiled↔interp transitions.
31	ENV	PSX_MIXED_STACK_KB	700	Mixed-mode stack overflow threshold in KB.
32	ENV	PSX_STARVATION_TIMEOUT_US	4000000	Watchdog timeout in microseconds (default 4s). Aborts if emulation stalls.
33	ENV	PSX_RECORD_FRAME	(none)	Arm the frame-gated ordered access recorder from boot for guest frame N.
34	ENV	PSX_READ_WATCH	lo,hi	Arm a targeted main-RAM read watch range for the recorded frame.
35	ENV	PSX_STACK_GUARD_KB	(default)	Stack guard size in KB for overflow detection.
36	ENV	PSX_PRECISE_SLICE	0	Precise-cycle slicing mode (0=off	1=on). Breaks large blocks at device deadlines.
37	ENV	PSX_PRECISE_ALWAYS	0	Always use precise-cycle mode (0=off	1=on).
38	ENV	PSX_PRECISE_MARGIN	500	Margin in cycles for precise-slice deadline detection.
39	ENV	PSX_DIRTY_ENTRY_POLL	0	Dirty-RAM entry poll interval.
40	ENV	PSX_DEFER_SWITCH	1	Defer mode switch on exception (1=on	0=off).
41	ENV	PSX_EXC_CLEAR_RESUME_LATCH	0	Clear resume latch on exception.
42	ENV	PSX_SAME_THREAD_RESTORE	0	Restore on same thread (0=default).
43	ENV	PSX_COSIM_PORT	4600	TCP port for cycle-lockstep cosimulation oracle.
44	ENV	PSX_COSIM_STRIDE	(default)	Cosimulation stride (cycles between checks).
45	ENV	PSX_COSIM_START_CYCLE	0	Cycle number to start cosimulation.
46	ENV	PSX_PARITY_TRACE	0	Enable control-flow parity trace (compiled vs interp dispatch parity	1=on).
47	ENV	PSX_PARITY_WATCH	lo,hi	Address range for parity watch (hex).
48	ENV	PSX_DEVTRACE	0	Enable device event ring (1=on). Records I_STAT source events with cycle timestamps.
49	ENV	PSX_FNTRACE_ALL	0	Enable function trace for ALL dispatches (1=on). Heavy overhead.
50	ENV	PSX_OVERLAY_BACKEND	auto	Overlay tier selection: auto | gcc | tcc | auto-no-gcc | sljit(deprecated).
51	ENV	PSX_OVERLAY_NATIVE_BLOCK	addr,...	Per-game overlay addresses to block from native compilation (hex	comma-separated).
52	ENV	PSX_OVERLAY_NATIVE_OFF	0	Force overlay native compilation OFF (1=on). Routes everything through interpreter.
53	ENV	PSX_OVERLAY_DIFF	0	Enable overlay shadow diff (track native vs interpreter divergence	1=on).
54	ENV	PSX_OVERLAY_IRQ_SUPPRESS	0	Suppress IRQ delivery during overlay native execution (1=on). For timing isolation.
55	ENV	PSX_OVERLAY_IRQ_RATELIMIT	0	IRQ rate-limit during overlay native execution (finer than full suppress).
56	ENV	PSX_OVERLAY_IRQ_BUDGET	(default)	IRQ budget during overlay native execution.
57	ENV	PSX_OVERLAY_IRQ_NO_CDROM	0	Exclude CDROM IRQs from overlay IRQ suppression.
58	ENV	PSX_OVERLAY_IRQ_DEFER_CDROM	0	Defer CDROM IRQs during overlay native execution.
59	ENV	PSX_OVERLAY_IRQ_POST_PUMP	(default)	Post-IRQ pump cycles during overlay native execution.
60	ENV	PSX_OVERLAY_UNIT_DEFER	0	Defer overlay unit loading.
61	ENV	PSX_SLJIT_ENABLE	0	Enable SLJIT JIT tier for overlays.
62	ENV	PSX_SLJIT_SYNC	0	Force synchronous SLJIT compilation (disable async).
63	ENV	PSX_SLJIT_LIVE	0	Enable SLJIT live compilation mode.
64	ENV	PSX_NO_SLJIT	0	Disable SLJIT entirely.
65	ENV	PSX_WS_FORCE_2D	0	Force widescreen 2D mode (1=on). For testing pure-2D games.
66	ENV	PSX_SCREEN	(default)	Override CRT filter / screen kind (raw|crt|composite|trinitron).
67	ENV	PSX_AUDIO_SHADOW	0	Enable SPU float-shadow re-render (1=on). Catmull-Rom resample	verified-enhancement.
68	ENV	PSX_CD_TRAP_CMD	(none)	Trap specific CDROM command (hex byte). Pauses when matching command is issued.
69	ENV	PSX_CD_TRAP_NTH	1	Stop on the Nth matching CDTRAP command (default 1st).
70	ENV	PSX_CD_DMA_TRACE	0	Enable CD DMA trace logging (1=on).
71	ENV	PSX_XLATE_LE	0	Little-endian text translation mode.
72	ENV	PSX_XLATE_ALLOW_NUL	0	Allow NUL bytes in text translation capture.
73	ENV	PSX_XLATE_CAPTURE	0	Enable text translation capture mode.
74	ENV	PSX_LOW_LATENCY_INPUT	1	Re-sample pad after wall-clock pacer (1=on). Reduces input→photon latency.
75	ENV	PSX_VSYNC	1	Present/swap mode: 1=on (tear-free)	0=immediate (may tear)	-1=adaptive.
76	ENV	PSX_XPROBE_FRAME_TRIP	(default)	Cross-probe frame trip threshold.
77	ENV	PSX_XPROBE_STK_KB	(default)	Cross-probe stack KB threshold.
78	ENV	PSX_XPROBE_WARMUP	(default)	Cross-probe warmup frames.
79	ENV	PSX_RECORD_FRAME	(default)	Arm frame-gated ordered-access recorder from boot for frame N.
80	ENV	PSX_READ_WATCH	lo,hi	Arm targeted main-RAM read watch for recorded frame.
81	game.toml	[game].exe_path	(required)	Path to PS-X EXE file.
82	game.toml	[game].load_address	0x80010000	EXE load address in guest RAM.
83	game.toml	[game].entry_pc	(required)	EXE entry PC address.
84	game.toml	[game].text_size	(required)	EXE text segment size in bytes.
85	game.toml	[game].stack_base	(none)	Initial $sp value.
86	game.toml	[game].disc	...	Disc path (CUE). Single disc or first of [[game.discs]].
87	game.toml	[[game.discs]]	(none)	Array of disc paths for multi-disc games.
88	game.toml	[game].disc_crc	(none)	Expected CRC32 of data track (for launcher badge).
89	game.toml	[game].disc_sha1	(none)	Expected SHA-1 of data track (hex).
90	game.toml	[runtime].debug_port	(none)	TCP debug-server port for this game.
91	game.toml	[runtime].language	en	Default localization language code.
92	game.toml	[[runtime].languages]	(none)	Launcher language menu options [{code	label}].
93	game.toml	[runtime].window_title	(none)	Default SDL window title.
94	game.toml	[runtime].memcard_dir	(none)	Memory card directory path.
95	game.toml	[runtime].fast_boot	0	DEPRECATED → alias for HLE boot shell-skip.
96	game.toml	[runtime].bios_hle	1	Enable HLE BIOS tier (1=on	0=off for pure LLE).
97	game.toml	[runtime].bios_hle_keep_intro	0	Keep intro animation when HLE BIOS is on.
98	game.toml	[runtime].hle_scheduler	1	Enable deterministic HLE TCB scheduler (1=on).
99	game.toml	[runtime].overlay_cache	0	Enable overlay DLL cache + capture (1=on).
100	game.toml	[runtime].turbo_loads	0	OPT-IN: run unpaced during CD load screens (1=on).
101	game.toml	[runtime].overlay_autocompile_cmd	(none)	Shell command for auto-overlay compilation.
102	game.toml	[runtime].overlay_autocompile_cmd_tcc	(none)	Same as above but using bundled TinyCC.
103	game.toml	[runtime].overlay_backend	auto	Overlay compiler backend: auto | gcc | tcc | auto-no-gcc.
104	game.toml	[[runtime].overlay_native_block]	[]	Overlay function addresses to force through interpreter.
105	game.toml	[video].supersampling	1	Internal-resolution SSAA factor (1= native	2..4 = scaled).
106	game.toml	[video].antialiasing	1	Linear-filter upscale (1=smooth	0=sharp pixels).
107	game.toml	[video].low_latency_input	1	Re-sample pad before present (1=on).
108	game.toml	[video].vsync	1	Present mode: 1=on	0=immediate	-1=adaptive.
109	game.toml	[video].auto_skip_fmv	0	Skip FMVs instantly when detected (1=on).
110	game.toml	[video].fmv_skip_total_table	0	Address of per-movie total-frame table (for game-native FMV skip).
111	game.toml	[video].fmv_skip_movie_id	0	Address of current movie-id byte.
112	game.toml	[video].fmv_skip_end_total	3	Offset subtracted from total to trigger skip.
113	game.toml	[video].fmv_skip_no_xa	0	Broaden FMV detection to MDEC-only (no XA required).
114	game.toml	[audio].spu_hq	0	Enable SPU float-shadow re-render (Catmull-Rom	1=on).
115	game.toml	[controller].allow_hybrid	1	Show Hybrid option in launcher pad-mode selector.
116	game.toml	[controller].lock_mode	0	Hide pad-mode selector (force default_mode for all ports).
117	game.toml	[controller].lock_device	0	Hide controller device picker entirely.
118	game.toml	[controller].deadzone	12000	Default analog-stick deadzone (raw SDL axis units	0..32767).
119	game.toml	[controller].legacy_pad_config	0	Legacy pad protocol (pre-DualShock config SM). Only Tomba opts in.
120	settings.toml	[video].renderer	(from game.toml)	Override renderer: 0=software	1=opengl.
121	settings.toml	[video].supersampling	(from game.toml)	Override SSAA factor (1..4).
122	settings.toml	[video].window_width	1280	Window width in pixels (height = width*3/4).
123	settings.toml	[video].antialiasing	(from game.toml)	Override AA toggle.
124	settings.toml	[video].texture_filter	(from game.toml)	Override texture filtering: 0=nearest	1=bilinear.
125	settings.toml	[video].screen_kind	(from game.toml)	Override CRT filter.
126	settings.toml	[video].auto_skip_fmv	(from game.toml)	Override FMV skip toggle.
127	settings.toml	[video].turbo_loads	1	Override turbo-through-loads toggle.
128	settings.toml	[video].fast_boot	0	Override fast boot toggle.
129	settings.toml	[video].bios_hle	(from game.toml)	Override HLE BIOS toggle.
130	settings.toml	[video].fullscreen	0	Launch in desktop fullscreen (1=on). In-game F11/Alt+Enter toggles live.
131	settings.toml	[video].low_latency_input	(from game.toml)	Override low-latency input toggle.
132	settings.toml	[video].vsync	(from game.toml)	Override vsync mode.
133	settings.toml	[launcher].skip_launcher	0	Boot straight in	skip GUI launcher (1=on).
134	settings.toml	[launcher].ui_scale	1.0	Launcher UI scale (0.5 .. 2.0).
135	settings.toml	[audio].spu_hq	(from game.toml)	Override SPU HQ toggle.
136	settings.toml	[bios].path	(from game.toml)	Override BIOS ROM path.
137	settings.toml	[disc].path	(from game.toml)	Override disc path.
138	settings.toml	[memcard].dir	(from game.toml)	Override memory card directory.
139	settings.toml	[memcard].card1_path	(auto)	Override slot-1 card file path.
140	settings.toml	[memcard].card2_path	(auto)	Override slot-2 card file path.
141	settings.toml	[memcard].card1_enabled	1	Enable memory card slot 1.
142	settings.toml	[memcard].card2_enabled	1	Enable memory card slot 2.
143	settings.toml	[controller].p2_device	none	Player 2 input device.
144	settings.toml	[controller].p1_mode	hybrid	Player 1 pad mode: hybrid | analog | digital.
145	settings.toml	[controller].p2_mode	hybrid	Player 2 pad mode.
146	settings.toml	[controller].deadzone	(from game.toml)	Override analog-stick deadzone.
147	settings.toml	[localization].language	en	Override localization language.