Prototype/Entity: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(→‎collision_mask: Fixed defaults, added new 0.17 defaults)
(Removed old prototype docs)
Tag: Replaced
 
(50 intermediate revisions by 10 users not shown)
Line 1: Line 1:
==Basics==
<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/prototypes/EntityPrototype.html https://lua-api.factorio.com/latest/prototypes/EntityPrototype.html]
This type is abstract and cannot be created directly.


The common properties of all entities in the game.
</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>
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]
 
== Extensions ==
<div class="factorio-list">
* [[Prototype/Arrow]] '''arrow'''
* [[Prototype/ArtilleryProjectile]] '''artillery-projectile'''
* [[Prototype/Beam]] '''beam'''
* [[Prototype/CharacterCorpse]] '''character-corpse'''
* [[Prototype/Cliff]] '''cliff'''
* [[Prototype/Corpse]] '''corpse'''
** [[Prototype/RailRemnants]] '''rail-remnants'''
* [[Prototype/DeconstructibleTileProxy]] '''deconstructible-tile-proxy'''
* [[Prototype/EntityGhost]] '''entity-ghost'''
* [[Prototype/EntityWithHealth]] <abstract>
** [[Prototype/Accumulator]] '''accumulator'''
** [[Prototype/ArtilleryTurret]] '''artillery-turret'''
** [[Prototype/Beacon]] '''beacon'''
** [[Prototype/Boiler]] '''boiler'''
** [[Prototype/Character]] '''character'''
** [[Prototype/Combinator]] <abstract>
*** [[Prototype/ArithmeticCombinator]] '''arithmetic-combinator'''
*** [[Prototype/DeciderCombinator]] '''decider-combinator'''
** [[Prototype/ConstantCombinator]] '''constant-combinator'''
** [[Prototype/Container]] '''container'''
*** [[Prototype/LogisticContainer]] '''logistic-container'''
**** [[Prototype/InfinityContainer]] '''infinity-container'''
** [[Prototype/CraftingMachine]] <abstract>
*** [[Prototype/AssemblingMachine]] '''assembling-machine'''
**** [[Prototype/RocketSilo]] '''rocket-silo'''
*** [[Prototype/Furnace]] '''furnace'''
** [[Prototype/ElectricEnergyInterface]] '''electric-energy-interface'''
** [[Prototype/ElectricPole]] '''electric-pole'''
** [[Prototype/EnemySpawner]] '''unit-spawner'''
** [[Prototype/Fish]] '''fish'''
** [[Prototype/FlyingRobot]] <abstract>
*** [[Prototype/CombatRobot]] '''combat-robot'''
*** [[Prototype/RobotWithLogisticInterface]] <abstract>
**** [[Prototype/ConstructionRobot]] '''construction-robot'''
**** [[Prototype/LogisticRobot]] '''logistic-robot'''
** [[Prototype/Gate]] '''gate'''
** [[Prototype/Generator]] '''generator'''
** [[Prototype/HeatInterface]] '''heat-interface'''
** [[Prototype/HeatPipe]] '''heat-pipe'''
** [[Prototype/Inserter]] '''inserter'''
** [[Prototype/Lab]] '''lab'''
** [[Prototype/Lamp]] '''lamp'''
** [[Prototype/LandMine]] '''land-mine'''
** [[Prototype/Market]] '''market'''
** [[Prototype/MiningDrill]] '''mining-drill'''
** [[Prototype/OffshorePump]] '''offshore-pump'''
** [[Prototype/Pipe]] '''pipe'''
*** [[Prototype/InfinityPipe]] '''infinity-pipe'''
** [[Prototype/PipeToGround]] '''pipe-to-ground'''
** [[Prototype/PlayerPort]] '''player-port'''
** [[Prototype/PowerSwitch]] '''power-switch'''
** [[Prototype/ProgrammableSpeaker]] '''programmable-speaker'''
** [[Prototype/Pump]] '''pump'''
** [[Prototype/Radar]] '''radar'''
** [[Prototype/Rail]] <abstract>
*** [[Prototype/CurvedRail]] '''curved-rail'''
*** [[Prototype/StraightRail]] '''straight-rail'''
** [[Prototype/RailSignalBase]] <abstract>
*** [[Prototype/RailChainSignal]] '''rail-chain-signal'''
*** [[Prototype/RailSignal]] '''rail-signal'''
** [[Prototype/Reactor]] '''reactor'''
** [[Prototype/Roboport]] '''roboport'''
** [[Prototype/SimpleEntity]] '''simple-entity'''
** [[Prototype/SimpleEntityWithOwner]] '''simple-entity-with-owner'''
** [[Prototype/SimpleEntityWithForce]] '''simple-entity-with-force'''
** [[Prototype/SolarPanel]] '''solar-panel'''
** [[Prototype/StorageTank]] '''storage-tank'''
** [[Prototype/TrainStop]] '''train-stop'''
** [[Prototype/TransportBeltConnectable]] <abstract>
*** [[Prototype/Loader]] '''loader'''
*** [[Prototype/Splitter]] '''splitter'''
*** [[Prototype/TransportBelt]] '''transport-belt'''
*** [[Prototype/UndergroundBelt]] '''underground-belt'''
** [[Prototype/Tree]] '''tree'''
** [[Prototype/Turret]] '''turret'''
*** [[Prototype/AmmoTurret]] '''ammo-turret'''
*** [[Prototype/ElectricTurret]] '''electric-turret'''
*** [[Prototype/FluidTurret]] '''fluid-turret'''
** [[Prototype/Unit]] '''unit'''
** [[Prototype/Vehicle]] <abstract>
*** [[Prototype/Car]] '''car'''
*** [[Prototype/RollingStock]] <abstract>
**** [[Prototype/ArtilleryWagon]] '''artillery-wagon'''
**** [[Prototype/CargoWagon]] '''cargo-wagon'''
**** [[Prototype/FluidWagon]] '''fluid-wagon'''
**** [[Prototype/Locomotive]] '''locomotive'''
** [[Prototype/Wall]] '''wall'''
* [[Prototype/Explosion]] '''explosion'''
** [[Prototype/FlameThrowerExplosion]] '''flame-thrower-explosion'''
* [[Prototype/FireFlame]] '''fire'''
* [[Prototype/FluidStream]] '''stream'''
* [[Prototype/FlyingText]] '''flying-text'''
* [[Prototype/HighlightBoxEntity]] '''highlight-box'''
* [[Prototype/ItemEntity]] '''item-entity'''
* [[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/Projectile]] '''projectile'''
* [[Prototype/ResourceEntity]] '''resource'''
* [[Prototype/RocketSiloRocket]] '''rocket-silo-rocket'''
* [[Prototype/RocketSiloRocketShadow]] '''rocket-silo-rocket-shadow'''
* [[Prototype/Smoke]] <abstract>
** [[Prototype/SimpleSmoke]] '''smoke'''
** [[Prototype/SmokeWithTrigger]] '''smoke-with-trigger'''
* [[Prototype/SpeechBubble]] '''speech-bubble'''
* [[Prototype/Sticker]] '''sticker'''
* [[Prototype/TileGhost]] '''tile-ghost'''
</div>
 
== Mandatory properties ==
Inherits all properties from [[Prototype]].
 
=== 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]]
 
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.
<syntaxhighlight lang="lua">icon = "__base__/graphics/icons/wooden-chest.png"</syntaxhighlight>
 
== Optional properties ==
=== collision_box ===
'''Type''': [[Types/BoundingBox]]
 
'''Default''': Empty={{0, 0}, {0, 0}} it means no collisions.
 
Specification of the entity collision boundaries.
 
Empty collision box is used for smoke, projectiles, particles, explosions etc.
<syntaxhighlight lang="lua">collision_box = {{-0.4, -0.4}, {0.4, 0.4}}</syntaxhighlight>
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 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.
 
=== collision_mask ===
'''type''': [[Types/CollisionMask]]
 
'''Default''': {"item-layer", "object-layer", "player-layer", "water-tile"}
 
Two entities can collide only if they share a layer from the collision mask.
 
<div class="toccolours mw-collapsible mw-collapsed">
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/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/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/LegacyDecorative]] - <code>{"doodad-layer", "not-colliding-with-itself")</code>
* [[Prototype/Loader]] - <code>{"object-layer", "item-layer", "water-tile"}</code>
* [[Prototype/Particle]] - no masks
* [[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", "floor-layer", "water-tile", "not-colliding-with-itself"}</code>
* [[Prototype/RailSignalBase]] - <code>{"item-layer", "floor-layer"}</code>
* [[Prototype/ResourceEntity]] - <code>{"resource-layer"}</code>
* [[Prototype/RollingStock]] - <code>{"train-layer"}</code>
* [[Prototype/Smoke]] - no masks
* [[Prototype/SpeechBubble]] - no masks
* [[Prototype/Splitter]] - <code>{"object-layer", "item-layer", "water-tile"}</code>
* [[Prototype/Sticker]] - no masks
* [[Prototype/TileGhost]] - <code>{"ghost-layer"}</code>
* [[Prototype/TransportBelt]] - <code>{"object-layer", "floor-layer", "water-tile"}</code>
* [[Prototype/UndergroundBelt]] - <code>{"object-layer", "item-layer", "water-tile"}</code>
* [[Prototype/Unit]] - <code>{"player-layer", "train-layer"}</code>
* [[Prototype/Vehicle]] - <code>{"player-layer", "train-layer"}</code>
</div></div>
 
=== map_generator_bounding_box ===
'''Type''': [[Types/BoundingBox]]
 
'''Default''': The value of collision box.
 
=== selection_box ===
'''Type''': [[Types/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).
<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.
 
=== drawing_box ===
'''Type''': [[Types/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.
<syntaxhighlight lang="lua">drawing_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
 
=== sticker_box ===
'''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.
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>
 
=== hit_visualization_box ===
'''Type''': [[Types/BoundingBox]]
 
'''Default''': Empty = {{0, 0}, {0, 0}}
 
=== flags ===
'''Type''': [[Types/EntityPrototypeFlags]]
 
'''Default''': nil
 
=== minable ===
'''Type''': [[Types/MinableProperties]]
 
'''Default''': {hardness = 0, minable = false, mining_time = 0}
 
=== subgroup ===
'''Type''': [[Types/string]]
 
The name of the subgroup this entity should be sorted into in the map editor building selection.
 
=== allow_copy_paste ===
'''Type''': [[Types/bool]]
 
'''Default''': true
 
=== selectable_in_game ===
'''Type''': [[Types/bool]]
 
'''Default''': true
 
=== selection_priority ===
'''Type''': [[Types/uint8]]
 
'''Default''': 50
 
The entity with the higher number is selectable before the entity with the lower number.
 
=== emissions_per_second ===
'''Type''': [[Types/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.
 
<syntaxhighlight lang="lua">emissions_per_second = -0.0005 -- cleaning effect of big tree</syntaxhighlight>
 
=== emissions_per_tick ===
'''Type''': [[Types/double]]
 
'''Default''': 0
 
[[#emissions_per_second]], but per tick. Deprecated.
 
=== shooting_cursor_size ===
'''Type''': [[Types/double]]
 
The cursor size used when shooting at this entity.
 
=== created_smoke ===
'''Type''': [[Types/CreateTrivialSmokeEffectItem]]
 
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
 
Will also work on entities that don't actually do work.
 
=== created_effect ===
'''Type''': [[Types/Trigger]]
 
'''Default''': nil
 
The effect/trigger that happens when the entity is placed.
 
=== build_sound ===
'''Type''': [[Types/Sound]]
 
=== mined_sound ===
'''Type''': [[Types/Sound]]
 
=== vehicle_impact_sound ===
'''Type''': [[Types/Sound]]
 
=== open_sound ===
'''Type''': [[Types/Sound]]
 
=== close_sound ===
'''Type''': [[Types/Sound]]
 
=== build_base_evolution_requirement ===
'''Type''': [[Types/double]]
 
'''Default''': 0
 
=== alert_icon_shift ===
'''Type''': [[Types/vector]]
 
=== alert_icon_scale ===
'''Type''': [[Types/float]]
 
=== fast_replaceable_group ===
'''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 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:
 
  "underground-belt"
  "loader"
  "splitter"
  "transport-belt"
  "assembling-machine"
  "container"
  "long-handed-inserter"
  "inserter"
  "wall"
  "rail-signal"
  "container"
  "pipe"
  "furnace"
  "steam-engine"
 
=== next_upgrade ===
'''Type''': [[Types/string]]
 
Name of the entity that will be automatically selected as the upgrade of this entity when using the [[upgrade planner]].
 
=== placeable_by ===
'''Type''': [[Types/ItemToPlace]] or [[Types/table]] of [[Types/ItemToPlace]]
 
Item that when placed creates this entity. Also determines which item is picked when "Q" (smart pipette) is used on the entity.
 
=== remains_when_mined ===
'''Type''': [[Types/string]] or [[Types/table]] of [[Types/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''': [[Types/string]] or [[Types/table]] of [[Types/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.
 
=== tile_width ===
'''Type''': [[Types/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 [[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.
 
=== tile_height ===
'''Type''': [[Types/uint32]]
 
'''Default''': calculated by the collision box height rounded up.
 
=== map_color ===
'''Type''': [[Types/Color]]
 
=== friendly_map_color ===
'''Type''': [[Types/Color]]
 
=== enemy_map_color ===
'''Type''': [[Types/Color]]
 
== Example ==
<syntaxhighlight lang="lua">{
    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
  }</syntaxhighlight>

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/prototypes/EntityPrototype.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=Prototype/Entity&oldid=202884"