Modding:Lua/Hooks/Object
Description
These object hooks are stubs for global functions that object scripts can define, which will be called by C++. Documentation for it was removed from the assets, but an old and outdated (2015) version can be found here: https://pastebin.com/8kWFKrnf
Hooks
init()
Called immediately after the object is added to the world, and any time the world (or world chunk) containing the object is loaded. Note that variables stored under self are initialized each time init is called, whereas variables stored under storage are persisted with the object and should not be reinitialized on each call to init.
die(smash)
Called when the object is about to be removed from the world. Die indicates that the object is being removed from persistent storage, and as such, any values in the object's storage will be deleted. If the object was a container, its contents will be dropped as items into the world. In most cases, an object will also drop itself as an item into the world, unless the object is programmed not to do so, or the optional smash argument is true.
uninit()
Called immediately after die when the object is removed from the world, or any time the world (or world chunk) containing the object is unloaded. Note that when a world (or world chunk) is unloaded, die is not called, but uninit is. An object's persistent storage will not be affected when uninit is called due to a world (or world chunk) unloading, because the object is considered to still exist, it simply is not active in memory.
update(dt)
The update loop handler. Called once every scriptDelta (defined in the .object file) ticks. The dt argument indicates the number of seconds since the last invocation.
containerCallback()
Called when the container contents have been changed or interacted with in a GUI Pane.
To have the callback use a different name, add the parameter "containerCallback" : "[function name]" to your object's config file.
onInteraction(args)
Called when the object is interacted with.
'args' - Map of interaction event arguments:
{
sourceId = <Entity id of the entity interacting with this object>
sourcePosition = <The {x,y} position of the interacting entity>
}
Returns:
nil (no interaction response)
or a table -- see sbvnobject and challengedoor examples in
-- the link for code examples below.
{
<string "interactAction", --see above
<map {<interactData>}>
}
If interactData is malformed in the returned value, the object will not be interactable in game, even with object.setInteractive(true). The same applies if onInteracion() throws a lua exception at runtime.
Objects that only need to rely on a GUI Pane doesn't need to specify a "scripts" variable in their .object file, just provide values for "interactAction" and "interactData"/"uiConfig".
Available interaction responses ("interactActions") are:
"OpenCraftingInterface" --used 36 times in vanilla
"OpenTeleportDialog" --used 29 times in vanilla
"ScriptPane" - For widget-based panes --used 26 times in vanilla
"OpenMerchantInterface" --used 14 times in vanilla
"ShowPopup" --used 6 times in vanilla
"OpenCockpitInterface" --not used in vanilla
"SitDown" --not used in vanilla
"OpenCookingInterface" --not used in vanilla
"OpenTechInterface" --not used in vanilla
"Teleport" --not used in vanilla
"OpenSongbookInterface" --not used in vanilla
"OpenNpcCraftingInterface" --not used in vanilla
"OpenTech3DPrinterDialog" --not used in vanilla
"ScriptConsole" - For ScriptCanvases --not used in vanilla
See Modding:Lua/onInteraction for some code examples.
onInputNodeChange(args)
Called when the level of an inbound connected node changes
'args' - Map of:
{
node = <(int) index of the node that is changing>
level = <new level of the node>
}
onNodeConnectionChange(args)
Called when a node is connected or disconnected
onNpcPlay(npcId)
Called when the object is interacted with, by an NPC.
