Building Locally

By the end of this guide, you will have Unciv running locally from code, so you can make changes and test them locally.

With Android Studio

Install Android Studio - it's free and awesome! Be aware that it's a long download!
Install Git, it's the way for us to work together on this project. UI is optional, Android Studio has good Git tools built in :)
Getting the code
- Create a Github account, if you don't already have one
- Fork the repo - this will create a "copy" of the code on your account, at https://github.com/<YourUsername>/Unciv
Load the project in Android Studio
- File -> New -> Project from Version Control -> GitHub
- Enter your GitHub username and password
- Select the repository and hit clone - The GitHub repo will be created as a new project in Android Studio.
Gradle will attempt the initial sync. If this is your first time with Android Studio, this may require you to accept the Android Build-tools licenses, which works differently on every device, so search for your OS-specific solution.
- A new install may not be able to do the initial sync - this comes in the form of Unable to find method ''void org.apache.commons.compress.archivers.zip.ZipFile.<init>(java.nio.channels.SeekableByteChannel)'' errors when you try to sync. If you have this problem go into File > Settings > Languages & Frameworks > Android SDK
  - Click "SDK Platforms"
  - Click "Android 16.0 ("Baklava")" (Optionally, you can save some space by selecting 'Show Package Details' and choosing the Platform SDK only, without Sources or system Images)
  - Click "SDK Tools"
  - Select "Show Package Details" in the bottom right
  - Choose version 35.0.0 under "Android SDK Build-Tools"
  - Click "Apply"
  - Restart Android Studio
Have patience and let the initial Gradle sync finish. The subsequent ones won't take as long. Watch the status bar or the "Build" toolpane.
If everything went well, you will now have three "Run configurations" (look for green in the top bar): "android", "Desktop" and "Run unit tests".
- If the "android" one is missing, it's likely your Android SDK setup did not set the ANDROID_HOME environment variable. Do so, restart Studio and re-sync Gradle (the button with the elephant and arrow in the top bar).
- If the "Desktop" one is missing, here's how to create one manually:
  - Select Run > Edit configurations (from main menu or the configurations dropdown)
  - Click "+" to add a new configuration
  - Choose "Application"
  - Give the configuration a name, we recommend "Desktop"
  - Set the module classpath (the box to the right of the Java selection) to Unciv.desktop.main (Unciv.desktop for Bumblebee or below), main class to com.unciv.app.desktop.DesktopLauncher and $ProjectFileDir$/android/assets as the Working directory, OK to close the window
    - It may be useful to set some VM options - activate the field in the run config editor with Alt-V or via the Modify Options menu, then add -Xmx4096m -Xms256m -XX:MaxMetaspaceSize=256m to allow a debugged game a little more memory. Or, use the -DnoLog= or -DonlyLog= options to control console logging. See the Log.kt comments for details.
    - If you get a ../../docs/uniques.md (No such file or directory) error that means you forgot to set the working directory!
- If the "Run unit tests" is missing - look for the top-level "tests" folder, right-klick -> Modify Run Configuration...
Select the Desktop configuration (or however you chose to name it) and click the green arrow button to run! Or you can use the next button -the green critter with six legs and two feelers - to start debugging.
A few Android Studio settings that are recommended:
- Go to Settings > Version Control > Commit > Advanced Commit and turn off 'Analyze code'
- On the same page, we recommend turning off "Use non-modal commit interface". This puts the "Local Changes and "Console" Tabs back into the Git toolpane (and the Shelf once you have shelved diffs). These can be hard to find otherwise - feel free to ignore if you don't think you need them.
- Settings > Editor > Code Style > Kotlin > Tabs and Indents > Continuation Indent: 4
- Settings > Editor > General > On Save > Uncheck Remove trailing spaces on: [...] to prevent it from removing necessary trailing whitespace in template.properties for translation files
  
  Important: Unchecking this creates annoying merge conflicts. Before commits (non-translation) remove those trailing space. For more info check Coding Standard.
- Right-click the android/assets/SaveFiles folder once you have one, "Mark directory as" > Excluded
- If you download mods do the same for the android/assets/mods folder and any other files you may create while testing that do not belong in the public project.
- This disables indexing for performance.

Unciv uses Gradle to specify dependencies and how to run. In the background, the Gradle gnomes will be off fetching the packages (a one-time effort) and, once that's done, will build the project!

Unciv uses Gradle 8.11.1 and the Android Gradle Plugin 8.9.1. Can check in File > Project Structure > Project

Note: advanced build commands (as described in the next paragraph), specifically gradlew desktop:dist to build a jar, run just fine in Android Studio's terminal (Alt+F12), with most dependencies already taken care of.

Without Android Studio

Ensure you have JDK 11 or higher installed
Clone the project (see above initial steps)
Open a terminal in the Unciv folder and run the following commands

Windows (CMD)

Running: gradlew desktop:run
Building: gradlew desktop:dist

Linux / macOS / Windows (PowerShell)

Running: ./gradlew desktop:run
Building: ./gradlew desktop:dist

If the terminal returns Permission denied or Command not found on Mac/Linux, run chmod +x ./gradlew first. This is a one-time procedure.

If you get an error that Android SDK folder wasn't found, install it by running:

sudo apt update && sudo apt install android-sdk (Debian, Ubuntu, Mint etc.)

Then, set the SDK location in the local.properties file by adding:

sdk.dir = /path/to/android/sdk - for example, /usr/lib/android-sdk

If during initial launch you get an error that the JDK version is wrong, install the JDK from here.

Note: Gradle may take up to several minutes to download files After building, the output .JAR file should be in /desktop/build/libs/Unciv.jar

For actual development, you'll probably need to download Android Studio and build it yourself - see above :)

Running via Docker

Installing prerequisites

Docker

Ubuntu or other apt-based Linux distributions: sudo apt install -y docker.io (Not the 'docker' package which is unrelated). Sufficient but will need buildx, below, unless you only want to run the prebuilt container.
For a more current and complete coverage, follow instructions to use Docker's own repositories. With those, you would sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin instead of 'docker.io' and also get buildx easier.
Windows: Since you'll need a Linux kernel first, starting at the Docker desktop page is your best bet. Includes buildx. Or install WSL2, follow the Linux instructions, and pay attention to network routing issues between the desktop/wsl/docker layers.

buildx

This plugin is required to build (but not to run) the container. If you used the 'docker.io' package above, you must install manually:

Visit buildx releases, fetch the latest release for your platform and architecture.
Rename to docker-buildx, make executable, and move to ~/.docker/cli-plugins.
Verify with docker buildx version.

VNC viewers

Optional. Any compliant viewer should do. Look for open source to avoid malware.

TigerVNC is a lean and solid option. sudo apt install -y tigervnc-viewer is good enough on Ubuntu-based distros. They also have a Windows portable binary available.

Building / getting the image

Building is optional if you just want to run the prebuilt, public container, see below. From a terminal in your Unciv clone's root folder, with spare time (several minutes) and disk space (~10G):

If you have docker compose installed: run docker compose build && docker compose up

Otherwise: docker build . -t unciv and for a first start:

docker run --name unciv -d -p 6901:6901 -p 5901:5901 \
-v unciv-data:/home/headless/.local/share/Unciv unciv

To use our already built one:

docker run --name unciv -d -p 6901:6901 -p 5901:5901 \
-v unciv-data:/home/headless/.local/share/Unciv ghcr.io/yairm210/unciv

To update your image when the source has changed:

Run docker rm -f unciv. Removes the container (the updated image is a new one, and any container is bound to a specific image).
If you used the prebuilt image: docker pull ghcr.io/yairm210/unciv
Then repeat the above steps. Once it works, run docker image prune to clear outdated dangling images.

Running

By following the above steps, you have made sure you have a container with the logical name "unciv", and from now on, you can run docker stop unciv and docker start unciv as needed. That single named container, via a docker-managed volume, also ensures you can keep settings, saves and mods.

Connecting

Launch http://localhost:6901/vnc.html?password=headless
Or use your VNC viewer, connect to localhost:5901, and use password headless.

Troubleshooting

For moderately advanced users - in case you can't connect:

Try VNC instead of the web shim
A "deny-all" ufw setup can silently break Docker's port publishing: If connections time out or drop immediately, try with a temporary sudo ufw disable to confirm this.
docker ps: containers currently running
docker port unciv: confirm ports are as configured
docker logs unciv: top-level container output
docker exec unciv ps aux: verify Unciv, X11, VNC and noVNC processes are OK
docker exec unciv cat /dockerstartup/vnc.log VNC daemon's logs
docker exec unciv cat /dockerstartup/novnc.log web shim's logs

Debugging on Android

Sometimes, checking things out on the desktop version is not enough and you need to debug Unciv running on an Android device. For an introduction, see Testing android builds.

Testing packaged releases

You can produce most of the files that get listed in https://github.com/yairm210/Unciv/releases locally.

All of the following will run commands from a terminal in the project's root directory:

'Unciv.jar': run ./gradlew desktop:dist and find the jar in 'desktop/build/libs'.
'Unciv-Windows64.zip': run ./gradlew desktop:dist desktop:zipWindows64 - the result will appear in the 'deploy' folder.
'Unciv-Linux64.zip': run ./gradlew desktop:dist desktop:zipLinux64 - the result will appear in the 'deploy' folder.
'Unciv-MacOS.zip' (despite not being included in official releases due to preferring homebrew, it can be built - your mileage may vary): run ./gradlew desktop:dist desktop:zipMacOS.
'linuxFilesForJar.zip': run ./gradlew desktop:zipLinuxFilesForJar
'Unciv-signed.apk': Not possible, but you can build a debug-signed APK: run ./gradlew android:assembleDebug and get 'Unciv-debug.apk' in 'android/build/outputs/apk/debug'.
'Unciv.msi': Requires the Windows64 zip (see above) and the .NET SDK installed. On a powershell prompt in the project's root directory, replacing the
placeholder with an appropriate value of the form X.Y.Z (three numeric parts — the .wxs file appends a fourth automatically), run:
```
dotnet tool install --global wix --version 5.0.2
mkdir .github/workflows/wix-msi-files
tar -xf deploy/Unciv-Windows64.zip -C .github/workflows/wix-msi-files
$env:UNCIV_VERSION="<version>"; & "$HOME\.dotnet\tools\wix.exe" build -arch x64 .github/workflows/unciv.wxs
```
The result appears as '.github/workflows/Unciv.msi'. Cross-building from Linux should be possible, but we won't test and document the details here.
'UncivServer.jar': run ./gradlew server:dist, look in 'server/build/libs'.

Next steps

Congratulations! Unciv should now be running on your computer! Now we can start changing some code, and later we'll see how your changes make it into the main repository!

Now would be a good time to get to know the project in general at the Project Structure overview!

Unit Tests

You can (and in some cases should) run and even debug the unit tests locally.

The repository contains a run configuration "Run unit tests". If it's missing:
In Android Studio, Run > Edit configurations.
- Click "+" to add a new configuration
- Choose "Gradle" and name the config, e.g. "Run unit tests"
- Under "Gradle Project", choose "Unciv" from the dropdown (or type it), set "Tasks" to :tests:test and "Arguments" to --tests "com.unciv.*", OK to close the window.
Select the "Run unit tests" configuration and click the green arrow button to run! Or start a debug session as above.

Linting

Detekt checks for code smells and other linting issues. To generate Detekt reports:

Download detekt-cli (the zip file) and unzip it
Open a terminal in the Unciv root directory and run one of the following commands to generate the report. NOTE: If you're using Windows, replace detekt-cli with detekt-cli.bat.
- For warnings: PATH/TO/DETEKT/detekt-cli --parallel --report html:detekt/reports.html --config .github/workflows/detekt_config/detekt-warnings.yml
- For errors: PATH/TO/DETEKT/detekt-cli --parallel --report html:detekt/reports.html --config .github/workflows/detekt_config/detekt-errors.yml
The report will be generated in detekt/reports.html

Testing wiki changes

This wiki is automatically built from the main repository's 'docs' folder, so to help improve it, you would normally work on those files in a branch of your local Unciv clone.

However, typical editor previews of markdown are NOT authoritative, as the files get processed by mkdocs. For a conclusive check, run mkdocs locally and view the result in your browser.

Once set up, it's a simple mkdocs serve from Android Studio's terminal, or if you chose the simpler Windows setup, python -m mkdocs serve.

The command will tell you the link it's serving on, and e.g. in Android Studio's shell, you can click it. The server will monitor the source for changes, so you can edit while your test is running and see the changes almost immediately. (Look up when Android Studio actually saves to disk, or hit Ctrl-S to make sure. The browser won't need a manual refresh!)

The one-time setup procedure is as follows:

Install python
- Linux: sudo apt install python3 python-is-python3 -y or however you prefer
- Windows: Get it from python.org/downloads - look for "standalone installer"
Install mkdocs and required plugins
- Run pip install mkdocs mkdocs-material mkdocs-awesome-pages-plugin.
- On Debian-based Linux, you'll run into the "virtual environment" hassle, so either learn to manage that or add the --break-system-packages option.
Manage PATH
- On Windows, the python scripts folder is not added to the PATH by default.
  
  pip install will tell you about that, and show the correct location.
  
  Add %AppData%\Python\Python314\Scripts (adjust version as required) to your path, or use the more verbose command as shown.

Cleaning up obsolete files

From time to time, Unciv bumps the versions of major tools - mainly Gradle, the Android SDK Platform, and the Android SDK Build-Tools. The new versions and support files are automatically downloaded for you, but old versions are not cleaned up automatically, nor are intermediate build files specific to Gradle versions. This may leave a few gigabytes of dead files on your system. If these bother you, you can clean up as follows:

Remove obsolete Android SDK Platform and Build-Tools versions from SDK manager (remember all projects share these, so if you have other projects, keep their requirements too).
With Android Studio closed (on Windows, you'll have to manually kill leftover Gradle daemons too):
- Delete subfolders named after obsolete Gradle versions from Unciv/.gradle, ~/.gradle/caches (%HOME%.gradle\caches on Windows) and ~/.gradle/daemon
- For a thorough but more costly cleanup, clean out ~/.gradle/caches entirely except for the tag files. This will force the next gradle sync to re-download a large amount of support files, but this way you will also clean out remnants of superseded support libraries for kotlin, Gdx and so on.
Clean Android Studio settings and cache folders for replaced versions:
- File->Manage IDE Settings->Import Settings will tell you the current configuration folder.
- Help->Show log in Files (or in Explorer) will tell you where the cache folder is. Then, navigate with your file manager to the "Google" parents, and clear all folders named for outdated versions.
Check ~/.gradle/wrapper/dists for Gradle distributions you no longer use (over all your projects) and clean them - too much only costs bandwidth and time.

Additionally, git prioritizes safety of your changes over efficiency to the extreme, leading to some bloat. git gc is automatically done for you, but sparingly, and running it manually won't hurt. For a more thorough cleanup, run git gc --prune=now --aggressive sporadically from Studio's terminal (or any shell within Unicv's project folder), making sure to clean up all your obsolete branches first, and that all remaining branches are in sync with the online branches they're backing or based on master if they're local only.

Building artifacts (running ./gradlew desktop:packrWindows64, ./gradlew server:zipLinux64 or similar commands) will keep copies of downloaded packr jar and JRE archives in desktop/.jre-cache, which you can clean out at your leisure. A later run of these Gradle tasks will re-download as required.

If you have been running the Unciv Docker image, it's your only use of Docker, and you no longer need it: stop containers, then docker system prune -a --volumes && docker builder prune -a will clear everything and reclaim the maximum disk space. Caution: nukes everything Docker-related except the software itself.

UncivServer

The simple multiplayer host included in the sources can be set up to debug or run analogously to the main game: - In Android Studio, Run > Edit configurations. - Click "+" to add a new configuration - Choose "Application" and name the config, e.g. "UncivServer" - Set the module to Unciv.server.main (Unciv.server for Studio versions Bumblebee or below), main class to com.unciv.app.server.UncivServer and <repo_folder>/android/assets/ as the Working directory, OK to close the window. - Select the UncivServer configuration and click the green arrow button to run! Or start a debug session as above.

To build a jar file, refer to Without Android Studio and replace 'desktop' with 'server'. That is, run ./gradlew server:dist and when it's done look for /server/build/libs/UncivServer.jar