rgame 0.2.0 → 0.3.0

data/docs/api/audio.md

@@ -1,14 +1,22 @@
 # Audio
 
+rgame plays sound through three classes. `Audio` is the sound device. A `Sample`
+is a short sound that can play over itself. A `Song` is a long sound streamed
+from disk.
+
+**A scene in an `RGame::Game` never touches these classes.** It emits on
+[`AudioBus`](toolbox.md#audiobus--decoupled-audio-facts), for example
+`RGame::Engine::AudioBus.play_sound('hit.ogg')`, and the game's director plays it.
+The example below drives the device directly from a plain `App`:
+
 ```ruby
 require 'rgame/core'
 
 class MyGame < RGame::Core::App
   def initialize
     super(width: 800, height: 600, caption: 'demo')
-    @audio = RGame::Core::Audio.new
-    @hit = @audio.sample('assets/hit.ogg')
-    @music = @audio.song('assets/theme.ogg')
+    @hit = audio.sample('assets/hit.ogg')
+    @music = audio.song('assets/theme.ogg')
     @music.play(looping: true)
   end
 
@@ -16,35 +24,40 @@ class MyGame < RGame::Core::App
     @hit.play if id == RGame::Util::Controls::KEY_SPACE
   end
 end
-```
 
-Three classes. `Audio` is the sound device; `Sample` is a short sound played
-over itself; `Song` is a long one streamed from disk.
+MyGame.new.run
+```
 
-Ogg Vorbis and WAV are the formats. Nothing else — see [What is not
-here](#what-is-not-here).
+rgame decodes Ogg Vorbis and WAV, and nothing else. See
+[What is not here](#what-is-not-here).
 
 ## The device
 
 ```ruby
-audio = RGame::Core::Audio.new
-audio.backend    # => "PulseAudio"
-audio.volume     # => 1.0
+audio = app.audio          # the one a game uses
+audio.backend              # => "PulseAudio"
+audio.volume               # => 1.0
 audio.volume = 0.8
 ```
 
-**It takes no app.** Sound is not tied to a window: it survives one being
-resized or recreated, and there is no GL context involved. One device for the
-program is the normal arrangement.
+**Use `App#audio`.** An app opens the device on first use and hands it the app's
+asset manager. That manager lets `play_sound('hurt.ogg')` name a file.
+`RGame::Core::Audio.new` builds a standalone device for a tool or a spec. It has
+no manager, so it plays only objects it receives or has registered.
+
+**The device is not tied to a window.** Unlike an `Image`, a sound belongs to no
+GL context. It survives a window resize or rebuild, and `Audio.new` takes no app.
+An app holds one device only because a program wants exactly one, like its asset
+manager.
 
-**A machine with no sound hardware still gets a working device.** It opens a
-null backend and plays silently rather than raising, and `#backend` returns
-`"Null"`. That is deliberate — a game should run on a CI runner, in a container,
-or on a laptop with the sound card switched off, and crashing at startup over
-something nobody asked for is the worse failure. If your game wants to know, ask
-`#backend`; nothing else changes.
+**A machine without sound hardware still gets a working device.** It opens a
+null backend and plays silence instead of raising, and `#backend` returns
+`"Null"`. A game should run on a CI runner, in a container, or on a laptop with
+its sound card off. Crashing at startup over sound would be the worse failure.
+Ask `#backend` if your game needs to know; nothing else changes.
 
-`#volume` is the master volume, multiplied into everything the device plays.
+`#volume` is the master volume. The device multiplies it into everything it
+plays.
 
 ## Samples
 
@@ -55,21 +68,20 @@ hit.play
 hit.play    # a second voice, over the first
 ```
 
-A sample is decoded once, into memory, and played as often as you like.
-**Playing one that is already sounding layers another voice over it** rather
-than restarting it — which is what makes a fast run of footsteps sound like
-footsteps instead of one stuttering step.
+A sample decodes once, into memory, and plays as often as you like. **Playing a
+sample that is already sounding layers another voice over it.** It does not
+restart. A fast run of footsteps therefore sounds like footsteps, not one
+stuttering step.
 
-There is no handle for an individual play, and no way to stop one: a sample is
-fire-and-forget. Volume belongs to the sample and reaches every voice it has
-out, including the ones already sounding.
+A sample is fire-and-forget. A single play has no handle and cannot be stopped.
+Volume belongs to the sample and reaches every voice it has out, including those
+already sounding.
 
-Keep samples for short sounds. A sample holds its whole decoded length in
-memory — measured at roughly 10 MB per minute of CD-quality stereo — so a music
-track belongs in a `Song`.
+**Use samples for short sounds only.** A sample holds its whole decoded length in
+memory, roughly 10 MB per minute of CD-quality stereo. Put music in a `Song`.
 
-Two samples loaded from the **same path** share one decoded copy, so loading a
-file twice costs nothing the second time.
+Two samples loaded from the **same path** share one decoded copy. Loading a file
+a second time costs nothing.
 
 ## Songs
 
@@ -81,46 +93,71 @@ music.volume = 0.6
 music.stop
 ```
 
-A song is streamed from the file as it plays, so a three-minute track costs a
-buffer rather than forty megabytes.
+A song streams from its file as it plays. A three-minute track costs a buffer,
+not forty megabytes.
 
-**A song is one voice.** Playing one that is already playing restarts it from
-the beginning; so does playing it after `stop`. There is no pause — `stop` then
-`play` is "from the top", not "resume".
+**A song is one voice.** Playing a song that is already playing restarts it from
+the beginning, and so does playing it after `stop`. Songs cannot pause: `stop`
+then `play` starts from the top.
 
 `#playing?` and `#looping?` report what the song was last told to do.
-`#looping?` is the flag, not a count.
+`#looping?` is a flag, not a count.
 
-**"One song at a time" is your rule, not the engine's.** Two songs can play at
-once, which is what a crossfade is; if a game wants only one, it stops the old
-one before starting the new one.
+**The engine allows several songs at once**; a crossfade needs two. A game that
+wants one song at a time stops the old one before starting the next.
 
 ## Playing by id
 
-The same boundary drawing has: gameplay emits a fact and names the sound,
-because a scene may not hold a `Sample`.
+**Gameplay names a sound; it does not hold one.** Drawing follows the same rule,
+because a scene may not hold a `Sample`. `examples/sound` and `examples/music`
+show both kinds. The first fires and layers a sample from a button. The second
+loops, stops and restarts a song.
 
 ```ruby
-audio.register_sound(:hit, app.assets.sound('example 09/hurt.ogg'))
-audio.register_music(:theme, app.assets.song('example 09/theme.ogg'))
-
-audio.play_sound(:hit)
-audio.play_music(:theme)   # loops
+audio.play_sound('hurt.ogg')
+audio.play_music('theme.ogg')   # loops
 audio.stop_music
 ```
 
-Registration only, unlike the renderer's draw-by-id: a sound id is whatever a
-game wants to call it, and there is no per-frame path here to make resolving a
-path worth caching. An unknown id is a `KeyError`.
+**Ids come in two kinds, the same two the renderer uses.** A **String is a
+root-relative path**. The device resolves it through the asset manager on first
+use and remembers the result. A **Symbol is a name the game chose**, and only
+registration binds one:
 
-**`play_music` is idempotent.** Asking for the track that is already playing
-does nothing, so a scene that re-emits the request every time it is entered
-never restarts the music mid-loop.
+```ruby
+audio.register_sound(:hit, app.assets.sound('hurt.ogg'))
+audio.register_music(:theme, app.assets.song('theme.ogg'))
+audio.play_sound(:hit)
+audio.play_music(:theme)
+```
 
-**`stop_music` stops the song *this registry* started.** Gosu had a
-process-wide "current song"; there is no such global here, because one-song-at-
-a-time is a game's policy rather than the engine's. A `Song` you started by hand
-is yours to stop, and `stop_music` with nothing playing is a no-op.
+Registration also *overrides* a path. A game uses that to bind a sound it built
+instead of loaded. An id that is neither registered nor resolvable raises
+`KeyError`. `nil` raises `TypeError`, because an asset that resolved to nothing
+is a different bug from a mistyped name.
+
+**The device caches every resolution, and must.** `play_music` asks the song
+whether it is already playing. Resolving one path to two `Song` objects would
+defeat that check and restart the track on every request.
+
+**A game wires none of this.** When `RGame::Game` starts, it subscribes an
+[`AudioDirector`](toolbox.md) to the global `AudioBus`. When the loop ends, it
+unsubscribes it. A scene that emits on the bus is heard with no setup. The engine
+owns both steps because each failure is invisible. Without a director, the tree
+runs and the events fire, but nothing plays. A director left on the bus keeps
+the device, the asset manager and the whole `App` alive for the life of the
+process. A single game never notices, but a process running two games does.
+
+**`play_music` is idempotent.** Asking for the track already playing does
+nothing. A scene that repeats the request each time it is entered never restarts
+the music mid-loop.
+
+**`stop_music` stops the song `play_music` most recently started**, not whatever
+is sounding. The engine keeps no process-wide "current song", because one song at
+a time is a game's policy. **`play_music` with a different track does not stop the
+previous one**, so both play. To switch tracks, call `stop_music` first. You stop
+a `Song` you started by hand yourself. `stop_music` with nothing playing does
+nothing.
 
 ## Loading and failure
 
@@ -132,13 +169,18 @@ RGame::Core::Sample.new(audio, path)   # the same thing
 RGame::Core::Song.new(audio, path)
 ```
 
-Both forms exist. Prefer `audio.sample` — it reads in the direction the objects
-depend, and a stand-in device can offer it while `Sample.new` cannot (see
-[Testing](#testing)).
+**Prefer `audio.sample` and `audio.song`.** They read in the direction the
+objects depend, and a stand-in device can offer them, while `Sample.new` cannot
+be faked (see [Testing](#testing)).
+
+`audio.sample`, `audio.song` and the two constructors resolve a relative path
+against the working directory, and cache nothing. `app.assets.sound(path)` and
+`app.assets.song(path)` resolve against `media_root` and cache, and a String id
+passed to `play_sound` or `play_music` goes through them.
 
-A file that cannot be read, or that is not a format the engine decodes, raises
-`RGame::Core::Sample::LoadError` or `RGame::Core::Song::LoadError`, naming the
-file. Both are `StandardError`, so an ordinary `rescue` catches them:
+A file the engine cannot read or decode raises `RGame::Core::Sample::LoadError`
+or `RGame::Core::Song::LoadError`, naming the file. Both inherit from
+`StandardError`, so an ordinary `rescue` catches them:
 
 ```ruby
 @music = begin
@@ -149,12 +191,12 @@ rescue RGame::Core::Song::LoadError => e
 end
 ```
 
-The decision is made by **content, not by extension** — a text file named
-`.ogg` is refused.
+The engine checks the **content, not the extension**. It refuses a text file
+named `.ogg`.
 
 ## Volume
 
-Every volume — the device's, a sample's, a song's — behaves the same way:
+Every volume behaves the same way, whether the device's, a sample's or a song's:
 
 | Value | Effect |
 |---|---|
@@ -163,33 +205,32 @@ Every volume — the device's, a sample's, a song's — behaves the same way:
 | above `1.0` | amplified; clipping is yours to avoid |
 | below `0.0` | clamped to `0.0` |
 
-Negative is clamped rather than refused because a fader driven by a slider or an
-easing curve undershoots constantly, and silence is the meaningful answer — a
-negative volume would phase-invert the samples, which is *louder*.
+**A negative volume clamps to silence instead of raising.** A fader driven by a
+slider or an easing curve undershoots all the time, and silence is the useful
+answer. A true negative volume would invert the phase, which sounds *louder*.
 
-Volumes are 32-bit floats inside the mixer, so `0.8` reads back as
+The mixer stores volumes as 32-bit floats, so `0.8` reads back as
 `0.800000011920929`. Compare with a tolerance, not with `==`.
 
 ## What it costs
 
-Nothing needs freeing. A sample or a song releases what it holds when it is
-collected, and each one keeps its device alive for as long as it exists — so
-dropping your reference to the `Audio` while a sound is still around is safe,
-in either order.
+**Nothing needs freeing.** A sample or song releases its memory when it is
+collected. Each keeps its device alive while it exists. Dropping your reference
+to the `Audio` while a sound remains is safe, in either order.
 
-`RGame::Core::Audio.debug_live_sounds` reports how many samples and songs exist.
-It is there for tests, not for gameplay.
+`RGame::Core::Audio.debug_live_sounds` returns how many samples and songs exist.
+It serves tests, not gameplay.
 
 ## Testing
 
-Audio follows the same pattern as drawing: the engine layer is handed a device
-and calls it by method name, never by class, so a headless spec can substitute
-one that makes no sound and records everything.
+**Audio follows the drawing pattern.** The engine layer receives a device and
+calls it by method name, never by class. A headless spec can substitute a device
+that makes no sound and records every call.
 
-`spec/support/fake_audio.rb` is that stand-in, and
-`spec/support/shared_examples/an_audio_server.rb` is the interface both it and
-the real device are run against — so the fake cannot drift into describing an
-engine that no longer exists.
+rgame's own suite uses `spec/support/fake_audio.rb` as that stand-in.
+`spec/support/shared_examples/an_audio_server.rb` defines the contract, and both
+the fake and the real device run against it. A fake that drifted from the device
+would keep `rake spec` green while the game played nothing.
 
 ```ruby
 audio = FakeAudio.new
@@ -199,10 +240,10 @@ expect(audio.played?('hit.ogg')).to be(true)
 expect(audio.calls.map(&:name)).to eq(%i[sample sample_play])
 ```
 
-Nothing there loads a file, opens a device, or needs a sound card.
+That spec loads no file, opens no device and needs no sound card.
 
 ## What is not here
 
-MP3 and FLAC (Vorbis and WAV only, to keep the gem small), positional and 3D
-audio, effects and filters, fades, pausing, seeking, per-play handles, playback
-position, and recording.
+rgame audio has no MP3 or FLAC; it decodes Vorbis and WAV only, to keep the gem
+small. It also lacks positional and 3D audio, effects and filters, fades,
+pausing, seeking, per-play handles, playback position and recording.

data/docs/api/cli.md

@@ -0,0 +1,259 @@
+# The `rgame` command
+
+Installing the gem puts one command on your PATH.
+
+```
+gem install rgame
+rgame new tictactoe
+```
+
+| Command | Does |
+|---|---|
+| `rgame new NAME` | Creates the directory `NAME` and writes a runnable project into it |
+| `rgame version` | Prints the installed engine version |
+| `rgame help` | Prints usage |
+
+`rgame new` accepts a name made of letters, digits, underscores and dashes,
+starting with a letter, and refuses anything else. It also refuses a
+path that exists and is not a directory, and a directory that holds anything. It
+writes into an existing *empty* directory.
+
+## What `rgame new tictactoe` writes
+
+```
+tictactoe/
+├── Gemfile           rgame, plus rspec and rubocop for development
+├── Rakefile          rake spec, rake rubocop, rake
+├── README.md
+├── .ruby-version     the Ruby that ran `rgame new`
+├── .gitignore  .rspec  .rubocop.yml
+├── main.rb           boots the game and nothing else
+├── game.rb           class TictactoeGame < RGame::Game
+├── assets/           the game's media_root
+│   └── locales/
+│       └── en.yml    the English translation table
+├── nodes/
+│   └── root.rb       class Root < RGame::Engine::Node2D
+└── spec/
+    ├── spec_helper.rb
+    ├── locales_spec.rb
+    └── nodes/
+        └── root_spec.rb
+```
+
+Then:
+
+```
+cd tictactoe
+bundle install
+bundle exec rspec     # passes
+bundle exec rubocop   # green
+ruby main.rb          # a window saying "Hello from tictactoe!"
+```
+
+The generator builds the class name from the project name. It splits on
+underscores and dashes and capitalises each part. `tic_tac_toe` and
+`tic-tac-toe` both give `TicTacToeGame`.
+
+The project records two versions, both taken from the running generator rather
+than from a template. The `Gemfile` pins the engine loosely
+(`gem 'rgame', '~> 0.3'` from rgame 0.3.0). `.ruby-version` records the exact Ruby that ran
+`rgame new`, the one interpreter the project is known to work on. The Gemfile
+reads that file instead of repeating the number:
+
+```ruby
+ruby file: '.ruby-version'
+```
+
+Version managers and Bundler both read `.ruby-version`, so the two cannot drift
+apart.
+
+**Bundler treats that line as an exact requirement.** On any other Ruby,
+`bundle install` refuses to run. `4.0` does not match `4.0.5`; it matches only
+`4.0`. To accept a range, state it in the `Gemfile`. `.ruby-version` must stay a
+plain version number, because version managers read it:
+
+```ruby
+ruby '~> 4.0'   # instead of `ruby file: '.ruby-version'`
+```
+
+## Why the layout looks like this
+
+**The generated tree follows the engine's own layering.** The layout makes the
+right split the easy one in a new project. Three files carry it.
+
+**`game.rb` is the only file that requires `rgame/game`,** so it is the only one
+that loads SDL and OpenGL. It is the project's counterpart of
+[`RGame::Game`](game.md): the one class allowed to know both halves of the
+engine.
+
+```ruby
+require 'rgame/game'
+require_relative 'nodes/root'
+
+class TictactoeGame < RGame::Game
+  WIDTH = 640
+  HEIGHT = 480
+
+  def initialize(**)
+    super(root: Root.new,
+          caption: 'Tictactoe',
+          width: WIDTH,
+          height: HEIGHT,
+          media_root: File.join(__dir__, 'assets'),
+          **)
+  end
+end
+```
+
+The bare `**` forwards every keyword to `RGame::Game`, so all its options still
+work. Pass `players: 2` for split-screen. Pass `input:` to drive the game from a
+scripted input backend with no hardware attached.
+
+**`nodes/` requires `rgame`,** the graphics-free half. That loads `RGame::Util`
+and `RGame::Engine`, and no graphics library. A node receives a renderer at draw
+time and calls its methods by name. It never stores the renderer and never
+learns its class.
+
+```ruby
+require 'rgame'
+
+class Root < RGame::Engine::Node2D
+  def initialize
+    super
+    @greeting = RGame::Engine::Text.new('root.greeting')
+  end
+
+  def on_draw(renderer, _view)
+    renderer.text(@greeting, 20, 20)
+  end
+end
+```
+
+Override `on_control(actions)`, `on_update(dt)` and `on_draw(renderer, view)`,
+not `control`, `update` or `draw`. The engine does its bookkeeping in the outer
+methods and calls these hooks, so there is no `super` to forget. See
+[Scene graph](scene_graph.md).
+
+**`spec/spec_helper.rb` also requires `rgame`,** and `.rspec` loads it before
+every spec. It requires every file under `nodes/` too. The generated suite
+therefore runs headless. It has no window, no GPU and no clock, and `RGame::Core` is undefined.
+A spec that names Core fails loudly instead of opening a window.
+
+For the same reason, the generated spec uses a plain spy, not a verified double.
+The renderer it replaces lives on the far side of a line the suite does not
+cross. The generated `.rubocop.yml` turns `RSpec/VerifiedDoubles` off and writes
+down that reason:
+
+```ruby
+RSpec.describe Root do
+  describe '#on_draw' do
+    it 'draws its greeting from the English table' do
+      renderer = spy('renderer')
+
+      described_class.new.on_draw(renderer, nil)
+
+      expect(renderer).to have_received(:text).with('Hello from tictactoe!', 20, 20)
+    end
+  end
+end
+```
+
+The node passes its `Text` to `text`, so the spy records the `Text`. It still
+matches the String, because a `Text` is `==` to the String it reads. See
+[`Text`](toolbox.md#text--the-string-a-node-draws).
+
+Put new game logic under `nodes/`, and the whole simulation stays testable in
+milliseconds with no display, however large the game grows. Logic in `game.rb`
+loses that.
+
+## Text comes from a translation table
+
+**The generated root node draws a key, not a String.** `assets/locales/en.yml`
+holds the text, in Rails' format:
+
+```yaml
+en:
+  root:
+    greeting: "Hello from tictactoe!"
+```
+
+`RGame::Game` loads every `.yml` under `assets/locales/` and picks the player's
+language from their operating system. See
+[Game](game.md#translations-and-the-players-language). The node builds an
+[`Engine::Text`](toolbox.md#text--the-string-a-node-draws) once and draws it
+every frame. To add a language, add a file such as `de.yml` with the same keys.
+[Localization](localization.md) covers the format, plurals and the fallback.
+
+**The generated spec helper loads the same tables before every example.** It
+reads the files once, then calls `I18n.reset`, loads each table and sets
+`I18n.missing = :raise`. Every example therefore starts in the default locale
+with the game's own tables, whatever the example before it loaded. A spec that
+draws a key no table has fails with `I18n::MissingKey`.
+
+The spec helper names `assets/locales` itself, because `spec/` cannot load
+`game.rb`. Move the directory in one place and every spec that draws a key
+fails. Reloading costs about 8 µs per key per example.
+
+**`spec/locales_spec.rb` fails while a language lacks a key.** It checks that
+the default locale has a table, and that `I18n.missing_keys` is empty for every
+loaded locale. Its failure names each locale and its missing keys, such as
+`{de: ["root.greeting"]}`. In the game itself, a missing key falls back to the
+default locale's text, and a key no table has shows as itself.
+
+## The generated RuboCop configuration
+
+The generator loads `rubocop-performance`, `rubocop-rspec` and rgame's own cops,
+relaxes the `Metrics/*` cops for a game's long `update` and `draw` methods, and
+allows short coordinate names. `RSpec/SpecFilePathFormat` skips
+`spec/locales_spec.rb`, which describes `I18n` but checks the tables rather than a
+source file.
+
+**The gem ships its cops as a RuboCop plugin.** The generated `.rubocop.yml`
+loads it by path and class:
+
+```yaml
+plugins:
+  - rgame/rubocop:
+      plugin_class_name: RuboCop::Game::Plugin
+```
+
+The plain form, `- rgame`, would make RuboCop require the whole engine just to
+lint. An existing project gets the cops by adding those three lines.
+
+| Cop | Refuses | Where |
+|---|---|---|
+| `Game/NoInterpolationInHotPath` | string interpolation in a per-frame method | everywhere but `spec/` |
+| `Game/NoNeedlessAllocation` | a throwaway Array or Range literal on a per-frame path | everywhere but `spec/` |
+| `Game/DrawInLocalSpace` | a node's draw method reading its own `x`, `y` or `world_x` | everywhere |
+| `Game/NoLiteralText` | a String literal passed to `text` or `text_width` | everywhere |
+| `Game/NoCoreInEngineLayer` | naming `RGame::Core`, or requiring `rgame/core` or `rgame/game` | `nodes/` and `spec/` |
+
+A per-frame method is `update`, `control`, `draw`, `on_update`, `on_control` or
+`on_draw`, or any method with a `# hot-path` comment on the line above its
+`def`. For a label that changes, the answer to the first cop is an
+[`Engine::Text`](toolbox.md#text--the-string-a-node-draws).
+
+`Game/NoCoreInEngineLayer` guards the headless line the layout above draws. A
+spec that names `RGame::Core` already fails when it runs, but the cop also
+catches a branch no spec reaches. A bare `Core` counts only inside
+`module RGame`, so a game's own `Core` module passes.
+
+`Game/NoEngineInCoreLayer` ships too, switched off. It guards the engine's own
+repository, and a game has no layer for it to guard.
+
+## Adding to the generator
+
+`rgame new` derives its file list from `lib/rgame/cli/templates/`. A new file in
+a generated project needs a new template and nothing else; there is no manifest.
+The generator writes only files, so it creates a directory only by writing a
+template into it.
+Templates are ERB and may call `app_name`, `game_class`, `caption`,
+`ruby_version` and `rgame_requirement`.
+
+**No template may have a name starting with a dot.** The gemspec packages
+`lib/**/*` with `Dir.glob`, which skips dotfiles. A template called `.gitignore`
+would work in a checkout but be missing from the installed gem. Dotfile
+templates therefore use a plain name (`gitignore.tt`).
+`RGame::CLI::NewProject::DOTFILES` renames them on the way out.
+`spec/packaging_spec.rb` fails if a dotfile template appears.