ippa-chingu 0.2.0 → 0.3.0

data/History.txt

@@ -1,5 +1,8 @@
+=== 0.0.3 / 2009-08-14
+Too much to list. remade inputsystem. gamestates are better. window.rb is cleaner. lots of small bugfixes. Bigger readme.
+
 === 0.0.2 / 2009-08-10
 tons of new stuff and fixes. complete keymap. gamestate system. moreexamples/docs. better game_object.
 
 === 0.0.1 / 2009-08-05
-first release
+first release

data/README.rdoc

@@ -34,17 +34,27 @@ Chingu consists of the following core classes:
 The main window, use it at you use Gosu::Window.
 
 === Chingu::GameObject
-Use for your in game objects, got everything to put them on the screen.
+Use for all your in game objects. The player, the enemies, the bullets, the powerups, the loot laying around.
+It's very reusable and doesn't contain any game-logic (that's up to you!). Only stuff to put it on screen a certain way.
+It also gives you a couple of bonuses with chingu, as automatic updates/draws and easier input-mapping.
 Has either Chingu::Window or a Chingu::GameState as "owner".
 
 === Chingu::Text
-Makes use of Gosu::Font more rubyish and powerful
+Makes use of Gosu::Font more rubyish and powerful.
+In it's core, another Chingu::GameObject + Gosu::Font.
+
+=== Chingu::GameStateManager
+Keeps track of the game states. Implements a stack-based system with push_game_state and pop_game_state.
 
 === Chingu::GameState
-A "standalone game loop" that can be switched on/off to control game flow.
+A "standalone game loop" that can be activated and deactivated to control game flow.
+A game state is very much like a main gosu window. You define update() and draw() in a gamestate.
+It comes with 2 extras that main window doesn't have. #setup (called when activated) and #finalize (called when deactivated)
+
+If using game states, the flow of draw/update/button_up/button_down is:
+Chingu::Window --> Chingu::GameStateManager --> Chingu::GameState.
+For example, inside game state Menu you call push_game_state(Level). When Level exists, it will go back to Menu.
 
-=== Chingu::GameStateManager
-Keeps track of the game states. The flow of draw/update/button_down is Chingu::Window --> Chingu::GameStateManager --> Chingu::GameState.
 
 == THE BASICS
 
@@ -105,10 +115,10 @@ Chingu doesn't change any fundamental concept of Gosu, but it will make the abov
   #
   class Game < Chingu:Window
     def initialize
-      super # This is always needed
+      super       # This is always needed if you want to take advantage of what chingu offers
       #
       # Player will automaticly be updated and drawn since it's a Chingu::GameObject
-      # You'll need your own Game#update/#draw after a while, but just put #super there and Chingu can do its thing!
+      # You'll need your own Game#update/#draw after a while, but just put #super there and Chingu can do its thing.
       #
       @player = Player.new
       @player.input = {:left => :move_left, :right => :move_right}
@@ -178,6 +188,65 @@ I've chose to base it around Image#draw_rot. So basically all the arguments that
   #
   @player = Player.new(:draw => false, :update => false)
 
+=== Input
+One of the core things I wanted a more natural way of inputhandling.
+You can define input -> actions on Chingu::Window, Chingu::GameState and Chingu::GameObject.
+Like this:
+
+  #
+  # When left arrow is pressed, call @player.turn_left ... and so on.
+  #
+  @player.input = { :left => :turn_left, :right => :turn_right, :left => :halt_left, :right => :halt_right }
+
+  
+  #
+  # In Gosu the equivalent would be:
+  #
+  def button_down(id)
+    @player.turn_left		if id == Button::KbLeft
+    @player.turn_right	if id == Button::KbRight
+  end
+  
+  def button_up(id)
+    @player.halt_left		if id == Button::KbLeft
+    @player.halt_right	if id == Button::KbRight
+  end
+
+
+Another more complex example:
+
+  #
+  # So what happens here?
+  #
+  # Pressing P would create an game state out of class Pause, cache it and activate it.
+  # Pressing ESC would call Play#close
+  # Holding down LEFT would call Play#move_left on every game iteration
+  # Holding down RIGHT would call Play#move_right on every game iteration
+  # Relasing SPACE would call Play#fire
+  #
+  
+  class Play < Chingu::GameState
+    def initialize
+      self.input = { :p => Pause, :escape => :close, :holding_left => :move_left, :holding_right => :move_right, :released_space => :fire }
+    end
+  end
+  class Pause < Chingu::GameState
+    # pause logic here
+  end
+
+In Gosu the above code would include code in button_up(), button_down() and a check for button_down?() in update().
+
+Every symbol can be prefixed by either "released_" or "holding_" while no prefix at all defaults to pressed once.
+So, why not :up_space or :relase_space instead of :released_space?
+Or :hold_left or :down_left instead of :holding_left?
+
+:up_space doesn't sound like english, :release_space sounds more like a command then an event.
+
+:holding_left sounds like something that's happening over a period of time, not a single trigger, which corresponds good to what's happening when using it.
+
+And with the default :space => :something youd imagine that :something is called once. You press :space once, :something get's executed once.
+
+
 === GameState / GameStateManager
 Chingu incorporates a basic push/pop game state system (as discussed here: http://www.gamedev.net/community/forums/topic.asp?topic_id=477320).
 
@@ -186,7 +255,9 @@ Game states is a way of organizing your intros, menus, levels.
 Game states aren't complicated. In Chingu a GameState is a class that behaves mostly like your default Gosu::Window (or in our case Chingu::Window) game loop.
 
   
+  # A simple GameState-example
   class Intro < Chingu::GameState
+  
     def update
       # game logic here
     end
@@ -194,44 +265,62 @@ Game states aren't complicated. In Chingu a GameState is a class that behaves mo
     def draw
       # screen manipulation here
     end
-    
-    def button_down(id)
-      # called when a button is pressed
+        
+    # Called when we enter the game state
+    def setup
+      @player.angle = 0   # point player upwards
     end
     
+    # Called when we leave the current game state
     def finalize
-      push_gamestate(Menu.new)  # Called when Intro dies for whatever reason.
+      push_game_state(Menu)   # switch to game state "Menu"
     end
-    
-    # etc etc
+
   end
 
 Looks familiar ye?
-Active that game state/game loop in your main window (which is always the spider in the net).
+You can activate the above game state in 2 ways
 
   class Game < Chingu::Window
     def initialize
-      push_gamestate(Intro.new)
+      #
+      # 1) Create a new Intro-object and activate it (pushing to the top).
+      # This version makes more sense if you want to pass parameters to the gamestate, for example:
+      # push_game_state(Level.new(:level_nr => 10))
+      #
+      push_game_state(Intro.new)
+      
+      #
+      # 2) This leaves the actual object-creation to the game state manager.
+      # This results in only 1 object is ever created of class 'Intro'.
+      # The second time 'push_game_state(Intro)' is called, it will re-use the last one.
+      # This means code in Intro#initialize() is only  called once, Intro#setup() is called everytime Intro is activated though.
+      #
+      push_game_state(Intro)
     end
   end
   
 A GameState in Chingu is just a class with the following instance methods: 
 
-* setup()     - called when game state becomes active (switch_gamestate(gamestate) for example)
+* initialize()  - called only once with push_game_state(Intro) but everytime with push_game_state(Intro.new)
+* setup()       - called each time the game state becomes active. 
 * button_down(id) - Called when a button is down
 * button_up(id)   - Called when a button is released
 * update()    - just as in your normal game loop, put your game logic here.
 * draw()      - just as in your normal game loop, put your screen manipulation here.
-* finalize()  - called when a game state is finished
+* finalize()  - called when a game state de-activated (for example by pushing a new one on top with push_game_state)
 
 Chingu::Window automatically creates a @game_state_manager and makes it accessible in our game loop.
 By default the game loop calls update() / draw() on the the current game state.
 
-Chingu also has a couple of helpers to easy change between game states.
+Chingu also has a couple of helpers-methods for handling the game states:
 In a main loop or in a game state:
-* push_gamestate(state)     - adds a new gamestate, which then becomes the active one
-* pop_gamestate             - removes active gamestate and activates the previous one
-* switch_gamestate(state)   - pop all gamestates until given state is found
+* push_game_state(state)        - adds a new gamestate on top of the stack, which then becomes the active one
+* pop_game_state                - removes active gamestate and activates the previous one
+* current_game_state            - returns the current game state
+* previous_game_state           - returns the previous game state (useful for pausing and dialog boxes, see example4.rb)
+* pop_until_game_state(state)   - pop game states until given state is found
+* clear_game_states             - removes all game states from stack
 
 To switch to a certain gamestate with a keypress use Chingus input handler:
   class Intro < Chingu::GameState
@@ -240,15 +329,15 @@ To switch to a certain gamestate with a keypress use Chingus input handler:
     end
   end
   
-Or Chingus pretty shortcut:
+Or Chingus shortcut:
 
   class Intro < Chingu::GameState
     def setup
-      self.input = { :space => Menu }      #  { :space => Menu.new } works as well.
+      self.input = { :space => Menu }      #  or { :space => Menu.new } if you want to create a new object each time.
     end
   end
 
-Chingu will detect that Menu is a gamestate-class and call push_gamestate on it when space is pressed inside Intro.
+Chingus inputhandler will detect that Menu is a gamestate-class, create a new instance, cache it and activate it with push_game_state().
 
 === Assets / Paths
 
@@ -285,12 +374,13 @@ It's not only that the second example is readable by ppl now even familiar with
 
 == TODO:
 * (done) Complete the input-definitions with all possible inputs (keyboard, gamepad, mouse)!
-* Complete input-stuff with released-states etc
+* (done) Complete input-stuff with released-states etc
 * More gfx effects, for example: fade in/out to a specific color (black makes sense between levels).
-* Summon good proven community gosu snippets into Chingu
+* (posted request on forums) Summon good proven community gosu snippets into Chingu
 * (done) Generate docs @ ippa.github.com-  http://rdoc.info/projects/ippa/chingu !
 * (done) A good scene-manager to manage welcome screens, levels and game flow- GameStateManager / GameState !
 * More docs
+* make a playable simple game in examples\ that really depends on game states
 * (done) Make a gem- first gem made on github
 * Automate gemgenning rake-task even more
 * More examples when effects are more complete
@@ -298,14 +388,14 @@ It's not only that the second example is readable by ppl now even familiar with
 * class Actor/MovingActor with maybe abit more logic then the basic GameObject. Would ppl find is useful?
 * Spell check all docs, sloppy spelling turns ppl off.
 * Tests
-* Streamline fps / tick code
+* (done) Streamline fps / tick code
 * (done) Encapsulate Font.new / draw_rot with a "class Text < GameObject"
-* Make it possible for ppl to use the parts of Chingu they like
+* (10% done) Make it possible for ppl to use the parts of Chingu they like
 * A more robust game state <-> game_object system to connect them together.
 * Get better at styling rdocs
-* all �gamestate� ? �game state� ?
-* FIX example4: :p => Pause.new  would Change the "inside_game_state" to Pause and make @player belong to Pause.
+* (done) all �gamestate� ? �game state� ?   it's "game state"
 * intergrate rubygame_movie_make (maybe after a rename, GameAutomator? GameSequence?
+* FIX example4: :p => Pause.new  would Change the "inside_game_state" to Pause and make @player belong to Pause.
 
 == WHY?
 * Plain Gosu is very minimalistic, perfect to build some higher level logic on!

data/chingu.gemspec

@@ -2,11 +2,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{chingu}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["ippa"]
-  s.date = %q{2009-08-10}
+  s.date = %q{2009-08-14}
   s.description = %q{Game framework built on top of the OpenGL accelerated game lib Gosu.  It adds simple yet powerfull game states, prettier inputhandling, deploymentsafe asset-handling, a basic re-usable game object and automation of common task.}
   s.email = ["ippa@rubylicio.us"]
   s.extra_rdoc_files = ["History.txt", "Manifest.txt"]
@@ -24,11 +24,11 @@ Gem::Specification.new do |s|
     s.specification_version = 2
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
-      s.add_development_dependency(%q<hoe>, [">= 2.3.2"])
+      s.add_development_dependency(%q<hoe>, [">= 2.3.3"])
     else
-      s.add_dependency(%q<hoe>, [">= 2.3.2"])
+      s.add_dependency(%q<hoe>, [">= 2.3.3"])
     end
   else
-    s.add_dependency(%q<hoe>, [">= 2.3.2"])
+    s.add_dependency(%q<hoe>, [">= 2.3.3"])
   end
 end

data/examples/example1.rb

@@ -15,7 +15,13 @@ class Game < Chingu::Window
   def initialize
     super 
     @player = Player.new(:x => 200, :y => 200, :image => Image["spaceship.png"])
-    @player.input = {:left => :move_left, :right => :move_right, :up => :move_up, :down => :move_down}
+    @player.input = { :holding_left => :move_left, :holding_right => :move_right, 
+                      :holding_up => :move_up, :holding_down => :move_down}
+  end
+  
+  def update
+    super
+    self.caption = "FPS: #{self.fps} milliseconds_since_last_tick: #{self.milliseconds_since_last_tick}"
   end
 end
 

data/examples/example2.rb

@@ -15,7 +15,11 @@ class Game < Chingu::Window
     super
     
     @player = Player.new(:x => 200, :y => 200, :image => Image["spaceship.png"])
-    @player.input = {:left => :move_left, :right => :move_right, :up => :move_up, :down => :move_down, :space => :fire}
+    @player.input = { :holding_left => :move_left, 
+                      :holding_right => :move_right, 
+                      :holding_up => :move_up, 
+                      :holding_down => :move_down, 
+                      :space => :fire}
   end
 
   #
@@ -43,18 +47,23 @@ class Game < Chingu::Window
   
 end
 
+#
+# Our Player
+#
 class Player < Chingu::GameObject
+  def initialize(options = {})
+    super
+    @image = Image["spaceship.png"]
+  end
+  
   def move_left;  @x -= 1; end
   def move_right; @x += 1; end
   def move_up;    @y -= 1; end
-  def move_down;  @y += 1; end
-  
+  def move_down;  @y += 1; end 
+
   def fire
     Bullet.new(:x => @x, :y => @y)
-  end
-  
-  def update
-  end
+  end  
 end
 
 class Bullet < Chingu::GameObject
@@ -67,7 +76,7 @@ class Bullet < Chingu::GameObject
   end
 
   # Move the bullet forward
-  def update
+  def update(time)
     @y -= 2
   end
   

data/examples/example3.rb

@@ -9,7 +9,7 @@ include Gosu
 class Game < Chingu::Window
   def initialize
     super    
-    self.input = {:left => :scroll_left, :right => :scroll_right, :escape => :close}
+    self.input = {:holding_left => :scroll_left, :holding_right => :scroll_right, :escape => :close}
     
     @parallax = Chingu::Parallax.new(:x => 0, :y => 0, :center_x => 0, :center_y => 0)
     

data/examples/example4.rb

@@ -5,7 +5,7 @@ include Gosu
 #
 # Example demonstrating jumping between 4 different game states.
 #
-# push_gamestate, pop_gamestate and previous_gamestate are 3 helpers that Chingu mixes in
+# push_game_state, pop_game_state, current_game_state previous_game_state are 4 helper-methods that Chingu mixes in
 # into Chingu::Window and Chingu::GameState
 #
 # Behind the scenes they work against @game_state_manager that's autocreated within Chingu::Window.
@@ -19,7 +19,7 @@ include Gosu
 #
 # 3) @game_state_manager calls draw / update on the current active game state
 #
-# 4) Each gamestate keeps a collection @game_objects which it calls draw / update on.
+# 4) Each game state keeps a collection @game_objects which it calls draw / update on.
 #    Any object based on Chingu::GameObject (In this example Player and Text) automatically
 #    gets added to the correct state or or main window.
 #
@@ -29,19 +29,18 @@ include Gosu
 #
 class Game < Chingu::Window
   def initialize
-    super    
-    push_gamestate(Intro)
+    super
+    
+    push_game_state(Intro)
     
     # Yes you can do crazy things like this :)
-    self.input = { :left_mouse_button => lambda{Chingu::Text.new(:text => "Woff!")}}    
+    self.input = { :left_mouse_button => lambda{Chingu::Text.new(:text => "Woff!")}, :esc => :close}    
   end
 end
 
-#
-# Our Player
-#
+# Our Player 
 class Player < Chingu::GameObject
-  def initialize(options)
+  def initialize(options = {})
     super
     @image = Image["spaceship.png"]
   end
@@ -49,16 +48,42 @@ class Player < Chingu::GameObject
   def move_left;  @x -= 1; end
   def move_right; @x += 1; end
   def move_up;    @y -= 1; end
-  def move_down;  @y += 1; end  
+  def move_down;  @y += 1; end 
+
+  def fire
+    Bullet.new(:x => @x, :y => @y)
+  end  
+end
+
+# The bullet the Player fires
+class Bullet < Chingu::GameObject
+  def initialize(options)
+    super
+    @image = Image["fire_bullet.png"]
+  end
+  
+  def update(time)
+    @y -= 2
+  end
 end
 
+
 #
 # GAMESTATE #1 - INTRO
 #
 class Intro < Chingu::GameState 
-  def setup
-    @title = Chingu::Text.new(:text=>"Intro (press space)", :x=>200, :y=>50, :size=>30)
-    self.input = { :space => Menu, :escape => :close }
+  def initialize(options)
+    super
+    @title = Chingu::Text.new(:text=>"Press and release F1", :x=>200, :y=>50, :size=>30)
+    self.input = { :f1 => :pressed, :released_f1 => :released, :f2 => Menu}
+  end
+  
+  def pressed
+    @title.text = "F1 pressed (F2 to continue)"
+  end
+  
+  def released
+    @title.text = "F1 released (F2 to continue)"
   end
 end
 
@@ -66,9 +91,10 @@ end
 # GAMESTATE #2 - MENU
 #
 class Menu < Chingu::GameState
-  def setup
-    @title = Chingu::Text.new(:text => "GameState Menu (press 'm')", :x => 200, :y => 50, :size=>30)
-    self.input = { :m => Level.new(:level => 10) }
+  def initialize(options)
+    super
+    @title = Chingu::Text.new(:text => "Press 'S' to Start game", :x=>100, :y=>50, :size=>30)
+    self.input = { :s => Level.new(:level => 10) }
   end
 end
 
@@ -76,34 +102,56 @@ end
 # GAMESTATE #3 - LEVEL (Gameplay, yay)
 #
 class Level < Chingu::GameState
-  def setup
-    @title = Chingu::Text.new(:text=>"Level #{options[:level].to_s}. Pause with 'P'", :x=>200, :y=>10, :size => 30)
-    @player = Player.new(:x => 200, :y => 200)    
-    @player.input = {:left => :move_left, :right => :move_right, :up => :move_up, :down => :move_down, :left_ctrl => :fire}
+  #
+  # initialize() is called when you create the game state
+  #
+  def initialize(options)
+    super
+    @title = Chingu::Text.new(:text=>"Level #{options[:level].to_s}. P: pause R:restart", :x=>20, :y=>10, :size=>30)
+    @player = Player.new
+    @player.input = { :holding_left => :move_left, 
+                      :holding_right => :move_right, 
+                      :holding_up => :move_up, 
+                      :holding_down => :move_down, 
+                      :left_ctrl => :fire}
     
     #
     # The input-handler understands gamestates. P is pressed --> push_gamegate(Pause)
+    # You can also give it Procs/Lambdas which it will execute when key is pressed.
     #
-    self.input = {:p => Pause, :escape => :close}  
-  end    
+    self.input = {:p => Pause, :r => lambda{ current_game_state.setup } }
+  end
+  
+  #
+  # setup() is called each time you switch to the game state (and on creation time).
+  # You can skip setup by switching with push_game_state(:setup => false) or pop_game_state(:setup => false)
+  #
+  # This can be useful if you want to display some kind of box above the gameplay (pause/options/info/... box)
+  #
+  def setup
+    # Place player in a good starting position
+    @player.x = $window.width/2
+    @player.y = $window.height - @player.image.height
+  end
 end
 
 #
 # SPECIAL GAMESTATE - Pause
 #
 class Pause < Chingu::GameState
-  def setup
+  def initialize(options)
+    super
     @title = Chingu::Text.new(:text=>"PAUSED (press 'u' to un-pause)", :x=>100, :y=>200, :size=>20, :color => Color.new(0xFF00FF00))
     self.input = { :u => :un_pause }
   end
 
   def un_pause
-    pop_gamestate             # Return the previous gamestate
+    pop_game_state(:setup => false)    # Return the previous game state, dont call setup()
   end
   
   def draw
-    previous_gamestate.draw   # Draw prev gamestate onto screen
-    super                     # Draw game objects in current game state, this includes Chingu::Texts
+    previous_game_state.draw           # Draw prev game state onto screen (in this case our level)
+    super                         # Draw game objects in current game state, this includes Chingu::Texts
   end  
 end