Item Syntax

The Item Syntax has 3 components: amount, name, and metadata

get    3        pot-lid   [durability=3]
#      ^ amount ^ name    ^ metadata

The syntax could be used in 3 scenarios, depending on the command:

1. FINITE_ITEM_LIST

   • The amount must be a number, not keywords like all.
   • The name must be an item, not category.
   • The metadata is used to describe extra properties of the item.
   • Generally used by commands for adding items, such as get

2. INFINITE_ITEM_LIST

   • The amount could be a number or the keyword infinite.
   • The name could be an item or a category.
   • The metadata is used to describe extra properties of the item.
   • Currently, this form is not used by any command.

3. CONSTRAINED_ITEM_LIST

   • The amount could be a number, or:
     • The keyword all
     • In the form all but X, where X is a number.
   • The name could be an item or a category.
   • The metadata is used to match from items in some existing list (such as your inventory)
   • Generally used by commands that targets some item, such as hold and eat.
   • Position properties can be used

Amount

The amount of item may have different meaning in different commands. For example, when using the eat command, the amount is always the internal value (i.e. the stack size), since you can eat from corrupted food or decrease armor value/durability by eating. When using sell, however, the amount means how many slots for unstackable items.

In CONSTRAINED_ITEM_LIST, you can use 2 special amount forms: all and all but:

• all will repeatly find the item and perform the action on the item, until the item cannot be found.
• all but X will first count the total number of times the action can be performed, then perform the action count - X times. How the total number is counted depends on the command, similar to the eat vs sell situation mentioned earlier.

Name

You can specify the name of the item in 4 ways:

1. By Identifier - An Item Identifier is multiple english words (A to Z, case-insensitive), combined with - or _. For example, royal-claymore and trav-bow are both valid identifiers. There is a fixed algorithm for resolving the identifier to an item.
   • The result is an item that contains all the individual words, for example trav-bow results in traveller’s bow.
   • You can add an effect before a food item to specify the cook effect. For example hasty-elixir, sneaky-wild-greens
   • Plural forms with -s, -es, -ies postfixes are supported. They don’t affect the amount of the item, only makes the command sounds more natural in English.
   • Some shorthands are supported in this form. For example, geb for great-eagle-bow, aa for ancient-arrow.
2. By Actor - You can use angle brackets (<>) to specify the internal actor name directly, for example get <Weapon_Sword_070>. You cannot specify cook effect in this way.
3. By Localization - If English is not your preferred language, you can specify items by their localized name using a quoted-string. For example, "espadon royal" or "王族双手剑".
   • The string is fuzzy-searched in all languages
   • To lock the language, prepend the query with the language and a colon, for example, "fr:espadon royal" this could be useful if the query is short, and is matching in another language that you didn’t expect.
   • Localized search only applies to items, not commands (like get, hold, etc)
4. By Category - When selecting items from inventory or some other list of items, you can also use a category in the place of the item name to match the first item of that category. This can be useful in situations like unequip shield where you don’t need to care what shield is currently equipped, or pick-up 3 weapons, where it doesn’t matter which weapons are picked up.

Metadata

Metadata specifies extra properties of the item, in the format of [key1=value1, key2=value2, ...], either = or : can be used as the key/value delimiter

• In FINITE_ITEM_LIST, it is used to specify extra data on the item to be added
  • For example, get pot-lid[durability=1] gets a new pot-lid with 1 durability
• In CONSTRAINED_ITEM_LIST, it is used to specify extra data used to match the item to operate on.
  • For example, if you are multiple pot-lids, drop pot-lid[durability=1] targets the one with exactly 1 durability.

The metadata value can be one of the following types:

• string - english words separated by - or _
• int - an integer in decimal or hex (prefixed with 0x)
• float - a floating point number with 2 integers separated by . (the whole number part and the decimal part, both needs to be in decimal).
• bool - true or false. The value can be omitted to indicate true, for example, drop pot-lid[equipped] is the same as drop pot-lid[equipped=true]

Full list of item metadata properties:

Selecting from multiple matches

In CONSTRAINED_ITEM_LIST, there could be the case where there are multiple items that are exactly the same. There are additional meta properties that you can use to pick exactly which slot to select.

With from-slot property, you can pick the i-th matched item. For example, if there are 3 Pot Lids, you can use drop pot-lid[from-slot=2] to drop the second Pot Lid. The number is 1-indexed.

You can also target an item by its position in the inventory directly with one of the following methods:

# This is the same as using `from-slot`
# If there are >=2 slots of apple, this will eat from the second slot
eat 2 apple[slot=2]

# Category can be used as the name
# This eats the second slot in the entire inventory that is a material
eat 2 material[slot=2]

# Eat 2 apples from the material tab, in the first row and second column
# When using `category`, the indices are 1-indexed
eat 2 apple[category=material, row=1, col=2]

# Eat 2 apples from the second material tab, in the first row and second column
eat 2 apple[category=material, tab=2, row=1, col=2]

# Eat 2 apples from the second material tab, in the 0-th slot.
# The tab is 1-indexed.
# The slot is the 0-indexed slot in that tab, arranged like this:
# 00 01 02 03 04
# 05 06 07 08 09
# 10 11 12 13 14
# 15 16 17 18 19
eat 2 apple[category=material, tab=2, slot=0]

# Eat 2 apples from the 0-th tab, in the 3rd slot
# The tab index here is the 0-based index in the entire tab array
# The slot is the 0-indexed slot in that tab, see above
eat 2 apple[tab=0, slot=3]