Skip to main content

CustomAnimator

A simple class for working with animations.

local playerHumanoidCustomAnimator = CustomAnimator.new(humanoidAnimator)
local track = playerHumanoidCustomAnimator:loadAnimation(animation)
track:Play()

Types​

CustomAnimator​

</>
type CustomAnimator = CustomAnimator

Properties​

onAnimationLoaded​

CustomAnimator Instance
</>
CustomAnimator.onAnimationLoaded: Signal<animation: Animation,animationTrack: AnimationTrack>

A signal which is fired whenever a new animation is loaded through CustomAnimator:loadAnimation.

Functions​

new​

</>
CustomAnimator.new(animator: Animator | AnimationController) → CustomAnimator

Creates and returns a new custom animator object.

animationTrack​

CustomAnimator instance
</>
CustomAnimator:animationTrack(animation: Animation) → AnimationTrack?

Returns the given loaded animation track from the animation, if found.

onAnimationLoadPromise​

CustomAnimator instance
</>
CustomAnimator:onAnimationLoadPromise(animation: Animation) → Promise<AnimationTrack>

Returns a promise which is resolved once the given animation is loaded via CustomAnimator:loadAnimation.

Automatic promise cancellation

The returned promise will be cancelled if the animator object or the animation controller object this custom animator is connected to, is destroyed.

loadAnimation​

CustomAnimator instance
</>
CustomAnimator:loadAnimation(animation: Animation) → AnimationTrack

Loads in the given animation.

tryPlayAnimation​

CustomAnimator instance
</>
CustomAnimator:tryPlayAnimation(
animation: Animation,
priority: Enum.AnimationPriority?,
fadeTime: number?,
weight: number?,
speed: number?
) → AnimationTrack?

Tries to play the given animation, if it has been loaded into the custom animator via CustomAnimator:loadAnimation. This method will return the animation track of the loaded animation upon successfully playing it, else it'll return nil.

TIP

You can also setup attributes for fadeTime, weight, and speed in animation, which will be used incase the arguments for them aren't specified.

Attribute Argument
"AnimationPlayFadeTime" fadeTime
"AnimationPlayWeight" weight
"AnimationPlaySpeed" speed

scheduleAnimationToPlayOnLoadPromise​

CustomAnimator instance
</>
CustomAnimator:scheduleAnimationToPlayOnLoadPromise(
animation: Animation,
priority: Enum.AnimationPriority?,
fadeTime: number?,
weight: number?,
speed: number?
) → Promise<>

Plays the given animation as soon as it is loaded into the custom animator. Returns a promise which is resolved once the given animation has finished playing. Additionally, you can cancel the returned promise which in turn will also stop the animation from playing any further.

Automatic promise cancellation

  • If this method is called again for the same animation while the previous promise has not yet finished, then the previous promise will be cancelled.

  • The returned promise will be cancelled if the animator object or the animation controller object this custom animator is connected to, is destroyed.

tryStopAnimation​

CustomAnimator instance
</>
CustomAnimator:tryStopAnimation(
animation: Animation,
fadeTime: number?
) → ()

Tries to stop the given animation, if it is loaded. Also cancels the promise returned by CustomAnimator:scheduleAnimationPlayOnLoadPromise for the given animation, if found.

stopAll​

CustomAnimator instance
</>
CustomAnimator:stopAll(fadeTime: number?) → ()

Stops all loaded animations by calling CustomAnimator:tryStopAnimation on each one of them.

all​

CustomAnimator instance
</>
CustomAnimator:all() → {[Animation]: AnimationTrack}

Returns a read only copy dictionary of all animations loaded into the animator object.

cleanupAnimation​

CustomAnimator instance
</>
CustomAnimator:cleanupAnimation(animation: Animation) → ()

Destroys the animation track of the given animation if loaded, and removes it from the custom animator.

animator​

CustomAnimator instance
</>
CustomAnimator:animator() → Animator

Returns the animator associated to the animator object.

destroy​

CustomAnimator instance
</>
CustomAnimator:destroy() → ()

Destroys the custom animator object and renders it unusuable. Additionally, CustomAnimator:cleanupAnimationTrack is called on all loaded animation tracks too.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": " \nCreates and returns a new custom animator object. ",
            "params": [
                {
                    "name": "animator",
                    "desc": "",
                    "lua_type": "Animator | AnimationController"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "CustomAnimator"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 42,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "animationTrack",
            "desc": " \n\nReturns the given loaded animation track from the animation, if found.",
            "params": [
                {
                    "name": "animation",
                    "desc": "",
                    "lua_type": "Animation"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AnimationTrack?\n"
                }
            ],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 66,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "onAnimationLoadPromise",
            "desc": " \n\nReturns a promise which is resolved once the given animation is loaded via [CustomAnimator:loadAnimation].\n\n:::note Automatic promise cancellation\nThe returned promise will be cancelled if the animator object or the animation controller object this custom\nanimator is connected to, is destroyed.\n:::",
            "params": [
                {
                    "name": "animation",
                    "desc": "",
                    "lua_type": "Animation"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<AnimationTrack>"
                }
            ],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 83,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "loadAnimation",
            "desc": " \n\nLoads in the given `animation`.",
            "params": [
                {
                    "name": "animation",
                    "desc": "",
                    "lua_type": "Animation"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AnimationTrack\n"
                }
            ],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 100,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "tryPlayAnimation",
            "desc": " \n\nTries to play the given `animation`, if it has been loaded into the custom animator via [CustomAnimator:loadAnimation]. This\nmethod will return the animation track of the loaded `animation` upon successfully playing it, else it'll return `nil`.\n\n:::tip\nYou can also setup attributes for `fadeTime`, `weight`, and `speed` in `animation`,  which will be used incase the\narguments for them aren't specified.\n\n| Attribute | Argument \n| -- | -- |\n| `\"AnimationPlayFadeTime\"` | `fadeTime` \n| `\"AnimationPlayWeight\"` | `weight` \n| `\"AnimationPlaySpeed\"` | `speed` \n:::",
            "params": [
                {
                    "name": "animation",
                    "desc": "",
                    "lua_type": "Animation"
                },
                {
                    "name": "priority",
                    "desc": "",
                    "lua_type": "Enum.AnimationPriority?"
                },
                {
                    "name": "fadeTime",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "weight",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "speed",
                    "desc": "",
                    "lua_type": "number?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AnimationTrack?\n"
                }
            ],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 125,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "scheduleAnimationToPlayOnLoadPromise",
            "desc": " \n\nPlays the given `animation` as soon as it is loaded into the custom animator. Returns a promise which is resolved\nonce the given `animation` has **finished playing**. Additionally, you can cancel the returned promise which in turn\nwill also stop the `animation` from playing any further.\n\n:::note Automatic promise cancellation\n- If this method is called again for the same animation while the previous promise has not yet finished, then the previous promise\nwill be cancelled.\n\n- The returned promise will be cancelled if the animator object or the animation controller object this custom\nanimator is connected to, is destroyed.\n:::",
            "params": [
                {
                    "name": "animation",
                    "desc": "",
                    "lua_type": "Animation"
                },
                {
                    "name": "priority",
                    "desc": "",
                    "lua_type": "Enum.AnimationPriority?"
                },
                {
                    "name": "fadeTime",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "weight",
                    "desc": "",
                    "lua_type": "number?"
                },
                {
                    "name": "speed",
                    "desc": "",
                    "lua_type": "number?\n"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Promise<>"
                }
            ],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 162,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "tryStopAnimation",
            "desc": " \n\nTries to stop the given `animation`, if it is loaded. Also cancels the promise returned by \n[CustomAnimator:scheduleAnimationPlayOnLoadPromise] for the given `animation`, if found.",
            "params": [
                {
                    "name": "animation",
                    "desc": "",
                    "lua_type": "Animation"
                },
                {
                    "name": "fadeTime",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 212,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "stopAll",
            "desc": " \n\nStops all loaded animations by calling [CustomAnimator:tryStopAnimation] on each one of them.",
            "params": [
                {
                    "name": "fadeTime",
                    "desc": "",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 234,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "all",
            "desc": " \n\nReturns a read only copy dictionary of all animations loaded into the animator object.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ [Animation]: AnimationTrack }\n"
                }
            ],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 246,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "cleanupAnimation",
            "desc": " \n\nDestroys the animation track of the given `animation` if loaded, and removes it from the custom animator. ",
            "params": [
                {
                    "name": "animation",
                    "desc": "",
                    "lua_type": "Animation"
                }
            ],
            "returns": [],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 256,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "animator",
            "desc": " \n\nReturns the animator associated to the animator object.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Animator\n"
                }
            ],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 271,
                "path": "src/CustomAnimator/init.luau"
            }
        },
        {
            "name": "destroy",
            "desc": " \n\nDestroys the custom animator object and renders it unusuable. Additionally, [CustomAnimator:cleanupAnimationTrack] is called\non all loaded animation tracks too.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "tags": [
                "CustomAnimator instance"
            ],
            "source": {
                "line": 282,
                "path": "src/CustomAnimator/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "onAnimationLoaded",
            "desc": " \n\nA signal which is fired whenever a new animation is loaded through [CustomAnimator:loadAnimation].",
            "lua_type": "Signal<animation: Animation, animationTrack: AnimationTrack>",
            "tags": [
                "CustomAnimator Instance"
            ],
            "source": {
                "line": 25,
                "path": "src/CustomAnimator/init.luau"
            }
        }
    ],
    "types": [
        {
            "name": "CustomAnimator",
            "desc": " ",
            "lua_type": "CustomAnimator",
            "source": {
                "line": 17,
                "path": "src/CustomAnimator/init.luau"
            }
        }
    ],
    "name": "CustomAnimator",
    "desc": " \n\nA simple class for working with animations.\n\n```lua\nlocal playerHumanoidCustomAnimator = CustomAnimator.new(humanoidAnimator)\nlocal track = playerHumanoidCustomAnimator:loadAnimation(animation)\ntrack:Play()\n```",
    "source": {
        "line": 12,
        "path": "src/CustomAnimator/init.luau"
    }
}