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.