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:
| Type | Name | Description |
|---|---|---|
| any | data | 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. |
Common callbacks:
- server_onCreate
- client_onCreate
- server_onDestroy
- client_onDestroy
- server_onRefresh
- client_onRefresh
- server_onFixedUpdate
- client_onFixedUpdate
- client_onUpdate
- client_onClientDataUpdate
Callbacks:
- client_onEquip
- client_onUnequip
- client_onEquippedUpdate
- client_onToggle
- client_onReload
- client_canEquip
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:
| Type | Name | Description |
|---|---|---|
| table | self | The 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
server_onDestroy(self) serverEventCallback
Called when the scripted object is destroyed.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
client_onDestroy(self) clientEventCallback
Called when the scripted object is destroyed.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The 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:
| Type | Name | Description |
|---|---|---|
| table | self | The 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:
| Type | Name | Description |
|---|---|---|
| table | self | The 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| number | timeStep | The 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| number | timeStep | The 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| number | deltaTime | Delta 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| any | data | Any lua object set with Network.setClientData |
| integer | channel | Client data channel, 1 or 2. (default: 1) |
client_onEquip(self, animate) clientEventCallback
Called when a Player equips the Tool.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| boolean | animate | A boolean indicating whether the event should be animated or not. |
client_onUnequip(self, animate) clientEventCallback
Called when a Player unequips the Tool.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| boolean | animate | A 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| integer | primaryState | The interact state of the primary (left) mouse button. (See sm.tool.interactState) |
| integer | secondaryState | 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) |
client_onToggle(self) clientEventCallback
Called when the Player presses a toggle key with the Tool equipped (default 'Q' and 'Shift' + 'Q).
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
Returns:
| Type | Description |
|---|---|
| boolean | A 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
Returns:
| Type | Description |
|---|---|
| boolean | A 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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
Returns:
| Type | Description |
|---|---|
| boolean | A boolean that indicates if the Tool can be equipped. (Defaults to true) |