OpenClonk Wiki - User contributions [en]

Style Guidelines

2014-11-23T23:01:20Z

Isilkor: /* Line endings */ Mercurial is history

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.

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2014-11-23T23:00:22Z

Isilkor: /* Copyright Header */ Authors have been moved to the COPYING file

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. Mercurial provides
an extension named ''win32text'' you can use to auto-convert files from your
OS's native format to single LF and vice-versa.

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

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2013-11-11T14:52:19Z

Isilkor: /* Data Types */ Win32 typedefs are fine when interfacing with WinAPI

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. Mercurial provides
an extension named ''win32text'' you can use to auto-convert files from your
OS's native format to single LF and vice-versa.

==== 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Code Reviews

2013-10-27T16:13:24Z

Isilkor: Add short "How to Crucible" overview

The OpenClonk project is using [https://www.atlassian.com/software/crucible/overview Atlassian Crucible] to conduct code reviews. Code reviews help to improve the quality of our source code by having more than one set of eyes look at it.

==Request a Code Review==
To start a code review, either as a reviewer or a reviewee, [http://crucible.openclonk.org/ log into Crucible] and click the ''Create Review'' button in your toolbar. You will be asked to select a project for the review; use the one that most closely fits the patch you want to review. If no project fits well, you can use the OpenClonk project (OC) as a fall-back choice. Afterwards, click the ''Create Review'' button.

Once you have created the review in a specific project, you will have to add content to the review. [[#Review an un-pushed patch|If your code has not yet been pushed, you will have to generate a patch file and upload that.]] [[#Review a pushed changeset|If the code is already contained in the master repository, you can select the changeset directly.]]

===Review an un-pushed patch===
To review a patch that has not yet been pushed to the master repository, use the ''Pre-commit'' link. You will be asked to upload or paste a patch file. How to generate this file differs depending on the Git UI you're using; for the command line UI, it works as follows:

If you have staged, but not committed your changes:
:<tt>$ git diff --cached > some-file-name.patch</tt>

If you have already committed your changes:
:<tt>$ git diff HEAD~ > some-file-name.patch</tt>

This will emit a patch into the file <tt>some-file-name.patch</tt>. This is the file you will want to upload to or paste into Crucible.

:'''Note:''' Do not use the git format-patch command, as it will generate a file in mbox format instead of a plain patch.

:'''Note:''' Crucible also offers a python script that promises easier review creation. Unfortunately it currently suffers from a bug that occasionally introduces a spurious whitespace change. As such we recommend you do not use it.

Once uploaded, Crucible will try to anchor your patch to the OpenClonk repository. This will enable people reviewing the patch to see the complete source code of the files instead of just the changes. If this fails, it may mean that the patch does not cleanly apply to the most recent changeset on the master branch.

If the patch successfully anchored to the repository, or you want to proceed regardless, click the ''Finish upload'' button.

===Review a pushed changeset===
To review a changeset that has already been pushed to the master repository, use the ''Browse Changesets'' link. You will be shown a list of your most recent changesets. Check the revision (or revisions) that you want to have reviewed.

===Give the review a title===
Once you added the content to review, you should give the review a title so people know what to expect. To do this, click the ''Edit Details'' button.
If you added a changeset, the title will already be filled in with the title of the changeset. Otherwise, you'll have to enter one yourself. If you added a changeset, you can also change the author role of the review to the author of the changeset, so they know their code is being reviewed.

Then, add some reviewers. If you are trying to review somebody else's code, this should include yourself. If you don't know who should review the code, you can have Crucible suggest somebody; you can also hop in the IRC channel and ask if somebody wants to do the review, or just leave it empty so people can join later. Make sure you leave the ''Allow anyone to join'' checkbox checked.

Once that's all done, you can stop drafting the review and start it. To do that, click the ''Start Review'' button. If you did not specify any reviewers, you will get a warning message telling you so; confirm that you meant to do this and start handing out the review link. If you did specify reviewers, the people you chose will get an e-mail notification.

==Mail settings==
By default, Crucible will send members of a review an e-mail notification about pretty much everything that happens. If you do not want to get your mailbox filled up, you should change your notification settings.

To do that, click your profile picture in the top right corner of the screen and choose ''Profile settings''. In there, go to the Review settings and switch some or all of the events to ''No'' or ''Batch''. ''Batch'' will collect changes for about 30 minutes and then send an e-mail containing all changes that happened in the meantime.

Building with Windows

2013-03-31T22:11:31Z

Isilkor: /* Get Dependencies */ How about I get the URLs right this time?

= 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 its contents into the same directory you put all the other files (but keep the "deps" folder intact).

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

Building with Windows

2013-03-31T21:48:10Z

Isilkor: /* Get Dependencies */ Update packages for VS2012

= 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-deps-vc110-i386.zip the x86 package]; for a 64-bit binary, use [http://www.nosebud.de/~nh/openclonk-deps-vc110-amd64.zip the amd64 package]. Then unpack its contents into the same directory you put all the other files (but keep the "deps" folder intact).

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

File:Build windows build1.png

2013-03-31T21:37:33Z

Isilkor: uploaded a new version of "File:Build windows build1.png": Update to MSVS 2012

File:Build windows outofdate.png

2013-03-31T21:36:16Z

Isilkor:

Building with Windows

2013-03-31T21:35:57Z

Isilkor: /* Your First Build */ Update for 2012

= 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 try to search and download all those libraries by hand, but that would be pretty boring. Instead, just download [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

Unpack both directories into the same path you put all the other files. Don't worry, nothing will get overwritten in "planet".

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

File:Build windows build3.png

2013-03-31T21:30:39Z

Isilkor: uploaded a new version of "File:Build windows build3.png": Update to VS2012 UI

File:Build windows build2.png

2013-03-31T21:27:46Z

Isilkor: uploaded a new version of "File:Build windows build2.png": Now with more Visual Studio 2012

File:Build windows cmake4.png

2013-03-31T21:20:48Z

Isilkor: uploaded a new version of "File:Build windows cmake4.png"

Building with Windows

2013-03-31T21:20:20Z

Isilkor: /* Get CMake */ Update for 2012

= 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 try to search and download all those libraries by hand, but that would be pretty boring. Instead, just download [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

Unpack both directories into the same path you put all the other files. Don't worry, nothing will get overwritten in "planet".

== 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 "clonk" from the list, right-click and select "Set as Start-Up project"

[[File:build_windows_build3.png]]

Now select "Build Solution" from the "Build" menu (or just press F7). No, I don't know what "solution" means. Drink a cup of coffee or two while you wait for the compiler to do its job.

Eventually, you will arrive at this screen.

[[File:build_windows_build4.png]]

Nevertheless, you can now select "Start Debugging" from the "Debug" menu (or just press F5) and should be greeted by the startup screen of a fresh OpenClonk build!

[[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

2013-03-31T21:18:44Z

Isilkor: /* Get Microsoft Visual Studio */ Update for 2012

= 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 try to search and download all those libraries by hand, but that would be pretty boring. Instead, just download [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

Unpack both directories into the same path you put all the other files. Don't worry, nothing will get overwritten in "planet".

== 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, for example "Visual Studio 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[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 "clonk" from the list, right-click and select "Set as Start-Up project"

[[File:build_windows_build3.png]]

Now select "Build Solution" from the "Build" menu (or just press F7). No, I don't know what "solution" means. Drink a cup of coffee or two while you wait for the compiler to do its job.

Eventually, you will arrive at this screen.

[[File:build_windows_build4.png]]

Nevertheless, you can now select "Start Debugging" from the "Debug" menu (or just press F5) and should be greeted by the startup screen of a fresh OpenClonk build!

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

File:Msvc11 web download.png

2013-03-31T21:17:32Z

Isilkor:

Building with Windows

2013-03-31T20:09:31Z

Isilkor: DirectX is horribly broken and obtaining FMOD3 isn't trivial anymore

= 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/express/vc/#webInstall Visual Studio C++ 2010]. Follow that link, click yourself through the ever-shifting Microsoft website to the 2010 Express Edition, until you arrive at something that ideally looks like follows:

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

The installer will offer us a lot of stuff we don't really need for OpenClonk. You should uncheck it to make the installation faster.

[[File:build_windows_msvc2.png]]

You will most likely stare at the following screen for a bit. It won't take that long, and for me didn't even restart the computer like it suggested it would.

[[File:build_windows_msvc3.png]]

=== In case you use the Express Edition ===
Since clonk can currently only be compiled for 32 bit, and the 2010 Express Edition doesn't allow 32 bit compilation, you will need additional files

1. [http://www.microsoft.com/en-us/download/details.aspx?id=8279 Windows SDK 7.1]

2. [http://www.microsoft.com/en-us/download/details.aspx?id=4422 Compiler Update for the Windows SDK 7.1]

3. [http://www.microsoft.com/en-us/download/confirmation.aspx?id=23691 Visual Studio 2010 Service Pack 1]

== 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 try to search and download all those libraries by hand, but that would be pretty boring. Instead, just download [http://www.openclonk.org/openclonk-deps-vc90.zip this package] that contains everything you need to build Clonk.

[[File:build_windows_deps.png]]

Unpack both directories into the same path you put all the other files. Don't worry, nothing will get overwritten in "planet".

== 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, for example "Visual Studio 10". Do ''not'' pick the Win64 option, as the precompiled libraries are 32 bit.

[[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 "clonk" from the list, right-click and select "Set as Start-Up project"

[[File:build_windows_build3.png]]

Now select "Build Solution" from the "Build" menu (or just press F7). No, I don't know what "solution" means. Drink a cup of coffee or two while you wait for the compiler to do its job.

Eventually, you will arrive at this screen.

[[File:build_windows_build4.png]]

Nevertheless, you can now select "Start Debugging" from the "Debug" menu (or just press F5) and should be greeted by the startup screen of a fresh OpenClonk build!

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

Development

2012-06-21T15:16:41Z

Isilkor: Changed repository URL

__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://hg.openclonk.org/openclonk/ hg.openclonk.org/openclonk/]
* Browse source - [http://hg.openclonk.org/openclonk/file/ hg.openclonk.org/openclonk/file/]

=== 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]

=== 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]
* General instructions - [http://wiki.openclonk.org/w/Build_OpenClonk wiki.openclonk.org/w/Build_OpenClonk]
* Mercurial Guide - [http://wiki.openclonk.org/w/Mercurial_Guide wiki.openclonk.org/w/Mercurial_Guide]
* Mercurial Repository - [http://hg.openclonk.org/openclonk/ hg.openclonk.org/openclonk/]
* 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]

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

Style Guidelines

2010-03-26T19:19:29Z

Isilkor: . and -> aren't enclosed by spaces

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. Mercurial provides
an extension named ''win32text'' you can use to auto-convert files from your
OS's native format to single LF and vice-versa.

==== 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 (")"). Unary operators do not require spaces. Binary
operators (except for the member access operators "." and "->") 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

DevelopersGuide

2010-02-27T15:58:13Z

Isilkor: moved DevelopersGuide to Developers Guide: Spacey titles preferred

#REDIRECT [[Developers Guide]]

Developers Guide

2010-02-27T15:58:13Z

Isilkor: moved DevelopersGuide to Developers Guide: Spacey titles preferred

== Build OpenClonk ==

Windows users can check out this tutorial: [[Building_with_Windows|Building with Visual C++]]

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

'''1. Get the source code'''

We use Mercurial as our version control system. The [http://bitbucket.org/tortoisehg/stable/wiki/install TortoiseHG website] describes how to install it. If you just want to download the OpenClonk source code, you can also install Mercurial without TortoiseHG.
TortoiseHG is a GUI for Mercurial which makes using Mercurial much more comfortable.

Two tips for somebody new to Mercurial: Ignore the revision numbers, they are only there to mislead you. Pay attention to the changelog id. And activate the "Mercurial Queues" extension to get the "strip" command, with which one can delete changesets that are no longer needed.

To get the source, you have to clone the repository. Use the TortoiseHG dialog to clone http://hg.openclonk.org/ or execute this command in a commandline shell:
<nowiki>hg clone http://hg.openclonk.org/ openclonk</nowiki>
If you already cloned the repository and only want to update your local repository, use the Synchronise dialog of TortoiseHG to pull the repository and update. Or execute in the commandline:
<nowiki>hg pull --update</nowiki>

'''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://forum.openclonk.org/topic_show.pl?pid=1405#pid1405 for Microsoft C++ users]
* [http://forum.openclonk.org/topic_show.pl?pid=1522#pid1522 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.

== Get your changes into the openclonk.org repository ==

First, make the changes on your local copy of the repository. Then commit it to your local Mercurial repository. After that, you can export the changes as a patch (if you only changed source code or text) or as a bundle (if you changed binary files). Then attach the file to a forum post.

See also the [http://forum.openclonk.org/topic_show.pl?tid=226 topic in the developers corner].

== Miscellanous notes ==

We have [[SourceCodeReorganization|reorganized the source code]].

=== Mercurial extensions you really need ===

Add these to your ~/.hgrc:

hgext.mq=
This enables the "strip" command, with which you can remove a unwanted revision. Absolutely necessary, because the great thing about distributed revision control is that one can commit early and often and then go back and clean up, often creating new commits to replace the old ones. But the old ones do not disappear after being abandoned. Or maybe you want to try out some revision from somebody else, and get rid of it afterwards.

hgext.rebase=
hgext.transplant=
These enable you to reorder history. Essential if you have an experimental feature followed by a bugfix and only want to push the bugfix to the public repository.

C4Script Style Guidelines

2010-01-26T14:14:02Z

Isilkor: /* Control Structures */ Shortcut operators are right out

== Scripting policy ==

Style guideline for coding C4Script in OpenClonk.
The development is based on exchange of scripts. Therefore it is necessary to define some styling rules, so that other developers can read your code more easily.

=== Indentation ===

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

public func foo()
{
bar();
if (1)
{
bar2();
}
}

=== Braces ===

According to the [http://forum.openclonk.org/topic_show.pl?tid=208 poll] in the forum:

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 if statements if the first block or an else block has them.

if (bar)
{
foo();
}
else
{
foo2();
}

=== Spaces ===

Keywords followed by a space: <tt>if, while, for</tt>

Commas are followed by a space, function names not. <tt>-></tt>, <tt>->~</tt>, <tt>++</tt> and <tt>--</tt> don't need spaces, other operators do. <tt>+</tt> and <tt>-</tt> don't need spaces either when used as algebraic signs, otherwise they do.

var foo = 0;
foo++;
if (foo && bar)
{
foo = foo + 1;
}

=== Control Structures ===

Control structures with a single statements are written without braces. You may add braces for readability. Don't use shortcut operators instead of if.

Statements are written in a new line.

=== Comments ===

'''Please comment your script where it's necessary.'''

You may format your comments as you wish:
// single line comment

// multiline
// comment

/* multiline
comment 2 */

// Unnecessary comment:
// Increase i by one
i++;

// Necessary comment:
// This starts the whole effect, casts particles and stuff
CreateObject(BAR1, 0,0, GetOwner())->foo();

Especially for German scripters: '''comment in English please!'''

== IDs ==

The difference with CR is that OC allowes for IDs to have more than four characters. The main OC content will use the namespace Core_, so use this as prefix for all your objects which go into the main object pack for OC.

=== Objects.c4d/Libraries.c4d ===

ID's can now have more than four characters, so in the future use: Core_Library_.

IRCMeeting/20100118

2010-01-19T18:39:38Z

Isilkor: +Summary

== Summary ==
* Future meetings weekly at 18:00 UTC (19:00 CET, 13:00 EST)
** Rotating moderators
* ck: Mesh rendering on its way
** animation stack (http://forum.openclonk.org/topic_show.pl?pid=5302#pid5302)
** experimental features (perspective rendering)
* Isilkor: Long C4IDs
** need some polish, are usable
** namespaces?
* Maikel: Animal AI
* Newton: HUD complete except for some bugs and a few engine features
** Upcoming: Menus, Gamepad controls
* Blogs
** "news light"
** Newton will set one up
* Wiki
** to contain FAQs regarding OC dev, game
** clearer structure needed
* Roadmap
** We want something playable for OCM in April, see [[IRCMeeting/20100118-gobby|gobby log]]

== Full Log ==
<pre>19:11:45<!Mimmo_O> i think newton forgot about the time
19:11:52<!Mimmo_O> or maybe hell join us in 48 minutes
19:11:53<!Isilkor> Well, this meeting is off to a great start
19:12:35<!Isilkor> Which means I'll wrest control from him and just use the agenda he posted on the forums
19:12:49<!Randrian> hmm I am sorry, but I have to join dinner now... I'll join later
19:13:20<!Isilkor> Welcome to the first OpenClonk developer IRC meeting. We're trying to be constructive here, so please don't disrupt the discussion (too much).
19:13:40<!Maikel> Ty :)
19:14:21< Asmageddon> So that eeting was meant to be IRC meeting?
19:14:24<!Isilkor> I'll be providing a short summary of the meeting afterwards.
19:14:44-!- Newton [~Miranda@euirc-93eb52c2.adsl.alicedsl.de] has joined #openclonk-dev
19:14:45-!- mode/#openclonk-dev [+ao Newton Newton] by ChanServ
19:14:45<!ck> I also suggest to put the logs online, accessible from the wiki
19:14:45<!Isilkor> Asmageddon: We're doing a short weekly meeting to steer the project in a general direction
19:14:48<!Zapper> yo newton
19:14:55<!Isilkor> As a first, I'm going to assume that the time and place is acceptable for everyone. If there's any problems, please speak up now.
19:15:05<!Isilkor> ck: Can do.
19:15:06<!Newton> hey guys
19:15:16<!Maikel> hi
19:15:27<!Isilkor> Newton: We're just about to start, do you want to take the helm?
19:15:28< Asmageddon> hello!
19:15:28<!Newton> sorry for the lateness
19:15:58<!Newton> is everyone there?
19:16:10<!ck> I'd prefer if we could start about an hour later in future, though 19:00 is also OK if anybody objects
19:16:11<!Zapper> Well, I am
19:16:36<!Isilkor> Randrian will join us later
19:17:01<!Newton> so do we start at 19:00 or 20:00 in the future?
19:17:11<!Mimmo_O> Newton!
19:17:18<!Newton> Isilkor: ok@helm
19:17:30<!Isilkor> I'd prefer 19:00, but I'd be willing to compromise ;)
19:17:34<!Newton> same here
19:17:41<!Maikel> I don't care.
19:17:58<!Maikel> dependent on the length of the meetings.
19:18:14<!Mimmo_O> yeh
19:18:15<!Newton> hm, then lets stick to 19:00 for now
19:18:47<!Newton> do you think we should keep some kind of protocol of the meetings?
19:19:15< Asmageddon> what for?
19:19:16<!ck> I think it's enough to put the IRC logs online, and maybe a short summary
19:19:17< s_m_w> Logs are usually enough for meetings held on IRC
19:19:35<!Mimmo_O> yop
19:19:37<!Newton> but then, we still need someone to do that
19:19:44<!Maikel> I'll
19:19:46<!Isilkor> I'm doing it
19:19:49<!ck> Isilkor volunteered for today..
19:19:50<!Newton> fight for it
19:19:54<!Newton> ok
19:20:09<!Maikel> do>will
19:20:34<!Newton> I think its better if we have any additional TOPs, to mention them now even though we dont have to be that official
19:20:46<!Newton> anybody has something he wants to talk about?
19:21:03<!Mimmo_O> nothing really important
19:21:04< Asmageddon> I have
19:21:07<!Maikel> TOP = Topic?
19:21:12< Asmageddon> But nothing so important
19:21:16<!Newton> Maikel: yes, Agenda point
19:21:18<!Mimmo_O> TagesOrdnungsPunkte
19:21:25<!Newton> oh@TOP
19:21:27<!Newton> so its german
19:21:28<!Newton> anyway
19:21:37<!Newton> Asmageddon?
19:21:47<!Mimmo_O> i know that frm my german lessons :S we need to keep protocol of every hour.
19:21:49< Asmageddon> Wait a moment, I'm eating :P
19:22:05<!Newton> err ok. Then I'll mention my point
19:22:22<!Maikel> Maybe we can end with topics suggested during discussion, and start with the predefined agenda.
19:22:39<!Newton> yes, that would be another option
19:22:56<!Newton> however i fear that later (at point 5), the whole meeting will start to dissolve a little
19:22:59<!Maikel> For the future, just start with your point for now
19:23:31< Asmageddon> Ok, I want lightning system, not neccesarily dynamic, can be precalculated and updated when terrain is modified or light added/removed
19:23:40< Asmageddon> If you want I have example images made in GIMP
19:23:42< Asmageddon> but they are a bit big
19:23:55< Asmageddon> And it will take some time to upload them with my internet
19:24:21<!Newton> Asmageddon: this is more of a feature request and does not belong here. You'd better post that into the forum. We are now talking about more basic concepts
19:24:22< Ape> Make them JPEG and they will be small(?)
19:24:35< Asmageddon> Ok, forget that
19:24:46< Asmageddon> That is not feature request
19:24:49< Asmageddon> It is a suggestion
19:24:56< Asmageddon> it will make OC look WAY better
19:25:07<!Newton> ok
19:25:08<!Newton> anyway
19:25:08< Asmageddon> which can eventually make more people to play OC
19:25:28<!Isilkor> That is fine and all, but in the end it's still a feature request
19:25:32<!Newton> My agenda point: With property lists, effect vars, local vars and script constant callbacks ("IsArrow"), the whole design pattern of which goes where is a bit softened
19:25:47<+Matthi> (Asmageddon: As right as your point may be: please don't forget that currently, there isn't even a GAME one could play)
19:26:13< Asmageddon> ok :/
19:26:15<!Newton> + e.g. Visibility as a property, but not GetXDir
19:26:25<!Newton> I'd like to talk about that later, before point 5 perhaps
19:26:50<!Zapper> and what to talk about now? :o
19:26:57<!Newton> except you would like to postpone that to a later session or rather discuss it in the forum
19:27:22<!Newton> Zapper: what do you mean?
19:27:32<+Matthi> "Where do we start"
19:27:37< Ape> Matthi brought up an important issue. We have to make this game playable as quickly as possible.
19:27:55<!Maikel> That's what this meeting is for.
19:28:14<!ck> For me it's OK to discuss it today I guess. Not sure I have a strong opinion though.
19:28:15<!Newton> hmm, its not optimal that only the devs know of the agenda while the meeting itself is not moderated (=non-devs can talk too)
19:28:31<!Isilkor> Newton: move the agenda to the open forums then
19:28:35<!Isilkor> announcements or something
19:28:49<!Isilkor> or just post it here
19:28:54<!Newton> Ape, Asmageddon: http://forum.openclonk.org/topic_show.pl?tid=328
19:29:04< Ape> Thanks
19:29:48<!Newton> okay, I think the organizational stuff is finished. I propose that next time, we'll just find another moderator, we dont need to define some specific order
19:29:53<!Newton> point 2, status updates
19:30:16<!Newton> lets take the turns from top to down from the nicklist
19:30:19<!Newton> ck?
19:30:31<!ck> I'm busy with the mesh animation stuff
19:31:03<!ck> Turned out to be not as easy as I thought to provide a somewhat general mechanism with an easy-to-use (C4Script) API
19:31:18< Asmageddon> That gobby is a clone of another program like that
19:31:21< Asmageddon> But guess that is unimportant
19:31:23< Asmageddon> sorry :P
19:31:39<!ck> The goal is basically to get the swimming animation correct
19:31:56< Asmageddon> IMO swimming animation is good
19:32:03<!Newton> Asmageddon, please
19:32:04< Asmageddon> a 'bit' strange, but good
19:32:05<!ck> It's displayed incorrect however
19:32:20< Asmageddon> Ok, sorry :(
19:32:42<!ck> I guess I'll end up with something similar to the Stack system I proposed in the forums
19:33:15<!ck> Where each node in the stack can again be a combination of multiple animations
19:33:41<!Newton> the stack system you posted in the forum is not implemented yet?
19:33:43<!ck> Probably this is not the right place to express my thoughts, but I'll add a documentation page once this is working as I want it
19:34:33<!ck> No, it isn't. It partly is on my computer only, but it turned out to be not as easy to use as I'd like it to
19:34:49<!Newton> ok
19:35:16<!ck> And after that there is many more mesh stuff to keep me busy for quite a while ;)
19:36:11<!ck> (like trying out fixed point math or perspective rendering)
19:36:18<!Randrian> re
19:36:23-!- Irssi: #openclonk-dev: Total of 25 nicks [3 ops, 0 halfops, 2 voices, 20 normal]
19:36:28<!ck> Guess that's it from my side
19:36:53<!ck> So I think is it Isilkor's turn then
19:36:56<!Newton> .oO(wow, perspective rendering. Thats a feature I desire highly)
19:37:02<!Maikel> What about some models which use, UV,shaders(what do i know), is that hard to implement?
19:37:37<!ck> Maikel: not sure. I guess it's not hard, but requires some time
19:38:21<!ck> it's still on the agenda, just not with as much as priority as the ones I mentioned above
19:38:31< Ape> What is the point of perspective rendering if all the objects are on the same surface and has not much depth out of it?
19:38:59<!ck> The Clonk looks fine without, so it should be possible to get other (less complex?) model to do the same, right?
19:39:10<!ck> Ape: For ingame pictures basically
19:39:21<!Randrian> well the sprites for CR always were rendert orthogonally
19:39:32<!ck> As displayed for example in the HUD
19:39:46<!Newton> Ape: there has been already a discussion of that in the forum and it turned out that perspective rendering is applicable (and looks good) to a certain limit
19:39:50<!Isilkor> ck: The mesh rendering doesn't actually require fixpoint math, does it?
19:40:02<!Isilkor> It's just graphics anyway, so doesn't need to be in perfect sync
19:40:08<!Randrian> no, but attaching
19:40:14<!Randrian> attaching to bones needs that
19:40:17<!ck> Isilkor: No, but it is desirable to query vertex/bone positions in script
19:40:39<!ck> Randrian also suggested to make use of "ground bones" to aid in synchronizing the mesh animation with the object movement
19:41:11<!ck> That is, move an object according to a specific bone's position in the mesh
19:41:41<!ck> Of course the first step is to find out its impact on performance, and then we can still decide whether it's a good idea or not
19:42:54<!ck> (Another feature would be to mount a clonk correctly on a horse)
19:43:51<!Newton> as long as the bone position cant be queried but only certain meshes attached to it, the math doesnt have to be integer, no?
19:44:04<!Newton> (meshes, not objects)
19:44:30<!ck> Sure, but we might also want to put the Clonk as an object at the correct location
19:45:02<!ck> For collision detection to work correctly
19:45:06<!Newton> ah right, I was thinking of the sword in the hand of the clonk and such
19:45:31<!ck> In that case attaching just meshes should work (and that's even implemented already)
19:45:39<!Maikel> That's quite crucial.
19:46:55<!Newton> hm alright. I got some open items about mesh rendering too, but this doesnt belong here now. Ill get back to that later
19:47:07<!Newton> now, lets switch to Isilkor?
19:47:52<!Isilkor> My patch to implement >4 char C4IDs just needs some more polish, but otherwise seems quite solid
19:48:52<!Isilkor> There's obviously the problem of having optional definitions which would lead to syntax errors if they're used without checking
19:49:17<!Newton> optional defintions?
19:49:46<!ck> I think it's good to access those via C4Id, or a GetDefinition() loop, and to be able to rely on the required definitions to be available
19:49:50<!Isilkor> Stuff that you might want to check for, but isn't always loaded
19:49:54< Ape> Do we have a standard on the ID lenght? Should the names be as long as needed or should we prefer some a fixed lenght (like 4)?
19:49:58<!Maikel> Would that allow for C4IDs with variable length?
19:50:12<!Isilkor> They would allow for C4IDs of arbitrary identifiers
19:50:25<!Isilkor> so, things like OC_Library_Inventory
19:51:23<!Newton> I don't find the forum topic for that and I dont remember if this question has been discussed:
19:51:29<!Newton> are all C4IDs reserved words? In the sense that e.g. the C4ID of the clonk is 'Clonk': var Clonk = GetHiRank(0); Clonk->GetCategory()
19:51:49<!Isilkor> no, they aren't. They're just global constants.
19:52:32<!Newton> so I should not name a variable "Clonk", well but if I do, I can not access the global constant 'Clonk' in the scope of the variable 'Clonk'
19:52:38<!Newton> +?
19:52:55-!- Asmageddon [5570c416@euirc-c30e4972.mibbit.com] has quit [Quit: http://www.mibbit.com ajax IRC Client]
19:52:56<!Isilkor> yes, obviously. If you declare a local variable with the same name, it hides the constant.
19:53:09<!Isilkor> You can access it via C4Id("Clonk") though
19:53:26< Ape> I believe this is the forum topic for this: http://forum.openclonk.org/topic_show.pl?tid=195
19:53:41<!Newton> cool, then thats not an issue. I guess the standard will be to id objects with a big first letter (Clonk), variables are normally named with a small first letter (clonk)
19:54:36<!Maikel> We could also name everything OC_*, but some sort of ID-list in the wiki wouldn't be a bad thing, I guess.
19:55:02<!Isilkor> In the absence of namespaces, we should still name it OC_*, even with an ID list.
19:55:16<!Newton> at least we should agree on some naming scheme as soon as the feature is ~done
19:55:30<!ck> Do we have some C4Script style guidelines somewhere?
19:55:33< Ape> Can't it be ID->Clonk or something like that?
19:56:03<!Zapper> Ape, that looks as if "ID" was an object
19:56:08<!Newton> ck: Clonkonaut started it once: http://forum.openclonk.org/topic_show.pl?pid=4221;hl=style%20guidelines
19:56:35< Ape> Well it could be an object that is used to get the objects for IDs
19:57:09< loriel> I think it should be "Core_" or something rather than OC_, so it indicates where the IDs are from rather than trademarking them.
19:57:31<!Zapper> agreed
19:57:52<!Newton> hmm
19:57:55<!Newton> Core_Clonk?
19:58:03<!Newton> sounds a bit unnecessary
19:58:16<!ck> As unnecessary as OC_Clonk would be...
19:58:21<!Isilkor> Newton: Some kind of namespacing is necessary
19:58:32<!Isilkor> otherwise we'll get collisions
19:59:00< loriel> I am not entirely happy with the "OC_" name because at some point someone is going to want to rename the whole thing like it happened between CP, CE and CR at the least, and then there are all those outdated OC_ prefixes stuck all over the project :)
19:59:06<!Newton> how would the namespaces look?@Syntax
19:59:09-!- pluto [~pluto@82.113.106.euirc-d8d72950] has joined #openclonk-dev
19:59:20<!Zapper> There are still people who don't like the name "OpenClonk". I'd prefer Core/anything else over OC_
19:59:46< Ape> object.core.flint and object.apepack.megabomb?
19:59:57<!Zapper> I like the C++ style
20:00:06<!Newton> Core::Clonk
20:00:17<!Zapper> I think a point/-> should be reserved for example for stuff with real objects
20:00:21< loriel> On the other hand, a name like "Core" kind of prevents stuff from being split into a separate package at a later point, if that would be desirable.
20:00:23<!Maikel> Whatever types the easiest.
20:00:45<!ck> Well, we don't need to agree on a name right now
20:01:21< loriel> (I was just trying to start an argument about the name, not the syntax. If I understand this right, the _ thing would work right now without messing with the parser.)
20:01:28<!Isilkor> loriel: yes
20:01:43<!Isilkor> but foo::C4ID-> doesn't work anyway, so we can use :: to separate namespaces
20:02:16<!ck> I guess you mean C4ID::foo->? :)
20:02:29<!Isilkor> Uh... maybe ;)
20:02:55<!Newton> lets postpone that discussion of the name of the namespaces (and its syntax) to a later meeting. The feature is not finished yet anyway
20:03:08<!ck> I forum poll might also do it
20:03:18<!ck> once we have a few suggestions
20:03:28<!Maikel> C_
20:03:42<!Mimmo_O> or c.clonk
20:03:44<!Mimmo_O> c.hut
20:04:01-!- clonkine [~clonkine@euirc-0184f4a7.dynamic.qsc.de] has joined #openclonk-dev
20:04:09<!Newton> I'd say, let Isilkor do his thing and after the commit, we already have one suggestion (the one of Isilkor) and based on that, we can perhaps discuss it
20:04:11<!Mimmo_O> hallo clonkine
20:04:14< clonkine> hi
20:04:19<!Newton> its nothing we can't change later
20:04:38<!Maikel> Ok, my turn(we need to speed this up)
20:05:42<!Maikel> I tried to C4Script Disasters and some Animals, but got stuck for now because of the animations, and the scenario.txt interface might be changed.
20:05:50<!Newton> (yes, the temptation to start a discussion over the update is very high. I'll try to cut the discussion if it gets too long)
20:06:18<!Newton> the scenario.txt interface might be changed?
20:06:29<!Maikel> Also the with Command() System is somewhat hard to implement, basic AI stuff
20:06:53<!Zapper> AI stuff? like movement in a landscape?
20:06:57<!Zapper> or other AI stuff?
20:07:00<!Maikel> http://forum.openclonk.org/topic_show.pl?tid=326#pid5330
20:07:15<!Maikel> Well "Call"is only called once
20:07:25<!ck> What's the problem with animations? You mean the models not be loaded entirely?
20:07:30<!Maikel> yes
20:07:34<!ck> OK
20:08:20<!Maikel> So I guess it is nearly impossible to implement something like "Energy" in C4Script
20:08:35<!Zapper> ?
20:08:52<!Zapper> I don't know why you need the Call-Command. For periodic timers?
20:09:26<!Maikel> Ok you could do anything with effects
20:09:39<!Mimmo_O> ill take a shower now. im back in about 20 minutes.
20:09:45<!ck> Can't you just schedule another Call command in your callback?
20:10:19<!Newton> hmm, I am not sure myself what the exact problem is, but to clarify this problem shouldnt be part of the status update
20:10:24<!Newton> lets do that later, shall we?
20:10:30<!Maikel> Yes next.
20:10:40<!Zapper> Mimmo is gone. So, newton?
20:10:45<!Newton> ok
20:11:21<!Newton> the last 2 months or so I have been working on the script side of new controls (together with Sven2)
20:11:34<!Newton> and the hud
20:12:09<!Newton> basically to finish what I wrote in the HUD Konzept: http://forum.openclonk.org/topic_show.pl?tid=297
20:12:36<!Newton> apart from few bugs and some missing engine features (in the bugtracker), its now done
20:12:48-!- Sven2 [_ve_2@goldwipf.de] has joined #openclonk-dev
20:12:51-!- mode/#openclonk-dev [+ao Sven2 Sven2] by ChanServ
20:13:11<!Newton> the weapons-system if one can call it like that, is done, too. Again a few engine features are missing
20:13:42<!Newton> next I wanted to focus on A) Gamepad controls and B) menus
20:13:47<!Sven2> Hey
20:14:01<!Zapper> Also the close combat weapons?
20:14:06<!Zapper> Or just the ranged ones?
20:14:21<!Newton> for B) I have to confess that I can't do so much script side, so I am waiting for - hi Sven2! - Sven2 to do something in that case ;-)
20:14:23-!- pluto [~pluto@82.113.106.euirc-d8d72950] has left #openclonk-dev []
20:14:51<!Zapper> Or, did you do the object-side (like, real weapons) or the interface in the Clonk for weapons?
20:14:53<!Newton> for A), i wanted to wait how the transfer-contents-with-menus ( B) ) turns out
20:15:14< clonkine> poor Sven2
20:15:19<!Newton> Zapper: if you look at the bow, there is not much of a "system" there, it is not needed either
20:15:44<!Zapper> Otherwise the "weapons system" (aka the templates) for close combat weapons would be what I would do next
20:15:55<!Randrian> well I started to implement a bit the sword and the animation side of it; the strike animation and so
20:15:55<!Newton> The ControlUse* commands are basically enough for weapons. A little procedure-check here, a delay there and done is the weapon script
20:16:49<!Zapper> Randrian, imo we should have it that way that we have one template and the weapons just have to implement some callbacks (like in hazard)
20:16:53<!Newton> Ringwaul actually tried to create such a template in the tradition of hte Hazard-weapons-template, but it didnt turn out to be too useful
20:17:04<!Maikel> Well it get's harder if for example two swords hit each other, or?
20:17:10<!Zapper> for example!
20:17:17<!Newton> Zapper: Have a look at the bow. There is no need for a system
20:17:31<!Randrian> well two swords that shall hit each other will be difficult.
20:17:37<!Randrian> I would pefere a blocking animation.
20:17:52<!Randrian> not just some random "hit" of two swords.
20:18:06<!Newton> but before we dive into some kind of discussion here if a basic object to include from is wise or not, let me just mention one more thing and then Randrian has the word:
20:18:23<!Randrian> ok sorry
20:18:58<!Newton> I created some kind of ammunition system, based on a includable library object named "Stackable" (also posted it in the forum) which is from the concept similar to arrows
20:19:01<!Zapper> Well, Newton. The ideal weaponscript would look like that: func IsAmmunition(obj){return obj->~Isarrow();} func ShootingBehavior(){return STRAIGHT;} fiinished
20:19:35<!Newton> so the ammunition used for weapons and other stuff are actually still objects and also the objects which are shot (as opposed to hazard)
20:20:05<!Newton> I can tell you more abou the details later but for that, you should perhaps read the Bow- and Arrow-scripts first so that we are on the same level
20:20:08<!Newton> Randrian, your turn
20:20:13<!Zapper> I just read the bow script :<
20:20:54<!Randrian> well I have worked on the animations for the clonk.
20:21:16<!Randrian> for further progress it would be good to have ck's new animation system ready.
20:21:25<!Randrian> cause the script interface changes a lot with it.
20:21:39<!Mimmo_O> okay, re
20:22:25<!Randrian> I also think I have to change quite a bit about the rig, cause it isn't perfect for all types of animations yet.
20:22:39<!Randrian> well and all the animations still need some tweaks.
20:23:05<!Randrian> I also have made first steps with meshes attached to the clonk.
20:23:15<!Randrian> for example the clonk holding the sword and striking with it.
20:23:24<!Randrian> or the clonk holding the bow and animing with it.
20:23:42<!Newton> nice
20:23:53<!Randrian> its a bit difficult to get the orientation in Blender right, so the mesh is shown correct ingame
20:24:16<!ck> Let me know if there is something I can do in the engine to help you with that
20:24:32<!Randrian> the problem is, that when the mesh has a rotation in Blender (more precisly, the object of the mesh has a rotation assigned to it)
20:24:49<!Randrian> I think these rotations aren't shown ingame.
20:24:54<!Mimmo_O> ive done almost nothing :s i was just strawing around in the forum and posting smoe ideas, but nothing really special
20:25:14<!ck> Randrian: Would be cool if you can hand me a simple example object
20:25:20<!ck> I might have a look then
20:25:28<!Randrian> yes ok, I can make you an example.
20:25:56<!Randrian> I also got problems latly with exporting the female clonk, cause the animations somehow were wrong.
20:26:08<!Randrian> I don't quit know, if it was caused by Blender.
20:26:42<!Randrian> Blender can assign Armatures to meshes by parenting and also by using a modifier.
20:26:59<!Randrian> the female just had the armature parented, the male had both.
20:27:07<!Randrian> it was a bit strange.
20:27:45<!ck> maybe try whether it's also broken in an independant ogre mesh viewer. If so, make the model available to me and I'll see what I can do :)
20:27:46<!Zapper> As for me, I have not done much lately either. I started with an "animal" (mainly for experimenting with proplists and stuff) and thought I could do the close combat system next
20:28:15-!- Randrian_ [~randrian@euirc-a663a039.83.171.156.179.ip-pool.NEFkom.net] has joined #openclonk-dev
20:28:30< Randrian_> args internet...
20:28:32< Randrian_> <Randrian> yes ok, I can make you an example.
20:28:36< Randrian_> <Randrian> I also got problems latly with exporting the female clonk, cause the animations somehow were wrong.
20:28:38< Randrian_> <Randrian> I don't quit know, if it was caused by Blender.
20:28:40< Randrian_> <Randrian> Blender can assign Armatures to meshes by parenting and also by using a modifier.
20:28:42< Randrian_> <Randrian> the female just had the armature parented, the male had both.
20:28:44< Randrian_> <Randrian> it was a bit strange.
20:28:46< Randrian_> <Randrian> and I didn't manage to get the orientation of the bow right up till now.
20:29:09<!Newton> [20:28] Zapper: As for me, I have not done much lately either. I started with an "animal" (mainly for experimenting with proplists and stuff) and thought I could do the close combat system next
20:29:09<!Newton> [20:28] ck: maybe try whether it's also broken in an independant ogre mesh viewer. If so, make the model available to me and I'll see what I can do :)
20:29:45<!Mimmo_O> ive done almost nothing :s i was just strawing around in the forum and posting smoe ideas, but nothing certain for OC.
20:30:15< Randrian_> well the close combat system can be difficult, if it isn't done along with the animatiions.
20:30:47<!Newton> I also think that 90% of the close combat is animation-stuff as long as the system itself is not something elaborate
20:30:56< Randrian_> yes.
20:31:24<!Newton> (and with only one button=function available, it might be hard to do something elaborate ;-))
20:31:27<!Mimmo_O> will there be improvements in the close combat system?
20:31:31< Randrian_> well, the system can be more complex with the mouse move. Cliking and moving the mouse up could result in a strike up.
20:31:46<!Newton> yes, that would be possible
20:31:55<!Maikel> Someone else who wants to share what he/she was working on, I think we can end point 2
20:32:05<!Newton> Mimmo: I don't think that we stick in any way to the old system of "automatic fight"
20:32:11<!Zapper> <Newton> (and with only one button=function available, it might be hard to do something elaborate ;-)) <- well, I plan to use the acceleration of the clonk for stuff
20:32:12<!Mimmo_O> good
20:32:14<!Newton> well, there is still Sven2
20:32:16<!Mimmo_O> it was somehow terrible.
20:32:16<!Newton> @point 2
20:32:20<!Zapper> for example
20:32:30<!Maikel> Oh yes, Sry
20:32:36<!Newton> if he is still there
20:33:08-!- Randrian [~randrian@der.richard.im.euirc.net] has quit [Ping timeout]
20:33:09<!Maikel> A sword can also strike differently dependent on where you click relative to the clonk
20:33:12<!Zapper> Sven has no highlighting enabled as far as I know - will be quite hard to get him here :o
20:33:28<!Mimmo_O> hm, Maikel
20:33:30<!Newton> hmm, then perhaps later he returns
20:33:35<!Mimmo_O> that would result in just klicking and clicking
20:33:40<!Zapper> even later? :o
20:33:44<!Mimmo_O> then, suddenly, you stop fighting and accidently throw something away
20:33:53<!Newton> but well, I know what he was working on, so I can sum it up
20:34:04<!Zapper> I think throwing stuff away should _always_ be just on Shift+Click btw
20:34:08<!Zapper> Just to throw that in
20:34:15<!Mimmo_O> yes, same here
20:34:26<!Maikel> No, not for gold and rocks
20:34:47<!Maikel> Everything with ControlUse() { return true;} already does that
20:35:09<!Zapper> Gold and Rocks don't have ControlUse(){return true;}
20:35:19<!Zapper> I think we should have one behaviour everywhere
20:35:28<!Newton> okay, this shouldn't be discussed now
20:35:39<!Newton> I noted it down as something to discuss later
20:35:50<!Maikel> k
20:35:56<!Newton> I'll sum up really short was Sven has been working on well, during silvester
20:36:32<!Newton> The PlrControls are not quite finished yet. Some features are missing, some features that have been documented already are also missing
20:36:32<!Sven2> Sorry, was afk
20:36:42<!Newton> but as you can see, most of it works...
20:36:48<!Newton> ah well, you have the word
20:36:50<!Sven2> Yes, menus are on the list
20:37:26<!Sven2> Well, I thought about re-implementing controls for classic menus (really just a few bugixes I think) and then allow custom dialogs
20:38:05<!Sven2> Custom dialogs should cover stuff like PeterW mentioned in the forum; the overhead building menus
20:38:50<!Sven2> Anyway, what kind of stuff is really missing in the engine right now?
20:39:10<!Sven2> I don't think it's menus, because those aren't used anywhere yet?
20:39:38<!Newton> how can I use menus if they are not implemented yet? I need non-modal menus ^^
20:40:12<!Sven2> Is that in the bugtracker yet?
20:40:35<!Sven2> I believe it can be done quite easily. Though getting multiple menus per viewport might be difficult
20:40:41<!Newton> the other stuff that is 'really' missing are (from my side) a few single features that are all in the bugtracker
20:40:46<!Sven2> How are you supposed to control them by gamepad if they're not modal?
20:41:12<!Newton> the custom dialog stuff is not in the bugtracker though because I was thinking you have a concept for that
20:41:39<!Newton> Sven2: that is the question@how to control by gamepad
20:41:41<!Sven2> Basically, it's supposed to be a bunch of functions like CreateDialog, AddDialogItem, etc.
20:42:39<!Newton> (what we need is a concept for dialogs that work for mouse controls and non-mouse controls [gamepad] alike. I didnt think of anything yet)
20:42:47<!Sven2> Though I also thought about a different concept to have just CreateDialog(dlg) /UpdateDialog(handle, dlg) /DestroyDialog(handle) and have "dlg" be a proplist that contains all dialog information
20:45:31<!Newton> I am more concerned that a dialog-system that works good for mouse won't work with gamepad. I will start some topic to find how contents-transfer could work with gamepad (e.g. how it works in other console games with inventory and items)
20:45:46<!Newton> otherwise, I think we are done with point 2?
20:46:26<!Maikel> yes
20:46:27<!Sven2> You would need the concept of a "focused" dialog for gamepad control
20:46:55<!Newton> point 3, Website: Blog, Homepage, Wiki
20:46:56<!Sven2> Even if it's not "modal", i.e. you could have seperate controls for dialog and Clonk control if your gamepad permits it
20:47:45<!Mimmo_O> (Sven2, stop)
20:47:53<!Zapper> I still think we can use the forum as a "blog"
20:48:18<!Mimmo_O> i think we should use something like a blog
20:48:19<!ck> Do you mean these blogs that are built in into mwf?
20:48:33<!ck> Like they were enabled in the english forums some time ago?
20:48:37<!Zapper> no, mawic disabled them
20:48:41<!Zapper> or, kicked them out
20:48:46<!ck> oh.
20:48:47<!Zapper> just make a subforum "blogs"
20:48:48<!Newton> yes@kicked them out
20:48:49<!Maikel> About the wiki: That should contain (now and in the future) all faqs regarding OpenClonk development, but for now it should be structured somewhat more clearer.
20:48:54<!Mimmo_O> if someone who is interested in OC comes to the site, he just sees some black/white page with a forum... nooone wants to read through it just to gather some informations
20:48:55<!Zapper> Where would be the difference to any other blog software?
20:49:08<!Newton> err, lets stick to the blog topic a few minutes, Maikel
20:49:38<!Newton> I agree to Mimmo actually. A subforum with forum topics, this is not a blog
20:49:45<!Mimmo_O> its Blog, Homepage, Wiki, not Wiki, blabla :p
20:49:47<!Newton> as much as Announcements is not a blog
20:49:50<!Sven2> If people want to start blogs, they will. Otherwise, they won't. I don't think a forum will change this
20:50:03<!ck> Zapper: Does mwf provide RSS feeds?
20:50:14<!ck> Trackbacks?
20:50:14<!Zapper> Uh, I dont know
20:50:35<!Newton> ck: yes, I tried to enable them a few times but it does only work properly if you have a proper server, not some CGI enabled webspace
20:50:53<!Maikel> Wouldn't be useful to establish that we have enough writers, to have at least one item a week?
20:51:08<!ck> I think the serendipity ones work on my shared hosting account
20:51:15<!Mimmo_O> i think we will come to at least 3 a week
20:51:31<!Newton> ck: can you post your serendipity blog link?
20:51:36<!Mimmo_O> if every developer has acces to write a new entry
20:51:41<!ck> Newton: http://arbur.net/serendipity
20:52:40<!Newton> why is serendipity > wordpress? For our use?
20:52:52<!ck> I didn't say that.
20:53:11<!ck> I just said its RSS feeds work on my (quite limited) webspace account.
20:53:13<!Newton> err, I didnt mean it that way
20:53:28<!ck> It's the only blog system I have experienced with, I can't say anything about wordpress
20:53:29<!Newton> but I want to set up a system and asking you (you in plural) which one to prefer
20:53:57<!Mimmo_O> i have no opinion to that, due to my lack of knowledge about them
20:54:05<!Mimmo_O> i would say "one which is easy to use"
20:54:11<!Sven2> So, this is like a more relaxed "news" column?
20:54:31<!Newton> ck: can one integrate the blog (or e.g. "the newest 3 items of the blog") in the mediawiki or in some otherwise plain HTML file (e.g. the homepage)
20:54:58<!ck> Sven2: kind of... to keep interested partys informed in a structured way
20:55:10<!Newton> Sven2: a developers blog. Clonk.de didnt have this... well perhaps later with ClonkX, a little
20:55:27<!ck> Newton: I think so, with some scripting. My blog is aggregated on planet.gnome.org
20:55:46<!ck> which basically displays recent entries
20:55:49<!Maikel> Then the role of news, would just be to announce new versions and beta-test, etc.
20:56:26<!Newton> what i'd like is that we all have a single login for the blog
20:56:52<!ck> oh, why that?
20:56:56<!Newton> (so that the devs don't need to register in 4 places for the website)
20:57:07<!Newton> already now, with bugtrack, wiki and forum its a bit much, dont you think?
20:57:30<!ck> It might be interesting who wrote a particular blog entry though...
20:57:39<!ck> +to know
20:57:47<!Maikel> Well we can sign it with our names
20:57:51<!Maikel> yes @ newton
20:58:31<!Newton> ok, Ill first install Serendipity and then we can play around with it a little before we finally settle with that
20:58:59<!Newton> next: wiki. Maikel?
20:59:27<!Maikel> About the wiki: That should contain (now and in the future) all faqs regarding OpenClonk development, but for now it should be structured somewhat more clearer.
20:59:40<!Maikel> A bit more structure would already do the job there.
21:00:02<!ck> Do you have something concrete in mind?
21:00:04<!Maikel> code style rules at the right place, etc.
21:00:25<!Maikel> Well there are numerous examples of opensource game sites
21:01:01<!Newton> hm, I dont see your ponit
21:01:04<!Newton> *point
21:01:17<!Maikel> I would separate the page in Getting started(to play clonk), Content development, Engine development
21:01:22<!Newton> the /Project page and everything below seems to be perfectly structured
21:01:38<!Newton> you mean the Home page?
21:02:04<!Maikel> No, for example the coding style stuff is missing
21:02:31<!Newton> hmm, right
21:02:38<!Newton> it was there somewhere though, no?
21:03:11<!Maikel> http://wiki.openclonk.org/w/Style_Guidelines
21:04:26<!Newton> hm anyway. I am not sure if we have to discuss this. The wiki was just grown how the people contributed it. Nobody will cry if you add some links and reorganize some pages
21:04:37<!Maikel> Indeed
21:06:00<!Newton> so, err. Go ahead ;-)
21:06:41<!Newton> Also, the links in the upper navigation are not out of concrete. If you want additional links or something, tell me
21:06:55<!Newton> which leads us to the homepage, I guess
21:07:03<!Maikel> I'd rather go to point 4, and leave that for now( we can discuss it in some weeks)
21:07:08<!Newton> ok
21:07:27<!Newton> goals, yeah
21:07:32-!- Randrian__ [~randrian@euirc-06a781a2.83.171.170.113.ip-pool.NEFkom.net] has joined #openclonk-dev
21:07:37<!Newton> but this requires that everybody is still here, i think
21:07:47<!Newton> motivation check!
21:07:48<!Mimmo_O> .
21:07:48<!Maikel> Yes HL?
21:07:56 * ck
21:08:00-Mimmo_O:#openclonk-dev- everyone is here!
21:08:14<!Zapper> ill be afk soon
21:08:29<!Sven2> Yes
21:08:30< Randrian__> what is the question? I was just disconnected
21:08:43<!Newton> if all are stil lthere, because we move to point 5
21:08:44<!Newton> Goals
21:08:52< Randrian__> \me is here
21:09:02 * Ape is here
21:09:09<!Newton> Maikel mentioned in the forum, that we need to set reachable goals (and make them public)
21:09:12<!Mimmo_O> *point 4
21:09:13<!Isilkor> You want to go to point 4 if everyone is here, but then rather go to 5?
21:09:17<!Isilkor> I don't quite get it
21:09:24<!Newton> oops
21:09:27<!Newton> sorry, point 4
21:09:34<!Maikel> So I would like to have a somewhat playable game before the OCM in april. That is some melee scenario's where one can use some weapons, flints dynamite, catapult, and test the clonk's controls
21:09:59<!Sven2> Skyrace is playable ;)
21:10:12<!Mimmo_O> i want the catapult to be controllable like the on in CX
21:10:18<!Mimmo_O> with catapulting clonks.
21:10:26<!Mimmo_O> (i already have scripted something like this for CR)
21:10:31<!Newton> that means, focus on melee and race, tools and weapons rather than buildings and such (until the OCM), right?
21:10:48<!Maikel> Yes, but if we provide like 5-10 scenario's (Melee's & Races) we can have our first "release"
21:11:03<!Zapper> I am still eager to build the weapons system :]
21:11:16<!Maikel> Yes newton
21:11:27<!Mimmo_O> imo we need bows, muskets, swords, shields
21:11:29<!Sven2> Concerning Races: I thought about calling them "Parcour" instead
21:11:30<!Mimmo_O> maybe axes
21:11:32<!Maikel> Has anyone something against this plan?
21:11:33<!Sven2> So we'd have a new name :)
21:11:39<!Mimmo_O> sven: good idea
21:11:42<!Zapper> I dont @maikel
21:11:51<!ck> Sounds reasonable. Might be good to be a bit more specific though.
21:11:54<!Mimmo_O> me neither
21:11:57<!Zapper> But we should also do the planned landscape improvements before the first "release"
21:12:03-!- Randrian_ [~randrian@euirc-a663a039.83.171.156.179.ip-pool.NEFkom.net] has quit [Ping timeout]
21:12:08<!Maikel> Yes that's what I'd like to do now
21:12:10<!Zapper> Be it proper hiding of the pixels (as discussed) or the polygon stuff
21:12:22<!Newton> that goal is very reachable, I think. Too bad that this means that we dont do anything with production lines, buildings, mining etc. (until then at least). But the good thing is that we are not dependent on the dialog system up and running -> I can start with gamepad controls
21:12:48<!Newton> what landscape improvements, Zapper?
21:12:53<!Newton> ah
21:13:11<!Zapper> I mean, I zoomed in (to be able to see my Clonks!) and was like ":("
21:13:14<!Maikel> Personally I prefer settling too, but well Melee's are played so much more.
21:13:20<!Sven2> I think, most importantly, the landscape shouldn't be a blurry mess when zoomed in
21:13:30<!Mimmo_O> agreed
21:13:51<!Newton> well, I have been working on the polygon stuff but it is now frozen. It's my bachelors work and needs more time now (needs to be scientific and stuff ;-) )
21:14:05<!ck> This basically requires higher resolved textures, right?
21:14:11<!Newton> I'll probably work on that after I finished gamepad controls and my exams are over
21:14:17<!Sven2> I think PeterW had a simple approach to use a 3x zooming algorithm
21:14:22<!Sven2> (gp3x?)
21:14:27<!Mimmo_O> (textures, i posted a link in the forum for cool ice-textures)
21:14:32<!Mimmo_O> (hahaha, "cool ice textures")
21:15:00<!ck> Sven2: I think the straight-forward way turned out to be too slow performance-wise if I remember correctly
21:15:07-!- JC-weg is now known as JCaesar
21:15:24<!ck> I'm not sure this was the end of the story though
21:15:29<!Sven2> Zooming the 8 bit landscape with some algorithm, then turn texture indices into textures in a shader?
21:17:13<!ck> Is there another way?
21:17:21<!Maikel> Should we start specifying what needs to be done to reach the goal(Etherpad?)
21:17:43<!Newton> mh
21:18:05<!Newton> I guess its clear whats our goal until the last week of march
21:18:26<!Newton> so yeah, I guess we can move to etherpad to do some concepts of what should be inside the "release"
21:18:33< Ape> Aren't we supposed to play with Gobby :D
21:18:47<!Newton> wait a moment
21:18:54<!Maikel> *shameredcheeks* I havn't installed it
21:19:02<!Maikel> afk 2min
21:19:06<!Newton> http://etherpad.com/Clonkpad
21:19:17<!Newton> hmm
21:19:22<!Newton> there is only one document in etherpad?
21:19:32<!ck> Yes, I think so
21:25:33<!Newton> I started a gobby session
21:25:41<!Newton> 92.224.25.239 port 11111 (version 0.4.12 stable)
21:25:43<!Maikel> 4.12?
21:25:46<!Newton> yes
21:25:51<!Maikel> reinstall
21:28:31<!Newton> hm whats that
21:28:38<!Newton> did gobby jsut crash?
21:28:43<!Newton> ah, it was just randrian
21:29:00<!Maikel> How can I see which colour is who?
21:29:27-!- Mortimer [~Martin@euirc-74bf8acf.extern.uni-duisburg-essen.de] has quit [Client exited]
21:29:31<!ck> Maikel: Klick the user list item in the toolbar
21:29:37-!- Randrian_ [~randrian@euirc-1ce9338b.83.171.188.109.ip-pool.NEFkom.net] has joined #openclonk-dev
21:30:11<!Sven2> I cant get into a document...
21:30:53<!ck> touble click an item in the document list, or select one and hit subscribe
21:31:26<!Sven2> Doesnt work
21:31:32<!Sven2> My chat doesnt seem to arrive either
21:32:02-!- Randrian__ [~randrian@euirc-06a781a2.83.171.170.113.ip-pool.NEFkom.net] has quit [Ping timeout]
21:32:08<!Sven2> And I lose connection after a while
21:32:23<!Newton> shit :o
21:34:02<!Sven2> Just changed my color
21:34:14<!Sven2> I can see your chat though
21:34:22<!ck> no idea. Does gobby.0x539.de:6522 work?
21:34:50<!Sven2> I installed the old over the new. Is that a problem?
21:35:35<!Sven2> Where is gobby.0x539.de:6522?
21:35:58<!ck> I can't think of any problems out of my head, but you might try reinstalling it into a clean directory
21:35:58<!Isilkor> newton
21:36:01<!Isilkor> the wiki is broken
21:36:02<!Isilkor> editing pages fails
21:36:21< s_m_w> I cannot get into any documents either. After double clicking, subscribe is greyed out but it still doesn't work
21:36:30<!ck> Use gobby.0x539.de as hostname and 6522 as port. It's another (public) server.
21:37:56<!Sven2> I reinstalled and got in now
21:41:56<!Sven2> Hm. Have to leave for the cinema now
21:43:21<!Maikel> We'll change stuff later I guess
21:43:29<!Maikel> on later occasions.
21:53:18<!Newton> Isilkor: whoa??
21:53:49<!Isilkor> "A database query syntax error has occurred. [...] 1146: Table 'db1144497-wiki.wiki_tag_summary' doesn't exist (localhost)"
21:53:51<!Newton> what page exactly, Isilkor? For me it works
21:53:59<!Newton> hmm
21:54:01<!Isilkor> every page
21:54:19<!Newton> odd, for me it works
21:54:30<!Newton> ill be on that problem as soon as we are done in gobby
21:54:48<!Newton> i hope we can bring it to something substantial
21:55:42-!- Ape [~ape@euirc-7fdc53a9.dhcp.inet.fi] has quit [Client exited]
22:03:59-!- Phantomwipf is now known as Phanto^away
22:04:05-!- Randrian__ [~randrian@euirc-370b466d.83.171.161.68.ip-pool.NEFkom.net] has joined #openclonk-dev
22:06:04-!- Randrian_ [~randrian@euirc-1ce9338b.83.171.188.109.ip-pool.NEFkom.net] has quit [Ping timeout]
22:18:07<!Newton> shit
22:18:09<!Newton> gobby crashed
22:18:12<!Newton> someone save it
22:18:58<!ck> hrm
22:18:58<!ck> done
22:19:07<!Newton> can you reopen it?
22:19:09<!Mimmo_O> hab
22:19:24<!Mimmo_O> just reopen
22:19:45<!ck> on 0x539.de only, don't have access to the firewall here
22:20:02<!Newton> meaning you cant host?
22:20:06<!Mimmo_O> Newton, just rehost, ill paste everything
22:20:19<!ck> in that case all colors are lost
22:20:24<!Newton> oh, crashed again
22:20:26<!Newton> I'll reopen
22:20:45<!Newton> if you give me the session file
22:20:57<!Mimmo_O> they will also be lost if you save normally
22:21:16<!Newton> normally no
22:21:18<!Mimmo_O> i could only save the documents
22:21:23<!ck> mom
22:22:12<!Mimmo_O> whatever, i have to go
22:22:28<!Newton> yeah, it took really long
22:22:43<!ck> http://www-ekp.physik.uni-karlsruhe.de/~burgmeier/gobby.obby
22:22:46<!Newton> I want to try to get that meeting to an end too
22:23:23<!Newton> but the gobby session is the last point anyway
22:23:24<!Mimmo_O> if it does not work
22:23:28<!Mimmo_O> http://de.wiki.nosebud.de/paste/xlK44YJo.html
22:23:41<!Newton> because the distribution of work is already in the session
22:23:45<!Newton> reopen
22:24:05<!Mimmo_O> im off now
22:24:12<!Maikel> ok
22:24:18<!Maikel> cu
22:24:23<!Mimmo_O> good night
22:24:26<!ck> cya
22:24:35-!- Mimmo_O [~mimmoisgr@euirc-ae063962.dip0.t-ipconnect.de] has quit [Quit: ]
22:35:46<!Newton> err
22:35:51<!Newton> someone save the session please
22:36:01<!Newton> perhaps its just Randrian pinging out
22:36:38<!ck> it's still running, isn't it?
22:37:10-!- Randrian_ [~randrian@euirc-27f0becc.83.171.182.120.ip-pool.NEFkom.net] has joined #openclonk-dev
22:41:06-!- Randrian__ [~randrian@euirc-370b466d.83.171.161.68.ip-pool.NEFkom.net] has quit [Ping timeout]
22:44:32<!Newton> this meeting was even longer then I expected
22:44:41<!Newton> I'll summarize the Gobby session
22:45:14<!Maikel> Isolko-r would do the log
22:45:15<!Newton> and try to fix the wiki so that Isilkor can post the summary of the status updates (and point 3) in the wiki
22:45:27<!Newton> isilkor was not in the session
22:45:34<!Maikel> of irc
22:45:46<!ck> I can add the log of the gobby session
22:45:47<!Newton> thats what i said
22:46:21<!Newton> but first ill eat something. after that, wiki.
22:46:39<!Maikel> For next meetings anyone who is willing to contribute should be invited, and we should set up some guidelines to make the meetings shorter
22:48:48-!- stevi is now known as stevi`off
22:48:52<!ck> true. I still hope this was only so long because it was the first one
22:49:14<!ck> Maybe we'll also get some experience in constraining ourselves to the agenda :)
22:49:33<!Maikel> In our dreams maybe :P
22:49:44<!ck> Heh, give us a chance :)
22:49:51<!Newton> phew, by the way
22:50:04-!- Luchs^away is now known as Luchs
22:50:09<!Newton> i find a meeting over IRC a lot more tiresome then in real life
22:50:12<!Newton> but it was 4 hours too
22:50:31-!- Mortimer [~Mortimer@euirc-82816ebb.dip.t-dialin.net] has joined #openclonk-dev
22:51:26<!Maikel> You should do your thesis on teleportation ;)
22:51:48<!ck> we can try video conferencing next time :P
22:55:10<!Maikel> Got to go "The emergence of gravity through holographic scenario" is waiting for me at 9:00
22:55:13<!Maikel> Bye
22:56:51-!- Maikel [~maikeldev@euirc-49e109b6.speed.planet.nl] has quit [Life is too colorful...]
22:59:23<!Newton> ck, can you reproduce isilkors problem?
22:59:41<!ck> Newton: let me check. Just try to edit any page?
23:00:07<!Newton> yes
23:00:23<!Newton> for me, it works. Thats why im puzzled
23:00:25<!Isilkor> for example http://wiki.openclonk.org/index.php?title=Main_Page&action=edit
23:00:31<!Isilkor> A database query syntax error has occurred. This may indicate a bug in the software. The last attempted database query was:
23:00:33<!Isilkor> (SQL query hidden)
23:00:35<!Isilkor> from within function "IndexPager::reallyDoQuery (LogPager)". MySQL returned error "1146: Table 'db1144497-wiki.wiki_tag_summary' doesn't exist (localhost)".
23:00:51<!ck> Hm. Anybody knows my wiki password? %(
23:01:07<!ck> ah
23:01:08<!Newton> ah, right
23:01:16<!ck> yeah, same error
23:01:18<!Newton> for Project, it does not appear
23:01:21<!Newton> but for the homepage
23:01:32<!ck> by clicking Isilkor's link, that is
23:01:52<!ck> I can edit the page though when I navigate properly
23:02:01<!Isilkor> I got there by navigating properly :(
23:02:03<!ck> (I just added "This is a test" at the bottom of the main page)
23:02:27<!ck> ah
23:02:33<!ck> It only occurs for the Main Page for me
23:02:37<!Isilkor> Actually, I get this for History as ell
23:02:38<!ck> But I can edit the Project page for example
23:03:05<!Newton> well, yes the table does not exist
23:03:14<!Newton> the thing is
23:03:32<!Newton> the day before yesterday, i updated to the newest stable mediawiki
23:03:49<!Isilkor> http://wiki.openclonk.org/w/Special:RecentChanges does it too
23:03:51<!Newton> and during upload of the new files, I saw that I already had the newest update, I just forgot to write it down
23:03:55<!Isilkor> so something major is broken I think
23:04:17<!Newton> so I stopped replacing the files during the FTP upload (but not IN one file, after one file)
23:04:33<!Newton> because i assumed i could only have replaced the same files with the same files
23:04:37<!Newton> guess it wasnt the case
23:04:44<!Newton> so what ill do is reinstall the whole thing
23:04:54<!Newton> and the uploading via FTP takes ages
23:05:27-!- Kohlrabi [~Kohlrabi@euirc-621841f3.nosebud.de] has joined #openclonk-dev
23:05:37-!- Randrian__ [~randrian@euirc-be85727b.83.171.153.191.ip-pool.NEFkom.net] has joined #openclonk-dev
23:07:21<!Newton> during the upload I'll disable the wiki
23:09:32-!- Randrian_ [~randrian@euirc-27f0becc.83.171.182.120.ip-pool.NEFkom.net] has quit [Ping timeout]
23:12:16<!Newton> Zapper: till when are you still online?
23:12:26<!Zapper> till clonkine lets me go
23:12:46<!Newton> we wanted to talk about weapon systems and base objects
23:13:17<!Zapper> uh
23:13:18<!Zapper> mh
23:13:25< clonkine> she won'T
23:14:24<!Zapper> hm
23:14:44<!Zapper> I think I am too tired right now - tomorrow maybe?
23:15:47-!- Icewing [~Icewing@euirc-d575d80d.pool.mediaWays.net] has quit [Client exited]
23:15:49<!Newton> ok, maybe
23:19:57-!- s_m_w is now known as smw
23:44:41<!Newton> ck?
23:48:35<!ck> Newton
23:48:46< clonkine> ck, newton?
23:48:49< clonkine> ;)
23:49:08<!Newton> you said during the status update that you are basically trying to get the swimming right
23:49:14<!Newton> with all these stack-changes
23:49:23<!ck> right
23:49:26<!Newton> but what about günthers proposal to just use SetObjDrawTransform?
23:50:03<!Newton> for rotation
23:50:07<!ck> I'd like to avoid SetObjDrawTransform if possible
23:50:16<!ck> But that's not even the point
23:50:33<!ck> The problem is not only with the swimming but with the animation blending
23:50:48<!ck> so the same problem of incorrect blending might happen for other animations as well
23:51:17<!Newton> ah, well then
23:52:01<!Newton> I just think that providing 4 different swimming animations for every direction one seems to be the wrong approach
23:52:12<!Newton> better would be, to be able to set a rotation of the animation
23:52:33<!Newton> because i can really imagine that we want to rotate the clonk while climbing or hangling a little
23:52:39<!Newton> yeah even while running
23:53:05<!Newton> and partly really much while jumping and tumbling
23:53:45<!ck> that can also be done via an animation... i'm not even sure it will look correct when just rotating one animation either
23:53:46<!Newton> having to create animations which are oriented slightly differently seems to be... err not the right way
23:54:22<!Newton> you mean a general "rotate" animation that is combineable with any other animation?
23:55:15<!ck> I had a different one for every possible animation in mind
23:55:26<!ck> Though I'm not sure what makes most sense there from a modelling point of view
23:55:43<!ck> that is, whether there would be a difference in rotation for walking/climbing
23:56:04<!Newton> for walking and climbing... yeah for that you might be right
23:56:21<!Newton> but definitely not for jumping and not for hangling
23:58:07<!ck> Maybe let's just try out both ways and see which one works better
23:58:30<!ck> or try one, and switch if we encounter inherent problems
23:58:56<!ck> But I think these kind of problems can be solved by trying things out and experimenting rather than by thinking too much ;)</pre>

Style Guidelines

2009-11-08T14:41:51Z

Isilkor: Missing "you" added

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. Mercurial provides
an extension named ''win32text'' you can use to auto-convert files from your
OS's native format to single LF and vice-versa.

==== 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 (")"). Unary operators do not require spaces. 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

User talk:Isilkor/Style Guidelines

2009-10-24T16:56:30Z

Isilkor: moved User talk:Isilkor/Style Guidelines to Talk:Style Guidelines: These are now policy

#REDIRECT [[Talk:Style Guidelines]]

Talk:Style Guidelines

2009-10-24T16:56:30Z

Isilkor: moved User talk:Isilkor/Style Guidelines to Talk:Style Guidelines: These are now policy

Responses so far:
[[User:Günther|Günther]]:
* local headers before system headers
* don't forbid public data members
* <!Guenther> Demanding Doygen comments is also a very radical change
: <!Guenther> Doxygen is only really usefull if you are generating API docs that are intended to be read without looking at the source code
: <!Guenther> That's not a use case for us: our API is C4Script, not some C++ API

PeterW:
* order switch members by numeric value

Afterthoughts [[User:Isilkor|Isilkor]]:
* Use forward declarations instead of including the header inside other headers, if possible.

Opinions:
* Use anonymous namespaces instead of static: '''In favor:''' ck, Isilkor; '''Against:''' Günther, PeterW
* Doxygen comments: '''In favor:'''; '''Against:''' Günther, PeterW

The document should describe reality, not wishful thinking. Where reality is inconsistent, the document can describe which of several options is preferred, but it shouldn't contain anything that's not already in somewhat widespread use. That would mean changing the coding style, and that's not the job of a coding style document. --[[User:Günther|Günther]] 16:41, 4 August 2009 (UTC)
: The document is intended to describe guidelines for new code, and not the legacy code that's all over the place anyway. While it's probably preferable to change old code if you do work in the vicinity, I certainly don't expect the code to be changed/reformatted on its own. --[[User:Isilkor|Isilkor]] 17:35, 4 August 2009 (UTC)
:: I think the intention of a Coding Style document should be to ensure uniformity. For that, you have to describe what's already in use. And the Clonk source code really is not that much "all over the place". For example, the majority of files use indented braces, thus the coding style has to prescribe that, however much we would want to have another brace style. --[[User:Günther|Günther]] 11:36, 5 August 2009 (UTC)
::: No, it really '''is''' all over the place. Just take a look at standard. It's not even uniform within single files. There's mixed brace styles, tabs and spaces are both used for indenting (sometimes interspersed in the same function), you have a healthy mix of formatting in "section heading" comments, and so on. --[[User:Isilkor|Isilkor]] 14:01, 5 August 2009 (UTC)
:::: I'd argue that those are exceptions. Almost all new code uses tabs, only old code differs and when somebody configured their editor for two-space-tabs and I didn't notice the issue. (If you do configure your editor for two-space-tabs, the all-over-the-placeness vanishes from sight ;-), so I do not recommend that.) The brace style is a bigger issue because nobody tried to enforce uniformity there, but on the other hand I think the old code is more consistent in that regard, and overall there's a clear majority. Section heading comments are inconsistent, true, but they are also rare.--[[User:Günther|Günther]] 15:57, 5 August 2009 (UTC)
I would not restrict the order of case labels in a switch. But if we do, then I agree with PeterW that they should be ordered by numeric value (which, for enumeration values, is mostly the same as the order the enumerators are defined). Maybe we also want to note that for commenting out code, #if 0 is preferred. I am generally okay with these guidelines, though I'm likely to have problems with a few I'm not used to, especially the pointer asterisk position and the space following if/while/for. When I am writing code then I am paying attention to the code and not the style, and I often fall back to my own style without even noticing. So please don't punch me if I check in code that doesn't strictly obey the guidelines. --[[User:Clonk-Karl|Clonk-Karl]] 00:23, 5 August 2009 (UTC)

User:Isilkor/Style Guidelines

2009-10-24T16:56:30Z

Isilkor: moved User:Isilkor/Style Guidelines to Style Guidelines: These are now policy

#REDIRECT [[Style Guidelines]]

Style Guidelines

2009-10-24T16:56:30Z

Isilkor: moved User:Isilkor/Style Guidelines to Style Guidelines: These are now policy

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. Mercurial provides
an extension named ''win32text'' you can use to auto-convert files from your
OS's native format to single LF and vice-versa.

==== 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 (")"). Unary operators do not require spaces. 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2009-10-14T16:24:12Z

Isilkor: Line endings

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. Mercurial provides
an extension named ''win32text'' you can use to auto-convert files from your
OS's native format to single LF and vice-versa.

==== 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 (")"). Unary operators do not require spaces. 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2009-10-13T20:34:00Z

Isilkor: /* Preprocessor Macros */ Remove aligning of macro line continuations, since tab width may vary

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 ===
==== 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 (")"). Unary operators do not require spaces. 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2009-08-15T14:04:35Z

Isilkor: /* Braces */ Amending brace style in accordance with the style poll (see forum for details)

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 ===
==== 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 (")"). Unary operators do not require spaces. 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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. If your macro spans multiple lines,
align the backslashes. 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Talk:Style Guidelines

2009-08-05T14:01:20Z

Isilkor:

Responses so far:
[[User:Günther|Günther]]:
* local headers before system headers
* don't forbid public data members
* <!Guenther> Demanding Doygen comments is also a very radical change
: <!Guenther> Doxygen is only really usefull if you are generating API docs that are intended to be read without looking at the source code
: <!Guenther> That's not a use case for us: our API is C4Script, not some C++ API

PeterW:
* order switch members by numeric value

Afterthoughts [[User:Isilkor|Isilkor]]:
* Use forward declarations instead of including the header inside other headers, if possible.

Opinions:
* Use anonymous namespaces instead of static: '''In favor:''' ck, Isilkor; '''Against:''' Günther, PeterW
* Doxygen comments: '''In favor:'''; '''Against:''' Günther, PeterW

The document should describe reality, not wishful thinking. Where reality is inconsistent, the document can describe which of several options is preferred, but it shouldn't contain anything that's not already in somewhat widespread use. That would mean changing the coding style, and that's not the job of a coding style document. --[[User:Günther|Günther]] 16:41, 4 August 2009 (UTC)
: The document is intended to describe guidelines for new code, and not the legacy code that's all over the place anyway. While it's probably preferable to change old code if you do work in the vicinity, I certainly don't expect the code to be changed/reformatted on its own. --[[User:Isilkor|Isilkor]] 17:35, 4 August 2009 (UTC)
:: I think the intention of a Coding Style document should be to ensure uniformity. For that, you have to describe what's already in use. And the Clonk source code really is not that much "all over the place". For example, the majority of files use indented braces, thus the coding style has to prescribe that, however much we would want to have another brace style. --[[User:Günther|Günther]] 11:36, 5 August 2009 (UTC)
::: No, it really '''is''' all over the place. Just take a look at standard. It's not even uniform within single files. There's mixed brace styles, tabs and spaces are both used for indenting (sometimes interspersed in the same function), you have a healthy mix of formatting in "section heading" comments, and so on. --[[User:Isilkor|Isilkor]] 14:01, 5 August 2009 (UTC)
I would not restrict the order of case labels in a switch. But if we do, then I agree with PeterW that they should be ordered by numeric value (which, for enumeration values, is mostly the same as the order the enumerators are defined). Maybe we also want to note that for commenting out code, #if 0 is preferred. I am generally okay with these guidelines, though I'm likely to have problems with a few I'm not used to, especially the pointer asterisk position and the space following if/while/for. When I am writing code then I am paying attention to the code and not the style, and I often fall back to my own style without even noticing. So please don't punch me if I check in code that doesn't strictly obey the guidelines. --[[User:Clonk-Karl|Clonk-Karl]] 00:23, 5 August 2009 (UTC)

Style Guidelines

2009-08-05T10:50:38Z

Isilkor: /* Comments */

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 ===
==== 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. Braces around <tt>else</tt> may stand on the same
line as the <tt>else</tt>. 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 (")"). Unary operators do not require spaces. 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. Make sure you write enough text to
* warrant a multi-line comment. Also be sure to write in full sentences.
*/

//
// You may also write multi-line comments like this. Using C++-style comments
// helps if you need to comment out large pieces of code later. Of course you
// could still use #if 0 ... #endif to achieve that.
//

==== 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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. If your macro spans multiple lines,
align the backslashes. 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2009-08-05T09:31:40Z

Isilkor: /* Comments */ C++ style comments okay for ML also

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 ===
==== 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. Braces around <tt>else</tt> may stand on the same
line as the <tt>else</tt>. 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 (")"). Unary operators do not require spaces. 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. Make sure you write enough text to
* warrant a multi-line comment. Also be sure to write in full sentences.
*/

//
// You may also write multi-line comments like this. Using C++-style comments
// helps if you need to comment out large pieces of code. Of course you could
// still use #if 0 ... #endif to achieve that.
//

==== 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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. If your macro spans multiple lines,
align the backslashes. 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2009-08-05T09:26:00Z

Isilkor: /* Preprocessor Macros */ Undefine macro after use

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 ===
==== 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. Braces around <tt>else</tt> may stand on the same
line as the <tt>else</tt>. 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 (")"). Unary operators do not require spaces. 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. 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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. If your macro spans multiple lines,
align the backslashes. 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>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2009-08-05T09:21:46Z

Isilkor: Change ordering, removed Doxygen requirement

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 ===
==== 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. Braces around <tt>else</tt> may stand on the same
line as the <tt>else</tt>. 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 (")"). Unary operators do not require spaces. 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. 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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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, 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. If your macro spans multiple lines,
align the backslashes.

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

int *foo, *bar;
char *Qux(const char *quux);

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

Style Guidelines

2009-08-04T19:04:46Z

Isilkor: Doxygen not in favor. ;)

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.

// Single-line comments look like this

//
// Very important single-line comments look like this
//

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

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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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.

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 system headers first. Put the filename in angle brackets, and use
forward slashes as directory separators.

#include <vector>

Leave a blank line before local headers. Use double quotes to include these,
and sort them alphabetically.

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

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, 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. If your macro spans multiple lines,
align the backslashes.

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

Do not use the Win32 style integer declarations <tt>DWORD</tt> and
<tt>BOOL</tt>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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);

No class member variable should be declared <tt>public</tt>. Use
<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.

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.

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

Do not use C-style casts. Use a template cast instead.

<s>All classes and functions should have a comment explaining their purpose. This
comment is prepended to the prototype or class definition. If the function is
a local function without a prototype, it goes directly in front of the
definition. The comment uses [http://www.doxygen.org/ Doxygen] formatting.

/**
* Make light.
* \param book Object to enlighten.
*/
void Frotz(Spellbook *book);</s>

Elements in a <tt>switch</tt> statement are ordered alphabetically unless
parts of the <tt>switch</tt> cascade. Cascades 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");
}

Keywords (<tt>while</tt>, <tt>for</tt> etc.) are followed by a space. 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 */;

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

Braces are on their own line, on the same level of indentation as the
structure they belong to. Braces around <tt>else</tt> may stand on the same
line as the <tt>else</tt>. 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");
}

Function names are not followed by space. Commas are. No space follows opening
brackets ("[") or parentheses ("("). Also no space preceeds closing brackets
("]") or parentheses (")"). Unary operators do not require spaces. Binary
operators do.

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.

Talk:Style Guidelines

2009-08-04T17:35:42Z

Isilkor: Intended for new code

Talk:Style Guidelines

2009-08-04T15:34:01Z

Isilkor:

Talk:Style Guidelines

2009-08-04T15:00:53Z

Isilkor: fwd decls

Responses so far:
[[User:Günther|Günther]]:
* local headers before system headers
* use static instead of anonymous namespaces
* don't forbid public data members
* <!Guenther> Demanding Doygen comments is also a very radical change
: <!Guenther> Doxygen is only really usefull if you are generating API docs that are intended to be read without looking at the source code
: <!Guenther> That's not a use case for us: our API is C4Script, not some C++ API
Afterthoughts [[User:Isilkor|Isilkor]]:
* Use forward declarations instead of including the header inside other headers, if possible.

Talk:Style Guidelines

2009-08-04T00:17:28Z

Isilkor: Responses: Günther

Style Guidelines

2009-08-03T23:24:59Z

Isilkor: Draft of style guidelines

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.

// Single-line comments look like this

//
// Very important single-line comments look like this
//

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

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. If you choose to add yourself, use your real name,
not a nickname. Legally recognized pseudonyms are accepted, as are names of
legal entities. If you don't want to add yourself, you may add the catch-all
copyright attribution phrase, if it does not already exist.

/*
* OpenClonk, http://www.openclonk.org
*
* Copyright (c) 2000-2009 John Doe
* Copyright (c) 2005 Jane Q. Public
*
* Portions might be copyrighted by other authors who have contributed
* to OpenClonk.
*
* 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.

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 system headers first. Put the filename in angle brackets, and use
forward slashes as directory separators.

#include <vector>

Leave a blank line before local headers. Use double quotes to include these,
and sort them alphabetically.

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

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, 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. If your macro spans multiple lines,
align the backslashes.

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

Do not use the Win32 style integer declarations <tt>DWORD</tt> and
<tt>BOOL</tt>. 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.

int *foo, *bar;
char *Qux(const char *quux);

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);

No class member variable should be declared <tt>public</tt>. Use
<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.

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.

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

Do not use C-style casts. Use a template cast instead.

All classes and functions should have a comment explaining their purpose. This
comment is prepended to the prototype or class definition. If the function is
a local function without a prototype, it goes directly in front of the
definition. The comment uses [http://www.doxygen.org/ Doxygen] formatting.

/**
* Make light.
* \param book Object to enlighten.
*/
void Frotz(Spellbook *book);

Elements in a <tt>switch</tt> statement are ordered alphabetically unless
parts of the <tt>switch</tt> cascade. Cascades 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");
}

Keywords (<tt>while</tt>, <tt>for</tt> etc.) are followed by a space. 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 */;

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

Braces are on their own line, on the same level of indentation as the
structure they belong to. Braces around <tt>else</tt> may stand on the same
line as the <tt>else</tt>. 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");
}

Function names are not followed by space. Commas are. No space follows opening
brackets ("[") or parentheses ("("). Also no space preceeds closing brackets
("]") or parentheses (")"). Unary operators do not require spaces. Binary
operators do.

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.