programmable_speaker

class ProgrammableSpeaker(name: str = 'programmable-speaker', **kwargs: dict)

Bases: CircuitConditionMixin, ControlBehaviorMixin, CircuitConnectableMixin, Entity

An entity that makes sounds that can be controlled by circuit network signals.

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.

get() Entity | list[Entity]

TODO

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

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, if cmp is not a valid operation, or if b 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:

  1. The attribute is in the exports dictionary

  2. The 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 alert_icon: dict

What icon to show to the player(s) and on the map if the speaker makes a sound (and alerts are enabled).

Type:

SIGNAL_ID

Raises:
property alert_message: str

What message to show to the player(s) if the speaker makes a sound (and alerts are enabled).

Type:

SIGNAL_ID

Raises:
property alert_parameters: dict

A set of attributes that affect the alert this programmable speaker makes (if it’s set to do so).

Getter:

Gets the alert parameters of the speaker.

Setter:

Sets the alert parameters of the speaker.

Type:

ALERT_PARAMETERS

Raises:

DataFormatError – If set to anything that does not match the ALERT_PARAMETERS format.

property allow_polyphony: bool

Whether or not to allow the speaker to play multiple notes at once.

Type:

bool

Raises:

TypeError – If set to anything other than a bool or None.

property circuit_connectable: bool

Whether or not this EntityLike can be connected using circuit wires. Not exported; read only.

Type:

bool

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 connections: dict

Connections dictionary. Primarily holds information about the Entity’s circuit connections (as well as copper wire connections).

Type:

See draftsman.signatures.CONNECTIONS

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 empty dict if set to None.

Type:

See draftsman.signatures.CONTROL_BEHAVIOR

Raises:

DataFormatError – If set to anything that does not match the CONTROL_BEHAVIOR signature.

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_playback: bool

Whether or not to play this sound at a constant volume regardless of distance.

Type:

bool

Raises:

TypeError – If set to anything other than a bool or None.

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 an EntityCollection. 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 exists at (5, 5), the global_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}

property hidden: bool

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 or None.

  • DuplicateIDError – If the ID is changed while inside an EntityCollection to an ID that is already taken by another entity in said EntityCollection.

property instrument_id: int

Numeric index of the instrument. Updated in tandem with instrument_name.

Getter:

Gets the number of the current instrument, or None if not set.

Setter:

Sets the number of the current instrument. Removes the key if set to None.

Raises:
  • InvalidInstrumentID – If set to a number that is not recognized as a valid instrument index for this speaker.

  • TypeError – If set to anything other than an int or None.

property instrument_name: str

Name of the instrument. Updated in tandem with instrument_id. Not exported.

Getter:

Gets the name of the current instrument, or None if not set.

Setter:

Sets the name of the current instrument. Removes the key if set to None.

Raises:
  • InvalidInstrumentID – If set to a name that is not recognized as a valid instrument index for this speaker.

  • TypeError – If set to anything other than a str or None.

property instruments: dict

A list of all instruments that this ProgrammableSpeaker has. Not exported; read only.

Type:

list.

property name: str

The name of the entity. Must be a valid Factorio ID string. Read only.

Type:

str

property note_id: int

Numeric index of the note. Updated in tandem with note_name.

Getter:

Gets the number of the current note, or None if not set.

Setter:

Sets the number of the current note. Removes the key if set to None.

Raises:
  • InvalidInstrumentID – If set to a number that is not recognized as a valid note index for this speaker.

  • TypeError – If set to anything other than an int or None.

property note_name: str

Name of the note. Updated in tandem with note_id. Not exported.

Getter:

Gets the name of the current instrument, or None if not set.

Setter:

Sets the name of the current instrument. Removes the key if set to None.

Raises:
  • InvalidInstrumentID – If set to a name that is not recognized as a valid instrument name for this speaker.

  • TypeError – If set to anything other than a str or None.

property parameters: dict

A set of general attributes that affect this programmable speaker.

Getter:

Gets the parameters of the speaker.

Setter:

Sets the parameters of the speaker.

Type:

PARAMETERS

Raises:

DataFormatError – If set to anything that does not match the PARAMETERS format.

property parent: EntityCollection

The parent EntityCollection object that contains the entity, or None if the entity does not currently exist within an EntityCollection. 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 and tile_height.

position can be specified as a dict with "x" and "y" keys, or more succinctly as a sequence of floats, usually a list or tuple. position can also be specified more verbosely as a Vector 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:

Vector

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 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 return rotatable as False when queried. Not exported; read only.

Type:

bool

property show_alert: bool

Whether or not to show an alert to the player(s) if a sound is played.

Type:

bool

Raises:

TypeError – If set to anything other than a bool or None.

property show_alert_on_map: bool

Whether or not to show the alert on the map where the speaker lives.

Type:

bool

Raises:

TypeError – If set to anything other than a bool or None.

property signal_value_is_pitch: bool

Whether or not the value of a signal determines the pitch of the note to play.

Type:

bool

Raises:

TypeError – If set to anything other than a bool or None.

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 or None.

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 a dict with "x" and "y" keys, or more succinctly as a sequence of floats, usually a list or tuple.

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:

Vector

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 in EntityCollection.find_entities_filtered(). Not exported; read only.

Type:

str

property volume: float

The volume of the programmable speaker, in the range [0.0, 1.0].

Raises VolumeRangeWarning if set to a value outside of the range [0.0, 1.0].

Getter:

Gets the volume of the speaker, or None if not set.

Setter:

Sets the volume of the speaker. Removes the key if set to None.

Type:

float

Raises:

TypeError – If set to anything other than a float or None.