F5: Simulation core and player command stream

Add the fixed-tick Simulation, the EntityRegistry with never-reused IDs, SimRng's named
seeded streams, and the 14-byte PlayerCommand used by humans, bots and the network.
state_hash is a SHA-256 over a canonical encoding of the state. Movement is a flat
placeholder until the v0.2 character controller. Tests replay a 24-player command log
over 10,000 ticks and scan src/sim for unseeded randomness and presentation code.

Closes #5

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-09 17:16:03 -05:00
co-authored by Claude Opus 5.5
parent 16ad1b7754
commit 27e08db51d
21 changed files with 686 additions and 9 deletions
+112
View File
@@ -0,0 +1,112 @@
## The authoritative fixed-tick game state. It takes commands and a seed and nothing
## else: no scene tree, no wall clock, no unseeded randomness.
##
## Movement here is a flat placeholder until the character controller lands in v0.2.
class_name Simulation
extends RefCounted
const SECONDS_PER_TICK: float = 1.0 / Tuning.TICK_RATE_HZ
var tick: int = 0
var entities: EntityRegistry = EntityRegistry.new()
var rng: SimRng
## Player entity ID -> { command tick -> PlayerCommand }
var _pending: Dictionary = {}
## Player entity IDs, ascending.
var _players: Array[int] = []
func _init(match_seed: int) -> void:
rng = SimRng.new(match_seed)
## Adds a player at a seeded spawn position and returns its entity ID.
func add_player() -> int:
var player: SimEntity = entities.create(SimEntity.ARCHETYPE_PLAYER)
var spawn: RandomNumberGenerator = rng.stream("spawn")
var size: float = Tuning.WORLD_SIZE_METRES
player.position = Vector3(spawn.randf() * size, 0.0, spawn.randf() * size)
player.health = Tuning.PLAYER_MAX_HEALTH
_players.append(player.id)
_pending[player.id] = {}
return player.id
## Removes a player and any commands queued for it.
func remove_player(player_id: int) -> void:
entities.remove(player_id)
_players.erase(player_id)
_pending.erase(player_id)
## Queues a command for the tick it names. Returns false if it was rejected: the player
## is unknown, the tick has passed, or the tick is too far ahead to be legitimate.
## A later command for the same tick replaces an earlier one.
func submit_command(player_id: int, command: PlayerCommand) -> bool:
if not _pending.has(player_id):
return false
if command.tick < tick or command.tick > tick + Tuning.MAX_COMMAND_LEAD_TICKS:
return false
_pending[player_id][command.tick] = command
return true
## Advances the simulation by one tick.
func step() -> void:
for player_id: int in _players:
var queued: Dictionary = _pending[player_id]
var command: PlayerCommand = queued.get(tick)
queued.erase(tick)
_apply_command(entities.find(player_id), command)
tick += 1
func _apply_command(player: SimEntity, command: PlayerCommand) -> void:
# With no command this tick, the player keeps looking the same way and stands still.
if command == null:
return
player.yaw = command.yaw
player.pitch = command.pitch
var move: Vector2 = command.move_vector()
if move.length() > 1.0:
move = move.normalized()
var angle: float = command.yaw_radians()
var forward: Vector3 = Vector3(sin(angle), 0.0, cos(angle))
var right: Vector3 = Vector3(cos(angle), 0.0, -sin(angle))
var speed: float = (
Tuning.SPRINT_SPEED if command.is_pressed(PlayerCommand.BUTTON_SPRINT)
else Tuning.WALK_SPEED
)
var delta: Vector3 = (right * move.x + forward * move.y) * speed * SECONDS_PER_TICK
var size: float = Tuning.WORLD_SIZE_METRES
player.position = (player.position + delta).clamp(Vector3.ZERO, Vector3(size, 0.0, size))
## SHA-256 hex digest of a canonical encoding of the whole state.
func state_hash() -> String:
var buffer: StreamPeerBuffer = StreamPeerBuffer.new()
buffer.big_endian = false
buffer.put_64(tick)
buffer.put_64(entities.next_id())
buffer.put_64(rng.match_seed)
for stream_name: String in rng.stream_names():
buffer.put_utf8_string(stream_name)
buffer.put_64(rng.stream(stream_name).state)
buffer.put_64(entities.count())
for entity: SimEntity in entities.entities():
buffer.put_64(entity.id)
buffer.put_32(entity.archetype)
buffer.put_32(entity.health)
buffer.put_32(entity.yaw)
buffer.put_32(entity.pitch)
for value: float in [entity.position.x, entity.position.y, entity.position.z]:
buffer.put_64(roundi(value * 1000.0))
for value: float in [entity.velocity.x, entity.velocity.y, entity.velocity.z]:
buffer.put_64(roundi(value * 1000.0))
var hasher: HashingContext = HashingContext.new()
hasher.start(HashingContext.HASH_SHA256)
hasher.update(buffer.data_array)
return hasher.finish().hex_encode()