gemini 1.0.0 → 1.0.1

data/bin/gemini

@@ -2,17 +2,25 @@
 $LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), '..', 'src'))
 require 'project_generator'
 
-rawr_install_args = ''
-project_dir = nil
-until ARGV.empty?
-  arg = ARGV.shift
-  case arg
-  when /-RI(.+)/
-    rawr_install_args << $1 + ' '
-  else
-    project_dir = arg
+begin
+  rawr_install_args = ''
+  project_dir = nil
+  until ARGV.empty?
+    arg = ARGV.shift
+    case arg
+    when /-RI(.+)/
+      rawr_install_args << $1 + ' '
+    else
+      project_dir = arg
+    end
   end
+  raise "No project dir provided" if project_dir.nil?
+  generator = Gemini::ProjectGenerator.new(:project_dir => project_dir, :rawr_install => rawr_install_args)
+  generator.generate_project
+rescue => exception
+  abort [
+    "Usage: gemini [-RI--no-download] <dir_name>",
+    "Error: #{exception.message}",
+    exception.backtrace
+  ].join("\n")
 end
-raise "No project dir provided" if project_dir.nil?
-generator = Gemini::ProjectGenerator.new(:project_dir => project_dir, :rawr_install => rawr_install_args)
-generator.generate_project

data/src/base_state.rb

@@ -38,19 +38,13 @@ module Gemini
     end
     
     def create_on_layer(type, layer_name, *params)
-      game_object_type = begin
+      game_object_type = if :game_object == type.to_sym || :GameObject == type.to_sym
+                           Gemini::GameObject
+                         elsif Module.const_defined?(type.camelize.to_sym)
                            type.constantize
-                         rescue NameError
-                           begin
-                             require type.underscore
-                             begin
-                               type.constantize
-                             rescue NameError
-                               "Gemini::#{type}".constantize
-                             end
-                           rescue LoadError
-                             "Gemini::#{type}".constantize
-                           end
+                         else
+                           require type.underscore
+                           type.camelize.constantize
                          end
       game_object = game_object_type.new(self, *params)
       add_game_object_to_layer game_object, layer_name

data/src/behaviors/animated_sprite.rb

@@ -1,3 +1,4 @@
+#A 2D sprite with mutltiple frames of animation.
 class AnimatedSprite < Gemini::Behavior
   include_class 'org.newdawn.slick.Image'
   include_class 'org.newdawn.slick.Animation'
@@ -17,7 +18,8 @@ class AnimatedSprite < Gemini::Behavior
     end
     @mode = :normal
   end
-  
+
+  #Takes one or more Images or names of files in the data directory to add to the animation.
   def sprites(*sprite_names)
     sprite_names.each do |sprite_name|
       if sprite_name.kind_of? Image
@@ -29,12 +31,14 @@ class AnimatedSprite < Gemini::Behavior
     @target.set_image @animation.current_frame
   end
   alias_method :set_sprites, :sprites
-  
+
+  #Sets frames per second for the animation.
   def animation_fps(fps)
     @fps = fps
     (0...@animation.frame_count).each {|i| @animation.set_duration(i, 1000.0/@fps)}
   end
   
+  #Sets animation mode.  Possible values are :normal, :looping, or :ping_pong.
   def animation_mode(mode)
     case mode
     when :normal

data/src/behaviors/audible.rb

@@ -1,9 +1,14 @@
+#Makes an object emit sounds.
 class Audible < Gemini::Behavior
   
+  #Load a sound file and assign a reference to it, which can later be passed to emit_sound.
   def load_sound(reference, path)
     @target.game_state.manager(:sound).add_sound(reference, path)
   end
-  
+
+  #Plays a sound whose reference was assigned via load_sound.
+  #Pass in volume to play it back quieter or louder (1.0 is normal).
+  #Pass in pitch for a higher or lower tone (1.0 is normal).
   def emit_sound(reference, volume = 1.0, pitch = 1.0)
     @target.game_state.manager(:sound).play_sound(reference, volume, pitch)
   end

data/src/behaviors/axis_stateful.rb

@@ -1,4 +1,6 @@
+#Makes an object transition between several states in succession.
 class AxisStateful < Gemini::Behavior
+  #Indicates that an object has transitioned from one state to another along an axis.
   class AxialStateTransferEvent
     attr_accessor :before_state, :after_state, :axis
     def initialize(axis, before_state, after_state)

data/src/behaviors/big_sprite.rb

@@ -1,6 +1,6 @@
-# Simplistic implementation of a big image to be used as a background image
 require 'behaviors/drawable'
 
+#Simplistic implementation of a big image to be used as a background image.  See Sprite.
 class BigSprite < Drawable
   include_class 'org.newdawn.slick.BigImage'
   attr_accessor :image
@@ -38,6 +38,7 @@ class BigSprite < Drawable
     end
   end
   
+  #Takes a BigImage, but is otherwise identical to Sprite.set_image.
   def image=(sprite_name)
     if sprite_name.kind_of? BigImage
       @image = sprite_name

data/src/behaviors/bounding_box_collidable.rb

@@ -1,6 +1,7 @@
 require 'behavior_event'
 include_class 'org.newdawn.slick.geom.Rectangle'
 
+#Makes an object generate a BoundingBoxCollisionEvent if its bounding box intersects another's.
 class BoundingBoxCollidable < Gemini::Behavior
   depends_on :Spatial2d
   
@@ -15,6 +16,7 @@ class BoundingBoxCollidable < Gemini::Behavior
   end
 end
 
+#Indicates that one object has collided with another.
 class BoundingBoxCollisionEvent < Gemini::BehaviorEvent
   attr_accessor :colliding_object, :collided_object
   

data/src/behaviors/camera_anchored_drawable.rb

@@ -1,4 +1,4 @@
-# These are sprites that deliberately ignore the scrolling of the render manager.
+#These are sprites that deliberately ignore the scrolling of the render manager.
 class CameraAnchoredDrawable < Gemini::Behavior
   #TODO: Change this to Drawable when the engine supports overriding declared methods (such as draw)
   depends_on :Sprite

data/src/behaviors/cardinal_movable.rb

@@ -1,7 +1,6 @@
 # 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
-# TODO: Allow disabling of diaganol easily
+# TODO: Allow disabling of diagonal easily
 # TODO: Allow disabling of directions
 # TODO: Allow speed limit per axis
 # TODO: Allow speed limit per direction
@@ -14,8 +13,8 @@ class CardinalMovable < 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 :Tangible
@@ -39,12 +38,12 @@ class CardinalMovable < 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
@@ -52,12 +51,16 @@ class CardinalMovable < Gemini::Behavior
   end
   alias_method :set_facing_direction, :facing_direction=
 
+  #Set direction(s) the object is allowed to move in.
+  #Takes either a single directional constant, or an Array of them.
   def constrain_direction(directions)
     directions = [directions] unless directions.kind_of? Array
     directions.each
     directions.each { |direction| @allowed_directions.delete direction }
   end
 
+  #Initiate movement in a given direction.
+  #Takes a message with a directional constant as its value.
   def begin_cardinal_movement(message)
     direction = message.value
     return unless @allowed_directions.include? direction
@@ -66,9 +69,11 @@ class CardinalMovable < Gemini::Behavior
     @cardinal_velocity = direction_to_polar_vector(@facing_direction)
   end
 
+  #Halt movement in a given direction.
+  #Takes a message with a directional constant as its value.
   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
@@ -76,6 +81,8 @@ class CardinalMovable < Gemini::Behavior
       @cardinal_velocity = direction_to_polar_vector(@facing_direction)
     end
   end
+  
+private
 
   def direction_to_polar_vector(direction)
     angle = case direction
@@ -99,12 +106,12 @@ class CardinalMovable < 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/clickable.rb

@@ -1,3 +1,4 @@
+#Makes an object clickable with the mouse.
 class Clickable < Gemini::Behavior
   depends_on :ReceivesEvents
   depends_on :Regional

data/src/behaviors/countable.rb

@@ -1,3 +1,4 @@
+#Makes an object receive events when its numbers have changed.
 class Countable < Gemini::Behavior
   attr_accessor :count
   wrap_with_callbacks :count=

data/src/behaviors/debug_physical.rb

@@ -1,8 +1,17 @@
-class DebugPhysical < Gemini::Behavior #Drawable
-  #declared_methods :draw
-  PhysVector = Java::net::phys2d::math::Vector2f
-  SlickVector = Java::org::newdawn::slick::geom::Vector2f
-  
+#Makes an object draw its interactions with the physics engine on the screen.
+class DebugPhysical < Gemini::Behavior
+
+  PhysVector   = Java::net::phys2d::math::Vector2f
+  PhysCircle   = Java::net.phys2d.raw.shapes.Circle
+  PhysPolygon  = Java::net.phys2d.raw.shapes.Polygon
+  PhysLine  = Java::net.phys2d.raw.shapes.Line
+  SlickVector  = Java::org::newdawn::slick::geom::Vector2f
+  SlickPolygon = Java::org.newdawn.slick.geom.Polygon
+  SlickCircle  = Java::org.newdawn.slick.geom.Circle
+  SlickLine    = Java::org.newdawn.slick.geom.Line
+
+  include_class 'net.phys2d.raw.shapes.Box'
+
   def load
     @target.game_state.manager(:render).on_after_render do |graphics|
       draw(graphics)
@@ -10,19 +19,22 @@ class DebugPhysical < Gemini::Behavior #Drawable
   end
   
   def unload
-    # Remove listener for after render
+    # TODO: Remove listener for after render?
   end
-  
+
+private
   def draw(graphics)
     #TODO: Support joints and composite bodies(?)
     body = @target.instance_variable_get(:@__behaviors)[:Physical].instance_variable_get(:@body)
     physics_shape = body.shape
-    graphics_shape = if physics_shape.kind_of?(Java::net::phys2d::raw::shapes::Box)
-                       Java::org.newdawn.slick.geom.Polygon.new(physics_shape.get_points(body.position, body.rotation).map{|point| [point.x, point.y]}.flatten.to_java(:float))
-                     elsif physics_shape.kind_of?(Java::net.phys2d.raw.shapes.Polygon)
-                       Java::org.newdawn.slick.geom.Polygon.new(physics_shape.get_vertices(body.position, body.rotation).map{|point| [point.x, point.y]}.flatten.to_java(:float))
-                     elsif physics_shape.kind_of? Java::net.phys2d.raw.shapes.Circle
-                       Java::org.newdawn.slick.geom.Circle.new(body.position.x, body.position.y, physics_shape.radius)
+    graphics_shape = if physics_shape.kind_of? Box
+                       SlickPolygon.new(physics_shape.get_points(body.position, body.rotation).map{|point| [point.x, point.y]}.flatten.to_java(:float))
+                     elsif physics_shape.kind_of? PhysPolygon
+                       SlickPolygon.new(physics_shape.get_vertices(body.position, body.rotation).map{|point| [point.x, point.y]}.flatten.to_java(:float))
+                     elsif physics_shape.kind_of? PhysCircle
+                       SlickCircle.new(body.position.x, body.position.y, physics_shape.radius)
+#                     elsif physics_shape.kind_of? PhysLine
+#                       SlickLine.new(body_position.x, )
                      else
                        raise "#{self.class} does not know how to draw the shape #{physics_shape.class}"
                      end

data/src/behaviors/debug_tangible.rb

@@ -1,3 +1,4 @@
+#Makes an object draw its collisions on the screen.
 class DebugTangible < Gemini::Behavior #Drawable
   #declared_methods :draw
   PhysVector = Java::net::phys2d::math::Vector2f

data/src/behaviors/drawable.rb

@@ -1,3 +1,4 @@
+#Makes an object draw itself to the screen.
 class Drawable < Gemini::Behavior
   depends_on_kind_of :Spatial
   wrap_with_callbacks :draw

data/src/behaviors/drawable_shape.rb

@@ -1,5 +1,6 @@
 require 'behaviors/drawable'
 
+#Makes an object draw itself on the screen as a polygon.
 class DrawableShape < Drawable
   include_class 'org.newdawn.slick.geom.Vector2f'
   include_class 'org.newdawn.slick.geom.Polygon'
@@ -12,6 +13,9 @@ class DrawableShape < Drawable
     $v = 0.0
   end
 
+  #Set the shape to draw.
+  #Accepts :Polygon or the name of a class in the DrawableShape namespace.
+  #TODO: There are no DrawableShape::* classes yet!
   def set_visual_shape(shape, *params)
     if shape == :polygon || shape == :Polygon
       @visual_shape = "#{self.class}::#{shape}".constantize.new
@@ -25,9 +29,6 @@ class DrawableShape < Drawable
   
   def image=(image)
     @image = image
-    puts "width: #{@image.width}, height: #{@image.height}"
-    puts "width / screen width: #{@image.width.to_f / @target.game_state.screen_width.to_f}"
-    puts "1/width: #{1.0 / @image.width.to_f}"
   end
   alias_method :set_image, :image=
 

data/src/behaviors/fading_image_trail_emittable.rb

@@ -1,3 +1,4 @@
+#Makes an object leave a trail of images behind it that fade over time.
 class FadingImageTrailEmittable < Gemini::Behavior
   depends_on :Updates
   
@@ -17,10 +18,13 @@ class FadingImageTrailEmittable < Gemini::Behavior
     end 
   end
   
+  #Sets the Image to emit.
   def emit_fading_image(image)
     @image = image
   end
   
+  #Causes fading images to appear at some distance away from object.
+  #Takes a Vector with the x/y offset at which to emit the images.
   def emit_fading_image_trail_from_offset(offset)
     @fading_image_offset = offset
   end

data/src/behaviors/game_object_emittable.rb

@@ -1,3 +1,4 @@
+#Makes an object create other objects.
 class GameObjectEmittable < Gemini::Behavior
   attr_accessor :emitting_game_object_name
   alias_method :set_emitting_game_object_name, :emitting_game_object_name=

data/src/behaviors/gravity_source.rb

@@ -1,7 +1,8 @@
-# Enables game objects to attract other Physical game objects towards it
+#Makes an object attract other Physical game objects towards it.
 class GravitySource < Gemini::Behavior
   depends_on :Physical
   
+  #The attractive force to exert.  0 means no pull.
   attr_accessor :gravity
   alias_method :set_gravity, :gravity=
 
@@ -18,4 +19,4 @@ class GravitySource < Gemini::Behavior
       end
     end
   end
-end
+end

data/src/behaviors/inertial.rb

@@ -1,5 +1,8 @@
+#Makes an object resist changes in velocity.
 class Inertial < Gemini::Behavior
   depends_on :UpdatesAtConsistantRate
+  
+  #A 2-element array with x/y inertial values. 0 means no resistance to acceleration.
   attr_accessor :inertia
   
   def load

data/src/behaviors/movable2d.rb

@@ -1,3 +1,4 @@
+#Makes an object move within a 2D plane.
 class Movable2d < Gemini::Behavior
   depends_on :Spatial2d
   wrap_with_callbacks :move

data/src/behaviors/multi_animated_sprite.rb

@@ -1,10 +1,16 @@
+#Gives an object multiple animations it can switch between.
 class MultiAnimatedSprite < Gemini::Behavior
   depends_on :AnimatedSprite
   
   def load
     @animations = {}
   end
-  
+
+  #Add an animation for later use.
+  #Takes a hash with the following keys and values:
+  #[:name] The name to assign the animation.
+  #[:sprites] A list of Image names.
+  #[:speed] The speed at which to animate.
   def add_animation(options)
     name    = options[:name]
     sprites = options[:sprites]

data/src/behaviors/physical.rb

@@ -1,10 +1,10 @@
 require 'behaviors/spatial'
 
+#Makes an object interact with the physics engine.
 class Physical < Gemini::Behavior
-  # TODO: Move to Math?
-  SQUARE_ROOT_OF_TWO = Math.sqrt(2)
+
   INFINITE_MASS = Java::net::phys2d::raw::Body::INFINITE_MASS
-  
+
   include_class "net.phys2d.raw.Body"
   include_class "net.phys2d.raw.shapes.Box"
   include_class "net.phys2d.raw.shapes.Circle"
@@ -14,12 +14,13 @@ class Physical < Gemini::Behavior
   include_class "net.phys2d.math.Vector2f"
   include_class 'net.phys2d.raw.AngleJoint'
   include_class 'net.phys2d.raw.BasicJoint'
-  
+  include_class 'net.phys2d.raw.SpringJoint'
+
   attr_reader :mass, :name, :shape
   depends_on :Spatial
   depends_on :Updates
-  wrap_with_callbacks :mass=
-  
+  wrap_with_callbacks :mass=, :add_to_world, :body_position=, :set_body_position
+
   def load
     @mass = 1
     @shape = Box.new(1,1)
@@ -30,27 +31,32 @@ class Physical < Gemini::Behavior
     @target.enable_listeners_for :physical_collided
     @target.on_after_move { move @target.x , @target.y}
     # Manual angular damping. New Phys2D may support this? If not, file a bug.
-    @target.on_update {|delta| set_angular_velocity(angular_velocity - (angular_velocity * (@angular_damping * (1.0/mass) ))) }
+    @target.on_update do |delta|
+      next if @angular_damping.zero? || angular_velocity.zero?
+      decay = (delta * @angular_damping * angular_velocity) / (mass * shape.surface_factor)
+      set_angular_velocity(angular_velocity - decay) unless decay.nan?
+    end
   end
-  
+
   def add_excluded_physical(physical_game_object)
     @body.add_excluded_body physical_game_object.instance_variable_get(:@__behaviors)[:Physical].instance_variable_get(:@body)
   end
-  
+
   def physics_bitmask
     @body.bitmask
   end
-  
+
   def physics_bitmask=(bitmask)
     @body.bitmask = bitmask
   end
   alias_method :set_physics_bitmask, :physics_bitmask=
-  
-  
+
+
   def body_position
     @body.position
   end
-  
+
+  #Takes a Vector with the x/y coordinates to move the object to.
   def body_position=(vector)
     # set_position doesn't take a vector, only x/y
     @body.set_position(vector.x, vector.y)
@@ -58,24 +64,29 @@ class Physical < Gemini::Behavior
   alias_method :set_body_position, :body_position=
 
   # See about Phys2D joints here: http://www.cokeandcode.com/phys2d/source/javadoc/net/phys2d/raw/Joint.html
-  # what do we do with the joint? Just let it die when the objects die? Makes sense to me.
-  # Both physicals might want to own the joint
-  # This seems to need more work
+  # TODO: Make the joint a game object and/or behavior
   def join_to_physical(physical_game_object, options={})
     other_body = physical_game_object.instance_variable_get(:@__behaviors)[:Physical].instance_variable_get(:@body)
-    case options[:joint]
-    when :angle
-      AngleJoint.new(@body, other_body, options[:self_body_point].to_phys2d_vector, options[:other_body_point].to_phys2d_vector, options[:self_body_angle], options[:other_body_angle])
-    when :basic
-      BasicJoint.new(@body, other_body, options[:anchor].to_phys2d_vector)
-    else
-      raise "Joint type #{options[:joint].inspect} not supported."
-    end
+    joint = case options[:joint]
+            when :angle
+              AngleJoint.new(@body, other_body, options[:self_body_point].to_phys2d_vector, options[:other_body_point].to_phys2d_vector, options[:self_body_angle], options[:other_body_angle])
+            when :basic
+              joint = BasicJoint.new(@body, other_body, options[:anchor].to_phys2d_vector)
+              joint.relaxation = options[:relaxation] if options[:relaxation]
+              joint
+            when :spring
+              joint = SpringJoint.new(@body, other_body, options[:self_anchor].to_phys2d_vector, options[:other_anchor].to_phys2d_vector)
+              joint
+            else
+              raise "Joint type #{options[:joint].inspect} not supported."
+            end
+    @world.add joint
   end
 
+  #The maximum speed the object is allowed to travel.  Takes either a Vector with the x/y limits or the numeric value to assign to both x and y.
   def speed_limit=(vector_or_shared_value)
     if vector_or_shared_value.kind_of? Numeric
-      axis_limit_x = axis_limit_y = vector_or_shared_value / SQUARE_ROOT_OF_TWO
+      axis_limit_x = axis_limit_y = vector_or_shared_value / Gemini::Math::SQUARE_ROOT_OF_TWO
     else
       axis_limit_x = vector_or_shared_value.x
       axis_limit_y = vector_or_shared_value.y
@@ -83,7 +94,7 @@ class Physical < Gemini::Behavior
     @body.set_max_velocity(axis_limit_x, axis_limit_y)
   end
   alias_method :set_speed_limit, :speed_limit=
-  
+
 #  def safe_move=(safe_move)
 #    @safe_move = safe_move
 #    if safe_move
@@ -101,7 +112,9 @@ class Physical < Gemini::Behavior
 #    end
 #  end
 #  alias_method :set_safe_move, :safe_move=
-  
+
+  #Attempt to move the object to the given coordinates.
+  #Note that the object might be blocked if its path intersects another physical object.
   def wish_move(x, y)
     # WARNING: @body.last_position is not to be trusted. We'll just handle it ourselves.
     @last_x = @target.x
@@ -109,45 +122,50 @@ class Physical < Gemini::Behavior
     @body.move(x, y)
     #@body.set_position(@last_x, @last_y) if @target.game_state.manager(:physics).colliding? @body
   end
-  
+
   def width
     @body.shape.bounds.width
   end
-  
+
   def height
     @body.shape.bounds.height
   end
-  
+
   def radius
     @body.shape.radius
   end
-  
+
   def box_size
     @body.shape.size
   end
-  
-  def physical_rotation=(rotation)
-    @body.rotation = Gemini::Math.degrees_to_radians(rotation)
+
+  #Set the absolute rotation.
+  def physical_rotation=(degrees)
+    @body.rotation = Gemini::Math.degrees_to_radians(degrees)
   end
   alias_method :set_physical_rotation, :physical_rotation=
-  
+
+  #Set the rotation relative to the current rotation.
   def rotate_physical(degrees)
     @body.adjust_rotation Gemini::Math.degrees_to_radians(degrees)
   end
-  
+
   def physical_rotation
     Gemini::Math.radians_to_degrees(@body.rotation)
   end
-  
+
   def physical_rotatable?
     @body.rotatable?
   end
-  
+
+  #Set whether the object is allowed to rotate.
   def physical_rotatable=(rotatable)
     @body.rotatable = rotatable
   end
   alias_method :set_physical_rotatable, :physical_rotatable=
-  
+
+  #Push on the object.
+  #Takes either a Vector or x/y values representing the force to apply.
   def add_force(x_or_vector, y = nil)
     if y.nil?
       @body.add_force(x_or_vector.to_phys2d_vector)
@@ -155,15 +173,18 @@ class Physical < Gemini::Behavior
       @body.add_force(Vector2f.new(x_or_vector, y))
     end
   end
-  
+
+  #Set the force being applied to the object.  Disregards all other forces.
   def set_force(x, y)
     @body.set_force(x, y)
   end
-  
+
   def force
     @body.force
   end
-  
+
+  #Adjust the object's velocity.
+  #Takes either a Vector or x/y values representing the adjustment to make.
   def add_velocity(x_or_vector, y = nil)
     if x_or_vector.kind_of? Vector
       @body.adjust_velocity(x_or_vector.to_phys2d_vector)
@@ -171,25 +192,30 @@ class Physical < Gemini::Behavior
       @body.adjust_velocity(Java::net::phys2d::math::Vector2f.new(x_or_vector, y))
     end
   end
-  
+
   def velocity
     @body.velocity.to_vector
   end
-  
+
   def velocity=(vector)
     @body.adjust_velocity(Java::net::phys2d::math::Vector2f.new(vector.x - @body.velocity.x, vector.y - @body.velocity.y))
   end
   alias_method :set_velocity, :velocity=
-  
+
   def angular_velocity
     @body.angular_velocity
   end
-  
+
   def angular_velocity=(delta)
     @body.adjust_angular_velocity(delta - angular_velocity)
   end
   alias_method :set_angular_velocity, :angular_velocity=
-  
+
+  def apply_angular_velocity(velocity)
+    @body.adjust_angular_velocity velocity
+  end
+
+  #Immediately halt movement.
   def come_to_rest
     current_velocity = @body.velocity
     add_velocity(-current_velocity.x, -current_velocity.y)
@@ -197,7 +223,9 @@ class Physical < Gemini::Behavior
     @body.is_resting = true
   end
 
-  # numbers or :infinite
+  #Takes the following values:
+  #[:infinite] Object has infinite mass.
+  #[number] Value to set the mass to.
   def mass=(mass)
     @mass = mass
     x, y = @target.x, @target.y
@@ -208,21 +236,28 @@ class Physical < Gemini::Behavior
     @body.move x, y
   end
   alias_method :set_mass, :mass=
-  
+
   def restitution
     @body.restitution
   end
-  
+
   def restitution=(restitution)
     @body.restitution = restitution
   end
   alias_method :set_restitution, :restitution=
-  
+
+  #Set the shape of the object as seen by the physics engine.
+  #call-seq:
+  #set_shape(:Box, width, height)
+  #set_shape(:Circle, radius)
+  #set_shape(:Polygon, *vectors)
+  #
   def set_shape(shape, *params)
     # Save off data that is destroyed when @body.set is called
     saved_damping = damping
     saved_angular_damping = angular_damping
     saved_body_position = body_position
+    saved_friction = friction
     saved_position = @target.position
     saved_x, saved_y = @target.x, @target.y
     if shape.respond_to?(:to_str) || shape.kind_of?(Symbol)
@@ -238,91 +273,102 @@ class Physical < Gemini::Behavior
     @body.set(@shape, @mass)
     set_body_position saved_body_position
     @target.set_position saved_position
+    set_friction saved_friction
     @target.move(saved_x, saved_y)
     self.damping = saved_damping
-    self.angular_damping = saved_angular_damping 
+    self.angular_damping = saved_angular_damping
   end
-  
+
   def name=(name)
     @name = name
     setup_body
   end
-  
+
+  #Place this object under the control of the physics engine.
   def add_to_world(world)
     world.add @body
     @world = world
   end
-  
+
+  #Remove this object from the control of the physics engine.
   def remove_from_world(world)
     world.remove @body
     @world = nil
   end
-  
-  def physical_debug_mode=(mode)
-    if mode
+
+  #Turn debug mode on or off for this object.
+  def physical_debug_mode=(flag)
+    if flag
       @target.add_behavior :DebugPhysical
     else
       @target.remove_behavior :DebugPhysical
     end
   end
   alias_method :set_physical_debug_mode, :physical_debug_mode=
-  
-  def movable=(movable)
-    @body.moveable = movable
+
+  def movable=(flag)
+    @body.moveable = flag
   end
   alias_method :set_movable, :movable=
-  
+
   def movable?
     @body.moveable?
   end
-  
+
+  #The amount of air friction slowing the object's movement.
   def damping
     @body.damping
   end
-  
+
   def damping=(damping)
     @body.damping = damping
   end
   alias_method :set_damping, :damping=
-  
+
   def angular_damping
     @angular_damping
+    #@body.rot_damping
   end
-  
+
   def angular_damping=(damping)
     @angular_damping = damping
+    #@body.rot_damping = damping
   end
-  alias_method :set_angular_damping, :damping=
-  
+  alias_method :set_angular_damping, :angular_damping=
+
+  #Set this object as immobile.
   def set_static_body
     @body.moveable = false
     @body.rotatable = false
     @body.is_resting = true
   end
-  
-  def gravity_effected=(effected)
-    @body.gravity_effected = effected
+
+  #Set whether gravity affects this object.
+  def gravity_effected=(flag)
+    @body.gravity_effected = flag
   end
   alias_method :set_gravity_effected, :gravity_effected=
-  
+
+  #The amount of friction slowing the object's movement.
   def friction
     @body.friction
   end
-  
+
   def friction=(friction)
     @body.friction = friction
   end
   alias_method :set_friction, :friction=
-  
+
 #  def get_colliding_game_objects(tangible_game_object)
 #    # TODO: Tangibles only?
 #    tangible_game_object
 #  end
-  
+
+  #Get a list of CollisionEvents for objects currently colliding with this one.
   def get_collision_events
     @world.get_contacts(@body)
   end
-  
+
 private
   def setup_body
     if @name
@@ -330,7 +376,7 @@ private
     else
       @body = Body.new(@shape, @mass)
     end
-    
+
     x = @body.position.x
     y = @body.position.y