Rebuild battle flow as an explicit state machine with cutscene hooks

Replace the one-fighter-at-a-time turn model with an OPENING/PRE_ROUND/
PLAYER_SELECTION/AI_SELECTION/MOVES_EXECUTING/POST_ROUND/ENDED state
machine and a per-fighter action queue, so actions are decided before any
of them execute (needed for speed-ordered resolution) and so a cutscene
can pause the battle, wait for a specific state, and force a fighter's
action -- enabling automated, fully-scripted, and partially-scripted
battles. Adds CUTSCENE_PAUSE_BATTLE plus CUTSCENE_BATTLE_WAIT_STATE and
CUTSCENE_BATTLE_FORCE_ACTION cutscene items, and generic onStateChanged/
onActionDecided callbacks on battle_t. Re-enables the long-dormant
test/rpg suite and adds test/rpg/battle covering the state machine and
the new cutscene hooks end-to-end.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

src/dusk/rpg/battle/battle.c

@@ -8,6 +8,7 @@
 #include "battle.h"
 #include "assert/assert.h"
 #include "util/memory.h"
+#include "rpg/cutscene/cutscenesystem.h"
 
 battle_t BATTLE;
 
@@ -51,10 +52,8 @@ void battleStart(
   BATTLE.fleeAvailable = fleeAvailable;
   BATTLE.result = BATTLE_RESULT_NONE;
   BATTLE.round = 1;
-  BATTLE.turnIndex = 0;
-  battleBuildTurnOrder(true);
 
-  BATTLE.active = true;
+  battleSetState(BATTLE_STATE_OPENING);
 }
 
 void battleDispose(void) {
@@ -62,9 +61,9 @@ void battleDispose(void) {
 }
 
 battlefighter_t *battleGetCurrentFighter(void) {
-  if(!BATTLE.active) return NULL;
-  if(BATTLE.turnIndex >= BATTLE.turnCount) return NULL;
-  return &BATTLE.fighters[BATTLE.turnOrder[BATTLE.turnIndex]];
+  if(BATTLE.state != BATTLE_STATE_PLAYER_SELECTION) return NULL;
+  if(BATTLE.selectionIndex >= BATTLE.executionCount) return NULL;
+  return &BATTLE.fighters[BATTLE.executionOrder[BATTLE.selectionIndex]];
 }
 
 uint8_t battleGetAliveCount(const battlefighterteam_t team) {
@@ -92,91 +91,105 @@ void battleResolveAttack(
   if(defender->health == 0) defender->status = BATTLE_FIGHTER_STATUS_DEAD;
 }
 
-void battleNextTurn(void) {
-  BATTLE.turnIndex++;
-  if(BATTLE.turnIndex < BATTLE.turnCount) return;
-
-  BATTLE.round++;
-  BATTLE.turnIndex = 0;
-  battleBuildTurnOrder(false);
-}
-
 battleresult_t battleCheckResult(void) {
   if(BATTLE.result != BATTLE_RESULT_NONE) return BATTLE.result;
 
   if(battleGetAliveCount(BATTLE_FIGHTER_TEAM_ALLY) == 0) {
-    BATTLE.result = BATTLE_RESULT_LOSS;
+    battleSetResult(BATTLE_RESULT_LOSS);
   } else if(battleGetAliveCount(BATTLE_FIGHTER_TEAM_ENEMY) == 0) {
-    BATTLE.result = BATTLE_RESULT_WIN;
+    battleSetResult(BATTLE_RESULT_WIN);
   }
 
   return BATTLE.result;
 }
 
+void battleQueueAction(
+  const uint8_t fighterIndex,
+  const battleactiontype_t type,
+  const uint8_t targetIndex
+) {
+  battleaction_t *action = &BATTLE.actions[fighterIndex];
+  action->type = type;
+  action->targetIndex = targetIndex;
+
+  if(BATTLE.onActionDecided != NULL) {
+    BATTLE.onActionDecided(&BATTLE.fighters[fighterIndex], action);
+  }
+}
+
 void battlePlayerAttack(const uint8_t targetIndex) {
-  battlefighter_t *attacker = battleGetCurrentFighter();
-  if(attacker == NULL) return;
-  if(attacker->controller != BATTLE_FIGHTER_CONTROLLER_PLAYER) return;
+  battlefighter_t *fighter = battleGetCurrentFighter();
+  if(fighter == NULL) return;
   if(targetIndex >= BATTLE_FIGHTER_COUNT_MAX) return;
+  if(!battleFighterIsAlive(&BATTLE.fighters[targetIndex])) return;
 
-  battlefighter_t *defender = &BATTLE.fighters[targetIndex];
-  if(!battleFighterIsAlive(defender)) return;
-
-  battleResolveAttack(attacker, defender);
-  battleCheckResult();
-  if(BATTLE.result == BATTLE_RESULT_NONE) battleNextTurn();
+  battleQueueAction(fighter->id, BATTLE_ACTION_ATTACK, targetIndex);
+  BATTLE.selectionIndex++;
+  battleAdvanceSelection();
 }
 
 void battlePlayerFlee(void) {
   battlefighter_t *fighter = battleGetCurrentFighter();
   if(fighter == NULL) return;
-  if(fighter->controller != BATTLE_FIGHTER_CONTROLLER_PLAYER) return;
   if(!BATTLE.fleeAvailable) return;
 
-  BATTLE.result = BATTLE_RESULT_FLED;
+  battleSetResult(BATTLE_RESULT_FLED);
 }
 
 void battleUpdate(void) {
-  if(!BATTLE.active) return;
-  if(BATTLE.result != BATTLE_RESULT_NONE) return;
+  if(BATTLE.state == BATTLE_STATE_NONE) return;
+  if(BATTLE.state == BATTLE_STATE_ENDED) return;
+  if(CUTSCENE_SYSTEM.pause & CUTSCENE_PAUSE_BATTLE) return;
 
-  battlefighter_t *current = battleGetCurrentFighter();
-  if(current == NULL) return;
+  switch(BATTLE.state) {
+    case BATTLE_STATE_OPENING:
+      battleSetState(BATTLE_STATE_PRE_ROUND);
+      break;
 
-  if(!battleFighterIsAlive(current)) {
-    battleNextTurn();
-    return;
+    case BATTLE_STATE_PRE_ROUND:
+      battleUpdatePreRound();
+      break;
+
+    case BATTLE_STATE_AI_SELECTION:
+      battleUpdateAiSelection();
+      break;
+
+    case BATTLE_STATE_MOVES_EXECUTING:
+      battleUpdateMovesExecuting();
+      break;
+
+    case BATTLE_STATE_POST_ROUND:
+      battleUpdatePostRound();
+      break;
+
+    default:
+      // BATTLE_STATE_PLAYER_SELECTION: waits on battlePlayerAttack/Flee.
+      // BATTLE_STATE_NONE/ENDED: handled above.
+      break;
   }
-
-  if(current->controller != BATTLE_FIGHTER_CONTROLLER_AI) return;
-
-  battlefighter_t *target = battleAIChooseTarget(current);
-  if(target != NULL) battleResolveAttack(current, target);
-
-  battleCheckResult();
-  if(BATTLE.result == BATTLE_RESULT_NONE) battleNextTurn();
 }
 
-void battleBuildTurnOrder(const bool_t applyEncounterBias) {
-  BATTLE.turnCount = 0;
+void battleBuildExecutionOrder(const bool_t applyEncounterBias) {
+  BATTLE.executionCount = 0;
   for(uint8_t i = 0; i < BATTLE_FIGHTER_COUNT_MAX; i++) {
     if(!battleFighterIsAlive(&BATTLE.fighters[i])) continue;
-    BATTLE.turnOrder[BATTLE.turnCount++] = i;
+    BATTLE.executionOrder[BATTLE.executionCount++] = i;
   }
 
   // Insertion sort by speed descending -- fine for BATTLE_FIGHTER_COUNT_MAX.
-  for(uint8_t i = 1; i < BATTLE.turnCount; i++) {
-    const uint8_t key = BATTLE.turnOrder[i];
+  for(uint8_t i = 1; i < BATTLE.executionCount; i++) {
+    const uint8_t key = BATTLE.executionOrder[i];
     const uint16_t keySpeed = BATTLE.fighters[key].stats.speed;
 
     int8_t j = (int8_t)i - 1;
     while(
-      j >= 0 && BATTLE.fighters[BATTLE.turnOrder[j]].stats.speed < keySpeed
+      j >= 0 &&
+      BATTLE.fighters[BATTLE.executionOrder[j]].stats.speed < keySpeed
     ) {
-      BATTLE.turnOrder[j + 1] = BATTLE.turnOrder[j];
+      BATTLE.executionOrder[j + 1] = BATTLE.executionOrder[j];
       j--;
     }
-    BATTLE.turnOrder[j + 1] = key;
+    BATTLE.executionOrder[j + 1] = key;
   }
 
   if(!applyEncounterBias) return;
@@ -192,16 +205,16 @@ void battleMoveTeamFirst(const battlefighterteam_t team) {
   uint8_t sorted[BATTLE_FIGHTER_COUNT_MAX];
   uint8_t count = 0;
 
-  for(uint8_t i = 0; i < BATTLE.turnCount; i++) {
-    if(BATTLE.fighters[BATTLE.turnOrder[i]].team != team) continue;
-    sorted[count++] = BATTLE.turnOrder[i];
+  for(uint8_t i = 0; i < BATTLE.executionCount; i++) {
+    if(BATTLE.fighters[BATTLE.executionOrder[i]].team != team) continue;
+    sorted[count++] = BATTLE.executionOrder[i];
   }
-  for(uint8_t i = 0; i < BATTLE.turnCount; i++) {
-    if(BATTLE.fighters[BATTLE.turnOrder[i]].team == team) continue;
-    sorted[count++] = BATTLE.turnOrder[i];
+  for(uint8_t i = 0; i < BATTLE.executionCount; i++) {
+    if(BATTLE.fighters[BATTLE.executionOrder[i]].team == team) continue;
+    sorted[count++] = BATTLE.executionOrder[i];
   }
 
-  memoryCopy(BATTLE.turnOrder, sorted, sizeof(uint8_t) * BATTLE.turnCount);
+  memoryCopy(BATTLE.executionOrder, sorted, sizeof(uint8_t) * BATTLE.executionCount);
 }
 
 battlefighter_t *battleAIChooseTarget(const battlefighter_t *fighter) {
@@ -221,3 +234,93 @@ battlefighter_t *battleAIChooseTarget(const battlefighter_t *fighter) {
 
   return weakest;
 }
+
+void battleSetState(const battlestate_t next) {
+  const battlestate_t previous = BATTLE.state;
+  BATTLE.state = next;
+  if(BATTLE.onStateChanged != NULL) BATTLE.onStateChanged(previous, next);
+}
+
+void battleSetResult(const battleresult_t result) {
+  BATTLE.result = result;
+  battleSetState(BATTLE_STATE_ENDED);
+}
+
+bool_t battleFighterNeedsDecision(
+  const uint8_t fighterIndex,
+  const battlefightercontroller_t controller
+) {
+  return battleFighterIsAlive(&BATTLE.fighters[fighterIndex])
+    && BATTLE.fighters[fighterIndex].controller == controller
+    && BATTLE.actions[fighterIndex].type == BATTLE_ACTION_NONE;
+}
+
+void battleAdvanceSelection(void) {
+  while(BATTLE.selectionIndex < BATTLE.executionCount) {
+    const uint8_t fighterIndex = BATTLE.executionOrder[BATTLE.selectionIndex];
+    if(
+      battleFighterNeedsDecision(fighterIndex, BATTLE_FIGHTER_CONTROLLER_PLAYER)
+    ) {
+      return;
+    }
+    BATTLE.selectionIndex++;
+  }
+
+  battleSetState(BATTLE_STATE_AI_SELECTION);
+}
+
+void battleUpdatePreRound(void) {
+  // No need to clear BATTLE.actions here: every living fighter's action is
+  // unconditionally reset to BATTLE_ACTION_NONE as it's processed in
+  // battleUpdateMovesExecuting, and round 1 starts pre-zeroed by
+  // battleInit(). Clearing it here would also wipe out any action a
+  // cutscene force-queued while parked at BATTLE_STATE_PRE_ROUND.
+  battleBuildExecutionOrder(BATTLE.round == 1);
+
+  BATTLE.selectionIndex = 0;
+  battleSetState(BATTLE_STATE_PLAYER_SELECTION);
+  battleAdvanceSelection();
+}
+
+void battleUpdateAiSelection(void) {
+  for(uint8_t i = 0; i < BATTLE.executionCount; i++) {
+    const uint8_t fighterIndex = BATTLE.executionOrder[i];
+    if(
+      !battleFighterNeedsDecision(fighterIndex, BATTLE_FIGHTER_CONTROLLER_AI)
+    ) continue;
+
+    battlefighter_t *target =
+      battleAIChooseTarget(&BATTLE.fighters[fighterIndex]);
+    if(target == NULL) continue;
+
+    battleQueueAction(fighterIndex, BATTLE_ACTION_ATTACK, target->id);
+  }
+
+  BATTLE.executionIndex = 0;
+  battleSetState(BATTLE_STATE_MOVES_EXECUTING);
+}
+
+void battleUpdateMovesExecuting(void) {
+  if(BATTLE.executionIndex >= BATTLE.executionCount) {
+    battleSetState(BATTLE_STATE_POST_ROUND);
+    return;
+  }
+
+  const uint8_t fighterIndex = BATTLE.executionOrder[BATTLE.executionIndex++];
+  battlefighter_t *fighter = &BATTLE.fighters[fighterIndex];
+  if(!battleFighterIsAlive(fighter)) return;
+
+  battleaction_t *action = &BATTLE.actions[fighterIndex];
+  if(action->type == BATTLE_ACTION_ATTACK) {
+    battlefighter_t *target = &BATTLE.fighters[action->targetIndex];
+    if(battleFighterIsAlive(target)) battleResolveAttack(fighter, target);
+  }
+  action->type = BATTLE_ACTION_NONE;
+
+  battleCheckResult();
+}
+
+void battleUpdatePostRound(void) {
+  BATTLE.round++;
+  battleSetState(BATTLE_STATE_PRE_ROUND);
+}

src/dusk/rpg/battle/battle.h

@@ -27,19 +27,68 @@ typedef enum {
   BATTLE_RESULT_COUNT
 } battleresult_t;
 
+// Where BATTLE currently is within a round. A cutscene can pause progression
+// (CUTSCENE_PAUSE_BATTLE) and use CUTSCENE_BATTLE_WAIT_STATE to synchronize
+// with any of these, or CUTSCENE_BATTLE_FORCE_ACTION to decide a fighter's
+// action ahead of PLAYER_SELECTION/AI_SELECTION reaching them.
+typedef enum {
+  BATTLE_STATE_NONE, // Battle inactive.
+
+  BATTLE_STATE_OPENING, // Entered once by battleStart().
+  BATTLE_STATE_PRE_ROUND, // Rebuilds execution order, clears the action queue.
+  BATTLE_STATE_PLAYER_SELECTION, // Waits on battlePlayerAttack/Flee.
+  BATTLE_STATE_AI_SELECTION, // Auto-queues every undecided AI fighter.
+  BATTLE_STATE_MOVES_EXECUTING, // Resolves one queued action per update.
+  BATTLE_STATE_POST_ROUND, // Round wrap-up; loops back to PRE_ROUND.
+
+  BATTLE_STATE_ENDED, // Terminal for WIN/LOSS/FLED alike -- see BATTLE.result.
+
+  BATTLE_STATE_COUNT
+} battlestate_t;
+
+typedef enum {
+  BATTLE_ACTION_NONE, // No action decided yet for this fighter this round.
+  BATTLE_ACTION_ATTACK,
+
+  BATTLE_ACTION_COUNT
+} battleactiontype_t;
+
 typedef struct {
-  bool_t active;
+  battleactiontype_t type;
+  uint8_t targetIndex; // Meaningful for BATTLE_ACTION_ATTACK.
+} battleaction_t;
+
+typedef void (*battlestatechangedcallback_t)(
+  const battlestate_t previous,
+  const battlestate_t next
+);
+
+typedef void (*battleactiondecidedcallback_t)(
+  const battlefighter_t *fighter,
+  const battleaction_t *action
+);
+
+typedef struct {
+  battlestate_t state;
   battlefighter_t fighters[BATTLE_FIGHTER_COUNT_MAX];
+  battleaction_t actions[BATTLE_FIGHTER_COUNT_MAX];
 
   battleencountertype_t encounterType;
   bool_t fleeAvailable;
   battleresult_t result;
 
   // Fighter indices (into fighters[]), sorted for the current round.
-  uint8_t turnOrder[BATTLE_FIGHTER_COUNT_MAX];
-  uint8_t turnCount;
-  uint8_t turnIndex;
+  uint8_t executionOrder[BATTLE_FIGHTER_COUNT_MAX];
+  uint8_t executionCount;
+  uint8_t executionIndex;
   uint16_t round;
+
+  // Cursor into executionOrder used by BATTLE_STATE_PLAYER_SELECTION to find
+  // the next player-controlled fighter that still needs a decision.
+  uint8_t selectionIndex;
+
+  battlestatechangedcallback_t onStateChanged;
+  battleactiondecidedcallback_t onActionDecided;
 } battle_t;
 
 extern battle_t BATTLE;
@@ -77,11 +126,10 @@ battlefighter_t *battleAddFighter(
 );
 
 /**
- * Starts the battle: builds the opening turn order (biased by
- * encounterType for the first round only) and marks the battle active.
- * Call once every fighter has been added via battleAddFighter.
+ * Starts the battle: enters BATTLE_STATE_OPENING and marks the battle
+ * active. Call once every fighter has been added via battleAddFighter.
  *
- * @param encounterType Determines the opening round's turn order.
+ * @param encounterType Determines the opening round's execution order.
  * @param fleeAvailable Whether the party may attempt to flee this battle.
  */
 void battleStart(
@@ -95,10 +143,11 @@ void battleStart(
 void battleDispose(void);
 
 /**
- * Returns the fighter whose turn it currently is.
+ * Returns the fighter currently awaiting a player decision.
  *
- * @return Pointer to the active fighter, or NULL if the battle isn't
- *         active or has no living fighters left to act.
+ * @return Pointer to the fighter awaiting a decision, or NULL if the battle
+ *         isn't in BATTLE_STATE_PLAYER_SELECTION or every player-controlled
+ *         fighter has already decided.
  */
 battlefighter_t *battleGetCurrentFighter(void);
 
@@ -125,61 +174,68 @@ void battleResolveAttack(
 );
 
 /**
- * Ends the current fighter's turn and advances to the next fighter in
- * the turn order, starting a new round (rebuilding turn order purely by
- * speed) once every fighter in the current round has acted.
- */
-void battleNextTurn(void);
-
-/**
- * Checks whether the battle has been won or lost, updating and
- * returning BATTLE.result. Does nothing if a result has already been
- * set (e.g. by a successful flee).
+ * Checks whether the battle has been won or lost, transitioning to
+ * BATTLE_STATE_ENDED and updating BATTLE.result if so. Does nothing if a
+ * result has already been set (e.g. by a successful flee).
  *
  * @return The battle's current result.
  */
 battleresult_t battleCheckResult(void);
 
 /**
- * Submits the current fighter's attack against a target, if it is
- * currently a player-controlled fighter's turn. Resolves the attack,
- * checks for a battle result, and advances the turn.
+ * Queues an action for a fighter to perform once BATTLE_STATE_MOVES_EXECUTING
+ * reaches them this round, overwriting any action already queued for that
+ * fighter. Fires BATTLE.onActionDecided.
+ *
+ * @param fighterIndex Index into BATTLE.fighters of the deciding fighter.
+ * @param type The type of action to perform.
+ * @param targetIndex Index into BATTLE.fighters of the target, meaningful
+ *        for BATTLE_ACTION_ATTACK.
+ */
+void battleQueueAction(
+  const uint8_t fighterIndex,
+  const battleactiontype_t type,
+  const uint8_t targetIndex
+);
+
+/**
+ * Submits the currently-selecting fighter's attack against a target, if the
+ * battle is in BATTLE_STATE_PLAYER_SELECTION and awaiting a decision.
+ * Queues the action and advances the selection cursor.
  *
  * @param targetIndex Index into BATTLE.fighters of the target.
  */
 void battlePlayerAttack(const uint8_t targetIndex);
 
 /**
- * Submits a flee attempt for the current fighter's turn, if it is
- * currently a player-controlled fighter's turn and fleeing is
- * available for this battle. Always succeeds, ending the battle with
- * BATTLE_RESULT_FLED.
+ * Submits a flee attempt for the currently-selecting fighter, if the battle
+ * is in BATTLE_STATE_PLAYER_SELECTION and fleeing is available for this
+ * battle. Always succeeds, ending the battle with BATTLE_RESULT_FLED.
  */
 void battlePlayerFlee(void);
 
 /**
- * Updates the battle simulation for one frame: resolves the current
- * fighter's turn automatically if AI-controlled, otherwise waits for a
- * player action via battlePlayerAttack/battlePlayerFlee. No-op if the
- * battle isn't active or already has a result.
+ * Updates the battle simulation for one frame, dispatching on BATTLE.state.
+ * No-op if the battle isn't active, has already ended, or
+ * CUTSCENE_PAUSE_BATTLE is set.
  */
 void battleUpdate(void);
 
 /**
- * Rebuilds BATTLE.turnOrder/turnCount from every currently living
+ * Rebuilds BATTLE.executionOrder/executionCount from every currently living
  * fighter, sorted by speed descending.
  *
  * @param applyEncounterBias If true, reorders the freshly speed-sorted
  * queue so BATTLE.encounterType's favoured team goes first (used only
  * for the opening round).
  */
-void battleBuildTurnOrder(const bool_t applyEncounterBias);
+void battleBuildExecutionOrder(const bool_t applyEncounterBias);
 
 /**
- * Stably partitions BATTLE.turnOrder so every fighter on the given team
+ * Stably partitions BATTLE.executionOrder so every fighter on the given team
  * comes first, preserving each side's relative (speed-sorted) order.
  *
- * @param team The team to move to the front of the turn order.
+ * @param team The team to move to the front of the execution order.
  */
 void battleMoveTeamFirst(const battlefighterteam_t team);
 
@@ -192,3 +248,66 @@ void battleMoveTeamFirst(const battlefighterteam_t team);
  *         living fighters.
  */
 battlefighter_t *battleAIChooseTarget(const battlefighter_t *fighter);
+
+/**
+ * Sets BATTLE.state and fires BATTLE.onStateChanged with the previous and
+ * new state.
+ *
+ * @param next The state to transition to.
+ */
+void battleSetState(const battlestate_t next);
+
+/**
+ * Sets BATTLE.result and transitions to BATTLE_STATE_ENDED.
+ *
+ * @param result The result to end the battle with.
+ */
+void battleSetResult(const battleresult_t result);
+
+/**
+ * Checks whether a fighter is a live, undecided candidate for the given
+ * controller -- i.e. whether PLAYER_SELECTION or AI_SELECTION should still
+ * be deciding an action for it this round.
+ *
+ * @param fighterIndex Index into BATTLE.fighters to check.
+ * @param controller The controller PLAYER_SELECTION/AI_SELECTION is
+ *        currently deciding for.
+ * @return True if the fighter is alive, matches controller, and has no
+ *         action queued yet.
+ */
+bool_t battleFighterNeedsDecision(
+  const uint8_t fighterIndex,
+  const battlefightercontroller_t controller
+);
+
+/**
+ * Advances BATTLE.selectionIndex to the next player-controlled fighter that
+ * still needs a decision, or transitions to BATTLE_STATE_AI_SELECTION once
+ * none remain.
+ */
+void battleAdvanceSelection(void);
+
+/**
+ * Handles BATTLE_STATE_PRE_ROUND: rebuilds the execution order and moves on
+ * to BATTLE_STATE_PLAYER_SELECTION, positioning the selection cursor.
+ */
+void battleUpdatePreRound(void);
+
+/**
+ * Handles BATTLE_STATE_AI_SELECTION: queues an attack for every undecided
+ * AI-controlled fighter, then moves on to BATTLE_STATE_MOVES_EXECUTING.
+ */
+void battleUpdateAiSelection(void);
+
+/**
+ * Handles BATTLE_STATE_MOVES_EXECUTING: resolves one queued action from
+ * BATTLE.executionOrder per call, or transitions to BATTLE_STATE_POST_ROUND
+ * once every fighter this round has been processed.
+ */
+void battleUpdateMovesExecuting(void);
+
+/**
+ * Handles BATTLE_STATE_POST_ROUND: advances BATTLE.round and transitions
+ * back to BATTLE_STATE_PRE_ROUND.
+ */
+void battleUpdatePostRound(void);

src/dusk/rpg/cutscene/cutscene.h

@@ -162,6 +162,28 @@ typedef struct cutscene_s {
     .shake = { .amount = AMOUNT, .duration = DURATION } \
   }
 
+// Waits until BATTLE.state reaches STATE. Put this BEFORE
+// CUTSCENE_SET_PAUSE(CUTSCENE_PAUSE_BATTLE), not after -- pausing first
+// freezes BATTLE.state wherever it already is, so it would never reach
+// STATE on its own to satisfy the wait. Waiting unpaused, then pausing the
+// moment it's satisfied, catches the battle right at STATE before it can
+// advance further.
+#define CUTSCENE_BATTLE_WAIT_STATE(STATE) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_BATTLE_WAIT_STATE, \
+    .battleWaitState = { .state = STATE } \
+  }
+
+// Immediately queues an attack for FIGHTER_INDEX against TARGET_INDEX,
+// bypassing normal player/AI selection for that fighter this round.
+#define CUTSCENE_BATTLE_FORCE_ACTION(FIGHTER_INDEX, TARGET_INDEX) \
+  { \
+    .type = CUTSCENE_ITEM_TYPE_BATTLE_FORCE_ACTION, \
+    .battleForceAction = { \
+      .fighterIndex = FIGHTER_INDEX, .targetIndex = TARGET_INDEX \
+    } \
+  }
+
 #define CUTSCENE_SET_PAUSE(FLAGS) \
   { .type = CUTSCENE_ITEM_TYPE_SET_PAUSE, .setPause = (FLAGS) }
 

src/dusk/rpg/cutscene/cutscenepause.h

@@ -14,11 +14,13 @@ typedef uint8_t cutscenepause_t;
 #define CUTSCENE_PAUSE_NPC     ((cutscenepause_t)(1 << 0))
 #define CUTSCENE_PAUSE_PLAYER  ((cutscenepause_t)(1 << 1))
 #define CUTSCENE_PAUSE_WORLD   ((cutscenepause_t)(1 << 2))
+#define CUTSCENE_PAUSE_BATTLE  ((cutscenepause_t)(1 << 3))
 
 #define CUTSCENE_PAUSE_DEFAULT ((cutscenepause_t)( \
   CUTSCENE_PAUSE_NPC | CUTSCENE_PAUSE_PLAYER \
 ))
 
 #define CUTSCENE_PAUSE_ALL ((cutscenepause_t)( \
-  CUTSCENE_PAUSE_NPC | CUTSCENE_PAUSE_PLAYER | CUTSCENE_PAUSE_WORLD \
+  CUTSCENE_PAUSE_NPC | CUTSCENE_PAUSE_PLAYER | CUTSCENE_PAUSE_WORLD | \
+  CUTSCENE_PAUSE_BATTLE \
 ))

src/dusk/rpg/cutscene/item/battle/CMakeLists.txt

@@ -6,4 +6,6 @@
 target_sources(${DUSK_LIBRARY_TARGET_NAME}
   PUBLIC
     cutscenestartbattle.c
+    cutscenebattlewaitstate.c
+    cutscenebattleforceaction.c
 )

src/dusk/rpg/cutscene/item/battle/cutscenebattleforceaction.c

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+
+void cutsceneBattleForceActionStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  battleQueueAction(
+    item->battleForceAction.fighterIndex, BATTLE_ACTION_ATTACK,
+    item->battleForceAction.targetIndex
+  );
+}
+
+bool_t cutsceneBattleForceActionUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return true;
+}

src/dusk/rpg/cutscene/item/battle/cutscenebattleforceaction.h

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/battle/battle.h"
+
+typedef struct {
+  uint8_t fighterIndex;
+  uint8_t targetIndex;
+} cutscenebattleforceaction_t;
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+/**
+ * Starts a battle force-action step: immediately queues an attack for the
+ * given fighter against the given target, bypassing normal player/AI
+ * selection for that fighter this round.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ */
+void cutsceneBattleForceActionStart(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);
+
+/**
+ * Updates a battle force-action step (always completes immediately).
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true always.
+ */
+bool_t cutsceneBattleForceActionUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/battle/cutscenebattlewaitstate.c

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#include "rpg/cutscene/item/cutsceneitem.h"
+
+bool_t cutsceneBattleWaitStateUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+) {
+  return BATTLE.state == item->battleWaitState.state;
+}

src/dusk/rpg/cutscene/item/battle/cutscenebattlewaitstate.h

@@ -0,0 +1,30 @@
+/**
+ * Copyright (c) 2026 Dominic Masters
+ *
+ * This software is released under the MIT License.
+ * https://opensource.org/licenses/MIT
+ */
+
+#pragma once
+#include "rpg/battle/battle.h"
+
+typedef struct {
+  battlestate_t state;
+} cutscenebattlewaitstate_t;
+
+typedef struct cutsceneitem_s cutsceneitem_t;
+typedef union cutsceneitemdata_u cutsceneitemdata_t;
+
+/**
+ * Updates a battle wait-state step, completing once BATTLE.state reaches
+ * the watched state. Has no Start callback -- there's nothing to do until
+ * the state is actually reached.
+ *
+ * @param item The cutscene item.
+ * @param data Runtime data storage.
+ * @returns true once BATTLE.state equals the watched state.
+ */
+bool_t cutsceneBattleWaitStateUpdate(
+  const cutsceneitem_t *item,
+  cutsceneitemdata_t *data
+);

src/dusk/rpg/cutscene/item/cutsceneitem.c

@@ -118,6 +118,15 @@ cutsceneitemcallbacks_t CUTSCENE_ITEM_CALLBACKS[CUTSCENE_ITEM_TYPE_COUNT] = {
   [CUTSCENE_ITEM_TYPE_SHAKE] = {
     .init = cutsceneShakeStart,
     .update = cutsceneShakeUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_BATTLE_WAIT_STATE] = {
+    .update = cutsceneBattleWaitStateUpdate
+  },
+
+  [CUTSCENE_ITEM_TYPE_BATTLE_FORCE_ACTION] = {
+    .init = cutsceneBattleForceActionStart,
+    .update = cutsceneBattleForceActionUpdate
   }
 };
 

src/dusk/rpg/cutscene/item/cutsceneitem.h

@@ -27,6 +27,8 @@
 #include "maparea/cutscenemaparearemove.h"
 #include "maparea/cutscenemapareawait.h"
 #include "battle/cutscenestartbattle.h"
+#include "battle/cutscenebattlewaitstate.h"
+#include "battle/cutscenebattleforceaction.h"
 
 typedef struct cutscene_s cutscene_t;
 
@@ -55,6 +57,8 @@ typedef enum {
   CUTSCENE_ITEM_TYPE_START_BATTLE,
   CUTSCENE_ITEM_TYPE_EMOJI,
   CUTSCENE_ITEM_TYPE_SHAKE,
+  CUTSCENE_ITEM_TYPE_BATTLE_WAIT_STATE,
+  CUTSCENE_ITEM_TYPE_BATTLE_FORCE_ACTION,
 
   CUTSCENE_ITEM_TYPE_COUNT
 } cutsceneitemtype_t;
@@ -85,6 +89,8 @@ struct cutsceneitem_s {
     cutscenestartbattle_t startBattle;
     cutsceneemoji_t emoji;
     cutsceneshake_t shake;
+    cutscenebattlewaitstate_t battleWaitState;
+    cutscenebattleforceaction_t battleForceAction;
   };
 };