SEED

Note: This is a design document and not actually implemented or available yet!

Introduction

The new and improved LOD System for TDM v1.03 lets you place entities in your map that reduce their own complexity when being far away from the player. However, there are still some huge drawbacks to this technique:

• manually placing thousands of entities is very tedious and error prone
• 3000 entities "thinking" (deciding what LOD they have) takes about 7% of performance, even when they are not visible
• The overall entity limit of 8192 entities - even if only ever 100 entities are visible to the player, you would not be able to create a forest with 10000 objects (trees, treestumps, flower patches and rocks etc.)

To overcome these limitations, the new LODE (Level Of Detail Entity manager) system was created by Tels in June/July 2010.

What is it

It is foremost an entity manager that can:

• Create entities from "templates" (even multiple)
• Place created entities on random positions with random rotations
• Only creates the entities that are "near" the player (saving memory and CPU time)
• Can create entities depending on the surface of the floor (no trees on metal, or only pebbles on sand etc.)
• Removes entities "far" from the player, thus overcomes the entity limit
• Can also manage entities that were manually placed in the map
• Is tied in with the "Object detail" menu setting
• Works entirely automatic

The system also includes support for inhibitors, e.g. areas that are clear of generated entities. This way a forest clearing can be specified with only two entities, instead of being pieced together from multiple generators.

How to use it

IMPORTANT
The current system only supports axis-aligned boxes. If you rotate the entity in DR, it will simply cover the area that the bounds of the rotated brush include! In addition, the placement of entities is relative to the origin of the LODE entity. If you resize the entity in the editor, the origin can move from the center to some side. In this case select the entity, press CTRL+v to enter Vertic Mode and then move the origin back to the center (which you can easily identify, because linked entities will be drawn with their link exactly from the center).

A LODE entity in the editor

An entity targeted by the LODE

• In DarkRadiant, create a brush the size of the area you want to cover
• With that brush still selected, and select Create entity and select Darkmod/Info/atdm:lode

Note:
If you want to resize the LODE entity after creating it, select it with SHIFT + and press TAB to select the brush, then resize it normally.

• Now create the entities that you want to appear. (These entities are sometimes called "targets (because the LODE targets them) or templates (because they are just a blueprint for other entities that should be created). Entities that use the LOD system should be prefered.
• Link each entity from the LODE entity by selecting first the LODE, then the entity, and then press CTRL+K.
• Put the entities at the hight you want them to appear. Alternatively, use the spawnarg "lode_floor" on the entity (see below for more spawnargs). The X/Y or rotation position of the entity does not matter, but you can f.i. use different skins.
• Remember to dmap whenever you add, delete or change the position/size of a LODE!

Area shape and blocking areas

A NO LODE entity blocking an area

At the moment the area covered by the entity is always treated as a (possible rotated) box. That means you cannot get f.i. triangle shaped areas (yet). However, it is possible to block some areas inside the covered area from getting any entities via Darkmod/Info/atdm:no_lode entities. With this "boolean subtract" you can create "holes" or even more complex shapes.

To get this to work, place atdm::no_lode entities and then link them from the LODE. If you want to have one LODE inhibitor to block more than one intersecting LODE, simply link it from both. See screenshot at right for an example.

Important note

The current system only supports axis-aligned boxes. If you rotate the entity in DR, it will simply cover the area that the bounds of the rotated brush include! In addition, the placement of entities is relative to the origin of the LODE entity. If you resize the entity in the editor, the origin can move from the center to some side. In this case select the entity, press CTRL+v to enter Vertic Mode and then move the origin back to the center (which you can easily identify, because linked entities will be drawn with their link exactly from the center).

GUI Setting

The current "Object detail" setting influences LOD distances, and also slightly the density spawnarg.

We want to avoid overly complicated settings like some other games have, where you can control the density, the visibility distance, the texture quality etc all on their own. But rendering slightly less mushrooms for a playable framerate is still a good idea, so LOD distance and density are coupled.

If you want a LODE that always creates the same number of entities (e.g. does not scale wit the GUI setting), see #lod_scaling_limit.

Spawnargs on the LODE

These spawnargs can be set on the LODE itself and set defaults or influence overall strategies:

bunching

Default: "0" (Off). Number from 0.0 to 1.0, giving the probability that a randomly created entities "bunches" up with an already existing entity. Can be overriden for each entity class with lode_bunching.

cull_range

Default: 150 units. Entities further away from the player than hide_distance (as defined on each LOD entity) + cull_range will be removed from the game world. When they come closer to hide_distance + (cull_range / 2), they will respawn automatically.

Can be overriden on a per entity-class basis with lode_cull_range.

Set to 0 to disable any entity culling for this LODE. This should be only used for LODEs with a small number of entities, otherwise you can easily run out of entity slots.

density

Default: 1.0. A factor multiplied with the number of entities generated if max_entities is 0.

The density spawnarg controls how many entities are generated when max_entities is 0.

Note: The density is slightly influenced by the menu setting "Object Detail". Make sure you test your map with the "Normal" setting. If you can, test as well as the "Lowest" and "Highest" to get a feeling for the extremes that can appear.

falloff

Default: none. Defines a function that influences the probability that an entity will be generated. If set to none, all positions are equally likely, resulting in a square shape. All other values (except "func") create a ellipsoid-shape defined by the corners of the LODE and distribute the entities inside that shape.

The value can be set on a per-class base with lode_falloff.

Possible values:

• none - entities all over the square, none outside
• cutoff - no falloff, but entities restricted inside ellipsoid formed by LODE corners
• square - ellipsoid like cutoff, but square falloff from the center
• exp - ellipsoid like cutoff, but exponential falloff from the center
• func - a function calculated from parameters, see LODE - Falloff function for details and images.

The falloff spawnarg controls the distribution of the entities.

floor

Default: 0 (Off). If set to 1, all generated entities will be floored, that is their position will be adjusted so that they touch whatever is under them. They start out at the height the template entity is placed in the editor. This works with dynamically created terrain or terrain consisting of irregular heights like when it was made from patches. See also lode_collide and lode_stack.

Finding the height where the entity is placed is a three-step process, and the "floor" (or "lode_floor" per class) disables/enables the second step. Here is how it works:

First, the entities are placed in whatever height you place the template in the editor. This way you can control their maximum height - entities will only sink down from there (unless the "max_sink/min_sink" spawnargs are negative, then entities will raise from this point on).

Step 1: With floor off: Placing entities at the editor height.

Step 1: With floor on: Placing entities at the editor height.

If "floor" is true, then the second step will place entities downwards so their origin touches the terrain. Note that nothing happens when "floor" is off!

Step 2: With floor on: Touch down to the terrain.

In the third step random sinking/raising of the entities is done according to the "sink_min" and "skin_max" spawnargs:

Step 3: With floor on: Random sinking.

Step 3: With floor off: Random sinking.

lod_scaling_limit

Default: 10. Integer.

The max_entities number scales slightly with the GUI setting "Object details". This is generally a good thing, as it allows the player to lower/raise the details according to his machine. However, in specific circumstances you want a LODE control exactly so many entities as specified. This spawnarg gives the limit under that the scaling for the entity count will be skipped.

Example: You want to a LODE that always creates exactly 16 crates: Set the following spawnargs:

"lod_scaling_limit" "16"
"max_entities"      "16"

lod_scale_density

Default: 1. Boolean.

The density scales slightly with the GUI setting "Object details". This is generally a good thing, as it allows the player to lower/raise the details according to his machine. However, in specific circumstances you want a LODE to create an entity pattern that is not influenced by the menu setting, f.i. because it looks out-of-place with too many or too little entities. This spawnarg gives you the ability to turn the scaling off.

Note: Should only be used very seldom.

max_entities

Default: 0. The maximum number of entities generated. If 0 (the default), then the number will be computed from the aprox. area the LODE covers, taking into account the density spawnarg. Can be overridden by each entity class with lode_max_entities.

Note that the LODE might generate less entitis, f.i. when entities do not all fit into the LODE area, or the inhibitors inhibit too many entities.

probability

Default 1.0. Is used as default probability for entities to spawn on certain surface types, but only when you define lode_material_xyz spawnargs on the template/target entities. See there for an explanation on how this lets you spawn entities only on some surfaces but not on others.

remove

Default: 0. Boolean, if set to 1, the LODE will spawn all entities immediately (instead of spawning only the ones that are visible to the player) and then remove itself.

rotate_min/rotate_max

Default: 0 0 0 and 5 360 5. The range for each axis on how much the entity will be randomly rotated around it. In the order "Ymin Zmin Xmin" and "Ymax Zmax Xmax" (or pitch, yaw, roll (yzx), where the actual rotation order will be yaw, pitch, roll, e.g. "zyx").

The default makes entities yaw randomly between 0 and 360 degress around Z (turn), and pitch/roll between 0 and 5 degrees on the other two axes. Can also be overwritten on each class with lode_rotate_min and lode_rotate_max.

seed

Default: 0. The random seed. If not set or set to 0, a random value will be used (this is the recommended way, as it generates different results every time you start the map anew, but still keeps the entities when you f.i. save and then load a game).

If set to > 0, the random number generator will always generate the same sequence, so you get still randomly distributed results, but they are always the same.

sink_min/sink_max

Default: Both to 0. In Units.

Define the range (minimum/maximum) of how much entities randomly sink into the floor. Can be overridden on a per-class case with lode_sink_min and lode_sink_max. This is in addition to the "base line floor" of the entity, which is either determined by the placement of the template entity in DR (if "lode_floor" is false), or by the point where the entity origin touches the ground (if "lode_floor" is true).

This can f.i. be used to let all floored entities sink 1 or 2 units into the ground, to avoid that the entity, if placed on a step incline, sinks at one side into the ground, but stands "on air" on the other side.

Note: If sink_max is smaller than sink_min, it will be set to sink_min.

Usages:

• sink_min = 0, sink_max = 0 - all entities are at the same "height"
• sink_min = 5, sink_max = 5 - all entities sink 5 units "down"
• sink_min = 1, sink_max = 15 - all entities sink between 1 and 15 units "down"
• sink_min = -10, sink_max = -5 - all entities raise between 5 and 10 units "up" (note seemingly reversed numbers)

"Down" here refers to the gravity normal of the Lode, e.g. at the moment just down the z-axis.

spacing

Default: 0. Defines a minimum distance between placed entities. If set to > 0, implies collision check at creation time between all entities.

Spawnargs on Targets

These spawnargs can be set on the entities that the LODE targets:

lode_cull_range

Default: To whatever the LODE specifies, which defaults to 150 units. Entities further away from the player than hide_distance (as defined on each LOD entity) + lode_cull_range will be removed from the game world. When they come closer to hide_distance + (lode_cull_range / 2), they will respawn automatically.

To disable culling of entities set to 0.

lode_watch_brethren

Boolean, default: 0 (false).

If set, instead of taking this entity as a template to create new entities, this tells the LODE entity that all entities inside the LODE and of the same entityDefName as this one should be "watched" over by the LODE.

That means it will add these entities to its entity watch list, and do the LOD changes as well as cull/respawn them if nec.

The other "lode_*" spawnargs (like lode_floor, lode_spacing etc.) are ignored on the target entity. The only relevant spawnargs are lod_* and hide_distance - these cause the LOD system to kick in. Also, do not forget to put a hide_distance on the target entity, or the LODE will never cull the entities it watches.

lode_falloff

Default: Whatever the LODE specifies, or none. Defines a function that influences the probability that an entity will be generated. If set to none, all positions are equally likely, resulting in a square shape. The other values (except "func") create a ellipsoid-shape defined by the corners of the LODE and distribute the entities inside that shape.

Possible values:

• none - entities all over the square, none outside
• cutoff - no falloff, but entities restricted inside ellipsoid formed by LODE corners
• square - ellipsoid like cutoff, but square falloff from the center
• exp - ellipsoid like cutoff, but exponential falloff from the center
• func - a function calculated from parameters, see LODE - Falloff function for details and images.

The falloff spawnarg controls the distribution of the entities.

lode_floor

Default: 0 (Off). If set to 1, all entities of this class will be floored, that is their position will be adjusted so that they touch whatever is under them. This works with dynamically created terrain or terrain consisting of irregular heights like when it was made from patches. See also lode_collide and lode_stack.

lode_max_entities

Default: 0. The maximum number of entities generated. If 0 (the default), then the number will be computed from the accordingly to the lode_score of this class and the max_entities from the LODE. If greater than zero, only so many entities will be generated and the spawnarg lode_score will be ignored for this class.

Note that the LODE might generate less entities, f.i. when entities do not all fit into the LODE area, or the inhibitors inhibit too many entities.

lode_score

Sets the score for this entity class. All scores will be summed together, and the score for each class will be the percentage of entities of this class to create. Some examples:

• Entity A: 4, Entity B: 5: Sum: 9, 4/9 of all entities will be of class A, and 5/9 will be class B
• Entity A: 1, Entity B: 2: Entity C: 7, Sum: 10, 1/10 of all entities will be of class A, 2/10 will be class B and 7/10 will be of class C

lode_spacing

Defines a minimum distance between placed entities of this class. Overrides the default setting from "spacing" on the LODE. If set to > 0, implies collision check at creation time between all entities of this class.

lode_rotate_min/lode_rotate_max

Default: Same as the LODE specifies (which defaults to 0 0 0 and 5 360 5).

The range for each axis on how much the entity will be randomly rotated around it. I the order "Ymin Zmin Xmin" and "Ymax Zmax Xmax" (or pitch, yaw, roll (yzx), where the actual rotation order will be yaw, pitch, roll, e.g. "zyx").

The default makes entities rotate randomly between 0 and 360 degress around Z (turn), and tilt between 0 and 5 degrees on the other two axes. Use 0 0 0 and 0 360 0 for entities that should be perfectly upright.

lode_bunching

Default: What the LODE specifies with bunching. Number from 0.0 to 1.0, giving the probability that a randomly created entities "bunches" up with an already existing entity. Can be override per entity class with lode_bunching.

lode_noinhibit

Default: 0 (false). Boolean.

If set to 1 (true), entities of this class will not be inhibited by any inhibitor linked to this LODE. Can be used f.i. to add grass and trees to an area, but make it so that trees are inhibited in certain areas, but grass never is.

For more control over non-inhibition of entities, see the section #Spawnargs on the Inhibitors (atdm:no_lode).

lode_sink_min/lode_sink_max

Default: Both to what the LODE specifies with sink_min and sink_max. In Units.

Define the range (minimum/maximum) of how much entities randomly sink into the floor. This is in addition to the "base line floor" of the entity, which is either determined by the placement of the template entity in DR (if "lode_floor" is false), or by the point where the entity origin touches the ground (if "lode_floor" is true).

This can f.i. be used to let all floored entities sink 1 or 2 units into the ground, to avoid that the entity, if placed on a step incline, sinks at one side into the ground, but stands "on air" on the other side.

Note: If lode_sink_max is smaller than lode_sink_min, it will be set to lode_sink_min.

Usages:

• lode_sink_min = 0, lode_sink_max = 0 - all entities are at the same "height"
• lode_sink_min = 5, lode_sink_max = 5 - all entities sink 5 units "down"
• lode_sink_min = 1, lode_sink_max = 15 - all entities sink between 1 and 15 units "down"
• lode_sink_min = -10, lode_sink_max = -5 - all entities raise between 5 and 10 units "up" (note seemingly reversed numbers to make min smaller than max)

"Down" here refers to the gravity normal of the Lode, e.g. at the moment just down the z-axis.

lode_material_xyz

Defines the probability that an entity will spawn on the given material. If used, the "lode_probability" spawnarg will also be queried and used. Example:

 "lode_material_grass" "1.0"
 "lode_material_dirt" "0.5"
 "lode_probability" "0"

This would spawn the entity always on grass, only half the time on dirt, and never on anything else (the "lode_probability" "0").

The other way round is also possible:

 "lode_material_stone" "0"
 "lode_material_metal" "0"
 "lode_probability" "1.0"

Meaning: Never spawn on metal or stone, but always on anything else.

lode_probability

Default 1.0. Is used as default probability for entities to spawn on certain surface types, but only when you define material_xyz spawnargs. See there for an explanation on how this lets you spawn entities only on some surfaces but not on others.

lode_stack

Section not done yet.

lode_collide

Section not done yet.

Other LOD spawnargs

You can of course use other LOD spawnargs on the entities that the LODE creates. See LOD for a list.

Script events

There exist a few script events that can be used either from scripts, or by setting up a trigger that links to an atdm:target_callobjectfunction with the spawnarg call set to one of the script functions below:

Deactivate()

Deactivates the thinking of this LODE. Spawned entities stay where they are.

Activate()

Activates the LODE (e.g. it starts to think) again. If nec., the LODE will also spawn and unhide any entities that it needs.

CullAll()

Removes all entities under control of this LODE from the game. Only useful if either the player is very far away, or if you have called Deactivate() before - otherwise the entities might be spawned again in the next frame.

Ideas

Worth considering:

lode_strategy

How the entities will be placed. Default: "random", but can be "grid" (needs a way to specifiy grid-size, grid spacing, and random-offset from grid position).

lode_oriented_z

If true, orient the entity perpendicular to the floor, before applying the random rotation values. Good for things that should stand on step inclines.

See also

• LOD System
• LODE Usage - Example on how to use LODE in real-map scenarios
• LODE_-_Falloff_function - How to use "falloff" "func" to get more complicated distribution patterns