dama 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 14c7877e7cada9427d3f09b1e191b57ff91f44e0d7d95bda7967a6d2a0ba6969
+  data.tar.gz: 6441a240b6637c45c54fbb1b7418780038ea024a97233a2ac11c883644690a19
+SHA512:
+  metadata.gz: 66edc610afd44d66c6a775d8157f236e1fca18197a4331875dbedd03c4473431e7059872651a9c27e5765c44c51354435b26f66875555f5f6ca5ca29147d357e
+  data.tar.gz: 389de5e6386731517d326d284a20369c265f6682f90495eed2b94d4b0f6466b0a89b08c4f1e4111c1528ffc80328eb420fc34c08297e364cb85d5ca9101a078c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Caiubi Fonseca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,227 @@
+<div align="center">
+  <img src="dama-logo.svg" alt="dama-rb" width="120">
+</div>
+
+<h1 align="center">dama-rb</h1>
+
+<p align="center">
+  A cross-platform 2D game engine with a Ruby DSL and Rust rendering backend.
+</p>
+
+<p align="center">
+  <strong>Write games in Ruby. Render with wgpu. Run native or in the browser.</strong>
+  <br />
+  <a href="https://github.com/caiubi/dama-rb">View Demo</a>
+</p>
+
+---
+
+dama-rb lets you build 2D games using an expressive Ruby DSL. The engine handles rendering via a Rust/wgpu backend (Metal, Vulkan, DX12, WebGPU), so your game code is pure Ruby while GPU-accelerated graphics run at native speed.
+
+The name "dama" is inspired by the Japanese word for "orb" (玉) and the Portuguese word for the "checkers" game (dama).
+
+## Screenshots
+
+<p align="center">
+  <img src="docs/checkers_screenshot.png" alt="Checkers" width="380">
+  <img src="docs/breakout_screenshot.png" alt="Breakout" width="380">
+</p>
+
+## Features
+
+- **Ruby DSL** — Standard CRuby 3.4 — bring your gems, your tools, your workflow
+- **Rust/wgpu renderer** — GPU-accelerated shapes, text, sprites, shaders, and textures
+- **Cross-platform** — Native (macOS, Linux, Windows) and web (WebGPU via ruby.wasm)
+- **Input handling** — Keyboard, mouse (gamepad support is on the [roadmap](#roadmap))
+- **Sprite rendering** — Draw textures from your assets folder
+- **Shader support** 🔥 — Write custom fragment shaders in WGSL (basic functions supported)
+- **Sound effects** — Play audio files within your game
+- **Physics** — AABB collision detection with a simple API (Rapier2D integration is on the [roadmap](#roadmap))
+- **HiDPI/Retina** — Sharp rendering on high-density displays
+- **100% test coverage** — RSpec with headless native backend integration tests (Web build pipeline coverage is on the [roadmap](#roadmap))
+- **MIT licensed** — Every feature, for everyone, forever
+
+## Build Your First Game
+
+### 1. Create a project
+
+```bash
+mkdir my_game && cd my_game
+bundle init
+bundle add dama
+```
+
+### 2. Scaffold the game
+
+```bash
+bundle exec dama new
+```
+
+This generates a playable starter project:
+
+```
+my_game/
+├── bin/dama                       # game launcher
+├── config.rb                      # game settings (resolution, title, start scene)
+├── game/
+│   ├── components/transform.rb    # position data
+│   ├── nodes/player.rb            # entity with drawing
+│   └── scenes/main_scene.rb      # composes nodes, handles input
+└── assets/                        # images, sounds, shaders
+```
+
+### 3. Run it
+
+```bash
+bin/dama               # native window
+bin/dama web           # browser (WebGPU)
+```
+
+You'll see a red circle you can move with the arrow keys.
+
+### 4. How it works
+
+dama-rb uses a **Component → Node → Scene** architecture:
+
+```ruby
+# Components hold pure data
+class Transform < Dama::Component
+  attribute :x, default: 0.0
+  attribute :y, default: 0.0
+end
+
+# Nodes are entities — they own components and define drawing
+class Player < Dama::Node
+  component Transform, as: :transform, x: 400.0, y: 300.0
+
+  draw do
+    circle(transform.x, transform.y, 20.0, **Dama::Colors::RED.to_h)
+  end
+end
+
+# Scenes compose nodes and handle game logic
+class MainScene < Dama::Scene
+  compose do
+    add Player, as: :hero
+  end
+
+  update do |dt, input|
+    hero.transform.x += 200.0 * dt if input.right?
+    hero.transform.x -= 200.0 * dt if input.left?
+  end
+end
+
+# config.rb boots the game — must define a GAME constant
+GAME = Dama::Game.new do
+  settings resolution: [800, 600], title: "My Game"
+  start_scene MainScene
+end
+```
+
+### 5. Make it yours
+
+- Edit `game/scenes/main_scene.rb` to change game logic
+- Add new nodes in `game/nodes/`
+- Add new components in `game/components/`
+- Put images, sounds, and shaders in `assets/`
+- See the [examples](examples/) for physics, sprites, shaders, and scene transitions
+
+## Architecture
+
+```
+Ruby DSL (your game code)
+    ↓
+Dama Engine (Ruby)
+    ↓ FFI / JS bridge
+Rust Backend (wgpu)
+    ↓
+GPU (Metal / Vulkan / WebGPU)
+```
+
+- **Ruby** handles game logic, scene graph, components, input, and the update loop
+- **Rust** handles window management (winit), GPU rendering (wgpu), text (glyphon), and screenshots
+- **Native**: Ruby calls Rust via FFI (cdylib)
+- **Web**: Ruby runs in ruby.wasm, calls Rust wasm via JS bridge
+
+## Drawing Primitives
+
+```ruby
+draw do
+  rect(x, y, w, h, r:, g:, b:, a:)
+  circle(cx, cy, radius, r:, g:, b:, a:)
+  triangle(x1, y1, x2, y2, x3, y3, r:, g:, b:, a:)
+  text("Hello", x, y, size: 24.0, r:, g:, b:, a:)
+  sprite(texture_handle, x, y, w, h)
+end
+```
+
+## Examples
+
+- **[demo](examples/demo/)** — Shapes, sprites, FPS overlay, keyboard input
+- **[checkers](examples/checkers/)** — Full 8x8 checkers game with piece selection, captures, king promotion, and scene transitions
+- **[breakout](examples/breakout/)** — Brick breaker with physics, custom shaders, and score tracking
+
+## Development
+
+### Prerequisites
+
+- Ruby 3.4+
+- Rust (stable, via rustup)
+- wasm-bindgen-cli (`cargo install wasm-bindgen-cli`)
+- npm (for downloading ruby.wasm base binary — web builds only)
+
+> **Note:** Web builds require `npm` (to download the ruby.wasm base binary) and `wasm-bindgen-cli`.
+
+### Setup
+
+```bash
+git clone https://github.com/caiubi/dama-rb
+cd dama-rb
+bundle install
+```
+
+### Tests
+
+```bash
+bundle exec rspec              # Ruby specs (builds Rust automatically)
+bundle exec rubocop            # Ruby linting
+cd ext/dama_native && cargo test     # Rust tests
+cd ext/dama_native && cargo clippy   # Rust linting
+```
+
+### Run examples
+
+```bash
+cd examples/checkers && bin/dama       # Native
+cd examples/checkers && bin/dama web   # Browser
+```
+
+## Roadmap
+
+### Rapier2D Physics
+- [ ] Replace AABB with Rapier2D behind Cargo feature flag
+- [ ] Continuous collision detection, joints, raycasting
+
+### Game Framework Features
+- [ ] Particle system
+- [ ] UI framework (Button, Label, Panel)
+- [ ] Tilemap (Tiled JSON format)
+- [ ] Scene transitions (fade in/out)
+- [ ] Save/Load (JSON, localStorage on web)
+
+### Polish & Community
+- [ ] Gamepad support
+- [ ] Documentation site (YARD + GitHub Pages)
+- [x] Project generator (`dama new my_game`)
+- [ ] Hot reload
+- [ ] Debug overlay
+- [ ] Publish gem to RubyGems
+
+### Web Integration Testing
+- [ ] Capybara-like + Cuprite browser tests
+- [ ] Game state assertion helpers
+- [ ] CI integration
+
+## License
+
+[MIT](LICENSE)

data/dama-logo.svg

@@ -0,0 +1,91 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="60 -50 500 500" role="img" aria-labelledby="title desc">
+  <title id="title">dama-rb logo</title>
+  <desc id="desc">A glossy red orb over a circular checkerboard base.</desc>
+
+  <defs>
+<radialGradient id="orbFill" cx="38%" cy="28%" r="65%">
+      <stop offset="0%" stop-color="#ff8d8d"/>
+      <stop offset="25%" stop-color="#ff2323"/>
+      <stop offset="70%" stop-color="#c30012"/>
+      <stop offset="100%" stop-color="#6c0008"/>
+    </radialGradient>
+
+    <radialGradient id="orbGlow" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#ff4d4d" stop-opacity="0.55"/>
+      <stop offset="100%" stop-color="#ff4d4d" stop-opacity="0"/>
+    </radialGradient>
+
+    <linearGradient id="ringTop" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#3d434a"/>
+      <stop offset="100%" stop-color="#111418"/>
+    </linearGradient>
+
+    <linearGradient id="ringSide" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#20252b"/>
+      <stop offset="100%" stop-color="#050607"/>
+    </linearGradient>
+
+    <filter id="softShadow" x="-30%" y="-30%" width="160%" height="160%">
+      <feDropShadow dx="0" dy="14" stdDeviation="14" flood-color="#000000" flood-opacity="0.28"/>
+    </filter>
+
+<clipPath id="iconClip">
+      <rect x="60" y="-50" width="500" height="500" rx="90"/>
+    </clipPath>
+
+    <clipPath id="topEllipseClip">
+      <ellipse cx="310" cy="250" rx="190" ry="74"/>
+    </clipPath>
+  </defs>
+
+  <!-- White rounded-corner background -->
+  <rect x="60" y="-50" width="500" height="500" rx="90" fill="#ffffff"/>
+
+  <g clip-path="url(#iconClip)">
+  <g filter="url(#softShadow)">
+    <!-- Base side -->
+    <ellipse cx="310" cy="286" rx="190" ry="74" fill="url(#ringSide)"/>
+
+    <!-- Checkerboard top clipped to ellipse -->
+    <g clip-path="url(#topEllipseClip)">
+      <rect x="120" y="176" width="380" height="148" fill="#f4f4f4"/>
+      <g fill="#111111">
+        <rect x="120" y="176" width="47.5" height="37"/>
+        <rect x="215" y="176" width="47.5" height="37"/>
+        <rect x="310" y="176" width="47.5" height="37"/>
+        <rect x="405" y="176" width="47.5" height="37"/>
+
+        <rect x="167.5" y="213" width="47.5" height="37"/>
+        <rect x="262.5" y="213" width="47.5" height="37"/>
+        <rect x="357.5" y="213" width="47.5" height="37"/>
+        <rect x="452.5" y="213" width="47.5" height="37"/>
+
+        <rect x="120" y="250" width="47.5" height="37"/>
+        <rect x="215" y="250" width="47.5" height="37"/>
+        <rect x="310" y="250" width="47.5" height="37"/>
+        <rect x="405" y="250" width="47.5" height="37"/>
+
+        <rect x="167.5" y="287" width="47.5" height="37"/>
+        <rect x="262.5" y="287" width="47.5" height="37"/>
+        <rect x="357.5" y="287" width="47.5" height="37"/>
+        <rect x="452.5" y="287" width="47.5" height="37"/>
+      </g>
+      <ellipse cx="310" cy="250" rx="190" ry="74" fill="url(#ringTop)" opacity="0.16"/>
+    </g>
+
+    <!-- Rim -->
+    <ellipse cx="310" cy="250" rx="190" ry="74" fill="none" stroke="#2c3138" stroke-width="16"/>
+    
+    <!-- Orb shadow on board -->
+    <ellipse cx="290" cy="250" rx="95" ry="28" fill="#3c0008" opacity="0.28"/>
+
+    <!-- Orb -->
+    <circle cx="255" cy="170" r="118" fill="url(#orbGlow)" opacity="0.9"/>
+    <circle cx="255" cy="170" r="102" fill="url(#orbFill)"/>
+    <ellipse cx="222" cy="130" rx="32" ry="22" fill="#ffffff" opacity="0.78" transform="rotate(-22 222 130)"/>
+    <ellipse cx="294" cy="197" rx="13" ry="10" fill="#ffb2b2" opacity="0.36"/>
+    <ellipse cx="322" cy="178" rx="18" ry="14" fill="#ff6b6b" opacity="0.22"/>
+    <circle cx="255" cy="170" r="102" fill="none" stroke="#8d000d" stroke-width="4" opacity="0.55"/>
+  </g>
+  </g>
+</svg>

data/exe/dama

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+require "dama"
+
+Dama::Cli.run(args: ARGV)

data/lib/dama/animation.rb

@@ -0,0 +1,66 @@
+module Dama
+  # Cycles through sprite sheet frames over time.
+  # Supports looping and one-shot animations.
+  class Animation
+    attr_reader :fps
+
+    def initialize(frames:, fps:, loop: true, on_complete: nil)
+      @frame_indices = frames.to_a
+      @fps = fps.to_f
+      @looping = loop
+      @on_complete = on_complete
+      @elapsed = 0.0
+      @frame_position = 0
+      @completed = false
+    end
+
+    def update(delta_time:)
+      return if completed
+
+      @elapsed += delta_time
+      frame_duration = 1.0 / fps
+      frames_advanced = (elapsed / frame_duration).to_i
+
+      return unless frames_advanced > frame_position
+
+      @frame_position = frames_advanced
+      handle_frame_advancement
+    end
+
+    def complete?
+      completed
+    end
+
+    def reset
+      @elapsed = 0.0
+      @frame_position = 0
+      @completed = false
+    end
+
+    def current_frame
+      frame_indices[frame_position % frame_indices.size]
+    end
+
+    private
+
+    attr_reader :frame_indices, :looping, :on_complete, :elapsed, :frame_position, :completed
+
+    def handle_frame_advancement
+      return if frame_position < frame_indices.size
+
+      finish_animation
+    end
+
+    def finish_animation
+      return loop_animation if looping
+
+      @frame_position = frame_indices.size - 1
+      @completed = true
+      on_complete&.call
+    end
+
+    def loop_animation
+      @frame_position = frame_position % frame_indices.size
+    end
+  end
+end

data/lib/dama/asset_cache.rb

@@ -0,0 +1,56 @@
+module Dama
+  # Reference-counted texture cache. Textures are loaded once and shared
+  # across all nodes that declare the same path. When the last node using
+  # a texture is removed, the texture is unloaded from the GPU.
+  class AssetCache
+    def initialize(backend:)
+      @backend = backend
+      @entries = {}
+    end
+
+    # Acquire a texture handle for the given path. Loads from disk on first
+    # use; subsequent calls increment the reference count and return the
+    # same handle.
+    def acquire(path:)
+      entry = entries[path]
+
+      return increment_and_return(entry) if entry
+
+      handle = backend.load_texture_file(path:)
+      entries[path] = { handle:, ref_count: 1 }
+      handle
+    end
+
+    # Release one reference to the texture at the given path. When the
+    # reference count reaches zero, the texture is unloaded from the GPU.
+    def release(path:)
+      entry = entries[path]
+      return unless entry
+
+      entry[:ref_count] -= 1
+      return unless entry[:ref_count] <= 0
+
+      backend.unload_texture(handle: entry.fetch(:handle))
+      entries.delete(path)
+    end
+
+    # Release all textures regardless of reference count.
+    def release_all
+      entries.each_value { |entry| backend.unload_texture(handle: entry.fetch(:handle)) }
+      entries.clear
+    end
+
+    def handle_for(path:)
+      entries.dig(path, :handle)
+    end
+
+    private
+
+    attr_reader :backend, :entries
+
+    def increment_and_return(entry)
+      entry[:ref_count] += 1
+      entry.fetch(:handle)
+    end
+  end
+end

data/lib/dama/audio.rb

@@ -0,0 +1,47 @@
+module Dama
+  # High-level audio interface for loading and playing sounds.
+  # Manages sound handles with reference counting (like AssetCache).
+  #
+  # Usage in a Node:
+  #   sound :jump, path: "assets/jump.wav"
+  #
+  # Usage in update:
+  #   Audio.play(:jump)
+  #   Audio.play(:theme, volume: 0.5, loop: true)
+  class Audio
+    attr_reader :backend
+
+    def initialize(backend:)
+      @backend = backend
+      @sounds = {}
+    end
+
+    def load(name:, path:)
+      handle = backend.load_sound(path:)
+      sounds[name] = handle
+    end
+
+    def play(name, volume: 1.0, loop: false)
+      handle = sounds.fetch(name)
+      backend.play_sound(handle:, volume:, loop:)
+    end
+
+    def stop_all
+      backend.stop_all_sounds
+    end
+
+    def unload(name)
+      handle = sounds.delete(name)
+      backend.unload_sound(handle:) if handle
+    end
+
+    def unload_all
+      sounds.each_value { |handle| backend.unload_sound(handle:) }
+      sounds.clear
+    end
+
+    private
+
+    attr_reader :sounds
+  end
+end

data/lib/dama/auto_loader.rb

@@ -0,0 +1,54 @@
+module Dama
+  # Discovers and loads all Ruby files in a game project directory.
+  # Handles dependency ordering automatically by retrying files
+  # that fail due to undefined constants.
+  class AutoLoader
+    MAX_PASSES = 10
+
+    def initialize(game_dir:)
+      @game_dir = game_dir
+    end
+
+    def load_all
+      files = discover_files
+      load_with_retries(files:)
+    end
+
+    private
+
+    attr_reader :game_dir
+
+    def discover_files
+      Dir[File.join(game_dir, "**", "*.rb")]
+    end
+
+    # Repeatedly attempt to load files, retrying those that fail
+    # with NameError (undefined constant — dependency not yet loaded).
+    # Stops when all files are loaded or no progress is made.
+    def load_with_retries(files:)
+      remaining = files.dup
+
+      MAX_PASSES.times do
+        failed = []
+
+        remaining.each do |file|
+          require file
+        rescue NameError
+          failed << file
+        end
+
+        return if failed.empty?
+
+        # No progress — the remaining files have unresolvable errors.
+        raise_load_error(failed:) if failed.size == remaining.size
+
+        remaining = failed
+      end
+    end
+
+    def raise_load_error(failed:)
+      # Try loading each failed file one more time to get the real error message.
+      failed.each { |file| require file }
+    end
+  end
+end