Top

Secret Chronicles of the Scripting API documentation

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.