[Refactor] Added PhaseManager.toTitleScreen (#6114)

* Added `toTitlePhase`; documented phase manager

* Documented phase methods

* Fixed syntax errors + updated signature

* Reverted all the goodies

* Fixed missing shift phase call

GHAG

* Reverted change

src/battle-scene.ts

@@ -657,9 +657,7 @@ export class BattleScene extends SceneBase {
       ).then(() => loadMoveAnimAssets(defaultMoves, true)),
       this.initStarterColors(),
     ]).then(() => {
-      this.phaseManager.pushNew("LoginPhase");
-      this.phaseManager.pushNew("TitlePhase");
-
+      this.phaseManager.toTitleScreen(true);
       this.phaseManager.shiftPhase();
     });
   }
@@ -1269,13 +1267,12 @@ export class BattleScene extends SceneBase {
         duration: 250,
         ease: "Sine.easeInOut",
         onComplete: () => {
-          this.phaseManager.clearPhaseQueue();
-
           this.ui.freeUIData();
           this.uiContainer.remove(this.ui, true);
           this.uiContainer.destroy();
           this.children.removeAll(true);
           this.game.domContainer.innerHTML = "";
+          // TODO: `launchBattle` calls `reset(false, false, true)`
           this.launchBattle();
         },
       });

src/enums/dynamic-phase-type.ts

@@ -1,6 +1,7 @@
 /**
- * Enum representation of the phase types held by implementations of {@linkcode PhasePriorityQueue}
+ * Enum representation of the phase types held by implementations of {@linkcode PhasePriorityQueue}.
  */
+// TODO: We currently assume these are in order
 export enum DynamicPhaseType {
   POST_SUMMON
 }

src/phase-manager.ts

@@ -244,6 +244,21 @@ export class PhaseManager {
     this.dynamicPhaseTypes = [PostSummonPhase];
   }
 
+  /**
+   * Clear all previously set phases, then add a new {@linkcode TitlePhase} to transition to the title screen.
+   * @param addLogin - Whether to add a new {@linkcode LoginPhase} before the {@linkcode TitlePhase}
+   * (but reset everything else).
+   * Default `false`
+   */
+  public toTitleScreen(addLogin = false): void {
+    this.clearAllPhases();
+
+    if (addLogin) {
+      this.unshiftNew("LoginPhase");
+    }
+    this.unshiftNew("TitlePhase");
+  }
+
   /* Phase Functions */
   getCurrentPhase(): Phase | null {
     return this.currentPhase;

src/phases/select-starter-phase.ts

@@ -24,10 +24,11 @@ export class SelectStarterPhase extends Phase {
     globalScene.ui.setMode(UiMode.STARTER_SELECT, (starters: Starter[]) => {
       globalScene.ui.clearText();
       globalScene.ui.setMode(UiMode.SAVE_SLOT, SaveSlotUiMode.SAVE, (slotId: number) => {
+        // If clicking cancel, back out to title screen
         if (slotId === -1) {
-          globalScene.phaseManager.clearPhaseQueue();
-          globalScene.phaseManager.pushNew("TitlePhase");
-          return this.end();
+          globalScene.phaseManager.toTitleScreen();
+          this.end();
+          return;
         }
         globalScene.sessionSlotId = slotId;
         this.initBattle(starters);

src/phases/title-phase.ts

@@ -114,11 +114,11 @@ export class TitlePhase extends Phase {
               });
             }
           }
+          // Cancel button = back to title
           options.push({
             label: i18next.t("menu:cancel"),
             handler: () => {
-              globalScene.phaseManager.clearPhaseQueue();
-              globalScene.phaseManager.pushNew("TitlePhase");
+              globalScene.phaseManager.toTitleScreen();
               super.end();
               return true;
             },
@@ -191,11 +191,12 @@ export class TitlePhase extends Phase {
   initDailyRun(): void {
     globalScene.ui.clearText();
     globalScene.ui.setMode(UiMode.SAVE_SLOT, SaveSlotUiMode.SAVE, (slotId: number) => {
-      globalScene.phaseManager.clearPhaseQueue();
       if (slotId === -1) {
-        globalScene.phaseManager.pushNew("TitlePhase");
-        return super.end();
+        globalScene.phaseManager.toTitleScreen();
+        super.end();
+        return;
       }
+      globalScene.phaseManager.clearPhaseQueue();
       globalScene.sessionSlotId = slotId;
 
       const generateDaily = (seed: string) => {

src/ui/challenges-select-ui-handler.ts

@@ -382,8 +382,7 @@ export class GameChallengesUiHandler extends UiHandler {
         this.cursorObj?.setVisible(true);
         this.updateChallengeArrows(this.startCursor.visible);
       } else {
-        globalScene.phaseManager.clearPhaseQueue();
-        globalScene.phaseManager.pushNew("TitlePhase");
+        globalScene.phaseManager.toTitleScreen();
         globalScene.phaseManager.getCurrentPhase()?.end();
       }
       success = true;

src/ui/starter-select-ui-handler.ts

@@ -4303,7 +4303,10 @@ export class StarterSelectUiHandler extends MessageUiHandler {
     return true;
   }
 
-  tryExit(): boolean {
+  /**
+   * Attempt to back out of the starter selection screen into the appropriate parent modal
+   */
+  tryExit(): void {
     this.blockInput = true;
     const ui = this.getUi();
 
@@ -4317,12 +4320,13 @@ export class StarterSelectUiHandler extends MessageUiHandler {
         UiMode.CONFIRM,
         () => {
           ui.setMode(UiMode.STARTER_SELECT);
-          globalScene.phaseManager.clearPhaseQueue();
-          if (globalScene.gameMode.isChallenge) {
+          // Non-challenge modes go directly back to title, while challenge modes go to the selection screen.
+          if (!globalScene.gameMode.isChallenge) {
+            globalScene.phaseManager.toTitleScreen();
+          } else {
+            globalScene.phaseManager.clearPhaseQueue();
             globalScene.phaseManager.pushNew("SelectChallengePhase");
             globalScene.phaseManager.pushNew("EncounterPhase");
-          } else {
-            globalScene.phaseManager.pushNew("TitlePhase");
           }
           this.clearText();
           globalScene.phaseManager.getCurrentPhase()?.end();
@@ -4333,8 +4337,6 @@ export class StarterSelectUiHandler extends MessageUiHandler {
         19,
       );
     });
-
-    return true;
   }
 
   tryStart(manualTrigger = false): boolean {

test/test-utils/game-manager.ts

@@ -103,12 +103,9 @@ export class GameManager {
     if (!firstTimeScene) {
       this.scene.reset(false, true);
       (this.scene.ui.handlers[UiMode.STARTER_SELECT] as StarterSelectUiHandler).clearStarterPreferences();
-      this.scene.phaseManager.clearAllPhases();
 
       // Must be run after phase interceptor has been initialized.
-
-      this.scene.phaseManager.pushNew("LoginPhase");
-      this.scene.phaseManager.pushNew("TitlePhase");
+      this.scene.phaseManager.toTitleScreen(true);
       this.scene.phaseManager.shiftPhase();
 
       this.gameWrapper.scene = this.scene;