Setup guide

This guide explains how to install Un-Banished and start playing. It takes about ten minutes. It also explains where Un-Banished keeps your saves, settings and mods, and what to do when something goes wrong. To learn what the project is, read the README.

1. Check what you need

You need	Why
Banished 1.0.7 from Steam or GOG	Un-Banished reads the game's art, sound and data from your copy. It includes none of its own.
A graphics card from the last ten years	Anything with Vulkan, Metal, DirectX 12 or OpenGL ES 3.
About 3 GB of free disk space	For the build tools and the compiled game.

Getting the game files

Banished was released only for Windows. But Un-Banished needs only the game's data files. These files work on any system.

• On Windows, install the game from Steam or GOG in the normal way. Then go to step 2.
• On a Mac or a Linux PC, Steam and GOG do not install a Windows-only game in the normal way. Use one of the methods below.

Steam: download the Windows files with download_depot

Steam has a hidden console. With the console, you can download the files of any game you own, for any system. On Steam, Banished has the app number 242920. Its Windows game files are in the depot (download package) number 242921.

1. Open Steam and sign in with the account that owns Banished.

2. Open the Steam console. There are two ways:

   • type steam://open/console in the address bar of your web browser, and allow the browser to open Steam; or
   • close Steam, and start it again with the -console option.

   A Console tab then appears in Steam, next to Library, Store and Community.

3. In the box at the bottom of the Console tab, type this and press Enter:

   download_depot 242920 242921

4. Wait a few minutes. Steam shows no progress bar. When the download is complete, the console prints a message with the folder where Steam saved the files.

5. That folder contains WinData. It is usually:

   System	Folder
   macOS	~/Library/Application Support/Steam/Steam.AppBundle/Steam/Contents/MacOS/steamapps/content/app_242920/depot_242921
   Linux	~/.local/share/Steam/ubuntu12_32/steamapps/content/app_242920/depot_242921 (or under ~/.steam/steam/)

   If your folder is different, use the path that the console printed. You can move the folder to a simpler place, for example ~/Games/Banished. Steam does not manage this folder, so Steam will not update or delete it.

tools/extract-assets.sh already looks in the macOS folder above.

TIP

On Linux, you can also install Banished in the normal way. In Steam, open Settings → Compatibility, turn on Enable Steam Play for all other titles, and install Banished from your library. Steam installs the Windows version under ~/.steam/steam/steamapps/common/Banished.

GOG: unpack the Windows installer

GOG sells Banished without copy protection (DRM). So you can download the installer and unpack the files from it. You do not need to run the installer.

1. Sign in at gog.com, open Account → Games, and click Banished.
2. Under Download offline backup game installers, choose the Windows installer, in English or in your language. The file has a name like setup_banished_1.0.7_….exe. If GOG splits the installer into several files, also download the .bin files. Keep all of them in the same folder.
3. Install innoextract, which unpacks GOG installers:
   • macOS (with Homebrew): brew install innoextract
   • Debian or Ubuntu: sudo apt install innoextract
   • Fedora: sudo dnf install innoextract · Arch: sudo pacman -S innoextract
4. Unpack it into a new folder:

   mkdir -p ~/Games/Banished
   innoextract --gog --output-dir ~/Games/Banished ~/Downloads/setup_banished_*.exe

5. Look for the WinData folder inside ~/Games/Banished. Some installers put it one level lower, in a folder such as app. This WinData folder is the folder that Un-Banished needs.

If you have GOG Galaxy on a Windows PC, you can also install Banished there. Then copy its WinData folder to your Mac or Linux PC.

Another method: install Banished on a Windows PC. Then copy its WinData folder to your computer, with a USB stick or over your network. Un-Banished needs only the four .pkg files (about 165 MB).

2. Download it, or install the build tools

Ready-made downloads. From version 0.4.1, each release has a zip for Windows, macOS (Apple silicon and Intel) and Linux. Unpack it, then go on to 4. Find your game data: the program in the zip is unbanished (unbanished.exe on Windows). The program is not signed:

• on macOS, allow it once in the terminal: xattr -d com.apple.quarantine unbanished;
• on Windows, SmartScreen may warn about it: choose More info, then Run anyway.

Build it yourself. Un-Banished is written in Rust. You install Rust once, and Rust builds the game for you. Choose your system:

Windows

1. Download and run rustup-init.exe from https://rustup.rs.
2. If the installer asks to install the Visual Studio C++ build tools, choose yes and keep the default settings. Rust needs these tools to build Windows programs.
3. When the installer asks how to install Rust, press Enter. This chooses the default.
4. Install Git from https://git-scm.com/download/win. The default settings are correct.
5. Open a new PowerShell or Terminal window. Only a new window can find the new tools.

macOS

1. Open Terminal (in Applications → Utilities).
2. Install Apple's command-line tools, which include Git:

   xcode-select --install

3. Install Rust and accept the default option:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

4. Close Terminal and open it again. Only a new window can find the new tools.

Linux

1. Install a C compiler, Git and the ALSA sound headers. On Debian or Ubuntu:

   sudo apt install build-essential git pkg-config libasound2-dev

   On Fedora: sudo dnf install gcc git pkgconf-pkg-config alsa-lib-devel. On Arch: sudo pacman -S base-devel git alsa-lib.
2. Install Rust and accept the default option:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

3. Open a new terminal. Only a new terminal can find the new tools.
4. Check that your graphics driver supports Vulkan: the command vulkaninfo --summary must show your graphics card.

To check the installation, run cargo --version in the new terminal. It must print a version number.

3. Download and build Un-Banished

In the terminal, run:

git clone https://github.com/tanepiper/unbanished.git
cd unbanished
cargo build -p unbanished-app --release

The first build downloads the libraries that Un-Banished uses, and takes a few minutes. Later builds are much faster. When the build is complete, the game is in this file:

System	File
Windows	target\release\unbanished.exe
macOS, Linux	target/release/unbanished

To update Un-Banished later, run git pull in the same folder. Then run the cargo build command again.

4. Find your game data

Un-Banished reads four files from your game's WinData folder: data0.pkg, data1.pkg, patch0.pkg and patch1.pkg. It only reads them and never changes them.

Where you got Banished	The WinData folder
Steam, Windows	C:\Program Files (x86)\Steam\steamapps\common\Banished\WinData
Steam, macOS	~/Library/Application Support/Steam/steamapps/common/Banished/WinData
Steam, Linux	~/.steam/steam/steamapps/common/Banished/WinData
GOG or elsewhere	the folder with Banished's .exe files, then WinData inside it

TIP

In Steam, right-click Banished, then choose Manage → Browse local files. Steam opens the game's folder.

When you give it no folder, Un-Banished looks in Steam by itself: Steam's library folders on Windows, macOS and Linux, and Steam for Windows in CrossOver bottles and Wine on a Mac or on Linux. UNBANISHED_DIR, the folder that holds WinData, is searched first.

5. Play

There are four ways to start the game. Choose one.

A. Give it the folder. This way works on every system:

# Windows (PowerShell)
target\release\unbanished.exe "C:\Program Files (x86)\Steam\steamapps\common\Banished\WinData"

# macOS
target/release/unbanished ~/Library/Application\ Support/Steam/steamapps/common/Banished/WinData

# Linux
target/release/unbanished ~/.steam/steam/steamapps/common/Banished/WinData

B. Put it next to the game. Copy unbanished.exe (or unbanished) into your Banished folder, next to WinData. Start it from there, or make a desktop shortcut to it. It then works like the original program. It finds WinData in the same folder. It uses the same save folder as the original.

C. Start it from the launcher. The launcher is a small window that opens before the game, made with GameFrame. In Settings you choose the game, Banished 1.0.7 (exactly the original) or Un-Banished (with its extensions), and your copy of Banished: one found in Steam, or a folder you choose. Then press Start in Play. Each release zip has it next to the game: run unbanished-frame (unbanished-frame.exe on Windows). To install it from the source folder as an application instead:

./gameframe install extra    # macOS: /Applications/GameFrame/Un-Banished More.app

The launcher explains how it works.

D. Start it from the source folder. This way is for contributors. Copy your game data into the project once. Then start the game with cargo run:

tools/extract-assets.sh          # finds the usual Steam folders
cargo run -p unbanished-app --release

If your copy of Banished is in another place, run UNBANISHED_DIR="/path/to/Banished" tools/extract-assets.sh. UNBANISHED_DIR is the folder that contains WinData. The script needs Python 3 and a bash shell. On Windows, use Git Bash. The script copies the files into game-data/. Git ignores this folder, so the files are never committed.

The game then starts like the original. First you see the splash screen and the loading screen. Then you see the main menu, with its music and a 3D town scene. New Game, Load, Tutorials, Achievements, Mods and Options all work.

Choose New, keep the default settings, and press OK. Your settlers arrive next to their first stockpile:

Click a building or a citizen to open its window. This is the Town Hall in a large town: