rgame 0.1.0

data/lib/rgame/engine/spatial_hash.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A uniform-grid spatial hash for broadphase collision: bucket colliders into
+    # fixed-size cells, then test only candidates that share a cell instead of every
+    # pair. Pure logic; no graphics.
+    #
+    # Typical per-frame use: `clear`, `insert` every collider of the static set
+    # (here: rocks), then `query` around each moving collider (bullets, the ship).
+    #
+    #   hash.clear
+    #   rocks.each { |r| hash.insert(r, *r.aabb) }
+    #   hash.query(*bullet.aabb) { |rock| ...narrowphase... }
+    class SpatialHash
+      # Cell (col, row) → one integer key. The offset keeps negative cells (objects
+      # off-screen / mid-wrap) non-negative; the stride keeps pairs unique. Both fit
+      # in a tagged Fixnum, so keying allocates nothing.
+      OFFSET = 1 << 20
+      STRIDE = 1 << 21
+
+      def initialize(cell_size:)
+        @cell_size = cell_size
+        @buckets = Hash.new { |h, key| h[key] = [] }
+      end
+
+      # Reuse the bucket arrays across frames (clear contents, keep capacity).
+      def clear
+        @buckets.each_value(&:clear)
+      end
+
+      def insert(item, x, y, w, h)
+        each_cell(x, y, w, h) { |key| @buckets[key] << item }
+      end
+
+      # Yield every item whose buckets overlap the region. Dedup contract: an item
+      # spanning several cells may be yielded more than once. Narrowphase callers
+      # must already guard with `next if a.dead? || b.dead?` to make hits idempotent,
+      # so we skip a per-query visited set and stay allocation-free.
+      def query(x, y, w, h, &)
+        each_cell(x, y, w, h) do |key|
+          bucket = @buckets[key]
+          bucket.each(&) unless bucket.empty?
+        end
+      end
+
+      # Broadphase a circle: yield every item bucketed in a cell the circle's bounding
+      # box covers — the radial counterpart to #query, for range/nearest lookups. Same
+      # dedup contract (an item may be yielded more than once; the narrowphase caller
+      # refines by true distance). Allocation-free.
+      def query_circle(cx, cy, r, &)
+        d = r * 2
+        query(cx - r, cy - r, d, d, &)
+      end
+
+      private
+
+      def each_cell(x, y, w, h)
+        col0 = (x / @cell_size).floor
+        row0 = (y / @cell_size).floor
+        col1 = ((x + w) / @cell_size).floor
+        row1 = ((y + h) / @cell_size).floor
+        row0.upto(row1) do |row|
+          col0.upto(col1) do |col|
+            yield (col + OFFSET) * STRIDE + (row + OFFSET)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/tile_collision.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Axis-separated AABB-vs-tile collision resolution (pure). `solid` is a callable
+    # `solid.call(col, row) -> bool`. Resolve X then Y (with the X result) to get
+    # wall-sliding. Assumes per-step movement smaller than a tile (no tunneling),
+    # which holds for our speeds.
+    class TileCollision
+      EPS = 1e-9
+
+      def initialize(tile_width:, tile_height:, solid:)
+        @tile_width = tile_width
+        @tile_height = tile_height
+        @solid = solid
+      end
+
+      # Move an AABB (top-left x, y; size w, h) by dx, snapping flush against solids.
+      def resolve_x(x, y, w, h, dx)
+        nx = x + dx
+        return nx if dx.zero?
+
+        first_row = (y / @tile_height).floor
+        last_row  = ((y + h - EPS) / @tile_height).floor
+
+        if dx.positive?
+          col = ((nx + w - EPS) / @tile_width).floor
+          return col * @tile_width - w if solid_in_rows?(col, first_row, last_row)
+        else
+          col = (nx / @tile_width).floor
+          return (col + 1) * @tile_width if solid_in_rows?(col, first_row, last_row)
+        end
+        nx
+      end
+
+      def resolve_y(x, y, w, h, dy)
+        ny = y + dy
+        return ny if dy.zero?
+
+        first_col = (x / @tile_width).floor
+        last_col  = ((x + w - EPS) / @tile_width).floor
+
+        if dy.positive?
+          row = ((ny + h - EPS) / @tile_height).floor
+          return row * @tile_height - h if solid_in_cols?(row, first_col, last_col)
+        else
+          row = (ny / @tile_height).floor
+          return (row + 1) * @tile_height if solid_in_cols?(row, first_col, last_col)
+        end
+        ny
+      end
+
+      private
+
+      # Plain integer loops rather than (a..b).any? { ... }: the Range literal would
+      # allocate on this per-frame collision path.
+      def solid_in_rows?(col, first_row, last_row)
+        row = first_row
+        while row <= last_row
+          return true if @solid.call(col, row)
+
+          row += 1
+        end
+        false
+      end
+
+      def solid_in_cols?(row, first_col, last_col)
+        col = first_col
+        while col <= last_col
+          return true if @solid.call(col, row)
+
+          col += 1
+        end
+        false
+      end
+    end
+  end
+end

data/lib/rgame/engine/tile_map.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+require 'base64'
+require 'zlib'
+
+require_relative '../util'
+require_relative 'tileset'
+
+module RGame
+  module Engine
+    # An orthogonal tile map parsed from a Tiled .tmx. Holds the per-layer gid
+    # arrays and geometry, and answers collision queries via its Tileset.
+    #
+    # `parse` takes a *string*, so the parsing itself needs no filesystem at all;
+    # `load` adds the file plumbing on top — reading the .tmx, following it to the
+    # .tsx it names, and working out where the tileset image sits relative to
+    # that. Both belong here. What does *not* is the image: a texture is a GPU
+    # handle, and the renderer that owns one lives a layer below and may not name
+    # this class (see CLAUDE.md, "The rule points both ways"). So `load` hands
+    # back a path and stops there.
+    class TileMap
+      FLIP_MASK = 0x1FFFFFFF # strip Tiled's flip/rotation flags from a gid
+
+      attr_reader :width, :height, :tile_width, :tile_height,
+                  :pixel_width, :pixel_height, :tileset_source, :firstgid
+      attr_accessor :tileset
+
+      # Reads a .tmx and everything it points at, returning `[map, image_path]`.
+      #
+      # Two values rather than one because they are two kinds of thing: the map is
+      # the grid, and the path is where its pixels happen to live. Keeping the
+      # second off the map means a stand-in map in a spec has one less method to
+      # answer, and the renderer's protocol stays "things about the grid".
+      #
+      # Every path is resolved relative to the file that named it — the .tsx
+      # relative to the .tmx, the image relative to the .tsx — which is what Tiled
+      # itself writes and what lets a map be moved as a set.
+      def self.load(tmx_path)
+        map = parse(File.read(tmx_path))
+
+        tsx_path = File.join(File.dirname(tmx_path), map.tileset_source)
+        map.tileset = Tileset.parse(File.read(tsx_path), firstgid: map.firstgid)
+
+        [map, File.join(File.dirname(tsx_path), map.tileset.image_source)]
+      end
+
+      def self.parse(tmx_string)
+        root = REXML::Document.new(tmx_string).root
+        tileset_el = root.elements['tileset']
+
+        layers = []
+        above = []
+        root.each_element('layer') do |layer_el|
+          raw = Base64.decode64(layer_el.elements['data'].text.strip)
+          gids = Zlib::Inflate.inflate(raw).unpack('V*')
+          gids.map! { |g| g & FLIP_MASK }
+          layers << gids
+          above << layer_flag?(layer_el, 'above')
+        end
+
+        new(
+          width: root.attributes['width'].to_i,
+          height: root.attributes['height'].to_i,
+          tile_width: root.attributes['tilewidth'].to_i,
+          tile_height: root.attributes['tileheight'].to_i,
+          tileset_source: tileset_el.attributes['source'],
+          firstgid: tileset_el.attributes['firstgid'].to_i,
+          layers: layers,
+          above: above
+        )
+      end
+
+      # True if a layer carries a Tiled bool custom property `name` set to "true".
+      def self.layer_flag?(layer_el, name)
+        props = layer_el.elements['properties']
+        return false unless props
+
+        props.each_element('property') do |property|
+          return property.attributes['value'] == 'true' if property.attributes['name'] == name
+        end
+        false
+      end
+
+      def initialize(width:, height:, tile_width:, tile_height:, tileset_source:, firstgid:, layers:, above: [])
+        @width = width
+        @height = height
+        @tile_width = tile_width
+        @tile_height = tile_height
+        @pixel_width = width * tile_width
+        @pixel_height = height * tile_height
+        @tileset_source = tileset_source
+        @firstgid = firstgid
+        @above = above
+        @tileset = nil
+        @tiles = build_tiles(layers)
+      end
+
+      def layer_count
+        @tiles.depth
+      end
+
+      # Whether a layer is drawn *above* the actors (a tree canopy, roof, etc.) rather
+      # than beneath them. Marked in Tiled with a bool layer property `above`; layers
+      # without it default to below. Purely a rendering distinction (collision still
+      # considers every layer).
+      def above_layer?(index)
+        @above[index] || false
+      end
+
+      def in_bounds?(col, row)
+        col >= 0 && row >= 0 && col < @width && row < @height
+      end
+
+      def gid(layer_index, col, row)
+        return 0 unless in_bounds?(col, row)
+
+        @tiles[col, row, layer_index]
+      end
+
+      # Solid if any layer has a solid tile at (col, row). Out of bounds is not solid
+      # — the camera/bounds clamp keeps the player inside the map.
+      def solid_tile?(col, row)
+        return false unless in_bounds?(col, row)
+
+        @tiles.depth.times { |layer| return true if @tileset.solid?(@tiles[col, row, layer]) }
+        false
+      end
+
+      def solid_at?(world_x, world_y)
+        solid_tile?((world_x / @tile_width).floor, (world_y / @tile_height).floor)
+      end
+
+      private
+
+      # Pack the parsed per-layer gid rows into one flat Tensor ([col, row, layer]).
+      def build_tiles(layers)
+        tiles = Util::Tensor.new(@width, @height, layers.length, initial: 0)
+        layers.each_with_index do |gids, layer|
+          @height.times do |row|
+            base = row * @width
+            @width.times { |col| tiles[col, row, layer] = gids[base + col] }
+          end
+        end
+        tiles
+      end
+    end
+  end
+end

data/lib/rgame/engine/tileset.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require 'rexml/document'
+
+module RGame
+  module Engine
+    # Tile-type data parsed from a Tiled .tsx (pure; no graphics). Knows tile geometry,
+    # sheet columns, per-tile animations, and which tiles are solid. Solidity is
+    # *baked into the asset*: a tile is solid when it carries a Tiled collision shape
+    # (a per-tile `<objectgroup>` with at least one object), authored in Tiled's
+    # collision editor — so the map owns its collision, not the engine. `solid_ids`
+    # stays writable for games that want to override or augment it.
+    # Animation frames resolve from elapsed time so the renderer stays a thin layer.
+    class Tileset
+      Frame = Struct.new(:tile_id, :duration)
+
+      attr_reader :firstgid, :columns, :tile_width, :tile_height, :image_source, :animations
+      attr_accessor :solid_ids # Set of *local* tile ids treated as solid
+
+      def self.parse(tsx_string, firstgid:)
+        root = REXML::Document.new(tsx_string).root
+
+        animations = {}
+        solid = Set.new
+        root.each_element('tile') do |tile_el|
+          id = tile_el.attributes['id'].to_i
+          animations[id] = parse_animation(tile_el)
+          solid << id if collision_shape?(tile_el)
+        end
+        animations.compact!
+
+        new(
+          firstgid: firstgid,
+          columns: root.attributes['columns'].to_i,
+          tile_width: root.attributes['tilewidth'].to_i,
+          tile_height: root.attributes['tileheight'].to_i,
+          image_source: root.elements['image'].attributes['source'],
+          animations: animations,
+          solid_ids: solid
+        )
+      end
+
+      # Frames for an animated tile, or nil (compacted away) for a static one.
+      def self.parse_animation(tile_el)
+        anim = tile_el.elements['animation']
+        return unless anim
+
+        anim.get_elements('frame').map do |f|
+          Frame.new(f.attributes['tileid'].to_i, f.attributes['duration'].to_i)
+        end
+      end
+
+      # A tile is solid if it carries a Tiled collision shape — an `<objectgroup>`
+      # with at least one object (the per-tile collision editor's output).
+      def self.collision_shape?(tile_el)
+        group = tile_el.elements['objectgroup']
+        !group.nil? && !group.elements['object'].nil?
+      end
+
+      def initialize(firstgid:, columns:, tile_width:, tile_height:, image_source:, animations:, solid_ids: Set.new)
+        @firstgid = firstgid
+        @columns = columns
+        @tile_width = tile_width
+        @tile_height = tile_height
+        @image_source = image_source
+        @animations = animations
+        @solid_ids = solid_ids
+      end
+
+      def animated_ids
+        @animations.keys
+      end
+
+      def local_id(gid)
+        gid - @firstgid
+      end
+
+      def solid?(gid)
+        return false if gid.zero?
+
+        @solid_ids.include?(local_id(gid))
+      end
+
+      # The local tile id to draw for `local` at time `ms`, following its animation
+      # (or `local` itself if the tile isn't animated).
+      def frame_local_id(local, ms)
+        frames = @animations[local]
+        return local unless frames
+
+        total = frames.sum(&:duration)
+        t = ms % total
+        frames.each do |frame|
+          return frame.tile_id if t < frame.duration
+
+          t -= frame.duration
+        end
+        frames.last.tile_id
+      end
+    end
+  end
+end

data/lib/rgame/engine/timer.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A repeating interval timer for periodic events that aren't driven by input — a
+    # spawner emitting an enemy every N seconds, a tower's fire rate, a wave clock.
+    #
+    # It only accumulates time; the owner decides what each elapsed interval means. That
+    # split lets one primitive serve both styles: "act automatically" (consume every ready
+    # interval) and "stay loaded until conditions allow" (check `ready?`, but `consume`
+    # only when actually acting — so a tower with no target keeps its shot ready instead of
+    # wasting it). Pure and allocation-free, so it ticks on the per-frame path.
+    #
+    #   timer = Engine::Timer.new(0.8)
+    #   timer.update(dt)
+    #   if timer.ready?       # at least one whole interval has passed
+    #     timer.consume       # deduct it (remainder carries forward, so timing won't drift)
+    #     spawn_enemy
+    #   end
+    class Timer
+      attr_accessor :interval
+
+      def initialize(interval)
+        @interval = interval
+        @elapsed = 0.0
+      end
+
+      # Advance by one timestep. Returns self so callers can chain.
+      def update(dt)
+        @elapsed += dt
+        self
+      end
+
+      # Has at least one whole interval accumulated since the last consume?
+      def ready? = @elapsed >= @interval
+
+      # Deduct one interval after acting on a ready timer. Carries the remainder forward
+      # (rather than zeroing) so a long-running cadence doesn't drift. Returns self.
+      def consume
+        @elapsed -= @interval
+        self
+      end
+
+      # Drop any accumulated time — e.g. after retuning the interval. Returns self.
+      def reset
+        @elapsed = 0.0
+        self
+      end
+    end
+  end
+end

data/lib/rgame/engine.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+# RGame::Engine — the scene graph a game is written against: nodes, components,
+# signals, scenes, collision, tile maps, pathing, pooling.
+#
+# Pure Ruby, and it links nothing. It may hold `RGame::Util` values but may not
+# name `RGame::Core` at all, reaching the platform only through objects handed
+# to it — a `renderer` passed into `draw`, an audio server behind
+# `AudioDirector`. See CLAUDE.md, "The three layers, and who may talk to whom".
+#
+# That is what lets the whole layer be specified with no window, no GPU and no
+# clock: `spec/` drives `update(dt)` directly and can run a simulated hour in
+# milliseconds.
+#
+# Loaded by `require "rgame"` along with Util, since between them they are
+# everything that runs without a window. Requirable on its own too — hence the
+# `util` require below rather than relying on `rgame.rb` to have got there
+# first: `TileMap` holds a `Util::Tensor`, which is exactly the dependency the
+# three-layer rule allows and this file therefore has to declare.
+require_relative 'util'
+
+require_relative 'engine/matrix'
+require_relative 'engine/signal'
+require_relative 'engine/node2d'
+require_relative 'engine/component'
+require_relative 'engine/animation_set'
+require_relative 'engine/animator'
+require_relative 'engine/camera'
+require_relative 'engine/camera_view'
+require_relative 'engine/path'
+require_relative 'engine/timer'
+require_relative 'engine/tileset'
+require_relative 'engine/tile_map'
+require_relative 'engine/tile_collision'
+require_relative 'engine/collision_box'
+require_relative 'engine/collision_system'
+require_relative 'engine/circle_collider'
+require_relative 'engine/spatial_hash'
+require_relative 'engine/pool'
+require_relative 'engine/resettable'
+require_relative 'engine/audio_bus'
+require_relative 'engine/audio_director'
+require_relative 'engine/i18n'
+require_relative 'engine/cached_label'
+require_relative 'engine/debug_overlay'
+require_relative 'engine/body'
+require_relative 'engine/actor'
+require_relative 'engine/input/actions'
+require_relative 'engine/input/action_mapper'
+require_relative 'engine/input/player_controller'
+require_relative 'engine/scene/scene_stack'
+require_relative 'engine/components/velocity'
+require_relative 'engine/components/pool'
+require_relative 'engine/components/path_follow'
+require_relative 'engine/components/timer'
+require_relative 'engine/components/screen_wrap'
+require_relative 'engine/components/despawn_offscreen'
+require_relative 'engine/components/circle_collider'
+require_relative 'engine/components/collision_world'
+require_relative 'engine/components/targeting'
+require_relative 'engine/components/sprite'
+require_relative 'engine/components/thrust_controller'
+require_relative 'engine/components/action_trigger'
+require_relative 'engine/components/tile_world'
+require_relative 'engine/components/character_body'
+require_relative 'engine/components/player_controller'
+require_relative 'engine/components/wander_controller'
+require_relative 'engine/components/animated_sprite'

data/lib/rgame/fonts/OFL.txt

@@ -0,0 +1,102 @@
+Digitized data copyright (c) 2010 Google Corporation
+	with Reserved Font Arimo, Tinos and Cousine.
+Copyright (c) 2012 Red Hat, Inc.
+	with Reserved Font Name Liberation.
+
+This Font Software is licensed under the SIL Open Font License,
+Version 1.1.
+
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+
+PREAMBLE The goals of the Open Font License (OFL) are to stimulate
+worldwide development of collaborative font projects, to support the font
+creation efforts of academic and linguistic communities, and to provide
+a free and open framework in which fonts may be shared and improved in
+partnership with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves.
+The fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works.  The fonts and derivatives,
+however, cannot be released under any other type of license.  The
+requirement for fonts to remain under this license does not apply to
+any document created using the fonts or their derivatives.
+
+ 
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such.
+This may include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components
+as distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting ? in part or in whole ?
+any of the components of the Original Version, by changing formats or
+by porting the Font Software to a new environment.
+
+"Author" refers to any designer, engineer, programmer, technical writer
+or other person who contributed to the Font Software.
+
+
+PERMISSION & CONDITIONS
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,in
+   Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+   redistributed and/or sold with any software, provided that each copy
+   contains the above copyright notice and this license. These can be
+   included either as stand-alone text files, human-readable headers or
+   in the appropriate machine-readable metadata fields within text or
+   binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+   Name(s) unless explicit written permission is granted by the
+   corresponding Copyright Holder. This restriction only applies to the
+   primary font name as presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+   Software shall not be used to promote, endorse or advertise any
+   Modified Version, except to acknowledge the contribution(s) of the
+   Copyright Holder(s) and the Author(s) or with their explicit written
+   permission.
+
+5) The Font Software, modified or unmodified, in part or in whole, must
+   be distributed entirely under this license, and must not be distributed
+   under any other license. The requirement for fonts to remain under
+   this license does not apply to any document created using the Font
+   Software.
+
+
+ 
+TERMINATION
+This license becomes null and void if any of the above conditions are not met.
+
+ 
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT.  IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM OTHER
+DEALINGS IN THE FONT SOFTWARE.
+