refactor: decouple setOrder array from MovePhase (#6779)

* [Refactor/Test] Cleaned up and generalized `setTurnOrder` to apply to
non-move effects

* fixed type erorrs

* fixed setting set order to undefined

* Update turn-command-manager.ts

* Fixed typo

* Fixed metronome test

* clear set order on new turn start

moved to other pr

* ran boime

* Update global.d.ts

* Fix fragmented `biome.jsonc` config

* Fix docs in `field-helper.ts`

* Remove extra `*` because this is not a valid TSDoc comment

---------

Co-authored-by: Sirz Benjie <142067137+SirzBenjie@users.noreply.github.com>
Co-authored-by: NightKev <34855794+DayKev@users.noreply.github.com>

Author: 3 people

biome.jsonc

@@ -331,12 +331,12 @@
             "noNonNullAssertion": "off" // tedious in some tests
           },
           "nursery": {
+            // TODO: Enable for normal test folder files as well
             "noFloatingPromises": "error"
           }
         }
       }
     },
-
     // Prevent forcing type-only imports inside `overrides.ts` (where they serve as placeholders for actual runtime symbols)
     {
       "includes": ["**/src/overrides.ts"],

global.d.ts

@@ -8,6 +8,10 @@ declare global {
    * ⚠️ Should not be used in production code, as it is only populated during test runs!
    */
   var server: SetupServerApi;
+  // Override for `Array.isArray` to not remove `readonly`-ness from arrays known to be readonly
+  interface ArrayConstructor {
+    isArray<T>(arg: readonly T[]): arg is readonly T[];
+  }
 }
 
 // Global augments for `typedoc` to prevent TS from erroring when editing the config JS file

src/battle-scene.ts

@@ -23,6 +23,7 @@ import { InvertPostFX } from "#app/pipelines/invert";
 import { SpritePipeline } from "#app/pipelines/sprite";
 import { SceneBase } from "#app/scene-base";
 import { startingWave } from "#app/starting-wave";
+import { TurnCommandManager } from "#app/turn-command-manager";
 import { UiInputs } from "#app/ui-inputs";
 import { pokemonPrevolutions } from "#balance/pokemon-evolutions";
 import { FRIENDSHIP_GAIN_FROM_BATTLE } from "#balance/starters";
@@ -249,6 +250,8 @@ export class BattleScene extends SceneBase {
 
   /** Manager for the phases active in the battle scene */
   public readonly phaseManager: PhaseManager;
+  /** A manager for the commands and moves used in the current battle. */
+  public readonly turnCommandManager: TurnCommandManager = new TurnCommandManager();
   public field: Phaser.GameObjects.Container;
   public fieldUI: Phaser.GameObjects.Container;
   public charSprite: CharSprite;
@@ -1118,6 +1121,7 @@ export class BattleScene extends SceneBase {
       this.gameData = new GameData();
     }
 
+    this.turnCommandManager.resetTurnOrder();
     this.gameMode = getGameMode(GameModes.CLASSIC);
 
     this.disableMenu = false;

src/dynamic-queue-manager.ts

@@ -1,12 +1,12 @@
 import type { PokemonMove } from "#app/data/moves/pokemon-move";
 import type { Pokemon } from "#app/field/pokemon";
+import { globalScene } from "#app/global-scene";
 import type { Phase } from "#app/phase";
 import type { MovePhase } from "#app/phases/move-phase";
 import { MovePhasePriorityQueue } from "#app/queues/move-phase-priority-queue";
 import { PokemonPhasePriorityQueue } from "#app/queues/pokemon-phase-priority-queue";
 import { PostSummonPhasePriorityQueue } from "#app/queues/post-summon-phase-priority-queue";
 import type { PriorityQueue } from "#app/queues/priority-queue";
-import type { BattlerIndex } from "#enums/battler-index";
 import type { MovePhaseTimingModifier } from "#enums/move-phase-timing-modifier";
 import type { DynamicPhase, PhaseConditionFunc, PhaseString } from "#types/phase-types";
 
@@ -55,6 +55,9 @@ export class DynamicQueueManager {
     for (const queue of this.dynamicPhaseMap.values()) {
       queue.clear();
     }
+    // TODO: Remove in a later PR - this is both unwieldly for tests
+    // and would force MEs to reset the turn order at start of every single turn (which is dumb)
+    globalScene.turnCommandManager.resetTurnOrder();
   }
 
   /**
@@ -147,14 +150,6 @@ export class DynamicQueueManager {
     this.getMovePhaseQueue().cancelMove(condition);
   }
 
-  /**
-   * Sets the move order to a static array rather than a dynamic queue
-   * @param order - The order of {@linkcode BattlerIndex}s
-   */
-  public setMoveOrder(order: BattlerIndex[]): void {
-    this.getMovePhaseQueue().setMoveOrder(order);
-  }
-
   /**
    * @returns An in-order array of {@linkcode Pokemon}, representing the turn order as played out in the most recent turn
    */

src/queues/move-phase-priority-queue.ts

@@ -3,7 +3,6 @@ import type { Pokemon } from "#app/field/pokemon";
 import { globalScene } from "#app/global-scene";
 import type { MovePhase } from "#app/phases/move-phase";
 import { PokemonPhasePriorityQueue } from "#app/queues/pokemon-phase-priority-queue";
-import type { BattlerIndex } from "#enums/battler-index";
 import type { MovePhaseTimingModifier } from "#enums/move-phase-timing-modifier";
 import type { MovePriorityInBracket } from "#enums/move-priority-in-bracket";
 import type { PhaseConditionFunc } from "#types/phase-types";
@@ -79,10 +78,6 @@ export class MovePhasePriorityQueue extends PokemonPhasePriorityQueue<MovePhase>
     }
   }
 
-  public setMoveOrder(order: BattlerIndex[]) {
-    this.setOrder = order;
-  }
-
   public override pop(): MovePhase | undefined {
     this.reorder();
     const phase = this.queue.shift();
@@ -101,7 +96,6 @@ export class MovePhasePriorityQueue extends PokemonPhasePriorityQueue<MovePhase>
   }
 
   public override clear(): void {
-    this.setOrder = undefined;
     this.lastTurnOrder = [];
     super.clear();
   }

src/queues/pokemon-phase-priority-queue.ts

@@ -1,20 +1,10 @@
 import { PriorityQueue } from "#app/queues/priority-queue";
 import { sortInSpeedOrder } from "#app/utils/speed-order";
-import type { BattlerIndex } from "#enums/battler-index";
 import type { DynamicPhase } from "#types/phase-types";
 
 /** A generic speed-based priority queue of {@linkcode DynamicPhase}s. */
 export class PokemonPhasePriorityQueue<T extends DynamicPhase> extends PriorityQueue<T> {
-  protected setOrder: BattlerIndex[] | undefined;
   protected override reorder(): void {
-    const setOrder = this.setOrder;
-    if (setOrder) {
-      this.queue.sort(
-        (a, b) =>
-          setOrder.indexOf(a.getPokemon().getBattlerIndex()) - setOrder.indexOf(b.getPokemon().getBattlerIndex()),
-      );
-    } else {
-      this.queue = sortInSpeedOrder(this.queue);
-    }
+    this.queue = sortInSpeedOrder(this.queue);
   }
 }

src/turn-command-manager.ts

@@ -0,0 +1,15 @@
+import type { BattlerIndex } from "#enums/battler-index";
+
+// TODO: Add more methods and move `lastTurnOrder` here
+/** A manager for the commands and moves used in the current battle. */
+export class TurnCommandManager {
+  /**
+   * A preset order of {@linkcode BattlerIndex}es, used by tests and MEs to "fix" speed order-related effects.
+   */
+  public setOrder: readonly BattlerIndex[] | undefined;
+
+  /** Reset a prior set turn order. */
+  public resetTurnOrder(): void {
+    this.setOrder = undefined;
+  }
+}

src/utils/speed-order.ts

@@ -55,6 +55,18 @@ function getPokemon(p: Pokemon | HasPokemon): Pokemon {
  * @param groupedPokemonList - A grouped array of objects to sort; will be mutated in place
  */
 function sortBySpeed<T extends Pokemon | HasPokemon>(groupedPokemonList: T[][]): void {
+  const { setOrder } = globalScene.turnCommandManager;
+
+  // If a set turn order was provided, use that in ascending order.
+  if (setOrder) {
+    groupedPokemonList.sort((a, b) => {
+      const aIndex = getPokemon(a[0]).getBattlerIndex();
+      const bIndex = getPokemon(b[0]).getBattlerIndex();
+      return setOrder.indexOf(aIndex) - setOrder.indexOf(bIndex);
+    });
+    return;
+  }
+
   groupedPokemonList.sort((a, b) => {
     const aSpeed = getPokemon(a[0]).getEffectiveStat(Stat.SPD);
     const bSpeed = getPokemon(b[0]).getEffectiveStat(Stat.SPD);

test/framework/game-manager.ts

@@ -525,19 +525,27 @@ export class GameManager {
   }
 
   /**
-   * Modifies the queue manager to return move phases in a particular order
-   * Used to manually modify Pokemon turn order.
-   * Note: This *DOES NOT* account for priority.
-   * @param order - The turn order to set as an array of {@linkcode BattlerIndex}es.
+   * Override the turn order of the battle's current combatants.
+   *
+   * Affects all processes that check speed order.
+   * @param order - The turn order to set, as an array of {@linkcode BattlerIndex}es
    * @example
    * ```ts
-   * await game.setTurnOrder([BattlerIndex.PLAYER, BattlerIndex.ENEMY, BattlerIndex.ENEMY_2, BattlerIndex.PLAYER_2]);
+   * game.setTurnOrder([BattlerIndex.PLAYER, BattlerIndex.ENEMY, BattlerIndex.ENEMY_2, BattlerIndex.PLAYER_2]);
    * ```
+   * @throws Fails test immediately if `order` does not contain all non-fainted combatants' `BattlerIndex`es.
+   * @remarks
+   * This does not affect other relative orderings like move priority, nor does it change
+   * the battlers' innate speed stats (for the purposes of Electro Ball, etc).
    */
-  async setTurnOrder(order: BattlerIndex[]): Promise<void> {
-    await this.phaseInterceptor.to("TurnStartPhase", false);
+  // TODO: Move to `FieldHelper`
+  // TODO: Bulk-remove `await`s from existing test files in a follow-up PR
+  public setTurnOrder(order: BattlerIndex[]): void {
+    expect(order, "Turn order passed to `setTurnOrder` lacked values for one or more Pokemon!").toEqualUnsorted(
+      this.scene.getField(true).map(p => p.getBattlerIndex()),
+    );
 
-    this.scene.phaseManager.dynamicQueueManager.setMoveOrder(order);
+    this.scene.turnCommandManager.setOrder = order;
   }
 
   /**

test/helpers/field-helper.ts

@@ -8,6 +8,7 @@ import type { EnemyPokemon, PlayerPokemon, Pokemon } from "#field/pokemon";
 import { GameManagerHelper } from "#test/helpers/game-manager-helper";
 import type { MoveHelper } from "#test/helpers/move-helper";
 import { getEnumStr } from "#test/utils/string-utils";
+import { sortInSpeedOrder } from "#utils/speed-order";
 import { expect, type MockInstance, vi } from "vitest";
 
 /** Helper to manage pokemon */
@@ -64,36 +65,27 @@ export class FieldHelper extends GameManagerHelper {
 
   /**
    * Helper function to return all on-field {@linkcode Pokemon} in speed order (fastest first).
-   * @param indices - Whether to only return {@linkcode BattlerIndex}es instead of full Pokemon objects
-   * (such as for comparison with other speed order-related mechanisms); default `false`
-   * @returns An array containing all on-field {@linkcode Pokemon} in order of descending Speed. \
-   * Speed ties are returned in increasing order of index.
-   *
-   * @remarks
-   * This does not account for Trick Room as it does not modify the _speed_ of Pokemon on the field,
-   * only their turn order.
+   * @param indices - (Default `false`) Whether to only return {@linkcode BattlerIndex}es instead of full Pokemon objects
+   *   (such as for comparison with other speed order-related mechanisms)
+   * @param ignoreOverride - (Default `true`) Whether to ignore preset turn orders and speed-reversing effects (like Trick Room)
+   * @returns An array containing all on-field `Pokemon` in order of **descending** speed.
    */
-  public getSpeedOrder(indices?: false): Pokemon[];
-
+  public getSpeedOrder(indices?: false, ignoreOverride?: boolean): Pokemon[];
   /**
    * Helper function to return all on-field {@linkcode Pokemon} in speed order (fastest first).
-   * @param indices - Whether to only return {@linkcode BattlerIndex}es instead of full Pokemon objects
-   * (such as for comparison with other speed order-related mechanisms); default `false`
-   * @returns An array containing the {@linkcode BattlerIndex}es of all on-field {@linkcode Pokemon} on the field in order of descending Speed. \
-   * Speed ties are returned in increasing order of index.
-   *
-   * @remarks
-   * This does not account for Trick Room as it does not modify the _speed_ of Pokemon on the field,
-   * only their turn order.
+   * @param indices - (Default `false`) Whether to only return {@linkcode BattlerIndex}es instead of full Pokemon objects
+   *   (such as for comparison with other speed order-related mechanisms)
+   * @param ignoreOverride - (Default `true`) Whether to ignore preset turn orders and speed-reversing effects (like Trick Room)
+   * @returns An array containing the `BattlerIndex`es of all on-field `Pokemon` in order of **descending** speed.
    */
-  public getSpeedOrder(indices: true): BattlerIndex[];
-  public getSpeedOrder(indices = false): BattlerIndex[] | Pokemon[] {
-    const ret = this.game.scene
-      .getField(true)
-      .sort(
-        (pA, pB) =>
-          pB.getEffectiveStat(Stat.SPD) - pA.getEffectiveStat(Stat.SPD) || pA.getBattlerIndex() - pB.getBattlerIndex(),
-      );
+  public getSpeedOrder(indices: true, ignoreOverride?: boolean): BattlerIndex[];
+  public getSpeedOrder(indices = false, ignoreOverride = true): BattlerIndex[] | Pokemon[] {
+    let ret = this.game.scene.getField(true);
+    if (ignoreOverride) {
+      ret.sort((pA, pB) => pB.getEffectiveStat(Stat.SPD) - pA.getEffectiveStat(Stat.SPD));
+    } else {
+      ret = sortInSpeedOrder(ret);
+    }
 
     return indices ? ret.map(p => p.getBattlerIndex()) : ret;
   }