Skip to content

About

ModLoader For WorldBox | ACCES RELEASES FOR MOD!

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 

Repository files navigation

ContraModLoader

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.

What is included

  • A small .NET Standard 2.0 API that mod assemblies can reference.
  • mod.json discovery 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.dll from your local game installation. Running mods that call WorldBox APIs also requires those mods to reference matching game assemblies.

Build and test

Install the .NET SDK, then build and test the independent core:

dotnet build src/ContraModLoader/ContraModLoader.csproj
dotnet test tests/ContraModLoader.Tests/ContraModLoader.Tests.csproj

The loader core targets .NET Standard 2.0. The tests target .NET 10.

Build and install the WorldBox plugin

  1. Use the game's worldbox_Data/Managed folder, which contains UnityEngine.CoreModule.dll, and pass its path:

    dotnet build src/ContraModLoader.WorldBox/ContraModLoader.WorldBox.csproj -p:WorldBoxManagedDir="/path/to/WorldBox/worldbox_Data/Managed"
  2. Copy ContraModLoader.dll from src/ContraModLoader.WorldBox/bin/Debug/net472/ into worldbox_Data/StreamingAssets/mods/. The loader core is bundled into this plugin DLL; do not copy a separate core DLL.

  3. 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.

Mod format

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.

Mod-to-mod communication

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.

Example: press F5 for 100x speed

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.

License

This project is distributed under the Boost Software License 1.0; see LICENSE.

About

ModLoader For WorldBox | ACCES RELEASES FOR MOD!

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Contributors