M8: Complete offline match

`make match` plays one whole match from the lobby to the results and back to the
lobby: one scripted player and 23 bots on a local server, with no script errors.

- CommandLog records the seed, the rules and every command the server is given.
  MatchReplay plays a log again with nobody thinking and ends on the same state
  hash; `make match` saves the log, reads it back and checks that.
- ServerLoop.submit() is now the one way commands reach the simulation, so a
  recording server sees them all.
- ScriptedPlayer plays a human seat: it drops, loots, fights and flees as a bot
  does, and also cuts driftwood and builds a breakwater and a wall.
- Bots draw randomness from their own per-bot generators, not the simulation's
  streams. A bot thinking no longer changes the simulation's state, which a
  replay without bots needs.
- MatchView and EntityView draw a match from one Simulation: terrain, sea,
  points of interest, props, pieces, players, the barge, items and chests, with
  stand-in shapes for the art pass to replace.
- `make match-captures` renders eight stages of the recorded match.

Closes #31

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 05:35:32 -05:00
co-authored by Claude Opus 5.5
parent 8cf164d562
commit 1d6a24ab64
38 changed files with 1633 additions and 15 deletions
+178
View File
@@ -0,0 +1,178 @@
## A match's seed, rules and every command the server was given, in the order it got
## them. With the same engine build that is enough to play the match again exactly:
## the simulation takes nothing else in. See MatchReplay.
##
## Each record is the simulation tick the command arrived on, the handle it came from
## and the command's own 14 bytes. Commands are logged whether or not the simulation
## accepted them, so a replay turns the same ones down.
##
## On disk: "TWCL", a u32 header length, the header as JSON, a u32 length of the raw
## records, then the records compressed with Zstandard. The seed is a string in the
## header, because JSON numbers can't hold 63 bits.
class_name CommandLog
extends RefCounted
const MAGIC: String = "TWCL"
const VERSION: int = 1
## at-tick u32, handle s32, then the command.
const RECORD_SIZE: int = 8 + PlayerCommand.ENCODED_SIZE
## Refuse files that claim more than this many raw bytes: about four full matches.
const MAX_RAW_BYTES: int = 64 * 1024 * 1024
const RULE_KEYS: Array[String] = [
"max_players", "min_players", "team_size", "lobby_ticks", "countdown_ticks", "results_ticks", "fill_with_bots",
]
var session_seed: int = 0
## Human participants, who join with handles 1 and up before the first tick.
var humans: int = 0
var rules: MatchRules = MatchRules.new()
## What the recording ended with: the simulation tick, its state hash and the winning
## handles. `final_hash` is empty for a recording that was never finished.
var final_tick: int = 0
var final_hash: String = ""
var winners: Array[int] = []
## Free-form notes for whoever reads the file: bot count, difficulty and so on. Not
## needed to replay.
var notes: Dictionary = {}
var _records: StreamPeerBuffer = StreamPeerBuffer.new()
func _init(seed_value: int = 0, human_players: int = 0, match_rules: MatchRules = null) -> void:
session_seed = seed_value
humans = human_players
if match_rules != null:
rules = match_rules
_records.big_endian = false
func count() -> int:
return _records.get_size() / RECORD_SIZE
## Adds a command that arrived from `handle` while the simulation was at `at_tick`.
func record(at_tick: int, handle: int, command: PlayerCommand) -> void:
_records.seek(_records.get_size())
_records.put_u32(at_tick)
_records.put_32(handle)
_records.put_data(command.encode())
func at_tick_of(index: int) -> int:
return _records.data_array.decode_u32(index * RECORD_SIZE)
func handle_of(index: int) -> int:
return _records.data_array.decode_s32(index * RECORD_SIZE + 4)
func command_of(index: int) -> PlayerCommand:
return PlayerCommand.decode(_records.data_array, index * RECORD_SIZE + 8)
## Marks the recording finished with the state it reached.
func finish(flow: Match) -> void:
final_tick = flow.sim.tick
final_hash = flow.sim.state_hash()
winners = flow.winners.duplicate()
func header() -> Dictionary:
var rule_values: Dictionary = {}
for key: String in RULE_KEYS:
rule_values[key] = rules.get(key)
return {
"version": VERSION,
"engine": Engine.get_version_info()["string"],
"seed": str(session_seed),
"humans": humans,
"rules": rule_values,
"records": count(),
"final_tick": final_tick,
"final_hash": final_hash,
"winners": winners,
"notes": notes,
}
func to_bytes() -> PackedByteArray:
var head: PackedByteArray = JSON.stringify(header()).to_utf8_buffer()
var raw: PackedByteArray = _records.data_array
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
out.put_data(MAGIC.to_ascii_buffer())
out.put_u32(head.size())
out.put_data(head)
out.put_u32(raw.size())
if raw.size() > 0:
out.put_data(raw.compress(FileAccess.COMPRESSION_ZSTD))
return out.data_array
## Reads a log back, or returns null if the bytes aren't a usable log. Nothing in a bad
## file can raise an error: every length is checked before it is used.
static func from_bytes(bytes: PackedByteArray) -> CommandLog:
if bytes.size() < 12 or bytes.slice(0, 4).get_string_from_ascii() != MAGIC:
return null
var head_size: int = bytes.decode_u32(4)
if head_size <= 0 or 8 + head_size + 4 > bytes.size():
return null
var parser: JSON = JSON.new()
if parser.parse(bytes.slice(8, 8 + head_size).get_string_from_utf8()) != OK or not parser.data is Dictionary:
return null
var head: Dictionary = parser.data
if int(head.get("version", 0)) != VERSION or not head.get("rules") is Dictionary or not str(head.get("seed", "")).is_valid_int():
return null
var raw_size: int = bytes.decode_u32(8 + head_size)
if raw_size < 0 or raw_size > MAX_RAW_BYTES or raw_size % RECORD_SIZE != 0:
return null
var raw: PackedByteArray = PackedByteArray()
if raw_size > 0:
var packed: PackedByteArray = bytes.slice(12 + head_size)
if packed.is_empty():
return null
raw = packed.decompress(raw_size, FileAccess.COMPRESSION_ZSTD)
if raw.size() != raw_size:
return null
var result: CommandLog = CommandLog.new(str(head["seed"]).to_int(), clampi(int(head.get("humans", 0)), 0, Tuning.SOLO_PLAYERS))
var rule_values: Dictionary = head["rules"]
for key: String in RULE_KEYS:
if not rule_values.has(key):
return null
if key == "fill_with_bots":
result.rules.fill_with_bots = bool(rule_values[key])
else:
result.rules.set(key, int(rule_values[key]))
result.rules.max_players = clampi(result.rules.max_players, 1, Tuning.SOLO_PLAYERS)
result.rules.team_size = maxi(result.rules.team_size, 1)
result.final_tick = int(head.get("final_tick", 0))
result.final_hash = str(head.get("final_hash", ""))
if head.get("winners") is Array:
for winner: Variant in head["winners"]:
result.winners.append(int(winner))
if head.get("notes") is Dictionary:
result.notes = head["notes"]
result._records.data_array = raw
return result
## Writes the log to `path`, creating its folder. Returns OK or the error.
func save(path: String) -> Error:
var folder: String = path.get_base_dir()
if not DirAccess.dir_exists_absolute(folder):
var made: Error = DirAccess.make_dir_recursive_absolute(folder)
if made != OK:
return made
var file: FileAccess = FileAccess.open(path, FileAccess.WRITE)
if file == null:
return FileAccess.get_open_error()
file.store_buffer(to_bytes())
file.close()
return OK
## Reads the log at `path`, or returns null if it is missing or unusable.
static func load_from(path: String) -> CommandLog:
if not FileAccess.file_exists(path):
return null
return from_bytes(FileAccess.get_file_as_bytes(path))
+1
View File
@@ -0,0 +1 @@
uid://b0f8jbsbyhwiu
+85
View File
@@ -0,0 +1,85 @@
## Plays a recorded match again from its CommandLog: the same seed, the same rules, the
## same commands on the same ticks, and nobody thinking. Bots and scripted players
## aren't run; their commands are in the log like everyone else's.
##
## The replay covers the log's first match, from the lobby to its results.
class_name MatchReplay
extends RefCounted
var commands: CommandLog
var flow: Match
var sim: Simulation:
get:
return flow.sim
## Server ticks run, lobby and countdown included.
var ticks: int = 0
var _cursor: int = 0
func _init(command_log: CommandLog) -> void:
commands = command_log
flow = Match.new(commands.session_seed, commands.rules)
for handle: int in range(1, commands.humans + 1):
flow.join(handle)
## True once the match's results are in, or the match can't go on.
func finished() -> bool:
return flow.phase == Match.RESULTS
## Runs one server tick. Returns false, doing nothing, once the match has finished.
func step() -> bool:
if finished():
return false
if flow.in_match():
var tick: int = sim.tick
while _cursor < commands.count() and commands.at_tick_of(_cursor) <= tick:
if commands.at_tick_of(_cursor) == tick:
flow.submit_command(commands.handle_of(_cursor), commands.command_of(_cursor))
_cursor += 1
flow.step()
ticks += 1
return true
## Steps until `done` returns true (it is asked before each tick), the match finishes,
## or `limit` server ticks have run. Returns true if `done` was satisfied.
func run_until(done: Callable, limit: int = default_limit()) -> bool:
while ticks < limit:
if done.call():
return true
if not step():
return bool(done.call())
return bool(done.call())
## Steps to the match's results. Returns true if it got there within `limit` ticks.
func run_to_end(limit: int = default_limit()) -> bool:
while ticks < limit and step():
pass
return finished()
## The longest a logged match can take in server ticks: lobby, countdown, the tide's
## whole schedule, and slack.
func default_limit() -> int:
return commands.rules.lobby_ticks + commands.rules.countdown_ticks + Tide.new(0).time_limit_offset() + 60 * Tuning.TICK_RATE_HZ
## Compares where the replay is with what the recording ended on. Call after
## run_to_end(). Returns {"ok", "tick", "expected_tick", "hash", "expected_hash",
## "winners", "expected_winners"}.
func verify() -> Dictionary:
var digest: String = sim.state_hash()
return {
"ok": finished() and not commands.final_hash.is_empty() and digest == commands.final_hash
and sim.tick == commands.final_tick and flow.winners == commands.winners,
"tick": sim.tick,
"expected_tick": commands.final_tick,
"hash": digest,
"expected_hash": commands.final_hash,
"winners": flow.winners.duplicate(),
"expected_winners": commands.winners.duplicate(),
}
+1
View File
@@ -0,0 +1 @@
uid://bbybxusl4dakt
+57 -7
View File
@@ -15,6 +15,10 @@ var sim: Simulation:
## Entity IDs of everyone in the current match, humans first.
var player_ids: Array[int] = []
var bots: Array[BotBrain] = []
## Human seats played by script, when play_humans_by_script() was called.
var scripted: Array[ScriptedPlayer] = []
## When set, every command the server is given during the first match goes in it.
var recorder: CommandLog = null
## The current or next match's navigation grid and bot map, built while the lobby waits.
var nav: NavGrid = null
var world: BotWorld = null
@@ -25,6 +29,8 @@ var tick_usec: PackedInt64Array = PackedInt64Array()
## Server ticks run, across every match.
var ticks: int = 0
var _script_humans: bool = false
## `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
@@ -32,11 +38,7 @@ var ticks: int = 0
func _init(match_seed: int, human_players: int, bot_count: int, rules: MatchRules = null, difficulty: int = -1) -> void:
bot_difficulty = difficulty
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
rules = immediate_rules(human_players, bot_count)
match_flow = Match.new(match_seed, rules)
nav = NavGrid.build(match_flow.sim)
world = BotWorld.build(match_flow.sim, nav)
@@ -47,14 +49,55 @@ func _init(match_seed: int, human_players: int, bot_count: int, rules: MatchRule
_advance()
## Rules for a server that skips the lobby and fills the match with `bot_count` bots.
static func immediate_rules(human_players: int, bot_count: int) -> MatchRules:
var rules: MatchRules = 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
return rules
## Starts recording every command into a new log, which is returned. Call before the
## first tick; the log covers the first match.
func record_commands() -> CommandLog:
var humans: int = 0
for handle: int in match_flow.participants:
if not match_flow.bot_handles.has(handle):
humans += 1
recorder = CommandLog.new(match_flow.session_seed, humans, match_flow.rules)
recorder.notes = {"bot_difficulty": bot_difficulty}
return recorder
## From now on, every human seat is played by a ScriptedPlayer: a stand-in for a
## person at the controls, for whole-match tests before and without the network.
func play_humans_by_script() -> void:
_script_humans = true
if match_flow.in_match():
_track_players()
## Gives the simulation a participant's command for the current match. Returns false
## if it was turned down. This is the one way commands get in, for people, scripts and
## bots alike, so the recorder sees them all.
func submit(handle: int, command: PlayerCommand) -> bool:
if recorder != null and match_flow.matches_started == 1 and match_flow.in_match():
recorder.record(sim.tick, handle, command)
return match_flow.submit_command(handle, command)
## Runs one tick and records how long it took.
func run_tick() -> void:
var started: int = Time.get_ticks_usec()
if match_flow.in_match():
nav.sync(sim)
world.observe(sim)
for player: ScriptedPlayer in scripted:
submit(match_flow.handle_of[player.player_id], player.think(sim, nav, world))
for bot: BotBrain in bots:
sim.submit_command(bot.player_id, bot.think(sim, nav, world))
submit(match_flow.handle_of[bot.player_id], bot.think(sim, nav, world))
_advance()
ticks += 1
tick_usec.append(Time.get_ticks_usec() - started)
@@ -65,9 +108,12 @@ func _advance() -> void:
for event: Dictionary in match_flow.events:
if event["type"] == "match_started":
_track_players()
elif event["type"] == "match_ended" and recorder != null and match_flow.matches_started == 1 and recorder.final_hash.is_empty():
recorder.finish(match_flow)
elif event["type"] == "phase" and event["to"] == "lobby":
player_ids.clear()
bots.clear()
scripted.clear()
if event["from"] == "results":
nav = NavGrid.build(match_flow.sim)
world = BotWorld.build(match_flow.sim, nav)
@@ -76,10 +122,14 @@ func _advance() -> void:
func _track_players() -> void:
player_ids.clear()
bots.clear()
scripted.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):
if not match_flow.bot_handles.has(handle):
if _script_humans:
scripted.append(ScriptedPlayer.new(entity_id))
else:
var level: int = bot_difficulty if bot_difficulty >= 0 else bots.size() % Tuning.BOT_DIFFICULTIES.size()
bots.append(BotBrain.new(entity_id, level))
world.player_ids = player_ids.duplicate()