Prototype/Entity: Difference between revisions

From Official Factorio Wiki
Jump to navigation Jump to search
(→‎Optional properties: added open_sound and close_sound)
(Updated to 0.15)
Line 120: Line 120:


Unique identification of the prototype.
Unique identification of the prototype.
=== flags ===
'''Type''': [[Types/EntityPrototypeFlags]]


=== icon ===
=== icon ===
'''Type''': [[Types/FileName]]
'''Type''': [[Types/FileName]]


Mandatory for entities that have at least one of these flags active placeable-neutral, placeable-player, placeable-neutral.
Either icon or icons is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-neutral.
 
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>


The icon will be used in the editor building selection.
=== icons ===
    icon = "__base__/graphics/icons/wooden-chest.png"
Either icon or icons is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-neutral.
 
=== order ===
'''Type''': [[Types/Order]]
 
Mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-neutral.


== Optional properties ==
== Optional properties ==
Line 141: Line 146:


Empty collision box is used for smoke, projectiles, particles, explosions etc.
Empty collision box is used for smoke, projectiles, particles, explosions etc.
    collision_box = {{-0.4, -0.4}, {0.4, 0.4}}
<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.
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 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 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. and prevents stucked items on transport belt in some special cases (curves around the corner etc).
=== collision_mask ===
=== collision_mask ===
'''type''': [[Types/CollisionMask]]
'''type''': [[Types/CollisionMask]]


'''Default''': Depends on Entity type
'''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"}


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.
Line 161: Line 167:
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).
    selection_box = {{-0.5, -0.5}, {0.5, 0.5}}
<syntaxhighlight lang="lua">selection_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>
The selection box is usualy 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 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 ===
=== drawing_box ===
'''Type''': [[Types/AABBbox]]
'''Type''': [[Types/AABBbox]]


'''Default''': The value of selection_box
'''Default''': Empty = {{0, 0}, {0, 0}}


Specification of space needed to see the whole entity.
Specification of space needed to see the whole entity.  


This is used to calculate the correct zoom and positioning in the entity info gui.
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}}
<syntaxhighlight lang="lua">drawing_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>


=== sticker_box ===
=== sticker_box ===
Line 181: Line 187:
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.
  sticker_box = {{-0.5, -0.5}, {0.5, 0.5}}
<syntaxhighlight lang="lua">sticker_box = {{-0.5, -0.5}, {0.5, 0.5}}</syntaxhighlight>


=== weight ===
=== flags ===
'''Type''': [[Types/float]]
'''Type''': [[Types/EntityPrototypeFlags]]
 
'''Default''': 1


Weight of the entity used for physics calculation when car hits something.
'''Default''': nil
    weight = 5.7


=== minable ===
=== minable ===
'''Type''': [[Types/MinableProperties]]
'''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


=== emissions_per_tick ===
=== emissions_per_tick ===
'''Type''': [[Types/double]]
'''Type''': [[Types/double]]
'''Default''': 0


Amount of emissions created (positive number) or cleaned (negative number) every tick 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.
    emissions_per_tick = -0.0005 -- cleaning effect of big tree
<syntaxhighlight lang="lua">emissions_per_tick = -0.0005 -- cleaning effect of big tree</syntaxhighlight>
 
=== shooting_cursor_size ===
'''Type''': [[Types/double]]
 
The cursor size used when shooting at this entity.
 
=== created_smoke ===
'''Type''': [[Types/SmokeTrigger]]
 
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


=== fast_replaceable_group ===
=== fast_replaceable_group ===
Line 223: Line 301:
   "furnace"
   "furnace"
   "steam-engine"
   "steam-engine"
=== placeable_by ===
=== remains_when_mined ===
=== additional_pastable_entities ===


=== tile_width ===
=== tile_width ===
Line 236: Line 320:


'''Default''': calculated by the collision box height rounded up.
'''Default''': calculated by the collision box height rounded up.
=== vehicle_impact_sound ===
'''Type''': [[Types/Sound]]
=== open_sound ===
'''Type''': [[Types/Sound]]
=== close_sound ===
'''Type''': [[Types/Sound]]
=== working_sound ===
'''Type''': [[Types/WorkingSound]]
Will also work on entities that don't actually do work (Tried it on [[Prototype/ResourceEntity]], it was quite funny ~Bilka).


=== map_color ===
=== map_color ===
Line 260: Line 330:
'''Type''': [[Types/color]]
'''Type''': [[Types/color]]


=== autoplace ===
<!-- this is a property of the vehicle prototype, not the general entity one
'''Type''': [[Types/AutoplaceSpecification]]
== weight ===
'''Type''': [[Types/float]]


'''Default''': Entity is not autoplacable
'''Default''': 1


Used to specify the rules for placing this entity during map generation.
Weight of the entity used for physics calculation when car hits something.
<syntaxhighlight lang="lua">weight = 5.7</syntaxhighlight> -->


<syntaxhighlight lang="lua">autoplace =
== 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 =
     {
     {
       sharpness = 0.5,
       filename = "__base__/graphics/entity/wooden-chest/wooden-chest.png",
       control = "forest",
       priority = "extra-high",
       peaks =
       width = 46,
      height = 33,
      shift = {0.25, 0.015625}
    },
    circuit_wire_connection_point =
    {
      shadow =
       {
       {
         {
         red = {0.734375, 0.453125},
          influence = 0.2,
         green = {0.609375, 0.515625},
          water_optimal = 0.3,
       },
          water_range = 0.2,
       wire =
          water_max_range = 0.4
        },
         {
          influence = 0.9,
          noise_layer = "trees",
          noise_persistence = 0.5,
        }
      }
    }
</syntaxhighlight>
 
== 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"},
      collision_box = {{-0.4, -0.4}, {0.4, 0.4}},
       selection_box = {{-0.5, -0.5}, {0.5, 0.5}},
      max_health = 50,
      corpse = "small-remnants",
      fast_replaceable_group = "container",
      inventory_size = 16,
       picture =
       {
       {
         filename = "__base__/graphics/entity/wooden-chest/wooden-chest.png",
         red = {0.40625, 0.21875},
        priority = "extra-high",
         green = {0.40625, 0.375},
        width = 46,
         height = 33,
        shift = {0.3, 0}
       }
       }
     }
     },
    circuit_connector_sprites = get_circuit_connector_sprites({0.1875, 0.15625}, nil, 18),
    circuit_wire_max_distance = 9
  }</syntaxhighlight>

Revision as of 21:53, 11 November 2017

Basics

The common properties 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

Extensions

Mandatory properties

type

Type: Types/string

Specification of the type of the prototype.

name

Type: Types/string

Unique identification of the prototype.

icon

Type: Types/FileName

Either icon or icons is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-neutral.

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

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

icons

Either icon or icons is mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-neutral.

order

Type: Types/Order

Mandatory for entities that have at least one of these flags active: placeable-neutral, placeable-player, placeable-neutral.

Optional properties

collision_box

Type: Types/AABBbox

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.

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 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: 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"}

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

selection_box

Type: Types/AABBbox

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 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/AABBbox

Default: Empty = {{0, 0}, {0, 0}}

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: Types/AABBbox

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

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

emissions_per_tick

Type: Types/double

Default: 0

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. Currently used just for trees.

emissions_per_tick = -0.0005 -- cleaning effect of big tree

shooting_cursor_size

Type: Types/double

The cursor size used when shooting at this entity.

created_smoke

Type: Types/SmokeTrigger

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

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.

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"

placeable_by

remains_when_mined

additional_pastable_entities

tile_width

Type: Types/unsigned

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: Types/unsigned

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

{
    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
  }