Timberbot API

Status: active. mod works, still adding features

Steam Workshop | Getting Started | API Reference

C# mod + Python client that lets AI agents read and control a running Timberborn game over HTTP.

Timberborn (Unity)
  |-- Timberbot API mod (port 8085)   read and write game state

Python client
  |-- timberbot.py                   single-file API client + CLI + dashboard

Quick start

# with Timberborn running + mod loaded
timberbot.py summary                              # colony snapshot
timberbot.py buildings                            # list all buildings
timberbot.py beavers                              # beaver wellbeing + critical needs
timberbot.py map x1:110 y1:130 x2:130 y2:150     # ASCII map with terrain + blockers
timberbot.py place_building prefab:Path x:100 y:130 z:2 orientation:south
timberbot.py place_path x1:110 y1:130 x2:130 y2:150       # A* pathfinding with auto-stairs
timberbot.py set_speed speed:3                    # fast forward
timberbot.py science                              # science points + unlockable buildings
timberbot.py distribution                         # import/export settings per district
timberbot.py top                                  # live colony dashboard
timberbot.py                                      # list all methods

Auto-launch a save directly:

timberbot.py launch settlement:MyCastle save:day5

Or use raw HTTP. no Python needed:

curl http://localhost:8085/api/summary
curl -X POST http://localhost:8085/api/speed -d '{"speed": 3}'

Features

• A pathfinding*. place_path routes around obstacles, water, and ruins with auto-stairs
• Fresh-on-request reads. no stale data, zero cost when idle
• Blocker tracking. ruins and editor objects visible in /api/tiles and placement errors
• Write job system. budgeted frame execution, no spikes
• Debug endpoint. reflection inspector with chaining and validation
• Webhooks. subscribe to game events over HTTP
• Zero-alloc hot path. no garbage collection pressure on read endpoints

Docs

• Getting Started. install, first steps, examples
• API Reference. all HTTP endpoints
• Timberbot AI. AI guide for agents playing Timberborn
• Architecture. internals, thread model, read/write pipeline
• Developing. build from source, add endpoints, Workshop publishing

Settings

Drop a settings.json in your mod folder (Documents/Timberborn/Mods/Timberbot/):

{
  "httpPort": 8085,
  "debugEndpointEnabled": true,
  "webhooksEnabled": true,
  "webhookBatchMs": 200,
  "webhookCircuitBreaker": 30,
  "writeBudgetMs": 1.0
}

All fields are optional. missing keys use defaults.

Requirements

• Timberborn (Steam)
• .NET SDK 6+ (to build the mod)
• Python 3.8+ with requests (for the client, optional)
• pip install toons for compact TOON output (optional, falls back to JSON)

Credits

Learned from these Timberborn modding projects:

• mechanistry/timberborn-modding. official modding tools, wiki, and examples
• thomaswp/BeaverBuddies. BlockObjectPlacerService.Place() for building placement, TemplateInstantiator + MarkAsPreviewAndInitialize + IsValid() for game-native placement validation, BuildingUnlockingService.Unlock() for science, WorkingHoursManager for work schedules
• datvm/TimberbornMods. TreeCuttingArea.AddCoordinates() for tree marking, IAlertFragment patterns for building alerts
• ihsoft/TimberbornMods. Inventories.AllInventories for building inventory, BuildingUnlockingService.Unlocked() for science checks
• CordialGnom/timberborn-unity-modding. PlantingService.SetPlantingCoordinates() for crop planting, PlantingAreaValidator.CanPlant() for planting validation
• Timberborn-KyP-Mods/TimberPrint. PreviewFactory + BlockValidator patterns for placement validation
• toon-format/toon. Token-Oriented Object Notation for compact AI output