rgame 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6d5bcc5fc00641f0ff886974c919bdebc2c9ae3260d4333740243a4ff118ed55
-  data.tar.gz: 42d88501d55f42b2ecc2a037d080e74d2f1420bf46ad1aa965cc1cc069288d7e
+  metadata.gz: e7eb60de3d59e1a7c55ad4261e68be3a9cdb1d8f478e56354eb655c2452fbc4d
+  data.tar.gz: 73f0f53dec4c19b34bd32a80cfa86ac2c8068a80debbd32bc234c1dca4cbd0b5
 SHA512:
-  metadata.gz: d119e1dfe2b47bbc9444633a95cc8b3d4d4c4a1c2ae94329993e107df68f5f63421581c4bee023bf7ebaeca736410fbcca7c2366d8ba5fbdbc338421a11b545e
-  data.tar.gz: de260cc2b6a2c8ebf01db793da132d11a1bf5fa973426e4b846b22cdab369f7674f5045b48231b0a823961c5a36a220d3a09db67a601fc60998a44878f856872
+  metadata.gz: f71a457f48b0f45206b03c68e8dfc8f222c9c2a87957ac2c44edd0f2330dc3412d82874544176379143a5ccf7e24596665253e1a75983d475fd8273a500bcdbe
+  data.tar.gz: f3c7ac9d5663a9e0f0df3823be78c7cf7496176982e86933e5ad8c19293ade3c21320828127e4a31086f21b44a75096cde3b9b6a4695a51180517ba9f700313b

data/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+this project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html) —
+which before 1.0 means the public API can still change in a minor release.
+
+Entries describe what changed for someone *using* the engine. The reasoning
+behind a change belongs in the documentation it lands with; this file is the
+index, not the argument.
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-26
+
+### Added
+
+- **Split-screen.** A game has seats (`RGame::Game.new(players: 2)`), and a
+  `RGame::Engine::Player` owns a device, a binding table, a camera and a region
+  of the screen. The shared world is updated once and drawn once per viewport by
+  a `WorldView`. Which player a node answers to is inherited down the tree like
+  its transform, so `ship.input_owner = players[1]` moves a whole subtree.
+  New: `Player`, `Players`, `Viewports`, `View`, `WorldView`, `Layout`.
+- **`RGame::Engine::InputMap`** — one binding table per player, written in terms
+  of physical ids from `RGame::Util::Controls`, so a game names keys and pad
+  buttons in one place and reads named actions everywhere else.
+- **Draw bands** (`RGame::Util::Z`): `:world`, `:hud`, `:overlay` and `:debug`.
+  A band beats every `z` in the tree, so nothing in the world can draw over the
+  HUD. Inherited down the tree, and set by the nodes that exist to mark one.
+- **Culling** (`RGame::Engine::Culling`, `view.visible?`), which stops being an
+  optimisation once the world is drawn once per player.
+- **A bare-bones UI package**: `PlayerLayer` gives a player their own screen, and
+  `UI::Menu` / `UI::MenuItem` navigate it by focus and activation — enough for
+  keyboard and controller menus. Layout, nesting, scrolling and text entry are
+  not in it; see [docs/api/ui.md](docs/api/ui.md).
+- **Pausing** (`Node2D#paused`), which stops `control` and `update` for a node
+  and its whole subtree while it keeps drawing — a frozen world under a cutscene
+  overlay that goes on animating.
+- `Components::CameraFollow`, and `TileMapLayer` as a node of its own.
+- **`tools/drive_example.rb`** — boots an example unmodified, feeds it a
+  scripted input backend and reports what the game actually asked for: draws,
+  clips, sounds, scenes, ticks against frames.
+- **macOS and Windows support**, and CI that runs every verification tier on
+  all three platforms.
+- This changelog, linked from the gem's RubyGems page through `changelog_uri`.
+
+### Changed
+
+- `Node2D#draw` and `on_draw` take the viewport being drawn into:
+  `on_draw(renderer, view)`. Most nodes ignore it; laying out against the edges
+  of a player's region, and culling, need it.
+- `z` orders a node among its **siblings** only. It is never added to anything
+  and never reaches the renderer, so a node's whole subtree draws before or
+  after a sibling's, never interleaved with it. This replaces the additive
+  `abs_z = parent.abs_z + z`, under which a node at z 2 with a child at z 5
+  resolved to 7 and overtook a sibling at 4.
+- `F2` quits and `F1` toggles the debug overlay. `Esc` is deliberately left to
+  the game, because it is the button a player expects to back out of a menu.
+- Reading an action no `InputMap` declares raises `KeyError` instead of reading
+  as "never pressed" forever.
+
+### Removed
+
+- `RGame::Engine::CameraView`. A camera belongs to a `Player` and is applied by
+  the `View` being drawn.
+
+## [0.1.0] - 2026-08-20
+
+First release, and the first version that runs a game end to end.
+
+### Added
+
+- **The C engine**, as two Ruby extensions built from one source tree: an SDL2
+  window and a fixed-timestep main loop, keyboard and gamepad input with
+  hot-plug, a z-sorted batching renderer with transforms, clipping and baked
+  recordings, text from a shipped TrueType font, and audio (samples and
+  streamed Ogg Vorbis or WAV).
+- **`RGame::Core`** — the half that owns the window, the GPU and the sound
+  device: `App`, `Input`, `Gamepad`, `Image`, `Renderer`, `Recording`, `Font`,
+  `Audio`, plus the asset layer (`AssetManager`, `SpriteSheet`, `NineSlice`,
+  `UIAtlas`, `TileMapRenderer`).
+- **`RGame::Util`** — the graphics-free half, so values can be required with no
+  SDL and no OpenGL in the process: `Tensor`, `Color`, `Controls`.
+- **`RGame::Engine`** — the scene graph a game is written in: nodes,
+  components, signals, sprites, tile maps, collision and pathfinding. Pure
+  Ruby, and unable to name `RGame::Core` at all, which is what lets game logic
+  and its specs run with no display.
+- **`RGame::Game`** — the entry point that wires the two halves together.
+- Examples: `14_asteroids`, `15_tiled_world`, `16_hello_world`.
+
+[Unreleased]: https://github.com/psuessenb/rgame/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/psuessenb/rgame/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/psuessenb/rgame/releases/tag/v0.1.0

data/README.md

@@ -1,6 +1,10 @@
 # RGame
 
-A small 2D game engine written in Ruby and C, on top of SDL2, OpenGL and miniaudio.
+RGame is a small 2D game engine for Ruby, written in Ruby and C. It's build on top of SDL2, OpenGL and miniaudio. It's built with testability and performance in mind, and aims to be an engine where you can write your whole game code in Ruby, test it as usual with RSpec (or Minitest, or another test framework) and still have acceptable performance.
+
+While still a work in progress, RGame aims to be more than a SDL/OpenGL
+binding - it ships with high level features like a scene graph, sprites,
+collision systems, debugging tools and an UI toolkit.
 
 ## Why does this exist and should you use it?
 
@@ -37,47 +41,10 @@ game.start
 
 You can learn more about how it works in the [documentation](docs/api/README.md).
 
-# Where does stuff live
-
-Everything Ruby-visible lives under the `RGame` module, split in two by what it
-depends on:
-
-| | `RGame::Core` | `RGame::Util` |
-|---|---|---|
-| For | anything depending on SDL/OpenGL (or on something that does) | everything else |
-| C source | `ext/rgame_core/` | `ext/rgame_util/` |
-| Extension | `rgame/core_ext` | `rgame/util_ext` |
-| Links | SDL2 + OpenGL + pthread | nothing but Ruby |
-| Holds today | `App` — window, GL context, fixed-timestep main loop; `Input`, `Gamepad`, `Image`, `Renderer`, `Recording`, `Font`, `Audio`, `Sample`, `Song` | `Tensor`, `Controls`, `Color` |
-
-That split is load-bearing, not cosmetic: `require "rgame"` gives you the value
-types *and* the scene graph with **no graphics libraries loaded into the process
-at all**, so game logic and its specs run with no display and no SDL present.
-`RGame::Core` is an explicit opt-in:
-
-```ruby
-require "rgame"       # RGame::Util + RGame::Engine, no graphics
-require "rgame/core"  # adds RGame::Core, pulls in SDL2 + OpenGL
-require "rgame/game"  # all of it, wired — what a game writes
-```
-
-The engine opens a window, runs a fixed-timestep loop, reads keyboard and
-controllers, loads PNGs onto the GPU, draws shapes, sprites and text through
-a z-sorted batching renderer, and plays Ogg Vorbis and WAV. `RGame::Game` puts
-those together with a scene graph, and the two games under `examples/` run on
-it. Its C sources build two ways from one copy: a standalone binary (`build/rgame`, via the root
-`Makefile`) and the `core_ext` extension (via `extconf.rb`).
-
-Both halves ship as one gem — `rgame.gemspec` builds both extensions — though
-nothing is published yet, so it is installed from a checkout or a built `.gem`.
-
-**[docs/api/](docs/api/README.md) is the reference documentation** for using the
-engine from Ruby: the entry point, the frame loop, input, drawing, text, audio,
-assets and the value types. Start there if you want to write a game rather than
-work on the engine.
-
 ## Requirements
 
+At the moment this gem ships only source-code and no precompiled binaries, which unfortunately means you need to compile a bunch of C code on your locale machine.
+
 ### C engine
 
 - A C compiler — `gcc` or `clang`
@@ -112,19 +79,76 @@ fixture and needs `libvorbisenc` to run.
 Nothing else — the engine has no runtime Ruby dependencies, and the `Gemfile`
 holds only development gems.
 
+All three platforms below are built and tested on every push by
+[CI](.github/workflows/ci.yml).
+
 ### Debian / Ubuntu
 
 ```
 sudo apt install build-essential pkg-config libsdl2-dev libgl1-mesa-dev check
 ```
 
+`rake spec:core` opens real windows and starts its own Xvfb, which needs a few
+more packages — the display itself, the `xwininfo` it polls to know the display
+is up, a software rasteriser (Xvfb has no GPU, and `SDL_GL_CreateContext` fails
+without one) and the XTEST runtime for synthetic keystrokes:
+
+```
+sudo apt install xvfb x11-utils libgl1-mesa-dri libxtst6
+```
+
 ### macOS (Homebrew)
 
 ```
 brew install sdl2 pkg-config check
 ```
 
-OpenGL headers/libs ship with Xcode Command Line Tools (`xcode-select --install`).
+OpenGL ships with the Xcode Command Line Tools (`xcode-select --install`) — the
+full Xcode is not needed, and neither is anything else: `rake spec:core` uses
+the native window server, so there is no Xvfb equivalent to set up. Note
+Homebrew's `sdl2` formula now installs **sdl2-compat**, which is SDL2's API
+implemented on top of SDL3; the engine works through it unchanged.
+
+### Windows
+
+Use a **RubyInstaller-built** Ruby (mise, vfox and rbenv-style managers all
+fetch those), which is what supplies `ridk`. The combined DevKit installer is
+not required — a standalone MSYS2 that `ridk` can find works just as well, and
+`C:\msys64` is one of the places it looks:
+
+```
+winget install --id MSYS2.MSYS2 -e
+ridk exec pacman -Syu --noconfirm      # core update; may need a second pass
+```
+
+Then the libraries. Note `make` is an **msys** package with no prefix while
+everything else is **ucrt64**-prefixed — that split is the whole Windows story:
+
+```
+ridk exec pacman -S --needed \
+  mingw-w64-ucrt-x86_64-SDL2 \
+  mingw-w64-ucrt-x86_64-check \
+  mingw-w64-ucrt-x86_64-pkgconf \
+  mingw-w64-ucrt-x86_64-gcc \
+  make
+```
+
+**MSYS2 is several environments in one install, and picking the wrong one fails
+in a way that looks like missing packages.** UCRT64 builds native Windows
+binaries, which is what RubyInstaller's Ruby can load; the plain `msys`
+environment builds against a Cygwin-like runtime, which it cannot. Work from
+the "MSYS2 UCRT64" shell or run `ridk enable ucrt64` first, and verify before
+trusting anything:
+
+```
+which gcc                   # must be /ucrt64/bin/gcc, NOT /usr/bin/gcc
+pkg-config --cflags sdl2    # must print a ucrt64 include path
+```
+
+One more Windows fact worth knowing up front: **Check has no usable fork
+there**, so the first segfault kills the whole test binary and the output stops
+mid-suite. Use a debugger rather than reading the log — `CK_FORK=no gdb --args
+./build/test_rgame`, and `CK_RUN_SUITE=<name>` to run one suite.
 
 ## Build & run
 
@@ -184,11 +208,18 @@ ruby ext/rgame_core/example.rb
 
 ## Packaging
 
-Both extensions and the Ruby layer ship as one gem, built from `rgame.gemspec`:
+Both extensions and the Ruby layer ship as one gem, built from `rgame.gemspec`
+and published at [rubygems.org/gems/rgame](https://rubygems.org/gems/rgame):
+
+```
+gem install rgame               # from RubyGems; compiles both extensions here
+```
+
+Or from a checkout, which is the same gem built locally:
 
 ```
 rake build                      # package into pkg/rgame-<version>.gem
-gem install pkg/rgame-0.1.0.gem # compiles both extensions on this machine
+gem install pkg/rgame-*.gem     # compiles both extensions on this machine
 ```
 
 `gem install` runs each `extconf.rb` and installs the resulting `.so` into the
@@ -207,200 +238,66 @@ that no build artifact, spec directory or plan is, so the parts of this that
 would otherwise be a checklist fail the suite instead.
 
 The version is `RGame::VERSION` in [lib/rgame/version.rb](lib/rgame/version.rb).
-Nothing is published to RubyGems.
 
 ## Project structure
 
-The engine C lives under `ext/rgame_core/` — a Ruby C extension directory —
-rather than a top-level `src/`. That's deliberate: `gem install` unpacks the gem
-and runs each `extconf.rb`, which can only build sources inside its own
-directory, so keeping the C there means one copy of the code serves both the
-standalone binary and the gem.
-
-```
-ext/rgame_core/              RGame::Core — the SDL/GL half. The sources are
-                             grouped by subsystem, one folder each, and a file
-                             names the folder it includes from: graphics/canvas.c
-                             says #include "graphics/clip.h".
-  include/rgame/core.h       Public C API (opaque handle, no SDL/GL types
-                             leaked) — what both src/main.c and the extension
-                             bind against.
-  app/                       The window, the context and the loop.
-    app.c                    Engine implementation: SDL window + OpenGL context
-                             setup; owns the main loop and calls back to the
-                             caller's update/draw callbacks.
-    app_gl.h                 Private: the GL context behind the opaque handle.
-    frame_loop.h/.c          Pure fixed-timestep + FPS logic, no SDL/GL — unit-
-                             tested without a window (see CLAUDE.md's layering).
-  graphics/                  Everything on the drawing path.
-    transform.h/.c           Pure 2D affine transform stack — rotate, scale,
-                             translate, composed. No SDL.
-    clip.h/.c                Pure rects and the intersecting clip stack, in
-                             screen space. No SDL.
-    draw_queue.h/.c          Pure z-sort and batching: collects draw commands,
-                             orders them by z, merges what can share a GL call.
-    canvas.h/.c              Pure composition of transform + clip + queue; the
-                             seam the drawing API is written against.
-    backend.h/.c             The layer-2 seam: a function-pointer table a real
-                             GL backend or a recording fake plugs into, plus
-                             the loop that drives it from a prepared frame.
-    texture.h/.c             Pure: refcounted texture sheets, the sub-rects
-                             sprites cut out of them, and pixels -> UVs.
-    primitives.h/.c          Pure: rects, thick lines, circles and sprites, in
-                             terms of the canvas's triangles and quads.
-    recording.h/.c           Pure: a baked block of drawing, kept between
-                             frames and replayed as one call per texture.
-    gl_backend.h/.c          The real GL calls — the only file that issues
-                             them on the drawing path.
-    image.c                  Decode a PNG and upload it — the thin GL shim
-                             over texture.h. Views share one upload.
-    image_internal.h         What the draw path needs from inside an image.
-  text/                      Glyphs, from a .ttf to a texture page.
-    atlas.h/.c               Pure: shelf packing for the glyph atlas — where
-                             the next glyph goes on a texture page.
-    glyph_cache.h/.c         Pure: codepoint -> rasterised glyph, open
-                             addressed, never evicted.
-    font.h/.c                Pure: a typeface at one size — glyph metrics,
-                             kerning, rasterisation and UTF-8, over
-                             stb_truetype. No atlas, no GL.
-    font_atlas.c             Composes font + atlas + glyph cache and owns the
-                             GL pages — the only text file that calls gl*.
-    font_internal.h          What the draw path needs from inside a font.
-  input/                     Keyboard and controllers.
-    input.h/.c               Pure input snapshot + the flat button-id space
-                             (keyboard and gamepad ranges). No SDL.
-    device_slots.h/.c        Pure player-slot table for controllers: keeps a
-                             player on the same slot across a disconnect. No SDL.
-    gamepad.h/.c             Thin SDL_GameController shim: opens/closes pads on
-                             hot-plug and copies their state into the snapshot.
-  audio/                     Sound, which touches neither SDL nor GL.
-    audio.c                  The sound device, samples and songs — miniaudio
-                             talks to the platform directly.
-    audio_internal.h         The live-sound counter, for tests.
-    vorbis_decoder.h/.c      Ogg Vorbis for miniaudio, over stb_vorbis —
-                             miniaudio cannot read ogg on its own.
-  ruby/                      The Ruby-facing glue, and the only C here that
-                             includes ruby.h.
-    core_ext.c               VALUE wrappers + callback trampolines, and the
-                             extension's entry point.
-    core_ext.h               One init function per Ruby-visible class here.
-    image_ext.c              RGame::Core::Image — the Ruby binding.
-    audio_ext.c              RGame::Core::Audio, Sample and Song — the
-                             bindings; three classes in one file because they
-                             share a wrapping shape.
-    renderer_ext.c           RGame::Core::Renderer — the drawing primitives.
-    font_ext.c               RGame::Core::Font — the Ruby binding.
-    recording_ext.c          RGame::Core::Recording — baked, replayable draws.
-  vendor/                    Third-party sources + their licences.
-    <name>_impl.c            One per vendored library (stb_image, stb_truetype,
-                             stb_vorbis, miniaudio): instantiates it and picks
-                             its features. The only files built without
-                             -Wall -Wextra; the suffix is what selects that.
-  extconf.rb                 mkmf script; pkg_config("sdl2"), -lGL. It lists
-                             the subsystem folders, because mkmf's own default
-                             only finds sources one level up from here.
-  example.rb                 Manual smoke test driven from Ruby.
-
-ext/rgame_util/              RGame::Util — the graphics-free half, so pure-data
-                             helpers can be required without pulling in SDL/GL.
-  util_ext.c                 Entry point; hands RGame::Util to each class init.
-  tensor.c                   RGame::Util::Tensor — flat-array 3D grid.
-  color.c/.h                 Pure RGBA packing, no Ruby — Check-tested.
-  color_ext.c                RGame::Util::Color — the Ruby binding over it.
-  extconf.rb                 mkmf script; no pkg_config, no -lGL.
-
-lib/rgame.rb                 `require "rgame"` — loads RGame::Util only.
-lib/rgame/version.rb         RGame::VERSION, and nothing else — the gemspec
-                             loads this file before anything is compiled.
-lib/rgame/util.rb            Namespace loader.
-lib/rgame/util/tensor.rb     Requires the compiled rgame/util_ext.
-lib/rgame/util/controls.rb   Input id vocabulary (keys, pad buttons, axes,
-                             device slots) + default bindings. Pure Ruby
-                             values, so a game may name them without Core.
-lib/rgame/util/color.rb      Requires the compiled rgame/util_ext for Color.
-lib/rgame/core.rb            `require "rgame/core"` — opt-in, loads SDL/GL.
-lib/rgame/core/app.rb        Requires the compiled rgame/core_ext.
-lib/rgame/core/input.rb      Symbolic action -> button, over the C queries.
-lib/rgame/core/gamepad.rb    Which controllers are plugged in, and their names.
-lib/rgame/core/image.rb      Sprite-sheet slicing over the C-backed Image.
-lib/rgame/core/renderer.rb   Keyword args, colours and transform blocks over
-                             the C-backed Renderer.
-lib/rgame/core/recording.rb  #draw over the C-backed Recording.
-lib/rgame/core/font.rb       The default font path, over the C-backed Font.
-lib/rgame/fonts/             The default font shipped with the engine:
-                             Liberation Sans 2.1.5 (SIL OFL 1.1). Data read at
-                             runtime, so it lives here rather than in ext/.
-lib/rgame/*.so               Build artifacts, copied here by `make ext`.
-
-src/main.c                   Standalone executable entry point — the C
-                             equivalent of example.rb. Only talks to
-                             rgame/core.h, never touches SDL/GL directly. Kept
-                             outside ext/ so mkmf doesn't compile its main()
-                             into the extension.
-
-test/                        Check unit tests for the pure C logic (`make test`).
-  test_main.c                Runs every suite; one binary, build/test_rgame.
-  suites.h                   Each test_<x>.c exposes a Suite, declared here.
-  support/                   Test-only helpers, e.g. the recording draw backend
-                             that stands in for OpenGL.
-spec/                        Headless RSpec specs: RGame::Util and
-                             RGame::Engine (`rake spec`). Never loads SDL.
-  packaging_spec.rb          What the gem ships, asserted against the tree so a
-                             new source or data file cannot be left out of it.
-spec_core/                   RSpec specs for RGame::Core (`rake spec:core`).
-                             Opens real windows; boots its own Xvfb.
-docs/                        The feature spec the engine is being built out to.
-  api/                       Reference documentation for using it from Ruby.
-
-rgame.gemspec                Packages both halves as one gem: both extconf.rb
-                             files, and a globbed file list so a new source or
-                             asset ships without being listed anywhere.
-```
+The C lives under `ext/rgame_core/` rather than a top-level `src/`, because
+`gem install` runs each `extconf.rb` and an extension can only build sources
+inside its own directory — so one copy of the code serves both the standalone
+binary and the gem. The Ruby half is split the same way it is namespaced:
+`lib/rgame/util/`, `lib/rgame/core/` and `lib/rgame/engine/`.
 
-Three test suites: `make test` covers the C (Check), `rake spec` the headless
-Ruby half, `rake spec:core` the parts that open a window. None needs a display
-of its own — `spec:core` boots Xvfb itself. `rake` runs all three.
+A file-by-file map of the whole repository is in
+[docs/project_structure.md](docs/project_structure.md).
 
 ## Roadmap
 
-1. **C core** (in progress) — SDL2 window, OpenGL rendering, basic app loop.
-   Drawing primitives are the current gap.
-2. **Ruby C extensions** (done in first form) — `RGame::Core::App` wraps
-   `include/rgame/core.h`, so the engine can be driven from Ruby
-   (`ext/rgame_core/example.rb`); `RGame::Util::Tensor` covers the
-   graphics-free half.
-3. **Pure-Ruby half** (started) — `lib/` holds the namespace loaders; so far
-   the classes underneath them are all C-backed.
-4. **Gem** (done) — `rgame.gemspec` packages both halves, building each
-   extension into `lib/rgame/` on install the way `make ext` does in a
-   checkout. Not published to RubyGems.
-
-## Ruby API
-
-See [ext/README.md](ext/README.md) for detail.
-
-```ruby
-require "rgame/core"
-
-class MyGame < RGame::Core::App
-  def initialize = super(width: 800, height: 600, caption: "title")
-
-  def update(dt); end      # one fixed simulation tick
-  def draw; end            # render one frame
-  def needs_redraw?; end   # false skips the draw
-  def button_down(id); end # discrete key press
-end
-
-MyGame.new.run
-```
-
-The util half, with no graphics libraries loaded:
-
-```ruby
-require "rgame"
-
-grid = RGame::Util::Tensor.new(width, height, depth, initial: nil)
-grid[x, y, z] = value
-grid[x, y, z]
-grid.width # => Integer, also #height / #depth
-```
+All three layers exist and the engine is usable end to end: the games under
+[examples/](examples/) are written against exactly what is documented.
+
+**Done**
+
+1. **C engine** — an SDL2 window and a fixed-timestep loop, keyboard and
+   gamepad input with hot-plug, a z-sorted batching renderer with transforms,
+   clipping and baked recordings, text from a shipped TrueType font, and audio.
+   Linux, macOS and Windows are all supported and all gated by CI.
+2. **Ruby C extensions** — both halves. `RGame::Core` binds
+   `include/rgame/core.h` (the app, the renderer, images, fonts, recordings,
+   sound); `RGame::Util` is the graphics-free one, so values can be required
+   without pulling SDL and OpenGL into the process.
+3. **Pure-Ruby half** — `RGame::Engine`, the layer a game is actually written
+   in: the scene graph, components, signals, tile maps, collision,
+   pathfinding, and split-screen players with a camera and a binding table
+   each. `RGame::Game` wires it to `RGame::Core` and is the only class allowed
+   to name both.
+4. **Gem** — `rgame.gemspec` packages both halves, compiling each extension
+   into `lib/rgame/` on install the way `make ext` does in a checkout.
+   [Published to RubyGems](https://rubygems.org/gems/rgame), so
+   `gem install rgame` works.
+
+**Next**
+
+- **A UI package worth the name.** What exists covers a region per player,
+  focus and activation — enough for keyboard-and-controller menus. Layout,
+  nesting, scrolling lists and text entry are all still open; see
+  ["What this is not"](docs/api/ui.md#what-this-is-not).
+- **Precompiled binary gems**, so installing needs no compiler. The compiling
+  is the easy part — CI already does it on three platforms — and the real
+  blocker is that the binary still needs SDL2 at runtime. The options are
+  written up in
+  [docs/plans/precompiled-binary-gems.md](docs/plans/precompiled-binary-gems.md).
+- **Hot paths into C, where profiling says so** — the nine-slice tiling loops
+  and the animated-tile draw loop are the candidates. Deliberately last: each
+  is a straightforward move once the geometry is separable, and doing it early
+  would trade readability for a speedup nobody has measured.
+
+Also known and deliberately deferred: the drawing path uses legacy
+compatibility-profile OpenGL (`glBegin`/`glEnd`), which needs no loader library.
+Moving to core-profile GL is a decision to take on purpose, not a drive-by
+change.
+
+## AI clause
+
+This project is not vibe-coded, but AI tools were used heavily while
+writing code. If you dislike AI generated code, this project is not for
+you.