Introduction

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.

ZERO on-tick code

• Things does not make use of any on_tick handlers whatsoever.
• 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.