Plugin unloading
Plugins can be unloaded while the game is running (disabling a mod, changing the mod list or updating a mod doesn’t require restarting Barotrauma). This page explains what the game does when a plugin is unloaded, why a plugin sometimes doesn’t unload completely, and how to write a plugin that unloads cleanly.
What the game does
When a plugin is unloaded, the game does the following:
- calls
Dispose()on the plugin’sIBarotraumaPlugin, - clears everything the plugin registered through the plugin services (hooks, item components, extra fields, and so on),
- asks .NET to unload the plugin’s assembly load context, and
- disposes the services that hold on to things for the plugin, which includes undoing the Harmony patches made through the service.
Step 3 only starts the unload. .NET finishes it later, once nothing references the plugin’s code anymore, so the services disposed in step 4 still get cleaned up before then.
All of this is tracked per plugin so that none of it has to be cleaned up by hand. That is the reason to use the services instead of reaching into the game’s internals, since anything registered through a service is removed by the game for you.
Plugins don’t always unload
Plugins are loaded into a collectible assembly load context. Calling Unload() on a collectible context doesn’t remove the assembly by itself. It only marks it as unloadable, and .NET actually frees it later, once the garbage collector finds that nothing is referencing it any more.
If something in the game, or in the plugin itself, still holds a reference to the plugin, the assembly stays in memory and the plugin is stuck half-unloaded. For example, if the game kept a list of objects and a plugin added an instance of its own class to that list, the game would then have an object whose type belongs to an assembly that is supposed to be gone, so the runtime keeps the assembly loaded. This is why all the things a plugin registers are kept together and cleared when it is unloaded.
How you can tell an unload was successful
After a plugin is unloaded the game waits briefly, then forces garbage collections a few times and checks whether the assembly is gone. if the console prints a green message, “Plugin was successfully unloaded after N seconds”, then the unload was successful. if The game prints a warning: “the plugin could not be fully unloaded and is still active in memory after cleanup attempts”, it means immediate unloading has failed.
Writing a plugin that unloads cleanly
The unloading problems come from references that outlive the plugin. The plugin services deal with most of them for you, so the rest is up to the plugin’s own code:
- Clean up in
Dispose(). Undo whateverInit()and the rest of the plugin did that the services don’t track. - Unsubscribe from events. If you subscribe to an event on something that outlives the plugin, such as a static event or an event on a game object, the event’s delegate keeps your assembly alive. Unsubscribe in
Dispose(). - Don’t put your objects in the game’s collections. Anything you add to a list, dictionary or cache owned by the game, or by a library, must be removed again.
- Be careful with statics. Static fields that are filled with game objects, or that other code can reach, are a common way to leak. Clear them in
Dispose(). - Use the services. Register hooks, item components and so on through the plugin services rather than by patching or by storing your own references into the game.
- Use the Harmony service. Patches created via
IHarmonyProviderare removed automatically when the plugin unloads. If you create your ownHarmonyinstance, you must callUnpatchSelf()on it yourself. - Store per-object data with extra fields. Instead of keeping your own dictionary keyed by game objects, use the extra fields the game keeps per plugin. They are cleared with the plugin.
- Test unloading. Enable and disable your mod a few times while testing and check that the console shows the success message each time. The warning is much easier to track down while you still remember what you changed.
When a plugin won’t unload
If the not-unloaded warning shows up for your mod:
- Check that your own code isn’t the cause, using the list above. Event subscriptions and entries left in game collections are the most common causes.
- Try disabling the mod, waiting a few seconds, and checking the console again. Some plugins do unload slightly later.
- If you suspect the game is keeping a reference to something the plugin registered, that is a bug in the game and worth reporting, including the console output.
- Restarting the game always unloads the plugin. It’s the safe fallback for players too.