Document Sequence Modes and Related Functions

[engineer124]

This PR introduced the following enum for sequence modes:

typedef enum {
    /* 0 */ SEQ_MODE_DEFAULT,
    /* 1 */ SEQ_MODE_ENEMY,
    /* 2 */ SEQ_MODE_STILL, // Not moving or first-person view
    /* 3 */ SEQ_MODE_IGNORE
} SequenceMode;

Sequence modes 0 & 2 are heavily used by hyrule field sequence logic, as slightly altered bgms will play depending on if LInk moving, standing still, or even near an enemy.

Sequence mode 1 is related to the enemy bgm played that gets louder as you approach generic enemies. Many functions and struct names related to this enemy bgm are named as well.

Sequence mode 3 is primarily used to skip mode of the Audio_SetSequenceMode code and functionality, and is related to turning off generic enemy music instantly (for example, when the upgraded mini-boss bgm starts playing).

This adds a small amount of docs to Audio, Player, and Actor as they all play small parts in managing these different sequence modes

[Roman971]

Calling an actor pointer nearestEnemyBgm doesn't feel right to me, is it intended?

[engineer124]

It's the name I came up with yeah, but open to brainstorming a better one. Since it's a pointer to an actor, I guess it should probably end in enemy. Actor* nearestBgmEnemy?

[Roman971]

Having both "nearest" and "bgm" in the name doesn't make much sense to me. I think it could make more sense as simply the nearest enemy actor (used for bgm but possibly other things as well). Same for sNearestEnemyBgmDistSq

[engineer124]

From my understanding, this does not track all/generic enemies as you specifically need both the ACTOR_FLAG_0 (targetable) and ACTOR_FLAG_2 (0x4 is documented as the enemy bgm flag) to count as an enemy that plays the enemy bgm as you approach. Not all enemies have the ACTOR_FLAG_2 flag, so this is not pointing to a generic enemy, but rather a subset relating to bgm enemies.

That being said, there might be more to this as well. I just checked out @Dragorn421 ACTOR_FLAG PR to see if anything else is going on with ACTOR_FLAG_2 that hasn't been reported yet. It does seem to do slightly more. In actor, the only other function it serves is to be required play the enemy target sfx instead of the "human" lock on sfx.

In player, it's also related to state flags stateFlags1 & 0x10, stateFlags1 & 0x10000, and stateFlags2 & 0x2000. So that's interesting to me.

[fig02]

this is from the speedrunning communities notes so take with a grain of salt, but 0x10 is targeting an enemy, 0x10000 is targeting anything(?) and flags2 & 0x2000 is targeting something with switch targeting enabled specifically

[Roman971]

It makes sense in the most part, tho I'm not sure if we should trust the existing documentation on the enemy bgm flag part, but yeah if it's specifically for enemies with a bgm, then nearestBgmEnemy is probably fine

[engineer124]

That's fair to be cautious of the existing docs, but my current knowledge is entirely from the repo now. Setting the "nearestBgmEnemy", the target sfx, and the three stateFlags "possibly" related to targeting (haven't fully confirmed that myself, just the relation to the stateflags) seems to be the full usage of ACTOR_FLAG_2, assuming no instances were missed.

Other alternatives could be something like closestBgmEnemy or possibly just bgmEnemy if those sound nicer to you

[Roman971]

Does the audio system care about whether it's the nearest enemy? If not then bgmEnemy could be good enough yeah

[fig02]

I think a good compromise could be bgmEnemy with a brief comment explaining that its always going to be the closest one to you.
The audio system doesnt seem to care, but it is a variable in the actor context so the implementation of it in the actor system is a little bit relevant in that regard imo

[engineer124]

The single parameter that the audio system cares about is "distance" to the nearest bgm enemy i.e.:
Audio_SetNearestEnemyBgmVolume(sqrtf(globalCtx->actorCtx.targetCtx.nearestEnemyBgm->xyzDistToPlayerSq));

This distance is used in setting both the volume of the "BGM_ENEMY" played on the sub-bgm player, but is also relevant to how the channels are split between the main-bgm player (for example, the dungeon music when no enemies are around) and the sub-bgm player.

I suppose it'd be fine just leaving it as bgmEnemy with the extra comment. There are a few places to remove the Nearest part, I'll try to add comments where necessary