OpenClonk Wiki - User contributions [en]

Style Guidelines

2019-06-17T17:03:03Z

Marky: /* Data Types */

This document specifies the preferred source code style of files inside the
OpenClonk source tree. Some of the style rules are also stated implicitly
inside the examples.

=== All-encompassing Guidelines ===
==== Line endings ====
Use a single line feed character (ASCII 10) for line endings.

==== Indentation ====
Indent your code with tabs (ASCII 9). Use space (ASCII 32) for all other
formatting.

==== Braces ====
Braces are on their own line, on the same level of indentation as the
structure they belong to. You may add braces around single statements in
<tt>if</tt> statements if the first block or an <tt>else</tt> block has them.

if (count < 10)
{
printf("Too few thingies!");
AddMore();
}
else
{
printf("We have enough");
}

==== Spaces ====
Function names are not followed by space. Commas are. No space follows opening
brackets ("[") or parentheses ("("). Also no space preceeds closing brackets
("]") or parentheses (")"), or commas. "::", "->", "." and unary operators do not
require spaces. Other binary operators do.

Keywords (<tt>while</tt>, <tt>for</tt> etc.) are followed by a space.

==== Parentheses ====
Do not use parentheses unless they are required for precedence or the code
gets confusing without them. Remember other people may have confusion
thresholds different from you.

==== Control Structures ====
Control structures with a single statements are written without braces. If the
statement spans multiple lines, you may add braces for readability. Structures
without a statement contain a comment denoting this.

while (*dest++ = *src++)
/* empty */;

Cascades in a <tt>switch</tt> statement are marked by a FALLTHROUGH
comment. Code that cannot be reached has an assertion. <tt>case</tt> elements
are not indented.

switch (foo)
{
case FOO_HEX:
accept_hex = true;
// FALLTHROUGH
case FOO_DEC:
accept_num = true;
break;
default:
assert(!"Invalid foo value");
// Do something meaningful here anyway, if possible;
// try to not leave the program in an ill-defined state.
}

==== Comments ====
// Single-line comments look like this

// Multi-line comments look like this. Using C++-style comments
// helps if you need to comment out large pieces of code later, or if the length of
// the comment changes over time. Of course you could still use #if 0 ... #endif
// to achieve that.

/* You may also write multi-line comments like this. Make sure you write enough
text to warrant a multi-line comment. Also be sure to write in full sentences. */

==== Type Casting ====
Do not use C-style or function style casts. Use a template cast instead.

=== Source File Layout ===
==== Copyright Header ====
Every source file begins with a copyright header. If you make significant
changes to the code, you may (but are not required to) add your name to the
list of copyright holders in <tt>COPYING</tt>. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2009-2014, The OpenClonk Team and contributors
*
* Other legalese goes here, but has been omitted for brevity. See an
* existing file for a template.
*/

The copyright header is followed by an empty line. Put a comment explaining
the purpose of the file next, and leave another blank line after this.

==== Inclusion Guards ====
If you are writing a header file, use #include guards. If your file is called
''C4Foo.h'', your guard should be <tt>INC_''C4Foo''</tt>.

#ifndef INC_C4Foo
#define INC_C4Foo
class C4Foo;
#endif

''TODO: Precompiled headers.''

==== #include Directives ====
Include local headers first. Put the filename in double quotes, and use
forward slashes as directory separators.

#include "Standard.h"
#include "StdBuf.h"

Leave a blank line before system headers. Use angle brackets to include these,
and sort them alphabetically.

#include <map>
#include <vector>

=== Declarations ===
==== Preprocessor Macros ====
Do not <tt>#define</tt> values in headers. Use <tt>const</tt> instead, or
<tt>enum</tt> if you are declaring an enumeration.

Do not <tt>#define</tt> inline functions either, use <tt>inline</tt>. If your
functions need to work on multiple data types, overload the function or write
a <tt>template</tt>.

If, despite of the above, you still need to write a macro, use an all-uppercase
name. If your macro contains a compound statement, enclose it in a <tt>do</tt>
loop to allow its use in <tt>if</tt> statements. A terminating semicolon
should be provided at the place of invocation. This makes parsing the source
easier for pretty-printers and editors. Consider undefining your macro when
you are done using it.

#define FOO(a, b) do { \
bar += (a); \
bar /= (b); \
} while(0)

==== Data Types ====
Do not use the Win32 style integer declarations <tt>DWORD</tt> and
<tt>BOOL</tt> except when interfacing with the Windows API. If you need a guarantee about the size of your variables, use
the C99 types <tt>int''XX''_t</tt> and <tt>uint''XX''_t</tt>. If you don't
need that guarantee, use <tt>int</tt>. If you need a variable that is large
enough to store a pointer on your current platform, use <tt>intptr_t</tt>.

If you come across code that still uses Win32 types, consider changing it if
you are working on code in the vicinity. Don't commit changes that only
consist of replacing <tt>DWORD</tt> by <tt>uint32_t</tt>.

When declaring a pointer, put a space in front of the asterisk, and none
after. This saves some confusion when declaring multiple variables at once.
The same goes for references.

Assign variable values in separate lines, because this improves readability. Do not assign variable values and declare other variables of the same type in the same line, because this reduces readability.

int *foo, *bar;
char *Qux(const char *quux);
int a = 1;
int b = 2;
int c, d, e;

==== Functions ====
Functions that are not used outside of the containing file are placed inside
of an anonymous namespace.

namespace
{
int Frobnicate(const char *foo);
}

Functions that are used across multiple files are prototyped inside a common
header. The prototypes should be grouped where appropriate, and ordered
logically or, failing that, alphabetically.

Function and class names begin with a capital letter, and use camel casing. If
you need to embed acronyms inside the name, pretend the acronym was all lower
case. Member variables use the same convention, but begin with a lower case
letter. Do not use hungarian prefixes.

XmlDocument *ParseXmlFile(const char *file);

When passing arguments that may be changed by the called function, pass them
as pointers. This makes it obvious that they may be changed. Use constant
references for all other parameters, unless they are a primitive type.

==== Class Members ====
No class member variable should be declared <tt>public</tt> unless necessary.
Consider using <tt>GetFoo</tt> and <tt>SetFoo</tt> accessors. If you want to
declare a compound data type that allows direct access to its members, use
<tt>struct</tt>. Do not add more functions than constructors, destructors, and
assignment operators to <tt>struct</tt>s.

Mark all class members that do not change the visible state of the object
<tt>const</tt>. If you need to modify internal state that is not visible from
outside of the class, mark the state variable <tt>mutable</tt>.

Building with Linux

2018-12-19T22:18:49Z

Marky: Moved the "in short version" to the top.

= In short =

If you prefer doing things on the command line, this is a short alternate path to getting a working build (tested on Ubuntu 17.10, the use of <kbd>ninja</kbd> is optional):
<code>
# apt-get install git cmake build-essential libpng-dev libjpeg-dev ninja-build \
libfreetype6-dev libglew-dev libreadline-dev libsdl2-dev libqt5widgets5 \
qtbase5-dev libalut-dev libvorbis-dev libopenal-dev libdw-dev
$ git clone https://github.com/openclonk/openclonk && cd openclonk && cmake . -GNinja && ninja openclonk
</code>

If you did it this way you can skip the rest of the tutorial. Otherwise, if you prefer using GUIs, have a look at the rest of this page.

= Get the sources =

To get the sources, you need to clone our git repository. Enter the command

$ git clone git://git.openclonk.org/openclonk.git

''OpenClonk team members:'' Use "ssh://git@git.openclonk.org/openclonk.git" instead.

Congratulations, you now have the bleeding edge of OpenClonk development on your hard drive! There is 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 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 the Compiler Tools ==

Before you can start building an executable, you will need some more tools:
* make, gcc for building (this may be part of your Linux distribution already)

== 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. Simply get the following packages (they may have different names on your distribution):
* libsdl2-dev
* libopenal-dev
* libminiupnpc-dev
* libgl1-mesa-dev (will most likely be already installed after you got libsdl2-dev)
* libxrandr-dev (will most likely be installed already after you got libsdl2-dev)
* qtbase5-dev
* libfreetype6-dev
* libjpeg-dev
* libpng-dev
* libglew-dev

== 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 you need 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, and having all those project files next to each other would become a problem in the long run.

Get the cmake package.

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:cmake-gui-linux_2.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, most likely the "Unix Makefile" will be the one that you need.

[[File:cmake-gui-linux.png]]

If you get some error messages (in red), you're probably missing some dependencies. CMake will tell you which ones are missing, and you just need to install those, too.

Repeat the "Configure" step, until CMake no longer gives you error messages. It may still show you some missing paths, but that shouldn't affect you:

The last step is to click the "Generate" button. If you can click "Generate" and you do not get an error message, you're good.

== Your First Build ==

Okay, now we have everything needed to make OpenClonk run for the first time. Open a terminal in the build directory that you configured in cmake, where the makefiles are located now. Enter the command

make -j$(nproc)

You could simply call make, but it will take a little longer to compile then: Instead, we start $(nproc) parallel jobs, where $(nproc) will be substituted by the amount of threads your processor can handle.

Build OpenClonk

2018-12-19T21:36:38Z

Marky: Added link to the "building with linux" page.

Windows users can check out these tutorials:

[[Building_with_Windows|Building with Visual C++]]

[[Building_with_MinGW|Building with MinGW]]

[[Building_with_Linux|Building with Linux]]

Otherwise, here is how you can build OpenClonk in three easy steps:

== 1. Get the source code ==
See [[Git Workflow]]

== 2. Install Build tools and libraries ==
OpenClonk has a couple of dependencies on other libraries. Please refer to the Readme.*.txt in the freshly checked out source tree.
: For Windows, we provide prebuilt packages of libraries:
:* [http://www.openclonk.org/openclonk-deps-vc90.zip for Microsoft C++ users]
:* [http://www.openclonk.org/mingwlibs2.zip for GNU Compiler Collection users]
== 3. Compile the game ==
Again, the Readme.*.txt has the details, as this step is highly platform dependent. But it's also comparatively uncomplicated: If you installed everything that's listed, and it doesn't build, you found a bug.

= Building a debug engine =

The Clonk source code contains lots of little pieces of code that check that the engine works correctly. They can often help finding or preventing bugs, but slow the game down, so they are skipped in normal builds. To enable them, pass -DCMAKE_BUILD_TYPE=Debug to cmake, choose the Debug build in the IDE, or pass --enable-debug to configure. If you are using the GNU Compiler Collection, you can also enable [http://gcc.gnu.org/onlinedocs/libstdc++/manual/debug_mode.html the libstdc++ debug mode] by passing CPPFLAGS=-D_GLIBCXX_DEBUG to configure.

Building with Linux

2017-07-09T19:46:21Z

Marky: Created page with "= Get the sources = Let's just assume you already have the sources :p = Get it to Compile = This is nice, but we are interested in seeing the game run, aren't we? For this,..."

= Get the sources =

Let's just assume you already have the sources :p

= 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 the Compiler Tools ==

Before you can start building an executable, you will need some more tools:
* make, gcc for building (this may be part of your Linux distribution already)

== 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. Simply get the following packages:
* libsdl2-dev
* libopenal-dev
* libminiupnpc-dev
* libgl1-mesa-dev (will most likely be already installed after you got libsdl2-dev)
* libxrandr-dev (will most likely be installed already after you got libsdl2-dev)
* qtbase5-dev
* libfreetype6-dev
* libjpeg-dev
* libglew-dev

== 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 you need 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, and having all those project files next to each other would become a problem in the long run.

Get the cmake package.

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, most likely the "Unix Makefile" will be the one that you need.

[[File:build_windows_cmake4.png]]

If you get some error messages (in red), you're probably missing some dependencies. Cmake will tell you which ones are missing, and you just need to install those, too.

Repeat the "Configure" step, until Cmake no longer gives you error messages. It may still show you some missing paths, but that shouldn't affect you:

The last step is to click the "Generate" button. If you can click "Generate" and you do not get an error message, you're good.

== Your First Build ==

Okay, now we have everything needed to make OpenClonk run for the first time. Open a terminal in the build directory that you configured in cmake, where the makefiles are located now. Enter the command

make -j$(nproc)

You could simply call make, but it will take a little longer to compile then: Instead, we start $(nproc) parallel jobs, where $(nproc) will be substituted by the amount of threads your processor can handle.

Development

2017-07-09T19:29:06Z

Marky:

__NOTOC__
OpenClonk is an open project. That means it depends on people coming in and helping out. People just like you! This page should give you an idea what you could do in order to get involved.

=== Use Development Snapshots ===

OpenClonk is continously in development. The "current" version can change daily! If you want to follow the development, it is a good idea to make sure you are able to run development versions. You will not need to build them yourself - just use the development snapshots linked below and you should be ready to go.

* Development Snapshots - [http://www.openclonk.org/nightly-builds/ www.openclonk.org/nightly-builds/]
* Blog - [http://blog.openclonk.org blog.openclonk.org]
* Changelog - [http://git.openclonk.org/openclonk.git git.openclonk.org/openclonk.git]
* Browse source - [http://git.openclonk.org/openclonk.git/tree/refs/heads/master git.openclonk.org/openclonk.git/tree/refs/heads/master]

=== Report Bugs ===

We cannot possibly account for every possible configuration out there. If you see something that's wrong, we would really like to know about it. Especially if you are willing to actively work with us in finding a solution for the problem.

Here's how you can reach us:

* IRC - [irc://irc.euirc.net/openclonk-dev #openclonk-dev] on irc.euirc.net (Problems connecting? Use irc.ham.de.euirc.net)
* Bugtracker - [http://bugs.openclonk.org bugs.openclonk.org]
* Forum - [http://forum.openclonk.org forum.openclonk.org]

=== Contribute Scripts or Game Content ===

Just like Clonk Rage before, most things in OpenClonk can be changed without touching the engine. Instead, we rely on a script language and a flexible game content system to make up our game content. This means that you can get involved easily - without having to learn C++ first! Traditionally, developing own objects and scenarios and sharing them with others has been how pretty much all of today's developers started out.

* Developer Documentation [http://docs.openclonk.org/en/sdk/ docs.openclonk.org/en/sdk/]
* Forum - [http://forum.openclonk.org forum.openclonk.org]
* Style Guide - [http://wiki.openclonk.org/w/C4Script_Style_Guidelines wiki.openclonk.org/w/C4Script_Style_Guidelines]
* Contribute changes - [[Git Workflow]]
* [http://crucible.openclonk.org Crucible] for code review
* Are you a sound artist? Here is a list of [[missing sounds]] you can contribute.
* Game content external to the main game: [[List Of Community Creations]]

=== Build OpenClonk Yourself ===

When delving deeper into OpenClonk, you will often find yourself in the situation that you need a closer look at what makes OpenClonk tick internally. At that point, it is a good idea to assume the perspective of developers - get the source code and build it in your own development environment.

* Tutorial for Windows - [http://wiki.openclonk.org/w/Building_with_Windows wiki.openclonk.org/w/Building_with_Windows]
* Tutorial for Linux - [http://wiki.openclonk.org/w/Building_with_Linux wiki.openclonk.org/w/Building_with_Linux]
* General instructions - [http://wiki.openclonk.org/w/Build_OpenClonk wiki.openclonk.org/w/Build_OpenClonk]
* Git Workflow Guide - [http://wiki.openclonk.org/w/Git_Workflow wiki.openclonk.org/w/Git_Workflow]
* Git Repository - [http://git.openclonk.org/openclonk.git git.openclonk.org/openclonk.git]
* Source Code Structure - [http://wiki.openclonk.org/w/Source_code_structure wiki.openclonk.org/w/Source_code_structure]

=== Hack the OpenClonk Engine ===

Maybe you already are well-versed in C++ and want to help out actually diagnosing problems? Or - even better - have your own ideas on engine improvements? We are always glad to look at patches.

* Wondering where to start? - [[GSoC2011Ideas|Ideas page]]
* Debugging synchronization losses - [http://wiki.openclonk.org/w/Sync_losses wiki.openclonk.org/w/Sync_Losses]
* Style Guide - [http://wiki.openclonk.org/w/Style_Guidelines wiki.openclonk.org/w/Style_Guidelines]
* Forum, developers' corner - [http://forum.openclonk.org/board_show.pl?bid=5 forum.openclonk.org]
* Contribute changes - [[Git Workflow]]

=== Internal Links ===

* [[Release Steps]]
* [http://londeroth.org/~ck/oc-release/oc-release.cgi The release button]

=== Legal Stuff ===

OpenClonk uses the ISC license for code (engine and script) and CC-by for most other media. Read more about the [[License | license stuff]] here.

List Of Community Creations

2017-06-24T14:37:05Z

Marky: Added the Hazard pack

Below a list of all scenarios and objects developed by the OpenClonk community and which do not appear in the main game. Download links to the latest version are provided if available as well as links to a repository. The OC Version indicates what version of OC is needed to play this creation.

{| border="1" class="wikitable"
|-
! Type
! Name
! DL
! Repository
! OC Version
! Main author(s)
|-
! [[File:Ocf.png|text-bottom|x18px|link=]]
! [http://wiki.openclonk.org/w/Base_Melees Base Melees]
!
! [https://github.com/MDT-Maikel/basemelees GitHub]
! [http://www.openclonk.org/nightly-builds/ snapshot]
! Maikel
|-
! [[File:Ocs.png|text-bottom|x18px|link=]]
! ClonkFest
!
! [https://github.com/clonkspot/ClonkFest.ocs GitHub]
! [http://www.openclonk.org/nightly-builds/ snapshot]
! Sven2
|-
! [[File:Ocf.png|text-bottom|x18px|link=]]
! Hazard
!
! [https://github.com/gitMarky/Hazard GitHub]
! [http://www.openclonk.org/nightly-builds/ snapshot]
! Marky
|-
! [[File:Ocf.png|text-bottom|x18px|link=]]
! [http://forum.openclonk.org/topic_show.pl?tid=3268 Knüppeln]
!
! [https://github.com/TheThow/OpenClonk-Stuff GitHub]
! [http://www.openclonk.org/nightly-builds/ snapshot]
! KKenny
|-
! [[File:Ocf.png|text-bottom|x18px|link=]]
! [http://forum.openclonk.org/topic_show.pl?tid=2817 Lands of Mystery]
!
!
!
! Sayned
|-
! [[File:Ocs.png|text-bottom|x18px|link=]]
! [http://wiki.openclonk.org/w/Tower_of_Despair Tower of Despair]
! [[File:Download.png|text-bottom|x18px|link=https://mwf-data.clonkspot.org/60/14860/OCTowerV0.5.ocs]]
! [https://github.com/MDT-Maikel/OCTower GitHub]
! [http://www.openclonk.org/nightly-builds/ snapshot]
! Maikel, Sven2
|-
! [[File:Ocd.png|text-bottom|x18px|link=]]
! Some object
!
!
!
!
|-
! [[File:Ocs.png|text-bottom|x18px|link=]]
! [http://forum.openclonk.org/topic_show.pl?pid=32527#pid32527 Winter food]
!
!
! [http://www.openclonk.org/nightly-builds/ snapshot]
! Armin
|-
|}

Please complete this list by adding your own creations. The list is sorted alphabetically according to the name of the creation.

C4Script Documentation

2017-06-24T14:35:26Z

Marky: Added list of community creations in "Further links"

__NOTOC__
[[File:C4Script.png|right|frame]]
Like the previous Clonk titles, OpenClonk offers countless possibilites to create your own scenarios, objects and campaigns. Since [http://www.clonk.de/classics.php?lng=en Clonk 4], one of Clonk's most remarkable features has been it's extensibility. The complete content is scripted in C4Script, Clonk's own powerful scripting language, has been developed further since 1998. Now, it feels pretty much like a typical C-style scripting language. If you know other programming languages, you will have no problem to familarize yourself with C4Script and if you never programmed before, it can be a good introduction and practice to programming.

You may want to develop based on the latest game data there is. See the [http://www.openclonk.org/nightly-builds/ nightly builds] page for the most current builds.

== [http://docs.openclonk.org/en/sdk/ OpenClonk Documentation] ==

[[File:Cpem.gif|left|link=http://docs.openclonk.org/en/sdk/]] The [http://docs.openclonk.org/en/sdk/ documentation] is a complete reference for everything you need to know about the script language C4Script and its data structures, how the the game data is organized and about the APIs for e.g. dynamic landscape generation, using the particle or the effect system.
Note that the documentation is also still [http://docs.openclonk.org/de/sdk/ available in German], however it lacks maintenance, so always refer to the English version for recent stuff.

== [http://wiki.openclonk.org/w/Developing_Content_with_Eclipse C4 Development Toolkit] ==

[[File:C4dt.png|left|52px|link=http://wiki.openclonk.org/w/Developing_Content_with_Eclipse]] The [http://wiki.openclonk.org/w/Developing_Content_with_Eclipse C4 Development Toolkit], or short C4DT, is a plugin for Eclipse. Using Eclipse with C4DT for Clonk development makes it very comfortable as the editor offers many useful features for editing and debugging scripts you might know from other IDEs.

== Tutorials series ==
* [[Tutorial: Scenario Creation]]
* [[Tutorial: Map Generator - The Basics]]

== Further links ==
* [[Artists Guide|Graphics]] - Render and texture 3D-models
* [[Artists_Guide#Sounds_.26_Music|Sounds and music]] - Include sound effects and music into the game
* [[C4Script Style Guidelines]]
* [http://forum.openclonk.org/board_show.pl?bid=7 Scenario & Object Development forum]
* [[Git Workflow]] - How to use our repository
* [[Developers Guide]] - For engine developers
* [[List Of Community Creations]] - List of community creations