Mystery Box functionality

It was a long shot, but I did it! I added the Mystery Box from Pokemon GO! Very happy with the results here.

So here's how it works: When used, the game will replace Pokemon encountered with Meltan until the player leaves the map. This is sort of how it works in GO, with the player unable to close it and naturally petering out as they play.

Now multiple Meltan can be obtained, and in abundance, just like GO. Technically, someone could use this as a pseudo-Repel to replace hard encounters with easy ones.

Oh, and I'm pretty sure this happens vs static encounters as well, but it's awkward to account for I think that's hilarious, so...

engine/battle/core.asm

@@ -6191,6 +6191,23 @@ LoadEnemyMonData:
 	ld a, [wLinkState]
 	cp LINK_STATE_BATTLING
 	jp z, LoadEnemyMonFromParty
+	
+	; Upon initiating a battle, check if the Mystery Box has been activated.
+	; ~50% of the time, Meltan will replace what you encounter.
+	ld a, [wMysteryBoxActive] ; Load the box.
+	cp $01 ; Check if it's active.
+	jr nz, .cont ; If not, load a normal Pokemon. I know this looks sort of weird, it's just how it panned out.
+	
+	; This didn't work for some reason. It seems unnecessary, anyway...
+	;call Random
+	;and a
+	;cp 128 ; Compare Random (a) with 128 (b).
+	;jr z, .cont ; If not within range, normal Pokemon appears. 50% chance.
+	
+	ld a, MELTAN ; Meltan is loaded...
+	ld [wEnemyMonSpecies2], a ; Here!
+
+.cont ; Standard loading.
 	ld a, [wEnemyMonSpecies2]
 	ld [wEnemyMonSpecies], a
 	ld [wd0b5], a

engine/debug/debug_party.asm

@@ -161,6 +161,7 @@ DebugSetPokedexEntries:
 	ret
 
 DebugItemsList:
+	db MYSTERY_BOX, 1
 	db BICYCLE, 1
 	db FULL_RESTORE, 99
 	db MAX_REPEL, 99

engine/items/item_effects.asm

@@ -64,7 +64,7 @@ ItemUsePtrTable:
 	dw UnusableItem      ; BIKE_VOUCHER
 	dw ItemUseXAccuracy  ; X_ACCURACY
 	dw ItemUseEvoStone   ; LEAF_STONE
-	dw ItemUseCardKey    ; CARD_KEY
+	dw UnusableItem      ; CARD_KEY
 	dw UnusableItem      ; NUGGET
 	dw UnusableItem      ; WING_FOSSIL
 	dw ItemUsePokedoll   ; POKE_DOLL
@@ -109,6 +109,7 @@ ItemUsePtrTable:
 	dw UnusableItem      ; OLD_SEA_MAP
 	dw ItemUseEvoStone   ; UP_GRADE
 	dw ItemUseEvoStone   ; METAL_COAT
+	dw ItemUseMysteryBox ; MYSTERY_BOX
 	dw UnusableItem      ; FLOOR_B2F
 	dw UnusableItem      ; FLOOR_B1F
     dw UnusableItem      ; FLOOR_1F
@@ -124,6 +125,19 @@ ItemUsePtrTable:
 	dw UnusableItem      ; FLOOR_11F
 	dw UnusableItem      ; FLOOR_14F
 
+ItemUseMysteryBox:
+	; Mystery Box can't be used in battle.
+	ld a, [wIsInBattle]
+	and a
+	jp nz, ItemUseNotTime
+	; Sets a variable in WRAM that'll trigger a Meltan wild encounter.
+	; Handled in engine\core.asm
+	ld a, $1
+	ld [wMysteryBoxActive], a
+	ld hl, MysteryBoxText ; Simple text is shown. Ambiguous to the user, identical to GO.
+	call PrintText
+	jp TextScriptEnd
+
 ItemUseBall:
 
 ; Balls can't be used out of battle.
@@ -1585,55 +1599,55 @@ ItemUseXAccuracy:
 
 ; This function is bugged and never works. It always jumps to ItemUseNotTime.
 ; The Card Key is handled in a different way.
-ItemUseCardKey:
-	xor a
-	ld [wUnusedD71F], a
-	call GetTileAndCoordsInFrontOfPlayer
-	ld a, [GetTileAndCoordsInFrontOfPlayer]
-	cp $18
-	jr nz, .next0
-	ld hl, CardKeyTable1
-	jr .next1
-.next0
-	cp $24
-	jr nz, .next2
-	ld hl, CardKeyTable2
-	jr .next1
-.next2
-	cp $5e
-	jp nz, ItemUseNotTime
-	ld hl, CardKeyTable3
-.next1
-	ld a, [wCurMap]
-	ld b, a
-.loop
-	ld a, [hli]
-	cp -1
-	jp z, ItemUseNotTime
-	cp b
-	jr nz, .nextEntry1
-	ld a, [hli]
-	cp d
-	jr nz, .nextEntry2
-	ld a, [hli]
-	cp e
-	jr nz, .nextEntry3
-	ld a, [hl]
-	ld [wUnusedD71F], a
-	jr .done
-.nextEntry1
-	inc hl
-.nextEntry2
-	inc hl
-.nextEntry3
-	inc hl
-	jr .loop
-.done
-	ld hl, ItemUseText00
-	call PrintText
-	ld hl, wd728
-	set 7, [hl]
-	ret
+;ItemUseCardKey:
+;	xor a
+;	ld [wUnusedD71F], a
+;	call GetTileAndCoordsInFrontOfPlayer
+;	ld a, [GetTileAndCoordsInFrontOfPlayer]
+;	cp $18
+;	jr nz, .next0
+;	ld hl, CardKeyTable1
+;	jr .next1
+;.next0
+;	cp $24
+;	jr nz, .next2
+;	ld hl, CardKeyTable2
+;	jr .next1
+;.next2
+;	cp $5e
+;	jp nz, ItemUseNotTime
+;	ld hl, CardKeyTable3
+;.next1
+;	ld a, [wCurMap]
+;	ld b, a
+;.loop
+;	ld a, [hli]
+;	cp -1
+;	jp z, ItemUseNotTime
+;	cp b
+;	jr nz, .nextEntry1
+;	ld a, [hli]
+;	cp d
+;	jr nz, .nextEntry2
+;	ld a, [hli]
+;	cp e
+;	jr nz, .nextEntry3
+;	ld a, [hl]
+;	ld [wUnusedD71F], a
+;	jr .done
+;.nextEntry1
+;	inc hl
+;.nextEntry2
+;	inc hl
+;.nextEntry3
+;	inc hl
+;	jr .loop
+;.done
+;	ld hl, ItemUseText00
+;	call PrintText
+;	ld hl, wd728
+;	set 7, [hl]
+;	ret
 
 INCLUDE "data/events/card_key_coords.asm"
 
@@ -2980,3 +2994,7 @@ CheckMapForMon:
 	jr nz, .loop
 	dec hl
 	ret
+
+MysteryBoxText:
+	text_far _MysteryBoxText
+	text_end

engine/menus/item_descriptions.asm

@@ -198,6 +198,8 @@ ItemDescriptionPointers:
 	text_end
 	text_far _MetalCoatDescription
 	text_end
+	text_far _MysteryBoxDescription
+	text_end
 	text_far _HM01Description
 	text_end
 	text_far _HM02Description

engine/overworld/clear_variables.asm

@@ -10,7 +10,7 @@ ClearVariablesOnEnterMap::
 	ldh [hJoyReleased], a
 	ldh [hJoyHeld], a
 	ld [wActionResultOrTookBattleTurn], a
-	ld [wUnusedD5A3], a
+	ld [wMysteryBoxActive], a
 	ld hl, wCardKeyDoorY
 	ld [hli], a
 	ld [hl], a