Add a Big Nugget

2 files changed, 110 insertions, 11 deletions

diff --git a/Add-different-kinds-of-new-items.md b/Add-different-kinds-of-new-items.md
index 41e0103..51ed5b5 100644
--- a/Add-different-kinds-of-new-items.md
+++ b/Add-different-kinds-of-new-items.md
@@ -6,24 +6,28 @@ This tutorial is for how to add different kinds of new items, including a key it
 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. [No effect: Big Nugget](#no-effect-big-nugget)
+   2. [`RestoreHPEffect`: Sweet Heart](#restorehpeffect-sweet-heart)
+   3. [`StatusHealingEffect`: Lava Cookie](#statushealingeffect-lava-cookie)
+   4. [`PokeBallEffect`: Dusk Ball](#pokeballeffect-dusk-ball)
+   5. [`EvoStoneEffect`: Mist Stone](#evostoneeffect-mist-stone)
+   6. [`TownMapEffect`: Town Map](#townmapeffect-town-map)
 
 
 ## 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:
+- `NO_ITEM` is the first item ID, which is used to indicate a lack of item. Leave this alone.
+- Item constants start out as an ordinary sequence, from `MASTER_BALL` to `ITEM_BE`, including 23 unused <code>ITEM_<i>XX</i></code> constants. Those are simplest to replace with any kind of item you want, except for TMs or HMs.
+- After the ordinary items come the TMs, from `TM_DYNAMICPUNCH` to `TM_NIGHTMARE`. These are defined with an `add_tm` macro that simultaneously defines the next <code>TM_<i>MOVENAME</i></code> item constant *and* the next <code><i>MOVENAME</i>_TMNUM</code> constant (starting at 1 for the first `add_tm` use). The first time `add_tm` is used it defines `TM01` as the current item, and any items after that are assumed to also be TMs. Note that `ITEM_C3` and `ITEM_DC` are two unusable item IDs in-between the TMs—they can't become normal items, since they're greater than `TM01`, 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).
+- After the TMs come the HMs, from `HM_CUT` to `HM_WATERFALL`. These are defined with an `add_hm` macro that simultaneously defines the next <code>HM_<i>MOVENAME</i></code> item constant *and* the next <code><i>MOVENAME</i>_TMNUM</code> constant (continuing from the TMs, so for instance, `CUT_TMNUM` is 51). The first time `add_hm` is used it defines `HM01` as the current item, and any items after that 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).
+- There can't be useful items after the HMs, since by definition anything after `HM01` is treated as an HM itself. In fact, `ITEM_FA` is defined after the HMs, so you might need to move or delete it.
+- `ITEM_FROM_MEM` is the last item ID, which is 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.)
 
-- **`NO_ITEM` ($00):** Zero indicates the lack of an item; leave this alone.
-- **Regular items ($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.
-- **TMs ($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 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).
-- **HMs ($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).
-- **Unused ($FA−$FE):** Not really usable, since they're beyond the range of all kinds of items. Of these ID values, only `ITEM_FA` is even defined.
-- **`ITEM_FROM_MEM` ($FF):** 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> item constants, so the moves are recognized as teachable but don't have an associated item.)
 
-(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.
+It's important to understand that there's nothing special about the specific numeric values, except $00 for `NO_ITEM` and $FF for `ITEM_FROM_MEM`. `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.
 
 
 ## 2. Essential item data: name, description, attributes, and effect
@@ -59,9 +63,104 @@ Every kind of item has these pieces of data. `ItemNames`, `ItemDescriptions`, `I
    - `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.
+**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 `StatusHealingEffect`, `PokeBallEffect`, 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
 
+### 1. No effect: Big Nugget
+
+To start with, we'll implement a new item that just has the essential data. A Big Nugget doesn't do anything, it just has a high price. So here's how to add one:
+
+Edit [constants/item_constants.asm](../blob/master/constants/item_constants.asm):
+
+```diff
+ 	const WATER_STONE  ; 18
+-	const ITEM_19      ; 19
++	const BIG_NUGGET   ; 19
+ 	const HP_UP        ; 1a
+```
+
+Edit [data/items/names.asm](../blob/master/data/items/names.asm):
+
+```diff
+ 	db "WATER STONE@"
+-	db "TERU-SAMA@"
++	db "BIG NUGGET@"
+ 	db "HP UP@"
+```
+
+Edit [data/items/descriptions.asm](../blob/master/data/items/descriptions.asm):
+
+```diff
+ 	dw WaterStoneDesc
+-	dw TeruSama2Desc
++	dw BigNuggetDesc
+ 	dw HPUpDesc
+
+ 	...
+
+-TeruSama2Desc:
+-	db   "?@"
++BigNuggetDesc:
++	db   "Made of pure gold."
++	next "Sell very high.@"
+```
+
+Edit [data/items/attributes.asm](../blob/master/data/items/attributes.asm):
+
+```diff
+-; ITEM_19
+-	item_attribute $9999, 0, 0, 0, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
++; BIG_NUGGET
++	item_attribute 20000, 0, 0, CANT_SELECT, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
+```
+
+Edit [data/items/item_effects.asm](../blob/master/data/items/item_effects.asm):
+
+```diff
+ 	dw EvoStoneEffect      ; WATER_STONE
+-	dw NoEffect            ; ITEM_19
++	dw NoEffect            ; BIG_NUGGET
+ 	dw VitaminEffect       ; HP_UP
+```
+
+And last, edit [data/items/catch_rate_items.asm](../blob/master/data/items/catch_rate_items.asm):
+
+```diff
+ TimeCapsule_CatchRateItems: ; 28785
+-	db ITEM_19, LEFTOVERS
+```
+
+This is an easy-to-miss edit that's needed because of the Time Capsule. When a Pokémon is traded via Time Capsule from RBY to GSC, the byte in its data structure that represents its catch rate is interpreted as its held item. (A catch rate byte no longer exists in GSC, since that's part of base data.) For example, Jigglypuff's catch rate is 170, or $AA, so it holds a Polkadot Bow when traded to GSC because `POLKADOT_BOW` is $AA.
+
+The `TimeCapsule_CatchRateItems` is used to convert catch rate values that don't correspond to valid items. So a Pokémon with a catch rate of $19, when traded from RBY to GSC, would hold Leftovers instead of `ITEM_19`. (And even without any trading, if a Pokémon's held item is `ITEM_19`, it will appear as "LEFTOVERS" in the status screen!) But since we're replacing `ITEM_19` with a valid item, we don't want this to happen any more.
+
+Anyway, that's all you need to add a basic item:
+
+![Screenshot](screenshots/big-nugget.png)
+
+
+### 2. `RestoreHPEffect`: Sweet Heart
+
+TODO
+
+
+### 3. `StatusHealingEffect`: Lava Cookie
+
+TODO
+
+
+### 4. `PokeBallEffect`: Dusk Ball
+
+TODO
+
+
+### 5. `EvoStoneEffect`: Mist Stone
+
+TODO
+
+
+### 6. `TownMapEffect`: Town Map
+
 TODO
diff --git a/screenshots/big-nugget.png b/screenshots/big-nugget.png
new file mode 100644
index 0000000..b2e1ab1
--- /dev/null
+++ b/screenshots/big-nugget.png