As of now, you should have created an OpenClonk project and be sitting in front of something that is quite comparable to the original Clonk Editor. On the left side you have the Project Explorer (or on the right side or wherever you like, since all views can be freely arranged in Eclipse). You can use it to navigate packets as you'd do when using the editor.
Unlike the editor though, files are generally openend not it an external program but in a tab in the Eclipse window. You can still set programs to handle specific files by either using the Open With command in the context menu of the Project Explorer or by setting a program in the preferences. The first method works on a file-by-file basis so you could tell Eclipse to open a specific graphics file with Photoshop while opening others with Paint. The second method (Preferences -> General -> Editors -> File Associations) sets a file association for all files of that type.
Eclipse provides different internal editors for different file types. For Clonk-specific files, C4DT adds some more to the list. Among those are a
- C4Script Editor
- Landscape.txt Editor
- Ini Files Editor (DefCore.txt, ActMap.txt etc)
All editors provided by C4DT offer suitable syntax highlighting. Apart from that they include special support for the types of files they were intended for:
- The C4Script Editor is supposed to help you write scripts more quickly by displaying errors and warnings contained in the script as soon as you save them and offering you a list of identifiers you can insert in specific places. It also tries to make writing properly formatted scripts easier by automatically inserting closing brackets and indenting. In addition to that it also strives to make navigation among and inside scripts easier by hyperlinking between them and providing an outline of the script.
- The Landscape.txt Editor is tailored for editing - surprise! - Landscape.txt files. Sadly, it doesn't offer a live preview on how the generated map would look like so it's probably a good idea to use Mape instead. There are plans to include similar functionality directly in Eclipse though.
- The Ini Files Editor also includes support for hyperlinks.
Navigating to and between scripts quickly is very important. Because of that, C4DT adds several navigation features:
Eclipse Multitouch to navigate back and forth using gestures.
Lookup Declaration: From any script or when having selected a file in the project explorer, you can invoke Lookup Declaration from the Clonk menu (also a candidate for a nice keyboard assignment). You can then filter all the declarations from the current selection (either the project selected in the project explorer or the script being currently edited including its #includes) using regular expressions and jump to the declaration of any identifier matched by the expression.
Getting Content Assistance
When you are editing a script you can invoke a list offering you identifiers to insert. This list is context-sensitive so it will display different options depending on whether the cursor is inside a function or not or whether you are invoking it after having written '->'. The short cut for the Content Assist list is Ctrl+Space but like any other short cut it can be changed in the preferences.
Improvements compared to generic text editors
The C4Script editor adds special behaviour for some situations. Those are:
C4DT Editors fill the Outline view with an outline of the files being edited. The default Clonk perspective places the outline on the left below the Project Explorer.
The outline allows you to filter the list of declarations using a regular expression or wildcard.
The outline also shows types of variables and return types of functions, as inferred by the internal C4Script parser. Of course, since C4Script is relatively dynamic in its nature with eval and arbitrary attribute setting and the like, all those type inferences are without guarantee and might not reflect the true usage of the variable. A question mark following the type signals that the parser detected the possibility of the variable having just about any type so the weather forecast character is even more pronounced in that case.
Type guesses in the form of [x-y: <type>] represent cases where the expression is anticipated to have some array type where the range from x to y is of the given type. There could also be some additional '…' thrown in which would signify that the array will probably have more elements at runtime than those in the specified range.
Errors & Warnings
The script parser built into C4DT tries to detect lots of potential and actual errors, which are listed in the problems view. A script is reparsed when it gets saved. In some cases errors might become stale and won't get removed from the list automatically. What you can then do is Clean the project using Project -> Clean. This will reparse all the scripts in either the entire workspace or specific projects and hopefully remove the false errors.
For a list of warnings & errors take a look at ParserErrorCode.java.
Errors and Warnings listed in the Problems View can be individually deactivated if they annoy you. To do that, open up the properties window for the project you want to configure, select the Clonk category and deactivate kinds of errors/warnings to your heart's content.
For certain common cases of errors, c4dt offers automatic quick fixes which are offered to you when you press Ctrl/⌘+1 while having the cursor in a script inside a region marked as erroneous/problematic.
C4DT adds a handful of views. Two of them will get placed in the same tabzone as the Outline view by the Clonk perspective.
- The Preview view serves as a replacement for the preview feature found in the Clonk Editor.
- The Clonk Folder view enables quick access to packed c4group files inside the game folder of the engine set for the project whose files you are currently editing.
When updating your local repository clone, Eclipse tends to get confused because it keeps its own cache of file contents which won't match with the actual file contents after updating, so messages like 'This and that is out of sync with the file system' will pop up. To remedy that, you can open the General->Workspace preferences and set the settings as shown on the right.