quake-rb 0.1.0

data/lib/quake/bsp/vis.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Quake
+  module Bsp
+    # PVS (Potentially Visible Set) decompression and leaf lookup.
+    # Each leaf stores a compressed bitvector indicating which other leaves
+    # are visible from it. The compression is simple RLE: a zero byte is
+    # followed by a count of zero bytes to insert.
+    module Vis
+      # Decompress the PVS for a leaf into an array of visible leaf indices.
+      # visibility - raw visibility lump data (String)
+      # vis_offset - byte offset into visibility data for this leaf
+      # num_leafs  - total number of leafs in the level (excluding leaf 0)
+      # Returns a Set of visible leaf indices (1-based, matching leafs array).
+      def self.decompress_pvs(visibility, vis_offset, num_leafs)
+        return all_visible(num_leafs) if vis_offset < 0 || visibility.nil? || visibility.empty?
+
+        num_bytes = (num_leafs + 7) / 8
+        pvs = String.new("\0" * num_bytes, encoding: Encoding::BINARY)
+
+        src = vis_offset
+        dst = 0
+
+        while dst < num_bytes
+          byte = visibility.getbyte(src)
+          # Vis data ended before filling the bitvector. Remaining bytes
+          # are already zero (no additional visible leaves), which is safe.
+          break if byte.nil?
+          src += 1
+
+          if byte != 0
+            pvs.setbyte(dst, byte)
+            dst += 1
+          else
+            # RLE: next byte is count of zero bytes
+            count = visibility.getbyte(src) || 0
+            src += 1
+            dst += count # pvs already zeroed
+          end
+        end
+
+        # Convert bitvector to set of leaf indices
+        visible = Set.new
+        num_leafs.times do |i|
+          byte_idx = i / 8
+          bit_idx = i % 8
+          if pvs.getbyte(byte_idx) & (1 << bit_idx) != 0
+            visible << (i + 1) # leaf indices are 1-based (leaf 0 is the solid leaf)
+          end
+        end
+        visible
+      end
+
+      # Find which leaf a point is in by walking the BSP node tree.
+      def self.point_in_leaf(level, point)
+        node_index = 0
+
+        loop do
+          node = level.nodes[node_index]
+          plane = level.planes[node.plane_index]
+
+          dist = point.dot(plane.normal) - plane.dist
+          child = dist >= 0 ? node.children[0] : node.children[1]
+
+          # Negative child index means leaf: ~child gives leaf index
+          if child < 0
+            return ~child
+          else
+            node_index = child
+          end
+        end
+      end
+
+      # Compute a "fat" PVS by unioning the PVS of every leaf within ~8 units
+      # of the given point. Used near translucent water surfaces so the
+      # underwater leaves (which standard PVS excludes from above-water
+      # leaves) are included; without this the cave bed isn't drawn and
+      # alpha-blended water shows the clear color through gaps.
+      # Port of quakespasm SV_FatPVS / SV_AddToFatPVS.
+      def self.fat_pvs(level, point)
+        num_leafs = level.leafs.size - 1
+        result = Set.new
+        add_to_fat_pvs(level, point, 0, num_leafs, result)
+        result
+      end
+
+      def self.add_to_fat_pvs(level, point, node_index, num_leafs, result)
+        loop do
+          if node_index < 0
+            leaf_index = ~node_index
+            return if leaf_index == 0 # skip the universal solid leaf
+            leaf = level.leafs[leaf_index]
+            return if leaf.nil?
+            result.merge(decompress_pvs(level.visibility, leaf.vis_offset, num_leafs))
+            return
+          end
+
+          node = level.nodes[node_index]
+          plane = level.planes[node.plane_index]
+          d = point.dot(plane.normal) - plane.dist
+
+          if d > 8.0
+            node_index = node.children[0]
+          elsif d < -8.0
+            node_index = node.children[1]
+          else
+            # Straddling the plane within the fat radius - descend both sides
+            add_to_fat_pvs(level, point, node.children[0], num_leafs, result)
+            node_index = node.children[1]
+          end
+        end
+      end
+
+      # True if any of the given leaf's marksurfaces is a turbulent (liquid)
+      # surface. Quakespasm's "near water portal" check.
+      def self.near_liquid_portal?(level, leaf)
+        return false if leaf.nil?
+        leaf.num_marksurfaces.times do |i|
+          face_idx = level.marksurfaces[leaf.first_marksurface + i]
+          face = level.faces[face_idx]
+          next if face.nil?
+          ti = level.texinfo[face.texinfo_index]
+          next if ti.nil?
+          tex = level.textures[ti.miptex_index]
+          return true if tex && tex.name.start_with?("*")
+        end
+        false
+      end
+
+      # Precompute, for each liquid (turb) face, the two leaves it physically
+      # separates (computed via BSP traversal of a point on either side of
+      # the face's plane). The standard Quake VIS compiler treats water as
+      # opaque, so above-water and underwater leaves never see each other in
+      # the PVS. Marksurface lists are also unreliable here - many water
+      # faces are marked in only one leaf - so we use geometry instead. We
+      # use this index at runtime to "vis-through" water surfaces: when a
+      # water face is in the visible set, also include the leaves on its
+      # other side. Without this, translucent water alpha-blends against
+      # the clear color where the cave bed should be.
+      def self.liquid_face_to_leaves(level)
+        @liquid_face_to_leaves_cache ||= {}
+        cached = @liquid_face_to_leaves_cache[level.object_id]
+        return cached if cached
+
+        index = {}
+        level.faces.each_with_index do |face, face_idx|
+          next if face.nil?
+          ti = level.texinfo[face.texinfo_index]
+          next if ti.nil?
+          tex = level.textures[ti.miptex_index]
+          next unless tex && tex.name.start_with?("*")
+
+          # Compute face center
+          cx = cy = cz = 0.0
+          n = face.num_edges
+          n.times do |i|
+            se = level.surfedges[face.first_edge + i]
+            edge = level.edges[se.abs]
+            v = se >= 0 ? level.vertices[edge.v0] : level.vertices[edge.v1]
+            cx += v.x; cy += v.y; cz += v.z
+          end
+          cx /= n; cy /= n; cz /= n
+
+          plane = level.planes[face.plane_index]
+          # Step a small distance along + and - the plane normal, find the
+          # leaf each point lands in.
+          offsets = [1.0, -1.0]
+          leaves = offsets.map do |o|
+            pt = Math::Vec3.new(
+              cx + plane.normal.x * o,
+              cy + plane.normal.y * o,
+              cz + plane.normal.z * o
+            )
+            point_in_leaf(level, pt)
+          end.uniq.reject { |l| l == 0 } # skip solid leaf
+
+          index[face_idx] = leaves
+        end
+
+        @liquid_face_to_leaves_cache[level.object_id] = index
+        index
+      end
+
+      # Mark which faces are visible from the given leaf.
+      # Returns a Set of face indices that should be rendered.
+      def self.visible_faces(level, leaf_index, point: nil)
+        leaf = level.leafs[leaf_index]
+        return Set.new if leaf.nil?
+
+        num_leafs = level.leafs.size - 1 # exclude leaf 0
+        # Leaf 0 is the universal SOLID leaf and has no real PVS; its
+        # vis_offset is unused but Quake BSPs sometimes store 0 here, which
+        # would otherwise decompress garbage. Match TyrQuake Mod_LeafPVS:
+        # treat the solid leaf as all-visible so a camera that ends up in
+        # solid space (noclip, edge cases) still sees the world.
+        visible_leafs = if leaf_index == 0
+                          all_visible(num_leafs)
+                        elsif point && near_liquid_portal?(level, leaf)
+                          # Camera leaf touches a liquid surface. Use FatPVS
+                          # so the underwater leaves are included and
+                          # translucent water doesn't reveal void where the
+                          # bed should be.
+                          fat_pvs(level, point)
+                        else
+                          decompress_pvs(level.visibility, leaf.vis_offset, num_leafs)
+                        end
+
+        face_set = Set.new
+        leafs_to_walk = visible_leafs.dup
+        leafs_to_walk << leaf_index # also include current leaf
+
+        # Vis-through water: any visible water face brings the leaves on its
+        # other side into view too. Standard Quake PVS treats water as
+        # opaque, so without this expansion translucent water from above
+        # blends against void instead of the underwater cave bed.
+        liquid_index = liquid_face_to_leaves(level)
+        seen_leafs = Set.new
+        worklist = leafs_to_walk.to_a
+
+        while (li = worklist.shift)
+          next unless seen_leafs.add?(li)
+          vl = level.leafs[li]
+          next if vl.nil?
+
+          vl.num_marksurfaces.times do |i|
+            face_idx = level.marksurfaces[vl.first_marksurface + i]
+            face_set << face_idx
+
+            # If this is a water face, queue the leaves on its other side.
+            other_leaves = liquid_index[face_idx]
+            next unless other_leaves
+            other_leaves.each do |other_leaf|
+              worklist << other_leaf unless seen_leafs.include?(other_leaf)
+            end
+          end
+        end
+
+        face_set
+      end
+
+      def self.all_visible(num_leafs)
+        Set.new(1..num_leafs)
+      end
+    end
+  end
+end

data/lib/quake/camera.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "opengl"
+require "glu"
+
+module Quake
+  class Camera
+    attr_accessor :position, :yaw, :pitch
+    attr_reader :fov, :near, :far
+
+    SPEED = 320.0       # units per second (Quake run speed)
+    SENSITIVITY = 0.15  # degrees per pixel
+    MAX_MOUSE_DELTA = 50 # clamp insane deltas (e.g. first frame warp)
+
+    def initialize(position: Math::Vec3::ORIGIN, yaw: 0.0, pitch: 0.0,
+                   fov: 90.0, near: 4.0, far: 4096.0)
+      @position = position
+      @yaw = yaw
+      @pitch = pitch
+      @fov = fov
+      @near = near
+      @far = far
+      @ignore_mouse = 2  # skip first N motion events (SDL warp artifacts)
+    end
+
+    def forward
+      # Quake: X = forward, Y = left, Z = up
+      # yaw rotates around Z, pitch rotates around Y
+      ry = deg2rad(@yaw)
+      rp = deg2rad(@pitch)
+      cp = ::Math.cos(rp)
+      Math::Vec3.new(
+        ::Math.cos(ry) * cp,
+        ::Math.sin(ry) * cp,
+        -::Math.sin(rp)
+      )
+    end
+
+    def right
+      ry = deg2rad(@yaw - 90.0)
+      Math::Vec3.new(::Math.cos(ry), ::Math.sin(ry), 0.0)
+    end
+
+    def up
+      Math::Vec3.new(0.0, 0.0, 1.0)
+    end
+
+    def move_forward(dt)
+      @position = @position + forward * (SPEED * dt)
+    end
+
+    def move_right(dt)
+      @position = @position + right * (SPEED * dt)
+    end
+
+    def move_up(dt)
+      @position = @position + up * (SPEED * dt)
+    end
+
+    def rotate(dx, dy)
+      if @ignore_mouse > 0
+        @ignore_mouse -= 1
+        return
+      end
+      dx = dx.clamp(-MAX_MOUSE_DELTA, MAX_MOUSE_DELTA)
+      dy = dy.clamp(-MAX_MOUSE_DELTA, MAX_MOUSE_DELTA)
+      @yaw -= dx * SENSITIVITY
+      @pitch += dy * SENSITIVITY
+      @pitch = @pitch.clamp(-89.0, 89.0)
+    end
+
+    def apply_projection_gl(aspect)
+      GL.MatrixMode(GL::PROJECTION)
+      GL.LoadIdentity
+      GLU.Perspective(@fov, aspect, @near, @far)
+    end
+
+    def apply_gl
+      GL.MatrixMode(GL::MODELVIEW)
+      GL.LoadIdentity
+
+      # Quake coords (X-forward, Y-left, Z-up) -> GL coords (X-right, Y-up, Z-backward)
+      # Rotate -90 around X to convert Z-up to Y-up
+      # Rotate 90 around Z to convert X-forward to -Z-backward
+      GL.Rotatef(-90.0, 1.0, 0.0, 0.0)  # Z-up -> Y-up
+      GL.Rotatef(90.0, 0.0, 0.0, 1.0)   # X-forward -> GL
+
+      GL.Rotatef(-@pitch, 0.0, 1.0, 0.0)
+      GL.Rotatef(-@yaw, 0.0, 0.0, 1.0)
+      GL.Translatef(-@position.x, -@position.y, -@position.z)
+    end
+
+    private
+
+    def deg2rad(deg)
+      deg * ::Math::PI / 180.0
+    end
+  end
+end

data/lib/quake/debug/png_writer.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Quake
+  module Debug
+    # Minimal PNG encoder using zlib (no external dependencies).
+    # Writes 8-bit RGB PNGs.
+    module PngWriter
+      SIGNATURE = "\x89PNG\r\n\x1a\n".b
+
+      # Write an RGB PNG. rgb_data is W*H*3 bytes, top-to-bottom rows.
+      def self.write(filename, width, height, rgb_data)
+        File.binwrite(filename, encode(width, height, rgb_data))
+      end
+
+      def self.encode(width, height, rgb_data)
+        bytes_per_row = width * 3
+
+        # PNG requires a filter byte at the start of each row
+        filtered = String.new(capacity: (bytes_per_row + 1) * height)
+        height.times do |y|
+          filtered << "\x00".b # filter type 0 = None
+          filtered << rgb_data[y * bytes_per_row, bytes_per_row]
+        end
+
+        compressed = Zlib::Deflate.deflate(filtered)
+
+        out = String.new(capacity: 64 + compressed.bytesize)
+        out << SIGNATURE
+        # IHDR: width, height, bit_depth, color_type, compression, filter, interlace
+        ihdr = [width, height].pack("NN") + [8, 2, 0, 0, 0].pack("CCCCC")
+        out << chunk("IHDR", ihdr)
+        out << chunk("IDAT", compressed)
+        out << chunk("IEND", "".b)
+        out
+      end
+
+      # Build a PNG chunk: length, type, data, CRC
+      def self.chunk(type, data)
+        type_data = type.b + data.b
+        crc = Zlib.crc32(type_data)
+        [data.bytesize].pack("N") + type_data + [crc].pack("N")
+      end
+
+      # Flip RGB data vertically (glReadPixels returns bottom-up rows,
+      # PNG expects top-down).
+      def self.flip_rows(rgb_data, width, height)
+        bytes_per_row = width * 3
+        out = String.new(capacity: rgb_data.bytesize)
+        (height - 1).downto(0) do |y|
+          out << rgb_data[y * bytes_per_row, bytes_per_row]
+        end
+        out
+      end
+    end
+  end
+end

data/lib/quake/debug/screenshot.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require "opengl"
+require_relative "png_writer"
+
+module Quake
+  module Debug
+    # Captures the current GL framebuffer to a PNG file via glReadPixels.
+    module Screenshot
+      # Read the current framebuffer as RGB bytes (bottom-up).
+      def self.capture(width, height)
+        buf = ("\x00".b * (width * height * 3))
+        GL.PixelStorei(GL::PACK_ALIGNMENT, 1)
+        GL.ReadPixels(0, 0, width, height, GL::RGB, GL::UNSIGNED_BYTE, buf)
+        buf
+      end
+
+      # Save the current framebuffer as a PNG file.
+      def self.save(filename, width, height)
+        raw = capture(width, height)
+        flipped = PngWriter.flip_rows(raw, width, height)
+        PngWriter.write(filename, width, height, flipped)
+      end
+    end
+  end
+end

data/lib/quake/debug/script.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "json"
+require "sdl2"
+
+module Quake
+  module Debug
+    # DSL for scripting headless game runs.
+    #
+    # Example script.rb:
+    #
+    #   load_map "maps/e1m1.bsp"
+    #   teleport 480, 600, 96, yaw: 90
+    #   ticks 30
+    #   screenshot "shots/start.png"
+    #
+    #   hold :w
+    #   ticks 60                # 1 second forward
+    #   release :w
+    #
+    #   ticks 30
+    #   screenshot "shots/forward.png"
+    #   dump_state
+    class Script
+      DEFAULT_DT = 1.0 / 60.0
+
+      KEY_MAP = {
+        w: SDL::SCANCODE_W, a: SDL::SCANCODE_A,
+        s: SDL::SCANCODE_S, d: SDL::SCANCODE_D,
+        space: SDL::SCANCODE_SPACE,
+        ctrl: SDL::SCANCODE_LCTRL,
+        shift: SDL::SCANCODE_LSHIFT,
+        c: SDL::SCANCODE_C
+      }.freeze
+
+      def initialize(engine, output: $stdout)
+        @engine = engine
+        @output = output
+        @held = {}
+      end
+
+      def run_file(path)
+        instance_eval(File.read(path), path)
+      end
+
+      def run_block(&block)
+        instance_eval(&block)
+      end
+
+      # ---- Map / level ----
+
+      def load_map(map_name)
+        @output.puts ">> load_map #{map_name}"
+        @engine.load_map(map_name)
+      end
+
+      # ---- Player control ----
+
+      def teleport(x, y, z, yaw: nil, pitch: nil)
+        @output.puts ">> teleport (#{x}, #{y}, #{z}) yaw=#{yaw} pitch=#{pitch}"
+        @engine.teleport(x, y, z, yaw: yaw, pitch: pitch)
+      end
+
+      def set_yaw(yaw)
+        @engine.player.instance_variable_set(:@yaw, yaw.to_f)
+      end
+
+      def set_pitch(pitch)
+        @engine.player.instance_variable_set(:@pitch, pitch.to_f)
+      end
+
+      def noclip(enabled = true)
+        @engine.player.noclip = enabled
+      end
+
+      # ---- Input ----
+
+      def hold(key)
+        sc = scancode(key)
+        @held[sc] = true
+        @engine.set_key(sc, true)
+      end
+
+      def release(key)
+        sc = scancode(key)
+        @held[sc] = false
+        @engine.set_key(sc, false)
+      end
+
+      def press(key, frames: 2)
+        hold(key)
+        ticks(frames)
+        release(key)
+      end
+
+      def clear_keys
+        @held = {}
+        @engine.clear_keys
+      end
+
+      # ---- Time ----
+
+      def ticks(count, dt: DEFAULT_DT)
+        count.to_i.times { @engine.tick(dt) }
+      end
+
+      def wait_seconds(seconds, dt: DEFAULT_DT)
+        ticks((seconds / dt).round, dt: dt)
+      end
+
+      # ---- Output ----
+
+      def screenshot(filename)
+        FileUtils.mkdir_p(File.dirname(filename)) if filename.include?("/")
+        @engine.screenshot(filename)
+        @output.puts ">> screenshot #{filename}"
+      end
+
+      def dump_state
+        state = @engine.dump_state
+        @output.puts ">> state"
+        @output.puts JSON.pretty_generate(state)
+        state
+      end
+
+      # Print just specific fields
+      def dump(*paths)
+        state = @engine.dump_state
+        paths.each do |path|
+          value = path.to_s.split(".").inject(state) do |acc, key|
+            acc.is_a?(Hash) ? acc[key.to_sym] : nil
+          end
+          @output.puts "  #{path} = #{value.inspect}"
+        end
+      end
+
+      def find_entity(classname:, targetname: nil)
+        @engine.entities.find do |e|
+          e.classname == classname && (targetname.nil? || e.targetname == targetname)
+        end
+      end
+
+      def list_entities(classname_pattern = nil)
+        ents = @engine.entities
+        if classname_pattern
+          re = Regexp.new(classname_pattern)
+          ents = ents.select { |e| e.classname =~ re }
+        end
+        ents.each do |e|
+          @output.puts "  #{e.classname} pos=#{[e.position.x, e.position.y, e.position.z].inspect} " \
+                       "target=#{e.target.inspect} targetname=#{e.targetname.inspect}"
+        end
+        ents.size
+      end
+
+      # Trigger a brush entity by name (simulates a button press)
+      def trigger(target_name)
+        @engine.brush_game.send(:fire_targets, target_name)
+        @output.puts ">> trigger #{target_name}"
+      end
+
+      def log(msg)
+        @output.puts msg
+      end
+
+      private
+
+      def scancode(key)
+        case key
+        when Symbol then KEY_MAP.fetch(key) { raise "Unknown key: #{key}" }
+        when Integer then key
+        else raise "Unknown key: #{key.inspect}"
+        end
+      end
+    end
+  end
+end
+
+require "fileutils"