forked from Timmy_Foundation/the-nexus
73bc86d3a2
- scripts/bannerlord_launcher.sh: Mac launcher detects Whisky/CrossOver/Wine and GOG Bannerlord install - nexus/bannerlord_local.py: Python module for programmatic readiness check, launch, and stop - nexus/bannerlord_harness.py: Added --local and --launch-local CLI flags - portals.json: Updated bannerlord portal with local_launch metadata and environment=local - docs/BANNERLORD_LOCAL_MAC.md: Full documentation of local Mac setup
152 lines
6.9 KiB
Markdown
152 lines
6.9 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```json
|
|
"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
|