🌐 Multiplayer in Terra Studio

Enables Multiplayer experiences

Terra Studio supports full multiplayer capabilities using Netcode for Unity — Unity’s official networking solution for GameObjects ( (see the full documentation at Unity Multiplayer Netcode Docs). All standard Netcode workflows and components are supported directly, so if you’ve used Netcode before, you’re ready to go.

Terra Studio uses ➡️ Netcode for GameObjects – Unity Docs (v1.10.0)

---

🚀 Getting Started with Multiplayer

Just like with Unity, multiplayer scripts in Terra Studio derive from NetworkBehaviour. However, in Terra Studio, multiplayer scripts should inherit from TerraNetBehaviour, which wraps Unity's networking base class and is fully compatible with Netcode workflows.

✅ Basic Script Structure

public class MyMultiplayerScript : TerraNetBehaviour
{
    // Code specific to this networked object

    // Called when the object is spawned on the network
    public override void OnNetworkSpawn()
    {
        // Initialization logic
    }

    // Called when the object is despawned from the network
    public override void OnNetworkDespawn()
    {
        // Cleanup logic
    }
}

These two lifecycle methods are useful for initializing and cleaning up your networked GameObjects.

---

🛠 Things to Keep in Mind

• Every GameObject you want to network must have a NetworkObject component.

• Any networked script must extend TerraNetBehaviour (not MonoBehaviour or TerraBehaviour).

• Refer to the Unity Netcode documentation for working with RPCs, ownership, spawning, synchronization, and more.

---

Unity’s official Netcode documentation covers all essential multiplayer features you may need: ➡️ Netcode for GameObjects – Unity Docs (v1.10.0)

Multiplayer Events

TerraNet provides a number of events that are triggered when key network and scene activities occur. These events allow you to adjust your user interface, initialize game logic, or clean up resources at the right time. The events are grouped into two main categories: Matchmaking/Lobby events and Scene Management events.

Matchmaking & Lobby Events

• TerraNet.OnMatchMakingStopped Triggered when matchmaking has started, but the player presses the back button to cancel it.

• TerraNet.OnMatchFound

  • 2 Players: Triggered when the second player joins using the match code. (Use this event to hide matchmaking UI and transition to the loading screen.)

  • More Than 2 Players: Triggered when the host clicks the "Start Game" button once the minimum required number of players has been reached.

• TerraNet.OnAllUsersConnected Fires when all players have successfully connected. Use this event to hide the loading screen and begin game play.

If a disconnection occurs before the match is fully ready (i.e., before all players are connected), then monitor these events:

• TerraNet.OnHostDisconnected

• TerraNet.OnRoomLeft

• TerraNet.OnPlayerRoomLeft

• TerraNet.OnMatchMakingUiClose Triggered when the matchmaking UI is closed.

---

Scene Management & Synchronization Events

These events help coordinate scene loading, unloading, and synchronization across the network. Important: Do not start new scene events within these notification callbacks.

• TerraNet.OnNetSceneLoad Invoked when a SceneEventType.Load event is started by the server. All connected clients receive this notification.

• TerraNet.OnNetSceneLoadComplete Triggered when a client or the server generates a SceneEventType.LoadComplete event. The server will receive this notification from every client.

• TerraNet.OnNetSceneLoadEventComplete Fired when the server generates a SceneEventType.LoadEventCompleted event. This signals that all clients (and the server) have finished the load event—helpful for confirming synchronization when loading a scene (either in single or additive mode).

• TerraNet.OnNetSceneUnLoad Triggered when a SceneEventType.Unload event is started by the server. All connected clients receive this notification.

• TerraNet.OnNetSceneUnLoadComplete Called when a SceneEventType.UnloadComplete event is generated by any client or the server. Each client’s notification is sent to the server.

• TerraNet.OnNetSceneUnLoadEventComplete Invoked when the server generates a SceneEventType.UnloadEventCompleted event. This signifies that all clients (and the server) have completed unloading a scene. The LoadSceneMode for this event is always Additive.

• TerraNet.OnNetSceneSynchronize Called when a SceneEventType.Synchronize event is started by the server after a new client is approved, allowing that client to sync its scenes and NetworkObjects.

• TerraNet.OnNetSceneSynchronizeComplete Triggered when a client completes the SceneEventType.Synchronize event. The server receives a notification from each client (but does not generate this event for itself), which lets you know that the client is fully synchronized.

---

TerraNet Functions

These functions provide control over matchmaking, room sessions, scene management, and synchronized properties. They enable you to start and stop matchmaking, control networked scenes, and access session settings.

Matchmaking API

• TerraNet.StartMatchMaking(gameName) Starts the matchmaking process, for example when the player clicks "Play with Friends."

  Relay Variants:

  • TerraNet.StartMatchMaking(gameName, gameMode);

  • TerraNet.StartMatchMaking(gameName, gameMode, roomId);

  • TerraNet.StartMatchMaking(gameName, gameMode, autoRoomCreate);

• TerraNet.StartMatchMakingDedicated(...) Used for dedicated server scenarios; similar overloads are available.

• TerraNet.StopMatchMaking() Stops the matchmaking process.

• TerraNet.DisableMatchMakingUI() Disables the matchmaking user interface.

• TerraNet.EnableMatchMakingUI() Enables the matchmaking user interface.

Session & Room Control

• TerraNet.ShutdownSession() Call this when the game is exited and the player returns to the home screen.

• TerraNet.ServerReady() Used on dedicated servers. Trigger this when your server is ready to receive new players.

• TerraNet.GetMaxPlayers() Returns the maximum number of players allowed, as defined in the database.

• TerraNet.GetMinPlayers() Returns the minimum number of players required to start a match.

• TerraNet.GetExpectedPlayers() Returns a list of players who have joined using the match code (only players who entered the code are included).

Scene Management

• TerraNet.LoadNetworkedScene(sceneName) Loads the specified networked scene.

• TerraNet.UnloadNetworkedScene(sceneName) Unloads the specified networked scene.

• TerraNet.IsSceneNetworkReady(sceneName) Checks if a scene is ready for network synchronization.

Synchronized Properties

• TerraNet.UpdateSyncProperty(key, value) Updates a synchronized property across clients.

• TerraNet.GetSyncProperty(key) Retrieves the value of a synchronized property using the specified key.

---

TerraNetBehaviour API

Extend TerraNetBehaviour in your networked scripts to access properties, override callbacks, and send custom RPCs.

Key Properties

• NetworkManager Retrieves the network manager instance.

• NetworkObject Retrieves the network object instance.

• IsPlayerObject Returns true if this object is associated with a player.

• IsServer, IsHost, IsClient Boolean flags indicating the network role of the application.

• NetworkObjectId The unique ID of this networked object.

• LocalClientId Returns the server's client ID if IsServer is true; otherwise, it returns the local client ID.

• ServerClientId A constant ID (always 0) representing the server.

• ConnectedClients Provides a list of client IDs for all connected clients (server-only property).

Overridable Callbacks

Override these methods in your TerraNetBehaviour script to respond to network events:

• OnNetworkSpawn() Called when the NetworkObject is spawned. Use this to register RPC handlers or initialize network state.

• OnNetworkDespawn() Called when the NetworkObject is despawned. Use this to clean up any network-specific resources.

• OnClientConnect(ulong clientId) Called on the server and on the connecting client when a new client connects.

• OnClientDisconnect(ulong clientId) Called on the server and on the disconnecting client when a client leaves.

• OnRPCReceived(string key, object[] args) Invoked on the target machine when an RPC is received.

• OnSyncPropertiesUpdated(string key, object value) Called on all machines when a synchronized property is updated.

Sending RPCs

Use the SendRPC function to send remote procedure calls to other clients or the server:

SendRPC(SendTarget sendTo, string key, List<ulong> clientIds, object[] args);

Note:

• Use SendTarget.SpecifiedInParams when targeting specific client IDs.

• The clientIds list will be ignored if you are not targeting specific clients.

---

Best Practices for Multiplayer Development in Terra Studio

• Wait for Full Connection: Use TerraNet.OnAllUsersConnected to ensure that all players have connected before starting gameplay.

• Don’t Start New Scene Events Inside Callbacks: Always complete scene events before triggering new ones.

• Keep Synchronized Properties Up-To-Date: Use UpdateSyncProperty() to share gameplay-critical information (e.g., match timers).

• Use SendRPC for Gameplay Instructions: Leverage RPC calls for actions like updating positions, syncing health, or triggering animations.

• Test Thoroughly: Network timing can be variable; make sure to test multiplayer scenarios (especially on different network conditions).