F6: Headless server entry point and smoke test

`tools/godot.sh -- --server` runs a headless dedicated server with
--seed, --port, --players, --bots, --ticks, --unthrottled and
--log-every. ServerLoop drives the simulation and times every tick
without a scene tree, so tests run it directly. A placeholder WanderBot
gives smoke runs realistic load until the v0.4 bots land.

Logs are JSON lines that all carry the seed. An ErrorCounter logger
makes any engine or script error exit 1; a bad command line exits 2.

`make smoke` (now part of `make check`) runs 1,000 ticks with 24 bots,
prints min/mean/p50/p95/p99/max tick time against the 12 ms budget,
reruns to confirm the state hash reproduces, and proves a deliberate
script error and a bad config both exit non-zero.

Closes #6

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-09 20:07:39 -05:00
co-authored by Claude Opus 5.5
parent 46b131fe84
commit d9d4c04312
18 changed files with 621 additions and 3 deletions
+44
View File
@@ -0,0 +1,44 @@
## Counts engine and script errors, so the server can exit non-zero after any of them.
## Godot may call a Logger from any thread, so the state is guarded by a mutex, and
## nothing here prints (printing from a logger callback would recurse).
class_name ErrorCounter
extends Logger
var _mutex: Mutex = Mutex.new()
var _count: int = 0
var _first: String = ""
func _log_error(
function: String,
file: String,
line: int,
code: String,
rationale: String,
_editor_notify: bool,
error_type: int,
_script_backtrace: Array[ScriptBacktrace],
) -> void:
if error_type == Logger.ERROR_TYPE_WARNING:
return
_mutex.lock()
if _count == 0:
var what: String = rationale if not rationale.is_empty() else code
_first = "%s (at %s:%d in %s)" % [what, file, line, function]
_count += 1
_mutex.unlock()
func count() -> int:
_mutex.lock()
var value: int = _count
_mutex.unlock()
return value
## The first error seen, or an empty string.
func first() -> String:
_mutex.lock()
var value: String = _first
_mutex.unlock()
return value
+1
View File
@@ -0,0 +1 @@
uid://l3us7ygwk4vr
+130
View File
@@ -0,0 +1,130 @@
## A headless dedicated server. It runs the match at the real tick rate, or back to back
## with `--unthrottled`, and writes structured logs: one JSON object per line on stdout,
## each carrying the match seed so any run can be reproduced.
##
## Exits 0 after a clean run, 1 if any engine or script error happened, and 2 if the
## command line was invalid.
class_name HeadlessServer
extends Node
## Catch-up limit from docs/ARCHITECTURE.md.
const MAX_TICKS_PER_FRAME: int = 5
## Ticks per frame when unthrottled. Keeps the engine's main loop responsive.
const UNTHROTTLED_BATCH: int = 250
## Engine frame cap in real-time mode, so an idle server doesn't spin a core.
const REALTIME_MAX_FPS: int = 120
const FAULT_TICK: int = 10
var config: ServerConfig
var loop: ServerLoop
var _errors: ErrorCounter = ErrorCounter.new()
var _accumulator: float = 0.0
var _started_usec: int = 0
var _finished: bool = false
func _init(server_config: ServerConfig) -> void:
config = server_config
func _ready() -> void:
OS.add_logger(_errors)
_started_usec = Time.get_ticks_usec()
if not config.is_valid():
for problem: String in config.errors:
_log("config_error", {"message": problem})
_finish(2)
return
if not config.has_seed:
config.match_seed = _fresh_seed()
Engine.max_fps = 0 if config.unthrottled else REALTIME_MAX_FPS
loop = ServerLoop.new(config.match_seed, config.players, config.bots)
var started: Dictionary = config.to_dictionary()
started["engine"] = Engine.get_version_info()["string"]
started["tick_rate_hz"] = Tuning.TICK_RATE_HZ
started["listening"] = false
started["note"] = "networking arrives in v0.5; players join as idle slots until then"
_log("start", started)
func _process(delta: float) -> void:
if _finished or loop == null:
return
var due: int = UNTHROTTLED_BATCH
if not config.unthrottled:
_accumulator += delta
due = mini(floori(_accumulator * Tuning.TICK_RATE_HZ), MAX_TICKS_PER_FRAME)
_accumulator = maxf(_accumulator - float(due) / Tuning.TICK_RATE_HZ, 0.0)
if due == MAX_TICKS_PER_FRAME:
# Too far behind to catch up: drop the backlog rather than spiral.
_accumulator = minf(_accumulator, 1.0 / Tuning.TICK_RATE_HZ)
for _index: int in due:
if config.ticks > 0 and loop.sim.tick >= config.ticks:
break
_tick()
if config.ticks > 0 and loop.sim.tick >= config.ticks:
_finish(0)
func _exit_tree() -> void:
# Stopped from outside, for example by SIGTERM: still report what happened.
if not _finished and loop != null:
_finish(0)
func _tick() -> void:
if config.fault == "script-error" and loop.sim.tick == FAULT_TICK:
_deliberate_script_error()
loop.run_tick()
if config.log_every > 0 and loop.sim.tick % config.log_every == 0:
var stats: Dictionary = loop.timing_stats()
_log("progress", {"tick": loop.sim.tick, "p95_us": stats["p95_us"], "max_us": stats["max_us"]})
func _finish(requested_code: int) -> void:
_finished = true
var code: int = requested_code
if loop != null:
var stats: Dictionary = loop.timing_stats()
stats["state_hash"] = loop.sim.state_hash()
stats["entities"] = loop.sim.entities.count()
_log("stats", stats)
if code == 0 and _errors.count() > 0:
code = 1
var stopped: Dictionary = {
"exit_code": code,
"errors": _errors.count(),
"wall_ms": roundi((Time.get_ticks_usec() - _started_usec) / 1000.0),
}
if _errors.count() > 0:
stopped["first_error"] = _errors.first()
_log("stop", stopped)
OS.remove_logger(_errors)
if is_inside_tree():
get_tree().quit(code)
func _log(event: String, fields: Dictionary) -> void:
var record: Dictionary = {
"t_ms": roundi((Time.get_ticks_usec() - _started_usec) / 1000.0),
"event": event,
"seed": config.match_seed,
}
if loop != null:
record["tick"] = loop.sim.tick
record.merge(fields, false)
print(JSON.stringify(record))
## A non-negative 63-bit seed. Only the server picks seeds; the simulation never does.
static func _fresh_seed() -> int:
var rng: RandomNumberGenerator = RandomNumberGenerator.new()
rng.randomize()
return (rng.randi() << 31 | rng.randi()) & 0x7FFFFFFFFFFFFFFF
## Calls a method on a null object, the most common real script error.
func _deliberate_script_error() -> void:
var missing: Object = null
missing.call("deliberate_fault")
+1
View File
@@ -0,0 +1 @@
uid://bv6bvpw5ooxwv
+125
View File
@@ -0,0 +1,125 @@
## Command-line configuration for a headless server.
##
## tools/godot.sh -- --server [--seed=N] [--port=N] [--players=N] [--bots=N]
## [--ticks=N] [--unthrottled] [--log-every=N]
##
## Unknown or malformed arguments are errors, so a typo can't silently run the wrong
## match. See `parse()`.
class_name ServerConfig
extends RefCounted
const DEFAULT_PORT: int = 24650
## The `--fault` names `HeadlessServer` understands. They exist so tools/smoke.sh can
## prove a script error really produces a non-zero exit.
const FAULTS: Array[String] = ["", "script-error"]
## True when `--server` was given.
var server: bool = false
## The match seed. `has_seed` is false when none was given and the server must pick one.
var match_seed: int = 0
var has_seed: bool = false
## UDP port the server will listen on once networking lands (v0.5).
var port: int = DEFAULT_PORT
## Player slots for human clients. Until v0.5 they join as idle players.
var players: int = 0
var bots: int = 0
## Ticks to run before exiting. 0 runs until the process is stopped.
var ticks: int = 0
## Runs ticks back to back instead of at the real tick rate. For tests and smoke runs.
var unthrottled: bool = false
## Logs a progress line every this many ticks. 0 turns progress lines off.
var log_every: int = 0
var fault: String = ""
## Human-readable problems found while parsing. Empty when the config is usable.
var errors: Array[String] = []
## Parses arguments. Arguments before `--server` are ignored unless `--server` is absent,
## in which case nothing is parsed and `server` stays false.
static func parse(args: PackedStringArray) -> ServerConfig:
var config: ServerConfig = ServerConfig.new()
var start: int = args.find("--server")
if start < 0:
return config
config.server = true
for index: int in range(start + 1, args.size()):
config._parse_one(args[index])
config._validate()
return config
func is_valid() -> bool:
return errors.is_empty()
## The values that matter for reproducing a run, for the start log line.
func to_dictionary() -> Dictionary:
return {
"seed": match_seed,
"port": port,
"players": players,
"bots": bots,
"ticks": ticks,
"unthrottled": unthrottled,
}
func _parse_one(arg: String) -> void:
if arg == "--unthrottled":
unthrottled = true
return
var parts: PackedStringArray = arg.split("=", true, 1)
if parts.size() != 2 or not arg.begins_with("--"):
errors.append("unknown argument '%s'" % arg)
return
var key: String = parts[0]
var value: String = parts[1]
match key:
"--seed":
if _check_int(key, value):
match_seed = value.to_int()
has_seed = true
"--port":
if _check_int(key, value):
port = value.to_int()
"--players":
if _check_int(key, value):
players = value.to_int()
"--bots":
if _check_int(key, value):
bots = value.to_int()
"--ticks":
if _check_int(key, value):
ticks = value.to_int()
"--log-every":
if _check_int(key, value):
log_every = value.to_int()
"--fault":
fault = value
_:
errors.append("unknown argument '%s'" % arg)
func _check_int(key: String, value: String) -> bool:
if value.is_valid_int():
return true
errors.append("%s needs a whole number, got '%s'" % [key, value])
return false
func _validate() -> void:
if port < 1 or port > 65535:
errors.append("--port must be between 1 and 65535, got %d" % port)
if players < 0 or bots < 0:
errors.append("--players and --bots can't be negative")
if players + bots > Tuning.SOLO_PLAYERS:
errors.append(
"--players plus --bots is %d, more than the match size of %d"
% [players + bots, Tuning.SOLO_PLAYERS]
)
if ticks < 0:
errors.append("--ticks can't be negative")
if log_every < 0:
errors.append("--log-every can't be negative")
if fault not in FAULTS:
errors.append("unknown --fault '%s'" % fault)
+1
View File
@@ -0,0 +1 @@
uid://dbnjplsnqeona
+65
View File
@@ -0,0 +1,65 @@
## Drives one match's simulation for a server: adds players and bots, gathers their
## commands each tick, steps the simulation and times every tick.
## It has no scene-tree dependency, so tests can run it directly.
class_name ServerLoop
extends RefCounted
## The server-tick budget from docs/ARCHITECTURE.md, in microseconds.
const TICK_BUDGET_USEC: int = 12_000
var sim: Simulation
var player_ids: Array[int] = []
var bots: Array[WanderBot] = []
## Wall-clock duration of every tick run, in microseconds.
var tick_usec: PackedInt64Array = PackedInt64Array()
func _init(match_seed: int, human_players: int, bot_count: int) -> void:
sim = Simulation.new(match_seed)
for _index: int in human_players:
player_ids.append(sim.add_player())
for _index: int in bot_count:
var id: int = sim.add_player()
player_ids.append(id)
bots.append(WanderBot.new(id))
## Runs one tick and records how long it took.
func run_tick() -> void:
var started: int = Time.get_ticks_usec()
for bot: WanderBot in bots:
sim.submit_command(bot.player_id, bot.think(sim))
sim.step()
tick_usec.append(Time.get_ticks_usec() - started)
## Timing statistics over every tick run so far, in microseconds.
func timing_stats() -> Dictionary:
var count: int = tick_usec.size()
if count == 0:
return {"ticks": 0}
var sorted: PackedInt64Array = tick_usec.duplicate()
sorted.sort()
var total: int = 0
var over_budget: int = 0
for value: int in sorted:
total += value
if value > TICK_BUDGET_USEC:
over_budget += 1
return {
"ticks": count,
"min_us": sorted[0],
"mean_us": roundi(float(total) / count),
"p50_us": _percentile(sorted, 0.50),
"p95_us": _percentile(sorted, 0.95),
"p99_us": _percentile(sorted, 0.99),
"max_us": sorted[count - 1],
"budget_us": TICK_BUDGET_USEC,
"over_budget": over_budget,
}
## Nearest-rank percentile of an ascending array.
static func _percentile(sorted: PackedInt64Array, fraction: float) -> int:
var rank: int = clampi(ceili(fraction * sorted.size()) - 1, 0, sorted.size() - 1)
return sorted[rank]
+1
View File
@@ -0,0 +1 @@
uid://cr14bfd1283vt