DragonRuby Game Toolkit Contributions

Parts of the engine are open sourced under the MIT License. You can view the source code associated with this specific version of DragonRuby:

• Locally: In the ./doc/oss directory.
• Online: At https://github.com/dragonruby/dragonruby-game-toolkit-contrib.

The Layout API provides tools for placing primitives on a virtual grid that stays within the "safe area" across all platforms. This is ideal for rendering static UI elements like buttons, menu items, and configuration screens.

All functions are available globally via Layout.*. You can use Layout.rect to define positions based on grid coordinates rather than raw pixel values.

def tick args
   puts Layout.function(...)
end

rure is a C API for Rust's regex library. It provides a regex engine that guarantees linear time searching using finite automata.

Key Features:

• Capturing groups
• Lazy matching
• Unicode support
• Word boundary assertions
• Matching semantics follow Perl's "leftmost first" approach.

Limitations:

• Does not support backreferences.
• Does not support arbitrary lookaround.
• Does not support splitting strings by regex or replacing regex matches in a string (these are currently missing from the C API).

Grid properties fall into two categories:

1. Logical: Values are represented at the logical scale of 720p (1280x720 for landscape, 720x1280 for portrait). You should almost always use these.
2. Pixels: Values represent actual pixels for the current display. These are primarily used for C Extensions, Shaders, or sanity checking Texture Atlases.

Note: For Standard License holders, Pixel category properties will return the same values as the Logical category. Pixel-accurate values require a Pro License with hd=true.

def tick args
  # Logical width
  Grid.w

  # Width in pixels
  Grid.w_px
end

DragonRuby operates on a fixed game loop that executes the tick method exactly 60 times per second (60Hz). All game logic and rendering instructions must reside within this method.

To implement your game, create a file at mygame/app/main.rb and define a Main module containing the tick method. The tick method receives a single argument, args, which is a structure containing all the information needed to manage game state, handle inputs, and send drawing commands to the engine.

DragonRuby clears args.outputs every frame, so you must re-submit all drawing instructions (labels, sprites, etc.) every single time tick runs.

module Main
  def tick args
    # Your game logic and rendering commands go here
  end
end

DragonRuby follows a philosophy of providing multiple options across a spectrum of "make it fast" vs "make it right". Instead of forcing a single "correct" way (the "Pit of Success" pattern), the engine provides incremental paths that allow developers to transition from rapid prototyping to highly structured code as their needs grow.

For example, when working with render primitives, you can choose from the following spectrum:

1. Tuples/Arrays: Simplest and fastest for prototyping.
2. Hashes: Requires slightly more work but allows for additional properties.
3. Open and Strict Entities: More complex, but yields cleaner APIs.
4. Classes: Provides maximum power and flexibility, but requires the most code and programming knowledge.

You can create custom Ruby classes to represent sprites. To be rendered as a primitive by args.outputs.sprites, the class must:

1. Implement all sprite properties (x, y, w, h, path, etc.).
2. Define a method primitive_marker that returns the symbol :sprite.

class Sprite
  attr_accessor :x, :y, :w, :h, :path, :angle, :a, :r, :g, :b, :source_x,
                :source_y, :source_w, :source_h, :flip_horizontally,
                :flip_vertically, :angle_anchor_x, :angle_anchor_y

  def primitive_marker
    :sprite
  end
end

class PlayerSprite < Sprite
  def initialize x, y, w, h
    self.x = x
    self.y = y
    self.w = w
    self.h = h
    self.path = 'sprites/player.png'
  end
end

# Render the custom object
args.outputs.sprites << PlayerSprite.new(10, 10, 32, 64)

When working with pixel arrays in DragonRuby, moving the creation and manipulation logic from Ruby to C can improve performance. This is particularly beneficial for computationally demanding tasks because C can access memory and process numbers faster.

Crucially, using C allows you to hand a pixel array directly to the renderer. This avoids the overhead of converting a C-based pixel array into a Ruby array, which the engine would otherwise have to convert back to a native format for rendering.

DragonRuby uses a sandboxed filesystem that automatically handles platform-specific storage locations. When using relative paths, the engine resolves them based on the game's directory or the platform's appropriate data directory.

Production Data Directories:

• Windows: C:\Users\YourWindowsUsername\AppData\Roaming\[devtitle]\gametitle
• MacOS: $HOME/Library/Application Support/[gametitle]
• Linux: $HOME/.local/share/[gametitle]
• HTML5: Browser's IndexedDB

Note: [devtitle] and [gametitle] are values from your app/metadata/game_metadata.txt file.

Reading Priority: When reading files, the engine checks the data directory first, then the game directory. If a file exists in both, the version in the data directory takes precedence. This allows for persistent user data to override shipped game assets.