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

Name	Type	Description
`data`	any	Data from the "data" json element.
`tool`	Tool	The Tool game object belonging to this class instance.
`network`	Network	A Network object that can be used to send messages between client and server.
`storage`	Storage	(Server side only.) A Storage object that can be used to store data for the next time loading this object after being unloaded.

Constants

Name	Type	Description
`equipWhileSeated`	—	Not documented in the source.

Server + Client

onCreate

ToolClass:server_onCreate(  )
ToolClass:client_onCreate(  )

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

Parameters:

Name	Type	Description
`self`	table	The class instance.

onDestroy

ToolClass:server_onDestroy(  )
ToolClass:client_onDestroy(  )

Called when the scripted object is destroyed.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onRefresh

ToolClass:server_onRefresh(  )
ToolClass:client_onRefresh(  )

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:

Name	Type	Description
`self`	table	The class instance.

onFixedUpdate

ToolClass:server_onFixedUpdate( timeStep )
ToolClass:client_onFixedUpdate( timeStep )

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:

Name	Type	Description
`self`	table	The class instance.
`timeStep`	number	The time period of a tick. (Is always 0.025, a 1/40th of a second.)

Server-only

onReceiveUpdate

ToolClass:server_onReceiveUpdate(  )

Called occasionally to indicate that some time has passed.

For performance reasons; it recommended to use this instead of server_onFixedUpdate for updates that do not need to happen frequently.

Use sm.game.getCurrentTick to calculate the time.

Parameters:

Name	Type	Description
`self`	table	The class instance.

Client-only

onUpdate

ToolClass:client_onUpdate( deltaTime )

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:

Name	Type	Description
`self`	table	The class instance.
`deltaTime`	number	Delta time since the last frame.

onClientDataUpdate

ToolClass:client_onClientDataUpdate( data, channel )

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:

Name	Type	Description
`self`	table	The class instance.
`data`	any	Any lua object set with Network.setClientData
`channel`	integer	Client data channel, 1 or 2. (default: 1)

onLocalPlayerChangedWorld

ToolClass:client_onLocalPlayerChangedWorld( world )

Called when the client player changes world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`world`	World	The entered world.

onEquip

ToolClass:client_onEquip( animate )

Called when a Player equips the Tool.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`animate`	boolean	A boolean indicating whether the event should be animated or not.

onUnequip

ToolClass:client_onUnequip( animate )

Called when a Player unequips the Tool.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`animate`	boolean	A boolean indicating whether the event should be animated or not.

onEquippedUpdate

ToolClass:client_onEquippedUpdate( primaryState, secondaryState )

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:

Name	Type	Description
`self`	table	The class instance.
`primaryState`	integer	The interact state of the primary (left) mouse button. (See sm.tool.interactState)
`secondaryState`	integer	The interact state of the secondary (right) mouse button. (See sm.tool.interactState)

Returns:

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

onToggle

ToolClass:client_onToggle(  )

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

Parameters:

Name	Type	Description
`self`	table	The class instance.

Returns:

Type	Description
boolean	A boolean that indicates if other toggle actions should be blocked (rotating shapes). (Defaults to false)

onReload

ToolClass:client_onReload(  )

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

Parameters:

Name	Type	Description
`self`	table	The class instance.

Returns:

Type	Description
boolean	A boolean that indicates if other reload actions should be blocked (PlayerClass.client_onReload). (Defaults to false)

canEquip

ToolClass:client_canEquip(  )

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

Parameters:

Name	Type	Description
`self`	table	The class instance.

Returns:

Type	Description
boolean	A boolean that indicates if the Tool can be equipped. (Defaults to true)