`radar`¶

class Radar( name: ~typing.Annotated[str, <function conditional.<locals>.decorator.<locals>.attr_validator at 0x7e1ce69271c0>] = NOTHING, id: str | None = None, position: Vector | tuple[int | float, int | float] = None, tile_position: Vector | tuple[int | float, int | float] = NOTHING, mirror: bool = False, quality: ~typing.Literal['normal', 'uncommon', 'rare', 'epic', 'legendary', 'quality-unknown'] = 'normal', item_requests: list[~draftsman.signatures.BlueprintInsertPlan] | None = NOTHING, tags: dict[str, ~typing.Any] | None = NOTHING, connections: dict = NOTHING, *, extra_keys: dict[str, ~typing.Any] | None = None, )¶

Bases: CircuitConnectableMixin, EnergySourceMixin, Entity

An entity that reveals and scans neighbouring chunks.

property allowed_fuel_items : set[str] | None¶: A set of strings, each one a valid item that can be used as a fuel source to power this entity. If energy_source is not of type “burner”, then this property returns an empty set. Returns None if this entity is not recognized by the current environment.

property circuit_connectable : bool¶

Whether or not this EntityLike can be connected using circuit wires.

Example:

>>> from draftsman.entity import *
>>> Beacon().circuit_connectable
False
>>> Inserter().circuit_connectable
True
>>> DeciderCombinator().circuit_connectable
True

property circuit_wire_max_distance : float¶

The maximum distance that this entity can reach for circuit connections, modified based on the entity’s quality. If the quality is unknown, the distance falls back to the default max distance.

Returns None if the entity’s name is not recognized under the current environment.

property collision_mask : set[str]¶: The set of all collision layers that this Entity collides with, specified as strings. Equivalent to Factorio’s data.raw entry.

property collision_set : CollisionSet | None¶: The set of all CollisionShapes that this entity inherits. This set is dynamically updated based on the rotation or orientation of the entity, if applicable. If you want the collision shape of this entity that does not change via rotation or orientation, use static_collision_set instead.

property connections : dict¶

Deprecated since version 3.0.0: (Factorio 2.0)

This information is now converted and stored in Blueprint.wires.

Serialized

This attribute is imported/exported from blueprint strings.

Connections dictionary. Primarily holds information about the Entity’s circuit connections, as well as the copper wire connections into/out of PowerSwitch.

Historically, power connections between power poles were retained in the neighbours attribute - but this attribute is also deprecated in favor of Blueprint.wires.

property double_grid_aligned : bool¶: Whether or not this EntityLike is “double-grid-aligned”, which applies to entities which need to align with the rail grid.

property dual_circuit_connectable : bool¶

Whether or not this EntityLike has two circuit connection points.

Example:

>>> from draftsman.entity import *
>>> Beacon().dual_circuit_connectable
False
>>> Inserter().dual_circuit_connectable
False
>>> DeciderCombinator().dual_circuit_connectable
True

property dual_power_connectable : bool¶

Whether or not this EntityLike has two power connection points.

Example:

>>> from draftsman.entity import *
>>> Beacon().dual_power_connectable
False
>>> ElectricPole().dual_power_connectable
False
>>> PowerSwitch().dual_power_connectable
True

property energy_source : dict | None¶: The energy source specification for this entity. Returns None if this entity is not recognized by the current environment.

See also

https://lua-api.factorio.com/latest/types/BaseEnergySource.html.

extra_keys : dict[str, Any] | None¶

Serialized

This attribute is imported/exported from blueprint strings.

Any additional keys that are not recognized by Draftsman when loading from a raw JSON dictionary end up as keys in this attribute. Under normal circumstances, this field should always remain None, indicating that all fields provided were properly translated into the internal Python format.

If there are any values in extra_keys after being imported from a raw JSON dictionary, then (left alone) these values will also be exported back into an output JSON dictionary in order to keep import-export cycles stable. A side effect of this is that users can use this attribute to add additional fields that will end up in the output string, primarily for custom metadata that can be read by other tools:

>>> input_dict = {
...    "name": "wooden-chest",
...    "position": {"x": 0.5, "y": 0.5},
...    "unknown_key": "blah"
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"unknown_key": "blah"}
>>> container.extra_keys["custom"] = "data"
>>> container.to_dict()
{
    "name": "wooden-chest",
    "position": {"x": 0.5, "y": 0.5},
    "unknown_key": "blah",
    "custom": "data"
}

The structure of input keys are preserved, meaning you may have to recurse through keys to find the unknown data:

>>> input_dict = {
...     "name": "wooden-chest",
...     "position": {"x": 0.5, "y": 0.5},
...     "nested": {
...         "dictionary": "value"
...     }
... }
>>> container = Container.from_dict(input_dict)
>>> container.extra_keys
{"nested": {"dictionary": "value"}}

Note

While Draftsman makes an effort to preserve keys that it doesn’t recognize, Factorio itself makes no such effort - so if you create a blueprint string with custom metadata and then import it into the game, that additional data will be stripped and cannot be retrieved when exporting a new string from the game.

property flags : list[str] | None¶: A set of string flags which indicate a number of behaviors of this prototype.

See also

https://wiki.factorio.com/Types/EntityPrototypeFlags

property flippable : bool¶: Whether or not this entity can be mirrored in game using ‘F’ or ‘G’.

Warning

Work in progress. May be incorrect, especially for modded entities.

property fuel_input_size : _AndValidator object at 0x7e1ce9d4e8c0>] | None¶: Gets the total number of fuel input slots that this entity can hold. Returns None if energy_source is not of type “burner”, or if the name of this entity is not recognized in the current environment.

property fuel_output_size : _AndValidator object at 0x7e1ce9d4e8c0>] | None¶: Gets the total number of fuel output slots that this entity has. Returns None if energy_source is not of type “burner”, or if the entity itself is not recognized in the current environment.

property global_position : Vector¶

The “global”, or root-most position of the Entity. This value is always equivalent to position, unless the entity exists inside of a containing Collection - 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 a Group at position (5, 5) and the Group.position is (5, 5), the global_position of the Entity will be (10, 10).

id : str | None¶: A unique string ID associated with this entity. IDs can be anything, though there can only be one entity with a particular ID in a Collection.

item_requests : list[BlueprintInsertPlan]¶

Serialized

This attribute is imported/exported from blueprint strings.

A list of items to deliver to the entity. Not to be confused with logistics requests (which are persistent), item requests are only fulfilled once when the entity is first constructed. Most notably, modules are requested to entities with this field.

For user-friendly ways to modify this array, see set_item_request() and request_modules().

mirror : bool¶: Serialized

This attribute is imported/exported from blueprint strings.

Whether or not this blueprint is mirrored horizontally or vertically, specifically in regards to it’s fluid inputs/outputs.

Added in version 3.0.0: (Factorio 2.0)

name : EntityID¶: Serialized

This attribute is imported/exported from blueprint strings.

The name of the entity.

property parent : Collection | None¶: The parent Collection object that contains the entity, or None if the entity does not currently exist within an Collection.

position : _PosVector¶

Serialized

This attribute is imported/exported from blueprint strings.

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 and tile_height.

This property is updated in tandem with tile_position, so using them both interchangeably is both allowed and encouraged.

Raises:: DraftsmanError – If the entities position is modified when inside a Collection, which is forbidden.

property power_connectable : bool¶

Whether or not this EntityLike can be connected using power wires.

Example:

>>> from draftsman.entity import *
>>> Beacon().power_connectable
False
>>> ElectricPole().power_connectable
True
>>> PowerSwitch().power_connectable
True

property prototype : dict¶: The prototype dictionary extracted from Factorio’s data.raw for this entity. If this entity’s name does not correspond to an entry under the current environment, an empty dict is returned instead.

quality : QualityID¶

Serialized

This attribute is imported/exported from blueprint strings.

The quality of this entity. Can modify certain other attributes of the entity in (usually) positive ways.

Draftsman will automatically scale attributes based on quality value when appropriate. For example:

>>> from draftsman.entity import Container
>>> c = Container("steel-chest", quality="normal")
>>> c.size
48
>>> c.quality_affects_inventory_size
True
>>> c.quality = "legendary"
>>> c.size
120

Added in version 3.0.0: (Factorio 2.0)

property rotatable : bool¶

Whether or not this EntityLike has the capability of being rotated. This does not mean that blueprints containing these entities cannot be rotated; rather, it just means they will only ever have one orientation.

For example, it’s impossible for a Factorio Reactor to be oriented, so Reactor.rotatable always returns False.

property similar_entities : list[str]¶: Returns a list of strings representing the names of entities that share the same type as this one.

property square : bool¶: Whether or not the tile width of this entity matches it’s tile height, giving it a square footprint.

property static_collision_set : CollisionSet | None¶: The set of all CollisionShapes that this entity inherits. This set is always the shape of the entity with it’s default orientation (typically facing north) and does not change when the entity is rotated/flipped. If you want the collision shape of this entity that does change when rotated, use collision_set instead.

property static_tile_height : int¶: The height of the entity irrespective of it’s current orientation. Equivalent to the tile_width when the entity is facing north.

property static_tile_width : int¶: The width of the entity irrespective of it’s current orientation. Equivalent to the tile_width when the entity is facing north.

property surface_conditions : dict | None¶

Gets the dictionary of surface constraints which apply when placing this entity. A missing entry in this dict means that this entity has no restriction for that particular property type.

If this entity has no constraints whatsoever, an empty dictionary is returned. If this entity is unrecognized by Draftsman, None is returned.

tags : dict[str, Any] | None¶: Serialized

This attribute is imported/exported from blueprint strings.

Tags associated with this Entity ghosts. Commonly used by mods to add custom data to a particular Entity when exporting and importing Blueprint strings.

property tile_height : int¶: The height of the entity in tiles, taking into account it’s current orientation.

tile_position : _TileVector¶

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 that the Entity overlaps.

This property is updated in tandem with position, so using them both interchangeably is both allowed and encouraged.

Raises:: DraftsmanError – If the entities position is modified when inside a Collection, which is forbidden.

property tile_width : int¶: The width of the entity in tiles, taking into account it’s current orientation.

property type : str | None¶: 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 in Collection.find_entities_filtered(). Returns None if this entity’s name is not recognized when created without validation.

classmethod from_dict( d: dict, version: tuple[int, ...] | None = None, ) → Self¶

Attempts to construct a new instance of this class from a Python dictionary in JSON format.

Parameters:

d: dict¶

The dictionary to interpret.

version: tuple[int, ...] | None = None¶

The Factorio version that the input data is compliant with.

The given version tuple will automatically attempt to grab the closest applicable converter - meaning that specifying a version of (1, 1, 96) will use the 1.0 converter, and a version of (2, 0, 32) will use the 2.0 converter.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

get() → Entity | list[Entity]¶

Gets this Entity. Redundant for regular instances of Entity, but is needed for Collections like Group.

This function resolves some abstract EntityLike object (which can have no direct relation to Factorio whatsoever) to one or more valid Factorio-importable Entity instances.

Returns:: One or more Entity instances that represents this entire EntityLike.

get_world_bounding_box() → AABB | None¶: Gets the world-space coordinates AABB that completely encompasses the collision_set of this SpatialLike. Returns None if the collision set of the target object is unknown.

get_world_collision_set() → CollisionSet¶

Get’s the world-space coordinate CollisionSet of the object, AKA the collection of all shapes that this EntityLike interacts with.

Returns:: A copy of this objects CollisionSet with the correct world-space location.

is_placable_on(planet_name: str) → bool¶

Check to see if this entity is placable on a particular planet. If the surface_conditions of this entity are unknown, then this function always returns True.

Parameters:

planet_name: str¶: The name of the planet being checked, such as "nauvis" or "vulcanus".

Returns:

True if the entity can be placed on this surface, False otherwise.

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 the two entities use merge().

Parameters:

other: Entity¶: The other EntityLike to check against.

Returns:

True if they can be merged, False otherwise.

merge( other: CircuitConnectableMixin, )¶

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: CircuitConnectableMixin¶: The other EntityLike to merge with.

Creates a construction request for an item. Removes the item request if count is set to 0 or None.

Parameters:

item: str¶: The string name of the requested item.
count: int | None = None¶: The desired amount of that item. If omitted a count of 0 will be assumed.
quality: 'normal' | 'uncommon' | 'rare' | 'epic' | 'legendary' | 'quality-unknown' = 'normal'¶: The quality of the requested item.
inventory: InventoryType = 1¶: The particular InventoryType to request this item to, since entities (as of Factorio 2.0) can have more than one distinct inventory to request items to. If omitted, it will default to 1, which is usally the “primary” inventory.
slot: int | None = None¶: The particular slot in the inventory to place the item. The next empty slot will be chosen automatically if omitted.

Raises:

TypeError – If item is anything other than a str, or if count is anything other than an int or None.
InvalidItemError – If item is not a valid item name.
ValueError – If count is less than zero.

to_dict( version: tuple[int, ...] | None = None, exclude_none: bool = True, exclude_defaults: bool = True, entity_number: int | None = None, )¶

Export this object to a JSON dictionary, usually directly prior to encoding into the compressed blueprint string format.

Parameters:

version: tuple[int, ...] | None = None¶

Which Factorio version format this entity should be exported with. The same Draftsman object can be converted to many version-specific output dictionaries, each of which may have different structures.

If no version is provided, it will default to current environment’s Factorio version, or to draftsman.DEFAULT_FACTORIO_VERSION if unable to read the current environment.

exclude_none: bool = True¶

Whether or not None properties should be omitted from the output string. For certain properties this option has no effect, as they either must always be present or never be present if None.

exclude_defaults: bool = True¶

Whether or not to exclude properties that are equivalent to their default values. Including these values in the generated output is redundant as Factorio will populate them automatically, but it is useful to disable for illustation purposes.

entity_number: int | None = None¶

What numeric index this entity should be given, used for when resolving associations into concrete integer indexes. If omitted (usually when debugging), no "entity_number" key is provided to the output dict.

validate( mode: ValidationMode = ValidationMode.STRICT, ) → ValidationResult¶

Validates the called object against it’s known format.

Example:

>>> import draftsman
>>> from draftsman.constants import ValidationMode
>>> from draftsman.entity import Container
>>> from draftsman.error import DataFormatError
>>> c = Container("wooden-chest")
>>> with draftsman.validators.set_mode(ValidationMode.DISABLED):
...     c.bar = "incorrect"
>>> try:
...     c.validate().reissue_all()
... except DataFormatError as e:
...     print("wrong!")
wrong!

Parameters:

mode: ValidationMode = ValidationMode.STRICT¶: How strict to be when valiating the object, corresponding to the number and type of errors and warnings returned.

Returns:

A ValidationResult object, which contains all errors and warnings from the validation pass.

radar¶

`radar`¶