World
Associated namespace: sm.world
A userdata object representing a world in the game.
Values:
Functions:
- clearLightColorOverride
- destroy
- getCellBounds
- getDominantMaterialInCapsule
- getDominantMaterialInSphere
- getId
- getVoxelMaterialFromWorldPosition
- getWeightedVoxelDensityInWorldPoint
- getZoneId
- isCellInBounds
- isCellLoadedClient
- isCellLoadedServer
- isIndoor
- isVoxelTerrainPointClear
- loadCell
- loadCellWithHandle
- loadNavMeshWithHandle
- reloadCell
- setLightColorOverride
- setMiningConfig
- setTerrainScriptData
- sphereVoxelDensityAddition
- sphereVoxelDensitySubtraction
- voxelDensityAddition
- voxelDensitySubtraction
- voxelDensitySubtraction
Operations:
| Operation | Return type | Description |
|---|---|---|
| World == World | boolean | Checks 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
destroy(world)
Server only
Destroys the given world.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world that should be removed. |
getCellBounds(world)
Returns the minimum and maximum cell coordinates for the given world.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
Returns:
| Type | Description |
|---|---|
| integer, integer, integer, integer | The minimum and maximum cell coordinates (minX, maxX, minY, maxY). |
getDominantMaterialInCapsule(world, position, radius, height)
Finds the dominant voxel material inside a capsule volume.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world to look in. |
| Vec3 | position | The center position of the capsule. |
| number | radius | The radius of the capsule. |
| number | height | 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, position, radius)
Finds the dominant voxel material inside a sphere volume.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world to look in. |
| Vec3 | position | The center position of the sphere. |
| number | radius | 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)
Returns the id of a world.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
Returns:
| Type | Description |
|---|---|
| integer | The world's id. |
getVoxelMaterialFromWorldPosition(world, worldPosition)
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world to look in. |
| Vec3 | worldPosition | 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, point)
Get weighted voxel density in world point.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world to look in. |
| Vec3 | point | 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, position)
Returns the zone id from a position.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Vec3 | position | The position. |
Returns:
| Type | Description |
|---|---|
| table | The 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| integer | x | The X coordinate of the cell. |
| integer | y | The Y coordinate of the cell. |
Returns:
| Type | Description |
|---|---|
| boolean | True if the cell is within the bounds of the world, false otherwise. |
isCellLoadedClient(world, cellX, cellY)
Client only
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world to look in. |
| integer | cellX | The cell X value. |
| integer | cellY | The cell Y value. |
Returns:
| Type | Description |
|---|---|
| boolean | If the cell is loaded or not. |
isCellLoadedServer(world, cellX, cellY)
Server only
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world to look in. |
| integer | cellX | The cell X value. |
| integer | cellY | The cell Y value. |
Returns:
| Type | Description |
|---|---|
| boolean | If the cell is loaded or not. |
isIndoor(world)
Returns true if the world is an indoor world.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
Returns:
| Type | Description |
|---|---|
| boolean | True if indoor. |
isVoxelTerrainPointClear(world, referencePosition, testPosition)
Tests if a world position is free from voxel terrain coverage.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Vec3 | referencePosition | The reference position (e.g. character position). |
| Vec3 | testPosition | 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. |
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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| integer | x | Cell X position. |
| integer | y | Cell Y Position. |
| Player | player | A player to load for, can be nil. |
| string | callback? | Lua function to call when cell is loaded. Callback parameters are ( world, x, y, player, params ) |
| any | params? | Parameter object passed to the callback. |
| ref | ref? | 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| integer | x | Cell X position. |
| integer | y | Cell Y Position. |
| string | callback? | Lua function to call when cell is loaded. Callback parameters are ( world, x, y, params ) |
| any | params? | Parameter object passed to the callback. |
| ref | ref? | Script ref to callback object. |
Returns:
| Type | Description |
|---|---|
| LoadCellHandle | Handle 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| integer | x | Cell X position. |
| integer | y | Cell Y Position. |
| string | callback? | Lua function to call when cell nav mesh is created. Callback parameters are ( world, x, y, params ) |
| any | params? | Parameter object passed to the callback. |
| ref | ref? | Script ref to callback object. |
Returns:
| Type | Description |
|---|---|
| LoadCellHandle | Handle 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| integer | x | Cell X position. |
| integer | y | Cell Y Position. |
| string | callback? | Lua function to call when cell is reloaded. Callback parameters are ( world, x, y, result ) (Optional) |
| ref | ref? | Script ref to callback object. (Optional) |
| any | params? | Parameter passed to the callback. (Optional) |
setLightColorOverride(world, color)
Server only
Sets the override light color on all light controllers in the world.
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Color | color | The 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| table | config | 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) }. |
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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| any | data | Any 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Vec3 | position | The world position of the sphere. |
| number | radius | The radius of the sphere. |
| integer | material | The material to add [0-7]. |
| Player | player? | The player who constructed. (Optional) |
sphereVoxelDensitySubtraction(world, position, radius, filter?, strength?, callback?, params?)
Server only
Modify destructable terrain with a sphere shape
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Vec3 | position | The world position of the sphere. |
| number | radius | The radius of the sphere. |
| integer | filter? | The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all) |
| number | strength? | The strength of the modification. (Defaults to radius) |
| string | callback? | 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. |
| any | params? | Parameter passed to the callback. (Optional) |
voxelDensityAddition(world, position, surfaceNormal, maxDistance, targetDensity, material, filter?, player?)
Server only
Modify destructable terrain
Parameters:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Vec3 | position | The voxel world position. |
| Vec3 | surfaceNormal | The surface normal. |
| number | maxDistance | The maximum distance from position that can be modified. |
| integer | targetDensity | The target density to add. |
| integer | material | The material to add [0-7]. |
| integer | filter? | The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all) |
| Player | player? | 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Vec3 | position | The world position a of the modification. |
| Vec3 | direction | The world direction of the modification. Non normalized direction that defines the center line of modification. |
| number | radius | The maximum distance from positions in the line defined by position and direction that can be modified. |
| integer | targetDensity | The target density to remove. |
| integer | filter? | The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all) |
| boolean | enableDestructionEffect? | Whether to enable destruction effect. (Defaults to true) |
| string | callback? | 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. |
| any | params? | 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:
| Type | Name | Description |
|---|---|---|
| World | world | The world. |
| Vec3 | position | The world position a of the modification. |
| Vec3 | direction | The world direction of the modification. Non normalized direction that defines the center line of modification. |
| number | radius | The maximum distance from positions in the line defined by position and direction that can be modified. |
| table | targetDensities | A table of target densities to remove per material type {[1] = integer, .., [8] = integer}. |
| integer | filter? | The materials the shape can modify. (See sm.world.voxelFilter). (Defaults to sm.world.voxelFilter.all) |
| boolean | enableDestructionEffect? | Whether to enable destruction effect. (Defaults to true) |
| string | callback? | 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. |
| any | params? | Parameter passed to the callback. (Optional) |