Community | Installation | Features | Troubleshooting | Development | Acknowledgements | License
Terasology Launcher is the official launcher for the open source game Terasology. It provides easy access to the different game versions and build types. Terasology and related projects are developed by a group of software enthusiast volunteers under the organization name MovingBlocks.
Community
If you want to get in contact with the Terasology community and the whole MovingBlocks team, you can easily connect with us, share your ideas, report and solve problems. We are present in nearly the complete round-up of social networks. Follow/friend us wherever you want, chat with us and tell the world.
Installation 
- Download the corresponding archive for your platform from the latest release
- Extract the archive to the path where the launcher should be installed
- Start Terasology Launcher
| Operating System | Executable |
|---|---|
| Windows | TerasologyLauncher.exe or bin/TerasologyLauncher.bat |
| Unix, Linux, Mac OS X | bin/TerasologyLauncher |
Features
The launcher installation directory is the folder you extracted the launcher archive into. This directory will also hold different versions of Terasology that are installed via the launcher.
On first start-up, the Terasology Launcher will prompt you with the selection of the Terasology data directory. The data directory is the place for configuration data and user-specific files such as key bindings and save games. The suggested default is a new directory in the user's home directory.
The Terasology Launcher UI provides functionality to download, start, and delete different game versions. The game versions are grouped by the type of build they belong to:
| Build Type | Explanation |
|---|---|
| Terasology | Released version of Terasology core game bundled with modules |
| Terasology Lite | Released version of Terasology core game only |
In addition to this main functionality, the UI displays information about new changes of the selected game version ("Changelog"), launcher information concerning changes, licensing and contribution guidelines ("About"), and logging data for the current launcher execution. Further, you have access to the social media representation of Terasology.
The settings view enables you to open the launcher installation, game installation and data directories for quick access. You can configure the memory settings for the game and even specify additional Java or game arguments as well as the logging level for the game. Please note, that the "Initial Game Memory" and "Maximum Game Memory" settings only apply to the game itself. The actual resource consumption may be higher due to additional resources required by the Java Virtual Machine (JVM).
The remaining settings can be used to configure the launcher. You can set the launcher language and decide whether the launcher should search for updates, close when a game is started and save downloaded game package files.
Troubleshooting
Find below common issues you may run into and how to resolve or work around them. If you cannot find help for an issue you might be facing, please open a GitHub Issue including the information available in the "Logging" tab.
⬇️ Download Issues
An indication of a download issue is the download starting but at some point suddenly stopping / failing. First information about the failure can be found in the "Logging" tab. The most common indicator you'll see there is a log message similar to "request timed out".
Downloading Terasology via the launcher can fail for multiple reasons including:
- GitHub being unavailable
- the Terasology artifact being unavailable
- your internet connection being slow
- something on your computer or in your network slowing down the download
To check whether GitHub is available, please refer to https://www.githubstatus.com/.
To check whether the Terasology artifact is available, please go to our Terasology release page and look for the version you were trying to download.
You should find it at https://github.com/MovingBlocks/Terasology/releases/tag/v<version>, for example, https://github.com/MovingBlocks/Terasology/releases/tag/v5.3.0.
At the bottom of the release information below the changelogs, there should be an "Asset" section.
If this section includes a TerasologyOmega.zip file, the Terasology artifact is available.
If not, please open up a GitHub Issue or inform us about this on Discord.
If the Terasology artifact and GitHub are available, but your download timed out, this is likely due to a slow internet connection or something on your computer or in your network slowing down the download. In this case, you can either try to hunt down the issue yourself or try to work around the issue manually
Manual Download Timeout Workaround
You can work around the launcher's timeout logic by downloading the Terasology artifact manually.
Workaround steps:
- Download the desired Terasology artifact from GitHub:
https://github.com/MovingBlocks/Terasology/releases/download/v<version>/TerasologyOmega.zip - Extract the artifact (zip archive)
- Rename the archive
For stable releases toterasology-omega-<version>-stable.zip, for example,terasology-omega-5.3.0-stable.zip
For nightly and pre-releases toterasology-omega-<version>-nightly.zip, for example,terasology-omega-5.3.0-rc.2-nightly.zip - Copy the renamed archive into the
cachedirectory located in the launcher managed directory
On Windows:C:\Users\AppData\Roaming\TerasologyLauncher\cache
On Linux/Unix:/home/<user>/.terasologylauncher - Start the launcher and select the version you downloaded the artifact for, click on the download icon (
⬇️ ) and wait for the download to complete. This should happen quickly as the launcher should use the already downloaded Terasology artifact from the cache.
On completion the download icon (⬇️ ) should turn into a play icon (▶️ ) - Click on the play icon (
▶️ ) to start Terasology
Development
To be able to run TerasologyLauncher from source follow these steps. This guide is designed for IntelliJ IDEA (you can use the free community edition), but alternative setups are possible.
Get Ready
To contribute to this repo, please open a pull request from your fork of this repository.
For more information on building and developing the Terasology Launcher, make sure to read the rest of this README and CONTRIBUTING.md.
Requirements
You'll need the following tools:
- Java SE Development Kit (JDK) 11. It should be possible to use a later version of the JDK for local development, please see the definition of push validation for the exact CI setup.
- Git to clone the repo and commit changes.
Development is possible on all common platforms (Windows, Linux, MacOS).
🤓 Start developing
Familiarise yourself with Git's concept of repositories, branches, and commits. To get the latest changes from remote repositories you need to fetch all remote data via git fetch --all. This does not change your workspace, it just loads up your local Git database.
Apart from Git, basically everything can be done using the Gradle wrapper. The following list is an excerpt of some commonly used tasks.
| Command | Description |
|---|---|
gradlew build |
Compile the source code, run tests and build a JAR. |
gradlew install |
Create a local runnable installation (placed in ./build/install/TerasologyLauncher). |
gradlew run |
Build and run the launcher. |
gradlew createRelease |
Create a local development release (located in ./build/distributions). |
gradlew tasks |
Display other available build script tasks. |
Assume you have pushed some changes to your fork into a branch myFeature.
In order to let us know about your work and give us the possibility to incorporate your changes you should send us a pull request.
You can do this by selecting the myFeature branch on your GitHub repo and click the button which says "Open pull request".
More information on how to contribute can be found in CONTRIBUTING.md. Remember, that all submissions must be licensed under Apache License, Version 2.0.
🎏 Translation
If you want to contribute by translating the Terasology Launcher to a new language or by improving an existing translation check out the Translation Guide.
📚 Related Resources
Tutorials and further information on Git:
Developer setup tutorials for our main project, Terasology:
Acknowledgements
Terasology Launcher is driven by its contributors!
This project uses
- Font Awesome Icon for Webchat (
fa-comments), CC BY 4.0 License, Font Awesome Free License - Mark James' Flag Icons Pack
- Bellsoft Liberica JDK 11 is bundled with the launcher
License 
Terasology Launcher is licensed under the Apache License, Version 2.0.