Skip to content

Document z_en_xc.c and csdis.py changes#2692

Open
mzxrules wants to merge 2 commits intozeldaret:mainfrom
mzxrules:cutscenes_doc
Open

Document z_en_xc.c and csdis.py changes#2692
mzxrules wants to merge 2 commits intozeldaret:mainfrom
mzxrules:cutscenes_doc

Conversation

@mzxrules
Copy link
Contributor

@mzxrules mzxrules commented Jan 27, 2026

Contributions made in this pr are licensed under CC0

Some important bullets:

  • added actor_cue_id_table in csdis.py for outputting named enums for individual actor cue ids. I've set it up so that for actor cues, the CutsceneCommand id is equivalent to the enum_no for the cue id enumeration.
  • I don't know what to call the ActorMovement_func_ functions. I've just given them temp names to sort of make them more readable for now.
  • For the moment, I have put z_en_xc's different cueId enums into cutscenes.h because there isn't a way to import them where required atm.

/* 0x77 */ CS_DEST_ZELDAS_COURTYARD_RECEIVE_LETTER
} CutsceneDestination;

typedef enum EnXcCueId {
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

since these are actor-specific I think it would make more sense to place them in the actor overlay header (if possible), I'm worried we'll end up with lots of actor-specific enums like this as more actor cues are documented in the future

Copy link
Contributor

@Yanis002 Yanis002 Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

oh nvm I should learn how to read lol

I wouldn't be against having a separate header for actor-specific cutscene stuff, like instead of having them in z_en_xc.h directly we could make another file in that folder for this

Copy link
Contributor Author

@mzxrules mzxrules Jan 29, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Personally I'd like to hold off until more asset splitting and cutscene documentation happens before deciding how to sort things.

Comment on lines +35 to +37
/* 00 */ SHEIK_ACTION_0_TEACH1_CHECK_DEMO_START,
/* 01 */ SHEIK_ACTION_1_TEACH1_INVISIBLE,
/* 02 */ SHEIK_ACTION_2_TEACH1_GRACEFUL_FALL,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's the purpose in keeping the numerical value in the enum name?

Copy link
Contributor Author

@mzxrules mzxrules Feb 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Primarily my own personal sanity. There are 80 actions with quite a bit of duplicated redundant behavior, and I only happened to land on unique names very late in the process. Keeping the numbers is very useful for keeping things straight.

Perhaps this is a good spot to explain how this this actor operates. This actor has about 8 let's call them sequences of actions it can do (you can see this at a glance by looking at the comments in sActionFuncs). You start at one action, and linearly advance down the line as different conditions are met, until you reach the end. Well if you read through the actions, you'll see many with identical behavior.

In most cases, duplicate code is avoided like this:
Say you have sequence A and B which have some functions that share behavior, and you're running through sequence B. If actionFunc B has identical behavior to actionFunc A, it will just call it. actionFunc A does its thing and when the next step should be done, the action variable updates to the next for sequence A. Then, actionFunc B calls a specific function (which I've named WhenNext) that checks if action has been modified and sets action to the next for sequence B if so.

But in a few cases the exact behavior just gets duplicated in a different function anyway.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants