新增FishNet文档
This commit is contained in:
@@ -0,0 +1,7 @@
|
||||
---
|
||||
description: A general overview of networking using FishNet.
|
||||
---
|
||||
|
||||
# High-Level Overview
|
||||
|
||||
<table data-card-size="large" data-view="cards" data-full-width="false"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="files"></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Fundamentals</strong></td><td>Learn the core concepts and basic principles of our<br>system.</td><td><a href="../../.gitbook/assets/foundamentals-card.png">foundamentals-card.png</a></td><td><a href="fundamentals.md">fundamentals.md</a></td></tr><tr><td><strong>Networking Models</strong></td><td>Dive deep into the various networking architectures<br>and designs.</td><td><a href="../../.gitbook/assets/networking-models-card.png">networking-models-card.png</a></td><td><a href="networking-models.md">networking-models.md</a></td></tr><tr><td><strong>Terminology</strong></td><td>Understand the key terms and definitions used<br>across our documentation.</td><td><a href="../../.gitbook/assets/terminology-card.png">terminology-card.png</a></td><td><a href="terminology/">terminology</a></td></tr><tr><td><strong>Transports</strong></td><td>Discover the different methods and protocols for<br>data transfer.</td><td><a href="../../.gitbook/assets/transports-card.png">transports-card.png</a></td><td><a href="transports.md">transports.md</a></td></tr></tbody></table>
|
||||
@@ -0,0 +1,38 @@
|
||||
---
|
||||
description: To understand FishNet, it's helpful to grasp a few fundamental concepts.
|
||||
cover: ../../.gitbook/assets/foundamentals-cover.png
|
||||
coverY: 0
|
||||
---
|
||||
|
||||
# Fundamentals
|
||||
|
||||
## A networked game
|
||||
|
||||
At its heart, a networked game using Fish-Networking can be thought of as a single-player game running on multiple machines (or even multiple instances of the game running on a the same machine, which is very useful for development). The magic of multiplayer comes from FishNet's ability to synchronize various parts of your game's code and state across these machines, and to send custom messages back and forth to trigger actions or update information. This ensures that all players experience a consistent and interactive world.
|
||||
|
||||
The code you write behaves the same as it does in a regular game, code in <mark style="color:blue;">`Update`</mark> will run each frame, <mark style="color:blue;">`Awake`</mark> triggers as soon as a script is being loaded, etc. **But** FishNet adds additional features such as [Synced Variables](../features/network-communication/synchronizing/), which you will be able to set on the game instance that is acting as the server and they will automatically have their value synced to all connected client game instances. FishNet also has [Remote Procedure Calls](../features/network-communication/remote-procedure-calls.md), which are methods that you call on one game instance and FishNet will execute the method on a different game instance instead of executing it locally.
|
||||
|
||||
To enable these features, FishNet needs to be able to identify game objects and scripts across the network so that it can know which game object and specific script on that game object you called an RPC[^1] or changed a SyncVar[^2] on. FishNet does this by assigning IDs to selected GameObjects that you give a [NetworkObject ](../features/networked-gameobjects-and-scripts/networkobjects/)component to. It also assigns IDs to any component that inherits from [NetworkBehaviour](../features/networked-gameobjects-and-scripts/network-behaviour-guides.md), which is a MonoBehaviour that supports RPCs, SyncVars, and useful network methods and properties.
|
||||
|
||||
For NetworkObjects that can be instantiated during run-time, FishNet needs to store a prefab of them and assign an ID to the prefab so that it can instantiate that same one across the network when you spawn it on the server. This is handled with a prefab collection scriptable object called the [Spawnable Prefabs](../../fishnet-building-blocks/scriptableobjects/spawnableprefabs/).
|
||||
|
||||
***
|
||||
|
||||
## The server and client
|
||||
|
||||
FishNet is capable of running as a server and/or as a client, and they can be started and stopped independently of one another. When you start the server, FishNet will set various fields such as `IsServerStarted` as true in that game instance that is running as the server. The same applies when you start a client; when both are running FishNet will also set values such as `IsHostStarted`. These fields can be used to determine if the code is running in the game instance acting as a server, client, or both.
|
||||
|
||||
***
|
||||
|
||||
## Key concepts
|
||||
|
||||
* **NetworkManager:** This is the central hub of your FishNet application. It manages the networking lifecycle, including starting and stopping servers and clients, handling connections, and overseeing the spawning of networked objects.
|
||||
* **NetworkObject:** Any GameObject in your Unity scene that needs to be linked across the network must have a NetworkObject component attached. This component assigns a unique network ID and manages the object's networked lifecycle, ensuring its existence and state are consistent across all connected clients.
|
||||
* **NetworkBehaviour:** Similar to Unity's MonoBehaviour, NetworkBehaviour is the base class for all scripts that need to directly contain RPCs, SyncTypes, or NetworkBehaviour methods. Scripts inheriting from `NetworkBehaviour` can access useful properties like `NetworkManager`, `IsServerStarted`, `IsSpawned`, `IsOwner`, as well as be directly referenced across the network.
|
||||
* **Ownership and Observers:** FishNet provides a clear system for defining **ownership** of NetworkObjects, typically assigned to the client that created or controls the object. **Observers** are clients that are "observing" a particular NetworkObject, meaning they receive updates about its state. This allows for efficient data transmission, sending updates only to relevant clients.
|
||||
* **Remote Procedure Calls (RPCs):** RPCs are a core mechanism for communication between clients and the server. They allow you to call methods on a specific NetworkBehaviour instance that execute on a remote machines linked version of that instance. Any script can call an RPC, even regular MonoBehaviours, ScriptableObjects, or other classes.
|
||||
* **SyncVars:** These are powerful features for automatically synchronizing variable values and complex data structures (like lists or dictionaries) across the network. When a SyncVar's value changes on the server, it's automatically replicated to all observing clients.
|
||||
|
||||
[^1]: Remote Procedure Call
|
||||
|
||||
[^2]: Synchronized Variable
|
||||
@@ -0,0 +1,86 @@
|
||||
---
|
||||
description: >-
|
||||
This page discusses the various networking models and architectures used in
|
||||
games and what Fish-Networking uses.
|
||||
---
|
||||
|
||||
# Networking Models
|
||||
|
||||
## Client-Server architecture
|
||||
|
||||
The **client-server model** is the most widely used approach in multiplayer networking. In this model:
|
||||
|
||||
* **Server**: The authoritative instance of the game. It manages game logic, synchronizes game state, validates player actions, and handles communication between clients.
|
||||
* **Client**: A player's instance of the game. It sends input to the server and receives updates about the game state.
|
||||
|
||||
There are two main types of servers:
|
||||
|
||||
### **Dedicated server**
|
||||
|
||||
The server runs as its own process, separate from any player. It’s more secure and scalable, commonly used in competitive or large-scale games.
|
||||
|
||||
<figure><img src="../../.gitbook/assets/client-server-model.svg" alt="An image showing multiple clients connected to a single server" width="563"><figcaption><p>A dedicated server model</p></figcaption></figure>
|
||||
|
||||
As you can see from the above diagram, the clients (players) are all connected directly to the server and communicate with it instead of with each other.
|
||||
|
||||
***
|
||||
|
||||
### **Host (listen-server)**
|
||||
|
||||
The server and one of the clients run in the same process. This is common in smaller games or development environments.
|
||||
|
||||
<figure><img src="../../.gitbook/assets/listen-server-model.svg" alt="An image showing multiple clients connected to a single server which is also acting as a client itself" width="563"><figcaption><p>A listen-server model</p></figcaption></figure>
|
||||
|
||||
The above diagram demonstrates how the listen-server is similar to the dedicated server model where all clients connect directly with the server, but unlike the dedicated server, the listen server is also acting as a client (player).
|
||||
|
||||
{% hint style="success" %}
|
||||
FishNet supports both dedicated and listen-server models out of the box.
|
||||
{% endhint %}
|
||||
|
||||
***
|
||||
|
||||
## Peer-to-peer (P2P)
|
||||
|
||||
In **peer-to-peer networking**, each player (or peer) connects directly to others without a central server. This reduces latency and server costs but comes with challenges:
|
||||
|
||||
* Poor security and cheating prevention
|
||||
* Difficult to synchronize game state reliably
|
||||
* NAT traversal issues
|
||||
|
||||
<figure><img src="../../.gitbook/assets/p2p-model.svg" alt="An image of four clients all interconnected with each other." width="563"><figcaption><p>A peer-to-peer model</p></figcaption></figure>
|
||||
|
||||
P2P is rarely used in modern real-time multiplayer games, especially competitive ones, due to these drawbacks. FishNet does not use P2P, as it is designed around the client-server model for reliability and security.
|
||||
|
||||
{% hint style="info" %}
|
||||
Very often a listen server setup is referred to as P2P, FishNet does support a listen server.
|
||||
{% endhint %}
|
||||
|
||||
***
|
||||
|
||||
## Relay servers
|
||||
|
||||
Sometimes clients are unable to connect directly to the server due to **NAT (Network Address Translation)** or **firewall** restrictions. A **relay server** acts as a middleman to forward traffic between clients and the server.
|
||||
|
||||
<figure><img src="../../.gitbook/assets/relay-server-model.svg" alt="An image of a three clients connecting to a server which links them to a server and client instance." width="563"><figcaption><p>A relay server</p></figcaption></figure>
|
||||
|
||||
Relay servers:
|
||||
|
||||
* Allow connectivity when direct connections fail
|
||||
* Introduce additional latency
|
||||
* May be used as a fallback or for web-based games
|
||||
|
||||
{% hint style="success" %}
|
||||
Fish-Networking supports multiple third-party relay services including [Unity's Relay](https://unity.com/products/relay), [Edgegap's Distributed Relay](https://edgegap.com/platform/distributed-relay), [Photon Realtime](https://www.photonengine.com/Realtime), [Epic Online Services' Relay Service](https://dev.epicgames.com/docs/epic-online-services/eos-overview#peer-to-peer-p2p-connections), and [Steam Datagram Relay](https://partner.steamgames.com/doc/features/multiplayer/steamdatagramrelay).
|
||||
|
||||
There is also the free self-hosted [BlitzRelay](https://github.com/abdelfattahradwan/blitz-relay) that you can use.
|
||||
{% endhint %}
|
||||
|
||||
***
|
||||
|
||||
### Host migration
|
||||
|
||||
When using a listen server, the host leaving the game would cause all players to leave the game; **Host migration** is a feature for maintaining game sessions in the event the current host disconnects or experiences network issues. It enables a new host to be elected from the remaining connected players, minimizing disruption and ensuring the game session can continue seamlessly.
|
||||
|
||||
{% hint style="warning" %}
|
||||
Fish-Networking doesn't have built-in host migration, but it is possible (though tricky) to create it yourself.
|
||||
{% endhint %}
|
||||
@@ -0,0 +1,8 @@
|
||||
---
|
||||
description: >-
|
||||
The following pages give some commonly used terminology for Fish-Networking as
|
||||
well as general networking terms you are likely to encounter.
|
||||
---
|
||||
|
||||
# Terminology
|
||||
|
||||
+105
@@ -0,0 +1,105 @@
|
||||
---
|
||||
description: There are a variety of ways to send communications between server and clients.
|
||||
---
|
||||
|
||||
# Communicating
|
||||
|
||||
Below are several terms you will become familiar with when wanting to send data.
|
||||
|
||||
## [SyncTypes](../../features/network-communication/synchronizing/) <a href="#server-and-host" id="server-and-host"></a>
|
||||
|
||||
{% tabs %}
|
||||
{% tab title="Description" %}
|
||||
SyncTypes reside on objects and are data driven variables or collections. SyncTypes send at adjustable intervals. When a SyncType is modified on an object the changes are automatically sent from the server to clients. Clients will receive the changes locally on the same object. A great example is a health variable. You may update the health variable as a player takes damage, and the new values will be sent to clients.
|
||||
{% endtab %}
|
||||
|
||||
{% tab title="Example" %}
|
||||
This basic example shows a simple integer variable that will automatically be synchronized to all clients whenever the server changes it.
|
||||
|
||||
```csharp
|
||||
using FishNet.Object;
|
||||
using FishNet.Object.Synchronizing;
|
||||
|
||||
public class Player : NetworkBehaviour
|
||||
{
|
||||
private readonly SyncVar<int> _health = new SyncVar<int>(100);
|
||||
|
||||
public void StepOnLego()
|
||||
{
|
||||
if (!IsServerInitialized)
|
||||
return;
|
||||
|
||||
_health. Value -= 10;
|
||||
}
|
||||
}
|
||||
```
|
||||
{% endtab %}
|
||||
{% endtabs %}
|
||||
|
||||
## [Remote Procedure Calls](../../features/network-communication/remote-procedure-calls.md) <a href="#server-and-host" id="server-and-host"></a>
|
||||
|
||||
{% tabs %}
|
||||
{% tab title="Description" %}
|
||||
[Remote Procedure Calls](#user-content-fn-1)[^1] are another object bound communication type. While SyncTypes are used to synchronize variables, RPCs allow you to run logic on server and clients. RPCs are not limited to an interval like states, RPCs can be sent immediately on the next network tick or as soon as possible. They are required to be within a NetworkBehaviour class.
|
||||
{% endtab %}
|
||||
|
||||
{% tab title="Example" %}
|
||||
This is a simple example that shows a [Server Remote Procedure Call](#user-content-fn-2)[^2]. The method should be called from a client and the body will not execute locally, instead, the arguments will be sent across the network and the method body with those arguments will run remotely on the server.
|
||||
|
||||
```csharp
|
||||
using FishNet.Object;
|
||||
|
||||
public class Player : NetworkBehaviour
|
||||
{
|
||||
[ServerRpc]
|
||||
private void UpdatePlayerName(string newName)
|
||||
{
|
||||
print($"Player {OwnerId} has updated their name to {newName}");
|
||||
}
|
||||
}
|
||||
```
|
||||
{% endtab %}
|
||||
{% endtabs %}
|
||||
|
||||
## [Broadcasts](../../features/network-communication/broadcasts.md) <a href="#server-and-host" id="server-and-host"></a>
|
||||
|
||||
{% tabs %}
|
||||
{% tab title="Description" %}
|
||||
Unlike states, broadcasts are not object bound. Broadcasts can be used for any number of tasks but are more commonly preferred for communicating data groups between server and clients. Broadcasts can be received and sent from anywhere in your code and do not need to be within a NetworkBehaviour class as RPCs do.
|
||||
{% endtab %}
|
||||
|
||||
{% tab title="Example" %}
|
||||
This example shows how a client could send a broadcast to the server.
|
||||
|
||||
```csharp
|
||||
using FishNet;
|
||||
using UnityEngine;
|
||||
|
||||
public class ChatSystem : MonoBehaviour
|
||||
{
|
||||
public void SendChatMessage(string text)
|
||||
{
|
||||
ChatBroadcast msg = new ChatBroadcast()
|
||||
{
|
||||
Message = text,
|
||||
FontColor = Color.white
|
||||
};
|
||||
|
||||
InstanceFinder.ClientManager.Broadcast(msg);
|
||||
}
|
||||
}
|
||||
```
|
||||
{% endtab %}
|
||||
{% endtabs %}
|
||||
|
||||
{% hint style="info" %}
|
||||
For all of the above communication methods, two channels are supported, Reliable and Unreliable. Data sent reliably is guaranteed to arrive and be processed in the order it was sent. Data sent unreliably uses less bandwidth, but can occasionally arrive out of order, or not at all.
|
||||
{% endhint %}
|
||||
|
||||
{% hint style="info" %}
|
||||
Some features of Fish-Networking internally use eventual consistency; an example of this are unreliable SyncVars or the NetworkTransform component. These features use the unreliable channel to send datas to consume less bandwidth and provide better performance, but you can still use them knowing that even if data is dropped or arrives out of order the features will eventually resolve the desynchronizations automatically.
|
||||
{% endhint %}
|
||||
|
||||
[^1]: Often called RPCs
|
||||
|
||||
[^2]: These are commonly called ServerRPCs
|
||||
+27
@@ -0,0 +1,27 @@
|
||||
---
|
||||
description: >-
|
||||
There are a several commonly terms which you may encounter throughout your
|
||||
development experience with FishNet.
|
||||
---
|
||||
|
||||
# Miscellaneous
|
||||
|
||||
## Scene object
|
||||
|
||||
A scene object is an object which is placed in a scene's hierarchy during edit-time. Scene objects are objects which may be spawned over the network, but do not require instantiating as they are already placed in the scene.
|
||||
|
||||
## Instantiated object
|
||||
|
||||
An instantiated object is an object which was instantiated at run-time, and is not a scene object. For example, `Instantiate(yourPrefab)`.
|
||||
|
||||
## Predicted object
|
||||
|
||||
An object which utilizes the prediction system. Predicted features generally run on the client and server at the same time to allow real-time gameplay interactions. These types of behaviors require more work but a proper prediction setup will prevent cheating.
|
||||
|
||||
## Client authoritative
|
||||
|
||||
Often means an object is controlled by the client and results are sent to the server without validation. Client authortative coding is easier to understand but may allow players to cheat more easily. An example of this is a NetworkTransform component with Client Authoritative set to true; the client controls the object locally and the server updates to client's values.
|
||||
|
||||
## Server authoritative
|
||||
|
||||
Values are controlled or verified by the server, such as SyncTypes. Predicted objects are server authoritative.
|
||||
+37
@@ -0,0 +1,37 @@
|
||||
# Server, Client, Host
|
||||
|
||||
## Ownership and controller <a href="#server-and-host" id="server-and-host"></a>
|
||||
|
||||
Ownership is when a specific client _owns_ the object, while _controller_ is whichever entity controls the object. By our terms, only a client can own an object, but either the server or a client may be the controller.
|
||||
|
||||
When a client owns an object they are the 'controller' and are able to send [remote procedure calls](../../features/network-communication/remote-procedure-calls.md) without disabling authority checks, among other tasks such as generating prediction data.
|
||||
|
||||
A controller is the server if the object is not owned by any client, but again, the client becomes the controller when they own the object.
|
||||
|
||||
## Server <a href="#server-and-host" id="server-and-host"></a>
|
||||
|
||||
Server is an instance of your project which clients connect to. A server allows clients to interact with each other and will often be responsible for important aspects of your game such as score keeping, world spawning, and more.
|
||||
|
||||
#### Local server
|
||||
|
||||
When a server is started the build or instance running the server is referred to as the local server.
|
||||
|
||||
#### Remote client
|
||||
|
||||
A remote client is a term only applicable when running as the server. A remote client is a player connection established with the server. It's possible for a remote client to be the same as a local client. The main difference is the local client refers to the player-side logic while a remote client refers to the server's connection with the client.
|
||||
|
||||
## Client <a href="#server-and-host" id="server-and-host"></a>
|
||||
|
||||
A client connects to the server, whether the server be local or online. A client is the player for your game. A client experiences the game-play while the server synchronizes data between clients.
|
||||
|
||||
#### Local client
|
||||
|
||||
Local client refers to the client controlling their game. If you join the server as a player, you are the local client.
|
||||
|
||||
#### Remote server
|
||||
|
||||
When the local client connects to a server, they are connecting to a remote server. It's possible the remote server is also the local server if the client is running as host.
|
||||
|
||||
## Host <a href="#server-and-host" id="server-and-host"></a>
|
||||
|
||||
When behaving as a host you are both the client and the server. An individual can become host without having to compile additional executables, nor having to provide any special access to their computer. Host is ideal for speedy development.
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
description: Transports control how data is sent, received, and handled over the network.
|
||||
---
|
||||
|
||||
# Transports
|
||||
|
||||
The **Transport** is the low-level layer responsible for sending and receiving raw data over the network. It abstracts away the details of TCP/UDP sockets and handles packet delivery, reliability, ordering, etc.
|
||||
|
||||
FishNet uses events internally to plug into transport messages. Although it be unlikely you would need to access such messages, they are available to you for your development as well.
|
||||
|
||||
There are many transports available, some are maintained by the Fish-Networking team and others maintained by the community.
|
||||
|
||||
* [Tugboat](../../fishnet-building-blocks/transports/tugboat.md) (LiteNetLib)
|
||||
* [Bayou](../../fishnet-building-blocks/transports/bayou.md) (WebGL)
|
||||
* [Yak](../../fishnet-building-blocks/transports/yak-pro-feature.md) (for offline gameplay)
|
||||
* [Multipass](../../fishnet-building-blocks/transports/multipass.md) (multi-transport support)
|
||||
* [Blitz Relay For FishNet](../../fishnet-building-blocks/transports/fishyblitzrelay.md) (self-hosted relay)
|
||||
* [FishySteamworks](../../fishnet-building-blocks/transports/fishysteamworks.md) (Steamworks.NET)
|
||||
* [FishyFacepunch](../../fishnet-building-blocks/transports/fishyfacepunch-steam.md) (Facepunch for Steam)
|
||||
* [FishyEOS](../../fishnet-building-blocks/transports/fishyeos-epic-online-services.md) (Epic Online Services)
|
||||
* [FishyUnityTransport](../../fishnet-building-blocks/transports/fishyunitytransport.md) (Unity Transport)
|
||||
* [FishyRealtime](../../fishnet-building-blocks/transports/fishyrealtime.md) (Photon Realtime)
|
||||
* [FishyWebRTC](../../fishnet-building-blocks/transports/fishywebrtc.md) (WebRTC)
|
||||
* [CanoeWebRTC](../../fishnet-building-blocks/transports/canoe-webrtc.md) (WebRTC)
|
||||
Reference in New Issue
Block a user