Table of Contents

Interface IWorldManagerAPI

Namespace
Vintagestory.API.Server
Assembly
VintagestoryAPI.dll

Methods to modify the game world

public interface IWorldManagerAPI
Extension Methods

Properties

AllLoadedChunks

Returns a (cloned) list of all currently loaded chunks. The key is the 3d index of the chunk, can be turned into an x/y/z coord. Warning: This locks the loaded chunk dictionary during the clone, preventing other threads from updating it. In other words: Using this method often will have a significant performance impact.

Dictionary<long, IServerChunk> AllLoadedChunks { get; }

Property Value

Dictionary<long, IServerChunk>

AllLoadedMapRegions

Returns a (cloned) list of all currently loaded map regions. The key is the 2d index of the map region, can be turned into an x/z coord

Dictionary<long, IMapRegion> AllLoadedMapRegions { get; }

Property Value

Dictionary<long, IMapRegion>

AllLoadedMapchunks

Returns a (cloned) list of all currently loaded map chunks. The key is the 2d index of the map chunk, can be turned into an x/z coord

Dictionary<long, IMapChunk> AllLoadedMapchunks { get; }

Property Value

Dictionary<long, IMapChunk>

AutoGenerateChunks

Completely disables automatic generation of chunks that normally builds up a radius of chunks around the player.

bool AutoGenerateChunks { get; set; }

Property Value

bool

ChunkDeletionsInQueue 

int ChunkDeletionsInQueue { get; }

Property Value

int

ChunkSize

Width/Length/Height in blocks of a chunk on the server

int ChunkSize { get; }

Property Value

int

CurrentGeneratingChunkCount

Amount of chunk columns currently in the generating queue

int CurrentGeneratingChunkCount { get; }

Property Value

int

CurrentPlayStyle

The currently selected playstyle

PlayStyle CurrentPlayStyle { get; }

Property Value

PlayStyle

CurrentWorldName

The current world filename

string CurrentWorldName { get; }

Property Value

string

DefaultSpawnPosition

Retrieves the default spawnpoint (x/y/z coordinate)

int[] DefaultSpawnPosition { get; }

Property Value

int[]

Default spawnpoint

MapSizeX

Width of the current world

int MapSizeX { get; }

Property Value

int

MapSizeY

Height of the current world

int MapSizeY { get; }

Property Value

int

MapSizeZ

Length of the current world

int MapSizeZ { get; }

Property Value

int

RegionSize

Width/Length/Height in blocks of a region on the server

int RegionSize { get; }

Property Value

int

SaveGame

The worlds savegame object. If you change these values they will be permanently stored

ISaveGame SaveGame { get; }

Property Value

ISaveGame

Seed

Get the seed used to generate the current world

int Seed { get; }

Property Value

int

The map seed

SendChunks

Disables sending of normal chunks to all players except for force loaded ones using ForceLoadChunkColumn

bool SendChunks { get; set; }

Property Value

bool

Methods

BroadcastChunk(int, int, int, bool)

Send or Resend a loaded chunk to all connected players. Has no effect when the chunk is not loaded

void BroadcastChunk(int chunkX, int chunkY, int chunkZ, bool onlyIfInRange = true)

Parameters

chunkX int
chunkY int
chunkZ int
onlyIfInRange bool

If true, the chunk will not be sent to connected players that are out of range from that chunk

ChunkIndex3D(int, int, int) 

long ChunkIndex3D(int chunkX, int chunkY, int chunkZ)

Parameters

chunkX int
chunkY int
chunkZ int

Returns

long

CreateChunkColumnForDimension(int, int, int)

Creates columns of empty chunks in the specified dimension

void CreateChunkColumnForDimension(int cx, int cz, int dim)

Parameters

cx int
cz int
dim int

DeleteChunkColumn(int, int)

Deletes a column of chunks at given coordinate from the save file. Also deletes the map chunk at the same coordinate (but keeps the map region). Also unloads the chunk in the same process. Also deletes all entities in this chunk

void DeleteChunkColumn(int chunkX, int chunkZ)

Parameters

chunkX int
chunkZ int

DeleteMapRegion(int, int)

Deletes a map region at given coordinate from the save file

void DeleteMapRegion(int regionX, int regionZ)

Parameters

regionX int
regionZ int

ForceSendChunkColumn(IServerPlayer, int, int, int)

API access to force send a chunk column in any dimension

void ForceSendChunkColumn(IServerPlayer player, int cx, int cz, int dimension)

Parameters

player IServerPlayer
cx int
cz int
dimension int

FullRelight(BlockPos, BlockPos)

Does a complete relighting of the cuboid deliminated by given min/max pos. Completely resends all affected chunk columns to all connected nearby clients.

void FullRelight(BlockPos minPos, BlockPos maxPos)

Parameters

minPos BlockPos
maxPos BlockPos

FullRelight(BlockPos, BlockPos, bool)

Does a complete relighting of the cuboid deliminated by given min/max pos. Can completely resend all affected chunk columns to all connected nearby clients.

void FullRelight(BlockPos minPos, BlockPos maxPos, bool sendToClients)

Parameters

minPos BlockPos
maxPos BlockPos
sendToClients bool

GetBlockAccessor(bool, bool, bool, bool)

Retrieve a customized interface to access blocks in the loaded game world.

[Obsolete("Use api.World.GetBlockAccessor instead")]
IBlockAccessor GetBlockAccessor(bool synchronize, bool relight, bool strict, bool debug = false)

Parameters

synchronize bool

Whether or not a call to Setblock should send the update also to all connected clients

relight bool

Whether or not to relight the chunk after a call to SetBlock and the light values changed by that

strict bool

Log an error message if GetBlock/SetBlock was called to an unloaded chunk

debug bool

If strict, crashes the server if a unloaded chunk was crashed, prints an exception and exports a png image of the current loaded chunks

Returns

IBlockAccessor

GetBlockAccessorBulkUpdate(bool, bool, bool)

Retrieve a customized interface to access blocks in the loaded game world. Does not to relight/sync on a SetBlock until Commit() is called. On commit all touched blocks are relit/synced at once. This method should be used when setting many blocks (e.g. tree generation, explosion, etc.).

[Obsolete("Use api.World.GetBlockAccessorBulkUpdate instead")]
IBulkBlockAccessor GetBlockAccessorBulkUpdate(bool synchronize, bool relight, bool debug = false)

Parameters

synchronize bool

Whether or not a call to Setblock should send the update also to all connected clients

relight bool

Whether or not to relight the chunk after the a call to SetBlock and the light values changed by that

debug bool

Returns

IBulkBlockAccessor

GetBlockAccessorPrefetch(bool, bool)

Same as GetBlockAccessor but you have to call PrefetchBlocks() before using GetBlock(). It pre-loads all blocks in given area resulting in faster GetBlock() access

[Obsolete("Use api.World.GetBlockAccessorPrefetch instead")]
IBlockAccessorPrefetch GetBlockAccessorPrefetch(bool synchronize, bool relight)

Parameters

synchronize bool

Whether or not a call to Setblock should send the update also to all connected clients

relight bool

Whether or not to relight the chunk after a call to SetBlock and the light values changed by that

Returns

IBlockAccessorPrefetch

GetBlockAccessorRevertable(bool, bool, bool)

Same as GetBlockAccessorBulkUpdate, additionally, each Commit() stores the previous state and you can perform undo/redo operations on these.

[Obsolete("Use api.World.GetBlockAccessorRevertable instead")]
IBlockAccessorRevertable GetBlockAccessorRevertable(bool synchronize, bool relight, bool debug = false)

Parameters

synchronize bool

Whether or not a call to Setblock should send the update also to all connected clients

relight bool

Whether or not to relight the chunk after a call to SetBlock and the light values changed by that

debug bool

Returns

IBlockAccessorRevertable

GetBlockId(AssetLocation)

Get the ID of a certain BlockType

int GetBlockId(AssetLocation name)

Parameters

name AssetLocation

Name of the BlockType

Returns

int

ID of the BlockType

GetCachingBlockAccessor(bool, bool)

Same as the normal block accessor but remembers the previous chunk that was accessed. This can give you a 10-50% performance boosts when you scan many blocks in tight loops DONT FORGET: Call .Begin() before getting/setting in a tight loop. Not calling it can cause the game to crash

[Obsolete("Use api.World.GetCachingBlockAccessor instead")]
ICachingBlockAccessor GetCachingBlockAccessor(bool synchronize, bool relight)

Parameters

synchronize bool
relight bool

Returns

ICachingBlockAccessor

GetChunk(int, int, int)

Gets the Server chunk at given coordinate. Returns null if it's not loaded or does not exist yet

IServerChunk GetChunk(int chunkX, int chunkY, int chunkZ)

Parameters

chunkX int
chunkY int
chunkZ int

Returns

IServerChunk

GetChunk(long)

Gets the Server chunk at given coordinate. Returns null if it's not loaded or does not exist yet

IServerChunk GetChunk(long index3d)

Parameters

index3d long

Returns

IServerChunk

GetChunk(BlockPos)

Gets the Server chunk at given coordinate. Returns null if it's not loaded or does not exist yet

IServerChunk GetChunk(BlockPos pos)

Parameters

pos BlockPos

Returns

IServerChunk

GetMapChunk(int, int)

Gets the Server map chunk at given coordinate. Returns null if it's not loaded or does not exist yet

IServerMapChunk GetMapChunk(int chunkX, int chunkZ)

Parameters

chunkX int
chunkZ int

Returns

IServerMapChunk

GetMapChunk(long)

Gets the Server map chunk at given coordinate index. Returns null if it's not loaded or does not exist yet

IMapChunk GetMapChunk(long index2d)

Parameters

index2d long

Returns

IMapChunk

GetMapRegion(int, int)

Gets the Server map region at given coordinate. Returns null if it's not loaded or does not exist yet

IMapRegion GetMapRegion(int regionX, int regionZ)

Parameters

regionX int
regionZ int

Returns

IMapRegion

GetMapRegion(long)

Gets the Server map region at given coordinate. Returns null if it's not loaded or does not exist yet

IMapRegion GetMapRegion(long index2d)

Parameters

index2d long

Returns

IMapRegion

GetNextUniqueId()

Returns a number that is guaranteed to be unique for the current world every time it is called. Curently use for entity herding behavior.

long GetNextUniqueId()

Returns

long

GetSurfacePosY(int, int)

Finds the first y position that is solid ground to stand on. Returns null if the chunk is not loaded.

int? GetSurfacePosY(int posX, int posZ)

Parameters

posX int
posZ int

Returns

int?

HasChunk(int, int, int, IServerPlayer)

Returns true if the server sent chunk at given coords to player and has it not unloaded yet

bool HasChunk(int chunkX, int chunkY, int chunkZ, IServerPlayer player)

Parameters

chunkX int
chunkY int
chunkZ int
player IServerPlayer

Returns

bool

LoadChunkColumn(int, int, bool)

Asynchronly normal priority load a chunk column at given coordinate. No effect when already loaded.

void LoadChunkColumn(int chunkX, int chunkZ, bool keepLoaded = false)

Parameters

chunkX int
chunkZ int
keepLoaded bool

If true, the chunk will never get unloaded unless UnloadChunkColumn() is called

LoadChunkColumnFast(int, int, int, int, ChunkLoadOptions)

Asynchronly high priority load an area of chunk columns at given coordinates. Make sure that X1<=X2 and Z1<=Z2

[Obsolete("Use LoadChunkColumnPriority()")]
void LoadChunkColumnFast(int chunkX1, int chunkZ1, int chunkX2, int chunkZ2, ChunkLoadOptions options = null)

Parameters

chunkX1 int
chunkZ1 int
chunkX2 int
chunkZ2 int
options ChunkLoadOptions

Additional loading options

LoadChunkColumnFast(int, int, ChunkLoadOptions)

Asynchronly high priority load a chunk column at given coordinate.

[Obsolete("Use LoadChunkColumnPriority()")]
void LoadChunkColumnFast(int chunkX, int chunkZ, ChunkLoadOptions options = null)

Parameters

chunkX int
chunkZ int
options ChunkLoadOptions

Additional loading options

LoadChunkColumnForDimension(int, int, int)

Loads chunk columns for the specified dimension

void LoadChunkColumnForDimension(int cx, int cz, int dim)

Parameters

cx int
cz int
dim int

LoadChunkColumnPriority(int, int, int, int, ChunkLoadOptions)

Asynchronly high priority load an area of chunk columns at given coordinates. Make sure that X1<=X2 and Z1<=Z2

void LoadChunkColumnPriority(int chunkX1, int chunkZ1, int chunkX2, int chunkZ2, ChunkLoadOptions options = null)

Parameters

chunkX1 int
chunkZ1 int
chunkX2 int
chunkZ2 int
options ChunkLoadOptions

Additional loading options

LoadChunkColumnPriority(int, int, ChunkLoadOptions)

Asynchronly high priority load a chunk column at given coordinate.

void LoadChunkColumnPriority(int chunkX, int chunkZ, ChunkLoadOptions options = null)

Parameters

chunkX int
chunkZ int
options ChunkLoadOptions

Additional loading options

MapChunkIndex2D(int, int) 

long MapChunkIndex2D(int chunkX, int chunkZ)

Parameters

chunkX int
chunkZ int

Returns

long

MapChunkPosFromChunkIndex2D(long) 

Vec2i MapChunkPosFromChunkIndex2D(long index2d)

Parameters

index2d long

Returns

Vec2i

MapRegionIndex2D(int, int) 

long MapRegionIndex2D(int regionX, int regionZ)

Parameters

regionX int
regionZ int

Returns

long

MapRegionIndex2DByBlockPos(int, int) 

long MapRegionIndex2DByBlockPos(int posX, int posZ)

Parameters

posX int
posZ int

Returns

long

MapRegionPosFromIndex2D(long) 

Vec3i MapRegionPosFromIndex2D(long index2d)

Parameters

index2d long

Returns

Vec3i

PeekChunkColumn(int, int, ChunkPeekOptions)

Generates chunk at given coordinate, completely bypassing any existing world data and caching methods, in other words generates, a chunk from scratch without keeping it in the list of loaded chunks

void PeekChunkColumn(int chunkX, int chunkZ, ChunkPeekOptions options)

Parameters

chunkX int
chunkZ int
options ChunkPeekOptions

ResendMapChunk(int, int, bool)

Send or resent a loaded map chunk to all connected players. Has no effect when the map chunk is not loaded

void ResendMapChunk(int chunkX, int chunkZ, bool onlyIfInRange)

Parameters

chunkX int
chunkZ int
onlyIfInRange bool

SendChunk(int, int, int, IServerPlayer, bool)

Send or Resend a loaded chunk to a connected player. Has no effect when the chunk is not loaded

void SendChunk(int chunkX, int chunkY, int chunkZ, IServerPlayer player, bool onlyIfInRange = true)

Parameters

chunkX int
chunkY int
chunkZ int
player IServerPlayer
onlyIfInRange bool

If true, the chunk will not be sent to connected players that are out of range from that chunk

SetBlockLightLevels(float[])

Allows setting a 32 float array that defines the brightness of each block light level. Has to be set before any players join or any chunks are generated.

void SetBlockLightLevels(float[] lightLevels)

Parameters

lightLevels float[]

SetDefaultSpawnPosition(int, int, int)

Permanently sets the default spawnpoint

void SetDefaultSpawnPosition(int x, int y, int z)

Parameters

x int

X coordinate of new spawnpoint

y int

Y coordinate of new spawnpoint

z int

Z coordinate of new spawnpoint

SetSeaLevel(int)

Sets the default sea level for the world to be generated. Currently used by the client to calculate the correct temperature/rainfall values for climate tinting.

void SetSeaLevel(int sealevel)

Parameters

sealevel int

SetSunBrightness(int)

Sets the default light range of sunlight. Default is 24. Has to be set before any players join or any chunks are generated.

void SetSunBrightness(int lightlevel)

Parameters

lightlevel int

SetSunLightLevels(float[])

Allows setting a 32 float array that defines the brightness of each sun light level. Has to be set before any players join or any chunks are generated.

void SetSunLightLevels(float[] lightLevels)

Parameters

lightLevels float[]

SunFloodChunkColumnForWorldGen(IWorldChunk[], int, int)

Floods the chunk column with sunlight. Only works on full chunk columns.

void SunFloodChunkColumnForWorldGen(IWorldChunk[] chunks, int chunkX, int chunkZ)

Parameters

chunks IWorldChunk[]
chunkX int
chunkZ int

SunFloodChunkColumnNeighboursForWorldGen(IWorldChunk[], int, int)

Spreads the chunk columns light into neighbour chunks and vice versa. Only works on full chunk columns.

void SunFloodChunkColumnNeighboursForWorldGen(IWorldChunk[] chunks, int chunkX, int chunkZ)

Parameters

chunks IWorldChunk[]
chunkX int
chunkZ int

TestChunkExists(int, int, int, Action<bool>)

Asynchrounly checks if this chunk is currently loaded or in the savegame database. Calls the callback method with true or false once done looking up. Does not load the actual chunk data.

void TestChunkExists(int chunkX, int chunkY, int chunkZ, Action<bool> onTested)

Parameters

chunkX int
chunkY int
chunkZ int
onTested Action<bool>

TestMapChunkExists(int, int, Action<bool>)

Asynchrounly checks if this map chunk is currently loaded or in the savegame database. Calls the callback method with true or false once done looking up. Does not load the actual map chunk data.

void TestMapChunkExists(int chunkX, int chunkZ, Action<bool> onTested)

Parameters

chunkX int
chunkZ int
onTested Action<bool>

TestMapRegionExists(int, int, Action<bool>)

Asynchrounly checks if this mapregion is currently loaded or in the savegame database. Calls the callback method with true or false once done looking up. Does not load the actual map region data.

void TestMapRegionExists(int regionX, int regionZ, Action<bool> onTested)

Parameters

regionX int
regionZ int
onTested Action<bool>

UnloadChunkColumn(int, int)

Unloads a column of chunks at given coordinate independent of any nearby players and sends an appropriate unload packet to the player

void UnloadChunkColumn(int chunkX, int chunkZ)

Parameters

chunkX int
chunkZ int