Consumables

Consumables are items that can be made "edible" to the player and "consuming" it will allow them to run an action or receive a kit. It can be defined and applied to items in kits. When consumed, these items can trigger actions, and override vanilla eating or drinking behavior.

Consumables Element

Element	Description
<consumables> </consumables>	Node containing the consumables definitions.

Sub-elements
<consumable> </consumable>	An individual consumable.

Consumable Attributes

Attribute	Description	Value	Default
id	RequiredUnique identifier used to reference this consumable from other places in the XML.	String
action	RequiredRun the specified action upon consumption.	Action ID
on	RequiredSpecify how the consumable should be used.	eat right click left click click (both)
override	The consumable is affected by vanilla behaviors, such as giving the player potion effects. This is useful when using potion bottles and golden apples as the consumable item.	true/false	true
consume	PGM will consume the item once per use for the user. Note: This attribute is ignored if the value of on attribute is eat.	true/false	*

Override & Consume Behavior

Some combinations of override and consume values can lead to unexpected behaviors involving either the user's client or PGM itself. This chart outlines the expected vanilla behavior for each configuration.

Override	Consume	Vanilla Behavior	Result
false	false	No consume (e.g.: stick)	Optimal0 used
false	false	Consumes (e.g.: snowball)	Sub-optimal1 used
false	true	No consume (e.g.: stick)	Optimal1 used
false	true	Consumes (e.g.: snowball)	Invalid2 used
true	false	Any case	Optimal0 used
true	true	Any case	Optimal1 used

Examples

<!-- Create the consumable "porkchop-that-says-yum" -->
<consumables>
    <consumable id="porkchop-that-says-yum" action="say-yum" on="eat" override="false"/>
</consumables>
<!-- Apply the consumable to an item -->
<kits>
    <kit id="spawn">
        <item slot="1" amount="5" consumable="porkchop-that-says-yum" material="pork"/>
    </kit>
</kits>
<!-- Define the action the consumable will run -->
<actions>
    <message id="say-yum" text="Yum!"/>
</actions>

<!-- Create the consumable "fast-apple" -->
<consumables>
    <consumable id="fast-apple" action="speed-kit" on="eat"/>
</consumables>
<kits>
    <!-- Apply the consumable to an item -->
    <kit id="spawn">
        <item slot="1" consumable="fast-apple" name="Fast Apple" material="golden apple"/>
    </kit>
    <!-- Define the kit the consumable gives you -->
    <kit id="speed-kit">
        <effect duration="4" amplifier="10">speed</effect>
    </kit>
</kits>

<!-- Create the consumable "heal" -->
<!-- When the healing stick is right clicked, it is "consumed" and applies the
heal-click action (kit) that sets the player's health back to 20 -->
<consumables>
    <consumable id="heal" action="heal-click" on="click" override="true" consume="true"/>
</consumables>
<kits>
    <!-- Apply the consumable to an item -->
    <kit id="spawn-kit">
        <item material="stick" consumable="heal" name="Healing stick!"/>
    </kit>
    <!-- Define the kit the consumable gives you -->
    <kit id="heal-click">
        <health>20</health>
    </kit>
</kits>