SM Docs
Docs›Game›Userdata›World

World

Availability
Server + Client
Serializable
Yes
Associated namespace
sm.world

A userdata object representing a world in the game.

Values:

  • clientPublicData [ table ]

    • Get: (Client-Only) Returns client public data from a world.
    • Set: (Client-Only) Sets client public data on a World.

  • id [ integer ]

    • Get: Returns the id of a world.

  • indoor [ boolean ]

    • Get: Returns true if the world is an indoor world.

  • publicData [ table ]

    • Get: (Server-Only) Returns public data from a world.
    • Set: (Server-Only) Sets public data on a World.

Operations:

Operation Returns Description
World == World boolean Checks if two instances of World refer to the same World.

Server + Client

getCellBounds

world:getCellBounds(  )

Returns the minimum and maximum cell coordinates for the given world.

Parameters:

Name Type Description
world World The world.

Returns:

Type Description
integer
integer
integer
integer		 The minimum and maximum cell coordinates (minX, maxX, minY, maxY).

getDominantMaterialInCapsule

world:getDominantMaterialInCapsule( position, radius, height )

Finds the dominant voxel material inside a capsule volume.

Parameters:

Name Type Description
world World The world to look in.
position Vec3 The center position of the capsule.
radius number The radius of the capsule.
height number The height of the cylindrical part of the capsule (Z-axis aligned, excluding hemispherical caps).

Returns:

Type Description
integer The dominant material index value. (returns nil if no voxel was found)
integer The highest single-voxel density of the dominant material.
Vec3 The weighted average world position of the dominant material (biased toward dense, nearby voxels)

getDominantMaterialInSphere

world:getDominantMaterialInSphere( position, radius )

Finds the dominant voxel material inside a sphere volume.

Parameters:

Name Type Description
world World The world to look in.
position Vec3 The center position of the sphere.
radius number The radius of the sphere.

Returns:

Type Description
integer The dominant material index value. (returns nil if no voxel was found)
integer The highest single-voxel density of the dominant material.
Vec3 The weighted average world position of the dominant material (biased toward dense, nearby voxels).

getId

world:getId(  )

Returns the id of a world.

Parameters:

Name Type Description
world World The world.

Returns:

Type Description
integer The world's id.

getVoxelMaterialFromWorldPosition

world:getVoxelMaterialFromWorldPosition( worldPosition )

Parameters:

Name Type Description
world World The world to look in.
worldPosition Vec3 The position of the voxel chunk in the world.

Returns:

Type Description
integer The material index value. (returns nil if no voxel was at point)
integer The density value. (returns nil if no voxel was at point)

getWeightedVoxelDensityInWorldPoint

world:getWeightedVoxelDensityInWorldPoint( point )

Get weighted voxel density in world point.

Parameters:

Name Type Description
world World The world to look in.
point Vec3 The world space point to check density in.

Returns:

Type Description
number Weighted density. (returns 0 if world doesn't have voxels)
Vec3 Weighted direction of voxel influence.

getZoneId

world:getZoneId( position )

Returns the zone id from a position.

Parameters:

Name Type Description
world World The world.
position Vec3 The position.

Returns:

Type Description
table The Zone id. (nil if position is invalid)

isCellInBounds

world:isCellInBounds( x, y )

Checks if the given cell coordinates are within the bounds of the world.

Parameters:

Name Type Description
world World The world.
x integer The X coordinate of the cell.
y integer The Y coordinate of the cell.

Returns:

Type Description
boolean True if the cell is within the bounds of the world, false otherwise.

isIndoor

world:isIndoor(  )

Returns true if the world is an indoor world.

Parameters:

Name Type Description
world World The world.

Returns:

Type Description
boolean True if indoor.

isVoxelTerrainPointClear

world:isVoxelTerrainPointClear( referencePosition, testPosition )

Tests if a world position is free from voxel terrain coverage.

Parameters:

Name Type Description
world World The world.
referencePosition Vec3 The reference position (e.g. character position).
testPosition Vec3 The position to test for voxel coverage (e.g. shape center).

Returns:

Type Description
bool True if the position is clear of voxel terrain, false if covered.

loadCellWithHandle

world:loadCellWithHandle( x, y, callback, params, ref )

Load a cell. The cell will stay loaded until the cell is released with LoadCellHandle.release()

or when the LoadCellHandle is garbage collected

Parameters:

Name Type Description
world World The world.
x integer Cell X position.
y integer Cell Y Position.
callback (optional) string Lua function to call when cell is loaded. Callback parameters are ( world, x, y, params )
params (optional) any Parameter object passed to the callback.
ref (optional) ref Script ref to callback object.

Returns:

Type Description
LoadCellHandle Handle to releasing cell.

reloadCell

world:reloadCell( x, y, callback, ref, params )

Reload a cell. Callback result values: 0 means cell isnt active and wont be reloaded, 1 means success

Parameters:

Name Type Description
world World The world.
x integer Cell X position.
y integer Cell Y Position.
callback (optional) string Lua function to call when cell is reloaded. Callback parameters are ( world, x, y, result ) (Optional)
ref (optional) ref Script ref to callback object. (Optional)
params (optional) any Parameter passed to the callback. (Optional)

setTerrainScriptData

world:setTerrainScriptData( data )

Set data to pass on to the terrain generation script. If no data is set the terrain generation script receives the same data as the world script.

Parameters:

Name Type Description
world World The world.
data any Any data, available to the terrain generation script as parameter 6 in the create callback.

Server-only

clearLightColorOverride

world:clearLightColorOverride(  )

Clears the override light color on all light controllers in the world.

Parameters:

Name Type Description
world World The world.

destroy

world:destroy(  )

Destroys the given world.

Parameters:

Name Type Description
world World The world that should be removed.

isCellLoadedServer

world:isCellLoadedServer( cellX, cellY )

Parameters:

Name Type Description
world World The world to look in.
cellX integer The cell X value.
cellY integer The cell Y value.

Returns:

Type Description
boolean If the cell is loaded or not.

loadCell

world:loadCell( x, y, player, callback, params, ref )

Load a cell for player. The cell will stay loaded until the player steps into the cell.

Parameters:

Name Type Description
world World The world.
x integer Cell X position.
y integer Cell Y Position.
player Player A player to load for, can be nil.
callback (optional) string Lua function to call when cell is loaded. Callback parameters are ( world, x, y, player, params )
params (optional) any Parameter object passed to the callback.
ref (optional) ref Script ref to callback object.

loadNavMeshWithHandle

world:loadNavMeshWithHandle( x, y, callback, params, ref )

Load a cell and nav mesh. The cell will stay loaded until the cell is released with LoadCellHandle.release()

or when the LoadCellHandle is garbage collected

Parameters:

Name Type Description
world World The world.
x integer Cell X position.
y integer Cell Y Position.
callback (optional) string Lua function to call when cell nav mesh is created. Callback parameters are ( world, x, y, params )
params (optional) any Parameter object passed to the callback.
ref (optional) ref Script ref to callback object.

Returns:

Type Description
LoadCellHandle Handle to releasing cell.

setLightColorOverride

world:setLightColorOverride( color )

Sets the override light color on all light controllers in the world.

Parameters:

Name Type Description
world World The world.
color Color The override color.

setMiningConfig

world:setMiningConfig( config )

Configures the mining loot population. Matched candidates are sent to the

world script via the server_onMining callback whenever voxels are removed.

Parameters:

Name Type Description
world World The world.
config table Spawn rules keyed by voxel material index (1-8). Each value is an array of rule tables: { sizeX, sizeY, sizeZ, seed, spawnId = integers, tunnelType = string (optional), maxDist = number (optional) }.

sphereVoxelDensityAddition

world:sphereVoxelDensityAddition( position, radius, material, player )

Modify voxel terrain with a sphere shape

Parameters:

Name Type Description
world World The world.
position Vec3 The world position of the sphere.
radius number The radius of the sphere.
material integer The material to add [0-7].
player (optional) Player The player who constructed. (Optional)

sphereVoxelDensitySubtraction

world:sphereVoxelDensitySubtraction(
    position,
    radius,
    filter,
    strength,
    callback,
    params
)

Modify destructable terrain with a sphere shape

Parameters:

Name Type Description
world World The world.
position Vec3 The world position of the sphere.
radius number The radius of the sphere.
filter (optional) integer The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
strength (optional) number The strength of the modification. (Defaults to radius)
callback (optional) string Lua function to call when cell is loaded. Callback parameters are a table of destruction data { remDensities = {integer, ..}, avgPositions = {Vec3, ..} } and (optional) pass-through params passed to this function.
params (optional) any Parameter passed to the callback. (Optional)

voxelDensityAddition

world:voxelDensityAddition(
    position,
    surfaceNormal,
    maxDistance,
    targetDensity,
    material,
    filter,
    player
)

Modify destructable terrain

Parameters:

Name Type Description
world World The world.
position Vec3 The voxel world position.
surfaceNormal Vec3 The surface normal.
maxDistance number The maximum distance from position that can be modified.
targetDensity integer The target density to add.
material integer The material to add [0-7].
filter (optional) integer The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
player (optional) Player The player who constructed. (Optional)

voxelDensitySubtraction - targetDensity

world:voxelDensitySubtraction(
    position,
    direction,
    radius,
    targetDensity,
    filter,
    enableDestructionEffect,
    callback,
    params
)

Modify destructible terrain around a point or line with a radius.

Parameters:

Name Type Description
world World The world.
position Vec3 The world position a of the modification.
direction Vec3 The world direction of the modification. Non normalized direction that defines the center line of modification.
radius number The maximum distance from positions in the line defined by position and direction that can be modified.
targetDensity integer The target density to remove.
filter (optional) integer The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
enableDestructionEffect (optional) boolean Whether to enable destruction effect. (Defaults to true)
callback (optional) string Lua function to call when cell is loaded. Callback parameters are a table of destruction data { remDensities = {integer, ..}, avgPositions = {Vec3, ..} } and (optional) pass-through params passed to this function.
params (optional) any Parameter passed to the callback. (Optional)

voxelDensitySubtraction - targetDensities

world:voxelDensitySubtraction(
    position,
    direction,
    radius,
    targetDensities,
    filter,
    enableDestructionEffect,
    callback,
    params
)

Modify destructible terrain around a point or line with a radius.

Parameters:

Name Type Description
world World The world.
position Vec3 The world position a of the modification.
direction Vec3 The world direction of the modification. Non normalized direction that defines the center line of modification.
radius number The maximum distance from positions in the line defined by position and direction that can be modified.
targetDensities table A table of target densities to remove per material type {[1] = integer, .., [8] = integer}.
filter (optional) integer The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
enableDestructionEffect (optional) boolean Whether to enable destruction effect. (Defaults to true)
callback (optional) string Lua function to call when cell is loaded. Callback parameters are a table of destruction data { remDensities = {integer, ..}, avgPositions = {Vec3, ..} } and (optional) pass-through params passed to this function.
params (optional) any Parameter passed to the callback. (Optional)

Client-only

isCellLoadedClient

world:isCellLoadedClient( cellX, cellY )

Parameters:

Name Type Description
world World The world to look in.
cellX integer The cell X value.
cellY integer The cell Y value.

Returns:

Type Description
boolean If the cell is loaded or not.