Skip to main content
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us