anima-core 0.2.1 → 1.0.0

data/skills/dragonruby/SKILL.md

@@ -0,0 +1,250 @@
+---
+name: dragonruby
+description: "DragonRuby 2D game development — game loops, sprites, input, collisions, scenes. Activate when building games with DragonRuby/DRGTK, working with args.outputs/state/inputs, or editing game files."
+---
+
+# DragonRuby Game Toolkit
+
+This skill provides comprehensive guidance for building 2D games with DragonRuby Game Toolkit (DRGTK). Use for game loop implementation, sprite rendering, input handling, collision detection, animation, and scene management.
+
+## Quick Reference
+
+### Basic Game Structure
+
+```ruby
+def boot args
+  args.state = {}
+end
+
+def tick args
+  # Called 60 times per second
+  args.state.player ||= { x: 640, y: 360, w: 50, h: 50, path: 'player.png' }
+
+  # Handle input
+  args.state.player.x += 5 if args.inputs.right
+  args.state.player.x -= 5 if args.inputs.left
+
+  # Render
+  args.outputs.sprites << args.state.player
+end
+```
+
+### Key Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| `def tick(args)` | Main game loop (60 FPS) |
+| `args.outputs` | Render sprites, labels, primitives |
+| `args.state` | Persistent game data storage |
+| `args.inputs` | Keyboard, mouse, controller input |
+| `args.grid` | Screen dimensions (1280x720) |
+| `Geometry` | Collision detection helpers |
+
+### Coordinate System
+
+- **Screen**: 1280x720 pixels
+- **Origin**: Bottom-left (0, 0)
+- **Y-axis**: Increases upward
+
+```
+(0, 720) ─────────────── (1280, 720)
+    │                        │
+    │     1280 × 720         │
+    │                        │
+(0, 0) ─────────────── (1280, 0)
+```
+
+## Rendering Primitives
+
+Use `args.outputs.primitives` for FIFO (first-in, first-out) render order control.
+
+### Sprites (Images)
+
+```ruby
+args.outputs.primitives << {
+  x: 100, y: 100, w: 64, h: 64,
+  path: 'sprites/player.png',
+  angle: 45,
+  anchor_x: 0.5, anchor_y: 0.5,
+  r: 255, g: 255, b: 255, a: 255,
+  flip_horizontally: false
+}
+```
+
+### Labels (Text)
+
+```ruby
+args.outputs.primitives << {
+  x: 640, y: 360,
+  text: "Score: #{args.state.score}",
+  size_px: 22,
+  anchor_x: 0.5, anchor_y: 0.5,
+  r: 255, g: 255, b: 255
+}
+```
+
+### Solids and Borders
+
+```ruby
+# Filled rectangle (use primitive_marker: :solid)
+args.outputs.primitives << {
+  x: 0, y: 0, w: 100, h: 100,
+  r: 255, g: 0, b: 0,
+  primitive_marker: :solid
+}
+
+# For many rectangles, use path: :solid for better performance
+args.outputs.primitives << { x: 0, y: 0, w: 100, h: 100, path: :solid, r: 255, g: 0, b: 0 }
+
+# Outline rectangle
+args.outputs.primitives << { x: 0, y: 0, w: 100, h: 100, r: 0, g: 0, b: 0, primitive_marker: :border }
+```
+
+## State Management
+
+Use `args.state` with `||=` for lazy initialization:
+
+```ruby
+def tick args
+  args.state.player ||= { x: 640, y: 360 }
+  args.state.enemies ||= []
+  args.state.score ||= 0
+  args.state.scene ||= :title
+end
+```
+
+## Input Handling
+
+### Unified Input (Keyboard + Controller)
+
+```ruby
+# Directional (arrows, WASD, gamepad)
+args.inputs.up / down / left / right
+
+# Magnitude values
+args.inputs.left_right  # -1, 0, or 1
+args.inputs.up_down     # -1, 0, or 1
+```
+
+### Keyboard
+
+```ruby
+args.inputs.keyboard.key_down.space   # Pressed this frame
+args.inputs.keyboard.key_held.space   # Held down
+args.inputs.keyboard.key_up.space     # Released this frame
+```
+
+### Mouse
+
+```ruby
+args.inputs.mouse.click               # Any button clicked
+args.inputs.mouse.x / .y              # Position
+args.inputs.mouse.inside_rect?(rect)  # Collision check
+```
+
+## Collision Detection
+
+```ruby
+if Geometry.intersect_rect?(player, enemy)
+  enemy.dead = true
+  args.state.score += 1
+end
+
+# Clean up dead entities
+args.state.enemies.reject! { |e| e.dead }
+```
+
+## Animation
+
+```ruby
+# Frame-based animation
+sprite_index = 0.frame_index(count: 6, hold_for: 8, repeat: true)
+args.state.player.path = "sprites/player-#{sprite_index}.png"
+```
+
+## Scene Management
+
+```ruby
+def tick args
+  args.state.scene ||= :title
+  send("#{args.state.scene}_tick", args)
+end
+
+def title_tick args
+  args.outputs.labels << { x: 640, y: 400, text: "Press SPACE", anchor_x: 0.5 }
+  args.state.scene = :gameplay if args.inputs.keyboard.key_down.space
+end
+
+def gameplay_tick args
+  # Game logic here
+end
+```
+
+## Best Practices
+
+### Do
+
+- Use hash syntax for sprites/labels (clearer than arrays)
+- Use `||=` for state initialization
+- Remove offscreen entities to prevent memory leaks
+- Update logic before rendering
+- Use `$gtk.reset` during development to reset state
+- Use `args.outputs.primitives` for FIFO render order control
+- Use `primitive_marker: :solid` or `:border` for rectangle types
+
+### Don't
+
+- Hardcode magic numbers (use constants like `FPS = 60`)
+- Forget early returns in scene methods
+- Render before updating state (causes 1-frame lag)
+- Let collections grow infinitely (reject dead entities)
+
+## Additional Resources
+
+### Reference Files
+
+For detailed API documentation and patterns:
+
+- **`references/core.md`** - Game loop, args object, rendering, coordinates
+- **`references/input.md`** - Keyboard, mouse, controller input patterns
+- **`references/entities.md`** - Entity spawning, collision, lifecycle
+- **`references/game-logic/state.md`** - Timers, scoring, scene transitions
+- **`references/game-logic/persistence.md`** - Save/load, file I/O patterns
+- **`references/audio.md`** - Sound effects, music playback, audio controls
+- **`references/rendering/primitives.md`** - Sprites, labels, solids, borders, layering
+- **`references/rendering/animation.md`** - frame_index, spritesheets, easing functions
+
+### Example Files
+
+Working code in `examples/`:
+
+- **`examples/core/`** - Hello world, sprites, labels, state, coordinates
+- **`examples/input/`** - Directional, keyboard, mouse, movement
+- **`examples/entities/`** - Storage, factories, collision, lifecycle
+- **`examples/game-logic/`** - Timers, scoring, save/load, state transitions
+- **`examples/audio/`** - Sound effects, background music, pause/resume
+- **`examples/rendering/`** - Sprites, labels, animation, layering
+
+## Development Workflow
+
+```ruby
+def tick args
+  # Game logic
+end
+
+$gtk.reset  # Add at end during development
+```
+
+### Reset Methods
+
+```ruby
+$gtk.reset            # Immediate reset
+$gtk.reset_next_tick  # Reset before next tick (safer)
+```
+
+### Debug Output
+
+```ruby
+args.outputs.debug << "Frame: #{Kernel.tick_count}"
+args.outputs.debug.watch args.state.player
+```

data/skills/dragonruby/examples/audio/audio_events.rb

@@ -0,0 +1,55 @@
+# audio_events.rb
+# Sound effects triggered by game events
+
+def tick(args)
+  defaults(args)
+  input(args)
+  calc(args)
+  render(args)
+end
+
+def defaults(args)
+  args.state.player ||= { x: 640, y: 360, w: 50, h: 50, dy: 0 }
+  args.state.coins  ||= [{ x: 700, y: 360, w: 30, h: 30 }]
+  args.state.timer  ||= 0
+end
+
+def input(args)
+  player = args.state.player
+
+  # Sound on input event (jump)
+  if args.inputs.keyboard.key_down.space && player.dy == 0
+    args.outputs.sounds << "sounds/jump.wav"
+    player.dy = 10
+  end
+end
+
+def calc(args)
+  player = args.state.player
+
+  # Gravity
+  player.dy -= 0.5
+  player.y += player.dy
+  player.y = 360 if player.y <= 360
+  player.dy = 0 if player.y == 360
+
+  # Sound on collision event (coin pickup)
+  args.state.coins.reject! do |coin|
+    if player.intersect_rect?(coin)
+      args.outputs.sounds << { path: "sounds/coin.wav", gain: 0.8 }
+      true
+    end
+  end
+
+  # Sound on timer event (every 3 seconds)
+  args.state.timer += 1
+  if args.state.timer.zmod?(180)
+    args.outputs.sounds << { path: "sounds/ambient.wav", gain: 0.3 }
+  end
+end
+
+def render(args)
+  args.outputs.solids << args.state.player
+  args.outputs.solids << args.state.coins.map { |c| c.merge(r: 255, g: 200, b: 0) }
+  args.outputs.labels << { x: 10, y: 720, text: "SPACE to jump (input event)" }
+end

data/skills/dragonruby/examples/audio/background_music.rb

@@ -0,0 +1,29 @@
+# background_music.rb
+# Looping music using args.audio[:key]
+
+def tick(args)
+  # Initialize music once - loops automatically
+  if Kernel.tick_count == 0
+    args.audio[:music] = {
+      input:   "sounds/music.ogg",  # Path to music file
+      gain:    0.8,                  # Volume (0.0 to 1.0)
+      looping: true                  # Loop when finished
+    }
+  end
+
+  # Stop music with Q key
+  if args.inputs.keyboard.key_down.q
+    args.audio[:music] = nil
+  end
+
+  # Start music with P key (if stopped)
+  if args.inputs.keyboard.key_down.p && !args.audio[:music]
+    args.audio[:music] = { input: "sounds/music.ogg", looping: true }
+  end
+
+  status = args.audio[:music] ? "Playing" : "Stopped"
+  args.outputs.labels << [
+    { x: 640, y: 400, text: "Music: #{status}", alignment_enum: 1 },
+    { x: 640, y: 360, text: "P = Play | Q = Stop", alignment_enum: 1 }
+  ]
+end

data/skills/dragonruby/examples/audio/crossfade.rb

@@ -0,0 +1,51 @@
+# crossfade.rb
+# Smooth crossfade between two music tracks
+
+def tick(args)
+  defaults(args)
+  update_crossfade(args)
+  input(args)
+  render(args)
+end
+
+def defaults(args)
+  return if args.audio[:track_a]
+
+  # Initialize two tracks - one playing, one silent
+  args.audio[:track_a] = { input: "sounds/music.ogg", gain: 1.0, looping: true }
+  args.audio[:track_b] = { input: "sounds/music2.ogg", gain: 0.0, looping: true }
+  args.state.active_track = :track_a
+end
+
+def update_crossfade(args)
+  active = args.state.active_track
+  inactive = active == :track_a ? :track_b : :track_a
+
+  # Fade in active track
+  if args.audio[active]
+    args.audio[active].gain = (args.audio[active].gain + 0.01).clamp(0, 1)
+  end
+
+  # Fade out inactive track
+  if args.audio[inactive]
+    args.audio[inactive].gain = (args.audio[inactive].gain - 0.01).clamp(0, 1)
+  end
+end
+
+def input(args)
+  # Swap tracks on SPACE
+  if args.inputs.keyboard.key_down.space
+    args.state.active_track = args.state.active_track == :track_a ? :track_b : :track_a
+  end
+end
+
+def render(args)
+  a_vol = (args.audio[:track_a]&.gain.to_f * 100).to_i
+  b_vol = (args.audio[:track_b]&.gain.to_f * 100).to_i
+
+  args.outputs.labels << [
+    { x: 640, y: 400, text: "Press SPACE to crossfade", alignment_enum: 1 },
+    { x: 640, y: 360, text: "Track A: #{a_vol}%", alignment_enum: 1 },
+    { x: 640, y: 330, text: "Track B: #{b_vol}%", alignment_enum: 1 }
+  ]
+end

data/skills/dragonruby/examples/audio/music_controls.rb

@@ -0,0 +1,51 @@
+# music_controls.rb
+# Music controls: pause, volume, seeking
+
+def tick(args)
+  defaults(args)
+  input(args)
+  render(args)
+end
+
+def defaults(args)
+  return if args.audio[:music]
+
+  args.audio[:music] = {
+    input:   "sounds/music.ogg",
+    looping: true,
+    gain:    0.5,
+    paused:  false
+  }
+end
+
+def input(args)
+  music = args.audio[:music]
+  return unless music
+
+  # Toggle pause
+  music.paused = !music.paused if args.inputs.keyboard.key_down.space
+
+  # Volume control
+  if args.inputs.keyboard.key_down.up
+    music.gain = (music.gain + 0.1).clamp(0, 1)
+  elsif args.inputs.keyboard.key_down.down
+    music.gain = (music.gain - 0.1).clamp(0, 1)
+  end
+
+  # Seeking
+  if args.inputs.keyboard.key_down.right
+    music.playtime += 5
+  elsif args.inputs.keyboard.key_down.left
+    music.playtime = [music.playtime - 5, 0].max
+  end
+end
+
+def render(args)
+  music = args.audio[:music]
+  args.outputs.labels << [
+    { x: 10, y: 700, text: "SPACE: #{music.paused ? 'Resume' : 'Pause'}" },
+    { x: 10, y: 670, text: "UP/DOWN: Volume (#{(music.gain * 100).to_i}%)" },
+    { x: 10, y: 640, text: "LEFT/RIGHT: Seek (+/- 5s)" },
+    { x: 10, y: 610, text: "Position: #{music.playtime.to_i}s" }
+  ]
+end

data/skills/dragonruby/examples/audio/sound_effects.rb

@@ -0,0 +1,30 @@
+# sound_effects.rb
+# One-shot sound effects using args.outputs.sounds
+
+def tick(args)
+  args.state.notes ||= [:c3, :d3, :e3, :f3, :g3, :a3, :b3, :c4]
+
+  # Basic sound playback - add path string
+  if args.inputs.mouse.click
+    args.outputs.sounds << "sounds/#{args.state.notes.sample}.wav"
+  end
+
+  # Sound with volume control - use hash
+  if args.inputs.keyboard.key_down.space
+    args.outputs.sounds << {
+      path: "sounds/#{args.state.notes.sample}.wav",
+      gain: 0.5  # Volume: 0.0 to 1.0
+    }
+  end
+
+  # Multiple sounds at once
+  if args.inputs.keyboard.key_down.enter
+    args.outputs.sounds << "sounds/jump.wav"
+    args.outputs.sounds << { path: "sounds/coin.wav", gain: 0.3 }
+  end
+
+  args.outputs.labels << [
+    { x: 640, y: 400, text: "Click or SPACE for sounds", alignment_enum: 1 },
+    { x: 640, y: 360, text: "ENTER for multiple sounds", alignment_enum: 1 }
+  ]
+end

data/skills/dragonruby/examples/core/coordinate_system.rb

@@ -0,0 +1,27 @@
+# Demonstrates DragonRuby's coordinate system
+# Origin (0, 0) is at BOTTOM-LEFT corner
+# Screen size is 1280 x 720 by default
+
+def tick args
+  # Show mouse position (updates in real-time)
+  pos = args.inputs.mouse.position
+  args.outputs.labels << {
+    x: pos.x + 10,
+    y: pos.y + 10,
+    text: "x: #{pos.x.to_i}, y: #{pos.y.to_i}"
+  }
+
+  # Draw axis lines
+  args.outputs.lines << { x: 0, y: 360, x2: 1280, y2: 360, r: 100, g: 100, b: 100 }
+  args.outputs.lines << { x: 640, y: 0, x2: 640, y2: 720, r: 100, g: 100, b: 100 }
+
+  # Corner labels to show coordinate system
+  args.outputs.labels << { x: 10, y: 710, text: "Top-Left (0, 720)" }
+  args.outputs.labels << { x: 10, y: 30, text: "Bottom-Left (0, 0) - ORIGIN" }
+  args.outputs.labels << { x: 1000, y: 710, text: "Top-Right (1280, 720)" }
+  args.outputs.labels << { x: 1000, y: 30, text: "Bottom-Right (1280, 0)" }
+
+  # Center marker
+  args.outputs.solids << { x: 638, y: 358, w: 4, h: 4, r: 255, g: 0, b: 0 }
+  args.outputs.labels << { x: 640, y: 340, text: "Center (640, 360)", anchor_x: 0.5 }
+end

data/skills/dragonruby/examples/core/hello_world.rb

@@ -0,0 +1,24 @@
+# Minimal DragonRuby example - Shows a simple label
+# The tick method is called 60 times per second
+
+def tick args
+  # Display text at position (640, 360) - center of the 1280x720 screen
+  args.outputs.labels << {
+    x: 640,
+    y: 360,
+    text: "Hello, DragonRuby!",
+    size_px: 22,
+    anchor_x: 0.5,
+    anchor_y: 0.5
+  }
+
+  # Show the current frame count
+  args.outputs.labels << {
+    x: 640,
+    y: 320,
+    text: "Frame: #{Kernel.tick_count}",
+    size_px: 18,
+    anchor_x: 0.5,
+    anchor_y: 0.5
+  }
+end

data/skills/dragonruby/examples/core/labels.rb

@@ -0,0 +1,22 @@
+# Demonstrates text rendering with alignment, size, and color
+
+def tick args
+  # Different text sizes
+  args.outputs.labels << { x: 100, y: 600, text: "Small text", size_px: 18 }
+  args.outputs.labels << { x: 100, y: 550, text: "Medium text", size_px: 22 }
+  args.outputs.labels << { x: 100, y: 500, text: "Large text", size_px: 26 }
+
+  # Text alignment (centered at x: 640)
+  args.outputs.labels << { x: 640, y: 400, text: "Left aligned", anchor_x: 0, anchor_y: 0.5 }
+  args.outputs.labels << { x: 640, y: 350, text: "Center aligned", anchor_x: 0.5, anchor_y: 0.5 }
+  args.outputs.labels << { x: 640, y: 300, text: "Right aligned", anchor_x: 1, anchor_y: 0.5 }
+
+  # Colored text (RGB values 0-255)
+  args.outputs.labels << { x: 100, y: 200, text: "Red text", r: 255, g: 0, b: 0 }
+  args.outputs.labels << { x: 100, y: 150, text: "Green text", r: 0, g: 255, b: 0 }
+  args.outputs.labels << { x: 100, y: 100, text: "Blue text", r: 0, g: 0, b: 255 }
+  args.outputs.labels << { x: 100, y: 50, text: "Faded text", r: 0, g: 0, b: 0, a: 128 }
+
+  # Reference line for alignment demonstration
+  args.outputs.lines << { x: 640, y: 0, x2: 640, y2: 720 }
+end

data/skills/dragonruby/examples/core/sprites.rb

@@ -0,0 +1,35 @@
+# Demonstrates sprite rendering with hash properties
+# Shows position, size, path, angle, and alpha (transparency)
+
+def tick args
+  # Basic sprite rendering
+  args.outputs.sprites << {
+    x: 100,
+    y: 200,
+    w: 128,
+    h: 101,
+    path: 'dragonruby.png'
+  }
+
+  # Sprite with animated alpha (fading effect)
+  args.outputs.sprites << {
+    x: 300,
+    y: 200,
+    w: 128,
+    h: 101,
+    path: 'dragonruby.png',
+    a: Kernel.tick_count % 255
+  }
+
+  # Rotating sprite with anchoring
+  args.outputs.sprites << {
+    x: 500,
+    y: 250,
+    w: 128,
+    h: 101,
+    path: 'dragonruby.png',
+    angle: Kernel.tick_count % 360,
+    anchor_x: 0.5,
+    anchor_y: 0.5
+  }
+end

data/skills/dragonruby/examples/core/state_management.rb

@@ -0,0 +1,29 @@
+# Demonstrates state management using args.state with ||= pattern
+# The ||= operator initializes values only on first tick
+
+def tick args
+  # Initialize player only once (on first frame)
+  # ||= means "assign if nil" - persists across frames
+  args.state.player ||= {
+    x: 640,
+    y: 360,
+    w: 50,
+    h: 50,
+    path: 'sprites/square/green.png'
+  }
+
+  # Initialize counter if not set
+  args.state.counter ||= 0
+  args.state.counter += 1
+
+  # Move player with arrow keys
+  args.state.player.x += 5 if args.inputs.right
+  args.state.player.x -= 5 if args.inputs.left
+  args.state.player.y += 5 if args.inputs.up
+  args.state.player.y -= 5 if args.inputs.down
+
+  # Render player and counter
+  args.outputs.sprites << args.state.player
+  args.outputs.labels << { x: 10, y: 710, text: "Counter: #{args.state.counter}" }
+  args.outputs.labels << { x: 10, y: 680, text: "Use arrow keys to move" }
+end

data/skills/dragonruby/examples/distribution/background_pause.rb

@@ -0,0 +1,42 @@
+# Handle background/unfocused state gracefully
+# Important for web and mobile where users tab away
+
+def tick(args)
+  if game_paused?(args)
+    render_pause_screen(args)
+    return
+  end
+
+  tick_game(args)
+end
+
+def game_paused?(args)
+  # Only pause in production builds when window loses focus
+  !args.inputs.keyboard.has_focus &&
+    args.gtk.production &&
+    Kernel.tick_count > 0
+end
+
+def render_pause_screen(args)
+  args.outputs.background_color = [0, 0, 0]
+  args.outputs.labels << {
+    x: 640,
+    y: 360,
+    text: "Game Paused",
+    size_enum: 10,
+    alignment_enum: 1,
+    r: 255, g: 255, b: 255
+  }
+  args.outputs.labels << {
+    x: 640,
+    y: 300,
+    text: "Click to resume",
+    size_enum: 2,
+    alignment_enum: 1,
+    r: 180, g: 180, b: 180
+  }
+end
+
+def tick_game(args)
+  # Normal game logic here
+end

data/skills/dragonruby/examples/distribution/build_workflow.sh

@@ -0,0 +1,26 @@
+#!/bin/bash
+# DragonRuby publishing workflow
+
+# 1. Clean up player-specific data before packaging
+rm -f mygame/high-score.txt
+rm -f mygame/saves/*
+rm -rf mygame/tmp/*
+
+# 2. Package only (creates ./builds/ directory)
+./dragonruby-publish --only-package
+
+# 3. Test locally before uploading
+# - Linux:   ./builds/mygame-linux-amd64.bin
+# - macOS:   open ./builds/mygame-mac-*/My\ Game.app
+# - Windows: ./builds/mygame-windows-amd64.exe
+
+# 4. Publish to itch.io (after first manual setup)
+./dragonruby-publish mygame
+
+# Alternative: Manual upload mode
+# ./dragonruby-publish --package mygame
+# Then upload ./builds/*.zip to itch.io manually
+
+# 5. Publish to Steam (requires steam_metadata.txt)
+# ./dragonruby-publish
+# Uses steamcmd for authentication

data/skills/dragonruby/examples/distribution/cvars_production.txt

@@ -0,0 +1,16 @@
+# Production-ready cvars.txt
+# Location: mygame/metadata/cvars.txt
+
+# Minimize logging noise
+log.level=info
+log.filter_subsystems=HTTPServer,HTTP
+
+# Disable web server in production
+# webserver.enabled=false
+
+# Keep game running when backgrounded (0 = no sleep)
+# Useful for music games or web where users tab away
+# renderer.background_sleep=0
+
+# Fullscreen by default (ensure quit option in game!)
+# renderer.fullscreen=true