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

./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:

   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:

./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:

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: #720