Package: factorio-draftsman
factorio-draftsmanA 'draftsman' is a kind of artist that specializes in creating technical drawings across many engineering disciplines, including architectural, mechanical, and electrical.
Similarly,factorio-draftsmanis a Python module for creating and editing blueprints for the gameFactorio.fromdraftsman.blueprintableimportBlueprint,BlueprintBookfromdraftsman.constantsimportDirectionfromdraftsman.entityimportConstantCombinatorblueprint=Blueprint()blueprint.label="Example"blueprint.description="A blueprint for the readme."blueprint.version=(1,0)# 1.0# Create a alt-mode combinator stringtest_string="testing"fori,cinenumerate(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 lightconstant=ConstantCombinator()constant.tile_position=(-1,3)constant.direction=Direction.EASTconstant.set_signal(0,"signal-red",1)constant.id="constant"blueprint.entities.append(constant)# Flexible ways to specify entitiesblueprint.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 blueprintsblueprint.entities.append("small-lamp",id="blinker",tile_position=(2,3))blinker=blueprint.entities["blinker"]blinker.set_circuit_condition("signal-red","=",60)blinker.use_colors=Trueblueprint.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 capabilitiesccs=blueprint.find_entities_filtered(name="constant-combinator")assertlen(ccs)==len(test_string)+1blueprint_book=BlueprintBook()blueprint_book.blueprints=[blueprint]print(blueprint_book)# Pretty printing using jsonprint(blueprint_book.to_string())# Blueprint string to import into FactorioOverviewSimply 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 articlewritten for the amazing fan-run community spotlight websiteAlt-F4.For more information on what exactly Draftsman is and does, as well as its intended purpose and philosophy,you can read the documentation here.For more examples on what exactly you can do with Draftsman, take a look at theexamples folder.FeaturesCompatible with the latest versions of Python 2 and 3Compatible with the latest versions of Factorio (1.0+)Compatible with Factorio mods(!)Well documentedIntuitive and flexible APIUseful constructs for ease-of-use:Give entities unique string IDs to make association between entities easierFilter entities from blueprints by type, region and other parametersjust like Factorio's own APIEntities are categorized and organized withindraftsman.datafor easy and flexible iterationGroup entities together and manipulate them all as one unitVerbose Errors and Warnings ("Factorio-safety" and "Factorio-correctness")Expansive and rigorous test suiteUsageInstallation:pip install factorio-draftsmanThis 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 tooldraftsman-update, which is described in detailhere.Testing withunittest:python -m unittest discoverNote that testing currently is onlyguaranteedto work with a vanilla install.Coverage withcoverage:coverage runHow to use mods with Draftsman:Determine where your mods are installed; you can either copy the mods you want into the localsite-packages/draftsman/factorio-modsfolder where Draftsman is installed (which it looks in by default), or you can specify an external path with the-por--pathargument which can point to your Factorio mods folder or anywhere else convenient.
Then, simply calldraftsman-updateordraftsman-update --path some/path/to/modsto automatically update the data associated with that Draftsman installation.draftsman-updatecan also be called in script via the methoddraftsman.env:update()if you want to change the mod list on the fly:# my_update_script.pyfromdraftsman.envimportupdateupdate(verbose=True,path="some/path")# equivalent to 'draftsman-update -v -p some/path'Bothmod-info.jsonandmod-settings.datare recognized bydraftsman-update, so you can also just change the settings in either of those and the loading process will adjust as well.TODOAdd warnings for placement constraints on rails, rail signals and train stopsAdd constraints onUpgradePlannerandDeconstructionPlannerBlueprint.schedulesconvenience functionsMore doctestsAdd documentation on report and contributingWrite test cases fordump_formatAdd plaintext representations of Entity JSON objects for all entities in addition to blueprintablesUpdate modding documentation guide to reflect 2.0 changesReevaluate the diamond diagrams for inheritedEntitysubclassFigure out exactly what determines if anEntityis flip-able or notMaybe 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 exampleRailPlanner (specify rail paths via turtle-like commands)Customdata.rawextraction and formatting?Maybe integrate defaults for more succinct blueprint strings?Unify entity validation into one monolithic thingInvestigate more performant alternatives toschema(validir? requires cython, currently we're pure python)Look into Lua (or other language) bindings via backport to C/Cython