Types/AutoplaceSpecification: Difference between revisions
m (removed version mentions) |
(Updated to 0.17) |
||
| Line 8: | Line 8: | ||
can be defined either in terms of a set of peaks, or using explicit expressions. | can be defined either in terms of a set of peaks, or using explicit expressions. | ||
== General | == General properties == | ||
=== control === | === control === | ||
| Line 56: | Line 56: | ||
Restricts surfaces or transition the entity can appear on. | Restricts surfaces or transition the entity can appear on. | ||
Contains list of specifications | Contains list of specifications. Each specification is a single [[Types/string]] with the name of an allowed tile, or a list of two tile names for entities allowed on transitions. | ||
list of two | |||
== Properties for Expression-based AutoplaceSpecifications == | == Properties for Expression-based AutoplaceSpecifications == | ||
| Line 86: | Line 85: | ||
Parameter of the sharpness filter for post-processing probability of entity placement. Value of 0 disables the filter, with value 1, the filter is a step function centered around 0.5. | Parameter of the sharpness filter for post-processing probability of entity placement. Value of 0 disables the filter, with value 1, the filter is a step function centered around 0.5. | ||
=== max_probability === | === max_probability === | ||
| Line 94: | Line 92: | ||
Multiplier for output of the sharpness filter. | Multiplier for output of the sharpness filter. | ||
=== richness_base === | === richness_base === | ||
| Line 101: | Line 98: | ||
'''Default''': 0 | '''Default''': 0 | ||
See [[# | See [[#Richness calculation]]. | ||
=== richness_multiplier === | === richness_multiplier === | ||
| Line 108: | Line 105: | ||
'''Default''': 0 | '''Default''': 0 | ||
See [[# | See [[#Richness calculation]]. | ||
=== richness_multiplier_distance_bonus === | === richness_multiplier_distance_bonus === | ||
| Line 116: | Line 113: | ||
Bonus to richness multiplier per tile of distance from starting point. | Bonus to richness multiplier per tile of distance from starting point. | ||
See [[# | See [[#Richness calculation]]. | ||
=== random_probability_penalty === | === random_probability_penalty === | ||
| Line 125: | Line 122: | ||
A random value between 0 and this number is subtracted from a probability after sharpness filter. | A random value between 0 and this number is subtracted from a probability after sharpness filter. | ||
Only works for entities. | Only works for entities. | ||
=== peaks === | === peaks === | ||
'''Type''': list of [[#Autoplace Peaks]] | '''Type''': list of [[#Autoplace Peaks]] | ||
If this property is missing, then the whole autoplace specification is interpreted as a single peak | If this property is missing, then the whole autoplace specification is interpreted as a single peak. | ||
=== coverage === | === coverage === | ||
| Line 146: | Line 142: | ||
=== starting_area_amount === | === starting_area_amount === | ||
''' Type''': [[Types/ | ''' Type''': [[Types/uint32]] | ||
'''Default''': 0 | '''Default''': 0 | ||
| Line 162: | Line 158: | ||
Controls approximate radius of the blob in tiles. | Controls approximate radius of the blob in tiles. | ||
== Autoplace | == Autoplace peaks == | ||
=== influence === | === influence === | ||
| Line 170: | Line 166: | ||
Influence multiplier. | Influence multiplier. | ||
See [[# | See [[#Influence calculation]]. | ||
=== min_influence === | === min_influence === | ||
| Line 178: | Line 174: | ||
Minimal influence (after all calculations) of current peak. | Minimal influence (after all calculations) of current peak. | ||
See [[#Influence | See [[#Influence calculation]]. | ||
=== max_influence === | === max_influence === | ||
| Line 186: | Line 182: | ||
Maximal influence (after all calculations) of current peak. | Maximal influence (after all calculations) of current peak. | ||
See [[#Influence | See [[#Influence calculation]]. | ||
=== richness_influence === | === richness_influence === | ||
| Line 194: | Line 190: | ||
Bonus for influence multiplier when calculating richness. | Bonus for influence multiplier when calculating richness. | ||
See [[#Influence | See [[#Influence calculation]]. | ||
=== noise_layer === | === noise_layer === | ||
| Line 201: | Line 197: | ||
'''Default''': "" | '''Default''': "" | ||
Name of [[Prototype/NoiseLayer|noise layer]] to use for this peak. | |||
If empty, then no noise is added to this peak. | If empty, then no noise is added to this peak. | ||
=== noise_persistence === | === noise_persistence === | ||
| Line 210: | Line 205: | ||
'''Default''': 0.5 | '''Default''': 0.5 | ||
Must be between 0 and 1. Persistence of the noise. | |||
Persistence of the noise | |||
=== noise_octaves_difference === | === noise_octaves_difference === | ||
'''Type''': [[Types/ | '''Type''': [[Types/double]] | ||
'''Default''': 0 | '''Default''': 0 | ||
Difference between number of octaves of the world and of the noise. | Difference between number of octaves of the world and of the noise. | ||
=== noise_scale === | |||
'''Type''': [[Types/double]] | |||
'''Default''': 1 | |||
=== *_optimal === | === *_optimal === | ||
| Line 254: | Line 248: | ||
== Dimensions == | == Dimensions == | ||
Peaks may reference a number of tile properties, specifying range of optimal values of the property | Peaks may reference a number of tile properties, specifying range of optimal values of the property and a range over which it is interpolated to no effect. | ||
and a range over which it is interpolated to no effect. | |||
Currently the properties are: | Currently the properties are: | ||
* starting_area_weight | * starting_area_weight — Number from 1 (inside starting area) to 0 (not influenced by starting area). | ||
* elevation — elevation of the terrain, up to 5000. Values smaller than 0 mean under water (elevation < 0 doesn't imply water tile, though) | |||
* elevation | * water — amount of available water on tile. Very simple dependence on elevation for now. | ||
* water | * temperature — average temperature on tile. Depends on elevation and some noise. | ||
* temperature | * aux | ||
* tier_from_start | * tier_from_start — Distance from start in starting area sizes, rounded to integers. | ||
* distance | |||
== Influence | == Influence calculation == | ||
There are two possible modes in which influence is calculated. | There are two possible modes in which influence is calculated. | ||
| Line 278: | Line 272: | ||
Finally this value is clamped to a range between [[#min_influence|min_influence]] and [[#max_influence|max_influence]]. | Finally this value is clamped to a range between [[#min_influence|min_influence]] and [[#max_influence|max_influence]]. | ||
== | <!-- Outdated - from 2016 | ||
== Probability calculation == | |||
Probability of placing an entity at a given position is calculated as a sum of influences plus a [[#size_control_multiplier|bonus for autoplace control]], passed through a [[#sharpness|sharpening filter]], multiplied by [[#max_probability|max_probability]] and finally a random value gets subtracted. | Probability of placing an entity at a given position is calculated as a sum of influences plus a [[#size_control_multiplier|bonus for autoplace control]], passed through a [[#sharpness|sharpening filter]], multiplied by [[#max_probability|max_probability]] and finally a random value gets subtracted. | ||
max_probability * sharpness_filter(sum of influences + size modifier from GUI) - random(0, random_probability_penalty) | max_probability * sharpness_filter(sum of influences + size modifier from GUI) - random(0, random_probability_penalty) | ||
--> | |||
== | == Richness calculation == | ||
If an entity is to be placed at a position and it a resource or a part of an enemy base, then richness is calculated in the next step. | If an entity is to be placed at a position and it's a resource or a part of an enemy base, then richness is calculated in the next step. | ||
as sum of influences * ([[#richness_multiplier|richness_multiplier]] + distance * [[#richness_multiplier_distance_bonus|richness_multiplier_distance_bonus]]) + [[#richness_base|richness_base]]. | as sum of influences * ([[#richness_multiplier|richness_multiplier]] + distance * [[#richness_multiplier_distance_bonus|richness_multiplier_distance_bonus]]) + [[#richness_base|richness_base]]. | ||
Note, that when calculating richness, influences of individual peaks use [[#richness_influence|richness_influence]] bonus. | Note, that when calculating richness, influences of individual peaks use [[#richness_influence|richness_influence]] bonus. | ||
<!-- Most likely outdated - from 2016. | |||
== Noise == | == Noise == | ||
A peak may have a noise multiplied with its influence. | A peak may have a noise multiplied with its influence. | ||
| Line 298: | Line 293: | ||
Intended use is to have noise layers separate for different types of objects that might appear (trees vs dry_trees vs enemy-bases). | Intended use is to have noise layers separate for different types of objects that might appear (trees vs dry_trees vs enemy-bases). | ||
Also it has proven useful not to mix peaks containing noise with peaks referencing tile properties. | Also it has proven useful not to mix peaks containing noise with peaks referencing tile properties. | ||
--><!-- Outdated - from 2016. | |||
== Controls == | == Controls == | ||
If the autoplace specification has a [[#control|control]] selected, then its influence is affected by the row in map generator gui. | If the autoplace specification has a [[#control|control]] selected, then its influence is affected by the row in map generator gui. | ||
| Line 308: | Line 303: | ||
In case you are wondering why we can "very slightly increase number of octaves" and not just add whole octaves, it is because we sacrificed a goat to gods of computer graphics and to Ken Perlin in particular. | In case you are wondering why we can "very slightly increase number of octaves" and not just add whole octaves, it is because we sacrificed a goat to gods of computer graphics and to Ken Perlin in particular. | ||
--> | |||
Revision as of 18:40, 8 November 2019
Autoplace specification is used to determine which entities are placed when generating map. Currently it is used for enemy bases, resources and other entities (trees, fishes, ...).
General structure
Autoplace specification describe conditions for placing tiles, entities, and decoratives during surface generation. Probability (of placement on any given tile) and richness (which has different meaning depending on the thing being placed) can be defined either in terms of a set of peaks, or using explicit expressions.
General properties
control
Type: Types/string
Default: ""
ID of autoplace control that applies to this entity.
default_enabled
Type: Types/bool
Default: true
Indicates whether the thing should be placed even if MapGenSettings do not provide frequency/size/richness for it (either for the specific prototype of for the control named by AutoplaceSpecification.control).
If true, normal frequency/size/richness (value=1) are used in that case. Otherwise it is treated as if 'none' were selected.
force
Type: Types/string
Default: "neutral"
Force of the placed entity. One of "enemy", "player", "neutral", or a custom force name. Only matters for EntityWithForce or EntityWithOwner.
order
Type: Types/Order
Default: ""
Order for placing the entity (has no effect when placing tiles). Entities whose order compares less are placed earlier (this influences placing multiple entities which collide with itself), from entities with equal order string only one with the highest probability is placed.
placement_density
Type: Types/uint32
Default: 1
For entities and decoratives, how many times to attempt to place on each tile (probability and collisions are taken into account each attempt).
tile_restriction
Type: list of specifications, see below
Default: empty list
Restricts surfaces or transition the entity can appear on.
Contains list of specifications. Each specification is a single Types/string with the name of an allowed tile, or a list of two tile names for entities allowed on transitions.
Properties for Expression-based AutoplaceSpecifications
probability_expression
Type: Types/NoiseExpression
If specified, provides a noise expression that will be evaluated at every point on the map to determine probability. If left blank, probability is determined by the 'peaks' system based on the properties listed below.
richness_expression
Type: Types/NoiseExpression
If specified, provides a noise expression that will be evaluated to determine richness.
If probability_expression is specified and richness_expression is not, then probability_expression will be used as the richness expression.
If neither are specified, then probability and richness are both determined by the 'peaks' system based on the properties listed below.
Properties for Peak-based AutoplaceSpecifications
sharpness
Type: Types/double
Default: 0
Parameter of the sharpness filter for post-processing probability of entity placement. Value of 0 disables the filter, with value 1, the filter is a step function centered around 0.5.
max_probability
Type: Types/double
Default: 1
Multiplier for output of the sharpness filter.
richness_base
Type: Types/double
Default: 0
richness_multiplier
Type: Types/double
Default: 0
richness_multiplier_distance_bonus
Type: Types/double
Default: 0
Bonus to richness multiplier per tile of distance from starting point. See #Richness calculation.
random_probability_penalty
Type: Types/double
Default: 0
A random value between 0 and this number is subtracted from a probability after sharpness filter. Only works for entities.
peaks
Type: list of #Autoplace Peaks
If this property is missing, then the whole autoplace specification is interpreted as a single peak.
coverage
Type: Types/double
Default: Calculated from existing peaks.
Sets a fraction of surface that should be covered by this item.
Internally this adds an additive influence modifier, so that expected fraction of tiles where total influence > 0.5 (the threshold for sharpness filter) equals the parameter.
Because of the autoplace system's complexity, this is only accurate on simple rules and does some simplification on the more complex ones:
- There is always just one combination of tile properties (see #Dimensions) for which the coverage is calculated. This combination is given by a first *_optimal value encountered of each type other than starting_area and tier_from_start. Starting_area value is fixed to 0 and tier_from_start to 4.
- min_influence and max_influence are completely ignored.
starting_area_amount
Type: Types/uint32
Default: 0
If this value is non zero, influence of this entity will be calculated differently in starting area: For each entity with this parameter a position in starting area is selected and a blob is placed centered on this position. The central tile of this blob will have approximately amount of resources selected by this value.
starting_area_size
Type: Types/double
Default: 10
See #starting_area_amount. Controls approximate radius of the blob in tiles.
Autoplace peaks
influence
Type: Types/double
Default: 1
Influence multiplier. See #Influence calculation.
min_influence
Type: Types/double
Default: min double
Minimal influence (after all calculations) of current peak. See #Influence calculation.
max_influence
Type: Types/double
Default: max double
Maximal influence (after all calculations) of current peak. See #Influence calculation.
richness_influence
Type: Types/double
Default: 0
Bonus for influence multiplier when calculating richness. See #Influence calculation.
noise_layer
Type: Types/string
Default: ""
Name of noise layer to use for this peak. If empty, then no noise is added to this peak.
noise_persistence
Type: Types/double
Default: 0.5
Must be between 0 and 1. Persistence of the noise.
noise_octaves_difference
Type: Types/double
Default: 0
Difference between number of octaves of the world and of the noise.
noise_scale
Type: Types/double
Default: 1
*_optimal
Type: Types/double
Optimal value of a tile property. If the property is close to this value, peak influence is 1. See #Dimensions.
*_range
Type: Types/double
Default: 0
Distance from the optimal parameters that is still considered optimal. See #Dimensions.
*_max_range
Type: Types/double
Distance from the optimal parameters that get influence of -1. See #Dimensions.
*_top_property_limit
Type: Types/double
Default: max double
Limit distance from the optimum on a single (positive) side. This is pure magic. See #Dimensions.
Dimensions
Peaks may reference a number of tile properties, specifying range of optimal values of the property and a range over which it is interpolated to no effect.
Currently the properties are:
- starting_area_weight — Number from 1 (inside starting area) to 0 (not influenced by starting area).
- elevation — elevation of the terrain, up to 5000. Values smaller than 0 mean under water (elevation < 0 doesn't imply water tile, though)
- water — amount of available water on tile. Very simple dependence on elevation for now.
- temperature — average temperature on tile. Depends on elevation and some noise.
- aux
- tier_from_start — Distance from start in starting area sizes, rounded to integers.
- distance
Influence calculation
There are two possible modes in which influence is calculated. By default influence is calculated as a sum of influences of peaks (see next paragraph). When #starting_area_amount parameter is non zero a position in starting area is selected and a blob is placed centered on this position. Influence is then a maximum of the default calculated value and a value obtained from this blob.
Influence of a peak is obtained by calculating a distance from each of its dimensions and sum of these individual distances is used as a distance from optimal conditions. Based on this distance a peak gets influence between -1 and 1, which is then multiplied by the noise function, if it is specified, and by the influence constant (or by influence + richness_influence if calculating richness). Finally this value is clamped to a range between min_influence and max_influence.
Richness calculation
If an entity is to be placed at a position and it's a resource or a part of an enemy base, then richness is calculated in the next step. as sum of influences * (richness_multiplier + distance * richness_multiplier_distance_bonus) + richness_base.
Note, that when calculating richness, influences of individual peaks use richness_influence bonus.