'''Intended article audience:''' players

Since The Dark Mod is designed to simulate the stealth gameplay of the Thief series, many things will be very familiar to Thief players. There are some features that work differently, however, and some things that are entirely new to TDM.

If you have never played Stealth Games before, start with the [[Basics of Stealth Gaming]].

Veteran stealth gamers can read the various sections below for more detail:

= The Game Menus =

Your experience with The Dark Mod will start with the Main Menu, where you may wish to adjust some settings before starting your first mission. If you already have saved games from a currently installed mission, you can load them from the Load/Save menu.

{{red|Note: While missions remain compatible with all updates, your saved games will not necessarily work after updating, due to code changes.}}

== Starting a Mission ==
[[Image:new_mission.jpg|thumb|The New Mission menu.]]

# Select ''New Mission'' from the Main Menu.
# Click "Download" to see a list of new missions available to download. You can even read details and see screenshots from the mission before downloading it.
# Select a Mission from the Available Mission list on the right (start with the Training Mission if this is your first time) and click ''Install Mission''.
# TDM will install the mission and restart. Select ''New Mission'' again, and click ''Start Mission''
# You will see a briefing that introduces the mission. Click ''Objectives'' to proceed.
# Read your objectives, and choose your Difficulty Level. Then select ''Buy Equipment'' (or ''Start Mission'' in some missions).
# After purchasing desired equipment, hit ''Start Mission''. (The option to ''Drop'' starting items is available, but use with caution...dropping some items may make a mission impossible to complete)
# The Mission Loading screen should appear. Be patient...loading a mission for the first time can take several minutes.

To call the Main Menu during the game, press {{ESC}}) .

See [[Installing and Running Fan Missions]] for more information.

== Changing Settings ==

# Select ''Settings'' from the Main Menu
# Select the type of setting you wish to adjust: ''Audio'', ''Video'', ''Controls'', or ''Gameplay''
# The controls are set to defaults familiar to ''Thief'' players, however there are new keys/features that are worth reviewing.

Under ''Gameplay'' are settings for combat difficulty, auto-parry, and more. AI Vision" under ''Gameplay'' controls how quickly AI realize you are an enemy when they spot you.

== Objectives ==

When you call the Main Menu during a mission (by hitting {{ESC}}), you will see an option for "Objectives". This is where you can check your progress.

Your objectives are also displayed after the Mission Briefing when you first start a mission.

When you complete an objective, a chime will sound and “Objective Completed” will be displayed at the top of the screen.

When you have completed all objectives, the map will close and a “Mission Succeeded” screen will appear. Likewise, if you fail an objective or are killed, a “Failed Mission” screen will appear. You can restart the map by selecting the "Restart" option or via the Main Menu.

Hitting {{key|O}} during gameplay will bring up your objectives on screen. You can use the mouse wheel to scroll up and down. Note that this method ''does not pause the game''.

----

= HUD Display =

[[Image:hud.jpg|thumb|The Game Screen indicators.]]

1. WEAPON ICON: An icon of your currently selected weapon is displayed in the bottom left corner of the screen.

2. BREATH INDICATOR: When you are underwater a small blue bar will appear above the lightgem. This bar measures how much air you have left. When the blue bar runs out, you start to take damage. Surfacing or using a Breath Potion will restore your air bar.

3. LIGHTGEM: The lightgem at the bottom of the screen indicates how easy you are to see. This is primarily due to how much light is hitting you, but also includes things like whether you are crouched, moving, or have a weapon drawn. Being under water also reduces your lightgem.

The wings on either side of the gem are a crouch indicator. When you are crouched, the wings 'crouch' down as well.

4. HEALTH INDICATOR: When you are injured, a small red healthbar appears below the lightgem. It will remain visible until you are returned to full health.

5. INVENTORY ICON: Your currently selected inventory object (or your loot total) is displayed as an icon in the bottom right.

== Weapons ==

Weapon hotkeys were changed at the last minute, so this list may need modifying:
* {{key|`}} Put away weapons
* {{key|1}} Blackjack
* {{key|2}} Short Sword
[[Image:arrows.jpg|thumb|A selection of arrows you can choose from.]]
* {{key|3}} Broadheads
* {{key|4}} [[Water Arrows]]
* {{key|5}} [[Fire Arrows]]
* {{key|6}} [[Rope Arrows]]
* {{key|7}} [[Gas Arrows]]
* {{key|8}} [[Noise Arrows]]
* {{key|9}} [[Moss Arrows]]
* {{key|0}} [[Vine Arrows]] (starting in TDM 1.07)

''(note that there has been a report that linux users cannot use the {{key|`}} as it is mapped to the console. Linux users will need to select a different key for 'Put away weapons'.)''

== Inventory Objects ==
Cycle through your inventory using the Inventory Prev/Next keys (default: {{key|[}} or {{key|TAB}} for next item and {{key|]}} for prev item). Inventory objects are stored in groups, so all keys will be stored together, all readables, etc. You can cycle through groups with the Prev/Next Group keys.

To ‘use’ an inventory object, select it and then hit the Use key (default: {{key|U}}). This will drink potions, throw mines, activate the spyglass, etc. To "use" objects on other objects (like using a key on a door), select the object in inventory, highlight the thing you want to use it on, and hit Use.

You can drop inventory items by hitting the Drop key (default: {{key|R}}) twice. See the section "Holding Junk Objects" for more information. Note that mappers may designate some important inventory items as undroppable.

You can clear the inventory selection by hitting the {{key| ←      }} (backspace) key.

To set hotkeys for your inventory items, please see [[Custom Settings for Players]].

=== Inventory Object: Flashbomb ===
[[Image:equipment.jpg|thumb|The tools of a professional burglar.]]
Activate a flashbomb by selecting it in inventory and hitting Use. Flashbombs detonate on impact. A short tap will cause it to fall and go off at your feet. Holding down the Use key will throw the flashbomb farther away. If you use the Drop key to put the flashbomb down, it is not activated at all.

An AI must be looking at the flashbomb to be blinded. Don't look at the point of impact or you'll be blinded too.

AI are only blinded for a few seconds, and they are alerted by the flash, so this tool is most useful for getting away when you've been spotted, or stunning an enemy before an attack.

Flashbombs have no effect on the undead.

=== Inventory Object: Holy Water ===

Select your holy water in inventory and hit the Use key. This puts holy water into your water arrows, making them lethal to undead. The effect only lasts 30 seconds, so use it wisely.

=== Inventory Objects: Keys ===
Some doors or chests require keys to open. To open a locked door, select the appropriate key by scrolling to it in your inventory and hit the Use key (or the Frob key if you wish) while highlighting the door. Note that certain types of door locks (like padlocks) might have to be frobbed separately.

You can also assign a key to ''Cycle Keys'' to quickly cycle through all keys in your inventory.

=== Inventory Objects: Lockpicks ===
See [[#Lockpicking|Lockpicking]] for more information on lockpicks.

=== Inventory Objects: Maps and Readables ===

In The Dark Mod, both maps and most readables (books, scrolls, etc) are inventory items. To read them, you scroll to the object in your inventory and then hit the Use key. The map or readable will be displayed on screen. Note that '''this does not pause the game'''. Unlike Thief, events continue to unfold around you, and you can be attacked while reading if not careful. You can see your environment around the edges of the map/readable, but the best suggestion is to find a safe place to read. With multi-page readables (distinguishable by folded corners on the page), use the next/prev inventory or next/prev weapon keys to scroll through pages. Hitting Use or Attack will put the readable away.

The Map key (default: {{key|M}}) will also automatically bring up your map, if you have one. You can also define a readables key (default: not mapped) to cycle through any readables you have.

=== Inventory Object: Mines ===

Place a mine by selecting it in inventory and hitting Use. A short tap will drop the mine at your feet. Holding down Use will throw the mine further away. Once activated in this way, a mine is armed and will go off if stepped on. If you use the Drop key to put the mine down, it is not armed.

Note that you can set mines off by shooting them with an arrow. You can disarm a mine by using a lockpick on it, the same as you would on a locked door. Armed mines give off a distinct ticking sound, which stops when the mine is disarmed. After disarming a mine, you can frob it to put it back into your inventory.

Map authors can place a mine and arm it at mission start. It behaves the same as any mine you've thrown: it will explode on contact, and it can be disarmed. So don't assume that any mine you come across is safe to pick up. Listen for the tell-tale armed ticking sound.

=== Inventory Object: Player Lantern ===

Light is usually the bane of thieves everywhere, but there are times when you need just a little to make your way around. To this end, some thieves carry a covered lantern with a hood that can be closed to block out the light. To use the lantern, select it in inventory and hit Use. This will lift the cover if the lantern is currently off, or close the cover if it is currently lit. There is also a hotkey for using the lantern; by default this is {{key|L}}. This lantern is clipped to your belt so your hands are free, and it can even be used underwater for short periods.

Obviously using the lantern makes you clearly visible to any nearby opponents.

=== Inventory Object: Potions ===

Potions are used by selecting them in inventory and hitting Use. Healing potions will restore hit points (the effect is somewhat gradual). Breath potions increase the player's breath meter, allowing them to stay underwater longer.

=== Inventory Object: Spyglass ===

A good Thief likes to scout ahead. To use the spyglass, select it in inventory and hit Use. Or use {{key|G}} as a shortcut. You can use the next/prev weapon keys to zoom in and out. You cannot use weapons or frob objects while using the spyglass.

= Movement =

Movement in The Dark Mod is not that different than Thief. You can run, walk, or creep, as well as do any of the three while crouching. The faster you move, the more noise you make.

== Climbing ==

''needs revising''

Holding down crouch will cause you to detach from the ladder or rope, causing you to slide down.

Ladder/vine climbing:

Rope climbing:

=== Swinging on Ropes ===

Tapping the "attack" key while on a rope will cause the rope to swing forward. You can actually gain more momentum by continuing to tap it every time you start swinging forward (think of it like swinging your legs forward on a swing). This can allow you to jump off the rope and grab ledges that are otherwise too far away.

Note that the further down the rope you are, the more distance you can travel when swinging (just like a real rope).

== Mantling ==
There are two different ways to mantle (pull yourself up onto ledges) in The Dark Mod. One is by holding down the Jump key, which Thief players will be familiar with. There is also a key specifically for mantling (default: {{key|
C}}), so that failing to mantle will not result in jumping and making noise. Ideally there should be no difference in these methods, but occasionally one method will work when the other will not.
Mantling is affected by where you are looking, so a successful mantle is more likely if you are looking directly at the edge of the object you wish to climb. To climb on a chair, look down at the seat then press the mantle control. By this means you can clamber over relatively low but awkward obstructions and even select one ledge above/below another.

You cannot mantle while carrying a junk object or body.

= Interacting With Your Environment =

The Dark Mod gives you far more flexibility than previous Thief games when it comes to interacting with things.

== Manipulating Junk Objects ==
This is one area that works quite differently from the Thief series. “Junk” objects (anything that you can carry that doesn’t go into inventory, like chairs, candles, or bodies) are held out in front of you when frobbed. Unlike in Thief, they take up physical space, and can be used to push or manipulate other objects. They can also bump into other objects, making noise (or being knocked out of your hands), so be careful.

To grab a junk object, frob it as normal. The object will stop highlighting, and any weapons you have selected will lower. At this point, you can use the next/prev weapon keys (default: mousewheel up/down) to move the object closer/further away from you, and moving your mouse around will move the object (it stays basically in the center of your screen).

The heavier the object, the slower it moves, so you may notice a ‘lag’ if you turn quickly with heavy objects. It can take a while to get used to this.

To drop an object, hit the Drop key (default: {{key|R}}). By crouching and angling your view down gently, you'll find that you can easily set down objects without making noise. You can also throw a held object by hitting the Attack key. Tapping the Attack key throws the object a short distance; holding the Attack key down and releasing it will throw it further.

To rotate a held object, hold down the {{key|Z}} key or middle mouse button, and move your mouse.
(By default, horizontal movement of the mouse yaws the object around the vertical axis, and vertical movement pitches the object up and down. Holding down the Run key makes horizontal mouse movement roll the object around the forward axis.) This can be useful for replacing objects that have been knocked over, or for placing moveable objects in creative ways (like putting a plank over a gap, or stacking chairs).
It is possible to “drop” inventory items into your hands, where they can be manipulated as if they were junk objects. Select the object in your inventory, and hit the Drop key {{key|R}}. The object will appear in front of you like a junk object, and you can rotate it, set it down, etc. To put it back into your inventory, you must "use" the item again ({{key|U}}) or scroll to the next inventory item ({{key|TAB}} or {{key|[}}/{{key|]}}).
[[Image:candles6.jpg|thumb|[http://www.youtube.com/watch?v=922ArtrKgC4 Click to see TDM candles in action.] ]]
AI will hear junk objects that are dropped or banged around. It takes some skill to pick up objects on a crowded table without knocking them into each other. Remember than an object moves to the center of the screen when you pick it up. If you are looking slightly above the object, it will jump up to center screen (usually a good thing). If you're looking slightly below the object, it will jump down, banging whatever surface it rests on (a bad thing). A little practice may be required to smoothly and quietly sort through objects.

Some objects that are too heavy to lift may still be movable (like large crates). Walking or running into such objects may (mapper's choice) push them along the ground.

=== Junk Objects: Candles ===

Lit candles can be frobbed and carried around to light your way (obviously you will be easily spotted while carrying a lit candle). They can also be used to light flammable objects like other candles or torches. Click the caption on the right for a demonstration.

Candles can be extinguished by water, or you can pinch them out by picking them up and clicking the Use key. (Note that this method can also be used on some movable lanterns). Candles can also be extinguished by knocking them over.

Be aware that multiple light sources can cause a significant drain on your framerate. If you go around a room lighting six or seven new candles, don't be surprised if your framerate drops significantly.

=== Junk Objects: Bodies ===

Bodies work differently than most other objects. There are two ways to deal with dead or unconscious bodies in The Dark Mod. You can both drag them and carry them.

To drag a body, you must ‘frob’ it (which probably requires crouching), and then back away. The body will drag along with you until you frob it again or the body gets stuck on something.

This is not the most graceful way of moving bodies and is not recommended for long distances. Bodies can catch on things and get pulled out of your hands. It can be useful for quickly shifting a body into a shadow, however. You can even move individual limbs to put a flailing arm back into a shadow.

You can also carry a body over your shoulder. While a body is being dragged, hitting the Use button will lift it up over your shoulder. While carrying a body you move more slowly and cannot use weapons or inventory objects (though you can open doors). When you are ready to drop the body, hit Use again. If there is not enough room, you will hear a grunt and nothing will happen. Back up a bit and try again. When you drop a body, it will be the opposite orientation from the way you picked it up (if a body is face-up when you lift it, it will be face-down when you drop it). This allows you to easily search a body for keys or other objects.

=== Junk Objects: Food ===

Some food can be eaten. When holding a piece of food (such as an apple) hit the "use" key. If the food is edible, you will 'eat' it. Discard any left-overs. Some of the healthy food will heal you by one HP.

== Doors ==
You can interrupt a door opening or closing by frobbing it again. Frobbing a moving door stops it, allowing you to open a door just a crack to peer beyond.

You can lean into a door (use the lean left/right keys) to press your ear up against it and hear what's on the other side. Note that while you're concentrating on what's beyond the door you'll be less able to hear the sounds in the room you're currently in.

Some doors or chests are locked and require keys (or lockpicks, see below) to open. To open a locked door, select the appropriate key by scrolling to it in your inventory and hit the Use key (or the Frob key if you wish) while highlighting the door. Note that certain types of door locks (like padlocks) might have to be frobbed separately.

== Lockpicking ==
You will definitely want to practice lockpicking in the Training Mission before trying a real map. Just reading the instructions is probably not enough to get the hang of it.

There are two types of lockpicks, 'triangle' and 'snake'. To begin, you must have the correct lockpick selected in inventory. If you do not, you will see a red flash behind the lockpick icon when you frob the locked door. To pick a lock, move close enough to highlight the door and hold the Use key. You will start to hear a sequence of clicks, and see the door handle (or lock pin) jiggle in sync.

The clicks are a random pattern. At the end of the pattern is a brief period of silence, then the pattern will begin again. To be successful you must hit the Attack key (or release the Use key if you prefer) at the start of that silence. If you hit the Attack key at the wrong time there is a dull 'fail' sound and the pattern begins again. Your goal is to learn the sequence of clicks so that you can anticipate when it will end. This requires concentration.

Some locks are more difficult than others and have multiple pins (which may require switching lockpicks). You can make lockpicking harder or easier in the Settings Menu, by adjusting how much silence there is between each pattern (the more silence, the easier it is to react in time). Setting Lockpicking to "Auto" will make locks open automatically after the pattern repeats 3 times.

Armed mines can be disarmed by lockpicking them. Afterward, they can be frobbed and put into inventory. Either lockpick type can be used.

== Chests ==
It can sometimes be a little awkward frobbing items inside deep chests. Leaning forward (or even sideways) will usually help.

If you get too close to a chest, you can sometimes get in the way of the lid opening or closing. Back up a little if the lid is not moving as expected.

----

= Combat =

There are a number of ways that combat is different in The Dark Mod.

Keep in mind that you are not a warrior. Guards are generally better trained than you are, and while you might win a few one-on-one battles, you will almost certainly die if facing two guards at once.

== Blackjacking ==

Your blackjack is more effective if your opponent is relaxed and not expecting trouble.

You must hit an AI on the head to knock them out. Hitting an AI anywhere else will simply alert them. For best results, don't get too close to the AI, or you may hit them with your elbow instead of your blackjack.

'''You can successfully knock out:'''

'''1. Unarmed civilian AI from any direction, any time.'''

'''2. Bare-headed guards from any direction when relaxed, or from behind when their weapon is out.'''

'''3. Helmeted guards from behind when relaxed (helmeted guards cannot be knocked out when their weapon is out).'''

All armed AI are harder to knock out when the AI has drawn a weapon, because they are assumed to be ready for you. Either they have searched for you or been warned by a friend that something is wrong.

The blackjack does a small amount of damage, so you could theoretically beat someone to death with it, if you have a lot of time on your hands.

Undead and some animals cannot be knocked out with the blackjack.

Certain heavy-duty helmets make their wearer immune to the blackjack. These can be identified by a face grill and a low back, which protects the base of the neck.

'''Note:''' the blackjack makes an overhead swing, so if there is something low in the way (like a doorframe) you might hit it instead of your target, especially if you are looking upwards.

== Melee Combat ==
[[image:combat1.jpg|thumb|A guard winds up for an overhead attack]]
There is a combat arena in the Training Map for practicing combat. After a few rounds you will have a much better feel for how it works.

You can use your shortsword to attack an enemy, as well as block enemy weapons. Attacking a relaxed enemy (ie, backstabbing) does extra damage.
To attack, hit the Attack key. This will make a left-to-right, slashing attack. If you move the mouse while clicking the Attack key, you can select other kinds of attacks. Moving the mouse down will cause an overhead swing. Moving the mouse up will cause a thrust attack. Moving the mouse left or right will cause a right-to-left or left-to-right slash, respectively.

AI can parry your swings (unless they are using a dagger), and they will do this more easily if you keep using the same kind of attack, so you will want to mix it up.

The amount of damage you do varies depending on where you hit. Hitting an AI in the head will do more damage than hitting their arm or leg. Armour also plays a factor. Your sword can't penetrate plate armour, and even chainmail or leather armour will provide the AI some protection.

To block an enemy strike, hold the Parry key. You must hit the parry key ''after'' the AI starts winding up for their attack. Too early and the AI will see the block and choose a different attack. Obviously, you must also be facing the AI...holding up a block while looking off to the side won't help.

If you are using Manual Parry (select in the Settings menu), you need to select the appropriate block. If your opponent is making an overhead attack, you must select an overhead block. Select blocks by moving the mouse while holding the Parry button down, just as you would for an attack.

If you successfully block an attack or damage your opponent the AI will be temporarily "flat-footed". They can still attack and defend, but they will not chase you if you turn to run. The effect lasts only a second or two, but that can sometimes be enough time to give you a head start.

The trick to a successful combat is timing. You need to try to anticipate your opponent's attacks, and then launch counter-attacks before he has a chance to parry.

AI will usually try to flee if they are badly wounded.

Different AI have different skill levels (novice, trained, skilled) when it comes to combat. An armed commoner will no longer fight as well as an elite guard. You can also change the overall combat difficulty in the Settings menu. Also, different weapons do different amounts of damage. A longsword is one of the most damaging weapons, while short swords do less damage and daggers even less.

'''Note:''' It is possible to hit walls or ceilings instead of your target. Keep track of how much space is around you when choosing your swing.

== Missile Combat ==

Your broadhead arrows cannot penetrate plate armour, and will do less damage if they hit chain or leather armour. The best result is to hit unarmoured flesh. A single arrow to the head will kill a relaxed guard. Alert guards are assumed to be taking measures to minimize the damage from incoming arrows.

If you are hit while trying to fire an arrow, your attack will be canceled.

AI will switch to missile combat if they can see you but cannot reach you. If they don't have a missile weapon, they will become angry and start throwing rocks at you.

AI archers will fire arrows at you. Some AI are better shots than others. When you get within melee range of an archer, they will pull out their melee weapon to fight with it instead.

----

= AI =

== AI Senses ==

AI can see you if your lightgem is not totally black. The longer you're in their field of vision and the closer you are, the more likely they are to notice you and come and investigate.

Some AI have hoods, eyepatches, or other things that block their field of vision. These can be exploited by clever thieves...

AI can hear your footsteps, and noise that you make from banging into things or dropping objects. They can also hear the sound of falling bodies, so aware of not only what you are walking on, but of what an AI is walking on, and what they are wearing. AI can also feel you if you bump into them, or vice versa.

TDM AI are fairly intelligent about searching. They can identify good hiding spots and will check them out first.

When AI become alert, their senses get slightly better. A shadow that is sufficient to hide you from a relaxed AI might not be enough for an AI that is alert and actively looking for trouble.

AI do not forget about you after giving up the search. They remain in an alert state, with heightened senses and their weapons out.

== AI Behaviour ==

* AI don't necessarily patrol the exact same route every time, or stand for the same amount of time at every spot they go to. Mappers can add as much randomness to the AI as they wish.

* AI need to see direct evidence in order to react to it. If a bloodstain or missing loot is in shadow, an AI won't notice it.

* AI can react to missing objects, but only if mappers set the objects as noteworthy.

* AI become suspicious if they find a weapon lying around. Finding blood or a body will cause them to go fully alert.

* AI can hear broadhead arrow impacts. If you shoot an arrow and it hits a wall nearby, they will notice. AI will also react to water arrows if you fire them too close (or if you hit an AI with one). AI will often notice and be suspicious of arrows that are left sticking into things, and they can see the rope from a rope arrow, walk over to investigate, and will treat it as evidence of an intruder.

*AI can notice and comment on lights that have been put out, and may relight ones that the mapper has set as important. AI will start to become suspicious of an intruder if this happens frequently.

*AI can notice important doors (set by mapper) that have been left open, and will start to become suspicious. They will also turn towards doors that they see opening, and may get suspicious if they don't see anyone responsible.

AI do not yet notice moss arrow impacts, broken objects or moss patches. These things will likely cause minor alerts in the future.

[[Category:Gameplay]]

The Dark Mod Gameplay

2013-11-01T15:58:14Z

Akira:

2013-11-01T15:03:59Z

Akira: /* General */

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

This article is constant WIP. When coding in the SDK, there are thousands of little lessons to be learned - some of them include things I wish I would have known earlier, some might be common knowledge. Anyway, I plan include all the miscellaneous things in this article.

== 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 was originally closed source, i.e. we didn't have the code, only the compiled binary in the form of DOOM3.exe.

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 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? ==
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 sound engine
* the collision model manager
* the Map and AAS compilers
* the declaration manager (although we can implement our own parsers)
* the network system
* the keyboard and mouse handlers
* anything platform-specific
* the command system
* the virtual file system
* the CVAR system plus some special CVARs
* the editor (D3Ed), but we have [[DarkRadiant]]

== What parts of the code were availiable for modification pre source release ==
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)
* physics
* AI
* custom declarations
* custom CVARs
* the scripting system
* the animation code
* plus everything outside the SDK like scripts, defs, materials and models.

== Coding Style ==
This deserves its own article: [[TDM Coding Style]]

It's easy to see that the gameplay code has been written by a number of different programmers at id software. It's also easy to see that several of them have strong roots in C, whereas others have used C++ coding paradigms more strongly. At any rate, almost all of those programmers need a heads up that the possibility of placing comments in the code has ''not'' been removed from C++ - only a few of them seem to know about comments at all, which is a shame, especially when it comes to the animation code.

Another thing that a newcomer might notice is the mere absence of STL or other standard stuff in the id code. I'm not in the position of judging whether this is actually necessary (which I doubt), but it seems that id rewrote every little low-level library on their own, including strings, lists, hashtables, vectors, etc. Some of the classes are admittedly quite handy, but sometimes it's clear that they did it just because they could. Overall, there is strong [http://en.wikipedia.org/wiki/Not_Invented_Here NIH] smell all about the place, but the code is there and stable already, so we might as well use it for TDM coding.

Something to keep in mind is also the custom memory manager, which (according the comments in the code) is multiple times faster than the one provided by the CRT. As a consequence of this, everything that is allocated in the game DLL must be freed again before the DLL is unloaded, otherwise you'll be running into weird crashes at shutdown. Most classes have Clear() methods in them, and whenever you write custom (global or standalone) classes you need to make sure that these are destroyed in idGameLocal::Shutdown() at the latest.

id software has been using the following coding style:
* class member variables are lowercase, plain notation (without the m_bVar hungarian stuff)
* class names start with the "id" prefix
* class methods are uppercase with mixed case, like this: <tt>idDict::MatchPrefix()</tt>
* One True Brace Style, i.e. the opening { brace is in the same line as the <tt>if ()</tt>.

TDM code is slightly different:
* class names are usually starting with C, like CFrobDoor.
* class members are usually using hungarian notation
* a new line for each opening or closing brace

Note that I've been "violating" these rules myself when I wrote the AI framework. I probably don't have a particularly good reason, but it seemed the right thing to do at that time as the framework is a completely new subsystem. It's pretty much the same coding style I was used to in DarkRadiant, minus a few things:
* all classes are in their correct namespace (the <tt>namespace ai</tt> in this case)
* class names are starting with an uppercase letter
* class methods are starting with an uppercase letter
* class members are lowercase, starting with an underscore, like <tt>_finishTime</tt>

Generally, I've been following the rule not to mix styles when I change existing code. If a class is using Hungarian notation, I stick to that, same goes for the id classes and the AI classes.

== STL vs. idLib ==
The most common idLib member is the '''idList<>''' template, which is the counter-part of std::vector<>. Whenever you need a variable-sized array, use idList. This class has some nice convenience functions and supports the definition of granularity, which allows you to specify the minimum size of memory blocks which are allocated by idList. This is useful to prevent idList from calling the <tt>new</tt> operator each time you push an element into that list.

Another popular member is '''idStr'''. This is mostly equivalent with std::string. Both classes provide the well-known c_str() method which can be used to retrieve the const char* pointer from the object. Two gotchas about idStr:
* <tt>void idStr::Empty()</tt> is an imperative method, i.e. it ''clears the string''. Do not confuse this with <tt>bool std::string::empty()</tt>, which returns true when the string is empty. If you want to check whether an idStr is empty, use <tt>idStr::IsEmpty()</tt>...
* idStr has an operator cast to const char*, so you can pass idStr to everything that expects a const char*. Where's the gotcha? Don't expect this to work when passing idStr to functions with variable-sized argument lists, like this
idStr mystr = "test";
idGameLocal::Printf("String is %s", mystr); // this will crash!
The compiler cannot know which operator cast to call for this type of function call, so use the c_str() function instead:
idStr mystr = "test";
idGameLocal::Printf("String is %s", mystr.c_str());

There are more container classes in idLib:
* 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
* idDict - this one is useful. The most common use for this is to contain all the spawnargs of an entity.
* idKeyValue - used to define a spawnarg pair
* idStrList - just a shortcut for idList<idStr>

Another thing I had to learn the hard way was using idStr in combination with std::map. Due to the built-in operator cast to const char*, an idStr cannot be used as index in a std::map. The std::map will try to sort the given idStr into the correct place, but the comparison operator is actually invoking the <tt>idStr::operator const char*() const</tt> which traps the std::map into comparing pointers instead of strings. If you want to use std::map, use std::map<std::string, someothertype>.

== Performance Considerations ==
The code might not win a beauty contest, but most of id's programmers know the ins and outs of how to code a performing game, no doubt about that.

When writing new code and you're worrying about performance, think about how your code is going to be used and more importantly: ''how often''. If your code piece is called when a projectile is hitting a surface, there's no problem with that. If your code is more or less directly hooked into the <tt>idAI::Think()</tt> routine, think twice before writing slow code.

How to recognise slow code? That's a difficult question, you need to use your brain and read lots of code to get a feeling for this.

Bad Things include:
* Looping over a large amount of entities.
* Querying spawnargs multiple times each frame, converting strings to float (e.g. calling idDict::GetFloat() for every little thing). Read the spawnarg once in your Spawn() method and store it in a local member variable instead.
* Calling the clip/trace/collision code exorbitantly.

Another thing to keep in mind: even if the game performs well in your neat little developer testmap with one light and three entities, things might change when you get it to run a full-grown mission with tons of complicated lighting, geometry, moveables and AI. The 16 ms frametime which appeared to be enormously much on your 2.4 GHz developer beast will melt like ice when the rendering of the scene takes up 13 ms on its own on a 1.4 GHz low-end system, leaving a whopping 3 ms for bringing your entire level to life including physics, animation, player movement and last but not least the lightgem. There goes the FPS below 60 and counting downwards. Don't even hope that future processors will execute your code faster - they won't, given that the processor clock rate ''of a single core'' has been almost stagnating over the last few years. The SDK code is using only one core.

== How to Debug ==
There are several techniques to find problems in your code to see why the heck your door is not playing the "close" sound, for instance.

=== Use your head ===
That goes without saying.

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

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 ===
If you don't want to interrupt your game by a breakpoint hit, use the console output commands to write stuff to the console, like this:
gameLocal.Printf("the time is %d\n", gameLocal.time); // will print the game time to the console

=== Use debug drawings ===
For things that happen really fast or mathematical things like vectors and bounding boxes use the excellent debug output features that are available for you:
// this will draw a red line from the AI's head to the player's head, lifetime is 16 msecs.
gameRenderWorld->DebugArrow(colorRed, ai->GetEyePosition(), player->GetEyePosition(), 1, 16);
You can also draw text in the game, but keep in mind that you need to pass the text orientation matrix to the function as well, otherwise the text is not oriented to the player:
// this will draw a white "test" at the "eyePosition", readable to the player, lifetime = 16 msecs
gameRenderWorld->DrawText("test", eyePosition, 0.1f, colorWhite, gameLocal.GetLocalPlayer()->viewAngles.ToMat3(), 16);
When drawing a large amount of these, the game performance will go down the drain, but you don't need to worry about that - it's debug output for your personal use only.

There is also a method allowing for drawin text on the GUI (but note that this only works when invoked after the scene is rendered in playerview.cpp):
renderSystem->DrawSmallStringExt(x, y, "text", idVec4( 1, 1, 1, 1 ), false, declManager->FindMaterial( "textures/bigchars" ));

If you happened to write a useful piece of debug drawing output, please don't delete it right away before committing. It might pay off if you take the time and make them optional by using a CVAR, like "tdm_ai_showdebugtext", which defaults to "0". There's a good chance that other developers will want to marry you for this.

=== Use the logfile ===
There are some debugging macros available in the TDM codebase, which you can use extensively.
// Let the logfile know that we've spawned
DM_LOG(LC_AI, LT_INFO)LOGSTRING("AI %s has spawned!\r", name.c_str());
There are several log classes and log levels available, just look at the <tt>darkmod.ini</tt>, which is also where you can switch them on or off. Examples are:
* LC_AI for AI stuff
* LC_ENTITY
* LC_LOCKPICK
* LC_OBJECTIVES
* LC_STIMRESPONSE
* ...
The loglevels can be used to filter a certain log class for specific events:
* LT_ERROR is the most severe message
* LT_WARNING
* LT_DEBUG
* LT_INFO contains verbose stuff
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? ==
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 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.

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 ===
Use this to allocate a new class:
// Allocate a new class instance and initialise the shared_ptr
boost::shared_ptr<MyClass> myClassPtr(new MyClass);

// use the class
myClassPtr->DoSomething();

// Don't worry about deletion, as soon as the shared_ptr is destroyed, your instance comes along
This snippet allocates a new MyClass instance and hands the pointer to it over to the shared_ptr<> instance. (This is following the RAII pattern, as the allocated resource is instantly used to initialise the memory-managing class (the shared_ptr)). You don't need to worry about deleting the MyClass instance, this will be handled by the shared_ptr automatically.

=== How to use shared_ptrs incorrectly ===
Use this to crash your application:
// Allocate a new object
MyClass* myClass = new Myclass;

{
// Construct a shared_ptr using the raw pointer from above
boost::shared_ptr<MyClass> myClassPtr(myClass);

// Do something with the shared_ptr
myClassPtr->DoSomething();

// The scope ends here, the shared_ptr is destroyed. As there is only one
// shared_ptr instance available, the internal reference count reaches 0 and
// the contained MyClass instance is <tt>delete</tt>d.
}

myClass->DoSomething(); // insta-crash, the object has already been deleted

delete myClass; // another sure-fire crash due to double-deletion, but you'll never reach this code.
So, the lesson is: follow the RAII design pattern and don't save the raw pointer outside of your shared_ptr. Don't manually <tt>delete</tt> resources that are managed by a shared_ptr<>.

This is another way to crash your app:
{
// Allocate a new class
boost::shared_ptr<MyClass> myClassPtr(new MyClass);

// get the contained raw pointer from the shared_ptr (this is possible)
MyClass* p = myClassPtr.get();

delete p; // this will free your instance

// the application will crash here, as the scope ends and the shared_ptr
// will attempt to destroy the contained object => double-free operation.
// the shared_ptr cannot know about your manual deletion using the raw pointer.
}
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
boost::shared_ptr<MySubClass> subClassPtr(new MySubClass);

// 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
boost::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:
* boost::static_pointer_cast<TYPE> complements static_cast<TYPE*>
* boost::dynamic_pointer_cast<TYPE> complements dynamic_cast<TYPE*>
* boost::const_pointer_cast<TYPE> complements const_cast<TYPE*>
* boost::reinterpret_pointer_cast<TYPE> complements reinterpret_cast<TYPE*>

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)
boost::shared_ptr<MyBaseClass> baseClassPtr(new MySubClass);

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

// If the dynamic_cast succeeded, the subClassPtr variable is non-NULL
=== typedefs ===
As typing <tt>boost::shared_ptr<MyClass></tt> is tiresome, use this convention to create short-hand types:
typedef boost::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:
// Allocate a new MyClass instance
MyClassPtr mc(new MyClass);

mc->DoSomething();

== The codebase is so friggin' huge! ==
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.

=== Using VC++ ===
* Move your mouse over variables to see their type.
* In Debugging mode: move your mouse over a variable to inspect it (including base classes)
* Right-Click a class or function name and choose '''Go to Declaration''' to find the header file where this class or function is declared.
* Right-Click a function and choose '''Go to Definition''' to jump to the function body, which is useful when reading the code. Note that this doesn't work very well with virtual functions. Implementations of pure virtual functions cannot be found this way at all, use your text search to look for '''::DoSomething''' instead to attempt to find places where this function is defined.
* Switch on the "Code Definition" window and dock it somewhere. When you place the cursor over an identifier, you can see the definition of that type in that small window (useful for looking at enums and structs without leaving your current view).
* Right-Click a class, function or variable name and choose '''Find all References''' to find all the places where this object is used. This is useful to find the callers of a function or see whether a function is used at all.
* Use the search function and choose the search scopes '''Current Document''' or '''Current Project''' to find a string in the entire codebase. There is also a fulltext search available in that search widget: choose '''Find in Files''' in the top-left dropdown field.

== Where does Code Execution "start"? ==
You might wonder where the "starting point" of the code is. The key to understanding this is the idGameLocal class, which implements a set of functions. These methods are called by the "core" engine (i.e. the EXE) on several events:

=== During Gameplay ===
Each frame the core engine is calling '''idGameLocal::RunFrame()''', without exception. When this function happens not to be called anymore, there is no active map running.

This function does a variety of things, like calculating the lightgem, processing the Stim/Response system and most importantly, it lets all active entities "think", i.e. the function <tt>idEntity::Think()</tt> is called. Hence everything that needs to be done each frame is located in each entity's thinking routine. This usually includes '''RunPhysics()''' and '''Present()'''.

After all entities have finished thinking, the event queue is processed. See the article [[Event System]] for more details.

=== When a new Map starts ===
Whenever you type '''map test''' in the console or start a map via the menus, the following happens:
* The engine checks whether the map exists.
* The engine calls '''idGameLocal::InitFromNewMap()''' which loads the map file, initialises the AAS, spawns the entities, etc.
After InitFromNewMap() has finished, the game will run a few frames to let some physics stuff settle and will start to fade in. Then see the above section ''During Gameplay''.

=== When a Game is loaded ===
Things are a bit different when a map is loaded or ''restored'' from a savegame file. In this case the engine calls '''idGameLocal::InitFromSavegame()''', which will instantiate all registered objects and de-serialises all member variables from the savegame file stream. An important thing to note is that '''entities are not spawned during game load'''. The entity classes are automatically instantiated by InitFromSaveGame() and the idEntity::Restore() methods are invoked instead, which puts the entities in their exact state as they were at save time. The map geometry and AAS file are still loaded afresh from the disk, only the "volatile" data like class members or other game state objects and variables are saved into the savefile.

After the map is loaded/restored, the engine proceeds to call idGameLocal::RunFrame(), as one might expect.

=== During Main Menu Display ===
Note that idGameLocal::RunFrame() is ''not'' called when the main menu is shown, which is logical as no map is active at that time. The only SDK function that is ever called during this phase is '''idGameLocal::HandleMainMenuCommands(const char*)'''. Whenever the GUI code sets the <tt>cmd</tt> state variable, this command is passed to HandleMainMenuCommands() to take the according action.

Let's say the '''mainmenu.gui''' executes this code:
set "cmd" "close;";
This code line is roughly equivalent to this call:
gameLocal.HandleMainMenuCommands("close");
Take a look at that method (it's in '''game/game_local.cpp''' btw.) to see how these commands are handled.

== This and That ==

=== How to find all spawnargs matching a given prefix ===
The idDict class provides a handy method '''MatchPrefix''' which takes the prefix string plus a pointer. Use this loop to traverse all matching spawnargs (in this example the prefix is ''"used_by"''):
for (const idKeyValue* kv = spawnArgs.MatchPrefix("used_by"); kv != NULL; kv = spawnArgs.MatchPrefix("used_by", kv))
{
// Do something with the key and the value
DoSomething(kv->GetKey(), kv->GetValue());
}

{{sdk}}