Merge master into doc-tower

3 files changed, 50 insertions, 39 deletions

diff --git a/asm/macros/battle_frontier/battle_factory.inc b/asm/macros/battle_frontier/battle_factory.inc
index 5a1eb33b7..684eeb98d 100644
--- a/asm/macros/battle_frontier/battle_factory.inc
+++ b/asm/macros/battle_frontier/battle_factory.inc
@@ -1,5 +1,3 @@
-@ TODO: Add explanatory comments to macros
-
 	@ Initialize the Battle Factory challenge
 	.macro factory_init
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_INIT
@@ -34,68 +32,68 @@
 	special CallBattleFactoryFunction
 	.endm
 
-	@  
+	@ Select the initial rental mons for the challenge
 	.macro factory_rentmons
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SELECT_RENT_MONS
 	special CallBattleFactoryFunction
 	.endm
 
-	@ 
+	@ Select a mon to swap for from the previously defeated team
 	.macro factory_swapmons
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SWAP_RENT_MONS
 	special CallBattleFactoryFunction
 	.endm
 
-	@
+	@ Allows FACTORY_DATA_WIN_STREAK_SWAPS to be incremented once
 	.macro factory_setswapped
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_SWAPPED
 	special CallBattleFactoryFunction
 	.endm
 
-	@ 
+	@ Update gEnemyParty with the next set of rental mons
 	.macro factory_setopponentmons
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_OPPONENT_MONS
 	special CallBattleFactoryFunction
 	.endm
 
-	@ 
+	@ Populate gPlayerParty and gEnemyParty with the rental mons. Only needed when resuming a challenge, otherwise only factory_setopponentmons and factory_rentmons/factory_swapmons are needed
 	.macro factory_setparties arg:req
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_PARTIES
 	setvar VAR_0x8005, \arg
 	special CallBattleFactoryFunction
 	.endm
 
-	@ 
+	@ Set the object event gfx for the opponent trainer
 	.macro factory_setopponentgfx
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_SET_OPPONENT_GFX
 	special CallBattleFactoryFunction
 	.endm
 
-	@  
+	@ Generate the mons for the opponents team
 	.macro factory_generateopponentmons
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GENERATE_OPPONENT_MONS
 	special CallBattleFactoryFunction
 	.endm
 
-	@  
+	@ Generate the random 6 mons to choose from for the initial rental
 	.macro factory_generaterentalmons
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GENERATE_RENTAL_MONS
 	special CallBattleFactoryFunction
 	.endm
 
-	@  
+	@ Return the pokemon type most common in the opponents team, or NUMBER_OF_MON_TYPES if there is no standout type
 	.macro factory_getopponentmontype
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_OPPONENT_MON_TYPE
 	special CallBattleFactoryFunction
 	.endm
 
-	@ 
+	@ Return the FACTORY_STYLE_* dependent on what types of moves the opponents team has, or FACTORY_NUM_STYLES if multiple styles tie for the same amount of moves
 	.macro factory_getopponentstyle 
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_GET_OPPONENT_STYLE
 	special CallBattleFactoryFunction
 	.endm
 
-	@  
+	@ Restore the held items for the players party to what they were pre-battle
 	.macro factory_resethelditems
 	setvar VAR_0x8004, BATTLE_FACTORY_FUNC_RESET_HELD_ITEMS
 	special CallBattleFactoryFunction
diff --git a/asm/macros/battle_frontier/battle_pyramid.inc b/asm/macros/battle_frontier/battle_pyramid.inc
index 0468e5956..f8141e2dd 100644
--- a/asm/macros/battle_frontier/battle_pyramid.inc
+++ b/asm/macros/battle_frontier/battle_pyramid.inc
@@ -1,5 +1,3 @@
-@ TODO: Add explanatory comments to macros
-
 	@ Initialize the Battle Pyramid challenge
 	.macro pyramid_init
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_INIT
@@ -28,37 +26,43 @@
 	special CallBattlePyramidFunction
 	.endm
 
-	@
+	@ Set the prize item to give from one of two lists of possible prizes, depending on streak.
 	.macro pyramid_setprize
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_PRIZE
 	special CallBattlePyramidFunction
 	.endm
 
-	@  
+	@ Unused. Give the set prize item to the player. TRUE if room in Bag for prize, FALSE otherwise
+	.macro pyramid_giveprize
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_GIVE_PRIZE
+	special CallBattlePyramidFunction
+	.endm
+
+	@ Set the random values for the floor (used to determine object positions, e.g.), and clear trainer flags
 	.macro pyramid_seedfloor
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SEED_FLOOR
 	special CallBattlePyramidFunction
 	.endm
 
-	@   
+	@ Set the item to pick up depending on the random seed and quantity (always 1) to the arguments for STD_FIND_ITEM
 	.macro pyramid_setitem
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_ITEM
 	special CallBattlePyramidFunction
 	.endm
 
-	@  
+	@ Hide the picked-up item (technically it moves the item far offscreen)
 	.macro pyramid_hideitem
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_HIDE_ITEM
 	special CallBattlePyramidFunction
 	.endm
 
-	@ 
-	.macro pyramid_inittrainers
-	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_INIT_TRAINERS
+	@ Set the facility trainers to gBattleFrontierTrainers
+	.macro pyramid_settrainers
+	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_TRAINERS
 	special CallBattlePyramidFunction 
 	.endm
 
-	@  
+	@ Show the post-battle hint text
 	.macro pyramid_showhint
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SHOW_HINT_TEXT
 	special CallBattlePyramidFunction
@@ -70,28 +74,31 @@
 	special CallBattlePyramidFunction
 	.endm   
 
-	@  
-	.macro pyramid_updatelight radius:req, mode:req
+	@ Update the light around the player. 2 different modes, for setting or incrementing light. See PYRAMID_LIGHT_*
+	.macro pyramid_updatelight radius:req, mode:req, sound=0xFFFF
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_UPDATE_LIGHT
 	setvar VAR_0x8005, \radius
 	setvar VAR_0x8006, \mode
+	.if \sound != 0xFFFF
+	setvar VAR_0x8007, \sound
+	.endif
 	special CallBattlePyramidFunction
 	.endm  
 
-	@  
+	@ Reset the held items to what they were at the start of the challenge
 	.macro pyramid_clearhelditems
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_CLEAR_HELD_ITEMS
 	special CallBattlePyramidFunction
 	.endm
 
-	@  
+	@ Set the palette depending on current floor number
 	.macro pyramid_setfloorpal
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_SET_FLOOR_PALETTE
 	special CallBattlePyramidFunction
 	.endm
 
-	@
-	.macro pyramid_healparty
+	@ Reset sketched moves and update the party order in the saveblock
+	.macro pyramid_resetparty
 	setvar VAR_0x8004, BATTLE_PYRAMID_FUNC_RESTORE_PARTY
 	special CallBattlePyramidFunction 
 	.endm
diff --git a/asm/macros/event.inc b/asm/macros/event.inc
index 9db57daf1..8b43d0821 100644
--- a/asm/macros/event.inc
+++ b/asm/macros/event.inc
@@ -1101,16 +1101,16 @@
 	.2byte \index
 	.endm
 
-	@ Fades the screen to and from black and white. Mode 0x00 fades from black, mode 0x01 fades out to black, mode 0x2 fades in from white, and mode 0x3 fades out to white.
-	.macro fadescreen effect:req
+	@ Fades the screen to and from black and white. Modes are FADE_(TO/FROM)_(WHITE/BLACK)
+	.macro fadescreen mode:req
 	.byte 0x97
-	.byte \effect
+	.byte \mode
 	.endm
 
-	@ Fades the screen to and from black and white. Mode 0x00 fades from black, mode 0x01 fades out to black, mode 0x2 fades in from white, and mode 0x3 fades out to white. Other modes may exist.
-	.macro fadescreenspeed effect:req, speed:req
+	@ Fades the screen to and from black and white. Modes are FADE_(TO/FROM)_(WHITE/BLACK)
+	.macro fadescreenspeed mode:req, speed:req
 	.byte 0x98
-	.byte \effect
+	.byte \mode
 	.byte \speed
 	.endm
 
@@ -1517,9 +1517,9 @@
 	.4byte \pointer
 	.endm
 
-	.macro fadescreenswapbuffers byte:req
+	.macro fadescreenswapbuffers mode:req
 	.byte 0xdc
-	.byte \byte
+	.byte \mode
 	.endm
 
 	.macro buffertrainerclassname out:req, class:req
@@ -1665,10 +1665,16 @@
 	callstd \type
 	.endm
 
-	.macro giveitem_std item:req, amount=1, function=0
+	.macro giveitem_std item:req, amount=1
+	setorcopyvar VAR_0x8000, \item
+	setorcopyvar VAR_0x8001, \amount
+	callstd STD_OBTAIN_ITEM
+	.endm
+
+	.macro finditem_std item:req, amount=1
 	setorcopyvar VAR_0x8000, \item
 	setorcopyvar VAR_0x8001, \amount
-	callstd \function
+	callstd STD_FIND_ITEM
 	.endm
 
 	.macro givedecoration_std decoration:req