rgame 0.4.0-x86_64-linux-gnu

data/docs/api/README.md

@@ -0,0 +1,224 @@
+# rgame API guide
+
+These pages document how to use rgame from Ruby. The engine is written in C and
+ships as two Ruby extensions. The scene graph sits on top of them in pure Ruby,
+and a game is written against that scene graph. Nothing here asks you to read
+or write C.
+
+| Page | Covers |
+|---|---|
+| This page | Loading the library, the three namespaces, a working program, testing |
+| [The `rgame` command](cli.md) | `rgame new NAME` — starting a project, and the layout it gives you |
+| [App](app.md) | `RGame::Core::App` — the window and the frame loop |
+| [Game](game.md) | `RGame::Game` — the entry point that wires both halves together |
+| [Input](input.md) | `RGame::Core::Input`, `RGame::Util::Controls`, `RGame::Core::Gamepad`, `RGame::Core::VirtualGamepad` |
+| [Drawing](drawing.md) | `RGame::Core::Renderer` — shapes, images, transforms, clipping, recordings |
+| [Images](images.md) | `RGame::Core::Image` — loading PNGs, subimages, tiles |
+| [Text](text.md) | `RGame::Core::Font` and `Renderer#text` |
+| [Audio](audio.md) | `RGame::Core::Audio`, `Sample`, `Song` — samples and streamed music |
+| [Assets](assets.md) | `RGame::Core::AssetManager`, `SpriteSheet`, `NineSlice`, `UiAtlas`, `TileMapRenderer` |
+| [Values](values.md) | `RGame::Util::Color`, `Tensor`, `SolidGrid`, `RouteSearch`, `TileSweep`, `Z`, `SaveFile` |
+| [Examples](examples.md) | What each program under `examples/` demonstrates |
+
+The scene graph is `RGame::Engine`, the layer a game is written in:
+
+| Page | Covers |
+|---|---|
+| [Scene graph](scene_graph.md) | `Node2D`, the tree, the lifecycle, transforms and the camera |
+| [Components](components.md) | Reusable behaviour attached to a node |
+| [Systems](systems.md) | Services a subtree shares — collision worlds, tile worlds |
+| [Tile maps](tile_maps.md) | `TileMap` and `Tileset` — a Tiled map as data: loading, cells, solidity, animated tiles |
+| [UI](ui.md) | `PlayerLayer` and `UI::Menu` — a player's own screen, and a list or wheel navigated by focus |
+| [Signals](signals.md) | The typed observer pattern nodes talk through |
+| [Toolbox](toolbox.md) | What a game author reaches for directly: the text a node draws, pooling, paths and routes, timers, the camera, collision boxes, the audio bus |
+| [Localization](localization.md) | `I18n` and translation tables — where they go, plurals, the fallback chain, the player's language, missing keys in specs |
+| [Internal building blocks](internals.md) | What components are built from: collision maths, the spatial index, animation playback |
+
+**The engine is a work in progress.** It opens a window, runs the loop, reads
+input, draws shapes, images and text, and plays sound. A scene graph with
+split-screen players runs on top. The games under `test_projects/` use exactly
+what these pages document. The missing piece is a UI *toolkit*. [UI](ui.md)
+gives each player a region of the screen, menus with focus and activation, and a
+column, row or ring of equal-sized buttons. It has no general layout, no scrolling
+lists and no text entry. These pages describe
+what exists and grow with the engine.
+
+## Loading it
+
+rgame has three entry points. Each one loads everything the one before it does:
+
+```ruby
+require 'rgame'       # RGame::Util + RGame::Engine — no graphics libraries at all
+require 'rgame/core'  # adds the window, the GPU and the sound device (SDL2 + OpenGL)
+require 'rgame/game'  # all of it, wired together — what a game writes
+```
+
+A game requires the last one. Its entry point is `RGame::Game`; see
+[Game](game.md).
+
+`require 'rgame'` loads **everything that runs without a window**: the value
+types and the whole scene graph. The process loads no SDL and no OpenGL, so game
+logic and its specs run with no display. `spec/rgame/no_graphics_spec.rb` checks
+this by reading the process's own memory map.
+
+You can also require `rgame/util`, `rgame/engine` and `rgame/core` on their own.
+The Core spec suite does this to load exactly one layer.
+
+`rgame/core` also loads `RGame::Util::Controls`, the input id vocabulary,
+because the input classes need it.
+
+**Your install either compiled both extensions or arrived with them built.** On
+Apple Silicon macOS, x86-64 Linux and 64-bit Windows, `gem install rgame` fetches
+a gem that already holds `core_ext` and `util_ext`, with SDL2 inside `core_ext`,
+and compiles nothing. Every other machine gets the gem that ships the C and
+builds both on install, against a system SDL2. Either way the two land in the
+same place and the three requires above behave the same.
+
+In a checkout of the repository, compile them before you require anything:
+
+```
+make ext        # builds both, copies them into lib/rgame/
+```
+
+## The three namespaces
+
+Everything lives under `RGame`. What a class depends on decides between `Util`
+and `Core`. `Engine` holds what a game is written in.
+
+| | `RGame::Util` | `RGame::Core` | `RGame::Engine` |
+|---|---|---|---|
+| Contains | shareable *values* — no window, no GPU, nothing to release | things owning a window, GPU or OS handle | game concepts: the scene graph a game is written in |
+| Classes | `Color`, `Tensor`, `Controls`, `Z`, `SolidGrid`, `RouteSearch`, `TileSweep`, `SaveFile` | `App`, `Input`, `Gamepad`, `VirtualGamepad`, `Image`, `Renderer`, `Recording`, `Font`, `Audio`, `SpriteSheet`, `NineSlice`, `UiAtlas`, `TileMapRenderer`, `AssetManager` | `Node2D`, components, systems, signals, `TileMap`, `Player`, `InputMap`, `UI::Menu` |
+| Loading it costs | nothing | SDL2 + OpenGL in your process | nothing |
+
+**A value goes in `Util`; only a handle-owner goes in `Core`.** A colour is a
+value. A window is not.
+
+`RGame::Engine` sits above both and follows three rules:
+
+- It may hold `Util` values as attributes, such as a `Color` or a `Tensor`.
+- It may **not name `Core` at all**: no require, no constant, no attribute.
+- It reaches `Core` only through objects it receives. A node's `on_draw`
+  receives a renderer and calls its methods by name. The node never stores the
+  renderer and never checks its class.
+
+These rules keep a whole game runnable and testable with no window: its rules,
+its scenes, its collisions. The testing section below relies on that. RuboCop
+cops enforce the rules in both directions inside rgame's own repository, and a
+project from `rgame new` runs the first of them over its `nodes/` and `spec/`.
+See [the generated RuboCop configuration](cli.md#the-generated-rubocop-configuration).
+
+`RGame::Game` is the one exception: the only class that names both `Engine` and
+`Core`. It exists to connect the two halves. Keeping that in one file lets the
+rule hold everywhere else.
+
+## A complete program
+
+A game is a tree of nodes, run by `RGame::Game`.
+
+```ruby
+require 'rgame/game'
+
+# One game object: a square the player walks around. Pure Engine — it names no
+# graphics class, so it runs unchanged in a spec with no window.
+class Hero < RGame::Engine::Node2D
+  SPEED = 200.0
+
+  def initialize
+    super(x: 400, y: 300, width: 16, height: 16)
+    @vx = 0.0
+    @vy = 0.0
+  end
+
+  # Intent, read once per simulation tick. Never a key: `move_x` is whatever
+  # this player's input map binds it to — arrows, WASD or a stick.
+  def on_control(actions)
+    @vx = actions.axis(:move_x) * SPEED
+    @vy = actions.axis(:move_y) * SPEED
+  end
+
+  # `dt` is always the same fixed step, never wall-clock frame time, so
+  # movement is deterministic. `x`/`y` are relative to the parent.
+  def on_update(dt)
+    self.x += @vx * dt
+    self.y += @vy * dt
+  end
+
+  # The renderer is handed in and never stored; `view` is the viewport being
+  # drawn into, which most nodes ignore. Draw in the node's own space: the
+  # traversal has already put the renderer on this node, so (0, 0) is here.
+  # See docs/api/scene_graph.md, "Drawing happens in local space".
+  def on_draw(renderer, _view)
+    renderer.rect(0, 0, width, height)
+  end
+end
+
+# The root of the tree. Children are added in `on_add`, once the node is in a
+# tree and can reach the game around it.
+class Scene < RGame::Engine::Node2D
+  def on_add
+    add_node(Hero.new)
+  end
+end
+
+RGame::Game.new(root: Scene.new, width: 800, height: 600, caption: 'My Game').start
+```
+
+Subclass `Node2D` and override the hooks you need: `on_control`, `on_update`,
+`on_draw`, and the lifecycle hooks around them. A hook you do not override does
+nothing. Separate phase methods do the bookkeeping: they push the node's
+transform, drive components and descend into children. You never override
+those, so there is no `super` to forget. [Scene graph](scene_graph.md) lists
+every hook. [Game](game.md) describes what `Game` builds around the tree: the
+window, the renderer, the asset manager, the sound device, the input mapper and
+the players.
+
+Without an `input_map:`, `Game` uses the default map shown above. It binds
+eight-way `move_x` / `move_y` to the arrows, WASD, the d-pad and the left stick,
+and adds `fire`. See [Input](input.md).
+
+## Testing a game built on this
+
+`require 'rgame'` loads `Util` and the whole scene graph with no SDL and no
+OpenGL. The nodes from the program above run there unchanged. A spec drives
+their phases directly, so a simulated hour takes milliseconds:
+
+<!-- doc-example: skip — an RSpec file for the Hero above, run by rspec -->
+```ruby
+require 'rgame'
+
+RSpec.describe Hero do
+  it 'walks right at 200 units a second' do
+    hero = Hero.new
+    # The same snapshot object the input mapper hands a node at runtime, built
+    # by hand with the stick pushed fully right.
+    actions = RGame::Engine::Actions.new(axes: { move_x: 1.0, move_y: 0.0 })
+
+    # One simulated second, sixty ticks, no window and no clock.
+    60.times do
+      hero.control(actions)
+      hero.update(1.0 / 60.0)
+    end
+
+    expect(hero.x).to be_within(0.01).of(600.0)
+  end
+end
+```
+
+Two properties make this work:
+
+- **`update` takes `dt` as an argument and reads no clock.** A test passes any
+  timestep it likes, so it can simulate minutes of play in milliseconds.
+- **A node never holds a renderer.** `on_draw` receives one. A spec passes a
+  recording double and asserts on what the node asked it to draw. rgame's own
+  suite checks its fake renderer against the real one with a shared contract in
+  `spec/support/shared_examples/`. The whole suite runs headless.
+
+The spec asserts `hero.x`, not `world_x`, because this hero has no parent. The
+world transform accumulates from the parent, and a node without one resolves to
+the origin. Under a root, game logic reads `world_x`. Drawing reads neither; see
+[Scene graph](scene_graph.md#drawing-happens-in-local-space).
+
+Keep the code that decides *what happens* in `RGame::Engine`. That layer cannot
+name `RGame::Core`, so it cannot come to depend on a window. Only the thin layer
+that puts pixels on screen then needs one.

data/docs/api/app.md

@@ -0,0 +1,249 @@
+# `RGame::Core::App`
+
+`App` owns the window and runs the frame loop. Subclass it, override the hooks
+you need, and call `run`.
+
+```ruby
+require 'rgame/core'
+
+class MyGame < RGame::Core::App
+  def initialize = super(width: 800, height: 600, caption: 'My Game')
+end
+
+MyGame.new.run   # returns when the loop stops
+```
+
+`App.new` takes keyword arguments only. It requires `width:`, `height:` and
+`caption:`. `media_root:` is optional and defaults to `'media'`. The constructor
+opens a real window at once.
+
+## What the app owns
+
+The app builds two objects on first use. A game needs exactly one of each:
+
+```ruby
+require 'rgame/core'
+
+class MyGame < RGame::Core::App
+  def initialize = super(width: 640, height: 480, caption: 'demo', media_root: 'assets')
+end
+
+app = MyGame.new
+app.assets   # => RGame::Core::AssetManager — rooted at media_root
+app.audio    # => RGame::Core::Audio — the sound device
+```
+
+**A game never constructs either of them.** An image belongs to one OpenGL
+context, so whatever loads it must know the app. The app builds its asset manager
+once, and scenes load through it by path. No class has to pass the app along to
+reach an image.
+
+Both objects are built on first use. `RGame::Core::Renderer.new(app)` asks for the
+asset manager, so any app that draws has one. An app that never plays a sound
+never opens a sound device; the first sound request opens it.
+
+`media_root` is read-only and fixed at construction. It has no writer: changing
+the root after a load would leave one cache keyed against two roots.
+
+[Assets](assets.md) describes the asset manager.
+
+## The frame loop
+
+`run` drives the loop until something stops it, and calls back into your object.
+One rendered frame runs these steps:
+
+```
+  poll input and window events   →  button_down / button_up / resize
+                                    gamepad_connected / gamepad_disconnected
+  frame_begin                    →  once, before any ticks
+  update(dt)                     →  zero or more times (see below)
+  needs_redraw?                  →  once; false skips the draw
+  draw                           →  once, unless skipped
+  frame_end                      →  once, after draw, unless skipped
+```
+
+### `update(dt)` runs a *fixed* number of times, not once per frame
+
+**The simulation advances in fixed steps.** Each frame adds the real elapsed
+time to an accumulator. The frame then runs every whole step that has come due.
+That can be **zero** steps, when the machine renders faster than the simulation
+needs. It can be **several**, when a slow frame forces the simulation to catch
+up. The loop caps catch-up, so a slow frame slows time down instead of spiralling.
+
+`dt` is always the same fixed step: **1/60 second**. It is never wall-clock
+frame time. A fixed step makes movement reproducible. It also lets a test call
+`update` directly and simulate any amount of time.
+
+**Do not sample input inside `update`.** A frame may run one tick or five, so a
+key held for one frame would be read a varying number of times. Sample input in
+`frame_begin`, or use `Input`. `Input` reads a snapshot taken once per frame, so
+it answers the same for every tick of that frame.
+
+### `needs_redraw?`
+
+Return `false` to skip the draw for that frame. The simulation still advances.
+Use it when nothing changed and drawing costs a lot. The default is `true`.
+
+```ruby
+def update(_dt)
+  @dirty = true if something_moved
+end
+
+def needs_redraw? = @dirty
+
+def draw
+  # ...
+  @dirty = false
+end
+```
+
+`update` runs only when a step happened. Setting `@dirty = true` there is usually
+the whole rule.
+
+## Hooks you can override
+
+Every hook inherits a default that does nothing. Override only what you use.
+
+| Hook | When |
+|---|---|
+| `frame_begin` | Once per frame, before that frame's ticks. Sample input here. |
+| `update(dt)` | One fixed simulation tick. |
+| `needs_redraw?` | Before drawing; `false` skips `draw`. Default `true`. |
+| `draw` | Render one frame. |
+| `frame_end` | After `draw` reaches the GPU, before the buffer swap. Not called when the draw was skipped. |
+| `button_down(id)` | A key was pressed. The loop filters auto-repeats, so a held key fires once. |
+| `button_up(id)` | A key was released. |
+| `resize(width, height)` | The window changed size. |
+| `gamepad_connected(slot)` | A controller arrived in a player slot. |
+| `gamepad_disconnected(slot)` | A controller left a slot. |
+
+`id` is a value from [`RGame::Util::Controls`](input.md), such as
+`Controls::KEY_ESCAPE`.
+
+`frame_end` is the one point where a test can read back the frame it drew.
+Game code rarely needs it.
+
+### There is no built-in quit key
+
+Closing the window stops the loop, because the platform decides that. Quitting
+on Escape is *your* decision, so the engine leaves it to you:
+
+```ruby
+def button_down(id)
+  close if id == RGame::Util::Controls::KEY_ESCAPE
+end
+```
+
+## Window methods
+
+| Method | |
+|---|---|
+| `run` | Runs the loop until it stops. Returns `self`. |
+| `close` | Asks the loop to stop. Safe to call from inside any hook. |
+| `width`, `height` | Current window size. |
+| `caption`, `caption=` | The window title. |
+| `fullscreen?`, `fullscreen=` | Whether the window covers the screen. |
+| `ticks_ms` | Monotonic milliseconds since startup. For measuring frames, not for drawing. |
+| `fps` | Most recent frames-per-second reading, updated about once a second. |
+
+`close` takes effect promptly. The loop checks between steps and starts no more
+work in the current frame.
+
+`ticks_ms` is the raw clock. A draw never reads it: animation accumulates its own
+time in `update`.
+
+### Fullscreen
+
+```ruby
+require 'rgame/core'
+
+app = RGame::Core::App.new(width: 640, height: 480, caption: 'demo', fullscreen: true)  # opens fullscreen
+app.fullscreen = !app.fullscreen?                                                      # switches either way
+```
+
+**To open fullscreen, pass `fullscreen: true` to the constructor.** Setting it
+after the window is up also works, but shows one windowed frame first. Players
+read that flash as a broken startup. A game whose settings say fullscreen passes
+the setting to `new`.
+
+`width` and `height` still matter when the window opens fullscreen. The window
+takes that size when it leaves fullscreen.
+
+rgame uses **desktop** fullscreen: the window covers the screen at the screen's
+own resolution. The display never changes mode. The switch is instant, needs no
+mode list, and leaves other windows alone. The game gets a bigger view, not a
+different one.
+
+**Switching resizes the window**, so the loop calls
+[`resize`](#hooks-you-can-override) with the new size. A user dragging a window
+edge triggers the same call. Everything that lays out against the window learns
+of the change through that one path. So a scene reads the `view` it is drawn
+with, not the width it passed to `new`.
+
+A layout written against fixed numbers will not follow a bigger view.
+[`scale_mode:`](game.md#scale_mode--what-width-and-height-mean) on `RGame::Game`
+offers the alternative: keep a logical size and scale it onto the window.
+
+`examples/fullscreen` shows both ways to open, the switch, and every scale mode.
+
+## Raw input queries
+
+`App` exposes the input snapshot directly. Code written against Core alone
+usually calls [`RGame::Core::Input`](input.md) instead, whose `down?` and `axis`
+default the device to the keyboard. A game on `RGame::Game` reads actions and
+never calls either. These queries are the primitives underneath:
+
+| Method | |
+|---|---|
+| `input_down?(device, button_id)` | Is that button held on that device? |
+| `input_axis(device, axis_id)` | Analog axis value; sticks −1.0…1.0, triggers 0.0…1.0. |
+| `gamepad_present?(slot)` | Is a controller plugged into that player slot? |
+| `gamepad_name(slot)` | Its human-readable name, or `nil`. |
+| `gamepad_count` | How many controllers are connected. |
+
+The query is named `gamepad_present?`, not `gamepad_connected?`. The hot-plug
+*hook* above owns that name, and two methods that differ only by a `?` invite
+mistakes.
+
+## The player's languages
+
+```ruby
+require 'rgame/core'
+
+RGame::Core.preferred_locales   # => ["de-AT", "en"] — most preferred first
+```
+
+`RGame::Core.preferred_locales` returns the locales the operating system says the
+user prefers, most preferred first. It is a module function: it needs no app and
+no window. Each entry is a language, followed by a hyphen and a country when the
+OS names one. The list is `[]` when the OS names none, as on Linux under
+`LANG=C`. It never holds `nil` or an empty String.
+
+It returns what SDL reports, unfiltered. On Linux SDL reads `LANG`, then
+`LANGUAGE`, and ignores `LC_ALL`, so a locale can appear twice. macOS and Windows
+ask the OS. Picking the language a game shows is
+[`I18n.choose`](localization.md#locales-and-the-fallback-chain), and `RGame::Game`
+makes that choice at startup.
+
+## When a hook raises
+
+`run` re-raises any exception from a hook, with its class, message and backtrace
+intact. The loop shuts down cleanly first and closes the window:
+
+```ruby
+begin
+  MyGame.new.run
+rescue MyGameError => e
+  # the loop has already stopped by the time this runs
+end
+```
+
+A **non-local exit** cannot cross the loop that way. That covers `throw`,
+`break` or `return` leaving a hook. `run` reports it as a `RuntimeError` that
+tells you to use `close`. Only `close` and closing the window stop the loop.
+
+## Several windows in one process
+
+A process can create more than one `App`, and their lifetimes may overlap. The
+engine keeps SDL alive until the last one is gone. Test suites rely on this: they
+create and discard a window per example.