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:
@@ -0,0 +1,47 @@
|
||||
## Owns every entity. IDs count up from 1 and are never reused within a match, and
|
||||
## iteration is always in ascending ID order.
|
||||
class_name EntityRegistry
|
||||
extends RefCounted
|
||||
|
||||
## Reserved: no entity has this ID.
|
||||
const NONE: int = 0
|
||||
|
||||
var _next_id: int = 1
|
||||
var _by_id: Dictionary = {}
|
||||
|
||||
|
||||
func create(archetype: int) -> SimEntity:
|
||||
var entity: SimEntity = SimEntity.new(_next_id, archetype)
|
||||
_next_id += 1
|
||||
# Dictionaries keep insertion order, and IDs only grow, so this stays sorted.
|
||||
_by_id[entity.id] = entity
|
||||
return entity
|
||||
|
||||
|
||||
## Returns the entity, or null if it doesn't exist or has been removed.
|
||||
func find(id: int) -> SimEntity:
|
||||
return _by_id.get(id)
|
||||
|
||||
|
||||
func remove(id: int) -> bool:
|
||||
return _by_id.erase(id)
|
||||
|
||||
|
||||
func contains(id: int) -> bool:
|
||||
return _by_id.has(id)
|
||||
|
||||
|
||||
func count() -> int:
|
||||
return _by_id.size()
|
||||
|
||||
|
||||
func next_id() -> int:
|
||||
return _next_id
|
||||
|
||||
|
||||
## All entities in ascending ID order. Safe to modify the registry while looping over this.
|
||||
func entities() -> Array[SimEntity]:
|
||||
var all: Array[SimEntity] = []
|
||||
for entity: SimEntity in _by_id.values():
|
||||
all.append(entity)
|
||||
return all
|
||||
@@ -0,0 +1 @@
|
||||
uid://b5d0n6yjh2qqd
|
||||
@@ -0,0 +1,99 @@
|
||||
## One tick of one player's intent. Humans, bots and network clients all produce these.
|
||||
## See "Player command stream" in docs/ARCHITECTURE.md.
|
||||
class_name PlayerCommand
|
||||
extends RefCounted
|
||||
|
||||
const ENCODED_SIZE: int = 14
|
||||
|
||||
const BUTTON_FIRE: int = 1 << 0
|
||||
const BUTTON_AIM: int = 1 << 1
|
||||
const BUTTON_JUMP: int = 1 << 2
|
||||
const BUTTON_CROUCH: int = 1 << 3
|
||||
const BUTTON_SPRINT: int = 1 << 4
|
||||
const BUTTON_RELOAD: int = 1 << 5
|
||||
const BUTTON_INTERACT: int = 1 << 6
|
||||
const BUTTON_BUILD: int = 1 << 7
|
||||
|
||||
const AXIS_MAX: int = 127
|
||||
const YAW_STEPS: int = 65536
|
||||
const PITCH_MAX: int = 32767
|
||||
|
||||
var tick: int = 0
|
||||
var move_x: int = 0
|
||||
var move_y: int = 0
|
||||
var yaw: int = 0
|
||||
var pitch: int = 0
|
||||
var buttons: int = 0
|
||||
var selection: int = 0
|
||||
var material: int = 0
|
||||
|
||||
|
||||
## Builds a command from real-valued input, clamping every field into range.
|
||||
static func from_input(
|
||||
at_tick: int,
|
||||
move: Vector2,
|
||||
yaw_radians: float,
|
||||
pitch_radians: float,
|
||||
pressed: int = 0,
|
||||
selected: int = 0,
|
||||
chosen_material: int = 0,
|
||||
) -> PlayerCommand:
|
||||
var command: PlayerCommand = PlayerCommand.new()
|
||||
command.tick = at_tick
|
||||
command.move_x = roundi(clampf(move.x, -1.0, 1.0) * AXIS_MAX)
|
||||
command.move_y = roundi(clampf(move.y, -1.0, 1.0) * AXIS_MAX)
|
||||
command.yaw = posmod(roundi(yaw_radians / TAU * YAW_STEPS), YAW_STEPS)
|
||||
command.pitch = clampi(roundi(pitch_radians / (PI * 0.5) * PITCH_MAX), -PITCH_MAX, PITCH_MAX)
|
||||
command.buttons = pressed
|
||||
command.selection = selected
|
||||
command.material = chosen_material
|
||||
return command
|
||||
|
||||
|
||||
## Returns the movement axes, scaled to -1..1, with diagonals no faster than straight lines.
|
||||
func move_vector() -> Vector2:
|
||||
return Vector2(move_x, move_y) / float(AXIS_MAX)
|
||||
|
||||
|
||||
func yaw_radians() -> float:
|
||||
return float(yaw) / YAW_STEPS * TAU
|
||||
|
||||
|
||||
func pitch_radians() -> float:
|
||||
return float(pitch) / PITCH_MAX * (PI * 0.5)
|
||||
|
||||
|
||||
func is_pressed(button: int) -> bool:
|
||||
return buttons & button != 0
|
||||
|
||||
|
||||
## Encodes to ENCODED_SIZE bytes, little-endian. Out-of-range fields are clamped.
|
||||
func encode() -> PackedByteArray:
|
||||
var bytes: PackedByteArray = PackedByteArray()
|
||||
bytes.resize(ENCODED_SIZE)
|
||||
bytes.encode_u32(0, tick & 0xFFFFFFFF)
|
||||
bytes.encode_s8(4, clampi(move_x, -AXIS_MAX, AXIS_MAX))
|
||||
bytes.encode_s8(5, clampi(move_y, -AXIS_MAX, AXIS_MAX))
|
||||
bytes.encode_u16(6, posmod(yaw, YAW_STEPS))
|
||||
bytes.encode_s16(8, clampi(pitch, -PITCH_MAX, PITCH_MAX))
|
||||
bytes.encode_u16(10, buttons & 0xFFFF)
|
||||
bytes.encode_u8(12, selection & 0xFF)
|
||||
bytes.encode_u8(13, material & 0xFF)
|
||||
return bytes
|
||||
|
||||
|
||||
## Decodes a command at `offset`, or returns null if the buffer is too short.
|
||||
## Values from the wire are clamped, so a hostile client can't exceed the valid range.
|
||||
static func decode(bytes: PackedByteArray, offset: int = 0) -> PlayerCommand:
|
||||
if offset < 0 or offset + ENCODED_SIZE > bytes.size():
|
||||
return null
|
||||
var command: PlayerCommand = PlayerCommand.new()
|
||||
command.tick = bytes.decode_u32(offset)
|
||||
command.move_x = clampi(bytes.decode_s8(offset + 4), -AXIS_MAX, AXIS_MAX)
|
||||
command.move_y = clampi(bytes.decode_s8(offset + 5), -AXIS_MAX, AXIS_MAX)
|
||||
command.yaw = bytes.decode_u16(offset + 6)
|
||||
command.pitch = clampi(bytes.decode_s16(offset + 8), -PITCH_MAX, PITCH_MAX)
|
||||
command.buttons = bytes.decode_u16(offset + 10)
|
||||
command.selection = bytes.decode_u8(offset + 12)
|
||||
command.material = bytes.decode_u8(offset + 13)
|
||||
return command
|
||||
@@ -0,0 +1 @@
|
||||
uid://6cm8jy0sdyp0
|
||||
@@ -0,0 +1,18 @@
|
||||
## One object in the simulation. IDs are assigned by EntityRegistry and never change.
|
||||
class_name SimEntity
|
||||
extends RefCounted
|
||||
|
||||
const ARCHETYPE_PLAYER: int = 1
|
||||
|
||||
var id: int = 0
|
||||
var archetype: int = 0
|
||||
var position: Vector3 = Vector3.ZERO
|
||||
var velocity: Vector3 = Vector3.ZERO
|
||||
var yaw: int = 0
|
||||
var pitch: int = 0
|
||||
var health: int = 0
|
||||
|
||||
|
||||
func _init(entity_id: int, entity_archetype: int) -> void:
|
||||
id = entity_id
|
||||
archetype = entity_archetype
|
||||
@@ -0,0 +1 @@
|
||||
uid://bqogpyfd311pn
|
||||
@@ -0,0 +1,46 @@
|
||||
## The match's seeded randomness. Each system draws from its own named stream, so one
|
||||
## system's extra rolls can't change what another rolls.
|
||||
class_name SimRng
|
||||
extends RefCounted
|
||||
|
||||
const FNV_PRIME: int = 16777619
|
||||
const FNV_OFFSET_LOW: int = 2166136261
|
||||
const FNV_OFFSET_HIGH: int = 3735928559
|
||||
const MASK_32: int = 0xFFFFFFFF
|
||||
|
||||
var match_seed: int = 0
|
||||
|
||||
var _streams: Dictionary = {}
|
||||
|
||||
|
||||
func _init(seed_value: int) -> void:
|
||||
match_seed = seed_value
|
||||
|
||||
|
||||
## Returns the named stream, creating it on first use.
|
||||
func stream(stream_name: String) -> RandomNumberGenerator:
|
||||
if not _streams.has(stream_name):
|
||||
var rng: RandomNumberGenerator = RandomNumberGenerator.new()
|
||||
rng.seed = match_seed ^ _hash_name(stream_name)
|
||||
_streams[stream_name] = rng
|
||||
return _streams[stream_name]
|
||||
|
||||
|
||||
## Stream names, sorted, so that state can be hashed in a stable order.
|
||||
func stream_names() -> Array[String]:
|
||||
var names: Array[String] = []
|
||||
for key: String in _streams:
|
||||
names.append(key)
|
||||
names.sort()
|
||||
return names
|
||||
|
||||
|
||||
## 64-bit name hash built from two 32-bit FNV-1a passes. It stays within 64-bit signed
|
||||
## arithmetic, and doesn't rely on String.hash(), which can change between engine versions.
|
||||
static func _hash_name(text: String) -> int:
|
||||
var low: int = FNV_OFFSET_LOW
|
||||
var high: int = FNV_OFFSET_HIGH
|
||||
for byte: int in text.to_utf8_buffer():
|
||||
low = ((low ^ byte) * FNV_PRIME) & MASK_32
|
||||
high = ((high ^ (byte + 1)) * FNV_PRIME) & MASK_32
|
||||
return (high << 32) | low
|
||||
@@ -0,0 +1 @@
|
||||
uid://dtl1a4nii45cq
|
||||
@@ -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()
|
||||
@@ -0,0 +1 @@
|
||||
uid://c33yi2km6174w
|
||||
@@ -5,6 +5,10 @@ extends RefCounted
|
||||
|
||||
# Simulation
|
||||
const TICK_RATE_HZ: int = 30
|
||||
## Commands further ahead of the current tick than this are rejected.
|
||||
const MAX_COMMAND_LEAD_TICKS: int = 60
|
||||
## Width and depth of the playable world. Positions are clamped inside it.
|
||||
const WORLD_SIZE_METRES: float = 1024.0
|
||||
|
||||
# Match sizes
|
||||
const SOLO_PLAYERS: int = 24
|
||||
|
||||
Reference in New Issue
Block a user