zyps 0.1.1

data/README.txt

@@ -0,0 +1,80 @@
+== Synopsis
+
+Zyps - A simulation/game with autonomous creatures.
+
+
+== Description
+
+Zyps are small creatures with minds of their own.  You can create dozens of Zyps, then decide how each will act.  (Will it run away from the others?  Follow them?  Eat them for lunch?)  You can combine rules and actions to create very complex behaviors.
+
+
+== Requirements
+
+* Ruby: http://www.ruby-lang.org
+* Ruby-GNOME2: http://ruby-gnome2.sourceforge.jp
+* Rake (to build from source): http://rake.rubyforge.org
+
+
+== Installation
+
+Make sure you have administrative privileges, then type the following at a command line:
+
+	gem install zyps
+
+
+== Usage
+
+Ensure Ruby-GNOME2 is installed and working.
+
+To see the demo, at a command line, type:
+
+	zyps_demo
+
+
+== Development
+
+Source code and documentation are available via the project site (http://jay.mcgavren.com/zyps).
+
+Once downloaded, change into the project directory.  For a list of targets, run:
+
+	rake -T
+
+To build a gem:
+
+	rake
+
+To see the demo:
+	
+	rake demo
+
+To create a "doc" subdirectory with API documentation:
+
+	rake rdoc
+
+Also see "bin/zyps_demo" and the "test" subfolder in the project directory for sample code.
+
+
+== Thanks
+
+The GUI is provided via Ruby-GNOME2.  Thanks to its authors for their considerable effort in making their library easy to use.
+
+
+== Author
+
+Copyright 2007 Jay McGavren, jay@mcgavren.com
+
+
+== License
+
+Zyps is free software; you can redistribute it and/or modify
+it under the terms of the GNU Lesser General Public License as published by
+the Free Software Foundation; either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.

data/bin/zyps

@@ -0,0 +1,41 @@
+#!/usr/local/bin/ruby
+
+# Copyright 2007 Jay McGavren, jay@mcgavren.com.
+# 
+# This file is part of Zyps.
+# 
+# Zyps is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+begin
+	require 'zyps'
+	require 'zyps/views/trails'
+rescue LoadError
+	require 'rubygems'
+	require 'zyps'
+	require 'zyps/views/trails'
+end
+
+
+begin
+
+	puts "This is just a placeholder for the final application."
+	puts "To see a demonstration of the library, please run 'zyps_demo'."
+
+rescue => exception
+
+	#Print error to STDERR and exit with an abnormal status.
+	abort "Error: " + exception.message + exception.backtrace.join("\n")
+
+end

data/bin/zyps_demo

@@ -0,0 +1,525 @@
+#!/usr/local/bin/ruby
+
+# Copyright 2007 Jay McGavren, jay@mcgavren.com.
+# 
+# This file is part of Zyps.
+# 
+# Zyps is free software; you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU Lesser General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+
+begin
+	require 'zyps'
+	require 'zyps/views/trails'
+rescue LoadError
+	require 'rubygems'
+	require 'zyps'
+	require 'zyps/views/trails'
+end
+
+
+
+
+class Demo
+
+	#The view width.
+	WIDTH = 400
+	#The view height.
+	HEIGHT = 300
+	#Number of frames to draw per demo.
+	FRAME_COUNT = 80
+
+	#Set up a window, a canvas, and an object environment, then run the given block.
+	def demo
+
+		#Create a window, and set GTK up to quit when it is closed.
+		window = Gtk::Window.new
+		window.signal_connect("delete_event") {false}
+		window.signal_connect("destroy") {Gtk.main_quit}
+		
+		#Add view to window.
+		@view = TrailsView.new(WIDTH, HEIGHT)
+		window.add(@view.canvas)
+		window.show_all
+		
+		#Create environment.
+		@environment = Environment.new
+		
+		#Point view at environment.
+		@environment.add_observer(@view)
+		
+		#Run the given block.
+		yield
+		
+		#Activate the GUI.
+		Gtk.main
+		
+		#A divider for explanation text between demos.
+		say("-" * 30)
+		
+	end
+
+
+	#Animate an environment for a given number of frames.
+	def animate(frame_count)
+		begin
+			(1..frame_count).each do |i|
+				@environment.interact
+				#Delay 1/60th second to avoid screen flicker.
+				sleep 1.0 / 60.0
+			end
+		rescue Exception => exception
+			puts exception, exception.backtrace
+		end
+	end
+
+
+	#Populate an environment with the given number of creatures.
+	def populate(environment, count = 50)
+		count.times do |i|
+			multiplier = i / count.to_f
+			environment.objects << Creature.new(
+				i,
+				Location.new(multiplier * @view.width, multiplier * @view.height),
+				Color.new(multiplier, 1 - multiplier, multiplier / 2 + 0.5),
+				Vector.new(100 * multiplier, multiplier * 360)
+			)
+		end
+	end
+
+	
+	#Explain what's going on to the user.
+	def say(phrase)
+		puts phrase
+	end
+
+
+	#Demonstrates drawing an environment and changing its size.
+	def test_render
+				
+		thread = Thread.new do
+		
+			say("The things that populate an environment are called GameObjects.  Each object has:")
+			object = GameObject.new
+			say("...a name")
+			object.name = "Clancy"
+			say("...a Location with x and y coordiates")
+			object.location = Location.new(@view.width/2, @view.height/2)
+			say("...a Color with red, green and blue components ranging from 0 to 1")
+			object.color = Color.new(1, 0, 0)
+			say("...and a Vector giving its speed and an angle from 0 to 360.")
+			object.vector = Vector.new(10, 45)
+			
+			say("Once your object is ready, add it to the environment.")
+			@environment.objects << object
+		
+			say("Call a view's render(objects) method to draw the objects.")
+			say("Call an environment's interact() method to have the objects in it move around.")
+			say("Our demo's animate() method does both these things for us.")
+			animate(FRAME_COUNT)
+			
+			say("Let's add a couple more objects with different colors and vectors.")
+			@environment.objects << GameObject.new(nil, Location.new(@view.width/2, @view.height/2), Color.new(0, 1, 0), Vector.new(20, 135))
+			@environment.objects << GameObject.new(nil, Location.new(@view.width/2, @view.height/2), Color.new(0, 0, 1), Vector.new(30, 225))
+			animate(FRAME_COUNT)
+			
+			say("The viewing area can be resized at any time via its width and height attributes.")
+			@view.width += 100
+			@view.height += 100
+			animate(FRAME_COUNT)
+			
+			say("TrailsView lets you set the thickness and length of the trails as well.")
+			@view.trail_width = 10
+			@view.trail_length = 10
+			animate(FRAME_COUNT)
+			
+		end
+				
+	end
+
+
+	#Demonstrates environmental factors by adding gravity to the environment.
+	def test_environmental_factors
+
+		populate(@environment)
+		
+		thread = Thread.new do
+		
+			say("Without gravity, objects just travel on forever.")
+			animate(FRAME_COUNT)
+			
+			say("Let's add a new EnvironmentalFactor to simulate gravity.")
+			gravity = EnvironmentalFactor.new
+			
+			say("We create a Behavior the EnvironmentalFactor will follow.")
+			accelerate = Behavior.new
+			say("The behavior will have a single action: to accelerate objects toward the 'ground' at 9.8 meters/second.")
+			accelerate.actions << lambda {|gravity, target| target.vector.y += 9.8}
+			say("We add the behavior to the EnvironmentalFactor.")
+			gravity.behaviors << accelerate
+			say("Then we add the EnvironmentalFactor to the Environment.")
+			@environment.environmental_factors << gravity
+			
+			say("Everything immediately drops.")
+			animate(FRAME_COUNT)
+			
+		end
+				
+	end
+
+
+	#Demonstrates creature behaviors.
+	def test_behaviors
+
+		populate(@environment)
+		
+		thread = Thread.new do
+
+			say("Let's add a behavior to our creatures.")
+			chase = Behavior.new
+			
+			say("We'll have them head straight toward their target.")
+			chase.actions << lambda do |creature, target|
+				angle_to_target = Utility.find_angle(creature.location, target.location)
+				creature.vector.pitch = angle_to_target
+			end
+			
+			say("So that they don't target every creature on the screen, we'll add a condition to the behavior saying the target must have the label 'food'.")
+			chase.conditions << lambda {|creature, target| target.tags.include?('food')}
+			
+			say("We'll apply this behavior to all creatures currently in the environment.")
+			@environment.objects.each {|creature| creature.behaviors << chase}
+			animate(FRAME_COUNT)
+			
+			say("Then we'll toss a piece of food (a GameObject with the label 'food') into the environment.")
+			@environment.objects << GameObject.new(
+				"target",
+				Location.new(@view.width / 2, @view.height / 2),
+				Color.new(1, 1, 1),
+				Vector.new(50, 315),
+				0, #Age.
+				["food"] #Tags.
+			)
+			
+			say("Let's see what the creatures do.")
+			animate(FRAME_COUNT)
+			
+		end
+		
+	end
+
+
+	#A Creature that changes the colors of other objects.
+	class Morpher < Creature
+		def initialize(*arguments)
+			super
+			morph = Behavior.new
+			#Shift the target's color to match the creature's.
+			morph.actions << lambda do |creature, target|
+				target.color.red += 0.1 if target.color.red < creature.color.red
+				target.color.green += 0.1 if target.color.green < creature.color.green
+				target.color.blue += 0.1 if target.color.blue < creature.color.blue
+			end
+			#Act only on nearby targets.
+			morph.conditions << lambda {|creature, target| Utility.find_distance(creature.location, target.location) < 50}
+			@behaviors << morph
+		end
+	end
+
+	#Demonstrates changing object colors.
+	def test_change_color
+
+		populate(@environment)
+		
+		say("Creatures can influence any attribute of their target, such as its color.")
+		say("This demo includes a Morpher class, which is a type of Creature.")
+		say("Morphers are created with a single behavior, which shifts the color of any nearby target to match the Morpher's color.")
+		
+		say("Let's place a red Morpher...")
+		@environment.objects << Morpher.new(nil, Location.new(0, 100), Color.new(1, 0, 0), Vector.new(100, 0))
+		say("a green one...")
+		@environment.objects << Morpher.new(nil, Location.new(0, 150), Color.new(0, 1, 0), Vector.new(200, 0))
+		say("and a blue one...")
+		@environment.objects << Morpher.new(nil, Location.new(0, 200), Color.new(0, 0, 1), Vector.new(300, 0))
+		
+		say("And see what they do.")
+		thread = Thread.new {animate(FRAME_COUNT)}
+				
+	end
+
+
+	#Demonstrates altering object speed.
+	def test_accelerate
+
+		populate(@environment)
+		
+		thread = Thread.new do
+
+		
+			say("Many actions need to happen smoothly over time, such as accelerating at a given rate.")
+			
+			say("Here are some Creatures, just plodding along.")
+			animate(FRAME_COUNT / 4)
+			say("We're going to have them pick up the pace.")
+			
+			say("A Clock helps track the passage of time (obviously).")
+			say("We'll create a separate Clock object for each creature.")
+			clocks = Hash.new {|h, k| h[k] = Clock.new}
+			
+			say("Our acceleration behavior is going to check to see how long it's been since it last took effect.")
+			say("It will multiply that time by a given rate, say 100 meters/second.")
+			say("Let's say it's been 0.1 seconds since this creature last accelerated.")
+			say("100 times 0.1 is 10.")
+			say("So we should add 10 meters/second to the creature's speed.")
+			accelerate = Behavior.new
+			accelerate.actions << lambda do |creature, target|
+				#Accelerate the appropriate amount for the elapsed time.
+				creature.vector.speed += 100 * clocks[creature].elapsed_time
+			end
+			
+			say("We add acceleration to all the creatures...")
+			@environment.objects.each {|creature| creature.behaviors << accelerate}
+			
+			say("And watch them rocket away.")
+			animate(FRAME_COUNT)
+			
+		end
+		
+	end
+
+
+	#Demonstrates altering object vectors.
+	def test_turn
+
+		populate(@environment, 20)
+		
+		thread = Thread.new do
+		
+			say("Turning smoothly requires tracking the rate of the turn as well.")
+			animate(FRAME_COUNT / 2)
+			
+			say("Again, we keep a separate Clock for each Creature.")
+			clocks = Hash.new {|h, k| h[k] = Clock.new}
+			
+			say("Our turn behavior follows the same principle as accelerating.")
+			say("We see how many seconds have elapsed, then multiply that by the turn rate.")
+			say("We add the result to the Vector angle.")
+			turn = Behavior.new
+			turn.actions << lambda do |creature, target|
+				#Turn the appropriate amount for the elapsed time.
+				creature.vector.pitch += 100 * clocks[creature].elapsed_time
+			end
+			
+			say("We add the behavior to each Creature...")
+			@environment.objects.each {|creature| creature.behaviors << turn}
+			
+			say("And watch things spiral out of control.")
+			animate(FRAME_COUNT)
+			
+		end
+		
+	end
+
+
+	#Demonstrates adding vectors.
+	def test_approach
+
+		populate(@environment, 50)
+		
+		say("When your car skids on ice, you might steer in a different direction, but you're going to keep following your original vector for a while.")
+		say("Adding vectors together lets us simulate this.")
+		
+		say("We'll keep a separate Vector for each Creature to track the direction it's 'steering' in.")
+		headings = Hash.new {|h, k| h[k] = Vector.new(k.vector.speed, k.vector.pitch)}
+		
+		say("We'll only allow them to turn a maximum of 20 degrees in either direction.")
+		max_turn_angle = 20
+		
+		say("We create a Behavior which adds the Vector the creature WANTS to follow to the Vector it's ACTUALLY following.")
+		approach = Behavior.new
+		approach.actions << lambda do |creature, target|
+		
+			#Find the difference between the current heading and the angle to the target.
+			turn_angle = Utility.find_angle(creature.location, target.location) - headings[creature].pitch
+			
+			#If the angle is the long way around from the current heading, change it to the smaller angle.
+			if turn_angle > 180 then
+				turn_angle -= 360.0
+			elsif turn_angle < -180 then
+				turn_angle += 360.0
+			end
+			
+			#If turn angle is greater than allowed turn speed, reduce it.
+			turn_angle = Utility.constrain_value(turn_angle, max_turn_angle)
+			
+			#Turn the appropriate amount.
+			headings[creature].pitch += turn_angle
+			
+			#Apply the heading to the creature's movement vector.
+			creature.vector += headings[creature]
+			
+		end
+		
+		say("We add a condition that it should only target its prey.")
+		approach.conditions << lambda do |creature, target|
+			target.tags.include?('prey')
+		end
+		
+		say("We add the behavior to all creatures...")
+		@environment.objects.each {|creature| creature.behaviors << approach}
+		
+		say("Add a target...")
+		@environment.objects << Creature.new(
+			"target",
+			Location.new(@view.width / 2, @view.height / 2),
+			Color.new(1, 1, 1),
+			Vector.new(3, 0),
+			0, #Age.
+			["prey"] #Tags.
+		)
+		
+		say("And watch them all TRY to catch it.")
+		thread = Thread.new {animate(FRAME_COUNT)}
+		
+	end
+
+
+	#Demonstrates turning away from an object, instead of toward it.
+	def test_flee
+
+		populate(@environment, 20)
+		
+		say("Fleeing from something is just like approaching it, but we head in the OPPOSITE direction.")
+		say("Just get the angle toward the object, then add 180 degrees.")
+		
+		#Keep a separate heading for each object.
+		headings = Hash.new {|h, k| h[k] = Vector.new(k.vector.speed, k.vector.pitch)}
+		
+		#Create a behavior.
+		max_turn_angle = 20
+		flee = Behavior.new
+		flee.actions << lambda do |creature, target|
+		
+			#Find the difference between the current heading and the angle AWAY from the target.
+			turn_angle = Utility.find_angle(creature.location, target.location) - headings[creature].pitch + 180
+			
+			#If the angle is the long way around from the current heading, change it to the smaller angle.
+			if turn_angle > 180 then
+				turn_angle -= 360.0
+			elsif turn_angle < -180 then
+				turn_angle += 360.0
+			end
+			
+			#If turn angle is greater than allowed turn speed, reduce it.
+			turn_angle = Utility.constrain_value(turn_angle, max_turn_angle)
+			
+			#Turn the appropriate amount for the elapsed time.
+			headings[creature].pitch += turn_angle
+			
+			#Apply the heading to the creature's movement vector.
+			creature.vector += headings[creature]
+			
+		end
+		
+		#Flee from only the creature's predator.
+		flee.conditions << lambda do |creature, target|
+			target.tags.include?('predator')
+		end
+		
+		#Add behavior to creatures.
+		@environment.objects.each {|creature| creature.behaviors << flee}
+		
+		#Add a target.
+		@environment.objects << Creature.new(
+			"lion",
+			Location.new(@view.width / 2, @view.height / 2),
+			Color.new(1, 1, 1),
+			Vector.new(3, 0),
+			0, #Age.
+			["predator"] #Tags.
+		)
+		
+		thread = Thread.new {animate(FRAME_COUNT)}
+		
+	end
+
+
+	#A Behavior that destroys the target.
+	class Destroy < Behavior
+		#Environment from which targets will be removed.
+		attr_accessor :environment
+		def initialize(actions = [], conditions = [], environment = Environment.new)
+			super(actions, conditions)
+			@environment = environment
+			#"Kill" target.
+			self.actions << lambda do |creature, target|
+				@environment.objects.delete(target)
+			end
+			#Act only if target is close.
+			self.conditions << lambda do |creature, target|
+				Utility.find_distance(creature.location, target.location) < 25
+			end
+		end
+	end
+
+
+	#Demonstrates keeping a reference to an Environment so a Creature can alter it.
+	def test_destroy
+	
+		populate(@environment)
+		
+		say("Most games are all about destruction, but there hasn't been much so far.")
+		say("Let's create a creature that causes some havoc.")
+		delinquent = Creature.new(nil, Location.new(0, 150), Color.new(0, 1, 0), Vector.new(200, 0))
+		
+		say("This demo code includes a subclass of Behavior, called Destroy.")
+		destroy = Destroy.new
+		
+		say("We'll destroy our targets by removing them from their environment.")
+		say("Creatures and their Behaviors normally know nothing about the Environment they belong to, so we added an environment attribute to Destroy.")
+		say("Destroy finds the target in Environment.objects and removes it.")
+		destroy.environment = @environment
+		
+		say("Add the Destroy instance to the creature's behaviors...")
+		delinquent.behaviors << destroy
+		
+		say("Drop the creature into the actual environment...")
+		@environment.objects << delinquent
+		
+		say("And - chomp!")
+		thread = Thread.new {animate(FRAME_COUNT)}
+		
+	end
+
+
+	#Run all the demos.
+	def main
+		say "After each demo, close the window to proceed."
+		say("-" * 30)
+		demo {test_render}
+		demo {test_environmental_factors}
+		demo {test_behaviors}
+		demo {test_change_color}
+		demo {test_accelerate}
+		demo {test_turn}
+		demo {test_approach}
+		demo {test_flee}
+		demo {test_destroy}
+	end
+
+
+end
+
+
+#Run the demos.
+Demo.new.main