Add new macro comments

asm/macros/field_effect_script.inc

@@ -1,3 +1,5 @@
+@ The first .byte argument of each macro below is an index into gFieldEffectScriptFuncs
+
 	.macro field_eff_loadtiles address:req
 	.byte 0
 	.4byte \address

asm/macros/m4a.inc

@@ -8,6 +8,6 @@
 	.4byte \info_struct
 	.4byte \track_struct
 	.byte \num_tracks
-	.byte 0  @ Padding
+	.space 1  @ Padding
 	.2byte \unknown
 	.endm

asm/macros/map.inc

@@ -1,37 +1,44 @@
+@ Most of the macros in this file are for arranging map event data, and are output by mapjson using data from each map's JSON file.
+
+	@ Takes a MAP constant and outputs the map group and map number as separate bytes
 	.macro map map_id:req
 	.byte \map_id >> 8    @ map group
 	.byte \map_id & 0xFF  @ map num
 	.endm
 
+	@ Defines a map script. 'type' is any MAP_SCRIPT_* constant (see include/constants/map_scripts.h)
 	.macro map_script type:req, script:req
 	.byte \type
 	.4byte \script
 	.endm
 
+	@ Defines an entry in a map script table (for either ON_WARP_INTO_MAP_TABLE or ON_FRAME_TABLE)
 	.macro map_script_2 var:req, compare:req, script:req
 	.2byte \var
 	.2byte \compare
 	.4byte \script
 	.endm
 
+	@ Defines an object event template for map data. Mirrors the struct layout of ObjectEventTemplate in include/global.fieldmap.h
 	.macro object_event index:req, gfx:req, inConnection:req, x:req, y:req, elevation:req, movement_type:req, x_radius:req, y_radius:req, trainer_type:req, sight_radius_tree_etc:req, script:req, event_flag:req
 	.byte \index
 	.byte \gfx
 	.byte \inConnection
-	.byte 0  @ Padding
+	.space 1  @ Padding
 	.2byte \x, \y
 	.byte \elevation
 	.byte \movement_type
 	.byte ((\y_radius << 4) | \x_radius)
-	.byte 0  @ Padding
+	.space 1  @ Padding
 	.2byte \trainer_type
 	.2byte \sight_radius_tree_etc
 	.4byte \script
 	.2byte \event_flag
-	.2byte 0  @ Padding
+	.space 2  @ Padding
 	inc _num_npcs
 	.endm
 
+	@ Defines a warp event for map data. Mirrors the struct layout of WarpEvent in include/global.fieldmap.h
 	.macro warp_def x:req, y:req, elevation:req, warpId:req, map_id:req
 	.2byte \x, \y
 	.byte \elevation
@@ -41,26 +48,31 @@
 	inc _num_warps
 	.endm
 
+	@ Defines a coord event for map data. Mirrors the struct layout of CoordEvent in include/global.fieldmap.h
 	.macro coord_event x:req, y:req, elevation:req, trigger:req, index:req, script:req
 	.2byte \x, \y
 	.byte \elevation
-	.byte 0  @ Padding
+	.space 1  @ Padding
 	.2byte \trigger
 	.2byte \index
-	.2byte 0  @ Padding
+	.space 2  @ Padding
 	.4byte \script
 	inc _num_traps
 	.endm
 
+	@ Defines a weather coord event for map data. Any coord event is treated as a weather coord event if its script is NULL
 	.macro coord_weather_event x:req, y:req, elevation:req, weather:req
 	coord_event \x, \y, \elevation, \weather, 0, NULL
 	.endm
 
+	@ Defines a generic background event for map data. Mirrors the struct layout of BgEvent in include/global.fieldmap.h
+	@ 'kind' is any BG_EVENT_* constant (see include/constants/event_bg.h).
+	@ 'arg6' and 'arg7' are used differently depending on the bg event type. See macros below
 	.macro bg_event x:req, y:req, elevation:req, kind:req, arg6:req, arg7
 	.2byte \x, \y
 	.byte \elevation
 	.byte \kind
-	.2byte 0  @ Padding
+	.space 2  @ Padding
 	.if \kind != BG_EVENT_HIDDEN_ITEM
 		.4byte \arg6
 	.else
@@ -70,24 +82,29 @@
 	inc _num_signs
 	.endm
 
+	@ Defines a background sign event for map data. 'facing_dir' is any of the BG_EVENT_PLAYER_FACING_* constants (see include/constants/event_bg.h)
 	.macro bg_sign_event x:req, y:req, elevation:req, facing_dir:req, script:req
 	bg_event \x, \y, \elevation, \facing_dir, \script
 	.endm
 
+	@ Defines a background hidden item event for map data
 	.macro bg_hidden_item_event x:req, y:req, elevation:req, item:req, flag:req
 	bg_event \x, \y, \elevation, BG_EVENT_HIDDEN_ITEM, \item, ((\flag) - FLAG_HIDDEN_ITEMS_START)
 	.endm
 
+	@ Defines a background secret base event for map data
 	.macro bg_secret_base_event x:req, y:req, elevation:req, secret_base_id:req
 	bg_event \x, \y, \elevation, BG_EVENT_SECRET_BASE, \secret_base_id
 	.endm
 
+	@ Defines the table of event data for a map. Mirrors the struct layout of MapEvents in include/global.fieldmap.h
 	.macro map_events npcs:req, warps:req, traps:req, signs:req
 	.byte _num_npcs, _num_warps, _num_traps, _num_signs
 	.4byte \npcs, \warps, \traps, \signs
 	reset_map_events
 	.endm
 
+	@ Resets the event counters used to track how many events a map has. Run when the events table is created by map_events
 	.macro reset_map_events
 	.set _num_npcs, 0
 	.set _num_warps, 0
@@ -95,9 +112,12 @@
 	.set _num_signs, 0
 	.endm
 
+	@ Initialize the event counters for the first map
 	reset_map_events
 
 
+	@ Directions for connecting maps
+	@ The map.json files will only have e.g. "down" as direction data, and this will be appended to "connection_" by the connection macro
 	.equiv connection_down, CONNECTION_SOUTH
 	.equiv connection_up, CONNECTION_NORTH
 	.equiv connection_left, CONNECTION_WEST
@@ -105,13 +125,16 @@
 	.equiv connection_dive, CONNECTION_DIVE
 	.equiv connection_emerge, CONNECTION_EMERGE
 
+	@ Defines a map connection. Mirrors the struct layout of MapConnection in include/global.fieldmap.h
 	.macro connection direction:req, offset:req, map:req
-	.4byte connection_\direction
+	.byte connection_\direction
+	.space 3  @ Padding
 	.4byte \offset
 	map \map
-	.space 2
+	.space 2  @ Padding
 	.endm
 
+	@ Defines the flags for a map header. Mirrors the layout of the bitfield in struct MapHeader in include/global.fieldmap.h
 	.macro map_header_flags allow_cycling:req, allow_escaping:req, allow_running:req, show_map_name:req
 	.byte ((\show_map_name & 1) << 3) | ((\allow_running & 1) << 2) | ((\allow_escaping & 1) << 1) | \allow_cycling
 	.endm