inserter
- class Inserter(name: str = 'burner-inserter', **kwargs: dict)
Bases:
StackSizeMixin
,CircuitReadHandMixin
,InserterModeOfOperationMixin
,CircuitConditionMixin
,LogisticConditionMixin
,ControlBehaviorMixin
,CircuitConnectableMixin
,DirectionalMixin
,Entity
An entity that can move items between machines.
Note
In Factorio, the
Inserter
prototype includes both regular and filter inserters. In Draftsman, inserters are split into two different classes,Inserter
andFilterInserter
- classmethod dump_format() dict
Dumps a JSON-serializable representation of the Entity’s
exports
dictionary, primarily for user interpretation.- Returns:
A JSON dictionary containing the names of each valid key, a short description of their purpose, and whether or not they’re considered optional.
- classmethod get_format() str
Produces a pretty string representation of
meth:dump_format
. Work in progress.- Returns:
A formatted string that can be output to stdout or file.
- get_world_bounding_box()
Gets the world-space coordinates AABB that completely encompasses the
collision_set
of this SpatialLike. Behaves similarly to the old function get_area(), except now it correctly handles non-AABB collision shapes.
- get_world_collision_set() CollisionSet
Get’s the world-space coordinate CollisionSet of the object, or the collection of all shapes that this EntityLike interacts with.
- Returns:
A new
CollisionSet
with it’s content’s copied.
- mergable_with(other: Entity) bool
Checks to see if an entity is “mergable” with another entity. This means that if a certain set of criteria is met, the attributes of
other
will be combined to the attributes of this entity. This is useful for mimicking cases where entities of the same name and type are placed on top of each other, merging them together into a single entity with shared attributes.For the full list of all merging rules, see (TODO).
Note
This function does not actually merge the two, it simply checks to see if such a merge is considered valid. To actually merge two entities use
merge()
.- Parameters:
other – The other
EntityLike
to check against.- Returns:
True
if they can be merged,False
otherwise.
- merge(other: Entity) None
Changes the attributes of the calling entity with the attributes of the passed in entity. The attributes of
other
take precedence over the attributes of the calling entity. They can be either copied or merged together, depending on the specific attribute being merged.For the full list of all merging rules, see (TODO).
- Parameters:
other – The other
EntityLike
to merge with.
- on_insert(parent: EntityCollection) None
TODO
- on_remove(parent: EntityCollection) None
TODO
- remove_circuit_condition() None
Removes the circuit condition of the Entity. Does nothing if the Entity has no circuit condition to remove.
- remove_logistic_condition() None
Removes the logistic condition of the Entity. Does nothing if the Entity has no logistic condition to remove.
- set_circuit_condition(a: str | None = None, cmp: str = '<', b: str | int = 0) None
Sets the circuit condition of the Entity.
cmp
can be specified as stored as the single unicode character which is used by Factorio, or you can use the Python formatted 2-character equivalents:# One of: [">", "<", "=", "≥", "≤", "≠"] # Or, alternatively: [">", "<", "==", ">=", "<=", "!="]
If specified in the second format, they are converted to and stored as the first format.
- Parameters:
a – The string name of the first signal.
cmp – The operation to use, as specified above.
b – The string name of the second signal, or some 32-bit constant.
- Raises:
DataFormatError – If
a
is not a valid signal name, ifcmp
is not a valid operation, or ifb
is neither a valid signal name nor a constant.
- set_logistic_condition(a: str | None = None, cmp: str = '<', b: str | int = 0) None
Sets the logistic condition of the Entity.
cmp
can be specified as stored as the single unicode character which is used by Factorio, or you can use the Python formatted 2-character equivalents:# One of: [">", "<", "=", "≥", "≤", "≠"] # Or, alternatively: [">", "<", "==", ">=", "<=", "!="]
If specified in the second format, they are converted to and stored as the first format.
- Parameters:
a – The string name of the first signal.
cmp – The operation to use, as specified above.
b – The string name of the second signal, or some 32-bit constant.
- Raises:
DataFormatError – If
a
is not a valid signal name, ifcmp
is not a valid operation, or ifb
is neither a valid signal name nor a constant.
- to_dict() dict
Converts the Entity to its JSON dict representation. The keys returned are determined by the contents of the exports dictionary and their criteria functions.
A attribute from the Entity will be included as a key in the output dict if both of the following conditions are met:
The attribute is in the
exports
dictionaryThe associated criteria function is either not present or returns
True
. This is used to avoid including excess keys, keeping Blueprint string size down.
In addition, a second function may be provided to have a formatting step to alter either the key and/or its value, which gets inserted into the output
dict
.- Returns:
The exported JSON-dict representation of the Entity.
- property circuit_connectable: bool
Whether or not this EntityLike can be connected using circuit wires. Not exported; read only.
- Type:
bool
- property circuit_stack_size_enabled: bool
Sets if the inserter’s stack size is controlled by circuit signal.
- Getter:
Gets whether or not the circuit stack size is enabled, or
None
if not set.- Setter:
Sets whether or not the circuit stack size is enabled. Removes the key if set to
None
.- Type:
bool
- Raises:
TypeError – If set to anything other than a
bool
orNone
.
- property circuit_wire_max_distance: int
The maximum distance that this entity can reach for circuit connections. Not exported; read only.
- Type:
float
- property collision_mask: set
The set of all collision layers that this Entity collides with, specified as strings. Equivalent to Factorio’s
data.raw
equivalent. Not exported; read only.- Type:
set{str}
- property collision_set: CollisionSet
TODO
- property connect_to_logistic_network: str
Whether or not this entity should use it’s logistic network condition to control its operation (if it has one).
- Getter:
Gets the value of
connect_to_logistic_network
, orNone
if not set.- Setter:
Sets the value of
connect_to_logistic_network
. Removes the key if set toNone
.- Type:
bool
- Raises:
TypeError – If set to anything other than a
bool
orNone
.
- property connections: dict
Connections dictionary. Primarily holds information about the Entity’s circuit connections (as well as copper wire connections).
- Type:
- Raises:
DataFormatError – If set to anything that does not match the format of
draftsman.signatures.CONNECTIONS
.
- property control_behavior: dict
The
control_behavior
of the Entity.- Getter:
Gets the
control_behavior
.- Setter:
Sets the
control_behavior
. Gets set to an emptydict
if set toNone
.- Type:
- Raises:
DataFormatError – If set to anything that does not match the
CONTROL_BEHAVIOR
signature.
- property direction: Direction
The direction that the Entity is facing. An Entity’s “front” is usually the direction of it’s outputs, if it has any.
For some entities, this attribute may be redundant; for example, the direction value for an
AssemblingMachine
only matters if the machine has a fluid input or output.Raises
DirectionWarning
if set to a diagonal direction. For 8-way rotations, ensure that the Entity inheritsEightwayDirectionalMixin
.- Getter:
Gets the direction that the Entity is facing.
- Setter:
Sets the direction of the Entity. Defaults to
Direction.NORTH
if set toNone
.- Type:
- Raises:
DraftsmanError – If the direction is set while inside an Collection, which is forbidden.
ValueError – If set to anything other than a
Direction
, or its equivalentint
.
- property double_grid_aligned: bool
Whether or not this EntityLike is “double-grid-aligned”, which applies to a number of rail entities. Not exported; read only.
- Type:
bool
- property dual_circuit_connectable: bool
Whether or not this EntityLike has two circuit connection points. Not exported; read only.
- Type:
bool
- property dual_power_connectable: bool
Whether or not this EntityLike has two power connection points. Not exported; read only.
- Type:
bool
- property flippable: bool
Whether or not this entity can be mirrored in game using ‘F’ or ‘G’. Not exported; read only.
Note
Work in progress. May be incorrect, especially for modded entities.
- property global_position: dict
The “global”, or root-most position of the Entity. This value is always equivalent to
position()
, unless the entity exists inside anEntityCollection
. If it does, then it’s global position is equivalent to the sum of all parent positions plus it’s own position. For example, if an Entity exists within aGroup
at position(5, 5)
and theGroup
exists at(5, 5)
, theglobal_position
of the Entity will be(10, 10)
.This is used to get an entity’s “actual” position in a blueprint, used when adding to a
SpatialHashMap
and when querying the entity by region. This attribute is always exported, but renamed to “position”; read only.- Type:
dict{"x": float, "y": float}
Whether or not this Entity is considered “hidden”, as specified in it’s flags in Factorio’s
data.raw
. Not exported; read only.Note
“Hidden” in this context is somewhat unintuitive, as items you might think would be considered hidden may not be. Ship wreckage entities, for example, are not considered “hidden”, even though the only way to access them is with the editor. Keep this in mind when querying this attribute, especially since this discrepancy might be considered a bug later on.
- Type:
bool
- property id: str
A unique string ID associated with this entity. ID’s can be anything, though there can only be one entity with a particular ID in an EntityCollection. Not exported.
- Getter:
Gets the ID of the entity, or
None
if the entity has no ID.- Setter:
Sets the ID of the entity.
- Type:
str
- Raises:
TypeError – If the set value is anything other than a
str
orNone
.DuplicateIDError – If the ID is changed while inside an
EntityCollection
to an ID that is already taken by another entity in saidEntityCollection
.
- property mode_of_operation: InserterModeOfOperation
The behavior that the inserter should follow when connected to a circuit network.
- Getter:
Gets the mode of operation, or
None
if not set.- Setter:
Sets the mode of operation. Removes the key if set to
None
.- Type:
- Raises:
ValueError – If set to a value that cannot be interpreted as a valid
InserterModeOfOperation
.
- property name: str
The name of the entity. Must be a valid Factorio ID string. Read only.
- Type:
str
- property override_stack_size: int
Sets an inserter’s stack size override. Will use this unless a circuit stack size is set and enabled.
- Getter:
Gets the overridden stack size.
- Setter:
Sets the overridden stack size.
- Type:
int
- Raises:
TypeError –
- property parent: EntityCollection
The parent
EntityCollection
object that contains the entity, orNone
if the entity does not currently exist within anEntityCollection
. Not exported; read only.- Type:
EntityCollection
- property position: Vector
The “canonical” position of the Entity, or the one that Factorio uses. Positions of most entities are located at their center, which can either be in the middle of a tile or on it’s transition, depending on the Entity’s
tile_width
andtile_height
.position
can be specified as adict
with"x"
and"y"
keys, or more succinctly as a sequence of floats, usually alist
ortuple
.position
can also be specified more verbosely as aVector
instance as well.This property is updated in tandem with
tile_position
, so using them both interchangeably is both allowed and encouraged.- Getter:
Gets the position of the Entity.
- Setter:
Sets the position of the Entity.
- Type:
- Raises:
IndexError – If the set value does not match the above specification.
DraftsmanError – If the entities position is modified when inside a EntityCollection, which is forbidden.
- property power_connectable: bool
Whether or not this EntityLike can be connected using power wires. Not exported; read only.
- Type:
bool
- property read_hand_contents: bool
Whether or not this Entity is set to read the contents of it’s hand to a circuit network.
- Getter:
Gets the value of
read_hand_contents
, orNone
if not set.- Setter:
Sets the value of
read_hand_contents
.- Type:
bool
- Raises:
TypeError – If set to anything other than a
bool
orNone
.
- property read_mode: ReadMode
The mode in which the contents of the Entity should be read. Either
ReadMode.PULSE
orReadMode.HOLD
.- Getter:
Gets the value of
read_mode
, orNone
if not set.- Setter:
Sets the value of
read_mode
.- Type:
- Raises:
ValueError – If set to anything other than a
ReadMode
value or theirint
equivalent.
- property rotatable: bool
Whether or not this EntityLike can be rotated. Note that this does not mean that the entity will prevent a blueprint from rotating; more, that this EntityLike does not have a concept of different rotation angles. For example, any
Reactor
entity will always returnrotatable
asFalse
when queried. Not exported; read only.- Type:
bool
- property stack_control_signal: dict
Specify the stack size input signal for the inserter if enabled.
Stored as a
dict
in the format{"name": str, "type": str}
, wherename
is the name of the signal andtype
is it’s type, either"item"
,"fluid"
, or"signal"
.However, because a signal’s type is always constant and can be inferred, it is recommended to simply set the attribute to the string name of the signal which will automatically be converted to the above format.
- Getter:
Gets the stack control signal, or
None
if not set.- Setter:
Sets the stack control signal. Removes the key if set to
None
.- Type:
- Raises:
InvalidSignalID – If set to a string that is not a valid signal name.
DataFormatError – If set to a dict that does not match the dict format specified above.
- property tags: dict
Tags associated with this Entity. Commonly used by mods to add custom data to a particular Entity when exporting and importing Blueprint strings.
- Getter:
Gets the tags of the Entity, or
None
if not set.- Setter:
Sets the Entity’s tags.
- Type:
dict{Any: Any}
- Raises:
TypeError – If tags is set to anything other than a
dict
orNone
.
- property tile_height: int
The height of the entity in tiles, rounded up to the nearest integer. Not exported; read only.
- Type:
int
- property tile_position: Vector
The tile-position of the Entity. The tile position is the position according the the LuaSurface tile grid, and is the top left corner of the top-leftmost tile of the Entity.
tile_position
can be specified as adict
with"x"
and"y"
keys, or more succinctly as a sequence of floats, usually alist
ortuple
.This property is updated in tandem with
position
, so using them both interchangeably is both allowed and encouraged.- Getter:
Gets the tile position of the Entity.
- Setter:
Sets the tile position of the Entity.
- Type:
- Raises:
IndexError – If the set value does not match the above specification.
DraftsmanError – If the entities position is modified when inside a EntityCollection, which is forbidden.
- property tile_width: int
The width of the entity in tiles, rounded up to the nearest integer. Not exported; read only.
- Type:
int
- property type: str
The type of the Entity. Equivalent to the key found in Factorio’s
data.raw
. Mostly equivalent to the type of the entity instance, though there are some differences, as noted here. Can be used as a criteria to search with inEntityCollection.find_entities_filtered()
. Not exported; read only.- Type:
str