Skip to content

Commit 018ace0

Browse files
EmandMEmandM
committed
Add initial ownership docs page
1 parent 47ed2dd commit 018ace0

File tree

4 files changed

+162
-64
lines changed

4 files changed

+162
-64
lines changed

‎com.unity.netcode.gameobjects/Documentation~/basics/ownership.md‎

Lines changed: 0 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -30,65 +30,3 @@ You can also use `NetworkObject.SetOwnershipLock` to lock and unlock the permiss
3030

3131
> [!NOTE]
3232
> The ownership permissions are only visible when the Multiplayer Services SDK package is installed and you're inspecting a NetworkObject within the editor. Ownership permissions have no impact when using a client-server network topology, since the server always has authority. For ownership permissions to be used, you must be using a distributed authority network topology.
33-
34-
## Checking for authority
35-
36-
### `HasAuthority`
37-
38-
The `HasAuthority` property, which is available on both NetworkObjects and NetworkBehaviours, is session-mode agnostic and works in both distributed authority and client-server contexts. It's recommended to use `HasAuthority` whenever you're working with individual objects, regardless of whether you're using a distributed authority or client-server topology.
39-
40-
```
41-
public class MonsterAI : NetworkBehaviour
42-
{
43-
public override void OnNetworkSpawn()
44-
{
45-
if (!HasAuthority)
46-
{
47-
return;
48-
}
49-
// Authority monster init script here
50-
base.OnNetworkSpawn();
51-
}
52-
53-
private void Update()
54-
{
55-
if (!IsSpawned || !HasAuthority)
56-
{
57-
return;
58-
}
59-
// Authority updates monster AI here
60-
}
61-
}
62-
```
63-
64-
Using distributed authority with Netcode for GameObjects requires a shift in the understanding of authority: instead of authority belonging to the server in all cases, it belongs to whichever client instance currently has authority. This necessitates a shift away from using local, non-replicated properties to store pertinent states; instead, [NetworkVariables](networkvariable.md) should be used to keep states synchronized and saved when all clients disconnect from a session or ownership is transferred to another client.
65-
66-
Distributed authority supports all built-in NetworkVariable data types. Since there's no concept of an authoritative server in a distributed authority session, all NetworkVariables are automatically configured with owner write and everyone read permissions.
67-
68-
### `IsServer`
69-
70-
`IsServer` or `!IsServer` is the traditional client-server method of checking whether the current context has authority, and is only available in client-server topologies (because distributed authority games have no single authoritative server). You can use a mix of `HasAuthority` and `IsServer` when building a client-server game: `HasAuthority` is recommended when performing object-specific operations, while `IsServer` can be useful to check for authority when performing global actions.
71-
72-
```
73-
public class MonsterAI : NetworkBehaviour
74-
{
75-
public override void OnNetworkSpawn()
76-
{
77-
if (!IsServer)
78-
{
79-
return;
80-
}
81-
// Server-side monster init script here
82-
base.OnNetworkSpawn();
83-
}
84-
85-
private void Update()
86-
{
87-
if (!IsSpawned || !IsServer)
88-
{
89-
return;
90-
}
91-
// Server-side updates monster AI here
92-
}
93-
}
94-
```

‎com.unity.netcode.gameobjects/Documentation~/terms-concepts/authority.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,3 +29,35 @@ The authority of each networked object is responsible for simulating the behavio
2929
Because distributed authority games share the simulation between each connected client, they are less resource intensive. Each machine connected to the game processes a subdivision of the simulation, so no single machine needs to have the capacity to process the entire simulation. This results in a multiplayer game experience that can run on cheaper machines and is less resource intensive.
3030

3131
The distributed authority model is the authority model used for [distributed authority games](distributed-authority.md).
32+
33+
## Checking for authority
34+
35+
The `HasAuthority` property, which is available on both NetworkObjects and NetworkBehaviours, is session-mode agnostic and works in both distributed authority and client-server contexts. It's recommended to use `HasAuthority` whenever you're working with individual objects, regardless of whether you're using a distributed authority or client-server topology.
36+
37+
```csharp
38+
public class MonsterAI : NetworkBehaviour
39+
{
40+
public override void OnNetworkSpawn()
41+
{
42+
if (!HasAuthority)
43+
{
44+
return;
45+
}
46+
// Authority monster init script here
47+
base.OnNetworkSpawn();
48+
}
49+
50+
private void Update()
51+
{
52+
if (!IsSpawned || !HasAuthority)
53+
{
54+
return;
55+
}
56+
// Authority updates monster AI here
57+
}
58+
}
59+
```
60+
61+
Using distributed authority with Netcode for GameObjects requires a shift in the understanding of authority: instead of authority belonging to the server in all cases, it belongs to whichever client instance currently has authority. This necessitates a shift away from using local, non-replicated properties to store pertinent states; instead, [NetworkVariables](networkvariable.md) should be used to keep states synchronized and saved when all clients disconnect from a session or ownership is transferred to another client.
62+
63+
Distributed authority supports all built-in NetworkVariable data types. Since there's no concept of an authoritative server in a distributed authority session, all NetworkVariables are automatically configured with owner write and everyone read permissions.

‎com.unity.netcode.gameobjects/Documentation~/terms-concepts/client-server.md‎

Lines changed: 100 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,107 @@ Client-server is one possible [network topology](network-topologies.md) you can
44

55
## Defining client-server
66

7-
In a client-server topology, a central server is responsible for running the main simulation and managing all aspects of running the networked game, including simulating physics, spawning and despawning objects, and authorizing client requests. Players connect to the server using separate client programs to see and interact with the game.
7+
The client-server topology is made up of two distinct types of game instances. There is one server game instance, and many client game instances. The server is always the [authority](./authority.md) and is responsible for running the main simulation of the game. The server is responsible for simulating physics, spawning and despawning objects, authorizing client requests along with any other responsibilities. Client game instances can then connect to the server to interact with and respond the the server's game simulation.
88

9-
Client-server encompasses a number of potential network arrangements. The most common is a dedicated game server, in which a specialized server manages the game and exists solely for that purpose. An alternative client-server arrangement is to have a [listen server](../learn/listenserverhostarchitecture.md), in which the game server runs on the same machine as a client.
9+
Client-server encompasses a number of potential network arrangements. The most common is a dedicated game server, in which a specialized server manages the game and exists solely for that purpose.
10+
11+
An alternative client-server arrangement is to have a [listen server](../learn/listenserverhostarchitecture.md), in which the game server runs on the same machine as a client. In this arrangement, the server game instance is referred to as a host. A host game instance runs as both a server and a client simultaneously.
12+
13+
## Checking for game instance type
14+
15+
### `IsServer`
16+
17+
`IsServer` or `!IsServer` is the traditional client-server method of checking whether the current game instance is running as a server instance. This is useful for ensuring that the server instance is the only instance running authoritative game logic, such as spawning objects, processing game rules, and validating client actions.
18+
19+
You should use `IsServer` to ensure that only the server executes code that should be authoritative or global. For example, spawning enemies, handling core game logic, or updating shared state should only happen on the server. This prevents clients from making unauthorized changes and helps maintain a consistent game state across all connected players.
20+
21+
```csharp
22+
public class MonsterAI : NetworkBehaviour
23+
{
24+
public override void OnNetworkSpawn()
25+
{
26+
if (!IsServer)
27+
{
28+
return;
29+
}
30+
// Server-side monster init script here
31+
base.OnNetworkSpawn();
32+
}
33+
34+
private void Update()
35+
{
36+
if (!IsSpawned || !IsServer)
37+
{
38+
return;
39+
}
40+
// Server-side updates monster AI here
41+
}
42+
}
43+
```
44+
45+
### `IsHost`
46+
47+
The `IsHost` property is used to determine if the current game instance is running as both a server and a client simultaneously—a configuration known as a host. In Unity's Netcode for GameObjects, this is common when using a listen server, where the server and one client share the same process.
48+
49+
`IsHost` could be useful for branching resource heavy logic so that a game running as a listen-server can use code-paths optimized for running on end devices.
50+
51+
```csharp
52+
public class MonsterAI : NetworkBehaviour
53+
{
54+
public override void OnNetworkSpawn()
55+
{
56+
if (!IsServer)
57+
{
58+
return;
59+
}
60+
// Server-side monster init script here
61+
base.OnNetworkSpawn();
62+
}
63+
64+
private void Update()
65+
{
66+
if (!IsSpawned || !IsServer)
67+
{
68+
return;
69+
}
70+
if (IsHost)
71+
{
72+
// Monster AI that is optimized for user devices using a listen-server here.
73+
return
74+
}
75+
76+
// Monster AI that is optimized for the dedicated game server here.
77+
}
78+
}
79+
```
80+
81+
### `IsClient`
82+
83+
The `IsClient` property is used to check if the current game instance is running as a client. This is helpful for executing logic that should only run on client machines, such as updating UI elements, handling local input, or playing client-specific effects. Use `IsClient` to ensure that code only runs on the client side, preventing unintended execution on the server or in non-client contexts.
84+
85+
`IsClient` will be `true` for host instances as a host game instance is running as both a server and a client simultaneously.
86+
87+
```csharp
88+
public class MonsterAI : NetworkBehaviour
89+
{
90+
public override void OnNetworkSpawn()
91+
{
92+
if (IsClient)
93+
{
94+
// Play client side effects here
95+
96+
if (!IsHost)
97+
{
98+
// exit early if the game instance is only a client
99+
return;
100+
}
101+
}
102+
103+
// Server-side monster init script here
104+
base.OnNetworkSpawn();
105+
}
106+
}
107+
```
10108

11109
## Use cases for client-server
12110

‎com.unity.netcode.gameobjects/Documentation~/terms-concepts/distributed-authority.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,36 @@ When using the distributed authority topology, it's necessary to have a single d
2222

2323
The initial session owner is the first client that joins when the session is created. If this client disconnects during the game, a new session owner is automatically selected and promoted from within the clients that are currently connected.
2424

25+
### `IsSessionOwner`
26+
27+
To determine if the current client is the session owner, use the `IsSessionOwner` property provided by Netcode for GameObjects. This property is available on the `NetworkManager.Singleton` instance and returns `true` if the local client is the session owner.
28+
29+
```csharp
30+
public class MonsterAI : NetworkBehaviour
31+
{
32+
public override void OnNetworkSpawn()
33+
{
34+
if (!IsSessionOwner)
35+
{
36+
return;
37+
}
38+
// Global monster init behaviour here
39+
base.OnNetworkSpawn();
40+
}
41+
42+
private void Update()
43+
{
44+
if (!IsSpawned || !IsSessionOwner)
45+
{
46+
return;
47+
}
48+
// Global monster AI updates here
49+
}
50+
}
51+
```
52+
53+
You can use this property to conditionally execute logic that should only run on the session owner, such as managing global game state or handling session-wide events.
54+
2555
## More information about distributed authority
2656

2757
For more information about how distributed authority works in Netcode for GameObjects, see the following pages in the documentation:

0 commit comments

Comments
 (0)