1
0
Fork 0
mirror of https://github.com/zeldaret/oot.git synced 2024-12-05 01:06:37 +00:00
oot/include/z64cutscene_commands.h
cadmic 39de6ce293
Extract unused scene headers (#1930)
* Extract unused scene headers

* git subrepo pull --force tools/ZAPD

subrepo:
  subdir:   "tools/ZAPD"
  merged:   "1300a4f36"
upstream:
  origin:   "https://github.com/zeldaret/ZAPD.git"
  branch:   "master"
  commit:   "1300a4f36"
git-subrepo:
  version:  "0.4.6"
  origin:   "git@github.com:ingydotnet/git-subrepo.git"
  commit:   "110b9eb"

* Add more unused arguments to CS_LIGHT_SETTING
2024-03-23 12:38:05 -04:00

283 lines
12 KiB
C

#ifndef Z64CUTSCENE_COMMANDS_H
#define Z64CUTSCENE_COMMANDS_H
#include "command_macros_base.h"
#include "z64cutscene.h"
/**
* Cutscene scripts are arrays of `CutsceneData` words, including bit-packed integers and floats.
*
* Most command macros have unused arguments. This is to account for the vanilla assets setting specific values
* that don't end up being used by any code. They can safely be set to anything, as they aren't used in the
* implementation.
*
* It is believed the original tool used for cutscenes handled most commands the same way, using similar
* fields, and the code would have accessed them using common structs. Given this, the unused values observed in vanilla
* assets may appear to map to a variable that makes sense, even if it doesn't end up being used in the code. It
* probably isn't garbage data.
*
* This codebase goes with specialized structs and macros to make it easier to follow the code.
* Note this common struct design is still partially reflected in all commands having a `startFrame` and `endFrame`,
* when sometimes only the `startFrame` matters (as documented).
*/
/**
* CMD_F expects an (IEEE 754) encoded float (colloquially "in hex", such as `0x42280000`),
* rather than a C float literal (such as `42.0f`).
* Float literals cannot be used because cutscenes are arrays of union type CutsceneData, which may contain integers and floats.
* Regardless of CutsceneData having a float member, initializing with a float will cast the float to s32.
* Designated initializers (added in C99) would solve this problem but are not supported by IDO (C89 and some extensions).
*/
#ifdef __GNUC__
#define CS_FLOAT(ieee754bin, f) (f)
#define CMD_F(a) {.f = (a)}
#else
#define CS_FLOAT(ieee754bin, f) (ieee754bin)
#define CMD_F(a) {(a)}
#endif
/**
* Marks the beginning of a cutscene script.
*/
#define CS_BEGIN_CUTSCENE(totalEntries, frameCount) CMD_W(totalEntries), CMD_W(frameCount)
/**
* Defines data for `CutsceneCameraPoint`, which can be used with any of the `eye` or `at` camera commands.
*/
#define CS_CAM_POINT(continueFlag, roll, frame, viewAngle, xPos, yPos, zPos, unused) \
CMD_BBH(continueFlag, roll, frame), CMD_F(viewAngle), CMD_HH(xPos, yPos), CMD_HH(zPos, unused)
/**
* Declares a list of camera `eye` points that form a spline.
* The points of the spline are interpolated over time to create smooth camera movements.
*/
#define CS_CAM_EYE_SPLINE(startFrame, endFrame) \
CS_CMD_CAM_EYE_SPLINE, CMD_HH(0x0001, startFrame), CMD_HH(endFrame, 0x0000)
/**
* Declares a list of camera `at` points that form a spline.
* The points of the spline are interpolated over time to create smooth camera movements.
*/
#define CS_CAM_AT_SPLINE(startFrame, endFrame) \
CS_CMD_CAM_AT_SPLINE, CMD_HH(0x0001, startFrame), CMD_HH(endFrame, 0x0000)
/**
* Declares a list of camera `eye` points that form a spline.
* The points of the spline are interpolated over time to create smooth camera movements.
* The points are relative to the player's position and yaw.
*/
#define CS_CAM_EYE_SPLINE_REL_TO_PLAYER(startFrame, endFrame) \
CS_CMD_CAM_EYE_SPLINE_REL_TO_PLAYER, CMD_HH(0x0001, startFrame), CMD_HH(endFrame, 0x0000)
/**
* Declares a list of camera `at` points that form a spline.
* The points of the spline are interpolated over time to create smooth camera movements.
* The points are relative to the player's position and yaw.
*/
#define CS_CAM_AT_SPLINE_REL_TO_PLAYER(startFrame, endFrame) \
CS_CMD_CAM_AT_SPLINE_REL_TO_PLAYER, CMD_HH(0x0001, startFrame), CMD_HH(endFrame, 0x0000)
/**
* Declares a single `eye` point that will be set on the specified frame, without any interpolation.
* Should only contain a single point, not a list.
* This feature is not used in the final game and lacks polish, it is recommended to use splines in all cases.
*/
#define CS_CAM_EYE(startFrame, endFrame) \
CS_CMD_CAM_EYE, CMD_HH(0x0001, startFrame), CMD_HH(endFrame, 0x0000)
/**
* Declares a single `at` point that will be set on the specified frame, without any interpolation.
* Should only contain a single point, not a list.
* This feature is not used in the final game and lacks polish, it is recommended to use splines in all cases.
*/
#define CS_CAM_AT(startFrame, endFrame) \
CS_CMD_CAM_AT, CMD_HH(0x0001, startFrame), CMD_HH(endFrame, 0x0000)
/**
* Declares a list of `CS_MISC` entries.
*/
#define CS_MISC_LIST(entries) \
CS_CMD_MISC, CMD_W(entries)
/**
* Various miscellaneous commands.
* @see `CutsceneMiscType` enum for the different types of commands.
* @note setting `endFrame` to same value as `startFrame` will not behave as expected.
* For commands that only need to last one frame, set `endFrame` to `startFrame + 1`.
*/
#define CS_MISC(type, startFrame, endFrame, unused0, unused1, unused2, unused3, unused4, unused5, unused6, unused7, unused8, unused9, unused10) \
CMD_HH(type, startFrame), CMD_HH(endFrame, unused0), \
CMD_W(unused1), CMD_W(unused2), CMD_W(unused3), CMD_W(unused4), CMD_W(unused5), \
CMD_W(unused6), CMD_W(unused7), CMD_W(unused8), CMD_W(unused9), CMD_W(unused10)
/**
* Declares a list of `CS_LIGHT_SETTING` entries.
*/
#define CS_LIGHT_SETTING_LIST(entries) \
CS_CMD_LIGHT_SETTING, CMD_W(entries)
/**
* Changes the environment lights to the specified setting.
* The lighting change will take place immediately with no blending.
* @note `endFrame` is not used in the implementation of the command, so its value does not matter
*/
#define CS_LIGHT_SETTING(lightSetting, startFrame, endFrame, unused0, unused1, unused2, unused3, unused4, unused5, unused6, unused7, unused8, unused9, unused10) \
CMD_BBH(0, (lightSetting + 1), startFrame), CMD_HH(endFrame, unused0), \
CMD_W(unused1), CMD_W(unused2), CMD_W(unused3), CMD_W(unused4), CMD_W(unused5), \
CMD_W(unused6), CMD_W(unused7), CMD_W(unused8), CMD_W(unused9), CMD_W(unused10)
/**
* Declares a list of `CS_RUMBLE_CONTROLLER` entries.
*/
#define CS_RUMBLE_CONTROLLER_LIST(entries) \
CS_CMD_RUMBLE_CONTROLLER, CMD_W(entries)
/**
* Rumble the controller.
* @note `endFrame` is not used in the implementation of the command, so its value does not matter
*/
#define CS_RUMBLE_CONTROLLER(unused0, startFrame, endFrame, sourceStrength, duration, decreaseRate, unused1, unused2) \
CMD_HH(unused0, startFrame), CMD_HBB(endFrame, sourceStrength, duration), CMD_BBH(decreaseRate, unused1, unused2)
/**
* Declares a list of `CS_ACTOR_CUE` entries.
*/
#define CS_ACTOR_CUE_LIST(cmdType, entries) \
CMD_W(cmdType), CMD_W(entries)
/**
* Defines a cue that an actor can listen for.
* The actor can choose whether or not to use the position and rotation data supplied to it.
* The cue `id` is a number that has an actor-specific meaning.
*/
#define CS_ACTOR_CUE(id, startFrame, endFrame, rotX, rotY, rotZ, startX, startY, startZ, endX, endY, endZ, unused0, unused1, unused2) \
CMD_HH(id, startFrame), CMD_HH(endFrame, rotX), CMD_HH(rotY, rotZ), \
CMD_W(startX), CMD_W(startY), CMD_W(startZ), \
CMD_W(endX), CMD_W(endY), CMD_W(endZ), \
CMD_F(unused0), CMD_F(unused1), CMD_F(unused2)
/**
* Declares a list of `CS_PLAYER_CUE` entries.
*/
#define CS_PLAYER_CUE_LIST(entries) \
CS_CMD_PLAYER_CUE, CMD_W(entries)
/**
* A player cue is the same as `CS_ACTOR_CUE` but is specifically for player.
*/
#define CS_PLAYER_CUE(id, startFrame, endFrame, rotX, rotY, rotZ, startX, startY, startZ, endX, endY, endZ, unused0, unused1, unused2) \
CS_ACTOR_CUE(id, startFrame, endFrame, rotX, rotY, rotZ, startX, startY, startZ, endX, endY, endZ, unused0, unused1, unused2)
/**
* Declares a list of `CS_TEXT_*` entries.
*/
#define CS_TEXT_LIST(entries) \
CS_CMD_TEXT, CMD_W(entries)
/**
* Starts a textbox at the specified time.
* For `CS_TEXT_OCARINA_ACTION`, `textId` is used as an ocarina action.
* For a choice textbox, `altTextId1` is the top text id to branch to and `altTextId2` is the bottom.
*/
#define CS_TEXT(textId, startFrame, endFrame, type, altTextId1, altTextId2) \
CMD_HH(textId, startFrame), CMD_HH(endFrame, type), CMD_HH(altTextId1, altTextId2)
#define CS_TEXT_NONE(startFrame, endFrame) \
CS_TEXT(CS_TEXT_ID_NONE, startFrame, endFrame, 0xFFFF, CS_TEXT_ID_NONE, CS_TEXT_ID_NONE)
#define CS_TEXT_OCARINA_ACTION(ocarinaAction, startFrame, endFrame, messageId) \
CS_TEXT(ocarinaAction, startFrame, endFrame, CS_TEXT_OCARINA_ACTION, messageId, CS_TEXT_ID_NONE)
/**
* Controls various types of screen transitions.
* @see `CutsceneTransitionType` for type options.
*/
#define CS_TRANSITION(type, startFrame, endFrame) \
CS_CMD_TRANSITION, 0x00000001, CMD_HH(type, startFrame), CMD_HH(endFrame, endFrame)
/**
* Declares a list of `CS_START_SEQ` entries.
*/
#define CS_START_SEQ_LIST(entries) \
CS_CMD_START_SEQ, CMD_W(entries)
/**
* Starts a sequence at the specified time.
* @note `endFrame` is not used in the implementation of the command, so its value does not matter
*/
#define CS_START_SEQ(seqId, startFrame, endFrame, unused0, unused1, unused2, unused3, unused4, unused5, unused6, unused7) \
CMD_HH((seqId + 1), startFrame), CMD_HH(endFrame, unused0), \
CMD_W(unused1), CMD_W(unused2), CMD_W(unused3), CMD_W(unused4), CMD_W(unused5), \
CMD_W(unused6), CMD_W(unused7), 0x00000000, 0x00000000, 0x00000000
/**
* Declares a list of `CS_STOP_SEQ` entries.
*/
#define CS_STOP_SEQ_LIST(entries) \
CS_CMD_STOP_SEQ, CMD_W(entries)
/**
* Stops a sequence at the specified time.
* @note `endFrame` is not used in the implementation of the command, so its value does not matter
*/
#define CS_STOP_SEQ(seqId, startFrame, endFrame, unused0, unused1, unused2, unused3, unused4, unused5, unused6, unused7) \
CMD_HH((seqId + 1), startFrame), CMD_HH(endFrame, unused0), \
CMD_W(unused1), CMD_W(unused2), CMD_W(unused3), CMD_W(unused4), CMD_W(unused5), \
CMD_W(unused6), CMD_W(unused7), 0x00000000, 0x00000000, 0x00000000
/**
* Declares a list of `CS_FADE_OUT_SEQ` entries.
*/
#define CS_FADE_OUT_SEQ_LIST(entries) \
CS_CMD_FADE_OUT_SEQ, CMD_W(entries)
/**
* Fade out the sequence that is playing on the specified sequence player, over the specified frame range.
* @see `CutsceneFadeOutSeqPlayer`
*/
#define CS_FADE_OUT_SEQ(seqPlayer, startFrame, endFrame, unused0, unused1, unused2, unused3, unused4, unused5, unused6, unused7) \
CMD_HH(seqPlayer, startFrame), CMD_HH(endFrame, unused0), \
CMD_W(unused1), CMD_W(unused2), CMD_W(unused3), CMD_W(unused4), CMD_W(unused5), \
CMD_W(unused6), CMD_W(unused7), 0x00000000, 0x00000000, 0x00000000
/**
* Declares a list of `CS_TIME` entries.
*/
#define CS_TIME_LIST(entries) \
CS_CMD_TIME, CMD_W(entries)
/**
* Sets the time of day.
* Both the day time and skybox time are set by this command.
* @note `endFrame` is not used in the implementation of the command, so its value does not matter
*/
#define CS_TIME(unused0, startFrame, endFrame, hour, min) \
CMD_HH(unused0, startFrame), CMD_HBB(endFrame, hour, min), CMD_W(0)
/**
* Sends the player to a new destination.
* `destination` maps to a custom block of code that must implement the scene transition on its own.
* This custom code can also do other tasks like changing age, setting flags, or any other setup that is needed
* before going to the next destination.
*
* @see `CutsceneDestination`
* @note `endFrame` is not used in the implementation of the command, so its value does not matter
*/
#define CS_DESTINATION(destination, startFrame, endFrame) \
CS_CMD_DESTINATION, 1, CMD_HH(destination, startFrame), CMD_HH(endFrame, endFrame)
/**
* Marks the end of a cutscene script.
*/
#define CS_END() 0xFFFFFFFF, 0x00000000
// most instances of this look like unimplemented actor cues.
// after confirming this, can probably switch those over and delete this
#define CS_UNK_DATA_LIST(cmdType, entries) CMD_W(cmdType), CMD_W(entries)
#define CS_UNK_DATA(unk1, unk2, unk3, unk4, unk5, unk6, unk7, unk8, unk9, unk10, unk11, unk12) \
CMD_W(unk1), CMD_W(unk2), CMD_W(unk3), CMD_W(unk4), CMD_W(unk5), CMD_W(unk6), \
CMD_W(unk7), CMD_W(unk8), CMD_W(unk9), CMD_W(unk10), CMD_W(unk11), CMD_W(unk12)
#endif