C4DT Editors

Introduction

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.

Navigation

Navigating to and between scripts quickly is very important. Because of that, C4DT adds several navigation features:

  • Eclipse Hyperlinks.png
    Hyperlinks: All valid identifiers can be turned into links by pressing Ctrl/⌘ while hovering over the identifier with your mouse. When you click on them the declaration location of the thing the identifier is referring to will be opened. This works for variables, functions, definitions and also for StringTbl entries ($BlaBla$).
    Eclipse HyperlinksIni.png
    Identifiers in ini editors can also be turned into hyperlinks.


  • Clonk OpenObject.png
    Open Object Dialog: The Open Object dialog can be activated using the Clonk menu in the main menu. As soon as you start typing the dialog starts listing definitions that match the typed text.

Eclipse BackForward.png
Going back and forward: When clicking on hyperlinks or navigating to other files by any other means you will always be able to go back to the original file by either pressing Alt+Left or using the yellow arrows in the toolbar. On a Mac, you can also install Eclipse Multitouch to navigate back and forth using gestures.


Eclipse DeclarationsFilter.png

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.

Eclipse ContentAssist.png

Improvements compared to generic text editors

The C4Script editor adds special behaviour for some situations. Those are:

  • Eclipse AutomaticBlock.png
    Automatic block: When typing '{' and then pressing Return a block will be created automatically and the caret will be placed inside the block indented by one tab.
  • Eclipse AutomaticParmBrackets.png
    When you type '(' or '[' the corresponding closing bracket will be automatically inserted. In order to not interrupt your typing those inserted closing brackets will be overridden if you type them by hand subsequently. In this special situation, pressing tab will cause the caret to jump over the closing bracket.
  • Eclipse ParmHint.png
    Parameter hints: As soon as you enter the brackets of a function call the parameters will be displayed above, not at all by chance similar to C4Scripter. The mechanism to find the right parameters to display is kind of smart and will also work when calling a function on an object using '->' as long as C4DT can deduce the object type of the expression left to '->'.
  • Eclipse AutoFunction.png
    When you want to declare a new function you can type the name and then invoke Content Assistance (Ctrl+Space). A function block will be created for you.

Outline

Eclipse Outline.png

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

Eclipse ProblemsView.png

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.

Eclipse ProblemsFilter.png

Quick Fixes

Eclipse QuickFix.png

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.

Additional Views

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.

Auto-Refresh

Eclipse AutoRefresh.png

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.