Player Readiness Component
UNihiloPlayerReadinessComponent tracks whether a set of participants
have signaled ready and fires events when the threshold is met — optionally after a countdown.
It is designed to live on a server-owned actor such as AGameState,
and all mutations are server-authoritative with results replicated to clients via multicast.
A common use case is a pre-match lobby: register all players as they join, wait for each to call
SetReady, then use OnAllPlayersReadyExecute
to trigger the match start. The countdown gives players a window to back out before it's final.
How It Works
Participants are tracked by int32 player ID — the value returned by
APlayerState::GetPlayerId. The component maintains two replicated lists:
a RegisteredParticipants list of everyone eligible to vote, and a
ReadyParticipants list of those who have. Only registered participants
can affect state — calls to SetReady for unregistered IDs are
silently ignored.
After every state change, the component internally calls CheckReadiness.
This compares the ready count against GetRequiredCount, which defaults
to the total registered count. When the threshold is met, one of two paths is taken:
- If CountdownSeconds is 0, OnAllPlayersReadyExecute fires immediately.
- If CountdownSeconds is greater than 0, OnAllPlayersReadyCountdownStart fires first. When the timer expires, readiness is re-validated before executing — so a player leaving mid-countdown will cancel it unless ForceReady was used.
If a participant un-readies or leaves while a countdown is active, it is automatically cancelled and
OnAllPlayersReadyCountdownCancelled is broadcast. The component
resets its internal fired state and waits for the threshold to be met again.
Setup
Two properties control automatic population at startup:
bShouldRegisterAllPlayers — when enabled, RegisterAllPlayers
is called on BeginPlay, registering every player currently in the
AGameState player array. This is useful for scenarios where all players
are already in the world when the component comes online.
bAutoUpdatePlayers — when enabled, the component binds to
UNihiloPlayerSubsystem and automatically calls
RegisterParticipant and UnregisterParticipant
as players join and leave during the session. When a player leaves mid-ready, their ID is removed from
both lists and readiness is re-evaluated — potentially cancelling an active countdown.
These two options can be used independently or together. For a lobby that starts empty and fills up,
bAutoUpdatePlayers alone is sufficient. For a scenario where all players
are loaded before the component activates, bShouldRegisterAllPlayers handles
the initial registration.
Customizing the Threshold
By default, GetRequiredCount returns the total number of registered
participants — meaning everyone must be ready. This is a BlueprintNativeEvent,
so it can be overridden in either Blueprint or C++ to implement any threshold logic you need.
Force Ready
ForceReady bypasses the registered/ready threshold entirely and
drives the component into the all-ready state immediately. This is useful for server-side overrides —
for example, a host skipping the lobby after a timeout, or an admin forcing a match to start regardless
of player count.
When forced, the countdown (if configured) still runs, but the re-validation check at the end of the
countdown is also bypassed — the execute event will fire even if players have since left.
API Reference
Participant Management
| Function | Description |
|---|---|
| RegisterParticipant | Adds a player ID to the registered list. Server only. |
| UnregisterParticipant | Removes a player ID from both lists and re-evaluates readiness. Server only. |
| RegisterAllPlayers | Registers every player currently in the AGameState player array. Server only. |
| ResetReadiness | Clears both lists and resets all internal state. Broadcasts OnReadyPlayersChanged. Server only. |
| SetReady | Marks a participant as ready or not ready, then checks the threshold. Unregistered IDs are ignored. Server only. |
| ForceReady | Forces the all-ready path regardless of current state. Server only. |
| CancelCountdown | Clears the countdown timer and broadcasts OnAllPlayersReadyCountdownCancelled. |
Queries
| Function | Description |
|---|---|
| IsParticipantReady | Returns whether the given ID is in the ready list. |
| AreAllReady | Returns true if the ready count meets GetRequiredCount. Always false with no registered participants. |
| GetReadyCount | Returns the number of currently ready participants. |
| GetTotalCount | Returns the total number of registered participants. |
| GetRequiredCount | Overridable. Returns the ready threshold. Defaults to GetTotalCount. |
Events
All events are multicast and fire on both server and clients.
| Delegate | Description |
|---|---|
| OnReadyPlayersChanged | Fires on any state change. Broadcasts the ready ID list, ready count, required count, and AreAllReady. |
| OnAllPlayersReadyCountdownStart | Fires when the threshold is met and a countdown begins. Broadcasts CountdownSeconds for UI. |
| OnAllPlayersReadyCountdownCancelled | Fires when an active countdown is cancelled due to a participant leaving or un-readying. |
| OnAllPlayersReadyExecute | Fires when the threshold is met and the countdown (if any) has elapsed. Bind your match start or transition logic here. |