path: root/Move-Tutor-and-Tutor-Moves.md

Pokémon Crystal was the first time in the series' history that the player was introduced to move tutors. They teach the player's Pokémon some interesting moves, usually for a price.

In this tutorial we will be expanding the existing move tutor code in pokecrystal, and create a new move tutor script to be used in a map. For this example, we will be creating a move tutor for Softboiled.

## Contents
1. [Edit existing move tutor code](#1-edit-existing-move-tutor-code)
2. [Edit Goldenrod Move Tutor to support the new changes](#2-edit-goldenrod-move-tutor-to-support-the-new-changes)
3. [Create a new tutor move](#3-create-a-new-tutor-move)
4. [Create a new Move Tutor script](#4-create-a-new-move-tutor-script)
5. [Other examples](#5-other-examples)


## 1. Edit existing move tutor code

The existing move tutor code is programmed in a way that it can only check for 3 variables (the three moves able to be tutored). Let's fix that. Head to `.GetMoveTutorMove` in [engine/events/move_tutor.asm](../blob/master/engine/events/move_tutor.asm):

```diff
.GetMoveTutorMove:
	ld a, [wScriptVar]
	cp MOVETUTOR_FLAMETHROWER
	jr z, .flamethrower
	cp MOVETUTOR_THUNDERBOLT
	jr z, .thunderbolt
	; MOVETUTOR_ICE_BEAM
	ld a, ICE_BEAM
	ret

.flamethrower
	ld a, FLAMETHROWER
	ret

.thunderbolt
	ld a, THUNDERBOLT
	ret
```

As you can see, it loads the currently selected `MOVETUTOR_MOVE` into `a`. If you didn't select `MOVETUTOR_FLAMETHROWER`, then the game assumes you picked `MOVETUTOR_THUNDERBOLT`, and loads `THUNDERBOLT` into `a`. If you selected neither, then the game loads `ICE_BEAM` into `a` instead.

Pretty straightforward, huh? But what if we wanted to add more moves? It's not optimal to keep tacking on additional checks the more tutor moves you have.

```diff
.GetMoveTutorMove:
	ld a, [wScriptVar]
-	cp MOVETUTOR_FLAMETHROWER
-	jr z, .flamethrower
-	cp MOVETUTOR_THUNDERBOLT
-	jr z, .thunderbolt
-	; MOVETUTOR_ICE_BEAM
-	ld a, ICE_BEAM
-	ret
-
-.flamethrower
-	ld a, FLAMETHROWER
-	ret
-
-.thunderbolt
-	ld a, THUNDERBOLT
	ret
```

Remove the checks entirely, and let the move tutor script in a map tell `a` which tutor move to load instead! This means you can add a few more tutor moves, and the game should handle it perfectly, if you create the right move tutor script. But first, we need to apply this new engine change to the existing move tutor in Goldenrod.

## 2. Edit Goldenrod Move Tutor to support the new changes

Now that `.GetMoveTutorMove` is edited to load whatever move the map script wants into `a`, we need to change the Goldenrod Move Tutor to support this change.

Open [maps/GoldenrodCity.asm](../blob/master/maps/GoldenrodCity.asm) and locate `MoveTutorScript`:

```diff
MoveTutorScript:
	faceplayer
	opentext
	writetext GoldenrodCityMoveTutorAskTeachAMoveText
	yesorno
	iffalse .Refused
	special DisplayCoinCaseBalance
	writetext GoldenrodCityMoveTutorAsk4000CoinsOkayText
	yesorno
	iffalse .Refused2
	checkcoins 4000
	ifequal HAVE_LESS, .NotEnoughMoney
	writetext GoldenrodCityMoveTutorWhichMoveShouldITeachText
	loadmenu .MoveMenuHeader
	verticalmenu
	closewindow
	ifequal MOVETUTOR_FLAMETHROWER, .Flamethrower
	ifequal MOVETUTOR_THUNDERBOLT, .Thunderbolt
	ifequal MOVETUTOR_ICE_BEAM, .IceBeam
	sjump .Incompatible

.Flamethrower:
	setval MOVETUTOR_FLAMETHROWER
	writetext GoldenrodCityMoveTutorMoveText
	special MoveTutor
	ifequal FALSE, .TeachMove
	sjump .Incompatible

.Thunderbolt:
	setval MOVETUTOR_THUNDERBOLT
	writetext GoldenrodCityMoveTutorMoveText
	special MoveTutor
	ifequal FALSE, .TeachMove
	sjump .Incompatible

.IceBeam:
	setval MOVETUTOR_ICE_BEAM
	writetext GoldenrodCityMoveTutorMoveText
	special MoveTutor
	ifequal FALSE, .TeachMove
	sjump .Incompatible
...
```

In this case, now that we've edited `.GetMoveTutorMove` to not contain `MOVETUTOR_MOVE` checks, this existing script will not function correctly. We need to edit each existing `setval` command to set the named value of each move from [data/moves/tmhm_moves.asm](../blob/master/data/moves/tmhm_moves.asm).

```diff
.Flamethrower:
-	setval MOVETUTOR_FLAMETHROWER
+       setval FLAMETHROWER
	writetext GoldenrodCityMoveTutorMoveText
	special MoveTutor
	ifequal FALSE, .TeachMove
	sjump .Incompatible

.Thunderbolt:
-	setval MOVETUTOR_THUNDERBOLT
+       setval THUNDERBOLT
	writetext GoldenrodCityMoveTutorMoveText
	special MoveTutor
	ifequal FALSE, .TeachMove
	sjump .Incompatible

.IceBeam:
-	setval MOVETUTOR_ICE_BEAM
+       setval ICE_BEAM
	writetext GoldenrodCityMoveTutorMoveText
	special MoveTutor
	ifequal FALSE, .TeachMove
	sjump .Incompatible
```

Now he functions just the same as before, but now the code that let him teach moves can now be expanded to teach others, as well.

## 3. Create a new tutor move
There are three parts to creating a new tutor move. Defining the constant, defining the move, and lastly, adding the move to a Pokémon's existing learnset.

Let's define the constant first. Open [constants/item_constants.asm](../blob/master/constants/item_constants.asm)
Even though tutor moves aren't items and therefore do not have item constants, they're technically still similar to TMs and HMs, in order to work with Pokémon movesets. So they must be defined as such below.

```diff
add_hm: MACRO
if !DEF(HM01)
HM01 EQU const_value
endc
	define _\@_1, "HM_\1"
	const _\@_1
	enum \1_TMNUM
ENDM

	add_hm CUT          ; f3
	add_hm FLY          ; f4
	add_hm SURF         ; f5
	add_hm STRENGTH     ; f6
	add_hm FLASH        ; f7
	add_hm WHIRLPOOL    ; f8
	add_hm WATERFALL    ; f9
NUM_HMS EQU const_value - HM01

add_mt: MACRO
	enum \1_TMNUM
ENDM

	add_mt FLAMETHROWER
	add_mt THUNDERBOLT
	add_mt ICE_BEAM
NUM_TM_HM_TUTOR EQU __enum__ + -1
```

As you can see, tutor moves are defined below HMs, with the `add_mt` macro. They function like TMs and HMs, just without an item corresponding to their use. Let's add our first new tutor move constant, Softboiled.

```diff
+; Move tutor moves don't have item constants, but do need
+; to be added after TMs and HMs for learnset compatibility!
	add_mt FLAMETHROWER
	add_mt THUNDERBOLT
	add_mt ICE_BEAM
+       add_mt SOFTBOILED
NUM_TM_HM_TUTOR EQU __enum__ + -1
```

Now that the constant is defined, we still need to define what move is actually taught. Head on over to [data/moves/tmhm_moves.asm](../blob/master/data/moves/tmhm_moves.asm):

```diff
; HMs
	db CUT
	db FLY
	db SURF
	db STRENGTH
	db FLASH
	db WHIRLPOOL
	db WATERFALL
; Move tutor
	db FLAMETHROWER
	db THUNDERBOLT
	db ICE_BEAM
	db 0 ; end
```

Just like before, tutor moves come after HMs. Be sure to adhere to the order, and the order of new tutor moves you add.

```diff
; Move tutor
	db FLAMETHROWER
	db THUNDERBOLT
	db ICE_BEAM
+       db SOFTBOILED
+
	db 0 ; end
```

Now that the new tutor move is defined, and has been added as a tutor move, we need to add the tutor move to a Pokémon's learnset. For this example, we'll specifically be using Chansey. Chansey's signature move is Softboiled, and is already learned on level up(evos_attacks.asm). But even if a Pokemon can naturally learn this tutor move, the tutor still can't teach it without the tutor move being added to the end of the Chansey's learnset! Just like before, tutor moves come after HMs.

Open up Chansey's base stats at [data/pokemon/base_stats/chansey.asm](../blob/master/data/pokemon/base_stats/chansey.asm)

```diff
	db CHANSEY ; 113

	db 250,  05,  05,  50,  35, 105
	;   hp  atk  def  spd  sat  sdf

	db NORMAL, NORMAL ; type
	db 30 ; catch rate
	db 255 ; base exp
	db NO_ITEM, LUCKY_EGG ; items
	db GENDER_F100 ; gender ratio
	db 100 ; unknown 1
	db 40 ; step cycles to hatch
	db 5 ; unknown 2
	INCBIN "gfx/pokemon/chansey/front.dimensions"
	dw NULL, NULL ; unused (beta front/back pics)
	db GROWTH_FAST ; growth rate
	dn EGG_FAIRY, EGG_FAIRY ; egg groups

	; tm/hm learnset
	tmhm DYNAMICPUNCH, HEADBUTT, CURSE, ROLLOUT, TOXIC, ZAP_CANNON, ROCK_SMASH, PSYCH_UP, HIDDEN_POWER, SUNNY_DAY, SNORE, BLIZZARD, HYPER_BEAM, ICY_WIND, PROTECT, RAIN_DANCE, ENDURE, FRUSTRATION, SOLARBEAM, IRON_TAIL, THUNDER, RETURN, PSYCHIC_M, SHADOW_BALL, MUD_SLAP, DOUBLE_TEAM, SWAGGER, SLEEP_TALK, SANDSTORM, FIRE_BLAST, DEFENSE_CURL, DREAM_EATER, REST, ATTRACT, STRENGTH, FLASH, FLAMETHROWER, THUNDERBOLT, ICE_BEAM
	; end
```

What we want to edit is the tm/hm learnset at the bottom. The TMs and HMs all follow the numeric order of each TM move from `tmhm_moves` and `item_constants`. Move tutor moves go at the end, and as you can see, Chansey already has the Goldenrod tutor moves at the end of her list, after HMs. Simply add `SOFTBOILED` to the end of the list, like so:

```diff
; tm/hm learnset
-	tmhm DYNAMICPUNCH, HEADBUTT, CURSE, ROLLOUT, TOXIC, ZAP_CANNON, ROCK_SMASH, PSYCH_UP, HIDDEN_POWER, SUNNY_DAY, SNORE, BLIZZARD, HYPER_BEAM, ICY_WIND, PROTECT, RAIN_DANCE, ENDURE, FRUSTRATION, SOLARBEAM, IRON_TAIL, THUNDER, RETURN, PSYCHIC_M, SHADOW_BALL, MUD_SLAP, DOUBLE_TEAM, SWAGGER, SLEEP_TALK, SANDSTORM, FIRE_BLAST, DEFENSE_CURL, DREAM_EATER, REST, ATTRACT, STRENGTH, FLASH, FLAMETHROWER, THUNDERBOLT, ICE_BEAM

+tmhm DYNAMICPUNCH, HEADBUTT, CURSE, ROLLOUT, TOXIC, ZAP_CANNON, ROCK_SMASH, PSYCH_UP, HIDDEN_POWER, SUNNY_DAY, SNORE, BLIZZARD, HYPER_BEAM, ICY_WIND, PROTECT, RAIN_DANCE, ENDURE, FRUSTRATION, SOLARBEAM, IRON_TAIL, THUNDER, RETURN, PSYCHIC_M, SHADOW_BALL, MUD_SLAP, DOUBLE_TEAM, SWAGGER, SLEEP_TALK, SANDSTORM, FIRE_BLAST, DEFENSE_CURL, DREAM_EATER, REST, ATTRACT, STRENGTH, FLASH, FLAMETHROWER, THUNDERBOLT, ICE_BEAM, SOFTBOILED
```

With that, our new tutor move has been created, and a Pokemon can learn it. All that's left to do is to create a new tutor to actually teach the move to our Chansey.


## 4. Create a new Move Tutor script

For this example, we'll be editing an NPC in Celadon City to turn them into a Softboiled move tutor, much like the one in Gen 3's Fire Red/Leaf Green.

Open [maps/CeladonCity.asm](../blob/master/maps/CeladonCity.asm):

```diff
CeladonCityGramps1Script:
	jumptextfaceplayer CeladonCityGramps1Text

...

CeladonCityGramps1Text:
	text "GRIMER have been"
	line "appearing lately."

	para "See that pond out"
	line "in front of the"

	para "house? GRIMER live"
	line "there now."

	para "Where did they"
	line "come from? This is"
	cont "a serious problem…"
	done

...

	def_object_events
	object_event 26, 11, SPRITE_FISHER, SPRITEMOVEDATA_STANDING_RIGHT, 0, 0, -1, -1, PAL_NPC_GREEN, OBJECTTYPE_SCRIPT, 0, CeladonCityFisherScript, -1
	object_event 27, 11, SPRITE_POLIWAG, SPRITEMOVEDATA_POKEMON, 0, 0, -1, -1, PAL_NPC_BLUE, OBJECTTYPE_SCRIPT, 0, CeladonCityPoliwrath, -1
	object_event 20, 24, SPRITE_TEACHER, SPRITEMOVEDATA_WALK_LEFT_RIGHT, 2, 0, -1, -1, PAL_NPC_RED, OBJECTTYPE_SCRIPT, 0, CeladonCityTeacher1Script, -1
	object_event 14, 16, SPRITE_GRAMPS, SPRITEMOVEDATA_STANDING_DOWN, 0, 0, -1, -1, PAL_NPC_BROWN, OBJECTTYPE_SCRIPT, 0, CeladonCityGramps1Script, -1
	object_event  8, 31, SPRITE_GRAMPS, SPRITEMOVEDATA_STANDING_UP, 0, 0, -1, -1, PAL_NPC_RED, OBJECTTYPE_SCRIPT, 0, CeladonCityGramps2Script, -1
	object_event 18, 13, SPRITE_YOUNGSTER, SPRITEMOVEDATA_WALK_LEFT_RIGHT, 2, 0, -1, -1, PAL_NPC_BLUE, OBJECTTYPE_SCRIPT, 0, CeladonCityYoungster1Script, -1
	object_event 24, 33, SPRITE_YOUNGSTER, SPRITEMOVEDATA_STANDING_UP, 0, 0, -1, -1, PAL_NPC_GREEN, OBJECTTYPE_SCRIPT, 0, CeladonCityYoungster2Script, -1
	object_event  6, 14, SPRITE_TEACHER, SPRITEMOVEDATA_WANDER, 2, 2, -1, -1, PAL_NPC_GREEN, OBJECTTYPE_SCRIPT, 0, CeladonCityTeacher2Script, -1
	object_event  7, 22, SPRITE_LASS, SPRITEMOVEDATA_WALK_UP_DOWN, 0, 2, -1, -1, PAL_NPC_RED, OBJECTTYPE_SCRIPT, 0, CeladonCityLassScript, -1
```

We'll be borrowing the old man at the house behind the small body of water in Celadon, `CeladonCityGramps1`.
You can either delete the `CeladonCityGramps1Script` and `CeladonCityGramps1Text` itself, or comment it out as we won't be needing them. The bottom part of this script block handles all the `object_event`s, the sprites that usually make up NPCs or important items. Now let's turn him into a tutor!

```diff
-CeladonCityGramps1Script:
-	jumptextfaceplayer CeladonCityGramps1Text
+CeladonCityTutorSoftboiledScript:
+	faceplayer
+	opentext
+	writetext CeladonCityTutorSoftboiledText
+	waitbutton
+	writetext CeladonCityTutorSoftboiledText2
+	yesorno
+	iffalse .TutorRefused
+	writebyte SOFTBOILED
+	writetext CeladonCityTutorSoftboiledClear
+	special MoveTutor
+	if_equal $0, .TeachMove
+.TutorRefused
+	writetext CeladonCityTutorSoftboiledRefused
+	waitbutton
+	closetext
+	end
+
+.TeachMove
+	writetext CeladonCityTutorSoftboiledTaught
+	waitbutton
+	closetext
+	end

...

-CeladonCityGramps1Text:
-	text "GRIMER have been"
-	line "appearing lately."
-
-	para "See that pond out"
-	line "in front of the"
-
-	para "house? GRIMER live"
-	line "there now."
-
-	para "Where did they"
-	line "come from? This is"
-	cont "a serious problem…"
-	done
+CeladonCityTutorSoftboiledText:
+	text "Hello there!"
+	line "I've seen you"
+	cont "running around."
+	para "It must be good"
+	line "luck that brought"
+	cont "us together."
+	done
+
+CeladonCityTutorSoftboiledText2:
+	text "Would you like me"
+	line "to teach your"
+	para "#MON to use"
+	line "SOFTBOILED"
+
+CeladonCityTutorSoftboiledClear:
+	text ""
+	done
+
+CeladonCityTutorSoftboiledRefused:
+	text "OK then."
+	done
+
+CeladonCityTutorSoftboiledTaught:
+	text "Now if your"
+	line "#MON is in a"
+	para "pinch, they can"
+	line "eat an egg"
+	cont "and restore HP."
+	para "Or if they are"
+	line "feeling a bit"
+	cont "hungry, hohoho!"
+	done

...

	def_object_events
	object_event 26, 11, SPRITE_FISHER, SPRITEMOVEDATA_STANDING_RIGHT, 0, 0, -1, -1, PAL_NPC_GREEN, OBJECTTYPE_SCRIPT, 0, CeladonCityFisherScript, -1
	object_event 27, 11, SPRITE_POLIWAG, SPRITEMOVEDATA_POKEMON, 0, 0, -1, -1, PAL_NPC_BLUE, OBJECTTYPE_SCRIPT, 0, CeladonCityPoliwrath, -1
	object_event 20, 24, SPRITE_TEACHER, SPRITEMOVEDATA_WALK_LEFT_RIGHT, 2, 0, -1, -1, PAL_NPC_RED, OBJECTTYPE_SCRIPT, 0, CeladonCityTeacher1Script, -1
-	object_event 14, 16, SPRITE_GRAMPS, SPRITEMOVEDATA_STANDING_DOWN, 0, 0, -1, -1, PAL_NPC_BROWN, OBJECTTYPE_SCRIPT, 0, CeladonCityTutorGramps1Script, -1
+	object_event 14, 16, SPRITE_GRAMPS, SPRITEMOVEDATA_STANDING_DOWN, 0, 0, -1, -1, PAL_NPC_BROWN, OBJECTTYPE_SCRIPT, 0, CeladonCityTutorSoftboiledScript, -1
```
There we go! A brand new move tutor! Now you know how it's done, you can expand on the existing functionality, such as asking for an item or currency as payment!

![Screenshot](https://i.imgur.com/hwPB2of.png)

## 5. Other examples
Now that new tutors can be added to the game, what else could you do? Like the tutors from Gen 3 onwards, you can charge a price, or demand a specific item. Adding a `checkitem` command is very simple, but effective! For this example, we will be using a `POKE_DOLL`.

```diff
CeladonCityTutorSoftboiledScript:
	faceplayer
	opentext
	writetext CeladonCityTutorSoftboiledText
	waitbutton
+	checkitem POKE_DOLL
+	iffalse .NoPokeDoll
	writetext CeladonCityTutorSoftboiledText2
	yesorno
	iffalse .TutorRefused
	writebyte SOFTBOILED
	writetext CeladonCityTutorSoftboiledClear
	special MoveTutor
	if_equal $0, .TeachMove

.TutorRefused:
	writetext CeladonCityTutorSoftboiledRefused
	waitbutton
	closetext
	end

+.NoPokeDoll:
+	writetext CeladonCityTutorNoDoll
+	waitbutton
+	closetext
+	end

.TeachMove
	writetext CeladonCityTutorPayment
	takeitem POKE_DOLL
	waitbutton
	writetext CeladonCityTutorSoftboiledTaught
	waitbutton
	closetext
	end

...

+CeladonCityTutorPayment:
+	text "<PLAYER> gave the"
+	line "man a #DOLL."
+	done

CeladonCityTutorSoftboiledTaught:
	text "Now if your"
	line "#MON is in a"
	para "pinch, they can"
	line "eat an egg"
	cont "and restore HP."
	para "Or if they are"
	line "feeling a bit"
	cont "hungry, hohoho!"
	done
+
+CeladonCityTutorNoDoll:
+	text "Ah, you don't"
+	line "have a #DOLL."
+
+	para "You can get one"
+	line "from the DEPT."
+
+	para "STORE in CEL-"
+	line "ADON CITY."
+	done
```

If the player has no `POKE_DOLL` in their Pack, the script will jump to `CeladonCityTutorNoDoll`, and will end dialogue with the tutor. If the player has one, the script will enter the Move Tutor dialogue. If the move is successfully taught, one will be taken in exchange to tutor a move. If the player quits out of the menu due to having no compatible Pokémon or changing their mind, they will get the "Refused" dialogue.

To charge a price, replace the `checkitem` command with a `checkmoney`, and after `yesorno`, add a `takemoney` command to the `TeachMove` script. Keep in mind you'll have to change the dialogue in `CeladonCityTutorNoDoll` also!

```diff
CeladonCityTutorSoftboiledScript:
	faceplayer
	opentext
	writetext CeladonCityTutorSoftboiledText
	waitbutton
-	checkitem POKE_DOLL
+	checkmoney YOUR_MONEY, 1000
-	iffalse .NoPokeDoll
+	ifequal HAVE_LESS, .NoPokeDoll
	writetext CeladonCityTutorSoftboiledText2
	yesorno
	iffalse .TutorRefused
	writebyte SOFTBOILED
	writetext CeladonCityTutorSoftboiledClear
	special MoveTutor
	if_equal $0, .TeachMove

.NoPokeDoll:
	writetext CeladonCityTutorNoDoll
	waitbutton
	closetext
	end

.TeachMove
	writetext CeladonCityTutorPayment
-	takeitem POKE_DOLL
+	takemoney YOUR_MONEY, 1000
	waitbutton
	writetext CeladonCityTutorSoftboiledTaught
	waitbutton
	closetext
	end
```

For other ideas, look at the Goldenrod move tutor script. Perhaps you want move tutors that appear on different days of the week? Or teach different moves based on what day it is? All of this is possible, and left up to you intrepid assembly hackers to challenge yourself with.