From f64364f37d8a9990258d29666afefaf336c92a7b Mon Sep 17 00:00:00 2001 From: Dominic Masters Date: Fri, 18 Sep 2026 11:21:12 -0500 Subject: [PATCH] Trim cutscenesystem.h doc comments to the essentials Comments-only change - drops implementation rationale/cross-referencing detail in favor of shorter one-liners, matching the simplified style already applied to part of the file. Co-Authored-By: Claude Sonnet 5 --- src/dusk/rpg/cutscene/cutscenesystem.h | 136 +++++-------------------- 1 file changed, 27 insertions(+), 109 deletions(-) diff --git a/src/dusk/rpg/cutscene/cutscenesystem.h b/src/dusk/rpg/cutscene/cutscenesystem.h index 57266768..76dd79f7 100644 --- a/src/dusk/rpg/cutscene/cutscenesystem.h +++ b/src/dusk/rpg/cutscene/cutscenesystem.h @@ -10,21 +10,15 @@ typedef struct entity_s entity_t; -// Sentinels accepted in place of a literal index/ID by the cutsceneSystemGet* -// resolvers below. -#define CUTSCENE_ENTITY_INTERACT ((uint8_t)0xFE) -#define CUTSCENE_ENTITY_INTERACTED ((uint8_t)0xFD) -#define CUTSCENE_ENTITY_LAST_CREATED ((uint8_t)0xFC) -#define CUTSCENE_ENTITY_LAST_REF ((uint8_t)0xFB) -#define CUTSCENE_AREA_LAST_CREATED ((uint8_t)0xFF) +#define CUTSCENE_ENTITY_INTERACT ((uint8_t)0xFE) +#define CUTSCENE_ENTITY_INTERACTED ((uint8_t)0xFD) +#define CUTSCENE_ENTITY_LAST_CREATED ((uint8_t)0xFC) +#define CUTSCENE_ENTITY_LAST_REF ((uint8_t)0xFB) +#define CUTSCENE_AREA_LAST_CREATED ((uint8_t)0xFF) #define CUTSCENE_TEXT_MINI_LAST_CREATED ((uint8_t)0xFA) #define CUTSCENE_TEXT_CACHE_MAX 64 #define CUTSCENE_LOADED_ITEMS_MAX 128 - -// Scratch capacity for resolving a JSON-authored CUTSCENE_ITEM_TYPE_INSERT -// target - see cutsceneSystemInsertCutscene. Sized small deliberately - -// an inserted snippet is meant to be a short splice, not a full cutscene. #define CUTSCENE_INSERT_ITEMS_MAX 16 typedef struct { @@ -38,10 +32,8 @@ typedef struct { uint8_t areaLastCreated; uint8_t textMiniLastCreated; - // Free-form text cache, e.g. holding whatever was last typed via a - // CUTSCENE_ITEM_TYPE_KEYBOARD item - see cutsceneSystemGetTextCache/ - // cutsceneSystemSetTextCache. Not tied to any one item type; any item - // may read or write it. + // Free-form text cache for the running cutscene - see + // cutsceneSystemGetTextCache/cutsceneSystemSetTextCache. char_t textCache[CUTSCENE_TEXT_CACHE_MAX]; // Runtime data for the current item. @@ -53,14 +45,7 @@ typedef struct { cutsceneitem_t loadedItems[CUTSCENE_LOADED_ITEMS_MAX]; cutscene_t loadedScene; - // Filename last passed to cutsceneSystemLoad, e.g. "main_menu.jsonc" - - // set right after it starts loadedScene running. Empty ("") for a - // cutscene started directly via cutsceneSystemStartCutscene* instead - // (a C-authored one, or loadedScene reused without going through - // cutsceneSystemLoad again), and cleared by cutsceneSystemPrepare on - // every fresh start so it never lingers from a previous file load. See - // cutsceneRestart, which re-loads (rather than just rerunning) whatever - // this names. + // Filename last passed to cutsceneSystemLoad - see cutsceneRestart. char_t loadedFile[ASSET_FILE_NAME_MAX]; } cutscenesystem_t; @@ -78,11 +63,7 @@ void cutsceneSystemDispose(); /** * Resets CUTSCENE_SYSTEM to run cutscene from its first item, binding - * interact/interacted entities - shared setup used by - * cutsceneSystemStartCutsceneWith and - * cutsceneSystemStartCutsceneAndGoToMarker. Does not itself advance to the - * first item; callers do that afterward (via cutsceneSystemNext or - * cutsceneGoTo). + * interact/interacted entities. Does not itself advance to the first item. * * @param cutscene Pointer to the cutscene to prepare. * @param interact The entity that initiated the interaction (player), or @@ -117,13 +98,11 @@ void cutsceneSystemStartCutsceneWith( /** * Starts a cutscene with no bound entities, jumping straight to the - * CUTSCENE_MARKER item with the given name instead of running from the - * first item - as if cutsceneGoTo(marker) had been called immediately - * after cutsceneSystemStartCutscene. Asserts if no marker with that - * name exists in the cutscene. + * marker with the given name instead of running from the first item. + * Asserts if no marker with that name exists. * * @param cutscene Pointer to the cutscene to start. - * @param marker Marker name to jump to, matched with stringEquals. + * @param marker Marker name to jump to. */ void cutsceneSystemStartCutsceneAndGoToMarker( cutscene_t *cutscene, @@ -131,87 +110,35 @@ void cutsceneSystemStartCutsceneAndGoToMarker( ); /** - * Splices cutscene's items into the running cutscene (CUTSCENE_SYSTEM.scene) - * in place, right after the currently-executing item, via cutsceneAppendNext - * - unlike cutsceneSystemStartCutscene (a one-way jump that replaces the - * running cutscene outright), the inserted items simply become part of the - * running scene's own item array, so there's nothing separate to "return" - * to once they finish - whatever already followed the CUTSCENE_ITEM_TYPE_ - * INSERT item continues normally, now shifted further down the same array. - * Then immediately advances into the first inserted item (see - * cutsceneSystemNext), so the splice takes effect within this same call. - * Deliberately does not touch pause flags, interact entities, "last - * created" state, or the text cache - those all keep whatever the - * outer cutscene set, since this is meant to feel like pasting cutscene's - * items in place rather than starting an independent cutscene. Because of - * this, cutscene's own .pause is ignored. Asserts if no cutscene is - * currently running, or if the running scene's own itemsMax has no room - * left for cutscene's items (see cutscene_t.itemsMax's doc comment - a - * cutscene that expects to have items inserted into it at runtime needs to - * be declared with spare capacity up front). + * Splices cutscene's items into the running cutscene. * * @param cutscene The cutscene whose items to splice in. */ void cutsceneSystemInsertCutscene(const cutscene_t *cutscene); /** - * Loads and immediately starts a cutscene asset by file name, e.g. - * cutsceneSystemLoad("main_menu.jsonc") loads and starts - * assets/cutscenes/main_menu.jsonc, parsing it into - * CUTSCENE_SYSTEM.loadedScene/loadedItems. Locks the underlying JSON - * asset entry just long enough to parse it, then unlocks it like any - * other asset - every cutsceneitem_t field that could reference the - * parsed doc owns its string data by value (see cutscenecutsceneref_t/ - * cutscenemarker_t's doc comments), so nothing needs to keep it resident - * past this call, and a later load of the same file is a normal cache - * hit (or a fresh re-read, if the entry was reaped meanwhile) rather than - * something this function has to force either way. Opens the fatal error - * overlay (see uiFatalErrorOpen) instead of starting anything if the - * asset fails to load. Records file into CUTSCENE_SYSTEM.loadedFile once - * it starts running. + * Loads and immediately starts a cutscene asset by file name. * - * @param file Cutscene file name (with .jsonc extension), relative to - * assets/cutscenes/. + * @param file Cutscene file name. */ void cutsceneSystemLoad(const char_t *file); /** - * Restarts the currently running cutscene from its first item, - * preserving whatever interact/interacted entities triggered it and - * whatever completion callback was armed. If CUTSCENE_SYSTEM.loadedFile - * is set (i.e. the running cutscene came from cutsceneSystemLoad), this - * re-invokes cutsceneSystemLoad on that same filename rather than just - * rerunning whatever's still resident in loadedScene/loadedItems - - * otherwise it's just cutsceneSystemStartCutsceneWith on the same - * cutscene_t. Asserts if no cutscene is running. + * Restarts the currently running cutscene. Will perform a load if the cutscene + * was initially from a file. */ void cutsceneRestart(void); /** * Sets a native callback to fire once when the currently running cutscene - * finishes by running off the end of its item list. A fresh - * cutsceneSystemStartCutscene* call clears any previously set callback, so - * call this again after starting a new cutscene to arm it - but - * cutsceneRestart() preserves whatever was armed, since a restart (e.g. - * retrying a failed check) is the same logical run trying again, not a new - * one. Invoked with NULL, same as CUTSCENE_CALLBACK. + * finishes. * - * Exists so a runtime-loaded cutscene file (which can't store a native - * function pointer) can still hand off to native code once it's done, - * without needing a whole name->function registry: the file just ends - * normally, and whoever started it supplies what happens next. - * - * @param onComplete Callback to fire on natural completion. May be NULL - * to clear a previously set one. + * @param onComplete Callback to fire on completion. */ void cutsceneSystemSetOnComplete(cutscenecallback_t onComplete); /** * Resolves a raw entity index (or sentinel) to an entity pointer. - * Handles CUTSCENE_ENTITY_INTERACT, CUTSCENE_ENTITY_INTERACTED, - * CUTSCENE_ENTITY_LAST_CREATED and CUTSCENE_ENTITY_LAST_REF. - * Updates CUTSCENE_SYSTEM.entityLastRef to the resolved entity. - * Asserts the resolved entity is within bounds. * * @param entityIndex Raw entity index or sentinel value. * @returns Pointer to the resolved entity. @@ -237,23 +164,17 @@ uint8_t cutsceneSystemGetAreaId(const uint8_t areaId); uint8_t cutsceneSystemGetTextMiniId(const uint8_t index); /** - * Returns CUTSCENE_SYSTEM.textCache - whatever was last written there via - * cutsceneSystemSetTextCache (e.g. by a CUTSCENE_ITEM_TYPE_KEYBOARD item - * once its keyboard closes). Empty ("") if nothing has been cached yet - * for the running cutscene. + * Returns the running cutscene's cached text - see + * cutsceneSystemSetTextCache. Empty ("") if nothing has been cached yet. * * @returns The cached text. */ const char_t * cutsceneSystemGetTextCache(void); /** - * Overwrites CUTSCENE_SYSTEM.textCache with a copy of text. Any item may - * call this - it isn't tied to any one item type - so later items can - * read back whatever the caller wants to pass along, up to - * CUTSCENE_TEXT_CACHE_MAX - 1 characters. + * Overwrites the running cutscene's cached text. * - * @param text The text to cache; copied internally, safe to be - * transient. Must not exceed CUTSCENE_TEXT_CACHE_MAX - 1 characters. + * @param text The text to cache; copied internally. */ void cutsceneSystemSetTextCache(const char_t *text); @@ -263,14 +184,11 @@ void cutsceneSystemSetTextCache(const char_t *text); void cutsceneSystemNext(); /** - * Jumps the running cutscene directly to the CUTSCENE_MARKER item with - * the given name and starts it immediately, as if cutsceneSystemNext() - * had advanced straight to it. Intended to be called from within - * another item's start/update (e.g. a CUTSCENE_CALLBACK) to implement - * flow control. Asserts if no cutscene is running or no marker with - * that name exists in it. + * Jumps the running cutscene directly to the marker with the given name + * and starts it immediately. Asserts if no cutscene is running or no + * marker with that name exists. * - * @param name Marker name to search for, matched with stringEquals. + * @param name Marker name to search for. */ void cutsceneGoTo(const char_t *name);