Table of Contents

Class BlockEntity

Namespace
Vintagestory.API.Common
Assembly
VintagestoryAPI.dll

Basic class for block entities - a data structures to hold custom information for blocks, e.g. for chests to hold it's contents

public abstract class BlockEntity
Inheritance
BlockEntity
Inherited Members

Constructors

BlockEntity()

Creats an empty instance. Use initialize to initialize it with the api.

public BlockEntity()

Fields

Api

The core API added to the block. Accessable after initialization.

public ICoreAPI Api

Field Value

ICoreAPI

Behaviors

List of block entity behaviors associated with this block entity

public List<BlockEntityBehavior> Behaviors

Field Value

List<BlockEntityBehavior>

CallbackHandlers 

protected List<long> CallbackHandlers

Field Value

List<long>

Pos

Position of the block for this block entity

public BlockPos Pos

Field Value

BlockPos

TickHandlers 

protected List<long> TickHandlers

Field Value

List<long>

Properties

Block

The block type at the position of the block entity. This poperty is updated by the engine if ExchangeBlock is called

public Block Block { get; set; }

Property Value

Block

Methods

CreateBehaviors(Block, IWorldAccessor) 

public virtual void CreateBehaviors(Block block, IWorldAccessor worldForResolve)

Parameters

block Block
worldForResolve IWorldAccessor

FromTreeAttributes(ITreeAttribute, IWorldAccessor)

Called when loading the world or when receiving block entity from the server. When overriding, make sure to still call the base method. FromTreeAttributes is always called before Initialize() is called, so the this.api field is not yet set!

public virtual void FromTreeAttributes(ITreeAttribute tree, IWorldAccessor worldAccessForResolve)

Parameters

tree ITreeAttribute
worldAccessForResolve IWorldAccessor

Use this api if you need to resolve blocks/items. Not suggested for other purposes, as the residing chunk may not be loaded at this point

GetBehavior<T>() 

public T GetBehavior<T>() where T : class

Returns

T

Type Parameters

T

GetBlockInfo(IPlayer, StringBuilder)

Called by the block info HUD for displaying additional information

public virtual void GetBlockInfo(IPlayer forPlayer, StringBuilder dsc)

Parameters

forPlayer IPlayer
dsc StringBuilder

HistoryStateRestore()

Called by the undo/redo system, after calling FromTreeAttributes

public virtual void HistoryStateRestore()

Initialize(ICoreAPI)

This method is called right after the block entity was spawned or right after it was loaded from a newly loaded chunk. You do have access to the world and its blocks at this point. However if this block entity already existed then FromTreeAttributes is called first! You should still call the base method to sets the this.api field

public virtual void Initialize(ICoreAPI api)

Parameters

api ICoreAPI

MarkDirty(bool, IPlayer)

When called on Server: Will resync the block entity with all its TreeAttribute to the client, but will not resend or redraw the block unless specified. When called on Client: Triggers a block changed event on the client, but will not redraw the block unless specified.

public virtual void MarkDirty(bool redrawOnClient = false, IPlayer skipPlayer = null)

Parameters

redrawOnClient bool

When true, the block is also marked dirty and thus redrawn. When called serverside a dirty block packet is sent to the client for it to be redrawn

skipPlayer IPlayer

OnBlockBroken(IPlayer)

Called when the block was broken in survival mode or through explosions and similar. Generally in situations where you probably want to drop the block entity contents, if it has any

public virtual void OnBlockBroken(IPlayer byPlayer = null)

Parameters

byPlayer IPlayer

OnBlockPlaced(ItemStack)

Called when the block entity just got placed, not called when it was previously placed and the chunk is loaded. Always called after Initialize()

public virtual void OnBlockPlaced(ItemStack byItemStack = null)

Parameters

byItemStack ItemStack

OnBlockRemoved()

Called when the block at this position was removed in some way. Removes the game tick listeners, so still call the base method

public virtual void OnBlockRemoved()

OnBlockUnloaded()

Called when the chunk the block entity resides in was unloaded. Removes the game tick listeners, so still call the base method

public virtual void OnBlockUnloaded()

OnExchanged(Block)

Called when blockAccessor.ExchangeBlock() is used to exchange this block. Make sure to call the base method when overriding.

public virtual void OnExchanged(Block block)

Parameters

block Block

OnLoadCollectibleMappings(IWorldAccessor, Dictionary<int, AssetLocation>, Dictionary<int, AssetLocation>, int)

Called by the blockschematic loader so that you may fix any blockid/itemid mappings against the mapping of the savegame, if you store any collectibles in this blockentity. Note: Some vanilla blocks resolve randomized contents in this method. Hint: Use itemstack.FixMapping() to do the job for you.

[Obsolete("Use the variant with resolveImports parameter")]
public virtual void OnLoadCollectibleMappings(IWorldAccessor worldForNewMappings, Dictionary<int, AssetLocation> oldBlockIdMapping, Dictionary<int, AssetLocation> oldItemIdMapping, int schematicSeed)

Parameters

worldForNewMappings IWorldAccessor
oldBlockIdMapping Dictionary<int, AssetLocation>
oldItemIdMapping Dictionary<int, AssetLocation>
schematicSeed int

If you need some sort of randomness consistency accross an imported schematic, you can use this value

OnLoadCollectibleMappings(IWorldAccessor, Dictionary<int, AssetLocation>, Dictionary<int, AssetLocation>, int, bool)

Called by the blockschematic loader so that you may fix any blockid/itemid mappings against the mapping of the savegame, if you store any collectibles in this blockentity. Note: Some vanilla blocks resolve randomized contents in this method. Hint: Use itemstack.FixMapping() to do the job for you.

public virtual void OnLoadCollectibleMappings(IWorldAccessor worldForNewMappings, Dictionary<int, AssetLocation> oldBlockIdMapping, Dictionary<int, AssetLocation> oldItemIdMapping, int schematicSeed, bool resolveImports)

Parameters

worldForNewMappings IWorldAccessor
oldBlockIdMapping Dictionary<int, AssetLocation>
oldItemIdMapping Dictionary<int, AssetLocation>
schematicSeed int

If you need some sort of randomness consistency accross an imported schematic, you can use this value

resolveImports bool

Turn it off to spawn structures as they are. For example, in this mode, instead of traders, their meta spawners will spawn

OnPlacementBySchematic(ICoreServerAPI, IBlockAccessor, BlockPos, Dictionary<int, Dictionary<int, int>>, int, Block, bool)

Called when this block entity was placed by a schematic, either through world edit or by worldgen

public virtual void OnPlacementBySchematic(ICoreServerAPI api, IBlockAccessor blockAccessor, BlockPos pos, Dictionary<int, Dictionary<int, int>> replaceBlocks, int centerrockblockid, Block layerBlock, bool resolveImports)

Parameters

api ICoreServerAPI
blockAccessor IBlockAccessor
pos BlockPos
replaceBlocks Dictionary<int, Dictionary<int, int>>
centerrockblockid int
layerBlock Block

If block.CustomBlockLayerHandler is true and the block is below the surface, this value is set

resolveImports bool

Turn it off to spawn structures as they are. For example, in this mode, instead of traders, their meta spawners will spawn

OnReceivedClientPacket(IPlayer, int, byte[])

Called whenever a blockentity packet at the blocks position has been received from the client

public virtual void OnReceivedClientPacket(IPlayer fromPlayer, int packetid, byte[] data)

Parameters

fromPlayer IPlayer
packetid int
data byte[]

OnReceivedServerPacket(int, byte[])

Called whenever a blockentity packet at the blocks position has been received from the server

public virtual void OnReceivedServerPacket(int packetid, byte[] data)

Parameters

packetid int
data byte[]

OnStoreCollectibleMappings(Dictionary<int, AssetLocation>, Dictionary<int, AssetLocation>)

Called by the worldedit schematic exporter so that it can also export the mappings of items/blocks stored inside blockentities

public virtual void OnStoreCollectibleMappings(Dictionary<int, AssetLocation> blockIdMapping, Dictionary<int, AssetLocation> itemIdMapping)

Parameters

blockIdMapping Dictionary<int, AssetLocation>
itemIdMapping Dictionary<int, AssetLocation>

OnTesselation(ITerrainMeshPool, ITesselatorAPI)

Let's you add your own meshes to a chunk. Don't reuse the meshdata instance anywhere in your code. Return true to skip the default mesh. WARNING! The Tesselator runs in a seperate thread, so you have to make sure the fields and methods you access inside this method are thread safe.

public virtual bool OnTesselation(ITerrainMeshPool mesher, ITesselatorAPI tessThreadTesselator)

Parameters

mesher ITerrainMeshPool

The chunk mesh, add your stuff here

tessThreadTesselator ITesselatorAPI

If you need to tesselate something, you should use this tesselator, since using the main thread tesselator can cause race conditions and crash the game

Returns

bool

True to skip default mesh, false to also add the default mesh

RegisterDelayedCallback(Action<float>, int)

Registers a delayed callback that does the disposing for you when the Block is removed

public virtual long RegisterDelayedCallback(Action<float> OnDelayedCallbackTick, int millisecondInterval)

Parameters

OnDelayedCallbackTick Action<float>
millisecondInterval int

Returns

long

RegisterGameTickListener(Action<float>, int, int)

Registers a game tick listener that does the disposing for you when the Block is removed

public virtual long RegisterGameTickListener(Action<float> onGameTick, int millisecondInterval, int initialDelayOffsetMs = 0)

Parameters

onGameTick Action<float>
millisecondInterval int
initialDelayOffsetMs int

Returns

long

TickingExceptionHandler(Exception) 

public virtual void TickingExceptionHandler(Exception e)

Parameters

e Exception

ToTreeAttributes(ITreeAttribute)

Called when saving the world or when sending the block entity data to the client. When overriding, make sure to still call the base method.

public virtual void ToTreeAttributes(ITreeAttribute tree)

Parameters

tree ITreeAttribute

UnregisterDelayedCallback(long)

Unregisters a callback. This is usually done automatically.

public virtual void UnregisterDelayedCallback(long listenerId)

Parameters

listenerId long

The ID of the callback listiner.

UnregisterGameTickListener(long)

Removes a registered game tick listener from the game.

public virtual void UnregisterGameTickListener(long listenerId)

Parameters

listenerId long

the ID of the listener to unregister.