Types/AutoplaceSpecification: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(Document 'placement_density' and break expression and peak properties into different sections)
(Removed old prototype docs)
Tag: Replaced
 
(12 intermediate revisions by 3 users not shown)
Line 1: Line 1:
Autoplace specification is used to determine which entities are placed when generating map.
<div class="stub"><p>'''The prototype docs have moved to a new website with an improved format.''' This documentation page can now be found here: [https://lua-api.factorio.com/latest/types/AutoplaceSpecification.html https://lua-api.factorio.com/latest/types/AutoplaceSpecification.html]
Currently it is used for enemy bases, resources and other entities (trees, fishes, ...).


== General structure ==
</p><p>This wiki page is no longer updated and '''will be removed at some point in the future''', so please update your browser bookmarks or other links that sent you here. If you'd like to contribute to the new docs, you can leave your feedback [https://forums.factorio.com/viewforum.php?f=233 on the forums].</p></div>
 
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 ==
 
=== default_enabled ===
'''Type''': [[Types/boolean]]
 
'''Default''': true
 
=== 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
 
'''Since''': 0.9.0
 
Restricts surfaces or transition the entity can appear on.
 
Contains list of specifications, each specification is a single [[Types/string]] with the ID of an allowed tile, or a
list of two [[Types/string]]s for entities allowed on transitions.
 
=== force ===
'''Type''': [[Types/string]]
 
'''Default''': "neutral"
 
'''Since''': 0.8.0
 
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''': ""
 
'''Since''': 0.9.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.
 
== 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
[[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.
See [[#Probability_Calculation|Probability Calculation]].
 
=== max_probability ===
'''Type''': [[Types/double]]
 
'''Default''': 1
 
'''Since''': 0.9.0
 
Multiplier for output of the sharpness filter.
See [[#Probability_Calculation]].
 
=== richness_base ===
'''Type''': [[Types/double]]
 
'''Default''': 0
 
See [[#Richness_Calculation]].
 
=== richness_multiplier ===
'''Type''': [[Types/double]]
 
'''Default''': 0
 
See [[#Richness_Calculation]].
 
=== richness_multiplier_distance_bonus ===
'''Type''': [[Types/double]]
 
'''Default''': 0
 
Bonus to richness multiplier per tile of distance from starting point.
See [[#Richness_Calculation]].
 
=== control ===
'''Type''': [[Types/string]]
 
'''Default''': ""
 
ID of [[Prototype/AutoplaceControl|autoplace control]] that applies to this entity.
 
=== 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 ===
'''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.
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
 
=== coverage ===
''' Type''': [[Types/double]]
 
'''Default''': Calculated from existing peaks.
 
'''Since''': 0.13.0
 
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/double]]
 
'''Default''': 0
 
'''Since''': 0.13.10
 
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
 
'''Since''': 0.13.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''': ""
 
ID of [[Prototype/NoiseLayer|noise layer]] to use for this peak.
If empty, then no noise is added to this peak.
See [[#Noise]].
 
=== noise_persistence ===
'''Type''': [[Types/double]]
 
'''Default''': 0.5
 
'''Min''': 0
 
'''Max''': 1
 
Persistence of the noise.
See [[#Noise]].
 
=== noise_octaves_difference ===
'''Type''': [[Types/int]]
 
'''Default''': 0
 
Difference between number of octaves of the world and of the noise.
See [[#Noise]]
 
=== *_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).
* 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)
* 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.
* tier_from_start -- Distance from start in starting area sizes, rounded to integers.
 
== 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|influence]] constant (or by [[#influence|influence]] + [[#richness_influence|richness_influence]]
if calculating richness).
Finally this value is clamped to a range between [[#min_influence|min_influence]] and [[#max_influence|max_influence]].
 
== 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 ==
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.
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.
 
== Noise ==
A peak may have a noise multiplied with its influence.
Noise used is a 2D multioctave perlin noise ( http://freespace.virgin.net/hugo.elias/models/m_perlin.htm ).
Range of the noise is approximately from -1.5 to 1.5.
 
Factorio uses up to 256 different (non correlated) layers of perlin noise, a noise layer has to be defined as a prototype before use (see [[Prototype/NoiseLayer]]).
 
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.
 
== Controls ==
If the autoplace specification has a [[#control|control]] selected, then its influence is affected by the row in map generator gui.
Autoplace controls must be defined before use, see [[Prototype/AutoplaceControl]].
 
* Frequency -- If frequency is set to low, then it increases number of octaves for all noises in this specification
* Size -- Set to large adds a bonus to all the final influence, also very slightly increases number of octaves
* Richness -- Adds a simple multiplier to richness.
 
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.

Latest revision as of 14:32, 25 October 2024

The prototype docs have moved to a new website with an improved format. This documentation page can now be found here: https://lua-api.factorio.com/latest/types/AutoplaceSpecification.html

This wiki page is no longer updated and will be removed at some point in the future, so please update your browser bookmarks or other links that sent you here. If you'd like to contribute to the new docs, you can leave your feedback on the forums.

Retrieved from "https://wiki.factorio.com/index.php?title=Types/AutoplaceSpecification&oldid=202620"