steering_behaviors 1.0.4 → 1.0.5

data/CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog for steering-behaviors
 
+## 1.0.5, 11 August 2013
+* Added 'separate', a predictive collision-avoidance steering behavior
+
 ## 1.0.4, 8 August 2013
 * Rewrote 'arrive' to the more canonical behavior described by Reynolds
 

data/README.md

@@ -12,7 +12,7 @@ The steering behaviors expect to operate on a 'kinematic' thing. That is, the st
 
 ## Supported stering behaviors
 
-The library supports these steering behaviors:
+The library supports a variety of steering behaviors. Some of these are the 'canonical' steering behaviors documented at Craig Reynold's website (see References, below). Others are behaviors documented in game programming books or behaviors that I have found useful for my own game programming needs:
 
 * Seek: aim for and reach the specified point at top speed
 * Flee: head away from the specified point at top speed (the opposite of Seek)
@@ -20,11 +20,7 @@ The library supports these steering behaviors:
 * Pursue: given a moving target, anticipate its future position and intercept the target intelligently
 * Evade: given a moving target, anticipate its future position and avoid the target intelligently (the opposite of Pursue)
 * Wander: move about the plain in a 'random walk' way
-
-These are all standard steering behaviors documented at Craig Reynold's website (see References, below).
-
-Additionally, this library supports some other useful behaviors:
-
+* Separate: predictively steer to avoid collision with another agent, based on the closest point of approach
 * Align: align my course with the target's course, without altering my speed
 * Match: match my course and speed to those of the target
 * Broadside: expose my side to the target in the manner of a ship's broadside; useful for orbiting or exposing weapons, say

data/lib/steering_behaviors.rb

@@ -12,6 +12,12 @@ require 'steering_behaviors/match.rb'
 require 'steering_behaviors/orthogonal.rb'
 require 'steering_behaviors/pursue.rb'
 require 'steering_behaviors/seek.rb'
+require 'steering_behaviors/separation.rb'
 require 'steering_behaviors/steering.rb'
 require 'steering_behaviors/vector.rb'
 require 'steering_behaviors/wander.rb'
+
+
+SteeringBehaviors::VEC_ZERO    = SteeringBehaviors::Vector.new(0, 0)
+SteeringBehaviors::VEC_UP_NEGY = SteeringBehaviors::Vector.new(0, -1)
+SteeringBehaviors::VEC_UP_POSY = SteeringBehaviors::Vector.new(0, 1)

data/lib/steering_behaviors/align.rb

@@ -11,15 +11,15 @@ class SteeringBehaviors::Align
   # Align with a moving target by observing its course.
   #
   # * *Args*    :
-  #   - +hunter_kinematic+ -> pursuing kinematic
-  #   - +quarry_kinematic+ -> kinematic of the target
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and aligning
+  #   - +other_kinematic+ -> kinematic of the thing to align with
   # * *Returns* :
-  #   -
+  #   - a steering force
   #
-  def self.steer(hunter_kinematic, quarry_kinematic)
-    desired_velocity = quarry_kinematic.heading_vec * hunter_kinematic.velocity_vec.length
+  def self.steer(character_kinematic, other_kinematic)
+    desired_velocity = other_kinematic.heading_vec * character_kinematic.velocity_vec.length
 
-    return desired_velocity - hunter_kinematic.velocity_vec
+    return desired_velocity - character_kinematic.velocity_vec
   end
 
 end

data/lib/steering_behaviors/arrive.rb

@@ -7,31 +7,30 @@
 # the terms found in the "LICENSE" file included with the framework.
 
 class SteeringBehaviors::Arrive
-  TARGET_RADIUS=0
-
   # Arrive 'gently' at the goal position by decelerating smoothly.
   #
   # * *Args*    :
-  #   - +kinematic+ -> the thing that is moving and arriving
-  #   - +goal_position+ -> a Vector of position
-  #   - +slow_radius+ -> don't begin decelerating until inside this radius; max speed outside
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and arriving
+  #   - +goal_position+ -> a Vector of position at which to arrive
+  #   - +slow_radius+ -> don't begin decelerating until inside this radius; maintain max speed outside
+  #   - +arrive_radius+ -> consider ourselves 'arrived' when inside this radius
   # * *Returns* :
   #   - a steering force
   #
-  def self.steer(kinematic, goal_position, slow_radius=200)
-    to_target = goal_position - kinematic.position_vec
+  def self.steer(character_kinematic, goal_position, slow_radius, arrive_radius=0)
+    to_target = goal_position - character_kinematic.position_vec
     dist = to_target.length
 
-    if dist < TARGET_RADIUS
-      return SteeringBehaviors::Vector.new(0,0)
+    if dist < arrive_radius
+      return SteeringBehaviors::VEC_ZERO
     elsif dist > slow_radius
-      desired_speed = kinematic.max_speed
+      desired_speed = character_kinematic.max_speed
     else
-      desired_speed = kinematic.max_speed * dist / slow_radius
+      desired_speed = character_kinematic.max_speed * dist / slow_radius
     end
 
     desired_vel = to_target.normalize * desired_speed
 
-    return desired_vel - kinematic.velocity_vec
+    return desired_vel - character_kinematic.velocity_vec
   end
 end

data/lib/steering_behaviors/broadside.rb

@@ -12,24 +12,24 @@ class SteeringBehaviors::Broadside
   # exposing weapons, orbiting, etc.
   #
   # * *Args*    :
-  #   - +hunter_kinematic+ -> pursuing kinematic
-  #   - +quarry_kinematic+ -> kinematic of the target
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and broadsiding
+  #   - +other_kinematic+ -> kinematic of thing to broadside to
   # * *Returns* :
   #   - a steering force
   #
-  def self.steer(hunter_kinematic, quarry_kinematic)
-    to_quarry = (quarry_kinematic.position_vec - hunter_kinematic.position_vec).normalize
+  def self.steer(character_kinematic, other_kinematic)
+    to_quarry = (other_kinematic.position_vec - character_kinematic.position_vec).normalize
     option_a = SteeringBehaviors::Vector.new(to_quarry.y, -to_quarry.x)
     option_b = SteeringBehaviors::Vector.new(-to_quarry.y, to_quarry.x)
 
-    da = option_a.delta(hunter_kinematic.heading_vec)
-    db = option_b.delta(hunter_kinematic.heading_vec)
+    da = option_a.delta(character_kinematic.heading_vec)
+    db = option_b.delta(character_kinematic.heading_vec)
 
     best_hdg_vec = (da < db ? option_a : option_b)
 
-    desired_velocity = best_hdg_vec.normalize * hunter_kinematic.velocity_vec.length
+    desired_velocity = best_hdg_vec.normalize * character_kinematic.velocity_vec.length
 
-    return desired_velocity - hunter_kinematic.velocity_vec
+    return desired_velocity - character_kinematic.velocity_vec
   end
 
 end

data/lib/steering_behaviors/common.rb

@@ -8,6 +8,67 @@
 
 module SteeringBehaviors::Common
 
+  # Given two kinematics, determine how many seconds until their Closest Point of Approach (CPA)
+  #
+  # * *Args*    :
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving
+  #   - +other_kinematic+ -> kinematic of the other mover
+  # * *Returns* :
+  #   - time in seconds until CPA; may be negative (for 'in the past')
+  #
+  def compute_nearest_approach_time(character_kinematic, other_kinematic)
+    relative_vel_vec = other_kinematic.velocity_vec - character_kinematic.velocity_vec
+    relative_speed = relative_vel_vec.length
+
+    return 0 if relative_speed==0
+
+    relative_tangent_vec = relative_vel_vec / relative_speed
+    relative_position_vec = character_kinematic.position_vec - other_kinematic.position_vec
+
+    projection = relative_tangent_vec.dot(relative_position_vec)
+    return projection / relative_speed
+  end
+
+  # Given two kinematics, determine where they will be at the time of closest approach.
+  #
+  # * *Args*    :
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving
+  #   - +other_kinematic+ -> kinematic of the other mover
+  # * *Returns* :
+  #   - a tuple consisting of (time until CPA), (character position at CPA), (other position at CPA)
+  #
+  def compute_nearest_approach(character_kinematic, other_kinematic)
+    # How long until it happens?
+    cpa_time = compute_nearest_approach_time(character_kinematic, other_kinematic)
+
+    # How far will the two kinematics go in that time?
+    char_travel_vec  = character_kinematic.velocity_vec * cpa_time
+    other_travel_vec = other_kinematic.velocity_vec * cpa_time
+
+    # Project forward from current positions...
+    char_pos_vec = char_travel_vec + character_kinematic.position_vec
+    other_pos_vec = other_travel_vec + other_kinematic.position_vec
+
+    return [cpa_time, char_pos_vec, other_pos_vec]
+  end
+
+  # Given two kinematics, determine how close the two agents will be at their
+  # time & place of closest approach. Largely a convenience method, since you
+  # could call compute_nearest_approach() and do the same subtraction
+  # just as easily.
+  #
+  # * *Args*    :
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving
+  #   - +other_kinematic+ -> kinematic of the other mover
+  # * *Returns* :
+  #   - the distance between the two agents at their closest approach
+  #
+  def compute_nearest_approach_distance(character_kinematic, other_kinematic)
+    cpa_time, char_pos_vec, other_pos_vec = compute_nearest_approach(character_kinematic, other_kinematic)
+
+    (char_pos_vec - other_pos_vec).length
+  end
+
   # A support routine used by Pursue and Evade. Observes how 'forward' the
   # target is, and how 'parallel' its course is to our own.
   #

data/lib/steering_behaviors/evade.rb

@@ -14,29 +14,29 @@ class SteeringBehaviors::Evade
   # See http://www.red3d.com/cwr/steer/
   #
   # * *Args*    :
-  #   - +evading_kinematic+ -> evading kinematic
-  #   - +enemy_kinematic+ -> kinematic of the thing to evade
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and evading
+  #   - +other_kinematic+ -> kinematic of the thing to evade
   # * *Returns* :
   #   - a steering force
   #
-  def self.steer(evading_kinematic, enemy_kinematic)
-    offset          = enemy_kinematic.position_vec - evading_kinematic.position_vec
+  def self.steer(character_kinematic, enemy_kinematic)
+    offset          = enemy_kinematic.position_vec - character_kinematic.position_vec
     direct_distance = offset.length
     unit_offset     = offset / direct_distance
 
-    parallelness = evading_kinematic.heading_vec.dot(enemy_kinematic.heading_vec)
-    forwardness  = unit_offset.dot(evading_kinematic.heading_vec)
+    parallelness = character_kinematic.heading_vec.dot(enemy_kinematic.heading_vec)
+    forwardness  = unit_offset.dot(character_kinematic.heading_vec)
 
     gen, tf = compute_time_factor(forwardness, parallelness)
 
-    direct_travel_time     = direct_distance / evading_kinematic.speed
-    direct_travel_time_2   = direct_distance / (evading_kinematic.speed + enemy_kinematic.speed)
+    direct_travel_time     = direct_distance / character_kinematic.speed
+    direct_travel_time_2   = direct_distance / (character_kinematic.speed + enemy_kinematic.speed)
     estimated_time_enroute = direct_travel_time_2 * tf
 
     # printf "#{ipos.entity}'s target #{qpos.entity} is '#{gen}'. fness: %0.3f pness: %0.3f f: %0.3f p: %0.3f tf: %0.3f\n", forwardness, parallelness, f, p, tf
     predicted_pos_vec = enemy_kinematic.position_vec + (enemy_kinematic.velocity_vec * estimated_time_enroute)
 
-    return [predicted_pos_vec, SteeringBehaviors::Flee.steer(evading_kinematic, predicted_pos_vec)]
+    return [predicted_pos_vec, SteeringBehaviors::Flee.steer(character_kinematic, predicted_pos_vec)]
   end
 
 end

data/lib/steering_behaviors/flee.rb

@@ -12,13 +12,13 @@ class SteeringBehaviors::Flee
   # See http://www.red3d.com/cwr/steer/
   #
   # * *Args*    :
-  #   - +kinematic+ -> the thing that is fleeing
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and fleeing
   #   - +flee_position+ -> the position-vector that we want to flee from
   # * *Returns* :
   #   - the calculated steering force
   #
-  def self.steer(kinematic, flee_position)
-    best_velocity_to_target = (kinematic.position_vec - flee_position).normalize * kinematic.max_speed
-    best_velocity_to_target - kinematic.velocity_vec
+  def self.steer(character_kinematic, flee_position)
+    desired_velocity = (character_kinematic.position_vec - flee_position).normalize * character_kinematic.max_speed
+    force = (desired_velocity - character_kinematic.velocity_vec)
   end
 end

data/lib/steering_behaviors/match.rb

@@ -11,15 +11,15 @@ class SteeringBehaviors::Match
   # Matches the target's course and speed.
   #
   # * *Args*    :
-  #   - +hunter_kinematic+ -> my moving thing
-  #   - +quarry_kinematic+ -> kinematic of the target
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and matching
+  #   - +other_kinematic+ -> kinematic of the thing to match
   # * *Returns* :
   #   - the steering force
   #
-  def self.steer(hunter_kinematic, quarry_kinematic)
-    desired_velocity = quarry_kinematic.heading_vec * quarry_kinematic.velocity_vec.length
+  def self.steer(character_kinematic, other_kinematic)
+    desired_velocity = other_kinematic.heading_vec * other_kinematic.velocity_vec.length
 
-    return desired_velocity - hunter_kinematic.velocity_vec
+    return desired_velocity - character_kinematic.velocity_vec
   end
 
 end

data/lib/steering_behaviors/orthogonal.rb

@@ -11,23 +11,23 @@ class SteeringBehaviors::Orthogonal
   # Moves at a 90-degree angle to the target's course.
   #
   # * *Args*    :
-  #   - +hunter_kinematic+ -> my moving thing
-  #   - +quarry_kinematic+ -> kinematic of the target
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving
+  #   - +other_kinematic+ -> kinematic of the thing to match
   # * *Returns* :
-  #   -
+  #   - a steering force
   #
-  def self.steer(hunter_kinematic, quarry_kinematic)
-    option_a = SteeringBehaviors::Vector.new(quarry_kinematic.heading_vec.y, -quarry_kinematic.heading_vec.x)
-    option_b = SteeringBehaviors::Vector.new(-quarry_kinematic.heading_vec.y, quarry_kinematic.heading_vec.x)
+  def self.steer(character_kinematic, other_kinematic)
+    option_a = SteeringBehaviors::Vector.new(other_kinematic.heading_vec.y, -other_kinematic.heading_vec.x)
+    option_b = SteeringBehaviors::Vector.new(-other_kinematic.heading_vec.y, other_kinematic.heading_vec.x)
 
-    da = option_a.delta(hunter_kinematic.heading_vec)
-    db = option_b.delta(hunter_kinematic.heading_vec)
+    da = option_a.delta(character_kinematic.heading_vec)
+    db = option_b.delta(character_kinematic.heading_vec)
 
     best_hdg_vec = (da < db ? option_a : option_b)
 
-    desired_velocity = best_hdg_vec * hunter_kinematic.velocity_vec.length
+    desired_velocity = best_hdg_vec * character_kinematic.velocity_vec.length
 
-    return desired_velocity - hunter_kinematic.velocity_vec
+    return desired_velocity - character_kinematic.velocity_vec
   end
 
 end

data/lib/steering_behaviors/pursue.rb

@@ -14,31 +14,29 @@ class SteeringBehaviors::Pursue
   # See http://www.red3d.com/cwr/steer/
   #
   # * *Args*    :
-  #   - +hunter_kinematic+ -> pursuing kinematic
-  #   - +quarry_kinematic+ -> kinematic of the target
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and pursuing
+  #   - +other_kinematic+ -> kinematic of the thing to pursue
   # * *Returns* :
-  #   -
-  # * *Raises* :
-  #   - ++ ->
+  #   - a steering force
   #
-  def self.steer(hunter_kinematic, quarry_kinematic)
-    offset          = quarry_kinematic.position_vec - hunter_kinematic.position_vec
+  def self.steer(character_kinematic, other_kinematic)
+    offset          = other_kinematic.position_vec - character_kinematic.position_vec
     direct_distance = offset.length
     unit_offset     = offset / direct_distance
 
-    parallelness = hunter_kinematic.heading_vec.dot(quarry_kinematic.heading_vec)
-    forwardness  = unit_offset.dot(hunter_kinematic.heading_vec)
+    parallelness = character_kinematic.heading_vec.dot(other_kinematic.heading_vec)
+    forwardness  = unit_offset.dot(character_kinematic.heading_vec)
 
     gen, tf = compute_time_factor(forwardness, parallelness)
 
-    direct_travel_time     = direct_distance / hunter_kinematic.speed
-    direct_travel_time_2   = direct_distance / (hunter_kinematic.speed + quarry_kinematic.speed)
+    direct_travel_time     = direct_distance / character_kinematic.speed
+    direct_travel_time_2   = direct_distance / (character_kinematic.speed + other_kinematic.speed)
     estimated_time_enroute = direct_travel_time_2 * tf
-
     # printf "#{ipos.entity}'s target #{qpos.entity} is '#{gen}'. fness: %0.3f pness: %0.3f f: %0.3f p: %0.3f tf: %0.3f\n", forwardness, parallelness, f, p, tf
-    predicted_pos_vec = quarry_kinematic.position_vec + (quarry_kinematic.velocity_vec * estimated_time_enroute)
+    predicted_pos_vec = other_kinematic.position_vec + (other_kinematic.velocity_vec * estimated_time_enroute)
 
-    return [predicted_pos_vec, SteeringBehaviors::Seek.steer(hunter_kinematic, predicted_pos_vec)]
+    # puts "#{compute_nearest_approach_distance(character_kinematic, other_kinematic)} in #{compute_nearest_approach_time(character_kinematic, other_kinematic)} sec"
+    return [predicted_pos_vec, SteeringBehaviors::Seek.steer(character_kinematic, predicted_pos_vec)]
   end
 
 

data/lib/steering_behaviors/seek.rb

@@ -12,13 +12,13 @@ class SteeringBehaviors::Seek
   # See http://www.red3d.com/cwr/steer/
   #
   # * *Args*    :
-  #   - +kinematic+ -> my seeking thing
-  #   - +goal_position+ -> the position-vector where we want to go
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and seeking
+  #   - +goal_position+ -> the position-vector that we want to seek
   # * *Returns* :
-  #   - the calculated steering force
+  #   - the steering force
   #
-  def self.steer(kinematic, goal_position)
-    desired_velocity = (goal_position - kinematic.position_vec).normalize * kinematic.max_speed
-    desired_velocity - kinematic.velocity_vec
+  def self.steer(character_kinematic, goal_position)
+    desired_velocity = (goal_position - character_kinematic.position_vec).normalize * character_kinematic.max_speed
+    desired_velocity - character_kinematic.velocity_vec
   end
 end

data/lib/steering_behaviors/separation.rb

@@ -0,0 +1,60 @@
+##
+# Copyright 2013, Prylis Incorporated.
+#
+# This file is part of The Ruby Steering Behaviors Library.
+# http://github.com/cpowell/steering-behaviors
+# You can redistribute and/or modify this software only in accordance with
+# the terms found in the "LICENSE" file included with the framework.
+
+class SteeringBehaviors::Separation
+  extend SteeringBehaviors::Common
+
+  # Steer to avoid another kinematic by a certain radius.
+  #
+  # * *Args*    :
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and separating
+  #   - +other_kinematic+ -> kinematic of the thing to separate from
+  #   - +danger_radius+ -> attempt to avoid closest approach of less than this value
+  # * *Returns* :
+  #   - a steering force
+  #
+  def self.steer(character_kinematic, other_kinematic, danger_radius)
+    cpa_time, char_pos_at_cpa, other_pos_at_cpa = compute_nearest_approach(character_kinematic, other_kinematic)
+
+    # Do nothing if the CPA is in the past, or if we won't breach the danger radius
+    return SteeringBehaviors::VEC_ZERO if cpa_time < 0
+    cpa_dist = (char_pos_at_cpa - other_pos_at_cpa).length
+    return SteeringBehaviors::VEC_ZERO if cpa_dist > danger_radius
+
+    parallelness = character_kinematic.heading_vec.dot(other_kinematic.heading_vec)
+
+    side_vec = character_kinematic.heading_vec.perpendicular
+    val = 0
+
+    if parallelness < -0.707
+      # anti-parallel, head-on paths
+      # steer away from the threat's future posn
+      offset_vec = other_pos_at_cpa - character_kinematic.position_vec
+      side_dot = offset_vec.dot(side_vec)
+      val = (side_dot > 0 ? -1.0 : 1.0)
+      # puts "Head-on, steering away from future pos"
+    elsif parallelness > 0.707
+      # parallel paths; steer away from threat
+      offset_vec = other_kinematic.position_vec - character_kinematic.position_vec
+      side_dot = offset_vec.dot(side_vec)
+      val = (side_dot > 0 ? -1.0 : 1.0)
+      # puts "Parallel, steering away from other guy"
+    else
+      # perpendicular paths; steer behind threat
+      if other_kinematic.speed <= character_kinematic.speed
+        side_dot = side_vec.dot(other_kinematic.velocity_vec)
+        val = (side_dot > 0 ? -1.0 : 1.0)
+        # puts "Perpendicular, steering behind other guy"
+      end
+    end
+
+    return side_vec * val
+
+  end
+
+end

data/lib/steering_behaviors/steering.rb

@@ -13,41 +13,43 @@ class SteeringBehaviors::Steering
   # directly alters the provided Mobile component.
   #
   # * *Args*    :
-  #   - +kinematic+ -> the kinematic thing
+  #   - +character_kinematic+ -> "our" character that is moving
   #   - +steering_force+ -> force vector supplied by a steering behavior
   #   - +delta+ -> time delta (in seconds) used for scaling the result
   #
-  def self.feel_the_force(kinematic, steering_force, delta)
-    acceleration = steering_force / kinematic.mass
+  def self.feel_the_force(character_kinematic, steering_force, delta, accelerative=true)
+    return if steering_force.nil?
 
-    # Compute the new, proposed velocity vector.
-    desired_velocity = kinematic.velocity_vec + (acceleration * delta)
+    acceleration = steering_force / character_kinematic.mass
 
-    desired_velocity.truncate!(kinematic.max_speed)
+    # Compute the new, proposed velocity vector.
+    desired_velocity = character_kinematic.velocity_vec + (acceleration * delta)
+    desired_velocity.truncate!(character_kinematic.speed) if !accelerative
+    desired_velocity.truncate!(character_kinematic.max_speed)
 
     # If this timeslice's proposed velocity-vector exceeds the turn rate,
     # come up with a revised velociy-vec that doesn't exceed the rate -- and use that.
-    angle             = Math.acos kinematic.heading_vec.dot(desired_velocity.normalize)
-    max_course_change = kinematic.max_turn * delta
+    angle             = Math.acos character_kinematic.heading_vec.clamped_dot(desired_velocity.normalize)
+    max_course_change = character_kinematic.max_turn * delta
 
     if angle.abs > max_course_change
-      direction    = SteeringBehaviors::Vector.sign(kinematic.velocity_vec, desired_velocity) # -1==CCW, 1==CW
-      limited_crse = kinematic.heading_vec.radians - max_course_change * direction
+      direction    = SteeringBehaviors::Vector.sign(character_kinematic.velocity_vec, desired_velocity) # -1==CCW, 1==CW
+      limited_crse = character_kinematic.heading_vec.radians - max_course_change * direction
 
       # printf "Current %0.4f. Angle %0.4f %s exceeds max change %0.4f. Desired course [%0.4f], limited course [%0.4f]\n",
-      #   kinematic.heading_vec.radians,
+      #   character_kinematic.heading_vec.radians,
       #   angle,
       #   (direction==1 ? 'CW' : 'CCW'),
       #   max_course_change,
       #   desired_velocity.radians,
       #   limited_crse
 
-      kinematic.velocity_vec = SteeringBehaviors::Vector.new(
-        Math.sin(limited_crse) * kinematic.speed,
-        Math.cos(limited_crse) * kinematic.speed
+      character_kinematic.velocity_vec = SteeringBehaviors::Vector.new(
+        Math.sin(limited_crse) * character_kinematic.speed,
+        Math.cos(limited_crse) * character_kinematic.speed
       )
     else
-      kinematic.velocity_vec = desired_velocity
+      character_kinematic.velocity_vec = desired_velocity
     end
   end
 

data/lib/steering_behaviors/vector.rb

@@ -90,9 +90,19 @@ class SteeringBehaviors::Vector
     self
   end
 
+  # A pure and correct dot product routine.
   # A · B = A.x * B.x + A.y * B.y
   def dot(b)
     val = @x*b.x + @y*b.y
+  end
+
+  # Unlike the 'pure' dot product above, this one ensures a -1.0..1.0 return value.
+  # If you're doing dot products of normalized vectors and expecting a pure -1.0..1.0
+  # return value for Math.acos() purposes, use this routine to avoid "Numerical argument
+  # is out of domain" errors that creep in due to rounding errors.
+  def clamped_dot(b)
+    val = self.dot(b)
+
     val = 1.0 if val > 1.0
     val = -1.0 if val < -1.0
 
@@ -104,13 +114,9 @@ class SteeringBehaviors::Vector
   end
 
   def compass_bearing(y_down_more_positive=false)
-    if y_down_more_positive
-      up = SteeringBehaviors::Vector.new(0, -1)
-    else
-      up = SteeringBehaviors::Vector.new(0, 1)
-    end
+    up = ( y_down_more_positive ? SteeringBehaviors::VEC_UP_NEGY : SteeringBehaviors::VEC_UP_POSY)
 
-    theta = Math.acos(self.normalize.dot(up))
+    theta = Math.acos(self.normalize.clamped_dot(up))
 
     theta *= -1 if @x < 0
     degs = SteeringBehaviors::Vector.rad2deg(theta)
@@ -197,5 +203,4 @@ class SteeringBehaviors::Vector
   def to_s
     format("Vector {[%.7f, %.7f] len %0.7f}", @x, @y, length)
   end
-
 end

data/lib/steering_behaviors/wander.rb

@@ -12,15 +12,15 @@ class SteeringBehaviors::Wander
   # See http://www.red3d.com/cwr/steer/
   #
   # * *Args*    :
-  #   - +kinematic+ -> the wandering thing
+  #   - +character_kinematic+ -> kinematic of "our" character that is moving and wandering
   #   - +erraticism+ -> how erratic the wandering effect will be
   # * *Returns* :
-  #   - the calculated steering force
+  #   - the steering force
   #
-  def self.steer(kinematic, erraticism)
-    kinematic.steering_target += SteeringBehaviors::Vector.new(rand(-1.0..1.0)*erraticism, rand(-1.0..1.0)*erraticism)
-    kinematic.steering_target.normalize!
+  def self.steer(character_kinematic, erraticism)
+    character_kinematic.steering_target += SteeringBehaviors::Vector.new(rand(-1.0..1.0)*erraticism, rand(-1.0..1.0)*erraticism)
+    character_kinematic.steering_target.normalize!
 
-    kinematic.steering_target.rotate(kinematic.heading_vec.radians)
+    character_kinematic.steering_target.rotate(character_kinematic.heading_vec.radians)
   end
 end

data/test/vector_test.rb

@@ -196,6 +196,14 @@ class VectorTest < MiniTest::Unit::TestCase
     @v2 = SteeringBehaviors::Vector.new(1.0, 0.5)
     assert_equal(1.0, @v1.dot(@v2))
 
+    @v1 = SteeringBehaviors::Vector.new(1.0, 1.0)
+    @v2 = SteeringBehaviors::Vector.new(1.0, 1.0)
+    assert_equal(2.0, @v1.dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(0.708, 0.707)
+    @v2 = SteeringBehaviors::Vector.new(0.707, 0.707)
+    assert_equal(1.000405, @v1.dot(@v2))
+
     @v1 = SteeringBehaviors::Vector.new(1.0, 0)
     @v2 = SteeringBehaviors::Vector.new(0, 1.0)
     assert_equal(0, @v1.dot(@v2))
@@ -224,8 +232,52 @@ class VectorTest < MiniTest::Unit::TestCase
     @v2 = SteeringBehaviors::Vector.new(0.866, 0.5)
     @v2.normalize!
     assert_equal(0.86603810567665, @v1.dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(500, 500)
+    @v2 = SteeringBehaviors::Vector.new(-14, 75)
+    assert_equal(30500, @v1.dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(-0.5, -0.5)
+    @v2 = SteeringBehaviors::Vector.new(2.2, 2.2)
+    assert_equal(-2.2, @v1.dot(@v2))
+  end
+
+  def test_clamped_dot_product
+    @v1 = SteeringBehaviors::Vector.new(0.5, 1)
+    @v2 = SteeringBehaviors::Vector.new(1.0, 0.5)
+    assert_equal(1.0, @v1.clamped_dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(0.708, 0.707)
+    @v2 = SteeringBehaviors::Vector.new(0.707, 0.707)
+    assert_equal(1.0, @v1.clamped_dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(0, 1.0)
+    @v2 = SteeringBehaviors::Vector.new(-1.0, 0)
+    assert_equal(0, @v1.clamped_dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(0, 1.0)
+    @v2 = SteeringBehaviors::Vector.new(0.707, 0.707)
+    @v2.normalize!
+    assert_equal(0.7071067811865476, @v1.clamped_dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(1.0, 0)
+    @v2 = SteeringBehaviors::Vector.new(-0.707, 0.707)
+    @v2.normalize!
+    assert_equal(-0.7071067811865476, @v1.clamped_dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(1.0, 0)
+    @v2 = SteeringBehaviors::Vector.new(-0.707, -0.707)
+    @v2.normalize!
+    assert_equal(-0.7071067811865476, @v1.clamped_dot(@v2))
+
+    @v1 = SteeringBehaviors::Vector.new(0.5, 0.866)
+    @v1.normalize!
+    @v2 = SteeringBehaviors::Vector.new(0.866, 0.5)
+    @v2.normalize!
+    assert_equal(0.86603810567665, @v1.clamped_dot(@v2))
   end
 
+
   def test_perpendicular
     @v2 = @v.perpendicular
     assert_equal(1.0, @v2.x)

metadata

@@ -2,14 +2,14 @@
 name: steering_behaviors
 version: !ruby/object:Gem::Version
   prerelease:
-  version: 1.0.4
+  version: 1.0.5
 platform: ruby
 authors:
 - Chris Powell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2013-08-05 00:00:00.000000000 Z
+date: 2013-08-11 00:00:00.000000000 Z
 dependencies: []
 description: |
   If you're building a game, you need your game agents and characters to move on their own. A standard way of doing this is with 'steering behaviors'. The seminal paper by Craig Reynolds established a core set of steering behaviors that could be utilized for a variety of common movement tasks and natural behaviors. This Ruby library can accomplish many/most of those tasks for your Ruby / JRuby game. The basic behaviors can be layered for more complicated and advanced behaviors, such as flocking and crowd movement.
@@ -29,6 +29,7 @@ files:
 - lib/steering_behaviors/orthogonal.rb
 - lib/steering_behaviors/pursue.rb
 - lib/steering_behaviors/seek.rb
+- lib/steering_behaviors/separation.rb
 - lib/steering_behaviors/steering.rb
 - lib/steering_behaviors/vector.rb
 - lib/steering_behaviors/wander.rb