# 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:

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

# Args: `args`

All of GTK's functionality hangs off of `args`.

## Args' Outputs: `args.outputs`

All render `primitive`s 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**

```ruby
#                       X    Y    TEXT
args.outputs.labels << [640, 360, "I am a black label."]
```

- **A Colored Label**

```ruby
# 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**

```ruby
# 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.

```ruby
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`**

```ruby
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}"]
end
```

### 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**

```ruby
#                          X    Y  WIDTH  HEIGHT  PATH
args.outputs.sprites << [100, 100,    32,     64, "sprites/player.png"]
```

- **Extended Capabilities**

```ruby
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
  0,            # TILE_X
  0,            # TILE_Y
  32,           # TILE_W
  32            # TILE_H
]
```

- **Named Parameters/Additional Metadata**

Here are all the properties for `sprites`:

```ruby
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,
  tile_x:  0,
  tile_y:  0,
  tile_w: -1,
  tile_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`:

```ruby
def tick args
   # Render a label showing the current tick_count.
   args.outputs.labels << [360, 640, args.state.tick_count]
end
```

- **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.

```ruby
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]
end
```

## Args' Inputs: `args.inputs`

# Numeric

## Numeric#elapsed?

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.
```