rgame 0.1.0

data/docs/api/systems.md

@@ -0,0 +1,98 @@
+# Systems & shared resources
+
+Some things a node needs don't live on the node: a tilemap, the world bounds, a
+shared collision world. The engine resolves this the way scene-graph engines do —
+shared resources are **systems that live on an anchor node and are reached by
+walking the tree**, not threaded through constructors. There is **no `GameContext`
+bag**: a system is just an `RGame::Engine::Component` on a boundary node, found with the
+same `get_component` every node already has.
+
+> Status: the anchor + lookup mechanism (`root`, `scene`, `system`), the
+> tree-lifecycle hooks, and deferred removal (`queue_free`) are in place.
+> `examples/14_asteroids` exercises the whole path end to end and shows **both
+> scopes**: a scene-scoped `CollisionWorld` system and a root-scoped `HighScores`
+> system. `examples/15_tiled_world` adds a second scene-scoped system, `TileWorld`
+> (the tile map: collision, world bounds, drawing). More systems arrive with the
+> rest of the component port (see `docs/wip/components.md`).
+
+## Two scopes = two anchor nodes
+
+Scope is a property of the **owner** you attach a system to, not of the system
+itself — the same insight behind Unreal's `UGameInstanceSubsystem` (whole session)
+vs `UWorldSubsystem` (one level), and Godot's autoload singletons vs per-scene
+nodes.
+
+- **Global scope → the root node.** `root` is set once and never changes, reachable
+  from every node. Program-lifetime systems (e.g. an audio bus, i18n) are components
+  on the root: `node.root.get_component(AudioBus)`.
+- **Scene scope → the scene node** (what `SceneStack` pushes). Scene-lifetime systems
+  (the collision world, the tilemap/world-bounds holder) are components on *that*
+  node — born when the scene is pushed, gone when it's popped:
+  `node.scene.get_component(CollisionWorld)`.
+
+## The anchors
+
+Both anchors are **methods that walk the parent chain**, not cached fields. A cached
+back-link set at add-time goes stale when a node is built before it's mounted (its
+children would cache the wrong root); resolving on access can't.
+
+- `root` — `@parent ? @parent.root : self`. The top-most node is its own root.
+- `scene` — the nearest ancestor marked as a scene boundary. `SceneStack#push` marks
+  the pushed scene with `scene.scene = scene`; descendants resolve up to it. Outside
+  any scene, `scene` is `nil`.
+
+### Looking a system up
+
+```ruby
+node.system(CollisionWorld)
+```
+
+`Node2D#system(klass)` checks the **scene scope first, then the global root**, so a
+scene can override a global default and free-standing nodes still find globals. Use
+the explicit anchor (`node.root.get_component` / `node.scene.get_component`) when you
+specifically mean one scope.
+
+## Registering with a system — use the lifecycle, not `initialize`
+
+A system and its clients only connect once everything is **in the live tree**, so
+wiring happens in the tree-lifecycle hooks, never in `initialize` (where a node has
+no anchors). See [Lifecycle](scene_graph.md#lifecycle-constructing-vs-entering-the-tree).
+
+The entered-tree cascade guarantees ordering that makes this safe: a scene's own
+components `on_attach` (so a `CollisionWorld` on the scene node exists), then the
+scene's `on_add`, then its children enter — so by the time a child collider attaches,
+the scene-scoped system it looks up is already there.
+
+```ruby
+# CircleCollider (engine/components/circle_collider.rb) registers itself when it
+# enters the tree and releases the registration when it leaves — the engine fires
+# both hooks, so a spawned/despawned entity can't leak a registration.
+class CircleCollider < RGame::Engine::Component
+  def on_attach = node.system(CollisionWorld).register(self)
+  def on_detach = node.system(CollisionWorld)&.unregister(self)
+end
+```
+
+## Systems that index their clients (the tag-registry pattern)
+
+A many-to-many system (broadphase collision) lives on the scene node and keeps its
+own index of registered clients, so it processes only nearby candidates instead of
+walking the tree for every pair. `CollisionWorld`
+(engine/components/collision_world.rb) holds a `SpatialHash` for exactly this — a
+spatial index of registered colliders, rebuilt each `update`. This indexing is the
+same idea as Godot's **groups**: a registry of node references. It is *not* an ECS —
+it indexes references, carries no component data, and gains none of ECS's
+data-locality; it's a lightweight index.
+
+`CollisionWorld` is layer-agnostic: it reports every overlapping pair by firing each
+collider's `on_hit` signal with the other collider, and the owning node decides what
+a contact *means* by reading the other's `layer` tag:
+
+```ruby
+collider.on_hit { |other| queue_free if other.layer == :bullet } # in a Rock node
+```
+
+Because it's a normal component on the scene node, it rides the `update` traversal
+(its broadphase runs in `update`) and is torn down with the scene. See
+`examples/14_asteroids` for the whole loop: ship, bullets, and rocks spawning,
+colliding, and despawning through this system.

data/docs/api/text.md

@@ -0,0 +1,116 @@
+# Text
+
+```ruby
+require 'rgame'
+require 'rgame/core'
+
+class MyGame < RGame::Core::App
+  def initialize
+    super(width: 800, height: 600, caption: 'demo')
+    @renderer = RGame::Core::Renderer.new(self)
+  end
+
+  def draw
+    @renderer.text('Score: 1200', 10, 10)
+  end
+end
+```
+
+That is the whole of it for most cases — the renderer has a font already, and
+`text` uses it.
+
+## Where text goes
+
+`text(string, x, y, …)` puts the **top-left corner** of the line at `(x, y)`,
+the same corner every other drawing method takes. Typography works from the
+baseline; a caller placing a label does not have to.
+
+```ruby
+renderer.text(string, x, y, z: 10, color: nil, font: nil)
+renderer.text_width(string, font: nil)   # => Float, pixels
+renderer.text_height(font: nil)          # => Integer, the line height
+```
+
+**A string is one line.** Newlines are not special. Two lines are two calls,
+stepped by `text_height`:
+
+```ruby
+lines.each_with_index do |line, i|
+  @renderer.text(line, 10, 10 + (i * @renderer.text_height))
+end
+```
+
+**`text_width` and `text` agree.** They walk the same code, so a label measured
+and then centred lands where it was measured to:
+
+```ruby
+@renderer.text(label, (width - @renderer.text_width(label)) / 2, 20)
+```
+
+Unlike the drawing methods, `text_width` and `text_height` work **outside**
+`draw` — measuring touches no GPU, and laying out a menu happens while updating.
+
+## Fonts
+
+```ruby
+font = RGame::Core::Font.new(app, 18)                          # the shipped font
+font = RGame::Core::Font.new(app, 18, path: 'assets/pixel.ttf')
+
+font.height              # => 18
+font.text_width('Hello') # => 38.7
+
+renderer.text('Hello', 10, 10, font: font)
+```
+
+A `Font` is **one typeface at one pixel size**. Two sizes are two fonts. Like an
+image, it belongs to the app whose GPU context holds its glyphs, and drawing it
+through another app's renderer raises rather than painting blank boxes.
+
+The renderer builds its own font at 18px on first use. Replace it and every
+unqualified `text` call follows:
+
+```ruby
+@renderer.font = RGame::Core::Font.new(self, 24)
+```
+
+A file that cannot be read or is not a TrueType font raises
+`RGame::Core::Font::LoadError`, naming the path.
+
+### The default font, and what it covers
+
+The engine ships **Liberation Sans** and uses it when no path is given. There is
+no font-*name* lookup and no system font database — a font is a file.
+
+That is a deliberate trade. Asking the operating system for "Arial" (which is
+what Gosu does) means a different font on every machine, so a UI laid out on the
+developer's box can overflow on a player's. Shipping one means text renders
+identically everywhere, at the cost of ~400 KB in the gem.
+
+| | |
+|---|---|
+| Covers | English, German, French, Italian, Spanish, Portuguese, Nordic, Polish — in full, including `ß`, `ẞ`, `« »`, curly quotes and `€`. Greek and Cyrillic too. |
+| Does not cover | CJK, Arabic, Hebrew, Devanagari. Pass your own font file for those; no font of this size includes them. |
+
+Text is UTF-8. A malformed byte draws one replacement character and the rest of
+the string survives — a bad byte in a data file costs a visible box, not the
+label.
+
+## What it costs
+
+Glyphs are rasterised the first time they are drawn and kept in a texture atlas
+afterwards, so the cost is bounded by the **characters** a game uses, not by the
+strings it draws. A score that changes every frame is free after the first ten
+digits; a whole Latin character set fits on one 512×512 page, so a line of text
+is one draw call.
+
+A font that is only measured and never drawn allocates no video memory at all.
+
+Nothing needs freeing — a font's atlas is released when the font is collected,
+in either order relative to its app. `Font.debug_live_pages` reports how many
+atlas pages exist and is there for tests, not for gameplay.
+
+## What is not here
+
+Markup (`<b>`, colour tags), bold and italic variants, multi-line layout, word
+wrapping, text input, and right-to-left or complex shaping. A string is one line
+of left-to-right glyphs.

data/docs/api/toolbox.md

@@ -0,0 +1,240 @@
+# Utilities
+
+Engine classes a **game author reaches for directly** that don't belong to the scene
+graph, components, signals, or systems chapters — pooling, localization, audio facts,
+flat grids, the camera, collision boxes. All are pure Ruby (none `require "gosu"`), so
+they stay headless-testable.
+
+For the low-level classes that sit *behind* components and are rarely constructed by
+hand (collision maths, the spatial index, animation playback), see
+[Internal building blocks](internals.md).
+
+## `Matrix` — a flat fixed-size grid
+
+`RGame::Engine::Matrix` is a fixed-size grid addressed as `[x, y]` but backed by a
+**single flat (row-major) array**, not an array-of-arrays. One contiguous
+allocation is cheaper than nested arrays, and it is the shape a C-level buffer
+takes — which is not hypothetical: its 3-D sibling made exactly that move.
+
+```ruby
+grid = RGame::Engine::Matrix.new(width, height, initial: 0)
+grid[col, row] = gid
+grid[col, row]                      # row-major: index = y * width + x
+```
+
+It does no bounds checking on the hot path (callers stay in range).
+
+For three dimensions, reach for [`RGame::Util::Tensor`](values.md#rgameutiltensor) — the C
+one. `TileMap` stacks its tile layers in a single
+`Tensor(width, height, layer_count)`, and that is the worked example of the rule
+that the engine layer may hold `RGame::Util` values: a grid is a value, so the
+layer above owns one outright rather than being handed it.
+
+## `CachedLabel` — a display string rebuilt only on change
+
+`RGame::Engine::CachedLabel` (`rgame/engine/cached_label`) holds a label string and rebuilds it only when its
+source value changes, so a per-frame draw shows the cached copy without interpolating (and
+allocating) a `String` every frame. Construct it — and its format block — outside the per-frame
+path (e.g. in `on_add`), then read it by value in `on_draw`:
+
+```ruby
+@score_label = RGame::Engine::CachedLabel.new { |score| "Score: #{score}" }  # built once
+
+def on_draw(renderer)
+  renderer.text(@score_label[@score], 12, 10)   # cached; rebuilds only when @score changes
+end
+```
+
+`@score_label[value]` returns the same `String` object while `value` is unchanged. This is the
+sanctioned home for build-on-change interpolation, so the per-frame allocation cops
+(`rubocop/cop/game/`) exempt it. For a value that changes *every* frame (an FPS or allocation counter) a cached string can't
+help — draw the digits individually from cached glyph strings instead, as `RGame::Engine::DebugOverlay` does.
+
+## `Pool` — reuse, don't allocate
+
+`RGame::Engine::Pool` (`rgame/engine/pool`) recycles many short-lived, homogeneous objects —
+bullets, particles, transient enemies — so steady-state spawning allocates nothing.
+Acquired objects come from a free list, falling back to a factory block only when the
+list is empty.
+
+```ruby
+pool = RGame::Engine::Pool.new { Bullet.new }   # factory builds a blank object
+b = pool.acquire                         # recycled, or freshly built once
+b.reset(x, y, angle)                     # caller re-initialises after acquire
+pool.each { |bullet| bullet.update(dt) }
+pool.reclaim_if(&:dead?)                 # sweep dead → free list, once per frame
+```
+
+The factory builds a *blank* object; the caller re-initialises it after `acquire`
+(typically via a `reset` from an [`RGame::Engine::Resettable`](#resettable--mutable-only-where-a-pool-needs-it)
+value object). `reclaim_if` is the deferred-removal seam: it sweeps the active list
+once, moving every object the block marks dead onto the free list. Call it *after*
+iterating with `each` — never mutate the active list mid-iteration. `active`, `size`,
+and `each` expose the live set for update/draw traversal.
+
+## `Path` — a walkable polyline
+
+`RGame::Engine::Path` (`rgame/engine/path`) is an ordered polyline of waypoints an entity walks along —
+the "road" of a tower-defense level. Pure data: it holds the waypoints and the precomputed
+per-segment lengths, so a follower walking it at runtime allocates nothing. Waypoints are
+stored flat (`x0, y0, x1, y1, …`) in one contiguous array and read back through scalar
+accessors, so neither construction nor traversal leaks a pair-object per waypoint.
+
+```ruby
+path = RGame::Engine::Path.new([[0, 0], [100, 0], [100, 100]]) # ≥ 2 waypoints, in walk order
+path.count             # number of waypoints
+path.x_at(i)           # scalar coords of waypoint i (no allocation)
+path.y_at(i)
+path.segment_length(i) # length of the segment from waypoint i to i+1
+path.length            # total length
+path.distance_to(x, y) # shortest distance from a point to the polyline
+```
+
+A follower ([`Components::PathFollow`](components.md#pathfollow)) reads segments by index
+and interpolates itself; Path never returns a coordinate pair. `distance_to` answers "how
+far is this point from the road" (allocation-free scalar maths) — e.g. to mask the
+tower-placement cells that sit on or hug the road.
+
+## `Timer` — paced periodic events
+
+`RGame::Engine::Timer` (`rgame/engine/timer`) is 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 is deliberate: the same primitive serves both "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.
+
+```ruby
+@spawn_timer = RGame::Engine::Timer.new(0.8)   # built once, off the hot path
+
+def on_update(dt)
+  @spawn_timer.update(dt)
+  return unless @spawn_timer.ready?      # a whole interval has accumulated
+
+  @spawn_timer.consume                   # deduct it; the remainder carries forward
+  spawn_enemy
+end
+```
+
+`consume` carries the overshoot forward (rather than zeroing), so a long-running cadence
+doesn't drift; `reset` drops accumulated time after retuning `interval`. When a step might
+span several intervals, loop: `while timer.ready? do …; timer.consume end`.
+
+For a node that should tick automatically, reach for
+[`Components::Timer`](components.md#timer) instead — it owns one of these, rides the node's
+update tick (so nothing can forget to drive it), and emits `on_timeout` rather than making
+you poll `ready?`/`consume`.
+
+## `Camera` — follow a point, clamp to the world
+
+`RGame::Engine::Camera` (`rgame/engine/camera`) is the pure follow-and-clamp maths for a scrolling
+view: `center_on(world_x, world_y)` parks its top-left so the point is centred, but
+clamped so it never shows past the map edges (near a corner the target drifts off-centre
+instead). A scene constructs one, sizes it with the viewport and the world, and centres
+it on the player each frame.
+
+```ruby
+camera = RGame::Engine::Camera.new(
+  viewport_width: 640, viewport_height: 480,
+  world_width: map.pixel_width, world_height: map.pixel_height
+)
+camera.center_on(player_x, player_y) # camera.x / camera.y now hold the clamped offset
+```
+
+It only computes the offset; applying it is a *view transform* —
+[`CameraView`](scene_graph.md#view-transforms-and-the-camera) wraps the world subtree in
+`renderer.translated(-camera.x, -camera.y)`, and a [`TileWorld`](components.md#tileworld)
+draws the map at the same offset. See `examples/15_tiled_world`.
+
+## `CollisionBox` — an actor's feet box
+
+`RGame::Engine::CollisionBox` (`rgame/engine/collision_box`) is a character's collision rectangle,
+expressed as an offset + size **relative to the sprite's top-left origin** — decoupled
+from the sprite size, so a 32×32 sprite can carry a small box at its feet. A
+[`CharacterBody`](components.md#characterbody) holds one and the collision code resolves
+*it* (not the sprite) against the tiles.
+
+```ruby
+box = RGame::Engine::CollisionBox.bottom_anchored(
+  sprite_width: 32, sprite_height: 32, width: 16, height: 16
+) # centred horizontally, anchored to the sprite's feet
+box.aabb(x, y) # => [x + offset_x, y + offset_y, width, height]
+```
+
+`bottom_anchored` is the common case (feet box); the raw constructor takes explicit
+`offset_x:`/`offset_y:`/`width:`/`height:` for anything else.
+
+## `RGame::Engine::I18n` — localization
+
+`RGame::Engine::I18n` (`engine/i18n`) is minimal localization: per-locale translation tables
+(loaded from YAML or an inline Hash), `t(key)` lookup with `%{var}` interpolation and a
+fallback locale, and pluralization. It is a **global module** (like the signal
+dispatcher), so `t` is reachable anywhere without wiring. YAML is its only dependency.
+
+```ruby
+RGame::Engine::I18n.load_file(:en, "locales/en.yml")
+RGame::Engine::I18n.load(:de, menu: { title: "Hauptmenü" })   # nested Hashes allowed
+RGame::Engine::I18n.default = :en        # fallback when the current locale lacks a key
+RGame::Engine::I18n.locale = :de
+
+RGame::Engine::I18n.t("menu.title")               # dotted key, resolved in :de then :en
+RGame::Engine::I18n.t(:greeting, name: "Ada")     # => "Hello, Ada" from %{name}
+RGame::Engine::I18n.t(:apples, count: 3)          # pluralized: { one:, other:, zero? }
+```
+
+Keys are symbolized on load, so YAML's string keys and inline symbol keys look the same
+to `t`. `t` resolves a dotted key in the current locale, then the fallback, then returns
+the key itself as a last resort. Pass `count:` to pluralize — the key's value is then a
+`{ one:, other:, optionally zero: }` table, and `count` is also exposed to interpolation
+as `%{count}` (English/German use the one/other rule).
+
+The **`generation` counter** is the headless-friendly change seam: it ticks whenever the
+locale changes, so cached UI text can re-resolve only when `generation` moves rather than
+re-running `t` every frame — keeping with the engine's no-per-frame-allocation rule.
+
+## `AudioBus` — decoupled audio facts
+
+`RGame::Engine::AudioBus` (`rgame/engine/audio_bus`) is a global, always-present audio bus: gameplay
+emits audio *facts* (`play this sound`, `play this music`) here, decoupled from playback,
+and an `AudioDirector` subscribes and turns them into actual
+sound. A module rather than an instance so any node can reach it without wiring.
+
+```ruby
+RGame::Engine::AudioBus.play_sound(:boom)
+RGame::Engine::AudioBus.play_music(:theme)
+RGame::Engine::AudioBus.stop_music
+```
+
+The emit shims (`play_sound`, `play_music`, `stop_music`) are the gameplay-facing API;
+underneath each is an [`RGame::Engine::Signal`](signals.md) (`on_play_sound`, `on_play_music`,
+`on_stop_music`) that is the actual subscription seam the director listens on. Because
+the engine only emits facts and never names an audio device, the bus stays in the engine
+layer and playback stays in `RGame::Core`.
+
+## `Resettable` — mutable only where a pool needs it
+
+`RGame::Engine::Resettable` (`rgame/engine/resettable`) builds value-object classes for pooling. Like
+`Data.define`, instances expose read-only accessors and carry their fields as a unit —
+but where a `Data` value is fully immutable (every change is a fresh allocation), these
+add exactly one mutation: `reset`, which overwrites all fields at once and returns self.
+
+```ruby
+Point = RGame::Engine::Resettable.define(:x, :y)
+p = Point.new(3, 4)
+p.x            # => 3 (read-only; no x= setter)
+p.reset(5, 6)  # overwrite in place, allocation-free → self
+
+Vel = RGame::Engine::Resettable.define(:dx, :dy, keyword_init: true)
+Vel.new(dx: 1, dy: 0).reset(dx: 2, dy: 0)
+```
+
+That single in-place `reset` is the only mutability a [`Pool`](#pool--reuse-dont-allocate)
+needs: acquire a recycled instance and `reset` it, without exposing the per-field setters
+a `Struct` would. Methods are generated fixed-arity with direct ivar assignment (as
+Struct/Data do), so `reset` is allocation-free and recycling stays zero-allocation in
+steady state — including the `keyword_init: true` form, which generates named parameters
+(`reset(x:, y:)`) rather than a `**kwargs` splat (the one form that would build a Hash per
+call). Reach for this over a mutable `Struct` whenever a value object is pool-recycled; see
+the Style notes in `CLAUDE.md`.

data/docs/api/values.md

@@ -0,0 +1,101 @@
+# Value types
+
+Everything in `RGame::Util` is a *value*: cheap, comparable, owning no window,
+GPU handle or file. That is what makes them safe for game logic to hold as
+attributes — they load with `require 'rgame'` and pull in no graphics libraries
+at all.
+
+```ruby
+require 'rgame'
+```
+
+## `RGame::Util::Color`
+
+An RGBA colour. Instances are **frozen** and compare **by value**, so one can be
+shared freely and used as a Hash key.
+
+```ruby
+Color = RGame::Util::Color
+
+Color.new(255, 128, 0)          # r, g, b — alpha defaults to 255
+Color.new(255, 128, 0, 200)     # explicit alpha
+Color.rgba(255, 128, 0, 200)    # the same thing, named
+Color.from_packed(0xFF8000C8)   # 0xRRGGBBAA
+```
+
+| | |
+|---|---|
+| `r` `g` `b` `a` | Components, `0..255`. |
+| `packed` | The `0xRRGGBBAA` form as an Integer. |
+| `==`, `eql?`, `hash` | Value semantics. |
+| `inspect` | `#<RGame::Util::Color r=1 g=2 b=3 a=4>` |
+
+Named colours: `Color::WHITE`, `Color::BLACK`, `Color::TRANSPARENT`.
+
+### Out-of-range components raise
+
+```ruby
+Color.new(300, 0, 0)   # ArgumentError: red must be in 0..255, got 300
+```
+
+Silently clamping would hide the bug that produced the 300.
+
+### `Color.coerce`
+
+Drawing calls accept a colour in several forms, and `coerce` is the single
+place that conversion happens:
+
+```ruby
+Color.coerce(nil)               # => Color::WHITE — an untinted draw
+Color.coerce([255, 128, 0])     # => opaque
+Color.coerce([255, 128, 0, 64]) # => with alpha
+Color.coerce(Color::WHITE)      # => returned unchanged, not copied
+```
+
+Anything else raises `TypeError`; a wrongly-sized array raises `ArgumentError`.
+
+### Value semantics in practice
+
+```ruby
+a = Color.new(1, 2, 3)
+b = Color.new(1, 2, 3)
+
+a == b            # => true — two objects, one value
+{ a => :hit }[b]  # => :hit
+a.frozen?         # => true
+```
+
+Because a colour is frozen, handing the same one to two sprites is safe: nobody
+can tint it out from under the other.
+
+## `RGame::Util::Tensor`
+
+A fixed-size three-dimensional grid, addressed as `[x, y, z]`. Backed by a
+single flat array in C, so it stays compact for the sizes a tile map or a
+lighting volume needs.
+
+```ruby
+grid = RGame::Util::Tensor.new(width, height, depth)
+grid = RGame::Util::Tensor.new(16, 16, 4, initial: 0)   # fill value
+
+grid[3, 4, 1] = :wall
+grid[3, 4, 1]          # => :wall
+
+grid.width             # also #height and #depth
+```
+
+Cells hold any Ruby object. `initial:` is optional and defaults to `nil`.
+
+The layout is x-fastest, then y, then z, so one z-slice is a contiguous run —
+worth knowing if you iterate a layer at a time and care about locality.
+
+```ruby
+grid.depth.times do |z|
+  grid.height.times do |y|
+    grid.width.times do |x|
+      cell = grid[x, y, z]
+      # ...
+    end
+  end
+end
+```