OpenClonk Wiki - User contributions [en]

C4DT Installation Guide

2013-11-08T19:41:21Z

Domtron: /* Prerequisites */

==Prerequisites==
First you need to install Eclipse itself. This is relatively straightforward. Go to the [http://eclipse.org/downloads/ 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 [http://askubuntu.com/questions/282951/how-to-completely-uninstall-eclipse 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.
[[File:Eclipse_InstallWindow.png|left]] 

C4DT's Update Site is currently [http://www.openclonk.org/c4dt/ 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:
[[File:EclipseAvailableFeatures.png|left]] 
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 [http://www.eclipse.org/babel/downloads.php 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==
[[File:Eclipse_ChoosePerspective.png|right]] 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...". [[File:Eclipse_Perspectives.png|border|right]] 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: 
[[File:Eclipse_DefaultClonkPerspective.png|border]] 

==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: 
[[File:Eclipse_ClonkPreferences.png|left]] 
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.
[[File:Eclipse_NewClonkProject.png|left]] 
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 ([[File:EclipseLinkedGroup.png]])
::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:
[[File:Eclipse_OpenClonkProjectCreated.png]] 
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.

Temporary test page for content development with Eclipse

2013-11-04T02:23:32Z

Domtron:

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment 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 [[C4DT_FAQ#Eclipse and C4DT FAQ's|Eclipse FAQ section]] or post your question in our [http://forum.openclonk.org/board_show.pl?bid=16 help forum]. Please notify us of any problems or bugs with this guide on the help forum

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

Temporary test page for content development with Eclipse

2013-11-04T02:12:34Z

Domtron:

=Introduction=

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment 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 [[C4DT_FAQ#Eclipse and C4DT FAQ's|Eclipse FAQ section]] or post your question in our [http://forum.openclonk.org/board_show.pl?bid=16 help forum]. Please notify us of any problems or bugs with this guide on the help forum

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

Temporary test page for content development with Eclipse

2013-11-04T02:08:26Z

Domtron: /* Introduction */

=Introduction=

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment 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 [[C4DT_FAQ#Eclipse and C4DT FAQ's|Eclipse FAQ section]] or post your question in our [http://forum.openclonk.org/board_show.pl?bid=16 help forum]. Please notify us of any problems or bugs with this guide on the help forum

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

Temporary test page for content development with Eclipse

2013-11-03T23:51:41Z

Domtron: /* Introduction */

=Introduction=

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment Integrated Development Environment] (IDE) written in Java, and is available from [http://eclipse.org/downloads/ the eclipse download page]. For the purpose of Clonk development, download the ''Eclipse IDE for Java Developers'' package. In order for Eclipse to be aware of C4Scripts and other Clonk-related files a plugin has to be installed. An explanation on how to do that can be found in the [[C4DT Installation Guide]]. Once you understand the basics of using Eclipse and C4DT for content creation you can continue onto the next step in the [[Content Developers Guide]]

==Problems==
If you run into any problems while using Eclipse checkout our [[C4DT_FAQ#Eclipse and C4DT FAQ's|Eclipse FAQ section]] or post your question in our [http://forum.openclonk.org/board_show.pl?bid=16 help forum]. Please notify us of any problems or bugs with this guide on the help forum

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

Temporary test page for content development with Eclipse

2013-11-03T15:57:07Z

Domtron: /* Problems */

=Introduction=

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment Integrated Development Environment] (IDE) written in Java, and is available from [http://eclipse.org/downloads/ the eclipse download page]. For the purpose of Clonk development, download the ''Eclipse IDE for Java Developers'' package. In order for Eclipse to be aware of C4Scripts and other Clonk-related files a plugin has to be installed. An explanation on how to do that can be found in the [[C4DT Installation Guide]]. Once you understand the basics of using Eclipse and C4DT for content creation you can continue onto the next step in the [[Content Developers Guide]

==Problems==
If you run into any problems while using Eclipse checkout our [[C4DT_FAQ#Eclipse and C4DT FAQ's|Eclipse FAQ section]] or post your question in our [http://forum.openclonk.org/board_show.pl?bid=16 help forum]. Please notify us of any problems or bugs with this guide on the help forum

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

Temporary test page for content development with Eclipse

2013-11-03T15:56:15Z

Domtron: /* Problems */

=Introduction=

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment Integrated Development Environment] (IDE) written in Java, and is available from [http://eclipse.org/downloads/ the eclipse download page]. For the purpose of Clonk development, download the ''Eclipse IDE for Java Developers'' package. In order for Eclipse to be aware of C4Scripts and other Clonk-related files a plugin has to be installed. An explanation on how to do that can be found in the [[C4DT Installation Guide]]. Once you understand the basics of using Eclipse and C4DT for content creation you can continue onto the next step in the [[Content Developers Guide]

==Problems==
If you run into any problems while using Eclipse checkout our [[C4DT_FAQ#Eclipse and C4DT FAQ's|FAQ's Eclipse section]] or post your question in our [http://forum.openclonk.org/board_show.pl?bid=16 help forum]. Please notify us of any problems or bugs with this guide on the help forum

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

Temporary test page for content development with Eclipse

2013-11-03T15:53:52Z

Domtron: Removed FAQ section and added a problems section that links to the general FAQ page.

=Introduction=

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment Integrated Development Environment] (IDE) written in Java, and is available from [http://eclipse.org/downloads/ the eclipse download page]. For the purpose of Clonk development, download the ''Eclipse IDE for Java Developers'' package. In order for Eclipse to be aware of C4Scripts and other Clonk-related files a plugin has to be installed. An explanation on how to do that can be found in the [[C4DT Installation Guide]]. Once you understand the basics of using Eclipse and C4DT for content creation you can continue onto the next step in the [[Content Developers Guide]

==Problems==
If you run into any problems while using Eclipse checkout our [[C4DT_FAQ#Eclipse and C4DT FAQ's|FAQ's Eclipse section]] or post your question in our [http://forum.openclonk.org/board_show.pl?bid=16 help forum].

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

C4DT FAQ

2013-11-03T15:16:36Z

Domtron: added a section for Elipse and C4DT FAQ's and moved the eclipse question under that.

==Eclipse and C4DT FAQ's==
===Eclipse corrupts my png files when I edit them in a graphics program===
You can go to Preferences -> General -> Editors -> File Associations and add a new file association for *.png files to ensure that png will always be opened in an external editor of your choice and not in an editor tab inside Eclipse.

Temporary test page for content development with Eclipse

2013-11-03T14:24:10Z

Domtron: /* Introduction */ Changed a few sentences so the intro would work with the new larger guide.

=Introduction=

This guide covers the basics of using Eclipse to create, organize, and test content for Open Clonk. Eclipse is an extensible opensource [http://en.wikipedia.org/wiki/Integrated_development_environment Integrated Development Environment] (IDE) written in Java, and is available from [http://eclipse.org/downloads/ the eclipse download page]. For the purpose of Clonk development, download the ''Eclipse IDE for Java Developers'' package. In order for Eclipse to be aware of C4Scripts and other Clonk-related files a plugin has to be installed. An explanation on how to do that can be found in the [[C4DT Installation Guide]].

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

=End=
If you have had any problems please checkout the FAQ below or post the question on our [http://forum.openclonk.org/board_show.pl?bid=16 forums]. Now that you know how to use Eclipse and C4DT for content creation you can continue with the [[Content Developers Guide]].

= FAQ =
==Eclipse corrupts my png files when I edit them in a graphics program==
You can go to Preferences -> General -> Editors -> File Associations and add a new file association for *.png files to ensure that png will always be opened in an external editor of your choice and not in an editor tab inside Eclipse.

Temporary test page for content development with Eclipse

2013-11-02T17:15:18Z

Domtron:

=Introduction=

Eclipse is an extensible opensource IDE written in Java. It can be obtained from [http://eclipse.org/downloads/ the eclipse]. For the purpose of Clonk development the ''Eclipse IDE for Java Developers'' package will do. In order for Eclipse to be aware of C4Scripts and other Clonk-related files a plugin has to be installed. An explanation on how to do that can be found in the [[C4DT Installation Guide]]. Below is a list of tutorials to introduce you to C4DT, the Clonk Development Tools for Eclipse.

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

=End=
If you have had any problems please checkout the FAQ below or post the question on our [http://forum.openclonk.org/board_show.pl?bid=16 forums]. Now that you know how to use Eclipse and C4DT for content creation you can continue with the [[Content Developers Guide]].

= FAQ =
==Eclipse corrupts my png files when I edit them in a graphics program==
You can go to Preferences -> General -> Editors -> File Associations and add a new file association for *.png files to ensure that png will always be opened in an external editor of your choice and not in an editor tab inside Eclipse.

Temporary test page for content development with Eclipse

2013-11-02T16:30:50Z

Domtron: Merged several separate pages about using eclipse for OC content development into one page. Tweaks are needed for image placements and the general flow of the guide.

=Introduction=

Eclipse is an extensible opensource IDE written in Java. It can be obtained from [http://eclipse.org/downloads/ the eclipse]. For the purpose of Clonk development the ''Eclipse IDE for Java Developers'' package will do. In order for Eclipse to be aware of C4Scripts and other Clonk-related files a plugin has to be installed. An explanation on how to do that can be found in the [[C4DT Installation Guide]]. Below is a list of tutorials to introduce you to C4DT, the Clonk Development Tools for Eclipse.

=C4DT Basic Usage=
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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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==
[[File:C4DT_Run_Scenario.png|right]] 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===
[[File:C4DT_Debug_Persp.PNG|right]] 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.
[[File:C4DT_Breakpoint.PNG|right]] 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"). 
[[File:C4DT_Debug_Button.PNG|right]] 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===
[[File:C4DT_Variables_View.PNG|right]] The Variables view displays local variables and parameters of the function being executed. 

===Expressions===
[[File:C4DT_Expressions_View.PNG]] 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".

=End=
If you have had any problems please checkout the FAQ below or post the question on our [http://forum.openclonk.org/board_show.pl?bid=16 forums].Now that you know how to use Eclipse and C4DT for content creation you can continue with the [[Content Developers Guide]].

= FAQ =
==Eclipse corrupts my png files when I edit them in a graphics program==
You can go to Preferences -> General -> Editors -> File Associations and add a new file association for *.png files to ensure that png will always be opened in an external editor of your choice and not in an editor tab inside Eclipse.

User talk:Domtron

2013-11-02T15:57:50Z

Domtron: Created page with "temporary test page for content development with Eclipse"

[[temporary test page for content development with Eclipse]]

C4DT Editors

2013-11-02T15:51:17Z

Domtron: added a missing that caused the for the next paragraph to be rendered as text on the page.

==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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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.

C4DT Editors

2013-11-02T15:47:44Z

Domtron: added a missing that caused the for the next paragraph to be rendered as text on the page.

=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:
*[[File:Eclipse_Hyperlinks.png|right]] '''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$). [[File:Eclipse_HyperlinksIni.png|right]] Identifiers in ini editors can also be turned into hyperlinks.
 
*[[File:Clonk_OpenObject.png|right]] '''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.
 
[[File:Eclipse_BackForward.png|right]] '''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 [http://marketplace.eclipse.org/content/eclipse-multi-touch Eclipse Multitouch] to navigate back and forth using gestures.
 
[[File:Eclipse_DeclarationsFilter.png|right]]
'''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.
[[File:Eclipse_ContentAssist.png]] 

==Improvements compared to generic text editors==
The C4Script editor adds special behaviour for some situations. Those are:
*[[File:Eclipse_AutomaticBlock.png|right]] 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. 
*[[File:Eclipse_AutomaticParmBrackets.png|right]] 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. 
*[[File:Eclipse_ParmHint.png|right]]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 '->'. 
*[[File:Eclipse_AutoFunction.png|right]] 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==
[[File:Eclipse_Outline.png|right]] 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==
[[File:Eclipse_ProblemsView.png|right]]

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 [http://bitbucket.org/mortimer/c4dt/src/tip/C4DT/src/net/arctics/clonk/parser/ParserErrorCode.java 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.
[[File:Eclipse_ProblemsFilter.png]]

==Quick Fixes==
[[File:Eclipse_QuickFix.png|right]]
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==
[[File:Eclipse_AutoRefresh.png|right]]
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.

Tutorial: Scenario Creation

2013-10-31T03:36:24Z

Domtron: /* Starting a Scenario in Editor Mode */

'''Hello and welcome to this guide on how to create your own scenarios for OpenClonk!'''

This tutorial will show you how to make maps for OpenClonk.
It's up to you if you want to create a settlement scenario, an arena, a parcour or whatever. Here you will learn the basics and then you can visit one of the follow-up tutorials for the type of scenario you would like to make.

I will use the Eclipse C4DT Editor, so if you did not already, follow [[C4DT Installation Guide|'''this guide''']] for installing and setting it up properly.

==First Steps==
Fire up Eclipse, you should be presented with your OpenClonk project. Right click on it and select New -> Szenario. In the following configuration window, you can specify the directory, the folder name (the name you see inside Eclipse), and the scenario titel itself. I recommend you to keep those two names the same so it doesn't get too confusing.

[[File:SetName.png]]

After hitting the Finish button, your scenario will most likely appear somewhere at the bottom, so press F5 to refresh and it will jump in it's place.

==Landscape==

Before continuing, let's talk a bit about the landscape. The landscape - also called map - is a fundamental part of any scenario. After you have finished the concept for your scenario and created the necessary files, designing a landscape is probably your first priority. In OpenClonk there are three ways to make landscapes, these are:
* Dynamic maps using Scenario.txt, which have the drawback of just being stretched and scaled sinusoidal chunks of different materials. This is an obsolete feature and should rather not be used as the landscapes it produces are very boring.
* Generated maps using a Landscape.txt file where you can create dynamic landscapes using complex algorithms. A lengthy tutorial about the map generator can be found [[Tutorial: Map Generator - The Basics|'''here''']].
The choice for either a static map or a generated dynamic map depends on the scenario design, adventures rather use static maps opposed to settlement rounds.
* Static maps which store a hand-drawn landscape in a Map.bmp file, where each pixel represents a certain amount of pixels ingame. This is the method which will be covered in this tutorial.

==Preparations for Static Map Creation==

Expand your newly created scenario by clicking on the little arrow beneath it and open up the file called "Scenario.txt". This file contains information about the scenario that will be executed at startup ([http://docs.openclonk.org/en/sdk/scenario/scenario.html more information]). 
Scroll down to the "[Landscape]" section and delete everything in it except ''MapWidth'' and ''MapHeight''. Those two values determine the map size. Changing them after having painted something won't have any effect, so choose them carefully. If you are not sure, think of a scenario which is about the size you would like yours to have and look up it's map size. This is how Scenario.txt looks like in my case:

[[File:Scentxt.png]]

Save and close the file.

Now we're gonna delete the file "Landscape.txt", it is for dynamic map generation and we want to paint our map manually, so we do not need it.

==Starting a Scenario in Editor Mode==
To edit a map, you have to start your scenario in Editor Mode, which gives you access to various editing tools. You can start a scenario with or without players. Unfortunately, it is not possible to toggle players inside Eclipse (yet), so you have to start OpenClonk and (de)activate players in the "Player Selection" dialogue. 
When starting without players, the game starts paused and you have to open a viewport yourself via Viewport -> New. I recommend you to start with a player though, because the viewport scrolling bars are broken and you can navigate better with the camera following a clonk. 
Either way, to start the scenario, select it and press the little play button in the action bar at the top.

[[File:StartButton.png]]
| |
| |
V V
[[File:TUT-SCEN_EMStart.png]]

And you will start in a perfectly clean world. Best conditions for creating your masterpiece, so let's get to the fun part! There are various tools available to design a map, they are explained in the next chapter:

==Map Editing Tools==
(See [http://docs.openclonk.org/en/sdk/console.html this page] for more details.)

'''Pause/Resume Buttons:''' [[File:TUT-SCEN_PauseResume.png]] 
As the name suggests, you can pause and resume the game using these. Left and right to them, you can see a frame counter, a real time counter, and the current FPS.

'''Game Cursor:''' [[File:TUT-SCEN_GameCursor.png]] 
This cursor is the same as the ingame cursor, you can use it to throw objects, shoot arrows, and do all the other mouse control stuff. 
'''Note:''' You can only zoom with the scrolling wheel when this cursor is selected. Otherwise, you have to use F5/F6.

'''Editing Cursor:''' [[File:TUT-SCEN_EditingCursor.png]] 
With this cursor, you can select objects, drag them around, duplicate them, and delete them. Try selecting your Clonk and drag him around. If there are multiple objects overlapping, you can rightclick and select the one you want in the contextmenu. 
When you pick the editing cursor, a properties window appears, and you can see the cursor position coordinates alongside the name of the object currently hovering over in the lower left corner of the engine window. These coordinates are especially important when it comes to determining the starting position or placing objects via script. 
You can delete and duplicate objects, and also access their contents, in the right click contextmenu.

'''Landscape Brush:''' [[File:TUT-SCEN_LandscapeBrush.png]] 
Select this tool, and a little window will appear with all the options greyed out, which says "Dynamic landscape". This means that the map is generated randomly on scenario start based on special [http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html Map Generator code.] (The Landscape.txt file we deleted, remember?) But since that's a bit more complicated and we just want to paint the map straight away inside the viewport, we're gonna switch to the second option: "Static landscape". 
Static landscape means you can paint a map with all the different materials, save the map into a Map.bmp file, and on next startup, you get the same map. 
'''Important:''' Do ''not'' use the third type, "Exact landscape". It generates way too big files and is buggy, so you can loose all your progress. 
[[File:TUT-SCEN_BrushTools.png]] 
The options in this window are pretty straightforward if you are familiar with an image editor like [http://www.gimp.org/ GIMP]. There are different brush types, you can adjust the stroke thickness with the slider, and you can select a material-texture combination. The right texture for each material is chosen automatically, but for some materials, like earth, there are multiple textures available, these are the ones above the hyphen. (You could theoretically also choose a texture from below and e.g. make gold which looks like rock.) Use the different textures to bring more diversity into your maps. 
The two buttons right to the slider determine the background appearing when the painted material is dug or blasted free. The lower one is tunnel background, the default, which is fine for most cases. However, you might want it to be sky background in a sky islands scenario for example.

'''Log:''' 
[[File:TUT-SCEN_Log.png]] 
The log is where all the information is displayed, like status messages, errors and executed functions.

'''Commandline:''' [[File:TUT-SCEN_Commandline.png]] 
Is used to execute global script commands. You can click the little expand arrow to bring up list of ''all'' available functions. (Which are indeed quite a lot.)

'''Adding Objects:'''
All the original objects are stored inside the Objects.ocd folder. You can add an object to your map by simply dragging the ocd file into the viewport.

'''Saving:'''
The engine doesn't save your changes automatically, so save your scenario frequently. Do this by selecting File -> Save scenario in the engine window. The log will say "Scenario saved." and you can quit with peace of mind. 
'''Note:''' Delete your Clonk before saving, otherwise there will be an "Object XY is missing!" error on startup.

==Follow-up Tutorials==

Now you can design all sorts of maps, but just a pretty landscape isn't enough - for a complete scenario, you need things like goals, spawnpoints, etc. You will learn how to do this stuff in the follow-up tutorials:

[[How to Create a Settlement Scenario|'''How to Create a Settlement Scenario''']]

[[How to Create an Arena Scenario|'''How to Create an Arena Scenario''']] - ''Not yet available''

Those are planned for the near future, but I hope there will be more to come.

About

2013-10-30T21:34:40Z

Domtron: "What is Clonk" section edit. I tried to improve the last sentence's syntax to make it sound better.

OpenClonk is the [http://en.wikipedia.org/wiki/Open_source Open source] successor of the '''Clonk gaming series'''.

OpenClonk is a project dedicated to the further development of the Clonk game series. Our goal is to improve and make the real strengths of Clonk more fun to play: Bustling mining, production lines and economy, fast and fiddly melees. Another focus lies on the further enchancement of the game engine and the extensibility/modability of the game content with [[C4Script Documentation|C4Script]] which has always been one of the most important features of Clonk.

== What is Clonk? ==
[[File:ClonkDigging.png|right]]
Clonk is a multiplayer-action-tactics-skill game. It is often referred to as a mixture of The Settlers and Worms. In a simple 2D antfarm-style landscape, the player controls his crew of Clonks, small but robust humanoid beings. The game encourages free play but the normal goal is to either exploit valuable resources from the earth by building a mine or fight each other on an arena-like map.

== History ==

The inventor of the game is Matthes Bender.
The first Clonk was a two player melee game in which the players fought with rocks, flints (basic explosives) and catapults. Through several versions Clonk developed into a hectic and quite complicated game with numerous tactics and possibilities. The classic versions of the game are freeware and can be downloaded from [http://www.clonk.de clonk.de] (may be in German only).

The newer versions of Clonk series (Clonk 4, Planet, Endeavour and Rage) are mostly based on the engine of Clonk 4. Clonk Planet (2000) was the first game in the series with a built-in developer mode that enabled the player to actually develop their own mods for the game. Permitting access the core scripts of the objects and scenarios, the developer mode became one of the most beloved features of Clonk. Thousands of player made and still make mods that are accessible on the [http://www.ccan.de CCAN], the main download archive. Single objects but also big settlements packs or adventures are available. On the [http://www.clonkforge.net Clonk Forge], hobby developers come together to collaborate and contribute to each others clonk development projects.
Since Clonk Planet, new original game content was continuously added to the main game, for example the knight pack (introducing the knight as a new type of Clonk and medieval battles), the fantasy pack (with a powerful mage and new magic spells) or the FarWorlds (uncommon places such as the Arctic, the Jungle and the Deep-sea). The scripts of the objects and scenarios are written in Clonk's own scripting language: [[C4Script Documentation|C4Script]] (with a C-style syntax).

In the last years the Clonk community grew continuously, even beyond the borders of the German speaking countries.

In early March 2009, Matthes Bender told the other developers of Clonk Rage that he wouldn't have any time to work on Clonk anymore. As the Lead Designer of Clonk since Clonk 1 and Directing Manager of RedWolf Design, the company selling the Clonk titles, he left a significant vacancy. The development of Clonk Rage, the last commercial Clonk title, was mostly done as a hobby by the other developers and although they wanted to continue doing that, they felt that more contributors were needed. RedWolf Design agreed to put the game engine's source code under an open source license, the [[License#The_ISC_license | ISC license]].
The source code was published in a public repository, allowing everyone to freely modify the source code and game content and discuss the future directions in an open forum. This big change gave us the opportunity to redesign the deadlocked structures of the shareware Clonk titles. By giving up the downward compatibility new concepts become possible. So it was also decided to drop a lot of the "old" game content and drop the [[FAQ#Why_do_you_start_from_scratch_regarding_the_game_content.3F|backwards compatibility requirement]].