Relevant files: item.lua, spell.lua, inventory.lua

Types of Items

There are multiple kinds of items available to make in Kristal. These types are armor, weapon, item, and key, and their files go in scripts/data/items. All dark world items are created by extending the global Item class, but light world equipment should be made by extending LightEquipItem instead (although they share all the same variables and functions).

The following variables can be defined when creating the item:

name: The name that displays in menus.
type: A string, being either item, key, weapon, or armor.
icon: The sprite path used for the item's icon, if it's an equippable item.
effect: A brief description of the item, used in battles.
shop: A brief description of the item, used in shops.
description: The description used in the overworld menu.
buy_price: The price the item can be bought for in shops.
sell_price: The price the item can be sold for in shops.
can_sell: Whether the item is able to be sold in shops.
target: A string defining who would be targeted by using the item. Options are: ally, referring to a single party member; party, referring to every party member; enemy, referring to a single enemy in a battle; enemies, referring to every enemy in a battle; and none, which means the player cannot select a target. Defaults to none.
usable_in: If the item is consumable, describes where the item can be used, being either world, battle, all, or none. Defaults to all.
result_item: If defined, then the item will transform into the item with this ID when consumed.
instant: If true, then if the item is consumed in battle, it will occur instantly, without describing the action.
bonuses: A table of values, with indexes referring to stat names (either defense, attack, or magic), and values referring to the change the item gives.
bonus_name: An extra name that can be used for another bonus (such as Cuteness).
bonus_icon: The sprite path used for the bonus name's icon.
can_equip: A table of values, with indexes referring to party member IDs, and values being a boolean determining whether the party member can equip it. For armors, this defaults to true for every party member; for weapons, this defaults to false for every party member.
reactions: A table of values, with indexes referring to party member IDs, and values being either a string, or another table. When it's a string, the associated party member will display this dialogue when given the item. When it's a table, the table must follow the same format as this table, with indexes being party IDs; when the associated party member is given the item, each party member will display their dialogue from this table.
dark_item: An optional string used by light world items to convert them into their dark counterpart upon entering a dark world.

In order for items (particularly consumables) to perform actions, functions must be overridden so they have behavior that gets run at certain events. All functions that occur during battles for items have the arguments user and target. user is the PartyBattler that is using the item, and target will be either a PartyBattler, an EnemyBattler, or nil, depending on what the item's target is. (Note that PartyBattler is not the same as PartyMember; the Battlers page clarifies the difference between these.) The functions that are available for being called and overridden are:

getName(), getDescription(), getBattleDescription(), getBuyPrice(), getSellPrice(), getStatBonuses(), getBonusName(), getBonusIcon(), getReactions(), isSellable(), getCheck(): Called to retrieve values. By default, returns their respective values.
getShopDescription(): Called to retrieve the item's shop description. By default, it returns a string combining the type of item it is, and its shop variable.
hasResultItem(): Returns whether the item has result_item defined.
createResultItem(): Returns a new Item instance based on result_item.
onEquip(character): Called when the item is equipped to a party member. character refers to a PartyMember instance, since this function is called in the overworld.
onCheck(): Called when the INFO option is selected on the item in the light world. By default, shows text displaying getName() and getCheck().
onToss(): Called when the DROP option is selected on the item in the light world. If this function returns false, the item will not be dropped. By default, shows random text about dropping the item, and returns true.
onWorldUse(character): Called when the item is used in the overworld (does not apply for equippable items).
onBattleUse(user, target): Called when the item is used in battle.
onBattleSelect(user, target): Called when the item is selected for use in battle.
onBattleDeselect(user, target): Called when the item selection is undone in battle.
onWorldUpdate(chara): Called every frame during overworld gameplay, if the item is equipped to a party member. chara is the Character instance that has the item equipped.
onBattleUpdate(battler): Called every frame during battle gameplay, if the item is equipped to a party member. battler is the PartyBattler instance that has the item equipped.
getBattleText(user, target): Returns a string used when the item is consumed in battle.
applyGoldBonus(gold): Returns how much gold the party will earn from a battle, taking in the current amount they'll receive as an argument. Useful if items affect how much gold the party should receive.
canEquip(chara, slot_type, slot_index): Whether the specified party member is able to equip the item. chara is the PartyMember instance that is attempting to equip the item, slot_type is a string referring to the type of item it is, and slot_index is a number referring to the slot the item is being applied to. This function is sometimes called without slot_type or slot_index being passed in. By default, if the item is an armor, it will return true for all party members that do not specify otherwise; if the item is a weapon, it will return false for all party members unless specified otherwise.
getReaction(user, reactor): Returns the reaction a party member will have to another party member using an item. user is the ID of the party member using the item, and reactor is the ID of the party member that is reacting. By default, returns a string based on getReactions().
getTypeName(): Returns a string describing the type of the item. By default, it returns Item, Key Item, Weapon, or Armor if its type is one of those four, or Unknown otherwise.
convertToLight(inventory): Returns whether the item should be converted to a new item upon entering the light world, or if it should be added to the Ball of Junk. inventory is the Inventory instance that will be used for the light world. If this function returns false, the item will be added to the Ball of Junk; if it returns true, the item will not be added to the Ball of Junk, and the item will not be readded upon reentering a dark world (useful if you need to add the item to the light world inventory manually); and if it returns either an Item instance or an Item ID, the specified item will be added to the light world inventory, and will convert back to its normal form upon reentering a dark world. By default, it returns false, adding the item to the Ball of Junk.
convertToDark(inventory): Returns whether the item should be converted to a new item upon entering a dark world. inventory is the Inventory instance that will be used for the dark world. If this function returns either an Item instance or an Item ID, the specified item will be added to its corresponding storage; otherwise, no item will be automatically added. By default, if the item was formerly a dark world item, it will return that item; otherwise, it returns false.
setFlag(flag, value): Sets a save data flag for the item to the specified value.
addFlag(flag, amount): Adds to the value stored to the specific flag.
getFlag(flag, default): Gets a save data flag for the item, returning default if the flag doesn't exist.

Additionally, there are extensions of Item that can be used: HealItem, TensionItem, and LightEquipItem. HealItems and TensionItems are convenient Item extensions that exist to make creating healing items simple, and LightEquipItems are items that can be extended to create equippable items to be used in the light world. The following defines the variables and functions useful for each:

HealItem

heal_amount: The amount the party member should be healed by upon using the item.
world_heal_amount: An optional number defining the amount of health healed when used in the overworld.
battle_heal_amount: An optional number defining the amount of health healed when used during battles.
heal_amounts: An optional table of values, with each index referring to the ID of a party member and each value defining how much health that party member should be healed by upon using the item.
world_heal_amounts: An optional table of values, defining the amount of health a party member will be healed by when used in the overworld.
battle_heal_amounts: An optional table of values, defining the amount of health a party member will be healed by when used during battles.
getHealAmount(id): Returns the amount the specified party member should be healed. id is a string referring to a party member ID. By default, returns the value defined in heal_amounts for the specified party member if it exists, and heal_amount otherwise.
getWorldHealAmount(id): Returns the amount the specified party member should be healed when the item is used in the overworld. By default, returns the value defined in world_heal_amounts for the specified party member if it exists, then world_heal_amount if it is defined, then getHealAmount() otherwise.
getBattleHealAmount(id): Returns the amount the specified party member should be healed when the item is used during battles. By default, returns the value defined in battle_heal_amounts for the specified party member if it exists, then battle_heal_amount if it is defined, then getHealAmount() otherwise.

TensionItem

tp_amount: The TP percentage the player should receive when the item is consumed during battles. getTensionAmount(): Returns the TP percentage the player should receive when the item is consumed during battles. By default, returns tp_amount.

Kristal implements nearly all items from Deltarune by default: you can see which items exist in Kristal's data/items folder, and can use them the same way you'd use custom items.

Inventory

The Inventory is a class that keeps track of all items the party has for a save file. Game.inventory is a global reference to the current inventory being used (either a dark world inventory or a light world one), and the default dark world inventory of a mod can be set in the mod.json. Inventory has 5 tables, called "storages", by default: items, key_items, weapons, armors, and storage. The first 4 contain their respective items, and storage is an extra table where consumable items will go if the items storage is full.

Inventory has the following variables and functions available for usage:

storages: A table of tables, each defining a storage in the player's inventory.
storage_enabled: Whether the storage storage will be used when the items storage is full. By default, true if the mod's chapter is greater than 1.

addItem(item): Adds an item to the inventory, putting it in the appropriate storage, if the storage is not full. item can be either an Item instance, or a string referring to the ID of an item. Returns the item if it was succesfully added, and nil otherwise.
addItemTo(storage, item, allow_fallback), addItemTo(storage, index, item, allow_fallback): Adds an item to the specified storage if it's not full. storage is either a storage table or a string referring to the ID of a storage, index is an optional value specifying which index the item should be added to (defaulting to the first open slot), item is either an Item instance or a string referring to the ID of the item to add, and allow_fallback is a boolean determining whether the item should be allowed to go to the specified storage's backup storage if it's failed to be added. Returns the item if it was successfully added, and nil otherwise.
removeItem(item): Removes the specified item from the inventory. item is either an Item instance or a string referring to an item ID to be removed from the inventory. Returns the item if it was successfully removed, and nil otherwise.
removeItemFrom(storage, index): Removes the item found in the specified storage at the specified index. storage is either a storage table or a string referring to the ID of a storage, and index is the index to remove the item from. Returns the item if it was successfully removed, and nil otherwise.
setItem(storage, index, item): Sets the specified index in the specified storage to the item, overwriting the previous item there if one existed. storage is either a storage table or a string referring to the ID of a storage, index is the index of the storage to set, and item is either an Item instance or a string referring to an item ID. Returns the item. If item is not defined, it will set the specified storage slot to be empty.
getItemIndex(item): Gets the index the specified item takes in the inventory if it exists. item is either an Item instance or a string referring to an item ID. Returns the storage table and index the item was found at, if it exists, and nil otherwise. replaceItem(item, new): Replaces the specified item with a new item. item is either an Item instance or a string referring to an item ID of an item in the inventory, and new is either an Item instance or a string referring to an item ID to replace the old item with.
swapItems(storage1, index1, storage2, index2): Swaps the items at the specified storages and indexes. storage1 and storage2 are either storage tables or strings referring to the IDs of storages, and index1 and index2 are the indexes of the items to swap.
getItem(storage, index): Returns the item at the specified storage and index. storage is either a storage table or a string referring to the ID of a storage, and index is the index of the storage to check.
hasItem(item): Returns whether the inventory has the specified item in any of its storages. item is either an Item instance or a string referring to an item ID.
isFull(storage, allow_fallback): Returns whether the specified storage and its fallback storage is full. storage is either a storage table or a string referring to the ID of a storage, and allow_fallback determines whether the storage should check fallback storages too.
getItemCount(storage, allow_fallback): Returns the number of items in the specified storage and its fallback storage. storage is either a storage table or a string referring to the ID of a storage, and allow_fallback determines whether the storage should check fallback storages too.
getFreeSpace(storage, allow_fallback): Returns how many empty spaces are in the specified storage and its fallback storage. storage is either a storage table or a string referring to the ID of a storage, and allow_fallback determines whether the storage should check fallback storages too.
getStorage(type): Returns the storage table for the specified ID.
getDefaultStorage(type): Returns the storage table used for the specified item type.

Defining a Spell

Spells are created by extending the global Spell class, very similarly to items. The following are fields that Spell can take:

name: The name that displays in menus.
cast_name: The name used by default in getCastMessage(). If undefined, getCastMessage() will just use name in full uppercase.
effect: A brief description of the spell, used in battles.
description: The description used in the overworld menu.
cost: The TP cost of the spell.
target: A string defining who would be targeted by using the item. Options are: ally, referring to a single party member; party, referring to every party member; enemy, referring to a single enemy in a battle; enemies, referring to every enemy in a battle; and none, which means the player cannot select a target. Defaults to none.
tags: A table of strings, listing properties of the spell. These tags can be checked by code in other places, to apply effects to certain kinds of spells. Example tags used in Kristal's code are rude, ice, and spare_tired. If a spell has the spare_tired tag, it will be highlighted when an enemy is tired.

Similarly to items, all spells have user and target variables, referring to PartyBattlers or EnemyBattlers. Functions that can be overridden or called include:

getName(), getCastName(), getDescription(), getBattleDescription(): Called to retrieve their associated values.
getTPCost(chara): Called to retrieve the TP cost of the spell. chara is the PartyMember instance using the spell.
getCastMessage(user, target): Text that's used when the spell is cast. Returns a combination of the user's name and getCastName().
hasTag(tag): Returns whether the spell has the specified tag.
onCast(user, target): Code that gets run when the spell is cast. This is where you would want to handle the effects of the spell, such as damage or healing.