Document Player Params (#2307)

* document player params

* better bgcamindex comment

* cant use -1 for condition

* fix match

* define for default bgcam

* doesnt work

* matches

* better comment

2 files changed, 17 insertions, 1 deletions

diff --git a/include/z64actor.h b/include/z64actor.h
index deac35481..0f047549e 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -759,6 +759,10 @@ typedef struct NpcInteractInfo {
 #define PARAMS_PACK(p, s, n) \
     (((p) & NBITS_TO_MASK(n)) << (s))
 
+// Moves the value `p` to bit position `s` for building actor parameters by OR-ing these together.
+#define PARAMS_PACK_NOMASK(p, s) \
+    ((p) << (s))
+
 // Generates a bitmask for bit position `s` of length `n`
 #define PARAMS_MAKE_MASK(s, n) PARAMS_GET_NOSHIFT(~0, s, n)
 
diff --git a/include/z64player.h b/include/z64player.h
index 09a1d34f5..d44da08ae 100644
--- a/include/z64player.h
+++ b/include/z64player.h
@@ -7,7 +7,19 @@
 
 struct Player;
 
-#define PLAYER_GET_START_MODE(thisx) PARAMS_GET_S(thisx->params, 8, 4)
+#define PLAYER_PARAMS(startMode, startBgCamIndex) (PARAMS_PACK_NOMASK(startMode, 8) | PARAMS_PACK_NOMASK(startBgCamIndex, 0))
+
+// Determines behavior when spawning. See `PlayerStartMode`.
+#define PLAYER_GET_START_MODE(thisx) PARAMS_GET_S((thisx)->params, 8, 4)
+
+// Sets initial `bgCamIndex`, which determines camera behavior.
+// The value is used to index a list of `BgCamInfo` contained within the scene's collision data.
+// See `PLAYER_START_BG_CAM_DEFAULT` for what a value of -1 does.
+#define PLAYER_GET_START_BG_CAM_INDEX(thisx) PARAMS_GET_S((thisx)->params, 0, 8)
+
+// A value of -1 for `startBgCamIndex` indicates that default behavior should be used.
+// This means the `bgCamIndex` will be read from the current floor polygon.
+#define PLAYER_START_BG_CAM_DEFAULT ((u8)-1)
 
 typedef enum PlayerStartMode {
     /*  0 */ PLAYER_START_MODE_NOTHING, // Update is empty and draw function is NULL, nothing occurs. Useful in cutscenes, for example.