WorldClass
A script class that is instanced for every World in the game.
When entering a warehouse floor, the player is entering a new world.
Can receive events sent with sm.event.sendToWorld.
Fields:
| Type | Name | Description |
|---|---|---|
| World | world | The World 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. |
| any | data | Parameters from sm.world.createWorld. |
Constants:
- cellMaxX
- cellMaxY
- cellMinX
- cellMinY
- enableAssets
- enableClutter
- enableCreations
- enableHarvestables
- enableKinematics
- enableNodes
- enableSurface
- groundMaterialSet
- isIndoor
- isStatic
- renderMode
- terrainScript
- worldBorder
Common callbacks:
- server_onCreate
- client_onCreate
- server_onDestroy
- client_onDestroy
- server_onRefresh
- client_onRefresh
- server_onFixedUpdate
- client_onFixedUpdate
- client_onUpdate
- client_onClientDataUpdate
Callbacks:
- server_onCellCreated
- server_onCellLoaded
- server_onCellUnloaded
- client_onCellLoaded
- client_onCellUnloaded
- server_onInteractableCreated
- server_onInteractableDestroyed
- server_onProjectile
- server_onExplosion
- server_onMelee
- server_onProjectileFire
- server_onCollision
- client_onCollision
cellMaxX integer
Terrain generation maximum cell position in X axis. (Defaults to 0)
cellMaxY integer
Terrain generation maximum cell position in Y axis. (Defaults to 0)
cellMinX integer
Terrain generation minimum cell position in X axis. (Defaults to 0)
cellMinY integer
Terrain generation minimum cell position in Y axis. (Defaults to 0)
enableAssets boolean
Enables or disables terrain assets for this world. (Defaults to true)
enableClutter boolean
Enables or disables terrain clutter for this world. (Defaults to true)
enableCreations boolean
Enables or disables creations for this world. (Defaults to true)
enableHarvestables boolean
Enables or disables terrain harvestables for this world. (Defaults to true)
enableKinematics boolean
Enables or disables terrain kinematics for this world. (Defaults to true)
enableNodes boolean
Enables or disables nodes for this world. (Defaults to true)
enableSurface boolean
Enables or disables terrain surface for this world. (Defaults to true)
groundMaterialSet string
Sets the ground material set used by the terrain. (Defaults to "$GAME_DATA/Terrain/Materials/gnd_standard_materialset.json")
Full $-path to the material set.
isIndoor boolean
Enables or disables indoor mode. (Defaults to false)
Indoor worlds have only one terrain cell in (0, 0)
isStatic boolean
Enables or disables static mode. (Defaults to false)
Static worlds are created at load time and doesn't stream in and out.
renderMode string
Sets the render mode for this world. (Default "outdoor")
Possible values: "outdoor", "challenge", "warehouse"
terrainScript string
Sets the script used to generate terrain.
Full $-path to the terrain generation script.
worldBorder boolean
Adds borders to the world to prevent objects falling through the ground. (Defaults to true)
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) |
server_onCellCreated(self, x, y) serverEventCallback
Called when a world cell is loaded and feature complete for the first time.
Note:
Interactables created by terrain scripts should be processed here using sm.cell.getInteractablesByTag and sm.cell.getInteractablesByUuid.
They are only accessable for 1 tick after being created.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| integer | x | Cell x position. |
| integer | y | Cell y position. |
server_onCellLoaded(self, x, y) serverEventCallback
Called when a world cell is loaded and feature complete, but has been before.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| integer | x | Cell x position. |
| integer | y | Cell y position. |
server_onCellUnloaded(self, x, y) serverEventCallback
Called when a world cell is no longer feature complete.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| integer | x | Cell x position. |
| integer | y | Cell y position. |
client_onCellLoaded(self, x, y) clientEventCallback
Called when a world cell is considered feature complete for a client (has nodes).
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| integer | x | Cell x position. |
| integer | y | Cell y position. |
client_onCellUnloaded(self, x, y) clientEventCallback
Called when a world cell is no longer considered feature complete for a client (no longer has nodes).
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| integer | x | Cell x position. |
| integer | y | Cell y position. |
server_onInteractableCreated(self, interactable) serverEventCallback
Called when an Interactable Shape is built in the world.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Interactable | interactable | The Interactable of the built Shape. |
server_onInteractableDestroyed(self, interactable) serverEventCallback
Called when an Interactable Shape is removed from the world.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Interactable | interactable | The Interactable of the removed Shape. |
server_onProjectile(self, position, airTime, velocity, projectileName, shooter, damage, customData, normal, target, uuid) serverEventCallback
Called when a projectile hits something in this world.
Note:
If the shooter is destroyed before the projectile hits, the shooter value will be nil.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Vec3 | position | The position in world space where the projectile hit. |
| number | airTime | The time, in seconds, that the projectile spent flying before the hit. |
| Vec3 | velocity | The velocity of the projectile at impact. |
| string | projectileName | The name of the projectile. (Legacy, use uuid instead) |
| Player/Unit/Shape/Harvestable/nil | shooter | The shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown. |
| integer | damage | The damage value of the projectile. |
| any | customData | A Lua object that can be defined at shoot time using sm.projectile.customProjectileAttack or an other custom version. |
| Vec3 | normal | The normal at the point of impact. |
| Character/Shape/Harvestable/Lift/nil | target | The hit target. Can be a Character, Shape, Harvestable, Lift or nil if terrain or unknown. |
| Uuid | uuid | The uuid of the projectile. |
server_onExplosion(self, center, destructionLevel) serverEventCallback
Called when an explosion occurs in this world.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Vec3 | center | The center of the explosion. |
| integer | destructionLevel | The level of destruction done by this explosion. Corresponds to the 'durability' rating of a Shape. |
server_onMelee(self, position, attacker, target, damage, power, direction, normal) serverEventCallback
Called when a melee attack hits something in this world.
Note:
If the attacker is destroyed before the hit lands, the attacker value will be nil.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Vec3 | position | The position in world space where the attack hit. |
| Player/Unit/nil | attacker | The attacker. Can be a Player, Unit or nil if unknown. |
| Character/Shape/Harvestable/Lift/nil | target | The hit target. Can be a Character, Shape, Harvestable, Lift or nil if terrain or unknown. |
| integer | damage | The damage value of the melee hit. |
| number | power | The physical impact impact of the hit. |
| Vec3 | direction | The direction that the melee attack was made. |
| Vec3 | normal | The normal at the point of impact. |
server_onProjectileFire(self, position, velocity, projectileName, shooter, uuid) serverEventCallback
Called when a projectile is fired in this world.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Vec3 | position | The position in world space where projectile was fired from. |
| Vec3 | velocity | The fire velocity of the projectile. |
| string | projectileName | The name of the projectile. (Legacy, use uuid instead) |
| Player/Unit/Shape/Harvestable/nil | shooter | The shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown. |
| Uuid | uuid | The uuid of the projectile. |
server_onCollision(self, objectA, objectB, position, pointVelocityA, pointVelocityB, normal) serverEventCallback
Called when a collision occurs in this world.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Shape/Character/Harvestable/Lift/nil | objectA | The first colliding object. Nil if terrain. |
| Shape/Character/Harvestable/Lift/nil | objectB | The other colliding object. Nil if terrain. |
| Vec3 | position | The position in world space where the collision occurred. |
| Vec3 | pointVelocityA | The velocity that that the first object had at the point of collision. |
| Vec3 | pointVelocityB | The velocity that that the other object had at the point of collision. |
| Vec3 | normal | The collision normal from objectA to objectB. |
client_onCollision(self, objectA, objectB, position, pointVelocityA, pointVelocityB, normal) clientEventCallback
Called when a collision occurs in this world.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| Shape/Character/Harvestable/Lift/nil | objectA | One of the colliding objects. Nil if terrain. |
| Shape/Character/Harvestable/Lift/nil | objectB | The other colliding object. Nil if terrain. |
| Vec3 | position | The position in world space where the collision occurred. |
| Vec3 | pointVelocityA | The velocity that that the first object had at the point of collision. |
| Vec3 | pointVelocityB | The velocity that that the other object had at the point of collision. |
| Vec3 | normal | The collision normal from objectA to objectB. |