Table of Contents

Class CollectibleObject

Namespace
Vintagestory.API.Common
Assembly
VintagestoryAPI.dll

Contains all properties shared by Blocks and Items

public abstract class CollectibleObject : RegistryObject
Inheritance
CollectibleObject
Derived
Inherited Members

Fields

AttackPower

How much damage this collectible deals when used as a weapon

public float AttackPower

Field Value

float

AttackRange

Until how for away can you attack entities using this collectibe

public float AttackRange

Field Value

float

Attributes

Custom Attributes that's always assiociated with this item

public JsonObject Attributes

Field Value

JsonObject

CollectibleBehaviors

Modifiers that can alter the behavior of the item or block, mostly for held interaction

public CollectibleBehavior[] CollectibleBehaviors

Field Value

CollectibleBehavior[]

CombustibleProps

Information about the burnable states

public CombustibleProperties CombustibleProps

Field Value

CombustibleProperties

CreativeInventoryStacks

If you want to add itemstacks with custom attributes to the creative inventory, add them to this list

public CreativeTabAndStackList[] CreativeInventoryStacks

Field Value

CreativeTabAndStackList[]

CreativeInventoryTabs

List of creative tabs in which this collectible should appear in

public string[] CreativeInventoryTabs

Field Value

string[]

CrushingProps

If set, the collectible can be crushed into something else

public CrushingProperties CrushingProps

Field Value

CrushingProperties

DamagedBy

From which damage sources does the item takes durability damage

public EnumItemDamageSource[] DamagedBy

Field Value

EnumItemDamageSource[]

Dimensions

Physical size of this collectible, 0.5 x 0.5 x 0.5 meters by default

public Size3f Dimensions

Field Value

Size3f

Durability

How many uses does this collectible has when being used. Item disappears at durability 0

public int Durability

Field Value

int

FpHandTransform

Used for scaling, rotation or offseting the block when rendered in the first person mode hand

public ModelTransform FpHandTransform

Field Value

ModelTransform

GrindingProps

If set, the collectible can be ground into something else

public GrindingProperties GrindingProps

Field Value

GrindingProperties

GroundTransform

Used for scaling, rotation or offseting the rendered as a dropped item on the ground

public ModelTransform GroundTransform

Field Value

ModelTransform

GuiTransform

Used for scaling, rotation or offseting the block when rendered in guis

public ModelTransform GuiTransform

Field Value

ModelTransform

HeldLeftReadyAnimation 

public string HeldLeftReadyAnimation

Field Value

string

HeldLeftTpIdleAnimation

The animation to play in 3rd person mod when holding this collectible in the left hand

public string HeldLeftTpIdleAnimation

Field Value

string

HeldPriorityInteract

If true, when the player holds the sneak key and right clicks with this item in hand, calls OnHeldInteractStart first. Without it, the order is reversed. Takes precedence over priority interact placed blocks.

public bool HeldPriorityInteract

Field Value

bool

HeldRightReadyAnimation 

public string HeldRightReadyAnimation

Field Value

string

HeldRightTpIdleAnimation

The animation to play in 3rd person mod when holding this collectible in the right hand

public string HeldRightTpIdleAnimation

Field Value

string

HeldSounds 

public HeldSounds HeldSounds

Field Value

HeldSounds

HeldTpHitAnimation

The animation to play in 3rd person mod when hitting with this collectible

public string HeldTpHitAnimation

Field Value

string

HeldTpUseAnimation

The animation to play in 3rd person mod when using this collectible

public string HeldTpUseAnimation

Field Value

string

LightHsv

For light emitting collectibles: hue, saturation and brightness value

public byte[] LightHsv

Field Value

byte[]

LiquidSelectable

When true, liquids become selectable to the player when being held in hands

public bool LiquidSelectable

Field Value

bool

MaterialDensity

Determines on whether an object floats on liquids or not. Water has a density of 1000

public int MaterialDensity

Field Value

int

MatterState

Liquids are handled and rendered differently than solid blocks.

public EnumMatterState MatterState

Field Value

EnumMatterState

MaxStackSize

Max amount of collectible that one default inventory slot can hold

public int MaxStackSize

Field Value

int

MiningSpeed

Modifies how fast the player can break a block when holding this item

public Dictionary<EnumBlockMaterial, float> MiningSpeed

Field Value

Dictionary<EnumBlockMaterial, float>

NutritionProps

Information about the nutrition states

public FoodNutritionProperties NutritionProps

Field Value

FoodNutritionProperties

ParticleProperties

Particles that should spawn in regular intervals from this block or item when held in hands

public AdvancedParticleProperties[] ParticleProperties

Field Value

AdvancedParticleProperties[]

RenderAlphaTest

Alpha test value for rendering in gui, fp hand, tp hand or on the ground

public float RenderAlphaTest

Field Value

float

StorageFlags

Determines in which kind of bags the item can be stored in

public EnumItemStorageFlags StorageFlags

Field Value

EnumItemStorageFlags

Tool

If set, this item will be classified as given tool

public EnumTool? Tool

Field Value

EnumTool?

ToolTier

What tier this block can mine when held in hands

public int ToolTier

Field Value

int

TopMiddlePos

The origin point from which particles are being spawned

public Vec3f TopMiddlePos

Field Value

Vec3f

TpHandTransform

Used for scaling, rotation or offseting the block when rendered in the third person mode hand

public ModelTransform TpHandTransform

Field Value

ModelTransform

TpOffHandTransform

Used for scaling, rotation or offseting the block when rendered in the third person mode offhand

public ModelTransform TpOffHandTransform

Field Value

ModelTransform

TransitionableProps

Information about the transitionable states

public TransitionableProperties[] TransitionableProps

Field Value

TransitionableProperties[]

api

The api object, assigned during OnLoaded

protected ICoreAPI api

Field Value

ICoreAPI

Properties

Id

The block or item id

public abstract int Id { get; }

Property Value

int

IsMissing

This value is set the the BlockId or ItemId-Remapper if it encounters a block/item in the savegame, but no longer exists as a loaded block/item

public bool IsMissing { get; set; }

Property Value

bool

ItemClass

Block or Item?

public abstract EnumItemClass ItemClass { get; }

Property Value

EnumItemClass

MiningTier 

[Obsolete("Use tool tier")]
public int MiningTier { get; set; }

Property Value

int

Methods

AppendPerishableInfoText(ItemSlot, StringBuilder, IWorldAccessor) 

public virtual float AppendPerishableInfoText(ItemSlot inSlot, StringBuilder dsc, IWorldAccessor world)

Parameters

inSlot ItemSlot
dsc StringBuilder
world IWorldAccessor

Returns

float

AppendPerishableInfoText(ItemSlot, StringBuilder, IWorldAccessor, TransitionState, bool) 

protected virtual float AppendPerishableInfoText(ItemSlot inSlot, StringBuilder dsc, IWorldAccessor world, TransitionState state, bool nowSpoiling)

Parameters

inSlot ItemSlot
dsc StringBuilder
world IWorldAccessor
state TransitionState
nowSpoiling bool

Returns

float

CanBePlacedInto(ItemStack, ItemSlot)

Should return true if the stack can be placed into given slot

public virtual bool CanBePlacedInto(ItemStack stack, ItemSlot slot)

Parameters

stack ItemStack
slot ItemSlot

Returns

bool

CanSmelt(IWorldAccessor, ISlotProvider, ItemStack, ItemStack)

Should return true if this collectible is smeltable in an open fire

public virtual bool CanSmelt(IWorldAccessor world, ISlotProvider cookingSlotsProvider, ItemStack inputStack, ItemStack outputStack)

Parameters

world IWorldAccessor
cookingSlotsProvider ISlotProvider
inputStack ItemStack
outputStack ItemStack

Returns

bool

CanSpoil(ItemStack)

Returns true if the stack can spoil

public virtual bool CanSpoil(ItemStack itemstack)

Parameters

itemstack ItemStack

Returns

bool

CarryOverFreshness(ICoreAPI, ItemSlot, ItemStack, TransitionableProperties) 

public static void CarryOverFreshness(ICoreAPI api, ItemSlot inputSlot, ItemStack outputStack, TransitionableProperties perishProps)

Parameters

api ICoreAPI
inputSlot ItemSlot
outputStack ItemStack
perishProps TransitionableProperties

CarryOverFreshness(ICoreAPI, ItemSlot[], ItemStack[], TransitionableProperties) 

public static void CarryOverFreshness(ICoreAPI api, ItemSlot[] inputSlots, ItemStack[] outStacks, TransitionableProperties perishProps)

Parameters

api ICoreAPI
inputSlots ItemSlot[]
outStacks ItemStack[]
perishProps TransitionableProperties

ConsumeCraftingIngredients(ItemSlot[], ItemSlot, GridRecipe)

Called after the player has taken out the item from the output slot

public virtual bool ConsumeCraftingIngredients(ItemSlot[] slots, ItemSlot outputSlot, GridRecipe matchingRecipe)

Parameters

slots ItemSlot[]
outputSlot ItemSlot
matchingRecipe GridRecipe

Returns

bool

true to prevent default ingredient consumption

DamageItem(IWorldAccessor, Entity, ItemSlot, int)

Causes the item to be damaged. Will play a breaking sound and removes the itemstack if no more durability is left

public virtual void DamageItem(IWorldAccessor world, Entity byEntity, ItemSlot itemslot, int amount = 1)

Parameters

world IWorldAccessor
byEntity Entity
itemslot ItemSlot
amount int

Amount of damage

DoSmelt(IWorldAccessor, ISlotProvider, ItemSlot, ItemSlot)

Transform the item to it's smelted variant

public virtual void DoSmelt(IWorldAccessor world, ISlotProvider cookingSlotsProvider, ItemSlot inputSlot, ItemSlot outputSlot)

Parameters

world IWorldAccessor
cookingSlotsProvider ISlotProvider
inputSlot ItemSlot
outputSlot ItemSlot

Equals(ItemStack, ItemStack, params string[])

Should return true if given stacks are equal, ignoring their stack size.

public virtual bool Equals(ItemStack thisStack, ItemStack otherStack, params string[] ignoreAttributeSubTrees)

Parameters

thisStack ItemStack
otherStack ItemStack
ignoreAttributeSubTrees string[]

Returns

bool

GeldHeldFpHitAnimation(ItemSlot, Entity)

Not implemented yet

[Obsolete]
public virtual ModelTransformKeyFrame[] GeldHeldFpHitAnimation(ItemSlot slot, Entity byEntity)

Parameters

slot ItemSlot
byEntity Entity

Returns

ModelTransformKeyFrame[]

GetAttackPower(IItemStack)

The amount of damage dealt when used as a weapon

public virtual float GetAttackPower(IItemStack withItemStack)

Parameters

withItemStack IItemStack

Returns

float

GetAttackRange(IItemStack)

The the attack range when used as a weapon

public virtual float GetAttackRange(IItemStack withItemStack)

Parameters

withItemStack IItemStack

Returns

float

GetBehavior(Type)

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

public CollectibleBehavior GetBehavior(Type type)

Parameters

type Type

Returns

CollectibleBehavior

GetBehavior(CollectibleBehavior[], Type, bool) 

protected virtual CollectibleBehavior GetBehavior(CollectibleBehavior[] fromList, Type type, bool withInheritance)

Parameters

fromList CollectibleBehavior[]
type Type
withInheritance bool

Returns

CollectibleBehavior

GetBehavior<T>()

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

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

Returns

T

Type Parameters

T

GetCollectibleBehavior(Type, bool)

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

public CollectibleBehavior GetCollectibleBehavior(Type type, bool withInheritance)

Parameters

type Type
withInheritance bool

Returns

CollectibleBehavior

GetCollectibleBehavior<T>(bool) 

public T GetCollectibleBehavior<T>(bool withInheritance) where T : CollectibleBehavior

Parameters

withInheritance bool

Returns

T

Type Parameters

T

GetDurability(IItemStack) 

[Obsolete("Use GetMaxDurability instead")]
public virtual int GetDurability(IItemStack itemstack)

Parameters

itemstack IItemStack

Returns

int

GetHandBookStacks(ICoreClientAPI) 

public virtual List<ItemStack> GetHandBookStacks(ICoreClientAPI capi)

Parameters

capi ICoreClientAPI

Returns

List<ItemStack>

GetHashCode()

For blocks and items, the hashcode is the id - useful when building HashSets

public override int GetHashCode()

Returns

int

GetHeldInteractionHelp(ItemSlot)

Interaction help thats displayed above the hotbar, when the player puts this item/block in his active hand slot

public virtual WorldInteraction[] GetHeldInteractionHelp(ItemSlot inSlot)

Parameters

inSlot ItemSlot

Returns

WorldInteraction[]

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 virtual void GetHeldItemInfo(ItemSlot inSlot, StringBuilder dsc, IWorldAccessor world, bool withDebugInfo)

Parameters

inSlot ItemSlot
dsc StringBuilder
world IWorldAccessor
withDebugInfo bool

GetHeldItemName(ItemStack)

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

public virtual string GetHeldItemName(ItemStack itemStack)

Parameters

itemStack ItemStack

Returns

string

GetHeldReadyAnimation(ItemSlot, Entity, EnumHand)

Called when an entity holds this item in hands in 3rd person mode

public virtual string GetHeldReadyAnimation(ItemSlot activeHotbarSlot, Entity forEntity, EnumHand hand)

Parameters

activeHotbarSlot ItemSlot
forEntity Entity
hand EnumHand

Returns

string

GetHeldTpHitAnimation(ItemSlot, Entity)

Called when an entity uses this item to hit something in 3rd person mode

public virtual string GetHeldTpHitAnimation(ItemSlot slot, Entity byEntity)

Parameters

slot ItemSlot
byEntity Entity

Returns

string

GetHeldTpIdleAnimation(ItemSlot, Entity, EnumHand)

Called when an entity holds this item in hands in 3rd person mode

public virtual string GetHeldTpIdleAnimation(ItemSlot activeHotbarSlot, Entity forEntity, EnumHand hand)

Parameters

activeHotbarSlot ItemSlot
forEntity Entity
hand EnumHand

Returns

string

GetHeldTpUseAnimation(ItemSlot, Entity)

Called when an entity holds this item in hands in 3rd person mode

public virtual string GetHeldTpUseAnimation(ItemSlot activeHotbarSlot, Entity forEntity)

Parameters

activeHotbarSlot ItemSlot
forEntity Entity

Returns

string

GetItemDamageColor(ItemStack)

Returns a hardcoded rgb color (green->yellow->red) that is representative for its remaining durability vs total durability

public virtual int GetItemDamageColor(ItemStack itemstack)

Parameters

itemstack ItemStack

Returns

int

GetItemDescText() 

public virtual string GetItemDescText()

Returns

string

GetLightHsv(IBlockAccessor, BlockPos, ItemStack)

Should return the light HSV values. Warning: This method is likely to get called in a background thread. Please make sure your code in here is thread safe.

public virtual byte[] GetLightHsv(IBlockAccessor blockAccessor, BlockPos pos, ItemStack stack = null)

Parameters

blockAccessor IBlockAccessor
pos BlockPos

May be null

stack ItemStack

Set if its an itemstack for which the engine wants to check the light level

Returns

byte[]

GetMaxDurability(ItemStack)

Returns the items total durability

public virtual int GetMaxDurability(ItemStack itemstack)

Parameters

itemstack ItemStack

Returns

int

GetMeltingDuration(IWorldAccessor, ISlotProvider, ItemSlot)

If the item is smeltable, this is the time it takes to smelt at smelting point

public virtual float GetMeltingDuration(IWorldAccessor world, ISlotProvider cookingSlotsProvider, ItemSlot inputSlot)

Parameters

world IWorldAccessor
cookingSlotsProvider ISlotProvider
inputSlot ItemSlot

Returns

float

GetMeltingPoint(IWorldAccessor, ISlotProvider, ItemSlot)

If the item is smeltable, this is its melting point

public virtual float GetMeltingPoint(IWorldAccessor world, ISlotProvider cookingSlotsProvider, ItemSlot inputSlot)

Parameters

world IWorldAccessor
cookingSlotsProvider ISlotProvider
inputSlot ItemSlot

Returns

float

GetMergableQuantity(ItemStack, ItemStack, EnumMergePriority)

Should return the max. number of items that can be placed from sourceStack into the sinkStack

public virtual int GetMergableQuantity(ItemStack sinkStack, ItemStack sourceStack, EnumMergePriority priority)

Parameters

sinkStack ItemStack
sourceStack ItemStack
priority EnumMergePriority

Returns

int

GetMiningSpeed(IItemStack, BlockSelection, Block, IPlayer)

Called every game tick when the player breaks a block with this item in his hands. Returns the mining speed for given block.

public virtual float GetMiningSpeed(IItemStack itemstack, BlockSelection blockSel, Block block, IPlayer forPlayer)

Parameters

itemstack IItemStack
blockSel BlockSelection
block Block
forPlayer IPlayer

Returns

float

GetNutritionProperties(IWorldAccessor, ItemStack, Entity)

Should return the nutrition properties of the item/block

public virtual FoodNutritionProperties GetNutritionProperties(IWorldAccessor world, ItemStack itemstack, Entity forEntity)

Parameters

world IWorldAccessor
itemstack ItemStack
forEntity Entity

Returns

FoodNutritionProperties

GetRandomColor(ICoreClientAPI, ItemStack)

Should return a random pixel within the items/blocks texture

public virtual int GetRandomColor(ICoreClientAPI capi, ItemStack stack)

Parameters

capi ICoreClientAPI
stack ItemStack

Returns

int

GetRemainingDurability(ItemStack) 

public virtual int GetRemainingDurability(ItemStack itemstack)

Parameters

itemstack ItemStack

Returns

int

GetStorageFlags(ItemStack)

Should return in which storage containers this item can be placed in

public virtual EnumItemStorageFlags GetStorageFlags(ItemStack itemstack)

Parameters

itemstack ItemStack

Returns

EnumItemStorageFlags

GetTemperature(IWorldAccessor, ItemStack)

Returns the stacks item temperature in degree celsius

public virtual float GetTemperature(IWorldAccessor world, ItemStack itemstack)

Parameters

world IWorldAccessor
itemstack ItemStack

Returns

float

GetToolMode(ItemSlot, IPlayer, BlockSelection)

Should return the current items tool mode.

public virtual int GetToolMode(ItemSlot slot, IPlayer byPlayer, BlockSelection blockSelection)

Parameters

slot ItemSlot
byPlayer IPlayer
blockSelection BlockSelection

Returns

int

GetToolModes(ItemSlot, IClientPlayer, BlockSelection) 

public virtual SkillItem[] GetToolModes(ItemSlot slot, IClientPlayer forPlayer, BlockSelection blockSel)

Parameters

slot ItemSlot
forPlayer IClientPlayer
blockSel BlockSelection

Returns

SkillItem[]

GetTransitionRateMul(IWorldAccessor, ItemSlot, EnumTransitionType) 

public virtual float GetTransitionRateMul(IWorldAccessor world, ItemSlot inSlot, EnumTransitionType transType)

Parameters

world IWorldAccessor
inSlot ItemSlot
transType EnumTransitionType

Returns

float

GetTransitionableProperties(IWorldAccessor, ItemStack, Entity)

Should return the transition properties of the item/block when in itemstack form

public virtual TransitionableProperties[] GetTransitionableProperties(IWorldAccessor world, ItemStack itemstack, Entity forEntity)

Parameters

world IWorldAccessor
itemstack ItemStack
forEntity Entity

Returns

TransitionableProperties[]

HasBehavior(string, IClassRegistryAPI)

Returns true if the block has given behavior

public virtual 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 virtual bool HasBehavior(Type type, bool withInheritance = false)

Parameters

type Type
withInheritance bool

Returns

bool

HasBehavior<T>(bool)

Returns true if the block has given behavior

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

Parameters

withInheritance bool

Returns

bool

Type Parameters

T

HasTemperature(IItemStack)

Returns true if the stack has a temperature attribute

public virtual bool HasTemperature(IItemStack itemstack)

Parameters

itemstack IItemStack

Returns

bool

InGuiIdle(IWorldAccessor, ItemStack)

Called every frame when this item is being displayed in the gui

public virtual void InGuiIdle(IWorldAccessor world, ItemStack stack)

Parameters

world IWorldAccessor
stack ItemStack

IsBackPack(IItemStack)

Returns true if this stack is a backpack that can hold other items/blocks

public static bool IsBackPack(IItemStack itemstack)

Parameters

itemstack IItemStack

Returns

bool

IsEmptyBackPack(IItemStack)

Returns true if this stack is an empty backpack

public static bool IsEmptyBackPack(IItemStack itemstack)

Parameters

itemstack IItemStack

Returns

bool

IsLiquid()

Returns true if this blocks matterstate is liquid. (Liquid blocks should also implement IBlockFlowing)
IMPORTANT: Calling code should have looked up the block using IBlockAccessor.GetBlock(pos, EnumBlockLayersAccess.LiquidOnly) !!!

public virtual bool IsLiquid()

Returns

bool

IsReasonablyFresh(IWorldAccessor, ItemStack)

Test is failed for Perish-able items which have less than 50% of their fresh state remaining (or are already starting to spoil)

public virtual bool IsReasonablyFresh(IWorldAccessor world, ItemStack itemstack)

Parameters

world IWorldAccessor
itemstack ItemStack

Returns

bool

MatchesForCrafting(ItemStack, GridRecipe, CraftingRecipeIngredient)

Called when this collectible is attempted to being used as part of a crafting recipe and should get consumed now. Return false if it doesn't match the ingredient

public virtual bool MatchesForCrafting(ItemStack inputStack, GridRecipe gridRecipe, CraftingRecipeIngredient ingredient)

Parameters

inputStack ItemStack
gridRecipe GridRecipe
ingredient CraftingRecipeIngredient

Returns

bool

OnAttackingWith(IWorldAccessor, Entity, Entity, ItemSlot)

An entity used this collectibe to attack something

public virtual void OnAttackingWith(IWorldAccessor world, Entity byEntity, Entity attackedEntity, ItemSlot itemslot)

Parameters

world IWorldAccessor
byEntity Entity
attackedEntity Entity
itemslot ItemSlot

OnBeforeRender(ICoreClientAPI, ItemStack, EnumItemRenderTarget, ref ItemRenderInfo)

This method is called before rendering the item stack into GUI, first person hand, third person hand and/or on the ground The renderinfo object is pre-filled with default values.

public virtual void OnBeforeRender(ICoreClientAPI capi, ItemStack itemstack, EnumItemRenderTarget target, ref ItemRenderInfo renderinfo)

Parameters

capi ICoreClientAPI
itemstack ItemStack
target EnumItemRenderTarget
renderinfo ItemRenderInfo

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

Player is holding this collectible and breaks the targeted block

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

Parameters

player IPlayer
blockSel BlockSelection
itemslot ItemSlot
remainingResistance float
dt float
counter int

Returns

float

OnBlockBrokenWith(IWorldAccessor, Entity, ItemSlot, BlockSelection, float)

Player has broken a block while holding this collectible. Return false if you want to cancel the block break event.

public virtual bool OnBlockBrokenWith(IWorldAccessor world, Entity byEntity, ItemSlot itemslot, BlockSelection blockSel, float dropQuantityMultiplier = 1)

Parameters

world IWorldAccessor
byEntity Entity
itemslot ItemSlot
blockSel BlockSelection
dropQuantityMultiplier float

Returns

bool

OnCollected(ItemStack, Entity)

Called when this item was collected by an entity

public virtual void OnCollected(ItemStack stack, Entity entity)

Parameters

stack ItemStack
entity Entity

OnConsumedByCrafting(ItemSlot[], ItemSlot, GridRecipe, CraftingRecipeIngredient, IPlayer, int)

Called when this collectible is being used as part of a crafting recipe and should get consumed now

public virtual void OnConsumedByCrafting(ItemSlot[] allInputSlots, ItemSlot stackInSlot, GridRecipe gridRecipe, CraftingRecipeIngredient fromIngredient, IPlayer byPlayer, int quantity)

Parameters

allInputSlots ItemSlot[]
stackInSlot ItemSlot
gridRecipe GridRecipe
fromIngredient CraftingRecipeIngredient
byPlayer IPlayer
quantity int

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 virtual void OnCreatedByCrafting(ItemSlot[] allInputslots, ItemSlot outputSlot, GridRecipe byRecipe)

Parameters

allInputslots ItemSlot[]
outputSlot ItemSlot
byRecipe GridRecipe

OnGroundIdle(EntityItem)

Called every game tick when this collectible is in dropped form in the world (i.e. as EntityItem)

public virtual void OnGroundIdle(EntityItem entityItem)

Parameters

entityItem EntityItem

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

public virtual void OnHandbookRecipeRender(ICoreClientAPI capi, GridRecipe recipe, ItemSlot slot, double x, double y, double z, double size)

Parameters

capi ICoreClientAPI
recipe GridRecipe
slot ItemSlot
x double
y double
z double
size double

OnHeldActionAnimStart(ItemSlot, EntityAgent, EnumHandInteract) 

public virtual void OnHeldActionAnimStart(ItemSlot slot, EntityAgent byEntity, EnumHandInteract type)

Parameters

slot ItemSlot
byEntity EntityAgent
type EnumHandInteract

OnHeldAttackCancel(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, EnumItemUseCancelReason)

When the player has canceled a custom attack action. Return false to deny action cancellation.

public virtual bool OnHeldAttackCancel(float secondsPassed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSelection, EntitySelection entitySel, EnumItemUseCancelReason cancelReason)

Parameters

secondsPassed float
slot ItemSlot
byEntity EntityAgent
blockSelection BlockSelection
entitySel EntitySelection
cancelReason EnumItemUseCancelReason

Returns

bool

OnHeldAttackStart(ItemSlot, EntityAgent, BlockSelection, EntitySelection, ref EnumHandHandling)

When the player has begun using this item for attacking (left mouse click). Return true to play a custom action.

public virtual void OnHeldAttackStart(ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, ref EnumHandHandling handling)

Parameters

slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection
handling EnumHandHandling

Whether or not to do any subsequent actions. If not set or set to NotHandled, the action will not called on the server.

OnHeldAttackStep(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection)

Called continously when a custom attack action is playing. Return false to stop the action.

public virtual bool OnHeldAttackStep(float secondsPassed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSelection, EntitySelection entitySel)

Parameters

secondsPassed float
slot ItemSlot
byEntity EntityAgent
blockSelection BlockSelection
entitySel EntitySelection

Returns

bool

OnHeldAttackStop(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection)

Called when a custom attack action is finished

public virtual void OnHeldAttackStop(float secondsPassed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSelection, EntitySelection entitySel)

Parameters

secondsPassed float
slot ItemSlot
byEntity EntityAgent
blockSelection BlockSelection
entitySel EntitySelection

OnHeldDropped(IWorldAccessor, IPlayer, ItemSlot, int, ref EnumHandling)

Callback when the player dropped this item from his inventory. You can set handling to PreventDefault to prevent dropping this item. You can also check if the entityplayer of this player is dead to check if dropping of this item was due the players death

public virtual void OnHeldDropped(IWorldAccessor world, IPlayer byPlayer, ItemSlot slot, int quantity, ref EnumHandling handling)

Parameters

world IWorldAccessor
byPlayer IPlayer
slot ItemSlot
quantity int

Amount of items the player wants to drop

handling EnumHandling

OnHeldIdle(ItemSlot, EntityAgent)

Called every frame when the player is holding this collectible in his hands. Is not called during OnUsing() or OnAttacking()

public virtual void OnHeldIdle(ItemSlot slot, EntityAgent byEntity)

Parameters

slot ItemSlot
byEntity EntityAgent

OnHeldInteractCancel(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, EnumItemUseCancelReason)

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

public virtual bool OnHeldInteractCancel(float secondsUsed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, EnumItemUseCancelReason cancelReason)

Parameters

secondsUsed float
slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection
cancelReason EnumItemUseCancelReason

Returns

bool

OnHeldInteractStart(ItemSlot, EntityAgent, BlockSelection, EntitySelection, bool, ref EnumHandHandling)

Called when the player right clicks while holding this block/item in his hands

public virtual void OnHeldInteractStart(ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, bool firstEvent, ref EnumHandHandling handling)

Parameters

slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection
firstEvent bool

True when the player pressed the right mouse button on this block. Every subsequent call, while the player holds right mouse down will be false, it gets called every second while right mouse is down

handling EnumHandHandling

Whether or not to do any subsequent actions. If not set or set to NotHandled, the action will not called on the server.

OnHeldInteractStep(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection)

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

public virtual bool OnHeldInteractStep(float secondsUsed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel)

Parameters

secondsUsed float
slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection

Returns

bool

False if the interaction should be stopped. True if the interaction should continue

OnHeldInteractStop(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection)

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

public virtual void OnHeldInteractStop(float secondsUsed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel)

Parameters

secondsUsed float
slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection

OnHeldRenderOit(ItemSlot, IClientPlayer)

This method is called during the order independent transparency render pass when this item or block is being held in hands

public virtual void OnHeldRenderOit(ItemSlot inSlot, IClientPlayer byPlayer)

Parameters

inSlot ItemSlot
byPlayer IClientPlayer

OnHeldRenderOpaque(ItemSlot, IClientPlayer)

This method is called during the opaque render pass when this item or block is being held in hands

public virtual void OnHeldRenderOpaque(ItemSlot inSlot, IClientPlayer byPlayer)

Parameters

inSlot ItemSlot
byPlayer IClientPlayer

OnHeldRenderOrtho(ItemSlot, IClientPlayer)

This method is called during the ortho (for 2D GUIs) render pass when this item or block is being held in hands

public virtual void OnHeldRenderOrtho(ItemSlot inSlot, IClientPlayer byPlayer)

Parameters

inSlot ItemSlot
byPlayer IClientPlayer

OnHeldUseCancel(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, EnumItemUseCancelReason)

General cancel use access. Override OnHeldAttackCancel or OnHeldInteractCancel to alter the behavior.

public EnumHandInteract OnHeldUseCancel(float secondsPassed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, EnumItemUseCancelReason cancelReason)

Parameters

secondsPassed float
slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection
cancelReason EnumItemUseCancelReason

Returns

EnumHandInteract

OnHeldUseStart(ItemSlot, EntityAgent, BlockSelection, EntitySelection, EnumHandInteract, bool, ref EnumHandHandling)

General begin use access. Override OnHeldAttackStart or OnHeldInteractStart to alter the behavior.

public virtual void OnHeldUseStart(ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, EnumHandInteract useType, bool firstEvent, ref EnumHandHandling handling)

Parameters

slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection
useType EnumHandInteract
firstEvent bool

True on first mouse down

handling EnumHandHandling

Whether or not to do any subsequent actions. If not set or set to NotHandled, the action will not called on the server.

OnHeldUseStep(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection)

General using access. Override OnHeldAttackStep or OnHeldInteractStep to alter the behavior.

public EnumHandInteract OnHeldUseStep(float secondsPassed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel)

Parameters

secondsPassed float
slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection

Returns

EnumHandInteract

OnHeldUseStop(float, ItemSlot, EntityAgent, BlockSelection, EntitySelection, EnumHandInteract)

General use over access. Override OnHeldAttackStop or OnHeldInteractStop to alter the behavior.

public void OnHeldUseStop(float secondsPassed, ItemSlot slot, EntityAgent byEntity, BlockSelection blockSel, EntitySelection entitySel, EnumHandInteract useType)

Parameters

secondsPassed float
slot ItemSlot
byEntity EntityAgent
blockSel BlockSelection
entitySel EntitySelection
useType EnumHandInteract

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

This method is called after a block/item like this has been imported as part of a block schematic. Has to restore fix the block/item id mappings as they are probably different compared to the world from where they were exported. By default iterates over all the itemstacks attributes and searches for attribute sof type ItenStackAttribute and calls .FixMapping() on them.

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

Parameters

worldForResolve IWorldAccessor
inSlot ItemSlot
oldBlockIdMapping Dictionary<int, AssetLocation>
oldItemIdMapping Dictionary<int, AssetLocation>

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

This method is called after a block/item like this has been imported as part of a block schematic. Has to restore fix the block/item id mappings as they are probably different compared to the world from where they were exported. By default iterates over all the itemstacks attributes and searches for attribute sof type ItenStackAttribute and calls .FixMapping() on them.

public virtual void OnLoadCollectibleMappings(IWorldAccessor worldForResolve, ItemSlot inSlot, Dictionary<int, AssetLocation> oldBlockIdMapping, Dictionary<int, AssetLocation> oldItemIdMapping, bool resolveImports)

Parameters

worldForResolve IWorldAccessor
inSlot ItemSlot
oldBlockIdMapping Dictionary<int, AssetLocation>
oldItemIdMapping Dictionary<int, AssetLocation>
resolveImports bool

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

OnLoaded(ICoreAPI)

Server Side: Called one the collectible has been registered Client Side: Called once the collectible has been loaded from server packet

public virtual void OnLoaded(ICoreAPI api)

Parameters

api ICoreAPI

OnLoadedNative(ICoreAPI) 

public void OnLoadedNative(ICoreAPI api)

Parameters

api ICoreAPI

OnModifiedInInventorySlot(IWorldAccessor, ItemSlot, ItemStack)

Whenever the collectible was modified while inside a slot, usually when it was moved, split or merged.

public virtual void OnModifiedInInventorySlot(IWorldAccessor world, ItemSlot slot, ItemStack extractedStack = null)

Parameters

world IWorldAccessor
slot ItemSlot

The slot the item is or was in

extractedStack ItemStack

Non null if the itemstack was removed from this slot

OnSmeltAttempt(InventoryBase)

Called immediately prior to a firepit or similar testing whether this Collectible can be smelted
Returns true if the caller should be marked dirty

public virtual bool OnSmeltAttempt(InventoryBase inventorySmelting)

Parameters

inventorySmelting InventoryBase

Returns

bool

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

This method is for example called by chests when they are being exported as part of a block schematic. Has to store all the currents block/item id mappings so it can be correctly imported again. By default it puts itself into the mapping and searches the itemstack attributes for attributes of type ItemStackAttribute and adds those to the mapping as well.

public virtual void OnStoreCollectibleMappings(IWorldAccessor world, ItemSlot inSlot, Dictionary<int, AssetLocation> blockIdMapping, Dictionary<int, AssetLocation> itemIdMapping)

Parameters

world IWorldAccessor
inSlot ItemSlot
blockIdMapping Dictionary<int, AssetLocation>
itemIdMapping Dictionary<int, AssetLocation>

OnTransitionNow(ItemSlot, TransitionableProperties)

Called when any of its TransitionableProperties causes the stack to transition to another stack. Default behavior is to return props.TransitionedStack.ResolvedItemstack and set the stack size according to the transition rtio

public virtual ItemStack OnTransitionNow(ItemSlot slot, TransitionableProperties props)

Parameters

slot ItemSlot
props TransitionableProperties

Returns

ItemStack

The stack it should transition into

OnUnloaded(ICoreAPI)

Called when the client/server is shutting down

public virtual void OnUnloaded(ICoreAPI api)

Parameters

api ICoreAPI

QuantityBackPackSlots(IItemStack)

If the stack is a backpack, this returns the amount of slots it has

public static int QuantityBackPackSlots(IItemStack itemstack)

Parameters

itemstack IItemStack

Returns

int

RefillSlotIfEmpty(ItemSlot, EntityAgent, ActionConsumable<ItemStack>) 

public virtual void RefillSlotIfEmpty(ItemSlot slot, EntityAgent byEntity, ActionConsumable<ItemStack> matcher)

Parameters

slot ItemSlot
byEntity EntityAgent
matcher ActionConsumable<ItemStack>

RequiresTransitionableTicking(IWorldAccessor, ItemStack)

Should returns true if this collectible requires UpdateAndGetTransitionStates() to be called when ticking.
Typical usage: true if this collectible itself has transitionable properties, or true for collectibles which hold other itemstacks with transitionable properties (for example, a cooked food container)

public virtual bool RequiresTransitionableTicking(IWorldAccessor world, ItemStack itemstack)

Parameters

world IWorldAccessor
itemstack ItemStack

Returns

bool

Satisfies(ItemStack, ItemStack)

Should return true if thisStack is a satisfactory replacement of otherStack. It's bascially an Equals() test, but it ignores any additional attributes that exist in otherStack

public virtual bool Satisfies(ItemStack thisStack, ItemStack otherStack)

Parameters

thisStack ItemStack
otherStack ItemStack

Returns

bool

SetTemperature(IWorldAccessor, ItemStack, float, bool)

Sets the stacks item temperature in degree celsius

public virtual void SetTemperature(IWorldAccessor world, ItemStack itemstack, float temperature, bool delayCooldown = true)

Parameters

world IWorldAccessor
itemstack ItemStack
temperature float
delayCooldown bool

SetToolMode(ItemSlot, IPlayer, BlockSelection, int)

Should set given toolmode

public virtual void SetToolMode(ItemSlot slot, IPlayer byPlayer, BlockSelection blockSelection, int toolMode)

Parameters

slot ItemSlot
byPlayer IPlayer
blockSelection BlockSelection
toolMode int

SetTransitionState(ItemStack, EnumTransitionType, float) 

public virtual void SetTransitionState(ItemStack stack, EnumTransitionType type, float transitionedHours)

Parameters

stack ItemStack
type EnumTransitionType
transitionedHours float

ShouldDisplayItemDamage(ItemStack)

Return true if remaining durability != total durability

public virtual bool ShouldDisplayItemDamage(ItemStack itemstack)

Parameters

itemstack ItemStack

Returns

bool

TryMergeStacks(ItemStackMergeOperation)

Is always called on the sink slots item

public virtual void TryMergeStacks(ItemStackMergeOperation op)

Parameters

op ItemStackMergeOperation

UpdateAndGetTransitionState(IWorldAccessor, ItemSlot, EnumTransitionType)

Returns the transition state of given transition type

public virtual TransitionState UpdateAndGetTransitionState(IWorldAccessor world, ItemSlot inslot, EnumTransitionType type)

Parameters

world IWorldAccessor
inslot ItemSlot
type EnumTransitionType

Returns

TransitionState

UpdateAndGetTransitionStates(IWorldAccessor, ItemSlot)

Returns a list of the current transition states of this item, redirects to UpdateAndGetTransitionStatesNative

public virtual TransitionState[] UpdateAndGetTransitionStates(IWorldAccessor world, ItemSlot inslot)

Parameters

world IWorldAccessor
inslot ItemSlot

Returns

TransitionState[]

UpdateAndGetTransitionStatesNative(IWorldAccessor, ItemSlot)

Returns a list of the current transition states of this item. Seperate from UpdateAndGetTransitionStates() so that you can call still call this methods several inheritances down, i.e. there is no base.base.Method() syntax in C#

protected virtual TransitionState[] UpdateAndGetTransitionStatesNative(IWorldAccessor world, ItemSlot inslot)

Parameters

world IWorldAccessor
inslot ItemSlot

Returns

TransitionState[]

playEatSound(EntityAgent, string, int) 

protected void playEatSound(EntityAgent byEntity, string eatSound = "eat", int eatSoundRepeats = 1)

Parameters

byEntity EntityAgent
eatSound string
eatSoundRepeats int

tryEatBegin(ItemSlot, EntityAgent, ref EnumHandHandling, string, int)

Tries to eat the contents in the slot, first call

protected virtual void tryEatBegin(ItemSlot slot, EntityAgent byEntity, ref EnumHandHandling handling, string eatSound = "eat", int eatSoundRepeats = 1)

Parameters

slot ItemSlot
byEntity EntityAgent
handling EnumHandHandling
eatSound string
eatSoundRepeats int

tryEatStep(float, ItemSlot, EntityAgent, ItemStack)

Tries to eat the contents in the slot, eat step call

protected virtual bool tryEatStep(float secondsUsed, ItemSlot slot, EntityAgent byEntity, ItemStack spawnParticleStack = null)

Parameters

secondsUsed float
slot ItemSlot
byEntity EntityAgent
spawnParticleStack ItemStack

Returns

bool

tryEatStop(float, ItemSlot, EntityAgent)

Finished eating the contents in the slot, final call

protected virtual void tryEatStop(float secondsUsed, ItemSlot slot, EntityAgent byEntity)

Parameters

secondsUsed float
slot ItemSlot
byEntity EntityAgent