rgame 0.1.0

data/lib/rgame/game.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+require_relative 'boot'
+require_relative 'core'
+require_relative 'engine'
+
+module RGame
+  # The entry point of a game, and the one class that knows both halves.
+  #
+  #   class HelloScene < RGame::Engine::Node2D
+  #     def on_draw(renderer) = renderer.text('Hello world!', 250, 200)
+  #   end
+  #
+  #   RGame::Game.new(root: HelloScene.new, caption: 'Hello').start
+  #
+  # A complete game is a root node plus that. `Game` assembles the pieces
+  # around it — the window and its loop, the renderer, the asset manager, the
+  # sound device, the input mapper, the debug overlay — and drives the root
+  # node once per tick.
+  #
+  # ## Why this class is allowed to name both layers
+  #
+  # `RGame::Engine` holds game concepts and may not name `RGame::Core`;
+  # `RGame::Core` owns handles and may not know Engine exists. Two RuboCop cops
+  # say so. Something still has to introduce them, and **this is that
+  # something** — see CLAUDE.md, "The rule points both ways". Keeping the
+  # introduction to one file is what makes the rule checkable everywhere else,
+  # so wiring belongs here and only here.
+  #
+  # The tile-map loader is the clearest case. Parsing a `.tmx` is Engine's job
+  # and drawing one is Core's, and neither may call the other, so `Game`
+  # installs the loader that joins them.
+  #
+  # ## The loop
+  #
+  # `Game` is an `App`, so it inherits the fixed-timestep loop rather than
+  # running one. Its hooks do three things: sample input once per frame, drive
+  # the root once per tick, and draw. Nothing here counts steps or measures
+  # time — `frame_loop.c` does that, and `update` is called once per whole tick.
+  class Game < RGame::Core::App
+    Controls = RGame::Util::Controls
+
+    WIDTH = 640
+    HEIGHT = 480
+
+    attr_reader :root, :renderer, :action_mapper
+
+    def initialize(root:, width: WIDTH, height: HEIGHT, caption: 'RGame',
+                   media_root: 'media', action_map: {})
+      super(width: width, height: height, caption: caption, media_root: media_root)
+
+      @root = root
+      @renderer = RGame::Core::Renderer.new(self)
+      @input = RGame::Core::Input.new(self)
+      @action_mapper = RGame::Engine::ActionMapper.new(action_map)
+      @overlay = RGame::Engine::DebugOverlay.new # always wired up; F1 reveals it
+      @dirty = true # draw the first frame
+
+      install_asset_loaders
+    end
+
+    # Brings the tree live and runs until the window closes.
+    #
+    # The root gets this object as its `context`, which is how a node deep in
+    # the tree reaches the asset manager (`node.root.context.assets`) without
+    # anything being threaded through its constructor.
+    def start
+      @root.context = self
+      @root.enter_tree # components attach, then on_add
+      run
+    end
+
+    # One fixed simulation tick. `dt` is always the engine's fixed step, so the
+    # tree never sees variable frame time.
+    #
+    # **Input is polled here, per tick, not in `frame_begin` per frame.** That
+    # is not where it started, and the reason is edge detection: `pressed?` is
+    # "held now, not held at the previous poll", so whatever polls decides what
+    # a press *is*. `frame_begin` runs once per rendered frame, and a loop that
+    # renders faster than it simulates runs it many times between two ticks —
+    # each one shifting the previous state, so the press is consumed by a poll
+    # no tick ever reads. Menus stop responding, and only on fast machines.
+    #
+    # Polling per tick costs nothing extra and loses nothing: the C layer
+    # snapshots the keyboard once per frame, so several ticks inside one frame
+    # read identical state, and the edge lands on the first of them — one press,
+    # one `pressed?`, which is what a caller means.
+    def update(dt)
+      @root.control(@action_mapper.poll(@input))
+      @root.update(dt)
+      @root.sweep_freed # flush queue_free'd nodes outside the update traversal
+      @dirty = true
+    end
+
+    # Only the simulation advancing makes the frame stale. While the overlay is
+    # up, redraw anyway, so its numbers stay live even when nothing is moving.
+    def needs_redraw? = @dirty || @overlay.visible?
+
+    def draw
+      @root.draw(@renderer)
+      @overlay.draw(@renderer, width, height, fps) # last, so it layers on top
+      @dirty = false
+    end
+
+    def button_down(id)
+      close if id == Controls::KEY_ESCAPE
+      @overlay.toggle if id == Controls::KEY_F1
+    end
+
+    private
+
+    # Teaches the asset manager the types Core cannot build for itself.
+    #
+    # `:tilemap` is the only one so far, and it is the reason this method
+    # exists: `RGame::Engine::TileMap` reads the `.tmx`, `Image#tiles` slices the
+    # tileset through the cache — so two maps sharing a tileset share one
+    # upload — and `Core::TileMapRenderer` draws the result. Three objects, and
+    # neither of the outer two may name the other.
+    def install_asset_loaders
+      game = self
+      assets.add_loader(:tilemap) do |path|
+        map, image_path = RGame::Engine::TileMap.load(path)
+        tiles = game.assets.image(image_path)
+                    .tiles(map.tileset.tile_width, map.tileset.tile_height)
+        RGame::Core::TileMapRenderer.new(map, tiles)
+      end
+    end
+  end
+end

data/lib/rgame/util/color.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# RGame::Util::Color is implemented in C — see ext/rgame_util/color_ext.c for
+# the Ruby binding and ext/rgame_util/color.c for the packing arithmetic.
+#
+#   Color = RGame::Util::Color
+#   Color.new(255, 128, 0)        # r, g, b, a defaults to 255
+#   Color.rgba(255, 128, 0, 200)  # the same thing, named
+#   Color.from_packed(0xFF8000FF) # 0xRRGGBBAA
+#   Color::WHITE                  # also BLACK and TRANSPARENT
+#
+#   c.r; c.g; c.b; c.a            # => Integer, 0..255
+#   c.packed                      # => Integer, 0xRRGGBBAA
+#
+# Instances are frozen and compare by value, so a Color works as a Hash key and
+# can be shared without anyone tinting it out from under its other holders.
+#
+# Every draw call accepts a colour as nil (white), [r, g, b], [r, g, b, a] or a
+# Color; `Color.coerce` is the single place that conversion happens.
+#
+# A colour is a *value* — no window, no GPU handle — so it lives in Util rather
+# than Core. That is what lets the engine layer hold one as an attribute; see
+# CLAUDE.md, "Value objects go in Util; only handle-owners go in Core".
+#
+# It loads from lib/rgame/util_ext.so, which `make ext-util` copies out of
+# ext/rgame_util/.
+require 'rgame/util_ext'

data/lib/rgame/util/controls.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module RGame
+  module Util
+    # The vocabulary of physical inputs: which integer means "the left arrow
+    # key", "the A button", "the left stick's X axis", "player 2's controller".
+    #
+    # These are values — plain integers with no window, GPU or OS handle behind
+    # them — so they live in Util rather than Core. That is what lets the engine
+    # layer and a game's own configuration name a physical input without
+    # touching RGame::Core, which they may not do:
+    #
+    #   bindings = Controls::DEFAULT_KEYBOARD.merge(fire: Controls::KEY_J)
+    #   RGame::Core::Input.new(app, bindings: bindings)
+    #
+    # The same numbers exist as `#define`s in
+    # ext/rgame_core/include/rgame/core.h, because the C engine and the
+    # standalone binary need them too and cannot see Ruby. Two definitions means
+    # a drift risk, so it is checked: the C side is tied to SDL's own scancodes
+    # by _Static_assert at compile time, and spec/rgame/util/controls_spec.rb
+    # parses that header and compares every value here against it.
+    module Controls
+      # --- Keyboard. Values are SDL scancodes. ---
+      KEY_RETURN = 40
+      KEY_ESCAPE = 41
+      KEY_SPACE = 44
+      KEY_F1 = 58
+      KEY_RIGHT = 79
+      KEY_LEFT = 80
+      KEY_DOWN = 81
+      KEY_UP = 82
+
+      # --- Gamepad buttons. The gamepad range plus SDL's controller button. ---
+      PAD_A = 4096
+      PAD_B = 4097
+      PAD_X = 4098
+      PAD_Y = 4099
+      PAD_BACK = 4100
+      PAD_GUIDE = 4101
+      PAD_START = 4102
+      PAD_LEFT_STICK = 4103
+      PAD_RIGHT_STICK = 4104
+      PAD_LEFT_SHOULDER = 4105
+      PAD_RIGHT_SHOULDER = 4106
+      PAD_DPAD_UP = 4107
+      PAD_DPAD_DOWN = 4108
+      PAD_DPAD_LEFT = 4109
+      PAD_DPAD_RIGHT = 4110
+
+      # --- Analog axes. Their own small space: they are float-valued and read
+      # through a different call, so folding them into the button space would
+      # only invite asking for an axis as if it were a button. ---
+      AXIS_LEFT_X = 0
+      AXIS_LEFT_Y = 1
+      AXIS_RIGHT_X = 2
+      AXIS_RIGHT_Y = 3
+      AXIS_TRIGGER_LEFT = 4
+      AXIS_TRIGGER_RIGHT = 5
+
+      # --- Devices. The keyboard is 0 so single-player code can leave it out;
+      # gamepads follow, one per player slot. ---
+      KEYBOARD = 0
+      GAMEPAD_FIRST = 1
+      MAX_GAMEPADS = 4
+
+      # The device id for a player slot: gamepad(0) is the first controller.
+      def self.gamepad(slot) = GAMEPAD_FIRST + slot
+
+      # --- Default bindings ---
+      #
+      # Symbolic action => physical input. Games override these to rebind; they
+      # are values, so a config screen can build its own table from the
+      # constants above and hand it to the input layer.
+      #
+      # Two button tables rather than one, because the same action is a
+      # different physical input per device class: :fire is the space bar on a
+      # keyboard and the A button on a pad.
+      DEFAULT_KEYBOARD = {
+        left: KEY_LEFT,
+        right: KEY_RIGHT,
+        up: KEY_UP,
+        down: KEY_DOWN,
+        confirm: KEY_RETURN,
+        fire: KEY_SPACE
+      }.freeze
+
+      DEFAULT_PAD = {
+        left: PAD_DPAD_LEFT,
+        right: PAD_DPAD_RIGHT,
+        up: PAD_DPAD_UP,
+        down: PAD_DPAD_DOWN,
+        confirm: PAD_A,
+        fire: PAD_A
+      }.freeze
+
+      # Analog axes exist only on pads, so there is one table.
+      DEFAULT_AXES = {
+        move_x: AXIS_LEFT_X,
+        move_y: AXIS_LEFT_Y,
+        aim_x: AXIS_RIGHT_X,
+        aim_y: AXIS_RIGHT_Y,
+        trigger_left: AXIS_TRIGGER_LEFT,
+        trigger_right: AXIS_TRIGGER_RIGHT
+      }.freeze
+    end
+  end
+end

data/lib/rgame/util/tensor.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# RGame::Util::Tensor is implemented in C — see ext/rgame_util/tensor.c. It used
+# to be a pure-Ruby class here; the public API (RGame::Util::Tensor.new(width,
+# height, depth, initial: nil), #[], #[]=, #width/#height/#depth) is unchanged,
+# only the backing implementation moved to C for speed and a compact flat-array
+# layout.
+#
+# The compiled extension is a separate .so from the SDL/GL engine, so requiring
+# Tensor pulls in no graphics libraries. It loads from lib/rgame/util_ext.so,
+# which the build (`make ext-util`) copies out of ext/rgame_util/.
+require 'rgame/util_ext'

data/lib/rgame/util.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# RGame::Util — everything that does NOT depend on SDL, OpenGL, or anything
+# built on them. Backed by the graphics-free extension in ext/rgame_util/.
+# Its counterpart is RGame::Core (see lib/rgame/core.rb).
+require_relative 'util/color'
+require_relative 'util/controls'
+require_relative 'util/tensor'

data/lib/rgame/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# The gem's version, and deliberately nothing else.
+#
+# rgame.gemspec loads this file directly to fill in `spec.version`, which
+# happens before either extension is compiled — so this file must never require
+# anything that reaches for `rgame/util_ext` or `rgame/core_ext`. Reopening the
+# module here is enough; the extensions define `RGame` too, and doing so twice
+# is harmless.
+module RGame
+  VERSION = '0.1.0'
+end

data/lib/rgame.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Entry point for `require "rgame"`: everything that runs without a window.
+#
+#   require 'rgame'         # RGame::Util + RGame::Engine — no graphics libraries
+#   require 'rgame/core'    # adds the window, the GPU and the sound device
+#   require 'rgame/game'    # all of it, wired together
+#
+# Each line is a strict superset of the one above, and the split is the point.
+# **This one loads no SDL and no OpenGL** — `RGame::Util` is a graphics-free
+# extension and `RGame::Engine` is pure Ruby — so game logic and the specs that
+# cover it run with no display present. `spec/rgame/no_graphics_spec.rb` holds
+# that up rather than leaving it to good intentions.
+#
+# Nothing is forced through this file. `rgame/util`, `rgame/engine` and
+# `rgame/core` are separately requirable, which is how the Core spec suite loads
+# exactly one layer and gets a `NameError` if it reaches for another.
+require_relative 'rgame/version'
+require_relative 'rgame/util'
+require_relative 'rgame/engine'

metadata

@@ -0,0 +1,215 @@
+--- !ruby/object:Gem::Specification
+name: rgame
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paul Süßenbach
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  rgame is a 2D game engine written in C on top of SDL2 and OpenGL and exposed
+  to Ruby as C extensions. It opens a window, runs a fixed-timestep main loop,
+  reads keyboard and controllers, loads PNGs onto the GPU and draws shapes and
+  sprites through a z-sorted batching renderer.
+
+  Everything Ruby-visible lives under the RGame module, split in two by what it
+  depends on. RGame::Core owns the window, the GPU and the OS handles;
+  RGame::Util holds the shareable value types and links no graphics libraries
+  at all, so `require "rgame"` gives you the pure half with no SDL or OpenGL in
+  the process and pure-logic code stays testable with no display.
+email:
+- 2452696+psuessenb@users.noreply.github.com
+executables: []
+extensions:
+- ext/rgame_core/extconf.rb
+- ext/rgame_util/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- docs/api/README.md
+- docs/api/app.md
+- docs/api/assets.md
+- docs/api/audio.md
+- docs/api/components.md
+- docs/api/drawing.md
+- docs/api/game.md
+- docs/api/images.md
+- docs/api/input.md
+- docs/api/internals.md
+- docs/api/scene_graph.md
+- docs/api/signals.md
+- docs/api/systems.md
+- docs/api/text.md
+- docs/api/toolbox.md
+- docs/api/values.md
+- ext/README.md
+- ext/rgame_core/app/app.c
+- ext/rgame_core/app/app_gl.h
+- ext/rgame_core/app/frame_loop.c
+- ext/rgame_core/app/frame_loop.h
+- ext/rgame_core/audio/audio.c
+- ext/rgame_core/audio/audio_internal.h
+- ext/rgame_core/audio/vorbis_decoder.c
+- ext/rgame_core/audio/vorbis_decoder.h
+- ext/rgame_core/example.rb
+- ext/rgame_core/extconf.rb
+- ext/rgame_core/graphics/backend.c
+- ext/rgame_core/graphics/backend.h
+- ext/rgame_core/graphics/canvas.c
+- ext/rgame_core/graphics/canvas.h
+- ext/rgame_core/graphics/clip.c
+- ext/rgame_core/graphics/clip.h
+- ext/rgame_core/graphics/draw_queue.c
+- ext/rgame_core/graphics/draw_queue.h
+- ext/rgame_core/graphics/gl_backend.c
+- ext/rgame_core/graphics/gl_backend.h
+- ext/rgame_core/graphics/image.c
+- ext/rgame_core/graphics/image_internal.h
+- ext/rgame_core/graphics/primitives.c
+- ext/rgame_core/graphics/primitives.h
+- ext/rgame_core/graphics/recording.c
+- ext/rgame_core/graphics/recording.h
+- ext/rgame_core/graphics/texture.c
+- ext/rgame_core/graphics/texture.h
+- ext/rgame_core/graphics/transform.c
+- ext/rgame_core/graphics/transform.h
+- ext/rgame_core/include/rgame/core.h
+- ext/rgame_core/input/device_slots.c
+- ext/rgame_core/input/device_slots.h
+- ext/rgame_core/input/gamepad.c
+- ext/rgame_core/input/gamepad.h
+- ext/rgame_core/input/input.c
+- ext/rgame_core/input/input.h
+- ext/rgame_core/ruby/audio_ext.c
+- ext/rgame_core/ruby/core_ext.c
+- ext/rgame_core/ruby/core_ext.h
+- ext/rgame_core/ruby/font_ext.c
+- ext/rgame_core/ruby/image_ext.c
+- ext/rgame_core/ruby/recording_ext.c
+- ext/rgame_core/ruby/renderer_ext.c
+- ext/rgame_core/text/atlas.c
+- ext/rgame_core/text/atlas.h
+- ext/rgame_core/text/font.c
+- ext/rgame_core/text/font.h
+- ext/rgame_core/text/font_atlas.c
+- ext/rgame_core/text/font_internal.h
+- ext/rgame_core/text/glyph_cache.c
+- ext/rgame_core/text/glyph_cache.h
+- ext/rgame_core/vendor/README.md
+- ext/rgame_core/vendor/miniaudio.h
+- ext/rgame_core/vendor/miniaudio_impl.c
+- ext/rgame_core/vendor/stb_image.h
+- ext/rgame_core/vendor/stb_image_impl.c
+- ext/rgame_core/vendor/stb_truetype.h
+- ext/rgame_core/vendor/stb_truetype_impl.c
+- ext/rgame_core/vendor/stb_vorbis.c
+- ext/rgame_core/vendor/stb_vorbis_impl.c
+- ext/rgame_util/color.c
+- ext/rgame_util/color.h
+- ext/rgame_util/color_ext.c
+- ext/rgame_util/extconf.rb
+- ext/rgame_util/tensor.c
+- ext/rgame_util/util_ext.c
+- ext/rgame_util/util_ext.h
+- lib/rgame.rb
+- lib/rgame/boot.rb
+- lib/rgame/core.rb
+- lib/rgame/core/app.rb
+- lib/rgame/core/asset_manager.rb
+- lib/rgame/core/audio.rb
+- lib/rgame/core/font.rb
+- lib/rgame/core/gamepad.rb
+- lib/rgame/core/image.rb
+- lib/rgame/core/input.rb
+- lib/rgame/core/nine_slice.rb
+- lib/rgame/core/recording.rb
+- lib/rgame/core/renderer.rb
+- lib/rgame/core/sprite_sheet.rb
+- lib/rgame/core/tile_map_renderer.rb
+- lib/rgame/core/ui_atlas.rb
+- lib/rgame/engine.rb
+- lib/rgame/engine/actor.rb
+- lib/rgame/engine/animation_set.rb
+- lib/rgame/engine/animator.rb
+- lib/rgame/engine/audio_bus.rb
+- lib/rgame/engine/audio_director.rb
+- lib/rgame/engine/body.rb
+- lib/rgame/engine/cached_label.rb
+- lib/rgame/engine/camera.rb
+- lib/rgame/engine/camera_view.rb
+- lib/rgame/engine/circle_collider.rb
+- lib/rgame/engine/collision_box.rb
+- lib/rgame/engine/collision_system.rb
+- lib/rgame/engine/component.rb
+- lib/rgame/engine/components/action_trigger.rb
+- lib/rgame/engine/components/animated_sprite.rb
+- lib/rgame/engine/components/character_body.rb
+- lib/rgame/engine/components/circle_collider.rb
+- lib/rgame/engine/components/collision_world.rb
+- lib/rgame/engine/components/despawn_offscreen.rb
+- lib/rgame/engine/components/path_follow.rb
+- lib/rgame/engine/components/player_controller.rb
+- lib/rgame/engine/components/pool.rb
+- lib/rgame/engine/components/screen_wrap.rb
+- lib/rgame/engine/components/sprite.rb
+- lib/rgame/engine/components/targeting.rb
+- lib/rgame/engine/components/thrust_controller.rb
+- lib/rgame/engine/components/tile_world.rb
+- lib/rgame/engine/components/timer.rb
+- lib/rgame/engine/components/velocity.rb
+- lib/rgame/engine/components/wander_controller.rb
+- lib/rgame/engine/debug_overlay.rb
+- lib/rgame/engine/i18n.rb
+- lib/rgame/engine/input/action_mapper.rb
+- lib/rgame/engine/input/actions.rb
+- lib/rgame/engine/input/player_controller.rb
+- lib/rgame/engine/matrix.rb
+- lib/rgame/engine/node2d.rb
+- lib/rgame/engine/path.rb
+- lib/rgame/engine/pool.rb
+- lib/rgame/engine/resettable.rb
+- lib/rgame/engine/scene/scene_stack.rb
+- lib/rgame/engine/signal.rb
+- lib/rgame/engine/spatial_hash.rb
+- lib/rgame/engine/tile_collision.rb
+- lib/rgame/engine/tile_map.rb
+- lib/rgame/engine/tileset.rb
+- lib/rgame/engine/timer.rb
+- lib/rgame/fonts/LiberationSans-Regular.ttf
+- lib/rgame/fonts/OFL.txt
+- lib/rgame/game.rb
+- lib/rgame/util.rb
+- lib/rgame/util/color.rb
+- lib/rgame/util/controls.rb
+- lib/rgame/util/tensor.rb
+- lib/rgame/version.rb
+homepage: https://github.com/psuessenb/rgame
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/psuessenb/rgame
+  bug_tracker_uri: https://github.com/psuessenb/rgame/issues
+  documentation_uri: https://github.com/psuessenb/rgame/blob/main/docs/api/README.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '4.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.10
+specification_version: 4
+summary: A 2D game engine in C on SDL2 and OpenGL, exposed to Ruby.
+test_files: []