N5: Replicate building, world damage, tide and loot

Built pieces, props' health, opened chests and the tide's schedule now reach
clients as WORLD messages on the reliable channel, and each player is told
what they carry as OWN messages.

- NetWorld: the WORLD and OWN wire formats, and world_hash(), a digest of
  everything replicated this way.
- WorldSender: one message after each tick in which something changed, the
  same for everyone, and the whole state for someone joining or a new match.
  StructureSet and PropSet keep the change lists it reads.
- ClientWorld: applies them to the client's world, so pieces and broken props
  are solid for prediction. A piece's health follows from its building and
  damage, so building costs nothing on the wire.
- Placing ahead of the server: a provisional piece goes up with the command
  and is replaced by the server's, or taken back once a snapshot shows the
  server had its chance. Snapshots carry the newest WORLD number for that.
- Protocol version 3.

A test plays a whole scripted match on a real island with a ClientGame
attached and compares the two worlds' hashes throughout.

Closes #36

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-12 14:27:58 -05:00
co-authored by Claude Opus 5.5
parent 63ef7b1968
commit 6b21e9d4f1
24 changed files with 1547 additions and 42 deletions
+310
View File
@@ -0,0 +1,310 @@
## The parts of a match that aren't entities, on the wire: built pieces, damaged and
## broken props, opened chests and the tide's schedule (WORLD), and what a client's own
## player carries (OWN). Both go on channel 0, reliably and in order, because a wall
## the client never heard about is a lie it would keep walking into.
##
## server -> WORLD
## u8 type, u8 flags (FLAG_ bits), u32 sequence number, u32 simulation tick,
## if FLAG_TIDE: u32 the tick the tide started, u8 level count, then f32 levels,
## varint count, then new pieces: varint ID, u8 (kind | material << 3 | facing << 5),
## s16 slot x, s8 slot level, s16 slot z, u8 slot type, varint owner entity,
## u32 the tick it was placed, varint ticks of building done, varint damage taken,
## varint count, then damaged pieces: varint ID, varint damage taken so far,
## varint count, then removed pieces: varint ID,
## varint count, then props: varint prop, varint health left,
## varint count, then opened chests: varint index
## server -> OWN
## u8 type, u32 simulation tick, u8 held selection,
## u8 count, then u16 of each material,
## u8 count, then slots: u8 item code plus one, u16 count, u16 rounds, u8 tier,
## u8 count, then u16 of each ammunition
##
## A WORLD with FLAG_FULL is the whole state: the client forgets what it had first. The
## others are changes, numbered one after another from the last full one. A piece's
## health isn't sent: it follows from how far its building had got at the message's
## tick, the ticks since, and the damage it has taken (StructureSet.set_progress), so a
## piece being built costs nothing to keep up to date.
##
## Decoders return an empty Dictionary for anything malformed and never raise an error.
class_name NetWorld
extends RefCounted
const MSG_WORLD: int = 5
const MSG_OWN: int = 6
## The whole state, not changes: forget everything first.
const FLAG_FULL: int = 1 << 0
## The match's loot has been rolled and placed, so its chests exist.
const FLAG_LOOT: int = 1 << 1
## The tide's schedule follows.
const FLAG_TIDE: int = 1 << 2
const WORLD_HEADER_BYTES: int = 10
## Indices into a decoded piece.
const P_ID: int = 0
const P_KIND: int = 1
const P_MATERIAL: int = 2
const P_FACING: int = 3
const P_SLOT: int = 4
const P_OWNER: int = 5
const P_PLACED: int = 6
const P_DAMAGE: int = 7
## Ticks of building done when the message was made.
const P_ELAPSED: int = 8
## A piece as it travels: see the P_ indices.
static func piece_entry(piece: StructureSet.Piece) -> Array:
return [
piece.id, piece.kind, piece.material, piece.facing, piece.slot, piece.owner, piece.placed_tick,
StructureSet.damage_taken(piece), piece.build_ticks - piece.build_ticks_left,
]
## Builds a WORLD. `message` has "flags", "seq", "tick", and optionally "tide"
## ({"started", "levels"}), "pieces" (piece_entry() arrays), "damaged" and "props"
## (PackedInt32Arrays of pairs), "removed" and "chests" (PackedInt32Arrays).
static func encode_world(message: Dictionary) -> PackedByteArray:
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
var tide: Dictionary = message.get("tide", {})
var flags: int = int(message.get("flags", 0)) & ~FLAG_TIDE
if not tide.is_empty():
flags |= FLAG_TIDE
out.put_u8(MSG_WORLD)
out.put_u8(flags)
out.put_u32(int(message.get("seq", 0)) & 0xFFFFFFFF)
out.put_u32(int(message.get("tick", 0)) & 0xFFFFFFFF)
if not tide.is_empty():
var levels: PackedFloat32Array = tide["levels"]
out.put_u32(int(tide["started"]) & 0xFFFFFFFF)
out.put_u8(levels.size())
for level: float in levels:
out.put_float(level)
var pieces: Array = message.get("pieces", [])
_put_varint(out, pieces.size())
for entry: Array in pieces:
var slot: Vector4i = entry[P_SLOT]
_put_varint(out, int(entry[P_ID]))
out.put_u8(int(entry[P_KIND]) | int(entry[P_MATERIAL]) << 3 | int(entry[P_FACING]) << 5)
out.put_16(slot.x)
out.put_8(slot.y)
out.put_16(slot.z)
out.put_u8(slot.w)
_put_varint(out, int(entry[P_OWNER]))
out.put_u32(int(entry[P_PLACED]) & 0xFFFFFFFF)
_put_varint(out, maxi(int(entry[P_ELAPSED]), 0))
_put_varint(out, maxi(int(entry[P_DAMAGE]), 0))
for key: String in ["damaged", "removed", "props", "chests"]:
var values: PackedInt32Array = message.get(key, PackedInt32Array())
var width: int = 2 if key == "damaged" or key == "props" else 1
_put_varint(out, values.size() / width)
for value: int in values:
_put_varint(out, maxi(value, 0))
return out.data_array
## {"full": bool, "loot": bool, "seq", "tick", "tide": {} or {"started", "levels"},
## "pieces", "damaged", "removed", "props", "chests"} as encode_world() takes them, or
## empty if malformed.
static func decode_world(bytes: PackedByteArray) -> Dictionary:
if bytes.size() < WORLD_HEADER_BYTES + 5 or bytes[0] != MSG_WORLD or bytes[1] > (FLAG_FULL | FLAG_LOOT | FLAG_TIDE):
return {}
var flags: int = bytes[1]
var result: Dictionary = {
"full": flags & FLAG_FULL != 0, "loot": flags & FLAG_LOOT != 0,
"seq": bytes.decode_u32(2), "tick": bytes.decode_u32(6), "tide": {},
}
var cursor: Array[int] = [WORLD_HEADER_BYTES]
if flags & FLAG_TIDE != 0:
if bytes.size() < cursor[0] + 5:
return {}
var count: int = bytes[cursor[0] + 4]
if count != Tide.phase_count() or bytes.size() < cursor[0] + 5 + count * 4:
return {}
var levels: PackedFloat32Array = PackedFloat32Array()
for index: int in count:
var level: float = bytes.decode_float(cursor[0] + 5 + index * 4)
if not is_finite(level):
return {}
levels.append(level)
result["tide"] = {"started": bytes.decode_u32(cursor[0]), "levels": levels}
cursor[0] += 5 + count * 4
var piece_count: int = _read_varint(bytes, cursor)
if piece_count < 0 or piece_count > bytes.size():
return {}
var pieces: Array = []
for _index: int in piece_count:
var piece_id: int = _read_varint(bytes, cursor)
var at: int = cursor[0]
if piece_id <= 0 or at + 7 > bytes.size():
return {}
var packed: int = bytes[at]
var kind: int = packed & 7
var material: int = (packed >> 3) & 3
var slot: Vector4i = Vector4i(bytes.decode_s16(at + 1), bytes.decode_s8(at + 3), bytes.decode_s16(at + 4), bytes[at + 6])
if packed > 0x7F or kind >= StructureSet.KINDS.size() or not Materials.is_valid(material):
return {}
var slot_fits: bool = slot.w == StructureSet.slot_type_of(kind)
if StructureSet.is_wall_kind(kind):
slot_fits = slot.w == StructureSet.SLOT_WALL_X or slot.w == StructureSet.SLOT_WALL_Z
if not slot_fits:
return {}
cursor[0] = at + 7
var owner: int = _read_varint(bytes, cursor)
if owner < 0 or cursor[0] + 4 > bytes.size():
return {}
var placed: int = bytes.decode_u32(cursor[0])
cursor[0] += 4
var elapsed: int = _read_varint(bytes, cursor)
var damage: int = _read_varint(bytes, cursor)
if elapsed < 0 or damage < 0:
return {}
pieces.append([piece_id, kind, material, packed >> 5, slot, owner, placed, damage, elapsed])
result["pieces"] = pieces
for key: String in ["damaged", "removed", "props", "chests"]:
var width: int = 2 if key == "damaged" or key == "props" else 1
var count: int = _read_varint(bytes, cursor)
if count < 0 or count * width > bytes.size():
return {}
var values: PackedInt32Array = PackedInt32Array()
for _index: int in count * width:
var value: int = _read_varint(bytes, cursor)
if value < 0 or value > 0x7FFFFFFF:
return {}
values.append(value)
result[key] = values
if cursor[0] != bytes.size():
return {}
return result
## What a player carries, as OWN sends it.
static func encode_own(player: SimEntity, sim_tick: int) -> PackedByteArray:
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
out.put_u8(MSG_OWN)
out.put_u32(sim_tick & 0xFFFFFFFF)
out.put_u8(clampi(player.selected, 0, 255))
out.put_u8(player.materials.size())
for amount: int in player.materials:
out.put_u16(clampi(amount, 0, 65535))
out.put_u8(player.slot_items.size())
for slot: int in player.slot_items.size():
out.put_u8(clampi(player.slot_items[slot] + 1, 0, 255))
out.put_u16(clampi(player.slot_counts[slot], 0, 65535))
out.put_u16(clampi(player.slot_rounds[slot], 0, 65535))
out.put_u8(clampi(player.slot_tiers[slot], 0, 255))
out.put_u8(player.ammo.size())
for amount: int in player.ammo:
out.put_u16(clampi(amount, 0, 65535))
return out.data_array
## {"tick", "selected", "materials", "slot_items", "slot_counts", "slot_rounds",
## "slot_tiers", "ammo"}, the lists as PackedInt32Arrays, or empty if malformed or not
## the shape this build's players have.
static func decode_own(bytes: PackedByteArray) -> Dictionary:
var materials: int = Materials.NAMES.size()
var slots: int = Inventory.slot_count()
var ammo: int = Tuning.AMMO.size()
if bytes.size() != 9 + materials * 2 + slots * 6 + ammo * 2 or bytes[0] != MSG_OWN:
return {}
if bytes[6] != materials or bytes[7 + materials * 2] != slots or bytes[8 + materials * 2 + slots * 6] != ammo:
return {}
var result: Dictionary = {
"tick": bytes.decode_u32(1), "selected": bytes[5],
"materials": PackedInt32Array(), "slot_items": PackedInt32Array(), "slot_counts": PackedInt32Array(),
"slot_rounds": PackedInt32Array(), "slot_tiers": PackedInt32Array(), "ammo": PackedInt32Array(),
}
var at: int = 7
for _index: int in materials:
result["materials"].append(bytes.decode_u16(at))
at += 2
at += 1
for _index: int in slots:
var item: int = bytes[at] - 1
if item >= ItemCatalog.count():
return {}
result["slot_items"].append(item)
result["slot_counts"].append(bytes.decode_u16(at + 1))
result["slot_rounds"].append(bytes.decode_u16(at + 3))
result["slot_tiers"].append(bytes[at + 5])
at += 6
at += 1
for _index: int in ammo:
result["ammo"].append(bytes.decode_u16(at))
at += 2
if int(result["selected"]) > slots:
return {}
return result
## Puts a decoded OWN into `player`.
static func apply_own(player: SimEntity, own: Dictionary) -> void:
player.selected = own["selected"]
player.materials = (own["materials"] as PackedInt32Array).duplicate()
player.slot_items = (own["slot_items"] as PackedInt32Array).duplicate()
player.slot_counts = (own["slot_counts"] as PackedInt32Array).duplicate()
player.slot_rounds = (own["slot_rounds"] as PackedInt32Array).duplicate()
player.slot_tiers = (own["slot_tiers"] as PackedInt32Array).duplicate()
player.ammo = (own["ammo"] as PackedInt32Array).duplicate()
## SHA-256 hex digest of everything WORLD replicates, as `sim` holds it: the tide's
## schedule, every prop's health, every built piece with its health and building, the
## opened chests and the crates not yet spilled. A client that has applied every WORLD
## up to some tick, and brought its pieces' building up to that tick, agrees with the
## server's simulation at that tick.
static func world_hash(sim: Simulation) -> String:
var buffer: StreamPeerBuffer = StreamPeerBuffer.new()
buffer.big_endian = false
buffer.put_64(sim.tide.started_tick if sim.tide != null else -1)
if sim.tide != null:
buffer.put_data(sim.tide.levels.to_byte_array())
buffer.put_64(sim.props.count())
buffer.put_data(sim.props.health.to_byte_array())
var piece_ids: Array = sim.structures.pieces.keys()
piece_ids.sort()
buffer.put_64(piece_ids.size())
for piece_id: int in piece_ids:
var piece: StructureSet.Piece = sim.structures.pieces[piece_id]
buffer.put_64(piece.id)
buffer.put_u8(piece.kind)
buffer.put_u8(piece.material)
buffer.put_u8(piece.facing)
for value: int in [piece.slot.x, piece.slot.y, piece.slot.z, piece.slot.w]:
buffer.put_32(value)
buffer.put_64(piece.owner)
buffer.put_32(piece.health)
buffer.put_32(piece.build_ticks_left)
buffer.put_u8(1 if piece.grounded else 0)
buffer.put_64(piece.placed_tick)
sim.loot.write_state(buffer)
var hasher: HashingContext = HashingContext.new()
hasher.start(HashingContext.HASH_SHA256)
hasher.update(buffer.data_array)
return hasher.finish().hex_encode()
static func _put_varint(out: StreamPeerBuffer, value: int) -> void:
value &= 0xFFFFFFFF
while value >= 0x80:
out.put_u8(value & 0x7F | 0x80)
value >>= 7
out.put_u8(value)
## Reads a varint of at most five bytes at cursor[0] and moves the cursor past it.
## Returns -1 if the buffer ends first or the number is too long.
static func _read_varint(bytes: PackedByteArray, cursor: Array[int]) -> int:
var value: int = 0
for shift: int in range(0, 35, 7):
if cursor[0] >= bytes.size():
return -1
var byte: int = bytes[cursor[0]]
cursor[0] += 1
value |= (byte & 0x7F) << shift
if byte & 0x80 == 0:
return value & 0xFFFFFFFF
return -1