rgame 0.4.0-x86_64-linux-gnu

data/docs/api/audio.md

@@ -0,0 +1,249 @@
+# 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')
+    @hit = audio.sample('assets/hit.ogg')
+    @music = audio.song('assets/theme.ogg')
+    @music.play(looping: true)
+  end
+
+  def button_down(id)
+    @hit.play if id == RGame::Util::Controls::KEY_SPACE
+  end
+end
+
+MyGame.new.run
+```
+
+rgame decodes Ogg Vorbis and WAV, and nothing else. See
+[What is not here](#what-is-not-here).
+
+## The device
+
+```ruby
+audio = app.audio          # the one a game uses
+audio.backend              # => "PulseAudio"
+audio.volume               # => 1.0
+audio.volume = 0.8
+```
+
+**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 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. The device multiplies it into everything it
+plays.
+
+## Samples
+
+```ruby
+hit = audio.sample('assets/hit.ogg')
+hit.volume = 0.5
+hit.play
+hit.play    # a second voice, over the first
+```
+
+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.
+
+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.
+
+**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. Loading a file
+a second time costs nothing.
+
+## Songs
+
+```ruby
+music = audio.song('assets/theme.ogg')
+music.play(looping: true)
+music.playing?   # => true
+music.volume = 0.6
+music.stop
+```
+
+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 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 a flag, not a count.
+
+**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
+
+**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.play_sound('hurt.ogg')
+audio.play_music('theme.ogg')   # loops
+audio.stop_music
+```
+
+**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:
+
+```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)
+```
+
+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
+
+```ruby
+audio.sample(path)   # => RGame::Core::Sample
+audio.song(path)     # => RGame::Core::Song
+
+RGame::Core::Sample.new(audio, path)   # the same thing
+RGame::Core::Song.new(audio, path)
+```
+
+**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 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
+  audio.song('assets/theme.ogg')
+rescue RGame::Core::Song::LoadError => e
+  warn "no music: #{e.message}"
+  nil
+end
+```
+
+The engine checks the **content, not the extension**. It refuses a text file
+named `.ogg`.
+
+## Volume
+
+Every volume behaves the same way, whether the device's, a sample's or a song's:
+
+| Value | Effect |
+|---|---|
+| `1.0` | unchanged, the default |
+| `0.0` … `1.0` | quieter |
+| above `1.0` | amplified; clipping is yours to avoid |
+| below `0.0` | clamped to `0.0` |
+
+**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*.
+
+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 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` returns how many samples and songs exist.
+It serves tests, not gameplay.
+
+## Testing
+
+**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.
+
+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
+audio.sample('hit.ogg').play
+
+expect(audio.played?('hit.ogg')).to be(true)
+expect(audio.calls.map(&:name)).to eq(%i[sample sample_play])
+```
+
+That spec loads no file, opens no device and needs no sound card.
+
+## What is not here
+
+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.