> For the complete documentation index, see [llms.txt](https://docs.marioded.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.marioded.com/keep-things-running/operations.md).

# Operations and performance

Keep recordings healthy, apply changes safely, and understand the main performance costs.

Start with the short checklist below. The later sections explain what needs a restart, what affects performance, and what information helps when a problem occurs.

## Your routine checklist

* [ ] Check save failures and degraded-terrain warnings, not just command success messages.
* [ ] Monitor free disk space or database size, heap use, server tick performance, and backend latency.
* [ ] Keep role jars and API integrations on matching builds.
* [ ] Verify that gameplay, lobby, and player nodes actually use the intended storage backend.
* [ ] On networks, verify both replay-node heartbeats and real proxy transfers.

## Reload versus restart

Use the role-specific commands for text, display, menus, open-access policy, and recorder radius. These update a selected subset of runtime state. They do not reconstruct SQL pools, swap storage providers, rename an existing playback world, or reconnect availability using new settings.

Perform a clean server restart for infrastructure changes. Do not use a generic plugin hot-reloader to unload and replace these runtimes while sessions, packet listeners, or downloads are active.

Configuration preparation may reject invalid input. Correct the reported field, retain a backup of your previous working configuration, and reload again. Treat success as “the supported live settings were applied,” not “every YAML field now changed the running process.”

## Stop gracefully

For planned maintenance:

1. Prevent new matches/recordings and new viewing requests.
2. Stop active recordings using their session IDs and wait for save completion.
3. Stop playback sessions or allow them to finish.
4. Stop the server cleanly.
5. Back up the storage dataset before upgrades or backend changes.

Recorder shutdown attempts to drain pending saves. That is a final cleanup path, not a substitute for waiting before terminating a process or container. Forced termination can interrupt writes or leave a scene incomplete.

## Capture cost

Capture cost grows with loaded terrain, entities, activity, and the number of independent recording sessions. A radius of `r` describes `(2r+1)²` horizontal chunk columns around a capture center, before overlap and actual chunk availability.

Ways to keep capture bounded:

* Use a dedicated arena world instead of a huge always-loaded lobby.
* Use recording bounds and participant sets through your minigame integration.
* Avoid unnecessarily large loaded areas before starting.
* Do not create duplicate sessions for the same match unless you need independent recordings.

## Playback cost

Recordings take memory while being watched, and the loaded scene can be much larger than its saved file. Long or very busy recordings can make seeking slower. Test realistic matches before deciding how many simultaneous viewers your server can comfortably support.

Every viewer in one session shares the playback cursor. Starting separate sessions gives independence but adds session state, scene resynchronization, and packet work. High speed can process more replay ticks per server tick and should be load-tested with realistic recordings.

## Database and cache tuning

Leave database connection limits at their defaults unless you are investigating a measured database bottleneck. Increasing them does not fix an unreachable database or incorrect settings.

Cache count settings are not memory quotas. Increase loaded-replay caching cautiously; large event streams can dominate heap usage. There is no owner-facing setting promising an overall memory cap for the entire plugin.

## Access administration

Keep `open-access: false` for private recordings and assign owners correctly at recording start. Enabling open access makes everyone a catalog administrator, including management actions offered by menus/commands.

Use separate test accounts for owners, nonowners, and administrators. Verify permissions on lobby and player independently; a permission granted on a gameplay server is not automatically synchronized to a replay server.

## Support information to collect

When reporting a problem, provide server distribution/version, Java version, Reverse build, installed role(s), storage/availability types, whether templates are used, the replay/session ID, exact reproduction commands, and the first related stack trace. Redact database passwords, Redis credentials, and license-bearing data.

{% content-ref url="/pages/1ClQXDROKUIqEESqA9ox" %}
[Troubleshooting](/keep-things-running/troubleshooting.md)
{% endcontent-ref %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.marioded.com/keep-things-running/operations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.