This document is about: FUSION 2
SWITCH TO

PlayerRef

Overview

A 'Player' in Fusion refers to any peer with a NetworkRunner which can provide player inputs to Fusion; i.e. any peer type OTHER than a Dedicated Game Session Server.

In this document, the various way to identify and access player information will be presented.

PlayerRef

Each NetworkRunner which can provide input for a player controlled peer is associated with a unique identifier called PlayerRef. The PlayerRef given to player only serves as an identifier, and does not contain any player specific data.

PlayerCount

This value is the maximum number of players which may be connected to a Game Session at any given time.

The default maximum PlayerCount per Game Session is defined globally in the NetworkProjectConfig asset by the Simulation > Default Players field.

When creating a new Game Session, PlayerCount is determined by the nullable StartGameArgs.PlayerCount value which was passed to NetworkRunner.StartGame(). If StartGameArgs.PlayerCount was not assigned a value (or was set to null), the new Game Session will use the Default Player count from the NetworkProjectConfig instead.

Note that a Dedicated Server does NOT have a PlayerRef and does not represent a player, so it does NOT count toward the PlayerCount limit. This means that a Game Session with a PlayerCount of 4 supports:

  • 1 Host and 3 Clients
  • 1 Dedicated Server and 4 Clients
  • 4 Shared Mode clients

Defining a Player Object

The Player Object is an optional convenient way to associate each PlayerRef in a Game Session with a particular NetworkObject 'Avatar'.

Each PlayerRef can be associated with exactly one NetworkObject. This association will be networked and automatically replicated on all clients.

The PlayerRef <-> NetworkObject association is set using the NetworkRunner.SetPlayerObject(PLayerRef, NetworkObject) method.

  • In Host & Server Mode: The Player Object can only be set by the Host / Server.
  • In Shared Mode: Each Player can only set their own Player Object association, and that Player must also have State Authority over the NetworkObject being associated.

Any peer can retrieve the NetworkObject associated with a particular PlayerRef via the NetworkRunner.TryGetPlayerObject(PlayerRef, out NetworkObject) method.

C#

// On Player Joined, create and define a Player Object.
void OnPlayerJoined(PlayerRef player, NetworkRunner runner){

    if (Object.HasStateAuthority == false) return;

    var plObject = runner.Spawn(PlayerObjectPrefab);
    var plData = plObject.GetComponent<PlayerData>();

    //SetData defines the PlayerRef for that NB and a life amount.
    plData.SetData(player, 3);

    runner.SetPlayerObject(player, plObject)
}


// When desired, get the Player Object.

int GetPlayerLife(PlayerRef player){
    if (Runner.TryGetPlayerObject(player, out var plObject)){
        return plObject.GetComponent<PlayerData>().Lifes;
    }

    Debug.LogError("Player Object Not found")
    return 0;
}

State Authority

Each NetworkObject has a PlayerRef associated as the StateAuthority. The StateAuthority is in control of the state of the NetworkObject such as its Networked Properties. Any changes made to a Networked Property on the StateAuthority is replicated over the network to other clients.

  • Host/Server Mode: Always the server/host, no player has state authority over the game state.
  • Share dMode: the authority is decentralized and shared among players. Any player can have state authority over any objects which does not already have a state authority assigned to it or has Allow StateAuthorityOverride Set to true on the NetworkObject. The state authority can be assigned when the object is spawned and change hands by calling NetworkObject.ReleaseStateAuthority() and NetworkObject.RequestStateAuthority().

Input Authority

In addition to the StateAuthority a NetworkObject can have an InputAuthority. InputAuthority is only relevant in Shared/Host Mode.

A Player can have input authority over multiple NetworkObjects. When a player has input authority over a NetworkObject, it can send inputs and the server will catch them when looking for inputs on that specific object. That is the main way of communication from clients to the server. For more information about inputs, read Player Input

Multiple Local Player on One Machine

If the game allows for more than one local physical player on a single NetworkRunner (for example, couch co-op combined with online players), then game specific logic will be needed to differentiate the local players, independent of Fusion’s 'Player' concept. All input from multiple local players must be consolidated into Fusion's input system, using one network input struct to hold data about all the local players inputs.

NOTE: Having local multiple players creates the need for additional custom logic when using functions that depend on PlayerRef, such as SetPlayerObject or OnPlayerJoined.

Back to top