Class Sprite
A Sprite is one of the most generic objects available in the MRuby API. Anything shown on the screen is somehow a sprite, and the methods defined in this class are therefore available to nearly all objects exposed to the MRuby API.
All sprites created by the regular TSC editor can be references by indexing the global UIDS table, see the section “Unique Identifiers” on the main page for more information on this topic.
UIDS[38].x
About coordinates
Instances of Sprite and its subclasses have two kinds of coordinates, the normal ones (usually called just "coordinates") and the starting position’s coordinates (usually called "initial coordinates"). Most sprites don’t really care about the initial coordinates, but some instances of subclasses of Sprite do, e.g. the Flyon remembers its starting position, i.e. where to return after jumping out, in its initial coordinates. Note that the method for specifying the initial coordinates also set the "normal" coordinates at the same time to the same value (so you usually don’t need to set both pairs manually).
Events
- Touch
-
This event is fired when the sprite collides with another sprite. Note that such a collision actually creates two Touch events, one for each sprite. This may be useful if you don’t want to use a long if-elsif-elsif-elsif... construct inside an event handler choosing an action depending on the collided sprite.
The event handler gets passed an instance of this class (or one of its subclasses) representing the other collision "partner".
Constants
- PASSIVE_Z_START
-
Lowest valid Z coordinate for passive sprites.
- MASSIVE_Z_START
-
Lowest valid Z coordinate for massive sprites.
- FRONTPASSIVE_Z_START
-
Lowest valid Z coordinate for front-passive sprites.
- HALFMASSIVE_Z_START
-
Lowest valid Z coordinate for half-massive sprites.
Class Methods
new
new( [path [, uid ] ] ) → a_sprite
Adds a sprite to the level.
Parameters
- path
-
The path to the sprite’s image, relative to the pixmaps/ directory.
- uid
-
The UID for the sprite. If not given, a free one will be used.
Return value
The newly created instance.
Instance Methods
active=
active=( bool ) → bool
TODO: Docs
active?
active?() → true or false
TODO: Docs
collision_rect
collision_rect() → [an_integer, another_integer, yetanother_integer, andafourthinteger]
The sprite’s collision rectangle. See also #rect.
hide
hide()
Makes a sprite invisible. See also #show.
image
image() → a_string or nil
Returns the path to the sprite’s current image. If the sprite was not constructed from a file, returns nil.
image=
image=( path ) → path
Change the sprite’s image to the given one.
Parameters
- path
-
The path to the new image, relative to the pixmaps/ directory.
massive_type
massive_type() → a_symbol
Returns the sprite’s current massive type. See #massive_type= for a list of possible return values; front passive will always be returned as :frontpassive, half massive will always be returned as :half_massive.
massive_type=
massive_type=( type )
Set the massivity of a sprite.
Parameters
- type
-
One of the following symbols. Their meaning is identical to the one in the TSC editor.
:passive
:front_passive or :frontpassive
:massive
:half_massive or :halfmassive
:climbable
Invalid types will cause an error.
player?
player?() → a_boolean
Checks whether this sprite is the player.
Return value
If this sprite is the player, returns true. Otherwise, returns false.
pos
pos() → [an_integer, another_integer]
Returns the sprite’s current X and Y coordinates.
Return value
An array of the current coordinates, both in pixels.
rect
rect() → [an_integer, another_integer, yetanother_integer, andafourthinteger]
The sprite’s full image rectangle. See also #collision_rect.
show
show()
Makes a sprite visible. See also #hide.
start_at
start_at( xpos, ypos )
Sets both the initial X and Y coordinates at once.
Parameters
- xpos
The initial X coordinate in pixels.
- ypos
The initial Y coordinate in pixels.
start_pos
start_pos() → [an_integer, another_integer]
Returns the initial coordinates for this sprite.
Return value
An array of the initial coordinates, both in pixels.
start_x
start_x()
Returns the sprite’s initial X coordinate.
start_x=
start_x=( val )
Like #x=, but also sets the sprite’s initial X coordinate.
start_y
start_y()
Returns the sprite’s initial Y coordinate.
start_y=
start_y=( val )
Like #y=, but also sets the sprite’s initial Y coordinate.
suppress_save
suppress_save() → a_boolean
Queries whether this sprite is saved in savegame files. See #suppress_save=.
Return value
True or false.
suppress_save=
suppress_save=(a_boolean) → a_boolean
Enable this to prevent this sprite from being saved in savegame files; it is disabled by default. This functionality is useful in certain scripting situations, where without it generates sprites would be saved into the savegame that should actually only ever be inserted by the game's script.
Return value
Returns its argument.
uid
uid() → an_integer
Returns the UID for the sprite.
warp
warp( new_x , new_y )
Warp the sprite somewhere. Note you are responsible for ensuring the coordinates are valid, this method behaves exactly as a level entry (i.e. doesn’t check coordinate validness).
You can easily get the coordinates by moving around the cursor in the TSC level editor and hovering over objects placed near the location where you want to warp to.
Parameters
- x
The new X coordinate.
- y
The new Y coordinate.
x
x() → an_integer
The current X coordinate.
x=
x=( val )
Sets a new X coordinate.
y
y() → an_integer
The current Y coordinate.
y=
y=( val )
Sets a new Y coordinate.
z
z() → an_integer
Returns the current Z coordinate. Note you cannot set the Z coordinate.