Full Workspace Setup¶

The engine repository at https://github.com/MovingBlocks/Terasology is the heart and central workspace of mostly everything Terasology.

To set up the workspace is a fairly easy process:

Git clone or download a source zip from GitHub to some location on your computer * See GitHub or Google for various Git tutorials. In short you’d clone with git clone https://github.com/MovingBlocks/Terasology.git into a local workspace directory
Run gradlew once in the root of the chosen directory via command prompt / terminal

Note

In OSX, the command is ./gradlew instand of gradlew

That’s it, really! You now should have a functioning game workspace.

Requirements¶

Okay, you might want a little more than that. The only mandatory requirement is a Java 8 SDK which you either download from Oracle or get via OpenJDK.

Note

Using OpenJDK has a slightly higher risk for encountering Common Issues - for instance the Launcher requires JavaFX which isn’t always bundled with OpenJDK.

Beyond that you might want an IDE and some IDE plugins, see Setup in IntelliJ or Setup in Eclipse. Maybe even a tool like YourKit to help profile game performance. But everything else really is optional!

Most our automation and project setup happens through Gradle which the gradlew script downloads a version of if needed. The initial gradlew execution will download all project dependencies (Maven style - downloading half the internet). Just give it a while. Read more on Codebase Structure if interested.

Run game from source¶

As long as you have the code and Java 8 you can run the game from source simply with gradlew game

Any problem encountered at this point is usually from Java not being configured right, such as having an older version as your default Java. See Common Issues for more.

Note

If the game itself behaves funny or crashes see if the normal release download works. If not check the Minimum Requirements [1] and make sure your graphics card driver is up to date.

Ask in the Support Forum if issues remain, or come join us on #terasology on Freenode IRC. See Using IRC and please be patient :-) IRC isn’t necessarily instant communication and it may take a while to get a reply.

You can also run a headless server from source using gradlew server - just run it in a second command prompt / terminal as it’ll not accept further input (other than CTRL-C to break the process)

IntelliJ¶

Running from command line is good and fine and some enjoy simply working in a plain text editor. For those preferring a full integrated development environment (IDE) we recommend IntelliJ

We have a series of customizations that prepare run configurations, Git integration, and so on for the project, specifically for IntelliJ. Eclipse has fewer of these but is still entirely usable, as is NetBeans, but you’ll need to figure out some details there yourself.

To prepare project files for IntelliJ simply run gradlew idea which as any gradlew also does the initial dependency fetch so you can go straight from source download to gradlew idea you don’t need a separate plain gradlew step.

Open the resulting Terasology.ipr as an existing project in IntelliJ

Warning

Do not create a new project or attempt to import the project via Gradle. It is possible to get that working but it may miss customizations and cause confusion.

Warning

After openning Terasology.ipr, IntelliJ will show: Unlinked Gradle project? Don’t click on Import Gradle project

The opened project should leave you with a series of run configurations to execute the game (and server) in various formats. It’ll hook up our license header as a template, configure code analytics, and so on.

Here is a video introducing downloading project from GitHub, runing the game from sources and openning the source with IntelliJ:

Eclipse¶

Eclipse can be used with Terasology just like IntelliJ, but needs a little more manual setup.

Todo

We have a few more files at config/eclipse that could use some setup instructions and/or automated customization like for IntelliJ.

Note

All of the settings described below can be applied to a specific Eclipse project or to an entire workspace.

To apply the settings on a per-project basis, right-click on a project in the Package Explorer and select Properties. (Alternatively, select the project and press Alt+Enter) After navigating to a relevant section of the Preferences menu, check Enable project-specific settings. Repeat this for all the projects you’d like to work on.
To apply the settings globally, select Window → Preferences from the main menu and navigate to a relevant section.

Formatting Convention Setup: In Java Code Style → Formatter, click Import and import Terasology’s formatting settings file (Terasology/config/eclipse/formatting.xml). The Terasology formatting conventions profile should be automatically selected.

Import Order Setup: In Java Code Style → Organize Imports, click Import and import Terasology’s import order file (Terasology/config/eclipse/.importorder).

Optional, but recommended: Switch to Window → Preferences → Editor → Save Actions. Check Perform the selected actions on save and Organize imports.

Here is a video introducing setting up Terasology with Eclipse:

Git¶

Git will be enabled as source control, however going deeper into the details of using Git is outside the scope of this wiki. Please see the excellent resources on GitHub for more like their bootcamp series.