> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marioded.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect your network

> Connect gameplay servers, a selection lobby, and replay servers through your proxy.

# Connect your network

Give players one place to choose a recording, then send them to a dedicated replay server. This guide connects **recorder → shared storage → lobby → player**.

> [!NOTE]
>
> **Only need one server?** Skip this page. Everything here is for multi-server setups with a proxy. Get local recording and playback working first.

## Before you begin

* A working local recording/playback test.
* A proxy with stable backend names, such as `replay-lobby` and `replay-1`.
* Shared SQL replay storage reachable by every role.

> [!NOTE]
>
> **Two systems, two jobs:** SQL stores your replay archive. Availability tells the lobby which replay servers are online; it can use that SQL database or Redis.

## Architecture

```mermaid theme={null}
flowchart LR
  Recorder[Gameplay server: Recorder] --> Storage[(Shared replay storage)]
  Lobby[Selection server: Lobby] -->|Read catalog| Storage
  Player[Replay server: Player] -->|Load events and terrain| Storage
  Lobby <-->|Selection and liveness| Availability[(SQL or Redis availability)]
  Player <-->|Heartbeat and handoff| Availability
  Lobby -->|Proxy transfer| Player
```

Two separate systems must be shared:

1. **Replay storage:** typically one SQL database used by recorder, lobby, and player.
2. **Availability:** either the database backend or a shared Redis endpoint used by lobby and player.

Redis contains liveness and short-lived handoffs, not `.rpl` event data or chunk snapshots.

## 1. Configure the proxy

Register your lobby and replay servers under stable proxy names, for example `replay-lobby`, `replay-1`, and `replay-2`. Players must be able to connect to those names through the proxy.

Transfers use the `BungeeCord` plugin-message channel with the `Connect` subchannel. For BungeeCord-compatible proxies, make sure that channel is supported. On Velocity, enable its BungeeCord plugin-message compatibility option where required by your proxy configuration. No separate Reverse proxy plugin is supplied.

Do an ordinary manual proxy transfer first. Fix forwarding/server-registration issues before debugging Reverse's selection flow.

## 2. Share storage

Use the same SQL connection settings on all participating roles. Merge this section into each `config.yml`, retaining the other generated storage fields:

```yaml theme={null}
storage:
  backend: sql
  database:
    type: mariadb
    host: database.internal
    port: 3306
    database: replay
    username: reverse
    password: 'replace-with-your-password'
  fallback-to-spatial: false
```

The example hostname is a placeholder. Create the database and a suitable account yourself. Reverse's backend initializes its schema; it does not provision a database server.

Do not enable local fallback on a worker and expect its private disk to be visible elsewhere. See [storage](https://docs.marioded.com/owners/storage.md).

## 3. Choose availability

Choose **one** backend and use the same choice on the lobby and every replay server.

`sql`, `mongodb` (matching the storage backend you opened) and `redis` are built-in choices opened at startup. Reverse does not discover availability providers from other installed plugins. The API exposes the runtime's existing availability service for integrations, but it is not an instruction to replace or reopen the backend after startup.

> [tab] SQL availability
>
> ### Use your shared database
>
> On the lobby:
>
> ```yaml theme={null}
> network:
>   enabled: true
>   backend: sql
>   node-id: replay-lobby
>   ping-millis: 5000
>   ping-timeout-millis: 15000
> ```
>
> On the first player server, use the same settings but `node-id: replay-1`. On the second use `node-id: replay-2`. Keep the generated `redis` section even when unused.
>
> SQL availability requires SQL storage to have actually opened successfully. `spatial` does not provide a shared SQL availability backend. With `storage.backend: mongodb`, use `backend: mongodb` instead; it reuses that backend's availability collections.

> [tab] Redis availability
>
> ### Use Redis for coordination
>
> Keep shared SQL replay storage, but change the network backend on both lobby and player:
>
> ```yaml theme={null}
> network:
>   enabled: true
>   backend: redis
>   node-id: replay-1
>   ping-millis: 5000
>   ping-timeout-millis: 15000
>   redis:
>     uri: redis://redis.internal:6379/0
>     command-timeout-millis: 5000
> ```
>
> Use the lobby's own proxy name on the lobby. All nodes must address the same Redis service/database. Protect the endpoint and credentials as you would any shared backend.

## 4. Restart and test

1. Restart backend servers after changing storage/network settings.
2. Make a test recording and wait for save completion.
3. Join the lobby as an owner or administrator.
4. Open `/reverseview` and select the replay.
5. Confirm arrival starts playback on the selected replay server.
6. Stop playback and confirm return to the origin lobby.
7. Repeat with a nonowner and check access denial.

> [!TIP]
>
> **Ready to use:** a viewer can select a saved recording in the lobby, arrive on a replay server, watch it, and return to the original lobby after stopping.

## How selection works

Player nodes publish heartbeats. The lobby queries fresh nodes in heartbeat order and chooses the first. It writes a pending selection for the target node/viewer and sends a proxy transfer. The player consumes that selection on join and loads the replay.

The lobby does not render scenes or read terrain through a chunk facade. Its Watch action only authorizes the catalog selection and dispatches through the proxy. Chunk delivery belongs to the player server.

Pending selections expire after five minutes and are consumed once. A successful dispatch result means the selection was written and a transfer message sent; it is not confirmation that the proxy completed the connection or the client finished loading.

Availability is not a queue, capacity reservation, or least-loaded matchmaking system. Several viewers can be sent to the same replayer. Duplicate requests by one viewer are guarded while pending.

## Common mistakes

* A node ID is a hostname, UUID, or display title instead of the proxy's server name.
* Lobby and player use different Redis databases or SQL databases.
* One node fell back to local storage at startup.
* A replay template is present on the recorder but not on the player.
* A player worker was switched to network mode without restarting.
* A heartbeat is present, but the proxy cannot reach that server.

Something still not lining up? Work through the [troubleshooting guide](https://docs.marioded.com/owners/troubleshooting.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.