Skip to content

macOS Testing

Use this checklist when validating Timberbot on macOS. The post-WS-rework flow is the same as Windows/Linux except where called out.

Prerequisites

  • Timberborn running on macOS (Apple Silicon native — no Rosetta needed since Timberborn 1.0)
  • Python 3.10+ on PATH (brew install python or any pyenv install)
  • A working claude, codex, or opencode CLI on PATH (whichever backend you'll test)

Install the mod (manual, GitHub release)

The Steam Workshop entry "Timberbot API" is the upstream abix-/TimberbornMods project; this fork ships only via GitHub releases. Download Timberbot.dll, manifest.json, thumbnail.png and place them under:

~/Documents/Timberborn/Mods/Timberbot/

If the upstream Workshop mod is already subscribed, disable or unsubscribe it before launching — both registering the same singleton would prevent the mod from loading.

Install the CLI

pipx install timberbot
tbot init

Primary test flow

  1. Start the connector in a terminal and leave it running: 
    tbot watch
    Expected: logs wsclient: connected to ws://127.0.0.1:8086/api/ws once the game is in a save.
  2. Launch Timberborn.
  3. Dismiss the Mod Manager dialog; load any save.
  4. Confirm the green Timberbot API widget appears in the bottom-right corner. The state pill should read Not Ready (yellow) with the banner "Connected to game session — waiting for player to Launch."
  5. Press Launch in the widget.
  6. Expected: pill flips to Idle (green); tbot watch log shows a new ws frame type=state within ~50 ms; the connector dispatches the configured backend.

Stop behavior

  1. Press Stop in the widget.
  2. Expected: pill flips back to Not Ready (yellow); subsequent curl http://127.0.0.1:8085/api/buildings returns 409 game_not_ready; tbot watch aborts any in-flight cycle and idles until the next Launch.

Save autoload helper

tbot launch on macOS prints the Steam launch options for the chosen settlement and doesn't open the game itself (Steam URL-handler launch isn't reliable on Mac from a CLI process):

tbot launch --settlement=<name> [--save=<filename>]

Expected: - Prints --tb-settlement <name> [--tb-save <save>] as a copy-pasteable Steam launch-options string. - Prints an open -a Steam --args -applaunch 1062090 … one-liner as an alternative. - Does not write any file under Documents/Timberborn/Mods/Timberbot/.

Set those launch options in Steam (Library → Timberborn → Properties → Launch Options) or run the open -a Steam command, then open Timberborn yourself; the mod's TimberbotAutoLoad reads the --tb-* args at the main menu and auto-loads the save.

What to send back if anything fails

Please include:

  • macOS version (sw_vers)
  • which backend (claude / codex / opencode)
  • the tbot watch stderr output around the failure
  • this log file:
~/Documents/Timberborn/Mods/Timberbot/timberbot.log