Class CollectibleBehavior

Namespace

Vintagestory.API.Common

Assembly

VintagestoryAPI.dll

A behavior object which can be added to any collectible. See the derived types for a list of documented collectible behaviors. Open in GitHub

[DocumentAsJson]
public abstract class CollectibleBehavior

Inheritance

object

CollectibleBehavior

Derived

BlockBehavior

Inherited Members

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

CollectibleBehavior(CollectibleObject)

public CollectibleBehavior(CollectibleObject collObj)

Parameters

collObj CollectibleObject

Fields

collObj

The collectible object (item or block) for this behavior instance.

public CollectibleObject collObj

Field Value

CollectibleObject

propertiesAtString

The properties of this block behavior.

public string propertiesAtString

Field Value

string

Properties

ClientSideOptional

If true, this behavior is not required on the client. This is here because copygirl doesn't stop asking for it. Probably breaks things. If it breaks things, complain to copygirl please :p

public virtual bool ClientSideOptional { get; }

Property Value

bool

Methods

AfterGetTemperature(IWorldAccessor, ItemStack, float, ref EnumHandling)

public virtual void AfterGetTemperature(IWorldAccessor world, ItemStack itemstack, float temperature, ref EnumHandling handling)

Parameters

world IWorldAccessor

itemstack ItemStack

temperature float

handling EnumHandling

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

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

Parameters

slots ItemSlot[]

outputSlot ItemSlot

matchingRecipe GridRecipe

handling EnumHandling

Returns

bool

GetAttackPower(ItemStack, float, ref EnumHandling)

public virtual float GetAttackPower(ItemStack itemstack, float attackPower, ref EnumHandling bhHandling)

Parameters

itemstack ItemStack

attackPower float

bhHandling EnumHandling

Returns

float

GetAttackRange(ItemStack, float, ref EnumHandling)

public virtual float GetAttackRange(ItemStack itemstack, float attackRange, ref EnumHandling bhHandling)

Parameters

itemstack ItemStack

attackRange float

bhHandling EnumHandling

Returns

float

GetDamageToEntity(float, Entity, ItemStack, ref bool, ref EnumHandling)

public virtual float GetDamageToEntity(float baseDamage, Entity entity, ItemStack itemStack, ref bool isCriticalHit, ref EnumHandling handling)

Parameters

baseDamage float

entity Entity

itemStack ItemStack

isCriticalHit bool

handling EnumHandling

Returns

float

GetHeldInteractionHelp(ItemSlot, ref EnumHandling)

Interaction help that is shown when selecting the item in the hotbar slot

public virtual WorldInteraction[] GetHeldInteractionHelp(ItemSlot inSlot, ref EnumHandling handling)

Parameters

inSlot ItemSlot

handling EnumHandling

Returns

WorldInteraction[]

GetHeldItemInfo(ItemSlot, StringBuilder, IWorldAccessor, bool)

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

Parameters

inSlot ItemSlot

dsc StringBuilder

world IWorldAccessor

withDebugInfo bool

GetHeldItemName(StringBuilder, ItemStack)

public virtual void GetHeldItemName(StringBuilder sb, ItemStack itemStack)

Parameters

sb StringBuilder

itemStack ItemStack

GetHeldReadyAnimation(ItemSlot, Entity, EnumHand, ref EnumHandling)

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

Parameters

activeHotbarSlot ItemSlot

forEntity Entity

hand EnumHand

bhHandling EnumHandling

Returns

string

GetHeldTpHitAnimation(ItemSlot, Entity, ref EnumHandling)

public virtual string GetHeldTpHitAnimation(ItemSlot slot, Entity byEntity, ref EnumHandling bhHandling)

Parameters

slot ItemSlot

byEntity Entity

bhHandling EnumHandling

Returns

string

GetHeldTpIdleAnimation(ItemSlot, Entity, EnumHand, ref EnumHandling)

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

Parameters

activeHotbarSlot ItemSlot

forEntity Entity

hand EnumHand

bhHandling EnumHandling

Returns

string

GetHeldTpUseAnimation(ItemSlot, Entity, ref EnumHandling)

public virtual string GetHeldTpUseAnimation(ItemSlot activeHotbarSlot, Entity forEntity, ref EnumHandling bhHandling)

Parameters

activeHotbarSlot ItemSlot

forEntity Entity

bhHandling EnumHandling

Returns

string

GetMaxDurability(ItemStack, int, ref EnumHandling)

Define the max durability of this item

public virtual int GetMaxDurability(ItemStack itemstack, int durability, ref EnumHandling bhHandling)

Parameters

itemstack ItemStack

durability int

The standard max durability of this item

bhHandling EnumHandling

If not set to PassThrough, the returned value is used

Returns

int

Exceptions

NotImplementedException

GetMergableQuantity(ItemStack, ItemStack, EnumMergePriority, ref EnumHandling)

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

Parameters

sinkStack ItemStack

sourceStack ItemStack

priority EnumMergePriority

handling EnumHandling

Returns

int

GetMiningSpeed(ItemStack, BlockSelection, Block, IPlayer, ref EnumHandling)

Multiplies resulted mining speed of the item by return value if 'bhHandling' is not equal to 'PassThrough'. If 'bhHandling' is not set to 'PreventDefault', the mining speed will be multiplied by standard item mining speed.

public virtual float GetMiningSpeed(ItemStack itemstack, BlockSelection blockSel, Block block, IPlayer forPlayer, ref EnumHandling bhHandling)

Parameters

itemstack ItemStack

blockSel BlockSelection

block Block

forPlayer IPlayer

bhHandling EnumHandling

Returns

float

Mining speed multiplier

GetMiningSpeeds(ItemSlot, ref EnumHandling)

Sets return value to mining speeds for all materials of the item if 'bhHandling' is not equal to 'PassThrough'.

public virtual Dictionary<EnumBlockMaterial, float> GetMiningSpeeds(ItemSlot slot, ref EnumHandling bhHandling)

Parameters

slot ItemSlot

bhHandling EnumHandling

Returns

Dictionary<EnumBlockMaterial, float>

Mining speeds

GetRemainingDurability(ItemStack, int, ref EnumHandling)

Sets return value to remaining durability if 'bhHandling' is not equal to 'PassThrough'. If 'bhHandling' is not set to 'PreventDefault', standard item durability will be added to result.

public virtual int GetRemainingDurability(ItemStack itemstack, int remainingDurability, ref EnumHandling bhHandling)

Parameters

itemstack ItemStack

remainingDurability int

Current remaining durability

bhHandling EnumHandling

Returns

int

Remaining durability

GetStorageFlags(ItemStack, ref EnumHandling)

public virtual EnumItemStorageFlags GetStorageFlags(ItemStack itemstack, ref EnumHandling handling)

Parameters

itemstack ItemStack

handling EnumHandling

Returns

EnumItemStorageFlags

GetTemperature(IWorldAccessor, ItemStack, ref EnumHandling)

public virtual float GetTemperature(IWorldAccessor world, ItemStack itemstack, ref EnumHandling handling)

Parameters

world IWorldAccessor

itemstack ItemStack

handling EnumHandling

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)

Called when the tool mode (F) key is pressed to generate the GUI

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

Parameters

slot ItemSlot

forPlayer IClientPlayer

blockSel BlockSelection

Returns

SkillItem[]

Initialize(JsonObject)

Called right after the block behavior was created, must call base method

public virtual void Initialize(JsonObject properties)

Parameters

properties JsonObject

OnBeforeRender(ICoreClientAPI, ItemStack, EnumItemRenderTarget, ref ItemRenderInfo)

Called when the collectible is rendered in hands, inventory or on the ground

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, ref EnumHandling)

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, ref EnumHandling handled)

Parameters

player IPlayer

blockSel BlockSelection

itemslot ItemSlot

remainingResistance float

dt float

counter int

handled EnumHandling

Returns

float

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

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, ref EnumHandling bhHandling)

Parameters

world IWorldAccessor

byEntity Entity

itemslot ItemSlot

blockSel BlockSelection

dropQuantityMultiplier float

bhHandling EnumHandling

Returns

bool

OnCreatedByCrafting(ItemSlot[], ItemSlot, ref EnumHandling)

[Obsolete("Use OnCreatedByCrafting(ItemSlot[] allInputSlots, ItemSlot outputSlot, IRecipeBase byRecipe, ref EnumHandling bhHandling) instead")]
public virtual void OnCreatedByCrafting(ItemSlot[] allInputslots, ItemSlot outputSlot, ref EnumHandling bhHandling)

Parameters

allInputslots ItemSlot[]

outputSlot ItemSlot

bhHandling EnumHandling

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

[Obsolete("Use OnCreatedByCrafting(ItemSlot[] allInputSlots, ItemSlot outputSlot, IRecipeBase byRecipe, ref EnumHandling bhHandling) instead")]
public virtual void OnCreatedByCrafting(ItemSlot[] allInputslots, ItemSlot outputSlot, GridRecipe byRecipe, ref EnumHandling bhHandling)

Parameters

allInputslots ItemSlot[]

outputSlot ItemSlot

byRecipe GridRecipe

bhHandling EnumHandling

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

public virtual void OnCreatedByCrafting(ItemSlot[] allInputSlots, ItemSlot outputSlot, IRecipeBase byRecipe, ref EnumHandling bhHandling)

Parameters

allInputSlots ItemSlot[]

outputSlot ItemSlot

byRecipe IRecipeBase

bhHandling EnumHandling

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

Called when item is damaged via 'CollectibleObject.DamageItem'

public virtual void OnDamageItem(IWorldAccessor world, Entity byEntity, ItemSlot itemslot, ref int amount, ref EnumHandling bhHandling)

Parameters

world IWorldAccessor

byEntity Entity

itemslot ItemSlot

amount int

bhHandling EnumHandling

OnDestroyItem(IWorldAccessor, Entity, ItemSlot, ref EnumHandling)

Called when item is destroyed via 'CollectibleObject.OnDestroyItem'

public virtual void OnDestroyItem(IWorldAccessor world, Entity byEntity, ItemSlot itemSlot, ref EnumHandling bhHandling)

Parameters

world IWorldAccessor

byEntity Entity

itemSlot ItemSlot

bhHandling EnumHandling

OnGetMaxDurability(ItemStack, ref EnumHandling)

Adds return value to resulted durability if 'bhHandling' is not equal to 'PassThrough'. If 'bhHandling' is not set to 'PreventDefault', standard item durability will be added to result.

[Obsolete("Use GetMaxDurability() instead, there do not return additional durability but the total durability")]
public virtual int OnGetMaxDurability(ItemStack itemstack, ref EnumHandling bhHandling)

Parameters

itemstack ItemStack

bhHandling EnumHandling

Returns

int

Additional durability

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

[Obsolete("Use GetMiningSpeed instead")]
public virtual float OnGetMiningSpeed(IItemStack itemstack, BlockSelection blockSel, Block block, IPlayer forPlayer, ref EnumHandling bhHandling)

Parameters

itemstack IItemStack

blockSel BlockSelection

block Block

forPlayer IPlayer

bhHandling EnumHandling

Returns

float

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

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

Parameters

capi ICoreClientAPI

recipe GridRecipe

slot ItemSlot

x double

y double

z double

size double

handling EnumHandling

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

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, ref EnumHandling handling)

Parameters

secondsPassed float

slot ItemSlot

byEntity EntityAgent

blockSelection BlockSelection

entitySel EntitySelection

cancelReason EnumItemUseCancelReason

handling EnumHandling

Returns

bool

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

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 handHandling, ref EnumHandling handling)

Parameters

slot ItemSlot

byEntity EntityAgent

blockSel BlockSelection

entitySel EntitySelection

handHandling EnumHandHandling

handling EnumHandling

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

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, ref EnumHandling handling)

Parameters

secondsPassed float

slot ItemSlot

byEntity EntityAgent

blockSelection BlockSelection

entitySel EntitySelection

handling EnumHandling

Returns

bool

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

Called when a custom attack action is finished

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

Parameters

secondsPassed float

slot ItemSlot

byEntity EntityAgent

blockSelection BlockSelection

entitySel EntitySelection

handling EnumHandling

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

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, ref EnumHandling handled)

Parameters

secondsUsed float

slot ItemSlot

byEntity EntityAgent

blockSel BlockSelection

entitySel EntitySelection

cancelReason EnumItemUseCancelReason

handled EnumHandling

Returns

bool

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

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 handHandling, ref EnumHandling handling)

Parameters

slot ItemSlot

byEntity EntityAgent

blockSel BlockSelection

entitySel EntitySelection

firstEvent bool

handHandling EnumHandHandling

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

handling EnumHandling

Set to PreventDefault to not try eating the item, set to PreventSubsequent to ignore any subsequent calls to OnHeldInteractStart() of other behaviors

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

Called every frame while the player is using this collectible

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

Parameters

secondsUsed float

slot ItemSlot

byEntity EntityAgent

blockSel BlockSelection

entitySel EntitySelection

handling EnumHandling

Returns

bool

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

Called when the player successfully completed the using action, not called when successfully cancelled

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

Parameters

secondsUsed float

slot ItemSlot

byEntity EntityAgent

blockSel BlockSelection

entitySel EntitySelection

handling EnumHandling

OnLoaded(ICoreAPI)

Server Side: Called once 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

OnSetDurability(ItemStack, ref int, ref EnumHandling)

Called when item durability is set via 'CollectibleObject.SetDurability'

public virtual void OnSetDurability(ItemStack itemstack, ref int amount, ref EnumHandling bhHandling)

Parameters

itemstack ItemStack

amount int

bhHandling EnumHandling

OnTransitionNow(ItemSlot, TransitionableProperties, ref EnumHandling)

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, ref EnumHandling handling)

Parameters

slot ItemSlot

props TransitionableProperties

handling EnumHandling

Returns

ItemStack

The stack it should transition into

OnUnloaded(ICoreAPI)

public virtual void OnUnloaded(ICoreAPI api)

Parameters

api ICoreAPI

RequiresTransitionableTicking(IWorldAccessor, ItemStack, ref EnumHandling)

public virtual bool RequiresTransitionableTicking(IWorldAccessor world, ItemStack itemstack, ref EnumHandling handling)

Parameters

world IWorldAccessor

itemstack ItemStack

handling EnumHandling

Returns

bool

SetTemperature(IWorldAccessor, ItemStack, float, bool, ref EnumHandling)

public virtual void SetTemperature(IWorldAccessor world, ItemStack itemstack, float temperature, bool delayCooldown, ref EnumHandling handling)

Parameters

world IWorldAccessor

itemstack ItemStack

temperature float

delayCooldown bool

handling EnumHandling

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

TryMergeStacks(ItemStackMergeOperation, ref EnumHandling)

public virtual void TryMergeStacks(ItemStackMergeOperation op, ref EnumHandling handling)

Parameters

op ItemStackMergeOperation

handling EnumHandling

UpdateAndGetTransitionState(IWorldAccessor, ItemSlot, EnumTransitionType, ref EnumHandling)

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

Parameters

world IWorldAccessor

inslot ItemSlot

type EnumTransitionType

handling EnumHandling

Returns

TransitionState

UpdateAndGetTransitionStates(IWorldAccessor, ItemSlot, ref EnumHandling)

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

Parameters

world IWorldAccessor

inslot ItemSlot

handling EnumHandling

Returns

TransitionState[]