Add a new move

5 files changed, 193 insertions, 6 deletions

diff --git a/Add-a-new-move.md b/Add-a-new-move.md
new file mode 100644
index 0000000..60ba60c
--- /dev/null
+++ b/Add-a-new-move.md
@@ -0,0 +1,182 @@
+This tutorial is for how to add a new move, allowing up to 254 moves. As an example, we'll add Nasty Plot.
+
+
+## Contents
+
+1. [Define a move constant](#1-define-a-move-constant)
+2. [Give it a name and description](#2-give-it-a-name-and-description)
+3. [Define its battle properties](#3-define-its-battle-properties)
+4. [Define its animation](#4-define-its-animation)
+5. [Let Pokémon learn the move](#5-let-pokémon-learn-the-move)
+
+
+## 1. Define a move constant
+
+Edit [constants/move_constants.asm](../blob/master/constants/move_constants.asm):
+
+```diff
+ ; move ids
+ ; indexes for:
+ ; - Moves (see data/moves/moves.asm)
+ ; - MoveNames (see data/moves/names.asm)
+ ; - MoveDescriptions (see data/moves/descriptions.asm)
+ ; - BattleAnimations (see data/moves/animations.asm)
+ 	const_def
+ 	const NO_MOVE      ; 00
+ 	const POUND        ; 01
+ 	...
+ 	const BEAT_UP      ; fb
++	const NASTY_PLOT   ; fc
+ NUM_ATTACKS EQU const_value + -1
+
+-	const MOVE_OR_ANIM_FC ; fc
+ 	const MOVE_OR_ANIM_FD ; fd
+ 	const MOVE_OR_ANIM_FE ; fe
+
+ ; Battle animations use the same constants as the moves up to this point
+ 	const ANIM_SWEET_SCENT_2     ; ff
+ 	...
+```
+
+Move constants are actually a subset of battle animation constants. $01 to $FB are the 251 constants from `POUND` to `BEAT_UP`; then `MOVE_OR_ANIM_FC`, `MOVE_OR_ANIM_FD`, and `MOVE_OR_ANIM_FE` are unused; then `ANIM_SWEET_SCENT_2` and above correspond to animations beyond the ones played for moves (throwing Poké Balls, showing confusion, etc). Anyway, those three `MOVE_OR_ANIM_*` constants can all be used for new moves.
+
+
+## 2. Give it a name and description
+
+Edit [data/moves/names.asm](../blob/master/data/moves/names.asm):
+
+```diff
+ MoveNames::
+ 	db "POUND@"
+ 	...
+ 	db "BEAT UP@"
++	db "NASTY PLOT@"
+```
+
+A name can be up to 12 characters long, plus a "@" at the end.
+
+Now edit [data/moves/descriptions.asm](../blob/master/data/moves/descriptions.asm):
+
+```diff
+ MoveDescriptions:: ; 2cb52
+ ; entries correspond to move ids (see constants/move_constants.asm)
+ 	dw PoundDescription
+ 	...
+ 	dw BeatUpDescription
+-	dw MoveFCDescription
++	dw NastyPlotDescription
+ 	dw MoveFDDescription
+ 	dw MoveFEDescription
+ 	dw MoveFFDescription
+ 	dw Move00Description
+ ; 2cd52
+
+-MoveFCDescription:
+ MoveFDDescription:
+ MoveFEDescription:
+ MoveFFDescription:
+ Move00Description:
+ 	db "?@"
+
+ ...
+
+ BeatUpDescription:
+ 	db   "Party #MON join"
+ 	next "in the attack.@"
++
++NastyPlotDescription:
++	db   "Sharply increases"
++	next "user's SPCL.ATK.@"
+ ; 2ed44
+```
+
+A description has two lines, each with up to 18 characters, plus a "@" at the end.
+
+
+## 3. Define its battle properties
+
+Edit [data/moves/moves.asm](../blob/master/data/moves/moves.asm):
+
+```diff
+ Moves: ; 41afb
+ ; entries correspond to constants/move_constants.asm
+ 	move POUND,        EFFECT_NORMAL_HIT,         40, NORMAL,   100, 35,   0
+ 	...
+ 	move BEAT_UP,      EFFECT_BEAT_UP,            10, DARK,     100, 10,   0
++	move NASTY_PLOT,   EFFECT_SP_ATK_UP_2,         0, DARK,     100, 20,   0
+```
+
+The `move` defines these properties:
+
+- **animation:** Which animation to play when using the move. Remember, constants like `POUND` correspond to moves but also to battle animations, as we'll see later.
+- **effect:** What effect the move has. Valid effects are in [constants/move_effect_constants.asm](../blob/master/constants/move_effect_constants.asm). Some exist that aren't used for any moves yet, like `EFFECT_SP_ATK_UP_2`.
+- **power:** The base power. 0 for non-damaging moves; 1 for moves that do damage but not with the standard formula, like Seismic Toss, Counter, or Magnitude.
+- **type:** The type.
+- **accuracy:** The accuracy, from 1 to 100.
+- **PP:** The PP, from 5 to 40. Sketch has 1 PP but it requires special-case code in some places; and 40 is the maximum because any more and PP Up could boost it out of bounds. (PP is stored in 6 bits, not a full byte, so cannot exceed 63.)
+- **effect chance:** The chances of an effect triggering. Not applicable for all effects.
+
+
+## 4. Define its animation
+
+Edit [data/moves/animations.asm](../blob/master/data/moves/animations.asm):
+
+```diff
+ BattleAnimations:: ; c906f
+ ; entries correspond to constants/move_constants.asm
+ 	dw BattleAnim_0
+ 	dw BattleAnim_Pound
+ 	...
+ 	dw BattleAnim_BeatUp
+-	dw BattleAnim_252
++	dw BattleAnim_NastyPlot
+ 	dw BattleAnim_253
+ 	dw BattleAnim_254
+ 	dw BattleAnim_SweetScent2
+ ; $100
+ 	dw BattleAnim_ThrowPokeBall
+ 	...
+ ; c929b
+
+ BattleAnim_0: ; c929b
+-BattleAnim_252: ; c929b
+ BattleAnim_253: ; c929b
+ BattleAnim_254: ; c929b
+ BattleAnim_MirrorMove: ; c929b
+ 	anim_ret
+ ; c929c
+
+ ...
+
++BattleAnim_NastyPlot:
+BattleAnim_PsychUp: ; cb917
+	anim_1gfx ANIM_GFX_STATUS
+	anim_call BattleAnim_FollowEnemyFeet_0
+	anim_bgeffect ANIM_BG_1A, $0, $1, $20
+	anim_sound 0, 0, SFX_PSYBEAM
+	anim_obj ANIM_OBJ_PSYCH_UP, 44, 88, $0
+	anim_obj ANIM_OBJ_PSYCH_UP, 44, 88, $10
+	anim_obj ANIM_OBJ_PSYCH_UP, 44, 88, $20
+	anim_obj ANIM_OBJ_PSYCH_UP, 44, 88, $30
+	anim_wait 64
+	anim_incbgeffect ANIM_BG_1A
+	anim_call BattleAnim_ShowMon_0
+	anim_wait 16
+	anim_ret
+; cb940
+```
+
+Designing a new animation is beyond the scope of this tutorial. They require careful placement and timing of different elements, and the scripting system used to do this is [poorly understood](../blob/master/docs/battle_anim_commands.md). Here we're just reusing Psych Up's animation for Nasty Plot, since it looks appropriate.
+
+
+## 5. Let Pokémon learn the move
+
+By now the move fully exists—it might show up with Metronome—but no Pokémon can use it. So add it to level-up learnsets in [data/pokemon/evos_attacks.asm](../blob/master/data/pokemon/evos_attacks.asm), egg move sets in [data/pokemon/egg_moves.asm](../blob/master/data/pokemon/egg_moves.asm), or NPC trainers' parties in [data/trainers/parties.asm](../blob/master/data/trainers/parties.asm) (see the [new Pokémon](Add-a-new-Pokémon) and [new trainer](Add-a-new-trainer-class) tutorials for help with that). Or add a new TM for it, following [the tutorial](Add-a-new-TM).
+
+I added `NASTY_PLOT` to these sets, based on their canon ones in later generations:
+
+- [data/pokemon/evos_attacks.asm](../blob/master/data/pokemon/evos_attacks.asm): Meowth, Persian, Drowzee, Hypno, Mew, Pichu, Aipom, Slowking, Girafarig, Houndour, Houndoom
+- [data/pokemon/egg_moves.asm](../blob/master/data/pokemon/egg_moves.asm): Zubat, Drowzee, Mr. Mime, Togepi, Misdreavus, Houndour, Smoochum
+- [data/trainers/parties.asm](../blob/master/data/trainers/parties.asm): Karen's Houndoom
+
+![Screenshot](screenshots/nasty-plot.png)
diff --git a/Add-a-new-music-song.md b/Add-a-new-music-song.md
index 89d01d4..41410f9 100644
--- a/Add-a-new-music-song.md
+++ b/Add-a-new-music-song.md
@@ -17,7 +17,7 @@ Edit [constants/music_constants.asm](../blob/master/constants/music_constants.as
  ; song ids
  ; Music indexes (see audio/music_pointers.asm)
  	const_def
- 
+
  	const MUSIC_NONE                         ; 00
  	...
  	const MUSIC_MOBILE_CENTER                ; 66
@@ -60,16 +60,16 @@ Edit [audio/music_pointers.asm](../blob/master/audio/music_pointers.asm):
 
 ```diff
  ; See song sections in audio.asm.
- 
+
  Music: ; e906e
  ; entries correspond to MUSIC_* constants
- 
+
  	dba Music_Nothing ; 0xe91a3
  	...
  	dba Music_PostCredits ; 0xcfd9e
- 
+
  ; Crystal adds the following songs:
- 
+
  	dba Music_Clair ; 0x1fa8d
  	...
  	dba Music_MobileCenter ; 0x17961d
@@ -83,6 +83,10 @@ Edit [audio/music_pointers.asm](../blob/master/audio/music_pointers.asm):
 Edit [audio.asm](../blob/master/audio.asm):
 
 ```diff
+ SECTION "Extra Songs 2", ROMX
+
+ INCLUDE "audio/music/postcredits.asm"
+
 +SECTION "New Songs", ROMX
 +
 +INCLUDE "audio/music/route47.asm"
diff --git a/Add-different-kinds-of-new-items.md b/Add-different-kinds-of-new-items.md
index 5fd6dd9..26264b0 100644
--- a/Add-different-kinds-of-new-items.md
+++ b/Add-different-kinds-of-new-items.md
@@ -49,7 +49,7 @@ Every kind of item has these pieces of data. `ItemNames`, `ItemDescriptions`, `I
 
 **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.
+**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 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:
 
diff --git a/Tutorials.md b/Tutorials.md
index 84da5fd..e3d6b1f 100644
--- a/Tutorials.md
+++ b/Tutorials.md
@@ -12,6 +12,7 @@ Tutorials may use diff syntax to show edits:
 - [Pokémon species](Add-a-new-Pokémon)
 - [Trainer class](Add-a-new-trainer-class)
 - [Type (Fairy)](Add-a-new-Fairy-type)
+- [Move](Add-a-new-move)
 - [Item (including a healing item, held item, Poké Ball, evolution stone, Town Map, etc)](Add-different-kinds-of-new-items)
 - [TM (up to 120 TMs)](Add-a-new-TM)
 - [Music song](Add-a-new-music-song)
diff --git a/screenshots/nasty-plot.png b/screenshots/nasty-plot.png
new file mode 100644
index 0000000..7fea2eb
--- /dev/null
+++ b/screenshots/nasty-plot.png