rgame 0.1.0 → 0.2.0

data/lib/rgame/util/z.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module RGame
+  module Util
+    # The vocabulary of draw order: which band a thing is drawn in, and how the
+    # single number the renderer sorts on is built out of one.
+    #
+    #   RGame::Util::Z::BANDS          # => [:world, :hud, :overlay, :debug]
+    #   RGame::Util::Z.base(:hud, 3)   # the fourth slot handed out in the HUD band
+    #
+    # These are values — plain Symbols and Integers with no window, GPU or OS
+    # handle behind them — so they live here rather than in Core, and both sides
+    # of the line may name them. `RGame::Engine` decides which band a node is
+    # in; `RGame::Core::Renderer` turns that into a z. Neither could reach the
+    # other's spelling of it, and the vocabulary is exactly what they have to
+    # agree on. Same reasoning as RGame::Util::Controls.
+    #
+    # ## Draw order is tree order, not a number a caller picks
+    #
+    # A frame's order is decided in three steps, coarsest first:
+    #
+    # 1. **The band.** Structural and inherited: everything in `:world` is under
+    #    everything in `:hud`, whatever either drew. Bands are 2**40 apart, so
+    #    no arithmetic below can carry one into the next.
+    # 2. **The slot.** The scene graph is walked depth-first with siblings in
+    #    `z` order, and each node takes the next slot in its band as it is
+    #    reached. Because the walk descends fully before moving on, a node's
+    #    subtree occupies one contiguous run of slots — which is what makes a
+    #    subtree atomic, and what stops some of a node's children landing in
+    #    front of a sibling the node itself is behind.
+    # 3. **The offset.** `Z_MIN..Z_MAX` inside the node's own slot, and the only
+    #    part a `z:` argument on a drawing call touches. It orders a node's
+    #    components against each other and its own draw calls against each
+    #    other, and it cannot reach the next node, let alone the next band.
+    #
+    # So a node's `z` is **only ever compared to its siblings'**. Its magnitude
+    # means nothing: `z: 1` and `z: 1_000_000` behave identically if they are
+    # the only two children, and negatives are ordinary.
+    #
+    # ## The arithmetic is exact
+    #
+    # Every value here is an integer below 2**42, and the `double` the draw
+    # queue sorts on is exact below 2**53. Two different slots can therefore
+    # never compare equal by rounding — which would show up as two sprites
+    # swapping places between frames, and would be very hard to see as a
+    # precision problem.
+    module Z
+      # How much room a node has for ordering its own drawing. Nothing in this
+      # repo uses more than three offsets; a thousand is room to stop thinking
+      # about it.
+      SLOT = 1024
+      HALF = SLOT / 2
+
+      # What a `z:` argument on a drawing call may be. Signed, because a node
+      # drawing something *behind* its sprite is as ordinary as drawing
+      # something in front of it, and the sprite's own default is 0.
+      Z_MIN = -HALF
+      Z_MAX = HALF - 1
+
+      # The gap between bands: 2**30 slots each, which no frame will approach.
+      STRIDE = 1 << 40
+      SLOTS_PER_BAND = STRIDE / SLOT
+
+      # In order, back to front.
+      #
+      # `:world` is what a node with no band ancestor is in, so a game that
+      # never mentions a band is entirely in it. `:hud` is one player's own
+      # screen space (RGame::Engine::PlayerLayer), `:overlay` is screen space
+      # across the whole window — a cutscene, a results panel — and `:debug` is
+      # the development overlay, over everything by construction.
+      BANDS = %i[world hud overlay debug].freeze
+      DEFAULT = :world
+
+      INDICES = BANDS.each_with_index.to_h.freeze
+
+      def self.band?(band) = INDICES.key?(band)
+
+      # Raises unless `band` names one. Called where a band is *set* rather than
+      # where it is used, so a typo surfaces at assignment with the list in the
+      # message instead of as a KeyError from inside a draw.
+      def self.band!(band)
+        return band if band?(band)
+
+        raise ArgumentError, "unknown z band #{band.inspect}; expected one of #{BANDS.inspect}"
+      end
+
+      # Which band this is, 0-based and back to front. This is what a renderer's
+      # slot counters are keyed on, so it is also where a bad band is caught.
+      def self.index(band)
+        INDICES[band] || band!(band)
+      end
+
+      # The z base of the `slot_index`-th slot in the band with that index.
+      # Offsets are measured from the middle of the slot, so Z_MIN..Z_MAX is
+      # symmetric — a node can draw behind its own sprite as easily as in front.
+      #
+      # Takes the band's *index* rather than its name because a renderer already
+      # has the index in hand (it counts slots per index), and looking the same
+      # Symbol up twice per node per frame is work with nothing to show for it.
+      # hot-path
+      def self.slot_base(band_index, slot_index)
+        if slot_index >= SLOTS_PER_BAND
+          raise RangeError,
+                "z band #{BANDS[band_index].inspect} is full at " \
+                "#{SLOTS_PER_BAND} slots per frame"
+        end
+
+        (band_index * STRIDE) + (slot_index * SLOT) + HALF
+      end
+
+      # The same thing by name, for a caller that has one rather than an index.
+      def self.base(band, slot_index) = slot_base(index(band), slot_index)
+
+      # Checks a `z:` argument and returns it. Drawing methods run this instead
+      # of trusting the caller, because the whole guarantee — that a node cannot
+      # draw outside its band — rests on the offset staying inside one slot.
+      # A stale global z (the bands used to be Integers a caller passed) lands
+      # here and says so rather than sorting somewhere surprising.
+      # hot-path
+      def self.offset(z)
+        raise TypeError, "no implicit conversion of #{z.class} into Float" unless z.is_a?(Numeric)
+
+        unless z.between?(Z_MIN, Z_MAX)
+          raise ArgumentError,
+                "z: #{z} is outside a node's slot (#{Z_MIN}..#{Z_MAX}); a `z:` orders one " \
+                'node\'s own drawing, and the band comes from the tree'
+        end
+
+        z
+      end
+    end
+  end
+end

data/lib/rgame/util.rb

@@ -6,3 +6,4 @@
 require_relative 'util/color'
 require_relative 'util/controls'
 require_relative 'util/tensor'
+require_relative 'util/z'

data/lib/rgame/version.rb

@@ -8,5 +8,5 @@
 # module here is enough; the extensions define `RGame` too, and doing so twice
 # is harmless.
 module RGame
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rgame
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Paul Süßenbach
@@ -10,16 +10,15 @@ 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.
+  RGame is a small 2D game engine for Ruby, written in Ruby and C. It's build
+  on top of SDL2, OpenGL and miniaudio. It's built with testability and
+  performance in mind, and aims to be an engine where you can write your whole
+  game code in Ruby, test it as usual with RSpec (or Minitest, or another test
+  framework) and still have acceptable performance.
 
-  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.
+  While still a work in progress, RGame aims to be more than a SDL/OpenGL
+  binding - it ships with high level features like a scene graph, sprites,
+  collision systems, debugging tools and an UI toolkit.
 email:
 - 2452696+psuessenb@users.noreply.github.com
 executables: []
@@ -28,6 +27,7 @@ extensions:
 - ext/rgame_util/extconf.rb
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - docs/api/README.md
@@ -45,6 +45,7 @@ files:
 - docs/api/systems.md
 - docs/api/text.md
 - docs/api/toolbox.md
+- docs/api/ui.md
 - docs/api/values.md
 - ext/README.md
 - ext/rgame_core/app/app.c
@@ -140,13 +141,13 @@ files:
 - 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/camera_follow.rb
 - lib/rgame/engine/components/character_body.rb
 - lib/rgame/engine/components/circle_collider.rb
 - lib/rgame/engine/components/collision_world.rb
@@ -162,14 +163,20 @@ files:
 - lib/rgame/engine/components/timer.rb
 - lib/rgame/engine/components/velocity.rb
 - lib/rgame/engine/components/wander_controller.rb
+- lib/rgame/engine/culling.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/input_map.rb
 - lib/rgame/engine/input/player_controller.rb
+- lib/rgame/engine/layout.rb
 - lib/rgame/engine/matrix.rb
 - lib/rgame/engine/node2d.rb
 - lib/rgame/engine/path.rb
+- lib/rgame/engine/player.rb
+- lib/rgame/engine/player_layer.rb
+- lib/rgame/engine/players.rb
 - lib/rgame/engine/pool.rb
 - lib/rgame/engine/resettable.rb
 - lib/rgame/engine/scene/scene_stack.rb
@@ -177,8 +184,14 @@ files:
 - lib/rgame/engine/spatial_hash.rb
 - lib/rgame/engine/tile_collision.rb
 - lib/rgame/engine/tile_map.rb
+- lib/rgame/engine/tile_map_layer.rb
 - lib/rgame/engine/tileset.rb
 - lib/rgame/engine/timer.rb
+- lib/rgame/engine/ui/menu.rb
+- lib/rgame/engine/ui/menu_item.rb
+- lib/rgame/engine/view.rb
+- lib/rgame/engine/viewports.rb
+- lib/rgame/engine/world_view.rb
 - lib/rgame/fonts/LiberationSans-Regular.ttf
 - lib/rgame/fonts/OFL.txt
 - lib/rgame/game.rb
@@ -186,6 +199,7 @@ files:
 - lib/rgame/util/color.rb
 - lib/rgame/util/controls.rb
 - lib/rgame/util/tensor.rb
+- lib/rgame/util/z.rb
 - lib/rgame/version.rb
 homepage: https://github.com/psuessenb/rgame
 licenses:
@@ -194,6 +208,7 @@ 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
+  changelog_uri: https://github.com/psuessenb/rgame/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:

data/lib/rgame/engine/camera_view.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module RGame
-  module Engine
-    # A node whose children live in *world* space and are drawn through a Camera: it
-    # wraps their draw in renderer.translated(-camera.x, -camera.y), so the camera's
-    # offset maps the world onto the screen. The children never know about the camera —
-    # they draw at their own absolute (world) origin, and the view transform does the
-    # rest. The owning scene drives the camera (e.g. centring it on the player); this
-    # node only applies it.
-    #
-    # The offset is a draw-time transform, not a position baked into a node, so the same
-    # world can later be drawn through several cameras (split-screen) by repeating the
-    # pass under different offsets/clips.
-    class CameraView < Node2D
-      def initialize(camera:, **)
-        super(**)
-        @camera = camera
-      end
-
-      private
-
-      def draw_children(renderer)
-        renderer.translated(-@camera.x, -@camera.y) { super }
-      end
-    end
-  end
-end