API

Warning

Parameter limitations apply to StateData.Value and client synchronization

Error

DO NOT YIELD in callback functions (OnEdited, OnRemoved, OnCalled). Yielding will cause state desync.

Notice

StateService will yield on require() if RemoteEvents aren't immediately available on client.

Common Types

Instance

Instance: Instance

StateName

StateName: string

StateTemplate

StateTemplate: any

StateCallbacks

StateCallbacks: {
    OnRemoved: ((Value: any, RemovedByLifespan: boolean) -> ())?,
    OnEdited: ((OldValue: any, NewValue: any) -> ())?,
    OnCalled: ((Caller: string, ...any) -> ())?
}

AuthorizationRule

AuthorizationRule: {
    ClientReadable: boolean?,
    AuthorizedPlayers: {Player}?
}

StateValue

StateValue: any

Guarantees

When client connects, all authorized states are immediately accessible via GetState().

StateService (Server)

StateService:AddState

StateService:AddState(
    Instance: Instance,
    StateName: string,
    Template: any?,
    Lifespan: number?,
    Callbacks: StateCallbacks?,
    Authorization: AuthorizationRule?
) -> boolean

StateService:EditState

StateService:EditState(
    Instance: Instance,
    StateName: string,
    NewValue: any,
    Override: boolean?
) -> boolean

StateService:RemoveState

StateService:RemoveState(
    Instance: Instance,
    StateName: string
) -> boolean

StateService (Client)

StateService:GetState

StateService:GetState(
    Instance: Instance,
    StateName: string
) -> StateData?

StateService:HasState

StateService:HasState(
    Instance: Instance,
    StateName: string
) -> boolean

StateService:GetAllStates

StateService:GetAllStates(
    Instance: Instance
) -> {[string]: StateData}

StateData Structure

StateData.Value

print(StateData.Value.Health) -- Access state data
print(StateData.CreatedAt) -- Timestamp when created
print(StateData.ExpiresAt) -- When it expires (if has lifespan)

Real-Time Updates (Client)

State Changed Events

if StateService.RemoteEvents and StateService.RemoteEvents.StateChanged then
    StateService.RemoteEvents.StateChanged.OnClientEvent:Connect(
        function(Instance: Instance, StateName: string, NewStateData: StateData)
            print("State updated:", StateName)
            print("New value:", NewStateData.Value)
        end
    )
end

State Removed Events

if StateService.RemoteEvents and StateService.RemoteEvents.StateRemoved then
    StateService.RemoteEvents.StateRemoved.OnClientEvent:Connect(
        function(Instance: Instance, StateName: string, ExpiredByLifespan: boolean)
            print("State removed:", StateName, "Expired:", ExpiredByLifespan)
        end
    )
end

Advanced Server Methods

StateService:SetStateCallbacks

StateService:SetStateCallbacks(
    Instance: Instance,
    StateName: string,
    Callbacks: StateCallbacks
) -> boolean

StateService:SetStateAuthorization

StateService:SetStateAuthorization(
    Instance: Instance,
    StateName: string,
    Authorization: AuthorizationRule
) -> boolean

StateService:ClearAllStates

StateService:ClearAllStates(
    Instance: Instance
) -> number

Utility Methods

StateService:GetInstanceCount

StateService:GetInstanceCount() -> number -- Server only

StateService:GetTotalStateCount

StateService:GetTotalStateCount() -> number -- Server only

---