Improve documentation for chr_move_to_pad

src/game/chr/chr.c

@@ -50500,7 +50500,7 @@ glabel func0f04b658
 );
 
 GLOBAL_ASM(
-glabel func0f04b748
+glabel chrMoveToPos
 /*  f04b748:	27bdff88 */ 	addiu	$sp,$sp,-120
 /*  f04b74c:	afbf0034 */ 	sw	$ra,0x34($sp)
 /*  f04b750:	afb00030 */ 	sw	$s0,0x30($sp)

src/game/chr/chraicommands.c

@@ -7173,11 +7173,10 @@ bool aiChrMoveToPad(void)
 	if (chr && chr->prop) {
 		if (cmd[5] == 88) {
 			chr2 = chrFindById(g_Vars.chrdata, cmd[4]);
-			pass = false;
 
 			if (chr2 && chr2->prop) {
 				somefloat = func0f03e45c(chr2);
-				pass = func0f04b748(chr, &chr2->prop->pos, &chr2->prop->rooms[0], somefloat, 0);
+				pass = chrMoveToPos(chr, &chr2->prop->pos, &chr2->prop->rooms[0], somefloat, 0);
 			}
 		} else {
 			s32 padnum = cmd[4] | (cmd[3] << 8);
@@ -7189,7 +7188,7 @@ bool aiChrMoveToPad(void)
 
 				rooms[0] = pad.room;
 				rooms[1] = -1;
-				pass = func0f04b748(chr, &pad.pos, &rooms[0], somefloat, cmd[5]);
+				pass = chrMoveToPos(chr, &pad.pos, &rooms[0], somefloat, cmd[5]);
 			}
 		}
 	}

src/game/game_0b28d0.c

@@ -6288,7 +6288,7 @@ glabel func0f0b7c60
 /*  f0b7cc4:	afa00010 */ 	sw	$zero,0x10($sp)
 /*  f0b7cc8:	8fa4003c */ 	lw	$a0,0x3c($sp)
 /*  f0b7ccc:	24450008 */ 	addiu	$a1,$v0,0x8
-/*  f0b7cd0:	0fc12dd2 */ 	jal	func0f04b748
+/*  f0b7cd0:	0fc12dd2 */ 	jal	chrMoveToPos
 /*  f0b7cd4:	24460028 */ 	addiu	$a2,$v0,0x28
 /*  f0b7cd8:	14400003 */ 	bnez	$v0,.L0f0b7ce8
 /*  f0b7cdc:	8fab004c */ 	lw	$t3,0x4c($sp)

src/game/game_187770.c

@@ -10486,7 +10486,7 @@ glabel func0f1905f0
 /*  f19068c:	afa90010 */ 	sw	$t1,0x10($sp)
 /*  f190690:	02002025 */ 	or	$a0,$s0,$zero
 /*  f190694:	27a5003c */ 	addiu	$a1,$sp,0x3c
-/*  f190698:	0fc12dd2 */ 	jal	func0f04b748
+/*  f190698:	0fc12dd2 */ 	jal	chrMoveToPos
 /*  f19069c:	27a6002c */ 	addiu	$a2,$sp,0x2c
 /*  f1906a0:	0c006b91 */ 	jal	func0001ae44
 /*  f1906a4:	8e040020 */ 	lw	$a0,0x20($s0)

src/include/commands.h

@@ -1975,19 +1975,26 @@
 
 /**
  * Attempt to move the chr to the given pad. The chr is moved immediately.
+ * If successful, the label will be followed.
  *
- * For an immersive gameplay experience, do not do this while the chr is on
- * screen.
+ * If the pad is occupied then a reasonable attempt will be made to place the
+ * chr near it. This attempt may fail if the pad is occupied by several chrs.
  *
- * If 88 is passed as the unknown argument then the pad number will be
- * interpreted as a chr number and the chr will be moved to the other chr
- * instead. This is likely a temporary hack used for debug purposes.
+ * If allowonscreen is FALSE, the chr will not be moved if the pad is on screen.
+ *
+ * If allowonscreen is TRUE, the chr will be moved even if the pad is on screen.
+ * This may cause them to appear out of nowhere.
+ *
+ * If allowonscreen is 88 then the pad number will be interpreted as a chr
+ * number and the chr will be moved to the other chr instead. This is likely a
+ * hack used for debugging purposes. When using this value, the chr will not be
+ * moved if the destination chr is on screen.
  */
-#define chr_move_to_pad(chr, pad, unknown, label) \
+#define chr_move_to_pad(chr, pad, allowonscreen, label) \
 	mkshort(0x00e2), \
 	chr, \
 	mkshort(pad), \
-	unknown, \
+	allowonscreen, \
 	label,
 
 #define cmd00e3(chr) \

src/include/game/chr/chr.h

@@ -389,7 +389,7 @@ bool chrSpawnAtCoord(s32 body, s32 head, struct coord *pos, s16 *room, f32 arg4,
 bool chrSpawnAtPad(struct chrdata *chr, s32 body, s32 head, s32 pad, u8 *ailist, u32 flags);
 bool chrSpawnAtChr(struct chrdata *basechr, s32 body, s32 head, u32 chrnum, u8 *ailist, u32 flags);
 u32 func0f04b658(struct chrdata *chr);
-s32 func0f04b748(struct chrdata *chr, struct coord *pos, s16 *room, f32 arg3, s32 arg4);
+bool chrMoveToPos(struct chrdata *chr, struct coord *pos, s16 *room, f32 arg3, u32 allowonscreen);
 u32 func0f04b950(struct chrdata *chr, u32 cover, u32 arg2);
 u32 func0f04ba34(struct chrdata *chr, u16 arg1, u32 arg2);
 u32 func0f04bffc(struct chrdata *chr, u32 arg1, u32 arg2);