Rename cutscenesystemrefs_t to cutsceneref_t, cutsceneRefsReset to cutsceneRefReset, and cutscenerefs.c/.h to cutsceneref.c/.h

Co-Authored-By: Claude Sonnet 5 <[email protected]>

src/dusk/rpg/cutscene/CMakeLists.txt

@@ -7,7 +7,7 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
     cutscene.c
-    cutscenerefs.c
+    cutsceneref.c
     cutscenesystem.c
 )
 

src/dusk/rpg/cutscene/cutscene.c

@@ -135,7 +135,6 @@ void cutsceneAppend(
   const cutsceneitem_t *items,
   const uint8_t count
 ) {
-  assertNotNull(scene, "Scene cannot be NULL");
   cutsceneAppendAt(scene, scene->itemCount, items, count);
 }
 
@@ -158,6 +157,7 @@ errorret_t cutsceneLoadParse(
   assertNotNull(scene, "Scene cannot be NULL");
   assertNotNull(items, "Items cannot be NULL");
 
+  // Lock the asset, require it loaded.
   assetentry_t *entry = assetLock(path, ASSET_LOADER_TYPE_JSON, NULL);
   errorret_t result = assetRequireLoaded(entry);
   if(errorIsNotOk(result)) {
@@ -165,13 +165,12 @@ errorret_t cutsceneLoadParse(
     errorChain(result);
   }
 
-  // Parse straight out of the entry's own doc while still locked - every
+  // Parse the loaded JSON
-  // cutsceneitem_t field that could reference it owns its string data by
-  // value, so nothing needs to survive past this call and the entry can
-  // just be unlocked like any other asset once parsing finishes.
   errorret_t parseResult = cutsceneParseDoc(
     entry->data.json, scene, items, itemsMax
   );
+
+  // Free up the asset entry.
   assetUnlockEntry(entry);
   errorChain(parseResult);
 

src/dusk/rpg/cutscene/cutsceneref.c

@@ -5,11 +5,11 @@
  * https://opensource.org/licenses/MIT
  */
 
-#include "cutscenerefs.h"
+#include "cutsceneref.h"
 #include "assert/assert.h"
 
-void cutsceneRefsReset(
+void cutsceneRefReset(
-  cutscenesystemrefs_t *refs,
+  cutsceneref_t *refs,
   entity_t *interact,
   entity_t *interacted
 ) {
@@ -19,6 +19,6 @@ void cutsceneRefsReset(
   refs->entityInteracted = interacted;
   refs->entityLastCreated = NULL;
   refs->entityLastRef = NULL;
-  refs->areaLastCreated = CUTSCENE_AREA_LAST_CREATED;
+  refs->areaLastCreated = CUTSCENE_REF_AREA_LAST_CREATED;
-  refs->textMiniLastCreated = CUTSCENE_TEXT_MINI_LAST_CREATED;
+  refs->textMiniLastCreated = CUTSCENE_REF_TEXT_MINI_LAST_CREATED;
 }

src/dusk/rpg/cutscene/cutsceneref.h

@@ -0,0 +1,36 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "dusk.h"
+
+typedef struct entity_s entity_t;
+
+#define CUTSCENE_REF_AREA_LAST_CREATED ((uint8_t)0xFF)
+#define CUTSCENE_REF_TEXT_MINI_LAST_CREATED ((uint8_t)0xFA)
+
+typedef struct {
+  entity_t *entityInteract;
+  entity_t *entityInteracted;
+  entity_t *entityLastCreated;
+  entity_t *entityLastRef;
+  uint8_t areaLastCreated;
+  uint8_t textMiniLastCreated;
+} cutsceneref_t;
+
+/**
+ * Resets refs to an empty state.
+ *
+ * @param refs Refs to reset.
+ * @param interact The entity that initiated the interaction, or NULL.
+ * @param interacted The entity being interacted with, or NULL.
+ */
+void cutsceneRefReset(
+  cutsceneref_t *refs,
+  entity_t *interact,
+  entity_t *interacted
+);

src/dusk/rpg/cutscene/cutscenerefs.h

@@ -1,46 +0,0 @@
-/**
- * Copyright (c) 2026 Dominic Masters
- *
- * This software is released under the MIT License.
- * https://opensource.org/licenses/MIT
- */
-
-#pragma once
-#include "dusk.h"
-
-typedef struct entity_s entity_t;
-
-#define CUTSCENE_AREA_LAST_CREATED ((uint8_t)0xFF)
-#define CUTSCENE_TEXT_MINI_LAST_CREATED ((uint8_t)0xFA)
-
-/**
- * Common cutscene references that should survive a cutsceneRestart -
- * grouped into one struct (rather than loose fields on cutscenesystem_t)
- * so cutsceneRestart can snapshot/restore all of them in one copy instead
- * of field-by-field, and so anything added here later comes along for the
- * ride automatically.
- */
-typedef struct {
-  entity_t *entityInteract;
-  entity_t *entityInteracted;
-  entity_t *entityLastCreated;
-  entity_t *entityLastRef;
-  uint8_t areaLastCreated;
-  uint8_t textMiniLastCreated;
-} cutscenesystemrefs_t;
-
-/**
- * Resets refs to a fresh state: interact/interacted set to the given
- * entities, everything else (last-created entity, last-referenced entity,
- * last-created map area, last-created mini textbox) cleared back to its
- * "nothing yet" sentinel.
- *
- * @param refs Refs to reset.
- * @param interact The entity that initiated the interaction, or NULL.
- * @param interacted The entity being interacted with, or NULL.
- */
-void cutsceneRefsReset(
-  cutscenesystemrefs_t *refs,
-  entity_t *interact,
-  entity_t *interacted
-);

src/dusk/rpg/cutscene/cutscenesystem.c

@@ -32,7 +32,7 @@ void cutsceneSystemDispose() {
   CUTSCENE_SYSTEM.scene = NULL;
   CUTSCENE_SYSTEM.currentItem = CUTSCENE_CURRENT_ITEM_NONE;
   CUTSCENE_SYSTEM.pause = CUTSCENE_PAUSE_NONE;
-  cutsceneRefsReset(&CUTSCENE_SYSTEM.refs, NULL, NULL);
+  cutsceneRefReset(&CUTSCENE_SYSTEM.refs, NULL, NULL);
   CUTSCENE_SYSTEM.textCache[0] = '\0';
   CUTSCENE_SYSTEM.onComplete = NULL;
   CUTSCENE_SYSTEM.loadedFile[0] = '\0';
@@ -47,7 +47,7 @@ void cutsceneSystemPrepare(
 
   CUTSCENE_SYSTEM.scene = cutscene;
   CUTSCENE_SYSTEM.pause = cutscene->pause;
-  cutsceneRefsReset(&CUTSCENE_SYSTEM.refs, interact, interacted);
+  cutsceneRefReset(&CUTSCENE_SYSTEM.refs, interact, interacted);
   CUTSCENE_SYSTEM.textCache[0] = '\0';
   CUTSCENE_SYSTEM.onComplete = NULL;
 
@@ -159,25 +159,25 @@ void cutsceneRestart(void) {
   assertNotNull(
     CUTSCENE_SYSTEM.scene, "cutsceneRestart called with no cutscene running"
   );
+  assertTrue(
+    CUTSCENE_SYSTEM.scene == &CUTSCENE_SYSTEM.loadedScene,
+    "cutsceneRestart called with a cutscene not loaded from file"
+  );
+  assertTrue(
+    CUTSCENE_SYSTEM.loadedFile[0] != '\0',
+    "cutsceneRestart called with no loaded file"
+  );
   
-  // Snapshotted as one struct (rather than field-by-field) so anything
+  // Copy the refs and callbacks
-  // added to cutscenesystemrefs_t later - entities, map areas, mini
-  // textboxes, etc - survives a restart automatically instead of needing
-  // its own line here. cutsceneSystemPrepare (called from within both
-  // branches below) resets refs to a fresh state, so it's restored after.
   cutscenecallback_t onComplete = CUTSCENE_SYSTEM.onComplete;
-  cutscenesystemrefs_t refs = CUTSCENE_SYSTEM.refs;
+  cutsceneref_t refs = CUTSCENE_SYSTEM.refs;
 
-  if(CUTSCENE_SYSTEM.loadedFile[0] != '\0') {
+  // Reload the file.
-    char_t file[ASSET_FILE_NAME_MAX];
+  char_t file[ASSET_FILE_NAME_MAX];
-    stringCopy(file, CUTSCENE_SYSTEM.loadedFile, ASSET_FILE_NAME_MAX - 1);
+  stringCopy(file, CUTSCENE_SYSTEM.loadedFile, ASSET_FILE_NAME_MAX - 1);
-    cutsceneSystemLoad(file);
+  cutsceneSystemLoad(file);
-  } else {
-    cutsceneSystemStartCutsceneWith(
-      CUTSCENE_SYSTEM.scene, refs.entityInteract, refs.entityInteracted
-    );
-  }
 
+  // Restore the refs and callbacks.
   CUTSCENE_SYSTEM.onComplete = onComplete;
   CUTSCENE_SYSTEM.refs = refs;
 }
@@ -230,10 +230,10 @@ entity_t * cutsceneSystemGetEntity(const uint8_t entityIndex) {
 }
 
 uint8_t cutsceneSystemGetAreaId(const uint8_t areaId) {
-  if(areaId == CUTSCENE_AREA_LAST_CREATED) {
+  if(areaId == CUTSCENE_REF_AREA_LAST_CREATED) {
     assertTrue(
-      CUTSCENE_SYSTEM.refs.areaLastCreated != CUTSCENE_AREA_LAST_CREATED,
+      CUTSCENE_SYSTEM.refs.areaLastCreated != CUTSCENE_REF_AREA_LAST_CREATED,
-      "CUTSCENE_AREA_LAST_CREATED used but no map area has been created"
+      "CUTSCENE_REF_AREA_LAST_CREATED used but no map area has been created"
     );
     return CUTSCENE_SYSTEM.refs.areaLastCreated;
   }
@@ -241,11 +241,11 @@ uint8_t cutsceneSystemGetAreaId(const uint8_t areaId) {
 }
 
 uint8_t cutsceneSystemGetTextMiniId(const uint8_t index) {
-  if(index == CUTSCENE_TEXT_MINI_LAST_CREATED) {
+  if(index == CUTSCENE_REF_TEXT_MINI_LAST_CREATED) {
     assertTrue(
       CUTSCENE_SYSTEM.refs.textMiniLastCreated !=
-        CUTSCENE_TEXT_MINI_LAST_CREATED,
+        CUTSCENE_REF_TEXT_MINI_LAST_CREATED,
-      "CUTSCENE_TEXT_MINI_LAST_CREATED used but no mini textbox has been "
+      "CUTSCENE_REF_TEXT_MINI_LAST_CREATED used but no mini textbox has been "
       "shown"
     );
     return CUTSCENE_SYSTEM.refs.textMiniLastCreated;

src/dusk/rpg/cutscene/cutscenesystem.h

@@ -7,7 +7,7 @@
 
 #pragma once
 #include "cutscene.h"
-#include "cutscenerefs.h"
+#include "cutsceneref.h"
 
 #define CUTSCENE_ENTITY_INTERACT ((uint8_t)0xFE)
 #define CUTSCENE_ENTITY_INTERACTED ((uint8_t)0xFD)
@@ -24,7 +24,7 @@ typedef struct {
   uint8_t currentItem;
   cutscenepause_t pause;
 
-  cutscenesystemrefs_t refs;
+  cutsceneref_t refs;
 
   // Free-form text cache for the running cutscene - see
   // cutsceneSystemGetTextCache/cutsceneSystemSetTextCache.
@@ -183,7 +183,7 @@ void cutsceneSystemSetOnComplete(cutscenecallback_t onComplete);
 entity_t * cutsceneSystemGetEntity(const uint8_t entityIndex);
 
 /**
- * Resolves a raw map area ID (or CUTSCENE_AREA_LAST_CREATED sentinel) to
+ * Resolves a raw map area ID (or CUTSCENE_REF_AREA_LAST_CREATED sentinel) to
  * a concrete map area ID.
  *
  * @param areaId Raw map area ID or sentinel value.
@@ -192,7 +192,7 @@ entity_t * cutsceneSystemGetEntity(const uint8_t entityIndex);
 uint8_t cutsceneSystemGetAreaId(const uint8_t areaId);
 
 /**
- * Resolves a raw mini textbox slot index (or CUTSCENE_TEXT_MINI_LAST_CREATED
+ * Resolves a raw mini textbox slot index (or CUTSCENE_REF_TEXT_MINI_LAST_CREATED
  * sentinel) to a concrete UI_TEXTBOX_MINI_LIST slot index.
  *
  * @param index Raw slot index or sentinel value.

src/dusk/rpg/cutscene/item/json/cutscenejsonareaid.h

@@ -10,7 +10,7 @@
 #include "yyjson.h"
 
 // Sentinel accepted in place of a literal area id - see cutscenesystem.h's
-// CUTSCENE_AREA_LAST_CREATED. Kept local since it's a JSON-authoring
+// CUTSCENE_REF_AREA_LAST_CREATED. Kept local since it's a JSON-authoring
 // convenience, not part of the item struct definitions themselves.
 #define CUTSCENE_JSON_AREA_SENTINEL_LAST_CREATED ((uint8_t)0xFF)
 

src/dusk/rpg/cutscene/item/maparea/cutscenemaparearemove.h

@@ -14,7 +14,7 @@ typedef struct {
 
 /**
  * Starts a map area remove step (removes the area immediately). Accepts
- * CUTSCENE_AREA_LAST_CREATED in place of a literal area ID.
+ * CUTSCENE_REF_AREA_LAST_CREATED in place of a literal area ID.
  *
  * @param item The cutscene item.
  * @param data Runtime data storage.

test/rpg/cutscene/test_cutscenemaparea.c

@@ -75,7 +75,7 @@ static void test_cutsceneMapAreaRemoveResolvesLastCreatedSentinel(
 
   cutsceneitem_t removeItem = {
     .type = CUTSCENE_ITEM_TYPE_MAP_AREA_REMOVE,
-    .mapAreaRemove = { .areaId = CUTSCENE_AREA_LAST_CREATED }
+    .mapAreaRemove = { .areaId = CUTSCENE_REF_AREA_LAST_CREATED }
   };
   cutsceneMapAreaRemoveStart(&removeItem, &data);
   assert_null(MAP_AREAS[id].callback);
@@ -150,7 +150,7 @@ static void test_cutsceneMapAreaWaitResolvesLastCreatedSentinel(
 
   cutsceneitem_t waitItem = {
     .type = CUTSCENE_ITEM_TYPE_MAP_AREA_WAIT,
-    .mapAreaWait = { .areaIds = { CUTSCENE_AREA_LAST_CREATED }, .count = 1 }
+    .mapAreaWait = { .areaIds = { CUTSCENE_REF_AREA_LAST_CREATED }, .count = 1 }
   };
   cutsceneMapAreaWaitStart(&waitItem, &data);
   assert_false(cutsceneMapAreaWaitUpdate(&waitItem, &data));

test/rpg/cutscene/test_cutscenesystem.c

@@ -158,28 +158,28 @@ static void test_cutsceneSystemGetAreaId(void **state) {
   cutsceneSystemInit();
   // cutsceneSystemInit() zero-inits the field -- only actually starting a
   // cutscene sets it to the "nothing created yet" sentinel.
-  CUTSCENE_SYSTEM.refs.areaLastCreated = CUTSCENE_AREA_LAST_CREATED;
+  CUTSCENE_SYSTEM.refs.areaLastCreated = CUTSCENE_REF_AREA_LAST_CREATED;
 
-  expect_assert_failure(cutsceneSystemGetAreaId(CUTSCENE_AREA_LAST_CREATED));
+  expect_assert_failure(cutsceneSystemGetAreaId(CUTSCENE_REF_AREA_LAST_CREATED));
   assert_int_equal(cutsceneSystemGetAreaId(5), 5);// direct IDs pass through
 
   CUTSCENE_SYSTEM.refs.areaLastCreated = 3;
-  assert_int_equal(cutsceneSystemGetAreaId(CUTSCENE_AREA_LAST_CREATED), 3);
+  assert_int_equal(cutsceneSystemGetAreaId(CUTSCENE_REF_AREA_LAST_CREATED), 3);
 }
 
 static void test_cutsceneSystemGetTextMiniId(void **state) {
 
   cutsceneSystemInit();
-  CUTSCENE_SYSTEM.refs.textMiniLastCreated = CUTSCENE_TEXT_MINI_LAST_CREATED;
+  CUTSCENE_SYSTEM.refs.textMiniLastCreated = CUTSCENE_REF_TEXT_MINI_LAST_CREATED;
 
   expect_assert_failure(
-    cutsceneSystemGetTextMiniId(CUTSCENE_TEXT_MINI_LAST_CREATED)
+    cutsceneSystemGetTextMiniId(CUTSCENE_REF_TEXT_MINI_LAST_CREATED)
   );
   assert_int_equal(cutsceneSystemGetTextMiniId(4), 4);
 
   CUTSCENE_SYSTEM.refs.textMiniLastCreated = 1;
   assert_int_equal(
-    cutsceneSystemGetTextMiniId(CUTSCENE_TEXT_MINI_LAST_CREATED), 1
+    cutsceneSystemGetTextMiniId(CUTSCENE_REF_TEXT_MINI_LAST_CREATED), 1
   );
 }