rgame 0.4.0-x86_64-linux-gnu

data/lib/rgame/util/z.rb

@@ -0,0 +1,123 @@
+# 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
+      SLOT = 1024
+      HALF = SLOT / 2
+
+      Z_MIN = -HALF
+      Z_MAX = HALF - 1
+
+      STRIDE = 1 << 40
+      SLOTS_PER_BAND = STRIDE / SLOT
+
+      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.
+      #
+      # @api private
+      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.
+      #
+      # @api private
+      # 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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'util/color'
+require_relative 'util/controls'
+require_relative 'util/route_search'
+require_relative 'util/save_file'
+require_relative 'util/solid_grid'
+require_relative 'util/tensor'
+require_relative 'util/tile_sweep'
+require_relative 'util/z'

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.4.0'
+end

data/lib/rgame.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative 'rgame/version'
+require_relative 'rgame/util'
+require_relative 'rgame/engine'

data/licenses/SDL2/LICENSE.txt

@@ -0,0 +1,18 @@
+Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
+  
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+  
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required. 
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.
+

metadata

@@ -0,0 +1,309 @@
+--- !ruby/object:Gem::Specification
+name: rgame
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: x86_64-linux-gnu
+authors:
+- Paul Süßenbach
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+description: |
+  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.
+
+  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:
+- rgame
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- docs/api/README.md
+- docs/api/app.md
+- docs/api/assets.md
+- docs/api/audio.md
+- docs/api/cli.md
+- docs/api/components.md
+- docs/api/drawing.md
+- docs/api/examples.md
+- docs/api/game.md
+- docs/api/images.md
+- docs/api/input.md
+- docs/api/internals.md
+- docs/api/localization.md
+- docs/api/scene_graph.md
+- docs/api/signals.md
+- docs/api/systems.md
+- docs/api/text.md
+- docs/api/tile_maps.md
+- docs/api/toolbox.md
+- docs/api/ui.md
+- docs/api/values.md
+- examples/assets/README.md
+- examples/assets/blip.ogg
+- examples/assets/glyphs.json
+- examples/assets/glyphs.png
+- examples/assets/hero.json
+- examples/assets/hero.png
+- examples/assets/icons.json
+- examples/assets/icons.png
+- examples/assets/music.ogg
+- examples/assets/skills.json
+- examples/assets/skills.png
+- examples/assets/tileset.png
+- examples/assets/tileset.tsx
+- examples/assets/town.tmx
+- examples/assets/ui.json
+- examples/assets/ui.png
+- examples/collision/locales/en.yml
+- examples/collision/main.rb
+- examples/collision_tiles/locales/en.yml
+- examples/collision_tiles/main.rb
+- examples/fullscreen/locales/en.yml
+- examples/fullscreen/main.rb
+- examples/game_menu/locales/en.yml
+- examples/game_menu/main.rb
+- examples/input_glyphs/locales/en.yml
+- examples/input_glyphs/main.rb
+- examples/jump_topdown/locales/en.yml
+- examples/jump_topdown/main.rb
+- examples/localization/locales/de.yml
+- examples/localization/locales/en.yml
+- examples/localization/main.rb
+- examples/menu_navigation/locales/en.yml
+- examples/menu_navigation/main.rb
+- examples/music/locales/en.yml
+- examples/music/main.rb
+- examples/pathfinding/locales/en.yml
+- examples/pathfinding/main.rb
+- examples/pooling/locales/en.yml
+- examples/pooling/main.rb
+- examples/quick_wheel/locales/en.yml
+- examples/quick_wheel/main.rb
+- examples/radial_menu/locales/en.yml
+- examples/radial_menu/main.rb
+- examples/save_load/locales/en.yml
+- examples/save_load/main.rb
+- examples/save_load_ids/locales/en.yml
+- examples/save_load_ids/main.rb
+- examples/scroll_map/locales/en.yml
+- examples/scroll_map/main.rb
+- examples/signals/locales/en.yml
+- examples/signals/main.rb
+- examples/skill_bar/locales/en.yml
+- examples/skill_bar/main.rb
+- examples/sound/locales/en.yml
+- examples/sound/main.rb
+- examples/split_screen/locales/en.yml
+- examples/split_screen/main.rb
+- examples/sprite/locales/en.yml
+- examples/sprite/main.rb
+- examples/timer/locales/en.yml
+- examples/timer/main.rb
+- examples/velocity/locales/en.yml
+- examples/velocity/main.rb
+- examples/walk/locales/en.yml
+- examples/walk/main.rb
+- exe/rgame
+- lib/rgame.rb
+- lib/rgame/boot.rb
+- lib/rgame/cli.rb
+- lib/rgame/cli/new_project.rb
+- lib/rgame/cli/templates/Gemfile.tt
+- lib/rgame/cli/templates/README.md.tt
+- lib/rgame/cli/templates/Rakefile.tt
+- lib/rgame/cli/templates/assets/locales/en.yml.tt
+- lib/rgame/cli/templates/game.rb.tt
+- lib/rgame/cli/templates/gitignore.tt
+- lib/rgame/cli/templates/main.rb.tt
+- lib/rgame/cli/templates/nodes/root.rb.tt
+- lib/rgame/cli/templates/rspec.tt
+- lib/rgame/cli/templates/rubocop.yml.tt
+- lib/rgame/cli/templates/ruby-version.tt
+- lib/rgame/cli/templates/spec/locales_spec.rb.tt
+- lib/rgame/cli/templates/spec/nodes/root_spec.rb.tt
+- lib/rgame/cli/templates/spec/spec_helper.rb.tt
+- 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/locale.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/core/virtual_gamepad.rb
+- lib/rgame/core_ext.so
+- lib/rgame/engine.rb
+- lib/rgame/engine/actor_blockers.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/bounds_blockers.rb
+- lib/rgame/engine/camera.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/box_collider.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
+- lib/rgame/engine/components/despawn_offscreen.rb
+- lib/rgame/engine/components/feet_collider.rb
+- lib/rgame/engine/components/hop.rb
+- lib/rgame/engine/components/identity.rb
+- lib/rgame/engine/components/mover.rb
+- lib/rgame/engine/components/navigator.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/components/world.rb
+- lib/rgame/engine/contact_set.rb
+- lib/rgame/engine/culling.rb
+- lib/rgame/engine/debug_overlay.rb
+- lib/rgame/engine/i18n.rb
+- lib/rgame/engine/i18n/plural.rb
+- lib/rgame/engine/i18n/plural_rules.rb
+- lib/rgame/engine/i18n/template.rb
+- lib/rgame/engine/input/action_mapper.rb
+- lib/rgame/engine/input/actions.rb
+- lib/rgame/engine/input/input_map.rb
+- lib/rgame/engine/layout.rb
+- lib/rgame/engine/nav_grid.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/presentation.rb
+- lib/rgame/engine/scene/scene_stack.rb
+- lib/rgame/engine/sealed_privates.rb
+- lib/rgame/engine/signal.rb
+- lib/rgame/engine/spatial_hash.rb
+- lib/rgame/engine/text.rb
+- lib/rgame/engine/tile_blockers.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/button.rb
+- lib/rgame/engine/ui/column.rb
+- lib/rgame/engine/ui/icon_button.rb
+- lib/rgame/engine/ui/menu.rb
+- lib/rgame/engine/ui/navigation.rb
+- lib/rgame/engine/ui/nine_slice_style.rb
+- lib/rgame/engine/ui/option_button.rb
+- lib/rgame/engine/ui/panel_button.rb
+- lib/rgame/engine/ui/panel_menu.rb
+- lib/rgame/engine/ui/pointing.rb
+- lib/rgame/engine/ui/radial_menu.rb
+- lib/rgame/engine/ui/ring.rb
+- lib/rgame/engine/ui/row.rb
+- lib/rgame/engine/ui/shape_style.rb
+- lib/rgame/engine/ui/stack.rb
+- lib/rgame/engine/ui/stepping.rb
+- lib/rgame/engine/ui/text_button.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
+- lib/rgame/rubocop.rb
+- lib/rgame/rubocop/cop/game/draw_in_local_space.rb
+- lib/rgame/rubocop/cop/game/hot_path.rb
+- lib/rgame/rubocop/cop/game/layer_boundary.rb
+- lib/rgame/rubocop/cop/game/no_core_in_engine_layer.rb
+- lib/rgame/rubocop/cop/game/no_engine_in_core_layer.rb
+- lib/rgame/rubocop/cop/game/no_interpolation_in_hot_path.rb
+- lib/rgame/rubocop/cop/game/no_literal_text.rb
+- lib/rgame/rubocop/cop/game/no_needless_allocation.rb
+- lib/rgame/rubocop/default.yml
+- lib/rgame/rubocop/plugin.rb
+- lib/rgame/util.rb
+- lib/rgame/util/color.rb
+- lib/rgame/util/controls.rb
+- lib/rgame/util/route_search.rb
+- lib/rgame/util/save_file.rb
+- lib/rgame/util/solid_grid.rb
+- lib/rgame/util/tensor.rb
+- lib/rgame/util/tile_sweep.rb
+- lib/rgame/util/z.rb
+- lib/rgame/util_ext.so
+- lib/rgame/version.rb
+- licenses/SDL2/LICENSE.txt
+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
+  changelog_uri: https://github.com/psuessenb/rgame/blob/main/CHANGELOG.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'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.3.22
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: A 2D game engine in C on SDL2 and OpenGL, exposed to Ruby.
+test_files: []