Skip to main content

Legacy Remote Interface

Stability - Stable

Experimental versions of Things (prior to 1.0.0) exposed primary API through a remote interface. That remote interface remains available for the use of mods written prior to 1.0 release. While new mods are encouraged to use the Things Client, this interface is marked stable and will continue to be available.

The legacy API is available as a remote interface under the name things. All API functions have a standard call and return signature:

local err, ...results = remote.call("things", "api_method_name", ...args)

The following methods are available:

get​

---Gets basic information about a Thing.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return things.ThingSummary? summary Summary of the Thing, or `nil` if the Thing doesn't exist.
function remote_interface.get(thing_identification) end

get_thing_id​

---Given an entity, gets the associated Thing ID.
---@param entity LuaEntity The entity to look up.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return int64? thing_id The ID of the Thing associated with the entity, or `nil` if none exists.
function remote_interface.get_thing_id(entity)
end

create_thing​

---Create a Thing from an entity.
---@param create_thing_params things.CreateThingParams Parameters controlling how the Thing is created.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return things.ThingShortSummary? thing Summary of the created Thing, or `nil` if there was an error.
function remote_interface.create_thing(create_thing_params) end

force_destroy​

---Forcefully destroy a Thing and its underlying entity, if any.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@param dont_destroy_entity boolean? If true, destroy the Thing but do not destroy the underlying entity.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.force_destroy(
	thing_identification,
	dont_destroy_entity
) end

void​

---Void a Thing, destroying its underlying entity but preserving its data and
---relationships for possible future reuse.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@param skip_destroy boolean? If true, do not destroy the underlying entity. Use with caution.
---@param skip_destroy_children boolean? If true, do not recursively destroy child Thing entities when voiding them. Use with caution.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.void(
	thing_identification,
	skip_destroy,
	skip_destroy_children
)
end

silent_revive​

---Silently revive a ghosted Thing. Returns the same values as `LuaEntity.silent_revive`.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return ItemWithQualityCounts?
---@return LuaEntity?
---@return LuaEntity?
function remote_interface.silent_revive(thing_identification) end

set_tags​

---Sets the tags of a Thing.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@param tags Tags The new tags to set on the Thing.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.set_tags(thing_identification, tags) end

set_tag​

---Set a single tag on a Thing.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@param key string The tag key to set.
---@param value AnyBasic The tag value to set.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.set_tag(thing_identification, key, value)
end

merge_tags​

---Shallow merges new tags into the existing tags of a Thing.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@param tags Tags The tags to merge into the Thing's existing tags.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.merge_tags(thing_identification, tags)
end

get_transient_data​

---Get transient data associated with a Thing. This data is not preserved when
---a Thing is blueprinted or copied.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return Tags|nil transient_data The transient data associated with this Thing, if any.
function remote_interface.get_transient_data(thing_identification) end

set_transient_data​

---Attach transient data to a Thing. This data is not preserved when
---a Thing is blueprinted or copied.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@param key string The key to set in the transient data.
---@param value AnyBasic? The value to set in the transient data.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.set_transient_data(thing_identification, key, value) end

add_child​

---Adds a child Thing to a parent Thing.
---@param parent_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it. The parent Thing.
---@param child_key string The key to assign the child in the parent Thing.
---@param child things.Id | LuaEntity The id of a Thing, or a `LuaEntity`. If the given entity represents a Thing, it will be used. Otherwise, a non-Thing child will be added.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.add_child(
	parent_identification,
	child_key,
	child
) end

remove_parent​

---Removes a child Thing from its current parent.
---@param child_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it. The child Thing.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
function remote_interface.remove_parent(child_identification) end

get_children​

---Gets all children of a parent Thing.
---@param parent_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it. The parent Thing.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return table<string, things.ThingChildInfo>? children Map of child indices to child info. `nil` if there was an error or the Thing doesn't exist. An empty object if the Thing has no children.
function remote_interface.get_children(parent_identification) end

modify_edge​

---Modify a graph edge between two Things.
---@param graph_name string The name of the graph to create the edge in.
---@param operation "create"|"delete"|"toggle"|"set-data" The operation to perform on the edge.
---@param from things.ThingIdentification One side of the edge.
---@param to things.ThingIdentification The other side of the edge.
---@param data Tags? Additional data to set on the edge.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return boolean? toggle_result If `operation` is "toggle", this will be `true` if the edge was created, or `false` if it was deleted. `nil` otherwise.
function remote_interface.modify_edge(graph_name, operation, from, to, data)
end

get_edges​

---Get all graph edges emanating from a Thing in a given graph. For undirected
---graphs, both `out_edges` and `in_edges` are relevant and must be checked.
---@param graph_name string The name of the graph to get edges from.
---@param thing_identification things.ThingIdentification Either the id of a Thing, or the LuaEntity currently representing it.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return {[int]: things.GraphEdge}|nil out_edges
---@return {[int]: things.GraphEdge}|nil in_edges
function remote_interface.get_edges(graph_name, thing_identification)
end

get_edge​

---If a graph edge exists between two Things, get it. In undirected graphs,
---the direction of the edge does not matter.
---@param graph_name string The name of the graph to get the edge from.
---@param from things.ThingIdentification One side of the edge.
---@param to things.ThingIdentification The other side of the edge.
---@return things.Error? error If the operation failed, the reason why. `nil` on success.
---@return things.GraphEdge? edge The edge between the two Things, or `nil` if none exists.
function remote_interface.get_edge(graph_name, from, to)
end