Prototype/Entity: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
m (→‎Extensions: typos)
(remove_decoratives automatic explanation)
(40 intermediate revisions by 6 users not shown)
Line 1: Line 1:
==Basics==
{{Prototype parent|PrototypeBase}}
The common properties of all entities in the game.
Abstract base of all entities in the game.
Entity is basically everything that can be on the map (except tiles).
Entity is basically everything that can be on the map (except tiles).
For in game script access to entity, take a look at [http://lua-api.factorio.com/latest/LuaEntity.html LuaEntity]
For in game script access to entity, take a look at [http://lua-api.factorio.com/latest/LuaEntity.html LuaEntity]
{{Prototype TOC|''abstract''}}


== Extensions ==
== Extensions ==
<div class="factorio-list">
<div class="factorio-list">
* [[Prototype/Arrow]] '''arrow'''
* [[Prototype/Arrow]] '''arrow'''
* [[Prototype/ArtilleryFlare]] '''artillery-flare'''
* [[Prototype/ArtilleryProjectile]] '''artillery-projectile'''
* [[Prototype/ArtilleryProjectile]] '''artillery-projectile'''
* [[Prototype/Beam]] '''beam'''
* [[Prototype/Beam]] '''beam'''
Line 15: Line 18:
* [[Prototype/DeconstructibleTileProxy]] '''deconstructible-tile-proxy'''
* [[Prototype/DeconstructibleTileProxy]] '''deconstructible-tile-proxy'''
* [[Prototype/EntityGhost]] '''entity-ghost'''
* [[Prototype/EntityGhost]] '''entity-ghost'''
* [[Prototype/EntityParticle]] '''particle''' (for migration, cannot be used)
** [[Prototype/LeafParticle]] '''leaf-particle''' (for migration, cannot be used)
* [[Prototype/EntityWithHealth]] <abstract>
* [[Prototype/EntityWithHealth]] <abstract>
** [[Prototype/Accumulator]] '''accumulator'''
** [[Prototype/Accumulator]] '''accumulator'''
Line 20: Line 25:
** [[Prototype/Beacon]] '''beacon'''
** [[Prototype/Beacon]] '''beacon'''
** [[Prototype/Boiler]] '''boiler'''
** [[Prototype/Boiler]] '''boiler'''
** [[Prototype/Character]] '''player'''
** [[Prototype/BurnerGenerator]] '''burner-generator'''
** [[Prototype/Character]] '''character'''
** [[Prototype/Combinator]] <abstract>
** [[Prototype/Combinator]] <abstract>
*** [[Prototype/ArithmeticCombinator]] '''arithmetic-combinator'''
*** [[Prototype/ArithmeticCombinator]] '''arithmetic-combinator'''
Line 43: Line 49:
** [[Prototype/Gate]] '''gate'''
** [[Prototype/Gate]] '''gate'''
** [[Prototype/Generator]] '''generator'''
** [[Prototype/Generator]] '''generator'''
** [[Prototype/HeatInterface]] '''heat-interface'''
** [[Prototype/HeatPipe]] '''heat-pipe'''
** [[Prototype/HeatPipe]] '''heat-pipe'''
** [[Prototype/Inserter]] '''inserter'''
** [[Prototype/Inserter]] '''inserter'''
Line 48: Line 55:
** [[Prototype/Lamp]] '''lamp'''
** [[Prototype/Lamp]] '''lamp'''
** [[Prototype/LandMine]] '''land-mine'''
** [[Prototype/LandMine]] '''land-mine'''
** [[Prototype/LinkedContainer]] '''linked-container'''
** [[Prototype/Market]] '''market'''
** [[Prototype/Market]] '''market'''
** [[Prototype/MiningDrill]] '''mining-drill'''
** [[Prototype/MiningDrill]] '''mining-drill'''
** [[Prototype/OffshorePump]] '''offshore-pump'''
** [[Prototype/OffshorePump]] '''offshore-pump'''
** [[Prototype/Pipe]] '''pipe'''
** [[Prototype/Pipe]] '''pipe'''
*** [[Prototype/InfinityPipe]] '''infinity-pipe'''
** [[Prototype/PipeToGround]] '''pipe-to-ground'''
** [[Prototype/PipeToGround]] '''pipe-to-ground'''
** [[Prototype/PlayerPort]] '''player-port'''
** [[Prototype/PlayerPort]] '''player-port'''
Line 70: Line 79:
** [[Prototype/SimpleEntityWithForce]] '''simple-entity-with-force'''
** [[Prototype/SimpleEntityWithForce]] '''simple-entity-with-force'''
** [[Prototype/SolarPanel]] '''solar-panel'''
** [[Prototype/SolarPanel]] '''solar-panel'''
** [[Prototype/SpiderLeg]] '''spider-leg'''
** [[Prototype/StorageTank]] '''storage-tank'''
** [[Prototype/StorageTank]] '''storage-tank'''
** [[Prototype/TrainStop]] '''train-stop'''
** [[Prototype/TrainStop]] '''train-stop'''
** [[Prototype/TransportBeltConnectable]] <abstract>
** [[Prototype/TransportBeltConnectable]] <abstract>
*** [[Prototype/Loader]] '''loader'''
*** [[Prototype/LinkedBelt]] '''linked-belt'''
*** [[Prototype/Loader1x1]] '''loader-1x1'''
*** [[Prototype/Loader1x2]] '''loader'''
*** [[Prototype/Splitter]] '''splitter'''
*** [[Prototype/Splitter]] '''splitter'''
*** [[Prototype/TransportBelt]] '''transport-belt'''
*** [[Prototype/TransportBelt]] '''transport-belt'''
Line 90: Line 102:
**** [[Prototype/FluidWagon]] '''fluid-wagon'''
**** [[Prototype/FluidWagon]] '''fluid-wagon'''
**** [[Prototype/Locomotive]] '''locomotive'''
**** [[Prototype/Locomotive]] '''locomotive'''
*** [[Prototype/SpiderVehicle]] '''spider-vehicle'''
** [[Prototype/Wall]] '''wall'''
** [[Prototype/Wall]] '''wall'''
* [[Prototype/Explosion]] '''explosion'''
* [[Prototype/Explosion]] '''explosion'''
Line 96: Line 109:
* [[Prototype/FluidStream]] '''stream'''
* [[Prototype/FluidStream]] '''stream'''
* [[Prototype/FlyingText]] '''flying-text'''
* [[Prototype/FlyingText]] '''flying-text'''
* [[Prototype/HighlightBoxEntity]] '''highlight-box'''
* [[Prototype/ItemEntity]] '''item-entity'''
* [[Prototype/ItemEntity]] '''item-entity'''
* [[Prototype/ItemRequestProxy]] '''item-request-proxy'''
* [[Prototype/ItemRequestProxy]] '''item-request-proxy'''
* [[Prototype/LegacyDecorative]] '''decorative''' probably exists for migration
* [[Prototype/Particle]] '''particle'''
** [[Prototype/ArtilleryFlare]] '''artillery-flare'''
** [[Prototype/LeafParticle]] '''leaf-particle'''
* [[Prototype/ParticleSource]] '''particle-source'''
* [[Prototype/ParticleSource]] '''particle-source'''
* [[Prototype/Projectile]] '''projectile'''
* [[Prototype/Projectile]] '''projectile'''
Line 108: Line 118:
* [[Prototype/RocketSiloRocketShadow]] '''rocket-silo-rocket-shadow'''
* [[Prototype/RocketSiloRocketShadow]] '''rocket-silo-rocket-shadow'''
* [[Prototype/Smoke]] <abstract>
* [[Prototype/Smoke]] <abstract>
** [[Prototype/SimpleSmoke]] '''smoke'''
** [[Prototype/SimpleSmoke]] '''smoke''' (for migration, cannot be used)
** [[Prototype/SmokeWithTrigger]] '''smoke-with-trigger'''
** [[Prototype/SmokeWithTrigger]] '''smoke-with-trigger'''
* [[Prototype/SpeechBubble]] '''speech-bubble'''
* [[Prototype/Sticker]] '''sticker'''
* [[Prototype/Sticker]] '''sticker'''
* [[Prototype/TileGhost]] '''tile-ghost'''
* [[Prototype/TileGhost]] '''tile-ghost'''
Line 115: Line 126:


== Mandatory properties ==
== Mandatory properties ==
Inherits all properties from [[Prototype]].
Inherits all properties from [[PrototypeBase]].
 
=== order ===
:''See [[Prototype#order]]''
Inherited from [[Prototype]]. It is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-enemy.
 
=== icons, icon,  icon_size (IconSpecification) ===
'''Type''': [[Types/IconSpecification]]


{{Prototype property|icons, icon,  icon_size (IconSpecification)|[[Types/IconSpecification|IconSpecification]]}}
An icon is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-enemy.
An icon is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-enemy.


Line 130: Line 135:


== Optional properties ==
== Optional properties ==
=== collision_box ===
'''Type''': [[Types/BoundingBox]]


'''Default''': Empty={{0, 0}, {0, 0}} it means no collisions.
=== order ===
:''See [[PrototypeBase#order]]''
Inherited from [[PrototypeBase]].


The order string is taken from the items in <code>placeable_by</code> if they exist, or from an item that has its [[Prototype/Item#place_result|place_result]] set to this entity if it exists.
{{Prototype property|collision_box|[[Types/BoundingBox|BoundingBox]]|Empty=<nowiki>{{0, 0}, {0, 0}} means no collisions.</nowiki>|optional=true}}
Specification of the entity collision boundaries.
Specification of the entity collision boundaries.


Line 143: Line 151:
It should be near the center of the collision box, to keep correct entity drawing order. It must include the {0,0} coordinate.
It should be near the center of the collision box, to keep correct entity drawing order. It must include the {0,0} coordinate.


Note, that for buildings, it is custom to leave 0.1 wide border between the edge of the tile and the edge of the building, this lets the player move between the building and electric poles/inserters etc.
Note, that for buildings, it is customary to leave 0.1 wide border between the edge of the tile and the edge of the building, this lets the player move between the building and electric poles/inserters etc.
 
=== collision_mask ===
'''type''': [[Types/CollisionMask]]


'''Default''': Depends on entity type, if it is not defined in the entity type, it falls back to: {"item-layer", "object-layer", "player-layer", "water-tile"}
{{Prototype property|collision_mask|[[Types/CollisionMask|CollisionMask]]|<nowiki>{"item-layer", "object-layer", "player-layer", "water-tile"}</nowiki>|optional=true}}


Two entities can collide only if they share a layer from the collision mask.
Two entities can collide only if they share a layer from the collision mask.


=== selection_box ===
<div class="toccolours mw-collapsible mw-collapsed">
'''Type''': [[Types/BoundingBox]]
NOTE: '''Some entity types have their own default''' that differs from the above default. They are listed here:
<div class="mw-collapsible-content">
* [[Prototype/Arrow]] - no masks
* [[Prototype/ArtilleryFlare]] - no masks
* [[Prototype/ArtilleryProjectile]] - no masks
* [[Prototype/Beam]] - no masks
* [[Prototype/Car]] - <code>{"player-layer", "train-layer", "consider-tile-transitions"}</code>
* [[Prototype/Character]] - <code>{"player-layer", "train-layer", "consider-tile-transitions"}</code>
* [[Prototype/CharacterCorpse]] - no masks
* [[Prototype/Cliff]] - <code>{ "item-layer", "object-layer", "player-layer", "water-tile", "not-colliding-with-itself"}</code>
* [[Prototype/Corpse]] - no masks
* [[Prototype/DeconstructibleTileProxy]] - <code>{"ground-tile"}</code>
* [[Prototype/EntityGhost]] - <code>{"ghost-layer"}</code>
* [[Prototype/EntityParticle]] - no masks
* [[Prototype/Explosion]] - no masks
* [[Prototype/FireFlame]] - no masks
* [[Prototype/Fish]] - <code>{"ground-tile", "colliding-with-tiles-only"}</code>
* [[Prototype/FluidStream]] - no masks
* [[Prototype/FlyingRobot]] - no masks
* [[Prototype/FlyingText]] - no masks
* [[Prototype/Gate]] - <code>{"item-layer", "object-layer", "player-layer", "water-tile", "train-layer"}</code>
* [[Prototype/HeatPipe]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/HighlightBoxEntity]] - no masks
* [[Prototype/ItemEntity]] - <code>{"item-layer"}</code>
* [[Prototype/ItemRequestProxy]] - no masks
* [[Prototype/LandMine]] - <code>{"object-layer", "water-tile"}</code>
* [[Prototype/LinkedBelt]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Loader1x1]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Loader1x2]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/ParticleSource]] - no masks
* [[Prototype/PlayerPort]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/Projectile]] - no masks
* [[Prototype/Rail]] - <code>{"item-layer", "object-layer",  "rail-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/RailSignalBase]] - <code>{"floor-layer", "rail-layer", "item-layer"}</code>
* [[Prototype/ResourceEntity]] - <code>{"resource-layer"}</code>
* [[Prototype/RollingStock]] - <code>{"train-layer"}</code>
* [[Prototype/Smoke]] - no masks
* [[Prototype/SpeechBubble]] - no masks
* [[Prototype/SpiderLeg]] - <code>{"player-layer", "rail-layer"}</code>
* [[Prototype/Splitter]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Sticker]] - no masks
* [[Prototype/TileGhost]] - <code>{"ghost-layer"}</code>
* [[Prototype/TransportBelt]] - <code>{"object-layer", "floor-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/UndergroundBelt]] - <code>{"object-layer", "item-layer", "transport-belt-layer", "water-tile"}</code>
* [[Prototype/Unit]] - <code>{"player-layer", "train-layer", "not-colliding-with-itself"}</code>
* [[Prototype/Vehicle]] - <code>{"player-layer", "train-layer"}</code>
</div></div>


'''Default''': Empty = {{0, 0}, {0, 0}}
{{Prototype property|map_generator_bounding_box|[[Types/BoundingBox|BoundingBox]]|The value of collision box.|optional=true}}
Used instead of the collision box during map generation. Allows space entities differently during map generation, for example if the box is bigger, the entities will be placed farther apart.


{{Prototype property|selection_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}}</nowiki>|optional=true}}
Specification of the entity selection area.
Specification of the entity selection area.
When empty  the entity will have no selection area (and thus is not selectable).
When empty  the entity will have no selection area (and thus is not selectable).
<syntaxhighlight lang="lua">selection_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
<syntaxhighlight lang="lua">selection_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
The selection box is usualy a little bit bigger than the collision box, for tilable entities (like buildings) it should match the tile size of the building.
The selection box is usually a little bit bigger than the collision box, for tilable entities (like buildings) it should match the tile size of the building.
 
=== drawing_box ===
'''Type''': [[Types/BoundingBox]]
 
'''Default''': Empty = {{0, 0}, {0, 0}} (selection_box is used instead)


{{Prototype property|drawing_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}} (selection_box is used instead)</nowiki>|optional=true}}
Specification of space needed to see the whole entity.  
Specification of space needed to see the whole entity.  


Line 172: Line 221:
<syntaxhighlight lang="lua">drawing_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
<syntaxhighlight lang="lua">drawing_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>


=== sticker_box ===
{{Prototype property|sticker_box|[[Types/BoundingBox|BoundingBox]]|The value of collision box.|optional=true}}
'''Type''': [[Types/BoundingBox]]
 
'''Default''': The value of collision box.
 
Used to set the area of the entity that can have stickers on it, currently only used for units to specify the area where the green slow down stickers can appear.
Used to set the area of the entity that can have stickers on it, currently only used for units to specify the area where the green slow down stickers can appear.
It is optional and the collision box is used when not specified.
It is optional and the collision box is used when not specified.
<syntaxhighlight lang="lua">sticker_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
<syntaxhighlight lang="lua">sticker_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>


=== flags ===
{{Prototype property|hit_visualization_box|[[Types/BoundingBox|BoundingBox]]|<nowiki>Empty = {{0, 0}, {0, 0}}</nowiki>|optional=true}}
'''Type''': [[Types/EntityPrototypeFlags]]
Where beams should hit the entity. Useful if the bounding box only covers part of the entity (e.g. feet of the character) and beams only hitting there would look weird.
 
'''Default''': nil


=== minable ===
{{Prototype property|trigger_target_mask|[[Types/TriggerTargetMask|TriggerTargetMask]]|optional=true}}
'''Type''': [[Types/MinableProperties]]


'''Default''': {hardness = 0, minable = false, mining_time = 0}
{{Prototype property|flags|[[Types/EntityPrototypeFlags|EntityPrototypeFlags]]|optional=true}}


=== subgroup ===
{{Prototype property|minable|[[Types/MinableProperties|MinableProperties]]|not minable|optional=true}}
'''Type''': [[Types/string]]


{{Prototype property|subgroup|[[Types/string|string]]|optional=true}}
The name of the subgroup this entity should be sorted into in the map editor building selection.
The name of the subgroup this entity should be sorted into in the map editor building selection.


=== allow_copy_paste ===
{{Prototype property|allow_copy_paste|[[Types/bool|bool]]|true|optional=true}}
'''Type''': [[Types/bool]]
 
'''Default''': true
 
=== selectable_in_game ===
'''Type''': [[Types/bool]]
 
'''Default''': true
 
=== selection_priority ===
'''Type''': [[Types/uint8]]


'''Default''': 50
{{Prototype property|selectable_in_game|[[Types/bool|bool]]|true|optional=true}}


{{Prototype property|selection_priority|[[Types/uint8|uint8]]|50|optional=true}}
The entity with the higher number is selectable before the entity with the lower number.
The entity with the higher number is selectable before the entity with the lower number.


=== emissions_per_tick ===
{{Prototype property|remove_decoratives|[[Types/string|string]]|"automatic"|optional=true}}
'''Type''': [[Types/double]]
Either "automatic", "true" or "false". Whether this entity should remove decoratives that collide with it when this entity is built. When set to "automatic", if the entity type is considered a building (e.g. an assembling machine or a wall) it will remove decoratives.


'''Default''': 0
{{Prototype property|emissions_per_second|[[Types/double|double]]|0|optional=true}}
 
Amount of emissions created (positive number) or cleaned (negative number) every second by the entity.
Amount of emissions created (positive number) or cleaned (negative number) every tick by the entity.
This is passive, and it is independent concept of the emissions of machines, these are created actively depending on the power consumption.
This is passive, and it is independent concept of the emissions of machines, these are created actively depending on the power consumption.
Currently used just for trees.
Currently used just for trees.
<syntaxhighlight lang="lua">emissions_per_tick = -0.0005 -- cleaning effect of big tree</syntaxhighlight>


=== shooting_cursor_size ===
<syntaxhighlight lang="lua">emissions_per_second = -0.001 -- cleaning effect of big tree</syntaxhighlight>
'''Type''': [[Types/double]]


{{Prototype property|shooting_cursor_size|[[Types/double|double]]|optional=true}}
The cursor size used when shooting at this entity.
The cursor size used when shooting at this entity.


=== created_smoke ===
{{Prototype property|created_smoke|[[Types/CreateTrivialSmokeEffectItem|CreateTrivialSmokeEffectItem]]|The "smoke-building"-smoke|optional=true}}
'''Type''': [[Types/CreateTrivialSmokeEffectItem]]
The smoke that is shown when the entity is placed.
 
The smoke that is shown when the entity is placed. Default is using the "smoke-building" smoke.
 
=== autoplace ===
'''Type''': [[Types/AutoplaceSpecification]]
 
'''Default''': nil (entity is not autoplacable)
 
Used to specify the rules for placing this entity during map generation.
 
=== working_sound ===
'''Type''': [[Types/WorkingSound]]
 
'''Default''': nil


{{Prototype property|working_sound|[[Types/WorkingSound|WorkingSound]]|optional=true}}
Will also work on entities that don't actually do work.
Will also work on entities that don't actually do work.


=== created_effect ===
{{Prototype property|created_effect|[[Types/Trigger|Trigger]]|optional=true}}
'''Type''': [[Types/Trigger]]
The effect/trigger that happens when the entity is placed.


'''Default''': nil
{{Prototype property|build_sound|[[Types/Sound|Sound]]|optional=true}}


The effect/trigger that happens when the entity is placed.
{{Prototype property|mined_sound|[[Types/Sound|Sound]]|optional=true}}


=== build_sound ===
{{Prototype property|mining_sound|[[Types/Sound|Sound]]|optional=true}}
'''Type''': [[Types/Sound]]


=== mined_sound ===
{{Prototype property|rotated_sound|[[Types/Sound|Sound]]|optional=true}}
'''Type''': [[Types/Sound]]


=== vehicle_impact_sound ===
{{Prototype property|vehicle_impact_sound|[[Types/Sound|Sound]]|optional=true}}
'''Type''': [[Types/Sound]]
When playing this sound, the volume is scaled by the speed of the vehicle when colliding with this entity.


=== open_sound ===
{{Prototype property|open_sound|[[Types/Sound|Sound]]|optional=true}}
'''Type''': [[Types/Sound]]


=== close_sound ===
{{Prototype property|close_sound|[[Types/Sound|Sound]]|optional=true}}
'''Type''': [[Types/Sound]]


=== build_base_evolution_requirement ===
{{Prototype property|radius_visualisation_specification|[[Types/RadiusVisualisationSpecification|RadiusVisualisationSpecification]]|optional=true}}
'''Type''': [[Types/double]]


'''Default''': 0
{{Prototype property|build_base_evolution_requirement|[[Types/double|double]]|0|optional=true}}


=== alert_icon_shift ===
{{Prototype property|alert_icon_shift|[[Types/vector|vector]]|optional=true}}
'''Type''': [[Types/vector]]


=== alert_icon_scale ===
{{Prototype property|alert_icon_scale|[[Types/float|float]]|optional=true}}
'''Type''': [[Types/float]]


=== fast_replaceable_group ===
{{Prototype property|fast_replaceable_group|[[Types/string|string]]|""|optional=true}}
'''Type''': [[Types/string]]
This allows you to replace an entity that's already placed, with a different one in your inventory. For example, replacing a burner inserter with a fast inserter.


This allows you to replace an entity that's already placed, with a different one in your inventory. For example, replacing a burner drill with an electric drill.
This is simply a string, so any string can be used here. The entity that should be replaced simply has to use the same string here.


The ones the game uses are:
The ones the game uses are:


  "underground-belt"
    "container"
  "loader"
    "furnace"
  "splitter"
    "transport-belt"
  "transport-belt"
    "electric-pole"
  "assembling-machine"
    "steam-engine"
  "container"
    "inserter"
  "long-handed-inserter"
    "long-handed-inserter"
  "inserter"
    "pipe"
  "wall"
    "assembling-machine"
  "rail-signal"
    "wall"
  "container"
    "loader"
  "pipe"
    "rail-signal"
  "furnace"
    "mining-drill"
  "steam-engine"
    "pumpjack"
 
{{Prototype property|next_upgrade|[[Types/string|string]]|optional=true}}
Name of the entity that will be automatically selected as the upgrade of this entity when using the [[upgrade planner]] without configuration.


=== placeable_by ===
This entity may not have 'not-upgradable' flag set and must be minable. This entity mining result must not contain item product with "hidden" flag set. Mining results with no item products are allowed. The entity may not be a [[Prototype/RollingStock]].<br>
'''Type''': [[Types/ItemToPlace]] or [[Types/table]] of [[Types/ItemToPlace]]
The upgrade target entity needs to have the same bounding box, collision mask, and fast replaceable group as this entity. The upgrade target entity must have least 1 item that builds it that isn't hidden.


Item that when placed creates this entity.
{{Prototype property|placeable_by|[[Types/ItemToPlace|ItemToPlace]] or [[Types/table|table]] of [[Types/ItemToPlace|ItemToPlace]]|optional=true}}
Item that when placed creates this entity. Determines which item is picked when "Q" (smart pipette) is used on the entity, determines which item is needed in a blueprint of this entity.


=== remains_when_mined ===
The item count specified here can't be larger than the stack size of that item.
'''Type''': [[Types/string]] or [[Types/table]] of [[Types/string]]


{{Prototype property|remains_when_mined|[[Types/string|string]] or [[Types/table|table]] of [[Types/string|string]]|optional=true}}
The entity that remains when this one is mined, deconstructed or fast-replaced. The entity wont actually be spawned if it would collide with the entity that is in the process of being mined.
The entity that remains when this one is mined, deconstructed or fast-replaced. The entity wont actually be spawned if it would collide with the entity that is in the process of being mined.


=== additional_pastable_entities ===
{{Prototype property|additional_pastable_entities|[[Types/table|table]] of [[Types/string|string]]|optional=true}}
'''Type''': [[Types/string]] or [[Types/table]] of [[Types/string]]
 
Entities this entity prototype can be pasted on to in addition to the standard supported types.
Entities this entity prototype can be pasted on to in addition to the standard supported types.
This is used to allow copying between types that aren't compatible on the C++ code side.
This is used to allow copying between types that aren't compatible on the C++ code side, by allowing mods to receive the [https://lua-api.factorio.com/latest/events.html#on_entity_settings_pasted on_entity_settings_pasted] event for the given entity and do the setting pasting via script.
 
=== tile_width ===
'''Type''': [[Types/uint32]]
 
'''Default''': calculated by the collision box width rounded up.


{{Prototype property|tile_width|[[Types/uint32|uint32]]|calculated by the collision box width rounded up.|optional=true}}
Used to determine how the center of the entity should be positioned when building (unless the offgrid [[Types/EntityPrototypeFlags|flag]] is specified).
Used to determine how the center of the entity should be positioned when building (unless the offgrid [[Types/EntityPrototypeFlags|flag]] is specified).
When the tile width is odd, the center will be in the center of the tile, when it is even, the center is on the tile transition.
When the tile width is odd, the center will be in the center of the tile, when it is even, the center is on the tile transition.


=== tile_height ===
{{Prototype property|tile_height|[[Types/uint32|uint32]]|calculated by the collision box height rounded up.|optional=true}}
'''Type''': [[Types/uint32]]


'''Default''': calculated by the collision box height rounded up.
{{Prototype property|autoplace|[[Types/AutoplaceSpecification|AutoplaceSpecification]]|nil (entity is not autoplacable)|optional=true}}
 
Used to specify the rules for placing this entity during map generation.
=== map_color ===
'''Type''': [[Types/color]]
 
=== friendly_map_color ===
'''Type''': [[Types/color]]


=== enemy_map_color ===
{{Prototype property|map_color|[[Types/Color|Color]]|optional=true}}
'''Type''': [[Types/color]]


<!-- this is a property of the vehicle prototype, not the general entity one
{{Prototype property|friendly_map_color|[[Types/Color|Color]]|optional=true}}
== weight ===
'''Type''': [[Types/float]]


'''Default''': 1
{{Prototype property|enemy_map_color|[[Types/Color|Color]]|optional=true}}


Weight of the entity used for physics calculation when car hits something.
{{Prototype property|water_reflection|[[Types/WaterReflectionDefinition|WaterReflectionDefinition]]|optional=true}}
<syntaxhighlight lang="lua">weight = 5.7</syntaxhighlight> -->
May also be defined inside <code>graphics_set</code> instead of directly in the entity prototype. This is useful for entities that use the a <code>graphics_set</code> property to define their graphics, becausen then all graphics can be in defined one place.


== Example ==
== Example ==

Revision as of 14:14, 12 May 2021

Prototype definitions » PrototypeBase » Prototype/Entity


Abstract base of all entities in the game. Entity is basically everything that can be on the map (except tiles). For in game script access to entity, take a look at LuaEntity


Prototype/Entity — abstract
icons, icon, icon_size (IconSpecification)::IconSpecification
additional_pastable_entities::table of string (optional)
alert_icon_scale::float (optional)
alert_icon_shift::vector (optional)
allow_copy_paste::bool (optional)
autoplace::AutoplaceSpecification (optional)
build_base_evolution_requirement::double (optional)
build_grid_size::uint8 (optional)
build_sound::Sound (optional)
close_sound::Sound (optional)
collision_box::BoundingBox (optional)
collision_mask::CollisionMask (optional)
created_effect::Trigger (optional)
created_smoke::CreateTrivialSmokeEffectItem (optional)
drawing_box::BoundingBox (optional)
emissions_per_second::double (optional)
enemy_map_color::Color (optional)
fast_replaceable_group::string (optional)
flags::EntityPrototypeFlags (optional)
friendly_map_color::Color (optional)
hit_visualization_box::BoundingBox (optional)
map_color::Color (optional)
map_generator_bounding_box::BoundingBox (optional)
minable::MinableProperties (optional)
mined_sound::Sound (optional)
mining_sound::Sound (optional)
next_upgrade::string (optional)
open_sound::Sound (optional)
placeable_by::ItemToPlace or table of ItemToPlace (optional)
protected_from_tile_building::bool (optional)
radius_visualisation_specification::RadiusVisualisationSpecification (optional)
remains_when_mined::string or table of string (optional)
remove_decoratives::string (optional)
rotated_sound::Sound (optional)
selectable_in_game::bool (optional)
selection_box::BoundingBox (optional)
selection_priority::uint8 (optional)
shooting_cursor_size::double (optional)
sticker_box::BoundingBox (optional)
subgroup::string (optional)
tile_height::uint32 (optional)
tile_width::uint32 (optional)
trigger_target_mask::TriggerTargetMask (optional)
vehicle_impact_sound::Sound (optional)
water_reflection::WaterReflectionDefinition (optional)
working_sound::WorkingSound (optional)
Inherited from PrototypeBase
name::string
type::string
localised_description::LocalisedString (optional)
localised_name::LocalisedString (optional)
order::Order (optional)

Extensions

Mandatory properties

Inherits all properties from PrototypeBase.

icons, icon, icon_size (IconSpecification)

Type: IconSpecification
An icon is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-enemy.

The icon will be used in the editor building selection and the bonus gui.

icon = "__base__/graphics/icons/wooden-chest.png"

Optional properties

order

See PrototypeBase#order

Inherited from PrototypeBase.

The order string is taken from the items in placeable_by if they exist, or from an item that has its place_result set to this entity if it exists.

collision_box

Type: BoundingBox
Specification of the entity collision boundaries.

Empty collision box is used for smoke, projectiles, particles, explosions etc.

collision_box = {{-0.4, -0.4}, {0.4, 0.4}}

The {0,0} coordinate in the collision box will match the entity position.

It should be near the center of the collision box, to keep correct entity drawing order. It must include the {0,0} coordinate.

Note, that for buildings, it is customary to leave 0.1 wide border between the edge of the tile and the edge of the building, this lets the player move between the building and electric poles/inserters etc.

collision_mask

Type: CollisionMask
Default: {"item-layer", "object-layer", "player-layer", "water-tile"}

Two entities can collide only if they share a layer from the collision mask.

NOTE: Some entity types have their own default that differs from the above default. They are listed here:

map_generator_bounding_box

Type: BoundingBox
Default: The value of collision box.
Used instead of the collision box during map generation. Allows space entities differently during map generation, for example if the box is bigger, the entities will be placed farther apart.

selection_box

Type: BoundingBox
Default: Empty = {{0, 0}, {0, 0}}
Specification of the entity selection area. When empty the entity will have no selection area (and thus is not selectable).

selection_box = {{-0.5, -0.5}, {0.5, 0.5}}

The selection box is usually a little bit bigger than the collision box, for tilable entities (like buildings) it should match the tile size of the building.

drawing_box

Type: BoundingBox
Default: Empty = {{0, 0}, {0, 0}} (selection_box is used instead)
Specification of space needed to see the whole entity.

This is used to calculate the correct zoom and positioning in the entity info gui.

drawing_box = {{-0.5, -0.5}, {0.5, 0.5}}

sticker_box

Type: BoundingBox
Default: The value of collision box.
Used to set the area of the entity that can have stickers on it, currently only used for units to specify the area where the green slow down stickers can appear. It is optional and the collision box is used when not specified.

sticker_box = {{-0.5, -0.5}, {0.5, 0.5}}

hit_visualization_box

Type: BoundingBox
Default: Empty = {{0, 0}, {0, 0}}
Where beams should hit the entity. Useful if the bounding box only covers part of the entity (e.g. feet of the character) and beams only hitting there would look weird.

trigger_target_mask

Type: TriggerTargetMask

flags

Type: EntityPrototypeFlags

minable

Type: MinableProperties
Default: not minable

subgroup

Type: string
The name of the subgroup this entity should be sorted into in the map editor building selection.

allow_copy_paste

Type: bool
Default: true

selectable_in_game

Type: bool
Default: true

selection_priority

Type: uint8
Default: 50
The entity with the higher number is selectable before the entity with the lower number.

remove_decoratives

Type: string
Default: "automatic"
Either "automatic", "true" or "false". Whether this entity should remove decoratives that collide with it when this entity is built. When set to "automatic", if the entity type is considered a building (e.g. an assembling machine or a wall) it will remove decoratives.

emissions_per_second

Type: double
Default: 0
Amount of emissions created (positive number) or cleaned (negative number) every second by the entity. This is passive, and it is independent concept of the emissions of machines, these are created actively depending on the power consumption. Currently used just for trees.

emissions_per_second = -0.001 -- cleaning effect of big tree

shooting_cursor_size

Type: double
The cursor size used when shooting at this entity.

created_smoke

Type: CreateTrivialSmokeEffectItem
Default: The "smoke-building"-smoke
The smoke that is shown when the entity is placed.

working_sound

Type: WorkingSound
Will also work on entities that don't actually do work.

created_effect

Type: Trigger
The effect/trigger that happens when the entity is placed.

build_sound

Type: Sound

mined_sound

Type: Sound

mining_sound

Type: Sound

rotated_sound

Type: Sound

vehicle_impact_sound

Type: Sound
When playing this sound, the volume is scaled by the speed of the vehicle when colliding with this entity.

open_sound

Type: Sound

close_sound

Type: Sound

radius_visualisation_specification

Type: RadiusVisualisationSpecification

build_base_evolution_requirement

Type: double
Default: 0

alert_icon_shift

Type: vector

alert_icon_scale

Type: float

fast_replaceable_group

Type: string
Default: ""
This allows you to replace an entity that's already placed, with a different one in your inventory. For example, replacing a burner inserter with a fast inserter.

This is simply a string, so any string can be used here. The entity that should be replaced simply has to use the same string here.

The ones the game uses are:

   "container"
   "furnace"
   "transport-belt"
   "electric-pole"
   "steam-engine"
   "inserter"
   "long-handed-inserter"
   "pipe"
   "assembling-machine"
   "wall"
   "loader"
   "rail-signal"
   "mining-drill"
   "pumpjack"

next_upgrade

Type: string
Name of the entity that will be automatically selected as the upgrade of this entity when using the upgrade planner without configuration.

This entity may not have 'not-upgradable' flag set and must be minable. This entity mining result must not contain item product with "hidden" flag set. Mining results with no item products are allowed. The entity may not be a Prototype/RollingStock.
The upgrade target entity needs to have the same bounding box, collision mask, and fast replaceable group as this entity. The upgrade target entity must have least 1 item that builds it that isn't hidden.

placeable_by

Type: ItemToPlace or table of ItemToPlace
Item that when placed creates this entity. Determines which item is picked when "Q" (smart pipette) is used on the entity, determines which item is needed in a blueprint of this entity.

The item count specified here can't be larger than the stack size of that item.

remains_when_mined

Type: string or table of string
The entity that remains when this one is mined, deconstructed or fast-replaced. The entity wont actually be spawned if it would collide with the entity that is in the process of being mined.

additional_pastable_entities

Type: table of string
Entities this entity prototype can be pasted on to in addition to the standard supported types. This is used to allow copying between types that aren't compatible on the C++ code side, by allowing mods to receive the on_entity_settings_pasted event for the given entity and do the setting pasting via script.

tile_width

Type: uint32
Default: calculated by the collision box width rounded up.
Used to determine how the center of the entity should be positioned when building (unless the offgrid flag is specified). When the tile width is odd, the center will be in the center of the tile, when it is even, the center is on the tile transition.

tile_height

Type: uint32
Default: calculated by the collision box height rounded up.

autoplace

Type: AutoplaceSpecification
Default: nil (entity is not autoplacable)
Used to specify the rules for placing this entity during map generation.

map_color

Type: Color

friendly_map_color

Type: Color

enemy_map_color

Type: Color

water_reflection

Type: WaterReflectionDefinition
May also be defined inside graphics_set instead of directly in the entity prototype. This is useful for entities that use the a graphics_set property to define their graphics, becausen then all graphics can be in defined one place.

Example

{
    type = "container",
    name = "wooden-chest",
    icon = "__base__/graphics/icons/wooden-chest.png",
    flags = {"placeable-neutral", "player-creation"},
    minable = {mining_time = 1, result = "wooden-chest"},
    max_health = 100,
    corpse = "small-remnants",
    collision_box = {{-0.35, -0.35}, {0.35, 0.35}},
    fast_replaceable_group = "container",
    selection_box = {{-0.5, -0.5}, {0.5, 0.5}},
    inventory_size = 16,
    open_sound = { filename = "__base__/sound/wooden-chest-open.ogg" },
    close_sound = { filename = "__base__/sound/wooden-chest-close.ogg" },
    vehicle_impact_sound =  { filename = "__base__/sound/car-wood-impact.ogg", volume = 1.0 },
    picture =
    {
      filename = "__base__/graphics/entity/wooden-chest/wooden-chest.png",
      priority = "extra-high",
      width = 46,
      height = 33,
      shift = {0.25, 0.015625}
    },
    circuit_wire_connection_point =
    {
      shadow =
      {
        red = {0.734375, 0.453125},
        green = {0.609375, 0.515625},
      },
      wire =
      {
        red = {0.40625, 0.21875},
        green = {0.40625, 0.375},
      }
    },
    circuit_connector_sprites = get_circuit_connector_sprites({0.1875, 0.15625}, nil, 18),
    circuit_wire_max_distance = 9
  }