This guide explains how the JSON file fits together. Start with the quick start if you only need a working five-client example.
A configuration has four core parts:
regions named rectangles on one or more displays
main_region the region treated as the primary gameplay area
instances programs to launch and their initial regions
keymaps keys and the actions they execute
Optional top-level sections control the application window, logging, capture compositor, registry cleanup, and virtual-mouse injection.
A region is a named pixel rectangle. display is a zero-based monitor index written as a string. Region coordinates are relative to that monitor.
{
"name": "client2",
"display": "0",
"region": {
"x": 2880,
"y": 0,
"width": 960,
"height": 540
}
}
If display is omitted, blank, or cannot be resolved, the application falls back to the first monitor. Width and height should be positive even though region dimensions are not rejected by the configuration validator itself.
Region names are compared without regard to uppercase and lowercase. Use unique, descriptive names anyway.
main_region must name an existing region. Exactly one configured instance must initially own it.
"main_region": "main"
Swapping can later move another client into this region. When the capture compositor is disabled, non-main clients may be parked off-screen as part of the main-region arrangement.
Every instance launches one executable:
{
"name": "game1",
"executable": "C:\\Games\\MyGame\\1\\Game.exe",
"working_directory": "C:\\Games\\MyGame\\1",
"title": "My Game 1",
"region": "main",
"modifier": "LAlt",
"keymap_on_select": "select_game1"
}
Only name, executable, and region are normally needed. Each instance must own a different initial region. If working_directory is omitted, the executable's directory is used. If title is omitted, the instance name becomes the window title after the window is found.
modifier is used only by actions with add_instance_modifier: true. keymap_on_select is advanced: it runs a named keymap when the instance becomes the foreground managed window, including selection through a region click or taskbar.
A keymap consists of trigger keys and one or more action steps:
{
"name": "combat_keys",
"enabled": true,
"keys": ["1", "2", "3"],
"execute_on": "press",
"actions": [
[
{ "action": "forward" }
]
]
}
actions is deliberately nested. The outer array contains steps. Each inner array contains actions that run together for that step.
The following sends different keys to different clients from one trigger:
"actions": [
[
{ "action": "forward", "send_key": "1", "targets": ["self"] },
{ "action": "forward", "send_key": "2", "targets": ["all_other"] }
]
]
Actions in the same inner array run in order during the same step.
Each activation advances to the next outer-array step:
{
"name": "formation",
"keys": ["F1"],
"actions": [
[
{ "action": "forward", "send_key": "1" }
],
[
{ "action": "forward", "send_key": "2" }
]
],
"reset_to_first_action": 3.0
}
After three seconds without advancing, the next activation starts at the first step again. The value is a number of seconds and may contain a decimal.
Forwarding and round-robin actions accept:
Target Meaning
----------- --------------------------------------------------
all Every active managed instance.
all_other Every active instance except the routing context.
self Only the routing-context instance.
game3 The explicitly named instance game3.
Omitting targets means all active managed instances. Several selectors and names can be combined; duplicates are ignored.
The routing context is normally the focused managed client. During some activation and click flows, the application keeps the relevant managed instance as context even while focus changes.
Use send_key to replace the trigger key:
{
"action": "forward",
"send_key": "Ctrl+2",
"targets": ["all_other"]
}
A combo has zero or more modifiers followed by exactly one ordinary key. Only modifiers may precede the final key.
sync_mouse: true copies the mouse position once immediately before an action is dispatched:
{ "action": "forward", "sync_mouse": true }
This differs from mouse_broadcast, which enables or disables continuous mouse movement and button broadcasting.
Give each instance a modifier:
"modifier": "LAlt"
Then request it in an action:
{
"action": "forward",
"targets": ["all_other"],
"add_instance_modifier": true
}
The modifier associated with the routing-context instance is added to the dispatched key. Supported modifier tokens are Ctrl, LCtrl, RCtrl, Alt, LAlt, RAlt, Shift, LShift, and RShift.
Only named keymaps can be controlled as groups:
{
"keys": ["Ctrl+B"],
"actions": [
[
{ "action": "toggle_keymaps", "keymaps": ["number_keys"] }
]
]
}
Use enable_keymaps, disable_keymaps, or toggle_keymaps. Every referenced name must exist. enabled: false makes a named keymap start disabled.
An advanced mapping can move an instance to another region:
{
"name": "show_game2",
"keys": ["NumPad2"],
"execute_on": "release",
"actions": [
[
{
"action": "swap_instance_to_region",
"source_instance": "game2",
"target_region": "main"
}
]
]
}
Both references must exist. Swapping changes positions without resizing the window during the swap operation.
The optional ui section positions the Multiboxer control window and its buttons. An action button invokes a named keymap; it does not simulate the keymap's trigger key.
"ui": {
"window": { "x": 100, "y": 100, "width": 640, "height": 400 },
"buttons": [
{
"id": "mouse",
"role": "action",
"text": "Mouse",
"x": 56,
"y": 8,
"width": 100,
"height": 40,
"keymap": "mouse_broadcast"
}
]
}
If there is no button with role config, the application adds one at the top left. Clicking it opens the active JSON file in Notepad.
Use keys and actions for recipes and accepted key names. Use the complete reference when you need exact defaults and validation rules.