gemini 1.0.0 → 1.0.1

data/src/behaviors/physical_cardinal_movable.rb

@@ -1,6 +1,5 @@
-# A CardinalMovable can move north, east, south and west.
-# Movement along certain axis can be constrained, for example, pong has horizonal (north/east)
-# movement constrained
+# A CardinalMovable that interacts with the physics manager.
+# See the API for CardinalMovable for method descriptions.
 # TODO: Allow disabling of diaganol easily
 # TODO: Allow disabling of directions
 # TODO: Allow speed limit per axis
@@ -14,8 +13,8 @@ class PhysicalCardinalMovable < Gemini::Behavior
   SOUTH_EAST = :south_east
   SOUTH_WEST = :south_west
   NORTH_WEST = :north_west
-  DIAGONOL_DIRECTIONS = [NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST]
-  CARDINAL_DIRECTIONS = [NORTH, EAST, SOUTH, WEST] + DIAGONOL_DIRECTIONS
+  DIAGONAL_DIRECTIONS = [NORTH_EAST, SOUTH_EAST, SOUTH_WEST, NORTH_WEST]
+  CARDINAL_DIRECTIONS = [NORTH, EAST, SOUTH, WEST] + DIAGONAL_DIRECTIONS
   DIRECTION_TRANSLATION_IN_DEGREES = []
   
   depends_on :Physical
@@ -35,12 +34,12 @@ class PhysicalCardinalMovable < Gemini::Behavior
   def facing_direction=(direction)
     if @allowed_directions.include? direction
       if @moving && orthogonal_directions?(@facing_direction, direction)
-        diagonol_direction = begin
+        diagonal_direction = begin
                                "#{self.class}::#{@facing_direction.to_s.upcase}_#{direction.to_s.upcase}".constantize
                              rescue
                                "#{self.class}::#{direction.to_s.upcase}_#{@facing_direction.to_s.upcase}".constantize
                              end
-        @facing_direction = diagonol_direction
+        @facing_direction = diagonal_direction
       else
         @facing_direction = direction
       end
@@ -64,7 +63,7 @@ class PhysicalCardinalMovable < Gemini::Behavior
   
   def end_cardinal_movement(message)
     direction = message.value
-    @facing_direction = other_direction(@facing_direction, direction) if diagonol_direction? @facing_direction
+    @facing_direction = other_direction(@facing_direction, direction) if diagonal_direction? @facing_direction
     if @facing_direction == direction
       @cardinal_velocity = Vector.new(0,0)
       @moving = false
@@ -72,7 +71,9 @@ class PhysicalCardinalMovable < Gemini::Behavior
       @cardinal_velocity = direction_to_polar_vector(@facing_direction)
     end
   end
-  
+
+private
+
   def direction_to_polar_vector(direction)
     angle = case direction
             when NORTH
@@ -95,12 +96,12 @@ class PhysicalCardinalMovable < Gemini::Behavior
     Vector.from_polar_vector(@cardinal_speed, angle)
   end
   
-  def diagonol_direction?(direction)
-    DIAGONOL_DIRECTIONS.include? direction
+  def diagonal_direction?(direction)
+    DIAGONAL_DIRECTIONS.include? direction
   end
   
-  def other_direction(diagonol_direction, direction)
-    diagonol_direction.to_s.sub(direction.to_s, '').sub('_', '').to_sym
+  def other_direction(diagonal_direction, direction)
+    diagonal_direction.to_s.sub(direction.to_s, '').sub('_', '').to_sym
   end
   
   def orthogonal_directions?(direction_a, direction_b)

data/src/behaviors/physical_sprite.rb

@@ -1,3 +1,4 @@
+#Gives an object a bitmap that responds appropriately to the physics engine.
 class PhysicalSprite < Gemini::Behavior
   depends_on :Sprite
   depends_on :Physical
@@ -5,15 +6,9 @@ class PhysicalSprite < Gemini::Behavior
   alias_method :set_tiled_to_bounds, :tiled_to_bounds=
   
   def load
-    #TODO: This should call a method that does the same thing for performance
-    @target.on_before_draw do
-      @target.image_rotation = @target.physical_rotation unless @target.image.nil?
-      #TODO: Only execute this if the shape is bound to the image.
-      #TODO: Call raw_move instead of x= and y=
-      position = @target.body_position
-      @target.x = position.x
-      @target.y = position.y
-    end
+    @target.on_before_draw :draw_physical_sprite
+    @offset_position = Vector.new
+    @offset_rotation = 0.0
   end
   
   def bounded_image=(new_image)
@@ -26,4 +21,25 @@ class PhysicalSprite < Gemini::Behavior
     @tiled_to_bounds = state
     @target.image_size = @target.box_size
   end
+
+  def physical_sprite_position_offset=(offset)
+    @offset_position = offset.dup
+  end
+  alias_method :set_physical_sprite_position_offset, :physical_sprite_position_offset=
+
+  def physical_sprite_rotation_offset=(offset)
+    @offset_rotation = offset
+  end
+  alias_method :set_physical_sprite_rotation_offset, :physical_sprite_rotation_offset=
+
+  def draw_physical_sprite(graphics)
+    @target.image_rotation = @target.physical_rotation unless @target.image.nil?
+    #TODO: Only execute this if the shape is bound to the image.
+    #TODO: Call raw_move instead of x= and y=
+    position = @target.body_position
+
+    offset = Vector::ORIGIN.pivot_around_degrees(@offset_position, @target.physical_rotation + @offset_rotation)
+    @target.x = position.x + offset.x
+    @target.y = position.y + offset.y
+  end
 end

data/src/behaviors/platformer_controllable.rb

@@ -61,14 +61,18 @@ class PlatformerControllable < Gemini::Behavior
 #    end
   end
   
+  #Refers to the cached result of detect_grounded to indicate whether the object is touching the ground.
   def grounded?
     @grounded
   end
   
+  #Cardinal direction the object is facing, :east or :west.
   def facing_direction
     @facing_right ? :east : :west
   end
-    
+  
+  #Move the object, setting the appropriate animation and flipping its bitmap in the appropriate direction.
+  #Takes a message with :left or :right as its value.  
   def start_move(message)
     @moving = true
     if grounded?
@@ -89,6 +93,8 @@ class PlatformerControllable < Gemini::Behavior
     end
   end
   
+  #Halt the object, setting the appropriate animation and flipping its bitmap in the appropriate direction.
+  #Takes a message with :left or :right as its value.  
   def stop_move(message)
     if grounded?
       @target.animate :stand
@@ -103,10 +109,10 @@ class PlatformerControllable < Gemini::Behavior
     end
   end
   
+  #Add vertical velocity to an object, but only if it's on the ground.
   def jump(message)
     detect_grounded
     if grounded?
-      puts "jump!"
       @target.animate :jump
       # This should help us get the object unstuck if it's sunk a little into another body
       # Although, this might also get us stuck too
@@ -119,6 +125,7 @@ class PlatformerControllable < Gemini::Behavior
     end
   end
   
+  #Determine if the object is touching the ground.
   def detect_grounded
     @target.get_collision_events.each do |collision_event|
       # shameless rip/port from Kevin Glass's platformer example, with his comments

data/src/behaviors/pointer.rb

@@ -1,3 +1,4 @@
+#Makes an object move with the mouse.
 class Pointer < Gemini::Behavior
   depends_on :Sprite
 #  depends_on :Movable2d
@@ -21,6 +22,7 @@ class Pointer < Gemini::Behavior
 #    end
   end
   
+  #Takes a message with a Vector indicating the x/y coordinates to move the object to.
   def mouse_movement(message)
     vector = message.value
     @target.move(vector.location.x, vector.location.y)

data/src/behaviors/pressable.rb

@@ -1,3 +1,4 @@
+#Makes an object change appearance when clicked.
 class Pressable < Gemini::Behavior
   depends_on :Sprite
   depends_on :Clickable
@@ -6,6 +7,9 @@ class Pressable < Gemini::Behavior
     add_tag :button, :gui, :ui
   end
   
+  #Takes a hash with the following keys and values:
+  #[:normal] The path for the image to display when the object is not pressed.
+  #[:pressed] The path for the image to display when the object is pressed.
   def images=(image_path_hash)
     @normal_image = image_path_hash[:normal]
     @pressed_image = image_path_hash[:pressed]

data/src/behaviors/receives_events.rb

@@ -1,9 +1,11 @@
+#Enables an object to respond to events.
 class ReceivesEvents < Gemini::Behavior
 
   def load
     @handled_events = []
   end
 
+  #Add a handler for a given event type.  Subsequent events of the given type will be passed to the given block or the given method name.
   def handle_event(type, method_name=nil, &block)
     if !method_name.nil?
       @target.game_state.manager(:message_queue).add_listener(type, self, @target.send(:method, method_name).to_proc)
@@ -15,6 +17,7 @@ class ReceivesEvents < Gemini::Behavior
     @handled_events << type
   end
 
+  #Unregisters all message handlers for this object.
   def unload
     @handled_events.each {|e| @target.game_state.manager(:message_queue).remove_listener(e, self)}
   end

data/src/behaviors/regional.rb

@@ -1,5 +1,6 @@
 require 'set'
 
+#Indicates that the receiver has entered/exited an area.
 class RegionalTransitionEvent
   attr_accessor :region, :spatial
   def initialize(region, spatial)
@@ -8,6 +9,7 @@ class RegionalTransitionEvent
   end
 end
 
+#Makes an object receive a RegionalTransitionEvent whenever it enters/exits a given area.
 class Regional < Gemini::Behavior
   depends_on :Spatial
   attr_accessor :dimensions, :region_shape
@@ -42,6 +44,7 @@ class Regional < Gemini::Behavior
 #    end
   end
   
+  #Indicates whether the given point is within the region's boundaries.
   def within_region?(spatial)
     half_width = dimensions.x / 2.0
     half_height = dimensions.y / 2.0
@@ -49,6 +52,8 @@ class Regional < Gemini::Behavior
     ((@target.y - half_height) < spatial.y) && ((@target.y + half_height) > spatial.y)
   end
   
+  #Indicates whether the given object existed on the previous world update.
+  #If not, it should not be considered for collision events on this update.
   def existed_last_update?(game_object)
     @last_spatials.find {|previous_game_object| game_object == previous_game_object}
   end

data/src/behaviors/repulsive.rb

@@ -0,0 +1,28 @@
+#Makes an object attract other Physical game objects towards it.
+class Repulsive < Gemini::Behavior
+  depends_on :Physical
+  
+  #The force to exert.  0 means no push.
+  attr_accessor :push
+  alias_method :set_push, :push=
+  
+  #There is no effect on targets that are beyond this distance.
+  attr_accessor :effect_radius
+  alias_method :set_effect_radius, :effect_radius=
+
+  def load
+    @push = 0
+    @effect_radius = 0
+    @target.on_update do |delta|
+      physicals = @target.game_state.manager(:game_object).game_objects.select {|game_object| game_object.kind_of? Physical}.compact
+      physicals.each do |physical|
+        next if @target == physical
+        distance = @target.position.distance_from physical
+        next if distance > @effect_radius
+        force = delta * @push / (distance * Gemini::Math::SQUARE_ROOT_OF_TWO)
+        repulsion = Vector.from_polar_vector(force, physical.position.angle_from(@target))
+        physical.add_force repulsion
+      end
+    end
+  end
+end

data/src/behaviors/rotates_to_point.rb

@@ -1,4 +1,4 @@
-# This behavior rotates to face the tracking point or game object
+# This behavior rotates to face the tracking point or game object.
 class RotatesToPoint < Gemini::Behavior
   #TODO: Add offset rotation
   depends_on :Physical
@@ -11,6 +11,7 @@ class RotatesToPoint < Gemini::Behavior
     end
   end
   
+  #The angle that the object must turn to face the rotation_target.
   def rotation_to_face_target
     #TODO: Use vector
     diff_angle = Gemini::Math.radians_to_degrees Math.atan2(@target.y - @rotation_target.y, @target.x - @rotation_target.x)

data/src/behaviors/spatial.rb

@@ -1,3 +1,4 @@
+#Gives an object x/y coordinates.
 class Spatial < Gemini::Behavior
   attr_accessor :position
   alias_method :set_position, :position=
@@ -23,16 +24,15 @@ class Spatial < Gemini::Behavior
     @position.y = y
   end
   
+  #Takes a Vector or x/y coordinates to move to.
   def move(x_or_other, y=nil)
     if y.nil?
-      if x_or_other.kind_of? Vector
-        @position = Vector.new(x_or_other.x, x_or_other.y)
       #TODO: Determine if Spatial should really suppor this behavior.
       # use case: Pipe a mouse move event directly to move
-      elsif x_or_other.kind_of? Gemini::Message
+      if x_or_other.kind_of? Gemini::Message
         @position = Vector.new(x_or_other.value.x, x_or_other.value.y)
       else
-        raise "move does not support #{x_or_other.class}"
+        @position = Vector.new(x_or_other.x, x_or_other.y)
       end
     else
       @position = Vector.new(x_or_other, y)

data/src/behaviors/sprite.rb

@@ -1,8 +1,6 @@
 require 'behaviors/drawable'
 
-# WARNING: Using Slick's image for rotation can cause some odd quirks with it
-# not quite rotating correctly (especially noticable around 180 degress).
-# @rotation stands alone for this reason, instead of using Slick's rotation
+#Makes an object draw itself as a bitmap image.
 class Sprite < Drawable
   include_class 'org.newdawn.slick.Image'
   depends_on :Spatial
@@ -15,7 +13,8 @@ class Sprite < Drawable
     @texture_coords = [Vector.new(0.0, 0.0), Vector.new(1.0, 1.0)]
     @rotation = 0.0
   end
-  
+
+  #Assign an Image to the sprite.  Takes an Image or the name of a file in the data directory.
   def image=(sprite_name)
     if sprite_name.kind_of? Image
       @image = sprite_name
@@ -25,18 +24,21 @@ class Sprite < Drawable
     set_image_size(Vector.new(@image.width, @image.height))
   end
   alias_method :set_image, :image=
-  
+
+  #Assign a Color to the sprite.
   def color=(color)
     @color = color
   end
   alias_method :set_color, :color=
-
+  
+  #Increase or decrease horizontal and vertical scale for the image.  1.0 is identical to the current scale.  If y_scale is omitted, x_scale is used for both axes.
   #TODO: Take vectors for first args as well
   def image_scaling(x_scale, y_scale = nil)
     y_scale = x_scale if y_scale.nil?
     set_image @image.get_scaled_copy(x_scale.to_f * image_size.x, y_scale.to_f * image_size.y)
   end
 
+  #Set horizontal and vertical scale for the image relative to the original.  1.0 is original scale.  If y_scale is omitted, x_scale is used for both axes.
   #TODO: Take vectors for first args as well
   def scale_image_from_original(x_scale, y_scale = nil)
     y_scale = x_scale if y_scale.nil?
@@ -44,6 +46,9 @@ class Sprite < Drawable
     set_image @original_image.get_scaled_copy(x_scale.to_f * @original_image.width, y_scale.to_f * @original_image.height)
   end
   
+  # WARNING: Using Slick's image for rotation can cause some odd quirks with it
+  # not quite rotating correctly (especially noticable around 180 degress).
+  # @rotation stands alone for this reason, instead of using Slick's rotation
   def image_rotation
     @rotation
   end
@@ -55,23 +60,28 @@ class Sprite < Drawable
   end
   alias_method :set_image_rotation, :image_rotation=
   
+  #Increment the image rotation.
   def add_rotation(rotation)
     @rotation += rotation
   end
   
+  #Flip the texture horizontally.
   def flip_horizontally
     @texture_coords[1].x, @texture_coords[0].x = @texture_coords[0].x, @texture_coords[1].x
   end
   
+  #Flip the texture vertically.
   def flip_vertically
     @texture_coords[1].y, @texture_coords[0].y = @texture_coords[0].y, @texture_coords[1].y
   end
   
+  #Returns a Vector with the x/y coordinates of the sprite Image's top left corner.
   def top_left_position
     #Vector.new(center_position.x - image_size.x / 2.0, center_position.y - image_size.y / 2.0)
     Vector.new(@target.x - image_size.x / 2.0, @target.y - image_size.y / 2.0)
   end
   
+  #Takes either a single Vector or the x/y coordinates to move the sprite Image's top left corner to.
   def move_by_top_left(move_x_or_vector, move_y = nil)
     half_width = image_size.x / 2.0
     half_height = image_size.y / 2.0
@@ -82,6 +92,7 @@ class Sprite < Drawable
     end
   end
   
+  #Draw the sprite to the given graphic context.
   def draw(graphics)
     return if @image.nil? || @image_size.nil?
     half_width = image_size.x / 2.0

data/src/behaviors/stateful.rb

@@ -1,3 +1,5 @@
+
+# Makes an object transition between states.
 # Notes from Logan:
 # I started on this behavior, and realized what I needed was multiple axises of states for my behavior
 # that I wanted to use Stateful in. This behavior is simple, and seems like it would be useful for some cases.

data/src/behaviors/taggable.rb

@@ -1,3 +1,4 @@
+#Allows an object to be categorized.
 class Taggable < Gemini::Behavior
 
   def load

data/src/behaviors/tangible.rb

@@ -1,3 +1,4 @@
+#A shape used to determine if one object collides with another.
 class TangibleBox
   attr_accessor :size
   def get_points(top_left_position, rotation)
@@ -9,6 +10,7 @@ class TangibleBox
   end
 end
 
+#Allows an object to indicate when it collides with another.
 class Tangible < Gemini::Behavior
   depends_on :Spatial
   attr_reader :tangible_shape
@@ -26,6 +28,11 @@ class Tangible < Gemini::Behavior
   end
   alias_method :set_tangible_debug_mode, :tangible_debug_mode=
 
+  #Set the shape of the object as seen by collision calculations.
+  #call-seq:
+  #set_shape(:Box, vector)
+  #set_shape(:Box, width, height)
+  #
   def set_tangible_shape(name, *args)
     @tangible_shape =  case name
                        when :Box
@@ -39,6 +46,7 @@ class Tangible < Gemini::Behavior
                        end
   end
 
+  #Indicates whether this object collides with the given object.
   def tangibly_collides_with?(other_tangible)
     #TODO: top_left isn't on spatial...
     other_shape = other_tangible.tangible_shape