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()
+246
View File
@@ -0,0 +1,246 @@
## A server's match flow: lobby, countdown, drop, play and results, then back to the
## lobby for a new match on a new island. Everything is driven by step(), one call per
## server tick, so it is deterministic and has no scene-tree or clock dependency.
##
## Participants are identified by handles the server chooses (a connection, a local
## player or a bot). Joining and leaving can happen in any phase: a join during a match
## waits in the lobby for the next one, and leaving during a match counts as being
## eliminated where they stood. Each match gets a fresh Simulation, built while the
## lobby waits, so nothing carries over from the last one.
class_name Match
extends RefCounted
const LOBBY: int = 0
const COUNTDOWN: int = 1
const DROP: int = 2
const PLAY: int = 3
const RESULTS: int = 4
const PHASE_NAMES: Array[String] = ["lobby", "countdown", "drop", "play", "results"]
## Bots added to fill a match get handles counting down from here, so they never clash
## with a server's own handles, which are positive.
const FIRST_BOT_HANDLE: int = -1
var rules: MatchRules
## The seed the server was started with. Match 0 uses it as is; later matches derive
## their own from it and their index.
var session_seed: int = 0
## How many matches have started. The current or next match's index is this, or this
## minus one once it has started.
var matches_started: int = 0
var phase: int = LOBBY
## Ticks spent in the current phase.
var phase_ticks: int = 0
## The current match's simulation during the drop, play and results. In the lobby and
## countdown, the next match's simulation, generated and waiting for players.
var sim: Simulation
## Participant handles in join order, and which of them are bots.
var participants: Array[int] = []
var bot_handles: Dictionary = {}
## Handles playing in the current match, and their entity IDs both ways.
var entity_of: Dictionary = {}
var handle_of: Dictionary = {}
## Handle -> team index, for the current match.
var team_of: Dictionary = {}
## Finishing order of the current match, last place first: {"handle", "place", "by",
## "left"}. "by" is the eliminating handle, or 0.
var placements: Array[Dictionary] = []
## The winning handles, empty for no winner (everyone left, or no one played).
var winners: Array[int] = []
## What happened during the last step(): phase changes, joins, leaves, placements.
var events: Array[Dictionary] = []
var _next_bot_handle: int = FIRST_BOT_HANDLE
## How many started the current match.
var _match_size: int = 0
func _init(seed_value: int, match_rules: MatchRules = null) -> void:
session_seed = seed_value
rules = match_rules if match_rules != null else MatchRules.new()
sim = Simulation.new(match_seed(0))
## The seed of match `index`: the session seed for the first, then a hash of it and the
## index, kept non-negative.
func match_seed(index: int) -> int:
if index == 0:
return session_seed
return (session_seed ^ SimRng._hash_name("match:%d" % index)) & 0x7FFFFFFFFFFFFFFF
## The current or next match's seed.
func current_seed() -> int:
return sim.rng.match_seed
func phase_name() -> String:
return PHASE_NAMES[phase]
func in_match() -> bool:
return phase == DROP or phase == PLAY
## Adds a participant. Returns false if the handle is already here or the lobby is
## full. During a match they wait for the next one.
func join(handle: int, bot: bool = false) -> bool:
if participants.has(handle) or participants.size() >= rules.max_players:
return false
participants.append(handle)
if bot:
bot_handles[handle] = true
events.append({"type": "joined", "handle": handle, "bot": bot})
return true
## Removes a participant. In a match, they're placed as if eliminated and their player
## leaves the simulation. Returns false if the handle isn't here.
func leave(handle: int) -> bool:
if not participants.has(handle):
return false
participants.erase(handle)
bot_handles.erase(handle)
events.append({"type": "left", "handle": handle})
if entity_of.has(handle):
var entity_id: int = entity_of[handle]
var player: SimEntity = sim.entities.find(entity_id)
if in_match() and player != null and not player.eliminated:
_place(handle, 0, true)
sim.remove_player(entity_id)
handle_of.erase(entity_id)
entity_of.erase(handle)
return true
## Passes a participant's command to the simulation. Returns false outside a match, for
## a handle that isn't playing, or if the simulation rejected it.
func submit_command(handle: int, command: PlayerCommand) -> bool:
if not in_match() or not entity_of.has(handle):
return false
return sim.submit_command(entity_of[handle], command)
## Handles still in the match and not eliminated, in join order.
func alive() -> Array[int]:
var living: Array[int] = []
if not in_match() and phase != RESULTS:
return living
for handle: int in entity_of:
var player: SimEntity = sim.entities.find(entity_of[handle])
if player != null and not player.eliminated:
living.append(handle)
return living
## Advances one server tick.
func step() -> void:
events.clear()
phase_ticks += 1
match phase:
LOBBY:
if participants.size() < rules.min_players:
phase_ticks = 0
elif participants.size() >= rules.max_players or phase_ticks >= rules.lobby_ticks:
_enter(COUNTDOWN)
if rules.countdown_ticks <= 0:
_start()
COUNTDOWN:
if participants.size() < rules.min_players:
_enter(LOBBY)
elif phase_ticks >= rules.countdown_ticks:
_start()
DROP, PLAY:
sim.step()
_collect_eliminations()
if phase == DROP and sim.drop.finished:
_enter(PLAY)
_check_finished()
RESULTS:
if phase_ticks >= rules.results_ticks:
_reset()
func _enter(next: int) -> void:
events.append({"type": "phase", "from": PHASE_NAMES[phase], "to": PHASE_NAMES[next], "match": current_seed()})
phase = next
phase_ticks = 0
## Fills empty places with bots, puts every participant on the barge and places loot.
func _start() -> void:
if rules.fill_with_bots:
while participants.size() < rules.max_players:
var handle: int = _next_bot_handle
_next_bot_handle -= 1
join(handle, true)
var size: int = maxi(rules.team_size, 1)
for index: int in participants.size():
var handle: int = participants[index]
var entity_id: int = sim.add_player()
entity_of[handle] = entity_id
handle_of[entity_id] = handle
team_of[handle] = index / size
_match_size = participants.size()
sim.start_drop()
sim.place_loot()
matches_started += 1
_enter(DROP)
events.append({"type": "match_started", "match": current_seed(), "index": matches_started - 1, "players": participants.size()})
_check_finished()
func _collect_eliminations() -> void:
for event: Dictionary in sim.events:
if event["type"] != "eliminated" or not handle_of.has(event["player"]):
continue
var by: int = int(handle_of.get(event["by"], 0))
_place(handle_of[event["player"]], by, false)
## Records a participant's finishing place: one more than the players left after them.
func _place(handle: int, by: int, left: bool) -> void:
for placed: Dictionary in placements:
if placed["handle"] == handle:
return
var place: int = _match_size - placements.size()
var record: Dictionary = {"handle": handle, "place": place, "by": by, "left": left}
placements.append(record)
var event: Dictionary = record.duplicate()
event["type"] = "placed"
events.append(event)
## Ends the match when at most one team has anyone standing.
func _check_finished() -> void:
if not in_match():
return
var teams: Dictionary = {}
for handle: int in alive():
teams[team_of[handle]] = true
if teams.size() > 1:
return
winners.clear()
for handle: int in alive():
winners.append(handle)
# Winners take first place, after everyone eliminated.
for handle: int in winners:
placements.append({"handle": handle, "place": 1, "by": 0, "left": false})
_enter(RESULTS)
events.append({"type": "match_ended", "match": current_seed(), "winners": winners.duplicate()})
## Back to the lobby: bots leave, the match's bookkeeping is cleared, and the next
## match's island is generated.
func _reset() -> void:
for handle: int in bot_handles.keys():
participants.erase(handle)
bot_handles.clear()
entity_of.clear()
handle_of.clear()
team_of.clear()
placements.clear()
winners.clear()
_next_bot_handle = FIRST_BOT_HANDLE
_match_size = 0
sim = Simulation.new(match_seed(matches_started))
_enter(LOBBY)
+1
View File
@@ -0,0 +1 @@
uid://dgeu4ua1a0qgm
+26
View File
@@ -0,0 +1,26 @@
## How a server runs its matches: lobby size, timers and team size. Defaults come from
## Tuning; a server or test changes them per instance.
class_name MatchRules
extends RefCounted
## The most participants in one match, bots included.
var max_players: int = Tuning.SOLO_PLAYERS
## The lobby counts down once this many participants have joined.
var min_players: int = Tuning.MATCH_MIN_PLAYERS
## Players on a team. 1 is solo.
var team_size: int = 1
## With enough players, the lobby waits this long for more before counting down. A
## full lobby counts down at once.
var lobby_ticks: int = roundi(Tuning.MATCH_LOBBY_SECONDS * Tuning.TICK_RATE_HZ)
var countdown_ticks: int = roundi(Tuning.MATCH_COUNTDOWN_SECONDS * Tuning.TICK_RATE_HZ)
var results_ticks: int = roundi(Tuning.MATCH_RESULTS_SECONDS * Tuning.TICK_RATE_HZ)
## Fill empty places with bots when the match starts.
var fill_with_bots: bool = true
## Rules for a server that skips the lobby: the match starts on the first tick.
static func immediate() -> MatchRules:
var rules: MatchRules = MatchRules.new()
rules.lobby_ticks = 0
rules.countdown_ticks = 0
return rules
+1
View File
@@ -0,0 +1 @@
uid://c8liu74vanogc
+9
View File
@@ -16,6 +16,15 @@ const DUO_TEAMS: int = 12
const DUO_TEAM_SIZE: int = 2
const REVIVE_SECONDS: float = 6.0
# Match flow, in seconds. See Match and MatchRules, which can override each one.
## The lobby counts down once this many participants have joined.
const MATCH_MIN_PLAYERS: int = 1
## With enough players, the lobby waits this long for more before counting down.
const MATCH_LOBBY_SECONDS: float = 20.0
const MATCH_COUNTDOWN_SECONDS: float = 10.0
## Results stay up this long before the server returns to the lobby.
const MATCH_RESULTS_SECONDS: float = 15.0
# Player
const PLAYER_MAX_HEALTH: int = 100
const PLAYER_MAX_ARMOR: int = 100