rgame 0.1.0 → 0.3.0

data/lib/rgame/core/asset_manager.rb

@@ -12,7 +12,7 @@ module RGame
     #   app.assets.release(:level1)
     #
     # The built-in types are `image`, `sound`, `song` and `read`, plus the
-    # composites `sheet` and `ui_atlas`. A game or its glue adds more with
+    # composites `sheet` and `ui_atlas`; `glob` lists what is there to load. A game or its glue adds more with
     # {#add_loader}, which is how a tile map gets loaded without Core having to
     # know what one is.
     #
@@ -55,7 +55,6 @@ module RGame
     # `loaders:` is what lets the caching, path resolution and grouping be
     # specced with no window, no GL context and no files at all.
     class AssetManager
-      # Owner of every ungrouped load. Never released, only cleared.
       PERMANENT = :__permanent__
 
       # `app` is what images are loaded into and where the audio device comes
@@ -65,7 +64,7 @@ module RGame
         @app = app
         @loaders = {}
         @cache = {}
-        @owners = {} # cache key => Set of groups holding it
+        @owners = {}
 
         (loaders || default_loaders).each { |type, loader| add_loader(type, &loader) }
       end
@@ -91,9 +90,6 @@ module RGame
       # offering it an id.
       def add_loader(type, &loader)
         @loaders[type] = loader
-        # A singleton method rather than a class-level one: two managers may
-        # know different types, and a game that adds `:tilemap` should not be
-        # teaching it to everyone else's.
         define_singleton_method(type) { |path, group = PERMANENT| leaf(type, path, group) }
         self
       end
@@ -130,10 +126,6 @@ module RGame
       # Takes `group` off every asset's owner set and drops whatever no group
       # still holds.
       def release(group)
-        # Without this, `release(PERMANENT)` would empty every ungrouped
-        # asset's owner set and drop the lot — the exact opposite of what the
-        # constant's name promises, and silent. It is only reachable by naming
-        # the sentinel, so saying what to use instead beats ignoring the call.
         raise ArgumentError, 'ungrouped assets are dropped by #clear, not #release' if group == PERMANENT
 
         @owners.each_value { |groups| groups.delete(group) }
@@ -153,15 +145,23 @@ module RGame
         self
       end
 
+      # The paths under the media root that match `pattern`, relative to the
+      # root and sorted, so what a caller loads from the list — and the order it
+      # merges in — is the same on every platform and file system:
+      #
+      #   assets.glob('locales/**/*.yml')   # => ["locales/de.yml", "locales/en.yml"]
+      #
+      # A directory that does not exist matches nothing, so a game without one
+      # gets `[]` rather than an error. An absolute pattern is used as it
+      # stands, and its matches come back absolute. Nothing is loaded or cached.
+      def glob(pattern) = Dir.glob(pattern, base: File.expand_path(@root)).sort
+
       # How many assets are cached. For tests and for a debug overlay; a game
       # has no reason to ask.
       def size = @cache.size
 
       private
 
-      # The app is reached through the ivar rather than captured, so
-      # `app.audio` is not called until a sound is actually asked for — loading
-      # an image opens no sound device.
       def default_loaders
         {
           image: ->(path) { Image.new(@app, path) },
@@ -175,20 +175,8 @@ module RGame
         fetch(type, path, group) { @loaders.fetch(type).call(resolve(path)) }
       end
 
-      # Where a path actually is on disk.
-      #
-      # `expand_path` rather than `join` for two reasons. An **absolute** path
-      # is used as it stands, which is what lets a loader hand one back — the
-      # tile-map loader gets its tileset image that way, since the path comes
-      # out of a `.tsx` that was itself found on disk. And `'a/./b.png'`,
-      # `'a/../b.png'` and `'b.png'` all land on one cache key rather than
-      # three, so a file cannot be loaded twice by being named twice.
       def resolve(path) = File.expand_path(path, @root)
 
-      # Memoise on miss, then record the owning group — so a cache *hit* under a
-      # new group is tagged too. Tagging after the load rather than before is
-      # what leaves a failed load with no owner behind it, which makes a retry a
-      # clean retry rather than a permanently half-registered asset.
       def fetch(type, path, group)
         key = [type, resolve(path)]
         object = (@cache[key] ||= yield)
@@ -204,17 +192,11 @@ module RGame
         UiAtlas.new(*composite_parts(relative_path, group))
       end
 
-      # The two halves a composite is made of, both through the cache: the
-      # descriptor as a cached `read`, and the image it names as a cached
-      # `image` resolved beside it.
       def composite_parts(relative_path, group)
         data = JSON.parse(read(relative_path, group), symbolize_names: true)
         [image(sibling(relative_path, data[:image]), group), data]
       end
 
-      # A path next to `relative_path`, still relative to the root — so a
-      # descriptor's image lands on the same `[:image, path]` cache key a
-      # standalone `image` of that file would.
       def sibling(relative_path, name)
         directory = File.dirname(relative_path)
         directory == '.' ? name : File.join(directory, name)

data/lib/rgame/core/audio.rb

@@ -19,6 +19,21 @@ module RGame
     # the alternative is a crash at startup for something nobody asked for.
     # `#backend` says which one was chosen.
     class Audio
+      # `assets` is what a path id is resolved through, and may be nil — a
+      # device built by hand plays only what it is handed. `RGame::Core::App`
+      # passes its own manager, so a game never sets this.
+      #
+      # A Ruby `self.new` because the C `initialize` takes no arguments and has
+      # no business knowing what an asset manager is — the same shape
+      # `Renderer.new` uses for the same reason.
+      def self.new(assets: nil)
+        audio = super()
+        audio.assets = assets
+        audio
+      end
+
+      attr_accessor :assets
+
       # Loads a short sound to play over itself. The same thing as
       # `Sample.new(audio, path)`, and the form to prefer: it reads in the
       # direction the objects depend, and it is the form a stand-in device can
@@ -28,15 +43,6 @@ module RGame
       # Loads a long one to stream. See {Song}.
       def song(path) = Song.new(self, path)
 
-      # --- play-by-id -----------------------------------------------------
-      #
-      # The same boundary the renderer's draw-by-id serves: game logic emits
-      # facts — "the ship was hit" — and names the sound, because a scene may
-      # not hold a `Sample`. Registration only, unlike the renderer: a sound id
-      # is whatever a game wants to call it, and there is no per-frame path to
-      # make resolving one worth caching.
-      #
-      #   audio.register_sound(:hit, app.assets.sound('example 09/hurt.ogg'))
       #   audio.play_sound(:hit)
 
       def register_sound(id, sample)
@@ -49,17 +55,17 @@ module RGame
         self
       end
 
-      # Plays a registered sample. Each call is another voice, layered over the
-      # ones already sounding.
+      # Plays a sample by id. Each call is another voice, layered over the ones
+      # already sounding.
       def play_sound(id)
-        samples.fetch(id).play
+        lookup(:sound, id).play
       end
 
-      # Starts a registered song looping, and does **nothing** if it is already
-      # playing — so a scene that re-emits the same request every time it is
-      # entered never restarts the music mid-loop.
+      # Starts a song looping, and does **nothing** if it is already playing —
+      # so a scene that re-emits the same request every time it is entered never
+      # restarts the music mid-loop.
       def play_music(id)
-        song = songs.fetch(id)
+        song = lookup(:song, id)
         return song if song.playing?
 
         @playing_song = song
@@ -81,6 +87,21 @@ module RGame
 
       def samples = @samples ||= {}
       def songs = @songs ||= {}
+
+      def registry(type) = type == :sound ? samples : songs
+
+      def lookup(type, id)
+        raise TypeError, "no implicit conversion of nil into #{type}" if id.nil?
+
+        table = registry(type)
+        table.fetch(id) { table[id] = resolve_asset(type, id) }
+      end
+
+      def resolve_asset(type, id)
+        resolved = @assets.public_send(type, id) if id.is_a?(String) && @assets.respond_to?(type)
+        resolved || raise(KeyError, "no #{type} registered for #{id.inspect} " \
+                                    'and no AssetManager to resolve it')
+      end
     end
 
     # A short sound, decoded once and played many times over.

data/lib/rgame/core/font.rb

@@ -34,9 +34,6 @@ module RGame
     # Scripts outside the shipped font's coverage — CJK, Arabic, Hebrew — need
     # their own file. No font of this size covers them.
     class Font
-      # Shipped with the gem, alongside its SIL OFL 1.1 licence. Resolved from
-      # this file's location so it works the same from a checkout and from an
-      # installed gem.
       DEFAULT_PATH = File.expand_path('../fonts/LiberationSans-Regular.ttf', __dir__)
 
       # `path:` is a keyword for callers but positional for the C initialize,

data/lib/rgame/core/input.rb

@@ -5,72 +5,66 @@ require_relative '../util/controls'
 
 module RGame
   module Core
-    # Translates the game's symbolic actions (:fire, :confirm) into the physical
-    # button ids the engine understands, and asks the app whether they're held.
+    # Asks the engine whether a physical input is active, on a given device.
     #
     #   input = RGame::Core::Input.new(app)
-    #   input.down?(:fire)                 # keyboard, the single-player default
-    #   input.down?(:fire, device: 1)      # the pad in player slot 0
-    #   input.axis(:move_x, device: 1)     # => Float, -1.0..1.0
+    #   input.down?(Controls::KEY_SPACE)                          # keyboard
+    #   input.down?(Controls::PAD_A, device: Controls.gamepad(0))  # player 1's pad
+    #   input.axis(Controls::AXIS_LEFT_X, device: Controls.gamepad(0))
     #
-    # The id vocabulary itself lives in RGame::Util::Controls, not here: ids are
-    # values, and the engine layer must be able to name one without touching
-    # Core. That is also what makes rebinding possible — a game builds its own
-    # table from those constants and passes it in:
+    # **This is the raw query, and deliberately nothing more.** It used to carry
+    # binding tables of its own — `down?(:fire)` resolved `:fire` to a scancode
+    # through one of three tables passed to the constructor. Those are gone, and
+    # binding now lives one layer up in RGame::Engine::InputMap, for two
+    # reasons. A game's rebinding screen has to be able to edit the table, and
+    # the engine layer may not name RGame::Core at all; and with a player per
+    # device, the table is a per-player value rather than a property of the one
+    # object that talks to the hardware.
     #
-    #   controls = RGame::Util::Controls
-    #   input = RGame::Core::Input.new(
-    #     app, bindings: controls::DEFAULT_KEYBOARD.merge(fire: controls::KEY_J)
-    #   )
+    # What is left is an argument-order adapter over the app's own
+    # `input_down?(device, id)` / `input_axis(device, axis_id)`. It stays a named
+    # class rather than collapsing into those, because it is what gets handed to
+    # the engine layer as an input backend — and handing it a whole App, which
+    # can also close the window and rename it, would be a worse seam.
     #
-    # Devices are numbered keyboard-first: Controls::KEYBOARD is 0, and
-    # Controls.gamepad(slot) is the pad in that player slot. Defaulting
-    # `device:` to the keyboard is what lets single-player call sites stay
-    # `input.down?(:fire)` with no ceremony.
+    # Ids come from RGame::Util::Controls. They are values with nothing behind
+    # them, so both layers can name one.
     #
     # **There is no pointer or mouse support, by design.** The layer this
     # replaced had a cursor position and a click button riding the same "is
     # held" path as keys, and none of it was carried over: this engine's input
-    # is keyboard and controllers. A game wanting click-based UI has to build
-    # hit-testing on top rather than find it here, and the intended answer for
-    # menus is keyboard and controller navigation instead.
+    # is keyboard and controllers. The intended answer for menus is keyboard and
+    # controller navigation instead.
     class Input
       Controls = RGame::Util::Controls
 
-      # `bindings` covers the keyboard, `pad_bindings` the controllers, and
-      # `axis_bindings` the analog axes. All default to the standard tables.
-      def initialize(app,
-                     bindings: Controls::DEFAULT_KEYBOARD,
-                     pad_bindings: Controls::DEFAULT_PAD,
-                     axis_bindings: Controls::DEFAULT_AXES)
+      def initialize(app)
         @app = app
-        @bindings = bindings
-        @pad_bindings = pad_bindings
-        @axis_bindings = axis_bindings
       end
 
-      # Is the action's physical button held on `device`?
+      # Is `id` held on `device`?
       #
       # Reads the engine's per-frame input snapshot, so the answer is identical
       # for every simulation tick within one frame — a key held for a single
       # frame behaves the same whether that frame ran one catch-up tick or five.
+      #
+      # A device only answers for its own kind of input: asking a gamepad about
+      # a keyboard scancode is `false`, never the keyboard's answer. That is
+      # what lets one binding table list a key and a pad button for the same
+      # action and still keep player two's pad from echoing player one.
       # hot-path
-      def down?(action, device: Controls::KEYBOARD)
-        @app.input_down?(device, bindings_for(device).fetch(action))
+      def down?(id, device: Controls::KEYBOARD)
+        @app.input_down?(device, id)
       end
 
       # Current value of an analog axis: sticks -1.0..1.0, triggers 0.0..1.0.
       # The keyboard has no axes, so it always reads 0.0.
+      #
+      # No dead zone is applied here — this is the hardware's answer. Ignoring
+      # a resting stick's jitter is RGame::Engine::ActionMapper's job.
       # hot-path
-      def axis(action, device: Controls::KEYBOARD)
-        @app.input_axis(device, @axis_bindings.fetch(action))
-      end
-
-      private
-
-      # hot-path
-      def bindings_for(device)
-        device == Controls::KEYBOARD ? @bindings : @pad_bindings
+      def axis(axis_id, device: Controls::KEYBOARD)
+        @app.input_axis(device, axis_id)
       end
     end
   end

data/lib/rgame/core/locale.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+
+module RGame
+  # `RGame::Core.preferred_locales` is C (`ext/rgame_core/app/locale.c`, bound in
+  # `ruby/locale_ext.c`): the user's preferred locales as the operating system
+  # reports them through SDL, most preferred first.
+  #
+  #   RGame::Core.preferred_locales   # => ["de-AT", "en"]
+  #
+  # Each is a language, then a hyphen and a country when the OS names one. The
+  # list is `[]` when the OS names none — on Linux, under `LANG=C`. It needs no
+  # app: SDL reads it without being initialised, so it is a module function
+  # rather than an `App` method.
+  #
+  # What it returns is taken as given. SDL on Linux reads `LANG` and then
+  # `LANGUAGE`, and ignores `LC_ALL`, so the list can repeat a locale; choosing
+  # among them is `RGame::Engine::I18n.choose`, which the glue calls.
+  module Core
+  end
+end

data/lib/rgame/core/nine_slice.rb

@@ -41,10 +41,6 @@ module RGame
       # (x, y, w, h) is the source rectangle inside `image`, so one sheet can
       # hold many of these — which is what UiAtlas does with it.
       def initialize(image, x:, y:, w:, h:, border:, scale: 1)
-        # A zero or negative scale would give every tile a step of zero pixels,
-        # and `#draw`'s tiling loops would never advance. Refusing it here costs
-        # nothing; a guard inside the loop would cost a branch per tile, per
-        # widget, per frame.
         raise ArgumentError, "nine-slice scale must be positive, got #{scale}" unless scale.positive?
 
         @scale = scale
@@ -69,10 +65,6 @@ module RGame
         r = @r * s
         t = @t * s
         b = @b * s
-        # These go negative for a rectangle narrower than its own borders, and
-        # are not clamped: #band refuses a non-positive size anyway, so clamping
-        # here would be a second guard that cannot change any outcome — and
-        # would read as if the case were handled in two places.
         inner_w = dw - l - r
         inner_h = dh - t - b
 
@@ -82,8 +74,6 @@ module RGame
         band(renderer, @left, dx, dy + t, l, inner_h, z, color)
         band(renderer, @right, dx + dw - r, dy + t, r, inner_h, z, color)
 
-        # Last, so a tile that reached the edge of its band is covered rather
-        # than showing through a corner's transparent pixels.
         piece(renderer, @tl, dx, dy, z, color)
         piece(renderer, @tr, dx + dw - r, dy, z, color)
         piece(renderer, @bl, dx, dy + dh - b, z, color)
@@ -92,10 +82,6 @@ module RGame
 
       private
 
-      # A uniform integer becomes four equal sides. Accepting both shapes here
-      # rather than in the callers is what makes `NineSlice.new(image, border: 7,
-      # ...)` work on its own — a bare integer would otherwise fail as
-      # `7[:left]`, which names nothing that appears in the caller's code.
       def normalize_border(border)
         return border.transform_keys(&:to_sym) unless border.is_a?(Integer)
 
@@ -122,11 +108,6 @@ module RGame
         @centre = cut(image, x + @l, y + @t, centre_w, centre_h)
       end
 
-      # A piece with no pixels is a legitimate part of a legitimate slice — a
-      # border with no centre column is a bar that only stretches vertically,
-      # and a zero border is one that does not stretch at all on that side. Such
-      # a piece is `nil` and simply never drawn; asking `Image#subimage` for it
-      # would raise.
       def cut(image, x, y, width, height)
         return nil unless width.positive? && height.positive?
 
@@ -139,8 +120,6 @@ module RGame
         renderer.image_at(image, x, y, scale_x: @scale, scale_y: @scale, z: z, color: color)
       end
 
-      # Repeats `image` across (bx, by, bw, bh), clipped to it so the trailing
-      # tile is cropped instead of overrunning into the next band.
       def band(renderer, image, bx, by, bw, bh, z, color)
         return if image.nil? || bw <= 0 || bh <= 0
 

data/lib/rgame/core/recording.rb

@@ -2,6 +2,7 @@
 
 require 'rgame/core_ext'
 require_relative '../util/color'
+require_relative '../util/z'
 
 module RGame
   module Core
@@ -37,6 +38,7 @@ module RGame
     #   renderer.clipped(0, 0, 400, 600) { ground.draw(0, 0) }
     class Recording
       Color = RGame::Util::Color
+      Z = RGame::Util::Z
 
       # Replays everything that was recorded, with the recording's origin at
       # (x, y).
@@ -45,7 +47,7 @@ module RGame
       # so white (the default) draws the recording unchanged and a colour with
       # alpha fades the whole layer out at once.
       def draw(x = 0, y = 0, z: 0, color: nil)
-        draw_at(x, y, z, Color.coerce(color).packed)
+        draw_at(x, y, Z.offset(z), Color.coerce(color).packed)
       end
     end
   end