Module Rubygame::Sprites::Sprite
In: lib/rubygame/sprite.rb

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.

Methods

add   alive?   col_rect   collide   collide_group   collide_sprite?   draw   kill   new   remove   undraw   update  

Attributes

col_rect  [W]  Set an alternative Rect to use for collision detection. If undefined or set to nil, the Sprite’s rect is used instead.
depth  [RW] 
groups  [R] 
image  [RW] 
rect  [RW] 

Public Class methods

Initialize the Sprite, defining @groups and @depth.

[Source]

# File lib/rubygame/sprite.rb, line 82
                        def initialize
                                @groups = []
                                @depth = 0
                        end

Public Instance methods

Add the Sprite to each given Group.

[Source]

# File lib/rubygame/sprite.rb, line 88
                        def add(*groups)
                                groups.each { |group|
                                        unless @groups.include? group
                                                @groups.push(group)
                                                group.push(self)
                                        end
                                }
                        end

True if the Sprite belongs to at least one Group.

[Source]

# File lib/rubygame/sprite.rb, line 100
                        def alive?
                                return @groups.length > 0
                        end

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.

[Source]

# File lib/rubygame/sprite.rb, line 113
                        def col_rect
                                if defined? @col_rect 
                                        return (@col_rect or rect)
                                else
                                        return rect
                                end
                        end

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.

[Source]

# File lib/rubygame/sprite.rb, line 131
                        def collide(other)
                                if other.class.is_a? Group
                                        return collide_group(other)
                                elsif collide_sprite?(other)
                                        return [other]
                                else
                                        return []
                                end
                        end

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.

[Source]

# File lib/rubygame/sprite.rb, line 149
                        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

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).

[Source]

# File lib/rubygame/sprite.rb, line 166
                        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

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.

[Source]

# File lib/rubygame/sprite.rb, line 181
                        def draw(destination)
                                self.image.blit(destination, self.rect)
                        end

Remove the caller from every Group that it belongs to.

[Source]

# File lib/rubygame/sprite.rb, line 186
                        def kill
                                @groups.each { |group| group.delete(self) }
                                @groups = []
                        end

Remove the caller from each given Group.

[Source]

# File lib/rubygame/sprite.rb, line 192
                        def remove(*groups)
                                groups.each { |group|
                                        if @groups.include? group
                                                @groups.delete(group)
                                                group.delete(self)
                                        end
                                }
                        end

‘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.

[Source]

# File lib/rubygame/sprite.rb, line 210
                        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.

[Source]

# File lib/rubygame/sprite.rb, line 224
                        def update( *args )
                                super
                        end

[Validate]