factorio-draftsman

factorio-draftsman

factorio-draftsman is a Python module designed for creating, manipulating, and exporting Factorio Blueprint strings. It provides a programmatic way to handle blueprint data without manual string manipulation.

Key Capabilities:

• Blueprint Manipulation: Import, modify, create, add, remove, and export blueprints and their contents.
• Entity Management: Use unique entity IDs and dynamic associations between entities.
• Advanced Querying: Search blueprint contents by area, name, type, and other criteria.
• Structural Organization: Group entities together to treat them as single units for reuse in design.
• Data Fidelity: Emulates the Factorio data lifecycle by extracting data directly from Wube's public repository. This ensures compatibility with Factorio versions and provides built-in support for mods.
• Error Handling: Provides verbose warnings for modifications on import that would normally be ignored by the game.

Compatibility:

• Python: Version 3.10 and higher.
• Factorio: Version 1.0 and up (functionality for older versions is not guaranteed).

Draftsman organizes its functionality into several specialized submodules. Depending on your goal, you should look into the following areas:

• Blueprintable objects: For working with Blueprint, BlueprintBook, UpgradePlanner, DeconstructionPlanner, and Group.
• Entities: For all Entity implementations and their abstract base classes.
• Prototypes: For individual Entity prototype definitions.
• Environment: For modules that extract data from Factorio and store it as a Draftsman environment.
• Data: For modules that read and modify the Draftsman environment.
• Constants: For enumerations used when defining blueprints or entities.
• Signatures: For abstract data formats used across multiple class implementations.
• Tiles: For the Tile class and related methods.
• Extras: For specialized features (e.g., reversing all belts in a blueprint).
• Utilities: For generic utility functions.
• Errors and Warnings: For exception and warning types issued by the library.

Draftsman's 'environment' is a collection of extracted metadata (stored as pickle files in site-packages/draftsman/data) derived from Factorio's data.raw Lua tables. This environment provides the contextual information necessary for Draftsman to perform advanced tasks such as:

• Automatic Type Deduction: Inferring entity types from names.
• Validation: Warning if productivity modules are placed in machines that don't support them.
• Autocorrect: Suggesting correct names (e.g., suggesting wooden-chest for woden-chest).
• Prototype Access: Accessing raw game data like collision boxes, icon paths, and inventory sizes.

By default, Draftsman ships with pregenerated data, but this data must be manually updated to match new Factorio versions or specific mod configurations.

from draftsman.entity import Container

# Accessing raw prototype data from the environment
chest = Container("wooden-chest")
print(chest.prototype.keys())
# dict_keys(['name', 'type', 'collision_box', ..., 'max_health'])

# Accessing graphics information
print(chest.prototype["picture"])

Draftsman uses two coordinate systems that stay in sync:

1. position: Floating point coordinates representing the actual center of the entity.
2. tile_position: Integer coordinates representing the top-leftmost tile covered by the entity.

Usage:

• You can set either position or tile_position, and the other will update automatically.
• You can pass a draftsman.utils.Vector, a tuple, or a list to these attributes.
• If no position is specified, it defaults to tile_position (0, 0), with the absolute position deduced from the entity's tile dimensions.

from draftsman.entity import Container
from draftsman.utils import Vector

container = Container("steel-chest")

# Using Vector
container.position = Vector(10.5, 10.5)

# Using tuple/list (updates tile_position)
container.position = (15.5, 45.5)
container.tile_position = [2, 3]

# Setting in constructor
container2 = Container("iron-chest", position=[10.5, 15.5])

In Draftsman, connections (like circuit wires) between entities are managed using Associations rather than static integer indices.

In standard Factorio blueprint strings, connections use the index of the entity in the entities list. However, if you insert or delete entities, these indices shift, which would break connections or cause them to point to the wrong entity.

Draftsman solves this by using Associations, which are wrappers around weakref.ref that point directly to the memory location of the Entity object. This ensures that:

1. Stability: Moving or inserting entities does not break connections because the reference follows the object, not its position in a list.
2. Data Integrity: Changes made to an entity (e.g., changing its id) are immediately reflected through the association.
3. Memory Safety: Because they use weakref, an association won't prevent an entity from being garbage collected if it is deleted from the blueprint.

When exporting to a Factorio blueprint string, these Associations are automatically converted back into the numeric indices required by the Factorio format.

blueprint = Blueprint()
blueprint.entities.append("inserter", tile_position=[-1, 0])
blueprint.entities.append("inserter", tile_position=[+1, 0])

# Uses indices initially, but internally creates Associations
blueprint.add_circuit_connection("red", 0, 1)

# Inserting an entity in the middle does NOT break the connection
blueprint.entities.insert(1, "wooden-chest", tile_position=(0, 0))