CONFIG_FILE.md

{
  bin: string,
  cwd?: string,
  args?: string,
  env?: object,
  priority?: string,
  hide?: bool,
  shell?: bool,
  wait?: bool,
  script?: {
    path: string,
    fs?: bool,
    net?: bool,
    reg?: bool,
    exec?: bool,
    import?: bool
  },
  addons?: []{
    path: string, 
    required?: bool
  },
  suspended?: bool,
  affinity?: []number,
  integrity?: []{
    sri: string, 
    path?: string, 
    size?: number,
    signed?: bool
  },
  splash?: {
    show: bool,
    image: []string,
    timeout?: number,
    wait?: string
  },
  symlink?: []{
    path: string,
    dest: string
  },
  shortcut?: {
    name: string,
    desktop?: bool,
    startmenu?: bool
  },
  compatibility?: {
    version?: string,
    fullscreen?: bool,
    admin?: bool,
    invoker?: bool,
    aware?: bool
  },
  patch?: {
    laa?: bool
  },
  prefix?: {
    winver?: string,
    dpi?: number,
    overrides?: object
  },
  attrib?: []{
    path: string,
    hidden?: boolean,
    readonly?: boolean
  },
  menu?: object
}

bin: string

File path to the executable to launch.
Path can be absolute or relative (to the current working dir).

%VAR% are expanded if any (see Expanding Variable for more details).

cwd?: string (parent directory)

An option to override the current working dir of the executable to be launched.
This is equivalent to the "Start In" option of a Windows shortcut.

By default the parent directory of the executable is used.
Example: G:\METAPHOR\METAPHOR.exe => G:\METAPHOR\

args?: string (none)

Optional argument(s) to pass to the executable.
Argument(s) are passed "verbatim" ie: no quoting or escaping is done.

%VAR% are expanded if any (see Expanding Variable for more details).

env?: object (none)

Add additional environment key-value pairs to the executable process.

Example:

{
  "env": {
    "GAMEPAD_LED": "BATTERYLVL"
  }
}

%VAR% in value are expanded if any (see Expanding Variable for more details).

priority?: string (none)

Set the executable process priority class:

• IDLE: Threads run only when the system is idle.
• BELOW_NORMAL: Above IDLE but below NORMAL.
• NORMAL: This is the default.
• ABOVE_NORMAL: Above NORMAL but below HIGH.
• HIGH: Performs time-critical tasks that must be executed immediately.
• REALTIME: Highest possible priority, higher than operating system processes performing important tasks.

hide?: bool (false)

When enabled, the executable will run without displaying a window, making it invisible to the user.

shell?: bool (false)

When enabled runs inside of a shell (%COMSPEC% ie cmd.exe).
💡 Use the hide option above to hide the shell.

wait?: bool (false)

When enabled, will wait for the executable to terminate before exiting.

⚠️ The command line flag --wait always enables this behavior.

local process = require("process")
process.On("will-quit", function()
  print("Bye bye!")
  -- do some cleanup for example
  -- like idk deleting logs generated by mods 🙃
end)

script?: { path: string, fs, net, reg, exec, import?: bool } (none)

Lua script to be run just before the executable.
See the ./example directory for some examples.

Originally this feature was for handling CD Key generation in old games.
The Lua API has since become quite extensive, so please kindly see the Lua Scripting section for more details.

• path: string

  Script file path can be absolute or relative (to the current working dir).
  %VAR% are expanded if any (see Expanding Variable for more details).

• fs, net, reg, exec, import ?: bool (false)

  These flags act as a simple permissions system:

  • fs: Filesystem operation
  • net: Network request
  • reg: Windows registry
  • exec: Shell command
  • import: Load external Lua code (via require, loadfile, loadstring, ...)

  You must explicitly grant access to these resources.

addons?: []{ path: string, required?: boolean } (none)

DLL Injection / ASI plugin loading

List of addons to inject to the executable process.
Supported file extension:

• .dll (Dynamic link library)
• .asi (Commonly used in game modding; technically it's a .dll file with a different extension).

When required is set to true and the injection failed: alert the user and kill the process.

Path can be absolute or relative (to the current working dir).
%VAR% are expanded if any (see Expanding Variable for more details).

Example:

{
  "addons": [
    { "path": "Launcher/opencnconline.dll", "required": true }
  ]
}

suspended?: bool (false)

When enabled, the main thread of the executable process is created in a suspended state and does not run until resumed.

The main thread will be automatically resumed after the process affinity and addons injection steps.

affinity?: []number (none)

Set the CPU affinity (pin to specific cores).
CPU indices are logical cores, exactly as shown in Windows' Task Manager.

Examples:

Pinning to the first core

{
  "affinity": [0]
}

Pinning to the 3rd and 4th cores

{
  "affinity": [2, 3]
}

Process affinity is set before any addons injection occurs to ensure that all threads are pinned to the specified logical cores.

When should I use this?

Some games behave better when restricted to specific CPU cores:

• Old games not designed for multi-core CPUs (ex: extreme gameplay speed on multi-core CPUs).
• Games that stutter or misbehave on modern systems.

⚠️ Most games do not need this option, use it only when required.

integrity?: []{sri: string, path?: string, size?: number, signed?: bool} (none)

Check file(s) integrity before starting the executable.

• sri: string is a Subresource Integrity, algo supported are sha256, sha384, sha512.

• path?: string (executable path) File path, can be absolute or relative (to the current working dir). If no path is specified then the sri targets the executable path.
  %VAR% are expanded if any (see Expanding Variable for more details).

• size?: number optional file size (in bytes), to accelerate sum comparison.

• signed?: bool (false) When true, will check if the file is signed and trusted.

splash?: { show: bool, image: []string, timeout?: number } (none)

Display a splash screen until the executable process change the cursor or display a window. The splash screen should be a BMP file.

• show: bool (false) Wether to display the splash screen or not.

• image: []string Splash screen filepath. When more than one, a splash screen is selected at random.
  File path can be absolute or relative (to the current working dir).
  %VAR% are expanded if any (see Expanding Variable for more details).

• timeout?: number (10 sec) Failsafe timeout in seconds.
  There was no event dispatched under Linux/Proton on Wayland in my limited testing.

• wait?: string ("FOREGROUND") Which window event to wait for (case insensitive):

  • FOREGROUND: The foreground window has changed and is visible.
  • WINDOW: An hidden window is shown.
  • CURSOR: An hidden cursor is shown.

symlink?: []{path: string, dest: string} (none)

Creates folder symlink before starting the executable.
Path can be absolute or relative (to the current working dir).
%VAR% are expanded if any (see Expanding Variable for more details).

💡 Useful for savegames:

{
  "symlink": [
    { 
      "path": "%DOCUMENTS%/Telltale Games/The Walking Dead",
      "dest": "%SAVEGAME%/The Walking Dead"
    }
  ]
}

shortcut?: { name: string, desktop?: bool, startmenu?: bool} (none)

Creates desktop / start menu shortcut(s) on launch.

compatibility?: object (none)

Set Program Compatibility Assistant (PCA) flags, this is equivalent to the right click > Properties > Compatibility tab on Windows.

PCA flag(s) are set in HKCU/Software/Microsoft/Windows NT/CurrentVersion/AppCompatFlags/Layers.

🐧 This has no effect on application behavior under Wine/Proton

• version?: string Run the executable in compatibility mode for:

  • WIN95
  • WIN98
  • WIN2000
  • WINXP
  • WINXPSP1
  • WINXPSP2
  • WINXPSP3
  • VISTARTM
  • VISTASP1
  • VISTASP2
  • WIN7RTM
  • WIN8RTM

• fullscreen?: bool Disable fullscreen optimizations.

• admin?: bool Run the executable as an Administrator.

• invoker?: bool Enforce running the executable as the invoker.

• aware?: bool Override high DPI scaling behavior (Application).

NB: admin and invoker are mutually exclusive. If both are set admin supersede invoker.

patch?: object (none)

Patch(es) to apply to the executable.

Does nothing by default; You must explicitly set a patch to true or false.

• laa?: bool:
  Large Adress Aware
  Allow x86 binary to access up to 4GB of virtual memory (instead of only 2) on x64 Windows.
  This option set (true) or unset (false) the LAA flag bit in the PE Header.
  

NB: Patching is done prior to any integrity check because it directly modifies the executable.

prefix?: {winver?: string, dpi?: number, overrides?: object} (none)

🐧 Linux Wine/Proton only.

Update current prefix settings.

• winver?: string Windows version. Accepted values are:

  • win11
  • win10
  • win81
  • win8
  • win7
  • vista
  • winxp

• dpi?: number Scale factor: 96 (100%), 120 (125%), 144 (150%), 192 (200%) to 480 (500%).

• overrides?: object key-value pairs of dll overrrides. Accepted values:

  • native,builtin
  • builtin,native
  • native
  • builtin

Example:

{
  "prefix": {
    "winver": "win10",
    "dpi": 96,
    "overrides": {
      "winmm": "native,builtin"
    }
  }
}

attrib?: []{path: string, hidden?: boolean = false, readonly?: boolean = false} (none)

Set file(s) attributes: read only and/or hidden.

Path can be absolute or relative (to the current working dir).
%VAR% are expanded if any (see Expanding Variable for more details).

💡NB: This is done before running any Lua Script. If you are dynamically creating/modifying file(s), consider the Lua API: file.SetAttributes() (see below).

menu?: object (none)

Show a very simple button menu where each key/value pair is a button label and its corresponding override config file.

Example:

{
  "menu": {
    "Mass Effect": "me.json",
    "Mass Effect 2": "me2.json",
    "Mass Effect 3": "me3.json"
  }
}

Path can be absolute or relative (to the current working dir). %VAR% in the path are expanded if any (see Expanding Variable for more details).

💡 You can point an entry to the default config file. If empty, the default is assumed ie: the value of --config string which defaults to launcher.json

Example:

{
  "binary": "bin/bg3_dx11.exe"
  "menu": {
    "Baldurs Gate 3": "",
    "Baldurs Gate 3 (Vulkan)": "vulkan.json"
  }
}