bg3-steam-launcher

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);