rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/core/asset_manager.rb

@@ -0,0 +1,206 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module RGame
+  module Core
+    # The one place file-backed assets are loaded and cached.
+    #
+    #   app.assets.image('space.png')
+    #   app.assets.sheet('example 09/player.json')
+    #   app.assets.preload(:level1, image: ['lvl1/bg.png'], sound: ['lvl1/hit.ogg'])
+    #   app.assets.release(:level1)
+    #
+    # The built-in types are `image`, `sound`, `song` and `read`, plus the
+    # 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.
+    #
+    # Every accessor takes a path **relative to the media root** — or an
+    # absolute one, which is used as it stands — and returns the same object
+    # every time, so a file asked for twice is read, decoded and uploaded once.
+    # Two spellings of one path are one entry, not two. That is the whole point: loading stops being scattered
+    # across a game's setup code, building paths ad hoc and constructing images
+    # inline, and becomes one object that knows what is loaded.
+    #
+    # A game does not build one of these. `App#assets` does, rooted at the
+    # app's `media_root:`, on first use — see RGame::Core::App.
+    #
+    # ## Groups, and what `release` frees
+    #
+    # Each cached asset remembers the **set of groups** that asked for it.
+    # Ungrouped loads belong to {PERMANENT} and survive every `release`; only
+    # `clear` drops those. A grouped load is reference counted, so an asset two
+    # levels both loaded stays until both release it:
+    #
+    #   assets.image('ui/buttons.png')                    # PERMANENT
+    #   assets.preload(:level1, image: ['lvl1/bg.png'])   # :level1
+    #   assets.release(:level1)                           # drops lvl1/bg.png only
+    #
+    # Releasing drops this cache's reference. The GPU texture goes when the last
+    # reference anywhere goes, which is the collector's business, not this
+    # class's — see `Image.debug_live_textures` if you need to watch it happen.
+    #
+    # ## Composites share their parts
+    #
+    # A sprite sheet is a descriptor plus an image, and both are pulled *through
+    # this same cache*. So `assets.sheet('hero.json')` and
+    # `assets.image('hero.png')` hand back one upload between them, and the
+    # sheet's PNG is released with the sheet's group.
+    #
+    # ## Loaders are injectable, and that is deliberate
+    #
+    # Each asset type maps to a proc, and the defaults name `Image`, `Audio` and
+    # friends only *inside* their bodies — never at load time. Passing your own
+    # `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
+      PERMANENT = :__permanent__
+
+      # `app` is what images are loaded into and where the audio device comes
+      # from; `root` is what every path is resolved against.
+      def initialize(root:, app:, loaders: nil)
+        @root = root
+        @app = app
+        @loaders = {}
+        @cache = {}
+        @owners = {}
+
+        (loaders || default_loaders).each { |type, loader| add_loader(type, &loader) }
+      end
+
+      # Teaches this manager a new asset type, and gives it an accessor:
+      #
+      #   assets.add_loader(:tilemap) { |path| ... }
+      #   assets.tilemap('map/island.tmx')
+      #
+      # The built-in types go through this too, at construction — there is one
+      # mechanism, not a privileged set plus an extension point.
+      #
+      # It exists because some asset types cannot be built from inside
+      # `RGame::Core` at all. A tile map is the case that forced it: parsing a
+      # `.tmx` belongs to the engine layer, and Core may not name that layer
+      # (see CLAUDE.md, "The rule points both ways"). So the glue installs the
+      # loader, and Core never learns what a tile map is.
+      #
+      # Defining the accessor rather than routing everything through a generic
+      # `load(type, path)` keeps `assets.tilemap(path)` reading like the
+      # built-ins — and makes `respond_to?(:tilemap)` false until a loader
+      # exists, which is exactly what `Renderer#resolve_asset` asks before
+      # offering it an id.
+      def add_loader(type, &loader)
+        @loaders[type] = loader
+        define_singleton_method(type) { |path, group = PERMANENT| leaf(type, path, group) }
+        self
+      end
+
+      # The types this manager can load. `:image`, `:sound`, `:song` and `:read`
+      # are built in; anything else came from #add_loader.
+      def types = @loaders.keys
+
+      # A sprite sheet, assembled through the cache: its descriptor is a cached
+      # `read` and its image a cached `image`, so nothing is loaded twice.
+      def sheet(path, group = PERMANENT)
+        fetch(:sheet, path, group) { build_sprite_sheet(path, group) }
+      end
+
+      # A UI atlas, assembled the same way.
+      def ui_atlas(path, group = PERMANENT)
+        fetch(:ui_atlas, path, group) { build_ui_atlas(path, group) }
+      end
+
+      # Loads a set of assets under one group, so they can be released together:
+      #
+      #   assets.preload(:level1, image: ['lvl1/bg.png'], sheet: ['lvl1/foes.json'])
+      def preload(group, **manifest)
+        manifest.each do |type, paths|
+          unless respond_to?(type)
+            raise ArgumentError, "unknown asset type #{type.inspect} in preload(#{group.inspect})"
+          end
+
+          Array(paths).each { |path| public_send(type, path, group) }
+        end
+        self
+      end
+
+      # Takes `group` off every asset's owner set and drops whatever no group
+      # still holds.
+      def release(group)
+        raise ArgumentError, 'ungrouped assets are dropped by #clear, not #release' if group == PERMANENT
+
+        @owners.each_value { |groups| groups.delete(group) }
+        @owners.reject! do |key, groups|
+          next false unless groups.empty?
+
+          @cache.delete(key)
+          true
+        end
+        self
+      end
+
+      # Drops everything, PERMANENT included.
+      def clear
+        @cache.clear
+        @owners.clear
+        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
+
+      def default_loaders
+        {
+          image: ->(path) { Image.new(@app, path) },
+          sound: ->(path) { @app.audio.sample(path) },
+          song: ->(path) { @app.audio.song(path) },
+          read: ->(path) { File.read(path) }
+        }.freeze
+      end
+
+      def leaf(type, path, group)
+        fetch(type, path, group) { @loaders.fetch(type).call(resolve(path)) }
+      end
+
+      def resolve(path) = File.expand_path(path, @root)
+
+      def fetch(type, path, group)
+        key = [type, resolve(path)]
+        object = (@cache[key] ||= yield)
+        (@owners[key] ||= Set.new) << group
+        object
+      end
+
+      def build_sprite_sheet(relative_path, group)
+        SpriteSheet.new(*composite_parts(relative_path, group))
+      end
+
+      def build_ui_atlas(relative_path, group)
+        UiAtlas.new(*composite_parts(relative_path, group))
+      end
+
+      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
+
+      def sibling(relative_path, name)
+        directory = File.dirname(relative_path)
+        directory == '.' ? name : File.join(directory, name)
+      end
+    end
+  end
+end

data/lib/rgame/core/audio.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+
+module RGame
+  module Core
+    # The sound device: one per game, and the thing samples and songs are made
+    # from.
+    #
+    #   audio = RGame::Core::Audio.new
+    #   audio.volume = 0.8
+    #
+    # It is not tied to a window. Sound outlives a resized or recreated window
+    # and has nothing to do with a GL context, so nothing here takes an `app`.
+    #
+    # A machine with no sound hardware still gets a working `Audio` — it opens a
+    # null device and plays silently. That is deliberate: a game should run on a
+    # server, in a container, or on a laptop with the sound card disabled, and
+    # 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
+      # implement, which `Sample.new` is not.
+      def sample(path) = Sample.new(self, path)
+
+      # Loads a long one to stream. See {Song}.
+      def song(path) = Song.new(self, path)
+
+      #   audio.play_sound(:hit)
+
+      def register_sound(id, sample)
+        samples[id] = sample
+        self
+      end
+
+      def register_music(id, song)
+        songs[id] = song
+        self
+      end
+
+      # Plays a sample by id. Each call is another voice, layered over the ones
+      # already sounding.
+      def play_sound(id)
+        lookup(:sound, id).play
+      end
+
+      # 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 = lookup(:song, id)
+        return song if song.playing?
+
+        @playing_song = song
+        song.play(looping: true)
+      end
+
+      # Stops the song this registry started.
+      #
+      # Deliberately not "stop whatever is playing": the layer being replaced
+      # reached for a process-wide `current_song`, and there is no such global
+      # here by the decision that one-song-at-a-time is a game's policy rather
+      # than the engine's. A `Song` a game started by hand is its own to stop.
+      def stop_music
+        @playing_song&.stop
+        @playing_song = nil
+      end
+
+      private
+
+      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.
+    #
+    #   hit = RGame::Core::Sample.new(audio, 'assets/hit.ogg')
+    #   hit.volume = 0.5
+    #   hit.play
+    #   hit.play   # layers a second voice over the first
+    #
+    # Playing a sample that is already sounding starts *another* copy rather
+    # than restarting it, which is what makes footsteps and gunfire sound like
+    # themselves. There is no handle for a single play and no way to stop one;
+    # a sample is fire-and-forget. Volume belongs to the sample and applies to
+    # every voice it has out, including the ones already sounding.
+    #
+    # Ogg Vorbis and WAV are the formats the engine reads. Anything else, or an
+    # unreadable file, raises {Sample::LoadError}.
+    class Sample
+    end
+
+    # A long piece of music, streamed from disk rather than decoded up front.
+    #
+    #   music = RGame::Core::Song.new(audio, 'assets/theme.ogg')
+    #   music.play(looping: true)
+    #   music.playing?  # => true
+    #   music.stop
+    #
+    # Unlike a sample, a song is one voice: playing it while it plays restarts
+    # it from the beginning. Stopping and playing again also restarts — there is
+    # no pause.
+    #
+    # "Only one song at a time" is a rule a game keeps, not one this class
+    # enforces. Two songs can play at once, which is what a crossfade is.
+    class Song
+      # `looping:` is a keyword here and positional in C, which has no keywords.
+      def play(looping: false)
+        play_looping(looping)
+      end
+    end
+  end
+end

data/lib/rgame/core/font.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+
+module RGame
+  module Core
+    # A typeface at one pixel size, with a glyph atlas behind it.
+    #
+    #   font = RGame::Core::Font.new(app, 18)
+    #   font.height                    # => 18
+    #   font.text_width('Score: 1200') # => 78.4
+    #
+    #   renderer.text('Score: 1200', 10, 10, font: font)
+    #
+    # Two sizes are two fonts. Glyphs are rasterised the first time they are
+    # drawn and kept afterwards, so what a font costs is bounded by the
+    # characters a game actually uses — a score that changes every frame is free
+    # after the first ten digits.
+    #
+    # Measuring works anywhere; drawing, like everything else, only inside
+    # `draw`. That split is deliberate: laying out a menu happens while
+    # updating.
+    #
+    # ## The default font
+    #
+    # Passing no path uses the one the engine ships — Liberation Sans, which
+    # covers Western European languages including `ß`, `ẞ`, accents, `«»` and
+    # `€`. There is no font-*name* lookup and no system font database: a font is
+    # a file. That is what makes text render identically on every machine, which
+    # a system lookup cannot promise.
+    #
+    #   RGame::Core::Font.new(app, 18, path: 'assets/pixel.ttf')
+    #
+    # Scripts outside the shipped font's coverage — CJK, Arabic, Hebrew — need
+    # their own file. No font of this size covers them.
+    class Font
+      DEFAULT_PATH = File.expand_path('../fonts/LiberationSans-Regular.ttf', __dir__)
+
+      # `path:` is a keyword for callers but positional for the C initialize,
+      # which has no business knowing where a gem installs its data.
+      def self.new(app, pixel_height, path: DEFAULT_PATH)
+        super(app, pixel_height, path)
+      end
+    end
+  end
+end

data/lib/rgame/core/gamepad.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+require_relative '../util/controls'
+
+module RGame
+  module Core
+    # Which controllers are plugged in, and what they are called.
+    #
+    #   pads = RGame::Core::Gamepad.new(app)
+    #   pads.count                  # => 1
+    #   pads.connected?(0)          # => true
+    #   pads.name(0)                # => "Xbox Controller"
+    #
+    # This is a readout for menus — "Player 2: connect a controller" — not part
+    # of the frame path; reading a *button* goes through RGame::Core::Input.
+    #
+    # Slots are player slots, stable across a momentary unplug: a pad that falls
+    # out and comes back returns to the slot it had, so player 2 stays player 2.
+    # The engine reports arrivals and departures through the App's
+    # `gamepad_connected` / `gamepad_disconnected` callbacks; this class answers
+    # the same question by polling, which is what a menu redraw wants.
+    class Gamepad
+      Controls = RGame::Util::Controls
+
+      def initialize(app)
+        @app = app
+      end
+
+      # How many controllers are currently connected.
+      def count = @app.gamepad_count
+
+      # The number of player slots the engine supports, connected or not — the
+      # bound for a "controller setup" screen's loop.
+      def max_slots = Controls::MAX_GAMEPADS
+
+      def connected?(slot) = @app.gamepad_present?(slot)
+
+      # Human-readable name of the pad in `slot`, or nil when the slot is empty.
+      def name(slot) = @app.gamepad_name(slot)
+
+      # The input device id for a slot, so a menu that just found a pad can hand
+      # the right device to Input without knowing how devices are numbered.
+      def device(slot) = Controls.gamepad(slot)
+
+      # Yields [slot, name] for each connected pad, lowest slot first. Allocates
+      # nothing, so it is safe to call from a menu that redraws every frame.
+      def each_connected
+        return enum_for(:each_connected) unless block_given?
+
+        max_slots.times { |slot| yield slot, name(slot) if connected?(slot) }
+      end
+    end
+  end
+end

data/lib/rgame/core/image.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+
+module RGame
+  module Core
+    # A picture on the GPU, and the sprites cut out of it.
+    #
+    #   img = RGame::Core::Image.new(app, 'hero.png')
+    #   img.width                       # => 64
+    #   frame = img.subimage(0, 0, 16, 16)
+    #   walk  = RGame::Core::Image.load_tiles(app, 'hero.png', 16, 16)
+    #
+    # Everything below the constructor is a *view*: `subimage`, `tile` and
+    # `load_tiles` share the one texture the file was decoded into, so slicing a
+    # sheet into a hundred frames costs a hundred small objects and no extra
+    # video memory. The texture is released when the last view of it is
+    # collected, in whatever order that happens.
+    #
+    # Images are always sampled nearest-neighbour: this engine draws pixel art,
+    # and there is no setting to blur it.
+    #
+    # The class itself is defined in C (ext/rgame_core/ruby/image_ext.c); what is
+    # added here is the sheet-slicing convenience, which is a loop and belongs
+    # in Ruby.
+    class Image
+      # Every whole `tile_width` x `tile_height` tile of an image file, in
+      # reading order: left to right, then top to bottom. A partial tile along
+      # the right or bottom edge is padding and is skipped.
+      #
+      # The file is decoded and uploaded exactly once however many tiles come
+      # out of it — the returned images are views of that single texture.
+      def self.load_tiles(app, path, tile_width, tile_height)
+        new(app, path).tiles(tile_width, tile_height)
+      end
+
+      # This image sliced into whole tiles, as an Array. `load_tiles` is the
+      # same thing starting from a path.
+      def tiles(tile_width, tile_height)
+        Array.new(tile_count(tile_width, tile_height)) do |index|
+          tile(tile_width, tile_height, index)
+        end
+      end
+
+      # Yields each tile in turn, without building the Array.
+      def each_tile(tile_width, tile_height)
+        return enum_for(:each_tile, tile_width, tile_height) unless block_given?
+
+        tile_count(tile_width, tile_height).times do |index|
+          yield tile(tile_width, tile_height, index)
+        end
+      end
+    end
+  end
+end

data/lib/rgame/core/input.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+require_relative '../util/controls'
+
+module RGame
+  module Core
+    # Asks the engine whether a physical input is active, on a given device.
+    #
+    #   input = RGame::Core::Input.new(app)
+    #   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))
+    #
+    # **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.
+    #
+    # 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.
+    #
+    # 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. The intended answer for menus is keyboard and
+    # controller navigation instead.
+    class Input
+      Controls = RGame::Util::Controls
+
+      def initialize(app)
+        @app = app
+      end
+
+      # 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?(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(axis_id, device: Controls::KEYBOARD)
+        @app.input_axis(device, axis_id)
+      end
+    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