From The DarkMod Wiki
Jump to navigationJump to search

A Level of Detail (LOD) system can be used to bring more details to the screen while still speeding up rendering. See Wikipedia for an introduction.

The new LOD System - Overview

TheDarkMod LOD System Overview.png

SVG version of the above graphic here.

Note: Fade in and fade out only work via alpha-fading, so on materials that use an alpha blend and don't respond to lighting.

How to use LOD in your TDM map

To enable the LOD system, use either one of the pre-made LOD-enabled entities in your map (most of these are defined in def/tdm_lod.def) or set dist_check_period to a number greater than 0.

Note: The dist_check_period spawnarg needs to be combined with one of "hide_distance" or "lod_X_distance" and "model_lod_X", "skin_lod_X" or "noshadows_lod_X" to have any effect!

2.10: Requirement have been relaxed. E.g. for shadow LOD you will now only need two spawnarg's: lod_1_distance and noshadows_lod_1.

See also LOD Bias for how to hide individual entities depending on the menu setting.

GUI Setting

There is a new GUI setting, called Object detail . You'll find it under Settings - Video - Advanced. It consist of multiple levels, where Normal is the default. Lower settings cause the LOD distances to shrink, meaning entities switch sooner to the low-quality version and vanish sooner. Higher settings are the opposite, increasing the quality, but may be decreasing the FPS.

Mappers should design and test their map with the Normal setting on a typical modern PC (e.g. not too old and not high-end gaming rig either), and preferable also test on some slower and faster machines.


Supported entity types:

  • Models that don't move (i.e. func static models)

From TDM version 2.03:

  • Animated models like waving flags and laundry (i.e. anything with spawnclass idAnimated)
  • AI
  • Animated attachments to AI

Example entities

  • atdm:nature_pine_skeleton (just the tree trunk)
  • atdm:nature_pine (Pine + particle leaves slowly swaying)
  • atdm:nature_tree_stump

More can be found in the "Nature" folder with the DarkRadiant "Create entity" command.



See LOD Bias for how to hide individual entities depending on the menu setting.


In D3 units. When set to a value > 0, then the entity will be hidden if it is further away than this distance from the player.

Note: This might cause "popping", e.g. the entity will suddenly vanish or appear. See lod_fadeout_range for how to avoid this.

The actual value used from this spawnarg is modified by the menu setting "Object detail", so make to sure to test with this setting at "Normal".


From TDM v1.05 onwards: This spawnarg defines a minimum distance from the player where the entity will ignore settings lower than Normal. This can be used to enforce a certain minimum distance so that players who set the detail level to Low or Lowest still do not experience entities popping in and out when being very close.

If this spawnarg is not set, it defaults to 500 units. Avoid setting this spawnarg too high or even equal or higher than "hide_distance". This would only result in the menu setting "Object detail" being fixed at "Normal", e.g. players could never lower the quality settings to achive better frame rates. Do so only in rare cases where important entities would otherwise vanish in front of the eyes of the player.


If lod_hide_distance is true, this spawnarg controls what the probabiliy of this entity vanishing is. Values range from 0.0 (will never vanish) to 1.0 (will certainly vanish). Whether a particular entity vanishes is computed at map start, so an entity either stays or vanishes, but does not change during the map play time.


"lod_hide_probability" "0.2"

If you place X identical entities, about 20% of them will vanish at the hide_distance and 80% will stay.

This can be used to "thin out" forests at a distance without having them vanish completely.


In D3 units. Sets the distance from where on LOD X is used. Will be valid until the next defined lod_(X+1)_distance, or infinty if there is no further LOD distance set.

To change the appearance of the entity inside this LOD, use the following spawnargs with a matching X:


Set the model the entity displays inside this LOD. If not set, uses the model from LOD 0 e.g. the one from the "model" spawnarg.

From TDM version 2.03:

A special value "be_still" is supported for animated models. Setting model_lod_X to "be_still" for a LOD level means: stop the animation but don't switch model.


Set the skin the entity displays uses this LOD. If not set, uses the skin from LOD 0 e.g. the one from the "skin" spawnarg.


Boolean. If set, the entity casts no shadows while in this LOD zone.


Vector. Origin offset that can be applied to the replacement model if it doesn't naturally line up with the original.


Note: Fade in and fade out only work via alpha-fading, so on materials that use an alpha blend and don't respond to lighting.

In D3 units. If set to non-zero, then the object will start hidden and begin to fade in at lod_1_distance - lod_fadein_range and be completely (100% opacity) visible at lod_1_distance. This can be used to create entities that only appear in some distance but not close up.


Note: Fade in and fade out only work via alpha-fading, so on materials that use an alpha blend and don't respond to lighting.

In D3 units. If set to non-zero, then the object will not vanish suddenly at hide_distance, but start to fade out and be completely invisible at hide_distance + lod_fadeoutrange. Defaults to 0.


This spawnarg will be available in TDM version 2.03

Set "no_lod" "1" to disable LOD completely on an entity. Useful if you want to make use of a LOD entity but use a custom setup.

Increasing the LOD steps

The number of possible LOD steps is fixed in code and defined in game/misc.h as a constant. The current value is 7, meaning that there are 5 different rendering possibilities beside level 0 (the original) and level 6 (the object is hidden). That should be enough even for huge outdoor maps.


Profiling showed that 3000 thinking entities consume about 7% CPU time. So if you use only a few hundred or thousand LOD entities, the performance of the extra thinking time is very small compared to the benefits of having only a few entities actually visible around the player.


At it's simplest, model, dist_check_period, hide_distance, lod_1_distance and model_lod_1 are used:

click for full size
  • model RegularModelName -- point this to the fully detailed model
  • dist_check_period 0.5 -- time in seconds between distance checks
  • hide_distance 400
  • lod_1_distance 100
  • model_lod_1 LessDetailedModelName -- lower detail model
  • lod_2_distance 200 -- (optional further step)
  • model_lod_2 LowerDetailModelName -- even lower detail model (optional further step)

Customizing AI models

From TDM 2.03, many of the common AI models use LOD. This is automatic. They are much more detailed than in 2.02 when seen close up, and are lower-poly when seen in the distance.

If you want to switch an AI's model, for example to make a Builder archer from a citywatch archer by changing the model def and the vocal set and team, then you have a choice: you can change all the different model_lod_* stages to match the ones used by your target Builder; or you can change only the "model" spawnarg, which will work ok but note that LOD will be switched off for that AI. That's because you won't your Builder archer to revert to a citywatch model when distant.

This rule was applied so that existing maps with custom models on AI woudn't get broken by the new AI LOD feature. The rules are: if the mapper overrides the "model" spawnarg but doesn't override any "model_lod" spawnargs, LOD is disabled on the entity. If the mapper overrides at least one "model_lod" spawnarg too, that shows they have it in hand so LOD remains enabled on the entity.


Doom3 did not have any LOD system at all. The first steps of such a system were added in TDM by supporting a hide_distance spawnarg, which made entities hide or portals close once they were further away than this distance. The LOD system in TDM was totally rewritten for v1.04.

Support for animated models and AI was added in TDM version 2.03. More details are available on the bugtracker.


Here we compare the new (v1.04) to the old system (until v1.02):

  • The old system had only two levels: 0 (original model), and 1 (entity is hidden)
  • Due to a typo, all thinking for the LOD entities happened in the first half of the interval. That means if you set the intervall to 1 s, all entities did their distance check between 0 and 0.5 seconds, and none between 0.5 and 1 second and so on. This lead to fluctuating frame rates.

The new system:

  • Supports up to 7 levels (last is hide), more can easily be done with a recompile
  • You can use less levels if you want
  • Thinking is distributed over the entire interval
  • makes scenes with thousands of entities possible
  • Can not only switch the model, but also change the skin (f.i. use less expensive glass shaders) and turn shadows off
  • Can hide only a fraction of all entities of the same class (thinning out)
  • Allows the player (via the settings menu) to control the quality vs. speed

See also