C4DT Installation Guide

Prerequisites

First you have to have Java 8 installed in order for C4DT to work with Eclipse.

Now you need to install Eclipse itself. This is relatively straightforward. Go to the Eclipse Download Page and download the Eclipse for Java Developers package. Eclipse does not require running an installer. Just unpack the folder somewhere and run the Eclipse program inside it. Unless you don't have Java installed Eclipse should boot although that might take a while. On first boot, Eclipse will usually ask you to provide a workspace location. That's the folder Eclipse will create projects in by default. Set it as you like.

Note to Linux Users: Download Eclipse from its website even if it is available from your distribution's repository. A number of Linux users have had problems when eclipse is installed from the repo.

Installing C4DT

Installing C4DT (Clonk Development Tools) is the next step to tailor that generic Eclipse installation you now have for the purpose of editing C4Scripts and other OpenClonk files with it. It is a plug-in that provides a number of improvements you might know from other IDEs. Among those are

  • Content Assistance (similar to IntelliSense from Visual Studio)
  • Error recognition (to not have to boot up the engine for getting a list of syntax errors)
  • Navigation (clicking on identifiers, getting to their declaration locations)
  • Debugging scripts (suspending execution of scripts, executing them in single steps)

To install C4DT, you first have to add its update site to the list of update sites Eclipse is maintaining. An update site is a location (usually on some web site although it can be local as well) Eclipse can download plug ins from. Once downloaded, those plug ins will also be updated from the same update site if Eclipse finds new versions of the plug-in there. To add an update site, go to Help -> Install New Software and press the Add button in the Install window.


C4DT's Update Site is currently http://www.openclonk.org/c4dt/. Add the Update Site (the name you choose for the site is of no concern), select it if that didn't happen automatically and you should see two items for installation:


The first one is the C4DT plugin itself that contains all the functionality. The second one is a German language pack you can optionally install as well. Note though that only functionality added by C4DT is translated. The rest of Eclipse stays in English. To change that, head over to the Eclipse Babel Project and install language packs from there. After pressing "Next" quite a few times, accepting the license (which is supposed to be the same as the one OpenClonk uses), agreeing to install unsigned content and restarting Eclipse, C4DT should be installed. A sign of success would be having a Clonk menu item in the main menu.

Setting Eclipse up for Clonk development

Now that C4DT is installed Eclipse needs to be set into Clonk mode. Press the button in the top-right of the window and "Other...".

You should see a window listing the available perspectives Eclipse can be put into. Choose the one named "Clonk".

In Eclipse lingo, a perspective is a default configuration on what views the main window should contain and how those views are arranged. There are perspectives for working on various tasks, like synchronizing code with a repository or working on a Java project. C4DT adds a Clonk perspective that by default looks like this:

Initial configuration

What now needs to be done is setting some default preferences that C4DT will need to not completely screw up. Open up the preferences (Window -> Preferences) and go to the Clonk section:


The preferences are divided into preferences to control the general behaviour of the plug-in (below) and engine-specific preferences (on top).

Set the game path for OpenClonk to the planet folder in your repository.

The two fields "C4Group Executable" and "Engine" will be filled out automatically if suitable executables are contained in the planet folder. If those are to be found somewhere else in your case, select them manually.

The repository field isn't exactly needed at the moment but you can set it to the path to your repository (not the planet folder) anyway.

This is all you need to set in the preferences but of course you can configure other things to your liking. Specifying Syntax highlighting colours used in Clonk text editors (expand the Clonk item in the tree view on the right) or keyboard short cuts (General -> Keys) come to mind.

When you're done, press OK.

Getting OpenClonk content into Eclipse

Now notice the Project Explorer view. It's glaringly empty. To fill it with OpenClonk content, open up the Clonk project wizard by pressing File -> New Clonk Project.


Choose the name of the project. "OpenClonk" is advisable but in the end it's up to your preference.

The following steps differ based on whether you cloned the OpenClonk repository or downloaded an official release.

  • Cloned from Repository

Eclipse will create projects in its workspace folder. But in the case of OpenClonk this is not suitable since all the game content is contained in the planet folder. Luckily, Eclipse provides a mechanism for such situations. It allows you to create projects from folders arbitrarily located in the file system. To use that mechanism uncheck "Use default location" and provide the path to the planet folder. This might feel kind of redundant since you already specified that path in the preferences and well, it is.

  • Downloaded official release
C4Groups in the official release are packed. C4DT can read packed c4groups, but not modify them. To access the content of packed groups, you have two choices. You can
  • link to those groups.
For that purpose, there is a link tab in the Clonk Project Wizard that enables you to add groups to be linked to the new project. Add all the .c4d/.c4f/.c4g files from the OpenClonk installation. When you finish the wizard later on, the linked groups will be displayed like regular folders, except for a link sign on the icon ()
To actually edit stuff, you need to create a new project that references the project containing the linked c4groups. Actually, this is not strictly necessary but advisable to keep things clear.
For referencing other projects (making stuff defined in that project known to the other project), use the Project References tab in the wizard. For changing project references later on, open the properties of a project (right click on the project in the Project Explorer, then select "Properties") and go to the Project References section.
  • import the groups.
The groups will be unpacked into the Eclipse workspace folder and modifying the unpacked files there won't be modify the original groups. Add groups to be imported from the Importing tab in the wizard.
If you plan on modyifing content from the releases you could think about whether it wouldn't be better to clone from the repository so you will be able to track your modifications using version control.
  • Both
Next, you should set the engine to "Open Clonk". When leaving it set to "Default engine" the project's engine will always be equal to the one selected in the preferences which might be troublesome when mixing Clonk Rage and Open Clonk projects in one workspace.

The Result

After creating the OpenClonk project and waiting a bit for Eclipse to analyze all the scripts you should be presented with a vista such as this:

In its current state, C4DT should more or less be able to parse all the scripts and not litter the problems view with false positives. When new functions are added to the engine (which tends to happen quite a lot with an engine still in development) those functions will be unknown to Eclipse at first, hence its complaining. But fear not, as those gaping holes of ignorance will sooner or later be stuffed.

Retrieved from "https://wiki.openclonk.org/index.php?title=C4DT_Installation_Guide&oldid=1573"