banished3 min read
I made a mod loader for Banished

Banished is a city builder from 2014 that I keep coming back to. It has an official mod kit, but the kit can only change data: the numbers in templates, models, textures. Anything that needs new behaviour, like placing a whole street in one drag or a speed past 10x, is out of reach.
So I wrote BML, a loader that runs real code mods inside the game. It's on GitHub with eight plugins.

How it gets in
The game's runtime DLL imports dinput8.dll for keyboard and mouse input, and Windows looks next to the exe before it looks in System32. So BML is a dinput8.dll. Windows loads it with the game, it passes every DirectInput call on to the real one, and on the side it loads every DLL in a NativeMods folder. Nothing in the game folder is patched. Delete the one file and the game is vanilla again.
Then it has to find its way around a game with no symbols. Two things help. Every class in the engine registers itself by name with a factory, so the names lead to the vtables. And the runtime DLL exports the engine's own API by its C++ names, so BML calls things like ExternalFactory::FindOrLoad or TextElement::SetText directly.
Everything else is addresses in one build of the exe. Before BML writes anything, it checks the bytes it expects at every address. On the GOG build, the 32-bit build or a future patch, it writes why to its log and does nothing.

A plugin
A plugin exports one function, and the loader hands it a small API. Here is roughly how Auto Rebuild works. The game keeps a damaged building in a state machine, waiting for you to press Rebuild, and that state has no update function at all. So the plugin gives it one. This is my code, trimmed.
// the game calls this every tick for each burnt building
bool DamagedUpdate(void*, uint8_t* machine, void*) {
g_damaged.push_back(machine); // not yet, mid tick
return false;
}
// runs after the tick, where the real button acts
void OnFrame(float, void*) {
for (uint8_t* machine : g_damaged)
Rebuild(machine); // the same call as the button
g_damaged.clear();
}The first version rebuilt straight from inside the update, and the game crashed a few seconds in. A citizen later in the same tick still had the ruin's job on their list, looked it up and found nothing. Waiting for the end of the tick fixed it.
The plugins
- Grid Build: shift-drag any building to fill an area with rows of them, two rows sharing each road
- Area Fill: shift-drag a field over rough ground and it fits in what it can
- Replant: shift-drag the Forester Lodge to plant a forest
- Speed: 10x, 50x and 250x
- Auto Rebuild, Farm Limits, Storage Sync and Growth Sync for the smaller stuff

22,000 herbs
My own town got to about 1,900 people and dropped to 4x on the 10x setting. The speed plugin logs how fast the game really runs, and the time per update had doubled in one go. Counting every object on the map by type gave the answer: about 22,000 wild herbs, two thirds of everything in the game. An earlier data change of mine had made herbs spread and never die.
Fixing the data wasn't enough, because each plant draws its lifespan once, when it appears, and keeps it in the save. Growth Sync came out of that. When a game loads, it cuts every plant back to what its template allows now. On the next load 21,987 herbs went, and the town ran twice as fast.
BML only works on the 64-bit Steam version, 1.0.7. The source is all on GitHub, and the API is documented there if you want to write your own plugins.