rgame 0.1.0

data/docs/api/drawing.md

@@ -0,0 +1,330 @@
+# Drawing
+
+`RGame::Core::Renderer` is what a game draws with. It is created from an app and
+used inside `draw`:
+
+```ruby
+require 'rgame'
+require 'rgame/core'
+
+class MyGame < RGame::Core::App
+  Color = RGame::Util::Color
+
+  def initialize
+    super(width: 800, height: 600, caption: 'demo')
+    @renderer = RGame::Core::Renderer.new(self)
+    @hero = RGame::Core::Image.new(self, 'hero.png')
+  end
+
+  def draw
+    @renderer.rect(40, 40, 160, 100, color: Color.new(224, 64, 64))
+    @renderer.circle(620, 110, 70, color: Color.new(64, 96, 224))
+    @renderer.image(@hero, 400, 300, angle: 45)
+  end
+end
+
+MyGame.new.run
+```
+
+Two things about that are worth knowing before anything else.
+
+**Drawing is only legal inside `draw`.** Calling one of these from `update` or
+from a constructor raises. The frame is not open at those times, so the call
+would be silently discarded — and an invisible failure is worse than a loud one.
+
+**Nothing is drawn immediately.** Calls accumulate, and the frame is sorted and
+sent to the GPU once, after `draw` returns. So the order you make calls in does
+not decide what ends up on top — `z:` does.
+
+## Coordinates, colours and z
+
+| | |
+|---|---|
+| Origin | Top-left. x grows right, y grows **down**. |
+| Angles | Degrees. A **positive angle turns clockwise** on screen. |
+| `z:` | Higher is nearer the viewer. Equal z keeps call order. |
+| `color:` | `nil` (white), `[r, g, b]`, `[r, g, b, a]`, or a `RGame::Util::Color`. |
+
+`z` defaults to `50` for shapes and `0` for images, so a debug box or a health
+bar drawn without a `z:` lands on top of the scene rather than under it.
+
+Equal-z stability matters more than it sounds: without it, two sprites on the
+same layer would swap places whenever the sort felt like it, which reads as
+flicker.
+
+### Colours and allocation
+
+Passing a `Color` allocates nothing — it is a frozen value, and the same one can
+be shared by every sprite that uses it. Passing an array allocates a colour per
+call, which is fine at setup and wasteful sixty times a second:
+
+```ruby
+RED = RGame::Util::Color.new(224, 64, 64)   # once
+
+def draw
+  @renderer.rect(10, 10, 50, 50, color: RED) # every frame, allocation-free
+end
+```
+
+## Shapes
+
+```ruby
+renderer.rect(x, y, width, height, z: 50, color: nil)
+renderer.quad(x1, y1, x2, y2, x3, y3, x4, y4, z: 50, color: nil)
+renderer.triangle(x1, y1, x2, y2, x3, y3, z: 50, color: nil)
+renderer.line(x1, y1, x2, y2, thickness: 1.0, z: 50, color: nil)
+renderer.circle(cx, cy, radius, z: 50, color: nil, segments: 64)
+renderer.debug_box(x, y, width, height, z: 50)
+```
+
+A **quad's** four points are taken in loop order — top-left, top-right,
+bottom-right, bottom-left for a rectangle. Listing them in Z order gives an
+hourglass.
+
+A **line** has real thickness because it is drawn as a quad. OpenGL's own line
+width is a suggestion drivers are free to ignore above one pixel, so a line
+worth seeing has to be a shape.
+
+A **circle** is a fan of triangles, and the whole fan is one batch — there is no
+cached circle texture to warm up and nothing to configure. `segments:` is there
+for the rare case where 64 is too many or too few.
+
+`debug_box` is a translucent red rectangle for visualising a collision box, so a
+scene can ask for one without deciding what colour "debug" is.
+
+## Images
+
+```ruby
+renderer.image(image, cx, cy, angle: 0, scale: 1, z: 0, color: nil)
+renderer.image_at(image, x, y, scale_x: 1, scale_y: 1, z: 0, color: nil)
+renderer.background(image, x = 0, y = 0, z: 0, color: nil)
+```
+
+Three anchors for three jobs. `image` **centres** on the position given and
+rotates about that centre — the sprite case. `image_at` places the **top-left**
+corner and scales each axis on its own — tiles, nine-slice corners, sheet
+frames. `background` is `image_at` at natural size, named for its usual job.
+
+### Mirroring
+
+A negative scale on `image_at` mirrors the image **inside the same rectangle**.
+It does not move it:
+
+```ruby
+renderer.image_at(frame, x, y, scale_x: facing_left ? -1 : 1)
+```
+
+Both calls cover the same pixels; only the picture is reversed. That is worth
+knowing if you are coming from Gosu, where a negative scale mirrors *about* the
+anchor and the caller adds a width back to compensate. Here `(x, y)` is the
+top-left corner whatever the sign, so there is nothing to compensate for — and
+nothing to forget.
+
+A scale of `0` draws nothing.
+
+`color:` tints: the image's pixels are multiplied by it, so white leaves the
+image alone and a colour with alpha fades it.
+
+See [Images](images.md) for loading files and slicing sprite sheets.
+
+**An image can only be drawn by the app that loaded it.** GPU textures belong to
+one window's OpenGL context and are not shared with another, so drawing another
+app's image would sample nothing and paint a plain white rectangle. Rather than
+let that happen quietly, it raises `ArgumentError`. In a one-window game — which
+is nearly all of them — this never comes up.
+
+## Drawing by id
+
+Game logic names an asset; it does not hold one. That is not a convenience —
+the scene layer may hold `RGame::Util` values but no `RGame::Core` handle at
+all, so a Symbol or a path is the only thing a node *can* carry.
+
+An id is normally a **root-relative path**, resolved through the app's
+[asset manager](assets.md) and then remembered:
+
+```ruby
+renderer.sprite('example 09/player.json', row, col, x, y, flip_x: false, z: 0)
+renderer.image('space.png', cx, cy, angle: 0, scale: 1)
+renderer.background('space.png')
+renderer.tilemap('map/island.tmx', camera_x, camera_y, viewport_w, viewport_h)
+renderer.tilemap_overlay('map/island.tmx', camera_x, camera_y, viewport_w, viewport_h, z: 20)
+```
+
+Nothing has to be set up for that: `Renderer.new(app)` takes the app's own
+manager, so a path just works. `Renderer.new(app, assets: other)` overrides it.
+
+### Registering
+
+`register_*` pre-binds an id to an object you chose, and wins over the asset
+manager. It is for the two things a path cannot name: an id that is not a file,
+and an object the game assembled itself.
+
+```ruby
+renderer.register_image(:space, app.assets.image('space.png'))
+renderer.register_sheet(:hero, app.assets.sheet('hero.json'))
+renderer.register_tilemap(:level1, app.assets.tilemap('island.tmx'))
+renderer.register_nine_slice(:panel, atlas.nine_slices[:panel])
+renderer.register_ui_atlas(atlas)   # every element under its own name
+
+renderer.image(:space, 100, 100)
+```
+
+**Nine-slices are registration-only.** Their ids name an *element of an atlas*,
+not a file, so there is nothing for a manager to resolve them to.
+
+### What resolution does
+
+| Given | |
+|---|---|
+| An `Image` | drawn directly — `#image`, `#image_at` and `#background` all take one |
+| A registered id | the registered object |
+| A `String` | resolved through the asset manager, then remembered |
+| A `Symbol` that is not registered | `KeyError`, naming the id and the type |
+| `nil` | `TypeError` |
+
+A Symbol is never offered to the asset manager, because only a String can be a
+path. So a typo'd Symbol says "no sheet registered for `:heor`" rather than
+whatever a loader makes of being handed a Symbol for a filename — and a broken
+*file* still raises its own `LoadError` naming it, which is a different bug
+wanting a different fix.
+
+Resolution happens once per id and the answer is kept, so per-frame drawing
+neither re-resolves nor allocates a lookup key.
+
+## Transform blocks
+
+Each of these applies to everything drawn inside it, and undoes itself
+afterwards — including when the block raises.
+
+```ruby
+renderer.translated(dx, dy) { ... }
+renderer.rotated(angle, pivot_x, pivot_y) { ... }
+renderer.scaled(sx, sy = sx) { ... }
+renderer.clipped(x, y, width, height) { ... }
+```
+
+They nest, and they compose in the order they are opened:
+
+```ruby
+renderer.translated(-camera.x, -camera.y) do   # world space -> screen space
+  renderer.rotated(ship.angle, ship.x, ship.y) do
+    renderer.image(hull, ship.x, ship.y)
+  end
+end
+```
+
+`translated` is how a camera works, and the reason it is a *draw-time* transform
+rather than something baked into positions is that the same world can then be
+drawn twice, under two different offsets — which is what split-screen is.
+
+`rotated(0, …)`, `translated(0, 0)` and `scaled(1)` are free: they skip the
+transform entirely and just run the block, so unrotated drawing pays nothing.
+
+### Clipping and split-screen
+
+A clip **narrows**. Nesting one inside another intersects them, so a child can
+never draw outside the region its parent allowed. Two clipped blocks are a
+split screen:
+
+```ruby
+def draw
+  @renderer.clipped(0, 0, 400, 600) do
+    @renderer.translated(-@player_one.x, -@player_one.y) { draw_world }
+  end
+
+  @renderer.clipped(400, 0, 400, 600) do
+    @renderer.translated(400 - @player_two.x, -@player_two.y) { draw_world }
+  end
+end
+```
+
+## Recordings: bake once, replay cheaply
+
+A tile layer is a couple of thousand quads that have not changed since the level
+loaded. `record` bakes a block of drawing so that replaying it costs one call
+per texture, however many draws went into it:
+
+```ruby
+def draw
+  @ground ||= @renderer.record do
+    @tiles.each { |tile| @renderer.image(tile.image, tile.x, tile.y) }
+  end
+
+  @ground.draw(-@camera.x, -@camera.y)
+end
+```
+
+Nothing is drawn at bake time — the block's output goes into the recording
+instead of into the frame. `record` must be called inside `draw` like everything
+else, which is why the example bakes on the first frame rather than in
+`initialize`.
+
+```ruby
+baked.draw(x = 0, y = 0, z: 0, color: nil)
+baked.batch_count   # GL calls one replay costs
+baked.width         # the size of what was baked
+baked.empty?
+```
+
+**Positions, texture coordinates, colours and any transforms inside the block
+are baked in.** The transform in effect when the recording is *drawn* applies on
+top, so a baked layer scrolls under a camera without being rebuilt, and the same
+recording can be stamped in several places:
+
+```ruby
+5.times { |i| @bush.draw(i * 120, 300) }
+```
+
+**`color:` tints the replay** — each recorded colour is multiplied by it, so a
+whole baked layer can be faded out at once.
+
+**Clipping cannot be baked.** Clipping happens when pixels are rasterised, so a
+clip rectangle captured in one place would be wrong everywhere else the
+recording is drawn. Pushing a clip inside a `record` block raises; clip the
+replay instead, which is what was meant anyway:
+
+```ruby
+@renderer.clipped(0, 0, 400, 600) { @ground.draw(-@camera.x, -@camera.y) }
+```
+
+Recordings do not nest, and a block that raises leaves nothing half-recorded
+behind. A recording keeps the images baked into it alive, so a sprite sheet
+dropped after baking does not take its texture with it.
+
+## Testing what a scene draws
+
+The renderer is an interface, not a class your game should name. Game logic
+receives one and calls methods on it; a headless spec passes a recording fake
+instead and asserts on the calls:
+
+```ruby
+renderer = FakeRenderer.new
+health_bar.draw(renderer)
+
+expect(renderer.calls_to(:rect).map(&:args)).to eq([[10, 10, 64, 8]])
+```
+
+Recordings are faked too, and the fake keeps the two questions apart — what was
+baked, and where it was replayed:
+
+```ruby
+ground = renderer.record { ... }   # => a FakeRecording
+
+expect(ground.calls.size).to eq(tiles.size)   # baked once, not per frame
+expect(ground.draws.map(&:args)).to eq([[-camera.x, -camera.y]])
+```
+
+That runs with no window, no GPU and no clock. The fake and the real renderer
+are both checked against one shared contract (`spec/support/shared_examples/
+a_renderer.rb`), so the fake cannot drift into describing a renderer that does
+not exist — which would leave a green test suite and a game that no longer runs.
+
+## Text
+
+`renderer.text(string, x, y)` draws a line of text, and `text_width` measures
+one. See [Text](text.md) for fonts, the shipped default and what it covers.
+
+## What is not here yet
+
+Audio and drawing by asset id (`sprite(:hero, row, col, …)`) are still to come.
+Today an image is passed as an object rather than looked up in a registry.

data/docs/api/game.md

@@ -0,0 +1,99 @@
+# `RGame::Game`
+
+The entry point of a game, and the one class that knows both halves of the
+engine.
+
+```ruby
+$LOAD_PATH.unshift File.expand_path('../lib', __dir__)
+require 'rgame/game'
+
+class HelloScene < Engine::Node2D
+  def on_draw(renderer) = renderer.text('Hello world!', 250, 200)
+end
+
+RGame::Game.new(root: HelloScene.new, caption: 'Hello').start
+```
+
+A complete game is a root node plus that. `Game` assembles what a running game
+needs around it — the window and its loop, the renderer, the asset manager, the
+sound device, the input mapper, the debug overlay — and drives the root node.
+
+```ruby
+RGame::Game.new(root:, width: 640, height: 480, caption: 'RGame',
+                media_root: 'media', action_map: {})
+```
+
+| Reader | |
+|---|---|
+| `root` | the node tree |
+| `renderer` | what scenes draw through |
+| `action_mapper` | physical input → named actions |
+| `assets`, `audio`, `media_root`, `width`, `height`, `fps` | inherited from [App](app.md) |
+
+`start` brings the tree live — it hands the game to the root as its `context`,
+calls `enter_tree`, and runs the loop until the window closes. `Esc` quits and
+`F1` toggles the debug overlay.
+
+## Why this class exists at all
+
+`RGame::Engine` holds game concepts and may not name
+`RGame::Core`; `RGame::Core` owns windows, textures and sound devices and may
+not know Engine exists. Two RuboCop cops enforce that. Something still has to
+introduce them, and **this is that something** — keeping the introduction in one
+file is what makes the rule checkable everywhere else.
+
+The tile map is the clearest case: parsing a `.tmx` is Engine's job, drawing one
+is Core's, and neither may call the other. So `Game` installs the loader that
+joins them, and `app.assets.tilemap('map/island.tmx')` works from then on.
+
+## Reaching the game from a node
+
+A node deep in the tree gets at the asset manager through the root's context,
+so nothing has to be threaded through constructors:
+
+```ruby
+sheet = node.root.context.assets.sheet('player.json')
+```
+
+## Input
+
+`action_map` names the actions a game has, in terms of the physical ids
+[Input](input.md) knows:
+
+```ruby
+RGame::Game.new(
+  root: Root.new,
+  action_map: {
+    move_x: { axis: %i[left right] },   # -1.0 .. 1.0
+    fire:   { button: %i[fire] }        # held / pressed / released
+  }
+)
+```
+
+A scene reads the resulting snapshot in `on_control(actions)` — `actions.axis(:move_x)`,
+`actions.pressed?(:fire)` — and never sees a key.
+
+**Input is polled once per simulation tick**, not once per rendered frame. That
+matters for edge queries: `pressed?` means "held now, not held at the previous
+poll", so whatever polls decides what a press *is*. A loop that renders faster
+than it simulates would otherwise consume the press between two ticks, and
+menus would stop responding on fast machines only.
+
+Polling per tick costs nothing and loses nothing, because the C layer snapshots
+the keyboard once per frame: several ticks inside one frame read identical
+state, and the edge lands on the first of them. One press, one `pressed?`.
+
+## Subclassing it
+
+`Game` is an [`App`](app.md), so anything an App can override it can too. The
+loop, the fixed timestep and the catch-up cap are the engine's; a subclass adds
+behaviour around the tree rather than replacing the shell.
+
+```ruby
+class MyGame < RGame::Game
+  def button_down(id)
+    super                      # keeps Esc and F1 working
+    @paused = !@paused if id == RGame::Util::Controls::KEY_SPACE
+  end
+end
+```

data/docs/api/images.md

@@ -0,0 +1,118 @@
+# Images
+
+`RGame::Core::Image` is a picture on the GPU. Loading one decodes a PNG and
+uploads it; everything after that — subimages, tiles, whole sprite sheets — is a
+*view* of that single upload.
+
+```ruby
+require 'rgame/core'
+
+img   = RGame::Core::Image.new(app, 'hero.png')
+frame = img.subimage(0, 0, 16, 16)
+walk  = RGame::Core::Image.load_tiles(app, 'hero.png', 16, 16)
+```
+
+There is nothing to draw them with yet — the renderer is the next piece of the
+engine to land. What works today is loading, slicing and measuring.
+
+## Loading
+
+```ruby
+image = RGame::Core::Image.new(app, 'assets/hero.png')
+image.width    # => 64
+image.height   # => 32
+```
+
+The `app` argument is required and comes first. A texture lives inside one
+OpenGL context, so an image genuinely is an image *of* a window rather than a
+free-floating object — and saying so is what makes two windows work, and what
+lets the image keep its app alive for as long as it needs it.
+
+PNG is the only format. A file that cannot be read or decoded raises
+`RGame::Core::Image::LoadError` with the path in the message:
+
+```ruby
+begin
+  RGame::Core::Image.new(app, 'assets/typo.png')
+rescue RGame::Core::Image::LoadError => e
+  warn e.message   # => "could not read assets/typo.png"
+end
+```
+
+Greyscale and palette PNGs load fine; they are converted to RGBA on the way in,
+so there is only ever one pixel format in play.
+
+**Images are always sampled nearest-neighbour.** There is no setting for it.
+The engine exists to draw pixel art, and blurring it on scale-up is never the
+intent.
+
+## Slicing: subimages and tiles
+
+```ruby
+sheet = RGame::Core::Image.new(app, 'tiles.png')   # say 64x32
+
+sheet.subimage(16, 0, 16, 16)   # one 16x16 region
+sheet.tile_count(16, 16)        # => 8   (4 columns x 2 rows)
+sheet.tile(16, 16, 5)           # the sixth tile
+sheet.tiles(16, 16)             # => [Image, Image, ...] all eight
+sheet.each_tile(16, 16) { |t| }  # the same, without building the Array
+```
+
+`Image.load_tiles(app, path, w, h)` is `new` plus `tiles` in one step, and is
+the usual way to open a sprite sheet:
+
+```ruby
+frames = RGame::Core::Image.load_tiles(app, 'explosion.png', 32, 32)
+```
+
+Three things are worth knowing about all of these:
+
+**Nothing is decoded or uploaded twice.** A hundred tiles are a hundred small
+Ruby objects over one texture. Slicing a sheet is cheap enough to do at load
+time without thinking about it.
+
+**Tiles come back in reading order** — left to right, then top to bottom — which
+is how sprite-sheet frames are numbered everywhere else.
+
+**A partial tile at the right or bottom edge is not a tile.** A 70-pixel-wide
+sheet sliced into 16s yields four columns and leaves six pixels of padding
+alone, because half a sprite is never what was meant.
+
+### Coordinates are relative to what you cut from
+
+`subimage` on a subimage composes, and cannot escape its parent:
+
+```ruby
+row  = sheet.subimage(0, 16, 64, 16)   # the bottom row of the sheet
+tile = row.subimage(32, 0, 16, 16)     # 32 pixels into *the row*, not the sheet
+```
+
+A rectangle that does not fit raises `ArgumentError`, and an out-of-range tile
+index raises `IndexError`, rather than either returning `nil`:
+
+```ruby
+sheet.subimage(0, 0, 999, 999)   # ArgumentError: does not fit in a 64x32 image
+sheet.tile(16, 16, 99)           # IndexError: 8 tiles of 16x16
+```
+
+A `nil` here would travel a long way — into an asset table, out of it three
+scenes later — before failing as a `NoMethodError` with nothing left pointing at
+the coordinates that were wrong.
+
+## Lifetime
+
+You never free an image. The texture is released when the last view of it is
+garbage-collected, and the order does not matter: dropping the sheet while its
+tiles are still in use keeps the upload alive, and dropping the window first is
+also fine.
+
+```ruby
+sheet  = RGame::Core::Image.new(app, 'tiles.png')
+ground = sheet.tile(16, 16, 0)
+sheet  = nil     # the upload stays — `ground` is still a view of it
+```
+
+That is worth stating because a leaked GPU texture is invisible while it
+happens: nothing is slower, nothing looks wrong, and video memory fills up over
+an hour of play. `Image.debug_live_textures` reports how many uploads exist, and
+is there for tests to assert against; it is not part of the drawing API.