OpenClonk Wiki - User contributions [en]

Building with Windows

2014-04-19T09:50:51Z

Andriel: /* Get CMake */

[[DE:Kompilieren unter Windows|German Version here]]

= Get the sources =

The source of OpenClonk is hold in a so-called version control system. Put simply, this is something that allows programmers to coordinate their work (see [[Git Workflow|the Git article]] for how that works). For the moment, it's just a couple of files you want to download.

== Install TortoiseGit ==

The notable difference to a simple download is that you need a special program to do it. Our version control system is Git, and we will use the [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

As the website tells you, the installation of TortoiseGit has two parts: TortoiseGit and msysGit. It also says that you should start with TortoiseGit, so let us get that installer first. Make sure to choose the right architecture for your version of Windows:

[[File:build_windows_tgit2.png|860px]]

And walk through the installation. Just selecting the default options should get you through alright.

''OpenClonk team members:'' If you want to use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY] to push commits, make sure to select the appropriate option along the way. Do it again for the msysGit installation below.

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png|860px]]

This installation will ask even more confusing questions. But again default options won't cause anything to break, I would just recommend deactivating some GUI options, as TortoiseGit already offers them:

[[File:build_windows_tgit5.png]]

After a bit of waiting and (if you're lucky) not a single request to restart your computer, this should have given you a working TortoiseGit installation.

== Clone ==

Okay, now we are going to download the sources. Git calls this "cloning" because it's actually a lot more than just the sources you get. After you're done, you can check the [[Git Workflow]] page for how to work with your clone.

For now, just find a place where you want the source to be, open the context menu by right-click and select "Git Clone..." from the TortoiseGit menu:

[[File:build_windows_tgit6.png]]

A dialog will appear asking for the repository URL and the destination path. In our case, we want the source to be the OpenClonk repository. The URL you need is normally "git://git.openclonk.org/openclonk.git". Here's how it should look like:

''OpenClonk team members:'' Use "ssh://git@git.openclonk.org/openclonk.git" instead and activate the option to auto-load the PuTTY key for maximum convenience.

[[File:build_windows_tgit_pub.png]]

After pressing "OK", TortoiseGit will work for a while. After watching a tortoise somersaulting for a while, it should finish. Congratulations, you now have the bleeding edge of OpenClonk development on your hard drive!

[[File:build_windows_tgit_finish.png]]

This a lot of stuff and most likely you won't understand much of it. Here's a quick orientation guide of the actually important bits:
* "docs" - the sources of our [http://docs.openclonk.org/en/sdk/ documentation]
* "planet" - these are the game resources - scripts, graphics and everything to explain how to make a game out of them
* "src" - all the source code of the game engine. Lots of C++ ahead.

= Get it to Compile =

This is nice, but we are interested in seeing the game run, aren't we? For this, we need a program that will take all those C++ files and make an executable file out of it. Unfortunately, programming is complicated stuff so even setting up the tools and the environment has become a bit of science. But this won't stop us.

== Get Microsoft Visual Studio ==

You can say what you want about Microsoft, but they sure make nice development environments. And they are even giving a lot of it away for free. We will use [http://www.microsoft.com/visualstudio/eng/downloads#d-2012-express Visual Studio C++ 2012]. Follow that link, find the 2012 Express Edition '''for Windows Desktop''', then download the [http://go.microsoft.com/?linkid=9816758 web installer]:

[[File:msvc11_web_download.png|860px|Make extra sure you got the "Windows Desktop" variant.]]

Run it, accept the licensing terms, click the big "Install" link and accept the UAC prompt.

Then go make a coffee because the install will probably take a while. If the setup asks you to restart your computer, do so; it will continue when you log back in.

== Get Dependencies ==

Like most big programs, OpenClonk doesn't stand on its own. Some things (like opening PNG images) were already programmed by other programers far better than we could ever do. This is why we have to get a few so-called "libraries" before Clonk can be built.

You could expend some effort try to find, download, and compile all those libraries by yourself, but that would take quite some time. Instead, just download one of the packages we've provided for your convenience. If you're trying to build a 32-bit binary of OpenClonk or you don't really know what this is all about, use [http://www.nosebud.de/~nh/openclonk/openclonk-deps-vc110-i386.zip the x86 package]; for a 64-bit binary, use [http://www.nosebud.de/~nh/openclonk/openclonk-deps-vc110-amd64.zip the amd64 package]. Then unpack the .zip archive and put the "deps" folder into the directory where you also want your build files.

== Get CMake ==

Before all this becomes useful, we still need something that tells the compiler ''how'' all those sources and libraries should be compiled together.

For this, Visual C++ needs a project file. But there is none - we have to consult ''another'' program to generate it for us. This might seem confusing - but the point is that there are a lot of build environments besides Visual Studio, and having all those project files next to each other would become a problem in the long run.

What we need is [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File:build_windows_cmake2.png]]

After the installation, start the CMake GUI from the start menu. Put the path you cloned the repository into the source code path field.
You can set the build path to any directory you want, but it is important that the "deps" folder from the last step is also in that directory.

[[File:build_windows_cmake3.png]]

Now click the "Configure" button in the lower left. It will ask what compiler we want to use. Select the compiler you want to use; either "Visual Studio 11" if you downloaded the 32-bit library package above, or "Visual Studio 11 Win64" if you got the 64-bit package.

[[File:build_windows_cmake4.png]]

If you get some error messages (in red), you're probably missing some dependencies. Don't worry if cmake complains about some missing paths, it shouldn't affect you.

The last step is to click the "Generate" button.

== Your First Build ==

Okay, now we have everything needed to make OpenClonk run for the first time. Go into the source directory and double-click on the "openclonk.sln" file that should now have appeared:

[[File:build_windows_build1.png]]

Visual C++ should open and look similar to this:

[[File:build_windows_build2.png]]

We only want to build the engine, so select "openclonk" from the list, right-click and select "Set as Start-Up project"

[[File:build_windows_build3.png]]

Now press F5 (or, if you prefer, click the "Local Windows Debugger" button in the tool bar). Visual Studio will notice that you don't actually have a current compiled version of OpenClonk yet. Tell it to build one, and if you like also tell it to always just automatically build a new version using the check box.

[[File:build_windows_outofdate.png]]

If all goes well, after a couple of minutes you'll be looking at the OpenClonk main menu.

[[File:Openclonk_first_start.jpg]]

In case you are wondering why OpenClonk suddenly starts in some kind of pseudo windowed mode: This is because we just built a debug build (note the "dbg" after the version?). This build is a bit slower but allows you to get a better look at the internals of the engine while it's running. Maybe we'll have another article about that soon.

Building with Windows

2014-04-19T09:48:10Z

Andriel: /* Get Dependencies */

[[DE:Kompilieren unter Windows|German Version here]]

= Get the sources =

The source of OpenClonk is hold in a so-called version control system. Put simply, this is something that allows programmers to coordinate their work (see [[Git Workflow|the Git article]] for how that works). For the moment, it's just a couple of files you want to download.

== Install TortoiseGit ==

The notable difference to a simple download is that you need a special program to do it. Our version control system is Git, and we will use the [http://code.google.com/p/tortoisegit/ TortoiseGit] client. Follow that link and click "Download".

[[File:build_windows_tgit.png|860px]]

As the website tells you, the installation of TortoiseGit has two parts: TortoiseGit and msysGit. It also says that you should start with TortoiseGit, so let us get that installer first. Make sure to choose the right architecture for your version of Windows:

[[File:build_windows_tgit2.png|860px]]

And walk through the installation. Just selecting the default options should get you through alright.

''OpenClonk team members:'' If you want to use [http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html PuTTY] to push commits, make sure to select the appropriate option along the way. Do it again for the msysGit installation below.

[[File:build_windows_tgit4.png]]

Next, you need msysGit, which is what actually does all the work behind the scenes. Following the [http://code.google.com/p/msysgit/downloads/list?can=2&q=%22Full+installer+for+official+Git+for+Windows%22 "Full installer for official Git"] link will get you to another download page:

[[File:build_windows_tgit3.png|860px]]

This installation will ask even more confusing questions. But again default options won't cause anything to break, I would just recommend deactivating some GUI options, as TortoiseGit already offers them:

[[File:build_windows_tgit5.png]]

After a bit of waiting and (if you're lucky) not a single request to restart your computer, this should have given you a working TortoiseGit installation.

== Clone ==

Okay, now we are going to download the sources. Git calls this "cloning" because it's actually a lot more than just the sources you get. After you're done, you can check the [[Git Workflow]] page for how to work with your clone.

For now, just find a place where you want the source to be, open the context menu by right-click and select "Git Clone..." from the TortoiseGit menu:

[[File:build_windows_tgit6.png]]

A dialog will appear asking for the repository URL and the destination path. In our case, we want the source to be the OpenClonk repository. The URL you need is normally "git://git.openclonk.org/openclonk.git". Here's how it should look like:

''OpenClonk team members:'' Use "ssh://git@git.openclonk.org/openclonk.git" instead and activate the option to auto-load the PuTTY key for maximum convenience.

[[File:build_windows_tgit_pub.png]]

After pressing "OK", TortoiseGit will work for a while. After watching a tortoise somersaulting for a while, it should finish. Congratulations, you now have the bleeding edge of OpenClonk development on your hard drive!

[[File:build_windows_tgit_finish.png]]

This a lot of stuff and most likely you won't understand much of it. Here's a quick orientation guide of the actually important bits:
* "docs" - the sources of our [http://docs.openclonk.org/en/sdk/ documentation]
* "planet" - these are the game resources - scripts, graphics and everything to explain how to make a game out of them
* "src" - all the source code of the game engine. Lots of C++ ahead.

= Get it to Compile =

This is nice, but we are interested in seeing the game run, aren't we? For this, we need a program that will take all those C++ files and make an executable file out of it. Unfortunately, programming is complicated stuff so even setting up the tools and the environment has become a bit of science. But this won't stop us.

== Get Microsoft Visual Studio ==

You can say what you want about Microsoft, but they sure make nice development environments. And they are even giving a lot of it away for free. We will use [http://www.microsoft.com/visualstudio/eng/downloads#d-2012-express Visual Studio C++ 2012]. Follow that link, find the 2012 Express Edition '''for Windows Desktop''', then download the [http://go.microsoft.com/?linkid=9816758 web installer]:

[[File:msvc11_web_download.png|860px|Make extra sure you got the "Windows Desktop" variant.]]

Run it, accept the licensing terms, click the big "Install" link and accept the UAC prompt.

Then go make a coffee because the install will probably take a while. If the setup asks you to restart your computer, do so; it will continue when you log back in.

== Get Dependencies ==

Like most big programs, OpenClonk doesn't stand on its own. Some things (like opening PNG images) were already programmed by other programers far better than we could ever do. This is why we have to get a few so-called "libraries" before Clonk can be built.

You could expend some effort try to find, download, and compile all those libraries by yourself, but that would take quite some time. Instead, just download one of the packages we've provided for your convenience. If you're trying to build a 32-bit binary of OpenClonk or you don't really know what this is all about, use [http://www.nosebud.de/~nh/openclonk/openclonk-deps-vc110-i386.zip the x86 package]; for a 64-bit binary, use [http://www.nosebud.de/~nh/openclonk/openclonk-deps-vc110-amd64.zip the amd64 package]. Then unpack the .zip archive and put the "deps" folder into the directory where you also want your build files.

== Get CMake ==

Before all this becomes useful, we still need something that tells the compiler ''how'' all those sources and libraries should be compiled together.

For this, Visual C++ needs a project file. But there is none - we have to consult ''another'' program to generate it for us. This might seem confusing - but the point is that there are a lot of build environments besides Visual Studio, and having all those project files next to each other would become a problem in the long run.

What we need is [http://www.cmake.org/cmake/resources/software.html#latest CMake]. Follow that link and download the installer:

[[File:build_windows_cmake1.png|860px]]

You know what to do.

[[File:build_windows_cmake2.png]]

After the installation, start the CMake GUI from the start menu. Put the path you cloned the repository into the source code path field.

[[File:build_windows_cmake3.png]]

Now click the "Configure" button in the lower left. It will ask what compiler we want to use. Select the compiler you want to use; either "Visual Studio 11" if you downloaded the 32-bit library package above, or "Visual Studio 11 Win64" if you got the 64-bit package.

[[File:build_windows_cmake4.png]]

If you get some error messages (in red), you're probably missing some dependencies. Don't worry if cmake complains about some missing paths, it shouldn't affect you.

The last step is to click the "Generate" button.

== Your First Build ==

Okay, now we have everything needed to make OpenClonk run for the first time. Go into the source directory and double-click on the "openclonk.sln" file that should now have appeared:

[[File:build_windows_build1.png]]

Visual C++ should open and look similar to this:

[[File:build_windows_build2.png]]

We only want to build the engine, so select "openclonk" from the list, right-click and select "Set as Start-Up project"

[[File:build_windows_build3.png]]

Now press F5 (or, if you prefer, click the "Local Windows Debugger" button in the tool bar). Visual Studio will notice that you don't actually have a current compiled version of OpenClonk yet. Tell it to build one, and if you like also tell it to always just automatically build a new version using the check box.

[[File:build_windows_outofdate.png]]

If all goes well, after a couple of minutes you'll be looking at the OpenClonk main menu.

[[File:Openclonk_first_start.jpg]]

In case you are wondering why OpenClonk suddenly starts in some kind of pseudo windowed mode: This is because we just built a debug build (note the "dbg" after the version?). This build is a bit slower but allows you to get a better look at the internals of the engine while it's running. Maybe we'll have another article about that soon.

Help:Editing

2014-03-16T17:56:55Z

Andriel: Created page with "Use <nowiki> </nowiki> for line break."

Use <nowiki> </nowiki> for line break.

Artists Guide

2014-03-16T17:53:43Z

Andriel: /* Exporting Meshes */

There are three main areas where artists can contribute: Modelling 3D objects and the texturing thereof, which requires different skills and doesn't need to be done by the same person. Most of our modellers use Blender, however which modeller you use is not important as long as it can export meshes to the OGRE format.
For creating scenario backgrounds, textures for models, scenario decoration and stuff, we actually need people who are good with Photoshop, GIMP or any other image manipulation software.
Also, we are in desperate need for people who are talented at creating sounds and/or music.

Have a look in the [http://forum.openclonk.org/board_show.pl?bid=2 art workshop].

__TOC__

== Modelling ==
[[File:Foundry_mesh.png|200px|thumb|right|The mesh of the foundry]] We got rid of the old graphics from Clonk Rage which were so tiny that it was already hard to play the game in a proper resolution. (The character you control smaller than a mouse cursor? Come on!) For OpenClonk, the graphics are about three times as big and detailed as in the old Clonk series.
Unlike in previous clonk titles, most objects are actually models that are rendered in game. The file format we use for this is the [http://www.ogre3d.org/ OGRE] format as it is a format designed to be used in games plus all important modellers can export into this format. However, we do exchange of the models in their native format (mostly .blend).

Now, for creating models that are to be rendered ingame (in OpenClonk), there are a few additional things that have to be considered if you are used to creating models that are rendered before the start of the game. Apart from the polygon count, for each model we only use one UV-mapped texture rather than zillion materials with different colors/googled textures. More guidelines on how to create a real time model for OpenClonk can be read here: [[Modelling Workflow]].

You might ask yourself if there is a guideline of how many polygons a model should max have. Yes, there is one: So many, that the object looks both good ingame with a 3x zoom and on it's picture graphic (whichever is bigger). Also, unanimated inventory items like materials don't need to be rendered ingame. As sprites, the polygon count doesn't matter.

Also, if you want to contribute a model, please always include the 3D-model when you attach a rendering of the same to your post. Otherwise, if you somehow lose your model, all the work was in vain.

== Textures ==
[[File:Foundry_texture.png|200px|thumb|left|UV mapped texture of the foundry]]
[[File:Foundry_render.png|200px|thumb|right|Foundry with mesh and texture]]
We use the [http://creativecommons.org/licenses/by/3.0/ CC-by] licence for OpenClonk and ask you to license your contributions under the same license. As many textures in texture archives have licenses which are not compatible with CC-by, we will have to create many textures on our own. But don't worry, it's quite easy and there are some really good tutorials on how to create quality textures from photos.

Here is a list of bigger texture archives and it's licenses which is a good source for resources: [[Texture Archives]]

My experience is that textures for 3D-models which are based on actual photos always turn out better then textures which where painted by oneself.

You might also ask yourself if there is a guideline of how big the texture for one 3D-model should be. Right: So big that it doesn't look blurred ingame with a 3x zoom and on it's picture graphic (whichever is bigger).

For material textures, we need seamless textures. Regarding this, there are different methods to create seamless textures from (a set of) photos, here is how I do it: [[Tutorial: Creating Seamless Textures]].
For GIMP, there are two filters which can do this automatically: The plugin ''[http://gimp-texturize.sourceforge.net/ Texturize]'' and the filter ''Resynthesise''. Both work good with textures with small random patterns like gravel, plaster, sand or ground. However, they don't produce quite as convincing results for bigger regular patterns like (roofing) tiles, bricks, wickerwork, pavements etc. The manual method that I proposed always produces better results and if you are experienced in this, it's a thing of five minutes.

== Exporting Meshes ==
Exporting a model properly for OpenClonk can be a tricky process, but we've compiled a step-by-step guide on how to do so.

'''Installing the Exporter Addon'''[[File:InstallingBlender2OgreAddon.png|200px|thumb|right|Enabling the addon.]]
Download the [http://code.google.com/p/blender2ogre/downloads/list blender2ogre exporter] for your version of Blender.

*Put the downloaded file 'io_export_ogreDotScene.py' into your [blender directory]/[version]/scripts/addons folder.
*Load up Blender, go to File>User Preferences>Addons>Import-Export and enable the "OGRE Exporter" addon. Then click on "Save User Settings".
You now have the exporter set up.

'''Exporting the Model''' 
(This is for objects without animations. For exporting animated objects, please refer to the [[NLA Hijacking]] guide and then continue at "Using the Exported Files") 

To export the model, select it (in Object Mode) and go to File>Export>Ogre3D (.scene and .mesh).
Models used for OpenClonk must be exported with specific options:
[[File:ExportSettingsStatic.png|450px|thumb|center|Use these settings for objects without animations.]]
After clicking "Export Ogre", you will be sent back to the 3D View and a Mini-Report will pop up, showing information about the exported mesh and potential errors.

'''Using the Exported Files'''[[File:ExportedFilesNew.png|250px|thumb|right|Typical bunch of exported files before user modification.]]
After you have exported the mesh, some files will be created in the chosen directory. You have to convert the ' .mesh.xml' file the exporter has created into the ' .mesh' format, the format used by OpenClonk, using the OgreXmlConverter.
Follow these steps:
*Obtain the [http://www.ogre3d.org/tikiwiki/OgreXmlConverter OGRE XML Converter software], bundled inside the OGRE Command Line Tools package (look in 'See Also' box for download).
*Extract the OGRE Command Line Tools somewhere easily accessible (ie: C:\OgreCommandLineTools).
*Drag'n'Drop the ' .mesh.xml' file onto OgreXMLConverter.exe
*Delete the ' .mesh.xml' file and the ' .log file' which has been created.
*Make sure the ' .mesh' file is named 'Graphics.mesh' and the ' .material' file is named 'Scene.material'.
*Put 'Graphics.mesh', the 'Scene.material' file, and any textures used by the mesh to your object definition.

'''Scene.material'''

Scene.material is the file which defines which materials to apply to meshes. Manually modifying Scene.material is crucial to the mesh appearing properly in game. When you export (assuming you are using a texture) your Scene.material file will look more or less like this (don't worry if it looks somewhat different):

<pre style="color:green;width:75%;background-color:#dcdcdc">
material MyCube
{
receive_shadows on
technique
{
pass
{
cull_hardware none
scene_blend alpha_blend

ambient 1.0 1.0 1.0 1.0
diffuse 1.0 1.0 1.0 1.0
specular 0.0 0.0 0.0 0.0 12.5
emissive 0.0 0.0 0.0 0.0

texture_unit
{
texture MyCube.png
tex_address_mode wrap
filtering trilinear
}
}
}
}</pre>
*If 'depth_write off' exists, delete that line.
*If you are using alpha, make sure 'scene_blend alpha_blend' exists (as shown above).
*If your mesh has visible backface(s), make sure to add 'cull_hardware none' (as shown above).
*Depending on the method you used to define alpha in blender, the 'pass' section in Scene.Material may look like this:
<pre style="color:green;width:75%;background-color:#dcdcdc">pass
{
ambient 0.500000 0.500000 0.500000 0.000000
diffuse 0.640000 0.640000 0.640000 0.000000
specular 0.500000 0.500000 0.500000 0.000000 12.500000
emissive 0.000000 0.000000 0.000000 0.000000
...</pre>
If so, make sure the fourth parameter on ambient, diffuse, specular, and emissive is '1.0', not '0.000000' (as shown in the 'material MyCube' example).

By following these steps, you should be able to properly export models for OpenClonk. If you run into any problems, please leave a post on the [http://forum.openclonk.org/board_show.pl?bid=16 forum] addressing the issue. (You don't have to register to post there)

== Sounds & Music ==
Any game is only half as good without proper sounds and music. If you played the titles of the old Clonk series, you will probably still suffer from the memories of the midi music from the last millenium, like "Pizza strings" or "On a razor blade". Anyway. So we need both people who are good at creating, editing (and searching) sound effects and talented people who can make music for OpenClonk.
There are some sound archives out there which have CC-licensed sound effects, also it can't hurt to ask the authors of one of the many many mods for commercial games if we are allowed to use their sounds under the terms of a CC-license (preferably CC-by).

Exporting Meshes From Blender 2.49b (Old Guide)

2014-03-16T09:55:47Z

Andriel: Created page with "'''WARNING: This is an old article for an outdated version of Blender! Please refer to the new article instead.''' ---- Exporting a mode..."

'''WARNING: This is an old article for an outdated version of Blender! Please refer to the [[Artists_Guide#Exporting_Meshes | new article]] instead.'''

----

Exporting a model properly for OpenClonk can be a tricky process, but we've compiled a step-by-step guide on how to do so.

Firstly, you'll need the proper tools. For [http://download.blender.org/release/Blender2.49b/ Blender 2.49b], you'll need the OGRE Exporter. Randrian has created an improved version of the OGRE Exporter which adds critical features necessary for animation blending. [http://attach.openclonk.org/9/17909/OgreExporterOC.zip Download Link]

*Extract the OGRE Exporter into your .blender/scripts/ folder.
*Install [http://www.python.org/download/releases/2.6.2/ Python 2.6.2]
*Obtain the [http://www.ogre3d.org/tikiwiki/OgreXmlConverter OGRE XML Converter software], bundled inside the OGRE Command Line Tools package (look in 'See Also' box for download).
*Extract the OGRE Command Line Tools somewhere easily accessible (ie: C:\OgreCommandLineTools).
*Load up blender, and create a new window and set the window type to 'Scripts Window'. Then click File>Export>OGRE Meshes to load the exporter GUI into that window.
*Hit the 'Preferences' button in the OGRE GUI. Set the location of the OGRE XML Exporter to Manual, and link to the location of the OgreXmlConverter.exe.
*In the directory of your .blend file, create an empty Actions.txt file. More on this later.
By following these steps, you should be able to properly export models for OpenClonk. If you run into any problems, leave a post on the forum addressing the issue.

'''Guidelines for Modelling'''
*Model on the Y/Z view-plane. Models in OpenClonk appear as they do on the Y/Z plane in blender. The X-Axis goes 'into' the screen. Make sure you model with regard to these axes (The Y/Z plane is the default side view in Blender).
*Do not use Mesh Transformations. Mesh transformations are not handled properly by the OGRE exporter, and will cause deformation in game. If you have transformations applied to an existing model, you can remove them (select the model and press alt+g, alt+s, alt+r). Caution: Avoid animating before removing transformations!
*3D Model must be Three-Dimensional. The 3D mesh must have length on all axes. Making a perfectly flat object on only two axes will cause it to not appear in-game. To fix this, move a vertex so the mesh has length on all axes.
*Avoid edges with more than two faces connected to them. Edges with more than two faces will cause shading errors in game. An easy way to circumvent this is to separate the third face from the edge, so it is close to the original edge, but not connected.
*What features work with the OGRE format? Not all of the features listed in Blender will affect an exported 3D OGRE mesh. For a full list of compatible features, visit: http://www.cs.ucr.edu/~macchiea/cs134/lab1/ogrehelp/ogremeshesexporter.html

'''Exporting the Model'''[[File:OgreExporter.png|200px|thumb|right|The OGRE Exporter frame in Blender]]
To export the model, you'll need to have a window for the OGRE exporter in Blender. Make a new pane for scripts, and click 'File/Export/OGRE Meshes'. Models used for OpenClonk must be exported with specific options.
*“Fix Up Axis to Y” should not be enabled.
*If you have the XML converter, make sure “OgreXMLConverter” is enabled.
*If you have already made manual modifications to the Scene.material file and are re-exporting the mesh and/or skeleton, make sure 'Export Materials' is not enabled.
*'Path:' will be where the OGRE files are exported to. You can use a temporary directory and then copy them into your OpenClonk object definition, or you can export the OGRE files directly into the object definition.

'''Using the Exported Files'''[[File:ExportedFiles.png|250px|thumb|right|Typical exported files before user modification.]]
Once you have exported the mesh, some files will be created in the chosen directory. Follow these steps:
*Make sure the “ .mesh” file is named “Graphics.mesh”.
*If you exported the OGRE files to a temporary directory, copy 'Graphics.mesh', the ' .skeleton' file, the 'Scene.material' file, and any textures used by the mesh to your object definition.
*If you have exported the OGRE files directly to your object definition, you can delete all .xml files and the .log file.

'''Scene.material'''

Scene.material is the file which defines which materials to apply to meshes. Manually modifying Scene.material is crucial to the mesh appearing properly in game. When you export (assuming you are using a texture) your Scene.material file will look more or less like this (don't worry if it looks somewhat different):

<pre style="color:green;width:75%;background-color:#dcdcdc">
material MyCube
{
receive_shadows on
technique
{
pass
{
cull_hardware none
scene_blend alpha_blend

ambient 1.0 1.0 1.0 1.0
diffuse 1.0 1.0 1.0 1.0
specular 0.0 0.0 0.0 0.0 12.5
emissive 0.0 0.0 0.0 0.0

texture_unit
{
texture MyCube.png
tex_address_mode wrap
filtering trilinear
}
}
}
}</pre>
*If 'depth_write off' exists, delete that line.
*If you are using alpha, make sure 'scene_blend alpha_blend' exists (as shown above).
*If your mesh has visible backface(s), make sure to add 'cull_hardware none' (as shown above).
*Depending on the method you used to define alpha in blender, the 'pass' section in Scene.Material may look like this:
<pre style="color:green;width:75%;background-color:#dcdcdc">pass
{
ambient 0.500000 0.500000 0.500000 0.000000
diffuse 0.640000 0.640000 0.640000 0.000000
specular 0.500000 0.500000 0.500000 0.000000 12.500000
emissive 0.000000 0.000000 0.000000 0.000000
...</pre>
If so, make sure the fourth parameter on ambient, diffuse, specular, and emissive is '1.00000', not '0.000000' (as shown in the 'material MyCube' example).

'''Actions.txt'''

This file controls what animations are exported, which frames of said animations, and which bones will be affected by the exported animations. Most often than not you will not need to use this functionality; your Actions.txt file could simply resemble this:
<pre style="color:green;width:25%;background-color:#dcdcdc">[Action]
Name=Open

[Action]
Name=Close

[End]</pre>

Other tags available for an [Action] include 'Start=', 'End=', 'ExportName=', and 'Group='.

Start and End will define the frames (in blender) that will be exported. ExportName will simply change the name of the Action on export (Useful if you have multiple versions of an animation but only need one exported).

A group is a special filter used to stop bones from affecting the exported animation. For example, if we want an aiming animation to only affect the upper body, or a blinking animation to only affect the character's eyelids.
Groups can either use the 'Include=' tag or 'Exclude=' tag.

As an example, a group which only affects the eyelids of the Clonk:
<pre style="color:green;width:25%;background-color:#dcdcdc">[Group]
Name=Eyelids
Include=eye_lid.R
Include=eye_lid.L
</pre>

This would make the exported animation only control the eye_lid.* bones and nothing else. Conversely, using the 'Exclude=' tag makes the animation use every bone excluding those defined. As an example:
<pre style="color:green;width:25%;background-color:#dcdcdc">
[Group]
Name=UpperBody
Exclude=skeleton_leg*
Exclude=skeleton_foot*
</pre>

Defining the group in an Action entry is fairly simple; just add the tag 'Group=' and enter the group's name. For example:
<pre style="color:green;width:25%;background-color:#dcdcdc">
[Action]
Name=CloseEyes
Group=Eyelids
</pre>

For an example of a finished Actions.txt file, [http://hg.openclonk.org/openclonk-resources/raw-file/9c271b749d31/models/Vehicles/catapult/Actions.txt this is the Catapult's].

Modelling Workflow

2014-03-16T09:52:18Z

Andriel:

In this article, I explain our workflow of creating a model for OpenClonk at the example of the lorry originally created by Mimmo. Also, I list things that are important to consider when modelling for use in OpenClonk.

== Guidelines for Modelling ==
*Model on the Y/Z view-plane. Models in OpenClonk appear as they do on the Y/Z plane in blender. The X-Axis goes 'into' the screen. Make sure you model with regard to these axes (The Y/Z plane is the default side view in Blender).
*Do not use Mesh Transformations. Mesh transformations are not handled properly by the OGRE exporter, and will cause deformation in game. If you have transformations applied to an existing model, you can remove them (select the model and press alt+g, alt+s, alt+r). Caution: Avoid animating before removing transformations!
*3D Model must be Three-Dimensional. The 3D mesh must have length on all axes. Making a perfectly flat object on only two axes will cause it to not appear in-game. To fix this, move a vertex so the mesh has length on all axes.
*Avoid edges with more than two faces connected to them. Edges with more than two faces will cause shading errors in game. An easy way to circumvent this is to separate the third face from the edge, so it is close to the original edge, but not connected.
*What features work with the OGRE format? Not all of the features listed in Blender will affect an exported 3D OGRE mesh. For a full list of compatible features, visit: http://code.google.com/p/blender2ogre/#Blender_to_Ogre_Exporter_Features

== Sketch ==
Every good modelling process starts with a sketch or some other image as a pattern. For the lorry, Mimmo used a picture from wikimedia commons.

[[File:Kipplore.jpeg|300px]]

== Low-Poly Model ==
This is the low-poly model of the lorry from Mimmo. If you plan to create both low- and high-poly models, always create the low-poly model first. I assume that you know how to model ;-)

[[File:Lorry.png|300px]]

The guideline on how low-poly the model should be is: The model with texture still needs to look good when displayed 3x the size as in Clonk Rage - there is no fixed number on how many polygons are good since it depends strongly on the model.

== Delete hidden faces ==
Details which can be displayed on the texture can be deleted. As you can see in the images, I deleted the bottom and top of the thing where the wheels are attached and replaced the top by a simpler geometry. This is actually all small shit and doesn't matter too much. You don't need to overdo this step as thanks to [http://en.wikipedia.org/wiki/Backface_culling#Backface_culling backface culling], faces that face away from the camera are not drawn anyway.

[[File:Lorry_bottom1.png|300px]]
[[File:Lorry_bottom2.png|280px]]

The lorry here is just a simple example of this removing-the-polygons step because of
# geometric details in the texture that go into the texture rather than in the model
# polygons that are inside other objects and thus never visible or hidden from any view to the object

When I first wrote this tutorial I suggested to delete the faces that face away from the camera. However, this is unecessary as noted above.

== UV unwrap ==
After having created the final low-poly model, create a good and clear UV map. The quality of the texture map (, normal map etc) strongly depends on the quality of this work, do not underestimate this step. However, I assume that you know how to unwrap a model ([http://www.blender.org/documentation/htmlI/x5336.html Tutorial for Blender]).
However, here are a few tips that are especially valid for OpenClonk:
* Mark the seams preferably on the backside of the model. E.g. if there is a cylinder, mark the seam on the side that is not seen ingame. Then the texturer doesn't need to worry (so much) about tileability.
* Regions of the model which are connected in the model should be connected in the uv map too as long as the uv mapping doesn't distort the whole thing (too much).
* Try to arrange the uv regions in a way that regions in the model which are upright are upright and not distorted in the uv map too. This helps the texturer a lot when he want to apply textures with a regular pattern like bricks.
* You can map faces that should look the same - like for example each of the 4 front wheels of the lorry - to the same position in the UV map.

[[File:Lorry_uv1.png|600px]]

If you don't plan to texture your model right away by yourself, be so kind and create and label a uv-map template and save it as an image. This helps the person who does the texturing work big deal; because the work of the texturing can be done (better) by 2D-artists and doesn't have to be up to the person who did the modelling.
Depending on the actual size of the model ingame, you can save the UV map template in different sizes. For the lorry, I chose 256x256 because it is a very tiny model.

[[File:Lorry_uv2.png|600px]]

== Texturing ==
As the model and texture for the lorry is already completed, I can show it to you here:

[[File:lorry_render.png|256px]]
[[File:lorry_tex.png|256px]]
[[File:lorry_uv.png|256px]]

Note that PNG textures can contain alpha. This is how transparency (imagine leaves on trees) is realized in OpenClonk.

== Animation and normal maps ==
After you created a UV map, you can add the animations if there are any. Additionally, if the model is egible for having a normal map, you can create a high-poly model of the lorry where you actually do model even the little geometric details. But keep in mind, to be able to bake a normal map with a high-poly model, the high- and low-poly model must have the same geometry ([http://blenderartists.org/forum/showthread.php?t=138194 Tutorial for Blender]). In Blender, there is a option called "multires" which allows you to create several models in different detail levels based on one low-poly model and it's geometry.

So when is a model egible of having a normal map. First there is to say that at this point of development we can not even say if we will be able to use normal maps. In general, creating normal maps for models only makes sense for those which have organic, round parts where too many polygons would need to be used. So, for blocky buildings it's normally not necessary - more for living creatures with one ([http://www.blender.org/development/release-logs/blender-246/render-baking/ Blender: example]) enclosing mesh.

Here is also a free to use tool with which easily all kinds of maps can be created: [http://www.crazybump.com/ CrazyBump]

Artists Guide

2014-03-16T09:51:33Z

Andriel: /* Exporting Meshes */

Modelling Workflow

2014-03-16T09:45:53Z

Andriel:

In this article, I explain our workflow of creating a model for open clonk at the example of the lorry originally created by Mimmo. Also, I list things that are important to consider when modelling for use in OpenClonk.

== Guidelines for Modelling ==
*Model on the Y/Z view-plane. Models in OpenClonk appear as they do on the Y/Z plane in blender. The X-Axis goes 'into' the screen. Make sure you model with regard to these axes (The Y/Z plane is the default side view in Blender).
*Do not use Mesh Transformations. Mesh transformations are not handled properly by the OGRE exporter, and will cause deformation in game. If you have transformations applied to an existing model, you can remove them (select the model and press alt+g, alt+s, alt+r). Caution: Avoid animating before removing transformations!
*3D Model must be Three-Dimensional. The 3D mesh must have length on all axes. Making a perfectly flat object on only two axes will cause it to not appear in-game. To fix this, move a vertex so the mesh has length on all axes.
*Avoid edges with more than two faces connected to them. Edges with more than two faces will cause shading errors in game. An easy way to circumvent this is to separate the third face from the edge, so it is close to the original edge, but not connected.
*What features work with the OGRE format? Not all of the features listed in Blender will affect an exported 3D OGRE mesh. For a full list of compatible features, visit: http://code.google.com/p/blender2ogre/#Blender_to_Ogre_Exporter_Features

== Sketch ==
Every good modelling process starts with a sketch or some other image as a pattern. For the lorry, Mimmo used a picture from wikimedia commons.

[[File:Kipplore.jpeg|300px]]

== Low-Poly Model ==
This is the low-poly model of the lorry from Mimmo. If you plan to create both low- and high-poly models, always create the low-poly model first. I assume that you know how to model ;-)

[[File:Lorry.png|300px]]

The guideline on how low-poly the model should be is: The model with texture still needs to look good when displayed 3x the size as in Clonk Rage - there is no fixed number on how many polygons are good since it depends strongly on the model.

== Delete hidden faces ==
Details which can be displayed on the texture can be deleted. As you can see in the images, I deleted the bottom and top of the thing where the wheels are attached and replaced the top by a simpler geometry. This is actually all small shit and doesn't matter too much. You don't need to overdo this step as thanks to [http://en.wikipedia.org/wiki/Backface_culling#Backface_culling backface culling], faces that face away from the camera are not drawn anyway.

[[File:Lorry_bottom1.png|300px]]
[[File:Lorry_bottom2.png|280px]]

The lorry here is just a simple example of this removing-the-polygons step because of
# geometric details in the texture that go into the texture rather than in the model
# polygons that are inside other objects and thus never visible or hidden from any view to the object

When I first wrote this tutorial I suggested to delete the faces that face away from the camera. However, this is unecessary as noted above.

== UV unwrap ==
After having created the final low-poly model, create a good and clear UV map. The quality of the texture map (, normal map etc) strongly depends on the quality of this work, do not underestimate this step. However, I assume that you know how to unwrap a model ([http://www.blender.org/documentation/htmlI/x5336.html Tutorial for Blender]).
However, here are a few tips that are especially valid for OpenClonk:
* Mark the seams preferably on the backside of the model. E.g. if there is a cylinder, mark the seam on the side that is not seen ingame. Then the texturer doesn't need to worry (so much) about tileability.
* Regions of the model which are connected in the model should be connected in the uv map too as long as the uv mapping doesn't distort the whole thing (too much).
* Try to arrange the uv regions in a way that regions in the model which are upright are upright and not distorted in the uv map too. This helps the texturer a lot when he want to apply textures with a regular pattern like bricks.
* You can map faces that should look the same - like for example each of the 4 front wheels of the lorry - to the same position in the UV map.

[[File:Lorry_uv1.png|600px]]

If you don't plan to texture your model right away by yourself, be so kind and create and label a uv-map template and save it as an image. This helps the person who does the texturing work big deal; because the work of the texturing can be done (better) by 2D-artists and doesn't have to be up to the person who did the modelling.
Depending on the actual size of the model ingame, you can save the UV map template in different sizes. For the lorry, I chose 256x256 because it is a very tiny model.

[[File:Lorry_uv2.png|600px]]

== Texturing ==
As the model and texture for the lorry is already completed, I can show it to you here:

[[File:lorry_render.png|256px]]
[[File:lorry_tex.png|256px]]
[[File:lorry_uv.png|256px]]

Note that PNG textures can contain alpha. This is how transparency (imagine leaves on trees) is realized in OpenClonk.

== Animation and normal maps ==
After you created a UV map, you can add the animations if there are any. Additionally, if the model is egible for having a normal map, you can create a high-poly model of the lorry where you actually do model even the little geometric details. But keep in mind, to be able to bake a normal map with a high-poly model, the high- and low-poly model must have the same geometry ([http://blenderartists.org/forum/showthread.php?t=138194 Tutorial for Blender]). In Blender, there is a option called "multires" which allows you to create several models in different detail levels based on one low-poly model and it's geometry.

So when is a model egible of having a normal map. First there is to say that at this point of development we can not even say if we will be able to use normal maps. In general, creating normal maps for models only makes sense for those which have organic, round parts where too many polygons would need to be used. So, for blocky buildings it's normally not necessary - more for living creatures with one ([http://www.blender.org/development/release-logs/blender-246/render-baking/ Blender: example]) enclosing mesh.

Here is also a free to use tool with which easily all kinds of maps can be created: [http://www.crazybump.com/ CrazyBump]

File:ExportedFilesNew.png

2014-03-16T09:20:29Z

Andriel: Typical bunch of exported files before user modification.

Typical bunch of exported files before user modification.

File:ExportedFiles.png

2014-03-16T09:19:36Z

Andriel: Andriel uploaded a new version of "File:ExportedFiles.png": Reverted to version as of 02:11, 6 October 2010

Typical bunch of exported files before user modification.

File:ExportedFiles.png

2014-03-16T09:18:24Z

Andriel: Andriel uploaded a new version of "File:ExportedFiles.png": Typical bunch of exported files before user modification.

Typical bunch of exported files before user modification.

File:ExportSettingsStatic.png

2014-03-16T08:59:54Z

Andriel: Andriel uploaded a new version of "File:ExportSettingsStatic.png"

Use these settings for objects without animations.

File:ExportSettingsStatic.png

2014-03-16T08:22:26Z

Andriel: Use these settings for objects without animations.

Use these settings for objects without animations.

File:InstallingBlender2OgreAddon.png

2014-03-16T08:05:14Z

Andriel: Enabling the addon.

Enabling the addon.

How to Create a Settlement Scenario

2013-09-02T14:59:11Z

Andriel:

'''NOT YET FINISHED'''

'''Welcome to this guide on how to create a Settlement scenario!''' 
This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''previous guide''']] is required. 

In the last tutorial, you learned how to create a basic scenario with a map and how to add objects to the map. However, a few more things are required for a complete settlement scenario: 
Goals, rules, base material like shovels and axes, etc. - all these things are set in the script. ''Script? But I have no idea of programming! :('' Don't worry, you don't need to be a C++ expert to get things working. OpenClonk features an easy-to-learn scripting language called C4Script. [[Script: Overview|'''Here''']] is a short overview. Typically, the best way to get into scripting is looking at scripts from other objects and scenarios and finding out what they do. There is also an extensive [http://docs.openclonk.org/en/sdk/ '''documentation'''] I will often link to in this tutorial. 
And even if you have no idea of C4Script, this guide will give you templates and code snippets you can use and easily customise to fit your needs.

= Preparations =

Expand your scenario and open the scenario script [http://docs.openclonk.org/en/sdk/scenario/script.html '''(docs)'''], a file called "Script.c". It should look similar to this:

[[File:TUT-SCEN-SETL ScriptInitial.png]]

Everything between /* and */ is a comment, highlighted in red by the Eclipse text editor. It will be ignored by the engine when executing the code. You can write a short description of your scenario below the name like I did.
Next we have this:

<code>func Initialize()
{
CreateEnvironment();
}</code>

It is a function (keyword ''func'') called ''Initialize''. Everything between the curly brackets is executed when the function is called. (More about [http://docs.openclonk.org/en/sdk/script/Funcs.html '''functions''']). It calls the function ''CreateEnvironment'' which is declared below and is empty as you can see in the screenshot. Delete both the call ''CreateEnvironment();'' and the function below, so we are left with an empty Initialize function.

= Goals =

First you'll need to decide which goal(s) you want to have for your scenario. Inside Eclipse, you can scroll down, expand "Objects.ocd" and then "Goals.ocd" to see all goals currently in the game. In the screenshot, I highlighted the ones which work with settlement scenarios, I will go through all of them.

[[File:TUT-SCEN-SETL SettlmentGoals.png]]

==Wealth==

This one's very easy to set up, just paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Wealth);
goal -> SetWealthGoal(XYXY);</code>

Replace XYXY with the wealth the player should achieve to win.

==Resource Extraction==

The goal is to mine all of a specific resource. Paste the following code into the Initialize function:

<code>var goal = CreateObject(Goal_ResourceExtraction);
goal -> SetResource("XYXY");</code>

Replace XYXY with the name of the ressource to extract, for example: ''SetRessource("Granite");'' or ''SetRessource("Gold");''

==Expansion==

A certain amount of the map must be claimed by constructing flags. Paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Expansion);
goal -> SetExpansionGoal(XYXY);</code>

Replace XYXY with the area to be covered in promillage of the total map. So for covering half the map, it would be ''SetExpansionGoal(500);''

= Rules =

Rules restrict or allow something. As well as for the goals, you can look them up in the objects browser. Adding rules is easy: Copy the following piece of code into your Initialize function:

<code>CreateObject(XYXY, 0, 0, NO_OWNER);</code>

where "XYXY" is replaced by the ID of the rule. The ID is the unique identifier every object has, like it's internal name. To find out the ID of an object, expand it and open the file "DefCore.txt". In the second line, it says ''id=XYXY'', that's the ID.
If you want multiple rules, just copy the snippet and insert another ID.
'''Note:''' You don't need to have rules, Goldrush, a standard settlement scenario, has no rules set.

This is what my Initialize function looks like after adding two goals and two rules.

[[File:TUT-SCEN-SETL GoalsAndRules.png]]

= Start Position and Equipment =

There is another important function: InitializePlayer. While Initalize is used to set up goals, rules, place objects, etc. (so gameworld-related things), InitializePlayer is for player-related stuff, like start position, base materials, or view range.

==Preparations==

Leave out one line after the closing curly bracket of the Initialize function and add this empty function below:

<code>func InitializePlayer(int plr)
{

}</code>

Right now not much is happening, put the following code into the newly created function:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{

}</code>

That may look quite complicated, but it's basically a loop (a [http://docs.openclonk.org/en/sdk/script/for.html '''for loop'''], to be precise) which runs through all the crew members. What we write into that loop (again between the curly braces) will be executed for every crew member (the variable "clonk") the player gets at the beginning of the scenario. The variable "index" is the index of the respective clonk, starting from 0 and then counting up until no more crew member is found, then the loop will end.

==Start Position==
'''Note: If you want the player to spawn at a random position, you can leave this out.'''

First you'll need to find out the coordinates of the position at which you want the players to get spawned. OpenClonk uses a 2D coordinate system, point 0X,0Y is the upper left corner. The X axis goes right, the Y axis goes down. One unit corresponds to 1 pixel ingame.
To find out the coordinates, you need to start your scenario in editor mode and select the editing cursor. Then move the cursor to your desired start point (the center of the clonk will be at this position, so don't set it too close to the ground or the clonk will stuck) and read the coordinates in the lower left corner of the engine window. Keep them in mind, you will need them shortly.
Now copy this code into your loop:

<code>clonk -> SetPosition(X, Y);</code>

And replace X and Y with your coordinates.

==Equipment==

The command we need for placing something in a clonks inventory is [http://docs.openclonk.org/en/sdk/script/fn/CreateContents.html '''CreateContents''']. It needs two arguments, ID and count of the object to be created (If count is not given, the default amount of 1 will be used). So if we wanted to give every crew member a shovel and a hammer, it would look like this:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{
clonk -> CreateContents(Shovel);
clonk -> CreateContents(Hammer);
}</code>

But we don't want the same equipment for every crew member, we want the first one to have shovel and hammer, the second one shovel and axe. How to do this? Using an [http://docs.openclonk.org/en/sdk/script/fn/if.html#if '''if condition'''] and ''else''!
Basically, you enter a condition inside the parentheses and if it returns true, the following command or code block will be executed. If it returns false, else will be executed. We have the variable ''index'' from the for loop which indicates the number of the current crew member. Let's use this and say: If it is the first crew member (index = 0), give it shovel and hammer, else give it shovel and axe. It looks like that:

[[File:TUT-SCEN-SETL GiveContents.png]]

Note that you can not only put the CreateContents commands into the if block, but also other things. You could for example let one crew member spawn at the left side of an abyss and the other one on the right side!

==View Range==

You may want to limit the zoom range so the player can't zoom out the whole map. This is also done in the InitializePlayer function, but it isn't applied to individual clonks, but to the player. As our for loop runs through all crew members, we don't write the following code into it, but outside of it below.
We need two commands, [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerZoomByViewRange.html '''SetPlayerZoomByViewRange'''] and [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerViewLock.html '''SetPlayerViewLock'''].
First we will limit the zoom range so the player cannot some out farther than 500 pixels:

<code>SetPlayerZoomByViewRange(plr, 500, nil, PLRZOOM_LimitMax);</code>

(The data type ''nil'' can be used to leave out a parameter.)
Then we will lock his view so he can't scroll around to explore the map:

<code>SetPlayerViewLock(plr, true);</code>

// Some natural disasters, earthquakes, volcanos, meteorites.
Meteor->SetChance(15);
Earthquake->SetChance(2);
Volcano->SetChance(4);
Volcano->SetMaterial("DuroLava");

= Addendum - Components of .ocs files =
This is an overview of all the files a Scenario.ocs can contain.
[img]http://img705.imageshack.us/img705/7878/confusingfiles.png[/img]

[b]Material.ocg[/b]
Contains material-texture combinations. Don't change it, otherwise you will get a [tt]FATAL ERROR: Error loading materials.[/tt] and the game won't start. If that happens, just delete the file, it will be recreated.

[b]Script.c[/b]
Contains the scenario script.

[b]Game.txt[/b]
Contains information about every object that has been saved and will be created on scenario startup. These are informations like position, size, category, flags, properties, etc. Don't touch it and everything will be fine.

[b]Landscape.txt[/b]
As mentioned before this file contains code to dynamically create a map. You can create complex landscapes that look different every game. Have a look at it:
[url=http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html]More information.[/url] [url=http://www.cc.striver.net/texts.php?action=sh&id=13]German tutorial.[/url]
Not needed if you are manually painting a map.

[b]Scenario.txt[/b]
Contains general scenario settings. These are some of the most important ones:

[i]MinPlayer/MaxPlayer[/i]
Sets the minimum and maximum number of players to play this scenario. You could for example only make it playable with 2 to 4 players using [tt]MinPlayer=2[/tt] and [tt]MaxPlayer=4[/tt].

[i]MapWidth/MapHeight[/i]
Specifies the map size.
[b]Note:[/b] Doesn't work if there already is a Map.bmp file. Use the method explained below to change the size of a painted map afterwards: Painting with an external program.

[i]MapZoom[/i]
Something between 5 and 15. The factor the Map.bmp file is zoomed by for the actual gameworld. So if you have a 300x100 bitmap file and MapZoom=15, the ingame landscape will be 4500x1500 pixels big.

[i]BottomOpen/TopOpen[/i]
If 1, objects and Clonks can fall out of the map.

For all options, see [url=http://docs.openclonk.org/en/sdk/scenario/scenario.html]Scenario.txt.[/url]

[b]Teams.txt[/b]
(See [url=http://docs.openclonk.org/en/sdk/scenario/Teams.html]docs[/url])
Used to define Teams. I will do another tutorial on that later.

[b]Title.txt[/b]
Contains the scenario titel which is shown in the frontend. DE: is the German titel and US: the English one.

[b]Title.png[/b]
The title graphic which will be shown alongside the description in the frontend. Has to have an aspect ratio of 4:3, preferably 640x480. Here is an article about how to design a good title graphics

[b]Map.bmp[/b]
The static map is saved into this bitmap. The colours do not necessarily correspond with the actual materials, so don't worry if it is pink and green. :)
You can edit it with an external program, that way it is possible to change the map dimensions even after already having painted something. (Scale canvas) [b]Attention Windows 7 users:[/b] The "Paint" program shipped by default can't handle OpenClonks colour palette properly and will break your map! Use another program like [url=http://www.softpedia.com/get/Multimedia/Graphic/Graphic-Editors/Paint-XP.shtml]Paint XP[/url].

[img]http://img547.imageshack.us/img547/6122/crasha.png[/img] [i]A typical Map.bmp (Crash landing)[/i]

The easiest way to get the materials right is to paint all the materials you want into the map in the engine, and then open the Map.bmp and use the Colour Picker tool to copy a material colour.
[url=http://www.cc.striver.net/texts.php?action=sh&id=7]Here[/url] is an extensive tutorial about materials. (German only D: | outdated D;)

[b]DescDE.rtf/DescUS.rtf[/b]
Contain the description in the respective language. Don't forget to write a description before releasing your work. :)

How to Create a Settlement Scenario

2013-09-02T14:57:12Z

Andriel: Added a few images

'''NOT YET FINISHED'''

'''Welcome to this guide on how to create a Settlement scenario!''' 
This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''previous guide''']] is required. 

In the last tutorial, you learned how to create a basic scenario with a map and how to add objects to the map. However, a few more things are required for a complete settlement scenario: 
Goals, rules, base material like shovels and axes, etc. - all these things are set in the script. ''Script? But I have no idea of programming! :('' Don't worry, you don't need to be a C++ expert to get things working. OpenClonk features an easy-to-learn scripting language called C4Script. [[Script: Overview|'''Here''']] is a short overview. Typically, the best way to get into scripting is looking at scripts from other objects and scenarios and finding out what they do. There is also an extensive [http://docs.openclonk.org/en/sdk/ '''documentation'''] I will often link to in this tutorial. 
And even if you have no idea of C4Script, this guide will give you templates and code snippets you can use and easily customise to fit your needs.

= Preparations =

Expand your scenario and open the scenario script [http://docs.openclonk.org/en/sdk/scenario/script.html '''(docs)'''], a file called "Script.c". It should look similar to this:

[[File:TUT-SCEN-SETL ScriptInitial.png]]

Everything between /* and */ is a comment, highlighted in red by the Eclipse text editor. It will be ignored by the engine when executing the code. You can write a short description of your scenario below the name like I did.
Next we have this:

<code>func Initialize()
{
CreateEnvironment();
}</code>

It is a function (keyword ''func'') called ''Initialize''. Everything between the curly brackets is executed when the function is called. (More about [http://docs.openclonk.org/en/sdk/script/Funcs.html '''functions''']). It calls the function ''CreateEnvironment'' which is declared below and is empty as you can see in the screenshot. Delete both the call ''CreateEnvironment();'' and the function below, so we are left with an empty Initialize function.

= Goals =

First you'll need to decide which goal(s) you want to have for your scenario. Inside Eclipse, you can scroll down, expand "Objects.ocd" and then "Goals.ocd" to see all goals currently in the game. In the screenshot, I highlighted the ones which work with settlement scenarios, I will go through all of them.

[[File:TUT-SCEN-SETL SettlmentGoals.png]]

==Wealth==

This one's very easy to set up, just paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Wealth);
goal -> SetWealthGoal(XYXY);</code>

Replace XYXY with the wealth the player should achieve to win.

==Resource Extraction==

The goal is to mine all of a specific resource. Paste the following code into the Initialize function:

<code>var goal = CreateObject(Goal_ResourceExtraction);
goal -> SetResource("XYXY");</code>

Replace XYXY with the name of the ressource to extract, for example: ''SetRessource("Granite");'' or ''SetRessource("Gold");''

==Expansion==

A certain amount of the map must be claimed by constructing flags. Paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Expansion);
goal -> SetExpansionGoal(XYXY);</code>

Replace XYXY with the area to be covered in promillage of the total map. So for covering half the map, it would be ''SetExpansionGoal(500);''

= Rules =

Rules restrict or allow something. As well as for the goals, you can look them up in the objects browser. Adding rules is easy: Copy the following piece of code into your Initialize function:

<code>CreateObject(XYXY, 0, 0, NO_OWNER);</code>

where "XYXY" is replaced by the ID of the rule. The ID is the unique identifier every object has, like it's internal name. To find out the ID of an object, expand it and open the file "DefCore.txt". In the second line, it says ''id=XYXY'', that's the ID.
If you want multiple rules, just copy the snippet and insert another ID.
'''Note:''' You don't need to have rules, Goldrush, a standard settlement scenario, has no rules set.

This is what my Initialize function looks like after adding two goals and two rules.

[[File:TUT-SCEN-SETL GoalsAndRules.png]]

= Start Position and Equipment =

There is another important function: InitializePlayer. While Initalize is used to set up goals, rules, place objects, etc. (so gameworld-related things), InitializePlayer is for player-related stuff, like start position, base materials, or view range.

==Preparations==

Leave out one line after the closing curly bracket of the Initialize function and add this empty function below:

<code>func InitializePlayer(int plr)
{

}</code>

Right now not much is happening, put the following code into the newly created function:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{

}</code>

That may look quite complicated, but it's basically a loop (a [http://docs.openclonk.org/en/sdk/script/for.html '''for loop'''], to be precise) which runs through all the crew members. What we write into that loop (again between the curly braces) will be executed for every crew member (the variable "clonk") the player gets at the beginning of the scenario. The variable "index" is the index of the respective clonk, starting from 0 and then counting up until no more crew member is found, then the loop will end.

==Start Position==
'''Note: If you want the player to spawn at a random position, you can leave this out.'''

First you'll need to find out the coordinates of the position at which you want the players to get spawned. OpenClonk uses a 2D coordinate system, point 0X,0Y is the upper left corner. The X axis goes right, the Y axis goes down. One unit corresponds to 1 pixel ingame.
To find out the coordinates, you need to start your scenario in editor mode and select the editing cursor. Then move the cursor to your desired start point (the center of the clonk will be at this position, so don't set it too close to the ground or the clonk will stuck) and read the coordinates in the lower left corner of the engine window. Keep them in mind, you will need them shortly.
Now copy this code into your loop:

<code>clonk -> SetPosition(X, Y);</code>

And replace X and Y with your coordinates.

==Equipment==

The command we need for placing something in a clonks inventory is [http://docs.openclonk.org/en/sdk/script/fn/CreateContents.html '''CreateContents''']. It needs two arguments, ID and count of the object to be created (If count is not given, the default amount of 1 will be used). So if we wanted to give every crew member a shovel and a hammer, it would look like this:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{
clonk -> CreateContents(Shovel);
clonk -> CreateContents(Hammer);
}</code>

But we don't want the same equipment for every crew member, we want the first one to have shovel and hammer, the second one shovel and axe. How to do this? Using an [http://docs.openclonk.org/en/sdk/script/fn/if.html#if '''if condition'''] and ''else''!
Basically, you enter a condition inside the parentheses and if it returns true, the following command or code block will be executed. If it returns false, else will be executed. We have the variable ''index'' from the for loop which indicates the number of the current crew member. Let's use this and say: If it is the first crew member (index = 0), give it shovel and hammer, else give it shovel and axe. It looks like that:

[[File:TUT-SCEN-SETL GiveContents.png]]

Note that you can not only put the CreateContents commands into the if block, but also other things. You could for example let one crew member spawn at the left side of an abyss and the other one on the right side!

==View Range==

You may want to limit the zoom range so the player can't zoom out the whole map. This is also done in the InitializePlayer function, but it isn't applied to individual clonks, but to the player. As our for loop runs through all crew members, we don't write the following code into it, but outside of it below.
We need two commands, [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerZoomByViewRange.html '''SetPlayerZoomByViewRange'''] and [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerViewLock.html SetPlayerViewLock'''].
First we will limit the zoom range so the player cannot some out farther than 500 pixels:

<code>SetPlayerZoomByViewRange(plr, 500, nil, PLRZOOM_LimitMax);</code>

(The data type ''nil'' can be used to leave out a parameter.)
Then we will lock his view so he can't scroll around to explore the map:

<code>SetPlayerViewLock(plr, true);</code>

// Some natural disasters, earthquakes, volcanos, meteorites.
Meteor->SetChance(15);
Earthquake->SetChance(2);
Volcano->SetChance(4);
Volcano->SetMaterial("DuroLava");

= Addendum - Components of .ocs files =
This is an overview of all the files a Scenario.ocs can contain.
[img]http://img705.imageshack.us/img705/7878/confusingfiles.png[/img]

[b]Material.ocg[/b]
Contains material-texture combinations. Don't change it, otherwise you will get a [tt]FATAL ERROR: Error loading materials.[/tt] and the game won't start. If that happens, just delete the file, it will be recreated.

[b]Script.c[/b]
Contains the scenario script.

[b]Game.txt[/b]
Contains information about every object that has been saved and will be created on scenario startup. These are informations like position, size, category, flags, properties, etc. Don't touch it and everything will be fine.

[b]Landscape.txt[/b]
As mentioned before this file contains code to dynamically create a map. You can create complex landscapes that look different every game. Have a look at it:
[url=http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html]More information.[/url] [url=http://www.cc.striver.net/texts.php?action=sh&id=13]German tutorial.[/url]
Not needed if you are manually painting a map.

[b]Scenario.txt[/b]
Contains general scenario settings. These are some of the most important ones:

[i]MinPlayer/MaxPlayer[/i]
Sets the minimum and maximum number of players to play this scenario. You could for example only make it playable with 2 to 4 players using [tt]MinPlayer=2[/tt] and [tt]MaxPlayer=4[/tt].

[i]MapWidth/MapHeight[/i]
Specifies the map size.
[b]Note:[/b] Doesn't work if there already is a Map.bmp file. Use the method explained below to change the size of a painted map afterwards: Painting with an external program.

[i]MapZoom[/i]
Something between 5 and 15. The factor the Map.bmp file is zoomed by for the actual gameworld. So if you have a 300x100 bitmap file and MapZoom=15, the ingame landscape will be 4500x1500 pixels big.

[i]BottomOpen/TopOpen[/i]
If 1, objects and Clonks can fall out of the map.

For all options, see [url=http://docs.openclonk.org/en/sdk/scenario/scenario.html]Scenario.txt.[/url]

[b]Teams.txt[/b]
(See [url=http://docs.openclonk.org/en/sdk/scenario/Teams.html]docs[/url])
Used to define Teams. I will do another tutorial on that later.

[b]Title.txt[/b]
Contains the scenario titel which is shown in the frontend. DE: is the German titel and US: the English one.

[b]Title.png[/b]
The title graphic which will be shown alongside the description in the frontend. Has to have an aspect ratio of 4:3, preferably 640x480. Here is an article about how to design a good title graphics

[b]Map.bmp[/b]
The static map is saved into this bitmap. The colours do not necessarily correspond with the actual materials, so don't worry if it is pink and green. :)
You can edit it with an external program, that way it is possible to change the map dimensions even after already having painted something. (Scale canvas) [b]Attention Windows 7 users:[/b] The "Paint" program shipped by default can't handle OpenClonks colour palette properly and will break your map! Use another program like [url=http://www.softpedia.com/get/Multimedia/Graphic/Graphic-Editors/Paint-XP.shtml]Paint XP[/url].

[img]http://img547.imageshack.us/img547/6122/crasha.png[/img] [i]A typical Map.bmp (Crash landing)[/i]

The easiest way to get the materials right is to paint all the materials you want into the map in the engine, and then open the Map.bmp and use the Colour Picker tool to copy a material colour.
[url=http://www.cc.striver.net/texts.php?action=sh&id=7]Here[/url] is an extensive tutorial about materials. (German only D: | outdated D;)

[b]DescDE.rtf/DescUS.rtf[/b]
Contain the description in the respective language. Don't forget to write a description before releasing your work. :)

File:TUT-SCEN-SETL GiveContents.png

2013-09-02T14:56:26Z

Andriel:

File:TUT-SCEN-SETL GoalsAndRules.png

2013-09-02T14:53:59Z

Andriel:

File:TUT-SCEN-SETL SettlmentGoals.png

2013-09-02T14:51:57Z

Andriel:

How to Create a Settlement Scenario

2013-09-02T14:44:48Z

Andriel:

'''NOT YET FINISHED'''

'''Welcome to this guide on how to create a Settlement scenario!''' 
This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''previous guide''']] is required. 

In the last tutorial, you learned how to create a basic scenario with a map and how to add objects to the map. However, a few more things are required for a complete settlement scenario: 
Goals, rules, base material like shovels and axes, etc. - all these things are set in the script. ''Script? But I have no idea of programming! :('' Don't worry, you don't need to be a C++ expert to get things working. OpenClonk features an easy-to-learn scripting language called C4Script. [[Script: Overview|'''Here''']] is a short overview. Typically, the best way to get into scripting is looking at scripts from other objects and scenarios and finding out what they do. There is also an extensive [http://docs.openclonk.org/en/sdk/ '''documentation'''] I will often link to in this tutorial. 
And even if you have no idea of C4Script, this guide will give you templates and code snippets you can use and easily customise to fit your needs.

= Preparations =

Expand your scenario and open the scenario script [http://docs.openclonk.org/en/sdk/scenario/script.html '''(docs)'''], a file called "Script.c". It should look similar to this:

[[File:TUT-SCEN-SETL ScriptInitial.png]]

Everything between /* and */ is a comment, highlighted in red by the Eclipse text editor. It will be ignored by the engine when executing the code. You can write a short description of your scenario below the name like I did.
Next we have this:

<code>func Initialize()
{
CreateEnvironment();
}</code>

It is a function (keyword ''func'') called ''Initialize''. Everything between the curly brackets is executed when the function is called. (More about [http://docs.openclonk.org/en/sdk/script/Funcs.html '''functions''']). It calls the function ''CreateEnvironment'' which is declared below and is empty as you can see in the screenshot. Delete both the call ''CreateEnvironment();'' and the function below, so we are left with an empty Initialize function.

= Goals =

First you'll need to decide which goal(s) you want to have for your scenario. Inside Eclipse, you can scroll down, expand "Objects.ocd" and then "Goals.ocd" to see all goals currently in the game. In the screenshot, I highlighted the ones which work with settlement scenarios, I will go through all of them.

[img]http://img689.imageshack.us/img689/8895/vvgj.png[/img]

==Wealth==

This one's very easy to set up, just paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Wealth);
goal -> SetWealthGoal(XYXY);</code>

Replace XYXY with the wealth the player should achieve to win.

==Resource Extraction==

The goal is to mine all of a specific resource. Paste the following code into the Initialize function:

<code>var goal = CreateObject(Goal_ResourceExtraction);
goal -> SetResource("XYXY");</code>

Replace XYXY with the name of the ressource to extract, for example: ''SetRessource("Granite");'' or ''SetRessource("Gold");''

==Expansion==

A certain amount of the map must be claimed by constructing flags. Paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Expansion);
goal -> SetExpansionGoal(XYXY);</code>

Replace XYXY with the area to be covered in promillage of the total map. So for covering half the map, it would be ''SetExpansionGoal(500);''

= Rules =

Rules restrict or allow something. As well as for the goals, you can look them up in the objects browser. Adding rules is easy: Copy the following piece of code into your Initialize function:

<code>CreateObject(XYXY, 0, 0, NO_OWNER);</code>

where "XYXY" is replaced by the ID of the rule. The ID is the unique identifier every object has, like it's internal name. To find out the ID of an object, expand it and open the file "DefCore.txt". In the second line, it says ''id=XYXY'', that's the ID.
If you want multiple rules, just copy the snippet and insert another ID.
'''Note:''' You don't need to have rules, Goldrush, a standard settlement scenario, has no rules set.

This is what my Initialize function looks like after adding two goals and two rules.

[img]http://img534.imageshack.us/img534/2552/hzn.png[/img]

= Start Position and Equipment =

There is another important function: InitializePlayer. While Initalize is used to set up goals, rules, place objects, etc. (so gameworld-related things), InitializePlayer is for player-related stuff, like start position, base materials, or view range.

==Preparations==

Leave out one line after the closing curly bracket of the Initialize function and add this empty function below:

<code>func InitializePlayer(int plr)
{

}</code>

Right now not much is happening, put the following code into the newly created function:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{

}</code>

That may look quite complicated, but it's basically a loop (a [http://docs.openclonk.org/en/sdk/script/for.html '''for loop'''], to be precise) which runs through all the crew members. What we write into that loop (again between the curly braces) will be executed for every crew member (the variable "clonk") the player gets at the beginning of the scenario. The variable "index" is the index of the respective clonk, starting from 0 and then counting up until no more crew member is found, then the loop will end.

==Start Position==
'''Note: If you want the player to spawn at a random position, you can leave this out.'''

First you'll need to find out the coordinates of the position at which you want the players to get spawned. OpenClonk uses a 2D coordinate system, point 0X,0Y is the upper left corner. The X axis goes right, the Y axis goes down. One unit corresponds to 1 pixel ingame.
To find out the coordinates, you need to start your scenario in editor mode and select the editing cursor. Then move the cursor to your desired start point (the center of the clonk will be at this position, so don't set it too close to the ground or the clonk will stuck) and read the coordinates in the lower left corner of the engine window. Keep them in mind, you will need them shortly.
Now copy this code into your loop:

<code>clonk -> SetPosition(X, Y);</code>

And replace X and Y with your coordinates.

==Equipment==

The command we need for placing something in a clonks inventory is [http://docs.openclonk.org/en/sdk/script/fn/CreateContents.html '''CreateContents''']. It needs two arguments, ID and count of the object to be created (If count is not given, the default amount of 1 will be used). So if we wanted to give every crew member a shovel and a hammer, it would look like this:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{
clonk -> CreateContents(Shovel);
clonk -> CreateContents(Hammer);
}</code>

But we don't want the same equipment for every crew member, we want the first one to have shovel and hammer, the second one shovel and axe. How to do this? Using an [http://docs.openclonk.org/en/sdk/script/fn/if.html#if '''if condition'''] and ''else''!
Basically, you enter a condition inside the parentheses and if it returns true, the following command or code block will be executed. If it returns false, else will be executed. We have the variable ''index'' from the for loop which indicates the number of the current crew member. Let's use this and say: If it is the first crew member (index = 0), give it shovel and hammer, else give it shovel and axe. It looks like that:

[img]http://img854.imageshack.us/img854/6408/n40b.png[/img]

Note that you can not only put the CreateContents commands into the if block, but also other things. You could for example let one crew member spawn at the left side of an abyss and the other one on the right side!

==View Range==

You may want to limit the zoom range so the player can't zoom out the whole map. This is also done in the InitializePlayer function, but it isn't applied to individual clonks, but to the player. As our for loop runs through all crew members, we don't write the following code into it, but outside of it below.
We need two commands, [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerZoomByViewRange.html '''SetPlayerZoomByViewRange'''] and [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerViewLock.html SetPlayerViewLock'''].
First we will limit the zoom range so the player cannot some out farther than 500 pixels:

<code>SetPlayerZoomByViewRange(plr, 500, nil, PLRZOOM_LimitMax);</code>

(The data type ''nil'' can be used to leave out a parameter.)
Then we will lock his view so he can't scroll around to explore the map:

<code>SetPlayerViewLock(plr, true);</code>

// Some natural disasters, earthquakes, volcanos, meteorites.
Meteor->SetChance(15);
Earthquake->SetChance(2);
Volcano->SetChance(4);
Volcano->SetMaterial("DuroLava");

= Addendum - Components of .ocs files =
This is an overview of all the files a Scenario.ocs can contain.
[img]http://img705.imageshack.us/img705/7878/confusingfiles.png[/img]

[b]Material.ocg[/b]
Contains material-texture combinations. Don't change it, otherwise you will get a [tt]FATAL ERROR: Error loading materials.[/tt] and the game won't start. If that happens, just delete the file, it will be recreated.

[b]Script.c[/b]
Contains the scenario script.

[b]Game.txt[/b]
Contains information about every object that has been saved and will be created on scenario startup. These are informations like position, size, category, flags, properties, etc. Don't touch it and everything will be fine.

[b]Landscape.txt[/b]
As mentioned before this file contains code to dynamically create a map. You can create complex landscapes that look different every game. Have a look at it:
[url=http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html]More information.[/url] [url=http://www.cc.striver.net/texts.php?action=sh&id=13]German tutorial.[/url]
Not needed if you are manually painting a map.

[b]Scenario.txt[/b]
Contains general scenario settings. These are some of the most important ones:

[i]MinPlayer/MaxPlayer[/i]
Sets the minimum and maximum number of players to play this scenario. You could for example only make it playable with 2 to 4 players using [tt]MinPlayer=2[/tt] and [tt]MaxPlayer=4[/tt].

[i]MapWidth/MapHeight[/i]
Specifies the map size.
[b]Note:[/b] Doesn't work if there already is a Map.bmp file. Use the method explained below to change the size of a painted map afterwards: Painting with an external program.

[i]MapZoom[/i]
Something between 5 and 15. The factor the Map.bmp file is zoomed by for the actual gameworld. So if you have a 300x100 bitmap file and MapZoom=15, the ingame landscape will be 4500x1500 pixels big.

[i]BottomOpen/TopOpen[/i]
If 1, objects and Clonks can fall out of the map.

For all options, see [url=http://docs.openclonk.org/en/sdk/scenario/scenario.html]Scenario.txt.[/url]

[b]Teams.txt[/b]
(See [url=http://docs.openclonk.org/en/sdk/scenario/Teams.html]docs[/url])
Used to define Teams. I will do another tutorial on that later.

[b]Title.txt[/b]
Contains the scenario titel which is shown in the frontend. DE: is the German titel and US: the English one.

[b]Title.png[/b]
The title graphic which will be shown alongside the description in the frontend. Has to have an aspect ratio of 4:3, preferably 640x480. Here is an article about how to design a good title graphics

[b]Map.bmp[/b]
The static map is saved into this bitmap. The colours do not necessarily correspond with the actual materials, so don't worry if it is pink and green. :)
You can edit it with an external program, that way it is possible to change the map dimensions even after already having painted something. (Scale canvas) [b]Attention Windows 7 users:[/b] The "Paint" program shipped by default can't handle OpenClonks colour palette properly and will break your map! Use another program like [url=http://www.softpedia.com/get/Multimedia/Graphic/Graphic-Editors/Paint-XP.shtml]Paint XP[/url].

[img]http://img547.imageshack.us/img547/6122/crasha.png[/img] [i]A typical Map.bmp (Crash landing)[/i]

The easiest way to get the materials right is to paint all the materials you want into the map in the engine, and then open the Map.bmp and use the Colour Picker tool to copy a material colour.
[url=http://www.cc.striver.net/texts.php?action=sh&id=7]Here[/url] is an extensive tutorial about materials. (German only D: | outdated D;)

[b]DescDE.rtf/DescUS.rtf[/b]
Contain the description in the respective language. Don't forget to write a description before releasing your work. :)

How to Create a Settlement Scenario

2013-09-02T14:43:43Z

Andriel:

'''NOT YET FINISHED'''

'''Welcome to this guide on how to create a Settlement scenario!''' 
This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''previous guide''']] is required. 

In the last tutorial, you learned how to create a basic scenario with a map and how to add objects to the map. However, a few more things are required for a complete settlement scenario: 
Goals, rules, base material like shovels and axes, etc. - all these things are set in the script. ''Script? But I have no idea of programming! :('' Don't worry, you don't need to be a C++ expert to get things working. OpenClonk features an easy-to-learn scripting language called C4Script. [[Script: Overview|'''Here''']] is a short overview. Typically, the best way to get into scripting is looking at scripts from other objects and scenarios and finding out what they do. There is also an extensive [http://docs.openclonk.org/en/sdk/ '''documentation'''] I will often link to in this tutorial. 
And even if you have no idea of C4Script, this guide will give you templates and code snippets you can use and easily customise to fit your needs.

= Preparations =

Expand your scenario and open the scenario script [http://docs.openclonk.org/en/sdk/scenario/script.html '''(docs)'''], a file called "Script.c". It should look similar to this:

[[File:TUT-SCEN-SETL ScriptInitial.png]]

Everything between /* and */ is a comment, highlighted in red by the Eclipse text editor. It will be ignored by the engine when executing the code. You can write a short description of your scenario below the name like I did.
Next we have this:

<code>func Initialize()
{
CreateEnvironment();
}</code>

It is a function (keyword ''func'') called ''Initialize''. Everything between the curly brackets is executed when the function is called. (More about [http://docs.openclonk.org/en/sdk/script/Funcs.html '''functions''']). It calls the function ''CreateEnvironment'' which is declared below and is empty as you can see in the screenshot. Delete both the call ''CreateEnvironment();'' and the function below, so we are left with an empty Initialize function.

= Goals =

First you'll need to decide which goal(s) you want to have for your scenario. Inside Eclipse, you can scroll down, expand "Objects.ocd" and then "Goals.ocd" to see all goals currently in the game. In the screenshot, I highlighted the ones which work with settlement scenarios, I will go through all of them.

[img]http://img689.imageshack.us/img689/8895/vvgj.png[/img]

==Wealth==

This one's very easy to set up, just paste the following code into your Initialize function:

<code c4script>var goal = CreateObject(Goal_Wealth);
goal -> SetWealthGoal(XYXY);</code c4script>

Replace XYXY with the wealth the player should achieve to win.

==Resource Extraction==

The goal is to mine all of a specific resource. Paste the following code into the Initialize function:

<code>var goal = CreateObject(Goal_ResourceExtraction);
goal -> SetResource("XYXY");</code>

Replace XYXY with the name of the ressource to extract, for example: ''SetRessource("Granite");'' or ''SetRessource("Gold");''

==Expansion==

A certain amount of the map must be claimed by constructing flags. Paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Expansion);
goal -> SetExpansionGoal(XYXY);</code>

Replace XYXY with the area to be covered in promillage of the total map. So for covering half the map, it would be ''SetExpansionGoal(500);''

= Rules =

Rules restrict or allow something. As well as for the goals, you can look them up in the objects browser. Adding rules is easy: Copy the following piece of code into your Initialize function:

<code>CreateObject(XYXY, 0, 0, NO_OWNER);</code>

where "XYXY" is replaced by the ID of the rule. The ID is the unique identifier every object has, like it's internal name. To find out the ID of an object, expand it and open the file "DefCore.txt". In the second line, it says ''id=XYXY'', that's the ID.
If you want multiple rules, just copy the snippet and insert another ID.
'''Note:''' You don't need to have rules, Goldrush, a standard settlement scenario, has no rules set.

This is what my Initialize function looks like after adding two goals and two rules.

[img]http://img534.imageshack.us/img534/2552/hzn.png[/img]

= Start Position and Equipment =

There is another important function: InitializePlayer. While Initalize is used to set up goals, rules, place objects, etc. (so gameworld-related things), InitializePlayer is for player-related stuff, like start position, base materials, or view range.

==Preparations==

Leave out one line after the closing curly bracket of the Initialize function and add this empty function below:

<code>func InitializePlayer(int plr)
{

}</code>

Right now not much is happening, put the following code into the newly created function:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{

}</code>

That may look quite complicated, but it's basically a loop (a [http://docs.openclonk.org/en/sdk/script/for.html '''for loop'''], to be precise) which runs through all the crew members. What we write into that loop (again between the curly braces) will be executed for every crew member (the variable "clonk") the player gets at the beginning of the scenario. The variable "index" is the index of the respective clonk, starting from 0 and then counting up until no more crew member is found, then the loop will end.

==Start Position==
'''Note: If you want the player to spawn at a random position, you can leave this out.'''

First you'll need to find out the coordinates of the position at which you want the players to get spawned. OpenClonk uses a 2D coordinate system, point 0X,0Y is the upper left corner. The X axis goes right, the Y axis goes down. One unit corresponds to 1 pixel ingame.
To find out the coordinates, you need to start your scenario in editor mode and select the editing cursor. Then move the cursor to your desired start point (the center of the clonk will be at this position, so don't set it too close to the ground or the clonk will stuck) and read the coordinates in the lower left corner of the engine window. Keep them in mind, you will need them shortly.
Now copy this code into your loop:

<code>clonk -> SetPosition(X, Y);</code>

And replace X and Y with your coordinates.

==Equipment==

The command we need for placing something in a clonks inventory is [http://docs.openclonk.org/en/sdk/script/fn/CreateContents.html '''CreateContents''']. It needs two arguments, ID and count of the object to be created (If count is not given, the default amount of 1 will be used). So if we wanted to give every crew member a shovel and a hammer, it would look like this:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{
clonk -> CreateContents(Shovel);
clonk -> CreateContents(Hammer);
}</code>

But we don't want the same equipment for every crew member, we want the first one to have shovel and hammer, the second one shovel and axe. How to do this? Using an [http://docs.openclonk.org/en/sdk/script/fn/if.html#if '''if condition'''] and ''else''!
Basically, you enter a condition inside the parentheses and if it returns true, the following command or code block will be executed. If it returns false, else will be executed. We have the variable ''index'' from the for loop which indicates the number of the current crew member. Let's use this and say: If it is the first crew member (index = 0), give it shovel and hammer, else give it shovel and axe. It looks like that:

[img]http://img854.imageshack.us/img854/6408/n40b.png[/img]

Note that you can not only put the CreateContents commands into the if block, but also other things. You could for example let one crew member spawn at the left side of an abyss and the other one on the right side!

==View Range==

You may want to limit the zoom range so the player can't zoom out the whole map. This is also done in the InitializePlayer function, but it isn't applied to individual clonks, but to the player. As our for loop runs through all crew members, we don't write the following code into it, but outside of it below.
We need two commands, [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerZoomByViewRange.html '''SetPlayerZoomByViewRange'''] and [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerViewLock.html SetPlayerViewLock'''].
First we will limit the zoom range so the player cannot some out farther than 500 pixels:

<code>SetPlayerZoomByViewRange(plr, 500, nil, PLRZOOM_LimitMax);</code>

(The data type ''nil'' can be used to leave out a parameter.)
Then we will lock his view so he can't scroll around to explore the map:

<code>SetPlayerViewLock(plr, true);</code>

// Some natural disasters, earthquakes, volcanos, meteorites.
Meteor->SetChance(15);
Earthquake->SetChance(2);
Volcano->SetChance(4);
Volcano->SetMaterial("DuroLava");

= Addendum - Components of .ocs files =
This is an overview of all the files a Scenario.ocs can contain.
[img]http://img705.imageshack.us/img705/7878/confusingfiles.png[/img]

[b]Material.ocg[/b]
Contains material-texture combinations. Don't change it, otherwise you will get a [tt]FATAL ERROR: Error loading materials.[/tt] and the game won't start. If that happens, just delete the file, it will be recreated.

[b]Script.c[/b]
Contains the scenario script.

[b]Game.txt[/b]
Contains information about every object that has been saved and will be created on scenario startup. These are informations like position, size, category, flags, properties, etc. Don't touch it and everything will be fine.

[b]Landscape.txt[/b]
As mentioned before this file contains code to dynamically create a map. You can create complex landscapes that look different every game. Have a look at it:
[url=http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html]More information.[/url] [url=http://www.cc.striver.net/texts.php?action=sh&id=13]German tutorial.[/url]
Not needed if you are manually painting a map.

[b]Scenario.txt[/b]
Contains general scenario settings. These are some of the most important ones:

[i]MinPlayer/MaxPlayer[/i]
Sets the minimum and maximum number of players to play this scenario. You could for example only make it playable with 2 to 4 players using [tt]MinPlayer=2[/tt] and [tt]MaxPlayer=4[/tt].

[i]MapWidth/MapHeight[/i]
Specifies the map size.
[b]Note:[/b] Doesn't work if there already is a Map.bmp file. Use the method explained below to change the size of a painted map afterwards: Painting with an external program.

[i]MapZoom[/i]
Something between 5 and 15. The factor the Map.bmp file is zoomed by for the actual gameworld. So if you have a 300x100 bitmap file and MapZoom=15, the ingame landscape will be 4500x1500 pixels big.

[i]BottomOpen/TopOpen[/i]
If 1, objects and Clonks can fall out of the map.

For all options, see [url=http://docs.openclonk.org/en/sdk/scenario/scenario.html]Scenario.txt.[/url]

[b]Teams.txt[/b]
(See [url=http://docs.openclonk.org/en/sdk/scenario/Teams.html]docs[/url])
Used to define Teams. I will do another tutorial on that later.

[b]Title.txt[/b]
Contains the scenario titel which is shown in the frontend. DE: is the German titel and US: the English one.

[b]Title.png[/b]
The title graphic which will be shown alongside the description in the frontend. Has to have an aspect ratio of 4:3, preferably 640x480. Here is an article about how to design a good title graphics

[b]Map.bmp[/b]
The static map is saved into this bitmap. The colours do not necessarily correspond with the actual materials, so don't worry if it is pink and green. :)
You can edit it with an external program, that way it is possible to change the map dimensions even after already having painted something. (Scale canvas) [b]Attention Windows 7 users:[/b] The "Paint" program shipped by default can't handle OpenClonks colour palette properly and will break your map! Use another program like [url=http://www.softpedia.com/get/Multimedia/Graphic/Graphic-Editors/Paint-XP.shtml]Paint XP[/url].

[img]http://img547.imageshack.us/img547/6122/crasha.png[/img] [i]A typical Map.bmp (Crash landing)[/i]

The easiest way to get the materials right is to paint all the materials you want into the map in the engine, and then open the Map.bmp and use the Colour Picker tool to copy a material colour.
[url=http://www.cc.striver.net/texts.php?action=sh&id=7]Here[/url] is an extensive tutorial about materials. (German only D: | outdated D;)

[b]DescDE.rtf/DescUS.rtf[/b]
Contain the description in the respective language. Don't forget to write a description before releasing your work. :)

File:TUT-SCEN-SETL ScriptInitial.png

2013-09-02T14:40:27Z

Andriel:

Tutorial: Scenario Creation

2013-09-02T14:36:25Z

Andriel: Added link to follow-up tutorial one

'''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.

How to Create a Settlement Scenario

2013-08-25T15:26:54Z

Andriel:

'''NOT YET FINISHED'''

'''Welcome to this guide on how to create a Settlement scenario!''' 
This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''previous guide''']] is required. 

In the last tutorial, you learned how to create a basic scenario with a map and how to add objects to the map. However, a few more things are required for a complete settlement scenario: 
Goals, rules, base material like shovels and axes, etc. - all these things are set in the script. ''Script? But I have no idea of programming! :('' Don't worry, you don't need to be a C++ expert to get things working. OpenClonk features an easy-to-learn scripting language called C4Script. [[Script: Overview|'''Here''']] is a short overview. Typically, the best way to get into scripting is looking at scripts from other objects and scenarios and finding out what they do. There is also an extensive [http://docs.openclonk.org/en/sdk/ '''documentation'''] I will often link to in this tutorial. 
And even if you have no idea of C4Script, this guide will give you templates and code snippets you can use and easily customise to fit your needs.

= Preparations =

Expand your scenario and open the scenario script [http://docs.openclonk.org/en/sdk/scenario/script.html '''(docs)'''], a file called "Script.c". It should look similar to this:

[img]http://img545.imageshack.us/img545/4609/2cx.png[/img]

Everything between /* and */ is a comment, highlighted in red by the Eclipse text editor. It will be ignored by the engine when executing the code. You can write a short description of your scenario below the name like I did.
Next we have this:

<code>func Initialize()
{
CreateEnvironment();
}</code>

It is a function (keyword ''func'') called ''Initialize''. Everything between the curly brackets is executed when the function is called. (More about [http://docs.openclonk.org/en/sdk/script/Funcs.html '''functions''']). It calls the function ''CreateEnvironment'' which is declared below and is empty as you can see in the screenshot. Delete both the call ''CreateEnvironment();'' and the function below, so we are left with an empty Initialize function.

= Goals =

First you'll need to decide which goal(s) you want to have for your scenario. Inside Eclipse, you can scroll down, expand "Objects.ocd" and then "Goals.ocd" to see all goals currently in the game. In the screenshot, I highlighted the ones which work with settlement scenarios, I will go through all of them.

[img]http://img689.imageshack.us/img689/8895/vvgj.png[/img]

==Wealth==

This one's very easy to set up, just paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Wealth);
goal -> SetWealthGoal(XYXY);</code>

Replace XYXY with the wealth the player should achieve to win.

==Resource Extraction==

The goal is to mine all of a specific resource. Paste the following code into the Initialize function:

<code>var goal = CreateObject(Goal_ResourceExtraction);
goal -> SetResource("XYXY");</code>

Replace XYXY with the name of the ressource to extract, for example: ''SetRessource("Granite");'' or ''SetRessource("Gold");''

==Expansion==

A certain amount of the map must be claimed by constructing flags. Paste the following code into your Initialize function:

<code>var goal = CreateObject(Goal_Expansion);
goal -> SetExpansionGoal(XYXY);</code>

Replace XYXY with the area to be covered in promillage of the total map. So for covering half the map, it would be ''SetExpansionGoal(500);''

= Rules =

Rules restrict or allow something. As well as for the goals, you can look them up in the objects browser. Adding rules is easy: Copy the following piece of code into your Initialize function:

<code>CreateObject(XYXY, 0, 0, NO_OWNER);</code>

where "XYXY" is replaced by the ID of the rule. The ID is the unique identifier every object has, like it's internal name. To find out the ID of an object, expand it and open the file "DefCore.txt". In the second line, it says ''id=XYXY'', that's the ID.
If you want multiple rules, just copy the snippet and insert another ID.
'''Note:''' You don't need to have rules, Goldrush, a standard settlement scenario, has no rules set.

This is what my Initialize function looks like after adding two goals and two rules.

[img]http://img534.imageshack.us/img534/2552/hzn.png[/img]

= Start Position and Equipment =

There is another important function: InitializePlayer. While Initalize is used to set up goals, rules, place objects, etc. (so gameworld-related things), InitializePlayer is for player-related stuff, like start position, base materials, or view range.

==Preparations==

Leave out one line after the closing curly bracket of the Initialize function and add this empty function below:

<code>func InitializePlayer(int plr)
{

}</code>

Right now not much is happening, put the following code into the newly created function:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{

}</code>

That may look quite complicated, but it's basically a loop (a [http://docs.openclonk.org/en/sdk/script/for.html '''for loop'''], to be precise) which runs through all the crew members. What we write into that loop (again between the curly braces) will be executed for every crew member (the variable "clonk") the player gets at the beginning of the scenario. The variable "index" is the index of the respective clonk, starting from 0 and then counting up until no more crew member is found, then the loop will end.

==Start Position==
'''Note: If you want the player to spawn at a random position, you can leave this out.'''

First you'll need to find out the coordinates of the position at which you want the players to get spawned. OpenClonk uses a 2D coordinate system, point 0X,0Y is the upper left corner. The X axis goes right, the Y axis goes down. One unit corresponds to 1 pixel ingame.
To find out the coordinates, you need to start your scenario in editor mode and select the editing cursor. Then move the cursor to your desired start point (the center of the clonk will be at this position, so don't set it too close to the ground or the clonk will stuck) and read the coordinates in the lower left corner of the engine window. Keep them in mind, you will need them shortly.
Now copy this code into your loop:

<code>clonk -> SetPosition(X, Y);</code>

And replace X and Y with your coordinates.

==Equipment==

The command we need for placing something in a clonks inventory is [http://docs.openclonk.org/en/sdk/script/fn/CreateContents.html '''CreateContents''']. It needs two arguments, ID and count of the object to be created (If count is not given, the default amount of 1 will be used). So if we wanted to give every crew member a shovel and a hammer, it would look like this:

<code>var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{
clonk -> CreateContents(Shovel);
clonk -> CreateContents(Hammer);
}</code>

But we don't want the same equipment for every crew member, we want the first one to have shovel and hammer, the second one shovel and axe. How to do this? Using an [http://docs.openclonk.org/en/sdk/script/fn/if.html#if '''if condition'''] and ''else''!
Basically, you enter a condition inside the parentheses and if it returns true, the following command or code block will be executed. If it returns false, else will be executed. We have the variable ''index'' from the for loop which indicates the number of the current crew member. Let's use this and say: If it is the first crew member (index = 0), give it shovel and hammer, else give it shovel and axe. It looks like that:

[img]http://img854.imageshack.us/img854/6408/n40b.png[/img]

Note that you can not only put the CreateContents commands into the if block, but also other things. You could for example let one crew member spawn at the left side of an abyss and the other one on the right side!

==View Range==

You may want to limit the zoom range so the player can't zoom out the whole map. This is also done in the InitializePlayer function, but it isn't applied to individual clonks, but to the player. As our for loop runs through all crew members, we don't write the following code into it, but outside of it below.
We need two commands, [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerZoomByViewRange.html '''SetPlayerZoomByViewRange'''] and [http://docs.openclonk.org/en/sdk/script/fn/SetPlayerViewLock.html SetPlayerViewLock'''].
First we will limit the zoom range so the player cannot some out farther than 500 pixels:

<code>SetPlayerZoomByViewRange(plr, 500, nil, PLRZOOM_LimitMax);</code>

(The data type ''nil'' can be used to leave out a parameter.)
Then we will lock his view so he can't scroll around to explore the map:

<code>SetPlayerViewLock(plr, true);</code>

// Some natural disasters, earthquakes, volcanos, meteorites.
Meteor->SetChance(15);
Earthquake->SetChance(2);
Volcano->SetChance(4);
Volcano->SetMaterial("DuroLava");

= Addendum - Components of .ocs files =
This is an overview of all the files a Scenario.ocs can contain.
[img]http://img705.imageshack.us/img705/7878/confusingfiles.png[/img]

[b]Material.ocg[/b]
Contains material-texture combinations. Don't change it, otherwise you will get a [tt]FATAL ERROR: Error loading materials.[/tt] and the game won't start. If that happens, just delete the file, it will be recreated.

[b]Script.c[/b]
Contains the scenario script.

[b]Game.txt[/b]
Contains information about every object that has been saved and will be created on scenario startup. These are informations like position, size, category, flags, properties, etc. Don't touch it and everything will be fine.

[b]Landscape.txt[/b]
As mentioned before this file contains code to dynamically create a map. You can create complex landscapes that look different every game. Have a look at it:
[url=http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html]More information.[/url] [url=http://www.cc.striver.net/texts.php?action=sh&id=13]German tutorial.[/url]
Not needed if you are manually painting a map.

[b]Scenario.txt[/b]
Contains general scenario settings. These are some of the most important ones:

[i]MinPlayer/MaxPlayer[/i]
Sets the minimum and maximum number of players to play this scenario. You could for example only make it playable with 2 to 4 players using [tt]MinPlayer=2[/tt] and [tt]MaxPlayer=4[/tt].

[i]MapWidth/MapHeight[/i]
Specifies the map size.
[b]Note:[/b] Doesn't work if there already is a Map.bmp file. Use the method explained below to change the size of a painted map afterwards: Painting with an external program.

[i]MapZoom[/i]
Something between 5 and 15. The factor the Map.bmp file is zoomed by for the actual gameworld. So if you have a 300x100 bitmap file and MapZoom=15, the ingame landscape will be 4500x1500 pixels big.

[i]BottomOpen/TopOpen[/i]
If 1, objects and Clonks can fall out of the map.

For all options, see [url=http://docs.openclonk.org/en/sdk/scenario/scenario.html]Scenario.txt.[/url]

[b]Teams.txt[/b]
(See [url=http://docs.openclonk.org/en/sdk/scenario/Teams.html]docs[/url])
Used to define Teams. I will do another tutorial on that later.

[b]Title.txt[/b]
Contains the scenario titel which is shown in the frontend. DE: is the German titel and US: the English one.

[b]Title.png[/b]
The title graphic which will be shown alongside the description in the frontend. Has to have an aspect ratio of 4:3, preferably 640x480. Here is an article about how to design a good title graphics

[b]Map.bmp[/b]
The static map is saved into this bitmap. The colours do not necessarily correspond with the actual materials, so don't worry if it is pink and green. :)
You can edit it with an external program, that way it is possible to change the map dimensions even after already having painted something. (Scale canvas) [b]Attention Windows 7 users:[/b] The "Paint" program shipped by default can't handle OpenClonks colour palette properly and will break your map! Use another program like [url=http://www.softpedia.com/get/Multimedia/Graphic/Graphic-Editors/Paint-XP.shtml]Paint XP[/url].

[img]http://img547.imageshack.us/img547/6122/crasha.png[/img] [i]A typical Map.bmp (Crash landing)[/i]

The easiest way to get the materials right is to paint all the materials you want into the map in the engine, and then open the Map.bmp and use the Colour Picker tool to copy a material colour.
[url=http://www.cc.striver.net/texts.php?action=sh&id=7]Here[/url] is an extensive tutorial about materials. (German only D: | outdated D;)

[b]DescDE.rtf/DescUS.rtf[/b]
Contain the description in the respective language. Don't forget to write a description before releasing your work. :)

How to Create a Settlement Scenario

2013-08-25T10:59:03Z

Andriel:

'''NOT YET FINISHED'''

'''Welcome to this guide on how to create a Settlement scenario!''' 
This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''previous guide''']] is required. 

In the last tutorial, you learned how to create a basic scenario with a map and how to add objects to the map. However, a few more things are required for a complete settlement scenario: 
Goals, rules, base material like shovels and axes, etc. - all these things are set in the script. "Script? But I have no idea of programming! :(" Don't worry, you don't need to be a C++ expert to get things working. OpenClonk features an easy to learn script language called C4Script. [[Script: Overview|'''Here''']] is a short overview. Typically, the best way to get into scripting is looking at scripts from other objects and scenarios and finding out what they do. There is also an extensive [http://docs.openclonk.org/en/sdk/ '''documentation'''] I will often link to in this tutorial. 
And even if you have no idea of C4Script, this guide will give you templates and code snippets you can use and easily customise to fit your needs.

= Preparations =

Expand your scenario and open the scenario script [http://docs.openclonk.org/en/sdk/scenario/script.html '''(docs)'''], a file called "Script.c". It should look similar to this:

[img]http://img545.imageshack.us/img545/4609/2cx.png[/img]

Everything between /* and */ is a comment, highlighted in red by the Eclipse text editor. It will be ignored by the engine when executing the code. You can write a short description of your scenario below the name like I did.
Next we have this:

[tt]func Initialize()
{
CreateEnvironment();
}[/tt]

It is a function (keyword [tt]func[/tt]) called "Initialize". Everything between the curly brackets is executed when the function is called. (More about [url=http://docs.openclonk.org/en/sdk/script/Funcs.html]functions[/url]). It calls the function "CreateEnvironment" which is declared below and is empty as you can see in the screenshot. Delete both the call "CreateEnvironment();" and the function below, so we are left with an empty Initialize function.

[b][b]========[/b][/b]
[b][b]---Goals---[/b][/b]
[b][b]========[/b][/b]

First you'll need to decide which goal(s) you want to have for your scenario. Inside Eclipse, you can scroll down, expand "Objects.ocd" and then "Goals.ocd" to see all goals currently in the game. In the screenshot, I highlighted the ones which work with settlement scenarios, I will go through all of them.

[img]http://img689.imageshack.us/img689/8895/vvgj.png[/img]

[b]Wealth[/b]

This one's very easy to set up, just paste the following code into your Initialize function:

[tt]var goal = CreateObject(Goal_Wealth);
goal -> SetWealthGoal(XYXY);[/tt]

Replace XYXY with the wealth the player should achieve to win.

[b]Resource Extraction[/b]

The goal is to mine all of a specific resource. Paste the following code into the Initialize function:

[tt]var goal = CreateObject(Goal_ResourceExtraction);
goal -> SetResource("XYXY");[/tt]

Replace XYXY with the name of the ressource to extract, for example: [tt]SetRessource("Granite");[/tt] or [tt]SetRessource("Gold");[/tt]

[b]Expansion[/b]

A certain amount of the map must be claimed by constructing flags. Paste the following code into your Initialize function:

[tt]var goal = CreateObject(Goal_Expansion);
goal -> SetExpansionGoal(XYXY);[/tt]

Replace XYXY with the area to be covered in promillage of the total map. So for covering half the map, it would be [tt]SetExpansionGoal(500);[/tt]

[b][b]========[/b][/b]
[b][b]---Rules---[/b][/b]
[b][b]========[/b][/b]

Rules restrict or allow something. As well as for the goals, you can look them up in the objects browser. Adding rules is easy: Copy the following piece of code into your Initialize function:

[tt]CreateObject(XYXY, 0, 0, NO_OWNER);[/tt]

whereas "XYXY" is replaced by the ID of the rule. The ID is the unique identifier every object has, like it's internal name. To find out the ID of an object, expand it and open the file "DefCore.txt". In the second line, it says [tt]id=XYXY[/tt], that's the ID.
If you want multiple rules, just copy the snippet and insert another ID.
[b]Note:[/b] You don't need to have rules, Goldrush, a standard settlement scenario, has no rules set.

This is what my Initialize function looks like after adding two goals and two rules.

[img]http://img534.imageshack.us/img534/2552/hzn.png[/img]

[b][b]=========================[/b][/b]
[b][b]---Start Position and Equipment---[/b][/b]
[b][b]=========================[/b][/b]

There is another important function: InitializePlayer. While Initalize is used to set up goals, rules, place objects, etc. (so gameworld-related things), InitializePlayer is for player-related stuff, like start position, base materials, or view range.

[b][b]Preparations[/b][/b]

Leave out one line after the closing curly bracket of the Initialize function and add this empty function below:

[tt]func InitializePlayer(int plr)
{

}[/tt]

Right now not much is happening, put the following code into the newly created function:

[tt]var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{

}[/tt]

That may look quite complicated, but it's basically a loop (a [url=http://docs.openclonk.org/en/sdk/script/for.html]for loop[/url], to be precise) which runs through all the crew members. What we write into that loop (again between the curly braces) will be executed for every crew member (the variable "clonk") the player gets at the beginning of the scenario. The variable "index" is the index of the respective clonk, starting from 0 and then counting up until no more crew member is found, then the loop will end.

[b][b]Start Position[/b][/b]
[b]Note: If you want the player to spawn at a random position, you can leave this out.[/b]

First you'll need to find out the coordinates of the position at which you want the players to get spawned. OpenClonk uses a 2D coordinate system, point 0X,0Y is the upper left corner. The X axis goes right, the Y axis goes down. One unit corresponds to 1 pixel ingame.
To find out the coordinates, you need to start your scenario in editor mode and select the editing cursor. Then move the cursor to your desired start point (the center of the clonk will be at this position, so don't set it too close to the ground or the clonk will stuck) and read the coordinates in the lower left corner of the engine window. Keep them in mind, you will need them shortly.
Now copy this code into your loop:

[tt]clonk -> SetPosition(X, Y);[/tt]

And replace X and Y with your coordinates.

[b]Equipment[/b]

The command we need for placing something in a clonks inventory is [url=http://docs.openclonk.org/en/sdk/script/fn/CreateContents.html]CreateContents[/url]. It needs two arguments, ID and count of the object to be created (If count is not given, the default amount of 1 will be used). So if we wanted to give every crew member a shovel and a hammer, it would look like this:

[tt]var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{
clonk -> CreateContents(Shovel);
clonk -> CreateContents(Hammer);
}[/tt]

But we don't want the same equipment for every crew member, we want the first one to have shovel and hammer, the second one shovel and axe. How to do this? Using an [url=http://docs.openclonk.org/en/sdk/script/fn/if.html#if]if condition[/url] and else!
Basically, you enter a condition inside the parentheses and if it returns true, the following command or code block will be executed. If it returns false, else will be executed. We have the variable [tt]index[/tt] from the for loop which indicates the number of the current crew member. Let's use this and say: If it is the first crew member (index = 0), give it shovel and hammer, else give it shovel and axe. It looks like that:

[img]http://img854.imageshack.us/img854/6408/n40b.png[/img]

Note that you can not only put the CreateContents commands into the if block, but also other things. You could for example let one crew member spawn at the left side of an abyss and the other one on the right side!

[b]View Range[/b]

You may want to limit the zoom range so the player can't zoom out the whole map. This is also done in the InitializePlayer function, but it isn't applied to individual clonks, but to the player. As our for loop runs through all crew members, we don't write the following code into it, but outside of it below.
We need two commands, [url=http://docs.openclonk.org/en/sdk/script/fn/SetPlayerZoomByViewRange.html]SetPlayerZoomByViewRange[/url] and [url=http://docs.openclonk.org/en/sdk/script/fn/SetPlayerViewLock.html]SetPlayerViewLock[/url].
First we will limit the zoom range so the player cannot some out farther than 500 pixels:

[tt]SetPlayerZoomByViewRange(plr, 500, nil, PLRZOOM_LimitMax);[/tt]

(The data type [tt]nil[/tt] can be used to leave out a parameter.)
Then we will lock his view so he can't scroll around to explore the map:

[tt]SetPlayerViewLock(plr, true);[/tt]

// Some natural disasters, earthquakes, volcanos, meteorites.
Meteor->SetChance(15);
Earthquake->SetChance(2);
Volcano->SetChance(4);
Volcano->SetMaterial("DuroLava");

[h]Addendum - Components of .ocs files[/h]
This is an overview of all the files a Scenario.ocs can contain.
[img]http://img705.imageshack.us/img705/7878/confusingfiles.png[/img]

[b]Material.ocg[/b]
Contains material-texture combinations. Don't change it, otherwise you will get a [tt]FATAL ERROR: Error loading materials.[/tt] and the game won't start. If that happens, just delete the file, it will be recreated.

[b]Script.c[/b]
Contains the scenario script.

[b]Game.txt[/b]
Contains information about every object that has been saved and will be created on scenario startup. These are informations like position, size, category, flags, properties, etc. Don't touch it and everything will be fine.

[b]Landscape.txt[/b]
As mentioned before this file contains code to dynamically create a map. You can create complex landscapes that look different every game. Have a look at it:
[url=http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html]More information.[/url] [url=http://www.cc.striver.net/texts.php?action=sh&id=13]German tutorial.[/url]
Not needed if you are manually painting a map.

[b]Scenario.txt[/b]
Contains general scenario settings. These are some of the most important ones:

[i]MinPlayer/MaxPlayer[/i]
Sets the minimum and maximum number of players to play this scenario. You could for example only make it playable with 2 to 4 players using [tt]MinPlayer=2[/tt] and [tt]MaxPlayer=4[/tt].

[i]MapWidth/MapHeight[/i]
Specifies the map size.
[b]Note:[/b] Doesn't work if there already is a Map.bmp file. Use the method explained below to change the size of a painted map afterwards: Painting with an external program.

[i]MapZoom[/i]
Something between 5 and 15. The factor the Map.bmp file is zoomed by for the actual gameworld. So if you have a 300x100 bitmap file and MapZoom=15, the ingame landscape will be 4500x1500 pixels big.

[i]BottomOpen/TopOpen[/i]
If 1, objects and Clonks can fall out of the map.

For all options, see [url=http://docs.openclonk.org/en/sdk/scenario/scenario.html]Scenario.txt.[/url]

[b]Teams.txt[/b]
(See [url=http://docs.openclonk.org/en/sdk/scenario/Teams.html]docs[/url])
Used to define Teams. I will do another tutorial on that later.

[b]Title.txt[/b]
Contains the scenario titel which is shown in the frontend. DE: is the German titel and US: the English one.

[b]Title.png[/b]
The title graphic which will be shown alongside the description in the frontend. Has to have an aspect ratio of 4:3, preferably 640x480. Here is an article about how to design a good title graphics

[b]Map.bmp[/b]
The static map is saved into this bitmap. The colours do not necessarily correspond with the actual materials, so don't worry if it is pink and green. :)
You can edit it with an external program, that way it is possible to change the map dimensions even after already having painted something. (Scale canvas) [b]Attention Windows 7 users:[/b] The "Paint" program shipped by default can't handle OpenClonks colour palette properly and will break your map! Use another program like [url=http://www.softpedia.com/get/Multimedia/Graphic/Graphic-Editors/Paint-XP.shtml]Paint XP[/url].

[img]http://img547.imageshack.us/img547/6122/crasha.png[/img] [i]A typical Map.bmp (Crash landing)[/i]

The easiest way to get the materials right is to paint all the materials you want into the map in the engine, and then open the Map.bmp and use the Colour Picker tool to copy a material colour.
[url=http://www.cc.striver.net/texts.php?action=sh&id=7]Here[/url] is an extensive tutorial about materials. (German only D: | outdated D;)

[b]DescDE.rtf/DescUS.rtf[/b]
Contain the description in the respective language. Don't forget to write a description before releasing your work. :)

How to Create a Settlement Scenario

2013-08-25T10:56:38Z

Andriel: Created page with "'''Welcome to this guide on how to create a Settlement scenario!''' This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''..."

'''Welcome to this guide on how to create a Settlement scenario!''' 
This is a follow-up tutorial, so all knowledge and progress from the [[Tutorial: Scenario Creation|'''previous guide''']] is required. 

In the last tutorial, you learned how to create a basic scenario with a map and how to add objects to the map. However, a few more things are required for a complete settlement scenario: 
Goals, rules, base material like shovels and axes, etc. - all these things are set in the script. "Script? But I have no idea of programming! :(" Don't worry, you don't need to be a C++ expert to get things working. OpenClonk features an easy to learn script language called C4Script. [[Script: Overview|'''Here''']] is a short overview. Typically, the best way to get into scripting is looking at scripts from other objects and scenarios and finding out what they do. There is also an extensive [http://docs.openclonk.org/en/sdk/ '''documentation'''] I will often link to in this tutorial. 
And even if you have no idea of C4Script, this guide will give you templates and code snippets you can use and easily customise to fit your needs.

= Preparations =

Expand your scenario and open the scenario script [http://docs.openclonk.org/en/sdk/scenario/script.html '''(docs)'''], a file called "Script.c". It should look similar to this:

[img]http://img545.imageshack.us/img545/4609/2cx.png[/img]

Everything between /* and */ is a comment, highlighted in red by the Eclipse text editor. It will be ignored by the engine when executing the code. You can write a short description of your scenario below the name like I did.
Next we have this:

[tt]func Initialize()
{
CreateEnvironment();
}[/tt]

It is a function (keyword [tt]func[/tt]) called "Initialize". Everything between the curly brackets is executed when the function is called. (More about [url=http://docs.openclonk.org/en/sdk/script/Funcs.html]functions[/url]). It calls the function "CreateEnvironment" which is declared below and is empty as you can see in the screenshot. Delete both the call "CreateEnvironment();" and the function below, so we are left with an empty Initialize function.

[b][b]========[/b][/b]
[b][b]---Goals---[/b][/b]
[b][b]========[/b][/b]

First you'll need to decide which goal(s) you want to have for your scenario. Inside Eclipse, you can scroll down, expand "Objects.ocd" and then "Goals.ocd" to see all goals currently in the game. In the screenshot, I highlighted the ones which work with settlement scenarios, I will go through all of them.

[img]http://img689.imageshack.us/img689/8895/vvgj.png[/img]

[b]Wealth[/b]

This one's very easy to set up, just paste the following code into your Initialize function:

[tt]var goal = CreateObject(Goal_Wealth);
goal -> SetWealthGoal(XYXY);[/tt]

Replace XYXY with the wealth the player should achieve to win.

[b]Resource Extraction[/b]

The goal is to mine all of a specific resource. Paste the following code into the Initialize function:

[tt]var goal = CreateObject(Goal_ResourceExtraction);
goal -> SetResource("XYXY");[/tt]

Replace XYXY with the name of the ressource to extract, for example: [tt]SetRessource("Granite");[/tt] or [tt]SetRessource("Gold");[/tt]

[b]Expansion[/b]

A certain amount of the map must be claimed by constructing flags. Paste the following code into your Initialize function:

[tt]var goal = CreateObject(Goal_Expansion);
goal -> SetExpansionGoal(XYXY);[/tt]

Replace XYXY with the area to be covered in promillage of the total map. So for covering half the map, it would be [tt]SetExpansionGoal(500);[/tt]

[b][b]========[/b][/b]
[b][b]---Rules---[/b][/b]
[b][b]========[/b][/b]

Rules restrict or allow something. As well as for the goals, you can look them up in the objects browser. Adding rules is easy: Copy the following piece of code into your Initialize function:

[tt]CreateObject(XYXY, 0, 0, NO_OWNER);[/tt]

whereas "XYXY" is replaced by the ID of the rule. The ID is the unique identifier every object has, like it's internal name. To find out the ID of an object, expand it and open the file "DefCore.txt". In the second line, it says [tt]id=XYXY[/tt], that's the ID.
If you want multiple rules, just copy the snippet and insert another ID.
[b]Note:[/b] You don't need to have rules, Goldrush, a standard settlement scenario, has no rules set.

This is what my Initialize function looks like after adding two goals and two rules.

[img]http://img534.imageshack.us/img534/2552/hzn.png[/img]

[b][b]=========================[/b][/b]
[b][b]---Start Position and Equipment---[/b][/b]
[b][b]=========================[/b][/b]

There is another important function: InitializePlayer. While Initalize is used to set up goals, rules, place objects, etc. (so gameworld-related things), InitializePlayer is for player-related stuff, like start position, base materials, or view range.

[b][b]Preparations[/b][/b]

Leave out one line after the closing curly bracket of the Initialize function and add this empty function below:

[tt]func InitializePlayer(int plr)
{

}[/tt]

Right now not much is happening, put the following code into the newly created function:

[tt]var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{

}[/tt]

That may look quite complicated, but it's basically a loop (a [url=http://docs.openclonk.org/en/sdk/script/for.html]for loop[/url], to be precise) which runs through all the crew members. What we write into that loop (again between the curly braces) will be executed for every crew member (the variable "clonk") the player gets at the beginning of the scenario. The variable "index" is the index of the respective clonk, starting from 0 and then counting up until no more crew member is found, then the loop will end.

[b][b]Start Position[/b][/b]
[b]Note: If you want the player to spawn at a random position, you can leave this out.[/b]

First you'll need to find out the coordinates of the position at which you want the players to get spawned. OpenClonk uses a 2D coordinate system, point 0X,0Y is the upper left corner. The X axis goes right, the Y axis goes down. One unit corresponds to 1 pixel ingame.
To find out the coordinates, you need to start your scenario in editor mode and select the editing cursor. Then move the cursor to your desired start point (the center of the clonk will be at this position, so don't set it too close to the ground or the clonk will stuck) and read the coordinates in the lower left corner of the engine window. Keep them in mind, you will need them shortly.
Now copy this code into your loop:

[tt]clonk -> SetPosition(X, Y);[/tt]

And replace X and Y with your coordinates.

[b]Equipment[/b]

The command we need for placing something in a clonks inventory is [url=http://docs.openclonk.org/en/sdk/script/fn/CreateContents.html]CreateContents[/url]. It needs two arguments, ID and count of the object to be created (If count is not given, the default amount of 1 will be used). So if we wanted to give every crew member a shovel and a hammer, it would look like this:

[tt]var clonk;
for(var index = 0; clonk = GetCrew(plr, index); ++index)
{
clonk -> CreateContents(Shovel);
clonk -> CreateContents(Hammer);
}[/tt]

But we don't want the same equipment for every crew member, we want the first one to have shovel and hammer, the second one shovel and axe. How to do this? Using an [url=http://docs.openclonk.org/en/sdk/script/fn/if.html#if]if condition[/url] and else!
Basically, you enter a condition inside the parentheses and if it returns true, the following command or code block will be executed. If it returns false, else will be executed. We have the variable [tt]index[/tt] from the for loop which indicates the number of the current crew member. Let's use this and say: If it is the first crew member (index = 0), give it shovel and hammer, else give it shovel and axe. It looks like that:

[img]http://img854.imageshack.us/img854/6408/n40b.png[/img]

Note that you can not only put the CreateContents commands into the if block, but also other things. You could for example let one crew member spawn at the left side of an abyss and the other one on the right side!

[b]View Range[/b]

You may want to limit the zoom range so the player can't zoom out the whole map. This is also done in the InitializePlayer function, but it isn't applied to individual clonks, but to the player. As our for loop runs through all crew members, we don't write the following code into it, but outside of it below.
We need two commands, [url=http://docs.openclonk.org/en/sdk/script/fn/SetPlayerZoomByViewRange.html]SetPlayerZoomByViewRange[/url] and [url=http://docs.openclonk.org/en/sdk/script/fn/SetPlayerViewLock.html]SetPlayerViewLock[/url].
First we will limit the zoom range so the player cannot some out farther than 500 pixels:

[tt]SetPlayerZoomByViewRange(plr, 500, nil, PLRZOOM_LimitMax);[/tt]

(The data type [tt]nil[/tt] can be used to leave out a parameter.)
Then we will lock his view so he can't scroll around to explore the map:

[tt]SetPlayerViewLock(plr, true);[/tt]

// Some natural disasters, earthquakes, volcanos, meteorites.
Meteor->SetChance(15);
Earthquake->SetChance(2);
Volcano->SetChance(4);
Volcano->SetMaterial("DuroLava");

[h]Addendum - Components of .ocs files[/h]
This is an overview of all the files a Scenario.ocs can contain.
[img]http://img705.imageshack.us/img705/7878/confusingfiles.png[/img]

[b]Material.ocg[/b]
Contains material-texture combinations. Don't change it, otherwise you will get a [tt]FATAL ERROR: Error loading materials.[/tt] and the game won't start. If that happens, just delete the file, it will be recreated.

[b]Script.c[/b]
Contains the scenario script.

[b]Game.txt[/b]
Contains information about every object that has been saved and will be created on scenario startup. These are informations like position, size, category, flags, properties, etc. Don't touch it and everything will be fine.

[b]Landscape.txt[/b]
As mentioned before this file contains code to dynamically create a map. You can create complex landscapes that look different every game. Have a look at it:
[url=http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html]More information.[/url] [url=http://www.cc.striver.net/texts.php?action=sh&id=13]German tutorial.[/url]
Not needed if you are manually painting a map.

[b]Scenario.txt[/b]
Contains general scenario settings. These are some of the most important ones:

[i]MinPlayer/MaxPlayer[/i]
Sets the minimum and maximum number of players to play this scenario. You could for example only make it playable with 2 to 4 players using [tt]MinPlayer=2[/tt] and [tt]MaxPlayer=4[/tt].

[i]MapWidth/MapHeight[/i]
Specifies the map size.
[b]Note:[/b] Doesn't work if there already is a Map.bmp file. Use the method explained below to change the size of a painted map afterwards: Painting with an external program.

[i]MapZoom[/i]
Something between 5 and 15. The factor the Map.bmp file is zoomed by for the actual gameworld. So if you have a 300x100 bitmap file and MapZoom=15, the ingame landscape will be 4500x1500 pixels big.

[i]BottomOpen/TopOpen[/i]
If 1, objects and Clonks can fall out of the map.

For all options, see [url=http://docs.openclonk.org/en/sdk/scenario/scenario.html]Scenario.txt.[/url]

[b]Teams.txt[/b]
(See [url=http://docs.openclonk.org/en/sdk/scenario/Teams.html]docs[/url])
Used to define Teams. I will do another tutorial on that later.

[b]Title.txt[/b]
Contains the scenario titel which is shown in the frontend. DE: is the German titel and US: the English one.

[b]Title.png[/b]
The title graphic which will be shown alongside the description in the frontend. Has to have an aspect ratio of 4:3, preferably 640x480. Here is an article about how to design a good title graphics

[b]Map.bmp[/b]
The static map is saved into this bitmap. The colours do not necessarily correspond with the actual materials, so don't worry if it is pink and green. :)
You can edit it with an external program, that way it is possible to change the map dimensions even after already having painted something. (Scale canvas) [b]Attention Windows 7 users:[/b] The "Paint" program shipped by default can't handle OpenClonks colour palette properly and will break your map! Use another program like [url=http://www.softpedia.com/get/Multimedia/Graphic/Graphic-Editors/Paint-XP.shtml]Paint XP[/url].

[img]http://img547.imageshack.us/img547/6122/crasha.png[/img] [i]A typical Map.bmp (Crash landing)[/i]

The easiest way to get the materials right is to paint all the materials you want into the map in the engine, and then open the Map.bmp and use the Colour Picker tool to copy a material colour.
[url=http://www.cc.striver.net/texts.php?action=sh&id=7]Here[/url] is an extensive tutorial about materials. (German only D: | outdated D;)

[b]DescDE.rtf/DescUS.rtf[/b]
Contain the description in the respective language. Don't forget to write a description before releasing your work. :)

Script: Overview

2013-08-25T10:55:36Z

Andriel: Added link to next part

This page should give you a short overview about the characteristics of C4Script in OpenClonk. It should be helpful if you either know some programming and quickly want to see how C4Script feels like or if you come from CR and want to see what changed. 
If you come from CR scripting, you might want to jump directly to [[#Proplists]].
 

= Script files =
In OpenClonk one script-file usually belongs to an object or is in the global System.ocg directory. 

= Variables and Data types =
OpenClonk does not use strict typing, you declare function-local variables with ''var'', object local variales outside of functions with ''local'' and global variables with ''static''. Such ''static'' variables might also be declared constant with ''static const''. 
Variables which have not been assigned any value yet, contain the value ''nil''. 
Parameters can have a type that is checked when the function is called. 

= Functions =
Functions can be either declared ''global'' or without an access specifier which would make them object-local. 
You can call functions from the same object like you would expect with ''FunctionName(parameters...)''. If you want to call a function in another object, use the arrow notation (''my_object->MyFunctionCall(par1, par2, par3);'').

= Arrays =
Arrays in Clonk are declared with brackets (''var a = [];'' or ''var a = [3];'') and grow dynamically when a field is assigned a value for the first time. You can get the length of arrays with ''GetLength()''. 
Indices start at 0. 

= Proplists =
Proplists are like assoziative arrays (if you come from another programming language, think of a map) and are declared with curly braces (''var p = {};'' or ''var p = { foo = 1, bar = 2 };''). 
You can access elements from a proplist with either the dot-notation ''p.key'' and ''p.key = value;'' or with the brackets and the key as a string (''p["key"] = value;''). 
Note that in Clonk a lot of things are proplists: even objects! You can access the local variables of an object like any proplist elements. 
Proplists can also contain functions, which are then called with the arrow notation as described above. 
 
The next part of this tutorial about callbacks and timers is [[Script: Callbacks and Timers|'''here''']].

[[Category:Scripting Tutorial]]

Artists Guide

2013-08-25T08:10:40Z

Andriel:

There are three main areas where artists can contribute: Modelling 3D objects and the texturing thereof, which requires different skills and doesn't need to be done by the same person. Most of our modellers use Blender, however which modeller you use is not important as long as it can export meshes to the OGRE format.
For creating scenario backgrounds, textures for models, scenario decoration and stuff, we actually need people who are good with Photoshop, GIMP or any other image manipulation software.
Also, we are in desperate need for people who are talented at creating sounds and/or music.

Have a look in the [http://forum.openclonk.org/board_show.pl?bid=2 art workshop].

__TOC__

== Modelling ==
[[File:Foundry_mesh.png|200px|thumb|right|The mesh of the foundry]] We got rid of the old graphics from Clonk Rage which were so tiny that it was already hard to play the game in a proper resolution. (The character you control smaller than a mouse cursor? Come on!) For OpenClonk, the graphics are about three times as big and detailed as in the old Clonk series.
Unlike in previous clonk titles, most objects are actually models that are rendered in game. The file format we use for this is the [http://www.ogre3d.org/ OGRE] format as it is a format designed to be used in games plus all important modellers can export into this format. However, we do exchange of the models in their native format (mostly .blend).

Now, for creating models that are to be rendered ingame (in OpenClonk), there are a few additional things that have to be considered if you are used to creating models that are rendered before the start of the game. Apart from the polygon count, for each model we only use one UV-mapped texture rather than zillion materials with different colors/googled textures. More guidelines on how to create a real time model for OpenClonk can be read here: [[Modelling Workflow]].

You might ask yourself if there is a guideline of how many polygons a model should max have. Yes, there is one: So many, that the object looks both good ingame with a 3x zoom and on it's picture graphic (whichever is bigger). Also, unanimated inventory items like materials don't need to be rendered ingame. As sprites, the polygon count doesn't matter.

Also, if you want to contribute a model, please always include the 3D-model when you attach a rendering of the same to your post. Otherwise, if you somehow lose your model, all the work was in vain.

== Textures ==
[[File:Foundry_texture.png|200px|thumb|left|UV mapped texture of the foundry]]
[[File:Foundry_render.png|200px|thumb|right|Foundry with mesh and texture]]
We use the [http://creativecommons.org/licenses/by/3.0/ CC-by] licence for OpenClonk and ask you to license your contributions under the same license. As many textures in texture archives have licenses which are not compatible with CC-by, we will have to create many textures on our own. But don't worry, it's quite easy and there are some really good tutorials on how to create quality textures from photos.

Here is a list of bigger texture archives and it's licenses which is a good source for resources: [[Texture Archives]]

My experience is that textures for 3D-models which are based on actual photos always turn out better then textures which where painted by oneself.

You might also ask yourself if there is a guideline of how big the texture for one 3D-model should be. Right: So big that it doesn't look blurred ingame with a 3x zoom and on it's picture graphic (whichever is bigger).

For material textures, we need seamless textures. Regarding this, there are different methods to create seamless textures from (a set of) photos, here is how I do it: [[Tutorial: Creating Seamless Textures]].
For GIMP, there are two filters which can do this automatically: The plugin ''[http://gimp-texturize.sourceforge.net/ Texturize]'' and the filter ''Resynthesise''. Both work good with textures with small random patterns like gravel, plaster, sand or ground. However, they don't produce quite as convincing results for bigger regular patterns like (roofing) tiles, bricks, wickerwork, pavements etc. The manual method that I proposed always produces better results and if you are experienced in this, it's a thing of five minutes.

== Exporting Meshes ==
Exporting a model properly for OpenClonk can be a tricky process, but we've compiled a step-by-step guide on how to do so.

Firstly, you'll need the proper tools. For [http://download.blender.org/release/Blender2.49b/ Blender 2.49b], you'll need the OGRE Exporter. Randrian has created an improved version of the OGRE Exporter which adds critical features necessary for animation blending. [http://attach.openclonk.org/9/17909/OgreExporterOC.zip Download Link]

*Extract the OGRE Exporter into your .blender/scripts/ folder.
*Install [http://www.python.org/download/releases/2.6.2/ Python 2.6.2]
*Obtain the [http://www.ogre3d.org/tikiwiki/OgreXmlConverter OGRE XML Converter software], bundled inside the OGRE Command Line Tools package (look in 'See Also' box for download).
*Extract the OGRE Command Line Tools somewhere easily accessible (ie: C:\OgreCommandLineTools).
*Load up blender, and create a new window and set the window type to 'Scripts Window'. Then click File>Export>OGRE Meshes to load the exporter GUI into that window.
*Hit the 'Preferences' button in the OGRE GUI. Set the location of the OGRE XML Exporter to Manual, and link to the location of the OgreXmlConverter.exe.
*In the directory of your .blend file, create an empty Actions.txt file. More on this later.
By following these steps, you should be able to properly export models for OpenClonk. If you run into any problems, leave a post on the forum addressing the issue.

'''Guidelines for Modelling'''
*Model on the Y/Z view-plane. Models in OpenClonk appear as they do on the Y/Z plane in blender. The X-Axis goes 'into' the screen. Make sure you model with regard to these axes (The Y/Z plane is the default side view in Blender).
*Do not use Mesh Transformations. Mesh transformations are not handled properly by the OGRE exporter, and will cause deformation in game. If you have transformations applied to an existing model, you can remove them (select the model and press alt+g, alt+s, alt+r). Caution: Avoid animating before removing transformations!
*3D Model must be Three-Dimensional. The 3D mesh must have length on all axes. Making a perfectly flat object on only two axes will cause it to not appear in-game. To fix this, move a vertex so the mesh has length on all axes.
*Avoid edges with more than two faces connected to them. Edges with more than two faces will cause shading errors in game. An easy way to circumvent this is to separate the third face from the edge, so it is close to the original edge, but not connected.
*What features work with the OGRE format? Not all of the features listed in Blender will affect an exported 3D OGRE mesh. For a full list of compatible features, visit: http://www.cs.ucr.edu/~macchiea/cs134/lab1/ogrehelp/ogremeshesexporter.html

'''Exporting the Model'''[[File:OgreExporter.png|200px|thumb|right|The OGRE Exporter frame in Blender]]
To export the model, you'll need to have a window for the OGRE exporter in Blender. Make a new pane for scripts, and click 'File/Export/OGRE Meshes'. Models used for OpenClonk must be exported with specific options.
*“Fix Up Axis to Y” should not be enabled.
*If you have the XML converter, make sure “OgreXMLConverter” is enabled.
*If you have already made manual modifications to the Scene.material file and are re-exporting the mesh and/or skeleton, make sure 'Export Materials' is not enabled.
*'Path:' will be where the OGRE files are exported to. You can use a temporary directory and then copy them into your OpenClonk object definition, or you can export the OGRE files directly into the object definition.

'''Using the Exported Files'''[[File:ExportedFiles.png|250px|thumb|right|Typical exported files before user modification.]]
Once you have exported the mesh, some files will be created in the chosen directory. Follow these steps:
*Make sure the “ .mesh” file is named “Graphics.mesh”.
*If you exported the OGRE files to a temporary directory, copy 'Graphics.mesh', the ' .skeleton' file, the 'Scene.material' file, and any textures used by the mesh to your object definition.
*If you have exported the OGRE files directly to your object definition, you can delete all .xml files and the .log file.

'''Scene.material'''

Scene.material is the file which defines which materials to apply to meshes. Manually modifying Scene.material is crucial to the mesh appearing properly in game. When you export (assuming you are using a texture) your Scene.material file will look more or less like this (don't worry if it looks somewhat different):

<pre style="color:green;width:75%;background-color:#dcdcdc">
material MyCube
{
receive_shadows on
technique
{
pass
{
cull_hardware none
scene_blend alpha_blend

ambient 1.0 1.0 1.0 1.0
diffuse 1.0 1.0 1.0 1.0
specular 0.0 0.0 0.0 0.0 12.5
emissive 0.0 0.0 0.0 0.0

texture_unit
{
texture MyCube.png
tex_address_mode wrap
filtering trilinear
}
}
}
}</pre>
*If 'depth_write off' exists, delete that line.
*If you are using alpha, make sure 'scene_blend alpha_blend' exists (as shown above).
*If your mesh has visible backface(s), make sure to add 'cull_hardware none' (as shown above).
*Depending on the method you used to define alpha in blender, the 'pass' section in Scene.Material may look like this:
<pre style="color:green;width:75%;background-color:#dcdcdc">pass
{
ambient 0.500000 0.500000 0.500000 0.000000
diffuse 0.640000 0.640000 0.640000 0.000000
specular 0.500000 0.500000 0.500000 0.000000 12.500000
emissive 0.000000 0.000000 0.000000 0.000000
...</pre>
If so, make sure the fourth parameter on ambient, diffuse, specular, and emissive is '1.00000', not '0.000000' (as shown in the 'material MyCube' example).

'''Actions.txt'''

This file controls what animations are exported, which frames of said animations, and which bones will be affected by the exported animations. Most often than not you will not need to use this functionality; your Actions.txt file could simply resemble this:
<pre style="color:green;width:25%;background-color:#dcdcdc">[Action]
Name=Open

[Action]
Name=Close

[End]</pre>

Other tags available for an [Action] include 'Start=', 'End=', 'ExportName=', and 'Group='.

Start and End will define the frames (in blender) that will be exported. ExportName will simply change the name of the Action on export (Useful if you have multiple versions of an animation but only need one exported).

A group is a special filter used to stop bones from affecting the exported animation. For example, if we want an aiming animation to only affect the upper body, or a blinking animation to only affect the character's eyelids.
Groups can either use the 'Include=' tag or 'Exclude=' tag.

As an example, a group which only affects the eyelids of the Clonk:
<pre style="color:green;width:25%;background-color:#dcdcdc">[Group]
Name=Eyelids
Include=eye_lid.R
Include=eye_lid.L
</pre>

This would make the exported animation only control the eye_lid.* bones and nothing else. Conversely, using the 'Exclude=' tag makes the animation use every bone excluding those defined. As an example:
<pre style="color:green;width:25%;background-color:#dcdcdc">
[Group]
Name=UpperBody
Exclude=skeleton_leg*
Exclude=skeleton_foot*
</pre>

Defining the group in an Action entry is fairly simple; just add the tag 'Group=' and enter the group's name. For example:
<pre style="color:green;width:25%;background-color:#dcdcdc">
[Action]
Name=CloseEyes
Group=Eyelids
</pre>

For an example of a finished Actions.txt file, [http://hg.openclonk.org/openclonk-resources/raw-file/9c271b749d31/models/Vehicles/catapult/Actions.txt this is the Catapult's].

== Sounds & Music ==
Any game is only half as good without proper sounds and music. If you played the titles of the old Clonk series, you will probably still suffer from the memories of the midi music from the last millenium, like "Pizza strings" or "On a razor blade". Anyway. So we need both people who are good at creating, editing (and searching) sound effects and talented people who can make music for OpenClonk.
There are some sound archives out there which have CC-licensed sound effects, also it can't hurt to ask the authors of one of the many many mods for commercial games if we are allowed to use their sounds under the terms of a CC-license (preferably CC-by).

Tutorial: Scenario Creation

2013-08-18T09:03:57Z

Andriel:

'''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 - ''Not yet available''

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.

Tutorial: Scenario Creation

2013-08-13T11:59:09Z

Andriel:

'''NOT YET FINISHED'''

'''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.

Now 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 - ''Not yet available''

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.

==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, creating a landscape is probably your first priority. In OpenClonk there are three ways to create a landscape, these are:
* Dynamic maps using Scenario.txt, which has the drawback of only having stretched and scaled sinusoidal landscapes. This is an obsolete feature and should rather not be used to create landscapes as they are boring.
* Static maps where a drawn landscape is stored in a Map.bmp file, where each pixel represents MapZoom pixels ingame. Check out this [[Tutorial: Dawing A Map|'''tutorial''']] if you want to learn how to draw and save static landscapes.
* 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.

Tutorial: Map Generator - The Basics

2013-08-13T11:58:02Z

Andriel:

In OpenClonk there are three ways to create a landscape, these are:
* Dynamic maps using Scenario.txt, which has the drawback of only having stretched and scaled sinusoidal landscapes.
* Static maps where a drawn landscape is stored in a Map.bmp file, where each pixel represents MapZoom pixels ingame.
* Generated maps using a Landscape.txt file where you can create dynamic landscapes with as many design parameters as a static landscape.
This tutorial covers the last method, which is called the map generator. Of course, this kind of dynamic landscape design is not as simple as moving bars, you need to have at least a basic understanding of [http://en.wikipedia.org/wiki/Set_theory sets] and [http://en.wikipedia.org/wiki/Logical_connective logical operators] and know how to create scenarios.

==Introduction & Features==

The landscape generator allows one to create dynamic and interesting landscapes. Dynamic in this context means that every time you start a scenario the landscape will look different. This is a great benefit opposed to static maps, depending of the type of scenario a dynamic map may be a must. On the other hand it is harder to create landscapes that look exactly the way you want it. The map generator can't simply be told to put in five nice looking gold chunks of some size into the ground.

Instead you have bit-layers which get a two dimensional 1-bit-texture. Then a material-texture-combination is assigned to that layer. Also you can create many sub layers inside a layer, which again can have sub layers and a material-texture-combination. Maybe it's easier to imagine as cutting several designs into pieces of paper and putting them behind each other, you'll get blank spots (where all papers have a hole), which will be like "Sky". Maybe you set the first layer to be some kind of an "Earth", that layer then has some shreds of paper on it that represent "Gold". But once you get to some really complicated combinations you'll see that that comparison is somewhat non-representative of the map-generator.

The approach taken in this tutorial is "learning by doing", as it should be the most fun and allows for a smooth introduction into the generator. Though this tutorial can't be completed by just anyone, basic knowledge of scenario creation is understood. The tutorial is divided up in parts, each part covers some theory explained in examples and ends with an exercise. The examples contain a snippet from Landscape.txt file together with some explanation and the generated map displayed on the right. But before starting of with the theory and some example landscapes we need a scenario to view our dynamic landscapes. You can create a scenario or download the scenario containing the first example here[TODO: file]. The map generator reads out the Landscape.txt file inside the scenario folder and generates the landscape at the start of the round. Either create a new Landscape.txt file or open the existing one in the downloaded example scenario. You can only view one example at a time, to view a new one clean the file and copy & paste the new example into your Landscape.txt file. Landscapes are best viewed in editor mode as you can scroll through the landscape.

The map generator also has its own [http://docs.openclonk.org/en/sdk/scenario/MapCreatorS2.html documentation]. Here all features of the generator can be found, and of course we will use it frequently in this sequence of tutorials. Furthermore we want to write readable generator code, so that we ourselves but most importantly others can profit from it. For this reason [[Map_Generator_Style_Guidelines|'''style guidelines''']] for map generator code have been compiled which should be followed within the OpenClonk project.

==Your First Landscape==

[[File:MapGenerator_ExampleFirstLandscape.png|200px|thumb|right|One big lake!]]
The map generator works with nesting, similar to HTML, XML and others. Therefore we start by creating the outer element, the <code>map</code>. This basically is a layer that spans the whole landscape of a scenario. So without further ado, here is your first example landscape.
// ''My first dynamic landscape!''
map ExampleFirstLandscape {
mat=Water; tex=water;
};
As you might have noticed this simply fills the whole map with water, but how does it work. The first line is a comment, everything after a // will be ignored until a new line occurs. Also multi line comments are possible, anything after a /* will be ignored completely until a */ is found. The third line has the keyword <code>map</code>. ''Example1'' is the name of that map. The actual definition is inside the brackets { }. To close the definition you also need to put a semicolon behind the closing bracket.

In this example we define the material (keyword <code>mat</code>) and the texture (keyword <code>tex</code>) of the map. This map will simply be completely filled with ''Water'' and that water will have the texture ''water''. Valid materials and textures can be found in the TexMap.txt file in the Material.c4g folder, which is explained in the [http://docs.openclonk.org/en/sdk/material/index.html material documentation].

==Layers==

[[File:MapGenerator_ExampleOneLayer.png|200px|thumb|right|A golden layer submerged in water.]]
That first map is somewhat limited. Maybe you could do a submarine battle in it, but that's about it. So let's add a new layer, new layers can be created with <code>overlay</code>.
// ''Introduced a golden layer.''
map ExampleLayers {
mat=Water; tex=water;
overlay {
mat=Gold; tex=gold;
x=10; y=10; wdt=80; hgt=80;
};
};
We added a sublayer to the map layer and that sublayer will be filled with the material ''Gold''. Furthermore we told the layer to be limited to the area that starts at <code>x, y</code> (in percent of the upper layer, the map) and to a height and width of 80% of the upper layer (the map).

Notice that changing the map size in the Scenario.txt will automatically fit your map to the new size and the percentages of the sublayer will also automatically scale themselves to the new values.

==Combining Layers==

[[File:MapGenerator_ExampleCombinedLayers.png|200px|thumb|right|Combined rock and gold layers.]]
You can combine layers in multiple ways. Low and behold:
// ''Gold, rock and set theory.''
map ExampleCombinedLayers {
mat=Water; tex=water;
overlay {
mat=Gold; tex=gold;
x=10; y=10; wdt=80; hgt=80;
overlay {
x=10; y=10; wdt=50; hgt=50;
} ^ overlay {
mat=Rock; tex=rock;
x=40; y=40; wdt=50; hgt=50;
};
};
};
Here begins the fun. The first layer (the gold layer) has got two sublayers which were combined by a logical operator - the ^. Since both layers are inside that gold-layer they will not affect anything outside of that layer. Any coordinates or percentage values are relative to that outer layer.

The two inner layers are combined by an operator. The last layer defines what material and texture will be used for that layer combination. You could also add more operators and layers, the operators will then be handled from left to right. Layers can be combined and sub-layered (meaning put into another layer) in any way you want. There are three logical operators:
* ^ is the XOR operator, that means anything covered by both layers will not be drawn, anything else covered by one of the layers will be drawn. This is shown in the example, the grey area in the top left corner is part of the first layer, the one in the lower left corner is the part of the second layer. The center is the part covered by both layers, which is not drawn due to the ^ operator.
* & is the AND operator, which draws any overlapping parts of the two layers.
* | is the OR operator, which draws anything any of the two layers would draw on their own.
As an exercise you can replace the XOR operator with the AND or the OR operator and see what happens. To be able to work with the landscape generator basic understanding of set theory and logical operators is quite handy.

==Exercise: Set Theory==

[[File:MapGenerator_ExerciseSetTheory.png|200px|thumb|right|Exercise: Create this landscape.]]
Since basic understanding of sets is required it will be tested in the this exercise. Try to construct a 5 by 5 checkers board out of gold and rock, looking like the landscape in the figure. There are multiple solutions, but try to use as little overlays as possible.

[TODO: solution as some sort of spoiler]

// ''Checkers board out of gold and rock.''
map ExerciseSetTheory {
mat=Rock; tex=rock;
overlay {
x=20; y=0; wdt=20; hgt=100;
} ^ overlay {
x=60; y=0; wdt=20; hgt=100;
} ^ overlay {
x=0; y=20; wdt=100; hgt=20;
} ^ overlay {
mat=Gold; tex=gold;
x=0; y=60; wdt=100; hgt=20;
};
};

==Summary==

Of course, this tutorial only covered the most important basics of dynamic landscapes. The following tutorials will require full knowledge about this one. If you have problems with the things covered by this tutorial it is most advisable to play around with operators and sublayers a little more.

The next part of this tutorial about algorithms and transformations is [[Tutorial: Map Generator - Algorithms & Transformations|'''here''']].

[[Category:Map Generator Tutorials]]

File:TUT-SCEN Commandline.png

2013-08-13T10:31:48Z

Andriel:

File:TUT-SCEN Log.png

2013-08-13T10:30:17Z

Andriel:

File:TUT-SCEN BrushTools.png

2013-08-13T10:23:00Z

Andriel:

File:TUT-SCEN LandscapeBrush.png

2013-08-13T10:20:39Z

Andriel:

File:TUT-SCEN EditingCursor.png

2013-08-13T10:19:13Z

Andriel:

File:TUT-SCEN GameCursor.png

2013-08-13T10:18:07Z

Andriel:

File:TUT-SCEN PauseResume.png

2013-08-13T09:37:48Z

Andriel:

File:TUT-SCEN EMStart.png

2013-08-13T09:28:50Z

Andriel:

File:StartButton.png

2013-08-13T08:02:33Z

Andriel:

File:Scentxt.png

2013-08-13T07:58:52Z

Andriel:

File:SetName.png

2013-08-13T07:56:53Z

Andriel: