Developer documentation
These pages are for people who want to build Un-Banished from source, change it, or study how it works. If you only want to play, read the setup guide instead.
What the project is
Un-Banished is a reimplementation of the game Banished 1.0.7 (Steam build 170910, Windows x64). It is written in Rust. It draws with wgpu, so it runs natively on Windows, macOS and Linux, and in web browsers through WebAssembly.
The goal is the same behaviour as the original program: the same maps, rules, numbers, timings, save files and interface. The source code of Banished is not available. Every behaviour was worked out from the original program files, and every ported function names the original function it came from.
Where to start
| If you want to | Read |
|---|---|
| Build the game, the viewer and the browser version | Building |
| Run the tests and the checks before a commit | Testing |
| Check that a change does not change the game's results | Compatibility between versions |
| Measure speed and memory | Performance |
| Prove that a change to the picture changes only what it should | Changing what is drawn |
| Record a video of the game without a window | Recording videos |
| Know the project rules | Contributing (AGENTS.md) |
| Port a behaviour of the original game | Development guides |
| Learn how a part of the game works | Topics |
| Use one of the libraries | Apps and crates and the API documentation |
The rules in short
The full rules are in AGENTS.md. These are the most important ones:
- Never commit game material. The game files, extracted resources, decompiled code and save files stay on your computer. Git ignores the folders that hold them (
game-data/,analysis/,save-game/). - Evidence before code. Each ported item cites the original function it came from, in the last line of its doc comment:
Original: `FUN_1400be680`. A guess is marked inferred or assumed. See the doc-comment style. - Mark every intentional difference with a comment that contains
Deviation:. The list of differences, DEVIATIONS.md, is generated from these comments. - Do not change the game's results in an optimisation or a refactor. Saves, frames and random numbers must stay identical.
The workspace
| Path | What it contains |
|---|---|
apps/game | The game (binary banished) |
apps/viewer | The asset browser (binary banished-viewer) |
apps/cli | Command-line tools (binary banished-cli) |
apps/modmanager | The mod manager (binary banished-mods) |
apps/relay | The multiplayer relay (binary banished-relay) |
crates/core | Exact maths, the game's random numbers, noise, game time |
crates/terrain | Map generation, the terrain mesh, ground queries |
crates/path | The pathfinder and the sector graph |
crates/game | The game rules |
crates/formats | Readers for the game's files |
crates/ui | The game's interface system |
crates/gfx, crates/audio, crates/wma | Shared rendering, sound playback, the WMA decoder |
crates/mods, crates/nexus, crates/banishedinfo | The mod list shared by the game and the mod manager; optional Nexus Mods and banishedinfo.com support |
crates/net | Multiplayer networking: the relay protocol and connection |
tools/ | Data extraction, emulator checks, analysis and comparison scripts |
docs/ | Research notes about the original game, and these pages |
site/ | This website |
Apps and crates describes each one and links to its README.