# Multiplayer (Pro)

{% hint style="info" %}
Multiplayer functionality is only available in the Professional version and requires Unity Netcode for GameObjects and Unity Services.
{% endhint %}

Real-time collaborative industrial automation simulation with support for multiple users and VR/AR integration.

## Overview

The realvirtual Professional Multiplayer system enables multiple users to simultaneously interact with the same virtual commissioning scenario. Built on [Unity Netcode for GameObjects](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest/) with [Unity Relay Service](https://docs.unity.com/ugs/manual/relay/manual/introduction), it provides synchronized automation components, real-time material flow, and collaborative design review capabilities.

## Key Features

* **Multi-user Collaboration**: Scalable concurrent users in the same simulation
* **Real-time Synchronization**: All automation components (Drives, Sensors, MUs, Sources) synchronized across clients
* **VR/AR Support**: Full XR controller tracking and avatar representation
* **Industrial Integration**: PLC signal synchronization and automation logic sharing
* **Cloud-based Connection**: [Unity Relay Service](https://docs.unity.com/ugs/manual/relay/manual/introduction) for secure peer-to-peer connections

## System Requirements

### Unity Packages

* [**Unity Netcode for GameObjects**](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest/): Core networking framework
* [**Unity Transport (UTP)**](https://docs.unity3d.com/Packages/com.unity.transport@latest/): Network transport layer with DTLS encryption
* **Unity Services Core**: Authentication and Unity Services integration
* **XR Interaction Toolkit** (optional): For VR/AR functionality

## Setup

### 1. Unity Services Configuration

1. **Enable Unity Services** in Project Settings → Services
2. **Create Unity Project ID** or link to existing project
3. **Enable** [**Relay Service**](https://docs.unity.com/ugs/manual/relay/manual/introduction) in Unity Dashboard → Multiplayer → Relay
4. **Enable** [**Authentication**](https://docs.unity.com/ugs/en-us/manual/authentication/manual/overview) for anonymous user sessions

### 2. Scene Setup

1. **Add the Multiplayer Prefab** to your scene from the realvirtual Professional package
   * The prefab contains all necessary components: NetworkManager, RelayConnectionManager, NetworkInitializer, and MultiuserWindow
   * All network prefabs are pre-configured and registered automatically

<figure><img src="/files/jJfe0DtjqlsrTYN9Q82n" alt="NetworkManager Configuration"><figcaption><p>NetworkManager configuration showing Unity Transport settings, Relay Connection Manager, and network prefab registration</p></figcaption></figure>

### 3. Automation Component Setup

The system automatically creates networked versions of:

* **Drives**: Position and speed synchronization
* **Sensors**: Occupancy state synchronization
* **MUs (Moving Units)**: Transform and identity synchronization
* **Sources**: Material generation events
* **Signals**: PLC signal values and states

## Usage

### Starting a Host Session

1. **Open Multiuser Window** via realvirtual → UI toolbar
2. **Enter Player Name** (stored locally)
3. **Click "Host"** to create session
4. **Share Join Code** with other users

### Joining as Client

1. **Open Multiuser Window**
2. **Enter Player Name**
3. **Input Join Code** received from host
4. **Click "Client"** to join session

<figure><img src="/files/M8WEh25U8BzatpCjqPGp" alt="Multiuser Window Interface"><figcaption><p>Multiuser window showing Code input field, Name field, and Host/Client connection buttons with status display</p></figcaption></figure>

### Connection Status

* **Connected**: Successfully connected to multiplayer session
* **No Connection**: Not connected or connection failed

## Synchronized Components

### NetworkDrive

* **Position Values**: Current drive positions
* **Speed Values**: Current drive speeds
* **Authority**: Host controls drives, clients receive updates
* **Override Mode**: Clients use PositionOverwrite and SpeedOverwrite

### NetworkMU (Moving Units)

* **Transform**: Position and rotation
* **Identity**: LocalID, GlobalID, Name
* **Physics**: Host maintains physics authority, clients use kinematic mode
* **Source Tracking**: References to creating Source component

{% hint style="warning" %}
Physics objects must be kinematic on client machines to prevent conflicts with the host's authoritative physics simulation.
{% endhint %}

### NetworkSensor

* **Occupancy State**: Boolean occupied/free status
* **Network Mode**: Clients automatically switch to network-controlled mode
* **Real-time Updates**: Immediate sensor state propagation

### NetworkSignal

* **Signal Values**: All PLC signal types (PLCInputBool, PLCOutputFloat, etc.)
* **Bidirectional**: Host-to-client signal synchronization
* **String-based**: Universal value representation

### NetworkPlayer

* **Player Names**: Persistent player identification
* **XR Controllers**: Left and right controller position/rotation sync
* **Avatar Visibility**: First-person view (own avatar hidden)
* **Camera Tracking**: Remote user viewpoint synchronization

## VR/AR Integration

### XR Setup

1. **Install XR Interaction Toolkit**
2. **Configure XR Controllers** as "LeftController" and "RightController" Groups
3. **Enable XR Support** in realvirtual-XR package
4. **Test Controller Tracking** before multiplayer sessions

### Supported VR Systems

* **Meta Quest 2/3**: Fully tested with Touch controllers
* **Other OpenXR Devices**: Compatible through Unity XR system
* **Mixed Reality**: Combine VR users with desktop users

## Performance Considerations

### Network Optimization

* **Change Detection**: Only synchronizes data when values change
* **Update Frequency**: FixedUpdate (50Hz) for smooth synchronization
* **Interpolation**: Client-side smooth movement for controllers
* **Authority Model**: Host maintains physics, clients display only

### Best Practices

* **Monitor Simultaneous MUs**: High MU counts can impact network performance depending on bandwidth
* **Use Appropriate Update Rates**: Balance responsiveness with bandwidth (50Hz default)
* **Test Network Conditions**: Verify performance under realistic network latency
* **Monitor Connection Quality**: Use Unity Profiler for network analysis
* **Unity Transport Configuration**: Use default settings for optimal Relay performance

## Troubleshooting

### Connection Issues

* **Unity Services Authentication**: Verify anonymous authentication is enabled in Project Settings → Services
* **Relay Allocation**: Check Unity Dashboard for Relay service status and CCU limits
* **Firewall Settings**: Ensure UDP traffic is allowed (Unity Transport uses UDP)
* **Join Code Validity**: Join codes expire after a timeout period (typically 10 minutes)
* **Package Installation**: Verify Unity Netcode for GameObjects is properly installed

{% hint style="info" %}
Use Unity Profiler → Networking tab to monitor connection quality and bandwidth usage during multiplayer sessions. See [Unity Netcode Profiler documentation](https://docs.unity3d.com/Packages/com.unity.netcode.gameobjects@latest/index.html?subfolder=/manual/troubleshooting/profiler-tools.html) for detailed analysis.
{% endhint %}

### Synchronization Problems

* **Network Prefabs**: Verify all automation components have corresponding network prefabs
* **Scene Path Resolution**: Check that GameObject hierarchy matches between clients
* **Authority Conflicts**: Ensure only host modifies authoritative data
* **Physics Conflicts**: Verify client MUs are using kinematic rigidbodies

### Performance Issues

* **Bandwidth Usage**: Monitor network traffic in Unity Profiler
* **Update Frequency**: Reduce FixedUpdate rate if needed
* **Object Count**: Limit number of synchronized objects
* **Connection Stability**: Test with realistic network conditions

## API Integration

### Custom Component Synchronization

To synchronize custom automation components:

```csharp
public class CustomNetworkComponent : NetworkBehaviour
{
    [SerializeField] private NetworkVariable<float> customValue = new NetworkVariable<float>();
    
    public override void OnNetworkSpawn()
    {
        if (IsHost)
        {
            // Initialize host-controlled values
            customValue.Value = GetComponentValue();
        }
    }
    
    private void FixedUpdate()
    {
        if (IsHost)
        {
            // Update network variable when value changes
            float newValue = GetComponentValue();
            if (Math.Abs(customValue.Value - newValue) > 0.001f)
            {
                customValue.Value = newValue;
            }
        }
        else
        {
            // Apply received values on clients
            ApplyNetworkValue(customValue.Value);
        }
    }
}
```

## See Also

* [Industrial Metaverse](https://github.com/game4automation/doc/blob/doc/extensions/realvirtual.io-industrial-metaverse) - VR/AR setup and configuration
* [Drive Components](/components-and-scripts/motion/drive.md) - Synchronized drive systems
* [Sensors](/components-and-scripts/sensors.md) - Networked sensor components
* [MU System](/components-and-scripts/mu-movable-unit.md) - Moving unit synchronization
* [Interfaces](https://github.com/game4automation/doc/blob/doc/components-and-scripts/interfaces/README.md) - PLC communication in multiplayer scenarios


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://doc.realvirtual.io/components-and-scripts/multiplayer-pro.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.