Skip to main content

RoundManager

Orchestrates round lifecycles, phase transitions, and state management.

Types​

Events​

</>
interface Events {
OnPhaseChanged: (
oldPhase: Phase,
newPhase: Phase
)
OnPlayerAdded: (player: Player)
OnPlayerRemoving: (
player: Player,
state: PlayerRoundState? | nil
)
OnWinConditionMet: (outcome: WinOutcome)
OnRoundReset: ()
}

RoundConfig​

</>
interface RoundConfig {
Phases: {[string]: Phase}--

Table of phase definitions, keyed by name

InitialPhase: string--

Which key in Phases to enter on Start()

WinCondition: string | WinCondition--

A registered name or a raw WinCondition instance

ReconnectionPolicy: string | ReconnectionPolicy?--

Optional; a registered name or raw instance

Driver: RBXScriptSignal?--

Optional; overrides the default polling loop

UpdateInterval: number?--

Optional; seconds between ticks when no Driver is set (default 1)

AutoWirePlayers: boolean?--

Optional; if true, automatically connects to Players.PlayerAdded and Players.PlayerRemoving (default false)

StaleStateTimeout: number?--

Optional; seconds before a disconnected player's state is considered stale (default 30)

}

The configuration table passed to RoundKit.new().

Functions​

new​

</>
RoundManager.new(config: RoundConfig) → RoundManager

Constructs a new RoundManager.

Start​

</>
RoundManager:Start() → ()

Starts the manager loop and initializes the first phase

Pause​

</>
RoundManager:Pause() → ()

Stops the manager from updating.

Resume​

</>
RoundManager:Resume() → ()

Resumes the manager loop.

TransitionTo​

</>
RoundManager:TransitionTo(
phaseName: string,
force: boolean?--

Internal use only; forces the transition even if the target phase is not allowed (used by Reset())

) → boolean

Evaluates whetever the current phase can transition to the given phase Fires 'OnPhaseChanged' if the transition is successful.

Update​

</>
RoundManager:Update(dt: number) → ()

Updates the round manager state, evaluates the current phase state, if it should transition, the win condition and manages stale player states.

CheckWinCondition​

</>
RoundManager:CheckWinCondition() → WinOutcome?

Checks the win condition and fires the OnWinConditionMet event if it is met. Fires 'OnWinConditionMet' if the win condition is met.

BuildContext​

</>
RoundManager:BuildContext() → Context

Builds a new context for the current state of the round manager.

EvaluateWinCondition​

</>
RoundManager:EvaluateWinCondition() → WinOutcome?

Evaluates the win condition and returns the outcome.

ResolveAllowedTransitions​

</>
RoundManager:ResolveAllowedTransitions(
phase: Phase,
ctx: Context
) → {string}

Types

​

interface Phase {
Name: string--

The name of the phase

AllowedTransitions: {[string]} | (ctx: Context) → {[string]}--

A list of phase names that this phase can transition to, or a function that returns such a list

Duration: number?--

Optional; the duration of this phase in seconds (default nil, meaning no automatic transition)

CanTransitionTo: (
ctx: Context,
targetPhase: string
) → boolean?--

Optional; a function that determines if the round can transition to the target phase (default nil, meaning always true)

EvaluateWinCondition: boolean?--

Optional; if true, the win condition will be evaluated at 'EvaluateWinConditionInterval' (defaults false)

EvaluateWinConditionInterval: number?--

Optional; the interval in seconds at which to evaluate the win condition (default 1)

OnEnter: (ctx: Context) → ()?--

Optional; a function that is called when the round enters this phase

OnExit: (ctx: Context) → ()?--

Optional; a function that is called when the round exits this phase

OnUpdate: (
ctx: Context,
dt: number
) → ()?--

Optional; a function that is called every update tick while in this phase

}

Resolves the allowed transitions for the given phase.

OnPlayerAdded​

</>
RoundManager:OnPlayerAdded(player: Player) → ()

Detects when a player is added to the game. If the player already has round state (reconnection), triggers the reconnection policy. Otherwise, fires the 'OnPlayerJoined' event for the developer to handle.

CAUTION

You must connect this to Players.PlayerAdded (or similar) or set AutoWirePlayers to true for it to work.

OnPlayerJoined​

</>
RoundManager:OnPlayerJoined(callback: (
context: Context,
player: Player
) → ()) → ()

Connects a callback to the OnPlayerJoined event.

CAUTION

You must connect :OnPlayerAdded to Players.PlayerAdded (or similar) or set AutoWirePlayers to true for it to work.

OnPlayerRemoving​

</>
RoundManager:OnPlayerRemoving(player: Player) → ()

Detects when a player is leaving the game. If the player has a round state, marks them as disconnected Fires the 'OnPlayerLeft' event for the developer to handle.

CAUTION

You must connect this to Players.PlayerRemoving (or similar) or set AutoWirePlayers to true for it to work.

CAUTION

The player round state is not removed from the registry, it is only marked as disconnected. This allows for reconnection policies to handle the player if they rejoin. Player's round state will be removed from the registry if it is considered stale (disconnected for longer than StaleStateTimeout seconds).

ClearRoundState​

</>
RoundManager:ClearRoundState() → ()

Clears the round state, fires the OnRoundReset event. Fires 'OnRoundReset' when the round state is cleared.

Reset​

</>
RoundManager:Reset() → ()

Resets the round state and forcefully transitions to the initial phase.

Destroy​

</>
RoundManager:Destroy() → ()

Destroys the round manager, clears the round state, disconnects all connections, and destroys the event bus.

Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Constructs a new RoundManager.",
            "params": [
                {
                    "name": "config",
                    "desc": "",
                    "lua_type": "RoundConfig"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "RoundManager"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 74,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "Start",
            "desc": "Starts the manager loop and initializes the first phase",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 98,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "Pause",
            "desc": "Stops the manager from updating.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 148,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "Resume",
            "desc": "Resumes the manager loop.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 153,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "TransitionTo",
            "desc": "Evaluates whetever the current phase can transition to the given phase\nFires 'OnPhaseChanged' if the transition is successful.",
            "params": [
                {
                    "name": "phaseName",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "force",
                    "desc": "Internal use only; forces the transition even if the target phase is not allowed (used by Reset())",
                    "lua_type": "boolean?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 166,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "Update",
            "desc": "Updates the round manager state, evaluates the current phase state, if it should transition, the win condition and manages stale player states.",
            "params": [
                {
                    "name": "dt",
                    "desc": "",
                    "lua_type": "number"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 215,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "CheckWinCondition",
            "desc": "Checks the win condition and fires the OnWinConditionMet event if it is met.\nFires 'OnWinConditionMet' if the win condition is met.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "WinOutcome?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 284,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "BuildContext",
            "desc": "Builds a new context for the current state of the round manager.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Context"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 299,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "EvaluateWinCondition",
            "desc": "Evaluates the win condition and returns the outcome.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "WinOutcome?"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 309,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "ResolveAllowedTransitions",
            "desc": "Resolves the allowed transitions for the given phase.",
            "params": [
                {
                    "name": "phase",
                    "desc": "",
                    "lua_type": "Phase"
                },
                {
                    "name": "ctx",
                    "desc": "",
                    "lua_type": "Context"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{string}"
                }
            ],
            "function_type": "method",
            "source": {
                "line": 322,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "OnPlayerAdded",
            "desc": "Detects when a player is added to the game.\nIf the player already has round state (reconnection), triggers the reconnection policy.\nOtherwise, fires the 'OnPlayerJoined' event for the developer to handle.\n:::caution\nYou must connect this to Players.PlayerAdded (or similar) or set AutoWirePlayers to true for it to work.\n:::",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 345,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "OnPlayerJoined",
            "desc": "Connects a callback to the OnPlayerJoined event.\n:::caution\nYou must connect :OnPlayerAdded to Players.PlayerAdded (or similar) or set AutoWirePlayers to true for it to work.\n:::",
            "params": [
                {
                    "name": "callback",
                    "desc": "",
                    "lua_type": "(context: Context, player: Player) -> ()"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 366,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "OnPlayerRemoving",
            "desc": "Detects when a player is leaving the game.\nIf the player has a round state, marks them as disconnected\nFires the 'OnPlayerLeft' event for the developer to handle.\n:::caution\nYou must connect this to Players.PlayerRemoving (or similar) or set AutoWirePlayers to true for it to work.\n:::\n:::caution\nThe player round state is not removed from the registry, it is only marked as disconnected. This allows for reconnection policies to handle the player if they rejoin.\nPlayer's round state will be removed from the registry if it is considered stale (disconnected for longer than StaleStateTimeout seconds).\n:::",
            "params": [
                {
                    "name": "player",
                    "desc": "",
                    "lua_type": "Player"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 381,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "ClearRoundState",
            "desc": "Clears the round state, fires the OnRoundReset event.\nFires 'OnRoundReset' when the round state is cleared.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 392,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "Reset",
            "desc": "Resets the round state and forcefully transitions to the initial phase.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 399,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "Destroy",
            "desc": "Destroys the round manager, clears the round state, disconnects all connections, and destroys the event bus.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 405,
                "path": "src/Classes/RoundManager.lua"
            }
        }
    ],
    "properties": [],
    "types": [
        {
            "name": "Events",
            "desc": "",
            "fields": [
                {
                    "name": "OnPhaseChanged",
                    "lua_type": "(oldPhase: Phase, newPhase: Phase)",
                    "desc": ""
                },
                {
                    "name": "OnPlayerAdded",
                    "lua_type": "(player: Player)",
                    "desc": ""
                },
                {
                    "name": "OnPlayerRemoving",
                    "lua_type": "(player: Player, state: PlayerRoundState? | nil)",
                    "desc": ""
                },
                {
                    "name": "OnWinConditionMet",
                    "lua_type": "(outcome: WinOutcome)",
                    "desc": ""
                },
                {
                    "name": "OnRoundReset",
                    "lua_type": "()",
                    "desc": ""
                }
            ],
            "source": {
                "line": 10,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "RoundConfig",
            "desc": "The configuration table passed to `RoundKit.new()`.",
            "fields": [
                {
                    "name": "Phases",
                    "lua_type": "{[string]: Phase}",
                    "desc": "Table of phase definitions, keyed by name"
                },
                {
                    "name": "InitialPhase",
                    "lua_type": "string",
                    "desc": "Which key in Phases to enter on Start()"
                },
                {
                    "name": "WinCondition",
                    "lua_type": "string | WinCondition",
                    "desc": "A registered name or a raw WinCondition instance"
                },
                {
                    "name": "ReconnectionPolicy",
                    "lua_type": "string | ReconnectionPolicy?",
                    "desc": "Optional; a registered name or raw instance"
                },
                {
                    "name": "Driver",
                    "lua_type": "RBXScriptSignal?",
                    "desc": "Optional; overrides the default polling loop"
                },
                {
                    "name": "UpdateInterval",
                    "lua_type": "number?",
                    "desc": "Optional; seconds between ticks when no Driver is set (default 1)"
                },
                {
                    "name": "AutoWirePlayers",
                    "lua_type": "boolean?",
                    "desc": "Optional; if true, automatically connects to Players.PlayerAdded and Players.PlayerRemoving (default false)"
                },
                {
                    "name": "StaleStateTimeout",
                    "lua_type": "number?",
                    "desc": "Optional; seconds before a disconnected player's state is considered stale (default 30)"
                }
            ],
            "source": {
                "line": 25,
                "path": "src/Classes/RoundManager.lua"
            }
        },
        {
            "name": "Phase",
            "desc": "",
            "fields": [
                {
                    "name": "Name",
                    "lua_type": "string",
                    "desc": "The name of the phase"
                },
                {
                    "name": "AllowedTransitions",
                    "lua_type": "{[string]} | (ctx: Context) -> {[string]}",
                    "desc": "A list of phase names that this phase can transition to, or a function that returns such a list"
                },
                {
                    "name": "Duration",
                    "lua_type": "number?",
                    "desc": "Optional; the duration of this phase in seconds (default nil, meaning no automatic transition)"
                },
                {
                    "name": "CanTransitionTo",
                    "lua_type": "(ctx: Context, targetPhase: string) -> boolean?",
                    "desc": "Optional; a function that determines if the round can transition to the target phase (default nil, meaning always true)"
                },
                {
                    "name": "EvaluateWinCondition",
                    "lua_type": "boolean?",
                    "desc": "Optional; if true, the win condition will be evaluated at 'EvaluateWinConditionInterval' (defaults false)"
                },
                {
                    "name": "EvaluateWinConditionInterval",
                    "lua_type": "number?",
                    "desc": "Optional; the interval in seconds at which to evaluate the win condition (default 1)"
                },
                {
                    "name": "OnEnter",
                    "lua_type": "(ctx: Context) -> ()?",
                    "desc": "Optional; a function that is called when the round enters this phase"
                },
                {
                    "name": "OnExit",
                    "lua_type": "(ctx: Context) -> ()?",
                    "desc": "Optional; a function that is called when the round exits this phase"
                },
                {
                    "name": "OnUpdate",
                    "lua_type": "(ctx: Context, dt: number) -> ()?",
                    "desc": "Optional; a function that is called every update tick while in this phase"
                }
            ],
            "source": {
                "line": 39,
                "path": "src/Classes/RoundManager.lua"
            }
        }
    ],
    "name": "RoundManager",
    "desc": "Orchestrates round lifecycles, phase transitions, and state management.",
    "source": {
        "line": 67,
        "path": "src/Classes/RoundManager.lua"
    }
}