DragonRuby Game Toolkit Cheatsheet#

A detailed documentation listing is located at mygame/documentation. For real world sample usages of GTK's APIs, take a look at the samples directory. The sample apps are ordered by beginner to advanced. So look at them in order to get the most out of them.

Minimum Code for Game#

The minimum amount of code required for a game is a file named mygame/main.rb with the following:

def tick args
  args.outputs.labels << [640, 360, "Hello World"]

Args: args#

All of GTK's functionality hangs off of args.

Args' Outputs: args.outputs#

All render primitives are accessible under args.outputs.

Labels: args.outputs.labels#

args.outputs.labels is used to render labels.

Labels are how you display text. This code will go directly inside of the def tick args method.

  • Minimum Code
#                       X    Y    TEXT
args.outputs.labels << [640, 360, "I am a black label."]
  • A Colored Label
# A colored label
#                       X    Y    TEXT,                   RED    GREEN  BLUE  ALPHA
args.outputs.labels << [640, 360, "I am a redish label.", 255,     128,  128,   255]
  • Extended Capabilities
# A colored label
#                       X    Y     TEXT           SIZE  ALIGNMENT  RED  GREEN  BLUE  ALPHA  FONT FILE
args.outputs.labels << [640, 360, "Hello world",    0,         1,   0,     0,    0,   255, "fonts/coolfont.ttf"]

A SIZE of 0 represents "default size". A negative value will decrease the label size. A positive value will increase the label's size.

An ALIGNMENT of 0 represents "left aligned". 1 represents "center aligned". 2 represents "right aligned".

  • Named Parameters/Additional Metadata

You can add additional metadata about your game within a label, which requires you to use a Hash instead.

args.outputs.labels << {
  x:              200,
  y:              550,
  text:           "dragonruby",
  size_enum:      2,
  alignment_enum: 1,
  r:              155,
  g:              50,
  b:              50,
  a:              255,
  font:           "fonts/manaspc.ttf",
  # You can add any properties you like (this will be ignored/won't cause errors)
  game_data_one:  "Something",
  game_data_two: {
     value_1: "value",
     value_2: "value two",
     a_number: 15
  • Getting The Size of a Piece of Text: args.gtk.calcstringbox
def tick args
  # local variable
  #                                       TEXT           SIZE_ENUM  FONT
  text_size = args.gtk.args.calcstringbox("some string",         0, "font.ttf")

  # print size of a label to screen using Ruby's string formatting capabilities: #{}
  args.outputs.labels << [640, 360, "the label's size is: #{text_size.x}, #{text_size.y}, #{text_size.w}, #{text_size.h}"]

Sprites: args.outputs.sprites#

args.outputs.sprites is used to render sprites.

All primitives in GTK have the same considerations as detailed in the Labels section.

  • Minimum Code
#                          X    Y  WIDTH  HEIGHT  PATH
args.outputs.sprites << [100, 100,    32,     64, "sprites/player.png"]
  • Extended Capabilities
args.outputs.sprites << [
  100,          # X
  100,          # Y
  32,           # W
  64,           # H
  "player.png", # PATH
  0,            # ANGLE
  255,          # ALPHA
  0,            # RED_SATURATION
  255,          # GREEN_SATURATION
  0             # BLUE_SATURATION
  • Named Parameters/Additional Metadata

Here are all the properties for sprites:

args.outputs.sprites << {
  x: 100,
  y: 100,
  w: 100,
  h: 100,
  path: "sprites/player.png",
  angle: 0,
  a, 255
  r: 255,
  g: 255,
  b: 255,
  source_x:  0,
  source_y:  0,
  source_w: -1,
  source_h: -1,
  flip_vertically: false,
  flip_horizontally: false,
  angle_anchor_x: 0.5,
  angle_anchor_y: 1.0

Sounds args.outputs.sounds#

Sounds that end .wav will play once: args.outputs.sounds << 'something.wav'.

Sounds that end .ogg is considered background music and will loop: args.outputs.sounds << 'background_music.ogg'.

If you want to play a .ogg once as if it were a sound effect, you can do: args.gtk.queue_sound 'some-ogg.ogg'

Args' State args.state#

args.state is where you can put all of your game state.

  • Tick Count args.state.tick_count

GTK has a fixed time step of 60 frames per second. You can access the current tick_count using args.state.tick_count:

def tick args
   # Render a label showing the current tick_count.
   args.outputs.labels << [360, 640, args.state.tick_count]
  • Working With "Open" Game State

args.state is a "open" data structure that allows you to define properties of any structure. You don't need to define any kind of class.

To initialize your game state, use the ||= operator. Any value on the right side of ||= will only be assigned once.

To assign a value every frame, just use the = operator, but make sure you've initalized a default value.

def tick args
  # initialize your game state ONCE
  args.player.x  ||= 0
  args.player.y  ||= 0
  args.player.hp ||= 100

  # increment the x position of the character by one every frame
  args.player.x += 1

  # Render a sprite with a label above the sprite

  #                        X              Y              W   H  PATH
  args.outputs.sprites << [args.player.x, args.player.y, 32, 32 "player.png"]

  #                        X              Y                   TEXT
  args.outputs.labels  << [args.player.x, args.player.y - 50, args.player.hp]

Args' Inputs: args.inputs#



Returns true if a numeric value plus an offset represents a point in time that has elapsed. This is related to args.state.tick_count.

args.state.attacked_at ||= args.state.tick_count
puts args.state.attacked_at.elapsed? 60  # will print false after one second.


gtk.current_framerate - Returns current framerate
gtk.pin_to_30fps? - Returns boolean determining if gtk is pinned to 30 FPS
gtk.pause! - Pauses game
gtk.paused - Returns boolean determining if game is paused
gtk.paused= - Allows you to change value of pause
gtk.unpause! - Unpauses game