BG3 Steam Launcher

Automate launching Baldur's Gate 3 via Steam and loading saved games.

MCP Servers Used:

• macos-automator - AppleScript execution for UI automation
• peekaboo - Fast screenshots and AI-powered visual analysis

Prerequisites

claude mcp add macos-automator -- npx -y @steipete/macos-automator-mcp@latest
claude mcp add peekaboo -- npx -y @steipete/peekaboo-mcp@beta

Grant accessibility permissions to osascript in System Preferences → Security → Accessibility.

MCP Tools Quick Reference

Peekaboo (Vision)

macos-automator (Actions)

Core Workflow

Step 1: Launch BG3 via Steam Protocol

do shell script "open steam://run/1086940"

BG3 Steam App ID: 1086940

Step 2: Wait for Larian Launcher

Use Peekaboo to monitor for the PLAY button, then click it.

Step 3: Wait for Main Menu (15-30s)

Poll with Peekaboo screenshots looking for Continue/Load Game/New Game buttons.

Step 4: Load Save

Navigate menus using keyboard (Enter=36, Esc=53, arrows) or mouse coordinates.

Mouse Clicks (JXA + CGEvent)

Standard AppleScript click at doesn't work for game UIs. Use JXA with CGEvent:

// Execute with language: "javascript"
ObjC.import('Cocoa');

function clickAt(x, y) {
    const point = $.CGPointMake(x, y);
    const down = $.CGEventCreateMouseEvent($(), $.kCGEventLeftMouseDown, point, $.kCGMouseButtonLeft);
    const up = $.CGEventCreateMouseEvent($(), $.kCGEventLeftMouseUp, point, $.kCGMouseButtonLeft);
    $.CGEventPost($.kCGHIDEventTap, down);
    delay(0.05);
    $.CGEventPost($.kCGHIDEventTap, up);
}

// Get window-relative coordinates
function getWindowClickPos(processName, xPercent, yPercent) {
    const se = Application('System Events');
    const proc = se.processes.byName(processName);
    const win = proc.windows[0];
    const pos = win.position();
    const size = win.size();
    return {
        x: pos[0] + (size[0] * xPercent),
        y: pos[1] + (size[1] * yPercent)
    };
}

// Example: click PLAY button (22% across, 87% down)
const coords = getWindowClickPos('bg3', 0.22, 0.87);
clickAt(coords.x, coords.y);

Process Names

Button Coordinates (1728x1117 fullscreen)

SE Testing Workflow

1. Build:

   cd /path/to/bg3se-macos && ./scripts/build.sh
   

2. Verify SE wrapper in Steam launch options:

   /tmp/bg3w.sh %command%
   

3. Launch via this skill and load a save

4. Check SE logs:

   tail -f /tmp/bg3se_macos.log
   

Crash Reports

SE Log: /tmp/bg3se_macos.log

macOS Crash Reports: ~/Library/Logs/DiagnosticReports/

• Files named Baldur's Gate 3-YYYY-MM-DD-HHMMSS.ips
• JSON format with full stack traces

# List recent BG3 crash reports
ls -la ~/Library/Logs/DiagnosticReports/ | grep -i "baldur"

# Find crash location in our dylib
grep -A5 "libbg3se.dylib" ~/Library/Logs/DiagnosticReports/'Baldur'\''s Gate 3-*.ips'

Troubleshooting