Groundwork for the Candy Jar rework

This does everything except the incrementation.

If you defeat a Meltan, `wCandyJarCount` increments by 1, capping at 40. This is represented in-game as 10, going up to 400, simply by adding a 0 at the end. This, in effect, replicates the Meltan quest from Pokemon Go.

Once 40/400 is reached, the Candy Jar will become an evolution stone, evolving Meltan. Instead of consuming the Jar, the Candies inside are zeroed out.

Currently, the Candy Jar increments, but only once, thus why this is being committed on a separate branch. The bug appears to be at `engine\battle\core.asm`, line 842-861, likely 854-856. It's possible that it could be due to its position in WRAM, or that it's a `db` instead of a `dw`.

data/items/key_items.asm

@@ -75,7 +75,7 @@ KeyItemFlags:
 	dbit TRUE  ; POKE_FLUTE
 	dbit TRUE  ; LIFT_KEY
 	dbit FALSE ; EXP_ALL
-	dbit FALSE  ; was TRUE for OLD_ROD, now CANDY_SACK
+	dbit TRUE  ; was TRUE for OLD_ROD, now CANDY_JAR
 	dbit FALSE  ; was GOOD_ROD & TRUE, now BOTTLE_CAP
 	dbit TRUE  ; SUPER_ROD
 	dbit FALSE ; PP_UP

data/text/text_2.asm

@@ -1834,3 +1834,10 @@ _MysteryBoxCloseText::
 	text "<PLAYER> closed"
 	line "the BOX!"
 	prompt
+
+_CandyJarCount::
+	text "MELTAN CANDY:"
+	line "@"
+	text_bcd wCandyJarCount, 2 | LEADING_ZEROES | LEFT_ALIGN
+	text "0"
+	prompt

engine/battle/core.asm

@@ -839,6 +839,26 @@ FaintEnemyPokemon:
 	call PrintText
 	call PrintEmptyString
 	call SaveScreenTilesToBuffer1
+	
+	; Meltan Candy functionality.
+	; The way this is done looks like it conflates 8- and 16-bit integers, but it never goes above 256, so it'll be fine.
+	ld a, [wEnemyMonSpecies] ; Load species.
+	cp $E7 ; Is it Meltan?
+	jr nz, .skip ; Continue as normal if not.
+	
+	; For engine\overworld\clear_variables.asm
+	; Needed so the Mystery Box effect isn't cleared upon leaving battle.
+	ld a, $01
+	ld [wDontSwitchOffMysteryBoxYet], a
+	
+	ld a, [wCandyJarCount]
+	inc a
+	ld [wCandyJarCount], a
+	
+	ld hl, MeltanIncrement ; Load text to show it's going up.
+	call PrintText ; Yep text.
+	call PrintEmptyString ; vs text likes this.
+.skip
 	xor a
 	ld [wBattleResult], a
 	ld a, [wCurMap]
@@ -7173,3 +7193,8 @@ StupidBattleTentFix:
 	text "Oops! Better"
 	line "luck next time!"
 	prompt
+
+MeltanIncrement:
+	text "<PLAYER> found"
+	line "10 MELTAN CANDY!"
+	prompt

engine/debug/debug_party.asm

@@ -22,12 +22,11 @@ SetIshiharaTeam:
 
 IshiharaTeam:
 	db EXEGGUTOR_A, 90
-	db PURAKKUSU, 90
+	db MELTAN, 90
 	db TRAMPEL, 90
 IF DEF(_DEBUG)
 	db TAUROS_PB, 90
 	db SNORLAX, 50
-	db TANGROWTH, 50
 ENDC
 	db -1 ; end
 
@@ -162,6 +161,7 @@ DebugSetPokedexEntries:
 
 DebugItemsList:
 	db MYSTERY_BOX, 1
+	db CANDY_JAR, 1
 	db BICYCLE, 1
 	db FULL_RESTORE, 99
 	db MAX_REPEL, 99

engine/items/item_effects.asm

@@ -92,7 +92,7 @@ ItemUsePtrTable:
 	dw ItemUsePokeflute  ; POKE_FLUTE
 	dw UnusableItem      ; LIFT_KEY
 	dw UnusableItem      ; EXP_ALL
-	dw ItemUseEvoStone    ; was OLD_ROD, now CANDY_SACK
+	dw ItemUseCandyJar    ; was OLD_ROD, now CANDY_JAR
 	dw UnusableItem    ; was GOOD_ROD, now BOTTLE_CAP
 	dw ItemUseSuperRod   ; SUPER_ROD
 	dw ItemUsePPUp       ; PP_UP (real one)
@@ -138,6 +138,21 @@ ItemUseMysteryBox:
 	call PrintText
 	jp TextScriptEnd
 
+ItemUseCandyJar:
+	; Candy Jar can't be used in battle.
+	ld a, [wIsInBattle]
+	and a
+	jp nz, ItemUseNotTime
+	
+	ld [wCandyJarCount], a ; Get the Candy count
+	cp 40 ; Is it 40? (represented as 400)
+	jr z, .Evolve ; If yes, jump to Evo Stone Script
+	ld hl, CandyJarCount ; Otherwise, load the Candy total...
+	call PrintText ; and display it as text.
+	jp TextScriptEnd ; se acabo!
+.Evolve ; Evo stone script time
+	jp ItemUseEvoStone ; Jump there!
+
 ItemUseBall:
 
 ; Balls can't be used out of battle.
@@ -824,10 +839,20 @@ ItemUseEvoStone:
 	jr z, .noEffect
 	pop af
 	ld [wWhichPokemon], a
+	
+	; The Candy Jar jumps here to save space if it's capable of evolving Meltan.
+	; However, we don't want it to leave the inventory - we want it to lose the candy.
+	ld a, [wEvoStoneItemID] ; Load the item ID we just got
+	cp CANDY_JAR ; Is it the Candy Jar?
+	jr z, .zeroOutJar ; If return zero (true), save the Jar from destruction.
 	ld hl, wNumBagItems
 	ld a, 1 ; remove 1 stone
 	ld [wItemQuantity], a
 	jp RemoveItemFromInventory
+.zeroOutJar
+	ld a, $0
+	ld [wCandyJarCount], a
+	ret
 .noEffect
 	call ItemUseNoEffect
 .canceledItemUse
@@ -2998,3 +3023,7 @@ CheckMapForMon:
 MysteryBoxText:
 	text_far _MysteryBoxText
 	text_end
+
+CandyJarCount:
+	text_far _CandyJarCount
+	text_end

engine/overworld/clear_variables.asm

@@ -10,11 +10,20 @@ ClearVariablesOnEnterMap::
 	ldh [hJoyReleased], a
 	ldh [hJoyHeld], a
 	ld [wActionResultOrTookBattleTurn], a
-	ld [wMysteryBoxActive], a
 	ld hl, wCardKeyDoorY
 	ld [hli], a
 	ld [hl], a
 	ld hl, wWhichTrade
 	ld bc, wStandingOnWarpPadOrHole - wWhichTrade
 	call FillMemory
+	
+	; The Mystery Box for Meltan gets switched off when leaving every map, but SPECIFICALLY not after a battle.
+	; Because leaving battle is map re-entry, this exception is included.
+	ld a, [wDontSwitchOffMysteryBoxYet] ; Load WRAM bit.
+	and a ; Did a battle just happen?
+	jr nz, .skip ; Yes? Off you go then.
+	ld a, $0 ; No? Let's zero both of these out then.
+	ld [wMysteryBoxActive], a ; This is now deactivated.
+	ld [wDontSwitchOffMysteryBoxYet], a ; To be activated when a Meltan is defeated later.
+.skip
 	ret

ram/wram.asm

@@ -2131,7 +2131,6 @@ wObtainedHiddenCoinsFlags:: flag_array 16
 ; $01 = biking
 ; $02 = surfing
 wWalkBikeSurfState:: db
-
 	ds 10
 
 wTownVisitedFlag:: flag_array NUM_CITY_MAPS
@@ -2144,7 +2143,23 @@ wFossilItem:: db
 ; mon that will result from the item
 wFossilMon:: db
 
-	ds 2
+; Meltan WRAM entries.
+; Meltan uses a 3 unique variables for its item functionality.
+
+; This is for the Melmetal Evolution Item. 
+; If it reaches 40 (represented as 400), the player can evolve Meltan.
+; Once used, the count will reset.
+wCandyJarCount:: db
+
+; Used for Meltan implementation. Replaced unused Card Key function.
+; When byte is $01, Meltan has a chance to replace a Pokemon that appears.
+	; $00 - Not Active
+	; $01 - Active
+wMysteryBoxActive:: db
+
+; ClearVariablesOnEnterMap does everything I want, except when leaving battle, so this switches off that specific aspect.
+; This is achieved through some jank in engine\core.asm and engine\overworld\clear_variables.asm.
+wDontSwitchOffMysteryBoxYet:: db
 
 ; trainer classes start at OPP_ID_OFFSET
 wEnemyMonOrTrainerClass:: db
@@ -2152,9 +2167,7 @@ wEnemyMonOrTrainerClass:: db
 wPlayerJumpingYScreenCoordsIndex:: db
 
 wRivalStarter:: db
-
-	ds 1
-
+ds 1
 wPlayerStarter:: db
 
 ; sprite index of the boulder the player is trying to push
@@ -2177,12 +2190,6 @@ wDungeonWarpDestinationMap:: db
 ; which dungeon warp within the source map was used
 wWhichDungeonWarp:: db
 
-; Used for Meltan implementation. Replaced unused Card Key function.
-; When byte is $01, Meltan has a chance to replace a Pokemon that appears.
-	; $00 - Not Active
-	; $01 - Active
-wMysteryBoxActive:: db
-
 	ds 8
 
 ; bit 0: using Strength outside of battle