rgame 0.1.0

data/lib/rgame/core/asset_manager.rb

@@ -0,0 +1,224 @@
+# 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`. 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
+      # Owner of every ungrouped load. Never released, only cleared.
+      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 = {} # cache key => Set of groups holding it
+
+        (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
+        # 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
+
+      # 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)
+        # 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) }
+        @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
+
+      # 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) },
+          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
+
+      # 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)
+        (@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
+
+      # 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)
+      end
+    end
+  end
+end

data/lib/rgame/core/audio.rb

@@ -0,0 +1,124 @@
+# 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
+      # 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)
+
+      # --- 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)
+        samples[id] = sample
+        self
+      end
+
+      def register_music(id, song)
+        songs[id] = song
+        self
+      end
+
+      # Plays a registered sample. Each call is another voice, layered over the
+      # ones already sounding.
+      def play_sound(id)
+        samples.fetch(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.
+      def play_music(id)
+        song = songs.fetch(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 ||= {}
+    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,49 @@
+# 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
+      # 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,
+      # 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,77 @@
+# frozen_string_literal: true
+
+require 'rgame/core_ext'
+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.
+    #
+    #   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
+    #
+    # 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:
+    #
+    #   controls = RGame::Util::Controls
+    #   input = RGame::Core::Input.new(
+    #     app, bindings: controls::DEFAULT_KEYBOARD.merge(fire: controls::KEY_J)
+    #   )
+    #
+    # 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.
+    #
+    # **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.
+    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)
+        @app = app
+        @bindings = bindings
+        @pad_bindings = pad_bindings
+        @axis_bindings = axis_bindings
+      end
+
+      # Is the action's physical button 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.
+      # hot-path
+      def down?(action, device: Controls::KEYBOARD)
+        @app.input_down?(device, bindings_for(device).fetch(action))
+      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.
+      # 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
+      end
+    end
+  end
+end