the-nexus-fork/docs/BANNERLORD_LOCAL_MAC.md

Bannerlord Local Mac Setup

Status: READY FOR TESTING Platform: macOS (Apple Silicon / Intel) Source: GOG (not Steam) Last Updated: 2026-04-10

Problem

Bannerlord is a Windows game. Alexander has it from GOG on macOS. We need it running locally through emulation before the harness can observe it.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    LOCAL BANNERLORD ON MAC                       │
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │  Bannerlord  │    │   Emulator   │    │   macOS Desktop  │  │
│  │   (GOG)      │───►│ Wine/Whisky/ │───►│   (the screen)   │  │
│  │              │    │  CrossOver   │    │                  │  │
│  └──────────────┘    └──────────────┘    └────────┬─────────┘  │
│                                                    │            │
│  ┌─────────────────────────────────────────────────┤            │
│  │              Bannerlord Harness                 │            │
│  │  ┌────────────┐  ┌───────────┐  ┌───────────┐  │            │
│  │  │ capture_   │  │ execute_  │  │ bannerlord│  │            │
│  │  │ state()    │  │ action()  │  │ _local.py │  │            │
│  │  └────────────┘  └───────────┘  └───────────┘  │            │
│  │         │               ▲             │        │            │
│  │         ▼               │             ▼        │            │
│  │  ┌─────────────────────────────────────────┐   │            │
│  │  │     MCP Servers (desktop-control)       │   │            │
│  │  │     Screenshots + keyboard/mouse        │   │            │
│  │  └─────────────────────────────────────────┘   │            │
│  └─────────────────────────────────────────────────┘            │
│                                                                 │
│  ┌─────────────────────────────────────────────────┐            │
│  │              Hermes WebSocket                   │            │
│  │              Telemetry + ODA loop               │            │
│  └─────────────────────────────────────────────────┘            │
└─────────────────────────────────────────────────────────────────┘

Components

File	Purpose
scripts/bannerlord_launcher.sh	Shell launcher — detects emulator + game, launches
nexus/bannerlord_local.py	Python module — programmatic readiness + launch control
nexus/bannerlord_harness.py	Existing harness — extended with --local and --launch-local
portals.json	Portal metadata — updated with local_launch block

Emulator Priority

1. Whisky — /Applications/Whisky.app (preferred, best macOS integration)
2. CrossOver — /Applications/CrossOver.app (good, paid)
3. Homebrew Wine — wine64 / wine on PATH (free, may need Rosetta on ARM)

Quick Start

Check Readiness

# Shell
./scripts/bannerlord_launcher.sh --check --verbose

# Python
python3 -m nexus.bannerlord_local --check --json

# Through harness
python3 -m nexus.bannerlord_harness --local --mock

Launch Game

# Shell
./scripts/bannerlord_launcher.sh --launch

# Python
python3 -m nexus.bannerlord_local --launch --json

# Through harness (launches game, then runs ODA)
python3 -m nexus.bannerlord_harness --launch-local --mock

Stop Game

python3 -m nexus.bannerlord_local --stop

GOG Install Paths Searched

The launcher checks these paths in order:

1. /Applications/Games/Mount & Blade II Bannerlord
2. ~/GOG Games/Mount and Blade II Bannerlord
3. ~/Games/Mount & Blade II Bannerlord
4. /Applications/Mount & Blade II Bannerlord
5. ~/Library/Application Support/GOG.com/Galaxy/Applications/*/
6. Recursive find as last resort

The game must have bin/Generic/Bannerlord.exe relative to the install root.

Portal Metadata

The portals.json bannerlord entry now includes:

"environment": "local",
"local_launch": {
  "platform": "macos",
  "source": "gog",
  "emulator_required": true,
  "emulator_options": ["whisky", "crossover", "wine"],
  "launcher": "scripts/bannerlord_launcher.sh",
  "harness_bridge": "nexus/bannerlord_local.py",
  "check_command": "python3 -m nexus.bannerlord_local --check --json"
}

Honest Status

Component	Status
Launcher script	Written, needs Mac testing
Python local module	Written, needs Mac testing
Harness integration	Added --local/--launch-local flags
Portal metadata	Updated
MCP observation of emulated window	Untested — depends on emulator window visibility
ODA loop with emulated game	Untested — needs game actually running

What Could Go Wrong

• Emulator not installed: User must install Whisky, CrossOver, or wine
• Game not found: User must install GOG Bannerlord to a known path
• Performance: Wine on Apple Silicon requires Rosetta + possible DXVK setup
• Window title: The emulated window may not match "Mount & Blade II: Bannerlord" — the harness may need to detect the actual window title
• MCP desktop-control on macOS: pyautogui on macOS needs Accessibility permissions

Next Steps

1. Alexander runs ./scripts/bannerlord_launcher.sh --check --verbose on his Mac
2. If missing emulator, install Whisky (brew install --cask whisky)
3. If missing game, install GOG Bannerlord
4. Run --launch to verify the game opens
5. Run --launch-local --mock to verify harness integration
6. Test MCP screenshots of the emulated window