`blueprint`

Contains the Blueprint class for easily creating and exporting blueprints.

{
    "blueprint": {
        "item": "blueprint", # The associated item with this structure
        "label": str, # A user given name for this blueprint
        "label_color": { # The overall color of the label
            "r": float[0.0, 1.0] or int[0, 255], # red
            "g": float[0.0, 1.0] or int[0, 255], # green
            "b": float[0.0, 1.0] or int[0, 255], # blue
            "a": float[0.0, 1.0] or int[0, 255]  # alpha (optional)
        },
        "icons": [ # A set of signals to act as visual identification
            {
                "signal": {"name": str, "type": str}, # Name and type of signal
                "index": int, # In range [1, 4], starting top-left and moving across
            },
            ... # Up to 4 icons total
        ],
        "description": str, # A user given description for this blueprint
        "version": int, # The encoded version of Factorio this planner was created 
                        # with/designed for (64 bits)
        "snap-to-grid": { # The size of the grid to snap this blueprint to
            "x": int, # X dimension in units
            "y": int, # Y dimension in units
        }
        "absolute-snapping": bool, # Whether or not to use absolute placement 
                                   # (defaults to True)
        "position-relative-to-grid": { # The offset of the grid if using absolute
                                       # placement
            "x": int, # X offset in units
            "y": int, # Y offset in units
        }
        "entities": [ # A list of entities in this blueprint
            {
                "name": str, # Name of the entity,
                "entity_number": int, # Unique number associated with this entity 
                "position": {"x": float, "y": float}, # Position of the entity
                ... # Any associated Entity key/value
            },
            ...
        ]
        "tiles": [ # A list of tiles in this blueprint
            {
                "name": str, # Name of the tile
                "position": {"x": int, "y": int}, # Position of the tile
            },
            ...
        ],
        "schedules": [ # A list of the train schedules in this blueprint
            {
                "schedule": [ # A list of schedule records
                    {
                        "station": str, # Name of the stop associated with these
                                        # conditions
                        "wait_conditions": [
                            {
                                "type": str, # Name of the type of condition
                                "compare_type": "and" or "or",
                                "ticks": int, # If using "time" or "inactivity"
                                "condition": CONDITION, # If a circuit condition is 
                                                        # needed
                            }
                        ],
                    },
                    ...
                ]
                "locomotives": [int, ...] # A list of ints, corresponding to
                                          # "entity_number" in "entities"
            },
            ...
        ]

    }
}

class Blueprint(blueprint: str | dict = None)

Bases: Transformable, TileCollection, EntityCollection, Blueprintable

Factorio Blueprint class. Contains and maintains a list of EntityLikes and Tiles and a selection of other metadata. Inherits all the functions and attributes you would expect, as well as some extra functionality.

add_circuit_connection(color: str, entity_1: EntityLike | int | str, entity_2: EntityLike | int | str, side1: int = 1, side2: int = 1) → None

Adds a circuit wire connection between two entities. Each entity can be either a reference to the original entity to connect, the index of the entity in the entities list, or it’s string ID. Color specifies the color of the wire to make the connection with, and is either "red" or "green". side1 specifies which side of the first entity to connect to (if applicable), and side2 specifies which side of the second entity to connect to (if applicable). Does nothing if the connection already exists.

Raises ConnectionSideWarning if the side of either of the entities is 2 when the entity is not dual-circuit-connectable.

Raises ConnectionRangeWarning if the distance between the two entities exceeds the maximum wire distance between the two.

Parameters:

color – Color of the wire to make the connection with. Must be either "red" or "green".
id1 – ID or index of the first entity to join.
id2 – ID or index of the second entity to join.
side1 – Which side of the first dual-circuit-entity to connect to, where 1 is “input” and 2 is “output”. Only used when the first entity is dual-circuit-connectable. Defaults to 1.
side2 – Which side of the second dual-circuit-entity to connect to, where 1 is “input” and 2 is “output”. Only used when the second entity is dual-circuit-connectable. Defaults to 1.

Raises:

KeyError, IndexError – If entity_1 and/or entity_2 are invalid ID’s or indices to the parent Collection.
InvalidAssociationError – If entity_1 and/or entity_2 are not inside the parent Collection.
InvalidWireTypeError – If color is neither "red" nor "green".
InvalidConnectionSideError – If side1 or side2 are neither 1 nor 2.
EntityNotCircuitConnectableError – If either entity_1 or entity_2 do not have the capability to be circuit wire connected.

add_power_connection(entity_1: EntityLike | int | str, entity_2: EntityLike | int | str, side: int = 1) → None

Adds a copper wire power connection between two entities. Each entity can be either a reference to the original entity to connect, the index of the entity in the entities list, or it’s string ID. Tuples of strings and ints mean to recursively search through EntityCollection instances in the base level, following the logic of EntityList.__getitem__(). For example:

blueprint.entities.append("small-electric-pole")
group = Group("group") # Type of EntityCollection
group.entities.append("small-electric-pole", tile_position=(5, 0))
blueprint.entities.append(group)

# Add a connection between the first power pole and the first entity
# in the group
blueprint.add_power_connection(blueprint.entities[0], ("group", 0))

Side specifies which side to connect to when establishing a connection to a dual-power-connectable entity (usually a power-switch). Does nothing if the connection already exists.

Raises ConnectionRangeWarning if the distance between the two entities exceeds the maximum wire distance between the two.

Raises TooManyConnectionsWarning if either of the power poles exceed 5 connections when this connection is added.

Note

side is in 1-based notation (1 and 2, input and output) which is identical to circuit connections. Internally, however, the connections are represented in 0-based notation as “Cu0” and “Cu1” respectively.

Note

You might notice that unlike add_circuit_connection(), there is only one side argument. This is because it is actually impossible to connect two dual-power-connectable entities with one another; they must be connected to a power pole in-between.

Parameters:

entity_1 – EntityLike, ID, or index of the first entity to join.
entity_2 – EntityLike, ID or index of the second entity to join.
side – Which side of a dual-power-connectable entity to connect to, where 1 is “input” and 2 is “output”. Only used when connecting a dual-power-connectable entity. Defaults to 1.

Raises:

KeyError, IndexError – If entity_1 and/or entity_2 are invalid ID’s or indices to the parent Collection.
InvalidAssociationError – If entity_1 and/or entity_2 are not inside the parent Collection.
InvalidConnectionSideError – If side is neither 1 nor 2.
EntityNotPowerConnectableError – If either entity_1 or entity_2 do not have the capability to be copper wire connected.
DraftsmanError – If both entity_1 and entity_2 are dual-power-connectable, of which a connection is forbidden.

find_entities(aabb: AABB | list[list[float, float], list[float, float]] | None = None) → list[EntityLike]

Returns a list of all entities within the area aabb. Works similiarly to LuaSurface.find_entities. If no aabb is provided then the method simply returns all the entities in the blueprint.

Parameters:: aabb – An AABB, or a Sequence of 4 floats, usually a list or tuple.
Returns:: A regular list of EntityLikes whose collision_box overlaps the queried AABB.

find_entities_filtered(**kwargs: dict) → list[EntityLike]

Returns a filtered list of entities within the Collection. Works similarly to LuaSurface.find_entities_filtered.

Keywords are organized into two main categrories: region and criteria:

Region keywords
Name	Type	Description
`position`	`Vector` or `PrimitiveVector`	Grid position to search.
`radius`	`float`	Radius of the circle around position to search.
`area`	`AABB` or `PrimitiveAABB`	AABB to search in.

Criteria keywords
Name	Type	Description
`name`	`str` or `set{str}`	The name(s) of the entities that you want to search for.
`type`	`str` or `set{str}`	The type(s) of the entities that you want to search for.
`direction`	`Direction` or `set{Direction}`	The direction(s) of the entities that you want to search for. Excludes entities that have no direction.
`limit`	`int`	Limit the maximum size of the returned list to this amount. Unlimited by default.
`invert`	`bool`	Whether or not to return the inverse of the search. False by default.

position and radius take precidence over aabb if all are specified. If no region keywords are specified, the entire Collection is searched.

find_entity(name: str, position: Vector | PrimitiveVector) → EntityLike

Finds an entity with name at a position position. If multiple entities exist at the queried position, the one that was first placed is returned.

Parameters:

name – The name of the entity to look for.
position – The position to search, either a PrimitiveVector or a Vector.

Retuns:

The EntityLike at position, or None of none were found.

find_entity_at_position(position: Vector | PrimitiveVector) → EntityLike

Finds any entity at the position position. If multiple entities exist at the queried position, the one that was first placed is returned.

Parameters:: position – The position to search, either a PrimitiveVector or a Vector.
Retuns:: The EntityLike at position, or None of none were found.

find_tile(position: Vector | PrimitiveVector) → Tile

Returns the tile at the tile coordinate position. If there are multiple tiles at that location, the entity that was inserted first is returned.

Parameters:: position – The position to search, either a PrimitiveVector or a Vector.
Returns:: The tile at position, or None if there is none.

find_tiles_filtered(**kwargs: dict) → list[Tile]

Returns a filtered list of tiles within the blueprint. Works similarly to LuaSurface.find_tiles_filtered.

Keywords are organized into two main categrories: region and criteria:

Region keywords
Name	Type	Description
`position`	`Vector` or `PrimitiveVector`	Grid position to search.
`radius`	`float`	Radius of the circle around position to search.
`area`	`AABB` or `PrimitiveAABB`	AABB to search in.

Criteria keywords
Name	Type	Description
`name`	`str` or `set{str}`	The name(s) of the entities that you want to search for.
`limit`	`int`	Limit the maximum size of the returned list to this amount. Unlimited by default.

position and radius take precidence over aabb if all are specified. If no region keywords are specified, the entire Collection is searched.

flip(direction: str = 'horizontal') → None

Flip the blueprint across an axis, if possible. Flipping is done over the x or y axis, depeding on the input direction.

Warning

This function is currently under active development.

Parameters:: direction – The direction to flip by; either "horizontal" or "vertical"

generate_power_connections(prefer_axis: bool = True, only_axis: bool = False) → None

Automatically create power connections between all electric poles.

The algorithm used is similar to demi-pixel’s generateElectricalConnections() function, but with some slight differences. Power poles are still prioritized closest first, but can be selected to prefer to connect neighbours on the same axis, as well as only connect to neighbours on the same axis. This function will only connect power poles that have less than 5 power connections already made, preserving power connections that were manually specified. This function does not generate connections between power-switches.

Parameters:

prefer_axis – Determines whether or not to rank power-poles on the same x or y coordinate higher than poles that are closer, but not on either axis. Used to prefer creating neat, regular grids when possible.
only_axis – Removes any neighbour that does not lie on the same x or y axis from the candidate pool, preventing non-grid connections.

load_from_string(string: str) → None

Load the Blueprintable with the contents of string.

Raises DraftsmanWarning if there are any unrecognized keywords in the blueprint string for this particular blueprintable.

Parameters:

string – Factorio-encoded blueprint string.

Raises:

MalformedBlueprintStringError – If the input string is not decodable to a JSON object.
IncorrectBlueprintTypeError – If the input string is of a different type than the base class.

on_entity_insert(entitylike: EntityLike, merge: bool) → EntityLike

Callback function for when an EntityLike is added to this Blueprint’s entities list. Handles the addition of the entity into entity_map, and recalculates it’s dimensions.

Raises:: UnreasonablySizedBlueprintError – If inserting the new entity causes the blueprint to exceed 10,000 x 10,000 tiles in dimension.

on_entity_remove(entitylike: EntityLike) → None: Callback function for when an EntityLike is removed from a Blueprint’s entities list. Handles the removal of the EntityLike from entity_map.

on_entity_set(old_entitylike: EntityLike, new_entitylike: EntityLike) → None: Callback function for when an EntityLike is overwritten in a Blueprint’s entities list. Handles the removal of the old EntityLike from entity_map and adds the new one in it’s stead.

on_tile_insert(tile: Tile, merge: bool) → None

Callback function for when a Tile is added to this Blueprint’s tiles list. Handles the addition of the tile into tile_map, and recalculates it’s dimensions.

Raises:: UnreasonablySizedBlueprintError – If inserting the new tile causes the blueprint to exceed 10,000 x 10,000 tiles in dimension.

on_tile_remove(tile: Tile) → None: Callback function for when a Tile is removed from a Blueprint’s tiles list. Handles the removal of the Tile from the tile_map.

on_tile_set(old_tile: Tile, new_tile: Tile) → None: Callback function for when a Tile is overwritten in a Blueprint’s tiles list. Handles the removal of the old Tile from tile_map and adds the new one in it’s stead.

recalculate_area() → None: Recalculates the area, tile_width, and tile_height. Called automatically when an EntityLike or Tile object is altered or removed. Can be called by the end user, though it shouldn’t be neccessary.

remove_circuit_connection(color: str, entity_1: EntityLike | int | str, entity_2: EntityLike | int | str, side1: int = 1, side2: int = 1) → None

Removes a circuit wire connection between two entities. Each entity can be either a reference to the original entity to connect, the index of the entity in the entities list, or it’s string ID. side1 specifies which side of the first entity to remove the connection from (if applicable), and side2 specifies which side of the second entity to remove the connection from (if applicable). Does nothing if the specified connection doesn’t exist.

Parameters:

color – Color of the wire to remove. Either "red" or "green".
entity_1 – ID or index of the first entity to remove the connection to.
entity_@ – ID or index of the second entity to remove the connection to.
side1 – Which side of the first dual-circuit-connectable entity to remove the connection from, where 1 is “input” and 2 is “output”. Only used when disjoining a dual-circuit-connectable entity. Defaults to 1.
side2 – Which side of the second dual-circuit-connectable entity to remove the connection from, where 1 is “input” and 2 is “output”. Only used when disjoining a dual-circuit-connectable entity. Defaults to 1.

Raises:

KeyError, IndexError – If entity_1 and/or entity_2 are invalid ID’s or indices to the parent Collection.
InvalidAssociationError – If entity_1 and/or entity_2 are not inside the parent Collection.

remove_circuit_connections() → None: Remove all circuit connections in the Collection. Recurses through all subgroups and removes circuit connections from them as well. Does nothing if there are no circuit connections in the Collection.

remove_power_connection(entity_1: EntityLike | int | str, entity_2: EntityLike | int | str, side: int = 1) → None

Removes a copper wire power connection between two entities. Each entity can be either a reference to the original entity to connect, the index of the entity in the entities list, or it’s string ID. side specifies which side to remove the connection from when removing a connection to a dual-power-connectable entity (usually a power-switch). Does nothing if the specified connection does not exist.

Parameters:

entity_1 – EntityLike, ID or index of the first entity to remove the connection to.
entity_2 – EntityLike, ID or index of the second entity to remove the connection to.
side – Which side of a dual-power-connectable entity to remove the connection from, where 1 is “input” and 2 is “output”. Only used when disjoining a dual-power-connectable entity. Defaults to 1.

Raises:

KeyError, IndexError – If entity_1 and/or entity_2 are invalid ID’s or indices to the parent Collection.
InvalidAssociationError – If entity_1 and/or entity_2 are not inside the parent Collection.

remove_power_connections() → None: Remove all power connections in the Collection, including any power connections between power switches. Recurses through any subgroups, and removes power connections from them as well. Does nothing if there are no power connections in the Collection.

rotate(angle: int) → None

Rotate the blueprint by angle, if possible. Operates the same as pressing ‘r’ with a blueprint selected.

angle is specified in terms of Direction enum, meaning that a rotation of 2 is 90 degrees clockwise.

Because eight-way rotatable entities exist in a weird gray area, this function behaves like the feature in-game and only rotates on 90 degree intervals. Attempting to rotate the blueprint an odd amount raises an RotationError.

Warning

This function is currently under active development.

Parameters:: angle – The angle to rotate the blueprint by.
Raises:: RotationError – If the rotation is attempted with an odd value.

setup(**kwargs)

Setup the Blueprintable’s parameters with the input keywords as values. Primarily used by the constructor, but can be used at any time to set a large number of keys all at once.

Raises DraftsmanWarning if any of the input keywords are unrecognized.

Parameters:: kwargs – The dict of all keywords to set in the blueprint.

Note

Calling setup only sets the specified keys to their values, and everything else to either their defaults or None. In other words, the effect of calling setup multiple times is not cumulative, but rather set to the keys in the last call.

Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint()
>>> blueprint.setup(label="test")
>>> assert blueprint.label == "test"
>>> test_dict = {"description": "testing..."}
>>> blueprint.setup(**test_dict)
>>> assert blueprint.description == "testing..."
>>> assert blueprint.label == None # Gone!

to_dict() → dict

Returns the blueprint as a dictionary. Intended for getting the precursor to a Factorio blueprint string before encoding and compression takes place.

Returns:: The dict representation of the Blueprint.

to_string() → str

Returns this object as an encoded Factorio blueprint string.

Returns:: The zlib-compressed, base-64 encoded string.
Example:

>>> from draftsman.blueprintable import (
...     Blueprint, DeconstructionPlanner, UpgradePlanner, BlueprintBook
... )
>>> Blueprint({"version": (1, 0)}).to_string()
'0eNqrVkrKKU0tKMrMK1GyqlbKLEnNVbJCEtNRKkstKs7Mz1OyMrIwNDE3sTQ3Mzc0MDM1q60FAHmVE1M='
>>> DeconstructionPlanner({"version": (1, 0)}).to_string()
'0eNpdy0EKgCAQAMC/7Nkgw7T8TIQtIdga7tol/HtdunQdmBs2DJlYSg0SMy1nWomwgL+BUSTSzuCppqQgCh7gf6H7goILC78Cfpi0cWZ21unejra1B7C2I9M='
>>> UpgradePlanner({"version": (1, 0)}).to_string()
'0eNo1yksKgCAUBdC93LFBhmm5mRB6iGAv8dNE3Hsjz/h0tOSzu+lK0TFThu0oVGtgX2C5xSgQKj2wcy5zCnyUS3gZdjukMuo02shV73qMH4ZxHbs='
>>> BlueprintBook({"version": (1, 0)}).to_string()
'0eNqrVkrKKU0tKMrMK4lPys/PVrKqVsosSc1VskJI6IIldJQSk0syy1LjM/NSUiuUrAx0lMpSi4oz8/OUrIwsDE3MTSzNzcwNDcxMzWprAVWGHQI='

translate(x: int, y: int) → None

Translates all entities and tiles in the blueprint by x and y. Raises RailAlignmentWarning if the parent class contains double-grid-aligned entities and the translation amount is an odd value on either x or y.

Parameters:

x – A number indicating how much to translate along x.
y – A number indicating how much to translate along y.

version_string() → str

Returns the version of the Blueprintable in human-readable string.

Returns:: a str of 4 version numbers joined by a ‘.’ character.
Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint({"version": (1, 2, 3)})
>>> blueprint.version_string()
'1.2.3.0'

version_tuple()

Returns the version of the Blueprintable as a 4-length tuple.

Returns:: A 4 length tuple in the format (major, minor, patch, dev_ver).
Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint({"version": 281474976710656})
>>> blueprint.version_tuple()
(1, 0, 0, 0)

property absolute_snapping: bool

Whether or not the blueprint uses absolute positioning or relative positioning for the snapping grid. On import, a value of None is interpreted as a default True.

Getter:: Gets whether or not this blueprint uses absolute positioning, or None if not set.
Setter:: Sets whether or not to use absolute-snapping. Removes the attribute if set to None.
Type:: bool
Raises:: TypeError – If set to anything other than a bool or None.

property area: list[list[float]]

The Axis-aligned Bounding Box of the Blueprint’s dimensions. Not exported; for user aid. Read only.

Stored internally as a list of two lists, where the first one represents the top-left corner (minimum) and the second the bottom-right corner (maximum). This attribute is updated every time an Entity or Tile is changed inside the Blueprint.

Type:: list[list[float, float], list[float, float]]

property description: str

The description of the blueprintable. Visible when hovering over it when inside someone’s inventory.

Getter:: Gets the description, or None if not set.
Setter:: Sets the description of the object. Removes the attribute if set to None.
Type:: str
Raises:: TypeError – If setting to anything other than a str or None.

property double_grid_aligned: bool

Whether or not the blueprint is aligned with the double grid, which is the grid that rail entities use, like rails and train-stops. If the blueprint has any entities that are double-grid-aligned, the Blueprint is considered double-grid-aligned. Read only.

Type:: bool

property entities: EntityList: The list of the Blueprint’s entities. Internally the list is a custom class named EntityList, which has all the normal properties of a regular list, as well as some extra features. For more information on EntityList, check out this writeup here.

Note

Currently, assigning to this always triggers a deep copy. To avoid this, use EntityList.append() or EntityList.extend() instead.

property entity_map: SpatialDataStructure: An implementation of SpatialDataStructure for entities. Not exported; read only.

property flippable: bool

Whether or not this collection can be flipped or not. This is determined by whether or not any of the entities contained can be flipped or not. Read only.

Type:: bool

property icons: list

The visible icons of the blueprintable, shown in as the objects icon.

Stored as a list of ICON objects, which are dicts that contain a SIGNAL_ID and an index key. Icons can be specified in this format, or they can be specified more succinctly with a simple list of signal names as strings.

All signal entries must be a valid signal ID. If the input format is a list of strings, the index of each item will be it’s place in the list + 1. A max of 4 icons are permitted.

Getter:: Gets the list if icons, or None if not set.
Setter:: Sets the icons of the Blueprint. Removes the attribute if set to None.
Type:: {"index": int, "signal": {"name": str, "type": str}}
Raises:: DataFormatError – If the set value does not match either of the specifications above.
Example:

>>> from draftsman.blueprintable import Blueprint
>>> blueprint = Blueprint()
>>> blueprint.icons = ["transport-belt"]
>>> blueprint.icons
[{'index': 1, 'signal': {'name': 'transport-belt', 'type': 'item'}}]

property item: str

Always the name of the corresponding Factorio item to this blueprintable instance. Read only.

Type:: str
Example:

>>> from draftsman.blueprintable import (
...     Blueprint, DeconstructionPlanner, UpgradePlanner, BlueprintBook
... )
>>> Blueprint().item
'blueprint'
>>> DeconstructionPlanner().item
'deconstruction-planner'
>>> UpgradePlanner().item
'upgrade-planner'
>>> BlueprintBook().item
'blueprint-book'

property label: str

The user given name (title) of the blueprintable.

Getter:: Gets the label, or None if not set.
Setter:: Sets the label of this object.
Type:: str
Raises:: TypeError – When setting label to something other than str or None.

property label_color: dict

The color of the Blueprint’s label.

The label_color parameter exists in a dict format with the “r”, “g”, “b”, and an optional “a” keys. The color can be specified like that, or it can be specified more succinctly as a sequence of 3-4 numbers, representing the colors in that order.

The value of each of the numbers (according to Factorio spec) can be either in the range of [0.0, 1.0] or [0, 255]; if all the numbers are <= 1.0, the former range is used, and the latter otherwise. If “a” is omitted, it defaults to 1.0 or 255 when imported, depending on the range of the other numbers.

Getter:: Gets the color of the label, or None if not set.
Setter:: Sets the label color of the Blueprint.
Type:: dict{"r": number, "g": number, "b": number, Optional("a"): number}
Raises:: DataFormatError – If the input label_color does not match the above specification.
Example:

blueprint.label_color = (127, 127, 127)
print(blueprint.label_color)
# {'r': 127.0, 'g': 127.0, 'b': 127.0}

property position_relative_to_grid: dict

The absolute position of the snapping grid in the world. Only used if absolute_snapping is set to True or None.

Getter:: Gets the absolute grid-position offset, or None if not set.
Setter:: Sets the a
Type:: dict{"x": int, "y": int}

property rotatable: bool

Whether or not this collection can be rotated or not. Included for posterity; always returns True, even when containing entities that have no direction component. Read only.

Type:: bool

property schedules: list

A list of the Blueprint’s train schedules.

Note

Currently there is no framework around creating schedules by script; It can still be done by manipulating the contents of this list, but an easier way to manipulate trains and their schedules is still under development.

blueprint

`blueprint`