> ## 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.

# Configure Reverse

> Find the right file, understand each setting, and know when a restart is needed.

# Configure Reverse

Reverse generates a full, commented template the first time it starts. Pick the file for the plugin you are configuring:

| Plugin | Main settings | Text and display |
| - | - | - |
| Recorder | `plugins/reverse-recorder/config.yml` | `messages.yml` |
| Player | `plugins/reverse-player/config.yml` | `messages.yml`, `layout.yml`, `gui.yml` |
| Lobby | `plugins/reverse-lobby/config.yml` | `messages.yml`, `gui.yml` |

Each role also reads a separate `license.yml` in its own data folder. Its `license-key` is used during startup, not refreshed by reload. See [activation](https://docs.marioded.com/owners/installation.md#activation).

> [!NOTE]
>
> **Merge examples into the generated file.** The snippets below show individual sections, not complete replacement configurations. Keep the other generated sections.

Reverse generates YAML using lower-kebab-case field names. Edit the generated files for your build, retain unknown-to-you sections, and quote text containing `<...>`, `:`, `#`, or other YAML-sensitive characters.

> [!TIP]
>
> **New to this page?** You do not need to change everything at once. Start with the [reload vs. restart table](#which-changes-need-a-restart) at the bottom, then edit one section at a time and reload.

## Shared storage section

Every role has `storage` in `config.yml`:

```yaml theme={null}
storage:
  backend: spatial
  recordings-folder: ''
  database:
    type: mysql
    host: 127.0.0.1
    port: 3306
    database: replay
    username: root
    password: ''
    sqlite-file: replay.db
    pool:
      maximum-pool-size: 10
      minimum-idle: 2
      connection-timeout-ms: 10000
  mongodb:
    uri: mongodb://localhost:27017
    database: reverse
    workers: 4
    timeout-millis: 5000
  cache:
    max-memory-chunks: 4096
    max-memory-manifests: 256
    max-memory-replays: 32
  slime:
    loaders: [file, mysql, mongodb]
  fallback-to-spatial: true
```

| Setting | Purpose |
| - | - |
| `backend` | Built-in, case-sensitive id: `spatial` for local files, `sql` for SQL, or `mongodb` for MongoDB/GridFS replay data and terrain. Unknown ids fail startup and list the known ids. |
| `recordings-folder` | Where recordings live on disk. Empty uses `plugins/recordings`. A relative path is resolved against the plugin data folder's parent; an absolute path is used as-is. |
| `database.type` | `mysql`, `mariadb`, `postgresql` (`postgres` is also recognized), or `sqlite`. |
| `database.host`, `port` | SQL endpoint. Set PostgreSQL's port explicitly, normally 5432. |
| `database.database`, `username`, `password` | Schema/database and credentials. The default root account is a template, not a recommended production account. |
| `database.sqlite-file` | SQLite file path resolved against the selected recordings folder; an absolute path is used as-is. Default: `plugins/recordings/replay.db`. |
| `database.pool.*` | Pool limits and acquisition timeout; SQLite resolves to a single-connection pool. |
| `mongodb.uri`, `database` | MongoDB connection URI and shared database, used only by `backend: mongodb`. MongoDB 6.0+ is required. |
| `mongodb.workers` | Blocking storage worker count, 1–16; default 4. |
| `mongodb.timeout-millis` | Connection, server selection and socket timeout; default 5000 ms. |
| `cache.*` | Limits for data kept in memory to speed up access. These do not delete saved recordings. |
| `slime.loaders` | Ordered names of loaders already configured in SWM. This is not Reverse's SQL connection configuration. |
| `fallback-to-spatial` | Allows startup to choose local storage if SQL or MongoDB creation fails. It is not live replication or an ongoing failover system. |

> [!WARNING]
>
> **Using shared storage?** Prefer `fallback-to-spatial: false`. A node falling back to private local files cannot see the shared SQL/MongoDB catalog.

## Recorder settings

```yaml theme={null}
adapter: packetevents
chunk-capture-radius: 4
```

* `adapter` selects a protocol capture backend shipped with this build. The current built-in id is `packetevents`. An unknown id fails startup with the known ids; installing another plugin does not register an adapter. Changing it requires restart.
* `chunk-capture-radius` controls the loaded-chunk capture radius around active players. Radius 4 describes a 9×9 horizontal area. It does not mean Reverse will load or generate every chunk within that square. See [recorder capture](https://docs.marioded.com/owners/recorder.md).

## Player settings

```yaml theme={null}
adapter: packetevents
playback-world-name: replay
hide-real-players: true
open-access: false
```

* `adapter` selects a protocol playback backend shipped with this build. The current built-in id is `packetevents`. Selection is case-sensitive, and an unknown id fails startup with the known ids. Changing it requires restart. See [protocol adapters](https://docs.marioded.com/api/adapters.md) for the implementation boundary.
* `playback-world-name` names the shared void playback world. Use a dedicated name, not a gameplay world you expect Reverse to reconstruct.
* `hide-real-players` controls extra cross-world player hiding. Same-world players outside a viewer's replay session are already hidden. Changing it requires restart.
* `open-access` gives every viewer the catalog's administrative access policy. This includes management operations, not just viewing. Keep it false for owner-private recordings.
* `gui` configures standalone catalog/details menus. These are initialized only when availability is disabled at startup.

## Network settings: player and lobby

```yaml theme={null}
network:
  enabled: false
  backend: sql
  node-id: player-1
  ping-millis: 5000
  ping-timeout-millis: 15000
  redis:
    uri: redis://localhost:6379/0
    command-timeout-millis: 5000
```

The lobby's generated node ID defaults to `lobby-1` instead. Recorder does not have this network section.

| Setting | Rules |
| - | - |
| `enabled` | Enable availability and cross-server handoff. Default false. |
| `backend` | Built-in id matching the selected storage backend (`sql` or `mongodb`), or the independent `redis`. The SQL/MongoDB choice requires that storage backend to have actually opened. |
| `node-id` | A proxy server name, unique for each replay node; lobby uses its own name for return transfers. |
| `ping-millis` | Positive heartbeat interval, in milliseconds. |
| `ping-timeout-millis` | Must be strictly greater than twice the interval. |
| `redis.uri` | Shared Redis endpoint/database, optionally including credentials/TLS syntax supported by the Redis client. |
| `redis.command-timeout-millis` | Positive command timeout. |

Backend and node identifiers accept 1–64 characters from `A–Z`, `a–z`, `0–9`, `_`, `.`, and `-`.

Redis coordinates nodes; it does not replace SQL or disk replay storage. See the complete [network setup](https://docs.marioded.com/owners/network.md).

Availability is opened once at startup from the built-in SQL/Redis backends. Installing a third-party plugin does not inject another configured backend. The player and lobby still expose their existing availability service through the API; integrations borrow that service rather than reopen or replace the running backend.

## Lobby settings

The lobby keeps `storage`, `network`, and `open-access` in `config.yml`. Text lives in `messages.yml`, and menus live in `gui.yml`. Its `open-access` policy has the same administrative implications as the player's. It does not have a player playback-world or recorder capture-radius section.

## Messages, menus, and display

* [Menus](https://docs.marioded.com/owners/menus.md) documents `catalog` and `details` in `gui.yml`, item fields, actions, visibility states, and placeholders.
* [Display](https://docs.marioded.com/owners/display.md) documents `layout.yml`, HUD, sidebar, and MiniMessage.
* Every role's messages live in `messages.yml`. Player/recorder retain their role sections; lobby message keys are at the root.

Player and lobby create missing files without rewriting existing ones. To retain custom menus from an older combined configuration, copy the contents of `gui` into `gui.yml` without the `gui:` wrapper. For lobby messages, copy the contents of `messages` into `messages.yml` without the `messages:` wrapper. Embedded sections in `config.yml` are no longer read.

## Which changes need a restart?

| Change | Apply using |
| - | - |
| Message text in any role | Role's reload command |
| Player hotbar, HUD, scoreboard | `/reverseplayer reload` |
| Player/lobby catalog menu settings | Role's reload command |
| Player/lobby open-access policy | Role's reload command |
| Recorder capture radius | `/reverserecorder reload` |
| Storage backend, recordings folder, SQL credentials/pool, caches, Slime loaders | Full server restart |
| Availability backend, node ID, Redis connection, heartbeat timing | Full server restart |
| Protocol adapter id (`adapter`) | Full server restart |
| License key (`license.yml`) | Full server restart |
| Playback world, real-player hiding policy | Full server restart |

Reload handlers update selected runtime settings. Do not assume a changed YAML value recreated an existing database pool or network backend. See [operations](https://docs.marioded.com/owners/operations.md).

Changing `storage.recordings-folder` does not move or import recordings. Stop the affected servers and transfer the complete dataset yourself before restarting with the new path; see [storage and backups](https://docs.marioded.com/owners/storage.md).

The configuration generated by your installed release is the full, authoritative list of available settings.

## Customize the experience

* Style the playback screen in [Hotbar, HUD, and messages](https://docs.marioded.com/owners/display.md).
* Restyle the catalog and details menus in [Catalog menus](https://docs.marioded.com/owners/menus.md).


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