Reference ‐ Animation Control - KormexGit/GM-Animate GitHub Wiki
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)