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 <[email protected]>

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*
+#define CUTSCENE_ENTITY_INTERACT ((uint8_t)0xFE)
-// resolvers below.
+#define CUTSCENE_ENTITY_INTERACTED ((uint8_t)0xFD)
-#define CUTSCENE_ENTITY_INTERACT        ((uint8_t)0xFE)
+#define CUTSCENE_ENTITY_LAST_CREATED ((uint8_t)0xFC)
-#define CUTSCENE_ENTITY_INTERACTED      ((uint8_t)0xFD)
+#define CUTSCENE_ENTITY_LAST_REF ((uint8_t)0xFB)
-#define CUTSCENE_ENTITY_LAST_CREATED    ((uint8_t)0xFC)
+#define CUTSCENE_AREA_LAST_CREATED ((uint8_t)0xFF)
-#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
+  // Free-form text cache for the running cutscene - see
-  // CUTSCENE_ITEM_TYPE_KEYBOARD item - see cutsceneSystemGetTextCache/
+  // cutsceneSystemGetTextCache/cutsceneSystemSetTextCache.
-  // cutsceneSystemSetTextCache. Not tied to any one item type; any item
-  // may read or write it.
   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" -
+  // Filename last passed to cutsceneSystemLoad - see cutsceneRestart.
-  // 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.
   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
+ * interact/interacted entities. Does not itself advance to the first item.
- * cutsceneSystemStartCutsceneWith and
- * cutsceneSystemStartCutsceneAndGoToMarker. Does not itself advance to the
- * first item; callers do that afterward (via cutsceneSystemNext or
- * cutsceneGoTo).
  *
  * @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
+ * marker with the given name instead of running from the first item.
- * first item - as if cutsceneGoTo(marker) had been called immediately
+ * Asserts if no marker with that name exists.
- * after cutsceneSystemStartCutscene. Asserts if no marker with that
- * name exists in the cutscene.
  *
  * @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)
+ * Splices cutscene's items into the running cutscene.
- * 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).
  *
  * @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.
+ * Loads and immediately starts a cutscene asset by file name.
- * 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.
  *
- * @param file Cutscene file name (with .jsonc extension), relative to
+ * @param file Cutscene file name.
- * assets/cutscenes/.
  */
 void cutsceneSystemLoad(const char_t *file);
 
 /**
- * Restarts the currently running cutscene from its first item,
+ * Restarts the currently running cutscene. Will perform a load if the cutscene
- * preserving whatever interact/interacted entities triggered it and
+ * was initially from a file.
- * 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.
  */
 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
+ * finishes.
- * 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.
  *
- * Exists so a runtime-loaded cutscene file (which can't store a native
+ * @param onComplete Callback to fire on completion.
- * 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.
  */
 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
+ * Returns the running cutscene's cached text - see
- * cutsceneSystemSetTextCache (e.g. by a CUTSCENE_ITEM_TYPE_KEYBOARD item
+ * cutsceneSystemSetTextCache. Empty ("") if nothing has been cached yet.
- * once its keyboard closes). Empty ("") if nothing has been cached yet
- * for the running cutscene.
  *
  * @returns The cached text.
  */
 const char_t * cutsceneSystemGetTextCache(void);
 
 /**
- * Overwrites CUTSCENE_SYSTEM.textCache with a copy of text. Any item may
+ * Overwrites the running cutscene's cached text.
- * 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.
  *
- * @param text The text to cache; copied internally, safe to be
+ * @param text The text to cache; copied internally.
- * transient. Must not exceed CUTSCENE_TEXT_CACHE_MAX - 1 characters.
  */
 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
+ * Jumps the running cutscene directly to the marker with the given name
- * the given name and starts it immediately, as if cutsceneSystemNext()
+ * and starts it immediately. Asserts if no cutscene is running or no
- * had advanced straight to it. Intended to be called from within
+ * marker with that name exists.
- * 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.
  *
- * @param name Marker name to search for, matched with stringEquals.
+ * @param name Marker name to search for.
  */
 void cutsceneGoTo(const char_t *name);