Types/AutoplaceSpecification: Difference between revisions

Latest revision as of 19:25, 21 January 2022

Note: The property names and types on this page are up to date. However, most of the textual components of this page have not been updated since 2016, so they are not reliable for the latest version of the game.

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 Prototype/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 tiles or tile transitions 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.

@@ Line 1: / Line 1: @@
-{{Languages}}
+<span style="color:#ff0000"> '''Note: The property names and types on this page are up to date. However, most of the textual components of this page have not been updated since 2016, so they are not reliable for the latest version of the game.''' </span>
 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 [[Prototype/AutoplaceControl|autoplace control]] that applies to this entity.
+=== default_enabled ===
+'''Type''': [[Types/bool]]
+'''Default''': true
+Indicates whether the thing should be placed even if [http://lua-api.factorio.com/latest/Concepts.html#MapGenSettings 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]]
-== General structure ==
+'''Default''': "neutral"
-Autoplace specification consists of a set of peaks that describe conditions for placing the entity and
-several parameters.
-== Properties ==
+Force of the placed entity. One of "enemy", "player", "neutral", or a custom force name. Only matters for [[Prototype/EntityWithOwner]].
-=== sharpness ===
+=== order ===
-'''Type''': [[Types/double]]
+'''Type''': [[Types/Order]]
-'''Default''': 0
+'''Default''': ""
-[[File:sharpness.png|thumb|Example of sharpness filter with value 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.
+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.
-See [[#Probability_Calculation|Probability Calculation]].
-=== max_probability ===
+=== placement_density ===
-'''Type''': [[Types/double]]
+'''Type''': [[Types/uint32]]
 '''Default''': 1
-'''Since''': 0.9.0
+For entities and decoratives, how many times to attempt to place on each tile
+(probability and collisions are taken into account each attempt).
-Multiplier for output of the sharpness filter.
-See [[#Probability_Calculation]].
 === tile_restriction ===
@@ Line 34: / Line 56: @@
 '''Default''': empty list
-'''Since''': 0.9.0
+Restricts tiles or tile transitions 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.
-Restricts surfaces or transition the entity can appear on.
+== Properties for Expression-based AutoplaceSpecifications ==
-Contains list of specifications, each specification is a single [[Types/string]] with the ID of an allowed tile, or a
+=== probability_expression ===
-list of two [[Types/string]]s for entities allowed on transitions.
+'''Type''': [[Types/NoiseExpression]]
-=== richness_base ===
+If specified, provides a noise expression that will be evaluated at every point on the map to determine probability.
-'''Type''': [[Types/double]]
+If left blank, probability is determined by the 'peaks' system based on the properties listed below.
-'''Default''': 0
+=== richness_expression ===
+'''Type''': [[Types/NoiseExpression]]
-See [[#Richness_Calculation]].
+If specified, provides a noise expression that will be evaluated to determine richness.
-=== richness_multiplier ===
+If probability_expression is specified and richness_expression is not,
-'''Type''': [[Types/double]]
+then probability_expression will be used as the richness expression.
-'''Default''': 0
+If neither are specified, then probability and richness are both determined by the 'peaks' system based on the properties listed below.
-See [[#Richness_Calculation]].
+== Properties for Peak-based AutoplaceSpecifications ==
-=== richness_multiplier_distance_bonus ===
+=== sharpness ===
 '''Type''': [[Types/double]]
 '''Default''': 0
+[[File:sharpness.png|thumb|Example of sharpness filter with value 0.5]]
-Bonus to richness multiplier per tile of distance from starting point.
+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.
-See [[#Richness_Calculation]].
+=== max_probability ===
+'''Type''': [[Types/double]]
-=== control ===
+'''Default''': 1
-'''Type''': [[Types/string]]
-'''Default''': ""
+Multiplier for output of the sharpness filter.
-ID of [[Prototype/AutoplaceControl|autoplace control]] that applies to this entity.
+=== richness_base ===
+'''Type''': [[Types/double]]
-=== force ===
+'''Default''': 0
-'''Type''': [[Types/string]]
-'''Default''': "neutral"
+See [[#Richness calculation]].
-'''Since''': 0.8.0
+=== richness_multiplier ===
+'''Type''': [[Types/double]]
-Force of the placed entity. One of "enemy", "player" or "neutral". Only matters for EntityWithForce or EntityWithOwner.
+'''Default''': 0
-=== order ===
+See [[#Richness calculation]].
-'''Type''': [[Types/string]]
-'''Default''': ""
+=== richness_multiplier_distance_bonus ===
+'''Type''': [[Types/double]]
-'''Since''': 0.9.0
+'''Default''': 0
-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.
+Bonus to richness multiplier per tile of distance from starting point.
+See [[#Richness calculation]].
-=== size_control_multiplier ===
-''' Type''': [[Types/double]]
-'''Default''': Magic. Based on sum of influences of noises.
-'''Since''': 0.9.2
-'''Until''': 0.12.x
-This value times the size control setting is added to influence right before sharpness filter.
-Very small has a multiplier of -1, very big has 1.5.
-This value is replaced by ```coverage``` parameter in 0.13.0.
 === random_probability_penalty ===
@@ Line 109: / Line 124: @@
 A random value between 0 and this number is subtracted from a probability after sharpness filter.
 Only works for entities.
-See [[#Probability_Calculation]].
 === 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 ===
@@ Line 120: / Line 134: @@
 '''Default''': Calculated from existing peaks.
-'''Since''': 0.13.0
 Sets a fraction of surface that should be covered by this item.
@@ Line 131: / Line 143: @@
 * min_influence and max_influence are completely ignored.
-== Autoplace Peaks ==
+=== 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 ===
@@ Line 139: / Line 168: @@
 Influence multiplier.
-See [[#Influence_Calculation]].
+See [[#Influence calculation]].
 === min_influence ===
@@ Line 147: / Line 176: @@
 Minimal influence (after all calculations) of current peak.
-See [[#Influence Calculation]].
+See [[#Influence calculation]].
 === max_influence ===
@@ Line 155: / Line 184: @@
 Maximal influence (after all calculations) of current peak.
-See [[#Influence Calculation]].
+See [[#Influence calculation]].
 === richness_influence ===
@@ Line 163: / Line 192: @@
 Bonus for influence multiplier when calculating richness.
-See [[#Influence Calculation]].
+See [[#Influence calculation]].
 === noise_layer ===
@@ Line 170: / Line 199: @@
 '''Default''': ""
-ID of [[Prototype/NoiseLayer|noise layer]] to use for this peak.
+Name of [[Prototype/NoiseLayer|noise layer]] to use for this peak.
 If empty, then no noise is added to this peak.
-See [[#Noise]].
 === noise_persistence ===
@@ Line 179: / Line 207: @@
 '''Default''': 0.5
-'''Min''': 0
+Must be between 0 and 1. Persistence of the noise.
-'''Max''': 1
-Persistence of the noise.
-See [[#Noise]].
 === noise_octaves_difference ===
-'''Type''': [[Types/int]]
+'''Type''': [[Types/double]]
 '''Default''': 0
 Difference between number of octaves of the world and of the noise.
-See [[#Noise]]
+=== noise_scale ===
+'''Type''': [[Types/double]]
+'''Default''': 1
 === *_optimal ===
@@ Line 223: / Line 250: @@
 == 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.
+All tile properties are of [[Types/double]].
 Currently the properties are:
-* starting_area_weight -- Number from 1 (inside starting area) to 0 (not influenced by starting area).
+* starting_area_weight — Number from 1 (inside starting area) to 0 (not influenced by starting area).
-* roughness -- a number between -1.5 and 1.5 which describe roughness of the terrain. In 0.7.2 roughness is visible only on the edges of lakes (smooth vs jagged).
+* elevation — elevation of the terrain, up to 5000. Values smaller than 0 mean under water (elevation < 0 doesn't imply water tile, though)
-* 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.
-* 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.
-* 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.
+* tier_from_start — Distance from start in starting area sizes, rounded to integers.
+* distance
-You can see sheets on the generation of trees, doodads, biomes, water and tiles on this page: [[AutoplaceSheets]]
+== Influence calculation ==
-== Influence Calculation ==
+There are two possible modes in which influence is calculated.
-Influence of a peak is obtained by calculating a distance from each of its dimensions.
+By default influence is calculated as a sum of influences of peaks (see next paragraph).
-A sum of these individual distances is used as a distance from optimal conditions.
+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|influence]] constant (or by [[#influence|influence]] + [[#richness_influence|richness_influence]]
@@ Line 245: / Line 275: @@
 Finally this value is clamped to a range between [[#min_influence|min_influence]] and [[#max_influence|max_influence]].
-== Probability_Calculation ==
+<!-- 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.
 max_probability * sharpness_filter(sum of influences + size modifier from GUI) - random(0, random_probability_penalty)
+-->
-== Richness_Calculation ==
+== 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]].
 Note, that when calculating richness, influences of individual peaks use [[#richness_influence|richness_influence]] bonus.
+<!-- Most likely outdated - from 2016.
 == Noise ==
 A peak may have a noise multiplied with its influence.
@@ Line 265: / Line 296: @@
 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.
+--><!-- Outdated - from 2016.
 == Controls ==
 If the autoplace specification has a [[#control|control]] selected, then its influence is affected by the row in map generator gui.
@@ Line 275: / Line 306: @@
 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.
+ -->

Types/AutoplaceSpecification: Difference between revisions

Latest revision as of 19:25, 21 January 2022

General structure

General properties

control

default_enabled

force

order

placement_density

tile_restriction

Properties for Expression-based AutoplaceSpecifications

probability_expression

richness_expression

Properties for Peak-based AutoplaceSpecifications

sharpness

max_probability

richness_base

richness_multiplier

richness_multiplier_distance_bonus

random_probability_penalty

peaks

coverage

starting_area_amount

starting_area_size

Autoplace peaks

influence

min_influence

max_influence

richness_influence

noise_layer

noise_persistence

noise_octaves_difference

noise_scale

*_optimal

*_range

*_max_range

*_top_property_limit

Dimensions

Influence calculation

Richness calculation

Navigation menu

Search