collection

Hosts the EntityCollection and TileCollection, which are used as parent classes for others, such as Blueprint and Group.

class EntityCollection

Abstract class used to describe an object that can contain a list of EntityLike instances.

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:
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.

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.

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

Function called when an EntityLike is inserted into this object’s entities list (assuming that the entities list is a EntityList). By default, this function does nothing, but any child class can customize it’s functionality by overriding it.

on_entity_remove(entitylike: EntityLike) → None

Function called when an EntityLike is removed from this object’s entities list (assuming that the entities list is a EntityList). By default, this function does nothing, but any child class can customize it’s functionality by overriding it.

on_entity_set(old_entitylike: EntityLike, new_entitylike: EntityLike) → None

Function called when an EntityLike is replaced with another in this object’s entities list (assuming that the entities list is a EntityList). By default, this function does nothing, but any child class can customize it’s functionality by overriding it.

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.

abstract property entities: EntityList

Object that holds the EntityLikes, usually a EntityList.

abstract property entity_map: SpatialDataStructure

Object that holds references to the entities organized by their spatial position. An implementation of SpatialDataStructure.

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

class TileCollection

Abstract class used to describe an object that can contain a list of Tile instances.

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.

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

Function called when an Tile is inserted into this object’s tiles list (assuming that the tiles list is a TileList). By default, this function does nothing, but any child class can customize it’s functionality by overriding it.

on_tile_remove(tile: Tile) → None

Function called when an Tile is removed from this object’s tiles list (assuming that the entities list is a TileList). By default, this function does nothing, but any child class can customize it’s functionality by overriding it.

on_tile_set(old_tile: Tile, new_tile: bool) → None

Function called when an Tile is replaced with another in this object’s tiles list (assuming that the tiles list is a TileList). By default, this function does nothing, but any child class can customize it’s functionality by overriding it.

abstract property tile_map: SpatialDataStructure

Object that holds the spatial information for the Tiles of this object, usually a SpatialHashMap.

abstract property tiles: TileList

Object that holds the Tiles, usually a TileList.