Better Battle Report (BBR) User Guide


Better Battle Report, or BBR, is a mod that records replays of skirmish games and saves them for later viewing. Originally started and still hosted by AlexBay, it is now developed and maintained by me (ShadowLotus). I can be contacted in the Nebulous Developer Discord for questions, issues, requests, or general modding inquiries.

The Mod

The BBR Mod is available here. It is enabled through Nebulous, and is a client-side only mod, meaning when you are in a lobby with it enabled the game will not force others to download the mod. Recording a match will begin automatically (as long as you have enabled the mod). Saving the BBR file (extension .bbr) will NOT happen automatically, but instead when you press the "Export Battle Report" button in the debriefing lobby.

The Viewer

The BBR Viewer is a standalone piece of software that interprets and displays .bbr files with full playback. There is a web version of the viewer here[] and a downloadable desktop version for both Linux and Windows here here[] .

How To Use

1. Subscribe to the mod

2. Enable the mod in the 'Mods' section of the game's main menu

3. BBR will automatically record any skirmish game you play

4. Once a game is complete (draw/drop/leaving early are currently not supported by BBR), click on the "Export Battle Report" button in the debriefing lobby to begin saving your recording. It will be saved to the same directory as the normal battle report file (../steamapps/common/Nebulous/Saves/SkirmishReports) as a .bbr file. This process may take a couple minutes, and you should get a pop up message when it is complete. If the .bbr file shows a size of 0, it is not done writing.

5. The .bbr file can be viewed either with the webviewer, or the downloadable desktop viewer

Things Wot BBR Do

Records positions of the following objects (as they are implemented in vanilla):



Collidable Terrain (terrain that does not have a collider in-game will not be captured)




Non-Physical munitions (Defender/Pavise)

Reactor Blooms Records the terrain of most modded maps. It has been tested on most maps available at time of writing. New maps will be tested as released, and issues fixed as they arise.

Calculates the score at any given time based on the rules of the scenario (CTF and Station Capture are not implemented, and are very low priority as their scoring is much easier to intuit).

.bbr files will be exported to the same place as base game battle reports (`..\Steam\steamapps\common\Nebulous\Saves\SkirmishReports`) with the same name as the associated battle report by clicking the 'Export Battle Report' button in the debriefing lobby.

Things Wot BBR D'ain't

BBR is not a game. It does not have game logic. It doesn't care about collisions, or that a missile and a ship are different things, it is just a visualization tool for recorded data. A video player doesn't care what the content of the video is, it just displays it. BBR is the same: it displays the data without doing any sort of interpretation.

BBR is a passion project, started by one person and currently being built by another. It's not perfect. There will be bugs, there will be design choices that you may not agree with, and news/development may be slow at times. That said: BBR is also both open source and a client-side, code-only mod. The viewer is a completely standalone piece of software. If there is something you don't like, want to change, or want to fix, you can simply build your own local copy of either or both.

Some Things Wot BBR Will Do But Ain't Done Yet (In No Particular Order)

Mod support will be fleshed out as there is dev time available, but vanilla compatibility and completeness will always take priority.

Saving partial reports for game drops/draws

Integrate base game battle reports

Selection of objects and detailed readouts of information about said objects (missile and ship configurations, status conditions, damage, etc.)

Viewer settings

Sensor web visualization, target locks

RCS/Signature visualization



PD net visualization

Projected threat/zones of control visualization

Derived stats (ship movement/death heatmaps, missile heatmaps, first blood, map side winrates, etc.) (this is honestly more of a separate project but it bears mentioning)

For Modders

The way BBR captures information is by patching specific methods with Harmony and saving relevant information. Each vanilla element has had it's own code path built, and if a modded component changes or avoids the specific function used, or is an entirely new system, BBR will not know what to do with it until a specific code path is built for it. A lot of the time of building those systems is figuring out how to get the needed data. Showing me how a given system works, or contributing a capture method directly will bring BBR mod support faster. It is always helpful just to catalog what doesn't work so I have a list of things to work on.

BBR is open source, and you are more than welcome to look through, contribute bug-fixes, or new capture methods. Just let me know in the Discord and we'll talk.

For Dedicated Server Operators

BBR Provides C# methods for dedicated servers to interact with report data:

void BBRMod.BBRMod.DedicatedServerExport(string fileName, string filePath = null, bool debug = false) will write the .bbr file of the most recent game to the specified place with the specified name. If `filePath` is passed as null it will save to the default skirmish report location. If `debug` is passed as true BBR will also output an uncompressed .json file that contains the same information as the .bbr file. It is helpful for debugging if there is an issue, or for reading the data raw if you so wish to do so, but it will be 4-8 times larger on average.

If your server already saves battle reports by calling `Game.Reports.FullAfterActionReport.Export(string filename)` then .bbr files will automatically be written to the same place with the same filename.

bool BBRMod.BBRMod.IsWritingReport() can be used to check if the server is in the process of serializing/writing the report file.

bool BBRMod.BBRMod.IsReportReady() will return false if the report has not been requested, or has not finished being serialized/written.

BBR will start automatically serializing a `byte[]` after Game.SkirmishDebriefingLobbyController.Start() finishes running. If this does not happen and you want the report as a `byte[]`, you can use void BBRMod.BBRMod.ForceStartSerialization() to manually initiate the process.

byte[] BBRMod.BBRMod.GetReportBytes() will return the `byte[]` containing the compressed binary .bbr file in memory if you wish to do something with it like sending it to another server before writing. If called when a report is not ready or while the Recorder is still running it will warn you as such and return an empty array.

void BBRMod.BBRMod.ForceHaltSerialization() will immediately halt any data serialization/writing and clear all data.

Bug Reports

If you experience an issue or bug with BBR, you may let me (ShadowLotus) know in the Discord, or submit an issue ticket here[]


More NEBULOUS: Fleet Command guilds