rubygame 2.4.1 → 2.5.0

data/lib/rubygame/event_handler.rb

@@ -1,6 +1,7 @@
 #--
+#
 #	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
-#	Copyright (C) 2004-2008  John Croisant
+#	Copyright (C) 2004-2009  John Croisant
 #
 #	This library is free software; you can redistribute it and/or
 #	modify it under the terms of the GNU Lesser General Public
@@ -15,6 +16,7 @@
 #	You should have received a copy of the GNU Lesser General Public
 #	License along with this library; if not, write to the Free Software
 #	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+#
 #++
 
 require 'rubygame/event_hook'
@@ -248,6 +250,7 @@ module Rubygame::EventHandler::HasEventHandler
 	# By default, triggers are converted according to these rules:
 	# 
 	#   * Symbols starting with "mouse" become a MouseClickTrigger.
+	#   * The symbol :tick becomes a TickTrigger. (Rubygame 2.5+)
 	#   * Keyboard symbols become a KeyPressTrigger.
 	#   * Classes become an InstanceOfTrigger.
 	#   * Objects with a #match? method are duplicated and used
@@ -286,13 +289,27 @@ module Rubygame::EventHandler::HasEventHandler
 	#                            :mouse_left => :shoot,
 	#                            DiedEvent   => died_action )
 	# 
-	def make_magic_hooks( hash )
-		hash.collect do |trigger, action|
+	def make_magic_hooks( hooks_hash )
+		hooks_hash.collect do |trigger, action|
 			append_hook( :trigger => _make_magic_trigger( trigger ),
 									 :action  => _make_magic_action(  action  ))
 		end
 	end
 
+
+  # Exactly like #make_magic_hooks, but the hooks' owner will be the
+  # given object, instead of self. See EventHook for more information
+  # about hook owners.
+  # 
+  def make_magic_hooks_for( owner, hooks_hash )
+    hooks_hash.collect do |trigger, action|
+      append_hook( :owner   => owner,
+                   :trigger => _make_magic_trigger( trigger ),
+                   :action  => _make_magic_action(  action  ) )
+    end
+  end
+
+
 	# Exactly like #append_hook, except that the hook is put at the
 	# top of the stack (it will be handled first).
 	# 
@@ -419,6 +436,8 @@ module Rubygame::EventHandler::HasEventHandler
 			case(trigger.to_s)
 			when /mouse/
 				Rubygame::EventTriggers::MousePressTrigger.new(trigger)
+			when "tick"
+				Rubygame::EventTriggers::TickTrigger.new
 			else
 				Rubygame::EventTriggers::KeyPressTrigger.new(trigger)
 			end

data/lib/rubygame/event_hook.rb

@@ -57,16 +57,16 @@ class EventHook
   # the following keys. See the class documentation for EventHook for
   # more information about what these mean.
   # 
-  # :owner::    the hook's owner. (any object, required)
-  # :trigger::  an event trigger which matches certain events.
-  #             (Object with +#match?(event)+, required)
-  # :action::   an event action to do when an event matches.
-  #             (Object with +#perform(owner,event)+, required)
-  # :consumes:: if true, the hook will "eat" matching so
-  #             later hooks won't see them. Default: false.
-  #             (true or false, optional)
-  # :active::   if false, the hook will ignore all events.
-  #             Default: true. (true or false, optional)
+  # :owner ::    the hook's owner. (any object, required)
+  # :trigger ::  an event trigger which matches certain events.
+  #              (Object with +#match?(event)+, required)
+  # :action ::   an event action to do when an event matches.
+  #              (Object with +#perform(owner,event)+, required)
+  # :consumes :: if true, the hook will "eat" matching so
+  #              later hooks won't see them. Default: false.
+  #              (true or false, optional)
+  # :active ::   if false, the hook will ignore all events.
+  #              Default: true. (true or false, optional)
   # 
   # NOTE: None of the attributes are truly required to create a hook.
   # But, the hook will do nothing unless both @trigger and @action are

data/lib/rubygame/event_triggers.rb

@@ -42,7 +42,7 @@ require 'rubygame'
 # impact on your game's framerate.
 # 
 # Here is an overview of the event trigger classes that
-# come with Rubygame as of version 2.4:
+# come with Rubygame as of version 2.5:
 # 
 # 
 # AndTrigger::          Holds multiple other triggers, and
@@ -75,6 +75,8 @@ require 'rubygame'
 # 
 # MouseReleaseTrigger:: Matches certain MouseReleased events.
 # 
+# TickTrigger::         Matches ClockTicked events.
+# 
 # YesTrigger::          Matches every event, no matter what.
 # 
 module Rubygame::EventTriggers
@@ -668,11 +670,17 @@ end
 
 
 
-# class TickTrigger
-# 	def match?( event )
-# 		event.kind_of?( Rubygame::Events::ClockTicked )
-# 	end
-# end
+# 
+# TickTrigger is an event trigger which will fire
+# when the Clock ticks (ClockTicked).
+# 
+class TickTrigger
+
+	# Returns true if the event is a ClockTicked event.
+	def match?( event )
+		event.kind_of?( Rubygame::Events::ClockTicked )
+	end
+end
 
 
 

data/lib/rubygame/events/clock_events.rb

@@ -0,0 +1,58 @@
+#--
+#  This file is one part of:
+#  Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#
+#  Copyright (C) 2009  John Croisant
+#
+#  This library 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 2.1 of the License, or (at your option) any later version.
+#
+#  This library 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
+#  Lesser General Public License for more details.
+#
+#  You should have received a copy of the GNU Lesser General Public
+#  License along with this library; if not, write to the Free Software
+#  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# ++
+
+
+module Rubygame
+
+  module Events
+
+    # ClockTicked is an event returned by Clock#tick, if the Clock
+    # has been configured with Clock#enable_tick_events.
+    # 
+    # ClockTicked stores the time that has passed since the previous
+    # tick. You can access that information with #seconds or
+    # #milliseconds. This is useful to calculate how far a character
+    # should move during the current frame, for example.
+    # 
+    class ClockTicked
+
+      # Create a new ClockTicked event.
+      # 
+      # milliseconds::  The time since the last tick,
+      #                 in milliseconds. (Numeric, required)
+      # 
+      def initialize( milliseconds )
+        @milliseconds = milliseconds
+      end
+
+      # Return the time since the last tick, in milliseconds.
+      def milliseconds
+        @milliseconds
+      end
+
+      # Return the time since the last tick, in seconds.
+      def seconds
+        @seconds or (@seconds = @milliseconds * 0.001)
+      end
+    end
+
+  end
+end

data/lib/rubygame/ftor.rb

@@ -18,8 +18,21 @@
 #	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 #++
 
+require "rubygame"
+
+#--
+# Ftor is DEPRECATED and will be removed in Rubygame 3.0!
+# Warn the user when this file is loaded.
+#++
+Rubygame.deprecated("Rubygame::Ftor", "3.0")
+
+
 module Rubygame
 
+# *NOTE*: Ftor is DEPRECATED and will be removed in Rubygame 3.0!
+# A mostly-compatible vector class will be provided at or before
+# that time.
+# 
 # *NOTE*: you must require 'rubygame/ftor' manually to gain access to
 # Rubygame::Ftor. It is not imported with Rubygame by default!
 # 

data/lib/rubygame/mediabag.rb

@@ -19,8 +19,18 @@
 
 require "rubygame"
 
+#--
+# MediaBag is DEPRECATED and will be removed in Rubygame 3.0!
+# Warn the user when this file is loaded.
+#++
+Rubygame.deprecated("Rubygame::MediaBag", "3.0")
+
+
 module Rubygame
 
+  # *NOTE*: MediaBag is DEPRECATED and will be removed in Rubygame 3.0!
+  # Use the NamedResource functionality of Music, Sound, and Surface instead.
+  # 
   # *NOTE*: you must require 'rubygame/mediabag' manually to gain access to
   # Rubygame::MediaBag. It is not imported with Rubygame by default!
   # 

data/lib/rubygame/shared.rb

@@ -0,0 +1,36 @@
+# 
+# Common / utility methods.
+# 
+#--
+# 
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 2009  John Croisant
+#
+#	This library 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 2.1 of the License, or (at your option) any later version.
+#
+#	This library 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
+#	Lesser General Public License for more details.
+#
+#	You should have received a copy of the GNU Lesser General Public
+#	License along with this library; if not, write to the Free Software
+#	Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+# 
+#++
+
+
+module Rubygame
+
+  # Warn of a deprecated Rubygame feature.
+  def self.deprecated( feature, version ) # :nodoc:
+    if $VERBOSE
+      warn( "warning: #{feature} is DEPRECATED and will be removed in " + \
+            "Rubygame #{version}! Please see the docs for more information." )
+    end
+  end
+
+end

data/samples/chimp.rb

@@ -229,8 +229,9 @@ def main
 
 	# This also differs from pygame. Rather than pass the desired framerate
 	# when you call clock.tick, you set the framerate for the clock, either
-	# when you create it, or afterwards with the desired_fps accessors.
-	clock = Clock.new { |clock| clock.target_framerate = 30 }
+	# when you create it, or afterwards with the target_framerate accessor.
+	clock = Clock.new
+	clock.target_framerate = 30
 
 	# Autoload the sound effects
 	whiff_sound = Sound['whiff.wav']

data/samples/demo_gl.rb

@@ -106,8 +106,8 @@ GL::NewList(cube_list,GL::COMPILE_AND_EXECUTE)
 			GL::Vertex(cube[1]);
 			GL::Vertex(cube[2]);
 			GL::Vertex(cube[7]);
-  GL::PopMatrix()
-	GL::End()
+    GL::End()
+ GL::PopMatrix()
 GL::EndList()
 
 angle = 0

data/samples/demo_gl_tex.rb

@@ -151,8 +151,10 @@ GL::NewList(cube_list,GL::COMPILE_AND_EXECUTE)
     GL::Vertex(cube[2]);
     GL::TexCoord(cube_st[5][3]);
     GL::Vertex(cube[7]);
+
+    GL::End()
+
   GL::PopMatrix()
-	GL::End()
 GL::EndList()
 
 angle = 0

data/samples/demo_rubygame.rb

@@ -66,16 +66,6 @@ Joystick.activate_all
 ########################
 
 
-# Holds information about the clock, created each frame.
-class ClockTicked
-	attr_reader :time, :framerate
-
-	def initialize( ms, framerate )
-		@time = ms / 1000.0
-		@framerate = framerate
-	end
-end
-
 # Signals sprites to draw themselves on the screen
 class DrawSprites
 	attr_accessor :screen
@@ -138,12 +128,12 @@ class Panda
 		# do nothing in base class, rotate/zoom image in subs
 	end
 
-	def update( event )
+	def update( tick_event )
 		x,y = @rect.center
-		self.update_image( event.time * 1000.0 )
+		self.update_image( tick_event.seconds * 1000.0 )
 		@rect.size = @image.size
 
-		base = @speed * event.time
+		base = @speed * tick_event.seconds
 		@rect.centerx = x + @vx * base
 		@rect.centery = y + @vy * base
 	end
@@ -252,7 +242,7 @@ class << pandas
 	end
 end
 
-pandas.make_magic_hooks( ClockTicked   => :update,
+pandas.make_magic_hooks( :tick         => :update,
                          DrawSprites   => :do_draw,
                          UndrawSprites => :do_undraw )
 
@@ -297,13 +287,6 @@ ttfont.render( "Press escape or q to quit.",
                true, [250,250,250] ).blit( background, [20,180] )
 
 
-# Now blit the background onto the screen and update the screen once.
-# During the loop, we'll use 'dirty rect' updating to refresh only the
-# parts of the screen that have changed.
-background.blit(screen,[0,0])
-screen.update()
-
-
 
 
 ############################
@@ -417,6 +400,12 @@ class Game
 		setup_queue()
 		setup_event_hooks()
 
+		# Now blit the background onto the screen and update the screen
+		# once. During the loop, we'll use 'dirty rect' updating to
+		# refresh only the parts of the screen that have changed.
+		@background.blit(screen,[0,0])
+		@screen.update()
+
 	end
 
 
@@ -457,6 +446,14 @@ class Game
 	def setup_clock
 		@clock = Clock.new()
 		@clock.target_framerate = 50
+
+    # Adjust the assumed granularity to match the system.
+    # This helps minimize CPU usage on systems with clocks
+    # that are more accurate than the default granularity.
+		@clock.calibrate
+
+    # Make Clock#tick return a ClockTicked event.
+    @clock.enable_tick_events
 	end
 
 
@@ -482,7 +479,7 @@ class Game
 			WindowExposed     => :update_screen,
 
 			# Refresh the window title.
-			ClockTicked       => :update_framerate
+			:tick             => :update_framerate
 		}
 
 		make_magic_hooks( hooks )
@@ -507,8 +504,7 @@ class Game
 		@queue << UndrawSprites.new( @screen, @background )
 		@queue.fetch_sdl_events
 		@queue << DrawSprites.new( @screen )
-		@queue << ClockTicked.new( $game.clock.tick,
-		                           $game.clock.framerate )
+		@queue << $game.clock.tick
 		@queue.each do |event|
 			handle( event )
 		end
@@ -524,9 +520,10 @@ class Game
 
 	# Update the window title to display the current framerate.
 	def update_framerate( event )
-		unless @old_framerate == event.framerate
-			@screen.title = "Rubygame test [%d fps]"%event.framerate
-			@old_framerate = event.framerate
+    new_framerate = @clock.framerate.to_i
+		unless @old_framerate == new_framerate
+			@screen.title = "Rubygame test [%d fps]"%new_framerate
+			@old_framerate = new_framerate
 		end
 	end
 

data/samples/framerate.rb

@@ -0,0 +1,120 @@
+#!/usr/bin/env ruby
+
+#--
+# This program is released to the PUBLIC DOMAIN.
+# It 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.
+#++
+# 
+# This is a simple demonstration of "framerate independence".
+# The speed of gameplay is defined independently of the framerate
+# of the game, i.e. as pixels per second instead of pixels per frame.
+# 
+# You can read more about framerate independence and how to use Clock
+# in doc/managing_framerate.rdoc.
+# 
+
+
+require "rubygame"
+
+# How fast the Mover moves. (pixels per second)
+$mover_speed = 30
+
+# How fast to run the app. (frames per second)
+$framerate = 20
+
+# How long to run the app. (seconds)
+$run_time = 1.0
+
+
+
+class Mover
+
+  def initialize()
+
+    # Define the Mover's speed.
+    @speed = $mover_speed
+
+    # Define the initial position of the Mover.
+    @position = 0
+
+  end
+
+
+  # This method will be called once per frame to update the
+  # Mover's position. tick_event will be a ClockTicked instance.
+  # 
+  def update( tick_event )
+
+    # Calculate how far it moved this frame.
+    # @speed is defined in pixels per second, so we use tick.seconds.
+    change = @speed * tick_event.seconds
+
+    # Apply the movement.
+    move_by( change, tick_event.seconds )
+
+  end
+
+
+  # This method updates the Mover's position and outputs a
+  # message to the user, for demonstration purposes.
+  #   
+  def move_by( change, seconds )
+
+    # Temporarily store the old position, for the message.
+    old_pos = @position
+
+    # Update position.
+    @position += change
+
+    # Calculate the actual speed, for the message.
+    actual_speed = change / seconds
+
+    # Calculate the framerate (frames per second) for the message.
+    framerate = 1.0 / seconds
+
+    puts( "Moved from #{old_pos} to #{@position} " +
+          "(diff: #{change}) in #{seconds} sec (#{framerate} FPS). " +
+          "Speed: #{actual_speed}" )
+
+  end
+
+end # class Mover
+
+
+
+def main_loop
+
+  # Create and configure the Clock
+  clock = Rubygame::Clock.new
+  clock.target_framerate = $framerate
+  clock.enable_tick_events
+
+  puts "Calibrating..."
+  clock.calibrate
+
+  # Create the Mover
+  mover = Mover.new
+
+
+  puts "Go!"
+
+  # Find out when the app should stop.
+  stop_time = Time.now + $run_time
+
+  until( Time.now >= stop_time )
+
+    # Tick the clock. Returns a ClockTicked instance
+    # telling us how long this frame was.
+    tick_event = clock.tick
+
+    # Update the Mover.
+    mover.update( tick_event )
+
+  end
+
+end
+
+
+main_loop()