Basics Guide

Adding GM Animate to your project

1. Download the newest .yymps file here
2. While your project is open, either drag the file in, or go to the tools menu at the top, hit import local package, and select the file
3. Click "add all" and then "import"
4. A folder called "GM Animate" should appear in your asset browser
5. You're all set!

Updating GM Animate to a new version

Select the GM Animate folder in your project, and delete it entirely. Then, follow the instructions above to re-add the new version.

[!WARNING] GM Animate will not work properly if you have the legacy copy on write behavior enabled for arrays!

Playing your object's animations with GM Animate

You can get the same functionality as assigning a sprite to an object by adding two lines of code.

In the create event:

anim = animation_start(spr_idle);

In the draw event:

animation_draw();

Just like when using GameMaker's default animation, you can edit various built in variables to change how the sprite looks. Using the example above, you can access the animation's variables with the anim variable, like so:

anim.image_speed = 0.5;
anim.image_angle = 90;

"anim" is not part of the library - you can call that variable whatever you like! animation_start returns a struct that contains everything related to that animation, so that's what you're storing in the variable.

All of GM's built in image_* variables are included, with the same names. sprite_index is also present, but if you change sprite_index directly, the animation's number of frames and FPS won't get updated and it may not animate properly. To change the sprite, you can either call animation_start again, or use animation_change.

• animation_start will reset everything about the animation, such as changed variables, effects, the queue, etc.
• animation_change will change the sprite and update relevant values like FPS without resetting things.

In most cases, animation_change will be the right choice!

[!CAUTION] Calling animation_start will create a new variable on your object called animations. Make sure you don't use this variable name for other things. While you can change the variables listed as free to edit on the animation struct page in the manner shown below, 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.

[!NOTE] x and y are not present in the animation struct. To change the coordinates the animation appears at, change the x and y arguments sent to animation_draw instead.

With that, you should be able to do everything GM's built in animation can do. Now for the fun stuff!

   

Using effects

Effects can be applied to your animation with just one line of code!

animation_effect_shake(30, 5);

This would make the animation shake for 30 frames. You can have as many effects active at once as you like, including stacking the same effect multiple times! Check out the effects page for details on each effect.

   

Playing multiple animations on one object

To animate multiple sprites on a single object, you don't actually need any new functions! By using the tracks feature, you can play and manipulate as many animations as you want, using the same functions you'd use if you only have a single animation. Each track is a number, and by default animation_start plays the animation on track 0. You can use a different number for the _track argument to create a new track:

body_anim = animation_start(spr_idle, true, 0);
weapon_anim = animation_start(spr_gun_idle, true, 1);
effects_anim = animation_start(spr_muzzle_flash, false, 2);

With this, the animations played on tracks 0, 1, and 2 will each animate independently, and you can change their variables separately as well. Most functions in the library have a track argument to apply them to a specific track. Some functions can also take all as the track to apply it to every active track at once.

animation_effect_shake(30, 5, 1);
animation_effect_hitstop(10, all);

This would apply a shake effect to just track 1, and apply a hitstop effect to every track.

[!NOTE] Tracks cannot be negative numbers or floats, and it's recommended to count up tracks from 0, such as having tracks 0, 1, 2, 3, etc. Doing something like having tracks 0 and 1000 will have a negative effect on performance.

   

Using the animation queue

The animation queue allows you to queue up multiple animations to play one after another automatically. If any sprites have been added to the queue, then the animation at the front of the queue will automatically play when the current animation has finished. To queue an animation, use animation_queue_add:

animation_queue_add(//sprite to queue goes here!);

That's it! The sprite you pass will automatically be swapped to whenever the current animation finishes. You can queue as many animations as you want. If multiple animations are queued, they will all play in sequence. Check out the animation queue page for more info!

   

Handling collision

Unlike GM's built in animation variables, changing the variables used by GM Animate do not affect the object's mask at all. In most cases, setting mask_index to something like your idle sprite is sufficient for setting up your mask. Since GM Animate does not change any of the object's own variables normally, you can manipulate the mask yourself in whatever way suits you. However, there is one function available if you need your mask to match the state of a currently playing animation, animation_set_instance_mask:

animation_set_instance_mask(true, true);

[!IMPORTANT] Using this function WILL change the object's variables, such as mask_index and image_index, as these are the only way to manipulate the object's mask. If you pass true for _use_scale and _use_angle, then the object's image_xscale, image_yscale, and image_angle will also change.

   

Other useful functions

GM Animate also has a handful of other handy functions.

animation_finished checks if an animation reached the end of it's final frame this step:

if animation_finished() {
    state = idle;
}

animation_on_frame checks if an animation is on the specified frame. It will return true every step that the animation is on that frame:

if animation_on_frame(6) {
    part_particles_create(part_system, x, y, part_sparks, 5);
}

animation_enter_frame is similar to animation_on_frame, but it will only return true on the first step that the animation hits the specified frame, making it useful for things you only want to happen once per loop of the animation:

if animation_enter_frame(10) {
    instance_create_layer(x, y, "Hitboxes", obj_hitbox);
}

For a full list of miscellaneous functions, check out the animation control page!

There are also a variety of functions to pausing and unpausing your animations to go alongside your pause system. Check out the pausing page for more info!