Further document AI stuff

engine/battle/core.asm

@@ -991,7 +991,7 @@ ReplaceFaintedEnemyMon: ; 3c664 (f:4664)
 	xor a
 	ld [W_ENEMYMOVENUM], a
 	ld [wcd6a], a
-	ld [wccd5], a
+	ld [wAILayer2Encouragement], a
 	inc a ; reset Z flag
 	ret
 
@@ -3128,7 +3128,7 @@ ExecutePlayerMove: ; 3d65e (f:565e)
 	jp z, ExecutePlayerMoveDone ; for selected move = FF, skip most of player's turn
 	xor a
 	ld [W_MOVEMISSED], a
-	ld [wcced], a
+	ld [wMonIsDisobedient], a
 	ld [wMoveDidntMiss], a
 	ld a, $a
 	ld [wDamageMultipliers], a
@@ -3251,7 +3251,7 @@ MirrorMoveCheck
 	call MirrorMoveCopyMove
 	jp z,ExecutePlayerMoveDone
 	xor a
-	ld [wcced],a
+	ld [wMonIsDisobedient],a
 	jp CheckIfPlayerNeedsToChargeUp ; if Mirror Move was successful go back to damage calculation for copied move
 .metronomeCheck
 	cp a,METRONOME_EFFECT
@@ -3778,7 +3778,7 @@ MonName1Text: ; 3dafb (f:5afb)
 	ld [hl], a
 	ld [wd11e], a
 	call Func_3db85
-	ld a, [wcced]
+	ld a, [wMonIsDisobedient]
 	and a
 	ld hl, Used2Text
 	ret nz
@@ -3799,7 +3799,7 @@ Used2Text: ; 3db34 (f:5b34)
 	db $08 ; asm
 
 PrintInsteadText: ; 3db39 (f:5b39)
-	ld a, [wcced]
+	ld a, [wMonIsDisobedient]
 	and a
 	jr z, PrintCF4BText
 	ld hl, InsteadText
@@ -4007,7 +4007,7 @@ OHKOText: ; 3dc83 (f:5c83)
 ; stores whether the mon will use a move in Z flag
 CheckForDisobedience: ; 3dc88 (f:5c88)
 	xor a
-	ld [wcced], a
+	ld [wMonIsDisobedient], a
 	ld a, [wLinkState]
 	cp LINK_STATE_BATTLING
 	jr nz, .checkIfMonIsTraded
@@ -4148,7 +4148,7 @@ CheckForDisobedience: ; 3dc88 (f:5c88)
 	cp b
 	jr z, .monDoesNothing ; mon will not use move if only one move has remaining PP
 	ld a, $1
-	ld [wcced], a
+	ld [wMonIsDisobedient], a
 	ld a, [wMaxMenuItem]
 	ld b, a
 	ld a, [wCurrentMenuItem]
@@ -5655,7 +5655,7 @@ ExecuteEnemyMove: ; 3e6bc (f:66bc)
 	cp $4
 	ret nc
 .executeEnemyMove
-	ld hl, wccd5
+	ld hl, wAILayer2Encouragement
 	inc [hl]
 	xor a
 	ld [W_MOVEMISSED], a
@@ -5693,7 +5693,7 @@ EnemyCanExecuteChargingMove: ; 3e70b (f:670b)
 	call CopyStringToCF4B
 EnemyCanExecuteMove: ; 3e72b (f:672b)
 	xor a
-	ld [wcced], a
+	ld [wMonIsDisobedient], a
 	call PrintMonName1Text
 	ld a, [W_ENEMYMOVEEFFECT]
 	ld hl, ResidualEffects1

engine/battle/e.asm

@@ -230,7 +230,7 @@ AIMoveChoiceModification1: ; 397ab (e:57ab)
 	ret z ; return if no status ailment on player's mon
 	ld hl, wBuffer - 1 ; temp move selection array (-1 byte offest)
 	ld de, wEnemyMonMoves ; enemy moves
-	ld b, $5
+	ld b, NUM_MOVES + 1
 .nextMove
 	dec b
 	ret z ; processed all 4 moves
@@ -255,25 +255,27 @@ AIMoveChoiceModification1: ; 397ab (e:57ab)
 	pop hl
 	jr nc, .nextMove
 	ld a, [hl]
-	add $5       ; discourage move
+	add $5 ; heavily discourage move
 	ld [hl], a
 	jr .nextMove
 
 StatusAilmentMoveEffects ; 57e2
-	db $01 ; some sleep effect?
+	db $01 ; unused sleep effect
 	db SLEEP_EFFECT
 	db POISON_EFFECT
 	db PARALYZE_EFFECT
 	db $FF
 
-; slightly encourage moves with specific effects
+; slightly encourage moves with specific effects.
+; in particular, stat-modifying moves and other move effects
+; that fall in-bewteen
 AIMoveChoiceModification2: ; 397e7 (e:57e7)
-	ld a, [wccd5]
+	ld a, [wAILayer2Encouragement]
 	cp $1 
 	ret nz
 	ld hl, wBuffer - 1 ; temp move selection array (-1 byte offest)
 	ld de, wEnemyMonMoves ; enemy moves
-	ld b, $5
+	ld b, NUM_MOVES + 1
 .nextMove
 	dec b
 	ret z ; processed all 4 moves
@@ -294,10 +296,12 @@ AIMoveChoiceModification2: ; 397e7 (e:57e7)
 	jr c, .preferMove
 	jr .nextMove
 .preferMove
-	dec [hl]       ; slighly encourage this move
+	dec [hl] ; sligthly encourage this move
 	jr .nextMove
 
-; encourages moves that are effective against the player's mon
+; encourages moves that are effective against the player's mon (even if non-damaging).
+; discourage damaging moves that are ineffective or not very effective against the player's mon,
+; unless there's no damaging move that deals at least neutral damage
 AIMoveChoiceModification3: ; 39817 (e:5817)
 	ld hl, wBuffer - 1 ; temp move selection array (-1 byte offest)
 	ld de, wEnemyMonMoves ; enemy moves
@@ -322,7 +326,7 @@ AIMoveChoiceModification3: ; 39817 (e:5817)
 	cp $10
 	jr z, .nextMove
 	jr c, .notEffectiveMove
-	dec [hl]       ; slighly encourage this move
+	dec [hl] ; sligthly encourage this move
 	jr .nextMove
 .notEffectiveMove ; discourages non-effective moves if better moves are available
 	push hl
@@ -363,7 +367,7 @@ AIMoveChoiceModification3: ; 39817 (e:5817)
 	pop hl
 	and a
 	jr z, .nextMove
-	inc [hl]       ; slighly discourage this move
+	inc [hl] ; sligthly discourage this move
 	jr .nextMove
 AIMoveChoiceModification4: ; 39883 (e:5883)
 	ret

wram.asm

@@ -378,7 +378,11 @@ wSimulatedJoypadStatesEnd:: ; ccd3
 
 wccd3:: ds 1
 wccd4:: ds 1
-wccd5:: ds 2
+
+; if [ccd5] != 1, the second AI layer is not applied
+wAILayer2Encouragement:: ; ccd5
+	ds 1
+	ds 1
 
 ; current HP of player and enemy substitutes
 wPlayerSubstituteHP:: ; ccd7
@@ -425,7 +429,7 @@ wSafariBaitFactor:: ; cce9
 
 wcceb:: ds 1
 wccec:: ds 1
-wcced:: ds 1
+wMonIsDisobedient:: ds 1
 wccee:: ds 1
 wccef:: ds 1
 wccf0:: ds 1