Getting started with Gamebox

Purpose

Why use Gamebox? Gamebox was designed to spring board game development. It allows the developer to define business rules about a game very quickly without having to worry about resource loading, sound/music management, creating windows, or messing with viewports. Gamebox allows you to define a game’s business rules within minutes.

The driving idea behind Gamebox is to provide the ability to have as many of the basic common pieces of a 2D game at the developers disposal from the beginning.

The reason I wrote Gamebox is twofold: first, to aid in 48 hour game writing competitions and second, to allow me to write simple educational games for my kid(s).

Installation

Game Creation

Actors to the Stage

An Actor is the base class for any game object. A building, the player, the score, the bullet are all examples of actors. Actors can even be invisible. Any number of Behavior s can be added to an Actor to define how it will react to the world via the Actor.has_behaviors method.

So Actors sound fun, how do I get one? That’s where the ActorFactory comes in. In your Level class (demo_level.rb by default) you can use the create_actor helper method as shown below. 

        @score = create_actor :score, :x => 10, :y => 10

This call will return an instance of the Score class (the first arg is the symbolized version of the classname). The ActorFactory will try to require the symbolized class name for you. It will also create the view for the actor and register it to be drawn. Which view is instantiated depends on the actor requested. The factory will always look for a class named the same as the actor with View on the end. So the actor Score will look for ScoreView. If ScoreView does not exist, a generic view class will be used based on the behaviors of the actor. Each ActorView class is constructed with a reference to the actor it is displaying. See ActorFactor#build for more details.

That’s great, but how do I tell my actors what to do? They can register for events of course! A common place for this is in your actor’s setup method. Here is an example from the roids example. 

        input_manager.reg KeyDownEvent, K_SPACE do
                shoot
        end

Sound

There are two ways to play sounds in Gamebox. From your level you can simple access the SoundManager via the @sound_manager instance variable. From your actors, you can play sounds via the play_sound helper method. 

        # music
        sound_manager.play_music :overworld

        # sounds
        sound_manager.play_sound :death

or 

        # from an actor
        play_sound :jump

Resources

All file loading is handled by the ResourceManager. It handles loading images, sounds, fonts, config files, and even svg files. The resource manager caches images based on their name and fonts based on their name/size pair. Example usage from the ScoreView class: 

        font = @mode.resource_manager.load_font 'Asimov.ttf', 30

Behaviors

Behaviors are designed to allow you to build Actors from previously built chunks of code. Lets look at the built in Animated behavior. 

  class SuperHero < Actor
    has_behaviors :animated, :updatable
  end

This snippet show us that our Actor wants to be updated on every gameloop and that it wants to be animated. Gamebox favors convention over configuration. This means that there are default locations and setting for most things. They can be overridden but you are not required to do so. The animated behavior assumes that your animated images are in a directory structure based on the Actor’s underscored name and its current action. 

        zapper/
        `-- data
            `-- graphics
                `-- super_hero
                    |-- flying
                    |   |-- 1.png
                    |   |-- 2.png
                    |   |-- ...
                    |   `-- 8.png
                    |-- idle
                    |   `-- 1.png
                    `-- walking
                        |-- 1.png
                        `-- 2.png

Here we can see that the SuperHere class has three actions (flying, walking, idle). These actions will be set by calling action= on your Actor. 

  batman = create_actor :super_hero
  batman.action = :flying

The animation will cycle through all the numbered png files for the current action. To stop animating you simple call stop_animating. 

  batman.stop_animating

Animated and Updatable are just two behaviors available in Gamebox. Other include graphical, layered, and physical. You can easily add your own game specific behaviors by extending Behavior. (see Wanderer in rague example).

Levels

Stages

Physics

SVG Levels

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.