dama 0.1.0

data/lib/dama/scene/composer.rb

@@ -0,0 +1,65 @@
+module Dama
+  class Scene
+    # Evaluates compose blocks to build the scene graph.
+    # Supports multiple forms of `add`:
+    #   add PlayerClass, as: :hero           # by Class
+    #   add :player, as: :hero               # by Symbol (auto-discover)
+    #   add "player", as: :hero              # by String (auto-discover)
+    #   add Player.new, as: :hero            # by Instance
+    #   add Player, as: :hero, tags: [:enemy] # with explicit tags
+    class Composer
+      RESOLVE_STRATEGIES = {
+        Symbol => ->(name, registry) { registry.resolve(name:, category: :node) },
+        String => ->(name, registry) { registry.resolve(name: name.to_sym, category: :node) },
+      }.freeze
+
+      def initialize(scene_graph:, registry:, scene:)
+        @scene_graph = scene_graph
+        @registry = registry
+        @scene = scene
+        @current_group = nil
+      end
+
+      def add(class_or_name_or_instance, as:, tags: [], **props, &block)
+        node_instance = resolve_and_build(class_or_name_or_instance, props)
+        instance_node = SceneGraph::InstanceNode.new(id: as, node: node_instance, tags:)
+        scene_graph.add(instance_node:, parent_group: current_group)
+
+        # Register the named accessor on the scene so `hero` works in update/enter.
+        scene.register_named_node(name: as, instance_node:)
+
+        instance_node.instance_eval(&block) if block
+      end
+
+      def camera(**)
+        scene.enable_camera(**)
+      end
+
+      def physics(gravity: [0.0, 0.0])
+        scene.enable_physics(gravity_x: gravity[0], gravity_y: gravity[1])
+      end
+
+      def group(name, &)
+        scene_graph.add_group(name:)
+        previous_group = current_group
+        @current_group = name
+        instance_eval(&)
+        @current_group = previous_group
+      end
+
+      private
+
+      attr_reader :scene_graph, :registry, :scene, :current_group
+
+      def resolve_and_build(class_or_name_or_instance, props)
+        return class_or_name_or_instance if class_or_name_or_instance.is_a?(Dama::Node)
+
+        return class_or_name_or_instance.new(**props) if class_or_name_or_instance.is_a?(Class)
+
+        strategy = RESOLVE_STRATEGIES.fetch(class_or_name_or_instance.class)
+        klass = strategy.call(class_or_name_or_instance, registry)
+        klass.new(**props)
+      end
+    end
+  end
+end

data/lib/dama/scene.rb

@@ -0,0 +1,233 @@
+module Dama
+  # Base class for game scenes. Scenes have a compose/enter/update
+  # lifecycle and manage a scene graph of nodes.
+  #
+  # Example:
+  #   class Level1 < Dama::Scene
+  #     sound :jump, path: "assets/sfx/jump.wav"
+  #
+  #     compose do
+  #       camera viewport_width: 800, viewport_height: 600
+  #       add Player, as: :hero
+  #     end
+  #
+  #     update do |dt, input|
+  #       hero.transform.x += 100 * dt if input.right?
+  #       play(:jump) if input.space?
+  #     end
+  #   end
+  class Scene # rubocop:disable Metrics/ClassLength
+    class << self
+      def compose(&block)
+        @compose_block = block
+      end
+
+      def enter(&block)
+        @enter_block = block
+      end
+
+      def update(&block)
+        @update_block = block
+      end
+
+      # Declare a sound asset at the class level.
+      # Loaded automatically during scene composition.
+      def sound(name, path:)
+        sound_declarations[name] = path
+      end
+
+      def sound_declarations
+        @sound_declarations ||= {}
+      end
+
+      attr_reader :compose_block, :enter_block, :update_block
+    end
+
+    attr_reader :camera
+
+    def initialize(registry:, asset_cache: nil, scene_switcher: nil, backend: nil)
+      @registry = registry
+      @asset_cache = asset_cache
+      @scene_switcher = scene_switcher
+      @backend = backend
+      @scene_graph = SceneGraph::Tree.new
+      @named_nodes = {}
+      @camera = nil
+      @audio = nil
+      @physics_world = nil
+      @collision_handlers = {}
+    end
+
+    # Play a sound declared via the `sound` class DSL.
+    def play(name)
+      audio&.play(name)
+    end
+
+    def enable_camera(viewport_width:, viewport_height:, **)
+      @camera = Camera.new(viewport_width:, viewport_height:, **)
+    end
+
+    # Enable physics for this scene. Called by `physics` DSL in composer.
+    def enable_physics(gravity_x: 0.0, gravity_y: 0.0)
+      event_bus = EventBus.new
+      @physics_world = Physics::World.new(gravity_x:, gravity_y:, event_bus:)
+
+      # Wire collision events to named handlers.
+      event_bus.on(:collision) do |collision:|
+        dispatch_collision(collision)
+      end
+    end
+
+    # Register a collision handler between two named nodes.
+    def on_collision(name_a, name_b, &block)
+      key = [name_a, name_b].sort
+      collision_handlers[key] = block
+    end
+
+    # Request a scene transition. The game applies it between frames.
+    def switch_to(scene_class)
+      scene_switcher&.call(scene_class)
+    end
+
+    def perform_compose
+      load_sounds
+      return unless self.class.compose_block
+
+      composer = Scene::Composer.new(scene_graph:, registry:, scene: self)
+      composer.instance_eval(&self.class.compose_block)
+    end
+
+    def perform_enter
+      return unless self.class.enter_block
+
+      instance_eval(&self.class.enter_block)
+    end
+
+    def perform_update(delta_time:, input:)
+      instance_exec(delta_time, input, &self.class.update_block) if self.class.update_block
+      physics_world&.step(delta_time:)
+    end
+
+    def perform_draw(backend:)
+      scene_graph.each_node do |instance_node|
+        draw_block = instance_node.node.class.draw_block
+        next unless draw_block
+
+        context = Node::DrawContext.new(node: instance_node.node, backend:, camera:)
+        context.instance_eval(&draw_block)
+      end
+    end
+
+    # Register a named node, load textures/shaders, and create physics body.
+    def register_named_node(name:, instance_node:)
+      named_nodes[name] = instance_node
+      define_singleton_method(name) { named_nodes.fetch(name) }
+
+      instance_node.node.load_textures(asset_cache:) if asset_cache
+      instance_node.node.load_shaders(backend:) if backend
+      create_physics_body(name:, node: instance_node.node)
+    end
+
+    # --- Query methods ---
+
+    def ref!(path)
+      scene_graph.query.by_path(path:)
+    end
+
+    def all(klass)
+      scene_graph.query.by_class(klass:)
+    end
+
+    def by_tag(tag)
+      scene_graph.query.by_tag(tag:)
+    end
+
+    def each(klass, &)
+      all(klass).each(&)
+    end
+
+    # Add a node dynamically at runtime (during update or enter).
+    def add(class_or_instance, as:, tags: [], group: nil, **props)
+      node_instance = build_node(class_or_instance, props)
+      instance_node = SceneGraph::InstanceNode.new(id: as, node: node_instance, tags: Array(tags))
+      scene_graph.add(instance_node:, parent_group: group)
+      register_named_node(name: as, instance_node:)
+      instance_node
+    end
+
+    # Remove a node, its physics body, and release its textures/shaders.
+    def remove(name)
+      instance_node = named_nodes.delete(name)
+      return unless instance_node
+
+      node = instance_node.node
+      node.unload_textures(asset_cache:) if asset_cache
+      node.unload_shaders(backend:) if backend
+      physics_world&.remove(node.physics) if node.physics
+
+      scene_graph.remove(id: name)
+    end
+
+    private
+
+    attr_reader :registry, :scene_graph, :named_nodes, :asset_cache,
+                :scene_switcher, :backend, :audio, :physics_world,
+                :collision_handlers
+
+    NODE_BUILDERS = {
+      Class => ->(klass, props) { klass.new(**props) },
+      :instance => ->(instance, _props) { instance },
+    }.freeze
+
+    def build_node(class_or_instance, props)
+      builder_key = class_or_instance.is_a?(Class) ? Class : :instance
+      NODE_BUILDERS.fetch(builder_key).call(class_or_instance, props)
+    end
+
+    # Load all class-level sound declarations via Audio.
+    def load_sounds
+      return if self.class.sound_declarations.empty?
+      return unless backend
+
+      @audio = Audio.new(backend:)
+      self.class.sound_declarations.each do |name, path|
+        audio.load(name:, path:)
+      end
+    end
+
+    COLLIDER_FACTORIES = {
+      rect: ->(opts) { Physics::Collider.rect(width: opts.fetch(:width), height: opts.fetch(:height)) },
+      circle: ->(opts) { Physics::Collider.circle(radius: opts.fetch(:radius)) },
+    }.freeze
+
+    # Create a physics body for a node if it declares `physics_body`.
+    def create_physics_body(name:, node:)
+      opts = node.class.physics_body_options
+      return unless opts && physics_world
+
+      collider_shape = opts.fetch(:collider, :rect)
+      collider = COLLIDER_FACTORIES.fetch(collider_shape).call(opts)
+      body = Physics::Body.new(
+        type: opts.fetch(:type, :dynamic),
+        mass: opts.fetch(:mass, 1.0),
+        collider:,
+        node:,
+        restitution: opts.fetch(:restitution, 0.0),
+      )
+      node.physics = body
+      physics_world.add(body)
+    end
+
+    # Route a collision event to the appropriate named handler.
+    def dispatch_collision(collision)
+      # Find node names for the two bodies.
+      name_a = named_nodes.key(named_nodes.values.find { |n| n.node == collision.body_a.node })
+      name_b = named_nodes.key(named_nodes.values.find { |n| n.node == collision.body_b.node })
+      return unless name_a && name_b
+
+      key = [name_a, name_b].sort
+      handler = collision_handlers[key]
+      handler&.call
+    end
+  end
+end

data/lib/dama/scene_graph/class_index.rb

@@ -0,0 +1,26 @@
+module Dama
+  module SceneGraph
+    # Indexes scene graph nodes by their Node class for fast lookup.
+    class ClassIndex
+      def initialize
+        @index = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def register(node:)
+        index[node.node.class] << node
+      end
+
+      def unregister(node:)
+        index[node.node.class].delete(node)
+      end
+
+      def by_class(klass:)
+        index.fetch(klass, [])
+      end
+
+      private
+
+      attr_reader :index
+    end
+  end
+end

data/lib/dama/scene_graph/group_node.rb

@@ -0,0 +1,27 @@
+module Dama
+  module SceneGraph
+    # A named container in the scene graph. Holds child nodes
+    # and supports polymorphic traversal.
+    class GroupNode
+      attr_reader :name, :children
+
+      def initialize(name:)
+        @name = name
+        @children = []
+      end
+
+      def <<(node)
+        children << node
+      end
+
+      def [](id)
+        children.detect { |child| child.id == id }
+      end
+
+      # Polymorphic traversal: delegates to each child.
+      def traverse(&)
+        children.each { |child| child.traverse(&) }
+      end
+    end
+  end
+end

data/lib/dama/scene_graph/instance_node.rb

@@ -0,0 +1,30 @@
+module Dama
+  module SceneGraph
+    # Wraps a live Node instance within the scene graph.
+    # Holds the id, tags, and delegates to the underlying Node.
+    class InstanceNode
+      attr_reader :id, :node, :tags
+
+      def initialize(id:, node:, tags: [])
+        @id = id
+        @node = node
+        @tags = tags
+      end
+
+      # Polymorphic traversal: yields self to the block.
+      def traverse(&block)
+        block.call(self)
+      end
+
+      def method_missing(method_name, ...)
+        return super unless node.respond_to?(method_name)
+
+        node.public_send(method_name, ...)
+      end
+
+      def respond_to_missing?(method_name, include_private = false)
+        node.respond_to?(method_name, include_private) || super
+      end
+    end
+  end
+end

data/lib/dama/scene_graph/path_selector.rb

@@ -0,0 +1,25 @@
+module Dama
+  module SceneGraph
+    # Resolves "group/node_id" path strings to nodes in the scene graph.
+    # Uses regex with named groups to parse the path (no split per CLAUDE.md).
+    class PathSelector
+      SEGMENT_PATTERN = %r{\A(?<group>[^/]+)/(?<node_id>[^/]+)\z}
+
+      def initialize(groups:)
+        @groups = groups
+      end
+
+      def resolve(path:)
+        match = path.match(SEGMENT_PATTERN)
+        raise ArgumentError, "Invalid path format: #{path}" unless match
+
+        group = groups.fetch(match[:group].to_sym)
+        group[match[:node_id].to_sym]
+      end
+
+      private
+
+      attr_reader :groups
+    end
+  end
+end

data/lib/dama/scene_graph/query.rb

@@ -0,0 +1,34 @@
+module Dama
+  module SceneGraph
+    # Unified query API for the scene graph. Provides by_id, by_class,
+    # by_tag, and by_path lookups.
+    class Query
+      def initialize(id_index:, tag_index:, class_index:, groups:)
+        @id_index = id_index
+        @tag_index = tag_index
+        @class_index = class_index
+        @path_selector = PathSelector.new(groups:)
+      end
+
+      def by_id(id:)
+        id_index.fetch(id)
+      end
+
+      def by_class(klass:)
+        class_index.by_class(klass:)
+      end
+
+      def by_tag(tag:)
+        tag_index.by_tag(tag:)
+      end
+
+      def by_path(path:)
+        path_selector.resolve(path:)
+      end
+
+      private
+
+      attr_reader :id_index, :tag_index, :class_index, :path_selector
+    end
+  end
+end

data/lib/dama/scene_graph/tag_index.rb

@@ -0,0 +1,26 @@
+module Dama
+  module SceneGraph
+    # Indexes scene graph nodes by their tags for fast lookup.
+    class TagIndex
+      def initialize
+        @index = Hash.new { |h, k| h[k] = [] }
+      end
+
+      def register(node:)
+        node.tags.each { |tag| index[tag] << node }
+      end
+
+      def unregister(node:)
+        node.tags.each { |tag| index[tag].delete(node) }
+      end
+
+      def by_tag(tag:)
+        index.fetch(tag, [])
+      end
+
+      private
+
+      attr_reader :index
+    end
+  end
+end

data/lib/dama/scene_graph/tree.rb

@@ -0,0 +1,65 @@
+module Dama
+  module SceneGraph
+    # Root container of the scene graph. Maintains flat indexes
+    # (by id, tag, class) and a hierarchy of groups for traversal.
+    class Tree
+      def initialize
+        @root_children = []
+        @id_index = {}
+        @tag_index = TagIndex.new
+        @class_index = ClassIndex.new
+        @groups = {}
+      end
+
+      def add(instance_node:, parent_group: nil)
+        target = parent_group ? groups.fetch(parent_group) : self
+        target << instance_node
+        id_index[instance_node.id] = instance_node
+        tag_index.register(node: instance_node)
+        class_index.register(node: instance_node)
+      end
+
+      def add_group(name:)
+        group = GroupNode.new(name:)
+        groups[name] = group
+        root_children << group
+        group
+      end
+
+      def <<(node)
+        root_children << node
+      end
+
+      def remove(id:)
+        node = id_index.delete(id)
+        return unless node
+
+        tag_index.unregister(node:)
+        class_index.unregister(node:)
+        remove_from_children(node:)
+      end
+
+      def query
+        @query ||= Query.new(id_index:, tag_index:, class_index:, groups:)
+      end
+
+      def each_node(&)
+        root_children.each { |child| child.traverse(&) }
+      end
+
+      # InstanceNode-like traversal protocol so Tree can be a container.
+      def traverse(&)
+        each_node(&)
+      end
+
+      private
+
+      attr_reader :root_children, :id_index, :tag_index, :class_index, :groups
+
+      def remove_from_children(node:)
+        root_children.delete(node)
+        groups.each_value { |group| group.children.delete(node) }
+      end
+    end
+  end
+end

data/lib/dama/scene_graph.rb

@@ -0,0 +1,4 @@
+module Dama
+  module SceneGraph
+  end
+end

data/lib/dama/sprite_sheet.rb

@@ -0,0 +1,36 @@
+module Dama
+  # Calculates UV coordinates for individual frames within a
+  # sprite sheet / texture atlas.
+  class SpriteSheet
+    attr_reader :frame_width, :frame_height, :columns, :rows, :frame_count
+
+    def initialize(texture_width:, texture_height:, frame_width:, frame_height:)
+      @frame_width = frame_width.to_f
+      @frame_height = frame_height.to_f
+      @texture_width = texture_width.to_f
+      @texture_height = texture_height.to_f
+      @columns = (texture_width / frame_width).to_i
+      @rows = (texture_height / frame_height).to_i
+      @frame_count = columns * rows
+    end
+
+    # Returns normalized UV coordinates for a given frame index.
+    # frame: 0-based index, left-to-right then top-to-bottom.
+    def frame_uv(frame:)
+      clamped = frame.clamp(0, frame_count - 1)
+      col = clamped % columns
+      row = clamped / columns
+
+      u = (col * frame_width) / texture_width
+      v = (row * frame_height) / texture_height
+      u2 = ((col + 1) * frame_width) / texture_width
+      v2 = ((row + 1) * frame_height) / texture_height
+
+      { u:, v:, u2:, v2: }
+    end
+
+    private
+
+    attr_reader :texture_width, :texture_height
+  end
+end

data/lib/dama/tween/easing.rb

@@ -0,0 +1,31 @@
+module Dama
+  class Tween
+    # Standard easing functions for use with Tween::Lerp.
+    # Each function maps a progress value t (0.0..1.0) to an eased value.
+    #
+    # Usage:
+    #   Tween::Lerp.new(target:, attribute:, from:, to:, duration:,
+    #                   easing: :ease_in_out_quad)
+    module Easing
+      FUNCTIONS = {
+        linear: ->(t) { t },
+
+        ease_in_quad: ->(t) { t * t },
+        ease_out_quad: ->(t) { t * (2.0 - t) },
+        ease_in_out_quad: ->(t) { t < 0.5 ? 2.0 * t * t : -1.0 + ((4.0 - (2.0 * t)) * t) },
+
+        ease_in_cubic: ->(t) { t * t * t },
+        ease_out_cubic: ->(t) { ((t - 1.0)**3) + 1.0 },
+        ease_in_out_cubic: lambda { |t|
+          t < 0.5 ? 4.0 * t * t * t : ((t - 1.0) * ((2.0 * t) - 2.0) * ((2.0 * t) - 2.0)) + 1.0
+        },
+
+        ease_in_out_sine: ->(t) { -(Math.cos(Math::PI * t) - 1.0) / 2.0 },
+      }.freeze
+
+      def self.fetch(name:)
+        FUNCTIONS.fetch(name)
+      end
+    end
+  end
+end

data/lib/dama/tween/lerp.rb

@@ -0,0 +1,35 @@
+module Dama
+  class Tween
+    # Interpolates a single attribute on a target object from a start value
+    # to an end value over a given duration, with optional easing.
+    class Lerp
+      def initialize(target:, attribute:, from:, to:, duration:, easing: :linear, on_complete: nil)
+        @target = target
+        @attribute = attribute
+        @from = from.to_f
+        @to = to.to_f
+        @duration = duration.to_f
+        @elapsed = 0.0
+        @easing_fn = Easing.fetch(name: easing)
+        @on_complete = on_complete
+      end
+
+      def update(delta_time:)
+        @elapsed += delta_time
+        linear_progress = [elapsed / duration, 1.0].min
+        eased_progress = easing_fn.call(linear_progress)
+        value = from + ((to - from) * eased_progress)
+        target.public_send(:"#{attribute}=", value)
+        on_complete&.call if complete?
+      end
+
+      def complete?
+        elapsed >= duration
+      end
+
+      private
+
+      attr_reader :target, :attribute, :from, :to, :duration, :elapsed, :easing_fn, :on_complete
+    end
+  end
+end

data/lib/dama/tween/manager.rb

@@ -0,0 +1,28 @@
+module Dama
+  class Tween
+    # Manages a collection of active tweens, updating them each
+    # frame and automatically removing completed ones.
+    class Manager
+      def initialize
+        @active_tweens = []
+      end
+
+      def add(tween:)
+        active_tweens << tween
+      end
+
+      def update(delta_time:)
+        active_tweens.each { |tween| tween.update(delta_time:) }
+        active_tweens.reject!(&:complete?)
+      end
+
+      def active?
+        active_tweens.any?
+      end
+
+      private
+
+      attr_reader :active_tweens
+    end
+  end
+end

data/lib/dama/tween.rb

@@ -0,0 +1,4 @@
+module Dama
+  class Tween
+  end
+end

data/lib/dama/version.rb

@@ -0,0 +1,3 @@
+module Dama
+  VERSION = "0.1.0".freeze
+end