Functions in the StatefulObject - Grisgram/gml-raptor GitHub Wiki

When doing a project with raptor, you will maybe find yourself doing the same queries or actions over and over again, like in any other development system.

I tried to cover some of these things with a small group of handy, generic functions:

set_state

Instead of having to invoke states.set_state(...), you can set a new state directly through set_state. This is especially useful from "outside" of an object, because player.set_state("died") is better and easier to read than player.states.set_state("died").

/// @function		set_state(name, enter_override = undefined, leave_override = undefined)
/// @description	Convenience shortcut to states.set_state 
set_state = function(name, enter_override = undefined, leave_override = undefined) 

is_in_state

A similar problem is covered by this tool method. Instead of doing a if (states.active_state_name() == "xyz") you can write better readable code by writing if (is_in_state("xyz")).

/// @function		is_in_state(name)
/// @description	Convenience shortcut to states.active_state_name() == name
is_in_state = function(name)

sprite_animate_once

The most powerful of the convenience functions. Very often, you want to change the sprite of an object to do a specific animation (like attacking oder being hit, or even dying) and then the original sprite shall be restored (like back-to-idle-state) or it shall be frozen at the last frame of a sprite (player died, the corpse stays).

This function will do exactly this for you.

/// @function 		sprite_animate_once(
///				_sprite_index, _sprite_index_after = undefined, 
///				_state_after = undefined, _finished_callback)
/// @description	Switch to the given sprite and let the animation run once.
///			When finished, the sprite is set to _sprite_index_after or
///			frozen at the last frame (if no _after is set).
///			Then the optional callback gets invoked.
/// @param {sprite}	_sprite_index		The sprite index to set
/// @param {sprite}	_sprite_index_after	If set, the sprite_index to set when animation finished
///						NOTE: If this is not set, the _sprite_index will freeze
///						with image_speed = 0 at the last frame!
/// @param {string} 	_state_after		The state to set on this object when the animation finished
///						NOTE: The state is set AFTER the finished_callback has been 
///						invoked to avoid code in the "enter" event of the state 
///						interfering with the callback
/// @param {func}	_finished_callback	A function to call, when the animation is finished

Here are some example usages: By skipping the second argument (no "after" sprite), this function will freeze the animation (image_speed = 0) at the last frame of the supplied sprite in the first argument.

sprite_animate_once(sprPlayerDie,, function() {
    log("Player die animation finished.");
});

By supplying an "after" sprite, the function will set this sprite as the sprite_index at frame 0 when the first animation finished. Used clever, you can write entire animation chains with this one by stacking calls of sprite_animate_once in each finished_callback of the animation before.

sprite_animate_once(sprPlayerAttack, sprPlayerIdle, function() {
    log("Player finished attacking animation and now shows idle animation again");
});