Skip to main content

StateManager

This item only works when running on the server. Server

Centralized state management system for characters. Manages character states with values, durations, and change listeners, providing a unified interface for state tracking across the game.

Types​

StateTypes​

</>
type StateTypes = boolean | {any} | number | string | nil

State​

</>
type State = {
value: StateTypes,
duration: number?,
isOverwritable: boolean?,
isUneditable: boolean?
}

StateManagerType​

</>
interface StateManagerType {
states: {[string]: {[string]: {[string]: State}}}
addEntity: (
self: StateManagerType,
entity: Model,
player: Player? | nil
) → ()
removeEntity: (
self: StateManagerType,
entityId: string
) → ()
addState: (
self: StateManagerType,
entityId: string,
stateName: string,
value: StateTypes,
duration: number?
) → ()
checkState: (
self: StateManagerType,
entityId: string,
stateName: string
) → StateTypes?
checkStateDuration:: (
self: StateManagerType,
entityId: string,
stateName: string
) → number?
changeState: (
self: StateManagerType,
entityId: string,
stateName: string,
newValue: StateTypes,
newDuration: number?
) → ()
startStateUpdateLoop: (self: StateManagerType) → ()
}

Defines the structure and methods available to the StateManager singleton.

Functions​

listenToState​

</>
StateManager.listenToState(
entityId: string?,--

Optional filter for a specific entity.

stateName: string?,--

Optional filter for a specific state.

callback: (
string,
string,
StateTypes,
StateTypes?
) → (),--

Callback function.

priority: number?--

Execution order priority (lower runs first).

) → () → ()--

A function that, when called, disconnects the listener.

Registers a callback to fire when a specific state changes. Supports priority and filtering by ID.

addEntity​

</>
StateManager:addEntity(
entity: Model,--

The physical instance of the entity.

player: Player?--

Optional player reference for state replication.

) → ()

Registers a new entity (Character or Object) into the state system.

removeEntity​

</>
StateManager:removeEntity(
entityId: string--

The name/ID of the entity to remove.

) → ()

Cleans up all state data and listeners associated with an entity ID.

addState​

</>
StateManager:addState(
entityId: string,--

Target entity ID.

stateName: string,--

Name of the state to add/update.

value: StateTypes,--

The value to store.

duration: number?,--

Time in seconds before the state expires.

isUnoverwritable: boolean?--

If true, current value cannot be overwritten until expiration.

) → ()

Creates or updates a state for a specific entity. Includes duration and overwrite protection.

checkState​

</>
StateManager:checkState(
entityId: string,--

Target entity ID.

stateName: string--

State name to query.

) → StateTypes?--

The value of the state, if it exists.

Retrieves the current value of a specific state.

checkStateDuration​

</>
StateManager:checkStateDuration(
entityId: string,--

Target entity ID.

stateName: string--

State name to query.

) → number?--

Seconds remaining, or nil if no duration exists.

Returns the remaining time for a state before it expires.

changeState​

</>
StateManager:changeState(
entityId: string,--

Target entity ID.

stateName: string,--

State name to modify.

newValue: StateTypes,--

New value to set.

newDuration: number?--

Optional new duration to set.

) → ()

Updates an existing state's value. Fails if the state is marked as uneditable.

StartStateUpdateLoop​

</>
StateManager:StartStateUpdateLoop() → ()

Starts a loop that periodically checks for and removes expired states.

DANGER

This function should only be called once, multiple calls will result in errors and degraded performance.

StartDebugReplicationLoop​

</>
StateManager:StartDebugReplicationLoop() → ()

Creates physical folders and values in PlayerGui for the iris debug menu to visualize states in real-time.

DANGER

This function should only be called once, multiple calls will result in errors and degraded performance.

Show raw api
{
    "functions": [
        {
            "name": "addEntity",
            "desc": "Registers a new entity (Character or Object) into the state system.",
            "params": [
                {
                    "name": "entity",
                    "desc": "The physical instance of the entity.",
                    "lua_type": "Model"
                },
                {
                    "name": "player",
                    "desc": "Optional player reference for state replication.",
                    "lua_type": "Player?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 189,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "removeEntity",
            "desc": "Cleans up all state data and listeners associated with an entity ID.",
            "params": [
                {
                    "name": "entityId",
                    "desc": "The name/ID of the entity to remove.",
                    "lua_type": "string"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 204,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "addState",
            "desc": "Creates or updates a state for a specific entity. Includes duration and overwrite protection.",
            "params": [
                {
                    "name": "entityId",
                    "desc": "Target entity ID.",
                    "lua_type": "string"
                },
                {
                    "name": "stateName",
                    "desc": "Name of the state to add/update.",
                    "lua_type": "string"
                },
                {
                    "name": "value",
                    "desc": "The value to store.",
                    "lua_type": "StateTypes"
                },
                {
                    "name": "duration",
                    "desc": "Time in seconds before the state expires.",
                    "lua_type": "number?"
                },
                {
                    "name": "isUnoverwritable",
                    "desc": "If true, current value cannot be overwritten until expiration.",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 228,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "checkState",
            "desc": "Retrieves the current value of a specific state.",
            "params": [
                {
                    "name": "entityId",
                    "desc": "Target entity ID.",
                    "lua_type": "string"
                },
                {
                    "name": "stateName",
                    "desc": "State name to query.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "The value of the state, if it exists.",
                    "lua_type": "StateTypes?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 270,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "checkStateDuration",
            "desc": "Returns the remaining time for a state before it expires.",
            "params": [
                {
                    "name": "entityId",
                    "desc": "Target entity ID.",
                    "lua_type": "string"
                },
                {
                    "name": "stateName",
                    "desc": "State name to query.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "Seconds remaining, or nil if no duration exists.",
                    "lua_type": "number?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 292,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "changeState",
            "desc": "Updates an existing state's value. Fails if the state is marked as uneditable.",
            "params": [
                {
                    "name": "entityId",
                    "desc": "Target entity ID.",
                    "lua_type": "string"
                },
                {
                    "name": "stateName",
                    "desc": "State name to modify.",
                    "lua_type": "string"
                },
                {
                    "name": "newValue",
                    "desc": "New value to set.",
                    "lua_type": "StateTypes"
                },
                {
                    "name": "newDuration",
                    "desc": "Optional new duration to set.",
                    "lua_type": "number?"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 316,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "StartStateUpdateLoop",
            "desc": "Starts a loop that periodically checks for and removes expired states.\n\n:::danger\nThis function should only be called once, multiple calls will result in errors and degraded performance.\n:::",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 343,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "StartDebugReplicationLoop",
            "desc": "Creates physical folders and values in PlayerGui for the iris debug menu to visualize states in real-time.\n\n:::danger\nThis function should only be called once, multiple calls will result in errors and degraded performance.\n:::",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 369,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "listenToState",
            "desc": "Registers a callback to fire when a specific state changes. Supports priority and filtering by ID.",
            "params": [
                {
                    "name": "entityId",
                    "desc": "Optional filter for a specific entity.",
                    "lua_type": "string?"
                },
                {
                    "name": "stateName",
                    "desc": "Optional filter for a specific state.",
                    "lua_type": "string?"
                },
                {
                    "name": "callback",
                    "desc": "Callback function.",
                    "lua_type": "(string, string, StateTypes, StateTypes?) -> ()"
                },
                {
                    "name": "priority",
                    "desc": "Execution order priority (lower runs first).",
                    "lua_type": "number?"
                }
            ],
            "returns": [
                {
                    "desc": "A function that, when called, disconnects the listener.",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 430,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "StateTypes",
            "desc": "",
            "lua_type": "boolean | { any } | number | string | nil",
            "source": {
                "line": 25,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "State",
            "desc": "",
            "lua_type": "{ value: StateTypes, duration: number?, isOverwritable: boolean?, isUneditable: boolean? }",
            "source": {
                "line": 31,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        },
        {
            "name": "StateManagerType",
            "desc": "Defines the structure and methods available to the StateManager singleton.",
            "fields": [
                {
                    "name": "states",
                    "lua_type": "{[string]: { [string]: { [string]: State } }",
                    "desc": ""
                },
                {
                    "name": "addEntity",
                    "lua_type": "(self: StateManagerType, entity: Model, player: Player? | nil) -> ()",
                    "desc": ""
                },
                {
                    "name": "removeEntity",
                    "lua_type": "(self: StateManagerType, entityId: string) -> ()",
                    "desc": ""
                },
                {
                    "name": "addState",
                    "lua_type": "(self: StateManagerType, entityId: string, stateName: string, value: StateTypes, duration: number?) -> ()",
                    "desc": ""
                },
                {
                    "name": "checkState",
                    "lua_type": "(self: StateManagerType, entityId: string, stateName: string) -> StateTypes?",
                    "desc": ""
                },
                {
                    "name": "checkStateDuration:",
                    "lua_type": "(self: StateManagerType, entityId: string, stateName: string) -> number?",
                    "desc": ""
                },
                {
                    "name": "changeState",
                    "lua_type": "(self: StateManagerType, entityId: string, stateName: string, newValue: StateTypes, newDuration: number?) -> ()",
                    "desc": ""
                },
                {
                    "name": "startStateUpdateLoop",
                    "lua_type": "(self: StateManagerType) -> ()",
                    "desc": ""
                }
            ],
            "source": {
                "line": 52,
                "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
            }
        }
    ],
    "name": "StateManager",
    "desc": "Centralized state management system for characters. Manages character states with values, durations, and change listeners, providing a unified interface for state tracking across the game.",
    "realm": [
        "Server"
    ],
    "source": {
        "line": 9,
        "path": "global/ServerStorage/Scripts/Modules/StateManager.luau"
    }
}