Animation Functions (Class) - Grisgram/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).
/// @function Animation(
/// _obj_owner, _delay, _duration, _animcurve, _repeats = 1, _finished_state = undefined)
/// @description 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).
add_started_trigger
/// @function add_started_trigger(trigger)
/// @description Add a trigger to run when animation starts.
/// The callback will receive 1 parameter: data
/// @param {func} trigger The callback to invoke.
add_frame_trigger
/// @function add_frame_trigger(trigger)
/// @description 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} trigger If true, runs every x frames.
add_loop_trigger
/// @function add_loop_trigger(trigger)
/// @description 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.
add_finished_trigger
/// @function add_finished_trigger(trigger)
/// @description Add a trigger to run when animation finishes.
/// The callback will receive 1 parameter: data
/// @param {func} trigger The callback to invoke.
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.
/// @function reset_triggers()
/// @description Remove all registered triggers from this animation.
set_name
/// @function set_name(_name)
/// @description 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.
set_move_distance
/// @function set_move_distance(xdistance, ydistance)
/// @description 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
set_move_target
/// @function set_move_target(xtarget, ytarget)
/// @description 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
set_scale_distance
/// @function set_scale_distance(xdistance, ydistance)
/// @description 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
set_scale_target
/// @function set_scale_target(xtarget, ytarget)
/// @description 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} xdistance Horizontal scale target
/// @param {real} ydistance Vertical scale target
set_rotation_distance
/// @function set_rotation_distance(degrees)
/// @description 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
set_rotation_target
/// @function set_rotation_target(degrees)
/// @description 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
set_blend_range
/// @function set_blend_range(start_color = c_white, end_color = c_white)
/// @description 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
set_animcurve
/// @function set_animcurve(_animcurve)
/// @description 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!
set_duration
/// @function set_duration(_duration)
/// @description Change the duration of this animation.
set_function
/// @function set_function(channel_name, _function)
/// @description 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
play_forward
/// @function play_forward()
/// @description Animation shall play forward (this is default), but it may be useful
/// to set it back to forward if this animation was reused and ran backwards
/// at any time in the past.
play_backwards
/// @function play_backwards()
/// @description Animation shall play backwards (Animcurve starts at 1 and goes back to 0)
is_playing_forward
/// @function is_playing_forward()
/// @description Returns whether the animation is currently in play_forward mode or not
pause
/// @function pause()
/// @description Pause the animation at the current frame
resume
/// @function resume()
/// @description Resume the animation at the frame it has been paused
set_paused
/// @function set_paused(paused)
/// @description Set the pause state
/// @param {bool} paused true to pause, false to resume
is_paused
/// @function is_paused()
/// @description Check whether this animation is currently paused
/// @returns {bool} The current pause state
is_active
/// @function is_active()
/// @description 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
get_frame_counter
/// @function get_frame_counter()
/// @description Gets the current running frame count
/// NOTE: This function returns 0 (zero) while waiting for the initial delay.
/// @returns {int} The current frame number
get_remaining_frames
/// @function get_remaining_frames()
/// @description 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
abort
/// @function abort(_run_finished_triggers = true)
/// @description Stop immediately, but finished trigger WILL fire unless you set the argument to false!
finish
/// @function finish()
/// @description 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.
reset
/// @function reset()
/// @description All back to start. Animation will RUN now (but respect the delay)!
/// NOTE: The animation direction (forward/backward) will NOT change
/// with a reset!
Continue in Animation Functions (Global).