the-nexus/docs/BANNERLORD_RUNTIME.md

# Bannerlord Runtime — Apple Silicon Selection

> **Issue:** #720
> **Status:** DECIDED
> **Chosen Runtime:** Whisky (via Apple Game Porting Toolkit)
> **Date:** 2026-04-12
> **Platform:** macOS Apple Silicon (arm64)

---

## Decision

**Whisky** is the chosen runtime for Mount & Blade II: Bannerlord on Apple Silicon Macs.

Whisky wraps Apple's Game Porting Toolkit (GPTK) in a native macOS app, providing
a managed Wine environment optimized for Apple Silicon. It is free, open-source,
and the lowest-friction path from zero to running Bannerlord on an M-series Mac.

### Why Whisky

| Criterion | Whisky | Wine-stable | CrossOver | UTM/VM |
|-----------|--------|-------------|-----------|--------|
| Apple Silicon native | Yes (GPTK) | Partial (Rosetta) | Yes | Yes (emulated x86) |
| Cost | Free | Free | $74/year | Free |
| Setup friction | Low (app install + bottle) | High (manual config) | Low | High (Windows license) |
| Bannerlord community reports | Working | Mixed | Working | Slow (no GPU passthrough) |
| DXVK/D3DMetal support | Built-in | Manual | Built-in | No (software rendering) |
| GPU acceleration | Yes (Metal) | Limited | Yes (Metal) | No |
| Bottle management | GUI + CLI | CLI only | GUI + CLI | N/A |
| Maintenance | Active | Active | Active | Active |

### Rejected Alternatives

**Wine-stable (Homebrew):** Requires manual GPTK/D3DMetal integration.
Poor Apple Silicon support out of the box. Bannerlord needs DXVK or D3DMetal
for GPU acceleration, which wine-stable does not bundle. Rejected: high falsework.

**CrossOver:** Commercial ($74/year). Functionally equivalent to Whisky for
Bannerlord. Rejected: unnecessary cost when a free alternative works. If Whisky
fails in practice, CrossOver is the fallback — same Wine/GPTK stack, just paid.

**UTM/VM (Windows 11 ARM):** No GPU passthrough. Bannerlord requires hardware
3D acceleration. Software rendering produces <5 FPS. Rejected: physics, not ideology.

---

## Installation

### Prerequisites

- macOS 14+ on Apple Silicon (M1/M2/M3/M4)
- ~60GB free disk space (Whisky + Steam + Bannerlord)
- Homebrew installed

### One-Command Setup

```bash
./scripts/bannerlord_runtime_setup.sh
```

This script handles:
1. Installing Whisky via Homebrew cask
2. Creating a Bannerlord bottle
3. Configuring the bottle for GPTK/D3DMetal
4. Pointing the bottle at Steam (Windows)
5. Outputting a verification-ready path

### Manual Steps (if script not used)

1. **Install Whisky:**
   ```bash
   brew install --cask whisky
   ```

2. **Open Whisky** and create a new bottle:
   - Name: `Bannerlord`
   - Windows Version: Windows 10

3. **Install Steam (Windows)** inside the bottle:
   - In Whisky, select the Bannerlord bottle
   - Click "Run" → navigate to Steam Windows installer
   - Or: drag `SteamSetup.exe` into the Whisky window

4. **Install Bannerlord** through Steam (Windows):
   - Launch Steam from the bottle
   - Install Mount & Blade II: Bannerlord (App ID: 261550)

5. **Configure D3DMetal:**
   - In Whisky bottle settings, enable D3DMetal (or DXVK as fallback)
   - Set Windows version to Windows 10

---

## Runtime Paths

After setup, the key paths are:

```
# Whisky bottle root
~/Library/Application Support/Whisky/Bottles/Bannerlord/

# Windows C: drive
~/Library/Application Support/Whisky/Bottles/Bannerlord/drive_c/

# Steam (Windows)
~/Library/Application Support/Whisky/Bottles/Bannerlord/drive_c/Program Files (x86)/Steam/

# Bannerlord install
~/Library/Application Support/Whisky/Bottles/Bannerlord/drive_c/Program Files (x86)/Steam/steamapps/common/Mount & Blade II Bannerlord/

# Bannerlord executable
~/Library/Application Support/Whisky/Bottles/Bannerlord/drive_c/Program Files (x86)/Steam/steamapps/common/Mount & Blade II Bannerlord/bin/Win64_Shipping_Client/Bannerlord.exe
```

---

## Verification

Run the verification script to confirm the runtime is operational:

```bash
./scripts/bannerlord_verify_runtime.sh
```

Checks:
- [ ] Whisky installed (`/Applications/Whisky.app`)
- [ ] Bannerlord bottle exists
- [ ] Steam (Windows) installed in bottle
- [ ] Bannerlord executable found
- [ ] `wine64-preloader` can launch the exe (smoke test, no window)

---

## Integration with Bannerlord Harness

The `nexus/bannerlord_runtime.py` module provides programmatic access to the runtime:

```python
from bannerlord_runtime import BannerlordRuntime

rt = BannerlordRuntime()
# Check runtime state
status = rt.check()
# Launch Bannerlord
rt.launch()
# Launch Steam first, then Bannerlord
rt.launch(with_steam=True)
```

The harness's `capture_state()` and `execute_action()` operate on the running
game window via MCP desktop-control. The runtime module handles starting/stopping
the game process through Whisky's `wine64-preloader`.

---

## Failure Modes and Fallbacks

| Failure | Cause | Fallback |
|---------|-------|----------|
| Whisky won't install | macOS version too old | Update to macOS 14+ |
| Bottle creation fails | Disk space | Free space, retry |
| Steam (Windows) crashes | GPTK version mismatch | Update Whisky, recreate bottle |
| Bannerlord won't launch | Missing D3DMetal | Enable in bottle settings |
| Poor performance | Rosetta fallback | Verify D3DMetal enabled, check GPU |
| Whisky completely broken | Platform incompatibility | Fall back to CrossOver ($74) |

---

## References

- Whisky: https://getwhisky.app
- Apple GPTK: https://developer.apple.com/games/game-porting-toolkit/
- Bannerlord on Whisky: https://github.com/Whisky-App/Whisky/issues (search: bannerlord)
- Issue #720: https://forge.alexanderwhitestone.com/Timmy_Foundation/the-nexus/issues/720