mirror of
https://github.com/pret/pokeplatinum.git
synced 2026-08-06 02:33:28 -05:00
167 lines
12 KiB
Markdown
167 lines
12 KiB
Markdown
# 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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
}
|
||
```
|