Util: Implement PlayerPuppetFunction

[c4nvm]

Implements the whole Util/PlayerPuppetFunction.o object — all 82 functions matching (tools/check clean, check-format.py reports no issues).

These are the rs:: player-puppet utility functions: wrappers around the IUsePlayerPuppet interface, and — where they touch state — the concrete PlayerPuppet.

(This replaces the earlier partial version of this PR: per feedback that objects should be implemented whole rather than cherry-picking the easy functions, the object is now complete in a single PR.)

Supporting changes worth a closer look

• IUsePlayerPuppet stays a pure interface; the member-accessing wrappers static_cast to PlayerPuppet and go through accessors. I named the previously-placeholder flag members on PlayerPuppet (mIsValidLookAt, mIsValidForceLookAt, mIsValidSeparateMode, mIsValidRecoveryArea, mIsValidGuideArrow, mIsValidWaterSurfaceShadow, mIsInvalidReceivePush, mIsCopyDitherAlpha, mForceLookAtDir, mJudgePreInputJump) — happy to adjust any of these.
• Added the BindKeepDemoInfo struct.
• PlayerInput::getStickMoveRaw was declared as const sead::Vector2f&, but the function returns the vector by value (in s0/s1); changed it to return sead::Vector2f. This is required for rs::getPuppetMoveStick to match — clang 3.9.1 won't tail-call a reference-returning forward, but does for a value return.
• Carved a bool flag out of PlayerEffect (previously an opaque char filler) for rs::clearStainEffect; the field name is inferred.

Tracker: MonsterDruide1/OdysseyDecompTracker#1530

---

This change is 

---

Report for 1.0 (ae6bf40 - 204c822)

📈 Matched code: 15.34% (+0.02%, +2860 bytes)

✅ 82 new matches

Unit	Item	Bytes	Before	After
Util/PlayerPuppetFunction	rs::requestUpdateSafetyPoint(IUsePlayerPuppet*, al::LiveActor const*, IUsePlayerCollision const*)	+224	0.00%	100.00%
Util/PlayerPuppetFunction	rs::addPuppetVelocityFall(IUsePlayerPuppet*)	+188	0.00%	100.00%
Util/PlayerPuppetFunction	rs::tryStartBindKeepDemo(BindKeepDemoInfo*, al::SensorMsg const*, IUsePlayerPuppet const*)	+188	0.00%	100.00%
Util/PlayerPuppetFunction	rs::tryEndBindKeepDemo(BindKeepDemoInfo*, al::SensorMsg const*, IUsePlayerPuppet*)	+124	0.00%	100.00%
Util/PlayerPuppetFunction	rs::setPuppetFront(IUsePlayerPuppet*, sead::Vector3<float> const&)	+116	0.00%	100.00%
Util/PlayerPuppetFunction	rs::setPuppetUp(IUsePlayerPuppet*, sead::Vector3<float> const&)	+116	0.00%	100.00%
Util/PlayerPuppetFunction	rs::calcPuppetQuat(sead::Quat<float>*, IUsePlayerPuppet const*)	+112	0.00%	100.00%
Util/PlayerPuppetFunction	rs::syncPuppetVisibility(al::LiveActor*, IUsePlayerPuppet const*)	+100	0.00%	100.00%
Util/PlayerPuppetFunction	rs::forcePutOnPuppetCapWithEffect(IUsePlayerPuppet*)	+96	0.00%	100.00%
Util/PlayerPuppetFunction	rs::startPuppet(al::HitSensor*, al::HitSensor*)	+88	0.00%	100.00%
Util/PlayerPuppetFunction	rs::isPuppetInputSwing(IUsePlayerPuppet const*)	+72	0.00%	100.00%
Util/PlayerPuppetFunction	rs::endBindOnGroundAndPuppetNull(IUsePlayerPuppet**)	+64	0.00%	100.00%
Util/PlayerPuppetFunction	rs::endBindJumpAndPuppetNull(IUsePlayerPuppet**, sead::Vector3<float> const&, int)	+64	0.00%	100.00%
Util/PlayerPuppetFunction	rs::endBindWallJumpAndPuppetNull(IUsePlayerPuppet**, sead::Vector3<float> const&, int)	+60	0.00%	100.00%
Util/PlayerPuppetFunction	rs::isPuppetTriggerAnyButton(IUsePlayerPuppet const*)	+60	0.00%	100.00%
Util/PlayerPuppetFunction	rs::isPuppetHoldAnyButton(IUsePlayerPuppet const*)	+60	0.00%	100.00%
Util/PlayerPuppetFunction	rs::endBindCapThrow(IUsePlayerPuppet**)	+56	0.00%	100.00%
Util/PlayerPuppetFunction	rs::tryReceiveBindCancelMsgAndPuppetNull(IUsePlayerPuppet**, al::SensorMsg const*)	+56	0.00%	100.00%
Util/PlayerPuppetFunction	rs::startPuppetAction(IUsePlayerPuppet*, char const*)	+56	0.00%	100.00%
Util/PlayerPuppetFunction	rs::copyPuppetDitherAlpha(IUsePlayerPuppet*, al::LiveActor const*)	+56	0.00%	100.00%
Util/PlayerPuppetFunction	rs::initBindKeepDemoInfo()	+52	0.00%	100.00%
Util/PlayerPuppetFunction	rs::endBindAndPuppetNull(IUsePlayerPuppet**)	+48	0.00%	100.00%
Util/PlayerPuppetFunction	rs::forcePutOnPuppetCap(IUsePlayerPuppet*)	+40	0.00%	100.00%
Util/PlayerPuppetFunction	rs::validatePuppetForceLookAt(IUsePlayerPuppet*, sead::Vector3<float> const&)	+36	0.00%	100.00%
Util/PlayerPuppetFunction	rs::requestForceSafetyPoint(IUsePlayerPuppet*, sead::Vector3<float> const&, sead::Vector3<float> const&)	+32	0.00%	100.00%
Util/PlayerPuppetFunction	rs::getPuppetGravity(IUsePlayerPuppet const*)	+28	0.00%	100.00%
Util/PlayerPuppetFunction	rs::getPuppetVelocity(IUsePlayerPuppet const*)	+28	0.00%	100.00%
Util/PlayerPuppetFunction	rs::getPuppetTrans(IUsePlayerPuppet const*)	+28	0.00%	100.00%
Util/PlayerPuppetFunction	rs::getCollidedPuppetGroundNormal(IUsePlayerPuppet*)	+28	0.00%	100.00%
Util/PlayerPuppetFunction	rs::calcPuppetUp(sead::Vector3<float>*, IUsePlayerPuppet const*)	+24	0.00%	100.00%

...and 52 more new matches

[MonsterDruide1]

@MonsterDruide1 reviewed 6 files and all commit messages, and made 12 comments.
Reviewable status: all files reviewed, 12 unresolved discussions (waiting on c4nvm).

---

src/Util/PlayerPuppetFunction.cpp line 32 at r1 (raw file):

    sead::Vector3f mTrans;
    sead::Quatf mQuat;
};

[..]Info and no functions usually means it's a struct - the difference between class and struct is never visible, but this project follows the rule of "classes may never have member variables as public". So if things usually access the members directly instead of going through a getter, it's a struct.

Suggestion:

struct BindKeepDemoInfo {
    bool mIsActive = false;
    sead::Vector3f mTrans = {0.0f, 0.0f, 0.0f};
    sead::Quatf mQuat = sead::Quatf::unit;
};

---

src/Util/PlayerPuppetFunction.cpp line 132 at r1 (raw file):

        return true;
    }
    return false;

Suggestion:

    if (!al::isMsgBindCancel(msg))
        return false;
    
    *playerPuppet = nullptr;
    return true;

---

src/Util/PlayerPuppetFunction.cpp line 145 at r1 (raw file):

bool tryStartBindKeepDemo(BindKeepDemoInfo* bindKeepDemoInfo, const al::SensorMsg* msg,
                          const IUsePlayerPuppet* playerPuppet) {
    if (isMsgBindKeepDemoStart(msg)) {

Flip this condition

---

src/Util/PlayerPuppetFunction.cpp line 153 at r1 (raw file):

        playerPuppet->calcFront(&front);
        playerPuppet->calcUp(&up);
        al::makeQuatUpFront(quat, up, front);

Suggestion:

        calcPuppetQuat(&bindKeepDemoInfo->mQuat, playerPuppet);

---

src/Util/PlayerPuppetFunction.cpp line 161 at r1 (raw file):

bool tryEndBindKeepDemo(BindKeepDemoInfo* bindKeepDemoInfo, const al::SensorMsg* msg,
                        IUsePlayerPuppet* playerPuppet) {
    if (isMsgBindKeepDemoEnd(msg)) {

Flip this condition

---

src/Util/PlayerPuppetFunction.cpp line 166 at r1 (raw file):

        bindKeepDemoInfo->mIsActive = false;
        bindKeepDemoInfo->mTrans.set(0.0f, 0.0f, 0.0f);
        bindKeepDemoInfo->mQuat.set(1.0f, 0.0f, 0.0f, 0.0f);

might mismatch, please report if it does

Suggestion:

        bindKeepDemoInfo->mTrans = {0.0f, 0.0f, 0.0f};
        bindKeepDemoInfo->mQuat = {1.0f, 0.0f, 0.0f, 0.0f};

---

src/Util/PlayerPuppetFunction.cpp line 402 at r1 (raw file):

void setPuppetFront(IUsePlayerPuppet* playerPuppet, const sead::Vector3f& front) {
    sead::Vector3f up(0.0f, 0.0f, 0.0f);

Suggestion:

sead::Vector3f up = {0.0f, 0.0f, 0.0f};

---

src/Util/PlayerPuppetFunction.cpp line 410 at r1 (raw file):

void setPuppetUp(IUsePlayerPuppet* playerPuppet, const sead::Vector3f& up) {
    sead::Vector3f front(0.0f, 0.0f, 0.0f);

Suggestion:

sead::Vector3f front = {0.0f, 0.0f, 0.0f};

---

src/Util/PlayerPuppetFunction.cpp line 419 at r1 (raw file):

void calcPuppetQuat(sead::Quatf* quat, const IUsePlayerPuppet* playerPuppet) {
    sead::Vector3f front(0.0f, 0.0f, 0.0f);
    sead::Vector3f up(0.0f, 0.0f, 0.0f);

Suggestion:

    sead::Vector3f front = {0.0f, 0.0f, 0.0f};
    sead::Vector3f up = {0.0f, 0.0f, 0.0f};

---

src/Util/PlayerPuppetFunction.cpp line 465 at r1 (raw file):

    al::HitSensor* hitSensor = puppet->getHitSensor();
    sead::Vector3f safetyPoint(0.0f, 0.0f, 0.0f);
    sead::Vector3f safetyPointNormal(0.0f, 0.0f, 0.0f);

Suggestion:

    sead::Vector3f safetyPoint = {0.0f, 0.0f, 0.0f};
    sead::Vector3f safetyPointNormal = {0.0f, 0.0f, 0.0f};

---

src/Util/PlayerPuppetFunction.cpp line 472 at r1 (raw file):

        puppet->requestUpdateRecoveryInfo(true, false, safetyPoint, safetyPointNormal, areaObj);
    } else {
        bool collisionCode = false;

Suggestion:

bool isInAir = false;

---

src/Util/PlayerPuppetFunction.cpp line 477 at r1 (raw file):

                                               playerCollision);
        puppet->requestUpdateRecoveryInfo(false, collisionCode, safetyPoint, safetyPointNormal,
                                          areaObj);

Suggestion:

        // NOTE: might pass {0,0,0} as normal into this function
        puppet->requestUpdateRecoveryInfo(false, collisionCode, safetyPoint, safetyPointNormal,
                                          areaObj);