Running Scripts

🔥 Power User Feature

Running Scripts allow you to execute custom actions while a game is running, triggered by keyboard or controller input. This is similar to LaunchBox's "Running AutoHotkey Script" feature but designed for macOS.

What Are Running Scripts?

Running Scripts monitor for keyboard or controller input while your game is active and execute custom code when specific keys or button combos are pressed. Common uses include:

  • Gracefully exiting stubborn emulators (like ARMSX2 that ignore Cmd+Q)
  • Taking screenshots with custom file naming
  • Pausing/resuming emulation
  • Custom keyboard shortcuts for emulator features
  • Process management (kill scripts, memory cleanup)

Basic Syntax

Running Scripts use a LaunchBox-inspired syntax:

::key {
    your code here
}

Examples

Simple Message Box:

::esc {
    display dialog "ESC pressed!" buttons {"OK"}
}

With Keyboard Modifiers:

::cmd+q {
    display dialog "Quit shortcut pressed!"
}

::shift+f1 {
    -- Quick save
    do shell script "echo 'Saving...' > /tmp/save.log"
}

Controller Button Combos:

::controller+share+menu {
    -- Gracefully exit ARMSX2
    do shell script "kill -INT {{{PID}}}"
    delay 2
    do shell script "kill -9 {{{PID}}} 2>/dev/null || true"
}

::controller+l1+triangle {
    -- Take screenshot
    do shell script "screencapture ~/Desktop/{{{GAME}}}_screenshot.png"
}

Priority System

Running Scripts operate at Priority 1, meaning they execute before controller profile hotkeys (Priority 2). This ensures your custom scripts always take precedence.

Execution Flow

  1. Priority 1: Running Scripts - Check if button combo matches script trigger
  2. Priority 2: Controller Profiles - If no script match, check profile hotkeys
  3. Fallback: Pass-through - If no match, input passes to game/emulator

Available Variables

Your scripts have access to three special variables that are automatically substituted at runtime:

VariableDescriptionExample Value
{{{PID}}}Process ID of running emulator12345
{{{GAME}}}Name of current gameMetal Gear Solid 3
{{{EMULATOR}}}Name of emulatorARMSX2

Example with Variables

::f12 {
    -- Screenshot with game name
    do shell script "screencapture ~/Desktop/{{{GAME}}}_screenshot.png"
    display notification "Screenshot saved!" with title "{{{GAME}}}"
}

::esc {
    -- Kill emulator by PID
    do shell script "kill -INT {{{PID}}}"
    delay 2
    do shell script "kill -9 {{{PID}}} 2>/dev/null || true"
}

Supported Keys

Running Scripts support standard keyboard keys and modifiers:

  • Letters: a-z
  • Numbers: 0-9
  • Function Keys: f1-f12
  • Special Keys: esc, space, tab, return, delete, backspace
  • Arrow Keys: up, down, left, right
  • Modifiers: cmd, shift, alt, ctrl (can combine: cmd+shift+q)
  • Controller: All 70+ button aliases (see Controller Reference)

Where to Add Scripts

Running Scripts are configured per-emulator in Settings:

  1. Open Settings → Emulators
  2. Select your emulator (e.g., ARMSX2)
  3. Click the Scripts tab
  4. Paste your script in the Running Script text area
  5. Click Save
running-script-editor.png - Running script text editor in emulator settings (1440x900)

Next Steps