Temporary test page for content development with Eclipse
This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource Integrated Development Environment (IDE) written in Java. Before you can start this guide you need to follow the instructions in the C4DT Installation Guide.
Once you have finished reading this guide and have a basic understanding of the C4DT interface you can continue onto the next step in the Content Developers Guide
Problems
If you run into any problems while using Eclipse checkout our Eclipse FAQ section or post your question in our help forum. Please notify us of any problems or bugs with this guide on the help forum
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:
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$). Identifiers in ini editors can also be turned into hyperlinks.
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.
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.
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:
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.
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.
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 '->'.
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
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.
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.
Quick Fixes
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
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.
Running Scenarios from Eclipse
You can run scenarios by selecting it in the Project Explorer and then selecting the option Run Scenario found in the popup menu of the Run button (the green one with the white play symbol).
Debugging
To execute scripts one-instruction-at-a-time and inspect values while the script is halted, you have to switch to the debug perspective first. The layout of the main window changes to acommodate debugging. You can still arrange the views as you want but changes to the layout done while in the debug perspective will stay in the debug perspective, so as soon as you switch back to the Clonk perspective your old layout will be restored.
Apart from window layout there are also some keyboard shortcuts that become available. Among those is the shortcut to create a breakpoint. By default, it's Ctrl+Shift+B. You can open any c4script and place a breakpoint in a line that contains function code by using that shortcut (or alternatively right-clicking the ledge on the left and clicking "Toggle Breakpoint").
To run a scenario in debug mode all you have to do is pressing the Debug button instead of the Run one. The engine will now be halting script execution as soon as it encounters an instruction marked by a breakpoint. Eclipse will highlight the location where script execution halted. Now various views can be utilised to gain information about the current state of variables and objects. More on those views below.
Now that execution is halted you can do three things:
Step Into: The instruction at the current execution position will be executed. If the instruction contains a function call, the debugger will jump into the function and allow you to continue stepping inside that function. Default keystroke: F5
Step Over: Same as Step Into with the exception that the debugger won't go into subordinate function calls. Default keystroke: F6
Resume: Resume script execution. The engine will run normally until the next breakpoint is encountered. Default keystroke: F8
Variables
The Variables view displays local variables and parameters of the function being executed.
Expressions
The expressions view displays a list of user-defined expressions that get evaluated after every execution step. It is evaluated in the context of the calling object so expressions like "GetName()" will work as expected. Local variables and parameters can in principle be used in expressions but evaluation of such expressions might be buggy.
To add new expressions right-click into the view and select "Add Watch Expression".
