Skip to content

Animation

Animation objects are used to gather data about specific animations. Although you can't spawn Animation objects directly, you can access them via other objects such as Actor and Player.

Example

using SurgeEngine.Actor;

object "MyExplosion" is "entity", "disposable", "private"
{
    actor = Actor("MyExplosion");

    state "main"
    {
        if(actor.animation.finished)
            destroy();
    }
}

Properties

id

id: number.

The number of the animation, defined in a .spr file.

sprite

sprite: string, read-only.

The name of the sprite, defined in a .spr file.

exists

exists: boolean, read-only.

Will be true if the animation exists, i.e., if its sprite and its animation number have been defined in a .spr file.

Available since: Open Surge 0.5.1

finished

finished: boolean, read-only.

Will be true if the animation has finished playing.

anchor

anchor: Vector2 object, read-only.

The hot spot of the animation normalized to [0,1] x [0,1].

Available since: Open Surge 0.6.0

hotSpot

hotSpot: Vector2 object, read-only.

The hot spot of the animation. Coordinates are given in pixels.

Note: prior to Open Surge 0.6.0, this property was called hotspot.

actionSpot

actionSpot: Vector2 object, read-only.

The action spot of the animation. Coordinates are given in pixels. If the sprite is flipped, the action spot is automatically flipped relative to the hot spot of the animation.

Available since: Open Surge 0.6.0

actionOffset

actionOffset: Vector2 object, read-only.

When this vector is added to the position of the sprite, you'll get the position of the action spot. This is suitable to be used with transform.localPosition.

Available since: Open Surge 0.6.0

repeats

repeats: boolean, read-only.

Does the animation repeat itself?

fps

fps: number, read-only.

Frames per second of the animation.

frameCount

frameCount: number, read-only.

The number of frames of the animation.

duration

duration: number, read-only.

The duration of the animation, in seconds.

Available since: Open Surge 0.6.1

frame

frame: number.

The current frame of the animation: an integer between 0 and frameCount - 1, inclusive.

speedFactor

speedFactor: number.

While the FPS rate controls the speed of the animation, the speed factor gives you an additional degree of control. This is a multiplier that defaults to 1.0, meaning that the animation will run using its normal speed. If it's set to 2.0, it will run using twice that speed. A value of 0.5 means half the speed, and so on.

sync

sync: boolean.

Is the animation is synchronized? A synchronized animation is a repeating animation that displays the same frame across multiple sprites. Defaults to false.

Functions

prop

prop(propertyName)

Read the user-defined custom property named propertyName defined in a custom_properties block of the sprite of this animation (.spr file). If the property exists, this function will return a string, a number, a boolean, or an Array of these, depending on the property. If the property does not exist, this function will return null.

Available since: Open Surge 0.6.1

Arguments

  • propertyName: string. The name of a custom property.

Returns

Returns a string, a number, a boolean, an array of these primitive types with at least two elements, or null.

Example

/*

Example of a custom_properties block:

// .spr file
sprite "My Test Sprite"
{
    // ...

    custom_properties
    {
        number_of_layers        8
        want_awesomeness        true
        font_name               "GoodNeighbors"
        position                100 200
    }
}

*/

// It's a good idea to cast the value of the property to the expected type, so
// that your script will work reliably regardless of what is in the .spr file!

animation = actor.animation;

numberOfLayers = Number(animation.prop("number_of_layers")); // 8
wantAwesomeness = Boolean(animation.prop("want_awesomeness")); // true
fontName = String(animation.prop("font_name") || "Default Font Name"); // "GoodNeighbors"
foobar = String(animation.prop("foobar") || "undefined"); // "undefined"

position = animation.prop("position");
if(typeof position == "object") {
    xpos = Number(position[0]); // 100
    ypos = Number(position[1]); // 200
}
else {
    xpos = 0;
    ypos = 0;
}

findTransform

findTransform()

When a keyframe-based animation is playing, compute an approximation of the transformation applied to the sprite at the current time. You may use this function to make objects follow the transformed sprite or to know its location. If no keyframe-based animation is currently playing, the identity transform will be returned.

Available since: Open Surge 0.6.1

Returns

Returns a Transform object.

Example

animationTransform = animation.findTransform();
Console.print(animationTransform.localPosition);