Animation Functions (Class) - coldrockgames/gml-raptor GitHub Wiki
Here you can find a list of all end-user functions of the Animation class. These can be invoked, as soon as you have created a new Animation(...) instance.
Aside from these functions, there are also helper functions outside of the Animation class available: Animation Functions (Global).
Animation constructor
NOTE: For better readable code, instead of specifying -1 to have an Animation repeat forever, you may use the LOOP_INFINITE macro (which resolves to -1).
/// @func Animation(_obj_owner, _delay, _duration, _animcurve, _repeats = 1,
/// _finished_state = undefined, _data = {})
/// @desc Holds an animation. set repeats to -1 to loop forever until you call abort()
/// @param {instance} _obj_owner The object to be animated
/// @param {int} _delay How many frames to wait until animation starts
/// @param {int} _duration Running time of (one loop) of the animation
/// @param {AnimCurve} _animcurve The AnimCurve providing the animated values
/// @param {int} _repeats Number of loops to perform. Default = 1, set to -1 for infinite repeats.
/// @param {string} _finished_state If the owner is stateful (or owns a StateMachine named "states"),
/// you can supply the name of a state here to set when this animation
/// finishes (A finished_trigger will be added for you).
/// @param {struct} _data A user defined data struct that will be delivered to all trigger functions
function Animation(_obj_owner, _delay, _duration, _animcurve, _repeats=1, _finished_state=undefined, _data={})
: DataBuilder() constructor {
add_started_trigger
/// @func add_started_trigger(trigger)
/// @desc Add a trigger to run when animation starts.
/// The callback will receive 1 parameter: data
/// @param {func} trigger The callback to invoke.
static add_started_trigger = function(trigger) {
add_frame_trigger
/// @func add_frame_trigger(trigger)
/// @desc Add a trigger to run on frame X.
/// If you set is_interval to 'true', it will run EVERY x frames.
/// The callback will receive 2 parameters: data,frame
/// @param {int} frame The frame number, when to do the callback
/// @param {func} trigger The callback to invoke.
/// @param {bool=false} is_interval If true, runs every x frames.
static add_frame_trigger = function(frame, trigger, is_interval = false) {
add_loop_trigger
/// @func add_loop_trigger(trigger)
/// @desc Add a trigger to run when the animation finished one loop.
/// A loop ends at the last frame of an animation.
/// The callback will receive 1 parameter: data
/// @param {func} trigger The callback to invoke.
static add_loop_trigger = function(trigger) {
add_finished_trigger
/// @func add_finished_trigger(trigger)
/// @desc Add a trigger to run when animation finishes.
/// The callback will receive 1 parameter: data
/// @param {func} trigger The callback to invoke.
static add_finished_trigger = function(trigger) {
reset_triggers
If you reuse the animation often, it may become handy to clear out all triggers from previous iterations. You can use the reset_triggers() function for that. It will delete all registered triggers.
/// @func reset_triggers()
/// @desc Remove all registered triggers from this animation.
static reset_triggers = function() {
set_name
/// @func set_name(_name)
/// @desc Gives this animation a specific name. Usage of names is totally optional,
/// but this allows you to set a unique marker to an animation, which can be
/// used as criteria in the is_in_animation(...) function.
/// You can access the name of an animation with .name
/// @param {string} _name The name this animation shall use.
static set_name = function(_name) {
set_move_distance
/// @func set_move_distance(xdistance, ydistance)
/// @desc use this function if the animcurve holds a standard 0..1 value
/// for x/y and the curve value shall be a multiplier for the total
/// distance you supply here (a "move by" curve).
/// Both default move functions for x and y respect this setting.
/// @param {real} xdistance Horizontal distance
/// @param {real} ydistance Vertical distance
static set_move_distance = function(xdistance, ydistance) {
set_move_target
/// @func set_move_target(xtarget, ytarget)
/// @desc use this function if the animcurve holds a standard 0..1 value
/// for x/y and the curve value shall be a multiplier from the current
/// to the target coordinates you supply here (a "move to" curve).
/// Both default move functions for x and y respect this setting.
/// @param {real} xtarget Horizontal target position
/// @param {real} ytarget Vertical target position
static set_move_target = function(xtarget, ytarget) {
set_scale_distance
/// @func set_scale_distance(xdistance, ydistance)
/// @desc use this function if the animcurve holds a standard 0..1 value
/// for x/y and the curve value shall be a multiplier for the total
/// distance you supply here (a "scale by" curve).
/// Both default scale functions for x and y respect this setting.
/// @param {real} xdistance Horizontal scale delta
/// @param {real} ydistance Vertical scale delta
static set_scale_distance = function(xdistance, ydistance) {
set_scale_target
/// @func set_scale_target(xtarget, ytarget)
/// @desc use this function if the animcurve holds a standard 0..1 value
/// for x/y and the curve value shall be a multiplier for the total
/// distance you supply here (a "scale to" curve).
/// Both default scale functions for x and y respect this setting.
/// @param {real} xtarget Horizontal scale target
/// @param {real} ytarget Vertical scale target
static set_scale_target = function(xtarget, ytarget) {
set_rotation_distance
/// @func set_rotation_distance(degrees)
/// @desc use this function if the animcurve holds a standard 0..1 value
/// for image_angle and the curve value shall be a multiplier for the total
/// distance you supply here (a "rotate by" curve).
/// @param {real} degrees The number of degrees to rotate
static set_rotation_distance = function(degrees) {
set_rotation_target
/// @func set_rotation_target(degrees)
/// @desc use this function if the animcurve holds a standard 0..1 value
/// for x/y and the curve value shall be a multiplier from the current
/// to the target angle you supply here (a "rotate to" curve).
/// Both default move functions for x and y respect this setting.
/// @param {real} degrees The angle to rotate to
static set_rotation_target = function(degrees) {
set_blend_range
/// @func set_blend_range(start_color = c_white, end_color = c_white)
/// @desc set the two colors that shall be modified during an image_blend curve
/// @param {color} start_color Color on animcurve value = 0. Default = c_white
/// @param {color} end_color Color on animcurve value = 1. Default = c_white
static set_blend_range = function(start_color = c_white, end_color = c_white) {
set_animcurve
/// @func set_animcurve(_animcurve)
/// @desc Assign a new animcurve to this animation.
/// ATTENTION: Changing a curve in the middle of an animation
/// can be used for advanced effects but also be a source of
/// really unexpected behavior!
static set_animcurve = function(_animcurve) {
set_duration
/// @func set_duration(_duration)
/// @desc Change the duration of this animation.
static set_duration = function(_duration) {
set_function
/// @func set_function(channel_name, _function)
/// @desc Assign a custom function that takes 1 argument (the value) for a channel.
/// You can override (replace) existing functions of Animation or you can add
/// your own custome channel name processors while the animation runs.
/// @param {string} channel_name The name of the channel this function processes
/// @param {func} function The function that processes the channel
static set_function = function(channel_name, _function) {
persist
/// @func persist(_persistent = true)
/// @desc Flags this animation as being persistent, which means,
/// it will be ignored by any _abort_all/_finish_all and _run_ex functions.
static persist = function(_persistent = true) {
play_forward
/// @func play_forward()
/// @desc Animation shall play forward (this is default)
static play_forward = function() {
play_backwards
/// @func play_backwards()
/// @desc Animation shall play backwards (Animcurve starts at 1 and goes back to 0)
static play_backwards = function() {
is_playing_forward
/// @func is_playing_forward()
/// @desc Returns whether the animation is currently in play_forward mode or not
static is_playing_forward = function() {
pause
/// @func pause()
/// @desc Pause the animation at the current frame
static pause = function() {
resume
/// @func resume()
/// @desc Resume the animation at the frame it has been paused
static resume = function() {
set_paused
/// @func set_paused(paused)
/// @desc Set the pause state
/// @param {bool} paused true to pause, false to resume
static set_paused = function(paused) {
is_paused
/// @func is_paused()
/// @desc Check whether this animation is currently paused
/// @returns {bool} The current pause state
static is_paused = function() {
is_active
/// @func is_active()
/// @desc Check if the animation has already started or still in delay countdown
/// @returns {bool} True, if the animation is running, false if still waiting for initial delay
static is_active = function() {
get_frame_counter
/// @func get_frame_counter()
/// @desc Gets the current running frame count
/// NOTE: This function returns 0 (zero) while waiting for the initial delay.
/// @returns {int} The current frame number
static get_frame_counter = function() {
get_remaining_frames
/// @func get_remaining_frames()
/// @desc Returns the amount of frames left for this animation iteration
/// In a looping animation with more than one repeat, this returns
/// the number of frames remaining in the current loop.
/// NOTE:
/// On the LAST FRAME of an iteration, this returns 1 (this one frame remaining)
/// Before the animations started (delay)
/// this returns duration + remaining_delay_frames
/// @returns {int} The remaining frames for this animation iteration
static get_remaining_frames = function() {
abort
/// @func abort(_run_finished_triggers = true)
/// @desc Stop immediately, but finished trigger WILL fire unless you set the argument to false!
static abort = function(_run_finished_triggers = true) {
finish
/// @func finish()
/// @desc Fast forward until the end of the animation, invoking all triggers on the way.
/// The function uses the current delta_time as time step until the end of the animation is reached.
/// If the animation is paused, the paused state is lifted for the operation.
/// Repeats will be set to 1, so only the current iteration will be finished.
/// Both variables (paused and repeats) are set back to their original values when the end of the
/// sequence is reached.
/// ATTENTION! This function uses a "while" loop to process frame-by-frame as fast as possible
/// Use with care in animation sequences (followed_by... etc) as this function will only
/// fast-forward the _current_ animation, not the entire sequence, so with the next frame, a sequence
/// will continue with the next animation in the sequence at normal speed.
static finish = function() {
reset
/// @func reset()
/// @desc All back to start. Animation will RUN now (but respect the delay)!
/// NOTE: The animation direction (forward/backward) will NOT change
/// with a reset!
static reset = function(_incl_triggers = false) {
Continue in Animation Functions (Global).