forked from Rockachopa/Timmy-time-dashboard
231 lines
6.1 KiB
Markdown
231 lines
6.1 KiB
Markdown
# Bannerlord Windows VM Setup Guide
|
|
|
|
**Issue:** #1098
|
|
**Parent Epic:** #1091 (Project Bannerlord)
|
|
**Date:** 2026-03-23
|
|
**Status:** Reference
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
This document covers provisioning the Windows VM that hosts Bannerlord + GABS mod,
|
|
verifying the GABS TCP JSON-RPC server, and confirming connectivity from Hermes.
|
|
|
|
Architecture reminder:
|
|
```
|
|
Timmy (Qwen3 on Ollama, Hermes M3 Max)
|
|
→ GABS TCP/JSON-RPC (port 4825)
|
|
→ Bannerlord.GABS C# mod
|
|
→ Game API + Harmony
|
|
→ Bannerlord (Windows VM)
|
|
```
|
|
|
|
---
|
|
|
|
## 1. Provision Windows VM
|
|
|
|
### Minimum Spec
|
|
| Resource | Minimum | Recommended |
|
|
|----------|---------|-------------|
|
|
| CPU | 4 cores | 8 cores |
|
|
| RAM | 16 GB | 32 GB |
|
|
| Disk | 100 GB SSD | 150 GB SSD |
|
|
| OS | Windows Server 2022 / Windows 11 | Windows 11 |
|
|
| Network | Private VLAN to Hermes | Private VLAN to Hermes |
|
|
|
|
### Hetzner (preferred)
|
|
```powershell
|
|
# Hetzner Cloud CLI — create CX41 (4 vCPU, 16 GB RAM, 160 GB SSD)
|
|
hcloud server create \
|
|
--name bannerlord-vm \
|
|
--type cx41 \
|
|
--image windows-server-2022 \
|
|
--location nbg1 \
|
|
--ssh-key your-key
|
|
```
|
|
|
|
### DigitalOcean alternative
|
|
```
|
|
Droplet: General Purpose 4 vCPU / 16 GB / 100 GB SSD
|
|
Image: Windows Server 2022
|
|
Region: Same region as Hermes
|
|
```
|
|
|
|
### Post-provision
|
|
1. Enable RDP (port 3389) for initial setup only — close after configuration
|
|
2. Open port 4825 TCP inbound from Hermes IP only
|
|
3. Disable Windows Firewall for 4825 or add specific allow rule:
|
|
```powershell
|
|
New-NetFirewallRule -DisplayName "GABS TCP" -Direction Inbound `
|
|
-Protocol TCP -LocalPort 4825 -Action Allow
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Install Steam + Bannerlord
|
|
|
|
### Steam installation
|
|
1. Download Steam installer from store.steampowered.com
|
|
2. Install silently:
|
|
```powershell
|
|
.\SteamSetup.exe /S
|
|
```
|
|
3. Log in with a dedicated Steam account (not personal)
|
|
|
|
### Bannerlord installation
|
|
```powershell
|
|
# Install Bannerlord (App ID: 261550) via SteamCMD
|
|
steamcmd +login <user> <pass> +app_update 261550 validate +quit
|
|
```
|
|
|
|
### Pin game version
|
|
GABS requires a specific Bannerlord version. To pin and prevent auto-updates:
|
|
1. Right-click Bannerlord in Steam → Properties → Updates
|
|
2. Set "Automatic Updates" to "Only update this game when I launch it"
|
|
3. Record the current version in `docs/research/bannerlord-vm-setup.md` after installation
|
|
|
|
```powershell
|
|
# Check installed version
|
|
Get-Content "C:\Program Files (x86)\Steam\steamapps\appmanifest_261550.acf" |
|
|
Select-String "buildid"
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Install GABS Mod
|
|
|
|
### Source
|
|
- NexusMods: https://www.nexusmods.com/mountandblade2bannerlord/mods/10419
|
|
- GitHub: https://github.com/BUTR/Bannerlord.GABS
|
|
- AGENTS.md: https://github.com/BUTR/Bannerlord.GABS/blob/master/AGENTS.md
|
|
|
|
### Installation via Vortex (NexusMods)
|
|
1. Install Vortex Mod Manager
|
|
2. Download GABS mod package from NexusMods
|
|
3. Install via Vortex — it handles the Modules/ directory layout automatically
|
|
4. Enable in the mod list and set load order after Harmony
|
|
|
|
### Manual installation
|
|
```powershell
|
|
# Copy mod to Bannerlord Modules directory
|
|
$BannerlordPath = "C:\Program Files (x86)\Steam\steamapps\common\Mount & Blade II Bannerlord"
|
|
Copy-Item -Recurse ".\Bannerlord.GABS" "$BannerlordPath\Modules\Bannerlord.GABS"
|
|
```
|
|
|
|
### Required dependencies
|
|
- **Harmony** (BUTR.Harmony) — must load before GABS
|
|
- **ButterLib** — utility library
|
|
Install via the same method as GABS.
|
|
|
|
### GABS configuration
|
|
GABS TCP server listens on `0.0.0.0:4825` by default. To confirm or override:
|
|
```
|
|
%APPDATA%\Mount and Blade II Bannerlord\Configs\Bannerlord.GABS\settings.json
|
|
```
|
|
Expected defaults:
|
|
```json
|
|
{
|
|
"ServerHost": "0.0.0.0",
|
|
"ServerPort": 4825,
|
|
"LogLevel": "Information"
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 4. Verify GABS TCP Server
|
|
|
|
### Start Bannerlord with GABS
|
|
Launch Bannerlord with the mod enabled. GABS starts its TCP server during game
|
|
initialisation. Watch the game log for:
|
|
```
|
|
[GABS] TCP server listening on 0.0.0.0:4825
|
|
```
|
|
|
|
Log location:
|
|
```
|
|
%APPDATA%\Mount and Blade II Bannerlord\logs\rgl_log_*.txt
|
|
```
|
|
|
|
### Local connectivity check (on VM)
|
|
```powershell
|
|
# Verify port is listening
|
|
netstat -an | findstr 4825
|
|
|
|
# Quick TCP probe
|
|
Test-NetConnection -ComputerName localhost -Port 4825
|
|
```
|
|
|
|
### Send a test JSON-RPC call
|
|
```powershell
|
|
$msg = '{"jsonrpc":"2.0","method":"ping","id":1}'
|
|
$client = New-Object System.Net.Sockets.TcpClient("localhost", 4825)
|
|
$stream = $client.GetStream()
|
|
$writer = New-Object System.IO.StreamWriter($stream)
|
|
$writer.AutoFlush = $true
|
|
$writer.WriteLine($msg)
|
|
$reader = New-Object System.IO.StreamReader($stream)
|
|
$response = $reader.ReadLine()
|
|
Write-Host "Response: $response"
|
|
$client.Close()
|
|
```
|
|
|
|
Expected response shape:
|
|
```json
|
|
{"jsonrpc":"2.0","result":{"status":"ok"},"id":1}
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Test Connectivity from Hermes
|
|
|
|
Use `scripts/test_gabs_connectivity.py` (checked in with this issue):
|
|
|
|
```bash
|
|
# From Hermes (M3 Max)
|
|
python scripts/test_gabs_connectivity.py --host <VM_IP> --port 4825
|
|
```
|
|
|
|
The script tests:
|
|
1. TCP socket connection
|
|
2. JSON-RPC ping round-trip
|
|
3. `get_game_state` call
|
|
4. Response latency (target < 100 ms on LAN)
|
|
|
|
---
|
|
|
|
## 6. Firewall / Network Summary
|
|
|
|
| Source | Destination | Port | Protocol | Purpose |
|
|
|--------|-------------|------|----------|---------|
|
|
| Hermes (local) | Bannerlord VM | 4825 | TCP | GABS JSON-RPC |
|
|
| Admin workstation | Bannerlord VM | 3389 | TCP | RDP setup (disable after) |
|
|
|
|
---
|
|
|
|
## 7. Reproducibility Checklist
|
|
|
|
After completing setup, record:
|
|
|
|
- [ ] VM provider + region + instance type
|
|
- [ ] Windows version + build number
|
|
- [ ] Steam account used (non-personal, credentials in secrets manager)
|
|
- [ ] Bannerlord App version (buildid from appmanifest)
|
|
- [ ] GABS version (from NexusMods or GitHub release tag)
|
|
- [ ] Harmony version
|
|
- [ ] ButterLib version
|
|
- [ ] GABS settings.json contents
|
|
- [ ] VM IP address (update Timmy config)
|
|
- [ ] Connectivity test output from `test_gabs_connectivity.py`
|
|
|
|
---
|
|
|
|
## References
|
|
|
|
- GABS GitHub: https://github.com/BUTR/Bannerlord.GABS
|
|
- GABS AGENTS.md: https://github.com/BUTR/Bannerlord.GABS/blob/master/AGENTS.md
|
|
- NexusMods page: https://www.nexusmods.com/mountandblade2bannerlord/mods/10419
|
|
- Parent Epic: #1091
|
|
- Connectivity test script: `scripts/test_gabs_connectivity.py`
|