Improve tutorial

1 files changed, 55 insertions, 47 deletions

diff --git a/Add-a-new-Pokémon.md b/Add-a-new-Pokémon.md
index e5b730c..7058636 100644
--- a/Add-a-new-Pokémon.md
+++ b/Add-a-new-Pokémon.md
@@ -5,15 +5,16 @@ This tutorial is for how to add a new species of Pokémon, allowing up to 253 sp
 
 1. [Define a species constant](#1-define-a-species-constant)
 2. [Give it a name](#2-give-it-a-name)
-3. [Define its base data](#2-define-its-base-data)
+3. [Define its base data](#3-define-its-base-data)
 4. [Define its evolutions and level-up learnset](#4-define-its-evolutions-and-level-up-learnset)
 5. [Define its egg moves](#5-define-its-egg-moves)
 6. [Define its cry](#6-define-its-cry)
 7. [Define its icon](#7-define-its-icon)
 8. [Define its Pokédex entry](#8-define-its-pokédex-entry)
 9. [Define its footprint](#9-define-its-footprint)
-10. [Define its sprites](#10-define-its-sprites)
-11. [Adding up to 253 Pokémon](#11-adding-up-to-253-pokémon)
+10. [Define its sprites and animation](#10-define-its-sprites-and-animation)
+11. [Include and point to the sprite and animation data](#11-include-and-point-to-the-sprite-and-animation-data)
+12. [Adding up to 253 Pokémon](#11-adding-up-to-253-pokémon)
 
 
 ## 1. Define a species constant
@@ -60,7 +61,7 @@ Some things to notice here:
 
 - Species constants are in national dex order; in fact, they're used as Pokédex IDs, so Munchlax is going to appear as #252.
 - `JOHTO_POKEMON` is defined right before the first Johto Pokémon, and `NUM_POKEMON` is defined right after the last non-Egg Pokémon.
-- There are a lot of data tables associated with Pokémon species! We'll go over them one by one later.
+- There are a lot of data tables associated with Pokémon species! We'll go over them one by one.
 
 
 # 2. Give it a name
@@ -216,7 +217,7 @@ Note that the order of the `EvosAttacksPointers` matters, since the entries pair
 
 Edit [data/pokemon/egg_move_pointers.asm](../blob/master/data/pokemon/egg_move_pointers.asm):
 
-```
+```diff
  EggMovePointers:: ; 0x23b11
  	dw BulbasaurEggMoves
  	...
@@ -280,6 +281,8 @@ Edit [data/pokemon/menu_icons.asm](../blob/master/data/pokemon/menu_icons.asm):
 
 Valid icons are in [constants/icon_constants.asm](../blob/master/constants/icon_constants.asm). They're used in the party menu and Day-Care.
 
+If you want a custom icon, you can define a new `ICON_*` constant, create a two-frame icon PNG in [gfx/icons](../tree/master/gfx/icons), `INCBIN` it as a 2bpp in [gfx/icons.asm](../blob/master/gfx/icons.asm), and update the corresponding pointer table in [data/icon_pointers.asm](../blob/master/data/icon_pointers.asm). Note that you can't simply add a unique icon for each Pokémon because they're all in one bank, and that's only large enough for 128 icons, not 251+. Updating the code to allow loading icons from multiple banks is left as an exercise for the reader (for now).
+
 
 ## 8. Define its Pokédex entry
 
@@ -410,46 +413,10 @@ Create **gfx/footprints/munchlax.png**:
 Running `make` will automatically create munchlax.1bpp from munchlax.png. Since it's a 1bpp file (**one** **b**it **p**er **p**ixel) you can only use black and white in the image.
 
 
-## 10. Define its sprites
+## 10. Define its sprites and animation
 
 This is a bit complicated. We need a front sprite with an animation sequence; a back sprite; and normal and shiny color palettes for both.
 
-Edit [data/pokemon/pic_pointers.asm](../blob/master/data/pokemon/pic_pointers.asm):
-
-```diff
- PokemonPicPointers::
- ; entries correspond to Pokémon species, two apiece
- 	dba_pic BulbasaurFrontpic
- 	dba_pic BulbasaurBackpic
- 	...
- 	dba_pic CelebiFrontpic
- 	dba_pic CelebiBackpic
--	dbw -1, -1 ; unused
--	dbw -1, -1 ; unused
-+	dba_pic MunchlaxFrontpic
-+	dba_pic MunchlaxBackpic
- 	dba_pic EggPic
- 	dbw -1, -1 ; unused
-```
-
-We have to use `dba_pic` here instead of a standard `dba`—declaring the bank and address of `MunchlaxFrontpic` and `MunchlaxBackpic`—because of [another design flaw](../blob/master/docs/design_flaws.md#pic-banks-are-offset-by-pics_fix). I strongly recommend removing the whole `FixPicBank` routine from [engine/gfx/load_pics.asm](../blob/master/engine/gfx/load_pics.asm), including both calls to it in that file, and just using `dba` here; then you'll be able to `INCBIN` sprites in arbitrary banks.
-
-Edit [gfx/pics.asm](../blob/master/gfx/pics.asm):
-
-```diff
- SECTION "Pics 19", ROMX
-
--; Seems to be an accidental copy of the previous bank
--
--INCBIN "gfx/pokemon/spinarak/back.2bpp.lz"
--...
--INCBIN "gfx/pokemon/unown_r/back.2bpp.lz"
-+MunchlaxFrontpic: INCBIN "gfx/pokemon/munchlax/front.animated.2bpp.lz"
-+MunchlaxBackpic:  INCBIN "gfx/pokemon/munchlax/back.2bpp.lz"
-```
-
-(If you *don't* fix the `dba_pic` design flaw, you'll have to put your sprites in the "Pics" sections, which are compatible with `dba_pic`. "Pics 19" isn't used for anything useful—all its contents are unused duplicates of "Pics 18"—so it's the easiest place to start adding new sprites. But if you have a lot of new sprites to add, you risk overflowing the banks, and it's hard to fit sprites within fixed bank limits. By using just `dba`, you can create new `SECTION`s with a few sprites each, that will automatically be placed wherever they can fit in the ROM.)
-
 Create **gfx/pokemon/munchlax/front.png**:
 
 ![gfx/pokemon/munchlax/front.png](screenshots/gfx-pokemon-munchlax-front.png)
@@ -499,15 +466,56 @@ These two colors will be used for shiny Munchlax, along with the standard black
 
 When you `make` the ROM, a number of sprite-related files will be automatically generated for you:
 
-- **normal.pal:** Like shiny.pal, but with the normal colors, derived from front.png and back.png.
-- **front.dimensions:** The size of a frame from front.png.
-- **front.animated.2bpp.lz:** The compressed tiles needed to animated the sprite. Animation frames tend to have lots of duplicate tiles, since only parts of a Pokémon move at a time, so each unique tile only exists once.
+- **normal.pal:** Like shiny.pal, but with the normal colors, derived from front.png.
+- **front.dimensions:** The size of the still sprite from front.png.
+- **front.animated.2bpp.lz:** The compressed tiles needed to animate the sprite. Animation frames tend to have lots of duplicate tiles, since only parts of a Pokémon move at a time, so each unique tile only exists once.
 - **bitmask.asm:** A sequence of masks that define which spots in each frame are changed from the still sprite.
 - **frames.asm:** A sequence of lists that declare the tile IDs with which to fill in the changed spots in each frame.
 
 There are two main reasons to pay attention to these auto-generated files. One, you want to make sure that normal.pal got its colors in the right order, and have shiny.pal match it. Two, if your animation appears corrupt, you want to make sure that frames.asm isn't using too high tile IDs. A 40x40 sprite can use IDs $00 to $31; a 48x48 sprite can use up to $47; a 56x56 sprite can use up to $61. If you see IDs above those limits, edit your front.png frames so they use fewer unique tiles.
 
-Anyway, all that's left is to `INCLUDE` and point to to the new data. Edit [data/pokemon/palettes.asm](../blob/master/data/pokemon/palettes.asm):
+Anyway, all that's left is to `INCLUDE` and point to to the new data!
+
+
+## 11. Include and point to the sprite and animation data
+
+Edit [data/pokemon/pic_pointers.asm](../blob/master/data/pokemon/pic_pointers.asm):
+
+```diff
+ PokemonPicPointers::
+ ; entries correspond to Pokémon species, two apiece
+ 	dba_pic BulbasaurFrontpic
+ 	dba_pic BulbasaurBackpic
+ 	...
+ 	dba_pic CelebiFrontpic
+ 	dba_pic CelebiBackpic
+-	dbw -1, -1 ; unused
+-	dbw -1, -1 ; unused
++	dba_pic MunchlaxFrontpic
++	dba_pic MunchlaxBackpic
+ 	dba_pic EggPic
+ 	dbw -1, -1 ; unused
+```
+
+We have to use `dba_pic` here instead of a standard `dba`—declaring the bank and address of `MunchlaxFrontpic` and `MunchlaxBackpic`—because of [another design flaw](../blob/master/docs/design_flaws.md#pic-banks-are-offset-by-pics_fix). I strongly recommend removing the whole `FixPicBank` routine from [engine/gfx/load_pics.asm](../blob/master/engine/gfx/load_pics.asm), including both calls to it in that file, and just using `dba` here; then you'll be able to `INCBIN` sprites in arbitrary banks.
+
+Edit [gfx/pics.asm](../blob/master/gfx/pics.asm):
+
+```diff
+ SECTION "Pics 19", ROMX
+
+-; Seems to be an accidental copy of the previous bank
+-
+-INCBIN "gfx/pokemon/spinarak/back.2bpp.lz"
+-...
+-INCBIN "gfx/pokemon/unown_r/back.2bpp.lz"
++MunchlaxFrontpic: INCBIN "gfx/pokemon/munchlax/front.animated.2bpp.lz"
++MunchlaxBackpic:  INCBIN "gfx/pokemon/munchlax/back.2bpp.lz"
+```
+
+(If you *don't* fix the `dba_pic` design flaw, you'll have to put your sprites in the "Pics" sections, which are compatible with `dba_pic`. "Pics 19" isn't used for anything useful—all its contents are unused duplicates of "Pics 18"—so it's the easiest place to start adding new sprites. But if you have a lot of new sprites to add, you risk overflowing the banks, and it's hard to fit sprites within fixed bank limits. By using just `dba`, you can create new `SECTION`s with a few sprites each, that will automatically be placed wherever they can fit in the ROM.)
+
+Edit [data/pokemon/palettes.asm](../blob/master/data/pokemon/palettes.asm):
 
 ```diff
  PokemonPalettes: ; a8ce
@@ -644,6 +652,6 @@ That's it—we're done! Munchlax works just like every other Pokémon.
 ![Screenshot](screenshots/munchlax.png)
 
 
-## 11. Adding up to 253 Pokémon
+## 12. Adding up to 253 Pokémon
 
 TODO