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, using the metaphor of a 5th grade play.
[GRAPHIC: illustration of kids in costumes on a stage]
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.
# sample of defining the player's behaviors define_actor :player do has_behaviors do positioned audible grounded looker mover gibify slicer shooter recharge_time: 4_000, shot_power: 15, kickback: 1.4 bomber kickback: 1.6 die_by_sword die_by_bomb blasted_by_bomb disoriented_by_bombs die_by_bullet shielded pulled_by_black_hole jump max_power: 80, min_power: 20 end end
Games made with Gamebox
- Killbox - Local multiplayer gravity deathmatch.
- Lonely Shepherd - Ludum Dare 22 entry.
- Seed Life - Ludum Dare 26 entry
- OMG Aliens - Space invaders clone.
The MIT License (MIT)
Copyright © 2013 Shawn Anderson
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
$ gem install gamebox
$ git clone git://github.com/shawn42/gamebox.git $ cd gamebox $ bundle install $ rake install
To create a new Gamebox project run:
$ gamebox zapper
To run your game:
$ cd zapper $ bundle $ bundle exec rake
- 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)]
- Main menu
Defining a stage
- curtain_up / curtain_down
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.
- What are behaviors?
- 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
- 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 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
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
Sound & Music
SoundManager handles the autoloading of sounds from
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:
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.
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.
- advanced viewport stuff
- auto reloading
- debug mode
- remote pry