doom 0.8.0 → 0.11.0

data/lib/doom/game/monster_ai.rb

@@ -6,8 +6,14 @@ module Doom
     # Matches Chocolate Doom's A_Look / A_Chase / P_NewChaseDir from p_enemy.c.
     class MonsterAI
       # 8 movement directions + no direction
-      DI_EAST = 0; DI_NORTHEAST = 1; DI_NORTH = 2; DI_NORTHWEST = 3
-      DI_WEST = 4; DI_SOUTHWEST = 5; DI_SOUTH = 6; DI_SOUTHEAST = 7
+      DI_EAST = 0
+      DI_NORTHEAST = 1
+      DI_NORTH = 2
+      DI_NORTHWEST = 3
+      DI_WEST = 4
+      DI_SOUTHWEST = 5
+      DI_SOUTH = 6
+      DI_SOUTHEAST = 7
       DI_NODIR = 8
 
       # Movement deltas per direction (map units, 1.0 = FRACUNIT)
@@ -21,38 +27,36 @@ module Doom
       MONSTER_SPEED = {
         3004 => 8, 9 => 8, 3001 => 8, 3002 => 10, 58 => 10,
         3003 => 8, 69 => 8, 3005 => 8, 3006 => 8, 16 => 16,
-        7 => 12, 65 => 8, 64 => 15, 71 => 8, 84 => 8,
+        7 => 12, 65 => 8, 64 => 15, 71 => 8, 84 => 8
       }.freeze
 
       CHASE_TICS = 4       # Steps between A_Chase calls
       SIGHT_RANGE = 768.0  # Max distance for sight check
       MELEE_RANGE = 64.0
       MISSILE_RANGE = 768.0
-      KEEP_DISTANCE = 196.0  # Ranged monsters prefer to stay this far from player
-
-      # Direction to angle (for sprite facing)
-      DIR_ANGLES = [0, 45, 90, 135, 180, 225, 270, 315].freeze
+      KEEP_DISTANCE = 196.0 # Ranged monsters prefer to stay this far from player
 
       # Monster attack definitions (from mobjinfo / A_Chase)
       # Cooldown = attack_anim_tics + avg_movecount(7.5) * chase_tics(4)
       # In DOOM, monsters only attempt attacks when movecount reaches 0,
       # then play full attack animation before returning to chase.
       MONSTER_ATTACK = {
-        3004 => { type: :hitscan, damage: [3, 15], cooldown: 56 },     # Zombieman
-        9    => { type: :hitscan, damage: [3, 15], cooldown: 56 },     # Shotgun Guy
-        3001 => { type: :projectile, cooldown: 52 },                    # Imp: fireball
-        3002 => { type: :melee,  damage: [4, 40], cooldown: 42 },      # Demon
-        58   => { type: :melee,  damage: [4, 40], cooldown: 42 },      # Spectre
-        3003 => { type: :projectile, cooldown: 54 },                    # Baron: fireball
-        69   => { type: :projectile, cooldown: 54 },                    # Hell Knight
-        3005 => { type: :projectile, cooldown: 56 },                    # Cacodemon
-        65   => { type: :hitscan, damage: [3, 15], cooldown: 40 },     # Heavy Weapon Dude
+        3004 => { type: :hitscan, damage: [3, 15], cooldown: 56 }, # Zombieman
+        9 => { type: :hitscan, damage: [3, 15], cooldown: 56 }, # Shotgun Guy
+        3001 => { type: :projectile, cooldown: 52 }, # Imp: fireball
+        3002 => { type: :melee, damage: [4, 40], cooldown: 42 }, # Demon
+        58 => { type: :melee, damage: [4, 40], cooldown: 42 }, # Spectre
+        3003 => { type: :projectile, cooldown: 54 }, # Baron: fireball
+        69 => { type: :projectile, cooldown: 54 }, # Hell Knight
+        3005 => { type: :projectile, cooldown: 56 }, # Cacodemon
+        65 => { type: :hitscan, damage: [3, 15], cooldown: 40 } # Heavy Weapon Dude
       }.freeze
 
-      REACTIONTIME = 8  # Tics before first attack after activation (from mobjinfo)
+      REACTIONTIME = 8 # Tics before first attack after activation (from mobjinfo)
 
       # Hitscan hit probability by distance (DOOM's P_AimLineAttack has bullet spread)
-      # Close = ~85%, mid = ~60%, far = ~35%
+      # The falloff is HITSCAN_ACCURACY * (1 - dist / (MISSILE_RANGE * 2)):
+      # close (dist 0) = ~85%, mid (dist 384) = ~64%, far (dist 768) = ~42%.
       HITSCAN_ACCURACY = 0.85
 
       # Attack animation frames per sprite prefix (E, F, G typically)
@@ -64,10 +68,10 @@ module Doom
         'HEAD' => %w[E F],       # Cacodemon
         'BOSS' => %w[E F G],     # Baron
         'BOS2' => %w[E F G],     # Hell Knight
-        'CPOS' => %w[E F],       # Heavy Weapon Dude
+        'CPOS' => %w[E F] # Heavy Weapon Dude
       }.freeze
 
-      ATTACK_FRAME_TICS = 8  # Tics per attack animation frame
+      ATTACK_FRAME_TICS = 8 # Tics per attack animation frame
 
       # Which frame index the actual attack happens on (matching Chocolate Doom)
       # Zombieman: A_PosAttack on frame F (index 1)
@@ -81,34 +85,36 @@ module Doom
         'HEAD' => 1,  # Cacodemon: E=charge, F=fire
         'BOSS' => 1,  # Baron: E=raise, F=throw, G=recover
         'BOS2' => 1,  # Hell Knight
-        'CPOS' => 1,  # Heavy Weapon Dude
+        'CPOS' => 1 # Heavy Weapon Dude
       }.freeze
 
       MonsterState = Struct.new(:thing_idx, :x, :y, :movedir, :movecount,
                                 :active, :chase_timer, :type, :attack_cooldown,
-                                :reactiontime, :last_saw_player,
-                                :attacking, :attack_frame_tic, :fired)
+                                :reactiontime, :last_saw_target,
+                                :attacking, :attack_frame_tic, :fired, :target)
 
-      def initialize(map, combat, player_state, sprites_mgr = nil, hidden_things = {}, sound_engine = nil)
+      def initialize(map, combat, sprites_mgr = nil, hidden_things = {}, sound_engine = nil,
+                     random: Random.new)
         @map = map
         @combat = combat
-        @player = player_state
+        @random = random
         @sprites_mgr = sprites_mgr
         @monsters = []
-        @aggression = true  # Monsters fight back (toggle with C)
+        @aggression = true # Monsters fight back (toggle with C)
         @damage_multiplier = 1.0
         @tic_counter = 0
         @sound = sound_engine
         @monster_by_thing_idx = {}
 
         map.things.each_with_index do |thing, idx|
-          next if hidden_things[idx]  # Filtered by difficulty
+          next if hidden_things[idx] # Filtered by difficulty
           next unless Combat::MONSTER_HP[thing.type]
           next if thing.type == Combat::BARREL_TYPE
+
           mon = MonsterState.new(
             idx, thing.x.to_f, thing.y.to_f,
             DI_NODIR, 0, false, 0, thing.type, 0, REACTIONTIME, 0,
-            false, 0, false
+            false, 0, false, nil
           )
           @monsters << mon
           @monster_by_thing_idx[idx] = mon
@@ -118,10 +124,16 @@ module Doom
       attr_reader :monsters, :monster_by_thing_idx
       attr_accessor :aggression, :damage_multiplier
 
-      # Called each game tic
-      def update(player_x, player_y)
+      # Called each game tic with every live player. Each monster keeps its own
+      # target so a second player walking past does not yank a monster off the
+      # one it is already fighting; it re-picks only when its target dies or
+      # leaves.
+      def update(players)
+        players = Array(players)
         @tic_counter += 1
         @monsters.each do |mon|
+          target = select_target(mon, players)
+          next unless target
           next if @combat.dead?(mon.thing_idx)
 
           # Pain state: monster is stunned, skip movement and attacks
@@ -139,7 +151,7 @@ module Doom
               fire_idx = FIRE_FRAME_INDEX[prefix] || 1
               fire_tic = fire_idx * ATTACK_FRAME_TICS
               if !mon.fired && mon.attack_frame_tic >= fire_tic
-                execute_attack(mon, player_x, player_y)
+                execute_attack(mon, target)
                 mon.fired = true
               end
 
@@ -154,54 +166,71 @@ module Doom
             mon.chase_timer -= 1
             if mon.chase_timer <= 0
               mon.chase_timer = CHASE_TICS
-              chase(mon, player_x, player_y)
+              chase(mon, target)
             end
           else
-            look(mon, player_x, player_y)
+            look(mon, target)
           end
         end
       end
 
       private
 
-      def look(mon, player_x, player_y)
-        dx = player_x - mon.x
-        dy = player_y - mon.y
-        dist = Math.sqrt(dx * dx + dy * dy)
+      # Keep fighting the current target while it is alive and still present;
+      # otherwise take the nearest living player. Monsters that have not woken
+      # up yet always look at the nearest one.
+      def select_target(mon, players)
+        current = mon.target
+        return current if current && !current.state.dead && players.include?(current)
+
+        living = players.reject { |p| p.state.dead }
+        return nil if living.empty?
+
+        mon.target = living.min_by { |p| ((p.x - mon.x)**2) + ((p.y - mon.y)**2) }
+      end
+
+      def look(mon, target)
+        target_x = target.x
+        target_y = target.y
+        dx = target_x - mon.x
+        dy = target_y - mon.y
+        dist = Math.sqrt((dx * dx) + (dy * dy))
         return if dist > SIGHT_RANGE
 
         # DOOM A_Look: monster only sees in ~180-degree forward arc
-        # unless player is very close (melee range)
+        # unless the target is very close (melee range)
         if dist > MELEE_RANGE
           thing = @map.things[mon.thing_idx]
           face_angle = thing.angle * Math::PI / 180.0
-          to_player = Math.atan2(dy, dx)
-          angle_diff = ((to_player - face_angle + Math::PI) % (2 * Math::PI) - Math::PI).abs
-          return if angle_diff > Math::PI / 2  # 90 degrees each side = 180 arc
+          to_target = Math.atan2(dy, dx)
+          angle_diff = (((to_target - face_angle + Math::PI) % (2 * Math::PI)) - Math::PI).abs
+          return if angle_diff > Math::PI / 2 # 90 degrees each side = 180 arc
         end
 
-        if has_line_of_sight?(mon.x, mon.y, player_x, player_y)
-          mon.active = true
-          mon.chase_timer = CHASE_TICS
-          @sound&.monster_see(mon.type)
-        end
+        return unless has_line_of_sight?(mon.x, mon.y, target_x, target_y)
+
+        mon.active = true
+        mon.chase_timer = CHASE_TICS
+        @sound&.monster_see(mon.type)
       end
 
-      def chase(mon, player_x, player_y)
+      def chase(mon, target)
+        target_x = target.x
+        target_y = target.y
         speed = MONSTER_SPEED[mon.type] || 8
 
         # Tick down attack cooldown
         mon.attack_cooldown -= CHASE_TICS if mon.attack_cooldown > 0
 
-        dx = player_x - mon.x
-        dy = player_y - mon.y
-        dist = Math.sqrt(dx * dx + dy * dy)
+        dx = target_x - mon.x
+        dy = target_y - mon.y
+        dist = Math.sqrt((dx * dx) + (dy * dy))
 
-        # Track if monster can see the player
-        can_see = dist < SIGHT_RANGE && has_line_of_sight?(mon.x, mon.y, player_x, player_y)
+        # Track if monster can see the target
+        can_see = dist < SIGHT_RANGE && has_line_of_sight?(mon.x, mon.y, target_x, target_y)
         if can_see
-          mon.last_saw_player = @tic_counter
-        elsif @tic_counter - (mon.last_saw_player || 0) > 105  # ~3 seconds without LOS
+          mon.last_saw_target = @tic_counter
+        elsif @tic_counter - (mon.last_saw_target || 0) > 105 # ~3 seconds without LOS
           # Monster gives up and goes idle (like DOOM's A_Chase returning to spawnstate)
           mon.active = false
           mon.reactiontime = REACTIONTIME
@@ -209,15 +238,15 @@ module Doom
         end
 
         # Only attempt attacks when: movecount == 0, has LOS, and in range
-        if @aggression && mon.attack_cooldown <= 0 && mon.movecount <= 0 && can_see && !@player.dead
-          attacked = try_attack(mon, player_x, player_y, dist)
+        if @aggression && mon.attack_cooldown <= 0 && mon.movecount <= 0 && can_see && !target.state.dead
+          attacked = try_attack(mon, target, dist)
         end
 
         # Move -- but ranged monsters stop advancing when they have LOS and are close enough
         # In DOOM, A_Chase skips movement when P_CheckMissileRange succeeds
         unless attacked
           atk = MONSTER_ATTACK[mon.type]
-          ranged = atk && (atk[:type] == :hitscan || atk[:type] == :projectile)
+          ranged = atk && %i[hitscan projectile].include?(atk[:type])
           skip_move = ranged && can_see && dist < KEEP_DISTANCE
 
           if skip_move
@@ -225,9 +254,7 @@ module Doom
             mon.movecount -= 1 if mon.movecount > 0
           else
             mon.movecount -= 1
-            if mon.movecount < 0 || !try_move(mon, speed)
-              new_chase_dir(mon, player_x, player_y)
-            end
+            new_chase_dir(mon, target) if mon.movecount < 0 || !try_move(mon, speed)
           end
         end
 
@@ -236,14 +263,16 @@ module Doom
         thing.x = mon.x.to_i
         thing.y = mon.y.to_i
 
-        # Face toward the player
-        target_angle = Math.atan2(player_y - mon.y, player_x - mon.x) * 180.0 / Math::PI
-        thing.angle = target_angle.round.to_i
+        # Face toward the target
+        facing_angle = Math.atan2(target_y - mon.y, target_x - mon.x) * 180.0 / Math::PI
+        thing.angle = facing_angle.round.to_i
       end
 
       # Decide whether to start an attack (does NOT apply damage yet)
       # Matches Chocolate Doom's P_CheckMissileRange from p_enemy.c
-      def try_attack(mon, player_x, player_y, dist)
+      def try_attack(mon, target, dist)
+        target_x = target.x
+        target_y = target.y
         if mon.reactiontime > 0
           mon.reactiontime -= 1
           return false
@@ -257,14 +286,14 @@ module Doom
           return false if dist > MELEE_RANGE + (Combat::MONSTER_RADIUS[mon.type] || 20)
         when :hitscan, :projectile
           return false if dist > MISSILE_RANGE
-          return false unless has_line_of_sight?(mon.x, mon.y, player_x, player_y)
+          return false unless has_line_of_sight?(mon.x, mon.y, target_x, target_y)
 
           # P_CheckMissileRange: subtract grace distance, cap at 200
-          check_dist = dist - 64  # 64 unit grace distance
-          check_dist -= 128 if atk[:type] == :projectile  # Pure ranged fire more
+          check_dist = dist - 64 # 64 unit grace distance
+          check_dist -= 128 if atk[:type] == :projectile # Pure ranged fire more
           check_dist = [check_dist, 0].max
-          check_dist = [check_dist, 200].min  # Cap: always >= 22% chance to fire
-          return false if rand(256) < check_dist
+          check_dist = [check_dist, 200].min # Cap: always >= 22% chance to fire
+          return false if @random.rand(256) < check_dist
         end
 
         # Start attack animation (damage applied later on fire frame)
@@ -276,44 +305,53 @@ module Doom
       end
 
       # Called on the fire frame of the attack animation
-      def execute_attack(mon, player_x, player_y)
+      def execute_attack(mon, target)
+        target_x = target.x
+        target_y = target.y
         atk = MONSTER_ATTACK[mon.type]
         return unless atk
 
         @sound&.monster_attack(mon.type)
 
-        dx = player_x - mon.x
-        dy = player_y - mon.y
-        dist = Math.sqrt(dx * dx + dy * dy)
+        dx = target_x - mon.x
+        dy = target_y - mon.y
+        dist = Math.sqrt((dx * dx) + (dy * dy))
+
+        # Re-check line of sight at fire time. The player may have moved
+        # behind cover or a door may have closed during the attack animation
+        # (which spans several tics between try_attack and the fire frame).
+        # Melee always lands on contact; ranged skips silently if LOS broke.
+        ranged = %i[hitscan projectile].include?(atk[:type])
+        return if ranged && !has_line_of_sight?(mon.x, mon.y, target_x, target_y)
 
         case atk[:type]
         when :melee
           min_dmg, max_dmg = atk[:damage]
-          damage = (rand(min_dmg..max_dmg) * @damage_multiplier).to_i
-          @player.take_damage(damage) if damage > 0
+          damage = (@random.rand(min_dmg..max_dmg) * @damage_multiplier).to_i
+          target.state.take_damage(damage) if damage > 0
 
         when :hitscan
-          hit_chance = HITSCAN_ACCURACY * (1.0 - dist / (MISSILE_RANGE * 2))
+          hit_chance = HITSCAN_ACCURACY * (1.0 - (dist / (MISSILE_RANGE * 2)))
           hit_chance = [hit_chance, 0.15].max
-          if rand < hit_chance
+          if @random.rand < hit_chance
             min_dmg, max_dmg = atk[:damage]
-            damage = (rand(min_dmg..max_dmg) * @damage_multiplier).to_i
-            @player.take_damage(damage) if damage > 0
+            damage = (@random.rand(min_dmg..max_dmg) * @damage_multiplier).to_i
+            target.state.take_damage(damage) if damage > 0
           end
 
         when :projectile
           # P_SpawnMissile: z = source->z + 32 (chest height)
           sector = @map.sector_at(mon.x, mon.y)
           spawn_z = (sector ? sector.floor_height : 0) + 32
-          @combat.spawn_monster_projectile(mon.x, mon.y, spawn_z, mon.type, @damage_multiplier)
+          @combat.spawn_monster_projectile(mon.x, mon.y, spawn_z, mon.type, @damage_multiplier, target)
         end
       end
 
       def try_move(mon, speed)
         return false if mon.movedir == DI_NODIR
 
-        new_x = mon.x + speed * XSPEED[mon.movedir]
-        new_y = mon.y + speed * YSPEED[mon.movedir]
+        new_x = mon.x + (speed * XSPEED[mon.movedir])
+        new_y = mon.y + (speed * YSPEED[mon.movedir])
 
         # Check if the position is valid (inside a sector, not blocked by walls)
         sector = @map.sector_at(new_x, new_y)
@@ -327,7 +365,7 @@ module Doom
 
           # Simple line-circle intersection
           radius = Combat::MONSTER_RADIUS[mon.type] || 20
-          next unless line_circle_intersect?(v1.x, v1.y, v2.x, v2.y, new_x, new_y, radius)
+          next unless Geometry.line_circle_intersect?(v1.x, v1.y, v2.x, v2.y, new_x, new_y, radius)
 
           # One-sided walls always block
           if ld.sidedef_left == 0xFFFF
@@ -336,16 +374,16 @@ module Doom
           end
 
           # Two-sided: check step height and headroom
-          if ld.sidedef_left < 0xFFFF
-            front = @map.sectors[@map.sidedefs[ld.sidedef_right].sector]
-            back = @map.sectors[@map.sidedefs[ld.sidedef_left].sector]
-            step = (back.floor_height - front.floor_height).abs
-            min_ceil = [front.ceiling_height, back.ceiling_height].min
-            max_floor = [front.floor_height, back.floor_height].max
-            if step > 24 || (min_ceil - max_floor) < 56
-              blocked = true
-              break
-            end
+          next unless ld.sidedef_left < 0xFFFF
+
+          front = @map.sectors[@map.sidedefs[ld.sidedef_right].sector]
+          back = @map.sectors[@map.sidedefs[ld.sidedef_left].sector]
+          step = (back.floor_height - front.floor_height).abs
+          min_ceil = [front.ceiling_height, back.ceiling_height].min
+          max_floor = [front.floor_height, back.floor_height].max
+          if step > 24 || (min_ceil - max_floor) < 56
+            blocked = true
+            break
           end
         end
         return false if blocked
@@ -355,9 +393,11 @@ module Doom
         true
       end
 
-      def new_chase_dir(mon, player_x, player_y)
-        deltax = player_x - mon.x
-        deltay = player_y - mon.y
+      def new_chase_dir(mon, target)
+        target_x = target.x
+        target_y = target.y
+        deltax = target_x - mon.x
+        deltay = target_y - mon.y
         old_dir = mon.movedir
 
         # Determine preferred directions
@@ -376,16 +416,12 @@ module Doom
           diag = diagonal_dir(dir_x, dir_y)
           if diag != OPPOSITE[old_dir]
             mon.movedir = diag
-            if try_walk(mon)
-              return
-            end
+            return if try_walk(mon)
           end
         end
 
         # Randomly swap X/Y priority
-        if rand > 0.22 || deltay.abs > deltax.abs
-          dir_x, dir_y = dir_y, dir_x
-        end
+        dir_x, dir_y = dir_y, dir_x if @random.rand > 0.22 || deltay.abs > deltax.abs
 
         # Try primary direction
         if dir_x != DI_NODIR && dir_x != OPPOSITE[old_dir]
@@ -406,10 +442,11 @@ module Doom
         end
 
         # Try all other directions
-        start = rand(8)
+        start = @random.rand(8)
         8.times do |i|
           d = (start + i) % 8
           next if d == OPPOSITE[old_dir]
+
           mon.movedir = d
           return if try_walk(mon)
         end
@@ -426,7 +463,7 @@ module Doom
       def try_walk(mon)
         speed = MONSTER_SPEED[mon.type] || 8
         if try_move(mon, speed)
-          mon.movecount = rand(16)
+          mon.movecount = @random.rand(16)
           true
         else
           false
@@ -449,46 +486,23 @@ module Doom
           v1 = @map.vertices[ld.v1]
           v2 = @map.vertices[ld.v2]
 
-          next unless segments_intersect?(x1, y1, x2, y2, v1.x, v1.y, v2.x, v2.y)
+          next unless Geometry.segments_intersect?(x1, y1, x2, y2, v1.x, v1.y, v2.x, v2.y)
 
           # One-sided walls always block
           return false if ld.sidedef_left == 0xFFFF
 
           # Two-sided: check if opening is big enough to see through
-          if ld.sidedef_left < 0xFFFF
-            front = @map.sectors[@map.sidedefs[ld.sidedef_right].sector]
-            back = @map.sectors[@map.sidedefs[ld.sidedef_left].sector]
-            max_floor = [front.floor_height, back.floor_height].max
-            min_ceil = [front.ceiling_height, back.ceiling_height].min
-            # Block sight if the opening is too small
-            return false if (min_ceil - max_floor) < 1
-          end
+          next unless ld.sidedef_left < 0xFFFF
+
+          front = @map.sectors[@map.sidedefs[ld.sidedef_right].sector]
+          back = @map.sectors[@map.sidedefs[ld.sidedef_left].sector]
+          max_floor = [front.floor_height, back.floor_height].max
+          min_ceil = [front.ceiling_height, back.ceiling_height].min
+          # Block sight if the opening is too small
+          return false if (min_ceil - max_floor) < 1
         end
         true
       end
-
-      def segments_intersect?(ax1, ay1, ax2, ay2, bx1, by1, bx2, by2)
-        d1x = ax2 - ax1; d1y = ay2 - ay1
-        d2x = bx2 - bx1; d2y = by2 - by1
-        denom = d1x * d2y - d1y * d2x
-        return false if denom.abs < 0.001
-        dx = bx1 - ax1; dy = by1 - ay1
-        t = (dx * d2y - dy * d2x).to_f / denom
-        u = (dx * d1y - dy * d1x).to_f / denom
-        t > 0.0 && t < 1.0 && u >= 0.0 && u <= 1.0
-      end
-
-      def line_circle_intersect?(x1, y1, x2, y2, cx, cy, radius)
-        dx = cx - x1; dy = cy - y1
-        line_dx = x2 - x1; line_dy = y2 - y1
-        line_len_sq = line_dx * line_dx + line_dy * line_dy
-        return false if line_len_sq == 0
-        t = ((dx * line_dx) + (dy * line_dy)) / line_len_sq
-        t = [[t, 0.0].max, 1.0].min
-        closest_x = x1 + t * line_dx; closest_y = y1 + t * line_dy
-        dist_sq = (cx - closest_x) ** 2 + (cy - closest_y) ** 2
-        dist_sq < radius * radius
-      end
     end
   end
 end

data/lib/doom/game/player.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Doom
+  module Game
+    # A player as a first-class entity.
+    #
+    # Before this existed the "player" was scattered across three objects:
+    # position and angle lived in Renderer, horizontal momentum lived in
+    # GosuWindow, and floor height lived in PlayerPhysics -- which made more
+    # than one of them impossible. Everything that identifies a player now
+    # lives here; Renderer is reduced to a camera that gets pointed at a pose.
+    #
+    # Angles are radians internally (Renderer's old setters took degrees).
+    class Player
+      attr_accessor :id, :x, :y, :z, :angle, :momx, :momy
+      # Edge-trigger latch for the use key, per player: holding the key must
+      # not spam doors, and each player needs its own latch.
+      attr_accessor :use_held
+      # Deathmatch score. It lives on the player rather than in a side table so
+      # it survives respawning, which throws away the whole PlayerState.
+      attr_accessor :frags
+      attr_reader :state, :sin_angle, :cos_angle
+
+      # Previous tic's pose, kept so the renderer can interpolate between tics
+      # and stay smooth above 35 FPS.
+      attr_reader :prev_x, :prev_y, :prev_z, :prev_angle
+
+      def initialize(id: 0, state: PlayerState.new)
+        @id = id
+        @state = state
+        @x = 0.0
+        @y = 0.0
+        @z = 41.0 # eye height
+        @momx = 0.0
+        @momy = 0.0
+        @use_held = false
+        @frags = 0
+        self.angle = 0.0
+        snapshot!
+      end
+
+      # Keeps the sin/cos cache in step with the angle -- every read path
+      # (thrust direction, firing direction, view transform) depends on it.
+      def angle=(radians)
+        @angle = radians
+        @sin_angle = Math.sin(radians)
+        @cos_angle = Math.cos(radians)
+      end
+
+      def angle_degrees=(degrees)
+        self.angle = degrees * Math::PI / 180.0
+      end
+
+      def turn(degrees)
+        self.angle = @angle + (degrees * Math::PI / 180.0)
+      end
+
+      def move_to(x, y)
+        @x = x.to_f
+        @y = y.to_f
+      end
+
+      # Place the player outright (spawn, teleport, respawn) and collapse the
+      # interpolation history so the camera doesn't sweep across the map.
+      def place(x, y, z, angle_degrees)
+        @x = x.to_f
+        @y = y.to_f
+        @z = z.to_f
+        self.angle_degrees = angle_degrees
+        @momx = 0.0
+        @momy = 0.0
+        snapshot!
+      end
+
+      # Called at the start of each tic, before the simulation moves the player.
+      def snapshot!
+        @prev_x = @x
+        @prev_y = @y
+        @prev_z = @z
+        @prev_angle = @angle
+      end
+
+      # Pose to render at, `alpha` of the way from the previous tic to this one.
+      # Angle is interpolated along the shortest arc so wrapping past +/-PI
+      # doesn't spin the view the long way round.
+      def view_pose(alpha)
+        a = alpha.clamp(0.0, 1.0)
+        delta = @angle - @prev_angle
+        delta -= 2 * Math::PI while delta > Math::PI
+        delta += 2 * Math::PI while delta < -Math::PI
+
+        [
+          @prev_x + ((@x - @prev_x) * a),
+          @prev_y + ((@y - @prev_y) * a),
+          @prev_z + ((@z - @prev_z) * a),
+          @prev_angle + (delta * a)
+        ]
+      end
+
+      def dead?
+        @state.dead
+      end
+    end
+  end
+end