Development: Difference between revisions
No edit summary |
m Remove MigrateTranslation template: all translation migrated |
||
(12 intermediate revisions by 6 users not shown) | |||
Line 1: | Line 1: | ||
<languages /> | |||
<languages/> | |||
<translate> | <translate> | ||
<!--T:1--> | <!--T:1--> | ||
Line 6: | Line 6: | ||
== Your development environment == <!--T:2--> | ==Your development environment== <!--T:2--> | ||
<!--T:3--> | <!--T:3--> | ||
It is extremely recommended to set up a Linux environment to begin programming in DDNet for the following reasons (as of now): | It is extremely recommended to set up a Linux environment to begin programming in DDNet for the following reasons (as of now): | ||
* Most DDNet contributors actually use Linux to contribute. | *Most DDNet contributors actually use Linux to contribute. | ||
* Easier package management, you can easily install all the needed libraries and begin contributing. | *Easier package management, you can easily install all the needed libraries and begin contributing. | ||
* This article doesn't have yet a Windows version and is focused on Linux. | *This article doesn't have yet a Windows version and is focused on Linux. | ||
<!--T:4--> | <!--T:4--> | ||
First | First and foremost, DDNet is coded using the C++ programming language, you will need to be fairly familiar with it, but you can also know the basics and learn more with it. | ||
<!--T:5--> | <!--T:5--> | ||
Some useful resources to learn C++: | Some useful resources to learn C++: | ||
* [https://www.learncpp.com/ learncpp.com] | *[https://www.learncpp.com/ learncpp.com] | ||
* [https://en.cppreference.com/w/ cppreference.com] | *[https://en.cppreference.com/w/ cppreference.com] | ||
* Your search engine of preference | *Your search engine of preference | ||
<!--T:6--> | <!--T:6--> | ||
Line 30: | Line 30: | ||
== Getting the source code == <!--T:8--> | ==Getting the source code== <!--T:8--> | ||
<!--T:9--> | <!--T:9--> | ||
Line 39: | Line 39: | ||
== Installing the dependencies == <!--T:11--> | ==Installing the dependencies== <!--T:11--> | ||
<!--T:12--> | <!--T:12--> | ||
Line 48: | Line 48: | ||
<!--T:14--> | <!--T:14--> | ||
< | <syntaxhighlight lang="bash"> | ||
sudo pacman -S --needed base-devel cmake curl ffmpeg freetype2 git glew glslang gmock libnotify libpng opusfile python rust sdl2 spirv-tools sqlite vulkan-headers vulkan-icd-loader wavpack x264 | |||
</syntaxhighlight> | |||
<!--T:71--> | |||
For Debian: | For Debian: | ||
< | <!--T:72--> | ||
<syntaxhighlight lang="bash"> | |||
sudo apt install build-essential cargo cmake git glslang-tools google-mock libavcodec-extra libavdevice-dev libavfilter-dev libavformat-dev libavutil-dev libcurl4-openssl-dev libfreetype6-dev libglew-dev libnotify-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsqlite3-dev libssl-dev libvulkan-dev libwavpack-dev libx264-dev python3 rustc spirv-tools | |||
</syntaxhighlight> | |||
== Compiling DDNet == <!--T:15--> | ==Compiling DDNet== <!--T:15--> | ||
<!--T:16--> | <!--T:16--> | ||
Line 68: | Line 74: | ||
== General information == <!--T:18--> | ==General information== <!--T:18--> | ||
<!--T:19--> | <!--T:19--> | ||
Here are some general bits of information: | Here are some general bits of information: | ||
* Currently, the source code is compiled with the C++17 standard, but you will see that many parts of the code are more C-like since only mostly new code uses C++17 stuff. | *Currently, the source code is compiled with the C++17 standard, but you will see that many parts of the code are more C-like since only mostly new code uses C++17 stuff. | ||
* <code>std::string</code> is rarely used, char arrays plus using <code>system.h</code> methods for handling them are the norm. | *<code>std::string</code> is rarely used, char arrays plus using <code>system.h</code> methods for handling them are the norm. | ||
* Most I/O code, formatting and printing is done using <code>system.h</code> provided methods. | *Most I/O code, formatting and printing is done using <code>system.h</code> provided methods. | ||
== The source code layout == <!--T:20--> | ==The source code layout== <!--T:20--> | ||
<!--T:21--> | <!--T:21--> | ||
Line 83: | Line 89: | ||
=== The src/base directory === <!--T:22--> | ===The src/base directory=== <!--T:22--> | ||
<!--T:23--> | <!--T:23--> | ||
Line 89: | Line 95: | ||
=== The src/engine directory === <!--T:24--> | ===The src/engine directory=== <!--T:24--> | ||
<!--T:25--> | <!--T:25--> | ||
Line 95: | Line 101: | ||
=== The src/game directory === <!--T:26--> | ===The src/game directory=== <!--T:26--> | ||
<!--T:27--> | <!--T:27--> | ||
Line 101: | Line 107: | ||
==== Server side ==== <!--T:28--> | ====Server side==== <!--T:28--> | ||
<!--T:29--> | <!--T:29--> | ||
Line 113: | Line 119: | ||
<!--T:32--> | <!--T:32--> | ||
* [https://github.com/ddnet/ddnet/blob/master/src/game/server/entities/character.h CCharacter]: Represents a [[Special:MyLanguage/Common_Terminology#Tee|tee]] that is alive, it is instantiated when a tee spawns and deleted when it dies. | *[https://github.com/ddnet/ddnet/blob/master/src/game/server/entities/character.h CCharacter]: Represents a [[Special:MyLanguage/Common_Terminology#Tee|tee]] that is alive, it is instantiated when a tee spawns and deleted when it dies. | ||
* [https://github.com/ddnet/ddnet/blob/master/src/game/server/player.h CPlayer] contains information not related to the [[Common Terminology/fr#Tee|Tee]] (nickname, flag, etc.). | |||
==== Client side ==== <!--T:33--> | ====Client side==== <!--T:33--> | ||
<!--T:34--> | <!--T:34--> | ||
The client side is made up of components, these are classes that inherit <code> | The client side is made up of components, these are classes that inherit [https://github.com/ddnet/ddnet/blob/master/src/game/client/component.h CComponent] defined in <code>src/game/client/component.h</code>. These components can implement the virtual methods such as <code>OnInit</code>, <code>OnMessage</code>, etc. to provide their functionality. | ||
==== Networking ==== <!--T:35--> | ====Networking==== <!--T:35--> | ||
<!--T:36--> | <!--T:36--> | ||
Line 128: | Line 135: | ||
== Code conventions == <!--T:37--> | ==Code conventions== <!--T:37--> | ||
<!--T:38--> | <!--T:38--> | ||
Line 137: | Line 144: | ||
=== Indentation style === <!--T:40--> | ===Indentation style=== <!--T:40--> | ||
<!--T:41--> | <!--T:41--> | ||
Line 156: | Line 163: | ||
<!--T:44--> | <!--T:44--> | ||
FinalThing(); | |||
</syntaxhighlight> | </syntaxhighlight> | ||
===Classes and Structs=== <!--T:45--> | |||
=== Classes and Structs === <!--T:45--> | |||
<!--T:46--> | <!--T:46--> | ||
Line 177: | Line 183: | ||
=== Enums and constants === <!--T:49--> | ===Enums and constants=== <!--T:49--> | ||
<!--T:50--> | <!--T:50--> | ||
Should be screaming snake case, for example: <code>MAX_PLAYERS</code> | Should be ''screaming snake case [https://en.wikipedia.org/wiki/Snake_case]'', for example: <code>MAX_PLAYERS</code> | ||
<!--T:51--> | <!--T:51--> | ||
Line 197: | Line 203: | ||
=== Variable naming === <!--T:52--> | ===Variable naming=== <!--T:52--> | ||
<!--T:53--> | <!--T:53--> | ||
* The names of variables contain 3 parts: qualifier, prefix and name. | *The names of variables contain 3 parts: qualifier, prefix and name. | ||
* Variable names should start with uppercase unless they are 1 char long without any prefix or qualifier, for example: <code>i</code>, <code>x</code>, <code>y</code>. | *Variable names should start with uppercase unless they are 1 char long without any prefix or qualifier, for example: <code>i</code>, <code>x</code>, <code>y</code>. | ||
* Variables can have more than 1 qualifier (or zero) and more than 1 prefix (or zero). | *Variables can have more than 1 qualifier (or zero) and more than 1 prefix (or zero). | ||
<!--T:54--> | <!--T:54--> | ||
Line 208: | Line 214: | ||
==== Qualifiers ==== <!--T:55--> | ====Qualifiers==== <!--T:55--> | ||
<!--T:56--> | <!--T:56--> | ||
* <code>m</code> for member variables: <code>m_MyVariable</code>. | *<code>m</code> for member variables: <code>m_MyVariable</code>. | ||
* <code>s</code> for static variables: <code>s_MyStaticVariable</code>, <code>ms_MyStaticMemberVariable</code>. | *<code>s</code> for static variables: <code>s_MyStaticVariable</code>, <code>ms_MyStaticMemberVariable</code>. | ||
* <code>g</code> for global variables with external linkage: <code>gs_MyGlobalStaticVar</code>. | *<code>g</code> for global variables with external linkage: <code>gs_MyGlobalStaticVar</code>. | ||
==== Prefixes ==== <!--T:57--> | ====Prefixes==== <!--T:57--> | ||
<!--T:58--> | <!--T:58--> | ||
* <code>p</code> for pointers: <code>pMyPointer</code>, <code>m_pCharacter</code>, <code>ppMyPointerToPointer</code>. | *<code>p</code> for pointers: <code>pMyPointer</code>, <code>m_pCharacter</code>, <code>ppMyPointerToPointer</code>. | ||
* <code>a</code> for arrays: <code>aMyArray</code>, <code>aBuf</code>. | *<code>a</code> for arrays: <code>aMyArray</code>, <code>aBuf</code>. | ||
* <code>v</code> for <code>std::vector</code>s: <code>vMyVector</code>, <code>vpvMyVectorOfPointersToVectors</code>. | *<code>v</code> for <code>std::vector</code>s: <code>vMyVector</code>, <code>vpvMyVectorOfPointersToVectors</code>. | ||
* <code>fn</code> for functions: <code>pfnMyCallback</code>, <code>m_papfnMyPointerToArrayOfCallbacks</code>. | *<code>fn</code> for functions: <code>pfnMyCallback</code>, <code>m_papfnMyPointerToArrayOfCallbacks</code>. | ||
== Common snippets == <!--T:59--> | ==Common snippets== <!--T:59--> | ||
<!--T:60--> | <!--T:60--> | ||
Line 231: | Line 237: | ||
=== Formatting text === <!--T:61--> | ===Formatting text=== <!--T:61--> | ||
<!--T:62--> | <!--T:62--> | ||
Line 239: | Line 245: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:63--> | |||
=== Iterating over all players === | See [https://cplusplus.com/reference/cstdio/printf/ printf documentation] for a list of all format specifiers. | ||
===Iterating over all players=== | |||
<!--T:64--> | <!--T:64--> | ||
Line 252: | Line 259: | ||
=== Printing to the game console === <!--T:65--> | ===Printing to the game console=== <!--T:65--> | ||
<!--T:66--> | <!--T:66--> | ||
Line 260: | Line 267: | ||
=== Debug printing === <!--T:67--> | ===Debug printing=== <!--T:67--> | ||
<!--T:68--> | <!--T:68--> | ||
Line 268: | Line 275: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
<!--T:73--> | |||
===Translating text in the client=== | |||
<code>Localize</code> can be used in the game client to get the translation for a specific string from the language file selected by the user.<syntaxhighlight lang="cpp"> | |||
DoButton(..., Localize("Connect"), ...); | |||
</syntaxhighlight>The string can also contain format specifiers. The translated string must contain the same format specifiers.<syntaxhighlight lang="cpp"> | |||
char aBuf[128]; | |||
str_format(aBuf, sizeof(aBuf), Localize("%d of %d servers"), NumServers, TotalServers); | |||
</syntaxhighlight>A script is used to scan the code for calls to <code>Localize</code> and collect the strings to update the translation files. For this reason, the call to <code>Localize</code> must not contain any other code, or the script cannot determine the text correctly.<syntaxhighlight lang="cpp"> | |||
// Do NOT do this: | |||
const char *pStr = Localize(Team == TEAM_RED ? "Red team" : "Blue team"); | |||
<!--T:74--> | |||
// Do this instead: | |||
const char *pStr = Team == TEAM_RED ? Localize("Red team") : Localize("Blue team"); | |||
</syntaxhighlight> | |||
== External resources == <!--T:69--> | ==External resources== <!--T:69--> | ||
<!--T:70--> | <!--T:70--> | ||
* [https://edgarluque.com/blog/intro-to-ddnet/ An intro to the DDraceNetwork game source code] by [[Special:MyLanguage/User:Ryozuki|Ryozuki]] | *[https://edgarluque.com/blog/ui-code-ddnet/ UI Code in DDraceNetwork] by [[Special:MyLanguage/User:Ryozuki|Ryozuki]] | ||
* [https://edgarluque.com/blog/code-conventions-in-ddnet/ Code conventions in DDraceNetwork] by [[Special:MyLanguage/User:Ryozuki|Ryozuki]] | *[https://edgarluque.com/blog/intro-to-ddnet/ An intro to the DDraceNetwork game source code] by [[Special:MyLanguage/User:Ryozuki|Ryozuki]] | ||
* [https://edgarluque.com/blog/chat-command-ddracenetwork/ Implementing a chat command in DDraceNetwork] by [[Special:MyLanguage/User:Ryozuki|Ryozuki]] | *[https://edgarluque.com/blog/code-conventions-in-ddnet/ Code conventions in DDraceNetwork] by [[Special:MyLanguage/User:Ryozuki|Ryozuki]] | ||
* [https://codedoc.ddnet.org/ Auto generated docs] | *[https://edgarluque.com/blog/chat-command-ddracenetwork/ Implementing a chat command in DDraceNetwork] by [[Special:MyLanguage/User:Ryozuki|Ryozuki]] | ||
* [https://ddnet.org/libtw2-doc/ Technical documentation of Teeworlds file formats and network protocol] | *[https://codedoc.ddnet.org/ Auto generated docs] | ||
* [https://heinrich5991.github.io/blog/blog/one-tick-unfreeze The Anatomy of a One Tick Unfreeze] | *[https://ddnet.org/libtw2-doc/ Technical documentation of Teeworlds file formats and network protocol] | ||
* [https://www.youtube.com/playlist?list=PLhJkqAQmOh5LyYOfnMy4PJB6CSZltQyTc Teeworlds programming YouTube tutorial] by ChillerDragon | *[https://heinrich5991.github.io/blog/blog/one-tick-unfreeze The Anatomy of a One Tick Unfreeze] | ||
*[https://www.youtube.com/playlist?list=PLhJkqAQmOh5LyYOfnMy4PJB6CSZltQyTc Teeworlds programming YouTube tutorial] by [[User:ChillerDragon|ChillerDragon]] | |||
*[https://chillerdragon.github.io/teeworlds-protocol/ Teeworlds 0.6/0.7 network protocol documentation] by [[User:ChillerDragon|ChillerDragon]] | |||
==About Tee Skin Rendering== <!--T:75--> | |||
<!--T:76--> | |||
This section explains how to render a tee skin. | |||
<!--T:77--> | |||
Values put together by Patiga | |||
Special Thanks to Jupstar | |||
Segment Scaling: | |||
body: 100% | |||
feet: 150% | |||
eyes: 120% | |||
eye blink: 45% | |||
hand: 93.75% | |||
Positioning: | |||
64/64 = 1 = width or height of the body segment | |||
body: 4/64 up | |||
feet: | |||
10/64 down | |||
7/64 left/right | |||
eyes: | |||
0.125 up | |||
0.05 left/right | |||
eye movement: | |||
dir = angle of eyes (view angle), right = 0 | |||
eyes: | |||
x: cos(dir) * 0.125 | |||
y: sin(dir) * 0.1 | |||
each eye (away from the other): | |||
x: abs(cos(dir)) * 0.01 | |||
</translate> | </translate> |
Latest revision as of 17:27, 4 May 2024
This article aims to introduce you into DDNet development, since it's an open-source game, it relies on random people kind enough to contribute to it on their free time.
Your development environment
It is extremely recommended to set up a Linux environment to begin programming in DDNet for the following reasons (as of now):
- Most DDNet contributors actually use Linux to contribute.
- Easier package management, you can easily install all the needed libraries and begin contributing.
- This article doesn't have yet a Windows version and is focused on Linux.
First and foremost, DDNet is coded using the C++ programming language, you will need to be fairly familiar with it, but you can also know the basics and learn more with it.
Some useful resources to learn C++:
- learncpp.com
- cppreference.com
- Your search engine of preference
The source code of DDNet is managed using Git, a version control system, an essential tool to collaborate with multiple developers.
If you don't have git yet in your Linux distribution, make sure to install it, for example in most debian/ubuntu based distributions: sudo apt install git
.
Getting the source code
The source code is located on Github, you can get the source code by cloning without the need of an account, but if you want to ever put your changes to the official source code you will need one.
If you are not familiar with git/github you can learn the basics here: Hello World - Github
Installing the dependencies
If you are on Linux, you can install all the needed dependencies by reading the README on the DDNet github page: https://github.com/ddnet/ddnet#dependencies-on-linux--macos
For Arch Linux:
sudo pacman -S --needed base-devel cmake curl ffmpeg freetype2 git glew glslang gmock libnotify libpng opusfile python rust sdl2 spirv-tools sqlite vulkan-headers vulkan-icd-loader wavpack x264
For Debian:
sudo apt install build-essential cargo cmake git glslang-tools google-mock libavcodec-extra libavdevice-dev libavfilter-dev libavformat-dev libavutil-dev libcurl4-openssl-dev libfreetype6-dev libglew-dev libnotify-dev libogg-dev libopus-dev libopusfile-dev libpng-dev libsdl2-dev libsqlite3-dev libssl-dev libvulkan-dev libwavpack-dev libx264-dev python3 rustc spirv-tools
Compiling DDNet
We use CMake to control the compilation process, if you have all the dependencies installed, it's as easy as following these commands (make sure you are on the DDNet folder):
mkdir build
cd build
cmake ..
make -j$(nproc)
General information
Here are some general bits of information:
- Currently, the source code is compiled with the C++17 standard, but you will see that many parts of the code are more C-like since only mostly new code uses C++17 stuff.
std::string
is rarely used, char arrays plus usingsystem.h
methods for handling them are the norm.- Most I/O code, formatting and printing is done using
system.h
provided methods.
The source code layout
Now that you can build DDNet you can begin editing it.
The src/base directory
Since DDNet is a cross-platform game, an abstraction layer over that is needed to make development easier, this directory contains many useful functions to handle that.
The src/engine directory
Here lies the game engine, it handles most stuff that is not gameplay related, such as graphics, sound, network, etc.
The src/game directory
All gameplay related code is here, separated into client and server.
Server side
This game uses its own hierarchical object-oriented entity system, the main class to which all other entities derive from is CEntity
located in src/game/server/entity.h
.
These entities are managed by the game world located here src/game/server/gameworld.h
Some important entities are:
- CCharacter: Represents a tee that is alive, it is instantiated when a tee spawns and deleted when it dies.
- CPlayer contains information not related to the Tee (nickname, flag, etc.).
Client side
The client side is made up of components, these are classes that inherit CComponent defined in src/game/client/component.h
. These components can implement the virtual methods such as OnInit
, OnMessage
, etc. to provide their functionality.
Networking
The network protocol is mostly generated by python scripts that output C++ code, for example, datasrc/network.py
defines all network packets.
Code conventions
The ongoing discussion on code conventions is located here: ddnet#2945
Currently, the following applies:
Indentation style
Allman style is used.
This style puts the brace associated with a control statement on the next line, indented to the same level as the control statement. Statements within the braces are indented to the next level.
while(x == y)
{
Something();
SomethingElse();
}
FinalThing();
Classes and Structs
Must be prefixed by C
(for legacy reasons this is ignored for structs in some places, such as in graphics code) or I
for interfaces. New struct
s should be prefixed by S
.
Example:
class CCharacter : public CEntity
{
// ...
}
Enums and constants
Should be screaming snake case [1], for example: MAX_PLAYERS
enum
{
FAKETUNE_FREEZE = 1,
FAKETUNE_SOLO = 2,
FAKETUNE_NOJUMP = 4,
FAKETUNE_NOCOLL = 8,
FAKETUNE_NOHOOK = 16,
FAKETUNE_JETPACK = 32,
FAKETUNE_NOHAMMER = 64,
};
Variable naming
- The names of variables contain 3 parts: qualifier, prefix and name.
- Variable names should start with uppercase unless they are 1 char long without any prefix or qualifier, for example:
i
,x
,y
. - Variables can have more than 1 qualifier (or zero) and more than 1 prefix (or zero).
These are laid out like this: [qualifiers]_[prefixes][Name]
Qualifiers
m
for member variables:m_MyVariable
.s
for static variables:s_MyStaticVariable
,ms_MyStaticMemberVariable
.g
for global variables with external linkage:gs_MyGlobalStaticVar
.
Prefixes
p
for pointers:pMyPointer
,m_pCharacter
,ppMyPointerToPointer
.a
for arrays:aMyArray
,aBuf
.v
forstd::vector
s:vMyVector
,vpvMyVectorOfPointersToVectors
.fn
for functions:pfnMyCallback
,m_papfnMyPointerToArrayOfCallbacks
.
Common snippets
Here is a list of code that you may frequently see across the codebase:
Formatting text
char aBuf[128];
str_format(aBuf, sizeof(aBuf), "number: %d", 2);
See printf documentation for a list of all format specifiers.
Iterating over all players
for(int i = 0; i < MAX_CLIENTS; i++)
{
// Server-side
CPlayer *pPlayer = GameServer()->m_apPlayers[i];
}
Printing to the game console
Console()->Print(IConsole::OUTPUT_LEVEL_STANDARD, "wikiprint", "Hello from the ddnet wiki!");
Debug printing
int i = 2;
dbg_msg("wikiprint", "Hello from the ddnet wiki: %d", i);
Translating text in the client
Localize
can be used in the game client to get the translation for a specific string from the language file selected by the user.
DoButton(..., Localize("Connect"), ...);
The string can also contain format specifiers. The translated string must contain the same format specifiers.
char aBuf[128];
str_format(aBuf, sizeof(aBuf), Localize("%d of %d servers"), NumServers, TotalServers);
A script is used to scan the code for calls to Localize
and collect the strings to update the translation files. For this reason, the call to Localize
must not contain any other code, or the script cannot determine the text correctly.
// Do NOT do this:
const char *pStr = Localize(Team == TEAM_RED ? "Red team" : "Blue team");
// Do this instead:
const char *pStr = Team == TEAM_RED ? Localize("Red team") : Localize("Blue team");
External resources
- UI Code in DDraceNetwork by Ryozuki
- An intro to the DDraceNetwork game source code by Ryozuki
- Code conventions in DDraceNetwork by Ryozuki
- Implementing a chat command in DDraceNetwork by Ryozuki
- Auto generated docs
- Technical documentation of Teeworlds file formats and network protocol
- The Anatomy of a One Tick Unfreeze
- Teeworlds programming YouTube tutorial by ChillerDragon
- Teeworlds 0.6/0.7 network protocol documentation by ChillerDragon
About Tee Skin Rendering
This section explains how to render a tee skin.
Values put together by Patiga Special Thanks to Jupstar Segment Scaling: body: 100% feet: 150% eyes: 120% eye blink: 45% hand: 93.75% Positioning: 64/64 = 1 = width or height of the body segment body: 4/64 up feet: 10/64 down 7/64 left/right eyes: 0.125 up 0.05 left/right eye movement: dir = angle of eyes (view angle), right = 0 eyes: x: cos(dir) * 0.125 y: sin(dir) * 0.1 each eye (away from the other): x: abs(cos(dir)) * 0.01