1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
# 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.
```
|
