rgame 0.2.0 → 0.3.0

data/lib/rgame/boot.rb

@@ -1,13 +1,3 @@
 # frozen_string_literal: true
 
-# Turns on YJIT, Ruby's JIT compiler, for a meaningful speedup in the game loop.
-#
-# Required by RGame::Game rather than left to each game to remember, because a
-# game loop is the case JIT was built for and forgetting costs frames silently.
-# It is deliberately *not* required by `rgame` or `rgame/core`: enabling a JIT
-# is a decision about the whole process, and a library has no business making
-# it for a host that only wanted a Color.
-#
-# Guarded, so the project still runs on a Ruby built without YJIT — it just runs
-# unaccelerated instead of crashing.
 RubyVM::YJIT.enable if defined?(RubyVM::YJIT) && RubyVM::YJIT.respond_to?(:enable)

data/lib/rgame/cli/new_project.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'erb'
+require 'fileutils'
+require 'rubygems/version'
+
+require_relative '../version'
+
+module RGame
+  module CLI
+    # Writes a new game project: `rgame new tictactoe`.
+    #
+    # The layout it produces is the project's own architecture in miniature, and
+    # the generated comments say so at each file:
+    #
+    #   - `game.rb` is the only file that requires `rgame/game`, so it is the
+    #     only one that loads SDL and OpenGL. It is the game's glue class, the
+    #     local counterpart of RGame::Game.
+    #   - `nodes/` requires `rgame` and names only RGame::Engine, so every node
+    #     runs with no window.
+    #   - `spec/` therefore loads `rgame` too, and the whole suite runs headless.
+    #
+    # Getting a newcomer to that shape by default is most of the point: it is
+    # the arrangement that keeps game logic spec-able, and it is not one anybody
+    # would arrive at by guessing.
+    #
+    # @api private
+    class NewProject
+      # Anything the caller did wrong: a bad name, a directory in the way.
+      # RGame::CLI turns it into a message and a non-zero status.
+      class Error < StandardError; end
+
+      TEMPLATE_ROOT = File.expand_path('templates', __dir__)
+
+      DOTFILES = {
+        'gitignore' => '.gitignore',
+        'rspec' => '.rspec',
+        'ruby-version' => '.ruby-version',
+        'rubocop.yml' => '.rubocop.yml'
+      }.freeze
+
+      NAME_PATTERN = /\A[a-z][a-z0-9_-]*\z/i
+
+      def initialize(name, out: $stdout, root: Dir.pwd)
+        @name = name
+        @out = out
+        @target = File.expand_path(name, root)
+
+        validate_name!
+      end
+
+      def generate
+        check_target!
+
+        templates.each { |source, destination| write(destination, render(source)) }
+
+        report_next_steps
+      end
+
+      # `tic_tac_toe` and `tic-tac-toe` both give `TicTacToe`. Used for the
+      # window caption and, with `Game` appended, for the game class.
+      def caption = @name.split(/[_-]+/).map(&:capitalize).join
+
+      def game_class = "#{caption}Game"
+
+      def app_name = @name
+
+      # "~> 0.2" for a 0.2.0 generator, so a project tracks whatever version
+      # created it rather than a number frozen into a template.
+      def rgame_requirement = Gem::Version.new(RGame::VERSION).approximate_recommendation
+
+      # The Ruby running `rgame new`, written to .ruby-version and pointed at
+      # from the Gemfile. Whichever Ruby generated the project is the one it was
+      # known to work on, which is the only version this can honestly claim.
+      #
+      # The bare `4.0.5` form rather than mise's `ruby 4.0.5`: every version
+      # manager reads it, and so does Bundler's `ruby file:`.
+      def ruby_version = RUBY_VERSION
+
+      private
+
+      def templates
+        Dir.glob('**/*.tt', base: TEMPLATE_ROOT).sort.map do |source|
+          [source, destination_for(source)]
+        end
+      end
+
+      def destination_for(source)
+        dir = File.dirname(source)
+        base = File.basename(source, '.tt')
+        base = DOTFILES.fetch(base, base)
+
+        dir == '.' ? base : File.join(dir, base)
+      end
+
+      def render(source)
+        erb = ERB.new(File.read(File.join(TEMPLATE_ROOT, source)), trim_mode: '-')
+        erb.filename = source
+        erb.result(binding)
+      end
+
+      def write(destination, content)
+        path = File.join(@target, destination)
+
+        FileUtils.mkdir_p(File.dirname(path))
+        File.write(path, content)
+
+        @out.puts("      create  #{File.join(@name, destination)}")
+      end
+
+      def validate_name!
+        return if @name.is_a?(String) && @name.match?(NAME_PATTERN)
+
+        raise Error, "#{@name.inspect} is not a valid project name — use letters, digits, " \
+                     'underscores and dashes, starting with a letter'
+      end
+
+      def check_target!
+        return unless File.exist?(@target)
+        raise Error, "#{@name} exists and is not a directory" unless File.directory?(@target)
+        return if (Dir.children(@target) - ['.', '..']).empty?
+
+        raise Error, "#{@name} already exists and is not empty"
+      end
+
+      def report_next_steps
+        @out.puts(<<~NEXT)
+
+          Created #{@name}. Next:
+
+            cd #{@name}
+            bundle install
+            bundle exec rspec     # the game logic, headless — no window needed
+            ruby main.rb          # the game itself
+        NEXT
+      end
+    end
+  end
+end

data/lib/rgame/cli/templates/Gemfile.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# The Ruby this project was generated with, kept in one place so bundler and
+# your version manager cannot disagree about it. Bundler reads .ruby-version as
+# an exact requirement and refuses to install on anything else; for a range,
+# replace this line with something like `ruby '~> <%= ruby_version.split('.').first(2).join('.') %>'`.
+ruby file: '.ruby-version'
+
+# The engine. It has no runtime dependencies of its own — SDL2 and OpenGL are
+# system libraries rather than gems — but installing it compiles two C
+# extensions, so a C compiler, `make`, `pkg-config` and the SDL2/OpenGL
+# development headers have to be present. See the rgame README.
+gem 'rgame', '<%= rgame_requirement %>'
+
+group :development, :test do
+  gem 'rake', require: false
+  gem 'rspec'
+  gem 'rubocop', require: false
+  gem 'rubocop-performance', require: false
+  gem 'rubocop-rspec', require: false
+end

data/lib/rgame/cli/templates/README.md.tt

@@ -0,0 +1,93 @@
+# <%= caption %>
+
+A game built with [rgame](https://github.com/psuessenb/rgame).
+
+## Running it
+
+```
+bundle install
+ruby main.rb
+```
+
+`F1` toggles the debug overlay, `F2` closes the window.
+
+This project was generated on Ruby <%= ruby_version %>, which is what
+`.ruby-version` holds and what the `Gemfile` points at. Bundler treats that as
+an exact requirement; see the note in the `Gemfile` to loosen it.
+
+## Testing it
+
+```
+bundle exec rspec
+```
+
+The suite runs **headless** — no window, no GPU, no clock. That is not an
+accident of this project being small; it is the arrangement the layout below is
+for, and it holds however large the game gets.
+
+```
+bundle exec rubocop
+bundle exec rake        # both of the above
+```
+
+## Layout
+
+```
+main.rb           boots the game and nothing else
+game.rb           the window, its size, its caption — and the ONLY file that
+                  loads SDL and OpenGL
+nodes/            the scene tree: game logic, graphics-free
+  root.rb         the root node, drawn every frame
+assets/           images, sounds, maps — RGame::Game's media_root
+  locales/        translation tables, one file per language
+spec/             specs for nodes/, run with no display
+  locales_spec.rb every language has every key en.yml has
+```
+
+### Why `game.rb` and `nodes/` are separate
+
+rgame comes in two halves, and they are worth keeping apart.
+
+`RGame::Core` owns the window, the GPU textures and the sound device — real
+operating-system handles. `RGame::Engine` is the scene graph: nodes, components,
+signals, sprites, tile maps. It holds no handles at all, and it never names
+`RGame::Core`. A node is *handed* a renderer at draw time and calls methods on
+it by name.
+
+So `require 'rgame'` loads the engine and the value types with no graphics
+library in the process, while `require 'rgame/game'` loads everything. `game.rb`
+does the latter, `nodes/*.rb` and `spec/*` do the former — and that one
+difference is what lets the entire game logic be tested in milliseconds, with a
+spy standing in for the renderer, on a machine with no display.
+
+Keep new game logic under `nodes/`. When something there needs to draw, give it
+an `on_draw(renderer, view)` and call the renderer by name.
+
+## Text on screen
+
+Text the game draws lives in `assets/locales/en.yml`, not in the code. A node
+builds an `RGame::Engine::Text` from a key once and draws it every frame:
+
+```ruby
+@greeting = RGame::Engine::Text.new('root.greeting')   # in initialize
+renderer.text(@greeting, 20, 20)                       # in on_draw
+```
+
+- **To add text,** add a key to `en.yml`.
+- **To add a language,** add a file beside it, such as `de.yml` starting with
+  `de:`, holding the same keys. The game loads every file in `assets/locales/`
+  and picks the player's language from their operating system.
+- **`bundle exec rspec` fails** when a language lacks a key `en.yml` has, and
+  when a spec draws a key no table has. In the game, a missing key shows the
+  English text instead.
+
+`spec/spec_helper.rb` loads the tables from `assets/locales/` itself, since specs
+cannot load `game.rb`. Move that directory and update both.
+
+The [localization guide](https://github.com/psuessenb/rgame/blob/main/docs/api/localization.md)
+covers plurals, variables and the fallback between languages.
+
+## Where to look next
+
+The [rgame API guide](https://github.com/psuessenb/rgame/blob/main/docs/api/README.md)
+covers the scene graph, components, input, drawing, audio and the asset layer.

data/lib/rgame/cli/templates/Rakefile.tt

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require 'rspec/core/rake_task'
+require 'rubocop/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/rgame/cli/templates/assets/locales/en.yml.tt

@@ -0,0 +1,10 @@
+# The English table: every piece of text the game draws, by key. Rails' format,
+# so the top-level key is the locale and everything below it nests.
+#
+# To add a language, add a file beside this one (de.yml, starting `de:`) with
+# the same keys. RGame::Game loads every .yml in this directory and picks the
+# player's language from their operating system; spec/locales_spec.rb fails
+# while a language lacks a key this file has.
+en:
+  root:
+    greeting: "Hello from <%= app_name %>!"

data/lib/rgame/cli/templates/game.rb.tt

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require 'rgame/game'
+
+require_relative 'nodes/root'
+
+class <%= game_class %> < RGame::Game
+  WIDTH = 640
+  HEIGHT = 480
+
+  # The bare `**` forwards every keyword straight through to RGame::Game, so
+  # anything it accepts still works here — `players: 2` for split-screen, or
+  # `input:` to hand the game a scripted input backend and drive it from a test
+  # harness with no hardware attached.
+  def initialize(**)
+    super(root: Root.new,
+          caption: '<%= caption %>',
+          width: WIDTH,
+          height: HEIGHT,
+          media_root: File.join(__dir__, 'assets'),
+          **)
+  end
+end

data/lib/rgame/cli/templates/gitignore.tt

@@ -0,0 +1,12 @@
+# Bundler
+/.bundle/
+/vendor/bundle/
+
+# Gem packaging, if this project ever becomes one
+/pkg/
+*.gem
+
+# Editor / OS
+.DS_Store
+*.swp
+/.ruby-lsp/

data/lib/rgame/cli/templates/main.rb.tt

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Entry point: `ruby main.rb`.
+#
+# Deliberately nothing but a boot. Everything the game *is* lives in game.rb and
+# nodes/, which is what lets the spec suite load the interesting half without
+# also starting a window.
+
+require_relative 'game'
+
+<%= game_class %>.new.start

data/lib/rgame/cli/templates/nodes/root.rb.tt

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'rgame'
+
+# The root of the scene tree. Everything the game draws hangs below it.
+#
+# The three hooks to override are `on_control(actions)`, `on_update(dt)` and
+# `on_draw(renderer, view)`. Override those rather than `control`, `update` or
+# `draw`: the engine does its own bookkeeping in the outer methods and calls
+# these, so there is no `super` to forget.
+#
+# Text on screen is a key into assets/locales/, not a String in the code. A
+# `Text` is built once and read every frame: it looks the key up again only when
+# the language changes, so drawing it costs nothing.
+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

data/lib/rgame/cli/templates/rspec.tt

@@ -0,0 +1,2 @@
+--require spec_helper
+--format documentation

data/lib/rgame/cli/templates/rubocop.yml.tt

@@ -0,0 +1,75 @@
+# rgame's own cops come with the gem. They catch what a game gets wrong without
+# noticing: a String built every frame, a node drawn at its own position twice,
+# text a translation cannot reach. Each explains itself in its message.
+plugins:
+  - rubocop-performance
+  - rubocop-rspec
+  - rgame/rubocop:
+      plugin_class_name: RuboCop::Game::Plugin
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 4.0
+
+# This is a game, not a web app: update/draw methods naturally run long, and
+# short coordinate and loop variable names (x, y, dt, id) are idiomatic in the
+# maths they contain. Relax the size and naming cops accordingly.
+Metrics/AbcSize:
+  Enabled: false
+Metrics/BlockLength:
+  Enabled: false
+Metrics/ClassLength:
+  Enabled: false
+Metrics/CyclomaticComplexity:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/ModuleLength:
+  Enabled: false
+Metrics/ParameterLists:
+  Enabled: false
+Metrics/PerceivedComplexity:
+  Enabled: false
+Naming/MethodParameterName:
+  Enabled: false
+
+# Maths-heavy code reads fine on standard operator precedence
+# (row * cols + col, x + w / 2); requiring parentheses everywhere is just noise.
+Lint/AmbiguousOperatorPrecedence:
+  Enabled: false
+
+# nodes/ and spec/ run with no window, and only game.rb loads one. This keeps it
+# so: naming RGame::Core, or requiring rgame/core or rgame/game, fails the lint
+# rather than the spec run on a machine without a display.
+Game/NoCoreInEngineLayer:
+  Enabled: true
+  Include:
+    - 'nodes/**/*.rb'
+    - 'spec/**/*.rb'
+
+Style/Documentation:
+  Enabled: false
+
+# Integration-flavoured specs in a game naturally run longer than five lines and
+# assert more than one thing about the frame they drove.
+RSpec/ExampleLength:
+  Enabled: false
+RSpec/MultipleExpectations:
+  Enabled: false
+
+# A node is handed a renderer and calls it by name — it never learns what class
+# answered, which is exactly what lets the spec suite run with no window.
+# Verifying a double against RGame::Core::Renderer would mean loading SDL and
+# OpenGL into the spec process, so these doubles are deliberately unverified.
+RSpec/VerifiedDoubles:
+  Enabled: false
+
+# Spec paths mirror the source tree, and a class with a trailing dimension maps
+# to node2d_spec.rb rather than the cop's default node2_d_spec.rb.
+RSpec/SpecFilePathFormat:
+  CustomTransform:
+    Node2D: node2d
+  # It checks the tables in assets/locales/, and describes I18n only because
+  # that is what it asks, so there is no source file for its path to mirror.
+  Exclude:
+    - spec/locales_spec.rb

data/lib/rgame/cli/templates/ruby-version.tt

@@ -0,0 +1 @@
+<%= ruby_version %>

data/lib/rgame/cli/templates/spec/locales_spec.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# The translation tables in assets/locales/, checked against each other. A key
+# added to en.yml and forgotten in another language fails here, rather than
+# showing a player English text in the middle of their own language.
+RSpec.describe RGame::Engine::I18n do
+  # Without this, deleting en.yml would leave nothing to compare against, and
+  # the example below would pass for every language.
+  it 'has a table for the default locale' do
+    expect(described_class.available).to include(described_class.default)
+  end
+
+  it 'gives every locale every key the default locale has' do
+    missing = described_class.available.to_h { |locale| [locale, described_class.missing_keys(locale)] }
+
+    expect(missing.reject { |_locale, keys| keys.empty? }).to be_empty
+  end
+end

data/lib/rgame/cli/templates/spec/nodes/root_spec.rb.tt

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# What a node spec looks like: build the node, drive one of its hooks, assert.
+# No window is opened, and none is needed — see spec/spec_helper.rb for why.
+RSpec.describe Root do
+  describe '#on_draw' do
+    it 'draws its greeting from the English table' do
+      # A node calls a renderer by name and never asks what class it is, so a
+      # plain spy stands in for one. The real RGame::Core::Renderer lives on the
+      # other side of a line this suite deliberately does not cross.
+      renderer = spy('renderer')
+
+      described_class.new.on_draw(renderer, nil)
+
+      expect(renderer).to have_received(:text).with('Hello from <%= app_name %>!', 20, 20)
+    end
+  end
+end

data/lib/rgame/cli/templates/spec/spec_helper.rb.tt

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# `rgame` and never `rgame/game`. It loads RGame::Util and RGame::Engine —
+# everything that runs without a window — so no SDL and no OpenGL enter this
+# process, and the whole suite runs with no display: in CI, over SSH, anywhere.
+#
+# It also means `RGame::Core` is an undefined constant here. A spec that reached
+# for it would fail loudly rather than quietly opening a window, which is the
+# point: game logic that can only be tested with a GPU attached is game logic
+# that stops being tested.
+require 'rgame'
+
+# The project root, so `require 'nodes/root'` works from anywhere in the suite.
+$LOAD_PATH.unshift File.expand_path('..', __dir__)
+
+Dir[File.expand_path('../nodes/**/*.rb', __dir__)].each { |file| require file }
+
+# The translation tables, read from disk once. This is the directory RGame::Game
+# loads in the game: `locales` under game.rb's `media_root`. Move one and move
+# the other, or every key a spec draws raises.
+LOCALES = Dir[File.expand_path('../assets/locales/**/*.yml', __dir__)]
+          .to_h { |path| [path, File.read(path)] }.freeze
+
+RSpec.configure do |config|
+  config.expect_with(:rspec) { |c| c.syntax = :expect }
+  config.disable_monkey_patching!
+
+  # RGame::Engine::I18n is global, so every example starts from the game's own
+  # tables in the default language, whatever the example before it loaded or
+  # switched to. A key no table has raises instead of drawing itself: found by
+  # `rake` rather than by a player.
+  config.before do
+    RGame::Engine::I18n.reset
+    LOCALES.each { |path, yaml| RGame::Engine::I18n.load(yaml, source: path) }
+    RGame::Engine::I18n.missing = :raise
+  end
+end

data/lib/rgame/cli.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require_relative 'version'
+require_relative 'cli/new_project'
+
+module RGame
+  # Argument parsing and dispatch. The work is in RGame::CLI::NewProject.
+  module CLI
+    USAGE = <<~USAGE
+      Usage: rgame COMMAND [ARGS]
+
+      Commands:
+        new NAME     Create a new game project in the directory NAME
+        version      Print the rgame version
+        help         Print this message
+
+      Example:
+        rgame new tictactoe
+    USAGE
+
+    # Runs one command and returns the process exit status, rather than calling
+    # `exit` itself — which is what lets a spec drive it in-process and assert on
+    # what it wrote and what it printed.
+    #
+    # `out` and `err` are injectable for the same reason.
+    def self.run(argv, out: $stdout, err: $stderr)
+      command, *rest = argv
+
+      case command
+      when 'new' then new_project(rest, out: out, err: err)
+      when 'version', '--version', '-v' then version(out: out)
+      when 'help', '--help', '-h', nil then help(out: out)
+      else
+        err.puts("rgame: unknown command #{command.inspect}", '', USAGE)
+        1
+      end
+    end
+
+    def self.help(out:)
+      out.puts(USAGE)
+      0
+    end
+
+    def self.version(out:)
+      out.puts("rgame #{RGame::VERSION}")
+      0
+    end
+
+    def self.new_project(args, out:, err:)
+      name = args.first
+
+      if name.nil? || name.start_with?('-')
+        err.puts('rgame new: expected a project name', '', USAGE)
+        return 1
+      end
+
+      NewProject.new(name, out: out).generate
+      0
+    rescue NewProject::Error => e
+      err.puts("rgame new: #{e.message}")
+      1
+    end
+
+    private_class_method :help, :version, :new_project
+  end
+end

data/lib/rgame/core/app.rb

@@ -1,48 +1,5 @@
 # frozen_string_literal: true
 
-# RGame::Core::App is implemented in C — see ext/rgame_core/. It wraps the
-# engine's public API (ext/rgame_core/include/rgame/core.h): an SDL window plus
-# OpenGL context, and a fixed-timestep main loop that drives callbacks.
-#
-# App is meant to be subclassed. The engine calls back into methods on the
-# object itself, so a game overrides the hooks it needs and inherits no-ops for
-# the rest:
-#
-#   class MyGame < RGame::Core::App
-#     def initialize = super(width: 800, height: 600, caption: 'my game')
-#
-#     def frame_begin; end     # once per frame, before that frame's ticks
-#     def update(dt); end      # one fixed simulation tick; dt is always the
-#                              # fixed step, never wall-clock frame time
-#     def needs_redraw?; end   # false skips the draw (simulation still runs)
-#     def draw; end            # render one frame
-#     def frame_end; end       # after draw is submitted, before the swap —
-#                              # rarely needed outside a test that reads pixels
-#     def button_down(id); end # discrete key press (no repeats)
-#     def button_up(id); end
-#     def resize(w, h); end
-#   end
-#
-#   MyGame.new.run
-#
-# Also inherited: #close (stops the loop; safe from inside a callback), #width,
-# #height, #caption, #caption=, #ticks_ms (monotonic ms since startup) and #fps.
-#
-# The loop owns the fixed-timestep accumulator, so #update is called once per
-# whole tick and may run zero or several times per rendered frame. #frame_begin
-# is the place to sample input once and reuse it across every tick of that
-# frame.
-#
-# If a callback raises, the exception is carried out of #run with its original
-# class, message and backtrace, and the loop shuts down cleanly first. A
-# non-local exit (throw/break/return) out of a callback cannot be carried
-# across the C loop and is reported as a RuntimeError instead — use #close to
-# stop the loop.
-#
-# Loading this .so pulls SDL2 and OpenGL into the process — see
-# lib/rgame/core.rb for why that's kept off the default `require "rgame"`.
-# It loads from lib/rgame/core_ext.so, which the build (`make ext-core`)
-# copies out of ext/rgame_core/.
 require 'rgame/core_ext'
 
 module RGame
@@ -73,7 +30,12 @@ module RGame
       # This app's sound device. Not tied to the window in any way — audio has
       # no GL context and survives one being recreated — it lives here because
       # a game wants exactly one, the same way it wants one asset manager.
-      def audio = @audio ||= Audio.new
+      # It is handed this app's asset manager, so `audio.play_sound('hurt.ogg')`
+      # resolves a path the same way `renderer.sprite('hero.json', …)` does.
+      # Building the manager does not touch audio — its loaders are lambdas,
+      # called at load time — so there is no cycle here despite the manager
+      # reaching back through `app.audio` to make a sound.
+      def audio = @audio ||= Audio.new(assets: assets)
 
       # Where #assets resolves relative paths from. Set once, as a keyword to
       # the constructor; there is deliberately no writer, because changing it