rgame 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7eb60de3d59e1a7c55ad4261e68be3a9cdb1d8f478e56354eb655c2452fbc4d
-  data.tar.gz: 73f0f53dec4c19b34bd32a80cfa86ac2c8068a80debbd32bc234c1dca4cbd0b5
+  metadata.gz: 54caa0772adc1eb3211edbd694540c196be0018d6482089447d727f5c871e19a
+  data.tar.gz: 16b3d1de8baefc2579bbf5a89fb7b42041d174567b6c7059d5c967f2598621f5
 SHA512:
-  metadata.gz: f71a457f48b0f45206b03c68e8dfc8f222c9c2a87957ac2c44edd0f2330dc3412d82874544176379143a5ccf7e24596665253e1a75983d475fd8273a500bcdbe
-  data.tar.gz: f3c7ac9d5663a9e0f0df3823be78c7cf7496176982e86933e5ad8c19293ade3c21320828127e4a31086f21b44a75096cde3b9b6a4695a51180517ba9f700313b
+  metadata.gz: ab441100a4d86c34d93efed615b350a7d65ad819d3b7929e868e709c6a9790b9c78a956b9860632e62750f0880ca9656a1f7f6c98cc3df6c1b19f7d229e40919
+  data.tar.gz: e98b7a96d21700bf0533f0155be99ffc9f480e35fda2375aaee4b8b2a7bb65b871d0a70a1f2486873b32e28a83aaa4abfc91a14991226153f57959b0d62237b4

data/CHANGELOG.md

@@ -12,6 +12,139 @@ index, not the argument.
 
 ## [Unreleased]
 
+## [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
@@ -89,6 +222,7 @@ First release, and the first version that runs a game end to end.
 - **`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
+[Unreleased]: https://github.com/psuessenb/rgame/compare/v0.3.0...HEAD
+[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/README.md

@@ -4,7 +4,7 @@ RGame is a small 2D game engine for Ruby, written in Ruby and C. It's build on t
 
 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.
+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?
 
@@ -14,19 +14,41 @@ RGame puts a lot of emphazis on testing and being testable: It separates the lay
 
 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).
+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, you can try this. 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.
+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!
 
-## Hello world
+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
+```
+
+What it writes is small — 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 why it matters.
+
+`gem install` compiles two C extensions, so the [requirements](#requirements) below have to be in place first. That's the one big hurdle at the moment: This gem ships source-only, so you have to compile a lot of C _on your machine_ to get this running.
+
+## 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)
+  def on_draw(renderer, _view)
     renderer.text('Hello world!', 250, 200)
   end
 end
@@ -41,9 +63,40 @@ 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 |
+
 ## 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.
+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. This _also_ means you need to install some system libaries and have header files present.
 
 ### C engine
 
@@ -67,20 +120,15 @@ fixture and needs `libvorbisenc` to run.
 
 ### Ruby side
 
-- **Ruby 4.0.5**, pinned in `.ruby-version`. Installed here with
-  [mise](https://mise.jdx.dev) (`mise install` in the project root picks up
-  `.ruby-version`); any version manager that reads `.ruby-version` works just
-  as well.
-- **Ruby development headers.** Version-manager builds (mise, rbenv, rvm,
-  asdf) include them. On a distro-packaged Ruby, install `ruby-dev`
+- **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 has no runtime Ruby dependencies, and the `Gemfile`
-holds only development gems.
+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).
+[CI](.github/workflows/ci.yml) - with that people have usually at home, so Apple Silicon and not Apple Intel, etc.
 
 ### Debian / Ubuntu
 
@@ -180,7 +228,7 @@ 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 rubocop/cop/game/.
+                     # project's own cops from lib/rgame/rubocop/.
 ```
 
 The two Ruby suites are two directories and two processes on purpose. `spec/`
@@ -208,8 +256,7 @@ 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):
+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
@@ -241,10 +288,7 @@ 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:
+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
@@ -252,49 +296,7 @@ A file-by-file map of the whole repository is in
 
 ## Roadmap
 
-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.
+There is currently no roadmap for the next version.
 
 ## AI clause