diff options
| -rw-r--r-- | Add-different-kinds-of-new-items.md | 63 | ||||
| -rw-r--r-- | Tutorials.md | 1 |
2 files changed, 64 insertions, 0 deletions
diff --git a/Add-different-kinds-of-new-items.md b/Add-different-kinds-of-new-items.md new file mode 100644 index 0000000..a523c95 --- /dev/null +++ b/Add-different-kinds-of-new-items.md @@ -0,0 +1,63 @@ +This tutorial is for how to add different kinds of new items, including a key item, ... + + +## Contents + +1. [How item constants work](#1-how-item-constants-work) +2. [Essential item data: name, description, attributes, and effect](2-essential-item-data-name-description-attributes-and-effect) +3. [Examples](3-examples) + + +## 1. How item constants work + +Item constants are defined in [constants/item_constants.asm](../blob/master/constants/item_constants.asm). But unlike some constants, they're not a simple sequence where you can append new items to the end. + +There are 256 valid item IDs, from $00 to $FF, broken into different segments: + +- **$00:** `NO_ITEM`. Zero indicates the lack of an item; leave this alone. +- **$01–$BE:** `MASTER_BALL` to `ITEM_BE`, including 23 unused <code>ITEM_<i>XX</i></code> constants. The <code>ITEM_<i>XX</i></code> constants are simplest to replace with any kind of item you want, except for TMs or HMs. +- **$BF–$F2:** `TM_DYNAMICPUNCH` to `TM_NIGHTMARE`, along with the unused `ITEM_C3` and `ITEM_DC`. These are defined with an `add_tm` macro that simultaneously defines the <code>TM_<i>MOVENAME</i></code> item constant (starting at whatever the current item ID is; by default it's $BF) and the <code><i>MOVENAME</i>_TMNUM</code> constant (starting at 1). Any item constants after the first TM are assumed to also be TMs, which is why you can't just add new items to the end of the list. Note that `ITEM_C3` and `ITEM_DC` are kind of unusable—they can't be normal items, and some TM-related code manually skips over those two slots—so if you want to use them you'll have to [correct that design flaw](../blob/master/docs/design_flaws.md#item_c3-and-item_dc-break-up-the-continuous-sequence-of-tm-items). +- **$F3−$F9:** `HM_CUT` to `HM_WATERFALL`. These are defined with an `add_hm` macro that simultaneously defines the <code>HM_<i>MOVENAME</i></code> item constant (starting at whatever the current item ID is; by default it's $F3) and the <code><i>MOVENAME</i>_TMNUM</code> constant (starting at whatever the current TM/HM number is; by default it's 51). Any item constants after the first HM are assumed to also be HMs, with all the differences that implies (they'll have an "H" in the Pack, using them will print "Booted up an HM", they can't be tossed, etc). +- **$FA−$FE:** Not really usable, and of these ID values, only `ITEM_FA` is defined. +- **$FF:** `ITEM_FROM_MEM`. A special value used in some scripts to give whatever item is in `wScriptVar`, instead of a hard-coded item. (For instance, fruit trees rely on it so they don't need a separate script for each kind of Berry and Apricorn.) + +(Note that after the `add_tm`s and `add_hm`s, there are also some `add_mt`s. This macro defines more <code><i>MOVENAME</i>_TMNUM</code> constants, but not more <code>TM_<i>MOVENAME</i></code> or <code>HM_<i>MOVENAME</i></code> constants, so the moves are recognized as teachable but don't have an associated item.) + +It's important to understand that there's nothing special about the specific numeric values, except $00 and $FF. `const_def` starts a new constant sequence at 0, and every `const`, `add_tm`, or `add_hm` after that defines the next constant in the sequence. In the line "`const BRIGHTPOWDER ; 03`", the "`; 03`" is just a comment; `BRIGHTPOWDER` has the value $03 only because it's the fourth item in the sequence (remember, IDs start at 0, not 1). So if you add or remove something in the middle of the sequence, everything after it will be shifted. To avoid getting confused, when you add or remove an item, update the comments with the new ID values. + + +## 2. Essential item data: name, description, attributes, and effect + +You may have already guessed this from the comment at the top of [constants/item_constants.asm](constants/item_constants.asm): + +```asm +; item ids +; indexes for: +; - ItemNames (see data/items/names.asm) +; - ItemDescriptions (see data/items/descriptions.asm) +; - ItemAttributes (see data/items/attributes.asm) +; - ItemEffects (see engine/items/item_effects.asm) +``` + +Every kind of item has these pieces of data. `ItemNames`, `ItemDescriptions`, `ItemAttributes`, and `ItemEffects` are four tables with an entry for each item constant, one after another. It's important for them all to be in sync, so that the Nth constant correctly matches the Nth name, the Nth description, and so on. + +**Names** are defined in [data/items/names.asm](../blob/master/data/items/names.asm). They're simply written as <code>db "<i>NAME</i>@"</code>: an opening quote, the name, an ending "@", and a closing quote. Names can be up to 12 characters long. The number of *printed* characters also matters, since screens like the Pack and the Mart menus are a fixed width. For example, when the name `"# DOLL@"` gets printed as "POKé DOLL", that's 9 characters, not 6. + +**Descriptions** are defined in [data/items/descriptions.asm](../blob/master/data/items/descriptions.asm). Unlike with names, each entry in the table of descriptions is a pointer to the actual description data. Descriptions have room for two lines, each with up to 18 characters. Again, what matters is the printed length, since they have to fit in a text box of that size. + +**Attributes** are defined in [data/items/attributes.asm](../blob/master/data/items/attributes.asm). They use an `item_attribute` macro that defines many pieces of data at once: + +* **price:** The price in Marts. Prices range from ¥0 to ¥65535 ($FFFF, the maximum value of a two-byte quantity). Items can be resold for half the price. +* **held effect:** The effect when held by a Pokémon. A `HELD_*` constant, or 0 if the item does nothing when held. The `HELD_*` constants are defined in [constants/item_data_constants.asm](../blob/master/constants/item_data_constants.asm). Creating a new held item effect is beyond the scope of this tutorial, but you can look at which effect constants are used by existing items to see what they do. +* **parameter:** A piece of extra data associated with the item. Usually 0, but some item effects use this parameter. For instance, BrightPowder's parameter of 20 is interpreted by `BattleCommand_CheckHit` as an extra 20/256 (~7.8%) chance to miss a move. +* **property:** Controls whether you can select and/or toss the item. 0, `CANT_SELECT`, `CANT_TOSS`, or `CANT_SELECT | CANT_TOSS`. Most items have `CANT_SELECT`, except for the usefully selectable ones like Bicycle or ItemFinder. `CANT_TOSS` is for key items and HMs. +* **pocket:** Which pocket it goes in. `ITEM`, `KEY_ITEM`, `BALL`, or `TM_HM`. +* **field menu:** What the item does when you try to use it in the field (i.e. outside of battle). `ITEMMENU_NOUSE` can't be used at all ("OAK: <i>PLAYER</i>! This isn't the time to use that!"); `ITEMMENU_CURRENT` just uses it right away (like Repel or Coin Case); `ITEMMENU_PARTY` lets you choose a party Pokémon to use it on (like Potion or HP Up); and `ITEMMENU_CLOSE` has a confirmation menu before using it (like Bicycle or Escape Rope). +* **battle menu:** What the item does when you try to use it during battle. Another `ITEMMENU_*` constant. + +**Effects** are defined in [engine/items/item_effects.asm](../blob/master/engine/items/item_effects.asm). Like descriptions, there's a table of pointers to the effects themselves, and the pointers are what correspond directly with item constants. Effects are implemented in assembly code, and are virtually unlimited in what they can do. But many of them are flexible. Effects like `PokeBallEffect`, `StatusHealingEffect`, or `EvoStoneEffect` get reused for many different items, and the items' particular details come from their attributes or from extra data tables related to that kind of item. Next we'll see how to add new items that use some of these general-purpose effects. + + +## 3. Examples + +TODO diff --git a/Tutorials.md b/Tutorials.md index ab81387..277fdea 100644 --- a/Tutorials.md +++ b/Tutorials.md @@ -10,6 +10,7 @@ Tutorials may use diff syntax to show edits: **How to add a new…** - [Type (Fairy)](Add-a-new-Fairy-type) +- [Item (many kinds of examples)](Add-different-kinds-of-new-items) - [Music song](Add-a-new-music-song) **Upgrades to existing features:** |