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

Name	Type	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.
`data`	any	Parameters from sm.world.createWorld.

Constants

Name	Type	Description
`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")
`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)
`isStatic`	boolean	Enables or disables static mode. (Defaults to false)
`renderMode`	string	Sets the render mode for this world. (Default "outdoor")
`terrainScript`	string	Sets the script used to generate terrain.
`voxelMaterialSet`	string	Sets the voxel material set used by the voxel terrain. (Defaults to "$SURVIVAL_DATA/Terrain/Materials/voxel_materialset_drill1.voxelmaterialset")
`worldBorder`	boolean	Adds borders to the world to prevent objects falling through the ground. (Defaults to true)

groundMaterialSet

Value type: 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

Value type: boolean

Enables or disables indoor mode. (Defaults to false)

Indoor worlds have only one terrain cell in (0, 0)

isStatic

Value type: boolean

Enables or disables static mode. (Defaults to false)

Static worlds are created at load time and doesn't stream in and out.

renderMode

Value type: string

Sets the render mode for this world. (Default "outdoor")

Possible values: "outdoor", "challenge", "warehouse"

terrainScript

Value type: string

Sets the script used to generate terrain.

Full $-path to the terrain generation script.

voxelMaterialSet

Value type: 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.

Server + Client

onCreate

WorldClass:server_onCreate(  )
WorldClass: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

WorldClass:server_onDestroy(  )
WorldClass:client_onDestroy(  )

Called when the scripted object is destroyed.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onRefresh

WorldClass:server_onRefresh(  )
WorldClass: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

WorldClass:server_onFixedUpdate( timeStep )
WorldClass: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.)

onTerrainCreated

Server

WorldClass:server_onTerrainCreated(  )

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:

Name	Type	Description
`self`	table	The class instance.

Client

WorldClass:client_onTerrainCreated(  )

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:

Name	Type	Description
`self`	table	The class instance.

onTerrainLoaded

Server

WorldClass:server_onTerrainLoaded(  )

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:

Name	Type	Description
`self`	table	The class instance.

Client

WorldClass:client_onTerrainLoaded(  )

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:

Name	Type	Description
`self`	table	The class instance.

onCellLoaded

Server

WorldClass:server_onCellLoaded( x, y )

Called when a world cell is loaded and feature complete, but has been before.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`x`	integer	Cell x position.
`y`	integer	Cell y position.

Client

WorldClass:client_onCellLoaded( x, y )

Called when a world cell is considered feature complete for a client (has nodes).

Parameters:

Name	Type	Description
`self`	table	The class instance.
`x`	integer	Cell x position.
`y`	integer	Cell y position.

onCellUnloaded

Server

WorldClass:server_onCellUnloaded( x, y )

Called when a world cell is no longer feature complete.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`x`	integer	Cell x position.
`y`	integer	Cell y position.

Client

WorldClass:client_onCellUnloaded( x, y )

Called when a world cell is no longer considered feature complete for a client (no longer has nodes).

Parameters:

Name	Type	Description
`self`	table	The class instance.
`x`	integer	Cell x position.
`y`	integer	Cell y position.

onProjectile

Server

WorldClass:server_onProjectile(
    position,
    airTime,
    velocity,
    projectileName,
    shooter,
    damage,
    customData,
    normal,
    target,
    uuid
)

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:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where the projectile hit.
`airTime`	number	The time, in seconds, that the projectile spent flying before the hit.
`velocity`	Vec3	The velocity of the projectile at impact.
`projectileName`	string	The name of the projectile. (Legacy, use uuid instead)
`shooter`	Player/Unit/Shape/Harvestable/nil	The shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown.
`damage`	integer	The damage value of the projectile.
`customData`	any	A Lua object that can be defined at shoot time using sm.projectile.customProjectileAttack or an other custom version.
`normal`	Vec3	The normal at the point of impact.
`target`	Character/Shape/Harvestable/Lift/nil	The hit target. Can be a Character, Shape, Harvestable, Lift or nil if terrain or unknown.
`uuid`	Uuid	The uuid of the projectile.

Client

WorldClass:client_onProjectile(
    position,
    airTime,
    velocity,
    projectileName,
    shooter,
    damage,
    normal,
    target,
    uuid
)

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:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where the projectile hit.
`airTime`	number	The time, in seconds, that the projectile spent flying before the hit.
`velocity`	Vec3	The velocity of the projectile at impact.
`projectileName`	string	The name of the projectile. (Legacy, use uuid instead)
`shooter`	Player/Character/Shape/Harvestable/nil	The shooter. Can be a Player, Character, Shape, Harvestable or nil if unknown.
`damage`	integer	The damage value of the projectile.
`normal`	Vec3	The normal at the point of impact.
`target`	Character/Shape/Harvestable/Lift/nil	The hit target. Can be a Character, Shape, Harvestable, Lift or nil if terrain or unknown.
`uuid`	Uuid	The uuid of the projectile.

onCollision

Server

WorldClass:server_onCollision(
    objectA,
    objectB,
    position,
    pointVelocityA,
    pointVelocityB,
    normal
)

Called when a collision occurs in this world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`objectA`	Shape/Character/Harvestable/Lift/nil	The first colliding object. Nil if terrain.
`objectB`	Shape/Character/Harvestable/Lift/nil	The other colliding object. Nil if terrain.
`position`	Vec3	The position in world space where the collision occurred.
`pointVelocityA`	Vec3	The velocity that that the first object had at the point of collision.
`pointVelocityB`	Vec3	The velocity that that the other object had at the point of collision.
`normal`	Vec3	The collision normal from objectA to objectB.

Client

WorldClass:client_onCollision(
    objectA,
    objectB,
    position,
    pointVelocityA,
    pointVelocityB,
    normal
)

Called when a collision occurs in this world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`objectA`	Shape/Character/Harvestable/Lift/nil	One of the colliding objects. Nil if terrain.
`objectB`	Shape/Character/Harvestable/Lift/nil	The other colliding object. Nil if terrain.
`position`	Vec3	The position in world space where the collision occurred.
`pointVelocityA`	Vec3	The velocity that that the first object had at the point of collision.
`pointVelocityB`	Vec3	The velocity that that the other object had at the point of collision.
`normal`	Vec3	The collision normal from objectA to objectB.

Server-only

onReceiveUpdate

WorldClass: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.

onUnload

WorldClass:server_onUnload(  )

Called when the World is unloaded from the game on shutdown.

Parameters:

Name	Type	Description
`self`	table	The class instance.

onCellCreated

WorldClass:server_onCellCreated( x, y )

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:

Name	Type	Description
`self`	table	The class instance.
`x`	integer	Cell x position.
`y`	integer	Cell y position.

onInteractableCreated

WorldClass:server_onInteractableCreated( interactable )

Called when an Interactable Shape is built in the world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`interactable`	Interactable	The Interactable of the built Shape.

onInteractableDestroyed

WorldClass:server_onInteractableDestroyed( interactable )

Called when an Interactable Shape is removed from the world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`interactable`	Interactable	The Interactable of the removed Shape.

onExplosion

WorldClass:server_onExplosion( center, destructionLevel, damage )

Called when an explosion occurs in this world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`center`	Vec3	The center of the explosion.
`destructionLevel`	integer	The level of destruction done by this explosion. Corresponds to the 'durability' rating of a Shape.
`damage`	integer	The damage value of the explosion.

onMelee

WorldClass:server_onMelee(
    position,
    attacker,
    target,
    damage,
    power,
    direction,
    normal
)

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:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where the attack hit.
`attacker`	Player/Unit/nil	The attacker. Can be a Player, Unit or nil if unknown.
`target`	Character/Shape/Harvestable/Lift/nil	The hit target. Can be a Character, Shape, Harvestable, Lift or nil if terrain or unknown.
`damage`	integer	The damage value of the melee hit.
`power`	number	The physical impact impact of the hit.
`direction`	Vec3	The direction that the melee attack was made.
`normal`	Vec3	The normal at the point of impact.

onProjectileFire

WorldClass:server_onProjectileFire(
    position,
    velocity,
    projectileName,
    shooter,
    uuid
)

Called when a projectile is fired in this world.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`position`	Vec3	The position in world space where projectile was fired from.
`velocity`	Vec3	The fire velocity of the projectile.
`projectileName`	string	The name of the projectile. (Legacy, use uuid instead)
`shooter`	Player/Unit/Shape/Harvestable/nil	The shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown.
`uuid`	Uuid	The uuid of the projectile.

onVoxelDestruction

WorldClass:server_onVoxelDestruction( densityLoss, positions )

Called when a cluster of voxels are destroyed by a player or creation

Parameters:

Name	Type	Description
`self`	table	The class instance.
`densityLoss`	table	A table containing information about density loss for all materials.
`positions`	table	A table containing all positions where voxels were lost for each material.

onVoxelConstruction

WorldClass:server_onVoxelConstruction( densityGain, positions )

Called when a cluster of voxels are added by a player

Parameters:

Name	Type	Description
`self`	table	The class instance.
`densityGain`	table	A table containing information about density gain for all materials.
`positions`	table	A table containing all positions where voxels were added for each material.

onMining

WorldClass:server_onMining( spawns )

Called when the mining manager has filtered a batch of voxel loot candidates.

Parameters:

Name	Type	Description
`self`	table	The class instance.
`spawns`	table	An array of { position = Vec3, spawnId = integer } describing where and what to spawn.

Client-only

onUpdate

WorldClass: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

WorldClass: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

WorldClass:client_onLocalPlayerChangedWorld( world )

Called when the client player changes world.

Parameters:

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