Using AnimCurves - Grisgram/gml-raptor GitHub Wiki

By setting the name of a channel in an AnimCurve, you define which property to animate. Name it x and you animate the x-position, name it image_alpha and you fade-in/-out the sprite, etc. And if you create a x, y and image_alpha channel in the same AnimCurve asset, you animate all three properties at the same time!

Supported built-in variables

If you name a channel as shown in the table below, the Animation will interpolate this property of the object.

Built-in variable	Description
`x`	Horizontal position
`y`	Vertical position
`hspeed`	Horizontal speed
`vspeed`	Vertical speed
`speed`	Speed (together with `Direction`)
`directon`	Moving direction
`image_alpha`	Transparency
`image_blend`	Image coloring
`image_xscale`	Horizontal scale
`image_yscale`	Vertical scale
`image_scale`	Special combined value: modifies image_xscale and image_yscale together
`image_angle`	Rotation of the sprite
`image_index`	Subimage of the sprite
`image_speed`	Animation speed

Your own custom channel animations

Animation can be extended very easily through the set_function(channel, function) method which allows you to create a function for any custom channel name you want to use.

Example: Say, you want to combine the scaling of some damage-shield sprite that is overlayed to your player sprite and want to do this in a single Animation with a single AnimCurve. When the player receives a level-up, it will scale up for a short time and return back to scale 1.0 (a simple bumping effect). To have two or more sprites animated, you would normally need two Animations, but you can combine that with a custom function.

Your AnimCurve could look like this:

And for the Animation that shall run this, you define something like

animation_run(my_player_object, 0, 30, acLevelUp)
    .set_function("ShieldAndPlayer", function(value) {
        my_player_object.image_xscale = value;
        my_player_object.image_yscale = value;
        my_player_object.shield.image_xscale = value;
        my_player_object.shield.image_yscale = value;
    });

And with that you run an Animation using the "acLevelUp" AnimCurve with a delay of zero frames (starts immediately) for 30 frames (0.5 seconds), and to interpret the custom channel "ShieldAndPlayer", you defined a function that scales both the player and the shield.

NOTE: Of course you could scale the shield together with the player in the object's code. This example here just shows a different approach -- one that does not require you to write code in the step/draw events with additional if... conditions for whether level-up is still animating and maintaining your animation states in the object. You can do this in one place without events, overrides, or cluttered code over many code windows.

The `values` member in an Animation

Every Animation instance offers a property values, which is a Bindable struct.
This means, in addition to triggers, you can also easily bind a watcher to any value of the curve, for instance, to update an effects layer to create animations on their values.
It holds all running values of the animation, named the same as the channel name in the Animation Curve, that it follows.

Example:
If you run an animation with a curve, that has a x and a y channel, then values.x and values.y hold the current values of the current frame of the curve.

Multiple Channels

I want to show you some AnimCurves I used in the game One (K)night alone where you can see how it looks to animate multiple values in a single AnimCurve asset.

Floating Text Animation

This curve lets the damage/heal text float above the target's head upwards, fading softly in and out.

Enter / Leave a Level

Those curves let the player enter the level (it climbs up stairs and moves to the start field) and exit (leave through the portal door and scales down to minimum to simulate "walking away".

Relative and Absolute values

If you look at the pictures above, you will recognize that all of those curves have a value range from 0..1. But how does that make sense when the Player enters a room? The object won't move only one single pixel, right?

There are some animated values that need more input than just a curve if you want to keep everything in a 0..1 range. These values can be configured with one of the functions shown below to tell the Animation how to interpret the values it receives from a channel.

Important

PLEASE NOTE: You are NOT FORCED to use these functions shown below! You may as well create your absolute values in the AnimCurve directly. Then > you don't need any of them, but you will face the same limitations that Sequences have. You create a static, non-configurable AnimCurve for only one purpose. Most likely, you won't be able to reuse the curve in multiple places.

The only exception to this is the image_blend channel. You must supply a starting and end color for this to work as described in the table below.

Channel	Function	Description
`x`,`y`	`set_move_distance(xd,yd)`	Set the absolute amount of pixels to move. Example: set_move_distance(150,50) will make the object move by 150x and 50y pixels over the time in a 0..1 channel. The channel value is the percent multiplier of how-much of that distance is already done each frame.
`x`,`y`	`set_move_target(xt,yt)`	Set the absolute final position where this `Animation` will end. The 0..1 range is again interpreted as percent value to reach this point.
`image_xscale` `image_yscale` `image_scale`	`set_scale_distance(xd,yd)`	Similar to `set_move_distance` for `x` and `y` this sets by how much the scale shall change over time.
`image_xscale` `image_yscale` `image_scale`	`set_scale_target(xt,yt)`	Similar to `set_move_target` for `x` and `y` this sets the final scale value to reach over time.
`image_angle`	`set_rotation_distance(degrees)`	Similar to `set_move_distance` for `x` and `y` this sets the number of degrees to rotate over time.
`image_angle`	`set_rotation_target(degrees)`	Similar to `set_move_target` for `x` and `y` this sets the final rotation degrees to reach over time.
`image_blend`	`set_blend_range(start, end)`	Color blending animation is done through the `merge_color` function of GameMaker. You supply the starting and end colors with this function and the `image_blend` curve should always be in 0..1 range.

Default AnimCurves in raptor

raptor comes with a set of default AnimCurves which can be found in the _generic_animcurves_ folder of the _gml_raptor_ section in the project template.
All of these curves follow the 0..1 scheme and can be used in both animation directions, play_forward and play_backwards (see the Animation Functions (Class) page for a definition of those functions).

They all look similar and follow a linear path from 0 to 1, but they already deliver the correct channel name to animate a property. So, for standard alpha blending or scaling, you do not need to define your own linear AnimCurve. You can use the ones from raptor.

This was a lot of information; now let's look at some practical examples. Dive into Animation meets StateMachine to see how this Animation class can bring your game objects to life directly in the StateMachine with minimal code.