From 3c16f534de369221f9f1d5d9542fd902b54743bc Mon Sep 17 00:00:00 2001
From: engineer124 <47598039+engineer124@users.noreply.github.com>
Date: Fri, 6 Dec 2024 15:48:38 +1100
Subject: [PATCH] Document Light-Based Actor Flags (#1754)

* light flags template

* first attempt

* typo

* improve names

* improve comments
---
 include/z64actor.h                            | 12 ++++++----
 src/code/z_actor.c                            |  8 +++++--
 src/code/z_lights.c                           | 24 +++++++++++--------
 .../ovl_Bg_Astr_Bombwall/z_bg_astr_bombwall.c |  2 +-
 .../ovl_Bg_Crace_Movebg/z_bg_crace_movebg.c   |  2 +-
 .../z_bg_ikana_bombwall.c                     |  2 +-
 .../ovl_Bg_Kin2_Bombwall/z_bg_kin2_bombwall.c |  2 +-
 .../ovl_Bg_Kin2_Shelf/z_bg_kin2_shelf.c       |  2 +-
 .../ovl_Bg_Market_Step/z_bg_market_step.c     |  2 +-
 .../actors/ovl_Door_Shutter/z_door_shutter.c  |  2 +-
 .../actors/ovl_Door_Spiral/z_door_spiral.c    |  2 +-
 .../z_en_horse_game_check.c                   |  2 +-
 src/overlays/actors/ovl_Obj_Bean/z_obj_bean.c |  2 +-
 .../actors/ovl_Obj_Dhouse/z_obj_dhouse.c      |  2 +-
 .../ovl_Obj_Spidertent/z_obj_spidertent.c     |  2 +-
 .../ovl_Obj_Tokei_Step/z_obj_tokei_step.c     |  2 +-
 tools/disasm/variables.txt                    |  4 ++--
 17 files changed, 43 insertions(+), 31 deletions(-)

diff --git a/include/z64actor.h b/include/z64actor.h
index 3bb6872c39..0faa4ff0dd 100644
--- a/include/z64actor.h
+++ b/include/z64actor.h
@@ -544,8 +544,11 @@ typedef enum DoorLockType {
 #define ACTOR_FLAG_100000        (1 << 20)
 // 
 #define ACTOR_FLAG_200000        (1 << 21)
-// 
-#define ACTOR_FLAG_400000        (1 << 22)
+
+// Specifies whether the actor can (not) use fake point lights, in the event that ucode point lights are not compatible with its display lists.
+// In F3DZEX2 versions that predate MM, microcode point lights didn't exist so `PointLight_t` could not be used.
+// Instead, fake point lights by using a directional light that constantly changes to face a reference position.
+#define ACTOR_FLAG_IGNORE_LEGACY_POINT_LIGHTS (1 << 22)
 
 // When Player is carrying this actor, it can only be thrown, not dropped/placed.
 // Typically an actor can only be thrown when moving, but this allows an actor to be thrown when standing still.
@@ -567,8 +570,9 @@ typedef enum DoorLockType {
 // Tatl will still be able to hover over the actor, assuming `ACTOR_FLAG_ATTENTION_ENABLED` is set.
 #define ACTOR_FLAG_LOCK_ON_DISABLED (1 << 27)
 
-// 
-#define ACTOR_FLAG_10000000      (1 << 28)
+// Specifies whether subsequent geometry is compatible with ucode point lights.
+// The current room must also enable point lights for point lights to take effect.
+#define ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED (1 << 28)
 
 // Signals that player has accepted an offer to use the ocarina to interact with an actor
 // An exception is made for EN_ZOT, see `Player_ActionHandler_13`.
diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 4ed9ead9bd..09ff56811d 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -2770,12 +2770,16 @@ void Actor_Draw(PlayState* play, Actor* actor) {
     OPEN_DISPS(play->state.gfxCtx);
 
     light = LightContext_NewLights(&play->lightCtx, play->state.gfxCtx);
-    if ((actor->flags & ACTOR_FLAG_10000000) && (play->roomCtx.curRoom.enablePosLights || (MREG(93) != 0))) {
+    if ((actor->flags & ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED) &&
+        (play->roomCtx.curRoom.enablePosLights || (MREG(93) != 0))) {
         light->enablePosLights = true;
     }
 
     Lights_BindAll(light, play->lightCtx.listHead,
-                   (actor->flags & (ACTOR_FLAG_10000000 | ACTOR_FLAG_400000)) ? NULL : &actor->world.pos, play);
+                   (actor->flags & (ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED | ACTOR_FLAG_IGNORE_LEGACY_POINT_LIGHTS))
+                       ? NULL
+                       : &actor->world.pos,
+                   play);
     Lights_Draw(light, play->state.gfxCtx);
 
     if (actor->flags & ACTOR_FLAG_IGNORE_QUAKE) {
diff --git a/src/code/z_lights.c b/src/code/z_lights.c
index bf13917e08..d7917a6786 100644
--- a/src/code/z_lights.c
+++ b/src/code/z_lights.c
@@ -191,8 +191,8 @@ void Lights_BindDirectional(Lights* lights, LightParams* params, void* unused) {
     }
 }
 
-typedef void (*LightsBindFunc)(Lights* lights, LightParams* params, Vec3f* vec);
-typedef void (*LightsPosBindFunc)(Lights* lights, LightParams* params, struct PlayState* play);
+typedef void (*LightsBindFuncLegacy)(Lights* lights, LightParams* params, Vec3f* vec);
+typedef void (*LightsBindFunc)(Lights* lights, LightParams* params, struct PlayState* play);
 
 /**
  * For every light in a provided list, try to find a free slot in the provided Lights group and bind
@@ -201,28 +201,32 @@ typedef void (*LightsPosBindFunc)(Lights* lights, LightParams* params, struct Pl
  *
  * Note: Lights in a given list can only be binded to however many free slots are
  * available in the Lights group. This is at most 7 slots for a new group, but could be less.
+ *
+ * Note: In F3DZEX2 versions that predate MM, microcode point lights didn't exist so `PointLight_t` could not be used.
+ * Instead, fake point lights by using a directional light that constantly changes to face a reference position.
+ * `sBindFuncs` maps to the new microcode point lights, and `sBindFuncsLegacy` maps to the old fake point lights.
  */
 void Lights_BindAll(Lights* lights, LightNode* listHead, Vec3f* refPos, PlayState* play) {
-    static LightsPosBindFunc sPosBindFuncs[] = {
+    static LightsBindFunc sBindFuncs[] = {
         Lights_BindPoint,
-        (LightsPosBindFunc)Lights_BindDirectional,
+        (LightsBindFunc)Lights_BindDirectional,
         Lights_BindPoint,
     };
-    static LightsBindFunc sDirBindFuncs[] = {
+    static LightsBindFuncLegacy sBindFuncsLegacy[] = {
         Lights_BindPointWithReference,
-        (LightsBindFunc)Lights_BindDirectional,
+        (LightsBindFuncLegacy)Lights_BindDirectional,
         Lights_BindPointWithReference,
     };
 
     if (listHead != NULL) {
         if ((refPos == NULL) && (lights->enablePosLights == 1)) {
             do {
-                sPosBindFuncs[listHead->info->type](lights, &listHead->info->params, play);
+                sBindFuncs[listHead->info->type](lights, &listHead->info->params, play);
                 listHead = listHead->next;
             } while (listHead != NULL);
         } else {
             do {
-                sDirBindFuncs[listHead->info->type](lights, &listHead->info->params, refPos);
+                sBindFuncsLegacy[listHead->info->type](lights, &listHead->info->params, refPos);
                 listHead = listHead->next;
             } while (listHead != NULL);
         }
@@ -400,7 +404,7 @@ void Lights_GlowCheck(PlayState* play) {
             worldPos.z = params->z;
             Actor_GetProjectedPos(play, &worldPos, &projectedPos, &invW);
 
-            params->drawGlow = 0;
+            params->drawGlow = false;
 
             if ((projectedPos.z > 1) && (fabsf(projectedPos.x * invW) < 1) && (fabsf(projectedPos.y * invW) < 1)) {
                 s32 screenPosX = PROJECTED_TO_SCREEN_X(projectedPos, invW);
@@ -409,7 +413,7 @@ void Lights_GlowCheck(PlayState* play) {
                 s32 zBuf = SysCfb_GetZBufferInt(screenPosX, screenPosY);
 
                 if (wZ < zBuf) {
-                    params->drawGlow = 1;
+                    params->drawGlow = true;
                 }
             }
         }
diff --git a/src/overlays/actors/ovl_Bg_Astr_Bombwall/z_bg_astr_bombwall.c b/src/overlays/actors/ovl_Bg_Astr_Bombwall/z_bg_astr_bombwall.c
index eeb52f04d8..a34924d836 100644
--- a/src/overlays/actors/ovl_Bg_Astr_Bombwall/z_bg_astr_bombwall.c
+++ b/src/overlays/actors/ovl_Bg_Astr_Bombwall/z_bg_astr_bombwall.c
@@ -109,7 +109,7 @@ void BgAstrBombwall_Init(Actor* thisx, PlayState* play) {
         Actor_Kill(&this->dyna.actor);
         return;
     }
-    this->dyna.actor.flags |= ACTOR_FLAG_10000000;
+    this->dyna.actor.flags |= ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED;
     if (!Collider_SetTris(play, &this->collider, &this->dyna.actor, &sTrisInit, this->colliderElements)) {
         Actor_Kill(&this->dyna.actor);
         return;
diff --git a/src/overlays/actors/ovl_Bg_Crace_Movebg/z_bg_crace_movebg.c b/src/overlays/actors/ovl_Bg_Crace_Movebg/z_bg_crace_movebg.c
index d9d9a67736..bf8b121e02 100644
--- a/src/overlays/actors/ovl_Bg_Crace_Movebg/z_bg_crace_movebg.c
+++ b/src/overlays/actors/ovl_Bg_Crace_Movebg/z_bg_crace_movebg.c
@@ -84,7 +84,7 @@ void BgCraceMovebg_Init(Actor* thisx, PlayState* play) {
     this->dyna.actor.world.rot.z = 0;
     this->dyna.actor.home.rot.x = 0;
     this->dyna.actor.home.rot.z = 0;
-    this->dyna.actor.flags |= ACTOR_FLAG_10000000;
+    this->dyna.actor.flags |= ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED;
 
     switch (BG_CRACE_MOVEBG_GET_TYPE(&this->dyna.actor)) {
         case BG_CRACE_MOVEBG_TYPE_CLOSING:
diff --git a/src/overlays/actors/ovl_Bg_Ikana_Bombwall/z_bg_ikana_bombwall.c b/src/overlays/actors/ovl_Bg_Ikana_Bombwall/z_bg_ikana_bombwall.c
index 584bae535e..ba106de13a 100644
--- a/src/overlays/actors/ovl_Bg_Ikana_Bombwall/z_bg_ikana_bombwall.c
+++ b/src/overlays/actors/ovl_Bg_Ikana_Bombwall/z_bg_ikana_bombwall.c
@@ -7,7 +7,7 @@
 #include "z_bg_ikana_bombwall.h"
 #include "assets/objects/object_ikana_obj/object_ikana_obj.h"
 
-#define FLAGS (ACTOR_FLAG_10000000)
+#define FLAGS (ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED)
 
 #define THIS ((BgIkanaBombwall*)thisx)
 
diff --git a/src/overlays/actors/ovl_Bg_Kin2_Bombwall/z_bg_kin2_bombwall.c b/src/overlays/actors/ovl_Bg_Kin2_Bombwall/z_bg_kin2_bombwall.c
index 1f58615b3d..d1e7774c51 100644
--- a/src/overlays/actors/ovl_Bg_Kin2_Bombwall/z_bg_kin2_bombwall.c
+++ b/src/overlays/actors/ovl_Bg_Kin2_Bombwall/z_bg_kin2_bombwall.c
@@ -6,7 +6,7 @@
 #include "z_bg_kin2_bombwall.h"
 #include "assets/objects/object_kin2_obj/object_kin2_obj.h"
 
-#define FLAGS (ACTOR_FLAG_10 | ACTOR_FLAG_10000000)
+#define FLAGS (ACTOR_FLAG_10 | ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED)
 
 #define THIS ((BgKin2Bombwall*)thisx)
 
diff --git a/src/overlays/actors/ovl_Bg_Kin2_Shelf/z_bg_kin2_shelf.c b/src/overlays/actors/ovl_Bg_Kin2_Shelf/z_bg_kin2_shelf.c
index e49b1061ef..59980fc8f3 100644
--- a/src/overlays/actors/ovl_Bg_Kin2_Shelf/z_bg_kin2_shelf.c
+++ b/src/overlays/actors/ovl_Bg_Kin2_Shelf/z_bg_kin2_shelf.c
@@ -204,7 +204,7 @@ void BgKin2Shelf_Init(Actor* thisx, PlayState* play) {
         this->dyna.actor.uncullZoneScale = 250.0f;
         this->dyna.actor.uncullZoneDownward = 300.0f;
         Actor_SetScale(&this->dyna.actor, 1.0f);
-        this->dyna.actor.flags |= ACTOR_FLAG_10000000;
+        this->dyna.actor.flags |= ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED;
     }
 
     DynaPolyActor_Init(&this->dyna, DYNA_TRANSFORM_POS);
diff --git a/src/overlays/actors/ovl_Bg_Market_Step/z_bg_market_step.c b/src/overlays/actors/ovl_Bg_Market_Step/z_bg_market_step.c
index 28f879c29f..8ac1130906 100644
--- a/src/overlays/actors/ovl_Bg_Market_Step/z_bg_market_step.c
+++ b/src/overlays/actors/ovl_Bg_Market_Step/z_bg_market_step.c
@@ -7,7 +7,7 @@
 #include "z_bg_market_step.h"
 #include "assets/objects/object_market_obj/object_market_obj.h"
 
-#define FLAGS (ACTOR_FLAG_20 | ACTOR_FLAG_10000000)
+#define FLAGS (ACTOR_FLAG_20 | ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED)
 
 #define THIS ((BgMarketStep*)thisx)
 
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 08c73bb315..1444dbcd36 100644
--- a/src/overlays/actors/ovl_Door_Shutter/z_door_shutter.c
+++ b/src/overlays/actors/ovl_Door_Shutter/z_door_shutter.c
@@ -218,7 +218,7 @@ void DoorShutter_Init(Actor* thisx, PlayState* play2) {
 
         sp24 = shutterSceneInfo->index;
         if (sp24 == 6) {
-            this->slidingDoor.dyna.actor.flags |= ACTOR_FLAG_10000000;
+            this->slidingDoor.dyna.actor.flags |= ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED;
         }
     } else if (sp24 == 0) {
         BossDoorInfo* bossDoorInfo = &D_808A22A0[0];
diff --git a/src/overlays/actors/ovl_Door_Spiral/z_door_spiral.c b/src/overlays/actors/ovl_Door_Spiral/z_door_spiral.c
index f51490e456..1286430aa6 100644
--- a/src/overlays/actors/ovl_Door_Spiral/z_door_spiral.c
+++ b/src/overlays/actors/ovl_Door_Spiral/z_door_spiral.c
@@ -103,7 +103,7 @@ s32 func_809A2B70(DoorSpiral* this, PlayState* play) {
         if (this->unk148 == 2) {
             this->unk148 = 3;
         }
-        this->actor.flags |= ACTOR_FLAG_10000000;
+        this->actor.flags |= ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED;
     }
     DoorSpiral_SetupAction(this, func_809A2FF8);
     return 0;
diff --git a/src/overlays/actors/ovl_En_Horse_Game_Check/z_en_horse_game_check.c b/src/overlays/actors/ovl_En_Horse_Game_Check/z_en_horse_game_check.c
index 7a378f878b..93ebf3d98c 100644
--- a/src/overlays/actors/ovl_En_Horse_Game_Check/z_en_horse_game_check.c
+++ b/src/overlays/actors/ovl_En_Horse_Game_Check/z_en_horse_game_check.c
@@ -57,7 +57,7 @@ s32 func_808F8AA0(EnHorseGameCheck* this, PlayState* play) {
     MtxF sp38;
 
     this->dyna.actor.scale.x = this->dyna.actor.scale.y = this->dyna.actor.scale.z = this->unk_160 * 0.001f;
-    this->dyna.actor.flags |= ACTOR_FLAG_400000;
+    this->dyna.actor.flags |= ACTOR_FLAG_IGNORE_LEGACY_POINT_LIGHTS;
 
     DynaPolyActor_Init(&this->dyna, 0);
 
diff --git a/src/overlays/actors/ovl_Obj_Bean/z_obj_bean.c b/src/overlays/actors/ovl_Obj_Bean/z_obj_bean.c
index 0b811f7457..209f04910b 100644
--- a/src/overlays/actors/ovl_Obj_Bean/z_obj_bean.c
+++ b/src/overlays/actors/ovl_Obj_Bean/z_obj_bean.c
@@ -8,7 +8,7 @@
 #include "assets/objects/object_mamenoki/object_mamenoki.h"
 #include "assets/objects/gameplay_keep/gameplay_keep.h"
 
-#define FLAGS (ACTOR_FLAG_400000)
+#define FLAGS (ACTOR_FLAG_IGNORE_LEGACY_POINT_LIGHTS)
 
 #define THIS ((ObjBean*)thisx)
 
diff --git a/src/overlays/actors/ovl_Obj_Dhouse/z_obj_dhouse.c b/src/overlays/actors/ovl_Obj_Dhouse/z_obj_dhouse.c
index 64d2155e77..b90d5e98b9 100644
--- a/src/overlays/actors/ovl_Obj_Dhouse/z_obj_dhouse.c
+++ b/src/overlays/actors/ovl_Obj_Dhouse/z_obj_dhouse.c
@@ -8,7 +8,7 @@
 #include "z64quake.h"
 #include "assets/objects/object_dhouse/object_dhouse.h"
 
-#define FLAGS (ACTOR_FLAG_10 | ACTOR_FLAG_400000)
+#define FLAGS (ACTOR_FLAG_10 | ACTOR_FLAG_IGNORE_LEGACY_POINT_LIGHTS)
 
 #define THIS ((ObjDhouse*)thisx)
 
diff --git a/src/overlays/actors/ovl_Obj_Spidertent/z_obj_spidertent.c b/src/overlays/actors/ovl_Obj_Spidertent/z_obj_spidertent.c
index 5b7f26ecb7..93bd5d79ee 100644
--- a/src/overlays/actors/ovl_Obj_Spidertent/z_obj_spidertent.c
+++ b/src/overlays/actors/ovl_Obj_Spidertent/z_obj_spidertent.c
@@ -7,7 +7,7 @@
 #include "z_obj_spidertent.h"
 #include "assets/objects/object_spidertent/object_spidertent.h"
 
-#define FLAGS (ACTOR_FLAG_10000000)
+#define FLAGS (ACTOR_FLAG_UCODE_POINT_LIGHT_ENABLED)
 
 #define THIS ((ObjSpidertent*)thisx)
 
diff --git a/src/overlays/actors/ovl_Obj_Tokei_Step/z_obj_tokei_step.c b/src/overlays/actors/ovl_Obj_Tokei_Step/z_obj_tokei_step.c
index 54f239f822..0381b9b895 100644
--- a/src/overlays/actors/ovl_Obj_Tokei_Step/z_obj_tokei_step.c
+++ b/src/overlays/actors/ovl_Obj_Tokei_Step/z_obj_tokei_step.c
@@ -9,7 +9,7 @@
 #include "z64rumble.h"
 #include "assets/objects/object_tokei_step/object_tokei_step.h"
 
-#define FLAGS (ACTOR_FLAG_10 | ACTOR_FLAG_400000)
+#define FLAGS (ACTOR_FLAG_10 | ACTOR_FLAG_IGNORE_LEGACY_POINT_LIGHTS)
 
 #define THIS ((ObjTokeiStep*)thisx)
 
diff --git a/tools/disasm/variables.txt b/tools/disasm/variables.txt
index 0e1f3a4067..bb6aaf9930 100644
--- a/tools/disasm/variables.txt
+++ b/tools/disasm/variables.txt
@@ -977,8 +977,8 @@
     0x801BEA1C:("sHeartsDDEnvFactors","s16","[3][3]",0x12),
     0x801BEA30:("sHeartTextures","UNK_TYPE1","",0x1),
     0x801BEA70:("sHeartDDTextures","UNK_TYPE1","",0x1),
-    0x801BEAB0:("sPosBindFuncs","LightsPosBindFunc","[3]",0xc),
-    0x801BEABC:("sDirBindFuncs","LightsBindFunc","[3]",0xc),
+    0x801BEAB0:("sBindFuncs","LightsBindFunc","[3]",0xc),
+    0x801BEABC:("sBindFuncsLegacy","LightsBindFuncLegacy","[3]",0xc),
     0x801BEAD0:("D_801BEAD0","s32","[4]",0x10),
     0x801BEAE0:("D_801BEAE0","s32","[4]",0x10),
     0x801BEAF0:("D_801BEAF0","u32","[4]",0x10),