Coding in the SDK - Revision history

Stgatilov: /* The codebase is so friggin' huge! */

2019-04-10T16:56:30Z

The codebase is so friggin' huge!

← Older revision		Revision as of 16:56, 10 April 2019
Line 233:		Line 233:
	Agreed, the codebase it is pretty huge. I can perfectly imagine that a newcomer can be overwhelmed when looking at the code. Here are some general notes and directions:		Agreed, the codebase it is pretty huge. I can perfectly imagine that a newcomer can be overwhelmed when looking at the code. Here are some general notes and directions:

	Use a good IDE for coding. I recommend Visual ~~C++ 2005 or 2008 Express~~ Edition (VC++) for Windows users (the free one), Linux people surely find something suitable in their package manager.		Use a good IDE for coding. I recommend Visual Studio Community Edition (VC++) for Windows users (the free one), Linux people surely find something suitable in their package manager.

	=== Using VC++ ===		=== Using VC++ ===

Stgatilov: /* std::shared_ptr */

2019-04-10T16:55:07Z

std::shared_ptr

← Older revision		Revision as of 16:55, 10 April 2019
Line 149:		Line 149:

	== std::shared_ptr ==		== std::shared_ptr ==
	The by far most useful class is the std::shared_ptr<> template, which belongs in the category of so-called "smart pointers". It stands for the [http://en.wikipedia.org/wiki/RAII RAII] design pattern and implements <tt>std~~::tr1~~::shared_ptr</tt>. This template makes your memory management tasks a lot easier. Due to the automatic internal reference counting it entirely eliminates memory leaks, when used correctly. As soon as the last shared_ptr<> reference to an object is destroyed, the contained object is deleted as well and the memory is released again.		The by far most useful class is the std::shared_ptr<> template, which belongs in the category of so-called "smart pointers". It stands for the [http://en.wikipedia.org/wiki/RAII RAII] design pattern and implements <tt>std::shared_ptr</tt>. This template makes your memory management tasks a lot easier. Due to the automatic internal reference counting it entirely eliminates memory leaks, when used correctly. As soon as the last shared_ptr<> reference to an object is destroyed, the contained object is deleted as well and the memory is released again.

	I made strong use of std::shared_ptrs when designing the new AI framework, and this saved me from placing a single <tt>delete</tt> call anywhere in the code, no memory leaks whatsoever.		I made strong use of std::shared_ptrs when designing the new AI framework, and this saved me from placing a single <tt>delete</tt> call anywhere in the code, no memory leaks whatsoever.

Stgatilov: Removed any mention of boost: it is no longer used in TDM.

2017-07-15T07:03:13Z

Removed any mention of boost: it is no longer used in TDM.

← Older revision		Revision as of 07:03, 15 July 2017
Line 148:		Line 148:
	You can also define new log classes in <tt>DarkMod/DarkModGlobals.cpp</tt>, if it's actually necessary. Note that performance is not a real issue here, as the code can be stripped with a single #define from the entire codebase, leaving our release code nice and clean. When switched on, each call does take a small amount of time. If you really need to know (like me), one log line usually takes up 12 µsecs, which is rather much, as the log buffer is immediately flushed to disk (otherwise the log line would vanish in case of a crash).		You can also define new log classes in <tt>DarkMod/DarkModGlobals.cpp</tt>, if it's actually necessary. Note that performance is not a real issue here, as the code can be stripped with a single #define from the entire codebase, leaving our release code nice and clean. When switched on, each call does take a small amount of time. If you really need to know (like me), one log line usually takes up 12 µsecs, which is rather much, as the log buffer is immediately flushed to disk (otherwise the log line would vanish in case of a crash).

	== ~~Why boost? Why not boost?~~ ==		== std::shared_ptr ==
	~~What~~ is ~~boost anyway? The boost libraries form a freely available~~, ~~open~~-~~sourced collection of (templated) utility classes~~. ~~Some of~~ the ~~boost libraries will likely be incorporated in~~ the ~~upcoming TR-1~~, ~~which~~ is ~~not surprising considering that some boost fonders are members of~~ the ~~C++ standards committee~~.		The by far most useful class is the std::shared_ptr<> template, which belongs in the category of so-called "smart pointers". It stands for the [http://en.wikipedia.org/wiki/RAII RAII] design pattern and implements <tt>std::tr1::shared_ptr</tt>. This template makes your memory management tasks a lot easier. Due to the automatic internal reference counting it entirely eliminates memory leaks, when used correctly. As soon as the last shared_ptr<> reference to an object is destroyed, the contained object is deleted as well and the memory is released again.

	~~The boost code is peer-reviewed and of high quality, mostly due to the brutal acceptance process new libraries have to go through before being integrated into boost.~~		I made strong use of std::shared_ptrs when designing the new AI framework, and this saved me from placing a single <tt>delete</tt> call anywhere in the code, no memory leaks whatsoever.

	~~There are several reasons for and against using boost:~~

	~~=== Pros ===~~
	* The boost libraries are stable as rock, you can rely on them.
	* Increased productivity. They provide a number general (templated) solutions for the most common low-level tasks. Don't wast time reinvent the wheel.
	* The shared_ptr template - which alone is reason enough to use boost.
	* Most libraries are consisting of headers only. This means, you don't need to link against static libraries for most things (with exceptions)

	~~=== Cons ===~~
	* Some libraries require static linkage (including boost::filesystem and boost::regex). More of a nuisance than a showstopper, but it requires some work to compile the statics for VC++.
	* The boost tree is quite large, consisting of several thousand files.
	* Some routines like string algorithms might not be as fast as a homegrown, specialised ones.

	~~=== boost::shared_ptr ===~~
	The by far most useful class is the boost::shared_ptr<> template, which belongs in the category of so-called "smart pointers". It stands for the [http://en.wikipedia.org/wiki/RAII RAII] design pattern and implements <tt>std::tr1::shared_ptr</tt>. This template makes your memory management tasks a lot easier. Due to the automatic internal reference counting it entirely eliminates memory leaks, when used correctly. As soon as the last shared_ptr<> reference to an object is destroyed, the contained object is deleted as well and the memory is released again.

	I made strong use of ~~boost~~::shared_ptrs when designing the new AI framework, and this saved me from placing a single <tt>delete</tt> call anywhere in the code, no memory leaks whatsoever.

	=== How to use shared_ptrs correctly ===		=== How to use shared_ptrs correctly ===
	Use this to allocate a new class:		Use this to allocate a new class:
	// Allocate a new class instance and initialise the shared_ptr		// Allocate a new class instance and initialise the shared_ptr
	~~boost~~::shared_ptr<MyClass> myClassPtr(new MyClass);		std::shared_ptr<MyClass> myClassPtr(new MyClass);

	// use the class		// use the class
Line 189:		Line 171:
	{		{
	// Construct a shared_ptr using the raw pointer from above		// Construct a shared_ptr using the raw pointer from above
	~~boost~~::shared_ptr<MyClass> myClassPtr(myClass);		std::shared_ptr<MyClass> myClassPtr(myClass);

	// Do something with the shared_ptr		// Do something with the shared_ptr
Line 207:		Line 189:
	{		{
	// Allocate a new class		// Allocate a new class
	~~boost~~::shared_ptr<MyClass> myClassPtr(new MyClass);		std::shared_ptr<MyClass> myClassPtr(new MyClass);

	// get the contained raw pointer from the shared_ptr (this is possible)		// get the contained raw pointer from the shared_ptr (this is possible)
Line 220:		Line 202:
	You can use this shared_ptr like an ordinary pointer, as the class provides a dereference <tt>operator-></tt>. You can copy-construct shared_ptrs or assign them to other shared_ptrs. You can use shared_ptrs in any STL container (vector, map, set, whatever) or more generally every container which can handle copy-constructible objects. shared_ptrs are type-safe, which means you can implicitly cast your shared_ptr like you're used to with raw pointers:		You can use this shared_ptr like an ordinary pointer, as the class provides a dereference <tt>operator-></tt>. You can copy-construct shared_ptrs or assign them to other shared_ptrs. You can use shared_ptrs in any STL container (vector, map, set, whatever) or more generally every container which can handle copy-constructible objects. shared_ptrs are type-safe, which means you can implicitly cast your shared_ptr like you're used to with raw pointers:
	// Create a shared_ptr holding an instance of MySubClass, which derives publically from MyBaseClass		// Create a shared_ptr holding an instance of MySubClass, which derives publically from MyBaseClass
	~~boost~~::shared_ptr<MySubClass> subClassPtr(new MySubClass);		std::shared_ptr<MySubClass> subClassPtr(new MySubClass);

	// Create a shared_ptr of the base class and assign the subclassPtr to it.		// Create a shared_ptr of the base class and assign the subclassPtr to it.
	// The internal pointers are compatible, as are their shared_ptr<> counter-parts		// The internal pointers are compatible, as are their shared_ptr<> counter-parts
	~~boost~~::shared_ptr<MyBaseClass> baseClassPtr = subClassPtr;		std::shared_ptr<MyBaseClass> baseClassPtr = subClassPtr;
	The shared_ptr headers include the counter-parts of the standard C++ static_cast<>, dynamic_cast<>, const_cast<> and even reinterpret_cast<> operators:		The shared_ptr headers include the counter-parts of the standard C++ static_cast<>, dynamic_cast<>, const_cast<> and even reinterpret_cast<> operators:
	* ~~boost~~::static_pointer_cast<TYPE> complements static_cast<TYPE*>		* std::static_pointer_cast<TYPE> complements static_cast<TYPE*>
	* ~~boost~~::dynamic_pointer_cast<TYPE> complements dynamic_cast<TYPE*>		* std::dynamic_pointer_cast<TYPE> complements dynamic_cast<TYPE*>
	* ~~boost~~::const_pointer_cast<TYPE> complements const_cast<TYPE*>		* std::const_pointer_cast<TYPE> complements const_cast<TYPE*>
	* ~~boost~~::reinterpret_pointer_cast<TYPE> complements reinterpret_cast<TYPE*>		* std::reinterpret_pointer_cast<TYPE> complements reinterpret_cast<TYPE*>

	An example of downcasting shared_ptrs:		An example of downcasting shared_ptrs:
	// Create a new baseclass pointer, but use a Subclass instance to initialise it (which is valid, the pointers are compatible)		// Create a new baseclass pointer, but use a Subclass instance to initialise it (which is valid, the pointers are compatible)
	~~boost~~::shared_ptr<MyBaseClass> baseClassPtr(new MySubClass);		std::shared_ptr<MyBaseClass> baseClassPtr(new MySubClass);

	// Perform a dynamic_cast<> using the baseClassPtr, the result is a new shared_ptr.		// Perform a dynamic_cast<> using the baseClassPtr, the result is a new shared_ptr.
	~~boost~~::shared_ptr<MySubClass> subClassPtr = ~~boost~~::dynamic_pointer_cast<MySubClass>(baseClassPtr);		std::shared_ptr<MySubClass> subClassPtr = std::dynamic_pointer_cast<MySubClass>(baseClassPtr);

	// If the dynamic_cast succeeded, the subClassPtr variable is non-NULL		// If the dynamic_cast succeeded, the subClassPtr variable is non-NULL
	=== typedefs ===		=== typedefs ===
	As typing <tt>~~boost~~::shared_ptr<MyClass></tt> is tiresome, use this convention to create short-hand types:		As typing <tt>std::shared_ptr<MyClass></tt> is tiresome, use this convention to create short-hand types:
	typedef ~~boost~~::shared_ptr<MyClass> MyClassPtr;		typedef std::shared_ptr<MyClass> MyClassPtr;
	So the convention is to append "Ptr" to your class name to denote a shared_ptr object. The allocation code becomes nicer then:		So the convention is to append "Ptr" to your class name to denote a shared_ptr object. The allocation code becomes nicer then:
	// Allocate a new MyClass instance		// Allocate a new MyClass instance

Akira at 15:07, 1 November 2013

2013-11-01T15:07:41Z

← Older revision		Revision as of 15:07, 1 November 2013
Line 1:		Line 1:
	Intended article audience: engine coders		'''Intended article audience:''' engine coders

	...also known as ''greebo's random notes about coding for The Dark Mod''.		...also known as ''greebo's random notes about coding for The Dark Mod''.

Akira at 15:07, 1 November 2013

2013-11-01T15:07:23Z

← Older revision		Revision as of 15:07, 1 November 2013
Line 1:		Line 1:
			Intended article audience: engine coders

	...also known as ''greebo's random notes about coding for The Dark Mod''.		...also known as ''greebo's random notes about coding for The Dark Mod''.

Akira: /* General */

2013-11-01T15:03:59Z

General

← Older revision		Revision as of 15:03, 1 November 2013
Line 4:		Line 4:

	== General ==		== General ==
	When the id people designed Doom 3, they roughly divided their code into two parts: the '''engine''' and the '''gameplay''' code. The engine code is closed source, i.e. we ~~don~~'t have the code, only the compiled binary in the form of DOOM3.exe.		When the id people designed Doom 3, they roughly divided their code into two parts: the '''engine''' and the '''gameplay''' code. The engine code was originally closed source, i.e. we didn't have the code, only the compiled binary in the form of DOOM3.exe.

	The '''engine''' ~~contains~~ all the "important" stuff which id software is making money with, by licensing it to third party companies. This is where the real brainpower is in, so we ~~don't get that~~ part ~~(yet - John Carmack repeatedly stated that he wants~~ to ~~release all~~ the source ~~under the GPL soon)~~.		The '''engine''' contained all the "important" stuff which id software were making money with, by licensing it to third party companies. This is where the real brainpower is in, and we did not have access to this part to begin with. Since the idTech 4/Doom 3 source code release in 2011, we have access to this part as well.

	The '''gameplay''' code is fully available. This includes the entities, game logic, AI, physics, weapon and animation code. This ~~leaves~~ a whole lot of headroom for modders like you and me, and we probably should thank id software for that. There are all kinds of mods out there which change the gameplay code to create their own game so to say. Some of them are "mini-mods" (introducing a new weapon or double-jump-mods), some of them are larger, aiming to change the nature of the game and finally there's The Dark Mod, which changed almost everything that can be changed in the first place. The term ''Total Conversion'' comes close - when playing TDM, you won't believe it's the same game as Doom 3.		The '''gameplay''' code were fully available to modders. This includes the entities, game logic, AI, physics, weapon and animation code. This still left a whole lot of headroom for modders like you and me, and we probably should thank id software for that. There are all kinds of mods out there which change the gameplay code to create their own game so to say. Some of them are "mini-mods" (introducing a new weapon or double-jump-mods), some of them are larger, aiming to change the nature of the game and finally there's The Dark Mod, which changed almost everything that can be changed in the first place. The term ''Total Conversion'' comes close - when playing TDM, you won't believe it's the same game as Doom 3.

	== What parts of the code used to be inaccessible? ==		== What parts of the code used to be inaccessible? ==

Akira: /* What parts of the code were left for us to change? */

2013-11-01T14:59:52Z

What parts of the code were left for us to change?

← Older revision		Revision as of 14:59, 1 November 2013
Line 25:		Line 25:
	* the editor (D3Ed), but we have [[DarkRadiant]]		* the editor (D3Ed), but we have [[DarkRadiant]]

	== What parts of the code ~~are left~~ for ~~us to change?~~ ==		== What parts of the code were availiable for modification pre source release ==
	~~A whole lot~~, ~~and in most cases it is sufficient~~:		These are the parts of the code that were possible to modify previous to the release of the source. At the time, Dark Mod was purely just that: a mod dependent on Doom 3.
	* gameplay code (entities, logic)		* gameplay code (entities, logic)
	* physics		* physics

Akira: /* What parts of the code used to be inaccessible? */

2013-11-01T14:56:57Z

What parts of the code used to be inaccessible?

← Older revision		Revision as of 14:56, 1 November 2013
Line 10:		Line 10:
	The '''gameplay''' code is fully available. This includes the entities, game logic, AI, physics, weapon and animation code. This leaves a whole lot of headroom for modders like you and me, and we probably should thank id software for that. There are all kinds of mods out there which change the gameplay code to create their own game so to say. Some of them are "mini-mods" (introducing a new weapon or double-jump-mods), some of them are larger, aiming to change the nature of the game and finally there's The Dark Mod, which changed almost everything that can be changed in the first place. The term ''Total Conversion'' comes close - when playing TDM, you won't believe it's the same game as Doom 3.		The '''gameplay''' code is fully available. This includes the entities, game logic, AI, physics, weapon and animation code. This leaves a whole lot of headroom for modders like you and me, and we probably should thank id software for that. There are all kinds of mods out there which change the gameplay code to create their own game so to say. Some of them are "mini-mods" (introducing a new weapon or double-jump-mods), some of them are larger, aiming to change the nature of the game and finally there's The Dark Mod, which changed almost everything that can be changed in the first place. The term ''Total Conversion'' comes close - when playing TDM, you won't believe it's the same game as Doom 3.

	== What parts of the code ~~are~~ inaccessible? ==		== What parts of the code used to be inaccessible? ==
	All of the code id are earning money with by licensing their engine to others. ~~I don't know all~~ the ~~parts~~, ~~but~~ these are ~~the ones from the top of my head:~~		All of the code id are/were earning money with by licensing their engine to others. Since the release of the source in 2011, these parts are also accessible.
	* the rendering engine		* the rendering engine
	* the sound engine		* the sound engine

Stgatilov: added a note about the autoexp templates

2011-03-26T19:34:15Z

added a note about the autoexp templates

← Older revision		Revision as of 19:34, 26 March 2011
Line 107:		Line 107:
	=== Use your debugger ===		=== Use your debugger ===
	Run the game in your IDE and use the breakpoints at the right places. Note that you can run both debug and release builds in your debugger - the difference of release builds is that some code lines will not be hit and not all variables are available to the inspector. For physics or animation code, the debugger is of limited use, because either the variables don't make sense to our little human brains or the code is executed just too fast and you can't tell when the bug is happening.		Run the game in your IDE and use the breakpoints at the right places. Note that you can run both debug and release builds in your debugger - the difference of release builds is that some code lines will not be hit and not all variables are available to the inspector. For physics or animation code, the debugger is of limited use, because either the variables don't make sense to our little human brains or the code is executed just too fast and you can't tell when the bug is happening.

			You can use templates from [[Displaying idLib types nicely in MSVC debugger]] to improve the way idLib containers are displayed in the MSVC watch.

	=== Use your console ===		=== Use your console ===

Greebo: /* STL vs. idLib */

2009-08-02T16:22:54Z

STL vs. idLib

← Older revision		Revision as of 16:22, 2 August 2009
Line 77:		Line 77:

	There are more container classes in idLib:		There are more container classes in idLib:
	* idLinkList, a circular linked list, but ~~not very similar~~ to std::list - I don't use that much, because it's inconvenient and unintuitive. The most prominent example is the "spawnedEntities" link list in idGameLocal. The "head" of this list is member of the idGameLocal class, each entity is added as node to that list (or rather: as "owner" of each idLinkList node). Don't use the LAS as example for an idLinkList, it's used the wrong way. Also, in my opinion it's just plain weird to start iterating over an idLinkList by calling Next() instead of begin(), oh well. My recommendation is to use std::list instead.		* idLinkList, a circular linked list, but pretty different to std::list - I don't use that much, because it's inconvenient and unintuitive. The most prominent example is the "spawnedEntities" link list in idGameLocal. The "head" of this list is member of the idGameLocal class, each entity is added as node to that list (or rather: as "owner" of each idLinkList node). Don't use the LAS as example for an idLinkList, it's used the wrong way there (without list head). Also, in my opinion it's just plain weird to start iterating over an idLinkList by calling Next() instead of begin(), oh well. My recommendation is to use std::list instead.
	* idHashTable, ditto		* idHashTable, ditto
	* idDict - this one is useful. The most common use for this is to contain all the spawnargs of an entity.		* idDict - this one is useful. The most common use for this is to contain all the spawnargs of an entity.