Item & Itemstack Utilities


The functions in this category are helpful for manipulating itemstacks/strings and item or tool definitions.

MISC. FUNCTIONS

General utilities for handling items

etc.split_oversized_stack

Usage: etc.split_oversized_stack(stack)
 Takes a single ItemStack and returns an array of ItemStacks that resulted from dividing it up based on its' stack_max definition. If the stack was already smaller than or equal in size to stack_max, the array will only contain the original ItemStack.

etc.give_or_drop

Usage: etc.give_or_drop(player, pos, itemstack)
 Attempts to insert the ItemStack into the the player's main inventory list. If the player doesn't have room for the item, it will instead be dropped at pos in the world. Note that this function calls etc.split_oversized_stack before attempting to give the item(s) to the player, so they may receive some but not all of the items if the stack was larger than allowed.

etc.sum_uses

Usage: etc.sum_uses(...)
 Returns the sum of all the uses across all the digging groups in the tool_capabilities of the specified items. Items must be in the form of an itemstring.

etc.average_uses

Usage: etc.average_uses(...)
 Similar to sum_uses but divides the result by the total number of digging groups found. If a tool has no capabilities, it will count as one group but add no uses, meaning the end result will be divided by one more than usual.

PLACEHOLDER ITEMS

These functions can be used to retrieve a stack that represents an action or a unit of something other than items, for example time, energy, etc.

etc.get_time_rep_stack

Usage: etc.get_time_rep_stack(description, time_in_seconds)
 Returns a stack of count time_in_seconds with the description metadata field description plus an additional line of text containing a timestamp in the format HH:MM:SS.

etc.get_chance_rep_stack

Usage: etc.get_chance_rep_stack(percent[, addendum, conditions])
 Returns a stack of count percent*100 (so percent should be formatted from 0-1). The raw percentage will be on the second line of the description, with the addendum concatenated after the percent sign to give extra context if defined. conditions is an array of strings added to a bullet-pointed list below the description, indicating special requirements for the chance to be evaluated.

etc.get_power_rep_stack

Usage: etc.get_power_rep_stack(description, unit, amount)
 Returns a stack of count amount with the description Energy (<description>), followed by another line showing the raw amount including decimals plus unit concatenated to the end.