Table of Contents

Interface IBlockAccessor

Namespace
Vintagestory.API.Common
Assembly
VintagestoryAPI.dll

Provides read/write access to the blocks of a world

public interface IBlockAccessor

Properties

ChunkSize

Width, Length and Height of a chunk

int ChunkSize { get; }

Property Value

int

MapSize

Size of the world in blocks

Vec3i MapSize { get; }

Property Value

Vec3i

MapSizeX

X Size of the world in blocks

int MapSizeX { get; }

Property Value

int

MapSizeY

Y Size of the world in blocks

int MapSizeY { get; }

Property Value

int

MapSizeZ

Z Size of the world in blocks

int MapSizeZ { get; }

Property Value

int

RegionMapSizeX

int RegionMapSizeX { get; }

Property Value

int

RegionMapSizeY

int RegionMapSizeY { get; }

Property Value

int

RegionMapSizeZ

int RegionMapSizeZ { get; }

Property Value

int

RegionSize

Width and Length of a region in blocks

int RegionSize { get; }

Property Value

int

UpdateSnowAccumMap

Whether to update the snow accum map on a SetBlock()

bool UpdateSnowAccumMap { get; set; }

Property Value

bool

Methods

BreakBlock(BlockPos, IPlayer, float)

Removes the block at given position and calls Block.GetDrops(), Block.OnBreakBlock() and Block.OnNeighbourBlockChange() for all neighbours. Drops the items that are return from Block.GetDrops()

void BreakBlock(BlockPos pos, IPlayer byPlayer, float dropQuantityMultiplier = 1)

Parameters

pos BlockPos
byPlayer IPlayer
dropQuantityMultiplier float

BreakDecor(BlockPos, BlockFacing, int?)

Removes all decors at given position, drops items if set

bool BreakDecor(BlockPos pos, BlockFacing side = null, int? decorIndex = null)

Parameters

pos BlockPos
side BlockFacing

If not null, breaks all the decor on given block face, otherwise the decor blocks on all sides are removed

decorIndex int?

If not null breaks only this part of the decor for give face. You can get this value via ToDecorIndex()

Returns

bool

True if a decor was removed

Commit()

Calling this method has no effect in normal block acessors except for:

  • Bulk update block accessor: Sets all blocks, relight all affected one chunks in one go and send blockupdates to clients in a packed format.
  • World gen block accessor: To Recalculate the heightmap in of all updated blocks in one go
  • Revertable block accessor: Same as bulk update block accessor plus stores a new history state.
List<BlockUpdate> Commit()

Returns

List<BlockUpdate>

List of changed blocks

CreateMiniDimension(Vec3d)

Used by World Edit to create previews, ships etc.

IMiniDimension CreateMiniDimension(Vec3d position)

Parameters

position Vec3d

Returns

IMiniDimension

DamageBlock(BlockPos, BlockFacing, float)

Client Side: Will render the block breaking decal on that block. If the remaining block resistance reaches 0, will call break block Server Side: Broadcasts a package to all nearby clients to update the block damage of this block for rendering the decal (note: there is currently no server side list of current block damages, these are client side only at the moemnt)

void DamageBlock(BlockPos pos, BlockFacing facing, float damage)

Parameters

pos BlockPos
facing BlockFacing
damage float

ExchangeBlock(int, BlockPos)

Set a block at the given position without calling OnBlockRemoved or OnBlockPlaced, which prevents any block entity from being removed or placed. Marks the chunk dirty so that it gets saved to disk during shutdown or next autosave. Should only be used if you want to prevent any block entity deletion at this position.
This also, for example, does not change a block's reinforcement level, useful for openable blocks such as doors, gates etc

void ExchangeBlock(int blockId, BlockPos pos)

Parameters

blockId int
pos BlockPos

GetBlock(int)

Get the Block object of a certain block ID. Returns null when not found.

Block GetBlock(int blockId)

Parameters

blockId int

The block ID to search for

Returns

Block

BlockType object

GetBlock(int, int, int)

Get the block type of the block at the given world coordinate. Will never return null. For air blocks or invalid coordinates you'll get a block instance with block code "air" and id 0 Same as GetBlock(BlockPos, int) with BlockLayersAccess.Default as layer

[Obsolete("Please use BlockPos version instead, for dimension awareness")]
Block GetBlock(int posX, int posY, int posZ)

Parameters

posX int
posY int
posZ int

Returns

Block

GetBlock(int, int, int, int)

Get the block type of the block at the given world coordinate. Will never return null. For airblocks or invalid coordinates you'll get a block instance with block code "air" and id 0
Reads the block from the specified layer(s), see BlockLayersAccess documentation for details.

[Obsolete("Please use BlockPos version instead, for dimension awareness")]
Block GetBlock(int x, int y, int z, int layer)

Parameters

x int

x coordinate

y int

y coordinate

z int

z coordinate

layer int

blocks layer e.g. solid, fluid etc.

Returns

Block

ID of the block at the given position

GetBlock(AssetLocation)

Get the Block object of for given block code. Returns null when not found.

Block GetBlock(AssetLocation code)

Parameters

code AssetLocation

Returns

Block

GetBlock(BlockPos)

Get the block type of the block at the given world coordinate. Will never return null. For air blocks or invalid coordinates you'll get a block instance with block code "air" and id 0 Same as GetBlock(BlockPos, int) with BlockLayersAccess.Default as layer

Block GetBlock(BlockPos pos)

Parameters

pos BlockPos

Returns

Block

GetBlock(BlockPos, int)

Get block type at given world coordinate. Will never return null. For airblocks or invalid coordinates you'll get a block instance with block code "air" and id 0
Reads the block from the specified layer(s), see BlockLayersAccess documentation for details.

Block GetBlock(BlockPos pos, int layer)

Parameters

pos BlockPos
layer int

blocks layer e.g. solid, fluid etc.

Returns

Block

GetBlockEntity(BlockPos)

Retrieve the block entity at given position. Returns null if there is no block entity at this position

BlockEntity GetBlockEntity(BlockPos position)

Parameters

position BlockPos

Returns

BlockEntity

GetBlockEntity<T>(BlockPos)

Retrieve the block entity at given position. Returns null if there is no block entity at this position

T GetBlockEntity<T>(BlockPos position) where T : BlockEntity

Parameters

position BlockPos

Returns

T

Type Parameters

T

GetBlockId(int, int, int)

Get the block id of the block at the given world coordinate

[Obsolete("Please use BlockPos version instead, for dimension awareness")]
int GetBlockId(int posX, int posY, int posZ)

Parameters

posX int
posY int
posZ int

Returns

int

GetBlockId(BlockPos)

Get the block id of the block at the given world coordinate

int GetBlockId(BlockPos pos)

Parameters

pos BlockPos

Returns

int

GetBlockOrNull(int, int, int, int)

Get the block type of the block at the given world coordinate. For invalid or unloaded coordinates this method returns null.

[Obsolete("Please use BlockPos version instead, for dimension awareness")]
Block GetBlockOrNull(int x, int y, int z, int layer = 4)

Parameters

x int

x coordinate

y int

y coordinate

z int

z coordinate

layer int

Block layer

Returns

Block

ID of the block at the given position

GetChunk(int, int, int)

Retrieve chunk at given chunk position (= divide block position by chunk size)
For dimension awareness, chunkY would need to be based on BlockPos.InternalY / chunksize or else explicitly include the dimensionId multiplied by GlobalConstants.DimensionSizeInChunks

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

Parameters

chunkX int
chunkY int
chunkZ int

Returns

IWorldChunk

GetChunk(long)

Retrieve chunk at given chunk position, returns null if chunk is not loaded

IWorldChunk GetChunk(long chunkIndex3D)

Parameters

chunkIndex3D long

Returns

IWorldChunk

GetChunkAtBlockPos(int, int, int)

Retrieve chunk at given block position, returns null if chunk is not loaded

[Obsolete("Please use BlockPos version instead, for dimension awareness")]
IWorldChunk GetChunkAtBlockPos(int posX, int posY, int posZ)

Parameters

posX int
posY int
posZ int

Returns

IWorldChunk

GetChunkAtBlockPos(BlockPos)

Retrieve chunk at given block position, returns null if chunk is not loaded

IWorldChunk GetChunkAtBlockPos(BlockPos pos)

Parameters

pos BlockPos

Returns

IWorldChunk

GetClimateAt(BlockPos, int)

Fast shortcut method for the clound renderer

ClimateCondition GetClimateAt(BlockPos pos, int climate)

Parameters

pos BlockPos
climate int

Returns

ClimateCondition

GetClimateAt(BlockPos, ClimateCondition, EnumGetClimateMode, double)

Returns the position's climate conditions at specified date, making use of previously obtained worldgen climate conditions

ClimateCondition GetClimateAt(BlockPos pos, ClimateCondition baseClimate, EnumGetClimateMode mode, double totalDays)

Parameters

pos BlockPos
baseClimate ClimateCondition
mode EnumGetClimateMode
totalDays double

Returns

ClimateCondition

GetClimateAt(BlockPos, EnumGetClimateMode, double)

Returns the position's current climate conditions

ClimateCondition GetClimateAt(BlockPos pos, EnumGetClimateMode mode = EnumGetClimateMode.NowValues, double totalDays = 0)

Parameters

pos BlockPos
mode EnumGetClimateMode

WorldGenValues = values as determined by the worldgenerator, NowValues = additionally modified to take season, day/night and hemisphere into account

totalDays double

When mode == ForSuppliedDateValues then supply here the date. Not used param otherwise

Returns

ClimateCondition

GetDecor(BlockPos, int)

Retrieves a single decor at given position

Block GetDecor(BlockPos pos, int decorIndex)

Parameters

pos BlockPos
decorIndex int

You can get this value via ToDecorIndex()

Returns

Block

GetDecors(BlockPos)

Get a list of all decors at this position

Block[] GetDecors(BlockPos position)

Parameters

position BlockPos

Returns

Block[]

null if this block has no decors. Otherwise a 6 element long list of decor blocks, any of which may be null if not set

GetDistanceToRainFall(BlockPos, int, int)

Returns a number of how many blocks away there is rain fall. Does a cheap 2D bfs up to 4 blocks away. Returns 99 if none was found within 4 blocks

int GetDistanceToRainFall(BlockPos pos, int horziontalSearchWidth = 4, int verticalSearchWidth = 1)

Parameters

pos BlockPos
horziontalSearchWidth int

Horizontal search distance, 4 default

verticalSearchWidth int

Vertical search distance, 1 default

Returns

int

GetLightLevel(int, int, int, EnumLightLevelType)

Returns the light level (0..32) at given position. If the chunk at that position is not loaded this method will return the default sunlight value
Note this is not currently dimensionally aware

int GetLightLevel(int x, int y, int z, EnumLightLevelType type)

Parameters

x int
y int
z int
type EnumLightLevelType

Returns

int

GetLightLevel(BlockPos, EnumLightLevelType)

Returns the light level (0..32) at given position. If the chunk at that position is not loaded this method will return the default sunlight value

int GetLightLevel(BlockPos pos, EnumLightLevelType type)

Parameters

pos BlockPos
type EnumLightLevelType

Returns

int

GetLightRGBs(int, int, int)

Returns the light values at given position. XYZ component = block light rgb, W component = sun light brightness
Note this is not currently dimensionally aware

Vec4f GetLightRGBs(int posX, int posY, int posZ)

Parameters

posX int
posY int
posZ int

Returns

Vec4f

GetLightRGBs(BlockPos)

Returns the light values at given position. XYZ component = block light rgb, W component = sun light brightness

Vec4f GetLightRGBs(BlockPos pos)

Parameters

pos BlockPos

Returns

Vec4f

GetLightRGBsAsInt(int, int, int)

Returns the light values at given position. bit 0-23: block rgb light, bit 24-31: sun light brightness

int GetLightRGBsAsInt(int posX, int posY, int posZ)

Parameters

posX int
posY int
posZ int

Returns

int

GetMapChunk(int, int)

Returns the map chunk at given chunk position

IMapChunk GetMapChunk(int chunkX, int chunkZ)

Parameters

chunkX int
chunkZ int

Returns

IMapChunk

GetMapChunk(Vec2i)

Returns the map chunk at given chunk position

IMapChunk GetMapChunk(Vec2i chunkPos)

Parameters

chunkPos Vec2i

Returns

IMapChunk

GetMapChunkAtBlockPos(BlockPos)

Returns the map chunk at given block position

IMapChunk GetMapChunkAtBlockPos(BlockPos pos)

Parameters

pos BlockPos

Returns

IMapChunk

GetMapRegion(int, int)

Retrieves a map region at given region position, returns null if region is not loaded

IMapRegion GetMapRegion(int regionX, int regionZ)

Parameters

regionX int
regionZ int

Returns

IMapRegion

GetMostSolidBlock(int, int, int)

Same as GetBlock(int, int, int, int) with BlockLayersAccess.MostSolid as layer

[Obsolete("Please use BlockPos version instead, for dimension awareness")]
Block GetMostSolidBlock(int x, int y, int z)

Parameters

x int
y int
z int

Returns

Block

GetMostSolidBlock(BlockPos)

Same as GetBlock(BlockPos, int) with BlockLayersAccess.MostSolid as layer

Block GetMostSolidBlock(BlockPos pos)

Parameters

pos BlockPos

Returns

Block

GetRainMapHeightAt(int, int)

Returns the topmost non-rain-permeable position at given x/z coordinate. This map is always updated after placing/removing blocks
Note this is meaningless in dimensions other than the normal world

int GetRainMapHeightAt(int posX, int posZ)

Parameters

posX int
posZ int

Returns

int

GetRainMapHeightAt(BlockPos)

Returns the topmost non-rain-permeable position at given x/z coordinate. This map is always updated after placing/removing blocks
Note this is meaningless in dimensions other than the normal world

int GetRainMapHeightAt(BlockPos pos)

Parameters

pos BlockPos

Returns

int

GetTerrainMapheightAt(BlockPos)

Returns the topmost solid surface position at given x/z coordinate as it was during world generation. This map is not updated after placing/removing blocks
Note this is meaningless in dimensions other than the normal world

int GetTerrainMapheightAt(BlockPos pos)

Parameters

pos BlockPos

Returns

int

GetWindSpeedAt(BlockPos)

Retrieves the wind speed for given position

Vec3d GetWindSpeedAt(BlockPos pos)

Parameters

pos BlockPos

Returns

Vec3d

GetWindSpeedAt(Vec3d)

Retrieves the wind speed for given position

Vec3d GetWindSpeedAt(Vec3d pos)

Parameters

pos Vec3d

Returns

Vec3d

IsNotTraversable(double, double, double)

Checks if this position can be traversed by a normal player (returns false for outside map or not yet loaded chunks)

bool IsNotTraversable(double x, double y, double z)

Parameters

x double
y double
z double

Returns

bool

IsNotTraversable(BlockPos)

Checks if this position can be traversed by a normal player (returns false for outside map or not yet loaded chunks)

bool IsNotTraversable(BlockPos pos)

Parameters

pos BlockPos

Returns

bool

IsSideSolid(int, int, int, BlockFacing)

Tests whether a side at the specified position is solid - testing both fluids layer (which could be ice) and solid blocks layer

bool IsSideSolid(int x, int y, int z, BlockFacing facing)

Parameters

x int
y int
z int
facing BlockFacing

Returns

bool

IsValidPos(int, int, int)

Checks if the position is inside the maps boundaries

[Obsolete("Please use BlockPos version instead, for dimension awareness")]
bool IsValidPos(int posX, int posY, int posZ)

Parameters

posX int
posY int
posZ int

Returns

bool

IsValidPos(BlockPos)

Checks if the position is inside the maps boundaries

bool IsValidPos(BlockPos pos)

Parameters

pos BlockPos

Returns

bool

MarkAbsorptionChanged(int, int, BlockPos)

Used by the chisel block when enough chiseled have been removed and the blocks light absorption changes as a result of that

void MarkAbsorptionChanged(int oldAbsorption, int newAbsorption, BlockPos pos)

Parameters

oldAbsorption int
newAbsorption int
pos BlockPos

MarkBlockDirty(BlockPos, Action)

Server Side: Same as MarkBlockDirty()
Client Side: Same as MarkBlockDirty(), but also calls supplied delegate after the chunk has been re-retesselated. This can be used i.e. for block entities to dynamically switch between static models and dynamic models at exactly the right timing

void MarkBlockDirty(BlockPos pos, Action OnRetesselated)

Parameters

pos BlockPos
OnRetesselated Action

MarkBlockDirty(BlockPos, IPlayer)

Server side: Sends that block to the client (via bulk packet). Through that packet the client will do a SetBlock on that position (which triggers a redraw if oldblockid != newblockid).
Client side: Triggers a block changed event and redraws the chunk

void MarkBlockDirty(BlockPos pos, IPlayer skipPlayer = null)

Parameters

pos BlockPos
skipPlayer IPlayer

Server side: Does not send the update to this player, Client Side: No effect

MarkBlockEntityDirty(BlockPos)

Server side call: Resends the block entity data (if present) to all clients. Triggers a block changed event on the client once received , but will not redraw the chunk. Marks also the chunk dirty so that it gets saved to disk during shutdown or next autosave.
Client side call: No effect

void MarkBlockEntityDirty(BlockPos pos)

Parameters

pos BlockPos

MarkBlockModified(BlockPos)

Server side: Triggers a OnNeighbourBlockChange on that position and sends that block to the client (via bulk packet), through that packet the client will do a SetBlock on that position (which triggers a redraw if oldblockid != newblockid).
Client side: Triggers a block changed event and redraws the chunk. Deletes and re-create block entities

void MarkBlockModified(BlockPos pos)

Parameters

pos BlockPos

MarkChunkDecorsModified(BlockPos)

Server: Marks this position as required for resending to the client Client: No effect

void MarkChunkDecorsModified(BlockPos pos)

Parameters

pos BlockPos

RemoveBlockEntity(BlockPos)

Permanently removes any block entity at this postion. Does not remove it's corresponding block, you have to do this yourself. Marks the chunk dirty so that it gets saved to disk during shutdown or next autosave.

void RemoveBlockEntity(BlockPos position)

Parameters

position BlockPos

RemoveBlockLight(byte[], BlockPos)

Call this on OnBlockBroken() when your block entity modifies the blocks light range. That way the lighting task can still retrieve the block entity before its gone.

void RemoveBlockLight(byte[] oldLightHsV, BlockPos pos)

Parameters

oldLightHsV byte[]
pos BlockPos

Rollback()

For the bulk update block accessor reverts all the SetBlocks currently called since the last Commit()

void Rollback()

SearchBlocks(BlockPos, BlockPos, ActionConsumable<Block, BlockPos>, Action<int, int, int>)

A method to search for a given block in an area
Currently NOT dimensionally aware

void SearchBlocks(BlockPos minPos, BlockPos maxPos, ActionConsumable<Block, BlockPos> onBlock, Action<int, int, int> onChunkMissing = null)

Parameters

minPos BlockPos
maxPos BlockPos
onBlock ActionConsumable<Block, BlockPos>

Return false to stop the search

onChunkMissing Action<int, int, int>

Called when a missing/unloaded chunk was encountered

SearchFluidBlocks(BlockPos, BlockPos, ActionConsumable<Block, BlockPos>, Action<int, int, int>)

A method to search for a given fluid block in an area
Currently NOT dimensionally aware

void SearchFluidBlocks(BlockPos minPos, BlockPos maxPos, ActionConsumable<Block, BlockPos> onBlock, Action<int, int, int> onChunkMissing = null)

Parameters

minPos BlockPos
maxPos BlockPos
onBlock ActionConsumable<Block, BlockPos>

Return false to stop the search

onChunkMissing Action<int, int, int>

Called when a missing/unloaded chunk was encountered

SetBlock(int, BlockPos)

Set a block at the given position. Use blockid 0 to clear that position from any blocks. Marks the chunk dirty so that it gets saved to disk during shutdown or next autosave. If called with a fluid block, the fluid will automatically get set in the fluid layer, and the solid layer will be emptied.

void SetBlock(int blockId, BlockPos pos)

Parameters

blockId int
pos BlockPos

SetBlock(int, BlockPos, int)

Sets a block to given layer. Can only use "BlockLayersAccess.Solid" or "BlockLayersAccess.Liquid". Use id 0 to clear a block from given position. Marks the chunk dirty so that it gets saved to disk during shutdown or next autosave.

void SetBlock(int blockId, BlockPos pos, int layer)

Parameters

blockId int
pos BlockPos
layer int

SetBlock(int, BlockPos, ItemStack)

Set a block at the given position. Use blockid 0 to clear that position from any blocks. Marks the chunk dirty so that it gets saved to disk during shutdown or next autosave. If called with a fluid block, the fluid will automatically get set in the fluid layer, and the solid layer will be emptied.

void SetBlock(int blockId, BlockPos pos, ItemStack byItemstack)

Parameters

blockId int
pos BlockPos
byItemstack ItemStack

If set then it will be passed onto the block.OnBlockPlaced method

SetDecor(Block, BlockPos, int)

Add a decor block to a specific sub-position on the side of an existing block. Use air block (id 0) to remove a decor.

bool SetDecor(Block block, BlockPos position, int decorIndex)

Parameters

block Block
position BlockPos
decorIndex int

You can get this value via ToDecorIndex()

Returns

bool

True if the decor was sucessfully set

SetDecor(Block, BlockPos, BlockFacing)

Add a decor block to the side of an existing block. Use air block (id 0) to remove a decor.

bool SetDecor(Block block, BlockPos position, BlockFacing onFace)

Parameters

block Block
position BlockPos
onFace BlockFacing

Returns

bool

True if the decor was sucessfully set

SpawnBlockEntity(string, BlockPos, ItemStack)

Spawn block entity at this position. Does not place it's corresponding block, you have to this yourself.

void SpawnBlockEntity(string classname, BlockPos position, ItemStack byItemStack = null)

Parameters

classname string
position BlockPos
byItemStack ItemStack

SpawnBlockEntity(BlockEntity)

Adds pre-initialized block entity to the world. Does not call CreateBehaviors/Initialize/OnBlockPlaced on the block entity. This is a very low level method for block entity spawning, normally you'd want to use SpawnBlockEntity(string, BlockPos, ItemStack)

void SpawnBlockEntity(BlockEntity be)

Parameters

be BlockEntity

TriggerNeighbourBlockUpdate(BlockPos)

Triggers the method OnNeighbourBlockChange() to all neighbour blocks at given position

void TriggerNeighbourBlockUpdate(BlockPos pos)

Parameters

pos BlockPos

WalkBlocks(BlockPos, BlockPos, Action<Block, int, int, int>, bool)

A method to iterate over blocks in an area. Less overhead than when calling GetBlock(pos) many times. If there is liquids in the liquid layer, the onBlock method will be called twice. Currently used for more efficient collision testing.
Currently NOT dimensionally aware

void WalkBlocks(BlockPos minPos, BlockPos maxPos, Action<Block, int, int, int> onBlock, bool centerOrder = false)

Parameters

minPos BlockPos
maxPos BlockPos
onBlock Action<Block, int, int, int>

The method in which you want to check for the block, whatever it may be.

centerOrder bool

If true, the blocks will be ordered by the distance to the center position

WalkStructures(BlockPos, Action<GeneratedStructure>)

Calls given handler if it encounters one or more generated structure at given position (read from mapregions, assuming a max structure size of 256x256x256)

void WalkStructures(BlockPos pos, Action<GeneratedStructure> onStructure)

Parameters

pos BlockPos
onStructure Action<GeneratedStructure>

WalkStructures(BlockPos, BlockPos, Action<GeneratedStructure>)

Calls given handler if it encounters one or more generated structure that intersect any position inside minpos->maxpos (read from mapregions, assuming a max structure size of 256x256x256)

void WalkStructures(BlockPos minpos, BlockPos maxpos, Action<GeneratedStructure> onStructure)

Parameters

minpos BlockPos
maxpos BlockPos
onStructure Action<GeneratedStructure>