Interface IBlockAccessor
- Namespace
- Vintagestory.API.Common
- Assembly
- VintagestoryAPI.dll
Provides read/write access to the blocks of a world
public interface IBlockAccessor
- Extension Methods
Properties
ChunkSize
Width, Length and Height of a chunk
int ChunkSize { get; }
Property Value
MapSize
Size of the world in blocks
Vec3i MapSize { get; }
Property Value
MapSizeX
X Size of the world in blocks
int MapSizeX { get; }
Property Value
MapSizeY
Y Size of the world in blocks
int MapSizeY { get; }
Property Value
MapSizeZ
Z Size of the world in blocks
int MapSizeZ { get; }
Property Value
RegionMapSizeX
int RegionMapSizeX { get; }
Property Value
RegionMapSizeY
int RegionMapSizeY { get; }
Property Value
RegionMapSizeZ
int RegionMapSizeZ { get; }
Property Value
RegionSize
Width and Length of a region in blocks
int RegionSize { get; }
Property Value
UpdateSnowAccumMap
Whether to update the snow accum map on a SetBlock()
bool UpdateSnowAccumMap { get; set; }
Property Value
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
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
BlockPosside
BlockFacingIf 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
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
BlockPosfacing
BlockFacingdamage
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
GetBlock(int)
Get the Block object of a certain block ID. Returns null when not found.
Block GetBlock(int blockId)
Parameters
blockId
intThe 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
Returns
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
intx coordinate
y
inty coordinate
z
intz coordinate
layer
intblocks 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
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
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
Returns
GetBlockAbove(BlockPos, int)
Get the block type of the block above 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
Block GetBlockAbove(BlockPos pos, int dy = 1)
Parameters
Returns
GetBlockBelow(BlockPos, int)
Get the block type of the block below 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
Specify a negative dy for a block above!
Block GetBlockBelow(BlockPos pos, int dy = 1)
Parameters
Returns
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
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
Returns
GetBlockId(BlockPos)
Get the block id of the block at the given world coordinate
int GetBlockId(BlockPos pos)
Parameters
pos
BlockPos
Returns
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
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
Returns
GetChunk(long)
Retrieve chunk at given chunk position, returns null if chunk is not loaded
IWorldChunk GetChunk(long chunkIndex3D)
Parameters
chunkIndex3D
long
Returns
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
Returns
GetChunkAtBlockPos(BlockPos)
Retrieve chunk at given block position, returns null if chunk is not loaded
IWorldChunk GetChunkAtBlockPos(BlockPos pos)
Parameters
pos
BlockPos
Returns
GetClimateAt(BlockPos, int)
Fast shortcut method for the clound renderer
ClimateCondition GetClimateAt(BlockPos pos, int climate)
Parameters
Returns
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
BlockPosbaseClimate
ClimateConditionmode
EnumGetClimateModetotalDays
double
Returns
GetClimateAt(BlockPos, EnumGetClimateMode, double)
Returns the position's current climate conditions
ClimateCondition GetClimateAt(BlockPos pos, EnumGetClimateMode mode = EnumGetClimateMode.NowValues, double totalDays = 0)
Parameters
pos
BlockPosmode
EnumGetClimateModeWorldGenValues = values as determined by the worldgenerator, NowValues = additionally modified to take season, day/night and hemisphere into account
totalDays
doubleWhen mode == ForSuppliedDateValues then supply here the date. Not used param otherwise
Returns
GetDecor(BlockPos, int)
Retrieves a single decor at given position
Block GetDecor(BlockPos pos, int decorIndex)
Parameters
pos
BlockPosdecorIndex
intYou can get this value via ToDecorIndex()
Returns
GetDecors(BlockPos)
Get a list of all decors at this position
[Obsolete("Use Dictionary<int, Block> GetSubDecors(BlockPos 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
BlockPoshorziontalSearchWidth
intHorizontal search distance, 4 default
verticalSearchWidth
intVertical search distance, 1 default
Returns
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
inty
intz
inttype
EnumLightLevelType
Returns
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
BlockPostype
EnumLightLevelType
Returns
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
Returns
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
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
Returns
GetMapChunk(int, int)
Returns the map chunk at given chunk position
IMapChunk GetMapChunk(int chunkX, int chunkZ)
Parameters
Returns
GetMapChunk(Vec2i)
Returns the map chunk at given chunk position
IMapChunk GetMapChunk(Vec2i chunkPos)
Parameters
chunkPos
Vec2i
Returns
GetMapChunkAtBlockPos(BlockPos)
Returns the map chunk at given block position
IMapChunk GetMapChunkAtBlockPos(BlockPos pos)
Parameters
pos
BlockPos
Returns
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
Returns
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
Returns
GetMostSolidBlock(BlockPos)
Same as GetBlock(BlockPos, int) with BlockLayersAccess.MostSolid as layer
Block GetMostSolidBlock(BlockPos pos)
Parameters
pos
BlockPos
Returns
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
Returns
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
GetSubDecors(BlockPos)
Get a list of all decors at this position
Dictionary<int, Block> GetSubDecors(BlockPos position)
Parameters
position
BlockPos
Returns
- Dictionary<int, Block>
null if this block position has no decors. Otherwise, a Dictionary with the index being the faceAndSubposition (subposition used for cave art etc.)
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
GetWindSpeedAt(BlockPos)
Retrieves the wind speed for given position
Vec3d GetWindSpeedAt(BlockPos pos)
Parameters
pos
BlockPos
Returns
GetWindSpeedAt(Vec3d)
Retrieves the wind speed for given position
Vec3d GetWindSpeedAt(Vec3d pos)
Parameters
pos
Vec3d
Returns
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)
[Obsolete("Better to use dimension-aware version")]
bool IsNotTraversable(double x, double y, double z)
Parameters
Returns
IsNotTraversable(double, double, double, int)
Checks if this position can be traversed by a normal player (returns false for outside map or not yet loaded chunks) Dimension-aware version
bool IsNotTraversable(double x, double y, double z, int dim)
Parameters
Returns
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
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
inty
intz
intfacing
BlockFacing
Returns
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
Returns
IsValidPos(BlockPos)
Checks if the position is inside the maps boundaries
bool IsValidPos(BlockPos pos)
Parameters
pos
BlockPos
Returns
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
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
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
BlockPosskipPlayer
IPlayerServer 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
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
BlockPosmaxPos
BlockPosonBlock
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
BlockPosmaxPos
BlockPosonBlock
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
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
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
intpos
BlockPosbyItemstack
ItemStackIf 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
Blockposition
BlockPosdecorIndex
intYou can get this value via ToDecorIndex() or via GetDecorIndex(BlockFacing, int, int, int).
It can include a subPosition for cave art etc.
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
Blockposition
BlockPosonFace
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
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
BlockPosmaxPos
BlockPosonBlock
Action<Block, int, int, int>The method in which you want to check for the block, whatever it may be.
centerOrder
boolIf 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
BlockPosonStructure
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
BlockPosmaxpos
BlockPosonStructure
Action<GeneratedStructure>