doom 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb48bcb7558c2e4f4ab959b16dbd857d2a1b6a3b9a9cc76c19a08ec91bdeb93e
-  data.tar.gz: 610f42cf954c60048a0c4030d96a8e8ceb2872aba90e90a141b2179329867c05
+  metadata.gz: c3cb562e8b88b905638cfa8792337bc1b7f818753fa90587bda474784513a6bd
+  data.tar.gz: 1f421713b797c02dfc10e2f9bdd3ad0981a631f88bc94df161aa5a792b539094
 SHA512:
-  metadata.gz: 1ff09fd05c29a5c49b7d41285424d58b8b46dbf995e1f18106d571f18866762e8b20ecb47d472dc2cb2be8f2fc8cdea5eb0b3a2dedae55d5b1881bbcb796088b
-  data.tar.gz: 41d4fcb793f3b25fb57f2d50c02f5eee1a56cb40a40baf2a9f7e0831634f43aa4777abf80968130c44593055dbaea23bd3257e7d4b509a068af2c92e1e16698d
+  metadata.gz: b06fd18ebfa1c5755e27c11b49e9e568fc4e2acfc7bc2b9760e7b7dda500a438afe9a6ecf0e33aa4f17c2271a6c28205e6bbb793e3b9c618c4df24b8bf74679a
+  data.tar.gz: ed5387b2c42963956cfe42c1cfe790a8f7f0e89a15c5a38934780b5ceaca34e3e64456756280d9c8f2d280763ef0fff89434dd8e826dc2e9e0184e25c4f94508

data/README.md

@@ -1,17 +1,19 @@
 # DOOM Ruby
 
-A faithful ruby port of the DOOM (1993) rendering engine to Ruby.
+A faithful port of the DOOM (1993) engine to pure Ruby. Renders the original WAD files with near pixel-perfect BSP rendering, full HUD, item pickups, and hitscan/projectile combat.
 
-![DOOM Ruby Screenshot](screenshot.png)
+![DOOM Ruby](demo.gif)
 
 ## Features
 
-- Pure Ruby implementation of DOOM's BSP rendering engine
-- Accurate wall, floor, and ceiling rendering with proper texture mapping
-- Sprite rendering with depth-correct clipping
-- Original DOOM lighting and colormap support
-- Mouse look and WASD movement controls
-- Supports original WAD files (shareware and registered)
+- **Rendering**: BSP traversal, visplanes, drawsegs, sprite clipping, sky rendering matching Chocolate Doom
+- **Combat**: Hitscan weapons (pistol, shotgun, chaingun), melee (fist, chainsaw), projectile rockets with splash damage
+- **Items**: Weapons, ammo, health, armor, keys -- all pickupable with correct DOOM behavior
+- **Movement**: Momentum-based physics with friction, smooth step transitions, wall sliding, view bob
+- **HUD**: Full status bar with ammo, health, armor, face, weapon selector, key cards, small ammo counts
+- **Effects**: Animated textures (NUKAGE, SLADRIP), sector light effects (flickering, glowing, strobing), scrolling walls
+- **Monsters**: Death animations, solid collision, HP tracking
+- **Compatibility**: Supports original WAD files (shareware and registered), YJIT-optimized
 
 ## Installation
 
@@ -21,7 +23,7 @@ gem install doom
 
 ## Quick Start
 
-Just run `doom` - it will offer to download the free shareware version:
+Just run `doom` -- it will offer to download the free shareware version:
 
 ```bash
 doom
@@ -44,11 +46,16 @@ doom /path/to/doom.wad
 | Left Arrow | Turn left |
 | Right Arrow | Turn right |
 | Mouse | Look around (click to capture) |
+| Left Click / X / Shift | Fire weapon |
+| Space / E | Use (open doors) |
+| 1-7 | Switch weapons |
+| M | Toggle automap |
+| Z | Toggle debug overlay |
 | Escape | Release mouse / Quit |
 
 ## Requirements
 
-- Ruby 3.1 or higher
+- Ruby 3.1+ (Ruby 4.0 with YJIT recommended for best performance)
 - Gosu gem (for window/graphics)
 - SDL2 (native library required by Gosu)
 
@@ -61,7 +68,7 @@ brew install sdl2
 
 **Ubuntu/Debian:**
 ```bash
-sudo apt-get install build-essential libsdl2-dev libgl1-mesa-dev libfontconfig1-dev
+sudo apt-get install build-essential libsdl2-dev libgl1-mesa-dev libopenal-dev libsndfile1-dev libmpg123-dev libfontconfig1-dev
 ```
 
 **Fedora:**
@@ -75,15 +82,15 @@ sudo pacman -S sdl2 mesa
 ```
 
 **Windows:**
-No additional setup needed - the gem includes SDL2.
+No additional setup needed -- the gem includes SDL2.
 
 ## Development
 
 ```bash
-git clone https://github.com/khasinski/doom-rb.git
-cd doom-rb
+git clone https://github.com/khasinski/doom.git
+cd doom
 bundle install
-ruby bin/doom doom1.wad
+ruby bin/doom
 ```
 
 Run specs:
@@ -92,15 +99,30 @@ Run specs:
 bundle exec rspec
 ```
 
+### Benchmarking
+
+```bash
+ruby bench/benchmark.rb                     # without YJIT
+ruby --yjit bench/benchmark.rb              # with YJIT
+ruby bench/benchmark.rb --compare           # side-by-side
+ruby bench/benchmark.rb --profile           # CPU profile with StackProf
+```
+
 ## Technical Details
 
-This implementation includes:
+- **BSP Traversal**: Front-to-back rendering using the map's BSP tree with R_CheckBBox culling
+- **Visplanes**: Floor/ceiling rendering with R_CheckPlane splitting and span-based drawing
+- **Drawsegs**: Wall segment tracking for proper sprite clipping (silhouette system)
+- **Texture Mapping**: Perspective-correct ray-seg intersection with non-power-of-2 support
+- **Lighting**: Distance-based light diminishing with wall and flat colormaps
+- **Sky Rendering**: Chocolate Doom sky hack (worldtop = worldhigh) with correct placement
+- **Movement Physics**: Continuous-time momentum/friction matching Chocolate Doom's P_XYMovement
+- **Hitscan**: Ray tracing against walls and monster bounding circles
+- **Projectiles**: Physical rockets with wall/monster collision and splash damage
+
+## Performance
 
-- **BSP Traversal**: Front-to-back rendering using the map's BSP tree
-- **Visplanes**: Floor/ceiling rendering with R_CheckPlane splitting
-- **Drawsegs**: Wall segment tracking for proper sprite clipping
-- **Texture Mapping**: Perspective-correct texture coordinates
-- **Lighting**: Distance-based light diminishing with colormaps
+With Ruby 4.0 and YJIT enabled, the renderer achieves 80-130 FPS on E1M1 (Apple Silicon). See [docs/performance-profiling.md](docs/performance-profiling.md) and [docs/yjit-vs-zjit.md](docs/yjit-vs-zjit.md) for detailed analysis.
 
 ## Legal
 
@@ -112,7 +134,7 @@ please purchase DOOM from [Steam](https://store.steampowered.com/app/2280/Ultima
 
 ## License
 
-GPL-2.0 - Same license as the original DOOM source code.
+GPL-2.0 -- Same license as the original DOOM source code.
 
 ## Author
 

data/bin/doom

@@ -1,9 +1,11 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-# Enable YJIT if available (Ruby 3.1+) for better performance
-if defined?(RubyVM::YJIT) && RubyVM::YJIT.respond_to?(:enable)
-  RubyVM::YJIT.enable
+# Enable YJIT unless --no-yjit flag is passed (for live toggle demo)
+unless ARGV.delete('--no-yjit')
+  if defined?(RubyVM::YJIT) && RubyVM::YJIT.respond_to?(:enable)
+    RubyVM::YJIT.enable
+  end
 end
 
 # Parse arguments before loading heavy dependencies

data/lib/doom/game/animations.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Doom
+  module Game
+    # Animated texture/flat cycling, matching Chocolate Doom's P_InitPicAnims
+    # and P_UpdateSpecials from p_spec.c.
+    #
+    # All animations run at 8 tics per frame (8/35 sec ≈ 0.23s).
+    # Frames must be consecutive entries in the WAD; the engine uses
+    # start/end names to find the range.
+    class Animations
+      TICS_PER_FRAME = 8
+
+      # [is_texture, start_name, end_name]
+      # From Chocolate Doom animdefs[] in p_spec.c
+      ANIMDEFS = [
+        # Animated flats
+        [false, 'NUKAGE1',  'NUKAGE3'],
+        [false, 'FWATER1',  'FWATER4'],
+        [false, 'SWATER1',  'SWATER4'],
+        [false, 'LAVA1',    'LAVA4'],
+        [false, 'BLOOD1',   'BLOOD3'],
+        [false, 'RROCK05',  'RROCK08'],
+        [false, 'SLIME01',  'SLIME04'],
+        [false, 'SLIME05',  'SLIME08'],
+        [false, 'SLIME09',  'SLIME12'],
+        # Animated wall textures
+        [true, 'BLODGR1',  'BLODGR4'],
+        [true, 'SLADRIP1', 'SLADRIP3'],
+        [true, 'BLODRIP1', 'BLODRIP4'],
+        [true, 'FIREWALA', 'FIREWALL'],
+        [true, 'GSTFONT1', 'GSTFONT3'],
+        [true, 'FIRELAV3', 'FIRELAVA'],
+        [true, 'FIREMAG1', 'FIREMAG3'],
+        [true, 'FIREBLU1', 'FIREBLU2'],
+        [true, 'ROCKRED1', 'ROCKRED3'],
+        [true, 'BFALL1',   'BFALL4'],
+        [true, 'SFALL1',   'SFALL4'],
+        [true, 'WFALL1',   'WFALL4'],
+        [true, 'DBRAIN1',  'DBRAIN4'],
+      ].freeze
+
+      attr_reader :flat_translation, :texture_translation
+
+      def initialize(texture_names, flat_names)
+        @flat_translation = {}      # flat_name -> current_frame_name
+        @texture_translation = {}   # texture_name -> current_frame_name
+        @anims = []
+
+        ANIMDEFS.each do |is_texture, start_name, end_name|
+          names = is_texture ? texture_names : flat_names
+
+          start_idx = names.index(start_name)
+          end_idx = names.index(end_name)
+          next unless start_idx && end_idx
+          next if end_idx <= start_idx
+
+          frames = names[start_idx..end_idx]
+          next if frames.size < 2
+
+          @anims << {
+            is_texture: is_texture,
+            frames: frames,
+            speed: TICS_PER_FRAME,
+          }
+        end
+      end
+
+      # Call every game tic (or approximate with leveltime).
+      # Matches Chocolate Doom P_UpdateSpecials:
+      #   pic = basepic + ((leveltime / speed + i) % numpics)
+      def update(leveltime)
+        @anims.each do |anim|
+          frames = anim[:frames]
+          numpics = frames.size
+          phase = leveltime / anim[:speed]
+          translation = anim[:is_texture] ? @texture_translation : @flat_translation
+
+          numpics.times do |i|
+            current_frame = frames[(phase + i) % numpics]
+            translation[frames[i]] = current_frame
+          end
+        end
+      end
+
+      # Translate a flat name to its current animation frame
+      def translate_flat(name)
+        @flat_translation[name] || name
+      end
+
+      # Translate a texture name to its current animation frame
+      def translate_texture(name)
+        @texture_translation[name] || name
+      end
+    end
+  end
+end

data/lib/doom/game/combat.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+module Doom
+  module Game
+    # Hitscan weapon firing and monster state tracking.
+    # Matches Chocolate Doom's P_LineAttack / P_AimLineAttack from p_map.c.
+    class Combat
+      # Monster starting HP (from mobjinfo[] in info.c)
+      MONSTER_HP = {
+        3004 => 20,   # Zombieman
+        9    => 30,   # Shotgun Guy
+        3001 => 60,   # Imp
+        3002 => 150,  # Demon
+        58   => 150,  # Spectre
+        3003 => 1000, # Baron of Hell
+        69   => 500,  # Hell Knight
+        3005 => 400,  # Cacodemon
+        3006 => 100,  # Lost Soul
+        16   => 4000, # Cyberdemon
+        7    => 3000, # Spider Mastermind
+        65   => 70,   # Heavy Weapon Dude
+        64   => 700,  # Archvile
+        71   => 400,  # Pain Elemental
+        84   => 20,   # Wolfenstein SS
+      }.freeze
+
+      MONSTER_RADIUS = {
+        3004 => 20, 9 => 20, 3001 => 20, 3002 => 30, 58 => 30,
+        3003 => 24, 69 => 24, 3005 => 31, 3006 => 16, 16 => 40,
+        7 => 128, 65 => 20, 64 => 20, 71 => 31, 84 => 20,
+      }.freeze
+
+      # Normal death frame sequences per sprite prefix (rotation 0 only)
+      # Identified by sprite heights: frames go from standing height to flat on ground
+      DEATH_FRAMES = {
+        'POSS' => %w[H I J K L],       # Zombieman: 55→46→34→27→17
+        'SPOS' => %w[H I J K L],       # Shotgun Guy: 60→50→35→27→17
+        'TROO' => %w[I J K L M],       # Imp: 62→59→54→46→22
+        'SARG' => %w[I J K L M N],     # Demon/Spectre: 56→56→53→57→46→32
+        'BOSS' => %w[H I J K L M N],   # Baron
+        'BOS2' => %w[H I J K L M N],   # Hell Knight
+        'HEAD' => %w[G H I J K L],     # Cacodemon
+        'SKUL' => %w[G H I J K],       # Lost Soul
+        'CYBR' => %w[I J],             # Cyberdemon
+        'SPID' => %w[I J K],           # Spider Mastermind
+        'CPOS' => %w[H I J K L M N],   # Heavy Weapon Dude
+        'PAIN' => %w[H I J K L M],     # Pain Elemental
+        'SSWV' => %w[I J K L M],       # Wolfenstein SS
+      }.freeze
+
+      DEATH_ANIM_TICS = 6  # Tics per death frame
+
+      # Projectile constants
+      ROCKET_SPEED = 20.0       # Map units per tic (matches DOOM's mobjinfo MISSILESPEED)
+      ROCKET_DAMAGE = 20        # Direct hit base (DOOM: 1d8 * 20)
+      ROCKET_RADIUS = 11        # Collision radius
+      SPLASH_RADIUS = 128.0     # Splash damage radius
+      SPLASH_DAMAGE = 128       # Max splash damage at center
+
+      Projectile = Struct.new(:x, :y, :z, :dx, :dy, :type, :spawn_tic)
+
+      # Weapon damage: DOOM does (P_Random()%3 + 1) * multiplier
+      # Pistol/chaingun: 1*5..3*5 = 5-15 per bullet
+      # Shotgun: 7 pellets, each 1*5..3*5 = 5-15
+      # Fist/chainsaw: 1*2..3*2 = 2-10
+
+      def initialize(map, player_state, sprites)
+        @map = map
+        @player = player_state
+        @sprites = sprites
+        @monster_hp = {}     # thing_idx => current HP
+        @dead_things = {}    # thing_idx => { tic: death_start_tic, prefix: sprite_prefix }
+        @projectiles = []    # Active projectiles in flight
+        @explosions = []     # Active explosions (for rendering)
+        @tic = 0
+      end
+
+      attr_reader :dead_things, :projectiles, :explosions
+
+      def dead?(thing_idx)
+        @dead_things.key?(thing_idx)
+      end
+
+      # Get the current death frame sprite for a dead monster
+      def death_sprite(thing_idx, thing_type, viewer_angle, thing_angle)
+        info = @dead_things[thing_idx]
+        return nil unless info
+
+        frames = DEATH_FRAMES[info[:prefix]]
+        return nil unless frames
+
+        elapsed = @tic - info[:tic]
+        frame_idx = (elapsed / DEATH_ANIM_TICS).clamp(0, frames.size - 1)
+        frame_letter = frames[frame_idx]
+
+        @sprites.get_frame(thing_type, frame_letter, viewer_angle, thing_angle)
+      end
+
+      # Called each game tic
+      def update
+        @tic += 1
+        update_projectiles
+        update_explosions
+      end
+
+      # Fire the current weapon
+      def fire(px, py, pz, cos_a, sin_a, weapon)
+        case weapon
+        when PlayerState::WEAPON_PISTOL, PlayerState::WEAPON_CHAINGUN
+          hitscan(px, py, cos_a, sin_a, 1, 0.0, 5)
+        when PlayerState::WEAPON_SHOTGUN
+          hitscan(px, py, cos_a, sin_a, 7, Math::PI / 32, 5)
+        when PlayerState::WEAPON_ROCKET
+          spawn_rocket(px, py, pz, cos_a, sin_a)
+        when PlayerState::WEAPON_FIST
+          melee(px, py, cos_a, sin_a, 2, 64)
+        when PlayerState::WEAPON_CHAINSAW
+          melee(px, py, cos_a, sin_a, 2, 64)
+        end
+      end
+
+      private
+
+      def spawn_rocket(px, py, pz, cos_a, sin_a)
+        # Spawn slightly ahead of the player
+        @projectiles << Projectile.new(
+          px + cos_a * 20, py + sin_a * 20, pz,
+          cos_a * ROCKET_SPEED, sin_a * ROCKET_SPEED,
+          :rocket, @tic
+        )
+      end
+
+      def update_projectiles
+        @projectiles.reject! do |proj|
+          # Move projectile
+          new_x = proj.x + proj.dx
+          new_y = proj.y + proj.dy
+
+          # Check wall collision
+          hit_wall = hits_wall?(proj.x, proj.y, new_x, new_y)
+
+          # Check monster collision
+          hit_monster = nil
+          @map.things.each_with_index do |thing, idx|
+            next unless MONSTER_HP[thing.type]
+            next if @dead_things[idx]
+            radius = (MONSTER_RADIUS[thing.type] || 20) + ROCKET_RADIUS
+            dx = new_x - thing.x
+            dy = new_y - thing.y
+            if dx * dx + dy * dy < radius * radius
+              hit_monster = idx
+              break
+            end
+          end
+
+          if hit_wall || hit_monster
+            explode(new_x, new_y, hit_monster)
+            true  # Remove projectile
+          else
+            proj.x = new_x
+            proj.y = new_y
+            false # Keep projectile
+          end
+        end
+      end
+
+      def explode(x, y, direct_hit_idx)
+        # Direct hit damage
+        if direct_hit_idx
+          damage = (rand(8) + 1) * ROCKET_DAMAGE
+          apply_damage(direct_hit_idx, damage)
+        end
+
+        # Splash damage to all monsters in radius
+        @map.things.each_with_index do |thing, idx|
+          next unless MONSTER_HP[thing.type]
+          next if @dead_things[idx]
+          next if idx == direct_hit_idx  # Already took direct hit
+
+          dx = x - thing.x
+          dy = y - thing.y
+          dist = Math.sqrt(dx * dx + dy * dy)
+          next if dist >= SPLASH_RADIUS
+
+          # Damage falls off linearly with distance
+          damage = ((SPLASH_DAMAGE * (1.0 - dist / SPLASH_RADIUS))).to_i
+          apply_damage(idx, damage) if damage > 0
+        end
+
+        # Spawn explosion visual
+        @explosions << { x: x, y: y, tic: @tic }
+      end
+
+      def update_explosions
+        # Explosions last 20 tics then disappear
+        @explosions.reject! { |e| @tic - e[:tic] > 20 }
+      end
+
+      def hits_wall?(x1, y1, x2, y2)
+        @map.linedefs.each do |ld|
+          # One-sided walls always block
+          blocks = ld.sidedef_left == 0xFFFF || (ld.flags & 0x0001 != 0)
+          unless blocks
+            next unless ld.sidedef_left < 0xFFFF
+            front = @map.sidedefs[ld.sidedef_right]
+            back = @map.sidedefs[ld.sidedef_left]
+            fs = @map.sectors[front.sector]
+            bs = @map.sectors[back.sector]
+            max_floor = [fs.floor_height, bs.floor_height].max
+            min_ceil = [fs.ceiling_height, bs.ceiling_height].min
+            blocks = (min_ceil - max_floor) < 56
+          end
+          next unless blocks
+
+          v1 = @map.vertices[ld.v1]
+          v2 = @map.vertices[ld.v2]
+          if segments_intersect?(x1, y1, x2, y2, v1.x, v1.y, v2.x, v2.y)
+            return true
+          end
+        end
+        false
+      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 hitscan(px, py, cos_a, sin_a, pellets, spread, multiplier)
+        pellets.times do
+          # Add random spread
+          if spread > 0
+            angle = Math.atan2(sin_a, cos_a) + (rand - 0.5) * spread * 2
+            ca = Math.cos(angle)
+            sa = Math.sin(angle)
+          else
+            # Slight pistol/chaingun spread
+            angle = Math.atan2(sin_a, cos_a) + (rand - 0.5) * 0.04
+            ca = Math.cos(angle)
+            sa = Math.sin(angle)
+          end
+
+          wall_dist = trace_wall(px, py, ca, sa)
+
+          best_idx = nil
+          best_dist = wall_dist
+
+          @map.things.each_with_index do |thing, idx|
+            next unless MONSTER_HP[thing.type]
+            next if @dead_things[idx]
+
+            radius = MONSTER_RADIUS[thing.type] || 20
+            hit_dist = ray_circle_hit(px, py, ca, sa, thing.x, thing.y, radius)
+            if hit_dist && hit_dist > 0 && hit_dist < best_dist
+              best_dist = hit_dist
+              best_idx = idx
+            end
+          end
+
+          if best_idx
+            damage = (rand(3) + 1) * multiplier
+            apply_damage(best_idx, damage)
+          end
+        end
+      end
+
+      def melee(px, py, cos_a, sin_a, multiplier, range)
+        best_idx = nil
+        best_dist = range.to_f
+
+        @map.things.each_with_index do |thing, idx|
+          next unless MONSTER_HP[thing.type]
+          next if @dead_things[idx]
+
+          dx = thing.x - px
+          dy = thing.y - py
+          dist = Math.sqrt(dx * dx + dy * dy)
+          next if dist > range + (MONSTER_RADIUS[thing.type] || 20)
+
+          # Check if roughly facing the monster
+          dot = dx * cos_a + dy * sin_a
+          next if dot < 0
+
+          if dist < best_dist
+            best_dist = dist
+            best_idx = idx
+          end
+        end
+
+        if best_idx
+          damage = (rand(3) + 1) * multiplier
+          apply_damage(best_idx, damage)
+        end
+      end
+
+      def apply_damage(thing_idx, damage)
+        thing = @map.things[thing_idx]
+        @monster_hp[thing_idx] ||= MONSTER_HP[thing.type] || 20
+
+        @monster_hp[thing_idx] -= damage
+
+        if @monster_hp[thing_idx] <= 0
+          prefix = @sprites.prefix_for(thing.type)
+          @dead_things[thing_idx] = { tic: @tic, prefix: prefix } if prefix
+        end
+      end
+
+      def trace_wall(px, py, cos_a, sin_a)
+        best_t = 4096.0  # Max hitscan range
+
+        @map.linedefs.each do |ld|
+          v1 = @map.vertices[ld.v1]
+          v2 = @map.vertices[ld.v2]
+
+          # One-sided always blocks; two-sided only if impassable
+          blocks = (ld.sidedef_left == 0xFFFF) || (ld.flags & 0x0001 != 0)
+          unless blocks
+            next unless ld.sidedef_left < 0xFFFF
+            front = @map.sidedefs[ld.sidedef_right]
+            back = @map.sidedefs[ld.sidedef_left]
+            fs = @map.sectors[front.sector]
+            bs = @map.sectors[back.sector]
+            # Blocks if opening is too small (step or low ceiling)
+            max_floor = [fs.floor_height, bs.floor_height].max
+            min_ceil = [fs.ceiling_height, bs.ceiling_height].min
+            blocks = (min_ceil - max_floor) < 56
+          end
+          next unless blocks
+
+          t = ray_segment_intersect(px, py, cos_a, sin_a,
+                                     v1.x, v1.y, v2.x, v2.y)
+          best_t = t if t && t > 0 && t < best_t
+        end
+
+        best_t
+      end
+
+      def ray_segment_intersect(px, py, dx, dy, x1, y1, x2, y2)
+        sx = x2 - x1
+        sy = y2 - y1
+        denom = dx * sy - dy * sx
+        return nil if denom.abs < 0.001
+
+        t = ((x1 - px) * sy - (y1 - py) * sx) / denom
+        u = ((x1 - px) * dy - (y1 - py) * dx) / denom
+
+        (t > 0 && u >= 0.0 && u <= 1.0) ? t : nil
+      end
+
+      def ray_circle_hit(px, py, cos_a, sin_a, cx, cy, radius)
+        dx = cx - px
+        dy = cy - py
+        proj = dx * cos_a + dy * sin_a
+        return nil if proj < 0
+
+        perp_sq = dx * dx + dy * dy - proj * proj
+        return nil if perp_sq > radius * radius
+
+        chord_half = Math.sqrt([radius * radius - perp_sq, 0].max)
+        proj - chord_half
+      end
+    end
+  end
+end