rgame 0.4.0-arm64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0e9a8df4b92f3e3a10ea64720724a76e4c896a2010c691149940ca36da734df3
+  data.tar.gz: aa2caa71ceba2a1ba39e5c9d043fd423059b624a1da24e5fed7244fc43dfd40b
+SHA512:
+  metadata.gz: 19de7a76ea8ec3a39ce6cb8031e679c95a133236fcc101a0a83d4dee4469afcef740e811a46a909906a247ccdc8944fd4506c48970055efc86e036051d4b6d48
+  data.tar.gz: ba2b069e3e47c5256de8d896e0f6849751d5c5524444454d7694195bc6760582a7b35b4e8e0c030b83b6205d4ca4eda61edb968a3787afedf203a4606e2337f5

data/CHANGELOG.md

@@ -0,0 +1,251 @@
+# 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.4.0] - 2026-09-16
+
+### Added
+
+- **`gem install rgame` needs no compiler and no SDL2 on a common desktop.**
+  Apple Silicon Macs, x86-64 Linux and 64-bit Windows get a gem whose two
+  extensions are already built, with SDL2 linked into them. Every other machine,
+  and every Ruby but 4.0, installs the source gem and compiles it as before.
+- **A virtual gamepad for tests.** `RGame::Core::VirtualGamepad.new` plugs a
+  synthetic controller into a running `App`, which seats it and reads it like a
+  real pad; `set_button`, `set_axis` and `detach` drive it. See
+  [docs/api/input.md](docs/api/input.md#rgamecorevirtualgamepad).
+
+## [0.3.1] - 2026-09-15
+
+### Fixed
+
+- `require "rgame"` failed under Bundler with `cannot load such file --
+  rexml/document`. The gem now declares `rexml` as a dependency, which Ruby 4.0
+  no longer loads without one.
+
+## [0.3.0] - 2026-09-15
+
+### Added
+
+- **`rgame new NAME`.** The gem installs an `rgame` command, and `rgame new`
+  generates a project: a game class, a root node, an English translation table,
+  and a spec suite and RuboCop config that pass. Only `game.rb` loads SDL, so the
+  generated specs run without a display. See [docs/api/cli.md](docs/api/cli.md).
+- **RuboCop cops for games.** The gem ships rgame's `Game/` cops as a RuboCop
+  plugin, and `rgame new` enables them. They catch per-frame allocations, a node
+  drawn at its own position twice, literal text and Core named from headless
+  code. See [docs/api/cli.md](docs/api/cli.md#the-generated-rubocop-configuration).
+- **Translation by default.** `RGame::Game` loads every `locales/**/*.yml` and
+  picks the player's language from `RGame::Core.preferred_locales`. A node draws
+  an `Engine::Text` built from a key, and a UI button's `label:` is a key. See
+  [docs/api/localization.md](docs/api/localization.md).
+- **Fullscreen and scaling.** `Game.new` takes `fullscreen:` and `scale_mode:`,
+  and both can change while the game runs. `scale_mode:` maps the logical size
+  onto the window, and defaults to `:letterbox`. See
+  [docs/api/game.md](docs/api/game.md).
+- **Saving.** `Util::SaveFile` reads and writes a game's state in the player's
+  save directory. `Components::Identity` gives a node a stable id to save it
+  under. See [docs/api/values.md](docs/api/values.md).
+- **Box colliders.** `Components::BoxCollider` is a rectangle in the same
+  `CollisionWorld` as `CircleCollider`. `FeetCollider` derives its box from the
+  node's size, so a top-down character collides at its feet. See
+  [docs/api/components.md](docs/api/components.md).
+- **Movers that something can stop.** `CharacterBody`, `Velocity` and
+  `PathFollow` share the base `Components::Mover`. Its `blocked_by:` lists what
+  stops a step: solid tiles, the world's edge or collider layers. `on_blocked` and
+  `on_unblocked` report the blocker and the axis. See
+  [docs/api/components.md](docs/api/components.md).
+- **Pathfinding.** `Engine::NavGrid` finds routes over a tile grid, and
+  `TileWorld#nav_grid` hands one out. `Components::Navigator#go_to` walks a node
+  there. The search runs in C, in `Util::SolidGrid`, `Util::RouteSearch` and
+  `Util::TileSweep`. See [docs/api/toolbox.md](docs/api/toolbox.md).
+- **`Components::World`** gives a scene its bounds without a tile map.
+  `ScreenWrap` and `DespawnOffscreen` read the bounds from it or from
+  `TileWorld`. See [docs/api/components.md](docs/api/components.md).
+- **`Components::Hop`** lifts a character's picture off the ground through the
+  new `Node2D#elevation`. Colliders and cameras ignore the lift. See
+  [docs/api/components.md](docs/api/components.md).
+- **New buttons and styles.** `UI::Button` is the base for a button with its
+  own look. `TextButton`, `PanelButton`, `OptionButton` and `IconButton` draw
+  their background from a `NineSliceStyle` or a `ShapeStyle`. A `hotkey:` presses
+  a button without focusing it. See [docs/api/ui.md](docs/api/ui.md).
+- **Menu layouts and navigations.** `UI::Menu` takes a `layout:` (`Column`,
+  `Row` or `Ring`) and a `navigation:` (`Stepping`, `Pointing` or `nil`).
+  `UI::RadialMenu` focuses whatever the stick points at. `UI::PanelMenu` draws a
+  panel that grows with its buttons. See [docs/api/ui.md](docs/api/ui.md).
+- **Menus open and close.** A menu answers `open?`, `open` and `close`, and
+  emits `on_opened` and `on_closed`. A closed menu draws nothing and takes no
+  input. `trigger:` names an action that holds a menu open while it is down. See
+  [docs/api/ui.md](docs/api/ui.md).
+- **A UI atlas can name images.** A descriptor's `images` section cuts
+  rectangles from the sheet, and `Renderer#register_ui_atlas` registers each by
+  name. `UI::IconButton.new(image: :home)` then draws one.
+- **Input prompts.** `InputMap#button_for(action, device)` returns the bound
+  button that device can press. `Controls.gamepad?` and `Controls.pad_button?`
+  tell the two kinds of id apart. See [docs/api/input.md](docs/api/input.md).
+- **Sounds by path.** `audio.play_sound` and `play_music` accept a path and
+  load it through the asset manager on first use. `RGame::Game` subscribes an
+  `AudioDirector`, so `AudioBus` sounds play without setup. See
+  [docs/api/audio.md](docs/api/audio.md).
+- **24 examples, one concept each.** Each is a single `main.rb` that runs on its
+  own, from `walk` and `sprite` to `pathfinding` and `localization`. See
+  [docs/api/examples.md](docs/api/examples.md).
+- `AssetManager#glob` lists the files under the media root that match a pattern.
+- `Util::Color` gains named colours, from `RED` to `DARK_GRAY`.
+
+### Changed
+
+- **A subclass may not redefine `Node2D`'s or `Component`'s internal methods.**
+  Their private and protected machinery now starts with `_`. A subclass that
+  defines one of those names raises `NameError` where the class is defined.
+  Before, it silently switched that machinery off. See
+  [docs/api/scene_graph.md](docs/api/scene_graph.md).
+- **Nodes draw in local space.** `Node2D#draw` pushes the node's transform
+  before it calls `on_draw`, so a node draws at its own origin:
+  `renderer.rect(0, 0, width, height)`. Drop `abs_x`/`abs_y` from draw calls, or
+  the position applies twice. See
+  [docs/api/scene_graph.md](docs/api/scene_graph.md).
+- **`abs_x`, `abs_y` and `abs_angle` are now `world_x`, `world_y` and
+  `world_angle`.** A node computes them when read, so they are never a tick
+  stale. `world_x=` and `world_y=` place a node in world space. See
+  [docs/api/scene_graph.md](docs/api/scene_graph.md).
+- **`UI::Menu` is handed its buttons.** `Menu#add(button)` replaces `add_item`,
+  `items` is now `buttons`, and `MenuItem` is now `UI::PanelButton`. The item
+  size moves to `layout: UI::Column.new(...)`. Confirm activates a button when
+  released. See [docs/api/ui.md](docs/api/ui.md).
+- **`CharacterBody` takes its shape from a sibling collider.**
+  `CharacterBody.new(speed:, blocked_by:)` replaces `feet_width:` and
+  `feet_height:`. A body with no `blocked_by:` moves freely, and `TileWorld#move`
+  is gone. See [docs/api/components.md](docs/api/components.md).
+- **Contacts are edges.** `on_hit` fires once when two colliders start to
+  overlap, and the new `on_separated` fires once when they part. Before,
+  `on_hit` fired on every step of an overlap.
+- **`I18n` reads YAML tables keyed by locale.** A key falls back from `de-AT`
+  to `de` to the default. Plurals follow CLDR rules, and `I18n.missing` decides
+  what a missing key shows. `load_file` is gone. See
+  [docs/api/localization.md](docs/api/localization.md).
+- **`ScreenWrap` and `DespawnOffscreen` work in world space**, so a node under an
+  offset parent wraps at the world's edge. Their `width:` and `height:` are now
+  optional. A node with two responses to the edge raises when the second
+  attaches.
+- **A component raises when its sibling is missing.** `PlayerController`,
+  `WanderController` and `AnimatedSprite` name what they need when they attach.
+  A node with two movers raises too.
+- **`AnimatedSprite` follows any mover**, and faces along the larger axis of
+  its heading.
+- **Engine internals are private.** `Renderer`'s raw `draw_*`, `push_*`, `pop`
+  and `*_record` methods, `Recording#draw_at` and `Song#play_looping` are
+  private. Call `rect`, `translated`, `record`, `Recording#draw` and `Song#play`
+  instead. The Tiled parse helpers are private too.
+
+### Removed
+
+- `Engine::CachedLabel`. Use `Engine::Text`.
+- `Engine::Body`, `Engine::Actor`, `Engine::Matrix`, `Engine::Resettable` and
+  `Engine::PlayerController`. None had a caller in the engine.
+  `Components::PlayerController` stays.
+- `Engine::TileCollision`, which is now `Engine::TileBlockers`.
+- The examples `14_asteroids`, `15_tiled_world` and `16_hello_world`. They are
+  whole games rather than examples of one concept, and no longer ship.
+
+### Fixed
+
+- The README's hello-world gave `on_draw` one parameter; it takes two
+  (`renderer, view`).
+- A new `UI::Menu` drew its first item without a highlight until the first
+  press.
+- `Path#distance_to` returned wrong distances for Integer coordinates.
+
+## [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.4.0...HEAD
+[0.4.0]: https://github.com/psuessenb/rgame/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/psuessenb/rgame/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/psuessenb/rgame/compare/v0.2.0...v0.3.0
+[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/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2026 Paul Süßenbach
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This project vendors third-party source under ext/rgame_core/vendor/, which
+carries its own licence terms. See ext/rgame_core/vendor/README.md.

data/README.md

@@ -0,0 +1,325 @@
+# RGame
+
+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. You can check out the examples to get a feel for its capabilities.
+
+## Why does this exist and should you use it?
+
+RGame is the product of both my lazyness and me looking for something that did not exist. Coming from Ruby on Rails, I wanted to write games while not learning a new language. There are Ruby game engines, but none offered me the option to write modern, standard Ruby and proper specs for the game logic. The closest I found was Gosu, and this project initially started as a "high level engine on top of Gosu", but eventually the limitations of Gosu drove me into rewriting this layer myself.
+
+RGame puts a lot of emphazis on testing and being testable: It separates the layers that talk to SDL2/OpenGL from the high level engine concepts, so the whole game logic is testable headless.
+
+It also tries to marry the beauty of Ruby with the hard performance requirements of games: Hot paths have no per-frame allocation, because garbadge collection is what really slows down Ruby interpreation, and math-heavy use-cases are backed by C code instead of Ruby classes.
+
+Should you use it, though? If you're looking for something mature, free, and more battle-tested take a look at Godot instead. If you're looking for something mature and battle-tested _in Ruby land_, take a look at dragonruby instead (it's not free, but it's probably worth the price).
+
+If you're just starting with game development and planning on making the next big indie hit, might as well pick this one as the engine for the game you never finish!
+
+In all seriousness, though: This is a hobby project of mine, and while it might develop into something actually useful, at the time of writing it's a playground. If you search for something I searched and found nothing - try RGame! If you want to learn how to write games or just need a small prototype, and you really like Ruby - try RGame! If all you know is Rails, but you want to make a game that doesn't run in a browser and don't care about shipping it - try RGame!
+
+I would be really happy if someone else actually uses it, but at this point I can't really recommend it for anything else than small projects and/or learning the ropes of game development.
+
+## Getting started
+
+Installing the gem puts an `rgame` command on your PATH, which you can use to setup a project:
+
+```
+gem install rgame
+rgame new tictactoe
+
+cd tictactoe
+bundle install
+bundle exec rspec     # the game logic, headless — no window needed
+ruby main.rb          # the game itself
+```
+
+It's just a small skeleton — a game class, a root node, a spec and the usual configuration — but it is laid out the way the engine wants to be used: one file loads SDL, everything else stays graphics-free and therefore testable with no display. [The `rgame` command](docs/api/cli.md) explains the layout and the reasoning. This is also sets you up with a Rubocop configuration already geared towards RGame and game development in general.
+
+**On a common desktop that first line needs nothing else** — no compiler, no SDL2, no header files. `gem install rgame` fetches a gem whose two C extensions are already built, with SDL2 linked into them:
+
+- macOS 11 or later on Apple Silicon
+- x86-64 Linux with glibc 2.29 or later
+- 64-bit Windows, on a RubyInstaller Ruby
+
+All three need Ruby 4.0. Anywhere else — an Intel Mac, a Raspberry Pi, Ruby 4.1 — `gem install` falls back to the gem that ships the C and compiles it on your machine. That one needs [a compiler and SDL2](#building-from-source).
+
+## Hello world
+
+The simplest "game" you can write, all in one file:
+
+```ruby
+require 'rgame/game'
+
+class Scene < RGame::Engine::Node2D
+  def on_draw(renderer, _view)
+    renderer.text('Hello world!', 250, 200)
+  end
+end
+
+game = RGame::Game.new(
+  root: Scene.new,
+  caption: 'Hello world!'
+)
+
+game.start
+```
+
+You can learn more about how it works in the [documentation](docs/api/README.md).
+
+## Examples
+
+`examples/` holds one small program per concept, each a single file you can run with `ruby examples/<name>/main.rb`. [The examples page](docs/api/examples.md) describes them in more detail. They're also all full of code comments so you have an easier time learning the concepts.
+
+| Example | Shows |
+|---|---|
+| [walk](docs/api/examples.md#walk) | A player-controlled sprite — a node, three components, input as actions |
+| [sprite](docs/api/examples.md#sprite) | One frame drawn at a node, with no animation behind it |
+| [velocity](docs/api/examples.md#velocity) | Movement with nobody driving: a velocity, integrated |
+| [scroll_map](docs/api/examples.md#scroll_map) | A Tiled map larger than the window, scrolled by a camera |
+| [collision](docs/api/examples.md#collision) | Two shapes touching, and who gets told about it |
+| [collision_tiles](docs/api/examples.md#collision_tiles) | Walking into a wall of solid tiles, and sliding along it |
+| [jump_topdown](docs/api/examples.md#jump_topdown) | A hop in a top-down view, where the sprite rises and the feet stay on the ground |
+| [signals](docs/api/examples.md#signals) | A node announcing something happened, to nobody in particular |
+| [timer](docs/api/examples.md#timer) | Things that happen on a clock, with nothing pressed |
+| [pooling](docs/api/examples.md#pooling) | Spawning a lot of things without allocating them |
+| [game_menu](docs/api/examples.md#game_menu) | A menu over a world that keeps running |
+| [menu_navigation](docs/api/examples.md#menu_navigation) | Several screens, and settings that persist |
+| [radial_menu](docs/api/examples.md#radial_menu) | A wheel of icons, chosen by the direction of the stick |
+| [quick_wheel](docs/api/examples.md#quick_wheel) | A wheel held open by a button and chosen by letting go |
+| [skill_bar](docs/api/examples.md#skill_bar) | A row of tools, stepped through or fired by hotkeys |
+| [sound](docs/api/examples.md#sound) | A sound effect fired by a button, and the seam it travels |
+| [music](docs/api/examples.md#music) | A looping track, started and stopped |
+| [split_screen](docs/api/examples.md#split_screen) | Two players in one world, drawn once per viewport |
+| [input_glyphs](docs/api/examples.md#input_glyphs) | Prompts that match the device in your hands |
+| [fullscreen](docs/api/examples.md#fullscreen) | Fullscreen, switched at any time, and the scale modes |
+| [save_load](docs/api/examples.md#save_load) | Writing game state to disk and putting it back |
+| [save_load_ids](docs/api/examples.md#save_load_ids) | A save that has to name things, and why a reference forces ids |
+| [localization](docs/api/examples.md#localization) | The same screen in two languages, switched and remembered |
+| [pathfinding](docs/api/examples.md#pathfinding) | Setting a target for an actor and let if find its way there |
+
+## Building from source
+
+**This section is for two readers: anyone on a platform the binary gems miss, and anyone working on RGame itself.** Installing on one of the three platforms above needs none of it.
+
+Compiling the C engine needs a compiler and the system libraries it links against. A source install of the gem needs the compiler, `pkg-config`, SDL2 and OpenGL from the list below. The rest is for running rgame's own suites.
+
+### C engine
+
+- A C compiler — `gcc` or `clang`
+- `make`
+- `pkg-config`
+- SDL2 development headers (`sdl2` pkg-config package)
+- OpenGL development headers/libs (provided by Mesa on Linux)
+- [Check](https://libcheck.github.io/check/) (`check` pkg-config package) — C unit test framework, only needed for `make test`
+
+PNG decoding, text and audio need no system libraries: `stb_image.h`,
+`stb_truetype.h`, `stb_vorbis.c` and `miniaudio.h` are vendored in
+`ext/rgame_core/vendor/` (public domain / MIT), and the default font ships in
+`lib/rgame/fonts/` (SIL OFL 1.1). miniaudio finds ALSA or PulseAudio at runtime,
+so there is nothing to install for sound either. See the README in
+`ext/rgame_core/vendor/` for all of it.
+
+`tools/` holds development tools that are not part of the engine and are not
+built by `make` — currently one, which generates the audio suite's `.ogg`
+fixture and needs `libvorbisenc` to run.
+
+### Ruby side
+
+- **Ruby 4.0.5**, pinned in `.ruby-version`.
+- **Ruby development headers.** Version-manager builds (mise, rbenv, rvm, asdf) include them. On a distro-packaged Ruby, install `ruby-dev`
+  (Debian/Ubuntu). These are what `extconf.rb` compiles against.
+- **Bundler**, then `bundle install` for the dev/test gems (RSpec, RuboCop).
+
+Nothing else. The engine's one runtime gem is `rexml`, which Bundler installs with it, and the `Gemfile` holds only development gems.
+
+All three platforms below are built and tested on every push by
+[CI](.github/workflows/ci.yml) - with that people have usually at home, so Apple Silicon and not Apple Intel, etc.
+
+### 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 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
+
+```
+make              # builds build/rgame (standalone C binary)
+make run          # build and run it
+make test         # build and run the Check unit tests (C, pure logic)
+make ext          # build both Ruby extensions
+make ext-core     # build only ext/rgame_core -> lib/rgame/core_ext.so
+make ext-util     # build only ext/rgame_util -> lib/rgame/util_ext.so
+make clean        # remove build artifacts, including both extensions'
+```
+
+`make run` opens a window with one of each drawing primitive in it — a rotating
+square, a clipped rectangle, a circle, a thick line, a baked strip replayed
+every frame, and a line of accented text. `Esc` or closing the window quits.
+`ruby ext/rgame_core/example.rb` is the same scene driven from Ruby, and takes
+an optional sound file — `ruby ext/rgame_core/example.rb theme.ogg` binds Space
+to play it as a sample and Return to start and stop it as looping music. That is
+the only place a real sound device is driven; everything automated runs against
+a null or offline one.
+
+The Ruby specs:
+
+```
+bundle install
+make ext             # both extensions; the suites need the compiled .so files
+rake spec            # headless specs: RGame::Util, the engine layer, packaging
+rake spec:core       # RGame::Core specs; opens real windows, boots its own Xvfb
+rake                 # everything: make test, rake spec, rake spec:core
+bundle exec rubocop  # lint; configured in .rubocop.yml, which also loads the
+                     # project's own cops from lib/rgame/rubocop/.
+```
+
+The two Ruby suites are two directories and two processes on purpose. `spec/`
+must never load SDL — the engine layer's whole value is that it can be
+specified with no window — and RSpec loads one root into one process, so a
+single `require "rgame/core"` anywhere would define `RGame::Core` for every
+other example in the run. Separate runners cannot be forgotten the way an
+exclude rule can. `rake spec` needs `make ext-util`; `rake spec:core` needs
+`make ext-core`.
+
+Each `make ext-*` target compiles its extension and copies the resulting `.so`
+into `lib/rgame/`, which is where `require "rgame/util_ext"` and `require
+"rgame/core_ext"` look for it. That mirrors how rake-compiler installs a
+compiled extension into `lib/<gem>/`. Without that step the specs can't even
+load, since `RGame::Util::Tensor` now lives in C.
+
+`rake spec` needs only `ext-util` — it never touches `RGame::Core`, which is
+what keeps it runnable with no display and no SDL. To drive the *engine* from
+Ruby by hand (opens a real window):
+
+```
+make ext-core
+ruby ext/rgame_core/example.rb
+```
+
+## Packaging
+
+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 nothing on a covered platform
+```
+
+Or from a checkout, which builds the source gem locally:
+
+```
+rake build                      # package into pkg/rgame-<version>.gem
+gem install pkg/rgame-*.gem     # compiles both extensions on this machine
+```
+
+**RubyGems holds two kinds of gem for each version.** The source gem carries the
+C and compiles on install. Three platform gems carry `core_ext` and `util_ext`
+already built, with SDL2 linked statically into `core_ext`; they ship no `.c`,
+no `extconf.rb` and declare no extensions, so they compile nothing. `gem
+install` picks by platform and Ruby version on its own.
+
+CI builds and publishes all four. `tools/platform_gem.rake` builds a platform
+gem, `tools/check_platform_gem.rb` checks it against nine rules before it may be
+published, and the `smoke` job installs it on a runner with no SDL2 and plays
+the examples out of it.
+
+Installing the source gem runs each `extconf.rb` and installs the resulting
+`.so` into the gem's own `lib/rgame/`, which is the same layout `make ext`
+produces in a checkout — so `require "rgame"` and `require "rgame/core"` behave
+identically whichever gem you got, including the guarantee that the first of
+those loads no graphics libraries. Its system dependencies are the ones the C
+engine needs (SDL2, OpenGL, pkg-config, a compiler); `extconf.rb` aborts with
+the package to install if one is missing, rather than failing later at the link
+step.
+
+What ships is a glob over `lib/`, `ext/` and `docs/api/`, not a hand-written
+list: a new C source or a runtime asset dropped into either tree is packaged
+without being registered anywhere. `spec/packaging_spec.rb` holds that up from
+the other side — it asserts every source, header and data file is in the gem and
+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).
+
+## Project structure
+
+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/`.
+
+A file-by-file map of the whole repository is in
+[docs/project_structure.md](docs/project_structure.md).
+
+## Roadmap
+
+There is currently no roadmap for the next version.
+
+## 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.