Command-Line Arguments

Complete reference for Xenia command-line flags and options

Xenia supports numerous command-line arguments for controlling emulator behavior, debugging, and advanced configuration.

Basic Usage

xenia [options] <game_path>

Where <game_path> can be:

• Path to an .xex executable
• Path to an .iso disc image
• Path to a game directory

General Options

--config · string · default: ""

Specify a custom configuration file path. Can be absolute or relative.

xenia --config=custom.toml game.xex

--headless · boolean · default: "false"

Run without displaying any UI, using defaults for all prompts. Useful for automated testing and benchmarking.

xenia --headless game.xex

GPU Options

Rendering

--vsync · boolean · default: "true"

Enable or disable vertical synchronization. Disabling allows the emulator to run as fast as possible.

xenia --vsync=false game.xex

--framerate_limit · uint64 · default: "60"

Set maximum frames per second. Use 0 for unlimited.

xenia --framerate_limit=120 game.xex

--gpu_allow_invalid_fetch_constants · boolean · default: "true"

Allow texture and vertex fetch constants with invalid types. May help with some games but is generally unsafe.

xenia --gpu_allow_invalid_fetch_constants=false game.xex

--half_pixel_offset · boolean · default: "true"

Enable vertex half-pixel offset support (D3D9 behavior).

xenia --half_pixel_offset=false game.xex

Debugging and Tracing

--trace_gpu_prefix · path · default: "scratch/gpu/"

Set the prefix path for GPU trace files. Used with F4 key to capture frames.

xenia --trace_gpu_prefix=traces/game1_ game.xex

See the GPU Trace Viewer documentation for more details.

--trace_gpu_stream · boolean · default: "false"

Trace all GPU packets to a file, allowing frame-by-frame seeking in the trace viewer. Warning: creates large files.

xenia --trace_gpu_stream game.xex

--dump_shaders · path · default: ""

Dump all compiled GPU shaders to the specified path for debugging. Shaders are named by their input hash.

xenia --dump_shaders=shaders/output/ game.xex

Advanced GPU Settings

--non_seamless_cube_map · boolean · default: "true"

Disable filtering between cube map faces (requires VK_EXT_non_seamless_cube_map on Vulkan).

--query_occlusion_sample_lower_threshold · int32 · default: "80"

Lower threshold for occlusion query sample counts. Set to -1 to disable.

--query_occlusion_sample_upper_threshold · int32 · default: "100"

Upper threshold for occlusion query sample counts.

CPU Options

--cpu · string · default: "any"

Select CPU backend. Options: any, x64. Currently has no practical effect.

--pvr · uint64 · default: "0x710700"

Set the Processor Version Register value. Different Xbox 360 models used different values:

• 0x710200 - Zephyr
• 0x710300 - Zephyr
• 0x710500 - Jasper
• 0x710700 - Default
• 0x710800 - Corona V1 & V2

xenia --pvr=0x710500 game.xex

Debugging

--load_module_map · path · default: ""

Load a .map file for symbol names and comparison with the generated symbol database.

xenia --load_module_map=game.map game.xex

--disassemble_functions · boolean · default: "false"

Disassemble functions during JIT compilation. Useful for debugging recompiler issues.

xenia --disassemble_functions game.xex

--trace_functions · boolean · default: "false"

Enable function execution tracing for statistics collection.

--trace_function_coverage · boolean · default: "false"

Generate tracing for function instruction coverage statistics.

--trace_function_references · boolean · default: "false"

Generate tracing for function address references.

--trace_function_data · boolean · default: "false"

Generate tracing for function result data.

--validate_hir · boolean · default: "false"

Perform validation checks on the HIR (High-level Intermediate Representation) during compilation.

Breakpoints

--break_on_instruction · uint64 · default: "0"

Trigger a debugger breakpoint (int3) before executing the specified guest address.

xenia --break_on_instruction=0x82000000 game.xex

--break_condition_gpr · int32 · default: "-1"

GPR (General Purpose Register) to compare for conditional breakpoints.

--break_condition_value · uint64 · default: "0"

Value to compare against for conditional breakpoints.

--break_condition_op · string · default: "eq"

Comparison operator for conditional breakpoints (e.g., eq, ne, gt, lt).

--break_condition_truncate · boolean · default: "true"

Truncate comparison value to 32 bits for conditional breakpoints.

--break_on_debugbreak · boolean · default: "true"

Trigger int3 on JITed __debugbreak requests from game code.

APU Options

--mute · boolean · default: "false"

Mute all audio output from the emulator.

xenia --mute game.xex

HID Options

--guide_button · boolean · default: "true"

Forward Xbox Guide button presses to the game. Set to false to prevent games from receiving guide button input.

xenia --guide_button=false game.xex

Kernel Options

--log_high_frequency_kernel_calls · boolean · default: "false"

Enable logging of high-frequency kernel calls. Warning: generates massive log files.

xenia --log_high_frequency_kernel_calls game.xex

Usage Examples

Performance Testing

Run a game at maximum speed without vsync:

xenia --vsync=false --framerate_limit=0 game.xex

Debug Session

Capture GPU traces and dump shaders while running:

xenia --trace_gpu_prefix=traces/game1_ --dump_shaders=shaders/ game.xex

During gameplay, press F4 to capture the current frame.

Compatibility Testing

Test with a specific PVR value and no audio:

xenia --pvr=0x710500 --mute game.xex

Automated Testing

Run headless with custom config:

xenia --headless --config=test.toml game.xex

Function Analysis

Trace function execution with disassembly:

xenia --trace_functions --disassemble_functions --load_module_map=symbols.map game.xex

Combining with Config Files

Command-line arguments override config file settings. This is useful for:

• Quick testing without modifying config files
• Scripted testing with different parameters
• Per-session overrides for specific debugging scenarios

Example workflow:

# Normal config has vsync enabled
# Temporarily disable for benchmark
xenia --vsync=false --framerate_limit=0 game.xex

# Config settings remain unchanged for next run
xenia game.xex

Boolean Flag Syntax

Boolean flags support multiple syntaxes:

# All equivalent ways to enable
--vsync=true
--vsync

# All equivalent ways to disable  
--vsync=false
--no-vsync
--novsync

Tips

Use --trace_gpu_prefix with descriptive names when capturing multiple games:

xenia --trace_gpu_prefix=traces/halo3_ halo3.xex
xenia --trace_gpu_prefix=traces/gears_ gears.xex

Enabling --trace_gpu_stream can create multi-gigabyte files. Ensure you have adequate disk space before using this option.

Command-line arguments take precedence over both global and game-specific config files, making them ideal for testing without permanent configuration changes.