Skip to content

Documentation pass on WaterBox code #1860

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mzxrules wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Documentation pass on WaterBox code #1860

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4f948f7
Documentation pass on WaterBox code
mzxrules Feb 17, 2026
ace8c96
format
mzxrules Feb 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 20 additions & 20 deletions include/z64bgcheck.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,15 +30,19 @@ struct DynaPolyActor;
#define BGCHECK_SUBDIV_MIN 150.0f

// Macros for `WaterBox.properties`
#define WATERBOX_LIGHT_INDEX_NONE 0x1F // warns and defaults to 0
#define WATERBOX_ROOM(p) ((((s32)p) >> 13) & 0x3F)
#define WATERBOX_ROOM_ALL 0x3F // value for "room index" indicating "all rooms"
#define WATERBOX_FLAG_19 (1 << 19)
#define WATERBOX_PROPERTIES(bgCamIndex, lightIndex, room, setFlag19) \
#define WATERBOX_PROPERTIES(bgCamIndex, lightIndex, roomIndex, isDisabled) \
((((bgCamIndex) & 0xFF) << 0) | \
(((lightIndex) & 0x1F) << 8) | \
(((room) & 0x3F) << 13) | \
(((setFlag19) & 1) << 19))
(((roomIndex) & 0x3F) << 13) | \
(((isDisabled) & 1) << 19))

#define WATERBOX_LIGHT_INDEX_NONE 0x1F // Generates warning when built for debug and defaults to 0
Copy link
Copy Markdown
Collaborator

@AngheloAlf AngheloAlf Feb 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What warning??

Copy link
Copy Markdown
Contributor Author

@mzxrules mzxrules Feb 18, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In Environment_EnableUnderwaterLights in z_kankyo.c, there is a PRINTF in Ocarina that generates an error message when DEBUG_FEATURES is enabled. It is unlikely this message has been removed in og source, but it currently does not appear in MM decomp

Copy link
Copy Markdown
Collaborator

@AngheloAlf AngheloAlf Feb 19, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, you mean a printf. I thought you meant a compilation warning.
I think we should word this part a bit different to avoid confusion, specially because that printf is not in this repo (yet?)

#define WATERBOX_ROOM(properties) (((properties) >> 13) & 0x3F) // retrieves the room the waterbox is active in
#define WATERBOX_ROOM_ALL 0x3F // value for "roomIndex" indicating "all rooms"

/* The true purpose of the flag is unknown. The state is never enabled on any waterbox, and functions that
* pass on flag enabled are never called, so there is no direct usecase context. */
#define WATERBOX_IS_DISABLED (1 << 19) // Disables collision for the WaterBox

// bccFlags (bgcheck check flags)
#define BGCHECK_CHECK_WALL (1 << 0)
Expand Down Expand Up @@ -131,14 +135,10 @@ typedef struct {
} BgCamFuncData; // size = 0x12

typedef struct {
/* 0x0 */ Vec3s minPos;
/* 0x0 */ Vec3s minPos; // y = water surface. Water is effectively infinitely deep.
/* 0x6 */ s16 xLength;
/* 0x8 */ s16 zLength;
/* 0xC */ u32 properties;
// 0x0008_0000 = ?
// 0x0007_E000 = room index, 0x3F = all rooms
// 0x0000_1F00 = lighting setting index
// 0x0000_00FF = bgCam index
} WaterBox; // size = 0x10

typedef enum FloorType {
Expand Down Expand Up @@ -296,7 +296,7 @@ typedef struct CollisionHeader {

typedef struct {
/* 0x0 */ s16 polyId;
/* 0x2 */ u16 next; // index of the next SSNode in the list, or SS_NULL if last element
/* 0x2 */ u16 next; // index of the next SSNode in the list, or SS_NULL if last element
} SSNode; // size = 0x4

// represents a linked list of type SSNode
Expand Down Expand Up @@ -612,16 +612,16 @@ s32 func_800C9DDC(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId);
ConveyorSpeed SurfaceType_GetConveyorSpeed(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId);
u32 SurfaceType_GetConveyorDirection(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId);
u32 SurfaceType_IsWallDamage(CollisionContext* colCtx, CollisionPoly* poly, s32 bgId);
s32 WaterBox_GetSurfaceImpl(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* ySurface, WaterBox** outWaterBox, s32* bgId);
s32 WaterBox_GetSurface1(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* ySurface, WaterBox** outWaterBox);
s32 WaterBox_GetSurface1_2(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* ySurface, WaterBox** outWaterBox);
s32 WaterBox_GetSurface2(struct PlayState* play, CollisionContext* colCtx, Vec3f* pos, f32 surfaceCheckDist, WaterBox** outWaterBox, s32* bgId);
f32 func_800CA568(CollisionContext* colCtx, s32 waterBoxId, s32 bgId);
s32 BgCheck_GetWaterSurface(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* outWaterSurface, WaterBox** outWaterBox, s32* outBgId);
s32 BgCheck_GetWaterSurfaceNoBgIdAlt(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* outWaterSurface, WaterBox** outWaterBox);
s32 BgCheck_GetWaterSurfaceNoBgId(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* outWaterSurface, WaterBox** outWaterBox);
s32 BgCheck_FindWaterBox(struct PlayState* play, CollisionContext* colCtx, Vec3f* pos, f32 surfaceCheckDist, WaterBox** outWaterBox, s32* outBgId);
f32 WaterBox_GetSurface(CollisionContext* colCtx, s32 waterBoxId, s32 bgId);
u16 WaterBox_GetBgCamSetting(CollisionContext* colCtx, WaterBox* waterBox, s32 bgId);
void WaterBox_GetSceneBgCamSetting(CollisionContext* colCtx, WaterBox* waterBox);
u32 WaterBox_GetLightSettingIndex(CollisionContext* colCtx, WaterBox* waterBox);
s32 func_800CA6F0(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* ySurface, WaterBox** outWaterBox, s32* bgId);
s32 func_800CA9D0(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* ySurface, WaterBox** outWaterBox);
s32 func_800CA6F0(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* outWaterSurface, WaterBox** outWaterBox, s32* outBgId);
s32 func_800CA9D0(struct PlayState* play, CollisionContext* colCtx, f32 x, f32 z, f32* outWaterSurface, WaterBox** outWaterBox);
s32 func_800CAA14(CollisionPoly* polyA, CollisionPoly* polyB, Vec3f* pointA, Vec3f* pointB, Vec3f* closestPoint);

#endif
6 changes: 4 additions & 2 deletions src/code/z_actor.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1729,7 +1729,8 @@ void Actor_UpdateBgCheckInfo(PlayState* play, Actor* actor, f32 wallCheckHeight,
func_800B7678(play, actor, &pos, updBgCheckInfoFlags);
y = actor->world.pos.y;

if (WaterBox_GetSurface1(play, &play->colCtx, actor->world.pos.x, actor->world.pos.z, &y, &waterbox)) {
if (BgCheck_GetWaterSurfaceNoBgIdAlt(play, &play->colCtx, actor->world.pos.x, actor->world.pos.z, &y,
&waterbox)) {
actor->depthInWater = y - actor->world.pos.y;
if (actor->depthInWater <= 0.0f) {
actor->bgCheckFlags &= ~(BGCHECKFLAG_WATER | BGCHECKFLAG_WATER_TOUCH);
Expand Down Expand Up @@ -1759,7 +1760,8 @@ void Actor_UpdateBgCheckInfo(PlayState* play, Actor* actor, f32 wallCheckHeight,
WaterBox* waterbox;
f32 y = actor->world.pos.y;

if (WaterBox_GetSurface1(play, &play->colCtx, actor->world.pos.x, actor->world.pos.z, &y, &waterbox)) {
if (BgCheck_GetWaterSurfaceNoBgIdAlt(play, &play->colCtx, actor->world.pos.x, actor->world.pos.z, &y,
&waterbox)) {
actor->depthInWater = y - actor->world.pos.y;

if (actor->depthInWater < 0.0f) {
Expand Down
Loading