gamebox 0.4.0.rc5 → 0.4.0.rc11

data/README.md

@@ -1,174 +1,252 @@
 # Gamebox
- ![http://travis-ci.org/shawn42/gamebox](https://secure.travis-ci.org/shawn42/gamebox.png)   
- ![https://gemnasium.com/shawn42/gamebox](https://gemnasium.com/shawn42/gamebox.png)
 
- * A game template for building and distributing Gosu games.
- * Quickly generate a game and have it up and running.
- * Provide conventions and DSL for building your game.
- * Facilitate quickly building distributable artifacts.
- * http://shawn42.github.com/gamebox/
- * see [gamebox on rubygems.org](https://rubygems.org/gems/gamebox) for the list of requirements
+[![Gamebox Build Status](https://secure.travis-ci.org/shawn42/gamebox.png)](http://travis-ci.org/shawn42/gamebox)
+[![Gamebox Deps Status](https://gemnasium.com/shawn42/gamebox.png)](https://gemnasium.com/shawn42/gamebox)
+[![Code Climate](https://codeclimate.com/github/shawn42/gamebox.png)](https://codeclimate.com/github/shawn42/gamebox)
 
+* A **game template** for building and distributing Gosu games.
+* Quickly **generate a game** and have it **up and running**.
+* Provide **conventions and DSL** for building your game.
+* Facilitate quickly building **distributable artifacts**.
+* http://shawn42.github.com/gamebox/
+* see [gamebox on rubygems.org](https://rubygems.org/gems/gamebox) for the list of requirements
 
-# Getting started with Gamebox
+## Getting started with Gamebox
 
-## Purpose
+### 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.
+**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, using the metaphor of a 5th grade play.
 
-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 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 kids.
 
-## Installation
+### Installation
 
- * gem install gamebox
- * or [tar](http://shawn42.github.com/gamebox)
- * or git clone git://github.com/shawn42/gamebox.git
+* `gem install gamebox`
+* `git clone git://github.com/shawn42/gamebox.git && cd gamebox && bundle && rake install`
 
-## Game Creation
+### Game Creation
 
-``` $ gamebox zapper```
+To create a new Gamebox project run:
 
-```$ this will create the directory structure and needed files to get a basic actor up on the screen```
+```bash
+gamebox zapper
+```
 
+This will create the directory structure and needed files to get a basic actor up on the screen:
+
+```
 zapper
-    ├── Gemfile  
-    ├── README.rdoc  
-    ├── Rakefile  
-    ├── config  
-    │   ├── boot.rb  
-    │   ├── environment.rb  
-    │   └── game.yml  
-    ├── data  
-    │   ├── fonts  
-    │   │   └── FONTS_GO_HERE  
-    │   ├── graphics  
-    │   │   └── GRAPHICS_GO_HERE  
-    │   ├── music  
-    │   │   └── MUSIC_GOES_HERE  
-    │   └── sounds  
-    │       └── SOUND_FX_GO_HERE  
-    ├── spec  
-    │   └── helper.rb  
-    └── src  
-        ├── actors  
-        │   └── player.rb  
-        ├── app.rb  
-        └── demo_stage.rb  
-
-
- you now have a runnable gamebox game
-`
-`	cd zapper  
-	rake  
-
-## 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 behaviors can be added to an actor to define how it will react to the world via the define_actor method. Actors are simply buckets of data and behaviors. The interactions with system are all driven by their behaviors.
-
-So Actors sound fun, how do I get one? That's where the ActorFactory comes in. In your Stage class (demo_stage.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 a score (the first arg is the symbolized version of the actor type).  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 view named the same as the actor with _view on the end. So the actor score will look for score_view.  If score_view does not exist, a generic view class will be used based on the behaviors of the actor. Each view 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? By defining their behaviors!
-`
-`define_actor :score do
-  has_behaviors :positioned, :score_keeping
+├── Gemfile
+├── README.rdoc
+├── Rakefile
+├── config
+│   ├── boot.rb
+│   ├── environment.rb
+│   └── game.yml
+├── data
+│   ├── fonts
+│   ├── graphics
+│   ├── music
+│   └── sounds
+├── spec
+│   └── helper.rb
+└── src
+    ├── actors
+    │   └── player.rb
+    ├── app.rb
+    └── demo_stage.rb
+```
+
+To run your game:
+
+```bash
+cd zapper
+bundle
+rake
+```
+
+## Stages
+
+A stage is where all the magic happens. Each new play type in your game will use a different stage. An example game may have a number of stages such as: `main_menu`, `play`, or `credits`.  A `demo_stage.rb` is created for you by using the `gamebox new` command.
+
+```ruby
+define_stage :demo do
+  curtain_up do
+   ...
+  end
 end
+```
 
+## Actors
 
-## Sound
+Actors are the basic building blocks of games in Gamebox. Everything in the game is an actor: the player, an alien, the bullet, even the score on the screen. Internally, actors are just named collections of behaviors and observable attributes.
 
-There are two ways to play sounds in Gamebox. From your stage you can simple access the SoundManager via the sound_manager method. From your actors, you can play sounds via the play_sound helper method in the audible behavior.
-`
-`	# music
-	sound_manager.play_music :overworld
-	
-	# sounds
-	sound_manager.play_sound :death
+```ruby
+define_actor :player do
+  has_behaviors do
+      shooter recharge_time: 4_000, shot_power: 15, kickback: 0.7
+      shielded
+      bomber kickback: 5
 
-or
-`
-`	# from an actor
-        has_behavior :audible
-	actor.react_to :play_sound, :jump
+      die_by_sword
+      die_by_bullet
+      die_by_bomb
+      blasted_by_bomb
 
-## Resources
+      jumper
+  end
+end
+```
 
-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
+Behaviors are what bring life to actors.  They interact interact with the actor's internal data, input, audio, etc.
 
-Behaviors are designed to allow you to build Actors from previously built chunks of code. Lets look at the built in Animated behavior.
-`
-`  define_behavior :shooting do
-    requires :input_manager
-    setup do
-      input_manager.reg :down, KbSpace do
-        shoot
-      end
-    end
+```ruby
+define_behavior :projectile do
 
-    helpers do
-      def shoot
-        # shoot
-      end
+  requires :director
+  requires_behaviors :positioned
+  setup do
+    actor.has_attributes vel_x: 0,
+                         vel_y: 0
+
+    director.when :update do |delta_ms, delta_secs|
+      actor.x += (actor.vel_x * delta_secs)
+      actor.y += (actor.vel_y * delta_secs)
     end
   end
+end
+```
 
+### Views
 
-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.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.
+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).
 
-  batman # create_actor :super_hero
-  batman.action # :flying
+```ruby
+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
+```
 
-The animation will cycle through all the numbered png files for the current action.  To stop animating you simple call stop_animating.
+### Getting actors on stage
 
-  batman.stop_animating
+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`.
 
+```ruby
+curtain_up do
+  @player = create_actor :label, x: 20, y: 30, text: "Hello World!"
+end
 
-Animated and Updatable are just two behaviors available in Gamebox. Other include	graphical, audible, layered, and physical. You can easily add your own game specific behaviors by extending Behavior. (see Wanderer in rague example for a simple behavior).
+# or
+stage.create_actor ..
+```
 
-## Stages
+## Input
+
+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.
+
+```ruby
+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
+```
+
+## Updates
+
+Updates all come from the Director. Again, the stage has direct access via `director` and behaviors must `requires :director`.
 
-A Stage is where all the magic happens. A Stage can be any gameplay mode in your game. The main menu has a different interactions than the _real_ game.  In Gamebox, each should have their own Stage. Stages are configured via the stage_config.yml file in config. Listing :demo there will create DemoStage for you.  Game.rb decides which stage to start on. 
+```ruby
+director.when :update do |t_ms, t_sec|
+  # update something
+end
+```
+
+## Sound and 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.
+
+```ruby
+# music
+sound_manager.play_music :overworld
+
+# sounds
+sound_manager.play_sound :death
+```
+
+## Reactions
 
-## StageManager
+To ask to react to something we use the `react_to` method. It sends your message to all of the actors behaviors, giving them a chance to (you guessed it), react.
 
-So how do these actors end up on the screen? The StageManager. The stage manager handles contruction of new stages and drawing their actors too. Gamebox has built-in support for parallaxing. Parallax layers denote this distance from the audience an Actor should be.  The clouds in the sky that are really far away can be set to INFINITY to have them not move at all as the viewport moves.  Each parallax layer has layers to allow Actors to be on top of one another, but have the same distance from the audience.  The StageManager respects Actor's layered behaviors, if specified. If no layer is specified, the StageManager puts the Actor on parallax layer one of layer one. Example layered behavior:
+```ruby
+actor.react_to :play_sound, :jump
+```
 
-  has_behavior :layered #> {:parallax #> 30, :layer #> 2}
+If the actor has an audible behavior listening, he'll play the jump sound. But what if something else wants to know about playing sounds. Maybe the actor triggers an effect by making sound. If the actor had a `noise_alert` behavior, it too would be notified of the `:play_sound` event.
+
+```ruby
+define_behavior :noise_alert do
+  setup do
+    reacts_with :play_sound
+  end
+
+  helpers do
+    def play_sound(*args)
+      # react here
+    end
+  end
+end
+```
 
-This Actor will be 30 layers away from the audience, and will sit on top of anything in parallax layer 30 that has layer less than 2.
+The `reacts_with` helper takes a list of events that your behavior is interested in, and maps them to helper methods.
 
+## TODO
 
-## Publisher
-## Physics
-## SVG Levels
+### Configuration
 
-## LICENSE:
+1. `Gamebox.configuration`
 
-(MIT)
+### Resources
+
+1. load paths
+2. fonts
+3. graphics (caching)
+4. sounds
+
+### Stages
+
+1. configuring stages
+1. changing stages
+
+### Physics
+
+## Links
+
+[Frequently Asked Questions](https://github.com/shawn42/gamebox/wiki/Frequently-Asked-Questions)
+
+## License
+
+The MIT License (MIT)
 
 Copyright © 2012 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.

data/bin/gamebox

@@ -1,12 +1,20 @@
 #!/usr/bin/env ruby
-
+require 'rake'
 require 'thor'
 require 'gamebox'
+include Rake::DSL
+
+DIST_TYPES = %w(mac win linux)
+load File.expand_path(File.join(File.dirname(__FILE__), "..", "/lib/gamebox/tasks/gamebox_tasks.rake"))
 
 def print_version
   puts "Gamebox #{Gamebox::VERSION::STRING}"
 end
 
+def run_rake_task(*args)
+  sh "rake #{args.shift}[#{args.join(',')}]"
+end
+
 if ARGV.include?('-v') || ARGV.include?('--version')
   print_version
   exit 0
@@ -31,11 +39,49 @@ class GameboxThorCommand < Thor
     end
 
     directory "app", "."
+  end
+  desc "n PATH", "Generates a new gamebox game at PATH."
+  alias_method :n, :new
+
+  desc "start", "starts the application"
+  def start
+    print_version
+    run_rake_task("run")
+  end
 
+  desc "s", "starts the application"
+  alias_method :s, :start
+
+  desc "debug", "starts the application in debug"
+  def debug
+    print_version
+    run_rake_task("debug")
   end
-  
 
+  desc "d", "starts the application in debug"
+  alias_method :d, :debug
+
+  desc "dist [mac|linux|win|all]", "Build an executable for your app"
+  def dist(*args)
+    dist_type = args[0]
+    if DIST_TYPES.include?(dist_type)
+      run_rake_task("dist:#{dist_type}")
+    elsif dist_type == "all"
+      DIST_TYPES.each do |type|
+        run_rake_task("dist:#{type}")
+      end
+    else
+      p "Unrecognized dist type"
+    end
+  end
+
+  desc "generate [actor|behavior|stage] NAME", "Gamebox generator, this will generate templated files for you for quicker development"
+  def generate(*args)
+    run_rake_task("generate:#{args.shift}", *args)
+  end
+  desc "g [actor|behavior|stage] NAME", "Gamebox generator, this will generate templated files for you for quicker development"
+  alias_method :g, :generate
 
 end
 
-GameboxThorCommand.start
+GameboxThorCommand.start