Module: Rubygame::Sprites::Sprite

Defined in:
lib/rubygame/sprite.rb

Overview

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.

Instance Attribute Summary collapse

Instance Method Summary collapse

Instance Attribute Details

#col_rect ⇒ Object

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.



113
114
115
116
117
118
119
 
# File 'lib/rubygame/sprite.rb', line 113

def col_rect
	if defined? @col_rect 
		return (@col_rect or rect)
	else
		return rect
	end
end

#depth ⇒ Object

Returns the value of attribute depth.



79
80
81
 
# File 'lib/rubygame/sprite.rb', line 79

def depth
  @depth
end

#groups ⇒ Object (readonly)

Returns the value of attribute groups.



78
79
80
 
# File 'lib/rubygame/sprite.rb', line 78

def groups
  @groups
end

#image ⇒ Object

Returns the value of attribute image.



79
80
81
 
# File 'lib/rubygame/sprite.rb', line 79

def image
  @image
end

#rect ⇒ Object

Returns the value of attribute rect.



79
80
81
 
# File 'lib/rubygame/sprite.rb', line 79

def rect
  @rect
end

Instance Method Details

#add(*groups) ⇒ Object

Add the Sprite to each given Group.



88
89
90
91
92
93
94
95
 
# 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

#alive? ⇒ Boolean

call-seq: alive? -> true or false

True if the Sprite belongs to at least one Group.

Returns:

  • (Boolean) 


100
101
102
 
# File 'lib/rubygame/sprite.rb', line 100

def alive?
	return @groups.length > 0
end

#collide(other) ⇒ Object

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.



131
132
133
134
135
136
137
138
139
 
# 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

#collide_group(group) ⇒ Object

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.



149
150
151
152
153
154
155
156
157
 
# 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

#collide_sprite?(sprite) ⇒ Boolean

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

Returns:

  • (Boolean) 


166
167
168
169
170
171
172
173
174
 
# 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

#draw(destination) ⇒ Object

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.



181
182
183
 
# File 'lib/rubygame/sprite.rb', line 181

def draw(destination)
	self.image.blit(destination, self.rect)
end

#initialize ⇒ Object

Initialize the Sprite, defining @groups and @depth.



82
83
84
85
 
# File 'lib/rubygame/sprite.rb', line 82

def initialize
	@groups = []
	@depth = 0
end

#kill ⇒ Object

Remove the caller from every Group that it belongs to.



186
187
188
189
 
# File 'lib/rubygame/sprite.rb', line 186

def kill
	@groups.each { |group| group.delete(self) }
	@groups = []
end

#remove(*groups) ⇒ Object

Remove the caller from each given Group.



192
193
194
195
196
197
198
199
 
# 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

#undraw(dest, background) ⇒ Object

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.



210
211
212
 
# File 'lib/rubygame/sprite.rb', line 210

def undraw(dest, background)
	background.blit(dest, @rect, @rect)
end

#update(*args) ⇒ Object

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.



224
225
226
 
# File 'lib/rubygame/sprite.rb', line 224

def update( *args )
	super
end