# Types/AutoplaceSpecification

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, ...).

## Contents

## General structure

Autoplace specification consists of a set of peaks that describe conditions for placing the entity and several parameters.

## Properties

### 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. See Probability Calculation.

### max_probability

**Type**: Types/double

**Default**: 1

**Since**: 0.9.0

Multiplier for output of the sharpness filter. See #Probability_Calculation.

### 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/strings for entities allowed on transitions.

### richness_base

**Type**: Types/double

**Default**: 0

### richness_multiplier

**Type**: Types/double

**Default**: 0

### control

**Type**: Types/string

**Default**: ""

ID of autoplace control that applies to this entity.

### force

**Type**: Types/string

**Default**: "neutral"

**Since**: 0.8.0

Force of the placed entity. One of "enemy", "player" or "neutral". Only matters for EntityWithForce or EntityWithOwner.

### order

**Type**: Types/string

**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.

### size_control_multiplier

** Type**: Types/double

**Default**: Magic. Based on sum of influences of noises.

**Since**: 0.9.2

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.

### peaks

**Type**: list of #Autoplace Peaks

If this property is missing, then the whole autoplace specification is interpreted as a single peak

## 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 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

Influence of a peak is obtained by calculating a distance from each of its dimensions. A 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.

## Probability_Calculation

Probability of placing an entity at a given position is calculated as a sum of influences plus a bonus for autoplace control, passed through a sharpening filter and multiplied by max_probability

## 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_base.

Note, that when calculating richness, influences of individual peaks use 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 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.