Table of Contents

Class Block

Namespace
Vintagestory.API.Common
Assembly
VintagestoryAPI.dll

Basic class for a placeable block

public class Block : CollectibleObject
Inheritance
Block
Derived
Inherited Members
Extension Methods

Constructors

Block()

Creates a new instance of a block with default model transforms

public Block()

Fields

AllCreaturesAllowed 

public bool AllCreaturesAllowed

Field Value

bool

AllowSpawnCreatureGroups

Defines what creature groups may spawn on this block

public string[] AllowSpawnCreatureGroups

Field Value

string[]

AllowStepWhenStuck 

public bool AllowStepWhenStuck

Field Value

bool

Ambientocclusion

Currently not used

public bool Ambientocclusion

Field Value

bool

BlockBehaviors

Modifiers that can alter the behavior of a block, particularly when being placed or removed

public BlockBehavior[] BlockBehaviors

Field Value

BlockBehavior[]

BlockEntityBehaviors

Modifiers that can alter the behavior of a block entity

public BlockEntityBehaviorType[] BlockEntityBehaviors

Field Value

BlockEntityBehaviorType[]

BlockId

Unique number of the block. Same as Id. This number depends on the order in which the blocks are order. The numbering is however always ensured to remain the same on a per world basis.

public int BlockId

Field Value

int

BlockMaterial

A way to categorize blocks. Used for getting the mining speed for each tool type, amongst other things. Use GetBlockMaterial() to query if not performance critical.

public EnumBlockMaterial BlockMaterial

Field Value

EnumBlockMaterial

CanStep 

public bool CanStep

Field Value

bool

ClimateColorMap

The color map for climate color mapping. Leave null for no coloring by climate

public string ClimateColorMap

Field Value

string

ClimateColorMapResolved 

public ColorMap ClimateColorMapResolved

Field Value

ColorMap

Climbable

Used for ladders. If true, walking against this blocks collisionbox will make the player climb

public bool Climbable

Field Value

bool

CollisionBoxes

Defines the area with which the player character collides with.

public Cuboidf[] CollisionBoxes

Field Value

Cuboidf[]

CropProps

Information about the blocks as a crop

public BlockCropProperties CropProps

Field Value

BlockCropProperties

CustomBlockLayerHandler 

public bool CustomBlockLayerHandler

Field Value

bool

DecorThickness

Used to adjust selection box of parent block

public float DecorThickness

Field Value

float

DefaultCollisionBox

Default Full Block Collision Box

public static Cuboidf DefaultCollisionBox

Field Value

Cuboidf

DoNotRenderAtLod2 

public bool DoNotRenderAtLod2

Field Value

bool

DragMultiplier

Drag multiplier applied to entities standing on it

public float DragMultiplier

Field Value

float

DrawType

If not set to JSON it will use an efficient hardcoded model

public EnumDrawType DrawType

Field Value

EnumDrawType

Drops

The items that should drop from breaking this block

public BlockDropItemStack[] Drops

Field Value

BlockDropItemStack[]

EmitSideAo

Defines which of the 6 block neighbours should receive AO if this block is in front of them

public byte EmitSideAo

Field Value

byte

EntityClass

If this block has a block entity attached to it, this will store it's code

public string EntityClass

Field Value

string

ExtraColorBits

Three extra color / season bits which may have meaning for specific blocks, such as leaves

public int ExtraColorBits

Field Value

int

FaceCullMode

Determines which sides of the blocks should be rendered

public EnumFaceCullMode FaceCullMode

Field Value

EnumFaceCullMode

FastTextureVariants

Fast array of texture variants, for use by cube (or similar) tesselators if the block has alternate shapes The outer array is indexed based on the 6 BlockFacing.Index numerals; the inner array is the variants

public BakedCompositeTexture[][] FastTextureVariants

Field Value

BakedCompositeTexture[][]

Fertility

0 = nothing can grow, 10 = some tallgrass and small trees can be grow on it, 100 = all grass and trees can grow on it

public int Fertility

Field Value

int

Frostable

A bit uploaded to the shader to add a frost overlay below freezing temperature

public bool Frostable

Field Value

bool

HasAlternates

A flag set during texture block shape tesselation

public bool HasAlternates

Field Value

bool

HasTiles 

public bool HasTiles

Field Value

bool

InteractionHelpYOffset 

public float InteractionHelpYOffset

Field Value

float

LightAbsorption

For light blocking blocks. Any value above 32 will completely block all light.

public int LightAbsorption

Field Value

int

LiquidCode

If this block is or contains a liquid, this should be the code (or "identifier") of the liquid

public string LiquidCode

Field Value

string

LiquidLevel

Value between 0..7 for Liquids to determine the height of the liquid

public int LiquidLevel

Field Value

int

LoadColorMapAnyway 

public bool LoadColorMapAnyway

Field Value

bool

Lod0Mesh 

public MeshData Lod0Mesh

Field Value

MeshData

Lod0Shape 

public CompositeShape Lod0Shape

Field Value

CompositeShape

Lod2Mesh 

public MeshData Lod2Mesh

Field Value

MeshData

Lod2Shape 

public CompositeShape Lod2Shape

Field Value

CompositeShape

PartialSelection

If true, players can target individual selection boxes of the block

public bool PartialSelection

Field Value

bool

ParticleCollisionBoxes

Defines the area with which particles collide with (if null, will be the same as CollisionBoxes).

public Cuboidf[] ParticleCollisionBoxes

Field Value

Cuboidf[]

PlacedPriorityInteract

If true, when the player holds the sneak key and right clicks this block, calls the blocks OnBlockInteractStart first, the items OnHeldInteractStart second. Without it the order is reversed.

public bool PlacedPriorityInteract

Field Value

bool

RainPermeable

Will be used for not rendering rain below this block

public bool RainPermeable

Field Value

bool

RandomDrawOffset

If true then the block will be randomly offseted by 1/3 of a block when placed

public int RandomDrawOffset

Field Value

int

RandomSizeAdjust 

public float RandomSizeAdjust

Field Value

float

RandomizeAxes

Random texture selection - whether or not to use the Y axis during randomization (for multiblock plants)

public EnumRandomizeAxes RandomizeAxes

Field Value

EnumRandomizeAxes

RandomizeRotations 

public bool RandomizeRotations

Field Value

bool

RenderPass

During which render pass this block should be rendered

public EnumChunkRenderPass RenderPass

Field Value

EnumChunkRenderPass

Replaceable

A value usually between 0-9999 that indicates which blocks may be replaced with others.

  • Any block with replaceable value above 5000 will be washed away by water
  • Any block with replaceable value above 6000 will replaced when the player tries to place a block Examples: 0 = Bedrock 6000 = Tallgrass 9000 = Lava 9500 = Water 9999 = Air
public int Replaceable

Field Value

int

RequiredMiningTier

The mining tier required to break this block

public int RequiredMiningTier

Field Value

int

Resistance

How long it takes to break this block in seconds. Use GetResistance() to query if not performance critical.

public float Resistance

Field Value

float

SeasonColorMap

The color map for season color mapping. Leave null for no coloring by season

public string SeasonColorMap

Field Value

string

SeasonColorMapResolved 

public ColorMap SeasonColorMapResolved

Field Value

ColorMap

SelectionBoxes

Defines the area which the players mouse pointer collides with for selection.

public Cuboidf[] SelectionBoxes

Field Value

Cuboidf[]

Shape

The default json block shape to be used when drawtype==JSON

public CompositeShape Shape

Field Value

CompositeShape

ShapeInventory

The block shape to be used when displayed in the inventory gui, held in hand or dropped on the ground

public CompositeShape ShapeInventory

Field Value

CompositeShape

ShapeUsesColormap

Internal value that's set during if the block shape has any tint indexes for use in chunk tesselation and stuff O_O

public bool ShapeUsesColormap

Field Value

bool

SideAo

Defines which of the 6 block side should be shaded with ambient occlusion

public bool[] SideAo

Field Value

bool[]

SideOpaque

Defines which of the 6 block sides are completely opaque. Used to determine which block faces can be culled during tesselation.

public bool[] SideOpaque

Field Value

bool[]

SideSolid

Defines which of the 6 block side are solid. Used to determine if attachable blocks can be attached to this block. Also used to determine if snow can rest on top of this block.

public SmallBoolArray SideSolid

Field Value

SmallBoolArray

Sounds

The sounds played for this block during step, break, build and walk. Use GetSounds() to query if not performance critical.

public BlockSounds Sounds

Field Value

BlockSounds

SplitDropStacks

If true, a blocks drops will be split into stacks of stacksize 1 for more game juice. This field is only used in OnBlockBroken() and OnBlockExploded()

public bool SplitDropStacks

Field Value

bool

TextureSubIdForBlockColor 

public int TextureSubIdForBlockColor

Field Value

int

Textures

Default textures to be used for this block (may be null, on servers prior to reading blockType, on clients prior to receipt of server assets)

public IDictionary<string, CompositeTexture> Textures

Field Value

IDictionary<string, CompositeTexture>

TexturesInventory

Textures to be used for this block in the inventory gui, held in hand or dropped on the ground (may be null, on servers prior to reading blockType, on clients prior to receipt of server assets)

public IDictionary<string, CompositeTexture> TexturesInventory

Field Value

IDictionary<string, CompositeTexture>

VertexFlags

Data thats passed on to the graphics card for every vertex of the blocks model

public VertexFlags VertexFlags

Field Value

VertexFlags

WalkSpeedMultiplier

Walk speed when standing or inside this block

public float WalkSpeedMultiplier

Field Value

float

alternatingVOffset

If true, the block will render with a UV offset enabling it to use the "other half" of a 64 x 64 texture on each alternate block position (e.g. Redwood trunk)

public bool alternatingVOffset

Field Value

bool

alternatingVOffsetFaces

Bit flags for the direction in which the alternatingVOffset is to be applied e.g. 0x30 to apply alternatingVOffset as the y position moves up and down

public int alternatingVOffsetFaces

Field Value

int

decorBehaviorFlags

To allow Decor Behavior settings to be accessed through the Block API. See DecorFlags class for interpretation.

public byte decorBehaviorFlags

Field Value

byte

miningTierNames 

protected static string[] miningTierNames

Field Value

string[]

notSnowCovered 

public Block notSnowCovered

Field Value

Block

snowCovered1 

public Block snowCovered1

Field Value

Block

snowCovered2 

public Block snowCovered2

Field Value

Block

snowCovered3 

public Block snowCovered3

Field Value

Block

snowLevel 

public float snowLevel

Field Value

float

waveFlagMinY 

protected float waveFlagMinY

Field Value

float

Properties

AllSidesOpaque

Sets the whole SideOpaque array to true

public bool AllSidesOpaque { get; set; }

Property Value

bool

ClimateColorMapForMap 

public virtual string ClimateColorMapForMap { get; }

Property Value

string

FirstTextureInventory

Returns the first textures in the TexturesInventory dictionary

public CompositeTexture FirstTextureInventory { get; }

Property Value

CompositeTexture

ForFluidsLayer

Return true if this block should be stored in the fluids layer in chunks instead of the solid blocks layer (e.g. water, flowing water, lake ice)

public virtual bool ForFluidsLayer { get; }

Property Value

bool

Id

Returns the block id

public override int Id { get; }

Property Value

int

ItemClass

Returns EnumItemClass.Block

public override EnumItemClass ItemClass { get; }

Property Value

EnumItemClass

PushVector

Entity pushing while an entity is inside this block. Read from attributes because i'm lazy.

public Vec3d PushVector { get; set; }

Property Value

Vec3d

RemapToLiquidsLayer

Return non-null if this block should have water (or ice) placed in its position in the fluids layer when updating from 1.16 to 1.17

public virtual string RemapToLiquidsLayer { get; }

Property Value

string

SeasonColorMapForMap 

public virtual string SeasonColorMapForMap { get; }

Property Value

string

Methods

Activate(IWorldAccessor, Caller, BlockSelection, ITreeAttribute)

When a Command Block, console command or (perhaps in future) non-player entity wants to activate this placed block

public virtual void Activate(IWorldAccessor world, Caller caller, BlockSelection blockSel, ITreeAttribute activationArgs = null)

Parameters

world IWorldAccessor
caller Caller
blockSel BlockSelection
activationArgs ITreeAttribute

AddExtraHeldItemInfoPostMaterial(ItemSlot, StringBuilder, IWorldAccessor)

Opportunity for blocks to add additional lines to the Held Item info prior to the behaviors output (such as nutrition properties or block reinforcement)

public virtual void AddExtraHeldItemInfoPostMaterial(ItemSlot inSlot, StringBuilder dsc, IWorldAccessor world)

Parameters

inSlot ItemSlot
dsc StringBuilder
world IWorldAccessor

AddMiningTierInfo(StringBuilder) 

public virtual void AddMiningTierInfo(StringBuilder sb)

Parameters

sb StringBuilder

AllowSnowCoverage(IWorldAccessor, BlockPos) 

public virtual bool AllowSnowCoverage(IWorldAccessor world, BlockPos blockPos)

Parameters

world IWorldAccessor
blockPos BlockPos

Returns

bool

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

Used by torches and other blocks to check if it can attach itself to that block

public virtual bool CanAttachBlockAt(IBlockAccessor blockAccessor, Block block, BlockPos pos, BlockFacing blockFace, Cuboidi attachmentArea = null)

Parameters

blockAccessor IBlockAccessor
block Block
pos BlockPos
blockFace BlockFacing
attachmentArea Cuboidi

Area of attachment of given face in voxel dimensions (0..15)

Returns

bool

CanCreatureSpawnOn(IBlockAccessor, BlockPos, EntityProperties, BaseSpawnConditions)

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

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

Parameters

blockAccessor IBlockAccessor
pos BlockPos
type EntityProperties
sc BaseSpawnConditions

Returns

bool

CanPlaceBlock(IWorldAccessor, IPlayer, BlockSelection, ref string)

Checks if this block does not intersect with something at given position

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

Parameters

world IWorldAccessor
byPlayer IPlayer
blockSel BlockSelection
failureCode string

Returns

bool

Clone()

Creates a deep copy of the block

public Block Clone()

Returns

Block

DetermineTopMiddlePos()

Used as base position for particles.

public virtual void DetermineTopMiddlePos()

DisplacesLiquids(IBlockAccessor, BlockPos)

Called for example when the player places a block inside a liquid block. Needs to return true if the liquid should get removed.

public virtual bool DisplacesLiquids(IBlockAccessor blockAccess, BlockPos pos)

Parameters

blockAccess IBlockAccessor
pos BlockPos

Returns

bool

DoEmitSideAo(IGeometryTester, BlockFacing) 

public virtual bool DoEmitSideAo(IGeometryTester caller, BlockFacing facing)

Parameters

caller IGeometryTester
facing BlockFacing

Returns

bool

DoEmitSideAoByFlag(IGeometryTester, Vec3iAndFacingFlags, int) 

public virtual bool DoEmitSideAoByFlag(IGeometryTester caller, Vec3iAndFacingFlags vec, int flags)

Parameters

caller IGeometryTester
vec Vec3iAndFacingFlags
flags int

Returns

bool

DoParticalSelection(IWorldAccessor, BlockPos)

If true, the player can select invdividual selection boxes of this block

public virtual bool DoParticalSelection(IWorldAccessor world, BlockPos pos)

Parameters

world IWorldAccessor
pos BlockPos

Returns

bool

DoPlaceBlock(IWorldAccessor, IPlayer, BlockSelection, ItemStack)

Called by TryPlaceBlock if placement is possible

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

Parameters

world IWorldAccessor
byPlayer IPlayer
blockSel BlockSelection
byItemStack ItemStack

Might be null

Returns

bool

ExplosionDropChance(IWorldAccessor, BlockPos, EnumBlastType)

Should return the chance of the block dropping its upon upon being exploded. Default behavior is to return BlockMaterialUtil.MaterialBlastDropChances(blastType, BlockMaterial);

public virtual double ExplosionDropChance(IWorldAccessor world, BlockPos pos, EnumBlastType blastType)

Parameters

world IWorldAccessor
pos BlockPos
blastType EnumBlastType

Returns

double

GetAmbientSoundStrength(IWorldAccessor, BlockPos)

If this block defines an ambient sounds, the intensity the ambient should be played at. Between 0 and 1. Return 0 to not play the ambient sound.

public virtual float GetAmbientSoundStrength(IWorldAccessor world, BlockPos pos)

Parameters

world IWorldAccessor
pos BlockPos

Returns

float

GetAttributes(IBlockAccessor, BlockPos)

Position-aware version of Attributes, for example can be used by BlockMultiblock

public virtual JsonObject GetAttributes(IBlockAccessor blockAccessor, BlockPos pos)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

Returns

JsonObject

GetBEBehavior<T>(BlockPos)

Alias of api.World.BlockAccessor.GetBlockEntity(pos)?.GetBehavior<T>()

public virtual T GetBEBehavior<T>(BlockPos pos) where T : BlockEntityBehavior

Parameters

pos BlockPos

Returns

T

Type Parameters

T

GetBehavior(Type, bool)

Returns the blocks behavior of given type, if it has such behavior

public BlockBehavior GetBehavior(Type type, bool withInheritance)

Parameters

type Type
withInheritance bool

Returns

BlockBehavior

GetBlastResistance(IWorldAccessor, BlockPos, Vec3f, EnumBlastType)

Should return the blocks blast resistance. Default behavior is to return BlockMaterialUtil.MaterialBlastResistance(blastType, BlockMaterial);

public virtual double GetBlastResistance(IWorldAccessor world, BlockPos pos, Vec3f blastDirectionVector, EnumBlastType blastType)

Parameters

world IWorldAccessor
pos BlockPos
blastDirectionVector Vec3f
blastType EnumBlastType

Returns

double

GetBlockEntity<T>(BlockSelection)

Alias of api.World.BlockAccessor.GetBlockEntity(blockSel.Position) as T

public virtual T GetBlockEntity<T>(BlockSelection blockSel) where T : BlockEntity

Parameters

blockSel BlockSelection

Returns

T

Type Parameters

T

GetBlockEntity<T>(BlockPos)

Alias of api.World.BlockAccessor.GetBlockEntity(position) as T

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

Parameters

position BlockPos

Returns

T

Type Parameters

T

GetBlockMaterial(IBlockAccessor, BlockPos, ItemStack)

Should return the blocks material Warning: This method is may get called in a background thread. Please make sure your code in here is thread safe.

public virtual EnumBlockMaterial GetBlockMaterial(IBlockAccessor blockAccessor, BlockPos pos, ItemStack stack = null)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

May be null and therfore stack is non-null

stack ItemStack

Returns

EnumBlockMaterial

GetCollisionBoxes(IBlockAccessor, BlockPos)

Returns the blocks collision box. Warning: This method may get called by different threads, so it has to be thread safe.

public virtual Cuboidf[] GetCollisionBoxes(IBlockAccessor blockAccessor, BlockPos pos)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

Returns

Cuboidf[]

GetColor(ICoreClientAPI, BlockPos)

Should return an RGB color for this block. Current use: In the world map. Default behavior: The 2 averaged pixels at 40%/40% ad 60%/60% position

public virtual int GetColor(ICoreClientAPI capi, BlockPos pos)

Parameters

capi ICoreClientAPI
pos BlockPos

Returns

int

GetColorWithoutTint(ICoreClientAPI, BlockPos)

Tint less version of GetColor. Used for map color export

public virtual int GetColorWithoutTint(ICoreClientAPI capi, BlockPos pos)

Parameters

capi ICoreClientAPI
pos BlockPos

Returns

int

GetDecal(IWorldAccessor, BlockPos, ITexPositionSource, ref MeshData, ref MeshData)

Called before a decal is created.

public virtual void GetDecal(IWorldAccessor world, BlockPos pos, ITexPositionSource decalTexSource, ref MeshData decalModelData, ref MeshData blockModelData)

Parameters

world IWorldAccessor
pos BlockPos
decalTexSource ITexPositionSource
decalModelData MeshData

The block model which need UV values for the decal texture

blockModelData MeshData

The original block model

GetDrops(IWorldAccessor, BlockPos, IPlayer, float)

Is called before a block is broken, should return what items this block should drop. Return null or empty array for no drops.

public virtual ItemStack[] GetDrops(IWorldAccessor world, BlockPos pos, IPlayer byPlayer, float dropQuantityMultiplier = 1)

Parameters

world IWorldAccessor
pos BlockPos
byPlayer IPlayer
dropQuantityMultiplier float

Returns

ItemStack[]

GetDropsForHandbook(ItemStack, IPlayer)

Should return all of the blocks drops for display in the handbook

public virtual BlockDropItemStack[] GetDropsForHandbook(ItemStack handbookStack, IPlayer forPlayer)

Parameters

handbookStack ItemStack
forPlayer IPlayer

Returns

BlockDropItemStack[]

GetHandbookDropsFromBreakDrops(ItemStack, IPlayer)

Helper method for a number of blocks

protected virtual BlockDropItemStack[] GetHandbookDropsFromBreakDrops(ItemStack handbookStack, IPlayer forPlayer)

Parameters

handbookStack ItemStack
forPlayer IPlayer

Returns

BlockDropItemStack[]

GetHeatRetention(BlockPos, BlockFacing)

Return a positive integer if the block retains heat (for warm rooms or greenhouses) or a negative integer if it preserves cool (for cellars)

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

Parameters

pos BlockPos
facing BlockFacing

Returns

int

GetHeldItemInfo(ItemSlot, StringBuilder, IWorldAccessor, bool)

Called by the inventory system when you hover over an item stack. This is the text that is getting displayed.

public override void GetHeldItemInfo(ItemSlot inSlot, StringBuilder dsc, IWorldAccessor world, bool withDebugInfo)

Parameters

inSlot ItemSlot
dsc StringBuilder
world IWorldAccessor
withDebugInfo bool

GetHorizontallyFlippedBlockCode(EnumAxis)

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)

Parameters

axis EnumAxis

Returns

AssetLocation

GetInterface<T>(IWorldAccessor, BlockPos)

Returns instance of class that implements this interface in the following order

  1. Block (returns itself)
  2. BlockBehavior (returns on of our own behavior)
  3. BlockEntity
  4. BlockEntityBehavior
public virtual T GetInterface<T>(IWorldAccessor world, BlockPos pos) where T : class

Parameters

world IWorldAccessor
pos BlockPos

Returns

T

Type Parameters

T

GetLightAbsorption(IBlockAccessor, BlockPos) 

public virtual int GetLightAbsorption(IBlockAccessor blockAccessor, BlockPos pos)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

Returns

int

GetLightAbsorption(IWorldChunk, BlockPos) 

public virtual int GetLightAbsorption(IWorldChunk chunk, BlockPos pos)

Parameters

chunk IWorldChunk
pos BlockPos

Returns

int

GetLiquidBarrierHeightOnSide(BlockFacing, BlockPos)

Return a decimal between 0.0 and 1.0 indicating - if this block is solid enough to block liquid flow on that side - how high the barrier is

public virtual float GetLiquidBarrierHeightOnSide(BlockFacing face, BlockPos pos)

Parameters

face BlockFacing
pos BlockPos

Returns

float

GetLiquidCode(IBlockAccessor, BlockPos)

If this block is or contains a liquid, it should return the code of it. Used for example by farmland to check if a nearby block is water

public virtual string GetLiquidCode(IBlockAccessor blockAccessor, BlockPos pos)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

Returns

string

GetParticleBreakBox(IBlockAccessor, BlockPos, BlockFacing)

The cuboid used to determine where to spawn particles when breaking the block

public virtual Cuboidf GetParticleBreakBox(IBlockAccessor blockAccess, BlockPos pos, BlockFacing facing)

Parameters

blockAccess IBlockAccessor
pos BlockPos
facing BlockFacing

Returns

Cuboidf

GetParticleCollisionBoxes(IBlockAccessor, BlockPos)

Returns the blocks particle collision box. Warning: This method may get called by different threads, so it has to be thread safe.

public virtual Cuboidf[] GetParticleCollisionBoxes(IBlockAccessor blockAccessor, BlockPos pos)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

Returns

Cuboidf[]

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)

Called by the block info HUD for display the interaction help besides the crosshair

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

Parameters

world IWorldAccessor
selection BlockSelection
forPlayer IPlayer

Returns

WorldInteraction[]

GetPlacedBlockName(IWorldAccessor, BlockPos)

Called by the block info HUD for displaying the blocks name

public virtual string GetPlacedBlockName(IWorldAccessor world, BlockPos pos)

Parameters

world IWorldAccessor
pos BlockPos

Returns

string

GetRandomColor(ICoreClientAPI, ItemStack)

Should return a random pixel within the items/blocks texture

public override int GetRandomColor(ICoreClientAPI capi, ItemStack stack)

Parameters

capi ICoreClientAPI
stack ItemStack

Returns

int

GetRandomColor(ICoreClientAPI, BlockPos, BlockFacing, int)

Should return the color to be used for the block particle coloring

public virtual int GetRandomColor(ICoreClientAPI capi, BlockPos pos, BlockFacing facing, int rndIndex = -1)

Parameters

capi ICoreClientAPI
pos BlockPos
facing BlockFacing
rndIndex int

Returns

int

GetResistance(IBlockAccessor, BlockPos)

Should return the blocks resistance to breaking

public virtual float GetResistance(IBlockAccessor blockAccessor, BlockPos pos)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

Returns

float

GetRetention(BlockPos, BlockFacing, EnumRetentionType)

Return a positive integer if the block retains something, e.g. (for warm rooms or greenhouses) or a negative integer if something can pass through, e.g. cool for cellars

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

Parameters

pos BlockPos
facing BlockFacing
type EnumRetentionType

Returns

int

GetRotatedBlockCode(int)

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)

Parameters

angle int

Returns

AssetLocation

GetSelectionBoxes(IBlockAccessor, BlockPos)

Returns the blocks selection boxes at this position in the world.

public virtual Cuboidf[] GetSelectionBoxes(IBlockAccessor blockAccessor, BlockPos pos)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

Returns

Cuboidf[]

GetSelectionColor(ICoreClientAPI, BlockPos) 

public virtual Vec4f GetSelectionColor(ICoreClientAPI capi, BlockPos pos)

Parameters

capi ICoreClientAPI
pos BlockPos

Returns

Vec4f

GetSnowCoveredVariant(BlockPos, float)

Should return the snow covered block code for given snow level. Return null if snow cover is not supported for this block. If not overridden, it will check if Variant["cover"] exists and return its snow covered variant.

public virtual Block GetSnowCoveredVariant(BlockPos pos, float snowLevel)

Parameters

pos BlockPos
snowLevel float

Returns

Block

GetSnowLevel(BlockPos) 

public virtual float GetSnowLevel(BlockPos pos)

Parameters

pos BlockPos

Returns

float

GetSounds(IBlockAccessor, BlockSelection, ItemStack)

Should returns the blocks sounds

public virtual BlockSounds GetSounds(IBlockAccessor blockAccessor, BlockSelection blockSel, ItemStack stack = null)

Parameters

blockAccessor IBlockAccessor
blockSel BlockSelection
stack ItemStack

Returns

BlockSounds

GetSounds(IBlockAccessor, BlockPos, ItemStack) 

[Obsolete("Use GetSounds with BlockSelection instead")]
public virtual BlockSounds GetSounds(IBlockAccessor blockAccessor, BlockPos pos, ItemStack stack = null)

Parameters

blockAccessor IBlockAccessor
pos BlockPos
stack ItemStack

Returns

BlockSounds

GetTraversalCost(BlockPos, EnumAICreatureType)

The cost of traversing this block as part of the AI pathfinding system. Return a negative value to prefer traversal of a block, return a positive value to avoid traversal of this block. A value over 10000f is considered impassable. Default value is 0

public virtual float GetTraversalCost(BlockPos pos, EnumAICreatureType creatureType)

Parameters

pos BlockPos
creatureType EnumAICreatureType

Returns

float

GetVerticallyFlippedBlockCode()

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()

Returns

AssetLocation

HasBehavior(string, IClassRegistryAPI)

Returns true if the block has given behavior

public override bool HasBehavior(string type, IClassRegistryAPI classRegistry)

Parameters

type string
classRegistry IClassRegistryAPI

Returns

bool

HasBehavior(Type, bool)

Returns true if the block has given behavior

public override bool HasBehavior(Type type, bool withInheritance = false)

Parameters

type Type
withInheritance bool

Returns

bool

HasBehavior<T>(bool)

Returns true if the block has given block behavior OR collectible behavior

public override bool HasBehavior<T>(bool withInheritance = false) where T : CollectibleBehavior

Parameters

withInheritance bool

Returns

bool

Type Parameters

T

HasBlockBehavior<T>(bool)

Returns true if the block has given block behavior

public bool HasBlockBehavior<T>(bool withInheritance = false) where T : BlockBehavior

Parameters

withInheritance bool

Returns

bool

Type Parameters

T

IsClimbable(BlockPos) 

public virtual bool IsClimbable(BlockPos pos)

Parameters

pos BlockPos

Returns

bool

IsReplacableBy(Block)

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)

Parameters

block Block

Returns

bool

LoadTextureSubIdForBlockColor() 

public virtual void LoadTextureSubIdForBlockColor()

OnAsyncClientParticleTick(IAsyncParticleManager, BlockPos, float, float)

Called evey 25ms if the block is in range (32 blocks) and block returned true on ShouldReceiveClientGameTicks(). Takes a few seconds for the game to register the block.

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

Parameters

manager IAsyncParticleManager
pos BlockPos
windAffectednessAtPos float
secondsTicking float

OnBeingLookedAt(IPlayer, BlockSelection, bool)

Called by the server and the client when the player currently looks at this block. Gets called continously every tick.

public virtual void OnBeingLookedAt(IPlayer byPlayer, BlockSelection blockSel, bool firstTick)

Parameters

byPlayer IPlayer
blockSel BlockSelection
firstTick bool

True when previous tick the player looked at a different block. You can use it to make an efficient, single-event lookat trigger

OnBlockBroken(IWorldAccessor, BlockPos, IPlayer, float)

Called when a survival player has broken the block. This method needs to remove the block.

public virtual void OnBlockBroken(IWorldAccessor world, BlockPos pos, IPlayer byPlayer, float dropQuantityMultiplier = 1)

Parameters

world IWorldAccessor
pos BlockPos
byPlayer IPlayer
dropQuantityMultiplier float

OnBlockExploded(IWorldAccessor, BlockPos, BlockPos, EnumBlastType)

Called when the block was blown up by explosives

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

Parameters

world IWorldAccessor
pos BlockPos
explosionCenter BlockPos
blastType EnumBlastType

OnBlockInteractCancel(float, IWorldAccessor, IPlayer, BlockSelection, EnumItemUseCancelReason)

When the player released the right mouse button. Return false to deny the cancellation (= will keep using the block until OnBlockInteractStep returns false).

public virtual bool OnBlockInteractCancel(float secondsUsed, IWorldAccessor world, IPlayer byPlayer, BlockSelection blockSel, EnumItemUseCancelReason cancelReason)

Parameters

secondsUsed float
world IWorldAccessor
byPlayer IPlayer
blockSel BlockSelection
cancelReason EnumItemUseCancelReason

Returns

bool

OnBlockInteractStart(IWorldAccessor, IPlayer, BlockSelection)

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)

Parameters

world IWorldAccessor
byPlayer IPlayer
blockSel BlockSelection

Returns

bool

False if the interaction should be stopped. True if the interaction should continue. If you return false, the interaction will not be synced to the server.

OnBlockInteractStep(float, IWorldAccessor, IPlayer, BlockSelection)

Called every frame while the player is using this block. Return false to stop the interaction.

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

Parameters

secondsUsed float
world IWorldAccessor
byPlayer IPlayer
blockSel BlockSelection

Returns

bool

OnBlockInteractStop(float, IWorldAccessor, IPlayer, BlockSelection)

Called when the player successfully completed the using action, always called once an interaction is over

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

Parameters

secondsUsed float
world IWorldAccessor
byPlayer IPlayer
blockSel BlockSelection

OnBlockPlaced(IWorldAccessor, BlockPos, ItemStack)

Always called when a block has been placed 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

public virtual void OnBlockPlaced(IWorldAccessor world, BlockPos blockPos, ItemStack byItemStack = null)

Parameters

world IWorldAccessor
blockPos BlockPos
byItemStack ItemStack

May be null!

OnBlockRemoved(IWorldAccessor, BlockPos)

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

public virtual void OnBlockRemoved(IWorldAccessor world, BlockPos pos)

Parameters

world IWorldAccessor
pos BlockPos

OnBrokenAsDecor(IWorldAccessor, BlockPos, BlockFacing) 

public virtual void OnBrokenAsDecor(IWorldAccessor world, BlockPos pos, BlockFacing side)

Parameters

world IWorldAccessor
pos BlockPos
side BlockFacing

OnCollectTextures(ICoreAPI, ITextureLocationDictionary)

Called by the texture atlas manager when building up the block atlas. Has to add all of the blocks texture

public virtual void OnCollectTextures(ICoreAPI api, ITextureLocationDictionary textureDict)

Parameters

api ICoreAPI
textureDict ITextureLocationDictionary

OnCreatedByCrafting(ItemSlot[], ItemSlot, GridRecipe)

Called when a matching grid recipe has been found and an item is placed into the crafting output slot (which is still before the player clicks on the output slot to actually craft the item and consume the ingredients)

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

Parameters

allInputslots ItemSlot[]
outputSlot ItemSlot
byRecipe GridRecipe

OnDecalTesselation(IWorldAccessor, MeshData, BlockPos) 

public virtual void OnDecalTesselation(IWorldAccessor world, MeshData decalMesh, BlockPos pos)

Parameters

world IWorldAccessor
decalMesh MeshData
pos BlockPos

OnEntityCollide(IWorldAccessor, Entity, BlockPos, BlockFacing, Vec3d, bool)

Whenever an entity collides with the collision box of the block

public virtual void OnEntityCollide(IWorldAccessor world, Entity entity, BlockPos pos, BlockFacing facing, Vec3d collideSpeed, bool isImpact)

Parameters

world IWorldAccessor
entity Entity
pos BlockPos
facing BlockFacing
collideSpeed Vec3d
isImpact bool

OnEntityInside(IWorldAccessor, Entity, BlockPos)

When an entity is inside a block 1x1x1 space, independent of of its selection box or collision box

public virtual void OnEntityInside(IWorldAccessor world, Entity entity, BlockPos pos)

Parameters

world IWorldAccessor
entity Entity
pos BlockPos

OnFallOnto(IWorldAccessor, BlockPos, Block, TreeAttribute)

Called when a falling block falls onto this one. Return true to cancel default behavior.

public virtual bool OnFallOnto(IWorldAccessor world, BlockPos pos, Block block, TreeAttribute blockEntityAttributes)

Parameters

world IWorldAccessor
pos BlockPos
block Block
blockEntityAttributes TreeAttribute

Returns

bool

OnGettingBroken(IPlayer, BlockSelection, ItemSlot, float, float, int)

Player is breaking this block. Has to reduce remainingResistance by the amount of time it should be broken. This method is called only client side, every 40ms during breaking.

public virtual float OnGettingBroken(IPlayer player, BlockSelection blockSel, ItemSlot itemslot, float remainingResistance, float dt, int counter)

Parameters

player IPlayer
blockSel BlockSelection
itemslot ItemSlot

The item the player currently has in his hands

remainingResistance float

how many seconds was left until the block breaks fully

dt float

seconds passed since last render frame

counter int

Total count of hits (every 40ms)

Returns

float

how many seconds now left until the block breaks fully. If a value equal to or below 0 is returned, OnBlockBroken() will get called.

OnInstancedTesselation(int, BlockPos, Block[], int, out int) 

public virtual int OnInstancedTesselation(int light, BlockPos pos, Block[] chunkExtBlocks, int extIndex3d, out int sideDisableWindwave)

Parameters

light int
pos BlockPos
chunkExtBlocks Block[]
extIndex3d int
sideDisableWindwave int

Returns

int

OnJsonTesselation(ref MeshData, ref int[], BlockPos, Block[], int)

If this block uses drawtype json, this method will be called everytime a chunk containing this block is tesselated.

public virtual void OnJsonTesselation(ref MeshData sourceMesh, ref int[] lightRgbsByCorner, BlockPos pos, Block[] chunkExtBlocks, int extIndex3d)

Parameters

sourceMesh MeshData
lightRgbsByCorner int[]

Emitted light from this block

pos BlockPos
chunkExtBlocks Block[]

Optional, fast way to look up a direct neighbouring block. This is an array of the current chunk blocks, also including all direct neighbours, so it's a 34 x 34 x 34 block list. extIndex3d is the index of the current Block in this array. Use extIndex3d+TileSideEnum.MoveIndex[tileSide] to move around in the array.

extIndex3d int

See description of chunkExtBlocks

OnLoaded(ICoreAPI)

Called when this block was loaded by the server or the client

public override void OnLoaded(ICoreAPI api)

Parameters

api ICoreAPI

OnNeighbourBlockChange(IWorldAccessor, BlockPos, BlockPos)

Called when any of its 6 neighbour blocks has been changed

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

Parameters

world IWorldAccessor
pos BlockPos
neibpos BlockPos

OnPickBlock(IWorldAccessor, BlockPos)

When the player has presed the middle mouse click on the block

public virtual ItemStack OnPickBlock(IWorldAccessor world, BlockPos pos)

Parameters

world IWorldAccessor
pos BlockPos

Returns

ItemStack

OnServerGameTick(IWorldAccessor, BlockPos, object)

Called by the main server thread if and only if this block returned true in ShouldReceiveServerGameTicks.

public virtual void OnServerGameTick(IWorldAccessor world, BlockPos pos, object extra = null)

Parameters

world IWorldAccessor
pos BlockPos

The position of this block

extra object

The value set for the 'extra' parameter when ShouldReceiveGameTicks was called.

PerformSnowLevelUpdate(IBulkBlockAccessor, BlockPos, Block, float)

Called in the servers main thread

public virtual void PerformSnowLevelUpdate(IBulkBlockAccessor ba, BlockPos pos, Block newBlock, float snowLevel)

Parameters

ba IBulkBlockAccessor
pos BlockPos
newBlock Block

The block as returned by your GetSnowLevelUpdateBlock() method

snowLevel float

RandomSoundPitch(IWorldAccessor) 

public virtual float RandomSoundPitch(IWorldAccessor world)

Parameters

world IWorldAccessor

Returns

float

ShouldMergeFace(int, Block, int)

This method gets called when facecull mode is set to 'Callback'. Curently used for custom behaviors when merging ice

public virtual bool ShouldMergeFace(int facingIndex, Block neighbourBlock, int intraChunkIndex3d)

Parameters

facingIndex int

The index of the BlockFacing face of this block being tested

neighbourBlock Block

The neighbouring block

intraChunkIndex3d int

The position index within the chunk (z * 32 * 32 + y * 32 + x): the BlockEntity can be obtained using this if necessary

Returns

bool

ShouldPlayAmbientSound(IWorldAccessor, BlockPos) 

[Obsolete("Use GetAmbientsoundStrength() instead. Method will be removed in 1.21")]
public virtual bool ShouldPlayAmbientSound(IWorldAccessor world, BlockPos pos)

Parameters

world IWorldAccessor
pos BlockPos

Returns

bool

ShouldReceiveClientParticleTicks(IWorldAccessor, IPlayer, BlockPos, out bool)

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.

public virtual bool ShouldReceiveClientParticleTicks(IWorldAccessor world, IPlayer player, BlockPos pos, out bool isWindAffected)

Parameters

world IWorldAccessor
player IPlayer
pos BlockPos
isWindAffected bool

Returns

bool

ShouldReceiveServerGameTicks(IWorldAccessor, BlockPos, Random, out object)

Called every interval specified in Server.Config.RandomTickInterval. Defaults to 50ms. This method is called on a separate server thread. This should be considered when deciding how to access blocks. If true is returned, the server will call OnServerGameTick on the main thread passing the BlockPos and the 'extra' object if specified. The 'extra' parameter is meant to prevent duplicating lookups and other calculations when OnServerGameTick is called.

public virtual bool ShouldReceiveServerGameTicks(IWorldAccessor world, BlockPos pos, Random offThreadRandom, out object extra)

Parameters

world IWorldAccessor
pos BlockPos

The position of this block

offThreadRandom Random

If you do anything with random inside this method, don't use world.Rand because Random its not thread safe, use this or create your own instance

extra object

Optional parameter to set if you need to pass additional data to the OnServerGameTick method

Returns

bool

SideIsSolid(IBlockAccessor, BlockPos, int)

Is the side solid or almost fully solid (in the case of chiselled blocks)? Called for example when deciding to place loose stones or boulders above this during worldgen

public virtual bool SideIsSolid(IBlockAccessor blockAccess, BlockPos pos, int faceIndex)

Parameters

blockAccess IBlockAccessor
pos BlockPos
faceIndex int

Returns

bool

SideIsSolid(BlockPos, int)

Does the side APPEAR fully solid? Called for example when deciding to render water edges at a position, or not Note: Worldgen code uses the blockAccessor-aware overload of this method

public virtual bool SideIsSolid(BlockPos pos, int faceIndex)

Parameters

pos BlockPos
faceIndex int

Returns

bool

SpawnBlockBrokenParticles(BlockPos) 

public void SpawnBlockBrokenParticles(BlockPos pos)

Parameters

pos BlockPos

SuggestedHVOrientation(IPlayer, BlockSelection)

Returns a horizontal and vertical orientation which should be used for oriented blocks like stairs during placement.

public static BlockFacing[] SuggestedHVOrientation(IPlayer byPlayer, BlockSelection blockSel)

Parameters

byPlayer IPlayer
blockSel BlockSelection

Returns

BlockFacing[]

ToString()

Simple string representation for debugging

public override string ToString()

Returns

string

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

Called when the player attempts to place this block

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

Parameters

world IWorldAccessor
byPlayer IPlayer
itemstack ItemStack
blockSel BlockSelection
failureCode string

If you return false, set this value to a code why it cannot be placed. Its used for the ingame error overlay. Set to "ignore" to not trigger an error

Returns

bool

TryPlaceBlockForWorldGen(IBlockAccessor, BlockPos, BlockFacing, IRandom, BlockPatchAttributes)

Currently used for wildvines and saguaro cactus

public virtual bool TryPlaceBlockForWorldGen(IBlockAccessor blockAccessor, BlockPos pos, BlockFacing onBlockFace, IRandom worldgenRandom, BlockPatchAttributes attributes = null)

Parameters

blockAccessor IBlockAccessor
pos BlockPos
onBlockFace BlockFacing
worldgenRandom IRandom
attributes BlockPatchAttributes

Returns

bool

TryPlaceBlockForWorldGenUnderwater(IBlockAccessor, BlockPos, BlockFacing, IRandom, int, int, BlockPatchAttributes) 

public virtual bool TryPlaceBlockForWorldGenUnderwater(IBlockAccessor blockAccessor, BlockPos pos, BlockFacing onBlockFace, IRandom worldgenRandom, int minWaterDepth, int maxWaterDepth, BlockPatchAttributes attributes = null)

Parameters

blockAccessor IBlockAccessor
pos BlockPos
onBlockFace BlockFacing
worldgenRandom IRandom
minWaterDepth int
maxWaterDepth int
attributes BlockPatchAttributes

Returns

bool