Manages the Factorio environment. Primarily holds draftsman.env.update(), which runs through the Factorio data lifecycle and updates the data in draftsman.data.

class Mod(name, internal_folder, version, archive, location, info, files, data)

Mod object that stores metadata during the load process. Mostly used for structuring the data and determining the load order.

archive_to_string(archive: ZipFile, filepath: str) None

Simply grabs a file with the specified name from an archive and returns it as a string. Ensures that the returned string is stripped of special unicode characters that Lupa dislikes.


Converts a Lua table to a Python dict. Correctly handles nesting, and interprets Lua arrays as lists.

extract_entities(lua, data_location, verbose, sort_tuple)

Extracts the entities to entities.pkl in draftsman.data.

extract_instruments(lua, data_location, verbose)

Extracts the instruments to instruments.pkl in draftsman.data.

extract_items(lua, data_location, verbose, sort_tuple)

Extracts the items to items.pkl in draftsman.data.

extract_mods(loaded_mods, data_location, verbose)

Extract all the mod versions to mods.pkl in draftsman.data.

extract_modules(lua, data_location, verbose, sort_tuple)

Extracts the modules to modules.pkl in draftsman.data.

extract_recipes(lua, data_location, verbose, sort_tuple)

Extracts the recipes to recipes.pkl in draftsman.data.

extract_signals(lua, data_location, verbose, sort_tuple)

Extracts the signals to signals.pkl in draftsman.data.

extract_tiles(lua, data_location, verbose)

Extracts the tiles to tiles.pkl in draftsman.data.


Simply grabs a file’s contents and returns it as a string. Ensures that the returned string is stripped of special unicode characters that Lupa dislikes.


Gets the loaded items, item subgroups, and item groups. Sorts them and returns them. Saves us the trouble of recalcualting this every time we sort something along item order, which we commonly do.


Reads mod_settings.dat and stores it as an easy-to-read dict. Would be trivial to implement an editor with this function. (Well, assuming you write a function to export back to a .dat file)

get_order(objects_to_sort, sort_objects, sort_subgroups, sort_groups)

Sorts the list of objects according to their Factorio order. Attempts to sort by item order first, and defaults to entity order if not present.

Item sort order: (https://forums.factorio.com/viewtopic.php?p=23818#p23818)

  1. object groups

  2. object subgroups

  3. object itself

Across the previous categories, each is sorted by:

  1. the item order string (if present)

  2. the item name (lexographic)

load_stage(lua: LuaRuntime, mod_list: list[Mod], mod: Mod, stage: str) None

Load a stage of the Factorio data lifecycle. Sets meta information and loads and executes the file string in the lua context.


draftsman-update console script entry point. Runs update() with command line arguments passed through. Type draftsman-update -h for a list of commands.

python_require(mod: Mod, mod_folder: str, module_name: str, package_path: str) str

Function called from Lua that checks for a file in a zipfile archive, and returns the contents of the file if found.

Used in the modified Lua require() function that handles special cases to model Factorio’s load pattern. This function is called after normalize_module_name, and expects the name to be it’s result.

update(verbose=False, path=None, show_logs=False, no_mods=False, report=None)

Updates the data in the draftsman.data modules.

Emulates the load pattern of Factorio and loads all of its data (hopefully) in the same way. Then that data is extracted into the module, updating it’s contents. Updates and changes made to the factorio-data folder are also reflected in this routine.