Correct grammar for plural trainers like Twins

3 files changed, 171 insertions, 0 deletions

diff --git a/Correct-grammar-for-plural-trainers-like-Twins.md b/Correct-grammar-for-plural-trainers-like-Twins.md
new file mode 100644
index 0000000..5823d20
--- /dev/null
+++ b/Correct-grammar-for-plural-trainers-like-Twins.md
@@ -0,0 +1,170 @@
+Battles begin with the phrase "*<ENEMY>* wants to battle!" and end with "*<ENEMY>* was defeated!" This makes sense if "*<ENEMY>*" is something like "YOUNGSTER JOEY", but it's ungrammatical for plural trainers like "TWINS AMY & MAY".
+
+Gen 3 addressed this issue by changing the phrases to "*<ENEMY>* would like to battle!" and "Player defeated *<ENEMY>*!" And then Gen 4 changed the starting phrase to "You are challenged by *<ENEMY>*!" But some people don't like the politeness of Gen 3, or the passive voice of Gen 4. (\*ahem\*) Plus they're both more verbose than the original Gen 2 phrases, which really matters when the textboxes are so small, and the "*<ENEMY>*" name can take up an entire line (like "MYSTICALMAN EUSINE").
+
+The alternative is to use the correct grammar for plural trainers: "*<ENEMY>* **want** to battle!" and "*<ENEMY>* **were** defeated!" This is fairly simple to implement. If you've worked with event scripts before but not assembly code, this is a good feature to start with.
+
+
+## Contents
+
+1. [Define alternative plural phrases](#1-define-alternative-plural-phrases)
+2. [Define plural trainers](#2-define-plural-trainers)
+3. [Use "<ENEMY> want to battle!"](#3-use-enemy-want-to-battle)
+4. [Use "<ENEMY> were defeated!"](#4-use-enemy-were-defeated)
+5. [Use "<ENEMY> are about to use…"](#5-use-enemy-are-about-to-use)
+
+
+## 1. Define alternative plural phrases
+
+Edit [data/text/battle.asm](../blob/master/data/text/battle.asm):
+
+```diff
+ WantsToBattleText::
+ 	text "<ENEMY>"
+ 	line "wants to battle!"
+ 	prompt
++
++WantToBattlePluralText::
++	text "<ENEMY>"
++	line "want to battle!"
++	prompt
+
+ ...
+
+ BattleText_EnemyWasDefeated:
+ 	text "<ENEMY>"
+ 	line "was defeated!"
+ 	prompt
++
++BattleText_PluralEnemyWereDefeated:
++	text "<ENEMY>"
++	line "were defeated!"
++	prompt
+
+ ...
+
+ BattleText_EnemyIsAboutToUseWillPlayerChangeMon:
+ 	text "<ENEMY>"
+ 	line "is about to use"
+ 	cont "@"
+ 	text_from_ram wEnemyMonNick
+ 	text "."
+
+ 	para "Will <PLAYER>"
+ 	line "change #MON?"
+ 	done
++
++BattleText_PluralEnemyAreAboutToUseWillPlayerChangeMon:
++	text "<ENEMY>"
++	line "are about to use"
++	cont "@"
++	text_from_ram wEnemyMonNick
++	text "."
++
++	para "Will <PLAYER>"
++	line "change #MON?"
++	done
+```
+
+(Yes, while looking through the file I found a third phrase using "<ENEMY>" that needed a different plural form. All the rest are okay as-is.)
+
+
+## 2. Define plural trainers
+
+Edit [engine/battle/core.asm](../blob/master/engine/battle/core.asm):
+
+```diff
+ IsKantoGymLeader:
+ 	ld hl, KantoGymLeaders
+ 	jr IsGymLeaderCommon
+ 
+ IsGymLeader:
+ 	ld hl, GymLeaders
+ IsGymLeaderCommon:
+ 	push de
+ 	ld a, [wOtherTrainerClass]
+ 	ld de, 1
+ 	call IsInArray
+ 	pop de
+ 	ret
+ 
+ INCLUDE "data/trainers/leaders.asm"
++
++IsPluralTrainer:
++; return z for plural trainers
++	ld a, [wOtherTrainerClass]
++	cp TWINS
++	ret
+```
+
+`IsPluralTrainer` sets the **z**ero flag if `[wOtherTrainerClass]` is `TWINS`. If you had more plural classes, like `ACE_DUO` or `SIS_AND_BRO`, you could check for them all like this:
+
+```
+IsPluralTrainer:
+; return z for plural trainers
+	ld a, [wOtherTrainerClass]
+	cp TWINS
+	ret z
+	cp ACE_DUO
+	ret z
+	; ...etc
+	cp SIS_AND_BRO
+	ret
+```
+
+(We're not bothering to use the `IsGymLeader` method of calling `IsInArray`, because it's overkill with just a few items to check, let alone one item.)
+
+Now we just have to find where those three original phrases are used, and call `IsPluralTrainer` to decide whether to use the new phrases instead.
+
+
+## 3. Use "<ENEMY> want to battle!"
+
+Edit [engine/battle/core.asm](../blob/master/engine/battle/core.asm) again:
+
+```diff
+ BattleStartMessage:
+ 	...
+
++	ld hl, WantToBattlePluralText
++	call IsPluralTrainer
++	jr z, .PlaceBattleStartText
+ 	ld hl, WantsToBattleText
+ 	jr .PlaceBattleStartText
+```
+
+
+## 4. Use "<ENEMY> were defeated!"
+
+Edit [engine/battle/core.asm](../blob/master/engine/battle/core.asm) again:
+
+```diff
+ WinTrainerBattle:
+ 	...
++	ld hl, BattleText_PluralEnemyWereDefeated
++	call IsPluralTrainer
++	jr z, .got_defeat_phrase
+ 	ld hl, BattleText_EnemyWasDefeated
++.got_defeat_phrase:
+ 	call StdBattleTextBox
+```
+
+
+## 5. Use "<ENEMY> are about to use…"
+
+Edit [engine/battle/core.asm](../blob/master/engine/battle/core.asm) again:
+
+```diff
+ OfferSwitch:
+ 	...
++	ld hl, BattleText_PluralEnemyAreAboutToUseWillPlayerChangeMon
++	call IsPluralTrainer
++	jr z, .got_switch_phrase
+	ld hl, BattleText_EnemyIsAboutToUseWillPlayerChangeMon
++.got_switch_phrase:
+ 	call StdBattleTextBox
+ 	...
+```
+
+That's all!
+
+![Screenshot](screenshots/plural-twins.png)
diff --git a/Tutorials.md b/Tutorials.md
index b9a6362..55c3c12 100644
--- a/Tutorials.md
+++ b/Tutorials.md
@@ -39,6 +39,7 @@ Tutorials may use diff syntax to show edits:
 - [Increase Pokémon sprite animation size](Increase-Pokémon-sprite-animation-size)
 - [Remove the 25% failure chance for AI status moves](Remove-the-25%25-failure-chance-for-AI-status-moves)
 - [Colored trainer card badges](Colored-trainer-card-badges)
+- [Correct grammar for plural trainers like Twins](Correct-grammar-for-plural-trainers-like-Twins)
 
 **Features from later generations:**
 
diff --git a/screenshots/plural-twins.png b/screenshots/plural-twins.png
new file mode 100644
index 0000000..af11b35
--- /dev/null
+++ b/screenshots/plural-twins.png