Document Actor Flags #1122

fig02 · 2022-01-26T02:32:07Z

This gives a name to every actor flag.

Some minor things were changed along with the flags, for example skyboxOffset -> quakeOffset which was discovered while figuring out how the flag worked

EllipticEllipsis

Just a lot of grammar in the new comments in z64actor.h for now. It seems to me that it should be Player over player everywhere, too, since it's referring to the actual actor (and not the person at the controls).

include/z64actor.h

fig02 · 2022-01-26T04:35:01Z

include/z64actor.h

+#define ACTOR_FLAG_NO_UPDATE_CULLING (1 << 4) // actor will keep updating even if outside of the uncull zone
+#define ACTOR_FLAG_NO_DRAW_CULLING (1 << 5) // actor will keep drawing even if outside of the uncull zone
+#define ACTOR_FLAG_NOT_CULLED (1 << 6) // actor is in the uncull zone. flag still updates regardless of the update/draw cull exclusion flags


I would be fine with changing "uncull zone" to "active zone" in general, it may help with all the negative words going on here that make this system confusing. uncull zone is a name i was never happy with since the beginning.
in that case I would also change ACTOR_FLAG_NOT_CULLED -> ACTOR_FLAG_IN_ACTIVE_ZONE

also, long conversation regarding these flags in general for anyone else who wants to talk about these https://discord.com/channels/688807550715560050/688851317593997489/935729171529887754

imo i would rather keep the first two as is, and rename the last one according to my suggestion above

A summary of how these three flags work:

An actor is "culled" when it is outside the "uncull zone" defined by the three uncullZone* members in the Actor struct.

An actor being culled or not is indicated by ACTOR_FLAG_6/ACTOR_FLAG_IN_UNCULL_ZONE being set (actor is not culled) or cleared (actor is culled).

The set/clear state of this flag is updated every frame between actor update and actor draw (right before draw):
https://github.com/fig02/oot/blob/7774a67ea79076099820a6386a6a5b21c2ee5949/src/code/z_actor.c#L2421-L2425 :

if (func_800314B0(globalCtx, actor)) { actor->flags |= ACTOR_FLAG_IN_UNCULL_ZONE; } else { actor->flags &= ~ACTOR_FLAG_IN_UNCULL_ZONE; }

When an actor is culled, by default its update and draw functions don't run.
This behavior can be overriden by setting the ACTOR_FLAG_4/ACTOR_FLAG_NO_UPDATE_CULLING and/or ACTOR_FLAG_5/ACTOR_FLAG_NO_DRAW_CULLING to make update and draw run regardless of the actor being culled.

Comments:

ACTOR_FLAG_NO_UPDATE_CULLING/draw one can't be "always update"/draw because frozen (freezeTimer) actors still don't update. This set of flag is "culling"-specific

"no X culling" means "do not apply culling for x" if that's clearer. Wording is hard, suggestions appreciated

Suggestions also appreciated on the "cull", "uncull" words if they can be replaced

src/code/z_player_lib.c

src/code/z_actor.c

Dragorn421 · 2022-01-26T20:34:43Z

src/code/z_actor.c

@@ -2932,11 +2938,13 @@ void func_800328D4(GlobalContext* globalCtx, ActorContext* actorCtx, Player* pla
    sp84 = player->unk_664;

    while (actor != NULL) {
-        if ((actor->update != NULL) && ((Player*)actor != player) && CHECK_FLAG_ALL(actor->flags, ACTOR_FLAG_0)) {
+        if ((actor->update != NULL) && ((Player*)actor != player) &&
+            CHECK_FLAG_ALL(actor->flags, ACTOR_FLAG_TARGETABLE)) {


Also not a fan of naming this one with the whole target context and relevant player code being undocumented. But at least this one is somewhat straightforward, so it may be fine

same for ACTOR_FLAG_CANT_TARGET (also it's unclear if the flags need to be combined, if they do cant_target shouldn't be a straight negation)

targetable encompasses the whole mechanism of navi flying over something and the player being able to target it.
the CANT_TARGET flag makes it so you cant target it, but navi can still fly over it. I agree that its confusing but didnt have any other way to phrase it
a better way to phrase it might be CANT_LOCK_ON or something, but people would generally call that targeting

maybe "target_focus_only"? something that makes it sound like it's taking a specific thing away compared to the targeting flag alone

i would argue focus sounds like the targeting/locking on part, which is what is being disabled here

src/overlays/actors/ovl_Arms_Hook/z_arms_hook.c

Dragorn421 · 2022-01-27T13:15:13Z

src/overlays/actors/ovl_En_Si/z_en_si.c


-    if (CHECK_FLAG_ALL(this->actor.flags, ACTOR_FLAG_13)) {
+    if (CHECK_FLAG_ALL(this->actor.flags, ACTOR_FLAG_HOOK_ATTACHED)) {


A comment about this also being boomerang would be useful

something like "this flag is also set by boomerang for EnSi specifically"

imo en_si doesnt really care about that, the hack is the boomerang using it

I feel like someone reading ensi code would appreciate knowing this also handles boomerang. I think it's worth documenting since the code works with more than hookshot (kind of unintendedly so?)

src/overlays/actors/ovl_player_actor/z_player.c

include/z64actor.h

Dragorn421 · 2022-01-28T16:43:04Z

include/z64actor.h

+#define ACTOR_FLAG_SFX_CENTERED (1 << 21) // play sound from sfx field at the center of the screen
+#define ACTOR_FLAG_IGNORE_POINT_LIGHTS (1 << 22) // ignores point lights but not directional lights (such as environment lights)
+#define ACTOR_FLAG_ALWAYS_THROW (1 << 23) // Player throws held actor even if standing still
+#define ACTOR_FLAG_PLAY_BODYHIT_SFX (1 << 24) // when actor hits Player's body, a thump sfx plays


Is the "body" part of this important? I'd rather have it be "playerhit"
I would kind of prefer _PLAYERHIT_SFX or _PLAYERHIT_PLAY_SFX, not sure

_HITPLAYER_PLAY_SFX... idk

the name comes from the original sfx name which is bodyhit
I think it does help, there are many sounds you could take to mean a hit sfx. but bodyhit is the thump noise against his body

Dragorn421 · 2022-01-28T16:44:32Z

include/z64actor.h

+#define ACTOR_FLAG_HOOK_ATTACHED (1 << 13) // hookshot has attached to the actor (either a collider or surface)
+#define ACTOR_FLAG_ARROW_CAN_CARRY (1 << 14) // when an arrow hits the actor it will attach to the actor and carry it
+#define ACTOR_FLAG_ARROW_IS_CARRYING (1 << 15) // an arrow is currently carrying this actor
+#define ACTOR_FLAG_IMMEDIATE_TALK (1 << 16) // forces Player to talk when in range. needs to be unset manually to avoid infinite talking


For symmetry with ACTOR_FLAG_TALK_REQUESTED this could be ACTOR_FLAG_TALK_IMMEDIATE

also

Suggested change

#define ACTOR_FLAG_IMMEDIATE_TALK (1 << 16) // forces Player to talk when in range. needs to be unset manually to avoid infinite talking

#define ACTOR_FLAG_IMMEDIATE_TALK (1 << 16) // forces Player to talk when in range. Needs to be unset manually to avoid infinite talking

In general for these comments it may be nicer to capitalize the sentences and add punctuation

also
Just for curiosity what kind of range are we talking about? 10, 100, 1000 units? I can't find the relevant piece of code

actors broadcast their ability to talk with func_8002F2CC and other related functions. they specify their own range, its not fixed

Dragorn421 · 2022-01-28T17:01:00Z

src/overlays/actors/ovl_En_Bb/z_en_bb.c

@@ -1232,7 +1233,7 @@ void EnBb_Update(Actor* thisx, GlobalContext* globalCtx2) {
    if (this->actor.colChkInfo.damageEffect != 0xD) {
        this->actionFunc(this, globalCtx);
        if ((this->actor.params <= ENBB_BLUE) && (this->actor.speedXZ >= -6.0f) &&
-            ((this->actor.flags & ACTOR_FLAG_15) == 0)) {
+            ((this->actor.flags & ACTOR_FLAG_ARROW_IS_CARRYING) == 0)) {


Suggested change

((this->actor.flags & ACTOR_FLAG_ARROW_IS_CARRYING) == 0)) {

!(this->actor.flags & ACTOR_FLAG_ARROW_IS_CARRYING)) {

Dragorn421 · 2022-01-28T17:03:49Z

src/overlays/actors/ovl_Elf_Msg2/z_elf_msg2.c

@@ -134,7 +135,8 @@ void ElfMsg2_WaitUntilActivated(ElfMsg2* this, GlobalContext* globalCtx) {
    if ((this->actor.world.rot.y >= 0x41) && (this->actor.world.rot.y <= 0x80) &&
        (Flags_GetSwitch(globalCtx, (this->actor.world.rot.y - 0x41)))) {
        ElfMsg2_SetupAction(this, ElfMsg2_WaitForTextRead);
-        this->actor.flags |= ACTOR_FLAG_0 | ACTOR_FLAG_18; // Make actor targetable and Navi-checkable
+        this->actor.flags |=
+            ACTOR_FLAG_TARGETABLE | ACTOR_FLAG_CHECK_WITH_NAVI; // Make actor targetable and Navi-checkable


Suggested change

ACTOR_FLAG_TARGETABLE | ACTOR_FLAG_CHECK_WITH_NAVI; // Make actor targetable and Navi-checkable

ACTOR_FLAG_TARGETABLE | ACTOR_FLAG_CHECK_WITH_NAVI;

Dragorn421 · 2022-01-28T17:05:17Z

include/z64actor.h

+#define ACTOR_FLAG_ARROW_IS_CARRYING (1 << 15) // an arrow is currently carrying this actor
+#define ACTOR_FLAG_IMMEDIATE_TALK (1 << 16) // forces Player to talk when in range. needs to be unset manually to avoid infinite talking
+#define ACTOR_FLAG_HEAVYBLOCK (1 << 17) // changes actor carrying behavior specifically for the golden gauntlets block actor
+#define ACTOR_FLAG_CHECK_WITH_NAVI (1 << 18) // Navi can be used to trigger dialogue when targeting the actor


Does "targeting" here refers to Navi hovering at the actor's focus pos or locking onto the actor?

Dragorn421 · 2022-01-28T17:07:07Z

src/overlays/actors/ovl_En_Bom_Chu/z_en_bom_chu.c

@@ -234,7 +234,7 @@ void EnBomChu_WaitForRelease(EnBomChu* this, GlobalContext* globalCtx) {
        //! @bug there is no NULL check on the floor poly.  If the player is out of bounds the floor poly will be NULL
        //! and will cause a crash inside this function.
        EnBomChu_UpdateFloorPoly(this, this->actor.floorPoly, globalCtx);
-        this->actor.flags |= ACTOR_FLAG_0; // make chu targetable
+        this->actor.flags |= ACTOR_FLAG_TARGETABLE; // make chu targetable


Suggested change

this->actor.flags |= ACTOR_FLAG_TARGETABLE; // make chu targetable

this->actor.flags |= ACTOR_FLAG_TARGETABLE;

include/z64actor.h

fig02 added 3 commits January 25, 2022 09:56

name a bunch of flags

6f68e34

done for now i think

837b07d

merge master

7570e22

EllipticEllipsis reviewed Jan 26, 2022

View reviewed changes

grammar fixes

081fffa

fig02 commented Jan 26, 2022

View reviewed changes

fig02 added 2 commits January 26, 2022 00:44

change cull flag

8287bbf

is in -> in

7774a67

Dragorn421 reviewed Jan 26, 2022

View reviewed changes

fig02 added 2 commits January 26, 2022 20:27

some review

6558395

remove unwanted file

ccff066

Dragorn421 reviewed Jan 27, 2022

View reviewed changes

adjust talk and light comments

019e7c9

Dragorn421 reviewed Jan 28, 2022

View reviewed changes

Roman971 reviewed Apr 30, 2022

View reviewed changes

include/z64actor.h Show resolved Hide resolved

fig02 added the Needs discussion There is a debate or other required discussion preventing changes from being made label Aug 27, 2022

Dragorn421 added Needs contributor approval labels Sep 30, 2022

fig02 mentioned this pull request Oct 15, 2022

Lens docs zeldaret/mm#1123

Merged

engineer124 reviewed Oct 15, 2022

View reviewed changes

include/z64actor.h Show resolved Hide resolved

Dragorn421 added the Waiting for author There are requested changes that have not been addressed label Nov 30, 2022

Dragorn421 marked this pull request as draft January 11, 2023 10:43

hensldm mentioned this pull request Mar 4, 2023

DynaPoly Docs Pass zeldaret/mm#1194

Merged

fig02 removed Needs contributor approval labels Aug 27, 2023

Dragorn421 mentioned this pull request Nov 19, 2023

Name actor flags 1: ACTOR_FLAG_REACT_TO_LENS, ACTOR_FLAG_IGNORE_POINT_LIGHTS #1583

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document Actor Flags #1122

Document Actor Flags #1122

fig02 commented Jan 26, 2022

EllipticEllipsis left a comment

fig02 Jan 26, 2022

fig02 Jan 26, 2022

Dragorn421 Jan 26, 2022

Dragorn421 Jan 26, 2022

fig02 Jan 26, 2022

Dragorn421 Jan 26, 2022

fig02 Jan 26, 2022

Dragorn421 Jan 27, 2022

fig02 Jan 27, 2022

Dragorn421 Jan 28, 2022

Dragorn421 Jan 28, 2022 •

edited

fig02 Jan 28, 2022

Dragorn421 Jan 28, 2022

fig02 Jan 28, 2022

Dragorn421 Jan 28, 2022

Dragorn421 Jan 28, 2022

Dragorn421 Jan 28, 2022

Dragorn421 Jan 28, 2022


		if (CHECK_FLAG_ALL(this->actor.flags, ACTOR_FLAG_13)) {
		if (CHECK_FLAG_ALL(this->actor.flags, ACTOR_FLAG_HOOK_ATTACHED)) {

	#define ACTOR_FLAG_IMMEDIATE_TALK (1 << 16) // forces Player to talk when in range. needs to be unset manually to avoid infinite talking
	#define ACTOR_FLAG_IMMEDIATE_TALK (1 << 16) // forces Player to talk when in range. Needs to be unset manually to avoid infinite talking

	((this->actor.flags & ACTOR_FLAG_ARROW_IS_CARRYING) == 0)) {
	!(this->actor.flags & ACTOR_FLAG_ARROW_IS_CARRYING)) {

	ACTOR_FLAG_TARGETABLE \| ACTOR_FLAG_CHECK_WITH_NAVI; // Make actor targetable and Navi-checkable
	ACTOR_FLAG_TARGETABLE \| ACTOR_FLAG_CHECK_WITH_NAVI;

	this->actor.flags \|= ACTOR_FLAG_TARGETABLE; // make chu targetable
	this->actor.flags \|= ACTOR_FLAG_TARGETABLE;

Document Actor Flags #1122

Are you sure you want to change the base?

Document Actor Flags #1122

Conversation

fig02 commented Jan 26, 2022

EllipticEllipsis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dragorn421 Jan 28, 2022 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Dragorn421 Jan 28, 2022 •

edited