# factorio-draftsman
[](https://badge.fury.io/py/factorio-draftsman)
[](https://factorio-draftsman.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/redruin1/factorio-draftsman)
[](https://github.com/psf/black)
A 'draftsman' is a kind of artist that specializes in creating technical drawings across many engineering disciplines, including architectural, mechanical, and electrical.
Similarly, `factorio-draftsman` is a Python module for creating and editing blueprints for the game [Factorio](https://factorio.com/).
```python
from draftsman.blueprintable import Blueprint, BlueprintBook
from draftsman.constants import Direction
from draftsman.entity import ConstantCombinator
blueprint = Blueprint()
blueprint.label = "Example"
blueprint.description = "A blueprint for the readme."
blueprint.version = (1, 0) # 1.0
# Create a alt-mode combinator string
test_string = "testing"
for i, c in enumerate(test_string):
constant_combinator = ConstantCombinator()
constant_combinator.tile_position = (i, 0)
letter_signal = "signal-{}".format(c.upper())
constant_combinator.set_signal(index=0, signal=letter_signal, count=0)
blueprint.entities.append(constant_combinator)
# Create a simple clock and blinking light
constant = ConstantCombinator()
constant.tile_position = (-1, 3)
constant.direction = Direction.EAST
constant.set_signal(0, "signal-red", 1)
constant.id = "constant"
blueprint.entities.append(constant)
# Flexible ways to specify entities
blueprint.entities.append(
"decider-combinator",
id="clock",
tile_position=[0, 3],
direction=Direction.EAST,
control_behavior={
"decider_conditions": {
"first_signal": "signal-red",
"comparator": "<=",
"constant": 60,
"output_signal": "signal-red",
"copy_count_from_input": True,
}
},
)
# Use IDs to keep track of complex blueprints
blueprint.entities.append("small-lamp", id="blinker", tile_position=(2, 3))
blinker = blueprint.entities["blinker"]
blinker.set_circuit_condition("signal-red", "=", 60)
blinker.use_colors = True
blueprint.add_circuit_connection("green", "constant", "clock")
blueprint.add_circuit_connection("red", "clock", "clock", 1, 2)
blueprint.add_circuit_connection("green", "clock", "blinker", 2, 1)
# Factorio API filter capabilities
ccs = blueprint.find_entities_filtered(name="constant-combinator")
assert len(ccs) == len(test_string) + 1
blueprint_book = BlueprintBook()
blueprint_book.blueprints = [blueprint]
print(blueprint_book) # Pretty printing using json
print(blueprint_book.to_string()) # Blueprint string to import into Factorio
```
--------------------------------------------------------------------------------
## Overview
Simply put, Draftsman attempts to provide a universal solution to the task of creating and manipulating Factorio blueprint strings, which are compressed text strings used by players to share their constructions easily with others.
Draftsman allows users to programmatically create these strings via script, allowing for designs that would normally be too tedious to design by hand, such as combinator computer compilers, image-to-blueprint converters, pumpjack placers, as well as any other complex or repetitive design better suited for a computer's touch.
For a user-friendly timeline of how this project came about, as well as some pretty illustrations of it's capabilities, [you can read an article](https://alt-f4.blog/ALTF4-61/) written for the amazing fan-run community spotlight website [Alt-F4](https://alt-f4.blog/).
For more information on what exactly Draftsman is and does, as well as its intended purpose and philosophy, [you can read the documentation here](https://factorio-draftsman.readthedocs.io/en/latest/index.html).
For more examples on what exactly you can do with Draftsman, take a look at the [examples folder](https://github.com/redruin1/factorio-draftsman/tree/main/examples).
### Features
* Compatible with the latest versions of Python 2 and 3
* Compatible with the latest versions of Factorio (1.0+)
* Compatible with Factorio mods(!)
* Well documented
* Intuitive and flexible API
* Useful constructs for ease-of-use:
* Give entities unique string IDs to make association between entities easier
* Filter entities from blueprints by type, region and other parameters [just like Factorio's own API](https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.find_entities_filtered)
* Entities are categorized and organized within `draftsman.data` for easy and flexible iteration
* Group entities together and manipulate them all as one unit
* Verbose Errors and Warnings ("Factorio-safety" and "Factorio-correctness")
* Expansive and rigorous test suite
--------------------------------------------------------------------------------
## Usage
### Installation:
```
pip install factorio-draftsman
```
This will install the latest version of Draftsman with a set of pre-generated data from the latest version of vanilla Factorio.
If you want to have the same data validation that Draftsman provides for vanilla data with mods as well, you can re-generate this data with the command line tool `draftsman-update`, which is described in detail [here](TODO).
### Testing with [unittest](https://docs.python.org/3/library/unittest.html):
```
python -m unittest discover
```
Note that testing currently is only *guaranteed* to work with a vanilla install.
### Coverage with [coverage](https://coverage.readthedocs.io/en/6.3.2/):
```
coverage run
```
--------------------------------------------------------------------------------
### How to use mods with Draftsman:
Determine where your mods are installed; you can either copy the mods you want into the local `site-packages/draftsman/factorio-mods` folder where Draftsman is installed (which it looks in by default), or you can specify an external path with the `-p` or `--path` argument which can point to your Factorio mods folder or anywhere else convenient.
Then, simply call `draftsman-update` or `draftsman-update --path some/path/to/mods` to automatically update the data associated with that Draftsman installation.
`draftsman-update` can also be called in script via the method `draftsman.env:update()` if you want to change the mod list on the fly:
```python
# my_update_script.py
from draftsman.env import update
update(verbose=True, path="some/path") # equivalent to 'draftsman-update -v -p some/path'
```
Both `mod-info.json` and `mod-settings.dat` are recognized by `draftsman-update`, so you can also just change the settings in either of those and the loading process will adjust as well.
## TODO
* Add warnings for placement constraints on rails, rail signals and train stops
* Add constraints on `UpgradePlanner` and `DeconstructionPlanner`
* `Blueprint.schedules` convenience functions
* More doctests
* Add documentation on report and contributing
* Write test cases for `dump_format`
* Add plaintext representations of Entity JSON objects for all entities in addition to blueprintables
* Update modding documentation guide to reflect 2.0 changes
* Reevaluate the diamond diagrams for inherited `Entity` subclass
* Figure out exactly what determines if an `Entity` is flip-able or not
* Maybe add interface so that mods can include files that can be loaded with Draftsman? (this would be neat)
* Split documentation from docstrings so that each function has a more readable example
* RailPlanner (specify rail paths via turtle-like commands)
* Custom `data.raw` extraction and formatting?
* Maybe integrate defaults for more succinct blueprint strings?
* Unify entity validation into one monolithic thing
* Investigate more performant alternatives to `schema` (validir? requires cython, currently we're pure python)
* Look into Lua (or other language) bindings via backport to C/Cython
Raw data
{
"_id": null,
"home_page": "https://github.com/redruin1/factorio-draftsman",
"name": "factorio-draftsman",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "factorio,blueprint,string",
"author": "redruin1",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/96/7b/10bc9d44a0f03e3cf9d7bcc5095dbb480ba7a4eecdd9074aade34c180c20/factorio-draftsman-1.1.0.tar.gz",
"platform": null,
"description": "# factorio-draftsman\r\n\r\n\r\n\r\n[](https://badge.fury.io/py/factorio-draftsman)\r\n[](https://factorio-draftsman.readthedocs.io/en/latest/?badge=latest)\r\n[](https://codecov.io/gh/redruin1/factorio-draftsman)\r\n[](https://github.com/psf/black)\r\n\r\nA 'draftsman' is a kind of artist that specializes in creating technical drawings across many engineering disciplines, including architectural, mechanical, and electrical.\r\nSimilarly, `factorio-draftsman` is a Python module for creating and editing blueprints for the game [Factorio](https://factorio.com/).\r\n\r\n```python\r\nfrom draftsman.blueprintable import Blueprint, BlueprintBook\r\nfrom draftsman.constants import Direction\r\nfrom draftsman.entity import ConstantCombinator\r\n\r\nblueprint = Blueprint()\r\nblueprint.label = \"Example\"\r\nblueprint.description = \"A blueprint for the readme.\"\r\nblueprint.version = (1, 0) # 1.0\r\n\r\n# Create a alt-mode combinator string\r\ntest_string = \"testing\"\r\nfor i, c in enumerate(test_string):\r\n constant_combinator = ConstantCombinator()\r\n constant_combinator.tile_position = (i, 0)\r\n letter_signal = \"signal-{}\".format(c.upper())\r\n constant_combinator.set_signal(index=0, signal=letter_signal, count=0)\r\n blueprint.entities.append(constant_combinator)\r\n\r\n# Create a simple clock and blinking light\r\nconstant = ConstantCombinator()\r\nconstant.tile_position = (-1, 3)\r\nconstant.direction = Direction.EAST\r\nconstant.set_signal(0, \"signal-red\", 1)\r\nconstant.id = \"constant\"\r\nblueprint.entities.append(constant)\r\n\r\n# Flexible ways to specify entities\r\nblueprint.entities.append(\r\n \"decider-combinator\",\r\n id=\"clock\",\r\n tile_position=[0, 3],\r\n direction=Direction.EAST,\r\n control_behavior={\r\n \"decider_conditions\": {\r\n \"first_signal\": \"signal-red\",\r\n \"comparator\": \"<=\",\r\n \"constant\": 60,\r\n \"output_signal\": \"signal-red\",\r\n \"copy_count_from_input\": True,\r\n }\r\n },\r\n)\r\n\r\n# Use IDs to keep track of complex blueprints\r\nblueprint.entities.append(\"small-lamp\", id=\"blinker\", tile_position=(2, 3))\r\nblinker = blueprint.entities[\"blinker\"]\r\nblinker.set_circuit_condition(\"signal-red\", \"=\", 60)\r\nblinker.use_colors = True\r\n\r\nblueprint.add_circuit_connection(\"green\", \"constant\", \"clock\")\r\nblueprint.add_circuit_connection(\"red\", \"clock\", \"clock\", 1, 2)\r\nblueprint.add_circuit_connection(\"green\", \"clock\", \"blinker\", 2, 1)\r\n\r\n# Factorio API filter capabilities\r\nccs = blueprint.find_entities_filtered(name=\"constant-combinator\")\r\nassert len(ccs) == len(test_string) + 1\r\n\r\nblueprint_book = BlueprintBook()\r\nblueprint_book.blueprints = [blueprint]\r\n\r\nprint(blueprint_book) # Pretty printing using json\r\nprint(blueprint_book.to_string()) # Blueprint string to import into Factorio\r\n```\r\n--------------------------------------------------------------------------------\r\n\r\n## Overview\r\nSimply put, Draftsman attempts to provide a universal solution to the task of creating and manipulating Factorio blueprint strings, which are compressed text strings used by players to share their constructions easily with others.\r\nDraftsman allows users to programmatically create these strings via script, allowing for designs that would normally be too tedious to design by hand, such as combinator computer compilers, image-to-blueprint converters, pumpjack placers, as well as any other complex or repetitive design better suited for a computer's touch.\r\n\r\nFor a user-friendly timeline of how this project came about, as well as some pretty illustrations of it's capabilities, [you can read an article](https://alt-f4.blog/ALTF4-61/) written for the amazing fan-run community spotlight website [Alt-F4](https://alt-f4.blog/).\r\n\r\nFor more information on what exactly Draftsman is and does, as well as its intended purpose and philosophy, [you can read the documentation here](https://factorio-draftsman.readthedocs.io/en/latest/index.html).\r\n\r\nFor more examples on what exactly you can do with Draftsman, take a look at the [examples folder](https://github.com/redruin1/factorio-draftsman/tree/main/examples).\r\n\r\n### Features\r\n* Compatible with the latest versions of Python 2 and 3\r\n* Compatible with the latest versions of Factorio (1.0+)\r\n* Compatible with Factorio mods(!)\r\n* Well documented\r\n* Intuitive and flexible API\r\n* Useful constructs for ease-of-use:\r\n * Give entities unique string IDs to make association between entities easier\r\n * Filter entities from blueprints by type, region and other parameters [just like Factorio's own API](https://lua-api.factorio.com/latest/LuaSurface.html#LuaSurface.find_entities_filtered)\r\n * Entities are categorized and organized within `draftsman.data` for easy and flexible iteration\r\n * Group entities together and manipulate them all as one unit\r\n* Verbose Errors and Warnings (\"Factorio-safety\" and \"Factorio-correctness\")\r\n* Expansive and rigorous test suite\r\n\r\n--------------------------------------------------------------------------------\r\n## Usage\r\n\r\n### Installation:\r\n```\r\npip install factorio-draftsman\r\n```\r\n\r\nThis will install the latest version of Draftsman with a set of pre-generated data from the latest version of vanilla Factorio.\r\n\r\nIf you want to have the same data validation that Draftsman provides for vanilla data with mods as well, you can re-generate this data with the command line tool `draftsman-update`, which is described in detail [here](TODO).\r\n\r\n### Testing with [unittest](https://docs.python.org/3/library/unittest.html):\r\n```\r\npython -m unittest discover\r\n```\r\n\r\nNote that testing currently is only *guaranteed* to work with a vanilla install.\r\n\r\n### Coverage with [coverage](https://coverage.readthedocs.io/en/6.3.2/):\r\n```\r\ncoverage run\r\n```\r\n--------------------------------------------------------------------------------\r\n### How to use mods with Draftsman:\r\n\r\nDetermine where your mods are installed; you can either copy the mods you want into the local `site-packages/draftsman/factorio-mods` folder where Draftsman is installed (which it looks in by default), or you can specify an external path with the `-p` or `--path` argument which can point to your Factorio mods folder or anywhere else convenient.\r\nThen, simply call `draftsman-update` or `draftsman-update --path some/path/to/mods` to automatically update the data associated with that Draftsman installation.\r\n\r\n`draftsman-update` can also be called in script via the method `draftsman.env:update()` if you want to change the mod list on the fly:\r\n```python\r\n# my_update_script.py\r\nfrom draftsman.env import update\r\nupdate(verbose=True, path=\"some/path\") # equivalent to 'draftsman-update -v -p some/path'\r\n```\r\n\r\nBoth `mod-info.json` and `mod-settings.dat` are recognized by `draftsman-update`, so you can also just change the settings in either of those and the loading process will adjust as well.\r\n\r\n## TODO\r\n* Add warnings for placement constraints on rails, rail signals and train stops\r\n* Add constraints on `UpgradePlanner` and `DeconstructionPlanner`\r\n* `Blueprint.schedules` convenience functions\r\n* More doctests\r\n* Add documentation on report and contributing\r\n* Write test cases for `dump_format`\r\n* Add plaintext representations of Entity JSON objects for all entities in addition to blueprintables\r\n* Update modding documentation guide to reflect 2.0 changes\r\n* Reevaluate the diamond diagrams for inherited `Entity` subclass\r\n* Figure out exactly what determines if an `Entity` is flip-able or not\r\n* Maybe add interface so that mods can include files that can be loaded with Draftsman? (this would be neat)\r\n* Split documentation from docstrings so that each function has a more readable example\r\n* RailPlanner (specify rail paths via turtle-like commands)\r\n* Custom `data.raw` extraction and formatting?\r\n* Maybe integrate defaults for more succinct blueprint strings?\r\n* Unify entity validation into one monolithic thing\r\n* Investigate more performant alternatives to `schema` (validir? requires cython, currently we're pure python)\r\n* Look into Lua (or other language) bindings via backport to C/Cython\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A complete, well-tested, and up-to-date module to manipulate Factorio blueprint strings. Compatible with mods.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/redruin1/factorio-draftsman"
},
"split_keywords": [
"factorio",
"blueprint",
"string"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "453351c627d257074579aab9897c0d52ccbefbda23f88ab0eff5c3d584a5b4e1",
"md5": "8ccc384cc672891b71f2a26efffce032",
"sha256": "e413bc78bcd7c087afcee496e611735336e49bac3de9b75d20d7b2359625778d"
},
"downloads": -1,
"filename": "factorio_draftsman-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8ccc384cc672891b71f2a26efffce032",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 1862348,
"upload_time": "2023-09-19T12:19:31",
"upload_time_iso_8601": "2023-09-19T12:19:31.406704Z",
"url": "https://files.pythonhosted.org/packages/45/33/51c627d257074579aab9897c0d52ccbefbda23f88ab0eff5c3d584a5b4e1/factorio_draftsman-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "967b10bc9d44a0f03e3cf9d7bcc5095dbb480ba7a4eecdd9074aade34c180c20",
"md5": "8b36cad0a50820c3754071ea405b0f1a",
"sha256": "6ade993d9f34ea36db22f45dd4ebbc24acd717bbf2599cba303cd7f591948e1f"
},
"downloads": -1,
"filename": "factorio-draftsman-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8b36cad0a50820c3754071ea405b0f1a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 3258354,
"upload_time": "2023-09-19T12:19:35",
"upload_time_iso_8601": "2023-09-19T12:19:35.110081Z",
"url": "https://files.pythonhosted.org/packages/96/7b/10bc9d44a0f03e3cf9d7bcc5095dbb480ba7a4eecdd9074aade34c180c20/factorio-draftsman-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-19 12:19:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "redruin1",
"github_project": "factorio-draftsman",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "factorio-draftsman"
}
JSON
