Skip to main content

TypeDefinitions

Shared Luau type definitions used across Motix and MotixNet.

This page documents every field on the core data types. You do not import this module directly. It exists as an API reference for the types that flow through the system.

Types​

AnimationConfig​

</>
interface AnimationConfig {
Name: string--

Unique animation identifier. Passed to Controller:Play() and Controller:Stop().

AssetId: string--

Roblox animation asset ID ("rbxassetid://...").

Layer: string--

Layer this animation belongs to. Must match a registered LayerProfile name.

Group: string?--

Exclusive group name. Only one animation per group may play at a time.

Priority: number--

Conflict priority within the layer or group. Higher values win. Default: 0.

Looped: boolean--

Whether the animation loops. Default: false.

FadeInTime: number--

Seconds for the animation to fade in when it starts playing. Default: 0.1.

FadeOutTime: number--

Seconds for the animation to fade out when it stops. Default: 0.1.

Speed: number--

Playback speed multiplier. Default: 1.0.

Weight: number--

Blend weight contribution within its layer. Range (0, 1]. Default: 1.0.

CanInterrupt: boolean--

Whether a lower-priority group member can replace this animation before it finishes. Default: true.

MinDuration: number?--

Minimum seconds the animation must play before group conflict resolution can interrupt it.

Tags: {string}--

Tag strings for batch operations via Controller:PlayTag(). Default: {}.

Additive: boolean--

Whether the animation plays in additive blending mode. Default: false.

Metadata: {[string]: any}?--

Arbitrary data stored with the config. Accessible from registry lookups.

}

Defines a single animation. All fields are required unless marked optional. Produced by BehaviorBuilder:Animation():Done() and stored in AnimationRegistry.

Once registered, configs are frozen. Modifying them after AnimationRegistry:Init() has no effect.

LayerProfile​

</>
interface LayerProfile {
Name: string--

Unique layer identifier. Referenced by AnimationConfig.Layer, state ActiveLayer, and SuppressLayer.

Order: number--

Integer blending order. Lower values are evaluated first. Must be unique per behavior.

BaseWeight: number--

Default layer weight when the layer is active. Range [0, 1]. Default: 1.0.

Additive: boolean--

When true, this layer composes with lower-order layers rather than replacing them. Default: false.

Isolated: boolean--

When true, this layer does not interact with other layers during blending. Default: false.

WeightLerpRate: number--

Speed in units per second at which the layer weight interpolates toward its target. Use math.huge for instant snapping. Default: 8.0.

}

Defines an animation layer. Layers control how animations blend and which animations can coexist. Produced by BehaviorBuilder:Layer():Done().

StateDefinition​

</>
interface StateDefinition {
Name: string--

Unique state name. Referenced by InitialState, Transition.ToState, and RequestStateTransition.

EntryActions: {AnimationDirective}--

Directives run when this state is entered.

ExitActions: {AnimationDirective}--

Directives run when this state is left.

Transitions: {TransitionRule}--

Rules evaluated each frame to determine when to leave this state.

ActiveLayers: {string}--

Layers set to their BaseWeight when this state is entered.

SuppressLayers: {string}--

Layers set to weight 0 when this state is entered.

}

Defines a state in the state machine. Produced by BehaviorBuilder:State():Done().

States with no Transitions are terminal states. The state machine stays in them until RequestStateTransition is called.

AnimationDirective​

</>
interface AnimationDirective {
Action: "PLAY" | "STOP" | "STOP_GROUP"--

The action to perform.

Target: string--

Animation name (for PLAY and STOP) or group name (for STOP_GROUP).

Immediate: boolean--

For STOP and STOP_GROUP: whether to stop without a fade-out.

}

A single action in a state entry or exit list.

TransitionRule​

</>
interface TransitionRule {
ToState: string--

The target state name. Must be a defined state in the behavior.

Condition: string--

The predicate name. Must be a registered predicate.

Priority: number--

Tiebreaker when multiple transitions are satisfied simultaneously. Higher wins.

}

A single transition definition within a state.

AnimationIntent​

</>
interface AnimationIntent {
CharacterId: string--

The character this intent is for.

AnimationName: string--

The resolved animation name.

Action: "PLAY" | "STOP"--

The requested action.

Timestamp: number--

Server time at which the intent was created (workspace:GetServerTimeNow()).

}

Represents an animation play/stop intent in the MotixNet system.

ControllerConfig​

</>
interface ControllerConfig {
CharacterId: string--

Unique identifier for this character instance.

Animator: Animator?--

The Roblox Animator instance. Passed only on the client. Ignored on server.

IsOwningClient: boolean--

Whether this client owns the character. Controls MotixNet intent sending.

OwningPlayer: Player?--

The player who owns this character. Used by MotixNet for ownership validation.

LayerProfiles: {LayerProfile}--

Layer definitions for this controller.

States: {StateDefinition}--

State definitions for the state machine.

InitialState: string--

The state the machine begins in.

Predicates: {[string]: () → boolean}--

Named boolean predicate functions for transition conditions.

}

Configuration table passed to AnimationController.new(). Typically produced by BuiltBehavior:CreateController().

Show raw api
{
    "functions": [],
    "properties": [],
    "types": [
        {
            "name": "AnimationConfig",
            "desc": "Defines a single animation. All fields are required unless marked optional.\nProduced by `BehaviorBuilder:Animation():Done()` and stored in `AnimationRegistry`.\n\nOnce registered, configs are frozen. Modifying them after `AnimationRegistry:Init()`\nhas no effect.",
            "fields": [
                {
                    "name": "Name",
                    "lua_type": "string",
                    "desc": "Unique animation identifier. Passed to `Controller:Play()` and `Controller:Stop()`."
                },
                {
                    "name": "AssetId",
                    "lua_type": "string",
                    "desc": "Roblox animation asset ID (`\"rbxassetid://...\"`)."
                },
                {
                    "name": "Layer",
                    "lua_type": "string",
                    "desc": "Layer this animation belongs to. Must match a registered `LayerProfile` name."
                },
                {
                    "name": "Group",
                    "lua_type": "string?",
                    "desc": "Exclusive group name. Only one animation per group may play at a time."
                },
                {
                    "name": "Priority",
                    "lua_type": "number",
                    "desc": "Conflict priority within the layer or group. Higher values win. Default: `0`."
                },
                {
                    "name": "Looped",
                    "lua_type": "boolean",
                    "desc": "Whether the animation loops. Default: `false`."
                },
                {
                    "name": "FadeInTime",
                    "lua_type": "number",
                    "desc": "Seconds for the animation to fade in when it starts playing. Default: `0.1`."
                },
                {
                    "name": "FadeOutTime",
                    "lua_type": "number",
                    "desc": "Seconds for the animation to fade out when it stops. Default: `0.1`."
                },
                {
                    "name": "Speed",
                    "lua_type": "number",
                    "desc": "Playback speed multiplier. Default: `1.0`."
                },
                {
                    "name": "Weight",
                    "lua_type": "number",
                    "desc": "Blend weight contribution within its layer. Range `(0, 1]`. Default: `1.0`."
                },
                {
                    "name": "CanInterrupt",
                    "lua_type": "boolean",
                    "desc": "Whether a lower-priority group member can replace this animation before it finishes. Default: `true`."
                },
                {
                    "name": "MinDuration",
                    "lua_type": "number?",
                    "desc": "Minimum seconds the animation must play before group conflict resolution can interrupt it."
                },
                {
                    "name": "Tags",
                    "lua_type": "{string}",
                    "desc": "Tag strings for batch operations via `Controller:PlayTag()`. Default: `{}`."
                },
                {
                    "name": "Additive",
                    "lua_type": "boolean",
                    "desc": "Whether the animation plays in additive blending mode. Default: `false`."
                },
                {
                    "name": "Metadata",
                    "lua_type": "{[string]: any}?",
                    "desc": "Arbitrary data stored with the config. Accessible from registry lookups."
                }
            ],
            "source": {
                "line": 36,
                "path": "docs/TypeDefinitions.lua"
            }
        },
        {
            "name": "LayerProfile",
            "desc": "Defines an animation layer. Layers control how animations blend and which animations can\ncoexist. Produced by `BehaviorBuilder:Layer():Done()`.",
            "fields": [
                {
                    "name": "Name",
                    "lua_type": "string",
                    "desc": "Unique layer identifier. Referenced by `AnimationConfig.Layer`, state `ActiveLayer`, and `SuppressLayer`."
                },
                {
                    "name": "Order",
                    "lua_type": "number",
                    "desc": "Integer blending order. Lower values are evaluated first. Must be unique per behavior."
                },
                {
                    "name": "BaseWeight",
                    "lua_type": "number",
                    "desc": "Default layer weight when the layer is active. Range `[0, 1]`. Default: `1.0`."
                },
                {
                    "name": "Additive",
                    "lua_type": "boolean",
                    "desc": "When true, this layer composes with lower-order layers rather than replacing them. Default: `false`."
                },
                {
                    "name": "Isolated",
                    "lua_type": "boolean",
                    "desc": "When true, this layer does not interact with other layers during blending. Default: `false`."
                },
                {
                    "name": "WeightLerpRate",
                    "lua_type": "number",
                    "desc": "Speed in units per second at which the layer weight interpolates toward its target. Use `math.huge` for instant snapping. Default: `8.0`."
                }
            ],
            "source": {
                "line": 50,
                "path": "docs/TypeDefinitions.lua"
            }
        },
        {
            "name": "StateDefinition",
            "desc": "Defines a state in the state machine. Produced by `BehaviorBuilder:State():Done()`.\n\nStates with no `Transitions` are terminal states. The state machine stays in them until\n`RequestStateTransition` is called.",
            "fields": [
                {
                    "name": "Name",
                    "lua_type": "string",
                    "desc": "Unique state name. Referenced by `InitialState`, `Transition.ToState`, and `RequestStateTransition`."
                },
                {
                    "name": "EntryActions",
                    "lua_type": "{AnimationDirective}",
                    "desc": "Directives run when this state is entered."
                },
                {
                    "name": "ExitActions",
                    "lua_type": "{AnimationDirective}",
                    "desc": "Directives run when this state is left."
                },
                {
                    "name": "Transitions",
                    "lua_type": "{TransitionRule}",
                    "desc": "Rules evaluated each frame to determine when to leave this state."
                },
                {
                    "name": "ActiveLayers",
                    "lua_type": "{string}",
                    "desc": "Layers set to their `BaseWeight` when this state is entered."
                },
                {
                    "name": "SuppressLayers",
                    "lua_type": "{string}",
                    "desc": "Layers set to weight `0` when this state is entered."
                }
            ],
            "source": {
                "line": 66,
                "path": "docs/TypeDefinitions.lua"
            }
        },
        {
            "name": "AnimationDirective",
            "desc": "A single action in a state entry or exit list.",
            "fields": [
                {
                    "name": "Action",
                    "lua_type": "\"PLAY\" | \"STOP\" | \"STOP_GROUP\"",
                    "desc": "The action to perform."
                },
                {
                    "name": "Target",
                    "lua_type": "string",
                    "desc": "Animation name (for PLAY and STOP) or group name (for STOP_GROUP)."
                },
                {
                    "name": "Immediate",
                    "lua_type": "boolean",
                    "desc": "For STOP and STOP_GROUP: whether to stop without a fade-out."
                }
            ],
            "source": {
                "line": 76,
                "path": "docs/TypeDefinitions.lua"
            }
        },
        {
            "name": "TransitionRule",
            "desc": "A single transition definition within a state.",
            "fields": [
                {
                    "name": "ToState",
                    "lua_type": "string",
                    "desc": "The target state name. Must be a defined state in the behavior."
                },
                {
                    "name": "Condition",
                    "lua_type": "string",
                    "desc": "The predicate name. Must be a registered predicate."
                },
                {
                    "name": "Priority",
                    "lua_type": "number",
                    "desc": "Tiebreaker when multiple transitions are satisfied simultaneously. Higher wins."
                }
            ],
            "source": {
                "line": 86,
                "path": "docs/TypeDefinitions.lua"
            }
        },
        {
            "name": "AnimationIntent",
            "desc": "Represents an animation play/stop intent in the MotixNet system.",
            "fields": [
                {
                    "name": "CharacterId",
                    "lua_type": "string",
                    "desc": "The character this intent is for."
                },
                {
                    "name": "AnimationName",
                    "lua_type": "string",
                    "desc": "The resolved animation name."
                },
                {
                    "name": "Action",
                    "lua_type": "\"PLAY\" | \"STOP\"",
                    "desc": "The requested action."
                },
                {
                    "name": "Timestamp",
                    "lua_type": "number",
                    "desc": "Server time at which the intent was created (`workspace:GetServerTimeNow()`)."
                }
            ],
            "source": {
                "line": 97,
                "path": "docs/TypeDefinitions.lua"
            }
        },
        {
            "name": "ControllerConfig",
            "desc": "Configuration table passed to `AnimationController.new()`. Typically produced by\n`BuiltBehavior:CreateController()`.",
            "fields": [
                {
                    "name": "CharacterId",
                    "lua_type": "string",
                    "desc": "Unique identifier for this character instance."
                },
                {
                    "name": "Animator",
                    "lua_type": "Animator?",
                    "desc": "The Roblox `Animator` instance. Passed only on the client. Ignored on server."
                },
                {
                    "name": "IsOwningClient",
                    "lua_type": "boolean",
                    "desc": "Whether this client owns the character. Controls MotixNet intent sending."
                },
                {
                    "name": "OwningPlayer",
                    "lua_type": "Player?",
                    "desc": "The player who owns this character. Used by MotixNet for ownership validation."
                },
                {
                    "name": "LayerProfiles",
                    "lua_type": "{LayerProfile}",
                    "desc": "Layer definitions for this controller."
                },
                {
                    "name": "States",
                    "lua_type": "{StateDefinition}",
                    "desc": "State definitions for the state machine."
                },
                {
                    "name": "InitialState",
                    "lua_type": "string",
                    "desc": "The state the machine begins in."
                },
                {
                    "name": "Predicates",
                    "lua_type": "{[string]: () -> boolean}",
                    "desc": "Named boolean predicate functions for transition conditions."
                }
            ],
            "source": {
                "line": 113,
                "path": "docs/TypeDefinitions.lua"
            }
        }
    ],
    "name": "TypeDefinitions",
    "desc": "Shared Luau type definitions used across Motix and MotixNet.\n\nThis page documents every field on the core data types. You do not import this module\ndirectly. It exists as an API reference for the types that flow through the system.",
    "source": {
        "line": 9,
        "path": "docs/TypeDefinitions.lua"
    }
}