World

Associated namespace: sm.world

A userdata object representing a world in the game.

Values:

Functions:

Operations:

OperationReturn typeDescription
World == WorldbooleanChecks if two instances of World refer to the same World.

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.


clearLightColorOverride(world)

Server only

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

Parameters:

TypeNameDescription
WorldworldThe world.

destroy(world)

Server only

Destroys the given world.

Parameters:

TypeNameDescription
WorldworldThe world that should be removed.

getCellBounds(world)

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

Parameters:

TypeNameDescription
WorldworldThe world.

Returns:

TypeDescription
integer, integer, integer, integerThe minimum and maximum cell coordinates (minX, maxX, minY, maxY).

getDominantMaterialInCapsule(world, position, radius, height)

Finds the dominant voxel material inside a capsule volume.

Parameters:

TypeNameDescription
WorldworldThe world to look in.
Vec3positionThe center position of the capsule.
numberradiusThe radius of the capsule.
numberheightThe height of the cylindrical part of the capsule (Z-axis aligned, excluding hemispherical caps).

Returns:

TypeDescription
integerThe dominant material index value. (returns nil if no voxel was found)
integerThe highest single-voxel density of the dominant material.
Vec3The weighted average world position of the dominant material (biased toward dense, nearby voxels)

getDominantMaterialInSphere(world, position, radius)

Finds the dominant voxel material inside a sphere volume.

Parameters:

TypeNameDescription
WorldworldThe world to look in.
Vec3positionThe center position of the sphere.
numberradiusThe radius of the sphere.

Returns:

TypeDescription
integerThe dominant material index value. (returns nil if no voxel was found)
integerThe highest single-voxel density of the dominant material.
Vec3The weighted average world position of the dominant material (biased toward dense, nearby voxels).

getId(world)

Returns the id of a world.

Parameters:

TypeNameDescription
WorldworldThe world.

Returns:

TypeDescription
integerThe world's id.

getVoxelMaterialFromWorldPosition(world, worldPosition)

Parameters:

TypeNameDescription
WorldworldThe world to look in.
Vec3worldPositionThe position of the voxel chunk in the world.

Returns:

TypeDescription
integerThe material index value. (returns nil if no voxel was at point)
integerThe density value. (returns nil if no voxel was at point)

getWeightedVoxelDensityInWorldPoint(world, point)

Get weighted voxel density in world point.

Parameters:

TypeNameDescription
WorldworldThe world to look in.
Vec3pointThe world space point to check density in.

Returns:

TypeDescription
numberWeighted density. (returns 0 if world doesn't have voxels)
Vec3Weighted direction of voxel influence.

getZoneId(world, position)

Returns the zone id from a position.

Parameters:

TypeNameDescription
WorldworldThe world.
Vec3positionThe position.

Returns:

TypeDescription
tableThe Zone id. (nil if position is invalid)

isCellInBounds(world, x, y)

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

Parameters:

TypeNameDescription
WorldworldThe world.
integerxThe X coordinate of the cell.
integeryThe Y coordinate of the cell.

Returns:

TypeDescription
booleanTrue if the cell is within the bounds of the world, false otherwise.

isCellLoadedClient(world, cellX, cellY)

Client only

Parameters:

TypeNameDescription
WorldworldThe world to look in.
integercellXThe cell X value.
integercellYThe cell Y value.

Returns:

TypeDescription
booleanIf the cell is loaded or not.

isCellLoadedServer(world, cellX, cellY)

Server only

Parameters:

TypeNameDescription
WorldworldThe world to look in.
integercellXThe cell X value.
integercellYThe cell Y value.

Returns:

TypeDescription
booleanIf the cell is loaded or not.

isIndoor(world)

Returns true if the world is an indoor world.

Parameters:

TypeNameDescription
WorldworldThe world.

Returns:

TypeDescription
booleanTrue if indoor.

isVoxelTerrainPointClear(world, referencePosition, testPosition)

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

Parameters:

TypeNameDescription
WorldworldThe world.
Vec3referencePositionThe reference position (e.g. character position).
Vec3testPositionThe position to test for voxel coverage (e.g. shape center).

Returns:

TypeDescription
boolTrue if the position is clear of voxel terrain, false if covered.

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

Server only

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

Parameters:

TypeNameDescription
WorldworldThe world.
integerxCell X position.
integeryCell Y Position.
PlayerplayerA player to load for, can be nil.
stringcallback?Lua function to call when cell is loaded. Callback parameters are ( world, x, y, player, params )
anyparams?Parameter object passed to the callback.
refref?Script ref to callback object.

loadCellWithHandle(world, 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:

TypeNameDescription
WorldworldThe world.
integerxCell X position.
integeryCell Y Position.
stringcallback?Lua function to call when cell is loaded. Callback parameters are ( world, x, y, params )
anyparams?Parameter object passed to the callback.
refref?Script ref to callback object.

Returns:

TypeDescription
LoadCellHandleHandle to releasing cell.

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

Server only

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:

TypeNameDescription
WorldworldThe world.
integerxCell X position.
integeryCell Y Position.
stringcallback?Lua function to call when cell nav mesh is created. Callback parameters are ( world, x, y, params )
anyparams?Parameter object passed to the callback.
refref?Script ref to callback object.

Returns:

TypeDescription
LoadCellHandleHandle to releasing cell.

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

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

Parameters:

TypeNameDescription
WorldworldThe world.
integerxCell X position.
integeryCell Y Position.
stringcallback?Lua function to call when cell is reloaded. Callback parameters are ( world, x, y, result ) (Optional)
refref?Script ref to callback object. (Optional)
anyparams?Parameter passed to the callback. (Optional)

setLightColorOverride(world, color)

Server only

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

Parameters:

TypeNameDescription
WorldworldThe world.
ColorcolorThe override color.

setMiningConfig(world, config)

Server only

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

world script via the server_onMining callback whenever voxels are removed.

Parameters:

TypeNameDescription
WorldworldThe world.
tableconfigSpawn 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) }.

setTerrainScriptData(world, 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:

TypeNameDescription
WorldworldThe world.
anydataAny data, available to the terrain generation script as parameter 6 in the create callback.

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

Server only

Modify voxel terrain with a sphere shape

Parameters:

TypeNameDescription
WorldworldThe world.
Vec3positionThe world position of the sphere.
numberradiusThe radius of the sphere.
integermaterialThe material to add [0-7].
Playerplayer?The player who constructed. (Optional)

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

Server only

Modify destructable terrain with a sphere shape

Parameters:

TypeNameDescription
WorldworldThe world.
Vec3positionThe world position of the sphere.
numberradiusThe radius of the sphere.
integerfilter?The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
numberstrength?The strength of the modification. (Defaults to radius)
stringcallback?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.
anyparams?Parameter passed to the callback. (Optional)

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

Server only

Modify destructable terrain

Parameters:

TypeNameDescription
WorldworldThe world.
Vec3positionThe voxel world position.
Vec3surfaceNormalThe surface normal.
numbermaxDistanceThe maximum distance from position that can be modified.
integertargetDensityThe target density to add.
integermaterialThe material to add [0-7].
integerfilter?The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
Playerplayer?The player who constructed. (Optional)

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

Server only

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

Parameters:

TypeNameDescription
WorldworldThe world.
Vec3positionThe world position a of the modification.
Vec3directionThe world direction of the modification. Non normalized direction that defines the center line of modification.
numberradiusThe maximum distance from positions in the line defined by position and direction that can be modified.
integertargetDensityThe target density to remove.
integerfilter?The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
booleanenableDestructionEffect?Whether to enable destruction effect. (Defaults to true)
stringcallback?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.
anyparams?Parameter passed to the callback. (Optional)

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

Server only

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

Parameters:

TypeNameDescription
WorldworldThe world.
Vec3positionThe world position a of the modification.
Vec3directionThe world direction of the modification. Non normalized direction that defines the center line of modification.
numberradiusThe maximum distance from positions in the line defined by position and direction that can be modified.
tabletargetDensitiesA table of target densities to remove per material type {[1] = integer, .., [8] = integer}.
integerfilter?The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all)
booleanenableDestructionEffect?Whether to enable destruction effect. (Defaults to true)
stringcallback?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.
anyparams?Parameter passed to the callback. (Optional)