ContraModLoader is an independent, open-source mod-loader core for WorldBox. It discovers mods in separate folders, resolves their declared dependencies, initializes them in order, and shuts them down in reverse order.
- A small .NET Standard 2.0 API that mod assemblies can reference.
mod.jsondiscovery and validation.- Deterministic dependency ordering and per-mod error reporting.
- Mod lifecycle hooks, a per-mod writable data directory, and a logger interface.
- A mod registry for direct API access and a typed message bus for mod-to-mod events.
ContraModLoader is inspired by the public mod-loader concepts used by NeoModLoader, but this project has its own implementation and API.
The WorldBox entry-point build requires game files. The WorldBox plugin project references
UnityEngine.CoreModule.dllfrom your local game installation. Running mods that call WorldBox APIs also requires those mods to reference matching game assemblies.
Install the .NET SDK, then build and test the independent core:
dotnet build src/ContraModLoader/ContraModLoader.csproj
dotnet test tests/ContraModLoader.Tests/ContraModLoader.Tests.csprojThe loader core targets .NET Standard 2.0. The tests target .NET 10.
-
Use the game's
worldbox_Data/Managedfolder, which containsUnityEngine.CoreModule.dll, and pass its path:dotnet build src/ContraModLoader.WorldBox/ContraModLoader.WorldBox.csproj -p:WorldBoxManagedDir="/path/to/WorldBox/worldbox_Data/Managed" -
Copy
ContraModLoader.dllfromsrc/ContraModLoader.WorldBox/bin/Debug/net472/intoworldbox_Data/StreamingAssets/mods/. The loader core is bundled into this plugin DLL; do not copy a separate core DLL. -
Enable WorldBox's experimental mod mode and start the game.
The Unity WorldBoxMod component creates or verifies these folders beside worldbox.exe when the game loads the plugin:
ContraModLoader/
├── Mods/
├── Config/
└── Logs/
Build the plugin against the same WorldBox version you will run. The plugin build can be checked locally, but actual loading inside WorldBox must be tested in the game. If WorldBox reports that it cannot load the plugin, check the game log and confirm its mod loader supports a MonoBehaviour entry type in this location.
The local Unity reference DLL is ignored by Git and should not be included in releases.
On first start, the loader also creates ContraModLoader/Config/settings.json:
{
"loadMods": true,
"enableInterModMessaging": true
}Set loadMods to false to skip loading mods at startup. Set enableInterModMessaging to false to disable the message bus. Existing settings are preserved when the game starts.
Place each mod in its own subfolder of ContraModLoader/Mods/, with its mod.json and compiled entry assembly. Example:
{
"id": "example.hello",
"name": "Hello WorldBox",
"version": "1.0.0",
"entryAssembly": "HelloWorldBox.dll",
"entryType": "HelloWorldBox.HelloMod",
"dependencies": []
}The entry type must be a public, parameterless class implementing ContraModLoader.IMod:
using ContraModLoader;
public sealed class HelloMod : IMod
{
public void OnInitialize(ModContext context)
{
context.Logger.Info($"Hello from {context.Manifest.Name}");
}
public void OnShutdown()
{
}
}Use another mod's ID in dependencies to ensure it initializes first; IDs are matched case-insensitively. Mod data is stored in <mods-directory>/.data/<mod-id>. Invalid manifests, missing dependencies, load failures, and lifecycle exceptions are reported through the logger. Mods are ordinary managed assemblies and are not sandboxed.
Each mod receives ModContext during OnInitialize.
Use the registry for direct calls through an interface both mods reference:
if (context.Mods.TryGetMod<IWeatherApi>("example.weather", out var weather))
{
weather.SetRain(true);
}Use the message bus for typed, synchronous events:
private IDisposable _subscription;
public void OnInitialize(ModContext context)
{
_subscription = context.Messages.Subscribe<string>(
"example.weather.changed",
message => context.Logger.Info(message));
context.Messages.Publish("example.weather.changed", "Rain started");
}
public void OnShutdown()
{
_subscription?.Dispose();
}Message topic names are case-sensitive. Subscriptions are automatically removed when their owning mod unloads; disposing them yourself during shutdown is still recommended. Each subscriber runs synchronously on the publishing thread. Subscriber exceptions are logged and do not prevent other subscribers from receiving the message.
The sample mod is in samples/Speed100Mod. It implements IUpdatableMod, whose OnUpdate() is called on Unity's main thread once per frame, registers a custom WorldTimeScaleAsset, then selects it when F5 is pressed.
First make sure the loader plugin is built and installed (it now forwards frame updates), following the plugin instructions above. Then build the sample against the game's managed assemblies:
dotnet build samples/Speed100Mod/Speed100Mod.csproj -p:WorldBoxManagedDir="/path/to/WorldBox/worldbox_Data/Managed"Copy mod.json and Speed100Mod.dll from samples/Speed100Mod/bin/Debug/net472/ into a new mod folder:
<WorldBox game root>/ContraModLoader/Mods/Speed100Mod/
├── mod.json
└── Speed100Mod.dll
Restart WorldBox, load a world, and press F5. The mod creates a 100x time-scale using the game's x5 settings for tick counts and visual properties. The game may run slowly or become unresponsive at this speed.
This project is distributed under the Boost Software License 1.0; see LICENSE.