Item Callbacks

Modding Tutorial: Item Callbacks

Overview

When you are making a new item, there are a variety of methods to override that will detail what your item can do and what user input it will respond to. This section will go over the different types of interactions will be supplied to you on the server.

To use any of these, simply override the corresponding method and you should begin receiving the callbacks automatically. (you do *not* need to call the base method).

It's worth noting that all overrides are optional. Network performance will be better if less methods are overridden since we figure out which items need what interactions and optimize the networking accordingly.

The bool that is returned by these methods is whether or not the callback was "handled", e.g. did you do anything of note in the override? We need to know this in order to make sure all the interactions get processed in the right order.

Item Interaction Methods

        public virtual bool OnActLeftDown(Player player)

        public virtual bool OnActLeftUp(Player player)
 
        public virtual bool OnActRight(Player player) 

Use the item on nothing (thin air) by clicking (LeftDown) then releasing (LeftUp) the left mouse button. Alternatively, when right mouse button is clicked. No released is available for RMB.

        public virtual bool OnActOnBlockLeftDown(Player player, Vector3i pos, Vector3i normal) 

        public virtual bool OnActOnBlockLeftUp(Player player, Vector3i pos, Vector3i normal)

Use the item on a block with the left mouse button. Pressed and released callbacks are available for this action. The pos is the position of the block the player is looking at and the normal is the face that the player's cursor is on. If you, for instance, wanted the position of the empty block that the player is looking towards it would be (pos + normal).

Note: When any of these methods is overridden the item will show the block cursor while selected on the toolbar.

        public virtual bool OnActOnBlockRight(Player player, Vector3i pos, Vector3i normal)

Equivalent to the previous callbacks, but when the right mouse button is pressed. No RMB released callbacks are available.

        public virtual bool OnActOnLeftDown(Player player, IInteractable target)

        public virtual bool OnActOnLeftUp(Player player, IInteractable target)

        public virtual bool OnActOnRight(Player player, IInteractable target)

For the two mouse buttons, with released and pressed states for LMB, this callback is when the item is used while targeting an interactable object. Interactable objects can be world objects, animals, trees, etc. Anything implementing `IInteractable` will trigger this callback on the item.

Note: once these methods are overridden, the item will begin to highlight selectable objects. You can specify this behavior by overriding the properties: `InteractDistance`, `HighlightedObjects`, and `GetInteractionColor`.

        public virtual bool OnUsed(Player player)

Triggered when the player right clicks on the item. This is often used for actions such as eating the item or opening a GUI for the item.

        public virtual bool OnSelected(Player player)

Called when the item is selected in the toolbar for the player.

Example Usage: Food

        public override bool OnUsed(Player player)
        {
            player.User.Food += this.Nutrition;
            return true;
        }