Top

Secret Chronicles of the Scripting API documentation

Module UIDS

The UIDS module (yes, really, it’s a module) is a simple way to refer to existing instances of class Sprite and its subclasses. It basically just offers the module method [] that allows you to retrieve any sprite you wish from the level, identified by its unique identifier (UID):

# Move the sprite with the UID 25 away
UIDS[25].warp(-100, 0)

The UIDS module maintains a cache for the sprite objects so that it doesn’t have to create MRuby objects for all the sprites right at the beginning of a level, but rather when you first access them. This means that while level loading is fast, referencing a bunch of not-yet-seen sprites will probably cause a noticable pause in the gameplay, so be careful when doing this. After a sprite has first been mapped to MRuby land, referencing it will just cause a lookup in the internal cache and therefore is quite fast.

Module Methods

[]

[uid]   → a_sprite
[range] → an_array
[ary]   → an_array

Retrieve an MRuby object for the sprite with the unique identifier uid. The first time you call this method with a given UID, it will cycle through all sprite objects in the level, so it will take relatively long. The sprite object is then cached internally, causing later lookups to be fast.

Parameters

uid

The unique identifier of the sprite you want to retrieve. You can look this up in the TSC editor. May also be a range.

range

Instead of requesting a single sprite, request a list of sprites corresponding to the given range of UIDs.

ary

Instead of requesting a single sprite, request a list of sprites corresponding to the given UIDs.

Return value

Returns an instance of class Sprite or one of its subclasses, as required. If the requested UID can’t be found, returns nil.

If you passed a range or array, you’ll get an array containing the requested Sprite subclass instances instead. The array may contain nil values for sprites that could not be found.

Example

# Request a single sprite
sprite = UIDS[14]

# Request all sprites between UID 10 and 20
ary = UIDS[10..20]

# Request the sprites 14, 16, 20, and 400
ary = UIDS[14, 16, 20, 400]

cache_size

cache_size() → an_integer

The current size of the UID cache. This method is mainly useful for debugging purposes.

cached_uids

cached_uids() → an_array

Returns an unsorted array of all UIDs currently cached. This method is mainly useful for debugging purposes.