Class BlockBehavior

Namespace

Vintagestory.API.Common

Assembly

VintagestoryAPI.dll

Allows for definitions of behaviors of a block that can be applied to any block See the derived types for a list of all documented block behaviors. Open in GitHub

[DocumentAsJson]
public abstract class BlockBehavior : CollectibleBehavior

Inheritance

object

CollectibleBehavior

BlockBehavior

Derived

StrongBlockBehavior

Inherited Members

CollectibleBehavior.collObj

CollectibleBehavior.propertiesAtString

CollectibleBehavior.ClientSideOptional

CollectibleBehavior.Initialize(JsonObject)

CollectibleBehavior.OnLoaded(ICoreAPI)

CollectibleBehavior.OnUnloaded(ICoreAPI)

CollectibleBehavior.GetStorageFlags(ItemStack, ref EnumHandling)

CollectibleBehavior.OnHeldAttackStart(ItemSlot, EntityAgent, BlockSelection, EntitySelection, ref EnumHandHandling, ref EnumHandling)

CollectibleBehavior.OnHeldAttackCancel(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, EnumItemUseCancelReason, ref EnumHandling)

CollectibleBehavior.OnHeldAttackStep(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, ref EnumHandling)

CollectibleBehavior.OnHeldAttackStop(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, ref EnumHandling)

CollectibleBehavior.OnHeldInteractStart(ItemSlot, EntityAgent, BlockSelection, EntitySelection, bool, ref EnumHandHandling, ref EnumHandling)

CollectibleBehavior.OnHeldInteractStep(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, ref EnumHandling)

CollectibleBehavior.OnHeldInteractStop(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, ref EnumHandling)

CollectibleBehavior.OnHeldInteractCancel(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, EnumItemUseCancelReason, ref EnumHandling)

CollectibleBehavior.OnBeforeRender(ICoreClientAPI, ItemStack, EnumItemRenderTarget, ref ItemRenderInfo)

CollectibleBehavior.GetHeldInteractionHelp(ItemSlot, ref EnumHandling)

CollectibleBehavior.GetToolModes(ItemSlot, IClientPlayer, BlockSelection)

CollectibleBehavior.GetToolMode(ItemSlot, IPlayer, BlockSelection)

CollectibleBehavior.SetToolMode(ItemSlot, IPlayer, BlockSelection, int)

CollectibleBehavior.GetHeldItemInfo(ItemSlot, StringBuilder, IWorldAccessor, bool)

CollectibleBehavior.GetHeldItemName(StringBuilder, ItemStack)

CollectibleBehavior.OnBlockBrokenWith(IWorldAccessor, Entity, ItemSlot, BlockSelection, float, ref EnumHandling)

CollectibleBehavior.OnBlockBreaking(IPlayer, BlockSelection, ItemSlot, float, float, int, ref EnumHandling)

CollectibleBehavior.GetHeldTpHitAnimation(ItemSlot, Entity, ref EnumHandling)

CollectibleBehavior.GetHeldReadyAnimation(ItemSlot, Entity, EnumHand, ref EnumHandling)

CollectibleBehavior.GetHeldTpIdleAnimation(ItemSlot, Entity, EnumHand, ref EnumHandling)

CollectibleBehavior.GetHeldTpUseAnimation(ItemSlot, Entity, ref EnumHandling)

CollectibleBehavior.OnCreatedByCrafting(ItemSlot[], ItemSlot, ref EnumHandling)

CollectibleBehavior.OnGetMiningSpeed(IItemStack, BlockSelection, Block, IPlayer, ref EnumHandling)

CollectibleBehavior.OnGetMaxDurability(ItemStack, ref EnumHandling)

CollectibleBehavior.OnGetRemainingDurability(ItemStack, ref EnumHandling)

CollectibleBehavior.OnDamageItem(IWorldAccessor, Entity, ItemSlot, ref int, ref EnumHandling)

CollectibleBehavior.OnSetDurability(ItemStack, ref int, ref EnumHandling)

CollectibleBehavior.OnTransitionNow(ItemSlot, TransitionableProperties, ref EnumHandling)

CollectibleBehavior.OnHandbookRecipeRender(ICoreClientAPI, GridRecipe, ItemSlot, double, double, double, double)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Extension Methods

ObjectHandleExtensions.ToGcHandle(object)

ObjectHandleExtensions.ToIntPtr(object)

Constructors

BlockBehavior(Block)

public BlockBehavior(Block block)

Parameters

block Block

Fields

block

The block for this behavior instance.

public Block block

Field Value

Block

Methods

Activate(IWorldAccessor, Caller, BlockSelection, ITreeAttribute, ref EnumHandling)

public virtual void Activate(IWorldAccessor world, Caller caller, BlockSelection blockSel, ITreeAttribute activationArgs, ref EnumHandling handled)

Parameters

world IWorldAccessor

caller Caller

blockSel BlockSelection

activationArgs ITreeAttribute

handled EnumHandling

CanAttachBlockAt(IBlockAccessor, Block, BlockPos, BlockFacing, ref EnumHandling, Cuboidi)

Used by torches and other blocks to check if it can attach itself to that block. The default behavior tests for SideSolid[blockFace.Index]

public virtual bool CanAttachBlockAt(IBlockAccessor world, Block block, BlockPos pos, BlockFacing blockFace, ref EnumHandling handling, Cuboidi attachmentArea = null)

Parameters

world IBlockAccessor

block Block

pos BlockPos

blockFace BlockFacing

handling EnumHandling

attachmentArea Cuboidi

Returns

bool

CanCreatureSpawnOn(IBlockAccessor, BlockPos, EntityProperties, BaseSpawnConditions, ref EnumHandling)

Should return if supplied entitytype is allowed to spawn on this block

public virtual bool CanCreatureSpawnOn(IBlockAccessor blockAccessor, BlockPos pos, EntityProperties type, BaseSpawnConditions sc, ref EnumHandling handling)

Parameters

blockAccessor IBlockAccessor

pos BlockPos

type EntityProperties

sc BaseSpawnConditions

handling EnumHandling

Returns

bool

CanPlaceBlock(IWorldAccessor, IPlayer, BlockSelection, ref EnumHandling, ref string)

Step 2: Test if the block can be placed

public virtual bool CanPlaceBlock(IWorldAccessor world, IPlayer byPlayer, BlockSelection blockSel, ref EnumHandling handling, ref string failureCode)

Parameters

world IWorldAccessor

byPlayer IPlayer

blockSel BlockSelection

handling EnumHandling

failureCode string

Returns

bool

DoPlaceBlock(IWorldAccessor, IPlayer, BlockSelection, ItemStack, ref EnumHandling)

Step 3: Place the block. Return false if it cannot be placed (but you should rather return false in CanPlaceBlock).

public virtual bool DoPlaceBlock(IWorldAccessor world, IPlayer byPlayer, BlockSelection blockSel, ItemStack byItemStack, ref EnumHandling handling)

Parameters

world IWorldAccessor

byPlayer IPlayer

blockSel BlockSelection

byItemStack ItemStack

handling EnumHandling

Returns

bool

GetDrops(IWorldAccessor, BlockPos, IPlayer, ref float, ref EnumHandling)

Is called before a block is broken, should return what items this block should drop. Return null or empty array for no drops. The default behavior drops whatever block.Drops is set to.

public virtual ItemStack[] GetDrops(IWorldAccessor world, BlockPos pos, IPlayer byPlayer, ref float dropChanceMultiplier, ref EnumHandling handling)

Parameters

world IWorldAccessor

pos BlockPos

byPlayer IPlayer

dropChanceMultiplier float

handling EnumHandling

Returns

ItemStack[]

GetHeatRetention(BlockPos, BlockFacing, ref EnumHandling)

[Obsolete("Use GetRetention() instead")]
public virtual int GetHeatRetention(BlockPos pos, BlockFacing facing, ref EnumHandling handled)

Parameters

pos BlockPos

facing BlockFacing

handled EnumHandling

Returns

int

GetHeldBlockInfo(IWorldAccessor, ItemSlot)

public virtual string GetHeldBlockInfo(IWorldAccessor world, ItemSlot inSlot)

Parameters

world IWorldAccessor

inSlot ItemSlot

Returns

string

GetHorizontallyFlippedBlockCode(EnumAxis, ref EnumHandling)

For any block that can be flipped vertically, this method should be implemented to return the correctly flipped block code. It is used by the world edit tool for allowing block data rotations

public virtual AssetLocation GetHorizontallyFlippedBlockCode(EnumAxis axis, ref EnumHandling handling)

Parameters

axis EnumAxis

handling EnumHandling

Returns

AssetLocation

GetLiquidBarrierHeightOnSide(BlockFacing, BlockPos, ref EnumHandling)

public virtual float GetLiquidBarrierHeightOnSide(BlockFacing face, BlockPos pos, ref EnumHandling handled)

Parameters

face BlockFacing

pos BlockPos

handled EnumHandling

Returns

float

GetMiningSpeedModifier(IWorldAccessor, BlockPos, IPlayer)

If this is less than 1.0, will slow down mining of the given block (e.g. used for reinforced blocks)

public virtual float GetMiningSpeedModifier(IWorldAccessor world, BlockPos pos, IPlayer byPlayer)

Parameters

world IWorldAccessor

pos BlockPos

byPlayer IPlayer

Returns

float

GetPlacedBlockInfo(IWorldAccessor, BlockPos, IPlayer)

Called by the block info HUD for displaying additional information

public virtual string GetPlacedBlockInfo(IWorldAccessor world, BlockPos pos, IPlayer forPlayer)

Parameters

world IWorldAccessor

pos BlockPos

forPlayer IPlayer

Returns

string

GetPlacedBlockInteractionHelp(IWorldAccessor, BlockSelection, IPlayer, ref EnumHandling)

public virtual WorldInteraction[] GetPlacedBlockInteractionHelp(IWorldAccessor world, BlockSelection selection, IPlayer forPlayer, ref EnumHandling handling)

Parameters

world IWorldAccessor

selection BlockSelection

forPlayer IPlayer

handling EnumHandling

Returns

WorldInteraction[]

GetPlacedBlockName(StringBuilder, IWorldAccessor, BlockPos)

public virtual void GetPlacedBlockName(StringBuilder sb, IWorldAccessor world, BlockPos pos)

Parameters

sb StringBuilder

world IWorldAccessor

pos BlockPos

GetRetention(BlockPos, BlockFacing, EnumRetentionType, ref EnumHandling)

public virtual int GetRetention(BlockPos pos, BlockFacing facing, EnumRetentionType type, ref EnumHandling handled)

Parameters

pos BlockPos

facing BlockFacing

type EnumRetentionType

handled EnumHandling

Returns

int

GetRotatedBlockCode(int, ref EnumHandling)

For any block that can be rotated, this method should be implemented to return the correct rotated block code. It is used by the world edit tool for allowing block data rotations

public virtual AssetLocation GetRotatedBlockCode(int angle, ref EnumHandling handling)

Parameters

angle int

handling EnumHandling

Returns

AssetLocation

GetSnowCoveredBlockCode(float)

public virtual AssetLocation GetSnowCoveredBlockCode(float snowLevel)

Parameters

snowLevel float

Returns

AssetLocation

GetVerticallyFlippedBlockCode(ref EnumHandling)

For any block that can be flipped upside down, this method should be implemented to return the correctly flipped block code. It is used by the world edit tool for allowing block data rotations

public virtual AssetLocation GetVerticallyFlippedBlockCode(ref EnumHandling handling)

Parameters

handling EnumHandling

Returns

AssetLocation

IsReplacableBy(Block, ref EnumHandling)

Used to determine if a block should be treated like air when placing blocks. (e.g. used for tallgrass)

public virtual bool IsReplacableBy(Block block, ref EnumHandling handling)

Parameters

block Block

handling EnumHandling

Returns

bool

OnAsyncClientParticleTick(IAsyncParticleManager, BlockPos, float, float)

public virtual void OnAsyncClientParticleTick(IAsyncParticleManager manager, BlockPos pos, float windAffectednessAtPos, float secondsTicking)

Parameters

manager IAsyncParticleManager

pos BlockPos

windAffectednessAtPos float

secondsTicking float

OnBlockBroken(IWorldAccessor, BlockPos, IPlayer, ref EnumHandling)

Called when a survival player has broken the block. The default behavior removes the block and spawns the block drops.

public virtual void OnBlockBroken(IWorldAccessor world, BlockPos pos, IPlayer byPlayer, ref EnumHandling handling)

Parameters

world IWorldAccessor

pos BlockPos

byPlayer IPlayer

handling EnumHandling

OnBlockExploded(IWorldAccessor, BlockPos, BlockPos, EnumBlastType, ref EnumHandling)

public virtual void OnBlockExploded(IWorldAccessor world, BlockPos pos, BlockPos explosionCenter, EnumBlastType blastType, ref EnumHandling handling)

Parameters

world IWorldAccessor

pos BlockPos

explosionCenter BlockPos

blastType EnumBlastType

handling EnumHandling

OnBlockInteractCancel(float, IWorldAccessor, IPlayer, BlockSelection, ref EnumHandling)

public virtual bool OnBlockInteractCancel(float secondsUsed, IWorldAccessor world, IPlayer byPlayer, BlockSelection blockSel, ref EnumHandling handling)

Parameters

secondsUsed float

world IWorldAccessor

byPlayer IPlayer

blockSel BlockSelection

handling EnumHandling

Returns

bool

OnBlockInteractStart(IWorldAccessor, IPlayer, BlockSelection, ref EnumHandling)

When a player does a right click while targeting this placed block. Should return true if the event is handled, so that other events can occur, e.g. eating a held item if the block is not interactable with.

public virtual bool OnBlockInteractStart(IWorldAccessor world, IPlayer byPlayer, BlockSelection blockSel, ref EnumHandling handling)

Parameters

world IWorldAccessor

byPlayer IPlayer

blockSel BlockSelection

handling EnumHandling

Returns

bool

OnBlockInteractStep(float, IWorldAccessor, IPlayer, BlockSelection, ref EnumHandling)

public virtual bool OnBlockInteractStep(float secondsUsed, IWorldAccessor world, IPlayer byPlayer, BlockSelection blockSel, ref EnumHandling handling)

Parameters

secondsUsed float

world IWorldAccessor

byPlayer IPlayer

blockSel BlockSelection

handling EnumHandling

Returns

bool

OnBlockInteractStop(float, IWorldAccessor, IPlayer, BlockSelection, ref EnumHandling)

public virtual void OnBlockInteractStop(float secondsUsed, IWorldAccessor world, IPlayer byPlayer, BlockSelection blockSel, ref EnumHandling handling)

Parameters

secondsUsed float

world IWorldAccessor

byPlayer IPlayer

blockSel BlockSelection

handling EnumHandling

OnBlockPlaced(IWorldAccessor, BlockPos, ref EnumHandling)

Step 4: Block was placed. Always called when a block has been placed through whatever method, except during worldgen or via ExchangeBlock() Until 1.20: The BlockEntity (if the block has one) does not exist yet at this point and will not be generated if handling is not PassThrough 1.21+: The BlockEntity (if the block has one) exists at this point. Setting handling to PreventDefault or PreventSubsequent has no effect on BlockEntity creation, but may affect/prevent later behaviors

public virtual void OnBlockPlaced(IWorldAccessor world, BlockPos blockPos, ref EnumHandling handling)

Parameters

world IWorldAccessor

blockPos BlockPos

handling EnumHandling

OnBlockRemoved(IWorldAccessor, BlockPos, ref EnumHandling)

Always called when a block has been removed through whatever method, except during worldgen or via ExchangeBlock() For Worldgen you might be able to use TryPlaceBlockForWorldGen() to attach custom behaviors during placement/removal

The default behavior is to delete the block entity, if this block has any

public virtual void OnBlockRemoved(IWorldAccessor world, BlockPos pos, ref EnumHandling handling)

Parameters

world IWorldAccessor

pos BlockPos

handling EnumHandling

OnCreatedByCrafting(ItemSlot[], ItemSlot, GridRecipe, ref EnumHandling)

public override void OnCreatedByCrafting(ItemSlot[] allInputslots, ItemSlot outputSlot, GridRecipe byRecipe, ref EnumHandling handled)

Parameters

allInputslots ItemSlot[]

outputSlot ItemSlot

byRecipe GridRecipe

handled EnumHandling

OnNeighbourBlockChange(IWorldAccessor, BlockPos, BlockPos, ref EnumHandling)

Called when any of it's 6 neighbour blocks has been changed

public virtual void OnNeighbourBlockChange(IWorldAccessor world, BlockPos pos, BlockPos neibpos, ref EnumHandling handling)

Parameters

world IWorldAccessor

pos BlockPos

neibpos BlockPos

handling EnumHandling

OnPickBlock(IWorldAccessor, BlockPos, ref EnumHandling)

When the player has presed the middle mouse click on the block. The default behavior returns an itemstack with the block itself

public virtual ItemStack OnPickBlock(IWorldAccessor world, BlockPos pos, ref EnumHandling handling)

Parameters

world IWorldAccessor

pos BlockPos

handling EnumHandling

Returns

ItemStack

ShouldReceiveClientParticleTicks(IWorldAccessor, IPlayer, BlockPos, ref EnumHandling)

Everytime the player moves by 8 blocks (or rather leaves the current 8-grid), a scan of all blocks 32x32x32 blocks around the player is initiated and this method is called. If the method returns true, the block is registered to a client side game ticking for spawning particles and such. This method will be called everytime the player left his current 8-grid area.

The default behavior is to return true if block.ParticleProperties are set

public virtual bool ShouldReceiveClientParticleTicks(IWorldAccessor world, IPlayer byPlayer, BlockPos pos, ref EnumHandling handling)

Parameters

world IWorldAccessor

byPlayer IPlayer

pos BlockPos

handling EnumHandling

Returns

bool

TryPlaceBlock(IWorldAccessor, IPlayer, ItemStack, BlockSelection, ref EnumHandling, ref string)

Step 1: Called when the player attempts to place this block. The default behavior calls Block.DoPlaceBlock(). If returned true and default behavior has not been prevented, the game will next call CanPlaceBlock(). If that method also returns true and default behavior has not been overriden, DoPlaceBlock() will get called.

public virtual bool TryPlaceBlock(IWorldAccessor world, IPlayer byPlayer, ItemStack itemstack, BlockSelection blockSel, ref EnumHandling handling, ref string failureCode)

Parameters

world IWorldAccessor

byPlayer IPlayer

itemstack ItemStack

blockSel BlockSelection

handling EnumHandling

failureCode string

Returns

bool