Skip to main content

AnimationRegistry

Global singleton registry for animation configs.

AnimationRegistry holds all animation configuration data for the game. It must be initialized once at startup, before any AnimationController is created. Controllers look up their animation configs from this registry by name. 

local AnimationRegistry = require(ReplicatedStorage.Motix.Modules.AnimationRegistry)

local Registry = AnimationRegistry.GetInstance()

Registry:Init({
	{
		Name         = "Idle",
		AssetId      = "rbxassetid://YOUR_ID",
		Layer        = "Base",
		Looped       = true,
		Priority     = 0,
		FadeInTime   = 0.2,
		FadeOutTime  = 0.2,
		Speed        = 1.0,
		Weight       = 1.0,
		CanInterrupt = true,
		Tags         = {},
		Additive     = false,
	},
})
One-time initialization

Init may only be called once. Calling it a second time throws an error. Initialize at the top of your startup script before requiring any other Motix modules that create controllers.

Functions​

GetInstance​

</>
AnimationRegistry.GetInstance() → AnimationRegistry

Returns the singleton AnimationRegistry instance.

The instance is created lazily on first call. All calls return the same object.

local Registry = AnimationRegistry.GetInstance()

Init​

</>
AnimationRegistry:Init(
Configs: {AnimationConfig}--

Array of animation config tables.

) → ()

Initializes the registry with an array of animation configs.

Each config is validated at call time. Errors throw immediately with a descriptive message.

Required fields per config:

Field Type Description
Name string Unique animation name. Referenced by Controller:Play() and Controller:Stop().
AssetId string Roblox animation asset ID ("rbxassetid://...").
Layer string Layer this animation belongs to. Must match a LayerProfile name on the controller.
Looped boolean Whether the animation loops.
Priority number Conflict priority within the layer or group.
FadeInTime number Seconds for the animation to fade in.
FadeOutTime number Seconds for the animation to fade out.
Speed number Playback speed multiplier.
Weight number Blend weight within its layer. Range (0, 1].
CanInterrupt boolean Whether this animation can be interrupted by a lower-priority group request.
Tags { string } Tag strings for batch operations via PlayTag.
Additive boolean Whether the animation is played in additive blending mode.

Optional fields:

Field Type Description
Group string? Exclusive group name. nil means no group.
MinDuration number? Minimum seconds before interruption is allowed.
Metadata table? Arbitrary key-value table stored with the config.

All configs are deep-frozen after validation. Modifying a config after Init has no effect on the registry. 

Registry:Init({
	{
		Name = "Fire", AssetId = "rbxassetid://FIRE_ID",
		Layer = "UpperBody", Group = "WeaponAction",
		Looped = false, Priority = 10,
		FadeInTime = 0.05, FadeOutTime = 0.1,
		Speed = 1.0, Weight = 1.0,
		CanInterrupt = false, Tags = { "weapon" }, Additive = false,
	},
})

GetByName​

</>
AnimationRegistry:GetByName(
Name: string--

The animation name to look up.

) → AnimationConfig?--

The frozen config, or nil.

Returns the frozen AnimationConfig for the given name, or nil if not found.

local config = Registry:GetByName("Idle")
if config then
	print(config.AssetId)
end

GetByTag​

</>
AnimationRegistry:GetByTag(
Tag: string--

The tag to look up.

) → {AnimationConfig}--

Frozen array of configs with this tag.

Returns all animation configs registered under the given tag.

Returns an empty table if no animations have the tag. The returned table is frozen.

local footsteps = Registry:GetByTag("footstep")
for _, config in footsteps do
	print(config.Name, config.AssetId)
end

GetByGroup​

</>
AnimationRegistry:GetByGroup(
Group: string--

The group name to look up.

) → {AnimationConfig}--

Frozen array of configs in this group.

Returns all animation configs registered under the given group name.

Returns an empty table if no animations belong to the group. The returned table is frozen.

local weaponAnims = Registry:GetByGroup("WeaponAction")

IsInitialized​

</>
AnimationRegistry:IsInitialized() → boolean

Returns whether the registry has been initialized.

if not Registry:IsInitialized() then
	Registry:Init(myConfigs)
end
Show raw api
{
    "functions": [
        {
            "name": "GetInstance",
            "desc": "Returns the singleton `AnimationRegistry` instance.\n\nThe instance is created lazily on first call. All calls return the same object.\n\n```lua\nlocal Registry = AnimationRegistry.GetInstance()\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "AnimationRegistry"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 52,
                "path": "docs/AnimationRegistry.lua"
            }
        },
        {
            "name": "Init",
            "desc": "Initializes the registry with an array of animation configs.\n\nEach config is validated at call time. Errors throw immediately with a descriptive message.\n\n**Required fields per config:**\n\n| Field | Type | Description |\n|---|---|---|\n| `Name` | `string` | Unique animation name. Referenced by `Controller:Play()` and `Controller:Stop()`. |\n| `AssetId` | `string` | Roblox animation asset ID (`\"rbxassetid://...\"`).|\n| `Layer` | `string` | Layer this animation belongs to. Must match a `LayerProfile` name on the controller. |\n| `Looped` | `boolean` | Whether the animation loops. |\n| `Priority` | `number` | Conflict priority within the layer or group. |\n| `FadeInTime` | `number` | Seconds for the animation to fade in. |\n| `FadeOutTime` | `number` | Seconds for the animation to fade out. |\n| `Speed` | `number` | Playback speed multiplier. |\n| `Weight` | `number` | Blend weight within its layer. Range `(0, 1]`. |\n| `CanInterrupt` | `boolean` | Whether this animation can be interrupted by a lower-priority group request. |\n| `Tags` | `{ string }` | Tag strings for batch operations via `PlayTag`. |\n| `Additive` | `boolean` | Whether the animation is played in additive blending mode. |\n\n**Optional fields:**\n\n| Field | Type | Description |\n|---|---|---|\n| `Group` | `string?` | Exclusive group name. `nil` means no group. |\n| `MinDuration` | `number?` | Minimum seconds before interruption is allowed. |\n| `Metadata` | `table?` | Arbitrary key-value table stored with the config. |\n\nAll configs are deep-frozen after validation. Modifying a config after `Init` has no\neffect on the registry.\n\n```lua\nRegistry:Init({\n\t{\n\t\tName = \"Fire\", AssetId = \"rbxassetid://FIRE_ID\",\n\t\tLayer = \"UpperBody\", Group = \"WeaponAction\",\n\t\tLooped = false, Priority = 10,\n\t\tFadeInTime = 0.05, FadeOutTime = 0.1,\n\t\tSpeed = 1.0, Weight = 1.0,\n\t\tCanInterrupt = false, Tags = { \"weapon\" }, Additive = false,\n\t},\n})\n```",
            "params": [
                {
                    "name": "Configs",
                    "desc": "Array of animation config tables.",
                    "lua_type": "{ AnimationConfig }"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 102,
                "path": "docs/AnimationRegistry.lua"
            }
        },
        {
            "name": "GetByName",
            "desc": "Returns the frozen `AnimationConfig` for the given name, or `nil` if not found.\n\n```lua\nlocal config = Registry:GetByName(\"Idle\")\nif config then\n\tprint(config.AssetId)\nend\n```",
            "params": [
                {
                    "name": "Name",
                    "desc": "The animation name to look up.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "The frozen config, or nil.",
                    "lua_type": "AnimationConfig?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 117,
                "path": "docs/AnimationRegistry.lua"
            }
        },
        {
            "name": "GetByTag",
            "desc": "Returns all animation configs registered under the given tag.\n\nReturns an empty table if no animations have the tag. The returned table is frozen.\n\n```lua\nlocal footsteps = Registry:GetByTag(\"footstep\")\nfor _, config in footsteps do\n\tprint(config.Name, config.AssetId)\nend\n```",
            "params": [
                {
                    "name": "Tag",
                    "desc": "The tag to look up.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "Frozen array of configs with this tag.",
                    "lua_type": "{ AnimationConfig }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 134,
                "path": "docs/AnimationRegistry.lua"
            }
        },
        {
            "name": "GetByGroup",
            "desc": "Returns all animation configs registered under the given group name.\n\nReturns an empty table if no animations belong to the group. The returned table is frozen.\n\n```lua\nlocal weaponAnims = Registry:GetByGroup(\"WeaponAction\")\n```",
            "params": [
                {
                    "name": "Group",
                    "desc": "The group name to look up.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "Frozen array of configs in this group.",
                    "lua_type": "{ AnimationConfig }"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 148,
                "path": "docs/AnimationRegistry.lua"
            }
        },
        {
            "name": "IsInitialized",
            "desc": "Returns whether the registry has been initialized.\n\n```lua\nif not Registry:IsInitialized() then\n\tRegistry:Init(myConfigs)\nend\n```",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 161,
                "path": "docs/AnimationRegistry.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "AnimationRegistry",
    "desc": "Global singleton registry for animation configs.\n\n`AnimationRegistry` holds all animation configuration data for the game. It must be\ninitialized once at startup, before any `AnimationController` is created. Controllers\nlook up their animation configs from this registry by name.\n\n```lua\nlocal AnimationRegistry = require(ReplicatedStorage.Motix.Modules.AnimationRegistry)\n\nlocal Registry = AnimationRegistry.GetInstance()\n\nRegistry:Init({\n\t{\n\t\tName         = \"Idle\",\n\t\tAssetId      = \"rbxassetid://YOUR_ID\",\n\t\tLayer        = \"Base\",\n\t\tLooped       = true,\n\t\tPriority     = 0,\n\t\tFadeInTime   = 0.2,\n\t\tFadeOutTime  = 0.2,\n\t\tSpeed        = 1.0,\n\t\tWeight       = 1.0,\n\t\tCanInterrupt = true,\n\t\tTags         = {},\n\t\tAdditive     = false,\n\t},\n})\n```\n\n:::caution One-time initialization\n`Init` may only be called once. Calling it a second time throws an error. Initialize at\nthe top of your startup script before requiring any other Motix modules that create\ncontrollers.\n:::",
    "source": {
        "line": 39,
        "path": "docs/AnimationRegistry.lua"
    }
}