Overview

Installation

Rubygems:

$ gem install gamebox

From source:

$ git clone git://github.com/shawn42/gamebox.git
$ cd gamebox
$ bundle install
$ rake install

Game Creation

To create a new Gamebox project run:

$ gamebox zapper

To run your game:

$ cd zapper
$ bundle
$ bundle exec rake

Stages

• what are they
  • The place where actors interact and perform
  • different gameplay types / modes

What is a stage?

• Creates actors

• Defines a gameplay mode

  • Multiple "maps" or "levels" might be the same stage.

  [GRAPHIC: Screenshots of a main menu, a few gameplay levels, and a credits screen. Screenshots grouped into sections for what stage they are (main_menu, gameplay, credits)]

• Examples:

  • Main menu
  • Overworld
  • Dungeon
  • Credits

Defining a stage

• curtain_up / curtain_down
• pausing
• backstage

Actors

What they are

[GRAPHIC: An actor contains multiple attributes and multiple behaviors]

Actors can be things that you see on the screen:

• The player space ship
• An alien
• A bullet
• The background
• The score on the screen

[GRAPHIC: Screenshot with different actors circled and labelled]

Actors can also be hidden things that interact with other actors.

An actor is made up of two kinds of things: behaviors, and observable attributes.

Behaviors

• What are behaviors?

Observable Attributes

• What are observable attributes?

Defining an actor type

Adding actors to the stage

To get an actor on the stage, use the create_actor method on stage. This can be done directly from a stage or from a behavior that has required stage via requires :stage.

Actor Views

• rendering overview
• layers & parallax
• defining actor views
• setting view on an actor (non magic name)
• custom renderer (here, stages, or advanced)

Actor views are the mechanism for drawing an actor in Gamebox. When an actor is created, Gamebox will see if there is a matching actor view by name. It will register the view to be drawn by the renderer. The draw callback is called with the rendering target, the x and y offsets based on the viewport, and the z layer to be used for drawing this actor (see the section on parallax layers for more on z layers).

define_actor_view :label_view do
  draw do |target, x_off, y_off, z|
    target.print actor.text, actor.x, actor.y, z, actor.font_style
  end
end

Behaviors

Behaviors are what bring life to actors. They interact interact with the actor's internal data, input, etc.

    define_behavior :die_by_bullet do
      requires :bullet_coordinator, :stage, :backstage, :score_keeper
    
      setup do
        bullet_coordinator.register_shootable actor
    
        reacts_with :shot
      end
    
      remove do
        bullet_coordinator.unregister_shootable actor
      end
    
      helpers do
        def shot(bullet)
          actor.react_to :play_sound, :death
          actor.remove
    
          actor.react_to :gibify, force: (bullet.vel * 0.2)
          score_keeper.player_score(bullet.player) unless actor == bullet.player
        end
    
      end
    end

Input & Updates

• input manager
• director for updates

Input comes from the InputManager. The stage has direct access via the input_manager method. Behaviors can request that they get the input_manager via requires :input_manager. The preferred way of getting input to your actors is via the actor's input method. It returns an InputMapper that can be built with a hash of events. Behaviors then subscribe for those events from the actor's input, or ask for it during updates.

actor.input.map_input '+space' => :shoot,
                      '+w' => :jump,
                      '+a' => :walk_left
                      '+s' => :duck
                      '+d' => :walk_right

actor.input.when :shoot do
  # shoot code
end

# or
if actor.input.walk_left?
  # walk left
end

The stage has access to the InputManager via the input_manager object that is in scope. For example, if we explicitly wanted to make the ESC key fire the pause menu stage, we could do this:

define_stage :flying do

  curtain_up do
    # ...
    input_manager.reg :down, K_ESCAPE do
      fire :change_stage, :pause_menu
      # be sure to explicitly list your stages in config/environment.rb
      # so gamebox knows what :pause_menu is
    end
    # ...
  end
end

The listing of key input constants is in gamebox/lib/gamebox/constants.rb but here are a few to give you an idea:

K_RETURN  K_A  K_B  K_C  K_ESCAPE  K_SPACE  K_RSHIFT  K_LSHIFT

In order to use these shorthand K_ constants, require 'gamebox/constants' in config/environment.rb.

Sound & Music

SoundManager handles the autoloading of sounds from data/sounds and data/music. The stage has direct access via sound_manager. To allow an actor to emit sounds or music, give them the audible behavior. See Reactions below for usage from actors.

# music
sound_manager.play_music :overworld

# sounds
sound_manager.play_sound :death

Music will continue playing when scenes transition. You could explicitly stop / start / change the music by calling .stop_music :overworld. For example, let's say you wanted to have music in the main gameplay stage but then play pause menu music when the player presses ESC.

define_stage :demo do
  curtain_up do
    sound_manager.play_music :game_music
    # ...
    # register key events or something that changes stages
  end
end

define_stage :pause_menu do
  curtain_up do
    sound_manager.stop_music :game_music
    sound_manager.play_music :pause_music
    # ...
  end
end

Sounds are placed in data/sounds. Audio is handled by gosu and gosu supports ogg/wav/mp3 file formats as well as others. Filenames are converted to symbols without the file extension. For example:

data/music/ambient.mp3

The file ambient.mp3 would be played with sound_manager.play_music :ambient. Files are accessed in alphabetical order. If you have two files that have the same name, gamebox will use the first one.

data/music/ambient.mp3
data/music/ambient.ogg

In this case with two files, sound_manager.play_music :ambient plays ambient.mp3 only (because "m" in mp3 comes before "o" in ogg). So name your files uniquely without relying on the file extension. This is true of all gamebox assets.

Music files can only be played one at a time. They won't mix. If music is playing with the same name, playing it again won't restart it. If you want to restart music, you can just stop/start it explicitly.

Testing

• unit
  • actors
  • behaviors
• acceptance
  • helpers
  • examples

Advanced

• advanced viewport stuff
• auto reloading
• debug mode
• remote pry
• conject?