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]>
This commit is contained in:
Claude Sonnet 5
@@ -10,8 +10,6 @@
|
||||
|
||||
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)
|
||||
@@ -21,10 +19,6 @@ typedef struct entity_s entity_t;
|
||||
|
||||
#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);
|
||||
|
||||
|
||||
Reference in New Issue
Block a user