ToolClass

A script class that is instanced for every active Tool in the game.

A tool something that a Player can equip by selecting it in the hotbar. For instance the Sledgehammer.

Fields:

TypeNameDescription
anydataData from the "data" json element.
TooltoolThe Tool game object belonging to this class instance.
NetworknetworkA Network object that can be used to send messages between client and server.
Storagestorage(Server side only.) A Storage object that can be used to store data for the next time loading this object after being unloaded.

Common callbacks:

Callbacks:


server_onCreate(self) serverEventCallback

Called when the scripted object is created. This occurs when a new object is built, spawned, or loaded from the save file.

Parameters:

TypeNameDescription
tableselfThe class instance.

client_onCreate(self) clientEventCallback

Called when the scripted object is created. This occurs when a new object is built, spawned, or loaded from the save file.

Parameters:

TypeNameDescription
tableselfThe class instance.

server_onDestroy(self) serverEventCallback

Called when the scripted object is destroyed.

Parameters:

TypeNameDescription
tableselfThe class instance.

client_onDestroy(self) clientEventCallback

Called when the scripted object is destroyed.

Parameters:

TypeNameDescription
tableselfThe class instance.

server_onRefresh(self) serverEventCallback

Called if the Lua script attached to the object is modified while the game is running.

Note:

This event requires Scrap Mechanic to be running with the '-dev' flag. This will allow scripts to automatically refresh upon changes.

Parameters:

TypeNameDescription
tableselfThe class instance.

client_onRefresh(self) clientEventCallback

Called if the Lua script attached to the object is modified while the game is running.

Note:

This event requires Scrap Mechanic to be running with the '-dev' flag. This will allow scripts to automatically refresh upon changes.

Parameters:

TypeNameDescription
tableselfThe class instance.

server_onFixedUpdate(self, timeStep) serverEventCallback

Called every game tick – 40 ticks a second. If the frame rate is lower than 40 fps, this event may be called twice.

During a fixed update, physics and logic between interactables are updated.

Parameters:

TypeNameDescription
tableselfThe class instance.
numbertimeStepThe time period of a tick. (Is always 0.025, a 1/40th of a second.)

client_onFixedUpdate(self, timeStep) clientEventCallback

Called every game tick – 40 ticks a second. If the frame rate is lower than 40 fps, this event may be called twice.

During a fixed update, physics and logic between interactables are updated.

Parameters:

TypeNameDescription
tableselfThe class instance.
numbertimeStepThe time period of a tick. (Is always 0.025, a 1/40th of a second.)

client_onUpdate(self, deltaTime) clientEventCallback

Called every frame.

During a frame update, graphics, animations and effects are updated.

Warning:

Because of how frequent this event is called, the game's frame rate is greatly affected by the amount of code executed here.

For any non-graphics related code, consider using client_onFixedUpdate instead.

If the event is not in use, consider removing it from the script. (Event callbacks that are not implemented will not be called.)

Parameters:

TypeNameDescription
tableselfThe class instance.
numberdeltaTimeDelta time since the last frame.

client_onClientDataUpdate(self, data, channel) clientEventCallback

Called when the client receives new client data updates from the server set with Network.setClientData.

Data set in this way is persistent and the latest data will automatically be sent to new clients.

The data will arrive after client_onCreate during the same tick.

Channel 1 will be received before channel 2 if both are updated.

Parameters:

TypeNameDescription
tableselfThe class instance.
anydataAny lua object set with Network.setClientData
integerchannelClient data channel, 1 or 2. (default: 1)

client_onEquip(self, animate) clientEventCallback

Called when a Player equips the Tool.

Parameters:

TypeNameDescription
tableselfThe class instance.
booleananimateA boolean indicating whether the event should be animated or not.

client_onUnequip(self, animate) clientEventCallback

Called when a Player unequips the Tool.

Parameters:

TypeNameDescription
tableselfThe class instance.
booleananimateA boolean indicating whether the event should be animated or not.

client_onEquippedUpdate(self, primaryState, secondaryState) clientEventCallback

Called every frame for the currently equipped Tool.

Note:

Swinging the sledgehammer is a typical example where you want to block other primary input.

Force building is an example where the primary input action is not blocked.

Not blocking secondary input allows shape removal while the tool is equipped.

Parameters:

TypeNameDescription
tableselfThe class instance.
integerprimaryStateThe interact state of the primary (left) mouse button. (See sm.tool.interactState)
integersecondaryStateThe interact state of the secondary (right) mouse button. (See sm.tool.interactState)

Returns:

TypeDescription
boolean, booleanThe first boolean indicates if other primary input actions should be blocked. The second if secondary input actions should be blocked. (Defaults to false, false)

client_onToggle(self) clientEventCallback

Called when the Player presses a toggle key with the Tool equipped (default 'Q' and 'Shift' + 'Q).

Parameters:

TypeNameDescription
tableselfThe class instance.

Returns:

TypeDescription
booleanA boolean that indicates if other toggle actions should be blocked (rotating shapes). (Defaults to false)

client_onReload(self) clientEventCallback

Called when the Player presses the 'Reload' key with the Tool equipped (default 'R').

Parameters:

TypeNameDescription
tableselfThe class instance.

Returns:

TypeDescription
booleanA boolean that indicates if other reload actions should be blocked (PlayerClass.client_onReload). (Defaults to false)

client_canEquip(self) clientEventCallback

This event is called to check whether the Tool can be equipped.

Parameters:

TypeNameDescription
tableselfThe class instance.

Returns:

TypeDescription
booleanA boolean that indicates if the Tool can be equipped. (Defaults to true)