diff options
Diffstat (limited to 'deploy_template/CHEATSHEET.txt')
| -rw-r--r-- | deploy_template/CHEATSHEET.txt | 232 |
1 files changed, 232 insertions, 0 deletions
diff --git a/deploy_template/CHEATSHEET.txt b/deploy_template/CHEATSHEET.txt new file mode 100644 index 0000000..e35f38f --- /dev/null +++ b/deploy_template/CHEATSHEET.txt @@ -0,0 +1,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. +``` |