Submarine Black Box - Advanced Replay System [WIP]

Some rounds end with everyone asking the same question: “What actually happened?”

Submarine Black Box is a black-box recorder for Barotrauma. It stores a round in its own .btr replay format and lets you inspect it later: move through time, follow players, read recorded chat and server events, listen to voice, inspect inventories and investigate a disaster after the live-round chaos is over.

This is not a video recorder. A replay is reconstructed from recorded world states and events, so it can be explored much more freely than a normal video capture.

Recording

• Authoritative server-side recording and local singleplayer recording.
• Optional local multiplayer client-view recording.
• 1-20 world snapshots per second. Cursor, camera and part of the player telemetry use a separate higher-rate track.
• Submarines, characters, items, hulls, structures, lighting and environment state.
• Health, afflictions, limbs, held and selected items.
• Inventories, containers, wiring and device interactions.
• Chat, voice packets, sounds, particles and explosions.
• Observer cameras, cursor, aim/view direction and player interaction data.
• Server journal, deaths, spawns and other timeline events.
• Round mod list, seed, game mode, missions and replay metadata.

Replay viewer

• Dedicated Replays browser with Local and Server replays.
• Pause, timeline seeking and configurable 5/10/15/20/25/30 second seek steps.
• 0.25x, 0.5x, 1x, 2x and 4x playback speeds.
• Free camera, player/submarine follow and recorded observer cameras.
• Player panel, context actions and visibility filters.
• Recorded cursor and player-POV elements, including object highlighting and some interaction UI when that data was available to the recorder.
• Recorded inventories, containers, items, wiring and state of supported devices.
• Recorded chat and server journal with jump-to-time actions.
• Voice archive, per-player volume and optional subtitles.
• Extra analysis options such as lighting/LOS, X-ray and hiding bots, creatures or AFK players.

Server and admin features

• Enable/disable server replay recording.
• Share server replays with players.
• Approval mode: a player requests a replay and a host/admin approves or rejects the download.
• Optional automatic distribution without manual approval.
• Admin replay deletion and replay storage limits.
• Server-only mode: the server can record replays without making Black Box a mandatory client mod.
• Security Guard compatibility for relevant journal information.
• Seed Preview for generating and inspecting a level before the round starts.

Simplified Replay

Simplified Replay is an experimental current-round viewer for hosts and admins that avoids a full world reconstruction.

It is still heavily in development and currently very buggy. Do not treat it as a replacement for the normal saved .btr viewer.

Replay files and sharing

Replays are normal .btr files. You can copy, archive and send them to other people manually. For modded rounds, the recipient should preferably have the same content mods that were used when the replay was recorded.

Black Box creates a Replay directory in the root/working directory of the running game or dedicated server:

• Replay/Local/ - local client replays.
• Replay/Server/ - server replays and downloaded server recordings.
• Replay/Logs/ - Black Box diagnostic logs.

Typical Windows client installation: ...\Steam\steamapps\common\Barotrauma\Replay\

Separate Windows Dedicated Server: ...\Steam\steamapps\common\Barotrauma Dedicated Server\Replay\

Typical Linux Steam installation: ~/.local/share/Steam/steamapps/common/Barotrauma/Replay/

Linux Dedicated Server installed through SteamCMD is commonly located at: ~/Steam/steamapps/common/Barotrauma Dedicated Server/Replay/

If you use a custom SteamCMD force_install_dir, Docker, LinuxGSM or a hosting panel, the Replay directory is created inside the actual Barotrauma Dedicated Server working directory.

Diagnostics and bug reports

The mod is still in active development. If a replay breaks, something is missing, UI behaves incorrectly or the game reports an error, please include the newest Black Box session log.

Logs are stored as: Replay/Logs/SubmarineBlackBox_vX.XX.XX_YYYY-MM-DD_HH-mm-ss.log

Windows usually: ...\Barotrauma\Replay\Logs\

Linux dedicated server: <server root/working directory>/Replay/Logs/

If the problem is specific to one replay, include the related .btr file when possible. When diagnostics are enabled, automatic Black Box diagnostic messages are written to the log file instead of flooding the in-game console.

Voice, subtitles and privacy

Black Box can store text and voice chat. Automatic subtitles may be generated while loading a replay when a compatible Windows speech recognizer is installed.

Important: if you use this mod on a public server, inform players that text/voice may be recorded and follow your platform rules and local laws.

Please keep in mind

• The mod is still WIP. The .btr format, UI and individual features may change.
• A replay is a reconstruction, not a deterministic engine demo and not a video.
• Older replay files may not contain data added by newer mod versions.
• A multiplayer client-view replay cannot record data the server never replicated to that client.
• LuaCs for Barotrauma is required.

❤️ Support Development

If you enjoy my mods and want to support future updates, fixes, and new features, you can leave a donation on Boosty.

Any amount helps me spend more time developing, maintaining, and improving my mods.