dama 0.1.0

data/lib/dama/backend/native/ffi_bindings.rb

@@ -0,0 +1,122 @@
+require "ffi"
+
+module Dama
+  module Backend
+    class Native
+      # Raw FFI bindings to the Rust cdylib. This is the only place in the
+      # Ruby codebase where FFI types appear. All other code interacts
+      # through the Backend::Native adapter.
+      module FfiBindings
+        extend FFI::Library
+
+        # Platform-specific shared library extension, resolved via hash
+        # lookup to avoid conditionals (per project coding guidelines).
+        LIBRARY_EXTENSIONS = {
+          "darwin" => "dylib",
+          "linux" => "so",
+          "mingw" => "dll",
+          "mswin" => "dll",
+        }.freeze
+
+        # Rust omits the "lib" prefix on Windows cdylibs (dama_native.dll
+        # instead of libdama_native.dll), so we need platform-aware names.
+        LIBRARY_PREFIXES = {
+          "darwin" => "lib",
+          "linux" => "lib",
+          "mingw" => "",
+          "mswin" => "",
+        }.freeze
+
+        def self.library_filename
+          platform_key = LIBRARY_EXTENSIONS.keys.detect { |k| RUBY_PLATFORM.include?(k) }
+          prefix = LIBRARY_PREFIXES.fetch(platform_key)
+          extension = LIBRARY_EXTENSIONS.fetch(platform_key)
+          "#{prefix}dama_native.#{extension}"
+        end
+
+        # Library resolution order:
+        # 1. DAMA_NATIVE_LIB env var — packaged games set this to their bundled copy
+        # 2. lib/dama/native/ — pre-compiled platform gems and source gem extconf.rb
+        #    install the shared library here
+        # 3. ext/dama_native/target/release/ — local development with cargo build
+        LIBRARY_PATH_RESOLVERS = [
+          lambda {
+            path = ENV.fetch("DAMA_NATIVE_LIB", nil)
+            path if path && File.exist?(path)
+          },
+          lambda {
+            path = File.expand_path("../../native/#{library_filename}", __dir__)
+            path if File.exist?(path)
+          },
+          lambda {
+            path = File.expand_path("../../../../ext/dama_native/target/release/#{library_filename}", __dir__)
+            path if File.exist?(path)
+          },
+        ].freeze
+
+        def self.library_path
+          LIBRARY_PATH_RESOLVERS.each do |resolver|
+            path = resolver.call
+            return path if path
+          end
+
+          raise "dama native library not found. Run `cargo build --release` in ext/dama_native/ " \
+                "or install a platform-specific gem."
+        end
+
+        ffi_lib library_path
+
+        # --- Lifecycle ---
+        attach_function :dama_engine_init_headless, %i[uint32 uint32], :int32
+        attach_function :dama_engine_init, %i[uint32 uint32 string], :int32
+        attach_function :dama_engine_shutdown, [], :int32
+        attach_function :dama_engine_poll_events, [], :int32
+        attach_function :dama_engine_begin_frame, [], :int32
+        attach_function :dama_engine_end_frame, [], :int32
+        attach_function :dama_engine_delta_time, [], :double
+        attach_function :dama_engine_frame_count, [], :uint64
+        attach_function :dama_engine_last_error, [], :string
+
+        # --- Rendering ---
+        attach_function :dama_render_clear, %i[float float float float], :int32
+        attach_function :dama_render_vertices, %i[pointer uint32], :int32
+        attach_function :dama_render_set_texture, [:uint64], :int32
+        attach_function :dama_render_text,
+                        %i[string float float float
+                           float float float float], :int32
+
+        # --- Assets ---
+        attach_function :dama_asset_load_texture, %i[pointer uint32], :uint64
+        attach_function :dama_asset_unload_texture, [:uint64], :int32
+
+        # --- Input ---
+        attach_function :dama_input_key_pressed, [:uint32], :int32
+        attach_function :dama_input_key_just_pressed, [:uint32], :int32
+        attach_function :dama_input_key_just_released, [:uint32], :int32
+        attach_function :dama_input_mouse_x, [], :float
+        attach_function :dama_input_mouse_y, [], :float
+        attach_function :dama_input_mouse_button_pressed, [:uint32], :int32
+
+        # --- Debug ---
+        attach_function :dama_debug_screenshot, [:string], :int32
+
+        # --- Fonts ---
+        attach_function :dama_font_load, [:string], :int32
+        attach_function :dama_render_text_with_font,
+                        %i[string float float float
+                           float float float float string], :int32
+
+        # --- Audio ---
+        attach_function :dama_audio_load_sound, [:string], :uint64
+        attach_function :dama_audio_play_sound, %i[uint64 float int32], :int32
+        attach_function :dama_audio_stop_all, [], :int32
+        attach_function :dama_audio_unload_sound, [:uint64], :int32
+
+        # --- Shaders ---
+        attach_function :dama_shader_load, [:string], :uint64
+        attach_function :dama_shader_unload, [:uint64], :int32
+        attach_function :dama_render_set_shader, [:uint64], :int32
+      end
+    end
+  end
+end

data/lib/dama/backend/native.rb

@@ -0,0 +1,191 @@
+module Dama
+  module Backend
+    # Native backend: calls the Rust cdylib through ruby-ffi.
+    # Shapes are decomposed into vertices in Ruby and submitted
+    # as a single batch per frame via dama_render_vertices.
+    class Native < Base
+      HEADLESS_INIT = lambda { |bindings, config|
+        bindings.dama_engine_init_headless(config.width, config.height)
+      }
+
+      # :nocov:
+      WINDOWED_INIT = ->(bindings, config) { bindings.dama_engine_init(config.width, config.height, config.title) }
+      # :nocov:
+
+      INIT_STRATEGIES = { true => HEADLESS_INIT, false => WINDOWED_INIT }.freeze
+
+      def initialize
+        @bindings = Native::FfiBindings
+        @vertex_batch = VertexBatch.new
+      end
+
+      def initialize_engine(configuration:)
+        strategy = INIT_STRATEGIES.fetch(configuration.headless)
+        result = strategy.call(bindings, configuration)
+        check_result(result:)
+      end
+
+      def shutdown
+        check_result(result: bindings.dama_engine_shutdown)
+      end
+
+      def poll_events
+        result = bindings.dama_engine_poll_events
+        result == 1
+      end
+
+      def begin_frame
+        check_result(result: bindings.dama_engine_begin_frame)
+      end
+
+      def end_frame
+        # Flush accumulated vertices to the GPU in one FFI call.
+        vertex_batch.flush(bindings:)
+        check_result(result: bindings.dama_engine_end_frame)
+      end
+
+      def delta_time
+        bindings.dama_engine_delta_time
+      end
+
+      def frame_count
+        bindings.dama_engine_frame_count
+      end
+
+      def clear(color: Dama::Colors::BLACK, r: color.r, g: color.g, b: color.b, a: color.a)
+        check_result(result: bindings.dama_render_clear(r, g, b, a))
+      end
+
+      def draw_triangle(x1:, y1:, x2:, y2:, x3:, y3:, color: Dama::Colors::WHITE,
+                        r: color.r, g: color.g, b: color.b, a: color.a, filled: true)
+        vertex_batch.push(Geometry::Triangle.vertices(x1:, y1:, x2:, y2:, x3:, y3:, r:, g:, b:, a:))
+      end
+
+      def draw_rect(x:, y:, w:, h:, color: Dama::Colors::WHITE,
+                    r: color.r, g: color.g, b: color.b, a: color.a, filled: true)
+        vertex_batch.push(Geometry::Rect.vertices(x:, y:, w:, h:, r:, g:, b:, a:))
+      end
+
+      def draw_circle(cx:, cy:, radius:, color: Dama::Colors::WHITE,
+                      r: color.r, g: color.g, b: color.b, a: color.a, filled: true, segments: 32)
+        vertex_batch.push(Geometry::Circle.vertices(cx:, cy:, radius:, r:, g:, b:, a:, segments:))
+      end
+
+      def draw_text(text:, x:, y:, size:, color: Dama::Colors::WHITE,
+                    r: color.r, g: color.g, b: color.b, a: color.a, font: nil)
+        vertex_batch.flush(bindings:)
+        result = if font
+                   bindings.dama_render_text_with_font(text, x, y, size, r, g, b, a, font)
+                 else
+                   bindings.dama_render_text(text, x, y, size, r, g, b, a)
+                 end
+        check_result(result:)
+      end
+
+      def load_font(path:)
+        check_result(result: bindings.dama_font_load(path))
+      end
+
+      def draw_sprite(texture_handle:, x:, y:, w:, h:, color: Dama::Colors::WHITE,
+                      r: color.r, g: color.g, b: color.b, a: color.a)
+        # Flush any untextured vertices, switch texture, push sprite, flush, reset.
+        vertex_batch.flush(bindings:)
+        check_result(result: bindings.dama_render_set_texture(texture_handle))
+        vertex_batch.push(Geometry::Sprite.vertices(x:, y:, w:, h:, r:, g:, b:, a:))
+        vertex_batch.flush(bindings:)
+        check_result(result: bindings.dama_render_set_texture(0))
+      end
+
+      def load_texture(bytes:)
+        ptr = FFI::MemoryPointer.new(:uint8, bytes.bytesize)
+        ptr.put_bytes(0, bytes)
+        handle = bindings.dama_asset_load_texture(ptr, bytes.bytesize)
+        raise "Failed to load texture" if handle.zero?
+
+        handle
+      end
+
+      def load_texture_file(path:)
+        load_texture(bytes: File.binread(path))
+      end
+
+      def unload_texture(handle:)
+        check_result(result: bindings.dama_asset_unload_texture(handle))
+      end
+
+      def screenshot(output_path:)
+        check_result(result: bindings.dama_debug_screenshot(output_path))
+      end
+
+      def key_pressed?(key_code:)
+        bindings.dama_input_key_pressed(key_code) == 1
+      end
+
+      def key_just_pressed?(key_code:)
+        bindings.dama_input_key_just_pressed(key_code) == 1
+      end
+
+      def key_just_released?(key_code:)
+        bindings.dama_input_key_just_released(key_code) == 1
+      end
+
+      def mouse_x
+        bindings.dama_input_mouse_x
+      end
+
+      def mouse_y
+        bindings.dama_input_mouse_y
+      end
+
+      def mouse_button_pressed?(button:)
+        bindings.dama_input_mouse_button_pressed(button) == 1
+      end
+
+      def load_sound(path:)
+        handle = bindings.dama_audio_load_sound(path)
+        raise "Failed to load sound: #{bindings.dama_engine_last_error}" if handle.zero?
+
+        handle
+      end
+
+      def play_sound(handle:, volume: 1.0, loop: false)
+        looping = loop ? 1 : 0
+        check_result(result: bindings.dama_audio_play_sound(handle, volume, looping))
+      end
+
+      def stop_all_sounds
+        check_result(result: bindings.dama_audio_stop_all)
+      end
+
+      def unload_sound(handle:)
+        check_result(result: bindings.dama_audio_unload_sound(handle))
+      end
+
+      def load_shader(source:)
+        bindings.dama_shader_load(source)
+      end
+
+      def unload_shader(handle:)
+        check_result(result: bindings.dama_shader_unload(handle))
+      end
+
+      def set_shader(handle:)
+        # Flush pending vertices before changing shader to ensure
+        # they render with the current shader, not the new one.
+        vertex_batch.flush(bindings:)
+        check_result(result: bindings.dama_render_set_shader(handle))
+      end
+
+      private
+
+      attr_reader :bindings, :vertex_batch
+
+      def check_result(result:)
+        return if result >= 0
+
+        error_msg = bindings.dama_engine_last_error
+        raise error_msg || "Unknown native engine error"
+      end
+    end
+  end
+end

data/lib/dama/backend/web.rb

@@ -0,0 +1,199 @@
+module Dama
+  module Backend
+    # Web backend: runs in ruby.wasm, sends high-level draw commands
+    # to the Rust wgpu wasm renderer via JavaScript bridge.
+    #
+    # Instead of decomposing shapes into triangles in Ruby (expensive in wasm),
+    # we send compact commands (9-14 floats each) and let Rust decompose them
+    # at native speed via dama_render_commands.
+    class Web < Base
+      def initialize
+        @frame_count = 0
+        @command_buffer = CommandBuffer.new
+      end
+
+      def initialize_engine(configuration:)
+        # On web, the engine is already initialized by index.html.
+        # Only call dama_init if not yet ready (avoids double-init replacing shaders).
+        w = configuration.width
+        h = configuration.height
+        ::JS.eval("if (!window.__damaReady) { window.damaWgpu.dama_init('game', #{w}, #{h}); }")
+      end
+
+      def shutdown; end
+      def poll_events = false
+
+      def begin_frame
+        command_buffer.clear
+        js_renderer.call(:dama_begin_frame)
+      end
+
+      def end_frame
+        flush_commands
+        js_renderer.call(:dama_end_frame)
+        @frame_count += 1
+      end
+
+      def delta_time
+        js_time[:delta].to_f
+      end
+
+      attr_reader :frame_count
+
+      def clear(color: Dama::Colors::BLACK, r: color.r, g: color.g, b: color.b, a: color.a)
+        js_renderer.call(:dama_clear, r, g, b, a)
+      end
+
+      def draw_triangle(x1:, y1:, x2:, y2:, x3:, y3:, color: Dama::Colors::WHITE,
+                        r: color.r, g: color.g, b: color.b, a: color.a, filled: true)
+        command_buffer.push_triangle(x1:, y1:, x2:, y2:, x3:, y3:, r:, g:, b:, a:)
+      end
+
+      def draw_rect(x:, y:, w:, h:, color: Dama::Colors::WHITE,
+                    r: color.r, g: color.g, b: color.b, a: color.a, filled: true)
+        command_buffer.push_rect(x:, y:, w:, h:, r:, g:, b:, a:)
+      end
+
+      def draw_circle(cx:, cy:, radius:, color: Dama::Colors::WHITE,
+                      r: color.r, g: color.g, b: color.b, a: color.a, filled: true, segments: 32)
+        command_buffer.push_circle(cx:, cy:, radius:, r:, g:, b:, a:, segments:)
+      end
+
+      def draw_text(text:, x:, y:, size:, color: Dama::Colors::WHITE,
+                    r: color.r, g: color.g, b: color.b, a: color.a, font: nil)
+        flush_commands
+        js_renderer.call(:dama_render_text, text, x, y, size, r, g, b, a)
+      end
+
+      def draw_sprite(texture_handle:, x:, y:, w:, h:, color: Dama::Colors::WHITE,
+                      r: color.r, g: color.g, b: color.b, a: color.a)
+        command_buffer.push_sprite(
+          texture_handle:, x:, y:, w:, h:, r:, g:, b:, a:,
+          u_min: 0.0, v_min: 0.0, u_max: 1.0, v_max: 1.0
+        )
+      end
+
+      def screenshot(output_path:); end
+
+      def key_pressed?(key_code:)
+        js_renderer.call(:dama_key_pressed, key_code).to_s == "true"
+      end
+
+      def key_just_pressed?(key_code:)
+        js_renderer.call(:dama_key_just_pressed, key_code).to_s == "true"
+      end
+
+      def key_just_released?(key_code:)
+        false
+      end
+
+      def mouse_x
+        js_renderer.call(:dama_mouse_x).to_f
+      end
+
+      def mouse_y
+        js_renderer.call(:dama_mouse_y).to_f
+      end
+
+      def mouse_button_pressed?(button:)
+        ::JS.eval("return !!window.damaMouseButtons[#{button}]").to_s == "true"
+      end
+
+      def load_texture(bytes:)
+        b64 = [bytes].pack("m0")
+        js_array = ::JS.eval("return Uint8Array.from(atob('#{b64}'), c => c.charCodeAt(0))")
+        from_bigint(js_renderer.call(:dama_load_texture, js_array))
+      end
+
+      def load_texture_file(path:)
+        load_texture(bytes: File.binread(path))
+      end
+
+      def unload_texture(handle:)
+        js_renderer.call(:dama_unload_texture, handle)
+      end
+
+      def load_sound(path:)
+        @next_sound_handle ||= 0
+        @next_sound_handle += 1
+
+        data = File.binread(path)
+        b64 = [data].pack("m0")
+        ::JS.eval("window.damaSounds = window.damaSounds || {}; " \
+                  "window.damaSounds[#{@next_sound_handle}] = 'data:audio/wav;base64,#{b64}'")
+        @next_sound_handle
+      end
+
+      def play_sound(handle:, volume: 1.0, loop: false)
+        loop_js = loop ? "a.loop = true;" : ""
+        ::JS.eval("(() => { const a = new Audio(window.damaSounds[#{handle}]); " \
+                  "a.volume = #{volume}; #{loop_js} a.play().catch(() => {}); })()")
+      end
+
+      def stop_all_sounds
+        ::JS.eval("document.querySelectorAll('audio').forEach(a => { a.pause(); a.currentTime = 0; })")
+      end
+
+      def unload_sound(handle:)
+        ::JS.eval("delete window.damaSounds[#{handle}]")
+      end
+
+      def load_font(path:); end
+
+      def load_shader(source:)
+        # Pass shader source via JS template literal to avoid ruby.wasm
+        # JsValue.call data corruption. Escape backticks and backslashes.
+        escaped = source.gsub("\\", "\\\\\\\\").gsub("`", "\\`")
+        result = ::JS.eval("return String(window.damaWgpu.dama_shader_load(`#{escaped}`))")
+        result.to_s.to_i
+      end
+
+      def unload_shader(handle:)
+        js_renderer.call(:dama_shader_unload, to_bigint(handle))
+      end
+
+      def set_shader(handle:)
+        # Merge shader switch INTO the next flush — don't send it separately.
+        # This avoids the ruby.wasm state persistence issue between JS.eval calls.
+        command_buffer.push_set_shader(shader_handle: handle)
+      end
+
+      private
+
+      attr_reader :command_buffer
+
+      def js_renderer
+        ::JS.global[:damaWgpu]
+      end
+
+      def js_time
+        ::JS.global[:damaTime]
+      end
+
+      # wasm-bindgen maps Rust u64 to JS BigInt.
+      # Ruby integers must be converted before passing to wasm.
+      def to_bigint(value)
+        ::JS.eval("return BigInt(#{value})")
+      end
+
+      # Convert a JS BigInt (from wasm u64 return) to Ruby integer.
+      # Uses BigInt.toString() → Ruby String#to_i for reliable conversion.
+      def from_bigint(js_bigint)
+        js_bigint.call(:toString).to_s.to_i
+      end
+
+      # Flush accumulated commands to Rust wasm via a single JS.eval call.
+      # We pass the data as a JSON array string and construct the Float32Array
+      # entirely in JS, because ruby.wasm's JsValue.call doesn't reliably pass
+      # typed arrays to wasm-bindgen functions.
+      def flush_commands
+        return if command_buffer.empty?
+
+        floats = command_buffer.to_a
+        json = floats.map { |f| f.to_f.to_s }.join(",")
+        ::JS.eval("window.damaWgpu.dama_render_commands(new Float32Array([#{json}]), #{floats.length})")
+        command_buffer.clear
+      end
+    end
+  end
+end

data/lib/dama/backend.rb

@@ -0,0 +1,13 @@
+module Dama
+  module Backend
+    PLATFORMS = {
+      web: -> { Backend::Web.new },
+      native: -> { Backend::Native.new },
+    }.freeze
+
+    def self.for
+      platform = defined?(JS) ? :web : :native
+      PLATFORMS.fetch(platform).call
+    end
+  end
+end

data/lib/dama/camera.rb

@@ -0,0 +1,68 @@
+module Dama
+  # 2D camera with position, zoom, follow, and viewport culling.
+  # All draw coordinates in a scene are translated/scaled through
+  # the camera before reaching the backend.
+  class Camera
+    MIN_ZOOM = 0.1
+    MAX_ZOOM = 10.0
+
+    attr_reader :x, :y, :zoom, :viewport_width, :viewport_height
+
+    def initialize(viewport_width:, viewport_height:, x: 0.0, y: 0.0, zoom: 1.0)
+      @viewport_width = viewport_width.to_f
+      @viewport_height = viewport_height.to_f
+      @x = x.to_f
+      @y = y.to_f
+      @zoom = zoom.to_f.clamp(MIN_ZOOM, MAX_ZOOM)
+    end
+
+    def move_to(x:, y:)
+      @x = x.to_f
+      @y = y.to_f
+    end
+
+    def move_by(dx:, dy:)
+      @x += dx.to_f
+      @y += dy.to_f
+    end
+
+    def zoom_to(level:)
+      @zoom = level.to_f.clamp(MIN_ZOOM, MAX_ZOOM)
+    end
+
+    # Converts world coordinates to screen pixel coordinates.
+    def world_to_screen(world_x:, world_y:)
+      {
+        screen_x: (world_x - x) * zoom,
+        screen_y: (world_y - y) * zoom,
+      }
+    end
+
+    # Converts screen pixel coordinates to world coordinates.
+    def screen_to_world(screen_x:, screen_y:)
+      {
+        world_x: (screen_x / zoom) + x,
+        world_y: (screen_y / zoom) + y,
+      }
+    end
+
+    # Returns true if a world-space rectangle overlaps the camera viewport.
+    def visible?(x:, y:, width:, height:)
+      screen = world_to_screen(world_x: x, world_y: y)
+      screen_w = width * zoom
+      screen_h = height * zoom
+
+      (screen.fetch(:screen_x) + screen_w).positive? &&
+        screen.fetch(:screen_x) < viewport_width &&
+        (screen.fetch(:screen_y) + screen_h).positive? &&
+        screen.fetch(:screen_y) < viewport_height
+    end
+
+    # Centers the camera on a target object (must respond to #x and #y).
+    # Use lerp < 1.0 for smooth following.
+    def follow(target:, lerp: 1.0)
+      @x += (target.x - x) * lerp
+      @y += (target.y - y) * lerp
+    end
+  end
+end

data/lib/dama/cli/new_project.rb

@@ -0,0 +1,112 @@
+require "fileutils"
+
+module Dama
+  class Cli
+    # Generates a new game project in the current directory.
+    # Creates the standard directory structure with starter files
+    # for a playable game: a red circle moveable with arrow keys.
+    class NewProject
+      FILE_PERMISSIONS = {
+        true => 0o755,
+        false => 0o644,
+      }.freeze
+
+      def self.run
+        new.generate
+      end
+
+      def generate
+        puts "Creating new dama game project..."
+
+        TEMPLATES.each do |path, template|
+          write_template(path:, template:)
+        end
+
+        create_directory("assets")
+
+        puts "\nDone! Run bin/dama to start your game."
+      end
+
+      private
+
+      def write_template(path:, template:)
+        full_path = File.join(Dir.pwd, path)
+        return puts("  exists  #{path}") if File.exist?(full_path)
+
+        FileUtils.mkdir_p(File.dirname(full_path))
+        File.write(full_path, template.fetch(:content))
+        FileUtils.chmod(FILE_PERMISSIONS.fetch(template.fetch(:executable)), full_path)
+        puts "  create  #{path}"
+      end
+
+      def create_directory(name)
+        return puts("  exists  #{name}/") if File.directory?(name)
+
+        FileUtils.mkdir_p(name)
+        puts "  create  #{name}/"
+      end
+
+      TEMPLATES = {
+        "config.rb" => {
+          content: <<~RUBY,
+            GAME = Dama::Game.new do
+              settings resolution: [800, 600], title: "My Game"
+              start_scene MainScene
+            end
+          RUBY
+          executable: false,
+        },
+        "bin/dama" => {
+          content: <<~RUBY,
+            #!/usr/bin/env ruby
+            require "bundler/setup"
+            require "dama"
+
+            Dama::Cli.run(args: ARGV, root: File.expand_path("..", __dir__))
+          RUBY
+          executable: true,
+        },
+        "game/components/transform.rb" => {
+          content: <<~RUBY,
+            class Transform < Dama::Component
+              attribute :x, default: 0.0
+              attribute :y, default: 0.0
+            end
+          RUBY
+          executable: false,
+        },
+        "game/nodes/player.rb" => {
+          content: <<~RUBY,
+            class Player < Dama::Node
+              component Transform, as: :transform, x: 400.0, y: 300.0
+
+              draw do
+                circle(transform.x, transform.y, 20.0, color: Dama::Colors::RED)
+              end
+            end
+          RUBY
+          executable: false,
+        },
+        "game/scenes/main_scene.rb" => {
+          content: <<~RUBY,
+            class MainScene < Dama::Scene
+              compose do
+                add Player, as: :hero
+              end
+
+              update do |dt, input|
+                speed = 200.0
+
+                hero.transform.x += speed * dt if input.right?
+                hero.transform.x -= speed * dt if input.left?
+                hero.transform.y += speed * dt if input.down?
+                hero.transform.y -= speed * dt if input.up?
+              end
+            end
+          RUBY
+          executable: false,
+        },
+      }.freeze
+    end
+  end
+end