Configuration Reference

This page describes the bot roster TOML used by the roWars CLI and Python SDK.

File Shape

gateway_url = "ws://localhost:8080/v1/bots/ws"

[[bot]]
handle = "scout"
token = "dev-bot-token-2"
slot = 0
on_death = "respawn"
group = 1

[bot.build.stats]
mode = "priority"
plan = [
  { stat = "dex", until = 20 },
  { stat = "agi", until = 20 },
]

[bot.build.jobs]
plan = [
  { at_job_level = 10, job = "archer" },
  { at_job_level = 40, job = "hunter" },
]

Global Fields

gateway_url

The WebSocket endpoint used by the CLI and SDK.

Default local value:

gateway_url = "ws://localhost:8080/v1/bots/ws"

Bot Fields

handle

Local name used by the CLI and SDK. It must be unique in the file.

handle = "scout"

token

Bearer token used to authenticate the bot session. The token selects the real bot account on the server.

token = "dev-bot-token-2"

slot

Character slot to spawn for that account.

slot = 0

group

Initial group id.

group = 0  no initial group
group = 1  member of @1
group = 2  member of @2

Groups are visible with:

rowars> /groups

Death Policy

on_death controls what the bot should do when it dies.

on_death = "respawn"

Supported values:

respawn            return to the save point immediately
wait               stay dead and wait for an external resurrection
wait_then_respawn  wait for revive_timeout seconds, then respawn

revive_timeout only applies to wait_then_respawn.

on_death = "wait_then_respawn"
revive_timeout = 20

Stat Build

Stat plans live under [bot.build.stats].

[bot.build.stats]
mode = "priority"
plan = [
  { stat = "dex", until = 20 },
  { stat = "agi", until = 20 },
  { stat = "str", until = 30 },
]

mode = "priority" means the bot spends stat points on the first entry until that stat reaches until, then moves to the next entry.

Valid stat names:

str
agi
vit
int
dex
luk

The stat plan is configuration for bot behavior. If the runner you are using does not implement automatic stat allocation yet, the plan is loaded but not applied.

Job Change Build

Job change plans live under [bot.build.jobs].

[bot.build.jobs]
plan = [
  { at_job_level = 10, job = "swordsman" },
  { at_job_level = 40, job = "knight" },
]

Each entry means: when the character reaches the configured job level, choose the configured job as the next job change target.

Common examples:

plan = [
  { at_job_level = 10, job = "archer" },
  { at_job_level = 40, job = "hunter" },
]

plan = [
  { at_job_level = 10, job = "swordsman" },
  { at_job_level = 40, job = "knight" },
]

The job change plan is configuration for bot behavior. If the runner you are using does not implement automatic job changes yet, the plan is loaded but not applied.

Validation Rules

The SDK validates the roster when it is loaded:

• handle is required and must be unique.
• token is required.
• slot must be 0 or greater.
• group must be 0 or greater.