Things

Quick Links

Docs
GitHub

Description

Things is a utility mod intended for use by other mod developers. It does not make gameplay changes.

Things provides advanced entity management services to other Factorio mods in the form of a high-level abstraction called a Thing.

Mod authors register custom entities in mod-data to have their lifecycles managed as Things. Once created, Things are manipulated via a documented remote interface, and provide additional custom events for mods to react to.

Here are some things Things can do:

Features

Extended Lifecycle

As opposed to Factorio entities, a Thing retains its identity and data throughout a vastly extended lifecycle:

Things have unique identifiers to help your mod track them, as well as lifecycle events that trigger when these states change. Unlike unit_numbers, Thing IDs persist through the entire lifecycle.
If a Thing is built as a ghost, the eventual revived entity is the same Thing as the ghost.
If a Thing is killed, the ghost left behind is the same Thing.
If a Thing is destroyed as a result of an undo or redo action, undoing or redoing that action later will restore the same Thing that was originally present.
If a Thing is modified in a context where Factorio allows undo, the undo will properly undo the modifications made to the Thing.

Parent-Child Relationships

A Thing may register a series of child Things to be created and managed alongside it.
Children can be configured to compute and maintain their position and orientation relative to their parents, with full support for in-world and in-blueprint rotation and flipping, where applicable.
Children and parents receive special events for each other's lifecycle state, making it easy to guarantee that the children come and go with the parent in a correct manner.
Child/parent relationships are preserved across blueprint and undo operations.

Comprehensive Support for Blueprinting

Things carry arbitrary custom serializable data (a Tags structure) which can be set via API and monitored with change events.
When a Thing is lifted into a blueprint, this data is carried along into the blueprint.
When a blueprint is applied, all of the Things resulting from the blueprint application will have the same data as the corresponding Things inside the blueprint.
This includes all cases involving Things in the blueprint overlapping pre-existing Things in the world.

Entity Graphs

Things may be connected to other Things by directed or undirected graph edges.
Distinct named graphs can co-exist, each having its own set of edges.
Connections are preserved in blueprinting, undo, and overlapping.
Graph edges can store custom edge data (a Tags structure) which is serialized with blueprints.

Synthetic Custom Events

Through metadata, Things can be instructed to fire custom events of your choice allowing you to respond to Thing lifecycle events.

Non-polling implementation

Things operates internally using various event and script triggering schemes, avoiding on_tick.
This means it will not impact performance outside of monitored construction and lifecycle events.
This also means Things (and by extension the Things you make with it) fully works while the game is paused in the editor.

Credits

protocol_1903 and boskid for technical knowledge relating to subtick events.
hgschmie and Telkine2018 for a helpful string hash representation of entities.
TalShar and Tekbox for technical contributions relating to circuit script triggers.
boskid, protocol_1903, and PennyJim for technical knowledge relating to virtual rotation of entities.
Bilka for fixing a Factorio bug that negatively impacted Things.
Kryzeth for being brave enough to use Things while it was still in Alpha.

Thanks also to the following indirect contributors:

justarandomgeek (for FMTK, as well answering a number of my weird questions in modding discord)
thesixthroc (for helping me find and fix bugs in bplib, the intellectual precursor to this library)

Contributing

Please use the GitHub repository for questions, bug reports, or pull requests.