This section has all the basic and miscellaneous functions that aren't tied to any specific system.

animation_start

Plays an animation by creating a new animation struct and adding it to the animations array on the calling instance. The array index used will be the same as the track used. If animation_start is called again for a track it was already previously called for, the existing animation struct will be overwritten, meaning all variable changes, effects, etc. will be reset. This is useful if you want to change a track to a new sprite without carrying anything from before over. If you want to just change the sprite without resetting things, use animation_change instead.

[!IMPORTANT] This function must be called at least once before using any other animation functions!

animation_start(_sprite, _loop = true, _track = 0)

Argument	Type	Description
_sprite	Sprite Asset	The sprite to use for the animation
_loop	Boolean	(Optional) Whether the animation should loop or not when it finishes
_track	Real (Int)	(Optional) The track to play the animation on

Returns: Animation struct

   

animation_change

Changes what sprite is used by an animation track, without resetting things like variables, effects, etc. A notable exception is image_speed, which will be reset to 1 if the previous animation had image_speed set to 0 as a result of having loop set to false. By default, image_index will also reset to 0, but you can pass -1 to the _starting_image_index argument to keep the image_index the previous animation was on.

animation_change(_sprite, _starting_image_index = 0, _loop = true, _track = 0)

Argument	Type	Description
_sprite	Sprite Asset	The sprite to change the animation to
_starting_image_index	Real	(Optional) The frame to start the new animation on. Pass -1 to keep the image_index of the previous animation
_loop	Boolean	(Optional) Whether the animation should loop or not when it finishes
_track	Real (Int)	(Optional) The track to change the animation of

Returns: Animation struct

   

animation_draw

Draws an animation at the specified coordinates. Internally this is a draw_sprite_ext call, so you are free to call it in draw GUI or apply shaders to it like you would any other draw_sprite call. You can pass all as the track argument to draw all tracks at once, though they will all be drawn at the same coordinates. They will draw in ascending track order, so track 0 will draw first, then track 1 on top of it, etc.

[!IMPORTANT] This function must be called at least once for your animation to be visible!

animation_draw(_x = x, _y = y, _track = 0)

Argument	Type	Description
_x	Real	(Optional) The x coordinate to draw the animation at
_y	Real	(Optional) The y coordinate to draw the animation at
_track	Real (Int)	(Optional) The track to draw. Pass all to draw all tracks at once

Returns: N/A (undefined)

   

animation_set_instance_mask

Sets variables on the calling instance to make it's variables match that of the specified animation track. The exact variable changes are as follows:

• mask_index will be set to the sprite_index of the animation track
• image_index will be set to match the animation track (so that precise per frame masks will work)
• if true is passed for _use_scale, image_xscale and image_yscale will be set to match the animation track
• if true is passed for _use_angle, image_angle will be set to match the animation track

[!WARNING] Unlike all other animation functions, this function will change built in variables on the instance itself, not just the animation's internal variables!

[!NOTE] Changes to position, scale, and angle from effects are not applied to the mask.

animation_set_instance_mask(_use_scale = false, _use_angle = false, _track = 0)

Argument	Type	Description
_use_scale	Bool	(Optional) Whether to apply the animation's image_xscale and image_yscale to the object or not
_use_angle	Bool	(Optional) Whether to apply the animation's image_angle to the object or not
_track	Real (Int)	(Optional) The track to base the mask on

Returns: N/A (undefined)

   

animation_finished

Checks if the animation on the specified track finished this step. This will only return true on the single step that the animation first reaches it's end, and will not return true repeatedly if the animation is stopped on it's final frame.

animation_finished(_track)

Argument	Type	Description
_track	Real (Int)	(Optional) The track to check

Returns: Bool

   

animation_on_frame

Checks if the animation on the specified track is currently on the specified frame. This function will return true every step that the animation is on that frame if the animation is on that frame for multiple steps. If you want to check for the animation arriving at a frame for the first time, use animation_enter_frame instead.

You can optionally pass an array of frames to check multiple frames in one call:

if animation_on_frame([2, 6, 11]) {
    //do something while on frames 2, 6, and 11
}

animation_on_frame(_frame, _track = 0)

Argument	Type	Description
_frame	Real or Array of Reals	The frame to check, or array of frames to check
_track	Real (Int)	(Optional) The track to check

Returns: Bool

   

animation_enter_frame

Checks if the animation on the specified track just reached the specified frame for the first time this loop. This function will only return true the first step that the animation reaches the specified frame. This is useful for spawning hitboxes or other one time only actions. If you want to check for the animation being on a frame regardless of how long it's been on it, use animation_on_frame instead.

You can optionally pass an array of frames to check multiple frames in one call:

if animation_enter_frame([1, 4, 8]) {
    //do something when first arriving at frames, 1, 4, and 8
}

animation_on_frame(_frame, _track = 0)

Argument	Type	Description
_frame	Real or Array of Reals	The frame to check, or array of frames to check
_track	Real (Int)	(Optional) The track to check

Returns: Bool

   

animation_get

Retrieves the animation struct for the specified track. If all is passed as the track argument, an array of all animation structs will be returned. Note that this returned array is just the animations array on the instance. This means you can also access animation structs for different tracks by accessing this array directly instead, eg. animation_get(1) could instead be animations[1].

[!CAUTION] While you can change the variables listed as free to edit on the animation struct page, you should not set one of the array indexes to anything or directly modify the array in any other way! Doing so will likely make everything explode.

animation_get(_track = 0)

Argument	Type	Description
_track	Real (Int)	(Optional) The track to get. Pass all to get an array of all animation structs

Returns: Animation Struct or array of animation structs (if all passed as track)

   

animation_exists

Checks if an animation exists for the specified track.

animation_exists(_track = 0)

Argument	Type	Description
_track	Real (Int)	(Optional) The track to check

Returns: Bool

   

animation_delete

Removes an animation track, deleting it entirely. This is useful if you added a new track for something like a temporary effect, and the effect is now finished and no longer needed. You can also pass all as the track argument to delete the animations on every track and start fresh.

animation_delete(_track)

Argument	Type	Description
_track	Real (Int)	(Optional) The track to delete. Pass all to delete all animation tracks at once

Returns: N/A (Undefined)

   

   

animation_set_looping

Sets a specified track to loop or not loop. You can also change the loop variable in the animation struct directly.

animation_set_looping(_loop, _track = 0)

Argument	Type	Description
_loop	Bool	Whether to set looping to true or false
_track	Real (Int)	(Optional) The track to set looping on. Pass all to set looping on every track at once

Returns: N/A (Undefined)

   

animation_get_looping

Checks if the specified track is currently looping or not.

animation_set_looping(_loop, _track = 0)

Argument	Type	Description
_track	Real (Int)	(Optional) The track to check

Returns: N/A (Undefined)

   

animation_get_sprite_width

Returns the animation's sprite_width. This is calculated the same way GM's built in sprite_width is, so it's the base width multiplied by xscale.

animation_get_sprite_width(_track = 0)

Argument	Type	Description
_track	Real (Int)	(Optional) The track to check

Returns: N/A (Undefined)

   

animation_get_sprite_height

Returns the animation's sprite_height. This is calculated the same way GM's built in sprite_height is, so it's the base height multiplied by yscale.

animation_get_sprite_height(_track = 0)

Argument	Type	Description
_track	Real (Int)	(Optional) The track to check

Returns: N/A (Undefined)