Skip to main content

​
Syntax

mod-tools runoverlay <overlay_dir> <config_file> [--game:<path>] [--opts:<opt1>/<opt2>/...]

​
Arguments

​
overlay_dir
string
required
Overlay directory produced by the mkoverlay command.
​
config_file
string
required
Config file consumed by the patcher (e.g., .ini file).

​
Flags

​
--game
string
Optional path to the game folder if required by the patcher context.
​
--opts
string
Slash-separated runtime options passed through to the patcher. Known values include:
  • none - No special options
  • configless - Run without config validation
Other options may be supported by the patcher.

​
Behavior

The runoverlay command performs live patching with the following characteristics:

​
Status Output

Prints real-time status to stdout:
  • Status: ... - Current patcher state
  • Config: ... - Configuration info
  • [DLL] ... - DLL injection messages

​
Exit Control

  • While patching or awaiting save: Exit is locked
  • When idle: Press Enter to exit the process cleanly

​
Patcher Lifecycle

  1. Loads overlay from <overlay_dir>
  2. Reads configuration from <config_file>
  3. Begins live patching process
  4. Streams status updates
  5. Waits for user input to exit when idle

​
Examples

​
Run overlay with configless mode

mod-tools runoverlay ./Overlay ./overlay.ini --game:/games/LoL --opts:configless
This command:
  • Loads overlay from ./Overlay
  • Uses overlay.ini configuration
  • References game at /games/LoL
  • Runs in configless mode (skips config validation)
  • Streams status to terminal

​
Run overlay with default options

mod-tools runoverlay ./Overlay ./config.ini --game:/games/LoL
This command:
  • Loads overlay with standard config validation
  • Uses default patcher options
  • Displays live patching status

​
Run overlay without game path

mod-tools runoverlay ./Overlay ./overlay.ini --opts:none
This command:
  • Runs overlay without explicit game path
  • Uses none option (no special runtime options)
  • Suitable for portable configurations

​
Status Messages

Typical status progression: 
Status: Initializing patcher
Config: Loading overlay.ini
Status: Injecting DLL
[DLL] Injection successful
Status: Patching game files
Status: Idle - Press Enter to exit

​
Use Cases

  • Live testing: Test overlay changes in real-time without game restart
  • Development: Rapidly iterate on mod development
  • Debugging: Monitor patcher status and DLL injection
  • Custom configs: Test different patcher configurations
  • Automation: Integrate with scripts for automated testing

​
Exit Behavior

​
Safe Exit States

You can exit by pressing Enter when:
  • Patcher shows “Idle” status
  • No active patching operations
  • No pending save operations

​
Locked Exit States

Exit is prevented when:
  • Active patching in progress
  • Awaiting file save operations
  • DLL injection in progress
Always wait for the idle state before exiting to avoid corrupting game files or leaving orphaned processes.

​
Troubleshooting

​
Patcher Won’t Start

  • Verify <overlay_dir> was created by mkoverlay
  • Check <config_file> exists and is valid INI format
  • Ensure game path is correct if using --game

​
DLL Injection Fails

  • Run with administrator/elevated privileges
  • Check antivirus isn’t blocking injection
  • Verify game process is running

​
Can’t Exit

  • Wait for idle status
  • Check terminal for status messages
  • Don’t force-kill unless absolutely necessary

Build docs developers (and LLMs) love

Get started for freeTalk to us