M1: Match state machine

Match (src/sim/match.gd) runs a server's matches back to back: lobby,
countdown, drop, play and results, then a fresh island and the lobby again.
It is stepped once per server tick and has no scene-tree or clock dependency.

- MatchRules holds max and min players, team size, the lobby, countdown and
  results timers (defaults in Tuning.MATCH_*) and whether bots fill empty
  places.
- Participants are server-chosen handles. Joining during a match waits for
  the next; leaving during the drop or play places the leaver as eliminated.
- Placements, winners (last team standing) and events for phase changes,
  joins, leaves, places, match start and end.
- Match 0 uses the server's seed; later matches derive their seed from it and
  their index. The next match's Simulation is built when the lobby opens.
- ServerLoop now drives a Match (immediate rules by default, so the smoke
  match is unchanged: same state hash), rebuilds bots each match, and counts
  server ticks across matches. The headless server logs match events.

Tests: test_match (13) covers every transition, leaving in each phase, an
empty lobby, an empty match, teams, late joiners, and ten consecutive matches
that each start identical to a freshly built simulation. A ServerLoop test
checks the server goes back to the lobby and starts the next match.

Closes #24

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-11 20:24:00 -05:00
co-authored by Claude Opus 5.5
parent 0013a81658
commit c6f3c19004
11 changed files with 649 additions and 23 deletions
+10 -6
View File
@@ -44,6 +44,7 @@ func _ready() -> void:
started["engine"] = Engine.get_version_info()["string"]
started["tick_rate_hz"] = Tuning.TICK_RATE_HZ
started["world_hash"] = loop.sim.island.heightmap_hash()
started["match_phase"] = loop.match_flow.phase_name()
started["listening"] = false
started["note"] = "networking arrives in v0.5; players join as idle slots until then"
_log("start", started)
@@ -61,10 +62,10 @@ func _process(delta: float) -> void:
# 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:
if config.ticks > 0 and loop.ticks >= config.ticks:
break
_tick()
if config.ticks > 0 and loop.sim.tick >= config.ticks:
if config.ticks > 0 and loop.ticks >= config.ticks:
_finish(0)
@@ -75,12 +76,15 @@ func _exit_tree() -> void:
func _tick() -> void:
if config.fault == "script-error" and loop.sim.tick == FAULT_TICK:
if config.fault == "script-error" and loop.ticks == FAULT_TICK:
_deliberate_script_error()
loop.run_tick()
if config.log_every > 0 and loop.sim.tick % config.log_every == 0:
for event: Dictionary in loop.match_flow.events:
if event["type"] in ["phase", "match_started", "match_ended"]:
_log("match", event)
if config.log_every > 0 and loop.ticks % 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"]})
_log("progress", {"tick": loop.ticks, "p95_us": stats["p95_us"], "max_us": stats["max_us"]})
func _finish(requested_code: int) -> void:
@@ -113,7 +117,7 @@ func _log(event: String, fields: Dictionary) -> void:
"seed": config.match_seed,
}
if loop != null:
record["tick"] = loop.sim.tick
record["tick"] = loop.ticks
record.merge(fields, false)
print(JSON.stringify(record))
+51 -17
View File
@@ -1,5 +1,5 @@
## Drives one match's simulation for a server: adds players and bots, gathers their
## commands each tick, steps the simulation and times every tick.
## Drives a server's matches: joins players, fills each match with bots, gathers their
## commands each tick, steps the match flow and times every tick.
## It has no scene-tree dependency, so tests can run it directly.
class_name ServerLoop
extends RefCounted
@@ -7,35 +7,69 @@ extends RefCounted
## The server-tick budget from docs/ARCHITECTURE.md, in microseconds.
const TICK_BUDGET_USEC: int = 12_000
var sim: Simulation
## The match flow. Its `sim` is the current match's simulation.
var match_flow: Match
var sim: Simulation:
get:
return match_flow.sim
## Entity IDs of everyone in the current match, humans first.
var player_ids: Array[int] = []
var bots: Array[WanderBot] = []
## Wall-clock duration of every tick run, in microseconds.
var tick_usec: PackedInt64Array = PackedInt64Array()
## Server ticks run, across every match.
var ticks: int = 0
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))
# Every match starts on the sky barge.
sim.start_drop()
sim.place_loot()
## `human_players` join as idle participants with handles 1 and up; `bot_count` bots
## fill the rest of every match. With `rules` null the match starts at once, and the
## server goes back to the lobby after each match's results and starts another.
func _init(match_seed: int, human_players: int, bot_count: int, rules: MatchRules = null) -> void:
if rules == null:
rules = MatchRules.immediate()
rules.max_players = maxi(human_players + bot_count, 1)
rules.fill_with_bots = bot_count > 0
# With only bots there's nobody to wait for, so the lobby starts with no one in it.
rules.min_players = 0 if human_players == 0 and bot_count > 0 else 1
match_flow = Match.new(match_seed, rules)
for handle: int in range(1, human_players + 1):
match_flow.join(handle)
if rules.lobby_ticks == 0 and rules.countdown_ticks == 0:
# Every match starts on the sky barge, on the first tick.
_advance()
## 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()
if match_flow.in_match():
for bot: WanderBot in bots:
sim.submit_command(bot.player_id, bot.think(sim))
_advance()
ticks += 1
tick_usec.append(Time.get_ticks_usec() - started)
func _advance() -> void:
match_flow.step()
for event: Dictionary in match_flow.events:
if event["type"] == "match_started":
_track_players()
elif event["type"] == "phase" and event["to"] == "lobby":
player_ids.clear()
bots.clear()
func _track_players() -> void:
player_ids.clear()
bots.clear()
for handle: int in match_flow.participants:
var entity_id: int = match_flow.entity_of[handle]
player_ids.append(entity_id)
if match_flow.bot_handles.has(handle):
bots.append(WanderBot.new(entity_id))
## Timing statistics over every tick run so far, in microseconds.
func timing_stats() -> Dictionary:
var count: int = tick_usec.size()