Merge remote-tracking branch 'kanzure/master'

14 files changed, 736 insertions, 416 deletions

diff --git a/INSTALL.md b/INSTALL.md
index 6c738498d..53cd30580 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -1,3 +1,37 @@
+# Vagrant
+
+The simplest way to get pokecrystal to compile is to use Vagrant and
+VirtualBox. Follow these steps:
+
+* [Download and install Vagrant](http://www.vagrantup.com/downloads.html)
+* Follow the instructions to [download and install VirtualBox](http://docs-v1.vagrantup.com/v1/docs/getting-started/)
+* Run these commands:
+
+```
+	vagrant box add pokecrystal http://diyhpl.us/~bryan/irc/pokecrystal/pokecrystal.box
+	mkdir vagrantbox
+	cd vagrantbox
+	vagrant init pokecrystal
+	vagrant up
+	vagrant ssh -c "cd /vagrant && git clone git://github.com/kanzure/pokecrystal.git"
+	vagrant ssh -c "cd /vagrant/pokecrystal && git submodule init && git submodule update"
+	vagrant ssh
+```
+
+Running "vagrant ssh" will give you a shell to type commands into for compiling
+the source code. The the "virtualbox" directory on the host appears as a shared
+folder inside of the guest virtual machine at "/vagrant".
+
+To build the project, run these commands in the guest (that is, inside "vagrant
+ssh"):
+
+	cd /vagrant/pokecrystal
+	make
+
+To make the build work you will need to copy baserom.gbc into the "pokecrystal"
+directory inside the "virtualbox" directory on the host machine. Eventually
+this will not be required.
+
 # Linux
 
 Dependencies:
diff --git a/Makefile b/Makefile
index 150e9bb80..b77607436 100644
--- a/Makefile
+++ b/Makefile
@@ -43,7 +43,7 @@ crystal: pokecrystal.gbc
 
 clean:
 	rm -f $(roms) $(all_obj)
-	find -iname '*.tx' -exec rm {} +
+	find . -iname '*.tx' -exec rm {} +
 
 baserom.gbc: ;
 	@echo "Wait! Need baserom.gbc first. Check README and INSTALL for details." && false
diff --git a/README.md b/README.md
index 8606e523e..058e6d63b 100644
--- a/README.md
+++ b/README.md
@@ -12,8 +12,7 @@ To set up the repository, see [**INSTALL.md**](INSTALL.md).
 ## See also
 
 * Disassembly of [**Pokémon Red/Blue**][pokered]
-* irc: **nucleus.kafuka.org** [**#skeetendo**][irc]
+* irc: **irc.freenode.net** [**#pret**][irc]
 
 [pokered]: https://github.com/iimarckus/pokered
-[irc]: https://kiwiirc.com/client/irc.nolimitzone.com/?#skeetendo
-
+[irc]: https://kiwiirc.com/client/irc.freenode.net/?#pret
diff --git a/Vagrantfile b/Vagrantfile
new file mode 100644
index 000000000..ef8ee2f03
--- /dev/null
+++ b/Vagrantfile
@@ -0,0 +1,59 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+
+# TODO: insert scripts to build the box instead of trusting the uploaded
+# version. The default should be to build the box when running "vagrant up",
+# rather than just downloading a pre-existing box.
+
+# Vagrantfile API/syntax version. Don't touch unless you know what you're doing!
+VAGRANTFILE_API_VERSION = "2"
+
+Vagrant.configure(VAGRANTFILE_API_VERSION) do |config|
+  # All Vagrant configuration is done here. The most common configuration
+  # options are documented and commented below. For a complete reference,
+  # please see the online documentation at vagrantup.com.
+
+  # Every Vagrant virtual environment requires a box to build off of.
+  config.vm.box = "pokecrystal"
+  config.vm.box_url = "http://diyhpl.us/~bryan/irc/pokecrystal/pokecrystal.box"
+
+  # Disable automatic box update checking. If you disable this, then
+  # boxes will only be checked for updates when the user runs
+  # `vagrant box outdated`. This is not recommended.
+  config.vm.box_check_update = false
+
+  # Create a forwarded port mapping which allows access to a specific port
+  # within the machine from a port on the host machine. In the example below,
+  # accessing "localhost:8080" will access port 80 on the guest machine.
+  config.vm.network "forwarded_port", guest: 80, host: 8650
+
+  # Create a private network, which allows host-only access to the machine
+  # using a specific IP.
+  # config.vm.network "private_network", ip: "192.168.33.10"
+
+  # Create a public network, which generally matched to bridged network.
+  # Bridged networks make the machine appear as another physical device on
+  # your network.
+  config.vm.network "public_network"
+
+  # If true, then any SSH connections made will enable agent forwarding.
+  # Default value: false
+  config.ssh.forward_agent = true
+
+  # Share an additional folder to the guest VM. The first argument is
+  # the path on the host to the actual folder. The second argument is
+  # the path on the guest to mount the folder. And the optional third
+  # argument is a set of non-required options.
+  config.vm.synced_folder "./", "/vagrant"
+
+  # Provider-specific configuration so you can fine-tune various
+  # backing providers for Vagrant. These expose provider-specific options.
+  # Example for VirtualBox:
+  config.vm.provider "virtualbox" do |vb|
+    # Don't boot with headless mode
+    vb.gui = false
+
+    # Use VBoxManage to customize the VM. For example to change memory:
+    vb.customize ["modifyvm", :id, "--memory", "1024"]
+  end
+end
diff --git a/battle/ai/scoring.asm b/battle/ai/scoring.asm
index 5e43470d7..52112faf6 100644
--- a/battle/ai/scoring.asm
+++ b/battle/ai/scoring.asm
@@ -21,6 +21,9 @@ AI_Basic: ; 38591
 	ld a, [wEnemyMoveStruct + MOVE_EFFECT]
 	ld c, a
 
+; Dismiss moves with special effects if they are
+; useless or not a good choice right now.
+; For example, healing moves, weather moves, Dream Eater...	
 	push hl
 	push de
 	push bc
@@ -30,6 +33,7 @@ AI_Basic: ; 38591
 	pop hl
 	jr nz, .discourage
 
+; Dismiss status-only moves if the player can't be statused.	
 	ld a, [wEnemyMoveStruct + MOVE_EFFECT]
 	push hl
 	push de
@@ -47,6 +51,7 @@ AI_Basic: ; 38591
 	and a
 	jr nz, .discourage
 
+; Dismiss Safeguard if it's already active.
 	ld a, [PlayerScreens]
 	bit SCREENS_SAFEGUARD, a
 	jr z, .checkmove
@@ -69,6 +74,10 @@ AI_Basic: ; 38591
 AI_Setup: ; 385e0
 ; Use stat-modifying moves on turn 1.
 
+; 50% chance to greatly encourage stat-up moves during the first turn of enemy's Pokemon.
+; 50% chance to greatly encourage stat-down moves during the first turn of player's Pokemon.
+; Almost 90% chance to greatly discourage stat-modifying moves otherwise.
+
 	ld hl, Buffer1 - 1
 	ld de, EnemyMonMoves
 	ld b, EnemyMonMovesEnd - EnemyMonMoves + 1
@@ -140,7 +149,10 @@ AI_Setup: ; 385e0
 
 
 AI_Types: ; 38635
-; Use super-effective moves.
+; Dismiss any move that the player is immune to.
+; Encourage super-effective moves.
+; Discourage not very effective moves unless 
+; all damaging moves are of the same type.
 
 	ld hl, Buffer1 - 1
 	ld de, EnemyMonMoves
@@ -229,7 +241,7 @@ AI_Types: ; 38635
 
 
 AI_Offensive: ; 386a2
-; Discourage non-damaging moves.
+; Greatly discourage non-damaging moves.
 
 	ld hl, Buffer1 - 1
 	ld de, EnemyMonMoves
@@ -391,6 +403,9 @@ AI_Smart: ; 386be
 
 
 AI_Smart_Sleep: ; 387e3
+; Greatly encourage sleep inducing moves if the enemy has either Dream Eater or Nightmare.
+; 50% chance to greatly encourage sleep inducing moves otherwise.
+
 	ld b, EFFECT_DREAM_EATER
 	call AIHasMoveEffect
 	jr c, .asm_387f0
@@ -415,14 +430,19 @@ AI_Smart_LeechHit: ; 387f7
 	callab Function347c8
 	pop hl
 
+; 60% chance to discourage this move if not very effective.
 	ld a, [$d265]
 	cp 10 ; 1.0
 	jr c, .asm_38815
+
+; Do nothing if effectiveness is neutral.
 	ret z
 
+; Do nothing if enemy's HP is full.
 	call AICheckEnemyMaxHP
 	ret c
 
+; 80% chance to encourage this move otherwise.
 	call AI_80_20
 	ret c
 
@@ -546,23 +566,31 @@ AI_Smart_LockOn: ; 3881d
 
 
 AI_Smart_Explosion: ; 388a6
+; Selfdestruct, Explosion
+
+; Unless this is the enemy's last Pokemon...
 	push hl
 	callba CountEnemyAliveMons
 	pop hl
 	jr nc, .asm_388b7
 
+; ...greatly discourage this move unless this is the player's last Pokemon too.
 	push hl
 	call AICheckLastPlayerMon
 	pop hl
 	jr nz, .asm_388c6
 
 .asm_388b7
+; Greatly discourage this move if enemy's HP is above 50%.
 	call AICheckEnemyHalfHP
 	jr c, .asm_388c6
 
+; Do nothing if enemy's HP is below 25%.
 	call AICheckEnemyQuarterHP
 	ret nc
 
+; If enemy's HP is between 25% and 50%,
+; over 90% chance to greatly discourage this move.
 	call Random
 	cp 20
 	ret c
@@ -576,9 +604,11 @@ AI_Smart_Explosion: ; 388a6
 
 
 AI_Smart_DreamEater: ; 388ca
+; 90% chance to greatly encourage this move.
+; The AI_Basic layer will make sure that
+; Dream Eater is only used against sleeping targets.
 	call Random
-
-	cp $19
+	cp 25
 	ret c
 	dec [hl]
 	dec [hl]
@@ -588,17 +618,22 @@ AI_Smart_DreamEater: ; 388ca
 
 
 AI_Smart_EvasionUp: ; 388d4
+
+; Dismiss this move if enemy's evasion can't raise anymore.
 	ld a, [EnemyEvaLevel]
 	cp $d
 	jp nc, AIDiscourageMove
 
+; If enemy's HP is full...
 	call AICheckEnemyMaxHP
 	jr nc, .asm_388f2
 
+; ...greatly encourage this move if player is badly poisoned.
 	ld a, [PlayerSubStatus5]
 	bit SUBSTATUS_TOXIC, a
 	jr nz, .asm_388ef
 
+; ...70% chance to greatly encourage this move if player is not badly poisoned.
 	call Random
 	cp $b2
 	jr nc, .asm_38911
@@ -609,21 +644,27 @@ AI_Smart_EvasionUp: ; 388d4
 	ret
 
 .asm_388f2
+
+; Greatly discourage this move if enemy's HP is below 25%.
 	call AICheckEnemyQuarterHP
 	jr nc, .asm_3890f
 
+; If enemy's HP is above 25% but not full, 4% chance to greatly encourage this move.
 	call Random
 	cp $a
 	jr c, .asm_388ef
 
+; If enemy's HP is between 25% and 50%,...
 	call AICheckEnemyHalfHP
 	jr nc, .asm_3890a
 
+; If enemy's HP is above 50% but not full, 20% chance to greatly encourage this move.
 	call AI_80_20
 	jr c, .asm_388ef
 	jr .asm_38911
 
 .asm_3890a
+; ...50% chance to greatly discourage this move.
 	call AI_50_50
 	jr c, .asm_38911
 
@@ -631,6 +672,11 @@ AI_Smart_EvasionUp: ; 388d4
 	inc [hl]
 	inc [hl]
 
+; 30% chance to end up here if enemy's HP is full and player is not badly poisoned.	
+; 77% chance to end up here if enemy's HP is above 50% but not full.
+; 96% chance to end up here if enemy's HP is between 25% and 50%.
+; 100% chance to end up here if enemy's HP is below 25%.
+; In other words, we only end up here if the move has not been encouraged or dismissed.
 .asm_38911
 	ld a, [PlayerSubStatus5]
 	bit SUBSTATUS_TOXIC, a
@@ -640,12 +686,14 @@ AI_Smart_EvasionUp: ; 388d4
 	bit SUBSTATUS_LEECH_SEED, a
 	jr nz, .asm_38941
 
+; Discourage this move if enemy's evasion level is higher than player's accuracy level.
 	ld a, [EnemyEvaLevel]
 	ld b, a
 	ld a, [PlayerAccLevel]
 	cp b
 	jr c, .asm_38936
 
+; Greatly encourage this move if the player is in the middle of Fury Cutter or Rollout.
 	ld a, [PlayerFuryCutterCount]
 	and a
 	jr nz, .asm_388ef
@@ -659,6 +707,9 @@ AI_Smart_EvasionUp: ; 388d4
 	inc [hl]
 	ret
 
+; Player is badly poisoned.
+; 80% chance to greatly encourage this move.
+; This would counter any previous discouragement.
 .asm_38938
 	call Random
 	cp $50
@@ -667,6 +718,9 @@ AI_Smart_EvasionUp: ; 388d4
 	dec [hl]
 	ret
 
+; Player is seeded.
+; 50% chance to encourage this move.
+; This would partly counter any previous discouragement.
 .asm_38941
 	call AI_50_50
 	ret c
@@ -677,10 +731,14 @@ AI_Smart_EvasionUp: ; 388d4
 
 
 AI_Smart_AlwaysHit: ; 38947
+; 80% chance to greatly encourage this move if either...
+
+; ...enemy's accuracy level has been lowered three or more stages
 	ld a, [EnemyAccLevel]
 	cp $5
 	jr c, .asm_38954
 
+; ...or player's evasion level has been raised three or more stages.
 	ld a, [PlayerEvaLevel]
 	cp $a
 	ret c
@@ -696,27 +754,37 @@ AI_Smart_AlwaysHit: ; 38947
 
 
 AI_Smart_MirrorMove: ; 3895b
+
+; If the player did not use any move last turn...
 	ld a, [LastEnemyCounterMove]
 	and a
 	jr nz, .asm_38968
 
-	call AICompareSpeed
+; ...do nothing if enemy is slower than player
+	call AICompareSpeed	
 	ret nc
 
+; ...or dismiss this move if enemy is faster than player.
 	jp AIDiscourageMove
 
+; If the player did use a move last turn...
 .asm_38968
 	push hl
-	ld hl, GoodMoves
+	ld hl, UsefulMoves
 	ld de, 1
 	call IsInArray
 	pop hl
+	
+; ...do nothing if he didn't use a useful move.
 	ret nc
 
+; If he did, 50% chance to encourage this move...
 	call AI_50_50
 	ret c
 
 	dec [hl]
+
+; ...and 90% chance to encourage this move again if the enemy is faster.
 	call AICompareSpeed
 	ret nc
 
@@ -730,16 +798,21 @@ AI_Smart_MirrorMove: ; 3895b
 
 
 AI_Smart_AccuracyDown: ; 38985
+
+; If player's HP is full...
 	call AICheckPlayerMaxHP
 	jr nc, .asm_389a0
 
+; ...and enemy's HP is above 50%...	
 	call AICheckEnemyHalfHP
 	jr nc, .asm_389a0
 
+; ...greatly encourage this move if player is badly poisoned.	
 	ld a, [PlayerSubStatus5]
 	bit SUBSTATUS_TOXIC, a
 	jr nz, .asm_3899d
 
+; ...70% chance to greatly encourage this move if player is not badly poisoned.
 	call Random
 	cp $b2
 	jr nc, .asm_389bf
@@ -750,20 +823,26 @@ AI_Smart_AccuracyDown: ; 38985
 	ret
 
 .asm_389a0
+
+; Greatly discourage this move if player's HP is below 25%.
 	call AICheckPlayerQuarterHP
 	jr nc, .asm_389bd
 
+; If player's HP is above 25% but not full, 4% chance to greatly encourage this move.	
 	call Random
 	cp $a
 	jr c, .asm_3899d
 
+; If player's HP is between 25% and 50%,...	
 	call AICheckPlayerHalfHP
 	jr nc, .asm_389b8
 
+; If player's HP is above 50% but not full, 20% chance to greatly encourage this move.	
 	call AI_80_20
 	jr c, .asm_3899d
 	jr .asm_389bf
 
+; ...50% chance to greatly discourage this move.	
 .asm_389b8
 	call AI_50_50
 	jr c, .asm_389bf
@@ -772,6 +851,7 @@ AI_Smart_AccuracyDown: ; 38985
 	inc [hl]
 	inc [hl]
 
+; We only end up here if the move has not been already encouraged.	
 .asm_389bf
 	ld a, [PlayerSubStatus5]
 	bit SUBSTATUS_TOXIC, a
@@ -781,12 +861,14 @@ AI_Smart_AccuracyDown: ; 38985
 	bit SUBSTATUS_LEECH_SEED, a
 	jr nz, .asm_389ef
 
+; Discourage this move if enemy's evasion level is higher than player's accuracy level.	
 	ld a, [EnemyEvaLevel]
 	ld b, a
 	ld a, [PlayerAccLevel]
 	cp b
 	jr c, .asm_389e4
 
+; Greatly encourage this move if the player is in the middle of Fury Cutter or Rollout.	
 	ld a, [PlayerFuryCutterCount]
 	and a
 	jr nz, .asm_3899d
@@ -799,6 +881,9 @@ AI_Smart_AccuracyDown: ; 38985
 	inc [hl]
 	ret
 
+; Player is badly poisoned.
+; 80% chance to greatly encourage this move.
+; This would counter any previous discouragement.	
 .asm_389e6
 	call Random
 	cp $50
@@ -807,6 +892,9 @@ AI_Smart_AccuracyDown: ; 38985
 	dec [hl]
 	ret
 
+; Player is seeded.
+; 50% chance to encourage this move.
+; This would partly counter any previous discouragement.	
 .asm_389ef
 	call AI_50_50
 	ret c
@@ -817,6 +905,8 @@ AI_Smart_AccuracyDown: ; 38985
 
 
 AI_Smart_Haze: ; 389f5
+
+; 85% chance to encourage this move if any of enemy's stat levels is lower than -2.
 	push hl
 	ld hl, EnemyAtkLevel
 	ld c, $8
@@ -828,6 +918,7 @@ AI_Smart_Haze: ; 389f5
 	jr c, .asm_38a12
 	jr .asm_389fb
 
+; 85% chance to encourage this move if any of player's stat levels is higher than +2.	
 .asm_38a05
 	ld hl, PlayerAtkLevel
 	ld c, $8
@@ -846,6 +937,9 @@ AI_Smart_Haze: ; 389f5
 	dec [hl]
 	ret
 
+; Discourage this move if neither:
+; Any of enemy's stat levels is	lower than -2.
+; Any of player's stat levels is higher than +2.
 .asm_38a1b
 	pop hl
 	inc [hl]
@@ -854,6 +948,8 @@ AI_Smart_Haze: ; 389f5
 
 
 AI_Smart_Bide: ; 38a1e
+; 90% chance to discourage this move unless enemy's HP is full.
+
 	call AICheckEnemyMaxHP
 	ret c
 	call Random
@@ -865,10 +961,16 @@ AI_Smart_Bide: ; 38a1e
 
 
 AI_Smart_Whirlwind: ; 38a2a
+; Whirlwind, Roar.
+
+; Discourage this move if the player has not shown 
+; a super-effective move against the enemy.
+; Consider player's type(s) if its moves are unknown. 
+
 	push hl
 	callab Function3484e
 	ld a, [$c716]
-	cp $a
+	cp 10 ; neutral
 	pop hl
 	ret c
 	inc [hl]
@@ -880,6 +982,10 @@ AI_Smart_Heal:
 AI_Smart_MorningSun:
 AI_Smart_Synthesis:
 AI_Smart_Moonlight: ; 38a3a
+; 90% chance to greatly encourage this move if enemy's HP is below 25%.
+; Discourage this move if enemy's HP is higher than 50%.
+; Do nothing otherwise.
+
 	call AICheckEnemyQuarterHP
 	jr nc, .asm_38a45
 	call AICheckEnemyHalfHP
@@ -899,6 +1005,8 @@ AI_Smart_Moonlight: ; 38a3a
 
 AI_Smart_Toxic:
 AI_Smart_LeechSeed: ; 38a4e
+; Discourage this move if player's HP is below 50%.
+
 	call AICheckPlayerHalfHP
 	ret c
 	inc [hl]
@@ -908,6 +1016,8 @@ AI_Smart_LeechSeed: ; 38a4e
 
 AI_Smart_LightScreen:
 AI_Smart_Reflect: ; 38a54
+; Over 90% chance to discourage this move unless enemy's HP is full.
+
 	call AICheckEnemyMaxHP
 	ret c
 	call Random
@@ -919,6 +1029,9 @@ AI_Smart_Reflect: ; 38a54
 
 
 AI_Smart_Ohko: ; 38a60
+; Dismiss this move if player's level is higher than enemy's level.
+; Else, discourage this move is player's HP is below 50%.
+
 	ld a, [BattleMonLevel]
 	ld b, a
 	ld a, [EnemyMonLevel]
@@ -932,10 +1045,15 @@ AI_Smart_Ohko: ; 38a60
 
 
 AI_Smart_Bind: ; 38a71
+; Bind, Wrap, Fire Spin, Clamp
+
+; 50% chance to discourage this move if the player is already trapped.
 	ld a, [$c730]
 	and a
 	jr nz, .asm_38a8b
 
+; 50% chance to greatly encourage this move if player is either
+; badly poisoned, in love, identified, stuck in Rollout, or has a Nightmare.
 	ld a, [PlayerSubStatus5]
 	bit SUBSTATUS_TOXIC, a
 	jr nz, .asm_38a91
@@ -944,10 +1062,12 @@ AI_Smart_Bind: ; 38a71
 	and 1<<SUBSTATUS_IN_LOVE | 1<<SUBSTATUS_ROLLOUT | 1<<SUBSTATUS_IDENTIFIED | 1<<SUBSTATUS_NIGHTMARE
 	jr nz, .asm_38a91
 
+; Else, 50% chance to greatly encourage this move if it's the player's Pokemon first turn.
 	ld a, [PlayerTurnsTaken]
 	and a
 	jr z, .asm_38a91
 
+; 50% chance to discourage this move otherwise.
 .asm_38a8b
 	call AI_50_50
 	ret c
@@ -1021,13 +1141,17 @@ AI_Smart_Unused2B: ; 38a9c
 
 
 AI_Smart_Confuse: ; 38adb
+
+; 90% chance to discourage this move if player's HP is between 25% and 50%.
 	call AICheckPlayerHalfHP
 	ret c
 	call Random
 	cp $19
 	jr c, .asm_38ae7
 	inc [hl]
+	
 .asm_38ae7
+; Discourage again if player's HP is below 25%.
 	call AICheckPlayerQuarterHP
 	ret c
 	inc [hl]
@@ -1036,12 +1160,18 @@ AI_Smart_Confuse: ; 38adb
 
 
 AI_Smart_SpDefenseUp2: ; 38aed
+
+; Discourage this move if enemy's HP is lower than 50%.
 	call AICheckEnemyHalfHP
 	jr nc, .asm_38b10
 
+; Discourage this move if enemy's special defense level is higher than +3.
 	ld a, [EnemySDefLevel]
 	cp $b
 	jr nc, .asm_38b10
+
+; 80% chance to greatly encourage this move if
+; enemy's Special Defense level is lower than +2, and the player is of a special type.
 	cp $9
 	ret nc
 
@@ -1066,11 +1196,18 @@ AI_Smart_SpDefenseUp2: ; 38aed
 
 
 AI_Smart_Fly: ; 38b12
+; Fly, Dig
+
+; Greatly encourage this move if the player is
+; flying or underground, and slower than the enemy.
+
 	ld a, [PlayerSubStatus3]
 	and 1 << SUBSTATUS_FLYING | 1 << SUBSTATUS_UNDERGROUND
 	ret z
+	
 	call AICompareSpeed
 	ret nc
+	
 	dec [hl]
 	dec [hl]
 	dec [hl]
@@ -1079,6 +1216,8 @@ AI_Smart_Fly: ; 38b12
 
 
 AI_Smart_SuperFang: ; 38b20
+; Discourage this move if player's HP is below 25%.
+
 	call AICheckPlayerQuarterHP
 	ret c
 	inc [hl]
@@ -1087,8 +1226,13 @@ AI_Smart_SuperFang: ; 38b20
 
 
 AI_Smart_Paralyze: ; 38b26
+
+; 50% chance to discourage this move if player's HP is below 25%.
 	call AICheckPlayerQuarterHP
 	jr nc, .asm_38b3a
+	
+; 80% chance to greatly encourage this move 
+; if enemy is slower than player and its HP is above 25%.	
 	call AICompareSpeed
 	ret c
 	call AICheckEnemyQuarterHP
@@ -1108,6 +1252,13 @@ AI_Smart_Paralyze: ; 38b26
 
 
 AI_Smart_SpeedDownHit: ; 38b40
+; Icy Wind
+
+; Almost 90% chance to greatly encourage this move if the following conditions all meet:
+; Enemy's HP is higher than 25%.
+; It's the first turn of player's Pokemon.
+; Player is faster than enemy.
+
 	ld a, [wEnemyMoveStruct + MOVE_ANIM]
 	cp ICY_WIND
 	ret nz
@@ -1128,6 +1279,8 @@ AI_Smart_SpeedDownHit: ; 38b40
 
 
 AI_Smart_Substitute: ; 38b5c
+; Dismiss this move if enemy's HP is below 50%.
+
 	call AICheckEnemyHalfHP
 	ret c
 	jp AIDiscourageMove
@@ -1137,6 +1290,8 @@ AI_Smart_Substitute: ; 38b5c
 AI_Smart_HyperBeam: ; 38b63
 	call AICheckEnemyHalfHP
 	jr c, .asm_38b72
+	
+; 50% chance to encourage this move if enemy's HP is below 25%.	
 	call AICheckEnemyQuarterHP
 	ret c
 	call AI_50_50
@@ -1145,6 +1300,7 @@ AI_Smart_HyperBeam: ; 38b63
 	ret
 
 .asm_38b72
+; If enemy's HP is above 50%, discourage this move at random
 	call Random
 	cp 40
 	ret c
@@ -1161,11 +1317,13 @@ AI_Smart_Rage: ; 38b7f
 	bit SUBSTATUS_RAGE, a
 	jr z, .asm_38b9b
 
+; If enemy's Rage is building, 50% chance to encourage this move.	
 	call AI_50_50
 	jr c, .asm_38b8c
 
 	dec [hl]
 
+; Encourage this move based on Rage's counter.	
 .asm_38b8c
 	ld a, [$c72c]
 	cp $2
@@ -1178,9 +1336,11 @@ AI_Smart_Rage: ; 38b7f
 	ret
 
 .asm_38b9b
+; If enemy's Rage is not building, discourage this move if enemy's HP is below 50%.
 	call AICheckEnemyHalfHP
 	jr nc, .asm_38ba6
 
+; 50% chance to encourage this move otherwise.
 	call AI_80_20
 	ret nc
 	dec [hl]
@@ -1222,7 +1382,7 @@ AI_Smart_Mimic: ; 38ba8
 .asm_38bd4
 	ld a, [LastEnemyCounterMove]
 	push hl
-	ld hl, GoodMoves
+	ld hl, UsefulMoves
 	ld de, 1
 	call IsInArray
 
@@ -1340,7 +1500,7 @@ AI_Smart_Encore: ; 38c3b
 .asm_38c68
 	push hl
 	ld a, [LastEnemyCounterMove]
-	ld hl, .table_38c85
+	ld hl, .EncoreMoves
 	ld de, 1
 	call IsInArray
 	pop hl
@@ -1360,7 +1520,7 @@ AI_Smart_Encore: ; 38c3b
 	inc [hl]
 	ret
 
-.table_38c85
+.EncoreMoves:
 	db SWORDS_DANCE
 	db WHIRLWIND
 	db LEER
@@ -1396,6 +1556,8 @@ AI_Smart_Encore: ; 38c3b
 
 
 AI_Smart_PainSplit: ; 38ca4
+; Discourage this move if [enemy's current HP * 2 > player's current HP].
+
 	push hl
 	ld hl, EnemyMonHP
 	ld b, [hl]
@@ -1417,6 +1579,9 @@ AI_Smart_PainSplit: ; 38ca4
 
 AI_Smart_Snore:
 AI_Smart_SleepTalk: ; 38cba
+; Greatly encourage this move if enemy is fast asleep.
+; Greatly discourage this move otherwise.
+
 	ld a, [EnemyMonStatus]
 	and $7
 	cp $1
@@ -1436,6 +1601,9 @@ AI_Smart_SleepTalk: ; 38cba
 
 
 AI_Smart_DefrostOpponent: ; 38ccb
+; Greatly encourage this move if enemy is frozen.
+; No move has EFFECT_DEFROST_OPPONENT, so this layer is unused.
+
 	ld a, [EnemyMonStatus]
 	and $20
 	ret z
@@ -1512,6 +1680,8 @@ Function_0x38d16; 38d16
 AI_Smart_DestinyBond:
 AI_Smart_Reversal:
 AI_Smart_SkullBash: ; 38d19
+; Discourage this move if enemy's HP is above 25%.
+
 	call AICheckEnemyQuarterHP
 	ret nc
 	inc [hl]
@@ -1520,6 +1690,10 @@ AI_Smart_SkullBash: ; 38d19
 
 
 AI_Smart_HealBell: ; 38d1f
+; Dismiss this move if none of the opponent's Pokemon is statused.
+; Encourage this move if the enemy is statused.
+; 50% chance to greatly encourage this move if the enemy is fast asleep or frozen.
+
 	push hl
 	ld a, [OTPartyCount]
 	ld b, a
@@ -1533,6 +1707,7 @@ AI_Smart_HealBell: ; 38d1f
 	or [hl]
 	jr z, .next
 
+	; status
 	dec hl
 	dec hl
 	dec hl
@@ -1575,12 +1750,14 @@ AI_Smart_HealBell: ; 38d1f
 
 AI_Smart_PriorityHit: ; 38d5a
 	call AICompareSpeed
-
 	ret c
+
+; Dismiss this move if the player is flying or underground.	
 	ld a, [PlayerSubStatus3]
 	and 1 << SUBSTATUS_FLYING | 1 << SUBSTATUS_UNDERGROUND
 	jp nz, AIDiscourageMove
 
+; Greatly encourage this move if it will KO the player.	
 	ld a, $1
 	ld [hBattleTurn], a
 	push hl
@@ -1605,6 +1782,8 @@ AI_Smart_PriorityHit: ; 38d5a
 
 
 AI_Smart_Thief: ; 38d93
+; Don't use Thief unless it's the only move available.
+
 	ld a, [hl]
 	add $1e
 	ld [hl], a
@@ -1659,7 +1838,7 @@ AI_Smart_Disable: ; 38dd1
 
 	push hl
 	ld a, [LastEnemyCounterMove]
-	ld hl, GoodMoves
+	ld hl, UsefulMoves
 	ld de, 1
 	call IsInArray
 
@@ -1695,18 +1874,22 @@ AI_Smart_MeanLook: ; 38dfb
 	pop hl
 	jp z, AIDiscourageMove
 
+; 80% chance to greatly encourage this move if the enemy is badly poisoned (weird).  	
 	ld a, [EnemySubStatus5]
 	bit SUBSTATUS_TOXIC, a
 	jr nz, .asm_38e26
 
+; 80% chance to greatly encourage this move if the player is either 
+; in love, identified, stuck in Rollout, or has a Nightmare.	
 	ld a, [PlayerSubStatus1]
 	and 1<<SUBSTATUS_IN_LOVE | 1<<SUBSTATUS_ROLLOUT | 1<<SUBSTATUS_IDENTIFIED | 1<<SUBSTATUS_NIGHTMARE
 	jr nz, .asm_38e26
 
+; Otherwise, discourage this move unless the player only has not very effective moves against the enemy.	
 	push hl
 	callab Function3484e
 	ld a, [$c716]
-	cp $b
+	cp $b ; not very effective
 	pop hl
 	ret nc
 
@@ -1752,6 +1935,10 @@ AICheckLastPlayerMon: ; 38e2e
 
 
 AI_Smart_Nightmare: ; 38e4a
+; 50% chance to encourage this move.
+; The AI_Basic layer will make sure that
+; Dream Eater is only used against sleeping targets.
+
 	call AI_50_50
 	ret c
 	dec [hl]
@@ -1760,6 +1947,8 @@ AI_Smart_Nightmare: ; 38e4a
 
 
 AI_Smart_FlameWheel: ; 38e50
+; Use this move if the enemy is frozen.
+
 	ld a, [EnemyMonStatus]
 	bit FRZ, a
 	ret z
@@ -1953,7 +2142,7 @@ AI_Smart_PerishSong: ; 38f4a
 
 	ld a, [PlayerSubStatus5]
 	bit SUBSTATUS_CANT_RUN, a
-	jr nz, .asm_38f6f
+	jr nz, .yes
 
 	push hl
 	callab Function3484e
@@ -1968,7 +2157,7 @@ AI_Smart_PerishSong: ; 38f4a
 	inc [hl]
 	ret
 
-.asm_38f6f
+.yes
 	call AI_50_50
 	ret c
 
@@ -1984,6 +2173,8 @@ AI_Smart_PerishSong: ; 38f4a
 
 
 AI_Smart_Sandstorm: ; 38f7a
+
+; Greatly discourage this move if the player is immune to Sandstorm damage.
 	ld a, [BattleMonType1]
 	push hl
 	ld hl, .SandstormImmuneTypes
@@ -2000,9 +2191,11 @@ AI_Smart_Sandstorm: ; 38f7a
 	pop hl
 	jr c, .asm_38fa5
 
+; Discourage this move if player's HP is below 50%.
 	call AICheckPlayerHalfHP
 	jr nc, .asm_38fa6
 
+; 50% chance to encourage this move otherwise.
 	call AI_50_50
 	ret c
 
@@ -2069,6 +2262,8 @@ AI_Smart_Endure: ; 38fac
 
 
 AI_Smart_FuryCutter: ; 38fdb
+; Encourage this move based on Fury Cutter's count.
+
 	ld a, [EnemyFuryCutterCount]
 	and a
 	jr z, .end
@@ -2092,6 +2287,9 @@ AI_Smart_FuryCutter: ; 38fdb
 
 
 AI_Smart_Rollout: ; 38fef
+; Rollout, Fury Cutter
+
+; 80% chance to discourage this move if the enemy is in love, confused, or paralyzed.
 	ld a, [EnemySubStatus1]
 	bit SUBSTATUS_IN_LOVE, a
 	jr nz, .asm_39020
@@ -2104,6 +2302,8 @@ AI_Smart_Rollout: ; 38fef
 	bit PAR, a
 	jr nz, .asm_39020
 
+; 80% chance to discourage this move if the enemy's HP is below 25%,
+; or if accuracy or evasion modifiers favour the player.
 	call AICheckEnemyQuarterHP
 	jr nc, .asm_39020
 
@@ -2114,6 +2314,7 @@ AI_Smart_Rollout: ; 38fef
 	cp 8
 	jr nc, .asm_39020
 
+; Otherwise, 80% chance to greatly encourage this move.
 	call Random
 	cp 200
 	ret nc
@@ -2131,6 +2332,9 @@ AI_Smart_Rollout: ; 38fef
 
 AI_Smart_Swagger:
 AI_Smart_Attract: ; 39026
+; 80% chance to encourage this move during the first turn of player's Pokemon.
+; 80% chance to discourage this move otherwise.
+
 	ld a, [PlayerTurnsTaken]
 	and a
 	jr z, .first_turn
@@ -2150,6 +2354,8 @@ AI_Smart_Attract: ; 39026
 
 
 AI_Smart_Safeguard: ; 3903a
+; 80% chance to discourage this move if player's HP is below 50%.
+
 	call AICheckPlayerHalfHP
 	ret c
 	call AI_80_20
@@ -2161,6 +2367,8 @@ AI_Smart_Safeguard: ; 3903a
 
 AI_Smart_Magnitude:
 AI_Smart_Earthquake: ; 39044
+
+; Greatly encourage this move if the player is underground and the enemy is faster.
 	ld a, [LastEnemyCounterMove]
 	cp DIG
 	ret nz
@@ -2176,22 +2384,28 @@ AI_Smart_Earthquake: ; 39044
 	ret
 
 .could_dig
-	; Try to predict if the player
-	; will use Dig this turn.
+	; Try to predict if the player will use Dig this turn.
+
+	; 50% chance to encourage this move if the enemy is slower than the player.
 	call AICompareSpeed
 	ret c
+
 	call AI_50_50
 	ret c
+
 	dec [hl]
 	ret
 ; 39062
 
 
 AI_Smart_BatonPass: ; 39062
+; Discourage this move if the player hasn't shown super-effective moves against the enemy.
+; Consider player's type(s) if its moves are unknown.
+
 	push hl
 	callab Function3484e
 	ld a, [$c716]
-	cp 10 ; 1.0
+	cp 10 ; neutral
 	pop hl
 	ret c
 	inc [hl]
@@ -2200,6 +2414,9 @@ AI_Smart_BatonPass: ; 39062
 
 
 AI_Smart_Pursuit: ; 39072
+; 50% chance to greatly encourage this move if player's HP is below 25%.
+; 80% chance to discourage this move otherwise.
+
 	call AICheckPlayerQuarterHP
 	jr nc, .asm_3907d
 	call AI_80_20
@@ -2217,6 +2434,9 @@ AI_Smart_Pursuit: ; 39072
 
 
 AI_Smart_RapidSpin: ; 39084
+; 80% chance to greatly encourage this move if the enemy is
+; trapped (Bind effect), seeded, or scattered with spikes.
+
 	ld a, [$c731]
 	and a
 	jr nz, .asm_39097
@@ -2243,22 +2463,28 @@ AI_Smart_HiddenPower: ; 3909e
 	push hl
 	ld a, 1
 	ld [hBattleTurn], a
+	
+; Calculate Hidden Power's type and base power based on enemy's DVs.
 	callab HiddenPowerDamage
 	callab Function347c8
 	pop hl
 
+; Discourage Hidden Power if not very effective.
 	ld a, [$d265]
 	cp 10
 	jr c, .bad
 
+; Discourage Hidden Power if its base power	is lower than 50.
 	ld a, d
 	cp 50
 	jr c, .bad
 
+; Encourage Hidden Power if super-effective.
 	ld a, [$d265]
 	cp 11
 	jr nc, .good
 
+; Encourage Hidden Power if its base power is 70.
 	ld a, d
 	cp 70
 	ret c
@@ -2274,6 +2500,9 @@ AI_Smart_HiddenPower: ; 3909e
 
 
 AI_Smart_RainDance: ; 390cb
+
+; Greatly discourage this move if it would favour the player type-wise.
+; Particularly, if the player is a Water-type.
 	ld a, [BattleMonType1]
 	cp WATER
 	jr z, AIBadWeatherType
@@ -2308,6 +2537,9 @@ RainDanceMoves: ; 390e7
 
 
 AI_Smart_SunnyDay: ; 390f3
+
+; Greatly discourage this move if it would favour the player type-wise.
+; Particularly, if the player is a Fire-type.
 	ld a, [BattleMonType1]
 	cp FIRE
 	jr z, AIBadWeatherType
@@ -2328,13 +2560,19 @@ AI_Smart_SunnyDay: ; 390f3
 
 
 AI_Smart_WeatherMove: ; 3910d
+; Rain Dance, Sunny Day
+
+; Greatly discourage this move if the enemy doesn't have
+; one of the useful Rain Dance or Sunny Day moves.
 	call AIHasMoveInArray
 	pop hl
 	jr nc, AIBadWeatherType
 
+; Greatly discourage this move if player's HP is below 50%.
 	call AICheckPlayerHalfHP
 	jr nc, AIBadWeatherType
 
+; 50% chance to encourage this move otherwise.
 	call AI_50_50
 	ret c
 
@@ -2350,13 +2588,19 @@ AIBadWeatherType: ; 3911e
 ; 39122
 
 AIGoodWeatherType: ; 39122
+; Rain Dance, Sunny Day
+
+; Greatly encourage this move if it would disfavour the player type-wise and player's HP is above 50%...
 	call AICheckPlayerHalfHP
 	ret nc
 
+; ...as long as one of the following conditions meet:
+; It's the first turn of the player's Pokemon.
 	ld a, [PlayerTurnsTaken]
 	and a
 	jr z, .good
 
+; Or it's the first turn of the enemy's Pokemon.
 	ld a, [EnemyTurnsTaken]
 	and a
 	ret nz
@@ -2382,16 +2626,19 @@ SunnyDayMoves: ; 39134
 
 
 AI_Smart_BellyDrum: ; 3913d
+; Dismiss this move if enemy's attack is higher than +2 or if enemy's HP is below 50%.
+; Else, discourage this move if enemy's HP is not full.
+
 	ld a, [EnemyAtkLevel]
 	cp $a
 	jr nc, .asm_3914d
 
 	call AICheckEnemyMaxHP
-
 	ret c
+
 	inc [hl]
-	call AICheckEnemyHalfHP
 
+	call AICheckEnemyHalfHP
 	ret c
 
 .asm_3914d
@@ -2406,8 +2653,10 @@ AI_Smart_PsychUp: ; 39152
 	push hl
 	ld hl, EnemyAtkLevel
 	ld b, $8
-	ld c, $64
+	ld c, 100
 
+; Calculate the sum of all enemy's stat level modifiers. Add 100 first to prevent underflow.
+; Put the result in c. c will range between 58 and 142.
 .asm_3915a
 	ld a, [hli]
 	sub $7
@@ -2416,9 +2665,11 @@ AI_Smart_PsychUp: ; 39152
 	dec b
 	jr nz, .asm_3915a
 
+; Calculate the sum of all player's stat level modifiers. Add 100 first to prevent underflow.
+; Put the result in d. d will range between 58 and 142.	
 	ld hl, PlayerAtkLevel
 	ld b, $8
-	ld d, $64
+	ld d, 100
 
 .asm_39169
 	ld a, [hli]
@@ -2428,19 +2679,25 @@ AI_Smart_PsychUp: ; 39152
 	dec b
 	jr nz, .asm_39169
 
+; Greatly discourage this move if enemy's stat levels are higher than player's (if c>=d).
 	ld a, c
 	sub d
 	pop hl
 	jr nc, .asm_39188
 
+; Else, 80% chance to encourage this move unless player's accuracy level is lower than -1...	
 	ld a, [PlayerAccLevel]
 	cp $6
 	ret c
+	
+; ...or enemy's evasion level is higher than +0.	
 	ld a, [EnemyEvaLevel]
 	cp $8
 	ret nc
+
 	call AI_80_20
 	ret c
+
 	dec [hl]
 	ret
 
@@ -2518,13 +2775,15 @@ AI_Smart_MirrorCoat: ; 3918b
 
 AI_Smart_Twister:
 AI_Smart_Gust: ; 391d5
+
+; Greatly encourage this move if the player is flying and the enemy is faster.
 	ld a, [LastEnemyCounterMove]
 	cp FLY
 	ret nz
 
 	ld a, [PlayerSubStatus3]
 	bit SUBSTATUS_FLYING, a
-	jr z, .asm_391e9
+	jr z, .couldFly
 
 	call AICompareSpeed
 	ret nc
@@ -2533,7 +2792,10 @@ AI_Smart_Gust: ; 391d5
 	dec [hl]
 	ret
 
-.asm_391e9
+; Try to predict if the player will use Fly this turn.	
+.couldFly
+
+; 50% chance to encourage this move if the enemy is slower than the player.
 	call AICompareSpeed
 	ret c
 	call AI_50_50
@@ -2544,6 +2806,9 @@ AI_Smart_Gust: ; 391d5
 
 
 AI_Smart_FutureSight: ; 391f3
+; Greatly encourage this move if the player is
+; flying or underground, and slower than the enemy.
+
 	call AICompareSpeed
 	ret nc
 
@@ -2558,6 +2823,8 @@ AI_Smart_FutureSight: ; 391f3
 
 
 AI_Smart_Stomp: ; 39200
+; 80% chance to encourage this move if the player has used Minimize.
+
 	ld a, [$c6fe]
 	and a
 	ret z
@@ -2571,6 +2838,9 @@ AI_Smart_Stomp: ; 39200
 
 
 AI_Smart_Solarbeam: ; 3920b
+; 80% chance to encourage this move when it's sunny.
+; 90% chance to discourage this move when it's raining.
+
 	ld a, [Weather]
 	cp WEATHER_SUN
 	jr z, .asm_3921e
@@ -2597,6 +2867,8 @@ AI_Smart_Solarbeam: ; 3920b
 
 
 AI_Smart_Thunder: ; 39225
+; 90% chance to discourage this move when it's sunny.
+
 	ld a, [Weather]
 	cp WEATHER_SUN
 	ret nz
@@ -2611,6 +2883,8 @@ AI_Smart_Thunder: ; 39225
 
 
 AICompareSpeed: ; 39233
+; Return carry if enemy is faster than player.
+
 	push bc
 	ld a, [EnemyMonSpeed + 1]
 	ld b, a
@@ -2647,6 +2921,7 @@ AICheckEnemyMaxHP: ; 39251
 
 AICheckMaxHP: ; 3925a
 ; Return carry if hp at de matches max hp at hl.
+
 	ld a, [de]
 	inc de
 	cp [hl]
@@ -2762,6 +3037,7 @@ AICheckPlayerQuarterHP: ; 392b3
 
 AIHasMoveEffect: ; 392ca
 ; Return carry if the enemy has move b.
+
 	push hl
 	ld hl, EnemyMonMoves
 	ld c, EnemyMonMovesEnd - EnemyMonMoves
@@ -2827,7 +3103,7 @@ AIHasMoveInArray: ; 392e6
 ; 39301
 
 
-GoodMoves: ; 39301
+UsefulMoves: ; 39301
 ; Moves that are usable all-around.
 	db DOUBLE_EDGE
 	db SING
@@ -2853,14 +3129,17 @@ GoodMoves: ; 39301
 
 
 AI_Opportunist: ; 39315
-; Don't use stall moves when the player's HP is low.
+; Discourage stall moves when the enemy's HP is low.
 
+; Do nothing if enemy's HP is above 50%.
 	call AICheckEnemyHalfHP
 	ret c
 
+; Discourage stall moves if enemy's HP is below 25%.	
 	call AICheckEnemyQuarterHP
 	jr nc, .asm_39322
-
+	
+; 50% chance to discourage stall moves if enemy's HP is between 25% and 50%.
 	call AI_50_50
 	ret c
 
@@ -2937,6 +3216,10 @@ AI_Opportunist: ; 39315
 AI_Aggressive: ; 39369
 ; Use whatever does the most damage.
 
+; Discourage all damaging moves but the one that does the most damage.
+; If no damaging move deals damage to the player (immune),
+; no move will be discouraged
+
 ; Figure out which attack does the most damage and put it in c.
 	ld hl, EnemyMonMoves
 	ld bc, 0
@@ -2963,6 +3246,7 @@ AI_Aggressive: ; 39369
 	pop de
 	pop hl
 
+; Update current move if damage is highest so far
 	ld a, [CurDamage + 1]
 	cp e
 	ld a, [CurDamage]
@@ -2998,6 +3282,7 @@ AI_Aggressive: ; 39369
 	cp EnemyMonMovesEnd - EnemyMonMoves + 1
 	jr z, .done
 
+; Ignore this move if it is the highest damaging one.
 	cp c
 	ld a, [de]
 	inc de
@@ -3006,15 +3291,19 @@ AI_Aggressive: ; 39369
 
 	call AIGetEnemyMove
 
+; Ignore this move if its power is 0 or 1.
+; Moves such as Seismic Toss, Hidden Power, 
+; Counter and Fissure have a base power of 1.	
 	ld a, [wEnemyMoveStruct + MOVE_POWER]
 	cp 2
 	jr c, .checkmove2
 
+; Ignore this move if it is reckless.	
 	push hl
 	push de
 	push bc
 	ld a, [wEnemyMoveStruct + MOVE_EFFECT]
-	ld hl, .aggressivemoves
+	ld hl, .RecklessMoves
 	ld de, 1
 	call IsInArray
 	pop bc
@@ -3022,13 +3311,14 @@ AI_Aggressive: ; 39369
 	pop hl
 	jr c, .checkmove2
 
+; If we made it this far, discourage this move. 	
 	inc [hl]
 	jr .checkmove2
 
 .done
 	ret
 
-.aggressivemoves
+.RecklessMoves:
 	db EFFECT_EXPLOSION
 	db EFFECT_RAMPAGE
 	db EFFECT_MULTI_HIT
@@ -3064,7 +3354,7 @@ AIDamageCalc: ; 393e7
 
 
 AI_Cautious: ; 39418
-; Don't use moves with residual effects after turn 1.
+; 90% chance to discourage moves with residual effects after the first turn.
 
 	ld a, [EnemyTurnsTaken]
 	and a
@@ -3121,7 +3411,7 @@ AI_Cautious: ; 39418
 
 
 AI_Status: ; 39453
-; Don't use status moves that don't affect the player.
+; Dismiss status moves that don't affect the player.
 
 	ld hl, Buffer1 - 1
 	ld de, EnemyMonMoves
@@ -3185,7 +3475,8 @@ AI_Status: ; 39453
 
 
 AI_Risky: ; 394a9
-; Use any move that will KO the opponent.
+; Use any move that will KO the target.
+; Risky moves will often be an exception (see below).
 
 	ld hl, Buffer1 - 1
 	ld de, EnemyMonMoves
@@ -3212,13 +3503,14 @@ AI_Risky: ; 394a9
 ; Don't use risky moves at max hp.
 	ld a, [wEnemyMoveStruct + MOVE_EFFECT]
 	ld de, 1
-	ld hl, .riskymoves
+	ld hl, .RiskyMoves
 	call IsInArray
 	jr nc, .checkko
 
 	call AICheckEnemyMaxHP
 	jr c, .nextmove
 
+; Else, 80% chance to exclude them.	
 	call Random
 	cp 200 ; 1/5
 	jr c, .nextmove
@@ -3250,7 +3542,7 @@ AI_Risky: ; 394a9
 	pop de
 	jr .checkmove
 
-.riskymoves
+.RiskyMoves:
 	db EFFECT_EXPLOSION
 	db EFFECT_OHKO
 	db $ff
@@ -3272,6 +3564,8 @@ AIDiscourageMove: ; 39503
 
 
 AIGetEnemyMove: ; 39508
+; Load attributes of move a into ram
+
 	push hl
 	push de
 	push bc
diff --git a/items/item_effects.asm b/items/item_effects.asm
index 7a4ae00e3..20ce0c313 100644
--- a/items/item_effects.asm
+++ b/items/item_effects.asm
@@ -245,7 +245,7 @@ ParkBall: ; e8a2
 	jp z, .asm_e99c
 	ld a, [CurItem]
 	ld c, a
-	ld hl, Table_0xec0a
+	ld hl, BallMultiplierFunctionTable
 
 .asm_e8f2
 	ld a, [hli]
@@ -329,19 +329,23 @@ ParkBall: ; e8a2
 
 	ld a, [$ffb6]
 	and a
-	jr nz, .asm_e960
+	jr nz, .statuscheck
 	ld a, 1
-.asm_e960
+.statuscheck
+; This routine is buggy. It was intended that SLP and FRZ provide a higher
+; catch rate than BRN/PSN/PAR, which in turn provide a higher catch rate than
+; no status effect at all. But instead, it makes BRN/PSN/PAR provide no
+; benefit.
 	ld b, a
 	ld a, [EnemyMonStatus]
 	and 1 << FRZ | SLP
 	ld c, 10
-	jr nz, .asm_e971
+	jr nz, .addstatus
 	and a
 	ld c, 5
-	jr nz, .asm_e971
+	jr nz, .addstatus
 	ld c, 0
-.asm_e971
+.addstatus
 	ld a, b
 	add c
 	jr nc, .asm_e977
@@ -725,34 +729,32 @@ ParkBall: ; e8a2
 ; ec0a
 
 
-Table_0xec0a: ; ec0a
-; Note: SAFARI_BALL does not exist.
-	dbw ULTRA_BALL,  UltraBallChance
-	dbw GREAT_BALL,  GreatBallChance
-	dbw SAFARI_BALL, SafariBallChance
-	dbw HEAVY_BALL,  HeavyBallChance
-	dbw LEVEL_BALL,  LevelBallChance
-	dbw LURE_BALL,   LureBallChance
-	dbw FAST_BALL,   FastBallChance
-	dbw MOON_BALL,   MoonBallChance
-	dbw LOVE_BALL,   LoveBallChance
-	dbw PARK_BALL,   ParkBallChance
+BallMultiplierFunctionTable:
+; table of routines that increase or decrease the catch rate based on
+; which ball is used in a certain situation.
+	dbw ULTRA_BALL, UltraBallMultiplier
+	dbw GREAT_BALL, GreatBallMultiplier
+	dbw 8,          SafariBallMultiplier ; Safari Ball, leftover from RBY
+	dbw HEAVY_BALL, HeavyBallMultiplier
+	dbw LEVEL_BALL, LevelBallMultiplier
+	dbw LURE_BALL,  LureBallMultiplier
+	dbw FAST_BALL,  FastBallMultiplier
+	dbw MOON_BALL,  MoonBallMultiplier
+	dbw LOVE_BALL,  LoveBallMultiplier
+	dbw PARK_BALL,  ParkBallMultiplier
 	db $ff
-; ec29
 
-
-UltraBallChance: ; ec29
-; x2
+UltraBallMultiplier:
+; multiply catch rate by 2
 	sla b
 	ret nc
 	ld b, $ff
 	ret
-; ec2f
 
-GreatBallChance: ; ec2f
-ParkBallChance:
-SafariBallChance:
-; x1.5
+SafariBallMultiplier:
+GreatBallMultiplier:
+ParkBallMultiplier:
+; multiply catch rate by 1.5
 	ld a, b
 	srl a
 	add b
@@ -760,10 +762,8 @@ SafariBallChance:
 	ret nc
 	ld b, $ff
 	ret
-; ec38
-
 
-GetPokedexEntryBank: ; ec38
+GetPokedexEntryBank:
 	push hl
 	push de
 	ld a, [EnemyMonSpecies]
@@ -790,9 +790,13 @@ GLOBAL PokedexEntries4
 	db BANK(PokedexEntries2)
 	db BANK(PokedexEntries3)
 	db BANK(PokedexEntries4)
-; ec50
 
-HeavyBallChance: ; ec50
+HeavyBallMultiplier:
+; subtract 20 from catch rate if weight < 102.4 kg
+; else add 0 to catch rate if weight < 204.8 kg
+; else add 20 to catch rate if weight < 307.2 kg
+; else add 30 to catch rate if weight < 409.6 kg
+; else add 40 to catch rate (never happens)
 	ld a, [EnemyMonSpecies]
 	ld hl, PokedexDataPointerTable
 	dec a
@@ -825,17 +829,18 @@ HeavyBallChance: ; ec50
 	srl b
 	rr c
 	endr
-	call .asm_ec99
+	call .subbc
 
 	srl b
 	rr c
-	call .asm_ec99
+	call .subbc
 
 	ld a, h
 	pop bc
-	jr .asm_eca4
+	jr .compare
 
-.asm_ec99
+.subbc
+	; subtract bc from hl
 	push bc
 	ld a, b
 	cpl
@@ -848,21 +853,21 @@ HeavyBallChance: ; ec50
 	pop bc
 	ret
 
-.asm_eca4
+.compare
 	ld c, a
-	cp $4
-	jr c, .asm_ecbc
+	cp 1024 >> 8 ; 102.4 kg
+	jr c, .lightmon
 
-	ld hl, .table_ecc4
-.asm_ecac
+	ld hl, .WeightsTable
+.lookup
 	ld a, c
 	cp [hl]
-	jr c, .asm_ecb4
+	jr c, .heavymon
 	inc hl
 	inc hl
-	jr .asm_ecac
+	jr .lookup
 
-.asm_ecb4
+.heavymon
 	inc hl
 	ld a, b
 	add [hl]
@@ -871,7 +876,7 @@ HeavyBallChance: ; ec50
 	ld b, $ff
 	ret
 
-.asm_ecbc
+.lightmon
 	ld a, b
 	sub 20
 	ld b, a
@@ -879,15 +884,15 @@ HeavyBallChance: ; ec50
 	ld b, $1
 	ret
 
-.table_ecc4
-	db   8,  0
-	db  12, 20
-	db  16, 30
-	db 255, 40
-; eccc
+.WeightsTable
+; weight factor, boost
+	db 2048 >> 8, 0
+	db 3072 >> 8, 20
+	db 4096 >> 8, 30
+	db 65280 >> 8, 40
 
-
-LureBallChance: ; eccc
+LureBallMultiplier:
+; multiply catch rate by 3 if this is a fishing rod battle
 	ld a, [BattleType]
 	cp BATTLETYPE_FISH
 	ret nz
@@ -903,10 +908,11 @@ LureBallChance: ; eccc
 .done
 	ld b, a
 	ret
-; ecdd
-
 
-MoonBallChance: ; ecdd
+MoonBallMultiplier:
+; This function is buggy.
+; Intent:  multiply catch rate by 4 if mon evolves with moon stone
+; Reality: no boost
 
 GLOBAL EvosAttacks
 GLOBAL EvosAttacksPointers
@@ -934,13 +940,9 @@ GLOBAL EvosAttacksPointers
 	inc hl
 	inc hl
 
-	; It appears that Moon Stone's
-	; constant from Pokémon Red is used.
-
-	; No Pokémon evolve with Burn Heal,
-	; so Moon Balls always have
-	; a catch rate of 1x.
-
+; Moon Stone's constant from Pokémon Red is used.
+; No Pokémon evolve with Burn Heal,
+; so Moon Balls always have a catch rate of 1×.
 	push bc
 	ld a, BANK(EvosAttacks)
 	call GetFarByte
@@ -956,16 +958,20 @@ GLOBAL EvosAttacksPointers
 	ld b, $ff
 .done
 	ret
-; ed12
 
+LoveBallMultiplier:
+; This function is buggy.
+; Intent:  multiply catch rate by 8 if mons are of same species, different sex
+; Reality: multiply catch rate by 8 if mons are of same species, same sex
 
-LoveBallChance: ; ed12
+	; does species match?
 	ld a, [TempEnemyMonSpecies]
 	ld c, a
 	ld a, [TempBattleMonSpecies]
 	cp c
 	ret nz
 
+	; check player mon species
 	push bc
 	ld a, [TempBattleMonSpecies]
 	ld [CurPartySpecies], a
@@ -974,52 +980,56 @@ LoveBallChance: ; ed12
 	ld a, [CurBattleMon]
 	ld [CurPartyMon], a
 	callba GetGender
-	jr c, .asm_ed66
+	jr c, .done1 ; no effect on genderless
 
-	ld d, 0
-	jr nz, .asm_ed39
-	inc d
-.asm_ed39
+	ld d, 0 ; male
+	jr nz, .playermale
+	inc d   ; female
+.playermale
 
+	; check wild mon species
 	push de
 	ld a, [TempEnemyMonSpecies]
 	ld [CurPartySpecies], a
 	ld a, WILDMON
 	ld [MonType], a
 	callba GetGender
-	jr c, .asm_ed65
+	jr c, .done2 ; no effect on genderless
 
-	ld d, 0
-	jr nz, .asm_ed52
-	inc d
-.asm_ed52
+	ld d, 0 ; male
+	jr nz, .wildmale
+	inc d   ; female
+.wildmale
 
 	ld a, d
 	pop de
 	cp d
 	pop bc
-	ret nz
+	ret nz ; for the intended effect, this should be “ret z”
 
 	sla b
-	jr c, .asm_ed62
+	jr c, .max
 	sla b
-	jr c, .asm_ed62
+	jr c, .max
 	sla b
 	ret nc
-.asm_ed62
+.max
 	ld b, $ff
 	ret
 
-.asm_ed65
+.done2
 	pop de
 
-.asm_ed66
+.done1
 	pop bc
 	ret
-; ed68
 
-
-FastBallChance: ; ed68
+FastBallMultiplier:
+; This function is buggy.
+; Intent:  multiply catch rate by 4 if enemy mon is in one of the three
+;          FleeMons tables.
+; Reality: multiply catch rate by 4 if enemy mon is one of the first three in
+;          the first FleeMons table.
 	ld a, [TempEnemyMonSpecies]
 	ld c, a
 	ld hl, FleeMons
@@ -1033,7 +1043,7 @@ FastBallChance: ; ed68
 	cp -1
 	jr z, .next
 	cp c
-	jr nz, .next
+	jr nz, .next ; for the intended effect, this should be “jr nz, .loop”
 	sla b
 	jr c, .max
 
@@ -1048,35 +1058,34 @@ FastBallChance: ; ed68
 	dec d
 	jr nz, .loop
 	ret
-; ed8c
-
 
-LevelBallChance: ; ed8c
+LevelBallMultiplier:
+; multiply catch rate by 8 if player mon level / 4 > enemy mon level
+; multiply catch rate by 4 if player mon level / 2 > enemy mon level
+; multiply catch rate by 2 if player mon level > enemy mon level
 	ld a, [BattleMonLevel]
 	ld c, a
 	ld a, [EnemyMonLevel]
 	cp c
-	ret nc
+	ret nc ; if player is lower level, we're done here
 	sla b
 	jr c, .max
 
 	srl c
 	cp c
-	ret nc
+	ret nc ; if player/2 is lower level, we're done here
 	sla b
 	jr c, .max
 
 	srl c
 	cp c
-	ret nc
+	ret nc ; if player/4 is lower level, we're done here
 	sla b
 	ret nc
 
 .max
 	ld b, $ff
 	ret
-; edab
-
 
 UnknownText_0xedab: ; 0xedab
 	; It dodged the thrown BALL! This #MON can't be caught!
diff --git a/main.asm b/main.asm
index 330776227..fe713adb4 100644
--- a/main.asm
+++ b/main.asm
@@ -41695,6 +41695,8 @@ TrainerClassNames:: ; 2c1ef
 
 AI_Redundant: ; 2c41a
 ; Check if move effect c will fail because it's already been used.
+; Return z if the move is a good choice.
+; Return nz if the move is a bad choice.
 	ld a, c
 	ld de, 3
 	ld hl, .Moves
@@ -47162,7 +47164,7 @@ AIChooseMove: ; 440ce
 
 	ld a, c
 	cp 16 ; up to 16 scoring layers
-	jr z, .asm_4415e
+	jr z, .DecrementScores
 
 	push bc
 	ld d, BANK(TrainerClassAttributes)
@@ -47191,28 +47193,36 @@ AIChooseMove: ; 440ce
 
 	jr .CheckLayer
 
-.asm_4415e
+; Decrement the scores of all moves one by one until one reaches 0.
+.DecrementScores
 	ld hl, Buffer1
 	ld de, EnemyMonMoves
 	ld c, EnemyMonMovesEnd - EnemyMonMoves
-.asm_44166
+	
+.DecrementNextScore
 	; If the enemy has no moves, this will infinite.
 	ld a, [de]
 	inc de
 	and a
-	jr z, .asm_4415e
+	jr z, .DecrementScores
 
+	; We are done whenever a score reaches 0
 	dec [hl]
-	jr z, .asm_44174
+	jr z, .PickLowestScoreMoves
 
+	; If we just decremented the fourth move's score, go back to the first move
 	inc hl
 	dec c
-	jr z, .asm_4415e
+	jr z, .DecrementScores
 
-	jr .asm_44166
+	jr .DecrementNextScore
 
-.asm_44174
+; In order to avoid bias towards the moves located first in memory, increment the scores
+; that were decremented one more time than the rest (in case there was a tie).
+; This means that the minimum score will be 1.
+.PickLowestScoreMoves
 	ld a, c
+	
 .asm_44175
 	inc [hl]
 	dec hl
@@ -47223,11 +47233,15 @@ AIChooseMove: ; 440ce
 	ld hl, Buffer1
 	ld de, EnemyMonMoves
 	ld c, NUM_MOVES
+	
+; Give a score of 0 to a blank move	
 .asm_44184
 	ld a, [de]
 	and a
 	jr nz, .asm_44189
-	ld [hl], a
+	ld [hl], a 
+
+; Disregard the move if its score is not 1	
 .asm_44189
 	ld a, [hl]
 	dec a
@@ -47235,6 +47249,7 @@ AIChooseMove: ; 440ce
 	xor a
 	ld [hli], a
 	jr .asm_44193
+	
 .asm_44191
 	ld a, [de]
 	ld [hli], a
@@ -47243,7 +47258,8 @@ AIChooseMove: ; 440ce
 	dec c
 	jr nz, .asm_44184
 
-.asm_44197
+; Randomly choose one of the moves with a score of 1 	
+.ChooseMove
 	ld hl, Buffer1
 	call Random
 	and 3
@@ -47252,7 +47268,7 @@ AIChooseMove: ; 440ce
 	add hl, bc
 	ld a, [hl]
 	and a
-	jr z, .asm_44197
+	jr z, .ChooseMove
 
 	ld [CurEnemyMove], a
 	ld a, c
@@ -59426,11 +59442,13 @@ String_50bb5: ; 50bb5
 
 
 GetGender: ; 50bdd
-; Return the gender of a given monster in a.
+; Return the gender of a given monster (CurPartyMon/CurOTMon/CurWildMon).
+; When calling this function, a should be set to an appropriate MonType value.
 
-; 1: male
-; 0: female
-; c: genderless
+; return values:
+; a = 1: f = nc|nz; male
+; a = 0: f = nc|z;  female
+;        f = c:  genderless
 
 ; This is determined by comparing the Attack and Speed DVs
 ; with the species' gender ratio.
diff --git a/maps/BlackthornCity.asm b/maps/BlackthornCity.asm
index 7cd37057f..e2a28527d 100644
--- a/maps/BlackthornCity.asm
+++ b/maps/BlackthornCity.asm
@@ -9,25 +9,22 @@ BlackthornCity_MapScriptHeader: ; 0x1a46d0
 
 	dbw 5, UnknownScript_0x1a46d8
 
-	dbw 2, UnknownScript_0x1a46dc
-; 0x1a46d8
+	dbw 2, SantosCallback
 
 UnknownScript_0x1a46d8: ; 0x1a46d8
 	setflag $004b
 	return
 ; 0x1a46dc
 
-UnknownScript_0x1a46dc: ; 0x1a46dc
+SantosCallback:
 	checkcode $b
-	if_equal SATURDAY, UnknownScript_0x1a46e5
+	if_equal SATURDAY, .SantosAppears
 	disappear $9
 	return
-; 0x1a46e5
 
-UnknownScript_0x1a46e5: ; 0x1a46e5
+.SantosAppears
 	appear $9
 	return
-; 0x1a46e8
 
 SuperNerdScript_0x1a46e8: ; 0x1a46e8
 	faceplayer
@@ -94,44 +91,41 @@ CooltrainerFScript_0x1a4728: ; 0x1a4728
 	jumptextfaceplayer UnknownText_0x1a4b1e
 ; 0x1a472b
 
-YoungsterScript_0x1a472b: ; 0x1a472b
+SantosScript:
 	faceplayer
 	loadfont
 	checkevent EVENT_GOT_SPELL_TAG_FROM_SANTOS
-	iftrue UnknownScript_0x1a4759
+	iftrue SantosSaturdayScript
 	checkcode $b
-	if_not_equal SATURDAY, UnknownScript_0x1a475f
+	if_not_equal SATURDAY, SantosNotSaturdayScript
 	checkevent EVENT_MET_SANTOS_OF_SATURDAY
-	iftrue UnknownScript_0x1a4746
-	2writetext UnknownText_0x1a4a27
+	iftrue .MetSantos
+	2writetext MeetSantosText
 	keeptextopen
 	setevent EVENT_MET_SANTOS_OF_SATURDAY
-UnknownScript_0x1a4746: ; 0x1a4746
-	2writetext UnknownText_0x1a4a57
+.MetSantos
+	2writetext SantosGivesGiftText
 	keeptextopen
 	verbosegiveitem SPELL_TAG, 1
-	iffalse UnknownScript_0x1a475d
+	iffalse SantosDoneScript
 	setevent EVENT_GOT_SPELL_TAG_FROM_SANTOS
-	2writetext UnknownText_0x1a4a6b
+	2writetext SantosGaveGiftText
 	closetext
 	loadmovesprites
 	end
-; 0x1a4759
 
-UnknownScript_0x1a4759: ; 0x1a4759
-	2writetext UnknownText_0x1a4ab6
+SantosSaturdayScript:
+	2writetext SantosSaturdayText
 	closetext
-UnknownScript_0x1a475d: ; 0x1a475d
+SantosDoneScript:
 	loadmovesprites
 	end
-; 0x1a475f
 
-UnknownScript_0x1a475f: ; 0x1a475f
-	2writetext UnknownText_0x1a4b00
+SantosNotSaturdayScript:
+	2writetext SantosNotSaturdayText
 	closetext
 	loadmovesprites
 	end
-; 0x1a4765
 
 MapBlackthornCitySignpost0Script: ; 0x1a4765
 	jumptext UnknownText_0x1a4b67
@@ -252,7 +246,7 @@ UnknownText_0x1a49f1: ; 0x1a49f1
 	done
 ; 0x1a4a27
 
-UnknownText_0x1a4a27: ; 0x1a4a27
+MeetSantosText:
 	text "SANTOS: …"
 
 	para "It's Saturday…"
@@ -260,14 +254,12 @@ UnknownText_0x1a4a27: ; 0x1a4a27
 	para "I'm SANTOS of"
 	line "Saturday…"
 	done
-; 0x1a4a57
 
-UnknownText_0x1a4a57: ; 0x1a4a57
+SantosGivesGiftText:
 	text "You can have this…"
 	done
-; 0x1a4a6b
 
-UnknownText_0x1a4a6b: ; 0x1a4a6b
+SantosGaveGiftText:
 	text "SANTOS: …"
 
 	para "SPELL TAG…"
@@ -278,9 +270,8 @@ UnknownText_0x1a4a6b: ; 0x1a4a6b
 	para "It will frighten"
 	line "you…"
 	done
-; 0x1a4ab6
 
-UnknownText_0x1a4ab6: ; 0x1a4ab6
+SantosSaturdayText:
 	text "SANTOS: …"
 
 	para "See you again on"
@@ -289,13 +280,11 @@ UnknownText_0x1a4ab6: ; 0x1a4ab6
 	para "I won't have any"
 	line "more gifts…"
 	done
-; 0x1a4b00
 
-UnknownText_0x1a4b00: ; 0x1a4b00
+SantosNotSaturdayText:
 	text "SANTOS: Today's"
 	line "not Saturday…"
 	done
-; 0x1a4b1e
 
 UnknownText_0x1a4b1e: ; 0x1a4b1e
 	text "Wow, you came"
@@ -386,7 +375,5 @@ BlackthornCity_MapEventHeader: ; 0x1a4c57
 	person_event SPRITE_BLACK_BELT, 35, 28, $5, $1, 255, 255, $90, 0, BlackBeltScript_0x1a470e, $ffff
 	person_event SPRITE_COOLTRAINER_F, 29, 13, $5, $2, 255, 255, $80, 0, CooltrainerFScript_0x1a4722, $ffff
 	person_event SPRITE_YOUNGSTER, 19, 17, $5, $1, 255, 255, $0, 0, YoungsterScript_0x1a4725, $ffff
-	person_event SPRITE_YOUNGSTER, 24, 26, $6, $0, 255, 255, $0, 0, YoungsterScript_0x1a472b, $075d
+	person_event SPRITE_YOUNGSTER, 24, 26, $6, $0, 255, 255, $0, 0, SantosScript, $075d
 	person_event SPRITE_COOLTRAINER_F, 23, 39, $7, $0, 255, 255, $a0, 0, CooltrainerFScript_0x1a4728, $ffff
-; 0x1a4d1d
-
diff --git a/maps/LakeofRage.asm b/maps/LakeofRage.asm
index fcd052968..0e3d6a1df 100644
--- a/maps/LakeofRage.asm
+++ b/maps/LakeofRage.asm
@@ -13,8 +13,7 @@ LakeofRage_MapScriptHeader: ; 0x70000
 
 	dbw 5, UnknownScript_0x70012
 
-	dbw 2, UnknownScript_0x70016
-; 0x70010
+	dbw 2, WesleyCallback
 
 UnknownScript_0x70010: ; 0x70010
 	end
@@ -29,17 +28,15 @@ UnknownScript_0x70012: ; 0x70012
 	return
 ; 0x70016
 
-UnknownScript_0x70016: ; 0x70016
+WesleyCallback:
 	checkcode $b
-	if_equal WEDNESDAY, UnknownScript_0x7001f
+	if_equal WEDNESDAY, .WesleyAppears
 	disappear $b
 	return
-; 0x7001f
 
-UnknownScript_0x7001f: ; 0x7001f
+.WesleyAppears
 	appear $b
 	return
-; 0x70022
 
 LanceScript_0x70022: ; 0x70022
 	checkevent EVENT_REFUSED_TO_HELP_LANCE_AT_LAKE_OF_RAGE
@@ -270,44 +267,41 @@ CooltrainerfLoisScript: ; 0x70106
 	end
 ; 0x7010e
 
-SuperNerdScript_0x7010e: ; 0x7010e
+WesleyScript:
 	faceplayer
 	loadfont
 	checkevent EVENT_GOT_BLACKBELT_FROM_WESLEY
-	iftrue UnknownScript_0x7013c
+	iftrue WesleyWednesdayScript
 	checkcode $b
-	if_not_equal WEDNESDAY, UnknownScript_0x70142
+	if_not_equal WEDNESDAY, WesleyNotWednesdayScript
 	checkevent EVENT_MET_WESLEY_OF_WEDNESDAY
-	iftrue UnknownScript_0x70129
-	2writetext UnknownText_0x70784
+	iftrue .MetWesley
+	2writetext MeetWesleyText
 	keeptextopen
 	setevent EVENT_MET_WESLEY_OF_WEDNESDAY
-UnknownScript_0x70129: ; 0x70129
-	2writetext UnknownText_0x707dd
+.MetWesley
+	2writetext WesleyGivesGiftText
 	keeptextopen
 	verbosegiveitem BLACKBELT, 1
-	iffalse UnknownScript_0x70140
+	iffalse WesleyDoneScript
 	setevent EVENT_GOT_BLACKBELT_FROM_WESLEY
-	2writetext UnknownText_0x7080b
+	2writetext WesleyGaveGiftText
 	closetext
 	loadmovesprites
 	end
-; 0x7013c
 
-UnknownScript_0x7013c: ; 0x7013c
-	2writetext UnknownText_0x70844
+WesleyWednesdayScript:
+	2writetext WesleyWednesdayText
 	closetext
-UnknownScript_0x70140: ; 0x70140
+WesleyDoneScript:
 	loadmovesprites
 	end
-; 0x70142
 
-UnknownScript_0x70142: ; 0x70142
-	2writetext UnknownText_0x708a9
+WesleyNotWednesdayScript:
+	2writetext WesleyNotWednesdayText
 	closetext
 	loadmovesprites
 	end
-; 0x70148
 
 ItemFragment_0x70148: ; 0x70148
 	db ELIXER, 1
@@ -561,7 +555,7 @@ UnknownText_0x70752: ; 0x70752
 	done
 ; 0x70784
 
-UnknownText_0x70784: ; 0x70784
+MeetWesleyText:
 	text "WESLEY: Well, how"
 	line "do you do?"
 
@@ -571,23 +565,20 @@ UnknownText_0x70784: ; 0x70784
 	para "I'm WESLEY of"
 	line "Wednesday."
 	done
-; 0x707dd
 
-UnknownText_0x707dd: ; 0x707dd
+WesleyGivesGiftText:
 	text "Pleased to meet"
 	line "you. Please take a"
 	cont "souvenir."
 	done
-; 0x7080b
 
-UnknownText_0x7080b: ; 0x7080b
+WesleyGaveGiftText:
 	text "WESLEY: BLACKBELT"
 	line "beefs up the power"
 	cont "of fighting moves."
 	done
-; 0x70844
 
-UnknownText_0x70844: ; 0x70844
+WesleyWednesdayText:
 	text "WESLEY: Since you"
 	line "found me, you must"
 
@@ -597,14 +588,12 @@ UnknownText_0x70844: ; 0x70844
 	para "Or did you just"
 	line "get lucky?"
 	done
-; 0x708a9
 
-UnknownText_0x708a9: ; 0x708a9
+WesleyNotWednesdayText:
 	text "WESLEY: Today's"
 	line "not Wednesday."
 	cont "That's too bad."
 	done
-; 0x708d7
 
 UnknownText_0x708d7: ; 0x708d7
 	text "LAKE OF RAGE,"
@@ -650,8 +639,6 @@ LakeofRage_MapEventHeader: ; 0x70919
 	person_event SPRITE_COOLTRAINER_M, 19, 8, $9, $0, 255, 255, $82, 1, TrainerCooltrainermAaron, $0735
 	person_event SPRITE_COOLTRAINER_F, 11, 40, $8, $0, 255, 255, $82, 0, TrainerCooltrainerfLois, $0735
 	person_event SPRITE_GYARADOS, 26, 22, $16, $0, 255, 255, $80, 0, GyaradosScript_0x70063, $0751
-	person_event SPRITE_SUPER_NERD, 8, 8, $6, $0, 255, 255, $0, 0, SuperNerdScript_0x7010e, $075c
+	person_event SPRITE_SUPER_NERD, 8, 8, $6, $0, 255, 255, $0, 0, WesleyScript, $075c
 	person_event SPRITE_POKE_BALL, 14, 11, $1, $0, 255, 255, $1, 0, ItemFragment_0x70148, $0645
 	person_event SPRITE_POKE_BALL, 6, 39, $1, $0, 255, 255, $1, 0, ItemFragment_0x7014a, $0646
-; 0x709de
-
diff --git a/maps/Route29.asm b/maps/Route29.asm
index f3b95ae7c..355e84fe0 100644
--- a/maps/Route29.asm
+++ b/maps/Route29.asm
@@ -11,8 +11,7 @@ Route29_MapScriptHeader: ; 0x1a0f4c
 
 	; callbacks
 
-	dbw 2, UnknownScript_0x1a0f5b
-; 0x1a0f59
+	dbw 2, TuscanyCallback
 
 UnknownScript_0x1a0f59: ; 0x1a0f59
 	end
@@ -22,20 +21,19 @@ UnknownScript_0x1a0f5a: ; 0x1a0f5a
 	end
 ; 0x1a0f5b
 
-UnknownScript_0x1a0f5b: ; 0x1a0f5b
+TuscanyCallback:
 	checkflag $001b
-	iftrue UnknownScript_0x1a0f64
-UnknownScript_0x1a0f61: ; 0x1a0f61
+	iftrue .DoesTuscanyAppear
+
+.TuscanyDisappears
 	disappear $8
 	return
-; 0x1a0f64
 
-UnknownScript_0x1a0f64: ; 0x1a0f64
+.DoesTuscanyAppear
 	checkcode $b
-	if_not_equal TUESDAY, UnknownScript_0x1a0f61
+	if_not_equal TUESDAY, .TuscanyDisappears
 	appear $8
 	return
-; 0x1a0f6d
 
 UnknownScript_0x1a0f6d: ; 0x1a0f6d
 	spriteface $2, $1
@@ -177,44 +175,41 @@ UnknownScript_0x1a1043: ; 0x1a1043
 	end
 ; 0x1a1049
 
-TeacherScript_0x1a1049: ; 0x1a1049
+TuscanyScript:
 	faceplayer
 	loadfont
 	checkevent EVENT_GOT_PINK_BOW_FROM_TUSCANY
-	iftrue UnknownScript_0x1a1077
+	iftrue TuscanyTuesdayScript
 	checkcode $b
-	if_not_equal TUESDAY, UnknownScript_0x1a107d
+	if_not_equal TUESDAY, TuscanyNotTuesdayScript
 	checkevent EVENT_MET_TUSCANY_OF_TUESDAY
-	iftrue UnknownScript_0x1a1064
-	2writetext UnknownText_0x1a13b2
+	iftrue .MetTuscany
+	2writetext MeetTuscanyText
 	keeptextopen
 	setevent EVENT_MET_TUSCANY_OF_TUESDAY
-UnknownScript_0x1a1064: ; 0x1a1064
-	2writetext UnknownText_0x1a142f
+.MetTuscany
+	2writetext TuscanyGivesGiftText
 	keeptextopen
 	verbosegiveitem PINK_BOW, 1
-	iffalse UnknownScript_0x1a107b
+	iffalse TuscanyDoneScript
 	setevent EVENT_GOT_PINK_BOW_FROM_TUSCANY
-	2writetext UnknownText_0x1a146f
+	2writetext TuscanyGaveGiftText
 	closetext
 	loadmovesprites
 	end
-; 0x1a1077
 
-UnknownScript_0x1a1077: ; 0x1a1077
-	2writetext UnknownText_0x1a14e7
+TuscanyTuesdayScript:
+	2writetext TuscanyTuesdayText
 	closetext
-UnknownScript_0x1a107b: ; 0x1a107b
+TuscanyDoneScript:
 	loadmovesprites
 	end
-; 0x1a107d
 
-UnknownScript_0x1a107d: ; 0x1a107d
-	2writetext UnknownText_0x1a1559
+TuscanyNotTuesdayScript:
+	2writetext TuscanyNotTuesdayText
 	closetext
 	loadmovesprites
 	end
-; 0x1a1083
 
 MapRoute29Signpost0Script: ; 0x1a1083
 	jumptext UnknownText_0x1a158e
@@ -382,7 +377,7 @@ UnknownText_0x1a137c: ; 0x1a137c
 	done
 ; 0x1a13b2
 
-UnknownText_0x1a13b2: ; 0x1a13b2
+MeetTuscanyText:
 	text "TUSCANY: I do be-"
 	line "lieve that this is"
 
@@ -395,18 +390,16 @@ UnknownText_0x1a13b2: ; 0x1a13b2
 	para "I am TUSCANY of"
 	line "Tuesday."
 	done
-; 0x1a142f
 
-UnknownText_0x1a142f: ; 0x1a142f
+TuscanyGivesGiftText:
 	text "By way of intro-"
 	line "duction, please"
 
 	para "accept this gift,"
 	line "a PINK BOW."
 	done
-; 0x1a146f
 
-UnknownText_0x1a146f: ; 0x1a146f
+TuscanyGaveGiftText:
 	text "TUSCANY: Wouldn't"
 	line "you agree that it"
 	cont "is most adorable?"
@@ -417,9 +410,8 @@ UnknownText_0x1a146f: ; 0x1a146f
 	para "I am certain it"
 	line "will be of use."
 	done
-; 0x1a14e7
 
-UnknownText_0x1a14e7: ; 0x1a14e7
+TuscanyTuesdayText:
 	text "TUSCANY: Have you"
 	line "met MONICA, my"
 	cont "older sister?"
@@ -430,14 +422,12 @@ UnknownText_0x1a14e7: ; 0x1a14e7
 	para "I am the second of"
 	line "seven children."
 	done
-; 0x1a1559
 
-UnknownText_0x1a1559: ; 0x1a1559
+TuscanyNotTuesdayText:
 	text "TUSCANY: Today is"
 	line "not Tuesday. That"
 	cont "is unfortunate…"
 	done
-; 0x1a158e
 
 UnknownText_0x1a158e: ; 0x1a158e
 	text "ROUTE 29"
@@ -481,7 +471,5 @@ Route29_MapEventHeader: ; 0x1a15e4
 	person_event SPRITE_FRUIT_TREE, 6, 16, $1, $0, 255, 255, $0, 0, FruitTreeScript_0x1a1089, $ffff
 	person_event SPRITE_FISHER, 7, 29, $7, $0, 255, 255, $90, 0, FisherScript_0x1a102e, $ffff
 	person_event SPRITE_COOLTRAINER_M, 8, 17, $6, $0, 255, 255, $80, 0, CooltrainerMScript_0x1a1031, $ffff
-	person_event SPRITE_TEACHER, 16, 33, $3, $0, 255, 255, $0, 0, TeacherScript_0x1a1049, $0759
+	person_event SPRITE_TEACHER, 16, 33, $3, $0, 255, 255, $0, 0, TuscanyScript, $0759
 	person_event SPRITE_POKE_BALL, 6, 52, $1, $0, 255, 255, $1, 0, ItemFragment_0x1a108b, $06ad
-; 0x1a1671
-
diff --git a/maps/Route32.asm b/maps/Route32.asm
index 88c3a01bc..62ea20e77 100644
--- a/maps/Route32.asm
+++ b/maps/Route32.asm
@@ -12,8 +12,7 @@ Route32_MapScriptHeader: ; 0x19044f
 
 	; callbacks
 
-	dbw 2, UnknownScript_0x190463
-; 0x190460
+	dbw 2, FriedaCallback
 
 UnknownScript_0x190460: ; 0x190460
 	end
@@ -27,17 +26,15 @@ UnknownScript_0x190462: ; 0x190462
 	end
 ; 0x190463
 
-UnknownScript_0x190463: ; 0x190463
+FriedaCallback:
 	checkcode $b
-	if_equal FRIDAY, UnknownScript_0x19046c
+	if_equal FRIDAY, .FriedaAppears
 	disappear $e
 	return
-; 0x19046c
 
-UnknownScript_0x19046c: ; 0x19046c
+.FriedaAppears
 	appear $e
 	return
-; 0x19046f
 
 CooltrainerMScript_0x19046f: ; 0x19046f
 	faceplayer
@@ -627,44 +624,41 @@ Bird_keeperPeterScript: ; 0x190731
 	end
 ; 0x190739
 
-LassScript_0x190739: ; 0x190739
+FriedaScript:
 	faceplayer
 	loadfont
 	checkevent EVENT_GOT_POISON_BARB_FROM_FRIEDA
-	iftrue UnknownScript_0x190767
+	iftrue FriedaFridayScript
 	checkcode $b
-	if_not_equal FRIDAY, UnknownScript_0x19076d
+	if_not_equal FRIDAY, FriedaNotFridayScript
 	checkevent EVENT_MET_FRIEDA_OF_FRIDAY
-	iftrue UnknownScript_0x190754
-	2writetext UnknownText_0x1911c1
+	iftrue .MetFrieda
+	2writetext MeetFriedaText
 	keeptextopen
 	setevent EVENT_MET_FRIEDA_OF_FRIDAY
-UnknownScript_0x190754: ; 0x190754
-	2writetext UnknownText_0x191204
+.MetFrieda
+	2writetext FriedaGivesGiftText
 	keeptextopen
 	verbosegiveitem POISON_BARB, 1
-	iffalse UnknownScript_0x19076b
+	iffalse FriedaDoneScript
 	setevent EVENT_GOT_POISON_BARB_FROM_FRIEDA
-	2writetext UnknownText_0x191222
+	2writetext FriedaGaveGiftText
 	closetext
 	loadmovesprites
 	end
-; 0x190767
 
-UnknownScript_0x190767: ; 0x190767
-	2writetext UnknownText_0x19129a
+FriedaFridayScript:
+	2writetext FriedaFridayText
 	closetext
-UnknownScript_0x19076b: ; 0x19076b
+FriedaDoneScript:
 	loadmovesprites
 	end
-; 0x19076d
 
-UnknownScript_0x19076d: ; 0x19076d
-	2writetext UnknownText_0x1912ff
+FriedaNotFridayScript:
+	2writetext FriedaNotFridayText
 	closetext
 	loadmovesprites
 	end
-; 0x190773
 
 ItemFragment_0x190773: ; 0x190773
 	db GREAT_BALL, 1
@@ -1100,7 +1094,7 @@ UnknownText_0x19118c: ; 0x19118c
 	done
 ; 0x1911c1
 
-UnknownText_0x1911c1: ; 0x1911c1
+MeetFriedaText:
 	text "FRIEDA: Yahoo!"
 	line "It's Friday!"
 
@@ -1109,15 +1103,13 @@ UnknownText_0x1911c1: ; 0x1911c1
 
 	para "Nice to meet you!"
 	done
-; 0x191204
 
-UnknownText_0x191204: ; 0x191204
+FriedaGivesGiftText:
 	text "Here's a POISON"
 	line "BARB for you!"
 	done
-; 0x191222
 
-UnknownText_0x191222: ; 0x191222
+FriedaGaveGiftText:
 	text "FRIEDA: Give it to"
 	line "a #MON that has"
 	cont "poison-type moves."
@@ -1130,9 +1122,8 @@ UnknownText_0x191222: ; 0x191222
 	line "how good it makes"
 	cont "poison moves!"
 	done
-; 0x19129a
 
-UnknownText_0x19129a: ; 0x19129a
+FriedaFridayText:
 	text "FRIEDA: Hiya! What"
 	line "day do you like?"
 
@@ -1142,16 +1133,14 @@ UnknownText_0x19129a: ; 0x19129a
 	para "Don't you think"
 	line "it's great too?"
 	done
-; 0x1912ff
 
-UnknownText_0x1912ff: ; 0x1912ff
+FriedaNotFridayText:
 	text "FRIEDA: Isn't it"
 	line "Friday today?"
 
 	para "It's so boring"
 	line "when it's not!"
 	done
-; 0x19133a
 
 UnknownText_0x19133a: ; 0x19133a
 	text "ROUTE 32"
@@ -1212,7 +1201,5 @@ Route32_MapEventHeader: ; 0x19138d
 	person_event SPRITE_FISHER, 74, 11, $6, $0, 255, 255, $0, 0, FisherScript_0x1904f2, $06fc
 	person_event SPRITE_POKE_BALL, 57, 10, $1, $0, 255, 255, $1, 0, ItemFragment_0x190773, $06b0
 	person_event SPRITE_FISHER, 17, 19, $9, $0, 255, 255, $0, 0, FisherScript_0x1904ce, $ffff
-	person_event SPRITE_LASS, 71, 16, $8, $0, 255, 255, $0, 0, LassScript_0x190739, $0758
+	person_event SPRITE_LASS, 71, 16, $8, $0, 255, 255, $0, 0, FriedaScript, $0758
 	person_event SPRITE_POKE_BALL, 34, 7, $1, $0, 255, 255, $1, 0, ItemFragment_0x190775, $06b1
-; 0x19148b
-
diff --git a/maps/Route36.asm b/maps/Route36.asm
index 7f29e415c..e95ff6d4e 100644
--- a/maps/Route36.asm
+++ b/maps/Route36.asm
@@ -11,8 +11,7 @@ Route36_MapScriptHeader: ; 0x194000
 
 	; callbacks
 
-	dbw 2, UnknownScript_0x19400f
-; 0x19400d
+	dbw 2, ArthurCallback
 
 UnknownScript_0x19400d: ; 0x19400d
 	end
@@ -22,17 +21,15 @@ UnknownScript_0x19400e: ; 0x19400e
 	end
 ; 0x19400f
 
-UnknownScript_0x19400f: ; 0x19400f
+ArthurCallback:
 	checkcode $b
-	if_equal THURSDAY, UnknownScript_0x194018
+	if_equal THURSDAY, .ArthurAppears
 	disappear $8
 	return
-; 0x194018
 
-UnknownScript_0x194018: ; 0x194018
+.ArthurAppears
 	appear $8
 	return
-; 0x19401b
 
 UnknownScript_0x19401b: ; 0x19401b
 	showemote $0, $0, 15
@@ -381,44 +378,41 @@ PsychicMarkScript: ; 0x1941f9
 	end
 ; 0x194201
 
-YoungsterScript_0x194201: ; 0x194201
+ArthurScript:
 	faceplayer
 	loadfont
 	checkevent EVENT_GOT_HARD_STONE_FROM_ARTHUR
-	iftrue UnknownScript_0x19422f
+	iftrue ArthurThursdayScript
 	checkcode $b
-	if_not_equal THURSDAY, UnknownScript_0x194235
+	if_not_equal THURSDAY, ArthurNotThursdayScript
 	checkevent EVENT_MET_ARTHUR_OF_THURSDAY
-	iftrue UnknownScript_0x19421c
-	2writetext UnknownText_0x194800
+	iftrue .MetArthur
+	2writetext MeetArthurText
 	keeptextopen
 	setevent EVENT_MET_ARTHUR_OF_THURSDAY
-UnknownScript_0x19421c: ; 0x19421c
-	2writetext UnknownText_0x19482d
+.MetArthur
+	2writetext ArthurGivesGiftText
 	keeptextopen
 	verbosegiveitem HARD_STONE, 1
-	iffalse UnknownScript_0x194233
+	iffalse ArthurDoneScript
 	setevent EVENT_GOT_HARD_STONE_FROM_ARTHUR
-	2writetext UnknownText_0x194847
+	2writetext ArthurGaveGiftText
 	closetext
 	loadmovesprites
 	end
-; 0x19422f
 
-UnknownScript_0x19422f: ; 0x19422f
-	2writetext UnknownText_0x1948aa
+ArthurThursdayScript:
+	2writetext ArthurThursdayText
 	closetext
-UnknownScript_0x194233: ; 0x194233
+ArthurDoneScript:
 	loadmovesprites
 	end
-; 0x194235
 
-UnknownScript_0x194235: ; 0x194235
-	2writetext UnknownText_0x1948f3
+ArthurNotThursdayScript:
+	2writetext ArthurNotThursdayText
 	closetext
 	loadmovesprites
 	end
-; 0x19423b
 
 MapRoute36Signpost2Script: ; 0x19423b
 	jumptext UnknownText_0x194924
@@ -678,22 +672,20 @@ UnknownText_0x1947aa: ; 0x1947aa
 	done
 ; 0x194800
 
-UnknownText_0x194800: ; 0x194800
+MeetArthurText:
 	text "ARTHUR: Who are"
 	line "you?"
 
 	para "I'm ARTHUR of"
 	line "Thursday."
 	done
-; 0x19482d
 
-UnknownText_0x19482d: ; 0x19482d
+ArthurGivesGiftText:
 	text "Here. You can have"
 	line "this."
 	done
-; 0x194847
 
-UnknownText_0x194847: ; 0x194847
+ArthurGaveGiftText:
 	text "ARTHUR: A #MON"
 	line "that uses rock-"
 
@@ -703,23 +695,20 @@ UnknownText_0x194847: ; 0x194847
 	para "It pumps up rock-"
 	line "type attacks."
 	done
-; 0x1948aa
 
-UnknownText_0x1948aa: ; 0x1948aa
+ArthurThursdayText:
 	text "ARTHUR: I'm ARTHUR"
 	line "of Thursday. I'm"
 
 	para "the second son out"
 	line "of seven children."
 	done
-; 0x1948f3
 
-UnknownText_0x1948f3: ; 0x1948f3
+ArthurNotThursdayText:
 	text "ARTHUR: Today's"
 	line "not Thursday. How"
 	cont "disappointing."
 	done
-; 0x194924
 
 UnknownText_0x194924: ; 0x194924
 	text "ROUTE 36"
@@ -796,8 +785,6 @@ Route36_MapEventHeader: ; 0x194a66
 	person_event SPRITE_LASS, 12, 55, $5, $2, 255, 255, $0, 0, LassScript_0x1940e0, $ffff
 	person_event SPRITE_FISHER, 13, 48, $8, $0, 255, 255, $0, 0, FisherScript_0x1940b9, $ffff
 	person_event SPRITE_FRUIT_TREE, 8, 25, $1, $0, 255, 255, $0, 0, FruitTreeScript_0x194247, $ffff
-	person_event SPRITE_YOUNGSTER, 10, 50, $2, $11, 255, 255, $0, 0, YoungsterScript_0x194201, $075a
+	person_event SPRITE_YOUNGSTER, 10, 50, $2, $11, 255, 255, $0, 0, ArthurScript, $075a
 	person_event SPRITE_LASS, 16, 37, $6, $0, 255, 255, $90, 0, LassScript_0x19408c, $0769
 	person_event SPRITE_SUICUNE, 10, 25, $1, $0, 255, 255, $90, 0, ObjectEvent, $07b0
-; 0x194b19
-
diff --git a/maps/Route37.asm b/maps/Route37.asm
index ca2298c26..f732f0a90 100644
--- a/maps/Route37.asm
+++ b/maps/Route37.asm
@@ -7,20 +7,17 @@ Route37_MapScriptHeader: ; 0x1a8d72
 
 	; callbacks
 
-	dbw 2, UnknownScript_0x1a8d77
-; 0x1a8d77
+	dbw 2, SunnyCallback
 
-UnknownScript_0x1a8d77: ; 0x1a8d77
+SunnyCallback:
 	checkcode $b
-	if_equal SUNDAY, UnknownScript_0x1a8d80
+	if_equal SUNDAY, .SunnyAppears
 	disappear $6
 	return
-; 0x1a8d80
 
-UnknownScript_0x1a8d80: ; 0x1a8d80
+.SunnyAppears
 	appear $6
 	return
-; 0x1a8d83
 
 TrainerTwinsAnnandanne1: ; 0x1a8d83
 	; bit/flag number
@@ -109,53 +106,48 @@ PsychicGregScript: ; 0x1a8db7
 	end
 ; 0x1a8dbf
 
-BugCatcherScript_0x1a8dbf: ; 0x1a8dbf
+SunnyScript:
 	faceplayer
 	loadfont
 	checkevent EVENT_GOT_MAGNET_FROM_SUNNY
-	iftrue UnknownScript_0x1a8dfa
+	iftrue SunnySundayScript
 	checkcode $b
-	if_not_equal SUNDAY, UnknownScript_0x1a8e00
+	if_not_equal SUNDAY, SunnyNotSundayScript
 	checkevent EVENT_MET_SUNNY_OF_SUNDAY
-	iftrue UnknownScript_0x1a8dda
-	2writetext UnknownText_0x1a8fc8
+	iftrue .MetSunny
+	2writetext MeetSunnyText
 	keeptextopen
 	setevent EVENT_MET_SUNNY_OF_SUNDAY
-UnknownScript_0x1a8dda: ; 0x1a8dda
+.MetSunny
 	checkflag $0063
-	iftrue UnknownScript_0x1a8de7
-	2writetext UnknownText_0x1a9004
+	iftrue .Kris
+	2writetext SunnyGivesGiftText1
 	keeptextopen
-	2jump UnknownScript_0x1a8deb
-; 0x1a8de7
-
-UnknownScript_0x1a8de7: ; 0x1a8de7
-	2writetext UnknownText_0x1a902f
+	2jump .next
+.Kris
+	2writetext SunnyGivesGiftText2
 	keeptextopen
-UnknownScript_0x1a8deb: ; 0x1a8deb
+.next
 	verbosegiveitem MAGNET, 1
-	iffalse UnknownScript_0x1a8dfe
+	iffalse SunnyDoneScript
 	setevent EVENT_GOT_MAGNET_FROM_SUNNY
-	2writetext UnknownText_0x1a905a
+	2writetext SunnyGaveGiftText
 	closetext
 	loadmovesprites
 	end
-; 0x1a8dfa
 
-UnknownScript_0x1a8dfa: ; 0x1a8dfa
-	2writetext UnknownText_0x1a90fc
+SunnySundayScript:
+	2writetext SunnySundayText
 	closetext
-UnknownScript_0x1a8dfe: ; 0x1a8dfe
+SunnyDoneScript:
 	loadmovesprites
 	end
-; 0x1a8e00
 
-UnknownScript_0x1a8e00: ; 0x1a8e00
-	2writetext UnknownText_0x1a916e
+SunnyNotSundayScript:
+	2writetext SunnyNotSundayText
 	closetext
 	loadmovesprites
 	end
-; 0x1a8e06
 
 MapRoute37Signpost0Script: ; 0x1a8e06
 	jumptext UnknownText_0x1a9197
@@ -245,30 +237,27 @@ UnknownText_0x1a8f80: ; 0x1a8f80
 	done
 ; 0x1a8fc8
 
-UnknownText_0x1a8fc8: ; 0x1a8fc8
+MeetSunnyText:
 	text "SUNNY: Hi!"
 
 	para "I'm SUNNY of Sun-"
 	line "day, meaning it's"
 	cont "Sunday today!"
 	done
-; 0x1a9004
 
-UnknownText_0x1a9004: ; 0x1a9004
+SunnyGivesGiftText1:
 	text "I was told to give"
 	line "you this if I saw"
 	cont "you!"
 	done
-; 0x1a902f
 
-UnknownText_0x1a902f: ; 0x1a902f
+SunnyGivesGiftText2:
 	text "I was told to give"
 	line "you this if I saw"
 	cont "you!"
 	done
-; 0x1a905a
 
-UnknownText_0x1a905a: ; 0x1a905a
+SunnyGaveGiftText:
 	text "SUNNY: That thing…"
 
 	para "Um…"
@@ -290,9 +279,8 @@ UnknownText_0x1a905a: ; 0x1a905a
 	line "it powers up"
 	cont "electric moves!"
 	done
-; 0x1a90fc
 
-UnknownText_0x1a90fc: ; 0x1a90fc
+SunnySundayText:
 	text "SUNNY: My sisters"
 	line "and brothers are"
 	cont "MONICA, TUSCANY,"
@@ -302,14 +290,12 @@ UnknownText_0x1a90fc: ; 0x1a90fc
 	para "They're all older"
 	line "than me!"
 	done
-; 0x1a916e
 
-UnknownText_0x1a916e: ; 0x1a916e
+SunnyNotSundayText:
 	text "SUNNY: Isn't today"
 	line "Sunday?"
 	cont "Um… I forgot!"
 	done
-; 0x1a9197
 
 UnknownText_0x1a9197: ; 0x1a9197
 	text "ROUTE 37"
@@ -337,8 +323,6 @@ Route37_MapEventHeader: ; 0x1a91a1
 	person_event SPRITE_WEIRD_TREE, 16, 11, $6, $0, 255, 255, $82, 1, TrainerTwinsAnnandanne2, $ffff
 	person_event SPRITE_YOUNGSTER, 10, 10, $a, $0, 255, 255, $92, 1, TrainerPsychicGreg, $ffff
 	person_event SPRITE_FRUIT_TREE, 9, 17, $1, $0, 255, 255, $0, 0, FruitTreeScript_0x1a8e09, $ffff
-	person_event SPRITE_BUG_CATCHER, 12, 20, $2, $11, 255, 255, $0, 0, BugCatcherScript_0x1a8dbf, $075b
+	person_event SPRITE_BUG_CATCHER, 12, 20, $2, $11, 255, 255, $0, 0, SunnyScript, $075b
 	person_event SPRITE_FRUIT_TREE, 9, 20, $1, $0, 255, 255, $0, 0, FruitTreeScript_0x1a8e0b, $ffff
 	person_event SPRITE_FRUIT_TREE, 11, 19, $1, $0, 255, 255, $0, 0, FruitTreeScript_0x1a8e0d, $ffff
-; 0x1a920c
-
diff --git a/maps/Route40.asm b/maps/Route40.asm
index fe7bd2610..1110356a4 100644
--- a/maps/Route40.asm
+++ b/maps/Route40.asm
@@ -7,21 +7,18 @@ Route40_MapScriptHeader: ; 0x1a6160
 
 	; callbacks
 
-	dbw 2, UnknownScript_0x1a6165
-; 0x1a6165
+	dbw 2, MonicaCallback
 
-UnknownScript_0x1a6165: ; 0x1a6165
+MonicaCallback:
 	clearevent $07cf
 	checkcode $b
-	if_equal MONDAY, UnknownScript_0x1a6171
+	if_equal MONDAY, .MonicaAppears
 	disappear $a
 	return
-; 0x1a6171
 
-UnknownScript_0x1a6171: ; 0x1a6171
+.MonicaAppears
 	appear $a
 	return
-; 0x1a6174
 
 TrainerSwimmerfElaine: ; 0x1a6174
 	; bit/flag number
@@ -161,44 +158,41 @@ StandingYoungsterScript_0x1a61d6: ; 0x1a61d6
 	jumptextfaceplayer UnknownText_0x1a6564
 ; 0x1a61d9
 
-BuenaScript_0x1a61d9: ; 0x1a61d9
+MonicaScript:
 	faceplayer
 	loadfont
 	checkevent EVENT_GOT_SHARP_BEAK_FROM_MONICA
-	iftrue UnknownScript_0x1a6207
+	iftrue MonicaMondayScript
 	checkcode $b
-	if_not_equal MONDAY, UnknownScript_0x1a620d
+	if_not_equal MONDAY, MonicaNotMondayScript
 	checkevent EVENT_MET_MONICA_OF_MONDAY
-	iftrue UnknownScript_0x1a61f4
-	2writetext UnknownText_0x1a6606
+	iftrue .MetMonica
+	2writetext MeetMonicaText
 	keeptextopen
 	setevent EVENT_MET_MONICA_OF_MONDAY
-UnknownScript_0x1a61f4: ; 0x1a61f4
-	2writetext UnknownText_0x1a6636
+.MetMonica
+	2writetext MonicaGivesGiftText
 	keeptextopen
 	verbosegiveitem SHARP_BEAK, 1
-	iffalse UnknownScript_0x1a620b
+	iffalse MonicaDoneScript
 	setevent EVENT_GOT_SHARP_BEAK_FROM_MONICA
-	2writetext UnknownText_0x1a666c
+	2writetext MonicaGaveGiftText
 	closetext
 	loadmovesprites
 	end
-; 0x1a6207
 
-UnknownScript_0x1a6207: ; 0x1a6207
-	2writetext UnknownText_0x1a66dc
+MonicaMondayScript:
+	2writetext MonicaMondayText
 	closetext
-UnknownScript_0x1a620b: ; 0x1a620b
+MonicaDoneScript:
 	loadmovesprites
 	end
-; 0x1a620d
 
-UnknownScript_0x1a620d: ; 0x1a620d
-	2writetext UnknownText_0x1a6737
+MonicaNotMondayScript:
+	2writetext MonicaNotMondayText
 	closetext
 	loadmovesprites
 	end
-; 0x1a6213
 
 MapRoute40Signpost0Script: ; 0x1a6213
 	jumptext UnknownText_0x1a6767
@@ -384,22 +378,20 @@ UnknownText_0x1a6564: ; 0x1a6564
 	done
 ; 0x1a6606
 
-UnknownText_0x1a6606: ; 0x1a6606
+MeetMonicaText:
 	text "MONICA: Glad to"
 	line "meet you. I'm"
 
 	para "MONICA of Monday."
 	done
-; 0x1a6636
 
-UnknownText_0x1a6636: ; 0x1a6636
+MonicaGivesGiftText:
 	text "As a token of our"
 	line "friendship, I have"
 	cont "a gift for you!"
 	done
-; 0x1a666c
 
-UnknownText_0x1a666c: ; 0x1a666c
+MonicaGaveGiftText:
 	text "MONICA: It's an"
 	line "item that raises"
 
@@ -410,9 +402,8 @@ UnknownText_0x1a666c: ; 0x1a666c
 	line "bird #MON with"
 	cont "that item."
 	done
-; 0x1a66dc
 
-UnknownText_0x1a66dc: ; 0x1a66dc
+MonicaMondayText:
 	text "MONICA: My broth-"
 	line "ers and sisters"
 
@@ -422,14 +413,12 @@ UnknownText_0x1a66dc: ; 0x1a66dc
 	para "See if you could"
 	line "find them all!"
 	done
-; 0x1a6737
 
-UnknownText_0x1a6737: ; 0x1a6737
+MonicaNotMondayText:
 	text "MONICA: I don't"
 	line "think today is"
 	cont "Monday. How sad…"
 	done
-; 0x1a6767
 
 UnknownText_0x1a6767: ; 0x1a6767
 	text "ROUTE 40"
@@ -465,9 +454,7 @@ Route40_MapEventHeader: ; 0x1a678e
 	person_event SPRITE_ROCK, 13, 10, $18, $0, 255, 255, $0, 0, RockScript_0x1a6216, $ffff
 	person_event SPRITE_ROCK, 12, 11, $18, $0, 255, 255, $0, 0, RockScript_0x1a6216, $ffff
 	person_event SPRITE_LASS, 17, 15, $6, $0, 255, 255, $0, 0, LassScript_0x1a61c4, $ffff
-	person_event SPRITE_BUENA, 14, 12, $3, $0, 255, 255, $0, 0, BuenaScript_0x1a61d9, $075e
+	person_event SPRITE_BUENA, 14, 12, $3, $0, 255, 255, $0, 0, MonicaScript, $075e
 	person_event SPRITE_POKEFAN_M, 10, 11, $9, $0, 255, 255, $0, 0, PokefanMScript_0x1a61c7, $ffff
 	person_event SPRITE_LASS, 8, 17, $3, $0, 255, 255, $a0, 0, LassScript_0x1a61d3, $ffff
 	person_event SPRITE_STANDING_YOUNGSTER, 13, 20, $3, $0, 255, 255, $90, 0, StandingYoungsterScript_0x1a61d6, $07cf
-; 0x1a683f
-