shattered_controller 0.3.1 → 0.3.2

data/lib/actor/actor.rb

@@ -1,5 +1,5 @@
 module ShatteredController
-  module Actor
+  module Actor #:nodoc:
 	  def self.append_features(base)
 	    super
 	    base.extend(ClassMethods)
@@ -7,24 +7,36 @@ module ShatteredController
 	  end
 	  module ClassMethods
 
-    # An actor is the MVC encapsulated into one object.
-     # With actors, you can send requests to each of the model, view and control
-     # objects, and even retrieve results from the MVC objects.
+     # An actor is the MVC encapsulated into one object.
      #
      # Here is how it works:  You specify a actor in a game state with some starting
      # attributes:
-     # 
-     #   actor :napolean, :mood => 'snobbish'
+     #   class BattleState
+     #     actor :player
+     #     actor :bullet, :target => :player
+     #   end
      #
-     # The options are the same as the camera options, except they propogate through
-     # the MVC object(as all commands do).
+     # With a model BulletModel defined as:
+     #   class BulletModel
+     #     attr_writer :target
+     #   end
      #
-     # When obtaining a result, the result will be the a response in the following order
-     # - Model
-     # - View
-     # - Controller
+     # And our BulletModel will be created, with the target set to the player object.
      #
-     # They are sorted so that you get the most useful response first.
+     # Setting values for the actors is done prior to initialization, so:
+     #
+     #   class BulletModel
+     #     attr_writer :target
+     #     def initialize
+     #       target.run_away_from(self)
+     #     end
+     #   end 
+     #
+     # Works fine.
+     #
+     # Actors delegate to ShatteredController::Base objects, and controllers delegate to Model and View.
+     #
+     # See ShatteredController::Base for more detail.
      def actor( name, options = {} )
        before_init_call( :actor, name, options )
      end
@@ -32,11 +44,14 @@ module ShatteredController
    end
    module InstanceMethods
      
+     # This returns all of the actors created by this controller.
      def actors
        return @actors || []
      end
 
-     # Used by Base#actor
+     # Same as ShatteredController::Actor::ClassMethods#actor
+     #
+     # Returns a newly created actor
      def actor(name=nil, options={})
        raise Error, "actor needs a name" if name.nil?
        actor = Actor.new(name,load_actor_classes(name))
@@ -46,6 +61,7 @@ module ShatteredController
 
        @actors ||= []
        @actors << actor
+       return actor
      end
      
      private
@@ -68,7 +84,7 @@ module ShatteredController
    end
 
    # An actor is a delegator to a controller game object.
-   class Actor
+   class Actor #:nodoc:all
      attr_reader :controller
      def initialize( name, options = {} )
        @actor_name = name

data/lib/base.rb

@@ -6,34 +6,94 @@ $:.unshift(File.dirname(__FILE__)) unless
 require 'keyboard_input/keyboard_input'
 require 'actor/actor'
 
-module ShatteredController
+module ShatteredController #:nodoc:
 	
+	 # Controllers tie together the Model and View.  They are the only objects that know
+	 # about both the model and the view, and as such have the responsibility of events.
+	 #
+	 # By default, when an unknown method is invoked on a controller object, it is delegated
+	 # to the model and the view. IE:
+	 #
+	 #   class BulletController < ...
+	 #     def known_method
+	 #       puts "This will not be delegated to the " + model.inspect + " or the " + view.inspect
+   #     end
+	 #   end
+	 #
+	 #   class BattleState < ...
+	 #     actor :bullet
+	 #     def initialize
+	 #       bullet.known_method # This is not delegated
+	 #       bullet.unknown_method # This is delegated (and will throw an exception if unknown among the view/model)
+	 #     end
+	 #   end
+	 #
+   # When obtaining a result from a delegated method, the result will be the a response in the following order
+   # - Model (first)
+   # - View  (last)
+   #
+   # They are sorted so that you get the most useful response first.
 	class Base < ShatteredSupport::Base
 	  attr_accessor :model, :view
+	  
+	  before_init_call :disable_event
 
 	  # Controller delegates all unknown methods to the view and model.
 	  def method_missing(method_name, *args, &block)
+	    return if disabled?
 	    raise_no_method_error = true
 	    result = nil
 	    [view, model].each do |delegate|
 	      if delegate.method_defined?(method_name)
-	        result = delegate.send(method_name, *args, &block) 
+	        result = delegate.send(method_name, *args, &block)
 	        raise_no_method_error = false
         end
 	    end
+	    
 	    raise NoMethodError, "Model, View, and Controller have no method defined named '#{method_name}'" if raise_no_method_error
 	    return result
 	  end
     
     
-    def update_timer(time_elapsed)
+    def update_timer(time_elapsed)
+      return if @timer == :unloaded
       timer.update(time_elapsed)
       model.timer.update(time_elapsed)
       view.timer.update(time_elapsed)
 unless view.nil?
     end
+    
+    # This is called to the State every frame by the main game loop.  All update events are now
+    # run through Timers.
+    def update_timers(time_elapsed) #:nodoc:
+      update_timer(time_elapsed)
+      actors.each { |actor| actor.update_timers(time_elapsed) }
+    end
+    
+    # Unloading a controller will completely unload an object from the scene.
+    def unload!
+      super
+    end
+  
+    # An object is disabled when it has been unloaded.
+    def disabled?
+      super
+    end
+    
+    private
+    
+    def disable_event
+      when_unloaded do
+        @disabled = true
+        @timer=:unloaded
+        @model.send(:unload!) if @model
+        @model = nil
+        @view.send(:unload!) if @view
+        @view = nil
+      end
+    end
 	end
 	
-	class Error < StandardError
+	class Error < StandardError #:nodoc:
   end
 end
 

data/lib/keyboard_input/key_converter.rb

@@ -1,7 +1,7 @@
 module ShatteredController
 # This is a wrapper around Ogre's input listener.
 # It allows us to query the status of each device every frame.
-class KeyConverter
+class KeyConverter #:nodoc:
 
   def initialize( ogre_input )
     @ogre_input = ogre_input

data/lib/keyboard_input/keyboard_input.rb

@@ -4,7 +4,7 @@ $:.unshift(File.dirname(__FILE__)) unless
 require 'key_converter'
 
 module ShatteredController
-  module KeyboardInput
+  module KeyboardInput #:nodoc:
 	  def self.append_features(base)
 	    super
 	    base.extend(ClassMethods)
@@ -44,38 +44,45 @@ module ShatteredController
 	      super
       end
 	    
-	    def key_types
+	    def reaction_types
 	      [:pressed, :released, :held]
 	    end
 	    # Given an input of:
 	    #   key :held=>:up, :action => :key_action
-	    #   This will return [:held, :up, :key_action]
-	    #  This is not used. Todo: use in new_key
-	    def reaction_from(options)
+	    #   This will return [:held, :key_action]
+	    def reaction_from(options) #:nodoc:
 	      # Define the method to send the actions when the keys are pressed/clicked/released.
-	      key_types.each do |reaction|
-	        return [reaction, options[reaction].to_sym, options[:action]] if !options[reaction].nil?
+	      reaction_types.each do |reaction_type|
+	        if options.has_key?(reaction_type)
+	          return [reaction_type, options[reaction_type]] if options[reaction_type].is_a? Array
+	          return [reaction_type, [options[reaction_type]]]
+	        end
 	      end
 	      raise Error, "Reaction to key input must be pressed, released, or held. #{options.inspect}" if options[:reaction].nil?
 	    end
 	    # See KeyboardInput::key
 	    def key(actions={})
-	      key_actions << reaction_from(actions)
+	      reaction, keys = reaction_from(actions)
+	      keys.each { |key| key_actions << [reaction, key.to_sym, actions[:action] ] }
 	    end
 	    # Update_key will send each of the events to the actor object for whatever key options
 	    # are defined.
-	    def key_action(reaction, action, time_elapsed)
+	    def key_action(reaction, action, time_elapsed) #:nodoc:
 	      if reaction == :held
-	        send(action, time_elapsed)
+	        begin
+	          send(action, time_elapsed)
+	        rescue ArgumentError
+            send(action)
+	        end
 	      else
 	        send(action)
 	      end
 	    end
-	    def key_actions
+	    def key_actions #:nodoc:
 	      @key_actions ||= []
 	    end
 	    # update_input takes the input object, and sends the actor every key event this frame.
-	    def update_input(time_elapsed, input)
+	    def update_input(time_elapsed, input) #:nodoc:
 	      key_actions.each do |reaction, key, action|
 	        key_action( reaction, action, time_elapsed ) if input.key_event?(reaction,key)
 	      end

data/lib/mock_camera.rb

@@ -1,6 +1,6 @@
 
-module ShatteredController
-	class MockCamera
+module ShatteredController 
+	class MockCamera #:nodoc:
 		attr_reader :position
 		def position=(x,y,z)
 		  @position=[x,y,z]

data/lib/runner.rb

@@ -2,7 +2,7 @@
 module ShatteredController
   #The class Runner is present in model, view, and controller, and signifies the
   #main entry point into the program.  This is called by script/runner.rb
-  class Runner
+  class Runner #:nodoc:
     def initialize( options = {} )
       @@environment ||= options
       @@environment[:input] = ShatteredController::KeyConverter.new(@@environment[:input])

data/lib/state.rb

@@ -9,7 +9,7 @@ module ShatteredController
     # In order to set the initial position of the camera, and any other attributes you would like,
     # use the following format.
     #  class CameraTestState < ShatteredController::Base
-    #    camera :position => [10,0,0], :orientation => [0.5, 0.5, 0.5, 0.5]
+    #    camera :position => v(10,0,0), :orientation => [0.5, 0.5, 0.5, 0.5]
     #  end
     #  
     # If you pass a symbol as a value, the symbol will be evaluated.
@@ -35,31 +35,25 @@ module ShatteredController
       before_init_set( "self", { :"sky" => [type, options[:material]] })
     end
   end
+  # State is the entry point for your shattered game.
+  #
+  # States define the actors, communications between the actors, and control the camera.
+  # You can choose your starting state in config/environment.rb
   class State < ShatteredController::Base      
-    
-    def pre_initialize
+    before_init_call :activate_state
+    def activate_state #:nodoc:
       ShatteredSupport::Configuration.environment[:state] = self
-      super
     end
-    def camera(*args)
+    
+    # Returns the camera used in the state. See ShatteredController::ClassMethods#camera
+    def camera(*args)
       if args.length == 0
         return @camera ||= Runner.environment[:camera]
       end
       call_object_function_for_each_key(:camera, args[0])
     end
     
-    # This is called every frame by the main game loop.  All update events are now
-    # run through Timers.
-    def update_timers(time_elapsed)
-      update_timer(time_elapsed)
-      actors.each { |actor| actor.update_timer(time_elapsed) }
-    end
-    
-    def unload!
-      actors.each { |actor| actor.unload! }      
-    end
-    
-    def sky=(type, material)
+    def sky=(type, material) #:nodoc:
       Runner.environment[:scene].send("setSky#{type.to_s.capitalize}",material)
     end
   end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.10
 specification_version: 1
 name: shattered_controller
 version: !ruby/object:Gem::Version 
-  version: 0.3.1
-date: 2006-05-16
+  version: 0.3.2
+date: 2006-06-04
 summary: "Shattered Controller: Controls the game states and objects in Shattered."
 require_paths: 
   - lib