Files
tidewall/src/net/net_world.gd
T
claudeandClaude Opus 5.5 0ddcb48ea0 H13: Say which part of the world differs when a soak hash does
When a client's world hash differs from the server's, the soak report
now names the part that differs (tide, props, pieces or loot), the
client's ClientWorld tick, and each piece whose entry differs on the
two sides, so the next transient mismatch can be traced.

- NetWorld.world_detail(): part hashes and a piece list. world_hash()
  is unchanged: the same bytes, hashed in four parts.
- The server's world_hash log lines and the soak clients' hash lines
  carry the detail.

A full soak with this (24 clients, 2 matches) compared 3,743 hashes
with 0 differing, so the mismatch didn't come back to trace yet.

Refs #80

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-13 11:46:35 -05:00

349 lines
14 KiB
GDScript

## 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 hasher: HashingContext = HashingContext.new()
hasher.start(HashingContext.HASH_SHA256)
for part: PackedByteArray in _world_parts(sim):
hasher.update(part)
return hasher.finish().hex_encode()
## The same state as world_hash(), hashed part by part ("tide", "props", "pieces",
## "loot"), with "piece_list": every piece as [id, health, build_ticks_left, grounded,
## placed_tick, kind, owner], in ID order. For telling where a client and the server
## disagree.
static func world_detail(sim: Simulation) -> Dictionary:
var parts: Array[PackedByteArray] = _world_parts(sim)
var detail: Dictionary = {}
var names: Array[String] = ["tide", "props", "pieces", "loot"]
for index: int in names.size():
var hasher: HashingContext = HashingContext.new()
hasher.start(HashingContext.HASH_SHA256)
hasher.update(parts[index])
detail[names[index]] = hasher.finish().hex_encode().substr(0, 12)
var piece_list: Array = []
var piece_ids: Array = sim.structures.pieces.keys()
piece_ids.sort()
for piece_id: int in piece_ids:
var piece: StructureSet.Piece = sim.structures.pieces[piece_id]
piece_list.append([piece.id, piece.health, piece.build_ticks_left, 1 if piece.grounded else 0, piece.placed_tick, piece.kind, piece.owner])
detail["piece_list"] = piece_list
return detail
## The bytes world_hash() hashes, in four parts: tide, props, pieces and loot. Their
## concatenation is the same buffer the hash has always covered.
static func _world_parts(sim: Simulation) -> Array[PackedByteArray]:
var tide: StreamPeerBuffer = _buffer()
tide.put_64(sim.tide.started_tick if sim.tide != null else -1)
if sim.tide != null:
tide.put_data(sim.tide.levels.to_byte_array())
var props: StreamPeerBuffer = _buffer()
props.put_64(sim.props.count())
props.put_data(sim.props.health.to_byte_array())
var pieces: StreamPeerBuffer = _buffer()
var piece_ids: Array = sim.structures.pieces.keys()
piece_ids.sort()
pieces.put_64(piece_ids.size())
for piece_id: int in piece_ids:
var piece: StructureSet.Piece = sim.structures.pieces[piece_id]
pieces.put_64(piece.id)
pieces.put_u8(piece.kind)
pieces.put_u8(piece.material)
pieces.put_u8(piece.facing)
for value: int in [piece.slot.x, piece.slot.y, piece.slot.z, piece.slot.w]:
pieces.put_32(value)
pieces.put_64(piece.owner)
pieces.put_32(piece.health)
pieces.put_32(piece.build_ticks_left)
pieces.put_u8(1 if piece.grounded else 0)
pieces.put_64(piece.placed_tick)
var loot: StreamPeerBuffer = _buffer()
sim.loot.write_state(loot)
return [tide.data_array, props.data_array, pieces.data_array, loot.data_array]
static func _buffer() -> StreamPeerBuffer:
var buffer: StreamPeerBuffer = StreamPeerBuffer.new()
buffer.big_endian = false
return buffer
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