N11: Build ghost, client flood and shot effects in the playable client

- Build ghost: ClientSession shows a BuildGhost in build mode while the
  client plays, asking Building.check() of its own world and predicted
  player with the mouse's newest look, so it agrees with the server.
- Flooded basins: ClientMirror.follow_flood() spreads the client's flood
  as the server's tide tick does, from the tide and the pieces it has.
  WaterView passes a mask of flooded cells (Flood.pours says when it
  changed) to the sea shader, which leaves dry cells undrawn.
- Shots, impacts and swings: a new FX message (NetFx) goes unreliably on
  the state channel next to each snapshot, with what happened within
  NET_FX_RADIUS_METRES of what the client watches or involving that
  player. ClientGame keeps them in `fx` for views and sound. They change
  no state, so a lost one is a missed flash; sending them reliably would
  add to the traffic a bad link can least afford (N8). The fuzzer covers
  the new parser.
- Captures: client_build and client_build_refused show the ghost in its
  allowed and refused tints; client_basin rings shore ground with
  breakwaters and plays until the tide stands over it, and the server,
  the client's flood and the drawn sea all keep the basin dry.
- Tests: NetFx round trips, limits and malformed input; a landed player's
  shots and impacts reach a client, each matching a server event; the
  client keeps a ringed basin dry through the first rise, floods it with
  no ring, catches up after a long frame; the water mask follows pours.

The held item is still not drawn; that needs the models (A4, #44).

Closes #78

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-13 02:24:16 -05:00
co-authored by Claude Opus 5.5
parent 2973abf144
commit 57faefb81a
22 changed files with 810 additions and 9 deletions
+18
View File
@@ -18,6 +18,8 @@ extends RefCounted
## The most ticks predicted in one advance(). Further behind than this, the ticks in
## between go without commands.
const MAX_CATCH_UP_TICKS: int = 12
## FX records kept for views at most; older ones are dropped.
const MAX_FX: int = 256
var receiver: SnapshotReceiver = SnapshotReceiver.new()
var prediction: ClientPrediction = ClientPrediction.new()
@@ -52,6 +54,12 @@ var bad_packets: int = 0
## expect `world` the moment a notice arrives leave it off. `make_world` must be safe
## to call from another thread when it is on.
var build_in_background: bool = false
## Shots, impacts and swings the server reported (NetFx records, positions in world
## metres), oldest first, for views and sound to take. Kept to MAX_FX; whoever draws
## them empties it.
var fx: Array[Dictionary] = []
## FX records received in all.
var fx_received: int = 0
## Called after each snapshot has been taken in, with no arguments. Soak tests use it
## to compare the client's world with the server's at that moment.
var on_snapshot: Callable = Callable()
@@ -186,6 +194,16 @@ func _receive_now(channel: int, bytes: PackedByteArray) -> void:
bad_packets += 1
return
_take_notice(notice)
elif not bytes.is_empty() and bytes[0] == NetFx.MSG_FX:
var message: Dictionary = NetFx.decode(bytes)
if message.is_empty():
bad_packets += 1
return
for record: Dictionary in message["events"]:
fx.append(record)
fx_received += 1
while fx.size() > MAX_FX:
fx.pop_front()
elif receiver.apply(bytes):
_take_snapshot()
if on_snapshot.is_valid():
+37
View File
@@ -21,8 +21,14 @@ var barge_at: Vector3 = Vector3.INF
## The moment being drawn, in simulation ticks.
var time: float = 0.0
## Ticks of flood the client works through at most in one frame.
const MAX_FLOOD_CATCH_UP_TICKS: int = 90
var _drop: Drop = null
var _drop_world: Simulation = null
## The last tick the client's flood was brought up to, and for which world.
var _flood_tick: int = 0
var _flood_world: Simulation = null
func sync(game: ClientGame) -> void:
@@ -44,6 +50,7 @@ func sync(game: ClientGame) -> void:
time = float(receiver.sim_tick)
world.tick = maxi(floori(time), 0)
world.sea_level = world.tide.level_at(world.tick) if world.tide != null else receiver.sea_level
follow_flood(world)
if in_match:
if _drop == null or _drop_world != world:
@@ -100,6 +107,36 @@ func sync(game: ClientGame) -> void:
world.projectiles = projectiles
## Spreads the client's flood as the server's tide tick does: across the edges the
## current breakwaters leave open once a second, and filling breached basins every
## tick. The server never sends the flood; it follows from the sea level and the
## pieces, which the client already has. It is only drawn (and used by prediction),
## so a breakwater that arrives a moment late can at worst show water a little early.
func follow_flood(world: Simulation) -> void:
if world.flood == null:
return
if _flood_world != world:
_flood_world = world
_flood_tick = world.tick
world.flood.update(world.sea_level, world.structures, 0.0)
return
if world.tide == null or world.tick <= _flood_tick:
return
# After a long gap (a stall, or joining late) catch up on the last few seconds only.
var first: int = maxi(_flood_tick + 1, world.tick - MAX_FLOOD_CATCH_UP_TICKS)
for tick: int in range(first, world.tick + 1):
var level: float = world.tide.level_at(tick)
if tick % Tuning.TICK_RATE_HZ == 0:
world.flood.update(level, world.structures, Simulation.SECONDS_PER_TICK)
else:
world.flood.flow(level, Simulation.SECONDS_PER_TICK)
if first > _flood_tick + 1:
# The skipped time still fills basins, and the sea still reaches what it can.
world.flood.update(world.sea_level, world.structures, (first - _flood_tick - 1) * Simulation.SECONDS_PER_TICK)
_flood_tick = world.tick
world.flood.sea_level = world.sea_level
func _show_player(entity: SimEntity, record: PackedInt32Array, shown: Dictionary) -> void:
var flags: int = record[NetSnapshot.R_FLAGS]
entity.yaw = posmod(roundi(float(shown["yaw"]) / TAU * PlayerCommand.YAW_STEPS), PlayerCommand.YAW_STEPS)
+174
View File
@@ -0,0 +1,174 @@
## Things that happen and are gone, on the wire: shots fired, where shots landed, and
## harvesting swings. They change nothing a client keeps (damage, broken props and
## pieces arrive in snapshots and WORLD), so they are only for drawing and sound: an
## FX message goes unreliably on the state channel next to each snapshot, and a lost
## one is a missed flash, not a wrong world. Sending them reliably would add to the
## reliable traffic that has to be acknowledged, which a bad link can least afford.
##
## server -> FX
## u8 type, u32 simulation tick of the newest event, u8 count, then events:
## u8 kind, u8 ticks before the newest, varint player entity, u8 item code plus one,
## s16 x 3 position in decimetres,
## SHOT: s16 yaw and s16 pitch of the aim, in 1/10000 radian,
## IMPACT: u8 what was hit (Weapons.HIT_), varint target,
## HARVEST: varint prop, or 0 and varint piece plus one for a piece.
##
## Positions are where the shot began, where it landed, or the swinging player's feet.
## The decoder returns an empty Dictionary for anything malformed and never raises.
class_name NetFx
extends RefCounted
const MSG_FX: int = 18
const SHOT: int = 1
const IMPACT: int = 2
const HARVEST: int = 3
const KIND_NAMES: Array[String] = ["", "shot", "impact", "harvest"]
const HEADER_BYTES: int = 6
const MAX_EVENTS: int = 255
## Decimetres: positions to 10 cm, over +/- 3.2 km.
const POSITION_SCALE: float = 10.0
const ANGLE_SCALE: float = 10000.0
## The FX record for a simulation event, or an empty Dictionary for events that aren't
## FX. `players` maps entity IDs to their feet, for harvest swings.
static func from_event(event: Dictionary, tick: int, players: Dictionary = {}) -> Dictionary:
match String(event.get("type", "")):
"shot":
var direction: Vector3 = event["direction"]
return {
"kind": SHOT, "tick": tick, "player": int(event["player"]), "item": int(event["item"]),
"position": event["from"],
"yaw": atan2(direction.x, direction.z), "pitch": asin(clampf(direction.y, -1.0, 1.0)),
}
"impact":
return {
"kind": IMPACT, "tick": tick, "player": int(event["player"]), "item": int(event["item"]),
"position": event["point"], "hit": int(event["hit"]), "target": int(event["target"]),
}
"harvest", "piece_hit":
var player: int = int(event["player"])
return {
"kind": HARVEST, "tick": tick, "player": player, "item": -1,
"position": players.get(player, Vector3.ZERO),
"prop": int(event.get("prop", -1)), "piece": int(event.get("piece", 0)),
}
return {}
## Encodes up to MAX_EVENTS records, newest last, keeping to `max_bytes`. Records past
## the limit are left out, oldest first. Returns an empty array for none.
static func encode(records: Array[Dictionary], max_bytes: int = Tuning.NET_SNAPSHOT_MAX_BYTES) -> PackedByteArray:
if records.is_empty():
return PackedByteArray()
var newest: int = int(records[records.size() - 1]["tick"])
var bodies: Array[PackedByteArray] = []
var total: int = HEADER_BYTES
for index: int in range(records.size() - 1, -1, -1):
var record: Dictionary = records[index]
var back: int = newest - int(record["tick"])
if back < 0 or back > 255:
continue
var body: PackedByteArray = _encode_one(record, back)
if total + body.size() > max_bytes or bodies.size() >= MAX_EVENTS:
break
total += body.size()
bodies.push_front(body)
if bodies.is_empty():
return PackedByteArray()
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
out.put_u8(MSG_FX)
out.put_u32(newest)
out.put_u8(bodies.size())
for body: PackedByteArray in bodies:
out.put_data(body)
return out.data_array
static func _encode_one(record: Dictionary, back: int) -> PackedByteArray:
var out: StreamPeerBuffer = StreamPeerBuffer.new()
out.big_endian = false
var kind: int = int(record["kind"])
out.put_u8(kind)
out.put_u8(back)
NetSnapshot._put_varint(out, maxi(int(record["player"]), 0))
out.put_u8(clampi(int(record["item"]) + 1, 0, 255))
var position: Vector3 = record["position"]
for value: float in [position.x, position.y, position.z]:
out.put_16(clampi(roundi(value * POSITION_SCALE), -32768, 32767))
match kind:
SHOT:
out.put_16(clampi(roundi(wrapf(float(record["yaw"]), -PI, PI) * ANGLE_SCALE), -32768, 32767))
out.put_16(clampi(roundi(float(record["pitch"]) * ANGLE_SCALE), -32768, 32767))
IMPACT:
out.put_u8(clampi(int(record["hit"]), 0, 255))
NetSnapshot._put_varint(out, maxi(int(record["target"]), 0))
HARVEST:
NetSnapshot._put_varint(out, maxi(int(record["prop"]), -1) + 1)
NetSnapshot._put_varint(out, maxi(int(record["piece"]), 0))
return out.data_array
## {"tick": newest tick, "events": Array of records as from_event() makes them, with
## positions and angles as decoded}, or {} if malformed.
static func decode(bytes: PackedByteArray) -> Dictionary:
if bytes.size() < HEADER_BYTES or bytes[0] != MSG_FX:
return {}
var newest: int = bytes.decode_u32(1)
var count: int = bytes[5]
var cursor: Array[int] = [HEADER_BYTES]
var events: Array[Dictionary] = []
for _index: int in count:
if cursor[0] + 2 > bytes.size():
return {}
var kind: int = bytes[cursor[0]]
var back: int = bytes[cursor[0] + 1]
cursor[0] += 2
if kind < SHOT or kind > HARVEST:
return {}
var player: int = NetSnapshot._read_varint(bytes, cursor)
if player < 0 or cursor[0] + 7 > bytes.size():
return {}
var item: int = bytes[cursor[0]] - 1
var position: Vector3 = Vector3(
bytes.decode_s16(cursor[0] + 1) / POSITION_SCALE,
bytes.decode_s16(cursor[0] + 3) / POSITION_SCALE,
bytes.decode_s16(cursor[0] + 5) / POSITION_SCALE)
cursor[0] += 7
var record: Dictionary = {"kind": kind, "tick": newest - back, "player": player, "item": item, "position": position}
match kind:
SHOT:
if cursor[0] + 4 > bytes.size():
return {}
record["yaw"] = bytes.decode_s16(cursor[0]) / ANGLE_SCALE
record["pitch"] = bytes.decode_s16(cursor[0] + 2) / ANGLE_SCALE
cursor[0] += 4
IMPACT:
if cursor[0] + 1 > bytes.size():
return {}
record["hit"] = bytes[cursor[0]]
cursor[0] += 1
record["target"] = NetSnapshot._read_varint(bytes, cursor)
if int(record["target"]) < 0:
return {}
HARVEST:
var prop: int = NetSnapshot._read_varint(bytes, cursor)
var piece: int = NetSnapshot._read_varint(bytes, cursor)
if prop < 0 or piece < 0:
return {}
record["prop"] = prop - 1
record["piece"] = piece
events.append(record)
if cursor[0] != bytes.size():
return {}
return {"tick": newest, "events": events}
## The direction a SHOT record aims along.
static func aim(record: Dictionary) -> Vector3:
var yaw: float = float(record["yaw"])
var pitch: float = float(record["pitch"])
return Vector3(sin(yaw) * cos(pitch), sin(pitch), cos(yaw) * cos(pitch))
+1
View File
@@ -0,0 +1 @@
uid://byl2i67hpew72