Document constants with comments, actual names, and more thorough usage

battle/ai/items.asm

@@ -27,7 +27,7 @@ AI_SwitchOrTryItem: ; 38000
 
 	ld a, [TrainerClass]
 	dec a
-	ld bc, 7
+	ld bc, NUM_TRAINER_ATTRIBUTES
 	call AddNTimes
 .ok
 	bit SWITCH_OFTEN_F, [hl]
@@ -174,8 +174,8 @@ AI_TryItem: ; 38105
 
 	ld a, [TrainerClass]
 	dec a
-	ld hl, TrainerClassAttributes + 5
+	ld hl, TrainerClassAttributes + TRNATTR_AI_ITEM_SWITCH
-	ld bc, 7
+	ld bc, NUM_TRAINER_ATTRIBUTES
 	call AddNTimes
 	ld b, h
 	ld c, l

constants/animation_constants.asm

@@ -1,3 +1,4 @@
+; battle_anim_struct members (see macros/wram.asm)
 	const_def
 	const BATTLEANIMSTRUCT_INDEX
 	const BATTLEANIMSTRUCT_01
@@ -25,6 +26,7 @@
 	const BATTLEANIMSTRUCT_17
 BATTLEANIMSTRUCT_LENGTH EQU const_value
 
+; BattleAnimObjects indexes (see battle/objects/data.asm)
 	const_def
 	const ANIM_OBJ_00
 	const ANIM_OBJ_01
@@ -215,6 +217,7 @@ BATTLEANIMSTRUCT_LENGTH EQU const_value
 	const ANIM_OBJ_BA
 	const ANIM_OBJ_BB
 
+; DoBattleAnimFrame arguments (see battle/objects/functions.asm)
 	const_def
 	const BATTLEANIMFUNC_00
 	const BATTLEANIMFUNC_01
@@ -297,6 +300,7 @@ BATTLEANIMSTRUCT_LENGTH EQU const_value
 	const BATTLEANIMFUNC_4E
 	const BATTLEANIMFUNC_4F
 
+; BattleAnimFrameData indexes (see battle/objects/framesets.asm)
 	const_def
 	const BATTLEANIMFRAMESET_00
 	const BATTLEANIMFRAMESET_01
@@ -484,6 +488,7 @@ BATTLEANIMSTRUCT_LENGTH EQU const_value
 	const BATTLEANIMFRAMESET_B7
 	const BATTLEANIMFRAMESET_B8
 
+; BattleAnimOAMData indexes (see battle/objects/oam.asm)
 	const_def
 	const BATTLEANIMOAMSET_00
 	const BATTLEANIMOAMSET_01
@@ -702,6 +707,7 @@ BATTLEANIMSTRUCT_LENGTH EQU const_value
 	const BATTLEANIMOAMSET_D6
 	const BATTLEANIMOAMSET_D7
 
+; BattleBGEffects indexes (see battle/bg_effects.asm)
 const_value SET 1
 	const ANIM_BG_FLASH_INVERTED
 	const ANIM_BG_FLASH_WHITE
@@ -757,17 +763,19 @@ const_value SET 1
 	const ANIM_BG_WOBBLE_MON
 	const ANIM_BG_35
 
+; PokeAnims indexes (see gfx/pics/animation.asm)
 	const_def
-	const ANIM_MON_SLOW    ; 0
+	const ANIM_MON_SLOW
-	const ANIM_MON_NORMAL  ; 1
+	const ANIM_MON_NORMAL
-	const ANIM_MON_MENU    ; 2
+	const ANIM_MON_MENU
-	const ANIM_MON_TRADE   ; 3
+	const ANIM_MON_TRADE
-	const ANIM_MON_EVOLVE  ; 4
+	const ANIM_MON_EVOLVE
-	const ANIM_MON_HATCH   ; 5
+	const ANIM_MON_HATCH
-	const ANIM_MON_UNUSED  ; 6
+	const ANIM_MON_UNUSED
-	const ANIM_MON_EGG1    ; 7
+	const ANIM_MON_EGG1
-	const ANIM_MON_EGG2    ; 8
+	const ANIM_MON_EGG2
 
+; AnimObjGFX indexes (see battle/objects/gfx_headers.asm)
 const_value SET 1
 	const ANIM_GFX_HIT
 	const ANIM_GFX_CUT
@@ -809,6 +817,7 @@ const_value SET 1
 	const ANIM_GFX_WAVE
 	const ANIM_GFX_AEROBLAST
 
+; battle_bg_effect struct members (see macros/wram.asm)
 	const_def
 	const BG_EFFECT_STRUCT_FUNCTION
 	const BG_EFFECT_STRUCT_JT_INDEX

constants/audio_constants.asm

@@ -1,5 +1,3 @@
-
-
 ; pitch
 	const_def
 	const __
@@ -40,7 +38,6 @@ SOUND_NOISE EQU 4
 SOUND_REST EQU 5
 
 ; Flags2
-
 SOUND_VIBRATO EQU 0
 SOUND_PITCH_WHEEL EQU 1
 SOUND_DUTY EQU 2

constants/battle_constants.asm

@@ -1,12 +1,20 @@
+; significant level values
 MAX_LEVEL EQU 100
 MIN_LEVEL EQU 2
 EGG_LEVEL EQU 5
+
+; maximum moves known per mon
 NUM_MOVES EQU 4
 
-REST_TURNS EQU 2
+; significant stat values
-MAX_STAT_LEVEL EQU 13
 BASE_STAT_LEVEL EQU 7
+MAX_STAT_LEVEL EQU 13
 
+; turns that Rest sleep lasts
+REST_TURNS EQU 2
+
+; PlayerStatLevels and EnemyStatLevels indexes
+; used for GetStatName
 	const_def
 	const ATTACK
 	const DEFENSE
@@ -15,10 +23,10 @@ BASE_STAT_LEVEL EQU 7
 	const SP_DEFENSE
 	const ACCURACY
 	const EVASION
-	const ABILITY
+	const ABILITY ; used for BattleCommand_Curse
 NUM_LEVEL_STATS EQU const_value
 
-; move struct
+; move struct members (see battle/moves/moves.asm)
 	const_def
 	const MOVE_ANIM
 	const MOVE_EFFECT
@@ -30,6 +38,9 @@ NUM_LEVEL_STATS EQU const_value
 	const MOVE_LENGTH
 
 ; stat constants
+; indexes for:
+; - PlayerStats and EnemyStats (see wram.asm)
+; - party_struct and battle_struct members (see macros/wram.asm)
 const_value SET 1
 	const STAT_HP
 	const STAT_ATK
@@ -38,6 +49,8 @@ const_value SET 1
 	const STAT_SATK
 	const STAT_SDEF
 NUM_STATS EQU const_value
+
+; stat formula constants
 STAT_MIN_NORMAL EQU 5
 STAT_MIN_HP EQU 10
 
@@ -45,12 +58,12 @@ STAT_MIN_HP EQU 10
 ATKDEFDV_SHINY EQU $EA
 SPDSPCDV_SHINY EQU $AA
 
-; battle classes
+; battle classes (wBattleMode values)
 const_value SET 1
 	const WILD_BATTLE
 	const TRAINER_BATTLE
 
-; battle types
+; battle types (BattleType values)
 	const_def
 	const BATTLETYPE_NORMAL
 	const BATTLETYPE_CANLOSE
@@ -66,7 +79,7 @@ const_value SET 1
 	const BATTLETYPE_CELEBI
 	const BATTLETYPE_SUICUNE
 
-; battle variables
+; GetBattleVar and GetBattleVarAddr arguments (see home/battle.asm)
 	const_def
 	const BATTLE_VARS_SUBSTATUS1
 	const BATTLE_VARS_SUBSTATUS2
@@ -90,8 +103,37 @@ const_value SET 1
 	const BATTLE_VARS_LAST_MOVE
 	const BATTLE_VARS_LAST_MOVE_OPP
 
-; status
+; GetBattleVar and GetBattleVarAddr internal indexes (see home/battle.asm)
-SLP EQU 7 ; 0-7 turns
+	const_def
+	const PLAYER_SUBSTATUS_1
+	const ENEMY_SUBSTATUS_1
+	const PLAYER_SUBSTATUS_2
+	const ENEMY_SUBSTATUS_2
+	const PLAYER_SUBSTATUS_3
+	const ENEMY_SUBSTATUS_3
+	const PLAYER_SUBSTATUS_4
+	const ENEMY_SUBSTATUS_4
+	const PLAYER_SUBSTATUS_5
+	const ENEMY_SUBSTATUS_5
+	const PLAYER_STATUS
+	const ENEMY_STATUS
+	const PLAYER_MOVE_ANIMATION
+	const ENEMY_MOVE_ANIMATION
+	const PLAYER_MOVE_EFFECT
+	const ENEMY_MOVE_EFFECT
+	const PLAYER_MOVE_POWER
+	const ENEMY_MOVE_POWER
+	const PLAYER_MOVE_TYPE
+	const ENEMY_MOVE_TYPE
+	const PLAYER_CUR_MOVE
+	const ENEMY_CUR_MOVE
+	const PLAYER_COUNTER_MOVE
+	const ENEMY_COUNTER_MOVE
+	const PLAYER_LAST_MOVE
+	const ENEMY_LAST_MOVE
+
+; status condition bit flags
+SLP EQU %111 ; 0-7 turns
 const_value SET 3
 	const PSN
 	const BRN
@@ -100,7 +142,7 @@ const_value SET 3
 
 ALL_STATUS EQU (1 << PSN) + (1 << BRN) + (1 << FRZ) + (1 << PAR) + SLP
 
-; substatus
+; PlayerSubStatus1 or EnemySubStatus1 bit flags
 	enum_start 7, -1
 	enum SUBSTATUS_IN_LOVE
 	enum SUBSTATUS_ROLLOUT
@@ -111,8 +153,10 @@ ALL_STATUS EQU (1 << PSN) + (1 << BRN) + (1 << FRZ) + (1 << PAR) + SLP
 	enum SUBSTATUS_CURSE
 	enum SUBSTATUS_NIGHTMARE
 
-SUBSTATUS_CURLED       EQU 0
+; PlayerSubStatus2 or EnemySubStatus2 bit flags
+SUBSTATUS_CURLED EQU 0
 
+; PlayerSubStatus3 or EnemySubStatus3 bit flags
 	enum_start 7, -1
 	enum SUBSTATUS_CONFUSED
 	enum SUBSTATUS_FLYING
@@ -123,6 +167,7 @@ SUBSTATUS_CURLED       EQU 0
 	enum SUBSTATUS_RAMPAGE
 	enum SUBSTATUS_BIDE
 
+; PlayerSubStatus4 or EnemySubStatus4 bit flags
 	enum_start 7, -1
 	enum SUBSTATUS_LEECH_SEED
 	enum SUBSTATUS_RAGE
@@ -133,6 +178,7 @@ SUBSTATUS_CURLED       EQU 0
 	enum SUBSTATUS_MIST
 	enum SUBSTATUS_X_ACCURACY
 
+; PlayerSubStatus5 or EnemySubStatus5 bit flags
 	enum_start 7, -1
 	enum SUBSTATUS_CANT_RUN
 	enum SUBSTATUS_DESTINY_BOND
@@ -143,7 +189,7 @@ SUBSTATUS_CURLED       EQU 0
 	enum SUBSTATUS_UNKNOWN_3
 	enum SUBSTATUS_TOXIC
 
-; environmental
+; PlayerScreens or EnemyScreens bit flags
 	enum_start 4, -1
 	enum SCREENS_REFLECT
 	enum SCREENS_LIGHT_SCREEN
@@ -151,7 +197,7 @@ SUBSTATUS_CURLED       EQU 0
 	enum SCREENS_UNUSED
 	enum SCREENS_SPIKES
 
-; weather
+; Weather values
 	const_def
 	const WEATHER_NONE
 	const WEATHER_RAIN
@@ -161,8 +207,7 @@ SUBSTATUS_CURLED       EQU 0
 	const WEATHER_SUN_END
 	const WEATHER_SANDSTORM_END
 
-
+; MoveEffectsPointers indexes (see battle/moves/move_effects_pointers.asm)
-; move effects
 	const_def
 	const EFFECT_NORMAL_HIT
 	const EFFECT_SLEEP
@@ -322,35 +367,6 @@ SUBSTATUS_CURLED       EQU 0
 	const EFFECT_FLY
 	const EFFECT_DEFENSE_CURL
 
-; Battle vars used in home/battle.asm
-	const_def
-	const PLAYER_SUBSTATUS_1
-	const ENEMY_SUBSTATUS_1
-	const PLAYER_SUBSTATUS_2
-	const ENEMY_SUBSTATUS_2
-	const PLAYER_SUBSTATUS_3
-	const ENEMY_SUBSTATUS_3
-	const PLAYER_SUBSTATUS_4
-	const ENEMY_SUBSTATUS_4
-	const PLAYER_SUBSTATUS_5
-	const ENEMY_SUBSTATUS_5
-	const PLAYER_STATUS
-	const ENEMY_STATUS
-	const PLAYER_MOVE_ANIMATION
-	const ENEMY_MOVE_ANIMATION
-	const PLAYER_MOVE_EFFECT
-	const ENEMY_MOVE_EFFECT
-	const PLAYER_MOVE_POWER
-	const ENEMY_MOVE_POWER
-	const PLAYER_MOVE_TYPE
-	const ENEMY_MOVE_TYPE
-	const PLAYER_CUR_MOVE
-	const ENEMY_CUR_MOVE
-	const PLAYER_COUNTER_MOVE
-	const ENEMY_COUNTER_MOVE
-	const PLAYER_LAST_MOVE
-	const ENEMY_LAST_MOVE
-
 ; wBattleAction
 	const_def
 	const BATTLEACTION_MOVE1
@@ -370,6 +386,7 @@ SUBSTATUS_CURLED       EQU 0
 	const BATTLEACTION_E
 	const BATTLEACTION_FORFEIT
 
+; wBattleResult
 	const_def
 	const WIN
 	const LOSE

constants/battle_tower_constants.asm

@@ -1,3 +1,4 @@
+; BattleTowerAction arguments (see misc/battle_tower_5c.asm)
 	const_def
 	const BATTLETOWERACTION_CHECK_EXPLANATION_READ
 	const BATTLETOWERACTION_SET_EXPLANATION_READ
@@ -32,8 +33,19 @@
 	const BATTLETOWERACTION_CHOOSEREWARD ; save options
 	const BATTLETOWERACTION_SAVEOPTIONS
 
-BATTLETOWER_NO_CHALLENGE         EQU 0
+; sBattleTowerChallengeState
-BATTLETOWER_SAVED_AND_LEFT       EQU 1
+	const_def
-BATTLETOWER_CHALLENGE_IN_PROGESS EQU 2
+	const BATTLETOWER_NO_CHALLENGE
-BATTLETOWER_WON_CHALLENGE        EQU 3
+	const BATTLETOWER_SAVED_AND_LEFT
-BATTLETOWER_RECEIVED_REWARD      EQU 4
+	const BATTLETOWER_CHALLENGE_IN_PROGESS
+	const BATTLETOWER_WON_CHALLENGE
+	const BATTLETOWER_RECEIVED_REWARD
+
+BATTLETOWER_NROFPKMNS EQU 3
+BATTLETOWER_TRAINERDATALENGTH EQU $24
+BATTLETOWER_NROFTRAINERS EQU 7
+BATTLETOWER_NRMONSPERLEVELBRACKET EQU BATTLETOWER_NROFPKMNS * BATTLETOWER_NROFTRAINERS
+BATTLE_TOWER_STRUCT_LENGTH EQU $e0 ; NAME_LENGTH + 3 * (PARTYMON_STRUCT_LENGTH + PKMN_NAME_LENGTH) + BATTLETOWER_TRAINERDATALENGTH
+
+; return value from BattleTowerAction(BATTLETOWERACTION_CHECKMOBILEEVENT)
+MOBILE_EVENT_OBJECT_GS_BALL EQU $b

constants/cgb_constants.asm

@@ -1,3 +1,4 @@
+; GetSGBLayout arguments (see predef/cgb.asm and predef/sgb.asm)
 	const_def
 	const SCGB_BATTLE_GRAYSCALE
 	const SCGB_BATTLE_COLORS

constants/cry_constants.asm

@@ -1,3 +1,4 @@
+; Cries indexes (see audio/cry_pointers.asm)
 	const_def
 
 ; gen 1

constants/deco_constants.asm

@@ -1,3 +1,4 @@
+; decoration types
 const_value = 1
 	const DECO_PLANT
 	const DECO_BED
@@ -6,6 +7,7 @@ const_value = 1
 	const DECO_DOLL
 	const DECO_BIGDOLL
 
+; DecorationNames indexes (see engine/decorations.asm)
 const_value = 1
 	const PUT_IT_AWAY
 	const MAGNAPLANT
@@ -33,6 +35,7 @@ const_value = 1
 	const YELLOW_CARPET
 	const GREEN_CARPET
 
+; DoDecorationAction2 arguments (see engine/decorations.asm)
 const_value = 1
 	const SET_UP_BED
 	const PUT_AWAY_BED
@@ -56,66 +59,67 @@ deco: MACRO
 	enum DECOFLAG_\1
 endm
 
+; decorations
 const_value = 1
 __enum__ = 0
 	const BEDS
-	deco  FEATHERY_BED ; 2 (0)
+	deco  FEATHERY_BED
-	deco  PINK_BED ; 3 (1)
+	deco  PINK_BED
-	deco  POLKADOT_BED ; 4 (2)
+	deco  POLKADOT_BED
-	deco  PIKACHU_BED ; 5 (3)
+	deco  PIKACHU_BED
 
 	const CARPETS
-	deco  RED_CARPET ; 7 (4)
+	deco  RED_CARPET
-	deco  BLUE_CARPET ; 8 (5)
+	deco  BLUE_CARPET
-	deco  YELLOW_CARPET ; 9 (6)
+	deco  YELLOW_CARPET
-	deco  GREEN_CARPET ; a (7)
+	deco  GREEN_CARPET
 
 	const PLANTS
-	deco  MAGNAPLANT ; c (8)
+	deco  MAGNAPLANT
-	deco  TROPICPLANT ; d (9)
+	deco  TROPICPLANT
-	deco  JUMBOPLANT ; e (a)
+	deco  JUMBOPLANT
 
 	const POSTERS
-	deco  TOWN_MAP ; 10 (b)
+	deco  TOWN_MAP
-	deco  PIKACHU_POSTER ; 11 (c)
+	deco  PIKACHU_POSTER
-	deco  CLEFAIRY_POSTER ; 12 (d)
+	deco  CLEFAIRY_POSTER
-	deco  JIGGLYPUFF_POSTER ; 13(e)
+	deco  JIGGLYPUFF_POSTER
 
 	const CONSOLES
-	deco  FAMICOM ; 15 (f)
+	deco  FAMICOM
-	deco  SNES ; 16 (10)
+	deco  SNES
-	deco  N64 ; 17 (11)
+	deco  N64
-	deco  VIRTUAL_BOY ; 18 (12)
+	deco  VIRTUAL_BOY
 
 	const BIG_DOLLS
-	deco  BIG_SNORLAX_DOLL ; 1a (13)
+	deco  BIG_SNORLAX_DOLL
-	deco  BIG_ONIX_DOLL ; 1b (14)
+	deco  BIG_ONIX_DOLL
-	deco  BIG_LAPRAS_DOLL ; 1c (15)
+	deco  BIG_LAPRAS_DOLL
 
 	const DOLLS
-	deco  PIKACHU_DOLL ; 1e (16)
+	deco  PIKACHU_DOLL
-	deco  SURF_PIKACHU_DOLL ; 1f (17)
+	deco  SURF_PIKACHU_DOLL
-	deco  CLEFAIRY_DOLL ; 20 (18)
+	deco  CLEFAIRY_DOLL
-	deco  JIGGLYPUFF_DOLL ; 21 (19)
+	deco  JIGGLYPUFF_DOLL
-	deco  BULBASAUR_DOLL ; 22 (1a)
+	deco  BULBASAUR_DOLL
-	deco  CHARMANDER_DOLL ; 23 (1b)
+	deco  CHARMANDER_DOLL
-	deco  SQUIRTLE_DOLL ; 24 (1c)
+	deco  SQUIRTLE_DOLL
-	deco  POLIWAG_DOLL ; 25 (1d)
+	deco  POLIWAG_DOLL
-	deco  DIGLETT_DOLL ; 26 (1e)
+	deco  DIGLETT_DOLL
-	deco  STARMIE_DOLL ; 27 (1f)
+	deco  STARMIE_DOLL
-	deco  MAGIKARP_DOLL ; 28 (20)
+	deco  MAGIKARP_DOLL
-	deco  ODDISH_DOLL ; 29 (21)
+	deco  ODDISH_DOLL
-	deco  GENGAR_DOLL ; 2a (22)
+	deco  GENGAR_DOLL
-	deco  SHELLDER_DOLL ; 2b (23)
+	deco  SHELLDER_DOLL
-	deco  GRIMER_DOLL ; 2c (24)
+	deco  GRIMER_DOLL
-	deco  VOLTORB_DOLL ; 2d (25)
+	deco  VOLTORB_DOLL
-	deco  WEEDLE_DOLL ; 2e (26)
+	deco  WEEDLE_DOLL
-	deco  UNOWN_DOLL ; 2f (27)
+	deco  UNOWN_DOLL
-	deco  GEODUDE_DOLL ; 30 (28)
+	deco  GEODUDE_DOLL
-	deco  MACHOP_DOLL ; 31 (29)
+	deco  MACHOP_DOLL
-	deco  TENTACOOL_DOLL ; 32 (2a)
+	deco  TENTACOOL_DOLL
-	deco  GOLD_TROPHY_DOLL ; 33 (2b)
+	deco  GOLD_TROPHY_DOLL
-	deco  SILVER_TROPHY_DOLL ; 34 (2c)
+	deco  SILVER_TROPHY_DOLL
 
-NUM_NON_TROPHY_DECOS EQU $2b
+NUM_DECOS = __enum__
-NUM_DECOS EQU $2d
+NUM_NON_TROPHY_DECOS = NUM_DECOS +- 2

constants/engine_flags.asm

@@ -1,22 +1,29 @@
+; EngineFlags indexes (see engine/engine_flasg.asm)
 	const_def
-
+; wPokegearFlags
 	const ENGINE_RADIO_CARD
 	const ENGINE_MAP_CARD
 	const ENGINE_PHONE_CARD
 	const ENGINE_EXPN_CARD
 	const ENGINE_POKEGEAR
+; wDaycareMan
 	const ENGINE_DAYCARE_MAN_HAS_EGG
 	const ENGINE_DAYCARE_MAN_HAS_MON
+; wDaycareLady
 	const ENGINE_DAYCARE_LADY_HAS_MON
+; wMomSavingMoney
 	const ENGINE_MOM_SAVING_MONEY
 	const ENGINE_DST
+; wUnusedTwoDayTimerOn
 	const ENGINE_0A
+; StatusFlags
 	const ENGINE_POKEDEX
 	const ENGINE_UNOWN_DEX
 	const ENGINE_POKERUS
 	const ENGINE_ROCKET_SIGNAL_ON_CH20
 	const ENGINE_CREDITS_SKIP
 	const ENGINE_BUG_CONTEST_ON ; 10
+; StatusFlags2
 	const ENGINE_BUG_CONTEST_TIMER
 	const ENGINE_SAFARI_ZONE
 	const ENGINE_ROCKETS_IN_RADIO_TOWER
@@ -24,9 +31,11 @@
 	const ENGINE_GIVE_POKERUS
 	const ENGINE_FLORIA
 	const ENGINE_ROCKETS_IN_MAHOGANY
+; BikeFlags
 	const ENGINE_STRENGTH_ACTIVE
 	const ENGINE_ALWAYS_ON_BIKE
 	const ENGINE_DOWNHILL
+; JohtoBadges
 	const ENGINE_ZEPHYRBADGE
 	const ENGINE_HIVEBADGE
 	const ENGINE_PLAINBADGE
@@ -35,6 +44,7 @@
 	const ENGINE_STORMBADGE ; 20
 	const ENGINE_GLACIERBADGE
 	const ENGINE_RISINGBADGE
+; KantoBadges
 	const ENGINE_BOULDERBADGE
 	const ENGINE_CASCADEBADGE
 	const ENGINE_THUNDERBADGE
@@ -43,6 +53,7 @@
 	const ENGINE_MARSHBADGE
 	const ENGINE_VOLCANOBADGE
 	const ENGINE_EARTHBADGE
+; UnlockedUnowns
 	const ENGINE_UNLOCKED_UNOWNS_1
 	const ENGINE_UNLOCKED_UNOWNS_2
 	const ENGINE_UNLOCKED_UNOWNS_3
@@ -51,6 +62,7 @@
 	const ENGINE_UNLOCKED_UNOWNS_6 ; 30
 	const ENGINE_UNLOCKED_UNOWNS_7
 	const ENGINE_UNLOCKED_UNOWNS_8
+; VisitedSpawns
 	const ENGINE_FLYPOINT_KRISS_HOUSE
 	const ENGINE_FLYPOINT_VIRIDIAN_POKECENTER
 	const ENGINE_FLYPOINT_PALLET
@@ -78,8 +90,11 @@
 	const ENGINE_FLYPOINT_BLACKTHORN
 	const ENGINE_FLYPOINT_SILVER_CAVE
 	const ENGINE_FLYPOINT_UNUSED
+; wLuckyNumberShowFlag
 	const ENGINE_LUCKY_NUMBER_SHOW
+; StatusFlags2
 	const ENGINE_4F
+; DailyFlags
 	const ENGINE_KURT_MAKING_BALLS ; 50
 	const ENGINE_DAILY_BUG_CONTEST
 	const ENGINE_SPECIAL_WILDDATA
@@ -88,6 +103,7 @@
 	const ENGINE_SHUCKLE_GIVEN
 	const ENGINE_GOLDENROD_UNDERGROUND_MERCHANT_CLOSED
 	const ENGINE_FOUGHT_IN_TRAINER_HALL_TODAY
+; WeeklyFlags
 	const ENGINE_MT_MOON_SQUARE_CLEFAIRY
 	const ENGINE_UNION_CAVE_LAPRAS
 	const ENGINE_GOLDENROD_UNDERGROUND_GOT_HAIRCUT
@@ -96,11 +112,16 @@
 	const ENGINE_INDIGO_PLATEAU_RIVAL_FIGHT
 	const ENGINE_DAILY_MOVE_TUTOR
 	const ENGINE_BUENAS_PASSWORD
+; SwarmFlags
 	const ENGINE_BUENAS_PASSWORD_2 ; 60
 	const ENGINE_GOLDENROD_DEPT_STORE_SALE_IS_ON
+; GameTimerPause
 	const ENGINE_62
+; PlayerGender
 	const ENGINE_PLAYER_IS_FEMALE
+; wCelebiEvent
 	const ENGINE_HAVE_EXAMINED_GS_BALL
+; wDailyRematchFlags
 	const ENGINE_JACK
 	const ENGINE_HUEY
 	const ENGINE_GAVEN
@@ -125,6 +146,7 @@
 	const ENGINE_WILTON
 	const ENGINE_PARRY
 	const ENGINE_ERIN
+; wDailyPhoneItemFlags
 	const ENGINE_BEVERLY_HAS_NUGGET
 	const ENGINE_JOSE_HAS_STAR_PIECE
 	const ENGINE_WADE_HAS_ITEM
@@ -135,6 +157,7 @@
 	const ENGINE_TULLY_HAS_WATER_STONE
 	const ENGINE_TIFFANY_HAS_PINK_BOW
 	const ENGINE_WILTON_HAS_ITEM
+; wDailyPhoneTimeOfDayFlags
 	const ENGINE_JACK_MONDAY_MORNING
 	const ENGINE_HUEY_WEDNESDAY_NIGHT
 	const ENGINE_GAVEN_THURSDAY_MORNING
@@ -159,7 +182,9 @@
 	const ENGINE_WILTON_THRUSDAY_MORNING
 	const ENGINE_PARRY_FRIDAY_AFTERNOON
 	const ENGINE_ERIN_SATURDAY_NIGHT
+; wPlayerSpriteSetupFlags
 	const ENGINE_KRIS_IN_CABLE_CLUB
+; SwarmFlags
 	const ENGINE_DUNSPARCE_SWARM ; a0
 	const ENGINE_YANMA_SWARM
 NUM_ENGINE_FLAGS EQU const_value

constants/event_flags.asm

@@ -1,7 +1,6 @@
-
+; EventFlags bit flags
 	const_def
-
+; The first eight flags are reset upon reloading the map
-; These first eight flags are reset upon reloading the map.
 	const EVENT_GAVE_KURT_APRICORNS ; 000
 	const EVENT_RECEIVED_BALLS_FROM_KURT
 	const EVENT_DRAGON_SHRINE_QUESTION_2
@@ -10,7 +9,7 @@
 	const EVENT_DRAGON_SHRINE_QUESTION_5
 	const EVENT_JUST_RECEIVED_DRATINI
 	const EVENT_IN_YOUR_ROOM
-; Johto story events
+; Johto Gym Leader TM gifts
 	const EVENT_GOT_TM31_MUD_SLAP
 	const EVENT_GOT_TM49_FURY_CUTTER
 	const EVENT_GOT_TM01_DYNAMICPUNCH
@@ -19,6 +18,7 @@
 	const EVENT_GOT_TM23_IRON_TAIL
 	const EVENT_GOT_TM16_ICY_WIND
 	const EVENT_GOT_TM24_DRAGONBREATH
+; HMs (EVENT_GOT_HM07_WATERFALL is with the Johto itemballs)
 	const EVENT_GOT_HM01_CUT
 	const EVENT_GOT_HM02_FLY
 	const EVENT_GOT_HM03_SURF
@@ -26,9 +26,11 @@
 	const EVENT_GOT_HM05_FLASH
 	const EVENT_GOT_HM06_WHIRLPOOL
 	const EVENT_016
+; Rods
 	const EVENT_GOT_OLD_ROD
 	const EVENT_GOT_GOOD_ROD
 	const EVENT_GOT_SUPER_ROD
+; Johto story events
 	const EVENT_GOT_A_POKEMON_FROM_ELM
 	const EVENT_GOT_CYNDAQUIL_FROM_ELM
 	const EVENT_GOT_TOTODILE_FROM_ELM
@@ -128,7 +130,7 @@
 	const EVENT_GOT_TM12_SWEET_SCENT
 	const EVENT_RELEASED_THE_BEASTS
 	const EVENT_GOT_MASTER_BALL_FROM_ELM
-; Johto Signpost Items
+; Johto signpost items
 	const EVENT_TIN_TOWER_4F_HIDDEN_MAX_POTION
 	const EVENT_TIN_TOWER_5F_HIDDEN_FULL_RESTORE
 	const EVENT_TIN_TOWER_5F_HIDDEN_CARBOS
@@ -234,7 +236,7 @@
 	const EVENT_TALKED_TO_OAK_IN_KANTO
 	const EVENT_GOT_HP_UP_FROM_VERMILION_GUY
 	const EVENT_GOT_TM29_PSYCHIC
-; Kanto Signpost Items
+; Kanto signpost items
 	const EVENT_DIGLETTS_CAVE_HIDDEN_MAX_REVIVE
 	const EVENT_UNDERGROUND_HIDDEN_FULL_RESTORE
 	const EVENT_UNDERGROUND_HIDDEN_X_SPECIAL
@@ -608,7 +610,7 @@
 	const EVENT_255
 	const EVENT_256
 	const EVENT_257
-; Kurt events
+; Kurt Apricorn events
 	const EVENT_GAVE_KURT_RED_APRICORN
 	const EVENT_GAVE_KURT_BLU_APRICORN
 	const EVENT_GAVE_KURT_YLW_APRICORN
@@ -682,7 +684,7 @@
 	const EVENT_ERIN_ASKED_FOR_PHONE_NUMBER
 	const EVENT_BUENA_OFFERED_HER_PHONE_NUMBER_NO_BLUE_CARD
 	const EVENT_29F
-; Ruins Of Alph puzzles
+; Ruins of Alph puzzles
 	const EVENT_SOLVED_HO_OH_PUZZLE ; 2a0
 	const EVENT_SOLVED_KABUTO_PUZZLE
 	const EVENT_SOLVED_OMANYTE_PUZZLE
@@ -734,7 +736,7 @@
 	const EVENT_DECO_BIG_SNORLAX_DOLL
 	const EVENT_DECO_BIG_ONIX_DOLL ; 2d0
 	const EVENT_DECO_BIG_LAPRAS_DOLL
-; More Johto events
+; More Johto story events
 	const EVENT_WARPED_FROM_ROUTE_35_NATIONAL_PARK_GATE
 	const EVENT_SWITCH_1
 	const EVENT_SWITCH_2
@@ -818,7 +820,7 @@
 	const EVENT_GOT_WATER_STONE_FROM_BILLS_GRANDPA
 	const EVENT_GOT_FIRE_STONE_FROM_BILLS_GRANDPA
 	const EVENT_GOT_THUNDERSTONE_FROM_BILLS_GRANDPA
-; More Crystal-specific events
+; More Crystal-exclusive events in Johto
 	const EVENT_LISTENED_TO_INITIAL_RADIO
 	const EVENT_WALL_OPENED_IN_HO_OH_CHAMBER
 	const EVENT_WALL_OPENED_IN_KABUTO_CHAMBER
@@ -1015,7 +1017,7 @@
 	const EVENT_3E5
 	const EVENT_3E6
 	const EVENT_3E7
-; Trainer Flags
+; Trainer flags
 ; Swimmer F
 	const EVENT_BEAT_SWIMMERF_ELAINE
 	const EVENT_BEAT_SWIMMERF_PAULA
@@ -1530,7 +1532,7 @@
 	const EVENT_BEAT_ELITE_4_BRUNO
 	const EVENT_BEAT_ELITE_4_KAREN
 	const EVENT_BEAT_CHAMPION_LANCE
-; New to Crystal
+; Crystal-exclusive trainer flags
 	const EVENT_BEAT_COOLTRAINERM_DARIN
 	const EVENT_BEAT_COOLTRAINERF_CARA
 	const EVENT_BEAT_TWINS_LEA_AND_PIA
@@ -1663,10 +1665,11 @@
 	const EVENT_63D
 	const EVENT_63E
 	const EVENT_63F
-; Sprite visibility: When these events are cleared, the sprite becomes visible; when set, the sprite is hidden.
+; Sprite visibility flags
+; When these events are cleared, the sprite becomes visible; when set, the sprite is hidden.
 ; The map script command macros `disappear` and `appear` set/clear these flags and immediately apply the effect on visibility.
 ; The map script command macros `setevent` and `clearevent` set/clear these flags, and their effects will be seen when the map is reloaded.
-; Johto items: 0x640
+; Johto itemballs
 	const EVENT_CYNDAQUIL_POKEBALL_IN_ELMS_LAB
 	const EVENT_TOTODILE_POKEBALL_IN_ELMS_LAB
 	const EVENT_CHIKORITA_POKEBALL_IN_ELMS_LAB
@@ -1986,6 +1989,7 @@
 	const EVENT_MT_MOON_RIVAL
 	const EVENT_INDIGO_PLATEAU_POKECENTER_RIVAL
 	const EVENT_TELEPORT_GUY
+; Kanto itemballs
 	const EVENT_PICKED_UP_FOCUS_BAND
 	const EVENT_ROCK_TUNNEL_1F_ELIXER
 	const EVENT_ROCK_TUNNEL_1F_TM_STEEL_WING

constants/gfx_constants.asm

@@ -1,4 +1,3 @@
 LEN_2BPP_TILE EQU 16
 LEN_1BPP_TILE EQU 8
 TILES_PER_FRAME EQU 6
-TILESIZE EQU $10

constants/item_constants.asm

@@ -1,3 +1,9 @@
+; item ids
+; indexes for:
+; - ItemAttributes (see items/item_attributes.asm)
+; - ItemDescriptions (see items/item_descriptions.asm)
+; - ItemEffects (see items/item_effects.asm)
+; - ItemNames (see items/item_names.asm)
 	const_def
 	const NO_ITEM      ; $00
 	const MASTER_BALL  ; $01
@@ -243,7 +249,7 @@
 	add_tm FIRE_PUNCH   ; $F0
 	add_tm FURY_CUTTER  ; $F1
 	add_tm NIGHTMARE    ; $F2
-NUM_TMS = const_value - TM01 - 2
+NUM_TMS = const_value - TM01 - 2 ; discount ITEM_C3 and ITEM_DC
 
 	add_hm CUT          ; $F3
 	add_hm FLY          ; $F4
@@ -253,27 +259,36 @@ NUM_TMS = const_value - TM01 - 2
 	add_hm WHIRLPOOL    ; $F8
 	add_hm WATERFALL    ; $F9
 NUM_HMS = const_value - HM01
-	const HM_08         ; $FA
+	const ITEM_FA       ; $FA
 
 	add_mt FLAMETHROWER
 	add_mt THUNDERBOLT
 	add_mt ICE_BEAM
 
-ITEM_FROM_MEM EQU $ff
+ITEM_FROM_MEM EQU $FF
-
 
 ; leftovers from red
-SAFARI_BALL    EQU  8 ; MOON_STONE
+SAFARI_BALL    EQU $08 ; MOON_STONE
-MOON_STONE_RED EQU 10 ; BURN_HEAL
+MOON_STONE_RED EQU $0A ; BURN_HEAL
-FULL_HEAL_RED  EQU 52 ; X_SPEED
+FULL_HEAL_RED  EQU $34 ; X_SPEED
-MAIL_MAX_LENGTH EQU $20
 
-; pockets
+; mail
+MAIL_MSG_LENGTH    EQU $20
+MAILBOX_CAPACITY   EQU 10
+MAIL_STRUCT_LENGTH EQU $2f ; mailmsg struct
+
+; pack pockets
 ITEM     EQU 1
 KEY_ITEM EQU 2
 BALL     EQU 3
 TM_HM    EQU 4
 
+; pack pocket sizes
+MAX_ITEMS     EQU 20
+MAX_KEY_ITEMS EQU 25
+MAX_BALLS     EQU 12
+MAX_PC_ITEMS  EQU 50
+
 ; item actions
 CANT_SELECT EQU 1 << 6
 CANT_TOSS   EQU 1 << 7
@@ -356,6 +371,7 @@ const_value SET 70
 	const HELD_78
 	const HELD_FOCUS_BAND
 
+; item_attribute struct members (see items/item_attributes.asm)
 	const_def
 	const ITEMATTR_PRICE
 	const ITEMATTR_PRICE_HI
@@ -366,11 +382,13 @@ const_value SET 70
 	const ITEMATTR_HELP
 NUM_ITEMATTRS EQU const_value
 
-ITEMMENU_NOUSE              EQU 0
+; item menu types
-ITEMMENU_CURRENT            EQU 4
+ITEMMENU_NOUSE   EQU 0
-ITEMMENU_PARTY              EQU 5
+ITEMMENU_CURRENT EQU 4
-ITEMMENU_CLOSE              EQU 6
+ITEMMENU_PARTY   EQU 5
+ITEMMENU_CLOSE   EQU 6
 
+; mart types (see engine/mart.asm)
 	const_def
 	const MARTTYPE_STANDARD
 	const MARTTYPE_BITTER
@@ -378,6 +396,7 @@ ITEMMENU_CLOSE              EQU 6
 	const MARTTYPE_PHARMACY
 	const MARTTYPE_ROOFTOP
 
+; Marts indexes (see items/marts.asm)
 	const_def
 	const MART_CHERRYGROVE
 	const MART_CHERRYGROVE_DEX
@@ -414,7 +433,8 @@ ITEMMENU_CLOSE              EQU 6
 	const MART_INDIGO_PLATEAU
 	const MART_UNDERGROUND
 
-; PartyMenuActionText
+; PartyMenuActionText values
+; GetPartyMenuTilemapPointers arguments (see engine/party_menu.asm)
 	const_def
 	const PARTYMENUACTION_CHOOSE_POKEMON
 	const PARTYMENUACTION_HEALING_ITEM
@@ -426,7 +446,7 @@ ITEMMENU_CLOSE              EQU 6
 	const PARTYMENUACTION_GIVE_MON_FEMALE ; unused
 	const PARTYMENUACTION_GIVE_ITEM
 	const PARTYMENUACTION_MOBILE ; mobile
-
+; PrintPartyMenuActionText arguments (see engine/party_menu.asm)
 const_value set $f0
 	const PARTYMENUTEXT_HEAL_PSN
 	const PARTYMENUTEXT_HEAL_BRN

constants/landmark_constants.asm

@@ -1,6 +1,7 @@
-
+; Landmarks indexes (see engine/landmarks.asm)
 	const_def
 
+; Johto landmarks
 	const SPECIAL_MAP       ; 00
 	const NEW_BARK_TOWN     ; 01
 	const ROUTE_29          ; 02
@@ -50,7 +51,6 @@
 	const SILVER_CAVE       ; 2e
 
 KANTO_LANDMARK EQU const_value
-
 	const PALLET_TOWN       ; 2f
 	const ROUTE_1           ; 30
 	const VIRIDIAN_CITY     ; 31

constants/map_constants.asm

@@ -5,7 +5,13 @@ GROUP_NONE EQU 0
 MAP_NONE   EQU 0
 
 ; map group ids
+; `newgroup` indexes are for:
+; - MapGroupPointers (see maps/map_headers.asm)
+; - OutdoorSprites (see engine/overworld.asm)
+; - MapGroupRoofs (see tilesets/roofs.asm)
+; `mapgroup` indexes are for the sub-tables of MapGroupPointers (see maps/map_headers.asm)
 	const_def
+
 	newgroup                                                    ;  1
 
 	mapgroup OLIVINE_POKECENTER_1F,                       4,  5 ;  1
@@ -473,40 +479,7 @@ MAP_NONE   EQU 0
 	mapgroup ROUTE_31_VIOLET_GATE,                        4,  5 ; 11
 
 
-; elevator floors
+; map permissions (wPermission)
-
-	const_def
-	const _B4F
-	const _B3F
-	const _B2F
-	const _B1F
-	const _1F
-	const _2F
-	const _3F
-	const _4F
-	const _5F
-	const _6F
-	const _7F
-	const _8F
-	const _9F
-	const _10F
-	const _11F
-	const _ROOF
-
-; connection directions
-	const_def
-	const EAST_F
-	const WEST_F
-	const SOUTH_F
-	const NORTH_F
-
-	const_def
-	shift_const EAST
-	shift_const WEST
-	shift_const SOUTH
-	shift_const NORTH
-
-; permissions
 const_value SET 1
 	const TOWN
 	const ROUTE
@@ -516,7 +489,48 @@ const_value SET 1
 	const GATE
 	const DUNGEON
 
-; object struct
+; map palettes (wPermission)
+	const_def
+	const PALETTE_AUTO
+	const PALETTE_DAY
+	const PALETTE_NITE
+	const PALETTE_MORN
+	const PALETTE_DARK
+
+; fish groups 
+	const_def
+	const FISHGROUP_NONE
+	const FISHGROUP_SHORE
+	const FISHGROUP_OCEAN
+	const FISHGROUP_LAKE
+	const FISHGROUP_POND
+	const FISHGROUP_DRATINI
+	const FISHGROUP_QWILFISH_SWARM
+	const FISHGROUP_REMORAID_SWARM
+	const FISHGROUP_GYARADOS
+	const FISHGROUP_DRATINI_2
+	const FISHGROUP_WHIRL_ISLANDS
+	const FISHGROUP_QWILFISH
+	const FISHGROUP_REMORAID
+	const FISHGROUP_QWILFISH_NO_SWARM
+
+
+; connection directions
+	const_def
+	const EAST_F
+	const WEST_F
+	const SOUTH_F
+	const NORTH_F
+
+; MapConnections
+	const_def
+	shift_const EAST
+	shift_const WEST
+	shift_const SOUTH
+	shift_const NORTH
+
+
+; object_struct members (see macros/wram.asm)
 	const_def
 	const OBJECT_SPRITE              ; 00
 	const OBJECT_MAP_OBJECT_INDEX    ; 01
@@ -553,7 +567,7 @@ const_value SET 1
 	const OBJECT_RANGE               ; 20
 ; 33-39 are not used
 
-; map object struct
+; map_object struct members (see macros/wram.asm)
 	const_def
 	const MAPOBJECT_OBJECT_STRUCT_ID ; 0
 	const MAPOBJECT_SPRITE ; 1
@@ -576,46 +590,25 @@ OBJECT_LENGTH EQU const_value
 MAPOBJECT_SCREEN_HEIGHT EQU 11
 MAPOBJECT_SCREEN_WIDTH EQU 12
 
+; object_struct OBJECT_FACING values
 OW_DOWN  EQU DOWN  << 2
 OW_UP    EQU UP    << 2
 OW_LEFT  EQU LEFT  << 2
 OW_RIGHT EQU RIGHT << 2
 
-	const_def
+; object_struct OBJECT_FLAGS1 bit flags
-	const EMOTE_SHOCK ; 0
+INVISIBLE    EQU 0
-	const EMOTE_QUESTION ; 1
+FIXED_FACING EQU 2
-	const EMOTE_HAPPY ; 2
+SLIDING      EQU 3
-	const EMOTE_SAD ; 3
+EMOTE_OBJECT EQU 7
-	const EMOTE_HEART ; 4
-	const EMOTE_BOLT ; 5
-	const EMOTE_SLEEP ; 6
-	const EMOTE_FISH ; 7
-	const EMOTE_SHADOW ; 8
-	const EMOTE_ROD ; 9
-	const EMOTE_BOULDER_DUST ; 10
-	const EMOTE_0B ; 11
-EMOTE_MEM EQU -1
-
-	const_def
-	const SIGNPOST_READ
-	const SIGNPOST_UP
-	const SIGNPOST_DOWN
-	const SIGNPOST_RIGHT
-	const SIGNPOST_LEFT
-	const SIGNPOST_IFSET
-	const SIGNPOST_IFNOTSET
-	const SIGNPOST_ITEM
-	const SIGNPOST_COPY
-
-; I'm relocating spawn constants here, so that they can be used anywhere in the disassembly.
 
 
+; SpawnPoints indexes (see engine/spawn_points.asm)
 const_value = -1
 	const SPAWN_N_A
-
 	const SPAWN_HOME
 	const SPAWN_DEBUG
-
+; kanto
 	const SPAWN_PALLET
 	const SPAWN_VIRIDIAN
 	const SPAWN_PEWTER
@@ -628,7 +621,7 @@ const_value = -1
 	const SPAWN_FUCHSIA
 	const SPAWN_CINNABAR
 	const SPAWN_INDIGO
-
+; johto
 	const SPAWN_NEW_BARK
 	const SPAWN_CHERRYGROVE
 	const SPAWN_VIOLET
@@ -645,18 +638,21 @@ const_value = -1
 	const SPAWN_FAST_SHIP
 NUM_SPAWNS EQU const_value
 
+
+; TryReadSign arguments (see engine/events.asm)
 	const_def
-	const PALETTE_AUTO
+	const SIGNPOST_READ
-	const PALETTE_DAY
+	const SIGNPOST_UP
-	const PALETTE_NITE
+	const SIGNPOST_DOWN
-	const PALETTE_MORN
+	const SIGNPOST_RIGHT
-	const PALETTE_DARK
+	const SIGNPOST_LEFT
-
+	const SIGNPOST_IFSET
-INVISIBLE    EQU 0
+	const SIGNPOST_IFNOTSET
-FIXED_FACING EQU 2
+	const SIGNPOST_ITEM
-SLIDING      EQU 3
+	const SIGNPOST_COPY
-EMOTE_OBJECT EQU 7
 
+; person_event types
+; TryObjectEvent arguments (see engine/events.asm)
 	const_def
 	const PERSONTYPE_SCRIPT
 	const PERSONTYPE_ITEMBALL
@@ -666,7 +662,24 @@ EMOTE_OBJECT EQU 7
 	const PERSONTYPE_5
 	const PERSONTYPE_6
 
-; fruit trees
+
+; EmotesPointers indexes (see engine/overworld.asm)
+	const_def
+	const EMOTE_SHOCK ; 0
+	const EMOTE_QUESTION ; 1
+	const EMOTE_HAPPY ; 2
+	const EMOTE_SAD ; 3
+	const EMOTE_HEART ; 4
+	const EMOTE_BOLT ; 5
+	const EMOTE_SLEEP ; 6
+	const EMOTE_FISH ; 7
+	const EMOTE_SHADOW ; 8
+	const EMOTE_ROD ; 9
+	const EMOTE_BOULDER_DUST ; 10
+	const EMOTE_GRASS_RUSTLE ; 11
+EMOTE_MEM EQU -1
+
+; FruitTreeItems indexes (see engine/fruit_trees.asm)
 const_value SET 1
 	const FRUITTREE_ROUTE_29      ; 01
 	const FRUITTREE_ROUTE_30_1    ; 02
@@ -700,6 +713,27 @@ const_value SET 1
 	const FRUITTREE_FUCHSIA_CITY  ; 1e
 NUM_FRUIT_TREES EQU const_value +- 1
 
+; elevator floors
+; used by `elevfloor`
+	const_def
+	const _B4F
+	const _B3F
+	const _B2F
+	const _B1F
+	const _1F
+	const _2F
+	const _3F
+	const _4F
+	const _5F
+	const _6F
+	const _7F
+	const _8F
+	const _9F
+	const _10F
+	const _11F
+	const _ROOF
+
+; command queue members
 CMDQUEUE_TYPE  EQU 0
 CMDQUEUE_ADDR  EQU 1
 CMDQUEUE_03    EQU 3
@@ -708,4 +742,9 @@ CMDQUEUE_05    EQU 5
 CMDQUEUE_ENTRY_SIZE EQU 6
 CMDQUEUE_CAPACITY EQU 4
 
+; command queue types
 CMDQUEUE_STONETABLE EQU 2
+
+; see engine/overworld.asm
+MAX_OUTDOOR_SPRITES EQU 23
+SPRITE_GFX_LIST_CAPACITY EQU $20

constants/map_setup_constants.asm

@@ -1,3 +1,5 @@
+; hMapEntryMethod values
+; MapSetupScripts indexes (see engine/map_setup.asm)
 const_value SET $f1
 	const MAPSETUP_WARP
 	const MAPSETUP_CONTINUE
@@ -12,6 +14,7 @@ const_value SET $f1
 	const MAPSETUP_BADWARP
 	const MAPSETUP_FLY
 
+; callback types
 const_value SET 1
 	const MAPCALLBACK_TILES
 	const MAPCALLBACK_OBJECTS
@@ -19,9 +22,10 @@ const_value SET 1
 	const MAPCALLBACK_SPRITES
 	const MAPCALLBACK_NEWMAP
 
-; Command descriptions from Condensation water's scripting compendium.
+; MapSetupCommands indexes (see engine/map_setup.asm)
+; Names taken from Condensation water's scripting compendium
+; https://hax.iimarck.us/files/scriptingcodes_eng.htm
 	const_def
-
 	const map_lcd_on              ; 00
 	const map_lcd_off             ; 01
 	const map_sound_off           ; 02

constants/misc_constants.asm

@@ -1,21 +1,32 @@
-PARTY_LENGTH EQU 6
+; Boolean checks
+FALSE EQU 0
+TRUE  EQU 1
 
-MAX_ITEMS     EQU 20
+; genders
-MAX_BALLS     EQU 12
+MALE   EQU 0
-MAX_KEY_ITEMS EQU 25
+FEMALE EQU 1
-MAX_PC_ITEMS  EQU 50
 
-; strings
+; FlagAction arguments (see home/flag.asm)
+RESET_FLAG EQU 0
+SET_FLAG   EQU 1
+CHECK_FLAG EQU 2
+
+; GetHPPal return values (see home.asm)
+HP_GREEN  EQU 0
+HP_YELLOW EQU 1
+HP_RED    EQU 2
+
+
+; name lengths
+NAME_LENGTH        EQU 11
 PLAYER_NAME_LENGTH EQU 8
-BOX_NAME_LENGTH EQU 9
+BOX_NAME_LENGTH    EQU 9
-PKMN_NAME_LENGTH EQU 11
+PKMN_NAME_LENGTH   EQU 11
-MOVE_NAME_LENGTH EQU 13
+MOVE_NAME_LENGTH   EQU 13
-ITEM_NAME_LENGTH EQU 13
+ITEM_NAME_LENGTH   EQU 13
 TRAINER_CLASS_NAME_LENGTH EQU 13
-NAME_LENGTH EQU 11
-LV_CHAR EQU $6e
 
-; GetName types
+; GetName types (see home.asm)
 PKMN_NAME     EQU 1
 MOVE_NAME     EQU 2
 ; dummied out EQU 3
@@ -25,35 +36,17 @@ ENEMY_OT_NAME EQU 6
 TRAINER_NAME  EQU 7
 ; broken ptr  EQU 8
 
-; hp
-HP_GREEN  EQU 0
-HP_YELLOW EQU 1
-HP_RED    EQU 2
 
 ; boxes
 MONS_PER_BOX EQU 20
 NUM_BOXES    EQU 14
 
-; mail
-MAIL_STRUCT_LENGTH EQU $2f
-MAILBOX_CAPACITY   EQU 10
-MAIL_MSG_LENGTH    EQU $20
-
 ; hall of fame
 HOF_MON_LENGTH = 1 + 2 + 2 + 1 + (PKMN_NAME_LENGTH +- 1) ; species, id, dvs, level, nick
 HOF_LENGTH = 1 + HOF_MON_LENGTH * PARTY_LENGTH + 1 ; win count, party, terminator
 NUM_HOF_TEAMS = 30
 
 
-; flag manipulation
-RESET_FLAG EQU 0
-SET_FLAG   EQU 1
-CHECK_FLAG EQU 2
-
-; Boolean checks
-FALSE EQU 0
-TRUE  EQU 1
-
 ; joypad
 
 	const_def
@@ -82,7 +75,9 @@ D_PAD      EQU D_RIGHT | D_LEFT | D_UP | D_DOWN
 R_DPAD     EQU %00100000
 R_BUTTONS  EQU %00010000
 
+
 ; screen
+
 HP_BAR_LENGTH EQU 6
 HP_BAR_LENGTH_PX EQU HP_BAR_LENGTH * 8
 EXP_BAR_LENGTH EQU 8
@@ -101,51 +96,7 @@ WMISC_HEIGHT  EQU 5 * 4
 TILE_WIDTH EQU 8
 
 
-; movement
+; printing text
-STEP_SLOW EQU 0
-STEP_WALK EQU 1
-STEP_BIKE EQU 2
-STEP_LEDGE EQU 3
-STEP_ICE EQU 4
-STEP_TURN EQU 5
-STEP_BACK_LEDGE EQU 6
-STEP_WALK_IN_PLACE EQU 7
-
-
-; ai
-CONTEXT_USE_F      EQU 6
-UNKNOWN_USE_F      EQU 5
-ALWAYS_USE_F       EQU 4
-SWITCH_SOMETIMES_F EQU 2
-SWITCH_RARELY_F    EQU 1
-SWITCH_OFTEN_F     EQU 0
-
-CONTEXT_USE        EQU 1 << CONTEXT_USE_F
-UNKNOWN_USE        EQU 1 << UNKNOWN_USE_F
-ALWAYS_USE         EQU 1 << ALWAYS_USE_F
-SWITCH_SOMETIMES   EQU 1 << SWITCH_SOMETIMES_F
-SWITCH_RARELY      EQU 1 << SWITCH_RARELY_F
-SWITCH_OFTEN       EQU 1 << SWITCH_OFTEN_F
-SPRITE_GFX_LIST_CAPACITY EQU $20
-
-const_value = 1
-	const MOM_ITEM
-	const MOM_DOLL
-
-BATTLETOWER_NROFPKMNS EQU 3
-BATTLETOWER_TRAINERDATALENGTH EQU $24
-BATTLETOWER_NROFTRAINERS EQU 7
-BATTLETOWER_NRMONSPERLEVELBRACKET EQU BATTLETOWER_NROFPKMNS * BATTLETOWER_NROFTRAINERS
-BATTLE_TOWER_STRUCT_LENGTH EQU $e0 ; NAME_LENGTH + 3 * (PARTYMON_STRUCT_LENGTH + PKMN_NAME_LENGTH) + BATTLETOWER_TRAINERDATALENGTH
-
-NUM_WILDMONS_PER_AREA_TIME_OF_DAY EQU 7
-WILDMON_GRASS_STRUCTURE_LENGTH EQU 2 + 3 * (1 + 2 * NUM_WILDMONS_PER_AREA_TIME_OF_DAY)
-
-MOBILE_EVENT_OBJECT_GS_BALL EQU $b
-MOBILE_LOGIN_PASSWORD_LENGTH EQU 17
-
-MALE EQU 0
-FEMALE EQU 1
 
 PRINTNUM_MONEY_F        EQU 5
 PRINTNUM_RIGHTALIGN_F   EQU 6
@@ -155,6 +106,20 @@ PRINTNUM_MONEY          EQU 1 << PRINTNUM_MONEY_F
 PRINTNUM_RIGHTALIGN     EQU 1 << PRINTNUM_RIGHTALIGN_F
 PRINTNUM_LEADINGZEROS   EQU 1 << PRINTNUM_LEADINGZEROS_F
 
+
+; movement
+	const_def
+	const STEP_SLOW          ; 0
+	const STEP_WALK          ; 1
+	const STEP_BIKE          ; 2
+	const STEP_LEDGE         ; 3
+	const STEP_ICE           ; 4
+	const STEP_TURN          ; 5
+	const STEP_BACK_LEDGE    ; 6
+	const STEP_WALK_IN_PLACE ; 7
+
+
+; ChangeHappiness arguments (see event/happiness_egg.asm)
 const_value = 1
 	const HAPPINESS_GAINLEVEL         ; 01
 	const HAPPINESS_USEDITEM          ; 02
@@ -178,44 +143,22 @@ const_value = 1
 
 
 	const_def
-	const LINK_NULL
+	const LINK_NULL        ; 0
-	const LINK_TIMECAPSULE
+	const LINK_TIMECAPSULE ; 1
-	const LINK_TRADECENTER
+	const LINK_TRADECENTER ; 2
-	const LINK_COLOSSEUM
+	const LINK_COLOSSEUM   ; 3
-	const LINK_MOBILE
+	const LINK_MOBILE      ; 4
 
 SERIAL_TIMECAPSULE EQU $60
 SERIAL_TRADECENTER EQU $70
 SERIAL_BATTLE      EQU $80
 
+
 HMENURETURN_SCRIPT EQU %10000000
 HMENURETURN_ASM    EQU %11111111
 
-NUM_MON_SUBMENU_ITEMS EQU 8
-
-	const_def
-	const ZEPHYRBADGE
-	const HIVEBADGE
-	const PLAINBADGE
-	const FOGBADGE
-	const MINERALBADGE
-	const STORMBADGE
-	const GLACIERBADGE
-	const RISINGBADGE
-NUM_JOHTO_BADGES EQU const_value
-	const_def
-	const BOULDERBADGE
-	const CASCADEBADGE
-	const THUNDERBADGE
-	const RAINBOWBADGE
-	const SOULBADGE
-	const MARSHBADGE
-	const VOLCANOBADGE
-	const EARTHBADGE
-NUM_KANTO_BADGES EQU const_value
-NUM_BADGES EQU NUM_JOHTO_BADGES + NUM_KANTO_BADGES
-NUM_KANA EQU $2d
 
+; MobileEZChatCategoryPointers indexes (see misc/fixed_words.asm)
 	const_def
 	const EZCHAT_POKEMON
 	const EZCHAT_TYPES
@@ -233,30 +176,6 @@ NUM_KANA EQU $2d
 	const EZCHAT_FAREWELLS
 	const EZCHAT_THISANDTHAT
 
-SWARM_DUNSPARCE EQU 0
+NUM_KANA EQU 45 ; length of SortedPokemon table (see misc/fixed_words.asm)
-SWARM_YANMA     EQU 1
 
-FISHSWARM_QWILFISH EQU 1
+MOBILE_LOGIN_PASSWORD_LENGTH EQU 17
-FISHSWARM_REMORAID EQU 2
-
-	const_def
-	const FISHGROUP_NONE
-	const FISHGROUP_SHORE
-	const FISHGROUP_OCEAN
-	const FISHGROUP_LAKE
-	const FISHGROUP_POND
-	const FISHGROUP_DRATINI
-	const FISHGROUP_QWILFISH_SWARM
-	const FISHGROUP_REMORAID_SWARM
-	const FISHGROUP_GYARADOS
-	const FISHGROUP_DRATINI_2
-	const FISHGROUP_WHIRL_ISLANDS
-	const FISHGROUP_QWILFISH
-	const FISHGROUP_REMORAID
-	const FISHGROUP_QWILFISH_NO_SWARM
-
-INIT_ENEMYOT_LIST    EQU 1
-INIT_BAG_ITEM_LIST   EQU 2
-INIT_OTHER_ITEM_LIST EQU 3
-INIT_PLAYEROT_LIST   EQU 4
-INIT_MON_LIST        EQU 5

constants/music_constants.asm

@@ -1,3 +1,5 @@
+; song ids
+; Music indexes (see audio/music_pointers.asm)
 	const_def
 
 	const MUSIC_NONE                         ; 00
@@ -93,6 +95,8 @@
 	const MUSIC_LAKE_OF_RAGE_ROCKET_RADIO    ; 5a
 	const MUSIC_PRINTER                      ; 5b
 	const MUSIC_POST_CREDITS                 ; 5c
+
+; new to Crystal
 	const MUSIC_CLAIR                        ; 5d
 	const MUSIC_MOBILE_ADAPTER_MENU          ; 5e
 	const MUSIC_MOBILE_ADAPTER               ; 5f
@@ -104,4 +108,7 @@
 	const MUSIC_BATTLE_TOWER_LOBBY           ; 65
 	const MUSIC_MOBILE_CENTER                ; 66
 
-MUSIC_MAHOGANY_MART EQU $64 ; leftover from gold
+; GetMapHeaderMusic picks music for this value (see home/map.asm)
+MUSIC_MAHOGANY_MART EQU $64
+; GetMapHeaderMusic picks music for this bit flag
+RADIO_TOWER_MUSIC EQU 7

constants/phone_constants.asm

@@ -1,4 +1,4 @@
-
+; PhoneContacts indexes (see engine/phone.asm)
 	const_def
 	const PHONE_00
 	const PHONE_MOM
@@ -39,6 +39,7 @@
 	const PHONE_PICNICKER_ERIN
 	const PHONE_BUENA
 
+; SpecialPhoneCallList indexes (see engine/phone.asm)
 	const_def
 	const SPECIALCALL_NONE
 	const SPECIALCALL_POKERUS
@@ -50,6 +51,7 @@
 	const SPECIALCALL_WORRIED
 	const SPECIALCALL_MASTERBALL
 
+; phone struct members
 	const_def
 	const PHONE_CONTACT_TRAINER_CLASS
 	const PHONE_CONTACT_TRAINER_NUMBER
@@ -64,4 +66,6 @@
 	const PHONE_CONTACT_SCRIPT2_ADDR_LO
 	const PHONE_CONTACT_SCRIPT2_ADDR_HI
 PHONE_TABLE_WIDTH EQU const_value
+
+; maximum number of pokegear contacts
 CONTACT_LIST_SIZE EQU 10