pokeplatinum/docs/datafiles/items.md

Item Data File Format

This document describes the file format for item data consumed by the itemproc build tool. Each item in the ROM is represented by a JSON file res/items/data/<name>.json. Fields from each of these files are mapped onto the ItemData struct from include/item.h and the BerryData struct from include/berry_data.h.

Bogus items in the retail ROM—those with the ITEM_UNUSED_ prefix—do not have corresponding JSON files. They are assigned placeholder text in the output, but they do not produce a data entry.

Schema

Field	Type	Description
name	string	The item's display name (singular).
plural	string	The item's display name (plural).
article	string	Indefinite article (e.g. "a", "an") for in-game text.
description	string[]	The item's description, as an array of lines.
icon	object	References to the item's icon graphics. See below.
gbaID	string	The corresponding Gen-III item identifier, or GBA_ITEM_NONE for Gen-IV items.
price	u16	Base price in Pokédollars paid when purchasing from a shop. 0 means the item cannot be sold.
effectParam	u8	Generic parameter; semantics vary by item type (e.g., heal amount).
holdEffect	enum ItemHoldEffect	Effect when held by a Pokémon.
pluckEffect	define PLUCK_EFFECT	Effect when consumed by Bug Bite / Pluck.
flingEffect	define FLING_EFFECT	Effect when used with Fling.
flingPower	u8	Base power of Fling when this item is flung.
naturalGiftPower	u8	Base power of Natural Gift when this item is held. 0 if not a berry.
naturalGiftType	enum PokemonType or null	Type of Natural Gift when this item is held. null if not a berry.
preventToss	bool	If true, then the item cannot be tossed or sold.
canRegister	bool	If true, then the item can be registered to the Y button.
fieldPocket	define POCKET	The Bag pocket the item belongs to (Items, Medicine, etc.).
battlePocket	define BATTLE_POCKET_MASK	The battle pocket mask for use during battle.
fieldUseFunc	define ITEM_USE_FUNC	The field-use function invoked from the overworld.
battleUseFunc	u8	The battle-use function invoked from the battle menu.
itemUseParams	object or null	Detailed usage parameters. See below.
teachesMove	enum Move	The move taught by this TM or HM (only for TMs/HMs).
berryData	object	Berry growth and flavor data (only for berries). See below.

The icon Object

Field	Type	Description
sprite	string	Name of the NCGR sprite resource for the item icon.
palette	string	Name of the NCLR palette resource for the item icon.

These fields map to the in-game files produced from the inputs in res/items/icons.

The itemUseParams Object

This object defines the parameters for items that act on a Pokémon in the party or in battle. All fields are optional and default to 0 or false.

Field	Type	Description
healSleep	bool	Cures sleep.
healPoison	bool	Cures poison.
healBurn	bool	Cures burn.
healFreeze	bool	Cures freeze.
healParalysis	bool	Cures paralysis.
healConfusion	bool	Cures confusion.
healAttract	bool	Cures infatuation.
guardSpec	bool	Temporarily protects from stat reduction.
revive	bool	Revives a fainted Pokémon.
reviveAll	bool	Revives all fainted Pokémon.
levelUp	bool	Increases the Pokémon's level by one.
ppUp	bool	Increases a move's PP.
ppMax	bool	Maximizes a move's PP.
restorePPAllMoves	bool	Restores PP to all moves.
atkStages	u8	Attack stage change (0–4).
defStages	u8	Defense stage change (0–4).
spatkStages	u8	Special Attack stage change (0–4).
spdefStages	u8	Special Defense stage change (0–4).
speedStages	u8	Speed stage change (0–4).
accStages	u8	Accuracy stage change (0–4).
critStages	u8	Critical-hit ratio stage change (0–2).
hpRestored	s8	HP restored. Use -1 for 100%, -2 for 50%, or -3 for 25%.
ppRestored	s8	PP restored. Use -1 for 100%.
hpEVs	s8	HP EVs gained.
atkEVs	s8	Attack EVs gained.
defEVs	s8	Defense EVs gained.
speedEVs	s8	Speed EVs gained.
spatkEVs	s8	Special Attack EVs gained.
spdefEVs	s8	Special Defense EVs gained.
friendshipLow	s8	Friendship change when friendship < 100.
friendshipMed	s8	Friendship change when 100 ≤ friendship < 200.
friendshipHigh	s8	Friendship change when friendship ≥ 200.

When fieldUseFunc is set to ITEM_USE_FUNC_BERRY, ITEM_USE_FUNC_EVO_STONE, ITEM_USE_FUNC_HEALING, or any other use function that acts on a party Pokémon, this object is optional but will be used if present.

The berryData Object

Field	Type	Description
size	u16	Size of the berry in millimeters.
firmness	define FIRMNESS	Firmness category (Very Soft through Super Hard).
baseYield	u8	Base yield per plant.
stageDuration	u8	Number of stages to grow.
moistureDrainRate	u8	How quickly moisture drains.
spiciness	u8	Spicy flavor value.
dryness	u8	Dry flavor value.
sweetness	u8	Sweet flavor value.
bitterness	u8	Bitter flavor value.
sourness	u8	Sour flavor value.
smoothness	u8	Smoothness for Poffin cooking.

This field is only recognized when fieldUseFunc is ITEM_USE_FUNC_BERRY.

Outputs

The tool produces the following outputs:

Output	Description
pl_item_data.narc	ItemData entries for every item, packed by index ID.
item_id_map.h	Maps item IDs to data index, icon resource, palette, and Gen-III ID.
item_tm_move_map.h	Maps TM indices to the move they teach.
item_berry_list.h	Lists all berry items by their berry index.
item_mail_list.h	Lists all mail items by their mail type index.
item_names.json	Text bank for singular item names.
item_names_plural.json	Text bank for plural item names.
item_names_with_articles.json	Text bank for item names with their indefinite article.
item_descriptions.json	Text bank for item descriptions.
hidden_item_scripts.h	Generated header mapping hidden item script IDs to script entries.
nuts_data.narc	BerryData entries for each in-game berry.

Example

{
    "name": "Potion",
    "plural": "Potions",
    "article": "a",
    "description": [
        "A spray-type medicine for wounds.\n",
        "It restores the HP of one Pokémon by\n",
        "just 20 points."
    ],
    "icon": {
        "sprite": "potion_NCGR",
        "palette": "potion_NCLR"
    },
    "gbaID": "GBA_ITEM_POTION",
    "price": 300,
    "effectParam": 20,
    "holdEffect": "HOLD_EFFECT_NONE",
    "pluckEffect": "PLUCK_EFFECT_NONE",
    "flingEffect": "FLING_EFFECT_NONE",
    "flingPower": 30,
    "naturalGiftPower": 0,
    "naturalGiftType": null,
    "preventToss": false,
    "canRegister": false,
    "fieldPocket": "POCKET_MEDICINE",
    "battlePocket": "BATTLE_POCKET_MASK_RECOVER_HP",
    "fieldUseFunc": "ITEM_USE_FUNC_HEALING",
    "battleUseFunc": 2,
    "itemUseParams": {
        "hpRestored": 20
    }
}