rgame 0.4.0-x86_64-linux-gnu

data/docs/api/systems.md

@@ -0,0 +1,231 @@
+# Systems & shared resources
+
+Some things a node needs do not live on the node: a tile map, the world bounds, a
+shared collision world. **Shared resources are systems. A system lives on an
+anchor node, and other nodes reach it by walking the tree**, not through
+constructor arguments. A system is an ordinary `RGame::Engine::Component` on a
+boundary node, found with the same `get_component` every node has.
+
+## Two scopes, two anchor nodes
+
+**Scope belongs to the node you attach a system to**, not to the system.
+
+- **Global scope → the root node.** Every node can reach the root, and it never
+  changes. Systems that live as long as the program are components on the root,
+  such as `Players` and `Viewports`: `node.root.get_component(RGame::Engine::Players)`.
+- **Scene scope → the scene node**, the node `SceneStack` pushes. Systems that
+  live as long as a scene are components on *that* node, such as the collision
+  world or the tile world. They appear when the scene is pushed and go when it is
+  popped: `node.scene.get_component(CollisionWorld)`.
+
+## The anchors
+
+**Both anchors are methods that walk the parent chain**, not cached fields. A
+back-link cached at add time would go stale for a node built before it is
+mounted: its children would cache the wrong root. Resolving on every access
+cannot go stale.
+
+- `root` is `@parent ? @parent.root : self`. The top-most node is its own root.
+- `scene` is the nearest ancestor marked as a scene boundary. `SceneStack#push`
+  marks the pushed scene with `scene.scene = scene`, and 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 first, then the root.** A scene can
+therefore override a global default, and nodes outside any scene still find
+globals. To mean one scope specifically, use its anchor:
+`node.root.get_component` or `node.scene.get_component`.
+
+### Ask for a contract, not a class
+
+**The lookup matches by ancestry**, so `klass` can be a module the system
+includes instead of its own class. One question can then have several answers.
+
+"How big is the world" shows this. A flat game mounts
+[`Components::World`](components.md#world). A tile game mounts
+[`Components::TileWorld`](components.md#tileworld), which derives the same two
+numbers from its map. Both include `Components::WorldBounds`, so a component
+that needs bounds asks for the *contract*:
+
+```ruby
+def on_attach
+  world = node.system(RGame::Engine::Components::WorldBounds)
+  @width = world.world_width
+  @height = world.world_height
+end
+```
+
+`ScreenWrap` and `DespawnOffscreen` work this way. They run unchanged in either
+kind of scene and never learn which one they are in. Naming the contract keeps
+the two implementations from drifting apart.
+
+## Registering with a system: use the lifecycle, not `initialize`
+
+**A system and its clients connect in the tree-lifecycle hooks**, never in
+`initialize`. They can only connect once everything is in the live tree, and a
+node under construction has no anchors. See
+[Lifecycle](scene_graph.md#lifecycle-constructing-vs-entering-the-tree).
+
+The entered-tree cascade fixes an order that makes this safe. The scene's own
+components run `on_attach` first, so a `CollisionWorld` on the scene node exists.
+Then the scene's `on_add` runs, then its children enter. 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
+```
+
+**A collider tolerates a missing world; most clients should not.** Both hooks
+above use `&.`. A collider in a scene without a `CollisionWorld` is a shape that
+reports nothing. A tile-only game wants exactly that: its character carries a
+feet box to be *stopped* by (see [`Mover`](components.md#mover)), and there are no
+pairs to find. The cost is that an `on_hit` handler in such a scene never fires,
+and nothing reports it. Weigh that deliberately. A client that is useless without
+its system raises instead, as a mover's `blocked_by:` does.
+
+## The two systems `Game` mounts
+
+**`RGame::Game` puts two systems on the root before the tree goes live.** Any node
+can reach them without the game wiring anything:
+
+| | |
+|---|---|
+| `node.system(RGame::Engine::Players)` | who is playing — devices, bindings, cameras, and who a newly used controller belongs to |
+| `node.system(RGame::Engine::Viewports)` | how the screen is divided — one `View` per active player, and collapsing the split |
+
+They are ordinary root-scoped systems, mounted the way a game mounts its own. A
+scene that needs a camera to follow asks `Players` (`players.primary.camera`). A
+cutscene that collapses the split asks `Viewports` (`viewports.solo!(camera)`).
+Both work from anywhere in the tree, with nothing passed in. That reach is why
+they are systems and not objects `Game` hands down.
+
+See [Input](input.md#players-seats-and-joining) and
+[Scene graph](scene_graph.md#viewports-and-views).
+
+## Collision: two indexes, one resolver
+
+Collision is the largest structure built from systems. Three pages cover its
+parts: the [components](components.md#boxcollider) a node carries, the
+[systems](#systems-that-index-their-clients-the-tag-registry-pattern) a scene
+mounts, and the
+[building blocks](internals.md#collisionsystem--move-an-actor-against-its-blockers)
+underneath. This section shows how they fit together.
+
+**A node has exactly one collision shape, and exactly one component owns it.** The
+[collider](components.md#boxcollider) *is* the shape. A
+[mover](components.md#mover) that wants to be stopped reads its sibling's box
+instead of building a second one. The rectangle that stops a step is the
+rectangle that reports a contact, so retuning one retunes both.
+
+**Collision uses two indexes, on purpose.** A tile map is already an index: the
+wall a step would hit follows from arithmetic on the step. A `TileWorld` divides
+by the tile size and asks the grid. Actors have no such structure, so a
+`CollisionWorld` buckets them into a
+[`SpatialHash`](internals.md#spatialhash--uniform-grid-broadphase) each step.
+Baking tile shapes into the broadphase would rebuild an index the grid already
+is. It would also cost time every frame on a map of tens of thousands of tiles.
+
+**The unification happens one level up.** A **blocker source** answers one
+question over plain numbers: where does this box land when it moves `dx`? Three
+sources exist:
+
+- `TileBlockers`, over the grid;
+- `ActorBlockers`, over the broadphase;
+- `BoundsBlockers`, over the world's edges.
+
+A blocked mover builds a
+[`CollisionSystem`](internals.md#collisionsystem--move-an-actor-against-its-blockers)
+at attach, from the sources its `blocked_by:` names. That system asks each source
+and takes the most restrictive answer on each axis. The axis-separated order that
+produces wall-sliding therefore exists **once**. An actor slides off a villager
+exactly as it slides off a fence.
+
+A source may also answer `travel?`: can this box move along a segment without
+being stopped? `TileBlockers` does. A [`Navigator`](components.md#navigator) uses
+it to check a route against the same resolver that will stop its walk.
+
+| | Mounted on the scene | Owned by the node |
+|---|---|---|
+| Tiles | [`TileWorld`](components.md#tileworld), which hands out one shared `TileBlockers` | — |
+| Actors | [`CollisionWorld`](components.md#collisionworld), the broadphase | an `ActorBlockers` per mover, holding its own collider and layer list |
+| The world's edge | any [`WorldBounds`](components.md#world) | a `BoundsBlockers` |
+| The step | — | one `CollisionSystem`, built at attach from the names above |
+
+Neither system needs the other, and most scenes mount one. `examples/scroll_map`
+has a map and no broadphase. `examples/collision` has a broadphase and no map.
+`examples/collision_tiles` mounts both, and the difference shows only in the names
+listed in `blocked_by`.
+
+"What stops a mover" and "what a collider touches" remain two questions, and a
+game sees the difference. See
+[Blocking and overlapping](#blocking-and-overlapping-are-two-reports-and-a-pair-gets-one-of-them)
+below, after the broadphase.
+
+## Systems that index their clients (the tag-registry pattern)
+
+**A many-to-many system keeps its own index of registered clients**, so it checks
+only nearby candidates instead of walking the tree for every pair. Broadphase
+collision works this way, on the scene node. `CollisionWorld`
+(engine/components/collision_world.rb) holds a `SpatialHash`: a spatial index of
+registered colliders, rebuilt each `update`. The index ignores shape, so
+`CircleCollider` and `BoxCollider` share one and collide with each other. The
+index holds node references only. It carries no component data and gives no
+data-locality benefit; it is a lightweight registry.
+
+**`CollisionWorld` ignores layers.** It reports every overlapping pair to both
+colliders. The owning node decides what a contact *means* by reading the other
+collider's `layer` tag:
+
+```ruby
+collider.on_hit { |other| queue_free if other.layer == :bullet } # in a Rock node
+```
+
+**A contact arrives as two edges, not as a state.** `on_hit` fires on the step a
+pair starts overlapping. `on_separated` fires on the step it stops. Each fires
+once per pair, with nothing in between. A handler can therefore count, play a
+sound or spend a life without guarding itself. That is why the system keeps an
+`Engine::ContactSet` per collider, instead of forwarding each step's broadphase
+results.
+
+`CollisionWorld` is a normal component on the scene node. It runs in the
+`update` traversal, where its broadphase runs, and goes away with the scene.
+`examples/collision` shows the whole loop: circles and crates registering,
+overlapping and separating through this system.
+
+### Blocking and overlapping are two reports, and a pair gets one of them
+
+**The same broadphase answers a second question.** A
+[mover](components.md#mover) that names a collider layer in `blocked_by:` is
+*stopped* by every box with that layer. It stops flush against the box's edge, as
+against a solid tile. One `BoxCollider` can thus be a wall to one actor and a
+trigger for another. Who declared the layer decides which; the collider itself
+says nothing.
+
+**The two reports never both fire for one pair.** Blocking leaves the boxes
+exactly touching. `CollisionBox.overlap?` uses the half-open span `[x, x + w)` on
+purpose. On a grid, pieces on neighbouring squares border each other constantly,
+and an inclusive test would report each as a contact. Measured on two 12×6 boxes:
+touching exactly, `on_hit` does not fire; overlapping by half a pixel, it does.
+That convention makes the two reports mutually exclusive by construction.
+
+A blocked pair therefore reports **no** contact. A mover that must both stop and
+react listens to `on_blocked`, not `on_hit`; see [`Mover`](components.md#mover).
+The rule of thumb:
+
+| The question | The report | Where it lives |
+|---|---|---|
+| what may I not pass through | `on_blocked` / `on_unblocked` | the mover that was stopped |
+| what am I touching | `on_hit` / `on_separated` | both colliders of the pair |
+
+`examples/collision_tiles` shows the first, and `examples/collision` the second.

data/docs/api/text.md

@@ -0,0 +1,133 @@
+# Text
+
+**The renderer comes with a font, and `text` draws with it.** Most games need
+nothing more:
+
+```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
+
+MyGame.new.run
+```
+
+## Where text goes
+
+`text(string, x, y, …)` puts the **top-left corner** of the line at `(x, y)`.
+Every other drawing method uses the same corner. Typography measures from the
+baseline, but 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
+```
+
+**`string` is a String or anything with `to_str`**, such as an
+[`Engine::Text`](toolbox.md#text--the-string-a-node-draws), which a node passes
+as it is. `text` and `text_width` raise `TypeError` for `nil`, a number, or a
+`to_str` that returns something other than a String.
+
+**A string is one line.** A newline has no special meaning. Draw two lines with
+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 run the same code, so a label centred by
+its measured width lands exactly there:
+
+```ruby
+@renderer.text(label, (width - @renderer.text_width(label)) / 2, 20)
+```
+
+**`text_width` and `text_height` also work outside `draw`**, unlike the drawing
+methods. Measuring touches no GPU, and a menu lays itself out while updating.
+
+A label built from a changing value, like a score, should come from
+[`RGame::Engine::Text`](toolbox.md#text--the-string-a-node-draws). It renders
+the string only when a variable or the language changes:
+
+```ruby
+@score = RGame::Engine::Text.new('hud.score', :score)   # once
+
+renderer.text(@score.with(score: @points), 10, 10)     # every frame
+```
+
+## 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 need two fonts. A font
+belongs to the app whose GPU context holds its glyphs, like an image. Drawing it
+through another app's renderer raises instead of painting blank boxes.
+
+The renderer builds its own 18px font on first use. Replace it, and every `text`
+call without a `font:` follows:
+
+```ruby
+@renderer.font = RGame::Core::Font.new(self, 24)
+```
+
+A file that is unreadable or 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 you pass no path.** It never
+looks a font up by name and never asks a system font database. A font is a file.
+
+This is a deliberate trade. Asking the operating system for "Arial" gets whatever
+that machine keeps under the name, or a substitute. A UI laid out on the
+developer's machine can then overflow on a player's. A shipped font renders
+identically everywhere, and costs about 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 still draws. A bad byte in a data file costs one visible box, not the
+whole label.
+
+## What it costs
+
+**The engine rasterises each glyph the first time it is drawn**, then keeps it in
+a texture atlas. Cost therefore grows with the **characters** a game uses, not
+with the strings it draws. A score that changes every frame costs no more glyph
+work after the 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, never drawn, uses no video memory.
+
+Nothing needs freeing. The engine releases a font's atlas when the font is
+collected, whether before or after its app. `Font.debug_live_pages` returns how
+many atlas pages exist. It serves tests, not gameplay.
+
+## What is not here
+
+rgame text has no markup (`<b>`, colour tags), no bold or italic variants, no
+multi-line layout and no word wrapping. It has no text input, no right-to-left
+text and no complex shaping. A string is one line of left-to-right glyphs.

data/docs/api/tile_maps.md

@@ -0,0 +1,237 @@
+# Tile maps
+
+**`RGame::Engine::TileMap` and `RGame::Engine::Tileset` hold a map made in
+[Tiled](https://www.mapeditor.org/) as plain data.** `TileMap` holds the grid: its
+size, its layers and the tile id in every cell. `Tileset` holds what each tile id
+means: which tiles are solid and which are animated. Neither class loads an image
+or names a renderer, so both run headless and in specs.
+
+A game rarely touches either class directly. The pieces that use them are:
+
+| | Uses the map to |
+|---|---|
+| [`TileWorld`](components.md#tileworld) | answer solidity and world-size questions for actors |
+| [`TileMapLayer`](components.md#tileworld) | draw one layer per node |
+| [`TileMapRenderer`](assets.md#tile-maps) | bake and draw the tiles |
+| `RGame::Game`'s `:tilemap` asset loader | load a `.tmx` and pair it with its tileset image |
+
+Read on when a scene queries the map itself, or when you author maps for rgame.
+
+## Loading a map
+
+```ruby
+require 'rgame'
+
+map, image_path = RGame::Engine::TileMap.load('examples/assets/town.tmx')
+
+image_path      # => "examples/assets/tileset.png"
+map.width       # => 60 — in tiles
+map.pixel_width # => 960
+map.tileset     # => RGame::Engine::Tileset
+```
+
+**`TileMap.load(tmx_path)` returns two values: the map and its tileset image
+path.** It reads the `.tmx`, follows it to the `.tsx` it names, parses both, and
+attaches the tileset to the map. It does not load the image. An image is a GPU
+handle, and the engine layer may not hold one. `RGame::Game`'s asset loader
+passes the path to the asset manager instead:
+
+```ruby
+app.assets.add_loader(:tilemap) do |path|
+  map, image_path = RGame::Engine::TileMap.load(path)
+  tiles = app.assets.image(image_path).tiles(map.tileset.tile_width,
+                                             map.tileset.tile_height)
+  RGame::Core::TileMapRenderer.new(map, tiles)
+end
+```
+
+In a game, reach the parsed map through that loader:
+`app.assets.tilemap('map/island.tmx').map`.
+
+**Every path resolves relative to the file that names it.** The `.tsx` resolves
+next to the `.tmx`, and the image next to the `.tsx`. Tiled writes paths this
+way, so you can move a map and its tileset together.
+
+`TileMap.parse(tmx_string)` parses a `.tmx` from a String and touches no files. It
+leaves `tileset` as `nil`. Attach one with `map.tileset = Tileset.parse(...)`
+before asking about solidity.
+
+### What rgame reads from Tiled
+
+rgame supports a subset of the `.tmx` format. A map outside it fails to parse or
+parses wrongly, so author within these limits:
+
+| | Supported |
+|---|---|
+| Orientation | orthogonal |
+| Tilesets | **one**, in an external `.tsx` file; an embedded tileset has no `source` and `load` raises |
+| Layer data | base64 with zlib compression (Tiled's "Base64 (zlib compressed)"); other encodings raise |
+| Layers | tile layers only; object and image layers are ignored |
+| Flipped or rotated tiles | the flip flags are stripped, so the tile draws unflipped |
+| Map size | fixed; infinite maps are not read |
+
+## `RGame::Engine::TileMap`
+
+### Geometry
+
+| Reader | |
+|---|---|
+| `width`, `height` | the map's size in tiles |
+| `tile_width`, `tile_height` | one tile's size in pixels |
+| `pixel_width`, `pixel_height` | the map's size in pixels |
+| `layer_count` | how many tile layers the map has |
+| `tileset`, `tileset=` | the attached `Tileset`, or `nil` |
+| `tileset_source`, `firstgid` | the `.tsx` path the map names, and the tileset's first gid |
+
+### Reading cells
+
+```ruby
+map.gid(0, 12, 7)          # the gid in layer 0 at column 12, row 7
+map.in_bounds?(60, 0)      # => false — columns run 0..59
+map.gid(0, -1, 0)          # => 0 — outside the map, every layer is empty
+```
+
+**A gid is Tiled's global tile id.** `0` means an empty cell. Any other gid names a
+tile in the tileset; `Tileset#local_id(gid)` turns it into the tile's index in the
+tileset image. Layer `0` is the bottom layer, as Tiled lists them.
+
+`gid` answers `0` for any cell outside the map, so a caller never checks bounds
+first. The map stores its gids in one
+[`Util::Tensor`](values.md#rgameutiltensor), indexed column, row, layer.
+
+### Solidity
+
+```ruby
+map.solid_tile?(12, 7)          # any layer solid at that cell?
+map.solid_at?(200.5, 116.0)     # the same, from a world position in pixels
+```
+
+**A cell is solid when any layer holds a solid tile there.** Collision considers
+every layer, whatever it draws like. `solid_at?(world_x, world_y)` divides by the
+tile size and asks `solid_tile?` for that cell. **Outside the map is not solid.**
+Keep actors inside with `blocked_by: [:bounds]` on their mover.
+
+Both methods need an attached tileset, which `load` provides.
+
+Actors do not call these per step. [`TileWorld`](components.md#tileworld) reads
+`solid_tile?` once per cell into a
+[`Util::SolidGrid`](values.md#rgameutilsolidgrid), and collision and pathfinding
+read that grid.
+
+### Layers drawn above the actors
+
+```ruby
+map.above_layer?(2)   # => true when Tiled marks layer 2 `above`
+```
+
+**Mark a layer `above` in Tiled** to draw it over the actors, for tree canopies
+or roofs. Add a custom **bool** property named `above` to the layer and tick it. A
+layer without the property draws below.
+
+The flag affects drawing order only. `TileWorld#first_above_layer` returns the
+first flagged layer, and
+[`TileMapLayer.mount`](components.md#tileworld) leaves the actors' gap below it.
+A map with no flagged layer puts the actors over everything.
+
+### Building a map by hand
+
+```ruby
+require 'rgame'
+
+map = RGame::Engine::TileMap.new(
+  width: 2, height: 1, tile_width: 16, tile_height: 16,
+  tileset_source: 'tiles.tsx', firstgid: 1,
+  layers: [[1, 2]],          # one layer, gids row by row
+  above: [false]
+)
+map.tileset = RGame::Engine::Tileset.new(
+  firstgid: 1, columns: 2, tile_width: 16, tile_height: 16,
+  image_source: 'tiles.png', animations: {}, solid_ids: Set[1]
+)
+
+map.solid_at?(20.0, 3.0)   # => true — gid 2 is local tile 1, which is solid
+map.solid_at?(3.0, 3.0)    # => false
+```
+
+**Specs build small maps this way**, with no files. `layers:` is an Array of
+layers. Each layer is a flat Array of `width * height` gids, row by row. `above:`
+is optional and defaults to no layer above.
+
+## `RGame::Engine::Tileset`
+
+**A `Tileset` says what each tile in a sheet is.** It knows the sheet's geometry,
+which tiles are solid, and which are animated.
+
+| Reader | |
+|---|---|
+| `firstgid` | the gid of the tileset's first tile in the map |
+| `columns` | how many tiles one row of the sheet holds |
+| `tile_width`, `tile_height` | one tile's size in pixels |
+| `image_source` | the sheet image, as the `.tsx` names it |
+| `animations` | `{ local_id => [Frame, ...] }` for every animated tile |
+| `animated_ids` | the local ids that have an animation |
+| `solid_ids`, `solid_ids=` | a Set of the local ids that are solid |
+
+`Tileset.parse(tsx_string, firstgid:)` parses a `.tsx` from a String. The
+`firstgid` comes from the map, because Tiled stores it in the `.tmx`, not in the
+`.tsx`.
+
+### Local ids
+
+```ruby
+tileset.local_id(37)   # => 36 when firstgid is 1
+```
+
+**A local id is a tile's index in the sheet**, counted from 0, left to right and
+top to bottom. It equals `gid - firstgid`. `Image#tiles` slices a sheet in the same
+order, so a local id indexes that Array directly.
+
+### Solid tiles
+
+```ruby
+tileset.solid?(gid)            # takes a gid, not a local id; 0 is never solid
+tileset.solid_ids << 12        # make local tile 12 solid
+```
+
+**A tile is solid when it has a collision shape in Tiled.** Open the tileset in
+Tiled's collision editor and draw any shape on the tile. `parse` marks every tile
+whose `<objectgroup>` holds at least one object. The shape itself is ignored:
+rgame treats a solid tile as a solid square. The map carries its collision, so
+changing which tiles block needs no code.
+
+`solid_ids` is writable, for a game that adds or removes solid tiles in code. Change
+it before a `TileWorld` first asks, because the world copies solidity into its own
+grid once.
+
+### Animated tiles
+
+```ruby
+tileset.animations[37]           # => [#<struct Frame tile_id=37, duration=250>, ...]
+tileset.frame_local_id(37, 0)    # => 37
+tileset.frame_local_id(37, 250)  # => 46
+```
+
+**Animate a tile in Tiled's tile animation editor.** `parse` reads each frame as a
+`Tileset::Frame` with a `tile_id` (a local id) and a `duration` in milliseconds.
+
+`frame_local_id(local, ms)` returns the local id to draw for tile `local` after
+`ms` milliseconds. The animation loops. A tile without an animation returns
+itself. The time is an argument, not a clock read, so pausing is "stop
+accumulating".
+
+**Tiled speaks milliseconds; the engine speaks seconds.** `TileWorld` accumulates
+`elapsed` in seconds, and `TileMapRenderer` converts it once per draw, as
+`(elapsed * 1000).to_i`. Convert the same way when you call `frame_local_id`
+yourself.
+
+## Testing against a map
+
+`TileMapRenderer` draws any object that answers the tile map contract, and never
+names `TileMap`. rgame's own suite states that contract in
+`spec/support/shared_examples/a_tile_map.rb`. It checks both `TileMap` and the
+spec stand-in `StubTileMap` against it. The contract covers `layer_count`,
+`width`, `height`, `tile_width`, `tile_height`, `gid`, and a `tileset` answering
+`local_id`, `animations` and `frame_local_id`.
+
+A spec that needs a map but no files builds one [by hand](#building-a-map-by-hand),
+or parses a `.tmx` string with `TileMap.parse`.