APlayerState

class Engine Blueprint Since 4.0

Inherits: UObjectBase › UObjectBaseUtility › UObject › AActor › AInfo › APlayerState

#include "GameFramework/PlayerState.h"

Description

Created for every player on a server (or in a standalone game) and replicated to all clients. Stores network-relevant player data such as name, score, ping, spectator status, and a reference to the controlled pawn.

Caveats & Gotchas

• PlayerStates are always relevant by default and replicate to every client. In high player-count games, set bShouldUpdateReplicatedPing to false on states where ping display is not needed to reduce network overhead.
• GetOwningController() returns null on clients for remote players — only the local player's PlayerState has a valid owning controller on the client.
• APlayerState persists across seamless travel. Override CopyProperties() to carry custom subclass data across level transitions.

Example

Access PlayerState from a Pawn C++

APlayerState* PS = GetPlayerState();
if (PS)
{
	FString Name = PS->GetPlayerName();
	float Score = PS->GetScore();
}

Functions (54)

Lifecycle 8 Networking 16 Identity 3 Messaging 1 Player Info 10 PlayerState 1 State 15

Lifecycle

8 ▼

Access	Type	Name	Description
public	function	APlayerState::Destroyed	Called when this PlayerState is destroyed.
public	function	APlayerState::OnDeactivated	Called on the server when the owning player disconnects.
public	function	APlayerState::OnReactivated	Called on the server when a previously disconnected player reconnects and their inactive PlayerState is restored to the active players array.
public	function	APlayerState::PostInitializeComponents	Called after all components have been initialized.
public	function	APlayerState::Reset	Resets the player state to its default values.
public	function	APlayerState::DispatchCopyProperties	Calls the internal CopyProperties method and then fires the Blueprint-implementable ReceiveCopyProperties event, used during seamless travel to propagate state to the new PlayerState.
public	function	APlayerState::DispatchOverrideWith	Calls the internal OverrideWith method and then fires the Blueprint-implementable ReceiveOverrideWith event, allowing both C++ and Blueprint subclasses to respond when a saved PlayerState overrides this one.
public	function	APlayerState::Duplicate	Creates a copy of this PlayerState for storage in the GameMode's InactivePlayerArray when a player disconnects.

Networking

16 ▼

Access	Type	Name	Description
public	function	APlayerState::BP_GetUniqueId	Returns the online subsystem unique ID for this player.
public	function	APlayerState::ClientInitialize	Called by the owning Controller on the client (or server in standalone) when the PlayerState is initially replicated and the controller links to it.
public	function	APlayerState::GetCompressedPing	Returns the replicated compressed ping value, where the actual ping in milliseconds equals CompressedPing * 4.
public	function	APlayerState::GetLifetimeReplicatedProps	Registers which properties are replicated and their replication conditions.
public	function	APlayerState::GetPingInMilliseconds	Returns the player's ping in milliseconds.
public	function	APlayerState::OnRep_bIsInactive	Replication notification called on clients when the bIsInactive flag changes.
public	function	APlayerState::OnRep_PlayerId	Replication notification called on clients when the PlayerId property is first replicated or changes.
public	function	APlayerState::OnRep_PlayerName	Replication notification called on clients when the PlayerNamePrivate property is updated from the server.
public	function	APlayerState::OnRep_Score	Replication notification called on clients when the Score property changes on the server.
public	function	APlayerState::OnRep_UniqueId	Replication notification called on clients when the UniqueId (FUniqueNetIdRepl) is first replicated.
public	function	APlayerState::RecalculateAvgPing	Computes the rolling average ping from the accumulated bucket data and writes it to ExactPing and (if bShouldUpdateReplicatedPing is true) CompressedPing.
public	function	APlayerState::RegisterPlayerWithSession	Registers this player with the online subsystem session identified by SessionName, allowing the platform to track the player's presence and enforce session membership.
public	function	APlayerState::SeamlessTravelTo	Called during seamless travel to copy persistent properties from this (old) PlayerState to the newly created one in the destination level.
public	function	APlayerState::SetCompressedPing	Sets the replicated compressed ping value directly.
public	function	APlayerState::UnregisterPlayerWithSession	Removes this player from the current online session via the online subsystem.
public	function	APlayerState::UpdatePing	Receives a new ping measurement from the net driver and accumulates it into the rolling ping bucket for averaging.

Identity

3 ▼

Access	Type	Name	Description
public	function	APlayerState::GetUniqueId	Returns a const reference to the player's online unique ID, which is consistent across all clients and servers when the player is logged in to an online subsystem.
public	function	APlayerState::SetUniqueId	Associates an online unique ID with this PlayerState and calls OnSetUniqueId to allow subclasses and the engine to react to the change.
public	function	APlayerState::OnSetUniqueId	Called on both server and client after UniqueId has been modified.

Messaging

1 ▼

Access	Type	Name	Description
public	function	APlayerState::ShouldBroadCastWelcomeMessage	Returns true if the engine should broadcast a welcome or farewell message for this player.

Player Info

10 ▼

Access	Type	Name	Description
public	function	APlayerState::GetHumanReadableName	Returns the player's name as a human-readable string.
public	function	APlayerState::GetOwningController	Returns the AI or player controller that created this player state.
public	function	APlayerState::GetPlayerController	Returns the player controller that created this player state, or null for remote clients.
public	function	APlayerState::GetPlayerName	Returns the current player name.
public	function	APlayerState::SetPlayerName	Sets the player's name and triggers replication to all clients, then broadcasts the name-change message using EngineMessageClass.
public	function	APlayerState::GetOldPlayerName	Returns the player's previous name, saved before the most recent name change.
public	function	APlayerState::IsOnlyASpectator	Returns true if this player can only ever be a spectator and is permanently barred from entering the game as a playing participant.
public	function	APlayerState::GetPlayerNameCustom	Extension point for returning a custom player name from a source other than the replicated PlayerNamePrivate field.
public	function	APlayerState::SetOldPlayerName	Stores a string as the player's previous name for later retrieval by GetOldPlayerName.
public	function	APlayerState::SetPlayerNameInternal	Sets the player name directly without triggering network replication callbacks or broadcasting a name-change message.

PlayerState

1 ▼

Access	Type	Name	Description
public	function	APlayerState::GetPawn	Returns the pawn currently associated with this PlayerState, or null if the player is not possessing a pawn.

State

15 ▼

Access	Type	Name	Description
public	function	APlayerState::GetPlayerId	Returns the player's unique numeric ID assigned by the server.
public	function	APlayerState::GetScore	Returns the player's current replicated score value.
public	function	APlayerState::IsABot	Returns whether this PlayerState belongs to an AI-controlled bot rather than a human player.
public	function	APlayerState::IsSpectator	Returns whether this player is currently spectating rather than actively playing.
public	function	APlayerState::SetIsSpectator	Sets the spectator flag on the PlayerState and replicates the change to clients.
public	function	APlayerState::SetScore	Sets the player's score and triggers replication to all clients via OnRep_Score.
public	function	APlayerState::GetStartTime	Returns the game time in seconds at which this player joined the session.
public	function	APlayerState::IsFromPreviousLevel	Returns the literal value of the bFromPreviousLevel flag, indicating whether this PlayerState was carried over from a previous level rather than freshly created.
public	function	APlayerState::IsInactive	Returns whether this PlayerState came from the GameMode's InactivePlayerArray, meaning the player has disconnected and the state is being preserved for a potential reconnect.
public	function	APlayerState::SetIsABot	Sets the bot flag on the PlayerState and replicates it to clients.
public	function	APlayerState::SetIsFromPreviousLevel	Sets the bFromPreviousLevel flag without triggering replication side effects.
public	function	APlayerState::SetIsOnlyASpectator	Sets the permanent spectator-only flag, indicating this player can never transition to an active playing role in the session.
public	function	APlayerState::SetPlayerId	Assigns the player's session-local numeric ID and triggers replication.
public	function	APlayerState::SetStartTime	Overrides the StartTime property directly.
public	function	APlayerState::SetIsInactive	Sets the inactive flag on the PlayerState and replicates it via OnRep_bIsInactive.

Properties

Access	Type	Name	Description
public	property	APlayerState::EngineMessageClass	The ULocalMessage subclass used to broadcast game-agnostic messages such as player-entered and player-left notifications.
public	property	APlayerState::OnPawnSet	Multicast delegate broadcast whenever the pawn associated with this PlayerState changes.
public	property	APlayerState::SavedNetworkAddress	Stores the network address of the player at the time of disconnect, used to match a reconnecting player controller back to an inactive PlayerState.

Events & Delegates

event OnPawnSet

Version History

Introduced in: 4.0

Version	Status	Notes
5.6	stable	—

Feedback

Was this helpful?