Doc dynapoly move flags (#1372)

* Doc dynapoly move flags

* Use `DYNAPOLYMOVE_UPD_` more

* remove `DynaPolyActor.unk_15A` (padding)

* `DYNAPOLYMOVE_UPD_` -> `DYNA_MOVE_`

* Remove `DYNA_MOVE_POS_AND_ROT_Y`

* Actual docs

* Update function names

* transformFlags and Carried names

Co-authored-by: fig02 <fig02srl@gmail.com>
Co-authored-by: EllipticEllipsis <elliptic.ellipsis@gmail.com>

* Fixup comment on `DynaPolyActor_UpdateCarriedActorPos`

* Format

* `DYNA_TRANSFORM_NONE` -> 0

* Touch up mentioning the `DYNA_TRANSFORM_` flags in docs

Co-authored-by: fig02 <fig02srl@gmail.com>
Co-authored-by: EllipticEllipsis <elliptic.ellipsis@gmail.com>

4 files changed, 37 insertions, 22 deletions

diff --git a/src/code/code_800430A0.c b/src/code/code_800430A0.c
index 95f7455ba..1ab9b5324 100644
--- a/src/code/code_800430A0.c
+++ b/src/code/code_800430A0.c
@@ -1,7 +1,10 @@
 #include "global.h"
 #include "vt.h"
 
-void func_800430A0(CollisionContext* colCtx, s32 bgId, Actor* actor) {
+/**
+ * Update the `carriedActor`'s position based on the dynapoly actor identified by `bgId`.
+ */
+void DynaPolyActor_UpdateCarriedActorPos(CollisionContext* colCtx, s32 bgId, Actor* carriedActor) {
     MtxF prevTransform;
     MtxF prevTransformInv;
     MtxF curTransform;
@@ -9,22 +12,30 @@ void func_800430A0(CollisionContext* colCtx, s32 bgId, Actor* actor) {
     Vec3f tempPos;
 
     if (DynaPoly_IsBgIdBgActor(bgId)) {
+
         SkinMatrix_SetTranslateRotateYXZScale(
             &prevTransform, colCtx->dyna.bgActors[bgId].prevTransform.scale.x,
             colCtx->dyna.bgActors[bgId].prevTransform.scale.y, colCtx->dyna.bgActors[bgId].prevTransform.scale.z,
             colCtx->dyna.bgActors[bgId].prevTransform.rot.x, colCtx->dyna.bgActors[bgId].prevTransform.rot.y,
             colCtx->dyna.bgActors[bgId].prevTransform.rot.z, colCtx->dyna.bgActors[bgId].prevTransform.pos.x,
             colCtx->dyna.bgActors[bgId].prevTransform.pos.y, colCtx->dyna.bgActors[bgId].prevTransform.pos.z);
+
         if (SkinMatrix_Invert(&prevTransform, &prevTransformInv) != 2) {
+
             SkinMatrix_SetTranslateRotateYXZScale(
                 &curTransform, colCtx->dyna.bgActors[bgId].curTransform.scale.x,
                 colCtx->dyna.bgActors[bgId].curTransform.scale.y, colCtx->dyna.bgActors[bgId].curTransform.scale.z,
                 colCtx->dyna.bgActors[bgId].curTransform.rot.x, colCtx->dyna.bgActors[bgId].curTransform.rot.y,
                 colCtx->dyna.bgActors[bgId].curTransform.rot.z, colCtx->dyna.bgActors[bgId].curTransform.pos.x,
                 colCtx->dyna.bgActors[bgId].curTransform.pos.y, colCtx->dyna.bgActors[bgId].curTransform.pos.z);
-            SkinMatrix_Vec3fMtxFMultXYZ(&prevTransformInv, &actor->world.pos, &tempPos);
+
+            // Apply the movement of the dynapoly actor `bgId` over the last frame to the `carriedActor` position
+            // pos = curTransform * prevTransformInv * pos
+            // Note (curTransform * prevTransformInv) represents the transform relative to the previous frame
+            SkinMatrix_Vec3fMtxFMultXYZ(&prevTransformInv, &carriedActor->world.pos, &tempPos);
             SkinMatrix_Vec3fMtxFMultXYZ(&curTransform, &tempPos, &pos);
-            actor->world.pos = pos;
+            carriedActor->world.pos = pos;
+
             if (BGCHECK_XYZ_ABSMAX <= pos.x || pos.x <= -BGCHECK_XYZ_ABSMAX || BGCHECK_XYZ_ABSMAX <= pos.y ||
                 pos.y <= -BGCHECK_XYZ_ABSMAX || BGCHECK_XYZ_ABSMAX <= pos.z || pos.z <= -BGCHECK_XYZ_ABSMAX) {
 
@@ -41,18 +52,18 @@ void func_800430A0(CollisionContext* colCtx, s32 bgId, Actor* actor) {
 }
 
 /**
- * Rotate actor
+ * Update the `carriedActor`'s Y rotation based on the dynapoly actor identified by `bgId`.
  */
-void func_800432A0(CollisionContext* colCtx, s32 bgId, Actor* actor) {
+void DynaPolyActor_UpdateCarriedActorRotY(CollisionContext* colCtx, s32 bgId, Actor* carriedActor) {
     if (DynaPoly_IsBgIdBgActor(bgId)) {
-        s16 rot = colCtx->dyna.bgActors[bgId].curTransform.rot.y - colCtx->dyna.bgActors[bgId].prevTransform.rot.y;
+        s16 rotY = colCtx->dyna.bgActors[bgId].curTransform.rot.y - colCtx->dyna.bgActors[bgId].prevTransform.rot.y;
 
-        if (actor->id == ACTOR_PLAYER) {
-            ((Player*)actor)->currentYaw += rot;
+        if (carriedActor->id == ACTOR_PLAYER) {
+            ((Player*)carriedActor)->currentYaw += rotY;
         }
 
-        actor->shape.rot.y += rot;
-        actor->world.rot.y += rot;
+        carriedActor->shape.rot.y += rotY;
+        carriedActor->world.rot.y += rotY;
     }
 }
 
@@ -70,14 +81,14 @@ void func_80043334(CollisionContext* colCtx, Actor* actor, s32 bgId) {
 }
 
 /**
- * Transform actor's position
- * `actor` is the actor to update
+ * Update the `carriedActor`'s position and Y rotation based on the dynapoly actor identified by `bgId`, according to
+ * the dynapoly actor's move flags (see `DYNA_TRANSFORM_POS` and `DYNA_TRANSFORM_ROT_Y`).
  */
-s32 func_800433A4(CollisionContext* colCtx, s32 bgId, Actor* actor) {
+s32 DynaPolyActor_TransformCarriedActor(CollisionContext* colCtx, s32 bgId, Actor* carriedActor) {
     s32 result = false;
     DynaPolyActor* dynaActor;
 
-    if (DynaPoly_IsBgIdBgActor(bgId) == false) {
+    if (!DynaPoly_IsBgIdBgActor(bgId)) {
         return false;
     }
 
@@ -91,13 +102,13 @@ s32 func_800433A4(CollisionContext* colCtx, s32 bgId, Actor* actor) {
         return false;
     }
 
-    if (dynaActor->unk_15C & 1) {
-        func_800430A0(colCtx, bgId, actor);
+    if (dynaActor->transformFlags & DYNA_TRANSFORM_POS) {
+        DynaPolyActor_UpdateCarriedActorPos(colCtx, bgId, carriedActor);
         result = true;
     }
 
-    if (dynaActor->unk_15C & 2) {
-        func_800432A0(colCtx, bgId, actor);
+    if (dynaActor->transformFlags & DYNA_TRANSFORM_ROT_Y) {
+        DynaPolyActor_UpdateCarriedActorRotY(colCtx, bgId, carriedActor);
         result = true;
     }
 
diff --git a/src/code/code_80043480.c b/src/code/code_80043480.c
index bcf2e0dd9..548ff4d0b 100644
--- a/src/code/code_80043480.c
+++ b/src/code/code_80043480.c
@@ -1,8 +1,12 @@
 #include "global.h"
 
-void DynaPolyActor_Init(DynaPolyActor* dynaActor, s32 flags) {
+/**
+ * @param transformFlags How other actors standing on the dynapoly actor's collision move when the dynapoly actor moves.
+ *   See `DYNA_TRANSFORM_POS`, `DYNA_TRANSFORM_ROT_Y`.
+ */
+void DynaPolyActor_Init(DynaPolyActor* dynaActor, s32 transformFlags) {
     dynaActor->bgId = -1;
-    dynaActor->unk_15C = flags;
+    dynaActor->transformFlags = transformFlags;
     dynaActor->interactFlags = 0;
     dynaActor->unk_150 = 0.0f;
     dynaActor->unk_154 = 0.0f;
diff --git a/src/code/z_actor.c b/src/code/z_actor.c
index 738fff1fb..ef5748d59 100644
--- a/src/code/z_actor.c
+++ b/src/code/z_actor.c
@@ -1238,7 +1238,7 @@ void Actor_UpdateBgCheckInfo(PlayState* play, Actor* actor, f32 wallCheckHeight,
     sp74 = actor->world.pos.y - actor->prevPos.y;
 
     if ((actor->floorBgId != BGCHECK_SCENE) && (actor->bgCheckFlags & BGCHECKFLAG_GROUND)) {
-        func_800433A4(&play->colCtx, actor->floorBgId, actor);
+        DynaPolyActor_TransformCarriedActor(&play->colCtx, actor->floorBgId, actor);
     }
 
     if (flags & UPDBGCHECKINFO_FLAG_0) {
diff --git a/src/code/z_en_a_keep.c b/src/code/z_en_a_keep.c
index ade2467f7..376476ca4 100644
--- a/src/code/z_en_a_keep.c
+++ b/src/code/z_en_a_keep.c
@@ -114,7 +114,7 @@ void EnAObj_Init(Actor* thisx, PlayState* play) {
     thisx->focus.pos = thisx->world.pos;
     this->dyna.bgId = BGACTOR_NEG_ONE;
     this->dyna.interactFlags = 0;
-    this->dyna.unk_15C = DPM_UNK;
+    this->dyna.transformFlags = 0;
     thisx->uncullZoneDownward = 1200.0f;
     thisx->uncullZoneScale = 200.0f;