rgame 0.1.0

data/lib/rgame/engine/components/targeting.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Picks an enemy for the owning node (a tower) to aim at: each update it queries the
+      # scene's CollisionWorld around the node's world origin and exposes the chosen target
+      # via #target (the enemy node, or nil). The owner reads it to fire — Targeting only
+      # selects, it never moves or shoots.
+      #
+      # The CollisionWorld it queries is the same broadphase enemies register with through
+      # their CircleCollider, so targeting needs no enemy list of its own. The `layer`
+      # restricts candidates (a tower wants :enemy, not other towers or projectiles).
+      #
+      # Policies (how to choose among the candidates in range):
+      #   - :nearest — the closest enemy (the default; one broadphase nearest-lookup).
+      # More policies (e.g. furthest-along-path) arrive with the state they need.
+      class Targeting < Engine::Component
+        POLICIES = %i[nearest].freeze
+
+        def initialize(range:, policy: :nearest, layer: nil)
+          super()
+          raise ArgumentError, "unknown targeting policy #{policy.inspect}" unless POLICIES.include?(policy)
+
+          @range = range
+          @policy = policy
+          @layer = layer
+          @target = nil
+        end
+
+        # The chosen enemy node, or nil when nothing is in range. Refreshed every update.
+        attr_reader :target
+
+        # Pull the broadphase once it's reachable (scene scope, resolved up the tree).
+        def on_attach = @world = node.system(CollisionWorld)
+
+        def update(_dt)
+          collider = pick
+          @target = collider&.node
+        end
+
+        private
+
+        # Allocation-free: a symbol dispatch over a known-small policy set, each delegating
+        # to an allocation-free CollisionWorld query.
+        def pick
+          case @policy
+          when :nearest then @world.nearest(node.abs_x, node.abs_y, @range, layer: @layer)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/components/thrust_controller.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Inertial "ship" flight on top of a Velocity sibling: a turn axis rotates the
+      # node (angular velocity) and a thrust axis accelerates it along its heading,
+      # with optional drag and a top-speed clamp. Reads intent in `control` and
+      # integrates it in `update`, so it composes with the normal phase order.
+      #
+      # Heading convention: angle 0 points along +x ("right"), so forward is
+      # (cos θ, sin θ) — consistent with the renderer's clockwise rotation under a y-down screen
+      # (e.g. +90° faces down). Firing is intentionally NOT here — see ActionTrigger +
+      # the owning node, which knows its muzzle geometry.
+      class ThrustController < Engine::Component
+        def initialize(turn_speed:, accel:, max_speed:, drag: 0.0,
+                       turn_action: :turn, thrust_action: :thrust)
+          super()
+          @turn_speed = turn_speed
+          @accel = accel
+          @max_speed = max_speed
+          @drag = drag
+          @turn_action = turn_action
+          @thrust_action = thrust_action
+          @thrust = 0.0
+        end
+
+        # The Velocity sibling is only guaranteed present once attached to a node.
+        def on_attach = @velocity = node.get_component(Velocity)
+
+        def control(actions)
+          @velocity.spin = actions.axis(@turn_action) * @turn_speed
+          @thrust = actions.axis(@thrust_action)
+        end
+
+        def update(dt)
+          if @thrust != 0.0
+            @velocity.vx += Math.cos(node.angle) * @accel * @thrust * dt
+            @velocity.vy += Math.sin(node.angle) * @accel * @thrust * dt
+          end
+          apply_drag(dt) if @drag.positive?
+          clamp_speed
+        end
+
+        private
+
+        def apply_drag(dt)
+          factor = 1.0 - (@drag * dt)
+          factor = 0.0 if factor.negative?
+          @velocity.vx *= factor
+          @velocity.vy *= factor
+        end
+
+        def clamp_speed
+          speed = Math.hypot(@velocity.vx, @velocity.vy)
+          return unless speed > @max_speed
+
+          scale = @max_speed / speed
+          @velocity.vx *= scale
+          @velocity.vy *= scale
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/components/tile_world.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # The scene-scoped tile world: a system component (it lives on the scene node and
+      # is found with node.system(TileWorld)) that owns the parsed Engine::TileMap and
+      # everything an actor needs from it — collision against the solid tiles, the world
+      # bounds, and drawing the map through the scene's camera.
+      #
+      # Collision reuses Engine::CollisionSystem (TileCollision + a world-bounds clamp);
+      # the tile solidity is whatever the map's tileset reports (baked per-tile in Tiled).
+      #
+      # Drawing splits into two z bands so actors can sit between them: the below band
+      # (ground, same-level detail) at GROUND_Z and the above band (canopies, roofs) at
+      # OVERLAY_Z. Actors draw at a z in between (the renderer sorts by z, so the
+      # draw-call order doesn't matter). The camera is centred by the scene before any
+      # drawing.
+      #
+      # It also owns the map's **animation clock**. Nothing below reads a wall clock —
+      # see CLAUDE.md, "`draw` renders state; time enters through `update`" — so the
+      # elapsed seconds animated tiles run on are accumulated here and handed down at
+      # draw time. Stop calling `update` and the water freezes, which is what pausing
+      # should look like.
+      class TileWorld < Engine::Component
+        GROUND_Z  = 0
+        OVERLAY_Z = 20
+
+        def initialize(map:, tilemap_id:, camera:)
+          super()
+          @map = map
+          @tilemap_id = tilemap_id
+          @camera = camera
+          @elapsed = 0.0
+          @collision = Engine::CollisionSystem.new(
+            tile_collision: Engine::TileCollision.new(
+              tile_width: map.tile_width, tile_height: map.tile_height,
+              solid: ->(col, row) { map.solid_tile?(col, row) }
+            ),
+            world_width: map.pixel_width, world_height: map.pixel_height
+          )
+        end
+
+        def world_width = @map.pixel_width
+        def world_height = @map.pixel_height
+
+        # Move an actor (responds to x/y/collision_box) by (dx, dy), sliding along solids
+        # and clamped inside the world. Delegates to the reused collision system.
+        def move(actor, dx, dy) = @collision.move(actor, dx, dy)
+
+        def solid?(col, row) = @map.solid_tile?(col, row)
+
+        # Advances the tile animations. Seconds, like every other duration here.
+        def update(dt)
+          @elapsed += dt
+        end
+
+        def draw(renderer)
+          renderer.tilemap(@tilemap_id, @camera.x, @camera.y,
+                           @camera.viewport_width, @camera.viewport_height, elapsed: @elapsed)
+          renderer.tilemap_overlay(@tilemap_id, @camera.x, @camera.y,
+                                   @camera.viewport_width, @camera.viewport_height,
+                                   z: OVERLAY_Z, elapsed: @elapsed)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/components/timer.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A node-driven interval timer: it rides the node's update tick — so nothing can
+      # forget to advance it — and emits `on_timeout` each time a whole interval elapses.
+      # It wraps the pure Engine::Timer, reusing its carry-forward `consume` (the remainder
+      # rolls over, so the cadence doesn't drift); this only adds the per-frame drive and
+      # the signal.
+      #
+      #   timer = node.add_component(Engine::Components::Timer.new(0.8), as: :spawn)
+      #   timer.on_timeout { spawn_enemy }
+      #
+      # `repeating: false` makes it a one-shot: it fires `on_timeout` exactly once and then
+      # goes inert — the fixed-board despawn case (a projectile that vanishes after N
+      # seconds, where DespawnOffscreen doesn't apply):
+      #
+      #   life = node.add_component(Engine::Components::Timer.new(2.0, repeating: false), as: :despawn)
+      #   life.on_timeout { node.queue_free }
+      #
+      # The countdown restarts in `on_attach`, so a pooled node reacquired and re-added
+      # starts fresh — a recycled projectile gets its full interval (and a one-shot can fire
+      # again) rather than inheriting the previous life's elapsed time.
+      #
+      # When a node needs more than one (a spawn cadence and a wave cadence), give them
+      # distinct `as:` names — a node holds one component per slot.
+      class Timer < Engine::Component
+        signal :on_timeout # emits no payload
+
+        def initialize(interval, repeating: true)
+          super()
+          @timer = Engine::Timer.new(interval)
+          @repeating = repeating
+          @done = false
+        end
+
+        def interval = @timer.interval
+
+        def interval=(seconds)
+          @timer.interval = seconds
+        end
+
+        # Start the countdown fresh whenever the node (re-)enters the tree, so a pooled node
+        # never inherits a previous life's accumulated time or spent one-shot.
+        def on_attach = reset
+
+        # Advance one step and fire on_timeout once per whole interval that elapsed — so a
+        # single long step still emits the right number of times (catch-up, not drift). A
+        # one-shot (`repeating: false`) fires once and then stops accumulating.
+        def update(dt)
+          return if @done
+
+          @timer.update(dt)
+          while @timer.ready?
+            @timer.consume
+            on_timeout_signal.emit
+            unless @repeating
+              @done = true
+              break
+            end
+          end
+        end
+
+        # Back to a fresh timer: drop accumulated time and re-arm a spent one-shot (e.g.
+        # after retuning the interval, or when a pooled node is reused). Returns self.
+        def reset
+          @timer.reset
+          @done = false
+          self
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/components/velocity.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # Integrates linear and angular velocity into the node's transform each step.
+      # Free-moving entities (rocks, bullets) use it alone; a controller component
+      # (or the node's own control hook) writes vx/vy/spin as intent. From Body#integrate.
+      class Velocity < Engine::Component
+        attr_accessor :vx, :vy, :spin
+
+        def initialize(vx: 0.0, vy: 0.0, spin: 0.0)
+          super()
+          @vx = vx
+          @vy = vy
+          @spin = spin
+        end
+
+        def update(dt)
+          node.x += @vx * dt
+          node.y += @vy * dt
+          node.angle += @spin * dt
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/components/wander_controller.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    module Components
+      # A simple AI driver for a CharacterBody sibling: every so often it rolls a new
+      # direction (one of eight, or idle) and holds it until a timer elapses — or until a
+      # wall blocks it, at which point it re-rolls early instead of pushing into the wall.
+      # The RNG is injected so behaviour is deterministic in tests.
+      class WanderController < Engine::Component
+        MOVED_EPS = 1e-6
+        DIRECTIONS = [
+          [-1, 0], [1, 0], [0, -1], [0, 1],
+          [-1, -1], [1, -1], [-1, 1], [1, 1]
+        ].freeze
+
+        def initialize(rng: Random.new, change_interval: 1.0..3.0, idle_chance: 0.25)
+          super()
+          @rng = rng
+          @change_interval = change_interval
+          @idle_chance = idle_chance
+          @timer = 0.0 # rolls a direction on the first update
+        end
+
+        def on_attach
+          @body = node.get_component(CharacterBody)
+          @last_x = node.x
+          @last_y = node.y
+        end
+
+        def update(dt)
+          blocked = intending_to_move? && !moved_since_last?
+          @last_x = node.x
+          @last_y = node.y
+
+          @timer -= dt
+          reroll if blocked || @timer <= 0.0
+        end
+
+        private
+
+        def intending_to_move? = !@body.move_x.zero? || !@body.move_y.zero?
+
+        def moved_since_last?
+          (node.x - @last_x).abs > MOVED_EPS || (node.y - @last_y).abs > MOVED_EPS
+        end
+
+        def reroll
+          if @rng.rand < @idle_chance
+            @body.set_intent(0.0, 0.0)
+          else
+            dx, dy = DIRECTIONS.sample(random: @rng)
+            @body.set_intent(dx.to_f, dy.to_f)
+          end
+          @timer = @rng.rand(@change_interval)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/engine/debug_overlay.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # A hard-wired development overlay, toggled by F1 (see RGame::Game), reporting
+    # runtime health in the bottom-right corner: frame rate (FPS), the process'
+    # cumulative allocated-object count (OBJ), and the objects allocated since the last
+    # frame (Δ/f).
+    #
+    # **Δ/f is the one to watch, and it is a standing guard rather than a
+    # diagnostic for one past bug.** A clean per-frame path holds it near zero; a
+    # steady nonzero number is a garbage collection being scheduled. The cost is
+    # invisible by every other measure — nothing looks wrong, nothing is slower,
+    # until a pause lands mid-frame — so without a number on screen it is not
+    # noticed at all.
+    #
+    # Every layer can break it and each has its own way of doing so. Core can
+    # allocate in a binding, the engine layer in a component's `draw`, and game
+    # code in a scene that builds a string or an array per frame. RuboCop's
+    # `Game/NoInterpolationInHotPath` and `Game/NoNeedlessAllocation` catch the
+    # shapes they can see in *this* repo; they cannot see a game built on top,
+    # and they cannot see an allocation that happens inside a method they think
+    # is cheap. This can.
+    #
+    # Pure: it reads only GC.stat and draws against the renderer interface, so it stays
+    # headless-testable. The crux is that it must not allocate while drawing — the values
+    # change every frame, so the usual "cache the string, rebuild on change" trick would
+    # allocate a String per frame, and the meter would be measuring itself. Instead
+    # numbers are drawn digit-by-digit from a fixed set of pre-built single-character
+    # strings, which the font caches per glyph.
+    class DebugOverlay
+      DIGITS = %w[0 1 2 3 4 5 6 7 8 9].freeze
+
+      FPS_LABEL   = 'FPS'
+      OBJ_LABEL   = 'OBJ'
+      DELTA_LABEL = 'Δ/f'
+
+      COLOR = [80, 255, 120].freeze # frozen so the renderer caches the resolved colour
+      Z     = 1_000_000             # above any scene content
+      PAD   = 8                     # margin from the screen edge
+      GAP   = 8                     # space between a label and its number
+
+      def initialize
+        @visible = false
+        @prev_allocated = 0
+        @digit_widths  = Array.new(10) # measured once, then reused
+        @label_widths  = {}            # measured once per label, then reused
+      end
+
+      def visible? = @visible
+
+      def toggle
+        @visible = !@visible
+        # Baseline the counter on reveal so the first Δ/f isn't the whole run's history.
+        @prev_allocated = GC.stat(:total_allocated_objects) if @visible
+      end
+
+      def draw(renderer, width, height, fps)
+        return unless @visible
+
+        allocated = GC.stat(:total_allocated_objects)
+        delta = allocated - @prev_allocated
+        @prev_allocated = allocated
+
+        line_h  = renderer.text_height
+        right_x = width - PAD
+        top_y   = height - PAD - (line_h * 3)
+
+        draw_line(renderer, FPS_LABEL, fps, right_x, top_y)
+        draw_line(renderer, OBJ_LABEL, allocated, right_x, top_y + line_h)
+        draw_line(renderer, DELTA_LABEL, delta, right_x, top_y + (line_h * 2))
+      end
+
+      private
+
+      # A right-aligned "label  number" row ending at right_x.
+      def draw_line(renderer, label, value, right_x, y)
+        number_left = draw_uint(renderer, value, right_x, y)
+        renderer.text(label, number_left - GAP - label_width(renderer, label), y, z: Z, color: COLOR)
+      end
+
+      # Draw a non-negative integer right-aligned ending at right_x, digit by digit so no
+      # String is built per frame. Returns the x of the leftmost digit.
+      def draw_uint(renderer, value, right_x, y)
+        x = right_x
+        more = true
+        while more
+          digit = value % 10
+          value /= 10
+          x -= digit_width(renderer, digit)
+          renderer.text(DIGITS[digit], x, y, z: Z, color: COLOR)
+          more = value.positive?
+        end
+        x
+      end
+
+      def digit_width(renderer, digit)
+        @digit_widths[digit] ||= renderer.text_width(DIGITS[digit])
+      end
+
+      def label_width(renderer, label)
+        @label_widths[label] ||= renderer.text_width(label)
+      end
+    end
+  end
+end

data/lib/rgame/engine/i18n.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module RGame
+  module Engine
+    # Minimal localization: per-locale translation tables (loaded from YAML or a Hash),
+    # `t(key)` with `%{var}` interpolation and a fallback locale, and a `generation`
+    # counter that ticks whenever the locale changes — so cached UI text knows when to
+    # re-resolve without polling every frame. A global module (like EventDispatcher),
+    # so `t` is reachable anywhere. Pure Ruby; YAML is the only (stdlib) dependency.
+    module I18n
+      class << self
+        attr_reader :generation
+
+        # The locale `t` falls back to when the current locale lacks a key.
+        def default = @fallback
+
+        def default=(locale)
+          @fallback = locale.to_sym
+        end
+
+        def reset
+          @locales = {}
+          @current = :en
+          @fallback = :en
+          @generation = 0
+        end
+
+        # Register a locale's translations (nested Hashes allowed). Keys are symbolized
+        # so YAML ("string keys") and inline symbol keys look the same to `t`.
+        def load(locale, translations)
+          @locales[locale.to_sym] = symbolize(translations)
+          self
+        end
+
+        def load_file(locale, path)
+          load(locale, YAML.load_file(path))
+        end
+
+        def locale = @current
+
+        # Switching the locale bumps the generation so observers re-resolve their text.
+        def locale=(locale)
+          locale = locale.to_sym
+          return if locale == @current
+
+          @current = locale
+          @generation += 1
+        end
+
+        def available = @locales.keys
+
+        # Resolve a dotted key ("menu.title" or :menu_title) in the current locale, then
+        # the fallback locale, then the key itself; interpolate %{var} from `vars`.
+        #
+        # Pass `count:` to pluralize: the key's value is then a table of forms
+        # ({ one:, other:, optionally zero: }), and `count` is also exposed to
+        # interpolation as %{count}. English/German use the one/other rule.
+        def t(key, count: nil, **vars)
+          value = lookup(@current, key) || lookup(@fallback, key)
+          value = pluralize(value, count) if count && value.is_a?(Hash)
+          return key.to_s unless value.is_a?(String)
+
+          vars = vars.merge(count: count) if count
+          vars.empty? ? value : (value % vars)
+        end
+
+        private
+
+        def pluralize(forms, count)
+          return forms[:zero] if count.zero? && forms.key?(:zero)
+
+          forms[count == 1 ? :one : :other] || forms[:other]
+        end
+
+        def lookup(locale, key)
+          node = @locales[locale]
+          key.to_s.split('.').each do |segment|
+            return nil unless node.is_a?(Hash)
+
+            node = node[segment.to_sym]
+          end
+          node
+        end
+
+        def symbolize(value)
+          return value unless value.is_a?(Hash)
+
+          value.to_h { |k, v| [k.to_sym, symbolize(v)] }
+        end
+      end
+
+      reset
+    end
+  end
+end

data/lib/rgame/engine/input/action_mapper.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Polls an InputBackend through a binding map and produces an Actions snapshot.
+    # The map is `{ action_name => { axis: %i[neg pos] } | { button: %i[ids] } }`;
+    # physical ids are decoupled from any backend's constants (the backend resolves
+    # them), so remapping is just swapping this data.
+    #
+    # Pure logic: the backend is duck-typed — the whole interface is
+    # `down?(physical_id)` — so a test passes a fake and a game passes
+    # `RGame::Core::Input`.
+    class ActionMapper
+      attr_accessor :map
+
+      def initialize(map)
+        @map = map
+        # One reusable snapshot: there's exactly one input state per tick, so we
+        # mutate these in place each poll instead of allocating (after the first
+        # poll warms the hash keys, steady-state polling allocates nothing).
+        # `@prev_held` carries last frame's button state so Actions can answer edge
+        # queries (pressed?/released?).
+        @held = {}
+        @prev_held = {}
+        @axes = {}
+        @actions = Actions.new(held: @held, axes: @axes, prev_held: @prev_held)
+      end
+
+      def poll(backend)
+        # Snapshot this frame's held state as "previous" before recomputing it
+        # (in-place copy: no allocation once the keys exist).
+        @held.each { |name, down| @prev_held[name] = down }
+
+        @map.each do |name, binding|
+          if (axis = binding[:axis])
+            neg, pos = axis
+            @axes[name] = (backend.down?(pos) ? 1.0 : 0.0) - (backend.down?(neg) ? 1.0 : 0.0)
+          end
+          @held[name] = binding[:button].any? { |b| backend.down?(b) } if binding[:button]
+        end
+
+        @actions
+      end
+    end
+  end
+end

data/lib/rgame/engine/input/actions.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # An immutable per-frame snapshot of abstract action state. Game logic reads
+    # this, never physical keys. Built by ActionMapper (or constructed directly in
+    # tests with a fake).
+    #
+    # Edge queries (`pressed?`/`released?`) compare against the previous frame's held
+    # state, so a one-shot action (menu confirm, jump) fires exactly once per press
+    # rather than every frame it's held.
+    class Actions
+      # `held`, `axes` and `prev_held` are mutable hashes the mapper updates in place
+      # each poll, so the snapshot stays a single reused, allocation-free object.
+      def initialize(held: {}, axes: {}, prev_held: {})
+        @held = held
+        @axes = axes
+        @prev_held = prev_held
+      end
+
+      def held?(name)
+        @held.fetch(name, false)
+      end
+
+      # True only on the frame the action transitions up→down.
+      def pressed?(name)
+        @held.fetch(name, false) && !@prev_held.fetch(name, false)
+      end
+
+      # True only on the frame the action transitions down→up.
+      def released?(name)
+        !@held.fetch(name, false) && @prev_held.fetch(name, false)
+      end
+
+      # Analog value in [-1.0, 1.0]; 0.0 if unbound/neutral.
+      def axis(name)
+        @axes.fetch(name, 0.0)
+      end
+    end
+  end
+end

data/lib/rgame/engine/input/player_controller.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module RGame
+  module Engine
+    # Drives an Actor from player input: turns the move_x/move_y actions into a
+    # movement intent. NPC controllers implement the same `intent(dt, input)` seam
+    # and ignore `input`.
+    class PlayerController
+      def intent(_dt, input)
+        [input.axis(:move_x), input.axis(:move_y)]
+      end
+    end
+  end
+end