From bda5e94ded7792308a3b48ccfb09ec38779814ef Mon Sep 17 00:00:00 2001 From: fig02 Date: Sun, 8 Dec 2024 14:56:01 -0500 Subject: [PATCH] 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 --- include/z64actor.h | 4 ++++ include/z64player.h | 14 ++++++++++++- src/code/z_actor.c | 3 ++- src/code/z_play.c | 7 ++++--- src/overlays/actors/ovl_Door_Ana/z_door_ana.c | 3 ++- .../actors/ovl_Door_Shutter/z_door_shutter.c | 3 ++- .../actors/ovl_player_actor/z_player.c | 21 ++++++++++++------- 7 files changed, 41 insertions(+), 14 deletions(-) diff --git a/include/z64actor.h b/include/z64actor.h index deac35481c..0f047549ef 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 09a1d34f5a..d44da08ae8 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. diff --git a/src/code/z_actor.c b/src/code/z_actor.c index 114afb8efe..4fc55d7a87 100644 --- a/src/code/z_actor.c +++ b/src/code/z_actor.c @@ -2186,7 +2186,8 @@ void Actor_DrawFaroresWindPointer(PlayState* play) { if (D_8015BC18 == 0.0f) { gSaveContext.respawn[RESPAWN_MODE_TOP] = gSaveContext.respawn[RESPAWN_MODE_DOWN]; - gSaveContext.respawn[RESPAWN_MODE_TOP].playerParams = 0x06FF; + gSaveContext.respawn[RESPAWN_MODE_TOP].playerParams = + PLAYER_PARAMS(PLAYER_START_MODE_FARORES_WIND, PLAYER_START_BG_CAM_DEFAULT); gSaveContext.respawn[RESPAWN_MODE_TOP].data = 40; } diff --git a/src/code/z_play.c b/src/code/z_play.c index dc37ab27a5..068bc6ee87 100644 --- a/src/code/z_play.c +++ b/src/code/z_play.c @@ -483,8 +483,9 @@ void Play_Init(GameState* thisx) { Camera_InitDataUsingPlayer(&this->mainCamera, player); Camera_RequestMode(&this->mainCamera, CAM_MODE_NORMAL); - playerStartBgCamIndex = PARAMS_GET_U(player->actor.params, 0, 8); - if (playerStartBgCamIndex != 0xFF) { + playerStartBgCamIndex = PLAYER_GET_START_BG_CAM_INDEX(&player->actor); + + if (playerStartBgCamIndex != PLAYER_START_BG_CAM_DEFAULT) { PRINTF("player has start camera ID (" VT_FGCOL(BLUE) "%d" VT_RST ")\n", playerStartBgCamIndex); Camera_RequestBgCam(&this->mainCamera, playerStartBgCamIndex); } @@ -1901,7 +1902,7 @@ void Play_LoadToLastEntrance(PlayState* this) { } void Play_TriggerRespawn(PlayState* this) { - Play_SetupRespawnPoint(this, RESPAWN_MODE_DOWN, 0xDFF); + Play_SetupRespawnPoint(this, RESPAWN_MODE_DOWN, PLAYER_PARAMS(PLAYER_START_MODE_IDLE, PLAYER_START_BG_CAM_DEFAULT)); Play_LoadToLastEntrance(this); } diff --git a/src/overlays/actors/ovl_Door_Ana/z_door_ana.c b/src/overlays/actors/ovl_Door_Ana/z_door_ana.c index b2b735c3ad..8c38023ac3 100644 --- a/src/overlays/actors/ovl_Door_Ana/z_door_ana.c +++ b/src/overlays/actors/ovl_Door_Ana/z_door_ana.c @@ -131,7 +131,8 @@ void DoorAna_WaitOpen(DoorAna* this, PlayState* play) { if ((this->actor.attentionRangeType != 0) && (play->transitionTrigger == TRANS_TRIGGER_OFF) && (player->stateFlags1 & PLAYER_STATE1_31) && (player->av1.actionVar1 == 0)) { destinationIdx = PARAMS_GET_U(this->actor.params, 12, 3) - 1; - Play_SetupRespawnPoint(play, RESPAWN_MODE_RETURN, 0x4FF); + Play_SetupRespawnPoint(play, RESPAWN_MODE_RETURN, + PLAYER_PARAMS(PLAYER_START_MODE_GROTTO, PLAYER_START_BG_CAM_DEFAULT)); gSaveContext.respawn[RESPAWN_MODE_RETURN].pos.y = this->actor.world.pos.y; gSaveContext.respawn[RESPAWN_MODE_RETURN].yaw = this->actor.home.rot.y; gSaveContext.respawn[RESPAWN_MODE_RETURN].data = PARAMS_GET_U(this->actor.params, 0, 16); diff --git a/src/overlays/actors/ovl_Door_Shutter/z_door_shutter.c b/src/overlays/actors/ovl_Door_Shutter/z_door_shutter.c index 1cfb4255d3..130b833b63 100644 --- a/src/overlays/actors/ovl_Door_Shutter/z_door_shutter.c +++ b/src/overlays/actors/ovl_Door_Shutter/z_door_shutter.c @@ -821,7 +821,8 @@ void DoorShutter_SetupClosed(DoorShutter* this, PlayState* play) { play->roomCtx.activeBufPage ^= 1; } Room_FinishRoomChange(play, &play->roomCtx); - Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, 0x0EFF); + Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, + PLAYER_PARAMS(PLAYER_START_MODE_MOVE_FORWARD_SLOW, PLAYER_START_BG_CAM_DEFAULT)); } this->isActive = false; this->dyna.actor.velocity.y = 0.0f; diff --git a/src/overlays/actors/ovl_player_actor/z_player.c b/src/overlays/actors/ovl_player_actor/z_player.c index 3377ec68e8..d5dfcaa4b3 100644 --- a/src/overlays/actors/ovl_player_actor/z_player.c +++ b/src/overlays/actors/ovl_player_actor/z_player.c @@ -4814,7 +4814,8 @@ s32 func_808382DC(Player* this, PlayState* play) { respawnInfo = &fallingSpikeTrapRespawn; } - Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, 0xDFF); + Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, + PLAYER_PARAMS(PLAYER_START_MODE_IDLE, PLAYER_START_BG_CAM_DEFAULT)); gSaveContext.respawn[RESPAWN_MODE_DOWN].pos = respawnInfo->pos; gSaveContext.respawn[RESPAWN_MODE_DOWN].yaw = respawnInfo->yaw; } @@ -10185,7 +10186,8 @@ s32 func_80845BA0(PlayState* play, Player* this, f32* arg2, s32 arg3) { s32 func_80845C68(PlayState* play, s32 arg1) { if (arg1 == 0) { - Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, 0xDFF); + Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, + PLAYER_PARAMS(PLAYER_START_MODE_IDLE, PLAYER_START_BG_CAM_DEFAULT)); } gSaveContext.respawn[RESPAWN_MODE_DOWN].data = 0; return arg1; @@ -10271,7 +10273,8 @@ void Player_Action_80845EF8(Player* this, PlayState* play) { Room_FinishRoomChange(play, &play->roomCtx); } Camera_SetFinishedFlag(Play_GetCamera(play, CAM_ID_MAIN)); - Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, 0xDFF); + Play_SetupRespawnPoint(play, RESPAWN_MODE_DOWN, + PLAYER_PARAMS(PLAYER_START_MODE_IDLE, PLAYER_START_BG_CAM_DEFAULT)); } return; } @@ -10750,7 +10753,8 @@ void Player_Init(Actor* thisx, PlayState* play2) { } if (func_80845C68(play, (respawnFlag == 2) ? 1 : 0) == 0) { - gSaveContext.respawn[RESPAWN_MODE_DOWN].playerParams = PARAMS_GET_S(thisx->params, 0, 8) | 0xD00; + gSaveContext.respawn[RESPAWN_MODE_DOWN].playerParams = + PLAYER_PARAMS(PLAYER_START_MODE_IDLE, PLAYER_GET_START_BG_CAM_INDEX(thisx)); } gSaveContext.respawn[RESPAWN_MODE_DOWN].data = 1; @@ -13785,7 +13789,8 @@ void Player_Action_8084E3C4(Player* this, PlayState* play) { s32 pad; gSaveContext.respawn[RESPAWN_MODE_RETURN].entranceIndex = sWarpSongEntrances[play->msgCtx.lastPlayedSong]; - gSaveContext.respawn[RESPAWN_MODE_RETURN].playerParams = 0x5FF; + gSaveContext.respawn[RESPAWN_MODE_RETURN].playerParams = + PLAYER_PARAMS(PLAYER_START_MODE_WARP_SONG, PLAYER_START_BG_CAM_DEFAULT); gSaveContext.respawn[RESPAWN_MODE_RETURN].data = play->msgCtx.lastPlayedSong; this->csAction = PLAYER_CSACTION_NONE; @@ -14806,13 +14811,15 @@ void Player_Action_808507F4(Player* this, PlayState* play) { if (this->av2.actionVar2 == 0) { gSaveContext.respawn[RESPAWN_MODE_TOP].data = 1; - Play_SetupRespawnPoint(play, RESPAWN_MODE_TOP, 0x6FF); + Play_SetupRespawnPoint(play, RESPAWN_MODE_TOP, + PLAYER_PARAMS(PLAYER_START_MODE_FARORES_WIND, PLAYER_START_BG_CAM_DEFAULT)); gSaveContext.save.info.fw.set = 1; gSaveContext.save.info.fw.pos.x = gSaveContext.respawn[RESPAWN_MODE_DOWN].pos.x; gSaveContext.save.info.fw.pos.y = gSaveContext.respawn[RESPAWN_MODE_DOWN].pos.y; gSaveContext.save.info.fw.pos.z = gSaveContext.respawn[RESPAWN_MODE_DOWN].pos.z; gSaveContext.save.info.fw.yaw = gSaveContext.respawn[RESPAWN_MODE_DOWN].yaw; - gSaveContext.save.info.fw.playerParams = 0x6FF; + gSaveContext.save.info.fw.playerParams = + PLAYER_PARAMS(PLAYER_START_MODE_FARORES_WIND, PLAYER_START_BG_CAM_DEFAULT); gSaveContext.save.info.fw.entranceIndex = gSaveContext.respawn[RESPAWN_MODE_DOWN].entranceIndex; gSaveContext.save.info.fw.roomIndex = gSaveContext.respawn[RESPAWN_MODE_DOWN].roomIndex; gSaveContext.save.info.fw.tempSwchFlags = gSaveContext.respawn[RESPAWN_MODE_DOWN].tempSwchFlags;