quake-rb 0.1.0

data/lib/quake/mdl/reader.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Quake
+  module Mdl
+    # Parses Quake MDL (alias model) files.
+    # Binary format: 76-byte header, skins, texcoords, triangles, frames.
+    # Vertices are stored as 3 compressed bytes decompressed via scale/origin.
+    class Reader
+      IDPOLYHEADER = 0x4F504449 # "IDPO" in little-endian
+      MDL_VERSION = 6
+
+      def initialize(data)
+        @data = data
+        @pos = 0
+      end
+
+      def parse
+        header = read_header
+        skins = read_skins(header)
+        stverts = read_stverts(header[:numverts])
+        triangles = read_triangles(header[:numtris])
+        frames = read_frames(header[:numframes], header[:numverts])
+
+        Model.new(
+          scale: header[:scale],
+          scale_origin: header[:scale_origin],
+          bounding_radius: header[:boundingradius],
+          eye_position: header[:eyeposition],
+          skin_width: header[:skinwidth],
+          skin_height: header[:skinheight],
+          skins: skins,
+          stverts: stverts,
+          triangles: triangles,
+          frames: frames,
+          flags: header[:flags],
+          sync_type: header[:synctype]
+        )
+      end
+
+      private
+
+      def read_header
+        ident, version = read_fmt("VV")
+        raise "Not an MDL file (ident=0x#{ident.to_s(16)})" unless ident == IDPOLYHEADER
+        raise "Unsupported MDL version #{version}" unless version == MDL_VERSION
+
+        sx, sy, sz = read_fmt("eee")
+        ox, oy, oz = read_fmt("eee")
+        boundingradius = read_fmt("e").first
+        ex, ey, ez = read_fmt("eee")
+        numskins, skinwidth, skinheight = read_fmt("VVV")
+        numverts, numtris, numframes = read_fmt("VVV")
+        synctype, flags = read_fmt("VV")
+        size = read_fmt("e").first
+
+        {
+          scale: Math::Vec3.new(sx, sy, sz),
+          scale_origin: Math::Vec3.new(ox, oy, oz),
+          boundingradius: boundingradius,
+          eyeposition: Math::Vec3.new(ex, ey, ez),
+          numskins: numskins,
+          skinwidth: skinwidth,
+          skinheight: skinheight,
+          numverts: numverts,
+          numtris: numtris,
+          numframes: numframes,
+          synctype: synctype,
+          flags: flags,
+          size: size
+        }
+      end
+
+      def read_skins(header)
+        skins = []
+        skin_size = header[:skinwidth] * header[:skinheight]
+
+        header[:numskins].times do
+          skin_type = read_fmt("V").first
+
+          if skin_type == 0 # ALIAS_SKIN_SINGLE
+            pixels = @data[@pos, skin_size]
+            @pos += skin_size
+            skins << [pixels]
+          else # ALIAS_SKIN_GROUP
+            num_skins = read_fmt("V").first
+            _intervals = read_fmt("e" * num_skins) # timing intervals
+            group = []
+            num_skins.times do
+              pixels = @data[@pos, skin_size]
+              @pos += skin_size
+              group << pixels
+            end
+            skins << group
+          end
+        end
+
+        skins
+      end
+
+      def read_stverts(count)
+        count.times.map do
+          on_seam, s, t = read_fmt("l<l<l<")
+          STVert.new(on_seam: on_seam, s: s, t: t)
+        end
+      end
+
+      def read_triangles(count)
+        count.times.map do
+          faces_front, v0, v1, v2 = read_fmt("l<l<l<l<")
+          Triangle.new(faces_front: faces_front, vertex_indices: [v0, v1, v2])
+        end
+      end
+
+      def read_frames(count, numverts)
+        count.times.map do
+          frame_type = read_fmt("V").first
+
+          if frame_type == 0 # ALIAS_SINGLE
+            read_single_frame(numverts)
+          else # ALIAS_GROUP
+            read_frame_group(numverts)
+          end
+        end
+      end
+
+      def read_single_frame(numverts)
+        bbox_min = read_trivertx
+        bbox_max = read_trivertx
+        name = @data[@pos, 16].unpack1("Z16")
+        @pos += 16
+
+        vertices = numverts.times.map { read_trivertx }
+
+        Frame.new(name: name, vertices: vertices,
+                  bbox_min: bbox_min, bbox_max: bbox_max)
+      end
+
+      def read_frame_group(numverts)
+        num_frames = read_fmt("V").first
+        _bbox_min = read_trivertx
+        _bbox_max = read_trivertx
+
+        intervals = read_fmt("e" * num_frames)
+
+        frames = num_frames.times.map do
+          read_single_frame(numverts)
+        end
+
+        FrameGroup.new(frames: frames, intervals: intervals)
+      end
+
+      def read_trivertx
+        x, y, z, n = @data[@pos, 4].unpack("CCCC")
+        @pos += 4
+        Vertex.new(x: x, y: y, z: z, normal_index: n)
+      end
+
+      def read_fmt(fmt)
+        # Calculate size by counting format characters
+        size = 0
+        fmt.each_char do |c|
+          case c
+          when "e", "E", "V", "N" then size += 4
+          when "v", "n", "S", "s" then size += 2
+          when "C", "c" then size += 1
+          when "l", "L" then size += 4
+          when "<", ">" then next # endian modifiers
+          end
+        end
+        values = @data[@pos, size].unpack(fmt)
+        @pos += size
+        values
+      end
+    end
+  end
+end

data/lib/quake/mdl/types.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Quake
+  module Mdl
+    # Compressed vertex: 3 bytes position + 1 byte normal index
+    Vertex = Data.define(:x, :y, :z, :normal_index)
+
+    # Single animation frame
+    Frame = Data.define(:name, :vertices, :bbox_min, :bbox_max)
+
+    # Frame group (multiple sub-frames with timing)
+    FrameGroup = Data.define(:frames, :intervals)
+
+    # Triangle: 3 vertex indices + front-facing flag
+    Triangle = Data.define(:faces_front, :vertex_indices)
+
+    # Texture coordinate for a vertex
+    STVert = Data.define(:on_seam, :s, :t)
+
+    # Complete MDL model
+    Model = Data.define(
+      :scale, :scale_origin, :bounding_radius, :eye_position,
+      :skin_width, :skin_height, :skins,
+      :stverts, :triangles, :frames, :flags, :sync_type
+    )
+
+    ALIAS_ONSEAM = 0x0020
+    DT_FACES_FRONT = 0x0010
+  end
+end

data/lib/quake/pak/reader.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Quake
+  module Pak
+    Entry = Data.define(:name, :offset, :size)
+
+    class Reader
+      MAGIC = "PACK"
+      HEADER_SIZE = 12
+      DIR_ENTRY_SIZE = 64
+
+      attr_reader :entries
+
+      def initialize(path)
+        @path = path
+        @io = File.open(path, "rb")
+        @entries = {}
+        parse_header
+      end
+
+      def list
+        @entries.keys
+      end
+
+      def read(name)
+        entry = @entries[name] || @entries[name.downcase]
+        raise "File not found in PAK: #{name}" unless entry
+
+        @io.seek(entry.offset)
+        @io.read(entry.size)
+      end
+
+      def close
+        @io.close
+      end
+
+      private
+
+      def parse_header
+        header = @io.read(HEADER_SIZE)
+        magic, dirofs, dirlen = header.unpack("a4V2")
+        raise "Not a PAK file: #{magic.inspect}" unless magic == MAGIC
+
+        num_entries = dirlen / DIR_ENTRY_SIZE
+        @io.seek(dirofs)
+        dir_data = @io.read(dirlen)
+
+        num_entries.times do |i|
+          offset = i * DIR_ENTRY_SIZE
+          raw = dir_data[offset, DIR_ENTRY_SIZE]
+          name, filepos, filelen = raw.unpack("Z56V2")
+          @entries[name.downcase] = Entry.new(name: name, offset: filepos, size: filelen)
+        end
+      end
+    end
+  end
+end

data/lib/quake/pak_downloader.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "fileutils"
+require "tmpdir"
+
+module Quake
+  # Downloads the shareware Quake pak0.pak if not present.
+  # The Quake shareware (episode 1) is freely redistributable; we fetch the
+  # archive from archive.org and extract pak0.pak via the system `unzip`.
+  class PakDownloader
+    SHAREWARE_URL = "https://archive.org/download/quakeshareware/QUAKE_SW.zip"
+    SHAREWARE_ZIP_SIZE = 18_079_976 # approximate, for progress fallback
+    PAK_FILENAME = "pak0.pak"
+
+    class DownloadError < StandardError; end
+
+    # Returns a path to a usable PAK directory (containing id1/pak0.pak), or
+    # nil/raises. Search order: `custom_path` -> `./data` -> `~/.quake/data`.
+    # If nothing is found, prompts the user to download.
+    def self.ensure_pak_available(custom_path = nil)
+      return custom_path if custom_path && File.exist?(File.join(custom_path, "id1", PAK_FILENAME))
+
+      local = File.join(Dir.pwd, "data")
+      return local if File.exist?(File.join(local, "id1", PAK_FILENAME))
+
+      home = File.join(Dir.home, ".quake", "data")
+      return home if File.exist?(File.join(home, "id1", PAK_FILENAME))
+
+      raise DownloadError, "PAK not found at #{custom_path}" if custom_path
+
+      prompt_and_download(home)
+    end
+
+    def self.prompt_and_download(destination_data_dir)
+      puts "No Quake pak0.pak found."
+      puts
+      puts "Download the shareware version of Quake (about 9 MB)?"
+      puts "It includes the first episode and is freely redistributable."
+      puts
+      print "Download shareware Quake? [Y/n] "
+
+      response = $stdin.gets&.strip&.downcase
+      if response.nil? || response.empty? || response == "y" || response == "yes"
+        download_shareware(destination_data_dir)
+        destination_data_dir
+      else
+        puts
+        puts "To play Quake you need a pak0.pak. Options:"
+        puts "  1. Run `quake-rb` again and accept the shareware download"
+        puts "  2. Copy your own pak0.pak into ./data/id1/"
+        puts "  3. Pass a custom path: quake-rb -basedir /path/to/data"
+        exit 1
+      end
+    end
+
+    def self.download_shareware(destination_data_dir)
+      Dir.mktmpdir("quake-rb-shareware") do |tmp|
+        zip_path = File.join(tmp, "quake106.zip")
+        download(SHAREWARE_URL, zip_path)
+        extract_pak(zip_path, destination_data_dir)
+      end
+    end
+
+    def self.download(url, dest_path)
+      puts
+      puts "Downloading shareware Quake from #{URI.parse(url).host}..."
+      FileUtils.mkdir_p(File.dirname(dest_path))
+      fetch_to_file(url, dest_path)
+      puts
+      size = File.size(dest_path)
+      raise DownloadError, "Download appears incomplete (#{size} bytes)" if size < 1_000_000
+    end
+
+    def self.fetch_to_file(url, dest_path, redirect_limit: 5)
+      raise DownloadError, "Too many redirects" if redirect_limit <= 0
+
+      uri = URI.parse(url)
+      ssl_opts = { use_ssl: uri.scheme == "https" }
+
+      Net::HTTP.start(uri.host, uri.port, **ssl_opts) do |http|
+        request = Net::HTTP::Get.new(uri)
+        http.request(request) do |response|
+          case response
+          when Net::HTTPRedirection
+            return fetch_to_file(response["location"], dest_path,
+                                 redirect_limit: redirect_limit - 1)
+          when Net::HTTPSuccess
+            total = response["content-length"]&.to_i || SHAREWARE_ZIP_SIZE
+            downloaded = 0
+            File.open(dest_path, "wb") do |f|
+              response.read_body do |chunk|
+                f.write(chunk)
+                downloaded += chunk.size
+                print_progress(downloaded, total)
+              end
+            end
+          else
+            raise DownloadError, "HTTP #{response.code} #{response.message}"
+          end
+        end
+      end
+    end
+
+    # Quake's shareware ZIP contains an installer, with pak0.pak nested inside
+    # `resource/Q!ZIP/ID1/PAK0.PAK`. Extract just that one entry into
+    # `<destination_data_dir>/id1/pak0.pak`. Uses system `unzip` so we don't
+    # need a runtime dep on rubyzip.
+    def self.extract_pak(zip_path, destination_data_dir)
+      target_dir = File.join(destination_data_dir, "id1")
+      FileUtils.mkdir_p(target_dir)
+      target_pak = File.join(target_dir, PAK_FILENAME)
+
+      puts "Extracting pak0.pak..."
+
+      # -j junks paths so the entry lands as just "PAK0.PAK"
+      # -C makes glob matching case-insensitive
+      Dir.mktmpdir("quake-rb-unzip") do |tmp|
+        ok = system("unzip", "-jo", "-C", zip_path, "*PAK0.PAK", "-d", tmp,
+                    out: File::NULL)
+        raise DownloadError, "unzip failed (is `unzip` installed?)" unless ok
+
+        extracted = Dir[File.join(tmp, "*")].find { |p| File.basename(p).match?(/pak0\.pak/i) }
+        raise DownloadError, "pak0.pak not found inside ZIP" unless extracted
+
+        FileUtils.mv(extracted, target_pak)
+      end
+
+      raise DownloadError, "extracted pak0.pak is suspiciously small" if File.size(target_pak) < 1_000_000
+      puts "Installed: #{target_pak} (#{(File.size(target_pak) / 1_048_576.0).round(1)} MB)"
+      puts
+    end
+
+    def self.print_progress(downloaded, total)
+      percent = (downloaded.to_f / total * 100).clamp(0, 100).to_i
+      bar_w = 40
+      filled = percent * bar_w / 100
+      bar = ("=" * filled) + ("-" * (bar_w - filled))
+      mb_d = (downloaded / 1_048_576.0).round(1)
+      mb_t = (total / 1_048_576.0).round(1)
+      print "\r[#{bar}] #{percent}% (#{mb_d}/#{mb_t} MB)"
+    end
+  end
+end

data/lib/quake/palette.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Quake
+  class Palette
+    SIZE = 256
+
+    def initialize(data)
+      raise "Palette data must be 768 bytes, got #{data.bytesize}" unless data.bytesize == 768
+      @rgb = Array.new(SIZE)
+      SIZE.times do |i|
+        r, g, b = data[i * 3, 3].unpack("C3")
+        @rgb[i] = [r, g, b]
+      end
+    end
+
+    def rgb(index)
+      @rgb[index]
+    end
+
+    # Convert an array of 8-bit indexed pixels to RGBA bytes
+    # Last palette entry (255) is typically transparent
+    def indexed_to_rgba(pixels, transparent_index: 255)
+      rgba = String.new(capacity: pixels.bytesize * 4)
+      pixels.each_byte do |idx|
+        r, g, b = @rgb[idx]
+        a = (idx == transparent_index) ? 0 : 255
+        rgba << r << g << b << a
+      end
+      rgba
+    end
+  end
+end

data/lib/quake/physics/hull_trace.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module Quake
+  module Physics
+    # Trace result from hull tracing.
+    TraceResult = Data.define(
+      :all_solid,    # started inside solid
+      :start_solid,  # started inside solid but found empty space
+      :in_open,      # trace passed through open space
+      :in_water,     # trace passed through water
+      :fraction,     # 0.0-1.0, how far along the trace before hitting
+      :end_pos,      # final position (Vec3)
+      :plane_normal, # normal of hit plane (Vec3 or nil)
+      :plane_dist    # distance of hit plane (Float or nil)
+    )
+
+    CONTENTS_EMPTY = -1
+    CONTENTS_SOLID = -2
+    CONTENTS_WATER = -3
+    CONTENTS_SLIME = -4
+    CONTENTS_LAVA  = -5
+
+    DIST_EPSILON = 0.03125 # 1/32, same as Quake
+
+    module HullTrace
+      # Check what content type a point is in, using the clipnode tree.
+      # hull_clipnodes: array of ClipNode
+      # planes: array of Plane
+      # node_index: starting clipnode index
+      # point: Vec3
+      def self.point_contents(clipnodes, planes, node_index, point)
+        while node_index >= 0
+          node = clipnodes[node_index]
+          plane = planes[node.plane_index]
+
+          dist = point.dot(plane.normal) - plane.dist
+          node_index = dist >= 0 ? node.children[0] : node.children[1]
+        end
+        node_index # negative value = content type
+      end
+
+      # Trace a line from p1 to p2 through the hull.
+      # Returns a TraceResult.
+      def self.trace(clipnodes, planes, node_index, p1, p2)
+        result = {
+          all_solid: false, start_solid: false,
+          in_open: false, in_water: false,
+          fraction: 1.0, end_pos: p2,
+          plane_normal: nil, plane_dist: nil
+        }
+
+        recursive_trace(clipnodes, planes, node_index, 0.0, 1.0, p1, p2, result)
+
+        if result[:fraction] == 1.0
+          result[:end_pos] = p2
+        else
+          result[:end_pos] = Math::Vec3.new(
+            p1.x + result[:fraction] * (p2.x - p1.x),
+            p1.y + result[:fraction] * (p2.y - p1.y),
+            p1.z + result[:fraction] * (p2.z - p1.z)
+          )
+        end
+
+        TraceResult.new(**result)
+      end
+
+      # Trace against the world AND all solid brush entities, returning the
+      # nearest hit.  Brush entity traces are done in entity-local space
+      # (subtract origin, trace sub-model hull, transform back).
+      def self.trace_world_and_entities(level, p1, p2, brush_entities, hull_num: 1)
+        clipnodes = level.clipnodes
+        planes = level.planes
+
+        # World trace
+        world_hull = level.models[0].head_nodes[hull_num]
+        world_hull = level.models[0].head_nodes[0] if world_hull < 0 || world_hull >= clipnodes.size
+        best = trace(clipnodes, planes, world_hull, p1, p2)
+
+        # Trace against each brush entity's sub-model
+        brush_entities&.each do |ent|
+          next unless ent.brush_entity?
+          # Triggers are SOLID_TRIGGER in Quake: they detect overlap but
+          # don't block movement. They're handled by check_triggers.
+          next if ent.classname.start_with?("trigger_")
+          model = level.models[ent.model_index]
+          next unless model
+
+          sub_hull = model.head_nodes[hull_num]
+          # Many sub-models only have hull 0; fall back gracefully
+          sub_hull = model.head_nodes[0] if sub_hull < 0 || sub_hull >= clipnodes.size
+          next if sub_hull < 0 || sub_hull >= clipnodes.size
+
+          # Transform trace into entity-local space
+          offset = ent.position
+          local_p1 = Math::Vec3.new(p1.x - offset.x, p1.y - offset.y, p1.z - offset.z)
+          local_p2 = Math::Vec3.new(p2.x - offset.x, p2.y - offset.y, p2.z - offset.z)
+
+          sub_result = trace(clipnodes, planes, sub_hull, local_p1, local_p2)
+
+          # Keep nearest hit
+          if sub_result.fraction < best.fraction
+            # Transform end_pos back to world space
+            ep = sub_result.end_pos
+            best = TraceResult.new(
+              all_solid: sub_result.all_solid,
+              start_solid: sub_result.start_solid,
+              in_open: sub_result.in_open,
+              in_water: sub_result.in_water,
+              fraction: sub_result.fraction,
+              end_pos: Math::Vec3.new(ep.x + offset.x, ep.y + offset.y, ep.z + offset.z),
+              plane_normal: sub_result.plane_normal,
+              plane_dist: sub_result.plane_dist
+            )
+          end
+        end
+
+        best
+      end
+
+      private_class_method def self.recursive_trace(clipnodes, planes, node_index, p1f, p2f, p1, p2, result)
+        if node_index < 0
+          # Leaf content
+          if node_index == CONTENTS_SOLID
+            result[:all_solid] = true unless result[:in_open]
+            result[:start_solid] = true
+          else
+            result[:all_solid] = false
+            result[:in_open] = true if node_index == CONTENTS_EMPTY
+            result[:in_water] = true if node_index <= CONTENTS_WATER
+          end
+          return
+        end
+
+        node = clipnodes[node_index]
+        plane = planes[node.plane_index]
+
+        d1 = p1.dot(plane.normal) - plane.dist
+        d2 = p2.dot(plane.normal) - plane.dist
+
+        # Both on same side?
+        if d1 >= 0 && d2 >= 0
+          recursive_trace(clipnodes, planes, node.children[0], p1f, p2f, p1, p2, result)
+          return
+        end
+        if d1 < 0 && d2 < 0
+          recursive_trace(clipnodes, planes, node.children[1], p1f, p2f, p1, p2, result)
+          return
+        end
+
+        # Split - find the crossing point
+        if d1 < 0
+          frac = (d1 + DIST_EPSILON) / (d1 - d2)
+          side = 1
+        else
+          frac = (d1 - DIST_EPSILON) / (d1 - d2)
+          side = 0
+        end
+
+        frac = frac.clamp(0.0, 1.0)
+
+        midf = p1f + (p2f - p1f) * frac
+        mid = Math::Vec3.new(
+          p1.x + frac * (p2.x - p1.x),
+          p1.y + frac * (p2.y - p1.y),
+          p1.z + frac * (p2.z - p1.z)
+        )
+
+        # Traverse near side first
+        recursive_trace(clipnodes, planes, node.children[side], p1f, midf, p1, mid, result)
+
+        # Check if near side hit anything
+        contents = point_contents(clipnodes, planes, node.children[1 - side], mid)
+        if contents != CONTENTS_SOLID
+          # Continue to far side
+          recursive_trace(clipnodes, planes, node.children[1 - side], midf, p2f, mid, p2, result)
+          return
+        end
+
+        # Far side is solid - this is the impact point
+        if result[:fraction] > midf
+          result[:fraction] = midf
+          if side == 0
+            result[:plane_normal] = plane.normal
+            result[:plane_dist] = plane.dist
+          else
+            result[:plane_normal] = -plane.normal
+            result[:plane_dist] = -plane.dist
+          end
+        end
+      end
+    end
+  end
+end