doom 0.8.0 → 0.11.0

data/lib/doom/net/client.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Doom
+  module Net
+    # The client half of the authoritative-server game. Talks only to the
+    # server (outbound UDP, so NAT is a non-issue), joins by restoring a
+    # snapshot of the live world, then follows the server's finalized frame
+    # stream -- applying joins, leaves and commands in tic order -- so its world
+    # stays byte-identical to the server's. It runs no simulation of its own and
+    # never predicts: the local player sees their own input after the round trip
+    # to the server and back, which is the price of a model where a dead phone
+    # can't stall anyone.
+    #
+    # Everything is polled, never blocking, so the game keeps rendering while a
+    # join is still in flight or a resync is underway.
+    #
+    # A join is a small state machine: HELLO -> WELCOME (who you are, which map)
+    # -> SNAPSHOT chunks (the world) -> playing. HELLO is resent until WELCOME
+    # arrives; if the snapshot never completes, or the frame stream leaves a gap
+    # too old for the server's redundancy to fill, the client asks again and the
+    # server sends a fresh snapshot at the current tic.
+    class Client
+      HELLO_RESEND_SECONDS = 0.25
+      SYNC_TIMEOUT_SECONDS = 1.5 # No completed snapshot this long -> ask again
+      # If the newest frame we've heard of is this far past the one we still
+      # need, the missing one has aged out of the server's resend window and is
+      # gone for good -- only a fresh snapshot recovers us.
+      RESYNC_GAP_TICS = 12
+
+      attr_reader :world, :local_id, :synced_tic
+
+      # `load_map` is a callable name -> Map::MapData; the client learns which
+      # map from WELCOME and has no other way to reach the WAD.
+      def initialize(host:, port:, sprites:, load_map:, sound: nil,
+                     clock: -> { Time.now }, transport: nil)
+        @host = host
+        @port = port
+        @sprites = sprites
+        @load_map = load_map
+        @sound = sound
+        @clock = clock
+        @transport = transport || Transport.new
+        reset_join
+        @last_hello_at = nil
+      end
+
+      def local_port = @transport.local_port
+      def connected? = !@local_id.nil?   # WELCOME received
+      def playing? = !@world.nil?        # snapshot restored, following frames
+
+      # Pump the network: chase the join if not yet playing, then drain and
+      # apply whatever has arrived. Safe every frame.
+      def poll
+        send_hello_if_due
+        @transport.poll.each { |msg, _host, _port| handle(msg) }
+        resync_if_stuck
+      end
+
+      # Send this frame's input for future tics. `pairs` is [[tic, Ticcmd], ...];
+      # recent inputs are repeated by the caller so a lost packet is covered.
+      def send_input(pairs)
+        return unless @local_id
+
+        send_packet(Protocol.encode_input(@local_id, pairs))
+      end
+
+      def quit
+        send_packet(Protocol.encode_quit(@local_id)) if @local_id && !@transport.closed?
+        @transport.close
+      end
+
+      private
+
+      def reset_join
+        @local_id = nil
+        @map_name = nil
+        @snapshot_tic = nil
+        @chunks = {}
+        @chunk_total = nil
+        @world = nil
+        @synced_tic = nil
+        @pending_frames = {}
+        @synced_at = nil
+      end
+
+      def send_packet(bytes) = @transport.send_to_addr(@host, @port, bytes)
+
+      def send_hello_if_due
+        return if playing?
+
+        now = @clock.call
+        return if @last_hello_at && (now - @last_hello_at) < HELLO_RESEND_SECONDS
+
+        @last_hello_at = now
+        send_packet(Protocol.encode_hello)
+      end
+
+      def handle(msg)
+        case msg[:type]
+        when Protocol::WELCOME  then on_welcome(msg)
+        when Protocol::SNAPSHOT then on_chunk(msg)
+        when Protocol::FRAME    then on_frame(msg)
+        end
+      end
+
+      # WELCOME may be the first one (join) or a fresh one answering a resync
+      # request; either way we start reassembling the snapshot it names and drop
+      # any stale in-progress reassembly for an older snapshot tic.
+      def on_welcome(msg)
+        return if @snapshot_tic == msg[:snapshot_tic] && @map_name
+
+        @local_id = msg[:player_id]
+        @map_name = msg[:map]
+        @snapshot_tic = msg[:snapshot_tic]
+        @map = @load_map.call(@map_name)
+        @chunks = {}
+        @chunk_total = nil
+        @last_hello_at = @clock.call # a WELCOME resets the hello clock
+      end
+
+      def on_chunk(msg)
+        return unless @snapshot_tic == msg[:snapshot_tic] && @map
+
+        total = msg[:total]
+        index = msg[:index]
+        # A stray or hostile chunk (bad total, or an index outside the range)
+        # must not corrupt reassembly: without this an out-of-range index could
+        # push @chunks.size up to @chunk_total while a real index stays missing,
+        # so the join below would splice a gap and Snapshot.load would raise on
+        # the network path. Drop it instead.
+        return if total.nil? || total.zero? || index.nil? || index >= total
+
+        @chunk_total = total
+        @chunks[index] = msg[:chunk]
+        return unless @chunks.size == @chunk_total && (0...@chunk_total).all? { |i| @chunks.key?(i) }
+
+        bytes = (0...@chunk_total).map { |i| @chunks[i] }.join
+        begin
+          world = Game::Snapshot.load(bytes, map: @map, sprites: @sprites, sound: @sound)
+        rescue StandardError => e
+          # A truncated or corrupt snapshot is recoverable: ask for a fresh one
+          # rather than letting the exception kill the client mid-game.
+          warn "snapshot load failed (#{e.class}: #{e.message}); requesting resync"
+          request_resync(@clock.call)
+          return
+        end
+
+        @world = world
+        @synced_tic = @snapshot_tic
+        @synced_at = @clock.call
+        # Frames at or before the snapshot are already baked into it.
+        @pending_frames.reject! { |tic, _| tic <= @synced_tic }
+        drain_pending
+      end
+
+      def on_frame(msg)
+        msg[:frames].each { |f| @pending_frames[f[:tic]] ||= f }
+        drain_pending
+      end
+
+      # Apply every consecutive frame we have, in tic order. A missing tic stops
+      # the drain -- lockstep can't skip -- and we wait for it to arrive (or for
+      # resync_if_stuck to give up on it).
+      def drain_pending
+        return unless @synced_tic
+
+        while (f = @pending_frames.delete(@synced_tic + 1))
+          f[:joins].each { |id| @world.add_player(id: id) }
+          f[:leaves].each { |id| @world.remove_player(id) }
+          @world.run_tic(f[:cmds].to_h)
+          @synced_tic += 1
+          @synced_at = @clock.call
+        end
+        prune_pending
+      end
+
+      def prune_pending
+        @pending_frames.reject! { |tic, _| tic <= @synced_tic }
+      end
+
+      # Ask for a fresh snapshot when the join stalls or an unfillable frame gap
+      # opens. Re-sending HELLO is the request; the server answers an existing
+      # client with a new WELCOME plus a snapshot at the current tic.
+      def resync_if_stuck
+        now = @clock.call
+
+        if playing?
+          newest = @pending_frames.keys.max
+          gap = newest && (newest - @synced_tic) > RESYNC_GAP_TICS
+          request_resync(now) if gap
+        elsif connected? && @synced_at.nil?
+          # WELCOME arrived but the snapshot never finished reassembling.
+          request_resync(now) if @last_hello_at && (now - @last_hello_at) >= SYNC_TIMEOUT_SECONDS
+        end
+      end
+
+      def request_resync(now)
+        reset_join
+        @last_hello_at = now
+        send_packet(Protocol.encode_hello)
+      end
+    end
+  end
+end

data/lib/doom/net/desync_monitor.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Doom
+  module Net
+    # Watches for lockstep divergence.
+    #
+    # Each peer fingerprints its world every CHECK_INTERVAL tics and broadcasts
+    # the result. When two peers report different fingerprints for the same
+    # tic, their simulations have already diverged and every tic after it is
+    # meaningless. The job here is to say so at the tic it happened, with
+    # enough detail to diagnose it, instead of letting the games drift apart
+    # while both players wonder why the other is shooting at nothing.
+    #
+    # Peers exchange per-section hashes, not just the folded one: five extra
+    # numbers a second is nothing on the wire, and it turns "something
+    # diverged" into "the monsters diverged", which is the difference between
+    # an alarming report and a useful one.
+    #
+    # Reports can arrive before or after the local check for the same tic, so
+    # both directions are buffered and compared whenever a pair completes.
+    class DesyncMonitor
+      CHECK_INTERVAL = 35   # One second at DOOM's tic rate
+      HISTORY_TICS = 350    # Keep ~10s; enough to pair up late reports
+
+      Desync = Struct.new(:tic, :peer_id, :local, :remote, :sections, keyword_init: true) do
+        def message
+          where = sections.nil? || sections.empty? ? 'unknown section' : sections.join(', ')
+          "desync at tic #{tic} with peer #{peer_id}: " \
+            "local #{format('%08x', local)} != remote #{format('%08x', remote)} (#{where})"
+        end
+      end
+
+      attr_reader :desyncs
+
+      # `on_desync` is called with a Desync the moment one is detected.
+      def initialize(interval: CHECK_INTERVAL, &on_desync)
+        @interval = interval
+        @on_desync = on_desync
+        @local = {}    # tic => section hashes
+        @remote = {}   # tic => { peer_id => section hashes }
+        @desyncs = []
+      end
+
+      def check_due?(tic)
+        (tic % @interval).zero?
+      end
+
+      # Fingerprint the world if this tic is a checkpoint. Returns the section
+      # hashes to broadcast, or nil on a tic that is not checked.
+      def record(tic, world)
+        return nil unless check_due?(tic)
+
+        sections = world.state_hash_sections
+        @local[tic] = sections
+        compare(tic)
+        prune(tic)
+        sections
+      end
+
+      # Section hashes received from another peer.
+      def remote_report(tic, peer_id, sections)
+        (@remote[tic] ||= {})[peer_id] = sections
+        compare(tic)
+      end
+
+      def desynced?
+        !@desyncs.empty?
+      end
+
+      private
+
+      def compare(tic)
+        local = @local[tic]
+        peers = @remote[tic]
+        return unless local && peers
+
+        peers.each do |peer_id, remote|
+          local_hash = Game::StateHash.fold(local)
+          remote_hash = Game::StateHash.fold(remote)
+          next if local_hash == remote_hash
+          next if @desyncs.any? { |d| d.tic == tic && d.peer_id == peer_id }
+
+          differing = Game::StateHash::SECTIONS.reject { |s| local[s] == remote[s] }
+          desync = Desync.new(tic: tic, peer_id: peer_id,
+                              local: local_hash, remote: remote_hash, sections: differing)
+          @desyncs << desync
+          @on_desync&.call(desync)
+        end
+      end
+
+      # Bound memory: a long session would otherwise keep every checkpoint.
+      def prune(tic)
+        cutoff = tic - HISTORY_TICS
+        return if cutoff <= 0
+
+        @local.delete_if { |t, _| t < cutoff }
+        @remote.delete_if { |t, _| t < cutoff }
+      end
+    end
+  end
+end

data/lib/doom/net/game_server.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+module Doom
+  module Net
+    # The authoritative game server for large, chaotic sessions.
+    #
+    # Peer-to-peer lockstep does not survive a conference: with mobile clients
+    # behind CGNAT they cannot reach each other, and lockstep makes everyone
+    # wait for the slowest, so the first person to close their laptop freezes
+    # the match. This server fixes both. Clients speak only to it (outbound
+    # UDP, so NAT is a non-issue), and it never waits: on every tic it takes
+    # whatever input has arrived, fills the gaps with neutral commands, runs
+    # the tic, and broadcasts the finalized result. A player whose phone dies
+    # simply stops acting -- nobody else is held up.
+    #
+    # It is still deterministic underneath: it holds the one canonical world,
+    # every client runs the identical command stream, and joins and leaves are
+    # tic events (a deathmatch spawn draws the shared RNG, so it must happen on
+    # the same tic everywhere). Because it holds the canonical world, it can
+    # hand a late joiner a snapshot of the exact current state instead of
+    # making them replay the match from the start.
+    #
+    # Nothing here blocks. `poll` drains the socket, `advance` runs whatever
+    # tics are due against an injected clock; a host loops them.
+    class GameServer
+      TICRATE = 35
+      TIC_SECONDS = 1.0 / TICRATE
+      FRAME_REDUNDANCY = 6   # Recent frames repeated per packet against loss
+      CLIENT_TIMEOUT = 5.0   # Drop a client silent this long
+
+      # A connected client's bookkeeping (named Member so it is not confused
+      # with Net::Client, the actual client program in the same module).
+      Member = Struct.new(:player_id, :host, :port, :last_seen, :joined) do
+        def key = "#{host}:#{port}"
+      end
+
+      attr_reader :world, :transport, :tic, :clients
+
+      def initialize(world:, transport:, max_players: 16, clock: -> { Time.now },
+                     client_timeout: CLIENT_TIMEOUT)
+        @world = world
+        @transport = transport
+        @max_players = max_players
+        @clock = clock
+        @client_timeout = client_timeout
+        @tic = world.leveltime
+        @start_tic = world.leveltime
+        @start_time = @clock.call
+
+        @clients = {}                 # addr key => Client
+        @by_id = {}                   # player_id => Client
+        @inputs = Hash.new { |h, k| h[k] = {} } # tic => { player_id => Ticcmd }
+        @pending_joins = []           # player ids to add on the next tic
+        @pending_leaves = []          # player ids to remove on the next tic
+        @frame_log = []               # recent finalized frames, for redundancy
+      end
+
+      # Drain and dispatch whatever has arrived. Safe every loop iteration.
+      def poll
+        @transport.poll.each { |msg, host, port| handle(msg, host, port) }
+      end
+
+      # Drop clients that have gone silent, so their stale bodies stop being
+      # simulated and stop holding a player slot. Called from the host loop.
+      # A leave is a tic event like a join, applied on the next tic.
+      def reap(now = @clock.call)
+        @clients.values.each do |c|
+          next unless c.joined
+          next if now - c.last_seen < @client_timeout
+
+          @clients.delete(c.key)
+          @by_id.delete(c.player_id)
+          @pending_leaves << c.player_id
+        end
+      end
+
+      # Run every tic whose deadline has passed, capping the catch-up so one
+      # long stall cannot make a single call run thousands of tics. Returns how
+      # many ran.
+      def advance(now = @clock.call, limit: 8)
+        target = @start_tic + ((now - @start_time) * TICRATE).floor
+        ran = 0
+        while @tic < target && ran < limit
+          step_one_tic
+          ran += 1
+        end
+        ran
+      end
+
+      def player_count = @world.players.size
+
+      private
+
+      # Advance exactly one tic: apply membership, gather input, simulate,
+      # then tell everyone what happened.
+      def step_one_tic
+        this_tic = @tic + 1
+
+        joins = @pending_joins.dup
+        leaves = @pending_leaves.dup
+        @pending_joins.clear
+        @pending_leaves.clear
+
+        apply_joins(joins)
+        apply_leaves(leaves)
+
+        cmds = finalize_cmds(this_tic)
+        @world.run_tic(cmds)
+        @tic = this_tic
+        @inputs.delete(this_tic)
+
+        frame = { tic: this_tic, joins: joins, leaves: leaves,
+                  cmds: cmds.map { |id, c| [id, c] } }
+        record_and_broadcast(frame)
+        send_welcomes(joins, this_tic)
+      end
+
+      # Missing players coast on a neutral command rather than stalling the tic.
+      # That is the whole point of the deadline: nobody waits.
+      def finalize_cmds(tic)
+        have = @inputs[tic]
+        @world.players.each_with_object({}) do |p, h|
+          h[p.id] = have[p.id] || Game::Ticcmd.none
+        end
+      end
+
+      def apply_joins(ids)
+        ids.each do |id|
+          @world.add_player(id: id)
+          client = @by_id[id]
+          client.joined = true if client
+        end
+      end
+
+      def apply_leaves(ids)
+        ids.each { |id| @world.remove_player(id) }
+      end
+
+      def record_and_broadcast(frame)
+        @frame_log << frame
+        @frame_log.shift while @frame_log.size > FRAME_REDUNDANCY
+        # Cap the packet under a safe MTU: at high player counts the full
+        # redundancy would fragment or be truncated. Redundancy degrades
+        # gracefully, the newest frame always ships.
+        packet = Protocol.encode_frame_capped(@frame_log)
+        @clients.each_value { |c| @transport.send_to_addr(c.host, c.port, packet) }
+      end
+
+      def handle(msg, host, port)
+        case msg[:type]
+        when Protocol::HELLO then on_hello(host, port)
+        when Protocol::INPUT then on_input(msg, host, port)
+        when Protocol::QUIT  then on_quit(host, port)
+        end
+      end
+
+      def on_hello(host, port)
+        existing = @clients["#{host}:#{port}"]
+        if existing
+          # A repeated hello is a resync request: the welcome was lost, or the
+          # client fell too far behind the frame stream to recover. Answer with
+          # a fresh snapshot at the current tic, not just the welcome, so it can
+          # restart from live state.
+          send_snapshot_to(existing) if existing.joined
+          return
+        end
+        return if @world.players.size + @pending_joins.size >= @max_players
+
+        id = next_free_id
+        return unless id
+
+        client = Member.new(id, host, port, @clock.call, false)
+        @clients[client.key] = client
+        @by_id[id] = client
+        @pending_joins << id
+      end
+
+      def on_input(msg, host, port)
+        client = @clients["#{host}:#{port}"]
+        return unless client
+
+        client.last_seen = @clock.call
+        # A client may only speak for the id it was assigned. The check does not
+        # vary per command, so reject the whole packet up front rather than
+        # re-testing it inside the loop.
+        return unless msg[:player_id] == client.player_id
+
+        msg[:cmds].each do |tic, cmd|
+          next if tic <= @tic # already simulated; too late to matter
+
+          @inputs[tic][client.player_id] = cmd
+        end
+      end
+
+      def on_quit(host, port)
+        client = @clients.delete("#{host}:#{port}")
+        return unless client
+
+        @by_id.delete(client.player_id)
+        @pending_leaves << client.player_id if client.joined
+      end
+
+      def next_free_id
+        taken = @by_id.keys + @pending_joins
+        (0...@max_players).find { |id| !taken.include?(id) }
+      end
+
+      # Hand each new joiner a snapshot of the world at the tic they joined,
+      # split into datagram-sized chunks. They restore it and follow the frame
+      # stream from the next tic.
+      def send_welcomes(join_ids, _tic)
+        join_ids.each do |id|
+          client = @by_id[id]
+          send_snapshot_to(client) if client
+        end
+      end
+
+      # WELCOME plus the world snapshot at the current tic, chunked. One dump
+      # per recipient is fine -- joins and resyncs are rare next to the tic loop.
+      def send_snapshot_to(client)
+        @transport.send_to_addr(client.host, client.port, Protocol.encode_welcome(
+                                                            player_id: client.player_id, num_players: @world.players.size,
+                                                            mode: @world.mode, skill: Session::DEFAULT_SKILL,
+                                                            snapshot_tic: @tic, map: @world.map.name
+                                                          ))
+        Protocol.snapshot_chunks(@tic, Game::Snapshot.dump(@world)).each do |chunk|
+          @transport.send_to_addr(client.host, client.port, chunk)
+        end
+      end
+    end
+  end
+end