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
- defaultVoxelDensity
- defaultVoxelMaterial
- enableAssets
- enableBuildOnAssets
- enableBuildOnBodies
- enableBuildOnLift
- enableBuildOnSurface
- enableClutter
- enableCreations
- enableHarvestables
- enableKinematics
- enableNavMesh
- enableNodes
- enableSurface
- enableVoxelTerrain
- groundMaterialSet
- hLod
- horizonWater
- isIndoor
- isStatic
- renderMode
- terrainScript
- voxelMaterialSet
- worldBorder
Common callbacks:
- server_onCreate
- client_onCreate
- server_onDestroy
- client_onDestroy
- server_onRefresh
- client_onRefresh
- server_onFixedUpdate
- server_onReceiveUpdate
- client_onFixedUpdate
- client_onUpdate
- client_onClientDataUpdate
- client_onLocalPlayerChangedWorld
Callbacks:
- server_onUnload
- server_onTerrainCreated
- server_onTerrainLoaded
- client_onTerrainCreated
- client_onTerrainLoaded
- 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
- client_onProjectile
- server_onVoxelDestruction
- server_onVoxelConstruction
- server_onMining
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)
defaultVoxelDensity integer
Default value when sampling voxel density. (Defaults to 0)
defaultVoxelMaterial integer
Default value when sampling voxel material. (Defaults to 0)
enableAssets boolean
Enables or disables terrain assets for this world. (Defaults to true)
enableBuildOnAssets boolean
Enables or disables the ability to build on terrain assets. (Defaults to true)
enableBuildOnBodies boolean
Enables or disables the ability to build on bodies. (Defaults to true)
enableBuildOnLift boolean
Enables or disables the ability to build on lift. (Defaults to true)
enableBuildOnSurface boolean
Enables or disables the ability to build on terrain surface. (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)
enableNavMesh boolean
Enables or disables navigation mesh generation for better AI path finding. (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)
enableVoxelTerrain boolean
Enables or disables voxel terrain 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.
hLod integer
Enables or disables h lods.
horizonWater integer
Enables or disables automatically placing water effects at the edge of the world.
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.
voxelMaterialSet string
Sets the voxel material set used by the voxel terrain. (Defaults to "$SURVIVAL_DATA/Terrain/Materials/voxel_materialset_drill1.voxelmaterialset")
Full $-path to the material set.
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.) |
server_onReceiveUpdate(self) serverEventCallback
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:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
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_onLocalPlayerChangedWorld(self, world) clientEventCallback
Called when the client player changes world.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| World | world | The entered world. |
server_onUnload(self) serverEventCallback
Called when the World is unloaded from the game on shutdown.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
server_onTerrainCreated(self) serverEventCallback
Called when a world's terrain is created for the first time on the server.
This callback is triggered during the initial generation of the world terrain.
* function World:server_onTerrainCreated() * -- Terrain creation logic here * end
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
server_onTerrainLoaded(self) serverEventCallback
Called when a world's terrain is loaded (not created) on the server.
This is triggered when existing terrain data is loaded into the world.
* function World:server_onTerrainLoaded() * -- Terrain loading logic here * end
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
client_onTerrainCreated(self) clientEventCallback
Called on the client when a world's terrain is created for the first time.
This callback is used for client-side terrain generation tasks.
* function World:client_onTerrainCreated() * -- Client-side terrain creation logic * end
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
client_onTerrainLoaded(self) clientEventCallback
Called on the client when a world's terrain is loaded (not created).
This function is useful for initializing client-side elements based on the loaded terrain.
* function World:client_onTerrainLoaded() * -- Client-side terrain loading logic * end
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
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, damage) 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. |
| integer | damage | The damage value of the explosion. |
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. |
client_onProjectile(self, position, airTime, velocity, projectileName, shooter, damage, normal, target, uuid) clientEventCallback
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/Character/Shape/Harvestable/nil | shooter | The shooter. Can be a Player, Character, Shape, Harvestable or nil if unknown. |
| integer | damage | The damage value of the projectile. |
| 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_onVoxelDestruction(self, densityLoss, positions) serverEventCallback
Called when a cluster of voxels are destroyed by a player or creation
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| table | densityLoss | A table containing information about density loss for all materials. |
| table | positions | A table containing all positions where voxels were lost for each material. |
server_onVoxelConstruction(self, densityGain, positions) serverEventCallback
Called when a cluster of voxels are added by a player
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| table | densityGain | A table containing information about density gain for all materials. |
| table | positions | A table containing all positions where voxels were added for each material. |
server_onMining(self, spawns) serverEventCallback
Called when the mining manager has filtered a batch of voxel loot candidates.
Parameters:
| Type | Name | Description |
|---|---|---|
| table | self | The class instance. |
| table | spawns | An array of { position = Vec3, spawnId = integer } describing where and what to spawn. |