## Game traffic after the handshake: what a snapshot of the world looks like on the ## wire, the input packet a client answers with, and the match notice. ## ## An entity travels as a **record**: a PackedInt32Array of whole numbers, already ## quantized, laid out per archetype (see the R_ constants). The server compares records ## to decide what changed, the wire carries only the changed field groups, and the ## client keeps records as its picture of the world. Everything is little-endian. ## ## server -> SNAPSHOT (channel 1, unreliable) ## u8 type, u32 server tick, u32 baseline tick (0 = none), u32 simulation tick, ## u32 newest command tick received from this client plus one (0 = none yet), ## u32 the sequence number of the newest WORLD message made (see NetWorld), ## varint the entity the client is watching (its own player, or the one it ## spectates; 0 = none), u8 match phase, u8 tide phase, s16 sea level in centimetres, ## u8 1 if the client's own block follows, then that block (see SELF_BYTES), ## u8 removed count, then entity IDs as varints, ## u16 record count, then per record: varint ID, u8 (archetype << 5 | group mask), ## then the fields of each group in the mask ## client -> INPUT (channel 1, unreliable) ## u8 type, u32 tick of the newest snapshot it holds (0 = send a full one), ## u8 command count, then that many 15-byte PlayerCommands, oldest first ## server -> MATCH (channel 0, reliable) ## u8 type, u8 match phase, u32 match index, s64 match seed ## ## Decoders return an empty Dictionary for anything malformed and never raise an error. class_name NetSnapshot extends RefCounted const MSG_MATCH: int = 4 const MSG_SNAPSHOT: int = 16 const MSG_INPUT: int = 17 ## The server tick counts every tick the server has run and never goes back, so it ## orders snapshots across matches. The simulation tick is the one commands name. const HEADER_BYTES: int = 21 const MATCH_BYTES: int = 14 ## The client's own block: what it needs to predict its own player and nobody else is ## told. Exact, not quantized, so a prediction made from it matches the server's to the ## bit: position and velocity (three f32 each, which is all a Vector3 holds), the water ## level around the player (f64), which of the nine flood cells around the player that ## water reaches (u16), swimming stamina in ticks (u16) and the player's FLAG_ bits (u8). const SELF_BYTES: int = 37 ## Every bit of the nine-cell water mask. const WATER_EVERYWHERE: int = 0x1FF ## The most commands one INPUT may carry. Clients send fewer; see Tuning. const MAX_INPUT_COMMANDS: int = 8 ## Positions are quantized to 1/64 m (about 1.5 cm) in a u16 per axis: 1,024 m across, ## and heights from Y_OFFSET metres below zero to 1,024 less that above. const POSITION_STEPS_PER_METRE: float = 64.0 const Y_OFFSET_METRES: float = 128.0 # Record layouts. Index 0 is always the archetype and 1 to 3 the position. const R_ARCHETYPE: int = 0 const R_X: int = 1 const R_Y: int = 2 const R_Z: int = 3 # Players. const R_YAW: int = 4 ## Pitch in steps of 1/127 of a right angle. const R_PITCH: int = 5 const R_HEALTH: int = 6 const R_ARMOR: int = 7 const R_FLAGS: int = 8 ## The held item's catalog code plus one; 0 is the boathook. const R_HELD: int = 9 # Pickups and projectiles: the item's catalog code plus one. const R_ITEM: int = 4 # Pickups. const R_COUNT: int = 5 const R_TIER: int = 6 # Projectiles: the entity that fired it. const R_OWNER: int = 5 const FLAG_ON_GROUND: int = 1 << 0 const FLAG_CROUCHING: int = 1 << 1 const FLAG_SWIMMING: int = 1 << 2 const FLAG_ELIMINATED: int = 1 << 3 ## Two bits: Drop.NONE, ABOARD, FREEFALL or GLIDING. const FLAG_DROP_SHIFT: int = 4 const FLAG_RELOADING: int = 1 << 6 const FLAG_USING: int = 1 << 7 const _U8: int = 0 const _S8: int = 1 const _U16: int = 2 const _U32: int = 3 const _WIDTH: Array[int] = [1, 1, 2, 4] ## Per archetype: the wire type of every record index. const _TYPES: Dictionary = { SimEntity.ARCHETYPE_PLAYER: [_U8, _U16, _U16, _U16, _U16, _S8, _U8, _U8, _U8, _U8], SimEntity.ARCHETYPE_PICKUP: [_U8, _U16, _U16, _U16, _U8, _U16, _U8], SimEntity.ARCHETYPE_PROJECTILE: [_U8, _U16, _U16, _U16, _U8, _U32], } ## Per archetype: the record indices in each field group. Bit n of a mask is group n. const _GROUPS: Dictionary = { SimEntity.ARCHETYPE_PLAYER: [[1, 2, 3], [4, 5], [6, 7], [8], [9]], SimEntity.ARCHETYPE_PICKUP: [[1, 2, 3], [4, 5, 6]], SimEntity.ARCHETYPE_PROJECTILE: [[1, 2, 3], [4, 5]], } static func known_archetype(archetype: int) -> bool: return _TYPES.has(archetype) ## The mask with every group of `archetype` set. static func full_mask(archetype: int) -> int: return (1 << (_GROUPS[archetype] as Array).size()) - 1 ## The record for an entity as it stands, or an empty array for an archetype that isn't ## replicated. static func record_of(entity: SimEntity) -> PackedInt32Array: var record: PackedInt32Array = PackedInt32Array() if not _TYPES.has(entity.archetype): return record record.resize((_TYPES[entity.archetype] as Array).size()) record[R_ARCHETYPE] = entity.archetype record[R_X] = _quantize(entity.position.x) record[R_Y] = _quantize(entity.position.y + Y_OFFSET_METRES) record[R_Z] = _quantize(entity.position.z) match entity.archetype: SimEntity.ARCHETYPE_PLAYER: record[R_YAW] = posmod(entity.yaw, PlayerCommand.YAW_STEPS) record[R_PITCH] = clampi(roundi(float(entity.pitch) / PlayerCommand.PITCH_MAX * 127.0), -127, 127) record[R_HEALTH] = clampi(entity.health, 0, 255) record[R_ARMOR] = clampi(entity.armor, 0, 255) record[R_FLAGS] = flags_of(entity) var held: int = -1 if entity.selected >= 1 and entity.selected <= entity.slot_items.size(): held = entity.slot_items[entity.selected - 1] record[R_HELD] = clampi(held + 1, 0, 255) SimEntity.ARCHETYPE_PICKUP: record[R_ITEM] = clampi(entity.item + 1, 0, 255) record[R_COUNT] = clampi(entity.item_count, 0, 65535) record[R_TIER] = clampi(entity.item_tier, 0, 255) SimEntity.ARCHETYPE_PROJECTILE: record[R_ITEM] = clampi(entity.item + 1, 0, 255) record[R_OWNER] = entity.owner_id & 0xFFFFFFFF return record ## A player's FLAG_ bits. static func flags_of(entity: SimEntity) -> int: var flags: int = (entity.drop_state & 3) << FLAG_DROP_SHIFT if entity.on_ground: flags |= FLAG_ON_GROUND if entity.crouching: flags |= FLAG_CROUCHING if entity.swimming: flags |= FLAG_SWIMMING if entity.eliminated: flags |= FLAG_ELIMINATED if entity.reload_ticks > 0: flags |= FLAG_RELOADING if entity.use_ticks > 0: flags |= FLAG_USING return flags ## The client's own block for `player`. `water` is the level of the water around it and ## `water_mask` says which of the nine flood cells around it that water reaches: bit ## (dz + 1) * 3 + (dx + 1) for the cell dx, dz away from the player's. static func self_of(player: SimEntity, water: float, water_mask: int) -> Dictionary: return { "position": player.position, "velocity": player.velocity, "water": water, "water_mask": water_mask, "stamina": player.stamina_ticks, "flags": flags_of(player), } ## Puts a client's own block into `player`: everything movement depends on. static func apply_self(player: SimEntity, own: Dictionary) -> void: var flags: int = own["flags"] player.position = own["position"] player.velocity = own["velocity"] player.stamina_ticks = own["stamina"] player.on_ground = flags & FLAG_ON_GROUND != 0 player.crouching = flags & FLAG_CROUCHING != 0 player.swimming = flags & FLAG_SWIMMING != 0 player.eliminated = flags & FLAG_ELIMINATED != 0 player.drop_state = (flags >> FLAG_DROP_SHIFT) & 3 ## Where a record's entity is, to the nearest 1/64 m. static func position_of(record: PackedInt32Array) -> Vector3: return Vector3( record[R_X] / POSITION_STEPS_PER_METRE, record[R_Y] / POSITION_STEPS_PER_METRE - Y_OFFSET_METRES, record[R_Z] / POSITION_STEPS_PER_METRE, ) static func yaw_radians_of(record: PackedInt32Array) -> float: return float(record[R_YAW]) / PlayerCommand.YAW_STEPS * TAU static func pitch_radians_of(record: PackedInt32Array) -> float: return float(record[R_PITCH]) / 127.0 * (PI * 0.5) ## The groups in which two records of one archetype differ. static func diff_mask(before: PackedInt32Array, after: PackedInt32Array) -> int: var groups: Array = _GROUPS[after[R_ARCHETYPE]] var mask: int = 0 for group: int in groups.size(): for index: int in groups[group]: if before[index] != after[index]: mask |= 1 << group break return mask ## Bytes one record takes on the wire with `mask`. static func record_bytes(entity_id: int, archetype: int, mask: int) -> int: var types: Array = _TYPES[archetype] var groups: Array = _GROUPS[archetype] var total: int = varint_bytes(entity_id) + 1 for group: int in groups.size(): if mask & (1 << group) != 0: for index: int in groups[group]: total += _WIDTH[types[index]] return total static func varint_bytes(value: int) -> int: var total: int = 1 while value >= 0x80: value >>= 7 total += 1 return total ## Builds a SNAPSHOT. `removed` are entity IDs; `records` is an array of ## [entity ID, mask, record] in the order they should travel. static func encode_snapshot(header: Dictionary, removed: PackedInt32Array, records: Array) -> PackedByteArray: var out: StreamPeerBuffer = StreamPeerBuffer.new() out.big_endian = false out.put_u8(MSG_SNAPSHOT) out.put_u32(int(header["tick"]) & 0xFFFFFFFF) out.put_u32(int(header.get("baseline", 0)) & 0xFFFFFFFF) out.put_u32(int(header.get("sim_tick", 0)) & 0xFFFFFFFF) out.put_u32((int(header.get("command_tick", -1)) + 1) & 0xFFFFFFFF) out.put_u32(int(header.get("world_seq", 0)) & 0xFFFFFFFF) _put_varint(out, int(header.get("own_id", 0))) out.put_u8(int(header.get("match_phase", 0))) out.put_u8(int(header.get("tide_phase", 0))) out.put_16(clampi(int(header.get("sea_cm", 0)), -32768, 32767)) var own: Dictionary = header.get("self", {}) out.put_u8(0 if own.is_empty() else 1) if not own.is_empty(): for vector: Vector3 in [own["position"], own["velocity"]]: out.put_float(vector.x) out.put_float(vector.y) out.put_float(vector.z) out.put_double(own["water"]) out.put_u16(int(own["water_mask"]) & WATER_EVERYWHERE) out.put_u16(clampi(int(own["stamina"]), 0, 65535)) out.put_u8(int(own["flags"]) & 0xFF) out.put_u8(removed.size()) for entity_id: int in removed: _put_varint(out, entity_id) out.put_u16(records.size()) for entry: Array in records: # A record may come already encoded (encode_record()), shared between clients. out.put_data(entry[3] if entry.size() > 3 else encode_record(int(entry[0]), int(entry[1]), entry[2])) return out.data_array ## One record as a snapshot carries it: the entity ID, the archetype and mask byte, and ## the fields of each group in `mask`. The same for every client that is sent it. static func encode_record(entity_id: int, mask: int, record: PackedInt32Array) -> PackedByteArray: var out: StreamPeerBuffer = StreamPeerBuffer.new() out.big_endian = false var archetype: int = record[R_ARCHETYPE] var types: Array = _TYPES[archetype] var groups: Array = _GROUPS[archetype] _put_varint(out, entity_id) out.put_u8(archetype << 5 | mask) for group: int in groups.size(): if mask & (1 << group) == 0: continue for index: int in groups[group]: match types[index]: _U8: out.put_u8(record[index]) _S8: out.put_8(record[index]) _U16: out.put_u16(record[index]) _U32: out.put_u32(record[index]) return out.data_array ## Reads a SNAPSHOT's header and lists, without applying them: {"tick", "baseline", ## "sim_tick", "command_tick" (-1 = none yet), "world_seq", "own_id", "match_phase", "tide_phase", ## "sea_cm", "self": the client's own block as self_of() made it, or empty, "removed": ## PackedInt32Array, "records": [[entity ID, archetype, mask, values]]}, where `values` ## holds the fields present, in record order. Empty if malformed. static func decode_snapshot(bytes: PackedByteArray) -> Dictionary: if bytes.size() < HEADER_BYTES + 8 or bytes[0] != MSG_SNAPSHOT: return {} var cursor: Array[int] = [HEADER_BYTES] var own_id: int = _read_varint(bytes, cursor) if own_id < 0 or cursor[0] + 6 > bytes.size(): return {} var at: int = cursor[0] var result: Dictionary = { "tick": bytes.decode_u32(1), "baseline": bytes.decode_u32(5), "sim_tick": bytes.decode_u32(9), "command_tick": bytes.decode_u32(13) - 1, "world_seq": bytes.decode_u32(17), "own_id": own_id, "match_phase": bytes[at], "tide_phase": bytes[at + 1], "sea_cm": bytes.decode_s16(at + 2), } var own: Dictionary = {} at += 5 if bytes[at - 1] > 1: return {} if bytes[at - 1] == 1: if at + SELF_BYTES + 1 > bytes.size(): return {} own = { "position": Vector3(bytes.decode_float(at), bytes.decode_float(at + 4), bytes.decode_float(at + 8)), "velocity": Vector3(bytes.decode_float(at + 12), bytes.decode_float(at + 16), bytes.decode_float(at + 20)), "water": bytes.decode_double(at + 24), "water_mask": bytes.decode_u16(at + 32) & WATER_EVERYWHERE, "stamina": bytes.decode_u16(at + 34), "flags": bytes[at + 36], } for value: float in [own["position"].x, own["position"].y, own["position"].z, own["velocity"].x, own["velocity"].y, own["velocity"].z, own["water"]]: if not is_finite(value): return {} at += SELF_BYTES result["self"] = own var removed_count: int = bytes[at] cursor[0] = at + 1 var removed: PackedInt32Array = PackedInt32Array() for _index: int in removed_count: var entity_id: int = _read_varint(bytes, cursor) if entity_id <= 0: return {} removed.append(entity_id) if cursor[0] + 2 > bytes.size(): return {} var record_count: int = bytes.decode_u16(cursor[0]) cursor[0] += 2 var records: Array = [] for _index: int in record_count: var entity_id: int = _read_varint(bytes, cursor) if entity_id <= 0 or cursor[0] >= bytes.size(): return {} var tag: int = bytes[cursor[0]] cursor[0] += 1 var archetype: int = tag >> 5 var mask: int = tag & 0x1F if not _TYPES.has(archetype) or mask == 0 or mask > full_mask(archetype): return {} var types: Array = _TYPES[archetype] var groups: Array = _GROUPS[archetype] var values: PackedInt32Array = PackedInt32Array() for group: int in groups.size(): if mask & (1 << group) == 0: continue for index: int in groups[group]: var type: int = types[index] var offset: int = cursor[0] if offset + _WIDTH[type] > bytes.size(): return {} match type: _U8: values.append(bytes[offset]) _S8: values.append(bytes.decode_s8(offset)) _U16: values.append(bytes.decode_u16(offset)) _U32: values.append(bytes.decode_u32(offset)) cursor[0] = offset + _WIDTH[type] records.append([entity_id, archetype, mask, values]) if cursor[0] != bytes.size(): return {} result["removed"] = removed result["records"] = records return result ## Lays decoded `values` over `base` (an existing record, or empty for a new entity, ## which needs every group). Returns the new record, or an empty array if it can't be. static func merge_record(base: PackedInt32Array, archetype: int, mask: int, values: PackedInt32Array) -> PackedInt32Array: var types: Array = _TYPES[archetype] var groups: Array = _GROUPS[archetype] var record: PackedInt32Array = base.duplicate() if record.is_empty(): if mask != full_mask(archetype): return PackedInt32Array() record.resize(types.size()) record[R_ARCHETYPE] = archetype elif record[R_ARCHETYPE] != archetype: return PackedInt32Array() var next: int = 0 for group: int in groups.size(): if mask & (1 << group) == 0: continue for index: int in groups[group]: record[index] = values[next] next += 1 return record static func encode_input(ack_tick: int, commands: Array[PlayerCommand]) -> PackedByteArray: var count: int = mini(commands.size(), MAX_INPUT_COMMANDS) var bytes: PackedByteArray = PackedByteArray() bytes.resize(6) bytes[0] = MSG_INPUT bytes.encode_u32(1, ack_tick & 0xFFFFFFFF) bytes[5] = count for index: int in range(commands.size() - count, commands.size()): bytes.append_array(commands[index].encode()) return bytes ## {"ack", "commands": Array[PlayerCommand]} or empty. static func decode_input(bytes: PackedByteArray) -> Dictionary: if bytes.size() < 6 or bytes[0] != MSG_INPUT: return {} var count: int = bytes[5] if count > MAX_INPUT_COMMANDS or bytes.size() != 6 + count * PlayerCommand.ENCODED_SIZE: return {} var commands: Array[PlayerCommand] = [] for index: int in count: commands.append(PlayerCommand.decode(bytes, 6 + index * PlayerCommand.ENCODED_SIZE)) return {"ack": bytes.decode_u32(1), "commands": commands} static func encode_match(phase: int, match_index: int, match_seed: int) -> PackedByteArray: var bytes: PackedByteArray = PackedByteArray() bytes.resize(MATCH_BYTES) bytes[0] = MSG_MATCH bytes[1] = phase bytes.encode_u32(2, match_index & 0xFFFFFFFF) bytes.encode_s64(6, match_seed) return bytes ## {"phase", "index", "seed"} or empty. static func decode_match(bytes: PackedByteArray) -> Dictionary: if bytes.size() != MATCH_BYTES or bytes[0] != MSG_MATCH or bytes[1] >= Match.PHASE_NAMES.size(): return {} return {"phase": bytes[1], "index": bytes.decode_u32(2), "seed": bytes.decode_s64(6)} static func _quantize(metres: float) -> int: return clampi(roundi(metres * POSITION_STEPS_PER_METRE), 0, 65535) 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