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:

TypeNameDescription
WorldworldThe World game object belonging to this class instance.
NetworknetworkA Network object that can be used to send messages between client and server.
Storagestorage(Server side only.) A Storage object that can be used to store data for the next time loading this object after being unloaded.
anydataParameters from sm.world.createWorld.

Constants:

Common callbacks:

Callbacks:


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)


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:

TypeNameDescription
tableselfThe 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:

TypeNameDescription
tableselfThe class instance.

server_onDestroy(self) serverEventCallback

Called when the scripted object is destroyed.

Parameters:

TypeNameDescription
tableselfThe class instance.

client_onDestroy(self) clientEventCallback

Called when the scripted object is destroyed.

Parameters:

TypeNameDescription
tableselfThe 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:

TypeNameDescription
tableselfThe 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:

TypeNameDescription
tableselfThe 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:

TypeNameDescription
tableselfThe class instance.
numbertimeStepThe 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:

TypeNameDescription
tableselfThe class instance.
numbertimeStepThe 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:

TypeNameDescription
tableselfThe class instance.
numberdeltaTimeDelta 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:

TypeNameDescription
tableselfThe class instance.
anydataAny lua object set with Network.setClientData
integerchannelClient 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:

TypeNameDescription
tableselfThe class instance.
integerxCell x position.
integeryCell y position.

server_onCellLoaded(self, x, y) serverEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.
integerxCell x position.
integeryCell y position.

server_onCellUnloaded(self, x, y) serverEventCallback

Called when a world cell is no longer feature complete.

Parameters:

TypeNameDescription
tableselfThe class instance.
integerxCell x position.
integeryCell y position.

client_onCellLoaded(self, x, y) clientEventCallback

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

Parameters:

TypeNameDescription
tableselfThe class instance.
integerxCell x position.
integeryCell 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:

TypeNameDescription
tableselfThe class instance.
integerxCell x position.
integeryCell y position.

server_onInteractableCreated(self, interactable) serverEventCallback

Called when an Interactable Shape is built in the world.

Parameters:

TypeNameDescription
tableselfThe class instance.
InteractableinteractableThe Interactable of the built Shape.

server_onInteractableDestroyed(self, interactable) serverEventCallback

Called when an Interactable Shape is removed from the world.

Parameters:

TypeNameDescription
tableselfThe class instance.
InteractableinteractableThe 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:

TypeNameDescription
tableselfThe class instance.
Vec3positionThe position in world space where the projectile hit.
numberairTimeThe time, in seconds, that the projectile spent flying before the hit.
Vec3velocityThe velocity of the projectile at impact.
stringprojectileNameThe name of the projectile. (Legacy, use uuid instead)
Player/Unit/Shape/Harvestable/nilshooterThe shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown.
integerdamageThe damage value of the projectile.
anycustomDataA Lua object that can be defined at shoot time using sm.projectile.customProjectileAttack or an other custom version.
Vec3normalThe normal at the point of impact.
Character/Shape/Harvestable/Lift/niltargetThe hit target. Can be a Character, Shape, Harvestable, Lift or nil if terrain or unknown.
UuiduuidThe uuid of the projectile.

server_onExplosion(self, center, destructionLevel) serverEventCallback

Called when an explosion occurs in this world.

Parameters:

TypeNameDescription
tableselfThe class instance.
Vec3centerThe center of the explosion.
integerdestructionLevelThe 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:

TypeNameDescription
tableselfThe class instance.
Vec3positionThe position in world space where the attack hit.
Player/Unit/nilattackerThe attacker. Can be a Player, Unit or nil if unknown.
Character/Shape/Harvestable/Lift/niltargetThe hit target. Can be a Character, Shape, Harvestable, Lift or nil if terrain or unknown.
integerdamageThe damage value of the melee hit.
numberpowerThe physical impact impact of the hit.
Vec3directionThe direction that the melee attack was made.
Vec3normalThe 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:

TypeNameDescription
tableselfThe class instance.
Vec3positionThe position in world space where projectile was fired from.
Vec3velocityThe fire velocity of the projectile.
stringprojectileNameThe name of the projectile. (Legacy, use uuid instead)
Player/Unit/Shape/Harvestable/nilshooterThe shooter. Can be a Player, Unit, Shape, Harvestable or nil if unknown.
UuiduuidThe uuid of the projectile.

server_onCollision(self, objectA, objectB, position, pointVelocityA, pointVelocityB, normal) serverEventCallback

Called when a collision occurs in this world.

Parameters:

TypeNameDescription
tableselfThe class instance.
Shape/Character/Harvestable/Lift/nilobjectAThe first colliding object. Nil if terrain.
Shape/Character/Harvestable/Lift/nilobjectBThe other colliding object. Nil if terrain.
Vec3positionThe position in world space where the collision occurred.
Vec3pointVelocityAThe velocity that that the first object had at the point of collision.
Vec3pointVelocityBThe velocity that that the other object had at the point of collision.
Vec3normalThe 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:

TypeNameDescription
tableselfThe class instance.
Shape/Character/Harvestable/Lift/nilobjectAOne of the colliding objects. Nil if terrain.
Shape/Character/Harvestable/Lift/nilobjectBThe other colliding object. Nil if terrain.
Vec3positionThe position in world space where the collision occurred.
Vec3pointVelocityAThe velocity that that the first object had at the point of collision.
Vec3pointVelocityBThe velocity that that the other object had at the point of collision.
Vec3normalThe collision normal from objectA to objectB.