rubygame 2.2.0-mswin32

data/lib/rubygame/sfont.rb

@@ -0,0 +1,223 @@
+#--
+# Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+# Copyright (C) 2004-2007  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
+
+  # *NOTE*: you must require 'rubygame/sfont' manually to gain access to
+  # Rubygame::SFont. It is not imported with Rubygame by default!
+  # 
+  # SFont is a type of bitmapped font, which is loaded from an image file
+  # with a meaningful top row of pixels, and the font itself below that. The
+  # top row provides information about what parts of of the lower area
+  # contains font data, and which parts are empty.
+  # 
+  # The image file should contain all of the glyphs on one row, with the
+  # colorkey color at the bottom-left pixel and the "skip" color at the 
+  # top-left pixel.
+  # 
+  # The colorkey color is applied to the image file when it is loaded, so
+  # that all pixels of that color appear transparent. Alternatively, if the
+  # alpha value of pixel [0,0] is 0 (that is, if it is fully transparent),
+  # the image file is assumed to have a proper alpha channel, and no colorkey
+  # is applied. The skip color is used in the top row of pixels to indicate
+  # that all the  pixels below it contain empty space, and that the next 
+  # pixel that is not the skip color marks the beginning of the next glyph.
+  # 
+  # The official SFont homepage, with information on SFont and sample font 
+  # files, can be found at http://www.linux-games.com/sfont/. More 
+  # information on SFont, and a useful utility for automatically generating 
+  # the top row for a font, can be found at: http://www.nostatic.org/sfont/
+
+  class SFont
+    @@default_glyphs = [\
+      "!",'"',"#","$","%","&","'","(",")","*","+",",","-",".","/","0",
+      "1","2","3","4","5","6","7","8","9",":",";","<","=",">","?","@",
+      "A","B","C","D","E","F","G","H","I","J","K","L","M","N","O","P",
+      "Q","R","S","T","U","V","W","X","Y","Z","[","\\","]","^","_","`",
+      "a","b","c","d","e","f","g","h","i","j","k","l","m","n","o","p",
+      "q","r","s","t","u","v","w","x","y","z","{","|","}","~"]
+
+    # Returns an array of strings, each string a single ASCII character
+    # from ! (33) to ~ (126). This is the default set of characters in a
+    # SFont. The full set is as follows:
+    # 
+    #   ! " # $ % & ' ( ) * + , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ? @
+    #   A B C D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _ `
+    #   a b c d e f g h i j k l m n o p q r s t u v w x y z { | } ~
+    def SFont.default_glyphs
+      @@default_glyphs
+    end
+
+    # Create a now SFont instance.
+    # 
+    # This function takes these arguments:
+    # filename:: the name of the image file from which the font should be
+    #            loaded. Or, a Surface with a font image on it. The
+    #            Surface will be copied onto separate Surfaces for each
+    #            glyph, so the original Surface can be recycled.
+    # glyphs::   array of strings, one for each glyph, in the order they
+    #            are found in the image file. If glyphs is not provided,
+    #            or is nil, it is assumed to be the normal SFont order;
+    #            that is, ASCII characters ! (33) to ~ (126). See 
+    #            SFont.default_glyphs for a full list.
+    # spacew::   represents the width of a space character ( ). You can
+    #            either specify the width in pixels, or specify a 
+    #            character whose width, as found in the image, should be
+    #            used. Alternatively, you could add a space character to
+    #            the list of glyphs, and to the image file. If +spacew+
+    #            is not given or is nil, and the space character is not 
+    #            in the list of glyphs, it will have the same width as
+    #            the double-quote character (").
+    def initialize(filename,glyphs=nil,spacew=nil)
+      # load the surface containing all the glyphs
+      surface = nil
+      if filename.is_a? String
+        surface = Surface.load_image(filename)
+      elsif filename.is_a? Surface
+        surface = filename
+      end
+      @height = surface.height
+      colorkey = surface.get_at(0,@height-1)
+
+      # set colorkey if "transparent" color is not actually transparent
+      if colorkey[3] != 0
+        surface.set_colorkey(colorkey[0..2])
+      end
+
+      @glyphs = {}
+      @skip = surface.get_at(0,0)[0..2]
+
+      # split the glyphs into separate surfaces
+      glyphs = (glyphs or @@default_glyphs)
+      start_x = 2
+      glyphs.each{ |glyph| start_x = load_glyph(surface,glyph,start_x) }
+
+      if not glyphs.include?(" ")
+        if spacew == nil
+          spacew = @glyphs['"'].width
+        elsif spacew.kind_of? Numeric
+          spacew = spacew.to_i
+        elsif spacew.kind_of? String
+          if glyphs.include? spacew
+            spacew = @glyphs[spacew].width
+          else
+            spacew = @glyphs['"'].width
+          end
+        else
+          raise(ArgumentError,"spacew must be Numeric, String, \
+or nil (got %s)"%[spacew.class])
+        end
+        @glyphs[" "] = Surface.new([spacew,@height])
+      end
+    end
+
+    # Return the height of the font, in pixels. This is the same as the
+    # height of the image file (all glyphs are the same height). 
+    attr_reader :height
+
+    # This is a private function which is used to parse the font image.
+    # 
+    # Create a Surface for a single glyph, and store it as a value in the
+    # +@glyphs+ hash, indexed by the glyph (string) it represents. 
+    # 
+    # Starting at a pixel in the "skip" region to the left of the glyph.
+    # Scans to the right along the top row until it finds a non-skip pixel
+    # (this is where the glyph starts) and then scans until it finds a skip
+    # pixel (this is where the glyph ends.
+    # 
+    # Returns the x value it stops at, plus 1. This should be fed back in
+    # for the +start_x+ of the next glyph.
+    # 
+    # This _private_ method takes these arguments:
+    # surface:: the Surface containing all glyph image data.
+    # glyph::   a string containing the current glyph
+    # start_x:: the x position to start scanning at. 
+    def load_glyph(surface,glyph,start_x) # :doc:
+      # find where this glyph starts
+      begin
+        while(surface.get_at(start_x,0)[0..2] == @skip)
+          start_x += 1
+        end
+      rescue IndexError
+        return -1
+      end
+
+      end_x = start_x
+
+      # find how wide this glyph is
+      begin
+        while(surface.get_at(end_x,0)[0..2] != @skip)
+          end_x += 1
+        end
+      rescue IndexError
+        return -1
+      end
+
+      # make a new surface for the glyph and blit the image onto it
+      rect = Rect.new(start_x, 0, end_x-start_x, surface.h)
+      @glyphs[glyph] = Surface.new(rect.size)
+      surface.blit(@glyphs[glyph],[0,0],rect)
+      
+      return end_x+1
+    end
+    private :load_glyph
+
+    # This is a private function which is used to render a string.
+    # 
+    # Blit a single glyph to a Surface at the given position.
+    # 
+    # This _private_ method takes these arguments:
+    # glyph::   a string containing the glyph to blit.
+    # surface:: the target surface to blit onto.
+    # pos::     an Array of the x and y values to blit the glyph to.
+    def blit_glyph(glyph,surface,pos) # :doc:
+      @glyphs[glyph].blit(surface,pos)
+    end
+    private :blit_glyph
+
+    # Pretends to render the given string, and returns the width in pixels
+    # of the surface that would be created if it were rendered using 
+    # SFont#render. If you want the height too, you can get it with 
+    # SFont#height (the height is contant).
+    # 
+    # This method takes this argument:
+    # string:: the string to pretend to render.
+    def string_width(string)
+      w = 0
+      string.each_byte { |glyph| w += @glyphs["%c"%[glyph]].width }
+      return w
+    end
+
+    # Renders the given string to a Surface, and returns that surface.
+    # 
+    # This method takes this argument:
+    # string:: the text string to render.
+    def render(string)
+      size = [self.string_width(string),self.height]
+      render = Surface.new(size)
+      x = 0
+      string.each_byte { |glyph| 
+        blit_glyph("%c"%[glyph],render,[x,0])
+        x += @glyphs["%c"%[glyph]].width
+      }
+      return render
+    end
+  end # class SFont
+
+end # module Rubygame

data/lib/rubygame/sprite.rb

@@ -0,0 +1,511 @@
+#--
+#	Rubygame -- Ruby code and bindings to SDL to facilitate game creation
+#	Copyright (C) 2004-2007  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
+
+	# The Sprites module provides classes and mix-in modules for managing
+	# sprites. A Sprite is, fundamentally, a Surface with an associated
+	# Rect which defines the position of that Surface on the Screen.
+	# Additionally, sprites can have some behavior associated with them
+	# via the Sprite#update method, including movement and collision detection;
+	# because of this, sprites can be the foundation of most on-screen objects,
+	# such as characters, items, missiles, and even user-interface elements.
+	# 
+	# There are several classes/modules under the Sprites module:
+	# Sprite::      mix-in module to turn an individual object or class into
+	#               a Sprite.
+	# Group::       class for containing and manipulating many Sprite objects.
+	# UpdateGroup:: mix-in module for Group to allow undrawing/redrawing of
+	#               member Sprite objects.
+	# LimitGroup::  mix-in module for Group to limit the number of Sprite objects
+	#               the Group can hold at once.
+	# 
+	# More mix-in modules to extend the functionality of Group or Sprite are
+	# planned for the future. Do not hesitate to change either (or both) Group
+	# or Sprite within your application to fit your needs! That's what they are
+	# here for!
+	# 
+	module Sprites
+
+		# The Sprite mix-in module (not to be confused with its parent module,
+		# Sprites) can be used to extend a class or object to behave as a
+		# sprite. Specifically, a sprite can:
+		# - #draw (blit) itself onto a Surface in its proper position
+		# - detect bounding-box collision with Groups (#collide_group) and/or other
+		#   sprites (#collide_sprite).
+		# - #update its own state based on arbitrary rules.
+		# 
+		# A Sprite is, fundamentally, a Surface with an associated
+		# Rect which defines the position of that Surface on the Screen.
+		# Additionally, sprites can have some behavior associated with them
+		# via the #update method, including movement and collision detection;
+		# because of this, sprites can be the foundation of most on-screen objects,
+		# such as characters, items, missiles, and even user-interface elements.
+		# 
+		# In order to work properly as a Sprite, the extended object or class must
+		# have two methods defined (by default, these are defined as accessors to
+		# attributes of the same names):
+		# image:: return a Surface with the sprite's image.
+		# rect::  returns a Rect with the position and dimensions of the sprite.
+		# 
+		# Normally, the value returned by rect is used to draw the sprite
+		# onto a Surface as well as to detect collision between sprites. However,
+		# if @col_rect will be used for collision detection instead, if it is
+		# defined. See also #col_rect.
+		#
+		# Additionally, if you are extending an already-existing instance (rather
+		# than a class), that instance must have an attribute @groups, which is
+		# an Array containing all Groups to which the sprite belongs.
+		# 
+		# 
+		module Sprite
+			attr_reader :groups
+			attr_accessor :image, :rect, :depth
+	
+			# Initialize the Sprite, defining @groups and @depth.
+			def initialize
+				@groups = []
+				@depth = 0
+			end
+
+			# Add the Sprite to each given Group.
+			def add(*groups)
+				groups.each { |group|
+					unless @groups.include? group
+						@groups.push(group)
+						group.push(self)
+					end
+				}
+			end
+
+			# call-seq: alive?  ->  true or false
+			# 
+			# True if the Sprite belongs to at least one Group.
+			def alive?
+				return @groups.length > 0
+			end
+
+			# Set an alternative Rect to use for collision detection. If undefined or
+			# set to nil, the Sprite's #rect is used instead.
+			attr_writer :col_rect
+
+			# call-seq: col_rect  ->  Rect
+			# 
+			# Returns @col_rect if it is defined, otherwise calls #rect.
+			# This method is used by #collide, #collide_group, and #collide_sprite
+			# to get the bounding box for collision detection.
+			def col_rect
+				if defined? @col_rect 
+					return (@col_rect or rect)
+				else
+					return rect
+				end
+			end
+
+			# call-seq: collide(other)  ->  Array
+			# 
+			# Check collision between the caller and a Group or another Sprite. See
+			# also #collide_group and #collide_sprite. This method uses the value
+			# of #col_rect as the bounding box when detecting collision.
+			# 
+			# If +other+ is a Group, returns an Array of every Sprite in that
+			# Group that collides with the caller. If +other+ is a Sprite, returns
+			# an Array containing +other+ if it collides with the caller. Otherwise,
+			# returns an empty Array.
+			def collide(other)
+				if other.class.is_a? Group
+					return collide_group(other)
+				elsif collide_sprite?(other)
+					return [other]
+				else
+					return []
+				end
+			end
+
+			# call-seq: collide_group(group)  ->  Array
+			# 
+			# Check collision between the caller and all members of a Group. This
+			# method uses the value of #col_rect as the bounding box when detecting
+			# collision.
+			# 
+			# Returns an Array of every Sprite in +group+ that collides with the 
+			# caller. If none collide, returns an empty Array.
+			def collide_group(group)
+				sprites = []
+				group.each { |sprite|
+					if self.collide_sprite?(sprite) and (not sprites.include?(sprite))
+						sprites.push(sprite)
+					end
+				}
+				return sprites
+			end
+
+			# call-seq: collide_sprite?(sprite)  ->  true or false or nil
+			# 
+			# Check collision between the caller and another Sprite. This method uses
+			# the value of #col_rect as the bounding box when detecting collision.
+			# Returns true if +sprite+ collides with the caller, false if they do 
+			# not, or nil if +sprite+ does not respond to either :col_rect or :rect
+			# (meaning it was not possible to detect collision).
+			def collide_sprite?(sprite)
+				if sprite.respond_to?(:col_rect)
+					return self.col_rect.collide_rect?(sprite.col_rect)
+				elsif sprite.respond_to?(:rect)
+					return self.col_rect.collide_rect?(sprite.rect)
+				else
+					return nil
+				end
+			end
+
+			# call-seq: draw(surface)  ->  Rect
+			# 
+			# Blit the Surface returned by #image onto +surface+ at the position
+			# given by the Rect returned by #rect. Returns a Rect representing
+			# the area of +surface+ which was affected by the draw.
+			def draw(destination)
+				self.image.blit(destination, self.rect)
+			end
+
+			# Remove the caller from every Group that it belongs to.
+			def kill
+				@groups.each { |group| group.delete(self) }
+				@groups = []
+			end
+
+			# Remove the caller from each given Group.
+			def remove(*groups)
+				groups.each { |group|
+					if @groups.include? group
+						@groups.delete(group)
+						group.delete(self)
+					end
+				}
+			end
+
+
+			# call-seq: undraw(surface, background)  ->  Rect
+			# 
+			# 'Erase' the sprite from +surface+ by drawing over it with part of
+			# +background+. For best results, +background+ should be the same size
+			# as +surface+.
+			# 
+			# Returns a Rect representing the area of +surface+ which was affected.
+			# 
+			def undraw(dest, background)
+				background.blit(dest, @rect, @rect)
+			end			
+			
+			# This method is meant to be overwritten by Sprite-based classes to
+			# define meaningful behavior. It can take any number of arguments you
+			# want, be called however often you want, and do whatever you want.
+			# It may return something, but Group#update will not (by default) use,
+			# or even collect, return values from this method.
+			# 
+			# An example definition might take the amount of time that has passed
+			# since the last update; the Sprite could then update its position
+			# accordingly. Game logic, collision detection, and animation would also
+			# fit in here, if appropriate to your class.
+			def update( *args )
+				super
+			end
+
+		end # module Sprite
+
+		# The Group class is a special container, based on Array, with supplemental
+		# methods for handling multiple Sprite objects. Group can draw, update,
+		# and check collision for all its member sprites with one call.
+		# 
+		# All members of a Group must be unique (duplicates will be refused), and
+		# should be a Sprite (or functionally equivalent).
+		class Group < Array
+
+			# Add +sprite+ to the Group. +sprite+ is notified so that it can
+			# add this Group to its list of parent Groups. See also #push.
+			def <<(sprite)
+				unless self.include? sprite
+					super(sprite)
+					sprite.add(self)
+				end
+				return self
+			end
+
+			# Call the method represented by +symbol+ for every member sprite,
+			# giving +args+ as the arguments to the method. This method uses
+			# Object#send, which does not hesitate to call private methods, so
+			# use this wisely! See also #draw and #update.
+			def call(symbol,*args)
+				self.each { |sprite|
+					sprite.send(symbol,*args)
+				}
+			end
+
+			# Remove every member sprite from the Group. Each sprite is notified
+			# so that it can remove this Group from its list of parent Groups.
+			# See also #delete.
+			def clear
+				self.dup.each { |sprite| sprite.remove(self) }
+			end
+
+			# call-seq: collide_sprite(sprite)  ->  Array
+			# 
+			# Check collision between each member of the Group and +sprite+. Returns
+			# an Array of all member sprites that collided with +sprite+. If none
+			# collided, returns an empty Array.
+			def collide_sprite(sprite)
+				sprite.collide_group(self)
+			end
+
+			# call-seq:
+			#    collide_group(group, &block)  ->  Hash
+			#    collide_group(group, killa=false, killb=false) -> Hash # deprecated
+			# 
+			# Check collision between each member of the calling Group and each 
+			# member of +group+. Returns a Hash table with each member of the calling
+			# Group as a key, and as a value an Array of all members of +group+ that
+			# it collided with.
+			# 
+			# If a block is given, that block is executed for every pair of colliding
+			# sprites. For example, if a1 collides with b1 and b2, the block will
+			# be called twice: once with [ a1, b1 ] and once with [ a1, b2 ].
+			# 
+			# Example: 
+			# 
+			#     # 'kills' both sprites when they collide
+			# 
+			#     groupA,collide_group(groupB) do |a, b|
+			#       a.kill
+			#       b.kill
+			#     end
+			# 
+			# *NOTE*: +killa+ and +killb+ are deprecated and will be removed in the future.
+			# It is highly recommended that you use the block argument instead.
+			# 
+			# *IMPORTANT*: +killa+ and +killb+ will be ignored if a block is given!
+			# 
+			# If +killa+ is true and a sprite in group A collides with a sprite in group B,
+			# the sprite in group A will have its #kill method called; the same goes for
+			# +killb+ and group B.
+			# 
+			def collide_group(group, killa=false, killb=false, &block)
+				sprites = {}
+				self.each { |sprite|
+					col = sprite.collide_group(group)
+					sprites[sprite] = col if col.length > 0
+				}
+				
+				if block_given?
+					sprites.each_pair do |a, bs|
+						bs.each { |b| yield(a, b) }
+					end
+				else
+					# killa and killb only work if no block is given
+					if killa
+						sprites.each_key { |sprite| sprite.kill }
+					end
+					if killb
+						sprites.each_value do |array|
+							array.each { |sprite| sprite.kill }
+						end
+					end
+				end
+				
+				return sprites
+			end
+
+			# Remove each sprite in +sprites+ from the Group. Each sprite is notified
+			# so that it can remove this Group from its list of parent Groups.
+			# Note that this will not work correctly if fed a list of its
+			# own sprites (use Array.dup if you want correct behavior)
+			def delete(*sprites)
+				sprites.each { |sprite|
+					if self.include? sprite
+						super(sprite)
+						sprite.remove(self)
+					end
+				}
+				return self
+			end
+
+			# Draw every sprite on Surface +dest+. Calls Sprite#draw for every member
+			# sprite, passing +dest+ as the argument. See also #call and #update.
+			def draw(dest)
+				self.each { |sprite| sprite.draw(dest) }
+			end
+
+			# Add each sprite in +sprites+ to the Group. Each sprite is notified so
+			# that it can add this Group to its list of parent Groups. See also #<<.
+			def push(*sprites)
+				sprites.each { |sprite|
+					self << sprite
+				}
+				return self
+			end
+
+			# Update every member sprite. Calls Sprite#update for every member
+			# sprite, passing on all arguments. See also #call and #draw.
+			def update(*args)
+				self.each { |sprite|
+					sprite.update(*args)
+				}
+			end
+
+		end #class Group
+
+		# UpdateGroup is a mix-in module that extends Group to allow it to "erase"
+		# (i.e. draw over with a background Surface) and re-draw each sprite in its
+		# new position. This eliminates the "trail" of images that sprites would
+		# otherwise leave as they move around.
+		# 
+		# UpdateGroup adds a new attribute, @dirty_rects, which is an Array storing
+		# all Rects which need to be updated, including the old positions of the
+		# sprites. This attribute is returned when UpdateGroup#draw is called,
+		# so that it can be used to update the parts of the Screen that have
+		# changed.
+		# 
+		# The general order of calls each frame should be:
+		# 1. #undraw; clear the old positions of the sprites.
+		# 2. #update; update the sprites to their new positions.
+		# 3. #draw; draw the sprites in their new positions.
+		# 
+		# This module can extend either a class or an already-existing Group
+		# instance (either empty or with members) without any special preparation.
+		module UpdateGroup
+			attr_accessor :dirty_rects
+
+			# Defines @dirty_rects when an existing object is extended.
+			def UpdateGroup.extend_object(obj)
+				super
+				obj.dirty_rects = []
+			end
+
+			# Initialize the Group, calling +super+ and defining @dirty_rects.
+			def initialize
+				super
+				@dirty_rects = []
+			end
+
+			# call-seq: draw(dest)  ->  Array
+			# 
+			# Draw every sprite on Surface +dest+. See Group#draw.
+			# Returns an Array of Rects representing the portions of +dest+ which
+			# were affected by the last #undraw and this #draw.
+			def draw(dest)
+				self.each { |sprite| 
+					@dirty_rects.push( sprite.draw(dest) ) 
+				}
+				rects = @dirty_rects
+				@dirty_rects = []
+				return rects
+			end
+
+			# Draw over part of +dest+ with image data from the corresponding part
+			# of +background+. For best results, +background+ should be at least as
+			# big as +dest+ (or, rather, the part of +dest+ that will ever be drawn
+			# over).
+			def undraw(dest,background)
+				self.each { |sprite|
+					@dirty_rects.push( sprite.undraw(dest, background) )
+				}
+			end
+		end # module UpdateGroup
+
+
+		# LimitGroup is a mix-in module that extends Group to limit the number
+		# of sprites it can contain. If the limit has been reached, each new sprite
+		# will "push out" the oldest sprite, on a First-In-First-Out basis.
+		# 
+		# The limit can be set either when the LimitGroup is created, or
+		# at any time during execution. However, if you reduce the limit,
+		# excess sprites will not be removed until the next time a sprite is
+		# added. (You can work around this by pushing the last sprite in the
+		# group again; the duplicate will be removed.)
+		# 
+		# Please note that, because Group#push is defined in terms of Group#<<,
+		# both LimitGroup#<< and LimitGroup#push work properly, even though only
+		# LimitGroup#<< is defined.
+		module LimitGroup
+			attr_accessor :limit
+
+			# Defines and sets @limit = 1 when an existing object is extended.
+			def LimitGroup.extend_object(obj)
+				super
+				obj.limit = 1
+			end
+
+			# Initialize the LimitGroup and define @limit (as 1, by default).
+			def initialize(limit=1)
+				@limit = limit
+			end
+
+			# Add +sprite+ to the LimitGroup, removing the oldest member if
+			# necessary to keep under the limit. If +sprite+ is already in
+			# the LimitGroup, it will be moved to the top of the queue.
+			def <<(sprite)
+				if not include? sprite
+					super(sprite)
+					while length > @limit
+						self.slice!(0)
+					end
+				else # move sprite to the back of the queue
+					self.delete(sprite)
+					super(sprite)
+				end
+			end
+		end # module LimitGroup
+
+		# DepthSortGroup is a mix-in module that extends Group to sort its
+		# sprites by their @depth attribute, so that sprites with low depths
+		# will appear on top of sprites with higher depths. A sprite's depth
+		# can be any Numeric, or nil (which will be counted as 0).
+		# 
+		# If two sprites have exactly the same depth, there is no guarantee about
+		# which one will be drawn on top of the other. (But, whichever one is on
+		# top will stay on top, at least until the group is re-sorted.)
+		# 
+		# If a sprite's depth changes after it has been added to the group, you
+		# must use the #sort_sprites method for the change to have any effect.
+		# 
+		module DepthSortGroup
+			# Add a single sprite to the group. For efficiency reasons, this
+			# method doesn't re-sort sprites afterwards. You should use #sort_sprites
+			# after you're done adding sprites. Or, better yet, just use #push.
+			def <<(sprite)
+				super
+			end
+			
+			# Add multiple sprites to the group, then re-sort all sprites.
+			def push(*sprites)
+				sprites.each { |sprite|
+					self << sprite
+				}
+				sort_sprites()
+				return self
+			end
+			
+			# Sort sprites by depth, in descending order, so that sprites with low depths
+			# will be drawn on top of sprites with high depths.
+			# 
+			# If a sprite has a depth of nil, it is sorted as if its depth were 0 (zero).
+			def sort_sprites
+				self.sort! { |a,b| (b.depth or 0) <=> (a.depth or 0) }
+			end
+		end
+		
+	end #module Sprite
+end # module Rubygame