Merge remote-tracking branch 'upstream/beta' into trap-cleanup

* [UI/UIX] Dex unseen species filter

* Removed changes to icon visibility rules

* Update src/ui/pokedex-ui-handler.ts

---------

Co-authored-by: Wlowscha <54003515+Wlowscha@users.noreply.github.com>

package.json

@@ -29,6 +29,7 @@
   "devDependencies": {
     "@biomejs/biome": "2.0.0",
     "@ls-lint/ls-lint": "2.3.1",
+    "@types/crypto-js": "^4.2.0",
     "@types/jsdom": "^21.1.7",
     "@types/node": "^22.16.5",
     "@vitest/coverage-istanbul": "^3.2.4",

pnpm-lock.yaml

@@ -48,6 +48,9 @@ importers:
       '@ls-lint/ls-lint':
         specifier: 2.3.1
         version: 2.3.1
+      '@types/crypto-js':
+        specifier: ^4.2.0
+        version: 4.2.2
       '@types/jsdom':
         specifier: ^21.1.7
         version: 21.1.7
@@ -718,6 +721,9 @@ packages:
   '@types/cookie@0.6.0':
     resolution: {integrity: sha512-4Kh9a6B2bQciAhf7FSuMRRkUWecJgJu9nPnx3yzpsfXX/c50REIqpHY4C82bXP90qrLtXtkDxTZosYO3UpOwlA==}
 
+  '@types/crypto-js@4.2.2':
+    resolution: {integrity: sha512-sDOLlVbHhXpAUAL0YHDUUwDZf3iN4Bwi4W6a0W0b+QcAezUbRtH4FVb+9J4h+XFPW7l/gQ9F8qC7P+Ec4k8QVQ==}
+
   '@types/deep-eql@4.0.2':
     resolution: {integrity: sha512-c9h9dVVMigMPc4bwTvC5dxqtqJZwQPePsWjPlpSOnojbor6pGqdk541lfA7AqFQr5pB1BRdq0juY9db81BwyFw==}
 
@@ -2525,6 +2531,8 @@ snapshots:
 
   '@types/cookie@0.6.0': {}
 
+  '@types/crypto-js@4.2.2': {}
+
   '@types/deep-eql@4.0.2': {}
 
   '@types/estree@1.0.8': {}

src/account.ts

@@ -17,45 +17,42 @@ export function initLoggedInUser(): void {
   };
 }
 
-export function updateUserInfo(): Promise<[boolean, number]> {
+export async function updateUserInfo(): Promise<[boolean, number]> {
-  return new Promise<[boolean, number]>(resolve => {
+  if (bypassLogin) {
-    if (bypassLogin) {
+    loggedInUser = {
-      loggedInUser = {
+      username: "Guest",
-        username: "Guest",
+      lastSessionSlot: -1,
-        lastSessionSlot: -1,
+      discordId: "",
-        discordId: "",
+      googleId: "",
-        googleId: "",
+      hasAdminRole: false,
-        hasAdminRole: false,
+    };
-      };
+    let lastSessionSlot = -1;
-      let lastSessionSlot = -1;
+    for (let s = 0; s < 5; s++) {
-      for (let s = 0; s < 5; s++) {
+      if (localStorage.getItem(`sessionData${s ? s : ""}_${loggedInUser.username}`)) {
-        if (localStorage.getItem(`sessionData${s ? s : ""}_${loggedInUser.username}`)) {
+        lastSessionSlot = s;
-          lastSessionSlot = s;
+        break;
-          break;
-        }
       }
-      loggedInUser.lastSessionSlot = lastSessionSlot;
-      // Migrate old data from before the username was appended
-      ["data", "sessionData", "sessionData1", "sessionData2", "sessionData3", "sessionData4"].map(d => {
-        const lsItem = localStorage.getItem(d);
-        if (lsItem && !!loggedInUser?.username) {
-          const lsUserItem = localStorage.getItem(`${d}_${loggedInUser.username}`);
-          if (lsUserItem) {
-            localStorage.setItem(`${d}_${loggedInUser.username}_bak`, lsUserItem);
-          }
-          localStorage.setItem(`${d}_${loggedInUser.username}`, lsItem);
-          localStorage.removeItem(d);
-        }
-      });
-      return resolve([true, 200]);
     }
-    pokerogueApi.account.getInfo().then(([accountInfo, status]) => {
+    loggedInUser.lastSessionSlot = lastSessionSlot;
-      if (!accountInfo) {
+    // Migrate old data from before the username was appended
-        resolve([false, status]);
+    ["data", "sessionData", "sessionData1", "sessionData2", "sessionData3", "sessionData4"].forEach(d => {
-        return;
+      const lsItem = localStorage.getItem(d);
+      if (lsItem && !!loggedInUser?.username) {
+        const lsUserItem = localStorage.getItem(`${d}_${loggedInUser.username}`);
+        if (lsUserItem) {
+          localStorage.setItem(`${d}_${loggedInUser.username}_bak`, lsUserItem);
+        }
+        localStorage.setItem(`${d}_${loggedInUser.username}`, lsItem);
+        localStorage.removeItem(d);
       }
-      loggedInUser = accountInfo;
-      resolve([true, 200]);
     });
-  });
+    return [true, 200];
+  }
+
+  const [accountInfo, status] = await pokerogueApi.account.getInfo();
+  if (!accountInfo) {
+    return [false, status];
+  }
+  loggedInUser = accountInfo;
+  return [true, 200];
 }

src/battle-scene.ts

@@ -27,13 +27,7 @@ import { UiInputs } from "#app/ui-inputs";
 import { biomeDepths, getBiomeName } from "#balance/biomes";
 import { pokemonPrevolutions } from "#balance/pokemon-evolutions";
 import { FRIENDSHIP_GAIN_FROM_BATTLE } from "#balance/starters";
-import {
+import { initCommonAnims, initMoveAnim, loadCommonAnimAssets, loadMoveAnimAssets } from "#data/battle-anims";
-  initCommonAnims,
-  initMoveAnim,
-  loadCommonAnimAssets,
-  loadMoveAnimAssets,
-  populateAnims,
-} from "#data/battle-anims";
 import { allAbilities, allMoves, allSpecies, modifierTypes } from "#data/data-lists";
 import { battleSpecDialogue } from "#data/dialogue";
 import type { SpeciesFormChangeTrigger } from "#data/form-change-triggers";
@@ -388,7 +382,6 @@ export class BattleScene extends SceneBase {
     const defaultMoves = [MoveId.TACKLE, MoveId.TAIL_WHIP, MoveId.FOCUS_ENERGY, MoveId.STRUGGLE];
 
     await Promise.all([
-      populateAnims(),
       this.initVariantData(),
       initCommonAnims().then(() => loadCommonAnimAssets(true)),
       Promise.all(defaultMoves.map(m => initMoveAnim(m))).then(() => loadMoveAnimAssets(defaultMoves, true)),

src/data/battle-anims.ts

@@ -404,22 +404,18 @@ export const chargeAnims = new Map<ChargeAnim, AnimConfig | [AnimConfig, AnimCon
 export const commonAnims = new Map<CommonAnim, AnimConfig>();
 export const encounterAnims = new Map<EncounterAnim, AnimConfig>();
 
-export function initCommonAnims(): Promise<void> {
+export async function initCommonAnims(): Promise<void> {
-  return new Promise(resolve => {
+  const commonAnimFetches: Promise<Map<CommonAnim, AnimConfig>>[] = [];
-    const commonAnimNames = getEnumKeys(CommonAnim);
+  for (const commonAnimName of getEnumKeys(CommonAnim)) {
-    const commonAnimIds = getEnumValues(CommonAnim);
+    const commonAnimId = CommonAnim[commonAnimName];
-    const commonAnimFetches: Promise<Map<CommonAnim, AnimConfig>>[] = [];
+    commonAnimFetches.push(
-    for (let ca = 0; ca < commonAnimIds.length; ca++) {
+      globalScene
-      const commonAnimId = commonAnimIds[ca];
+        .cachedFetch(`./battle-anims/common-${toKebabCase(commonAnimName)}.json`)
-      commonAnimFetches.push(
+        .then(response => response.json())
-        globalScene
+        .then(cas => commonAnims.set(commonAnimId, new AnimConfig(cas))),
-          .cachedFetch(`./battle-anims/common-${toKebabCase(commonAnimNames[ca])}.json`)
+    );
-          .then(response => response.json())
+  }
-          .then(cas => commonAnims.set(commonAnimId, new AnimConfig(cas))),
+  await Promise.allSettled(commonAnimFetches);
-      );
-    }
-    Promise.allSettled(commonAnimFetches).then(() => resolve());
-  });
 }
 
 export function initMoveAnim(move: MoveId): Promise<void> {
@@ -1396,279 +1392,3 @@ export class EncounterBattleAnim extends BattleAnim {
     return this.oppAnim;
   }
 }
-
-export async function populateAnims() {
-  const commonAnimNames = getEnumKeys(CommonAnim).map(k => k.toLowerCase());
-  const commonAnimMatchNames = commonAnimNames.map(k => k.replace(/_/g, ""));
-  const commonAnimIds = getEnumValues(CommonAnim);
-  const chargeAnimNames = getEnumKeys(ChargeAnim).map(k => k.toLowerCase());
-  const chargeAnimMatchNames = chargeAnimNames.map(k => k.replace(/_/g, " "));
-  const chargeAnimIds = getEnumValues(ChargeAnim);
-  const commonNamePattern = /name: (?:Common:)?(Opp )?(.*)/;
-  const moveNameToId = {};
-  // Exclude MoveId.NONE;
-  for (const move of getEnumValues(MoveId).slice(1)) {
-    // KARATE_CHOP => KARATECHOP
-    const moveName = MoveId[move].toUpperCase().replace(/_/g, "");
-    moveNameToId[moveName] = move;
-  }
-
-  const seNames: string[] = []; //(await fs.readdir('./public/audio/se/battle_anims/')).map(se => se.toString());
-
-  const animsData: any[] = []; //battleAnimRawData.split('!ruby/array:PBAnimation').slice(1); // TODO: add a proper type
-  for (let a = 0; a < animsData.length; a++) {
-    const fields = animsData[a].split("@").slice(1);
-
-    const nameField = fields.find(f => f.startsWith("name: "));
-
-    let isOppMove: boolean | undefined;
-    let commonAnimId: CommonAnim | undefined;
-    let chargeAnimId: ChargeAnim | undefined;
-    if (!nameField.startsWith("name: Move:") && !(isOppMove = nameField.startsWith("name: OppMove:"))) {
-      const nameMatch = commonNamePattern.exec(nameField)!; // TODO: is this bang correct?
-      const name = nameMatch[2].toLowerCase();
-      if (commonAnimMatchNames.indexOf(name) > -1) {
-        commonAnimId = commonAnimIds[commonAnimMatchNames.indexOf(name)];
-      } else if (chargeAnimMatchNames.indexOf(name) > -1) {
-        isOppMove = nameField.startsWith("name: Opp ");
-        chargeAnimId = chargeAnimIds[chargeAnimMatchNames.indexOf(name)];
-      }
-    }
-    const nameIndex = nameField.indexOf(":", 5) + 1;
-    const animName = nameField.slice(nameIndex, nameField.indexOf("\n", nameIndex));
-    if (!moveNameToId.hasOwnProperty(animName) && !commonAnimId && !chargeAnimId) {
-      continue;
-    }
-    const anim = commonAnimId || chargeAnimId ? new AnimConfig() : new AnimConfig();
-    if (anim instanceof AnimConfig) {
-      (anim as AnimConfig).id = moveNameToId[animName];
-    }
-    if (commonAnimId) {
-      commonAnims.set(commonAnimId, anim);
-    } else if (chargeAnimId) {
-      chargeAnims.set(chargeAnimId, !isOppMove ? anim : [chargeAnims.get(chargeAnimId) as AnimConfig, anim]);
-    } else {
-      moveAnims.set(
-        moveNameToId[animName],
-        !isOppMove ? (anim as AnimConfig) : [moveAnims.get(moveNameToId[animName]) as AnimConfig, anim as AnimConfig],
-      );
-    }
-    for (let f = 0; f < fields.length; f++) {
-      const field = fields[f];
-      const fieldName = field.slice(0, field.indexOf(":"));
-      const fieldData = field.slice(fieldName.length + 1, field.lastIndexOf("\n")).trim();
-      switch (fieldName) {
-        case "array": {
-          const framesData = fieldData.split("  - - - ").slice(1);
-          for (let fd = 0; fd < framesData.length; fd++) {
-            anim.frames.push([]);
-            const frameData = framesData[fd];
-            const focusFramesData = frameData.split("    - - ");
-            for (let tf = 0; tf < focusFramesData.length; tf++) {
-              const values = focusFramesData[tf].replace(/ {6}- /g, "").split("\n");
-              const targetFrame = new AnimFrame(
-                Number.parseFloat(values[0]),
-                Number.parseFloat(values[1]),
-                Number.parseFloat(values[2]),
-                Number.parseFloat(values[11]),
-                Number.parseFloat(values[3]),
-                Number.parseInt(values[4]) === 1,
-                Number.parseInt(values[6]) === 1,
-                Number.parseInt(values[5]),
-                Number.parseInt(values[7]),
-                Number.parseInt(values[8]),
-                Number.parseInt(values[12]),
-                Number.parseInt(values[13]),
-                Number.parseInt(values[14]),
-                Number.parseInt(values[15]),
-                Number.parseInt(values[16]),
-                Number.parseInt(values[17]),
-                Number.parseInt(values[18]),
-                Number.parseInt(values[19]),
-                Number.parseInt(values[21]),
-                Number.parseInt(values[22]),
-                Number.parseInt(values[23]),
-                Number.parseInt(values[24]),
-                Number.parseInt(values[20]) === 1,
-                Number.parseInt(values[25]),
-                Number.parseInt(values[26]) as AnimFocus,
-              );
-              anim.frames[fd].push(targetFrame);
-            }
-          }
-          break;
-        }
-        case "graphic": {
-          const graphic = fieldData !== "''" ? fieldData : "";
-          anim.graphic = graphic.indexOf(".") > -1 ? graphic.slice(0, fieldData.indexOf(".")) : graphic;
-          break;
-        }
-        case "timing": {
-          const timingEntries = fieldData.split("- !ruby/object:PBAnimTiming ").slice(1);
-          for (let t = 0; t < timingEntries.length; t++) {
-            const timingData = timingEntries[t]
-              .replace(/\n/g, " ")
-              .replace(/[ ]{2,}/g, " ")
-              .replace(/[a-z]+: ! '', /gi, "")
-              .replace(/name: (.*?),/, 'name: "$1",')
-              .replace(
-                /flashColor: !ruby\/object:Color { alpha: ([\d.]+), blue: ([\d.]+), green: ([\d.]+), red: ([\d.]+)}/,
-                "flashRed: $4, flashGreen: $3, flashBlue: $2, flashAlpha: $1",
-              );
-            const frameIndex = Number.parseInt(/frame: (\d+)/.exec(timingData)![1]); // TODO: is the bang correct?
-            let resourceName = /name: "(.*?)"/.exec(timingData)![1].replace("''", ""); // TODO: is the bang correct?
-            const timingType = Number.parseInt(/timingType: (\d)/.exec(timingData)![1]); // TODO: is the bang correct?
-            let timedEvent: AnimTimedEvent | undefined;
-            switch (timingType) {
-              case 0:
-                if (resourceName && resourceName.indexOf(".") === -1) {
-                  let ext: string | undefined;
-                  ["wav", "mp3", "m4a"].every(e => {
-                    if (seNames.indexOf(`${resourceName}.${e}`) > -1) {
-                      ext = e;
-                      return false;
-                    }
-                    return true;
-                  });
-                  if (!ext) {
-                    ext = ".wav";
-                  }
-                  resourceName += `.${ext}`;
-                }
-                timedEvent = new AnimTimedSoundEvent(frameIndex, resourceName);
-                break;
-              case 1:
-                timedEvent = new AnimTimedAddBgEvent(frameIndex, resourceName.slice(0, resourceName.indexOf(".")));
-                break;
-              case 2:
-                timedEvent = new AnimTimedUpdateBgEvent(frameIndex, resourceName.slice(0, resourceName.indexOf(".")));
-                break;
-            }
-            if (!timedEvent) {
-              continue;
-            }
-            const propPattern = /([a-z]+): (.*?)(?:,|\})/gi;
-            let propMatch: RegExpExecArray;
-            while ((propMatch = propPattern.exec(timingData)!)) {
-              // TODO: is this bang correct?
-              const prop = propMatch[1];
-              let value: any = propMatch[2];
-              switch (prop) {
-                case "bgX":
-                case "bgY":
-                  value = Number.parseFloat(value);
-                  break;
-                case "volume":
-                case "pitch":
-                case "opacity":
-                case "colorRed":
-                case "colorGreen":
-                case "colorBlue":
-                case "colorAlpha":
-                case "duration":
-                case "flashScope":
-                case "flashRed":
-                case "flashGreen":
-                case "flashBlue":
-                case "flashAlpha":
-                case "flashDuration":
-                  value = Number.parseInt(value);
-                  break;
-              }
-              if (timedEvent.hasOwnProperty(prop)) {
-                timedEvent[prop] = value;
-              }
-            }
-            if (!anim.frameTimedEvents.has(frameIndex)) {
-              anim.frameTimedEvents.set(frameIndex, []);
-            }
-            anim.frameTimedEvents.get(frameIndex)!.push(timedEvent); // TODO: is this bang correct?
-          }
-          break;
-        }
-        case "position":
-          anim.position = Number.parseInt(fieldData);
-          break;
-        case "hue":
-          anim.hue = Number.parseInt(fieldData);
-          break;
-      }
-    }
-  }
-
-  // biome-ignore lint/correctness/noUnusedVariables: used in commented code
-  const animReplacer = (k, v) => {
-    if (k === "id" && !v) {
-      return undefined;
-    }
-    if (v instanceof Map) {
-      return Object.fromEntries(v);
-    }
-    if (v instanceof AnimTimedEvent) {
-      v["eventType"] = v.getEventType();
-    }
-    return v;
-  };
-
-  const animConfigProps = ["id", "graphic", "frames", "frameTimedEvents", "position", "hue"];
-  const animFrameProps = [
-    "x",
-    "y",
-    "zoomX",
-    "zoomY",
-    "angle",
-    "mirror",
-    "visible",
-    "blendType",
-    "target",
-    "graphicFrame",
-    "opacity",
-    "color",
-    "tone",
-    "flash",
-    "locked",
-    "priority",
-    "focus",
-  ];
-  const propSets = [animConfigProps, animFrameProps];
-
-  // biome-ignore lint/correctness/noUnusedVariables: used in commented code
-  const animComparator = (a: Element, b: Element) => {
-    let props: string[];
-    for (let p = 0; p < propSets.length; p++) {
-      props = propSets[p];
-      // @ts-expect-error TODO
-      const ai = props.indexOf(a.key);
-      if (ai === -1) {
-        continue;
-      }
-      // @ts-expect-error TODO
-      const bi = props.indexOf(b.key);
-
-      return ai < bi ? -1 : ai > bi ? 1 : 0;
-    }
-
-    return 0;
-  };
-
-  /*for (let ma of moveAnims.keys()) {
-        const data = moveAnims.get(ma);
-        (async () => {
-            await fs.writeFile(`../public/battle-anims/${Moves[ma].toLowerCase().replace(/\_/g, '-')}.json`, stringify(data, { replacer: animReplacer, cmp: animComparator, space: '  ' }));
-        })();
-    }
-
-    for (let ca of chargeAnims.keys()) {
-        const data = chargeAnims.get(ca);
-        (async () => {
-            await fs.writeFile(`../public/battle-anims/${chargeAnimNames[chargeAnimIds.indexOf(ca)].replace(/\_/g, '-')}.json`, stringify(data, { replacer: animReplacer, cmp: animComparator, space: '  ' }));
-        })();
-    }
-
-    for (let cma of commonAnims.keys()) {
-        const data = commonAnims.get(cma);
-        (async () => {
-            await fs.writeFile(`../public/battle-anims/common-${commonAnimNames[commonAnimIds.indexOf(cma)].replace(/\_/g, '-')}.json`, stringify(data, { replacer: animReplacer, cmp: animComparator, space: '  ' }));
-        })();
-    }*/
-}

src/data/moves/pokemon-move.ts

@@ -11,7 +11,7 @@ import { BooleanHolder, toDmgValue } from "#utils/common";
  * These are the moves assigned to a {@linkcode Pokemon} object.
  * It links to {@linkcode Move} class via the move ID.
  * Compared to {@linkcode Move}, this class also tracks things like
- * PP Ups recieved, PP used, etc.
+ * PP Ups received, PP used, etc.
  * @see {@linkcode isUsable} - checks if move is restricted, out of PP, or not implemented.
  * @see {@linkcode getMove} - returns {@linkcode Move} object by looking it up via ID.
  * @see {@linkcode usePp} - removes a point of PP from the move.

src/data/mystery-encounters/encounters/dark-deal-encounter.ts

@@ -99,6 +99,7 @@ export const DarkDealEncounter: MysteryEncounter = MysteryEncounterBuilder.withE
   MysteryEncounterType.DARK_DEAL,
 )
   .withEncounterTier(MysteryEncounterTier.ROGUE)
+  .withDisallowedChallenges(Challenges.HARDCORE)
   .withIntroSpriteConfigs([
     {
       spriteKey: "dark_deal_scientist",

src/data/mystery-encounters/utils/encounter-pokemon-utils.ts

@@ -673,6 +673,8 @@ export async function catchPokemon(
   globalScene.gameData.updateSpeciesDexIvs(pokemon.species.getRootSpeciesId(true), pokemon.ivs);
 
   return new Promise(resolve => {
+    const addStatus = new BooleanHolder(true);
+    applyChallenges(ChallengeType.POKEMON_ADD_TO_PARTY, pokemon, addStatus);
     const doPokemonCatchMenu = () => {
       const end = () => {
         // Ensure the pokemon is in the enemy party in all situations
@@ -708,9 +710,7 @@ export async function catchPokemon(
         });
       };
       Promise.all([pokemon.hideInfo(), globalScene.gameData.setPokemonCaught(pokemon)]).then(() => {
-        const addStatus = new BooleanHolder(true);
+        if (!(isObtain || addStatus.value)) {
-        applyChallenges(ChallengeType.POKEMON_ADD_TO_PARTY, pokemon, addStatus);
-        if (!addStatus.value) {
           removePokemon();
           end();
           return;
@@ -807,10 +807,16 @@ export async function catchPokemon(
     };
 
     if (showCatchObtainMessage) {
+      let catchMessage: string;
+      if (isObtain) {
+        catchMessage = "battle:pokemonObtained";
+      } else if (addStatus.value) {
+        catchMessage = "battle:pokemonCaught";
+      } else {
+        catchMessage = "battle:pokemonCaughtButChallenge";
+      }
       globalScene.ui.showText(
-        i18next.t(isObtain ? "battle:pokemonObtained" : "battle:pokemonCaught", {
+        i18next.t(catchMessage, { pokemonName: pokemon.getNameToRender() }),
-          pokemonName: pokemon.getNameToRender(),
-        }),
         null,
         doPokemonCatchMenu,
         0,

src/phases/attempt-capture-phase.ts

@@ -253,8 +253,11 @@ export class AttemptCapturePhase extends PokemonPhase {
 
     globalScene.gameData.updateSpeciesDexIvs(pokemon.species.getRootSpeciesId(true), pokemon.ivs);
 
+    const addStatus = new BooleanHolder(true);
+    applyChallenges(ChallengeType.POKEMON_ADD_TO_PARTY, pokemon, addStatus);
+
     globalScene.ui.showText(
-      i18next.t("battle:pokemonCaught", {
+      i18next.t(addStatus.value ? "battle:pokemonCaught" : "battle:pokemonCaughtButChallenge", {
         pokemonName: getPokemonNameWithAffix(pokemon),
       }),
       null,
@@ -290,8 +293,6 @@ export class AttemptCapturePhase extends PokemonPhase {
           });
         };
         Promise.all([pokemon.hideInfo(), globalScene.gameData.setPokemonCaught(pokemon)]).then(() => {
-          const addStatus = new BooleanHolder(true);
-          applyChallenges(ChallengeType.POKEMON_ADD_TO_PARTY, pokemon, addStatus);
           if (!addStatus.value) {
             removePokemon();
             end();

src/phases/select-biome-phase.ts

@@ -16,8 +16,10 @@ export class SelectBiomePhase extends BattlePhase {
 
     globalScene.resetSeed();
 
+    const gameMode = globalScene.gameMode;
     const currentBiome = globalScene.arena.biomeType;
-    const nextWaveIndex = globalScene.currentBattle.waveIndex + 1;
+    const currentWaveIndex = globalScene.currentBattle.waveIndex;
+    const nextWaveIndex = currentWaveIndex + 1;
 
     const setNextBiome = (nextBiome: BiomeId) => {
       if (nextWaveIndex % 10 === 1) {
@@ -26,6 +28,15 @@ export class SelectBiomePhase extends BattlePhase {
         applyChallenges(ChallengeType.PARTY_HEAL, healStatus);
         if (healStatus.value) {
           globalScene.phaseManager.unshiftNew("PartyHealPhase", false);
+        } else {
+          globalScene.phaseManager.unshiftNew(
+            "SelectModifierPhase",
+            undefined,
+            undefined,
+            gameMode.isFixedBattle(currentWaveIndex)
+              ? gameMode.getFixedBattle(currentWaveIndex).customModifierRewardSettings
+              : undefined,
+          );
         }
       }
       globalScene.phaseManager.unshiftNew("SwitchBiomePhase", nextBiome);
@@ -33,12 +44,12 @@ export class SelectBiomePhase extends BattlePhase {
     };
 
     if (
-      (globalScene.gameMode.isClassic && globalScene.gameMode.isWaveFinal(nextWaveIndex + 9)) ||
+      (gameMode.isClassic && gameMode.isWaveFinal(nextWaveIndex + 9)) ||
-      (globalScene.gameMode.isDaily && globalScene.gameMode.isWaveFinal(nextWaveIndex)) ||
+      (gameMode.isDaily && gameMode.isWaveFinal(nextWaveIndex)) ||
-      (globalScene.gameMode.hasShortBiomes && !(nextWaveIndex % 50))
+      (gameMode.hasShortBiomes && !(nextWaveIndex % 50))
     ) {
       setNextBiome(BiomeId.END);
-    } else if (globalScene.gameMode.hasRandomBiomes) {
+    } else if (gameMode.hasRandomBiomes) {
       setNextBiome(this.generateNextBiome(nextWaveIndex));
     } else if (Array.isArray(biomeLinks[currentBiome])) {
       const biomes: BiomeId[] = (biomeLinks[currentBiome] as (BiomeId | [BiomeId, number])[])
@@ -73,9 +84,6 @@ export class SelectBiomePhase extends BattlePhase {
   }
 
   generateNextBiome(waveIndex: number): BiomeId {
-    if (!(waveIndex % 50)) {
+    return waveIndex % 50 === 0 ? BiomeId.END : globalScene.generateRandomBiome(waveIndex);
-      return BiomeId.END;
-    }
-    return globalScene.generateRandomBiome(waveIndex);
   }
 }

src/phases/victory-phase.ts

@@ -3,13 +3,9 @@ import { globalScene } from "#app/global-scene";
 import { modifierTypes } from "#data/data-lists";
 import { BattleType } from "#enums/battle-type";
 import type { BattlerIndex } from "#enums/battler-index";
-import { ChallengeType } from "#enums/challenge-type";
 import { ClassicFixedBossWaves } from "#enums/fixed-boss-waves";
-import type { CustomModifierSettings } from "#modifiers/modifier-type";
 import { handleMysteryEncounterVictory } from "#mystery-encounters/encounter-phase-utils";
 import { PokemonPhase } from "#phases/pokemon-phase";
-import { applyChallenges } from "#utils/challenge-utils";
-import { BooleanHolder } from "#utils/common";
 
 export class VictoryPhase extends PokemonPhase {
   public readonly phaseName = "VictoryPhase";
@@ -49,15 +45,19 @@ export class VictoryPhase extends PokemonPhase {
       if (globalScene.currentBattle.battleType === BattleType.TRAINER) {
         globalScene.phaseManager.pushNew("TrainerVictoryPhase");
       }
-      if (globalScene.gameMode.isEndless || !globalScene.gameMode.isWaveFinal(globalScene.currentBattle.waveIndex)) {
+
+      const gameMode = globalScene.gameMode;
+      const currentWaveIndex = globalScene.currentBattle.waveIndex;
+
+      if (gameMode.isEndless || !gameMode.isWaveFinal(currentWaveIndex)) {
         globalScene.phaseManager.pushNew("EggLapsePhase");
-        if (globalScene.gameMode.isClassic) {
+        if (gameMode.isClassic) {
-          switch (globalScene.currentBattle.waveIndex) {
+          switch (currentWaveIndex) {
             case ClassicFixedBossWaves.RIVAL_1:
             case ClassicFixedBossWaves.RIVAL_2:
               // Get event modifiers for this wave
               timedEventManager
-                .getFixedBattleEventRewards(globalScene.currentBattle.waveIndex)
+                .getFixedBattleEventRewards(currentWaveIndex)
                 .map(r => globalScene.phaseManager.pushNew("ModifierRewardPhase", modifierTypes[r]));
               break;
             case ClassicFixedBossWaves.EVIL_BOSS_2:
@@ -66,59 +66,53 @@ export class VictoryPhase extends PokemonPhase {
               break;
           }
         }
-        const healStatus = new BooleanHolder(globalScene.currentBattle.waveIndex % 10 === 0);
+        if (currentWaveIndex % 10) {
-        applyChallenges(ChallengeType.PARTY_HEAL, healStatus);
-        if (!healStatus.value) {
           globalScene.phaseManager.pushNew(
             "SelectModifierPhase",
             undefined,
             undefined,
-            this.getFixedBattleCustomModifiers(),
+            gameMode.isFixedBattle(currentWaveIndex)
+              ? gameMode.getFixedBattle(currentWaveIndex).customModifierRewardSettings
+              : undefined,
           );
-        } else if (globalScene.gameMode.isDaily) {
+        } else if (gameMode.isDaily) {
           globalScene.phaseManager.pushNew("ModifierRewardPhase", modifierTypes.EXP_CHARM);
-          if (
+          if (currentWaveIndex > 10 && !gameMode.isWaveFinal(currentWaveIndex)) {
-            globalScene.currentBattle.waveIndex > 10 &&
-            !globalScene.gameMode.isWaveFinal(globalScene.currentBattle.waveIndex)
-          ) {
             globalScene.phaseManager.pushNew("ModifierRewardPhase", modifierTypes.GOLDEN_POKEBALL);
           }
         } else {
-          const superExpWave = !globalScene.gameMode.isEndless ? (globalScene.offsetGym ? 0 : 20) : 10;
+          const superExpWave = !gameMode.isEndless ? (globalScene.offsetGym ? 0 : 20) : 10;
-          if (globalScene.gameMode.isEndless && globalScene.currentBattle.waveIndex === 10) {
+          if (gameMode.isEndless && currentWaveIndex === 10) {
             globalScene.phaseManager.pushNew("ModifierRewardPhase", modifierTypes.EXP_SHARE);
           }
-          if (
+          if (currentWaveIndex <= 750 && (currentWaveIndex <= 500 || currentWaveIndex % 30 === superExpWave)) {
-            globalScene.currentBattle.waveIndex <= 750 &&
-            (globalScene.currentBattle.waveIndex <= 500 || globalScene.currentBattle.waveIndex % 30 === superExpWave)
-          ) {
             globalScene.phaseManager.pushNew(
               "ModifierRewardPhase",
-              globalScene.currentBattle.waveIndex % 30 !== superExpWave || globalScene.currentBattle.waveIndex > 250
+              currentWaveIndex % 30 !== superExpWave || currentWaveIndex > 250
                 ? modifierTypes.EXP_CHARM
                 : modifierTypes.SUPER_EXP_CHARM,
             );
           }
-          if (globalScene.currentBattle.waveIndex <= 150 && !(globalScene.currentBattle.waveIndex % 50)) {
+          if (currentWaveIndex <= 150 && !(currentWaveIndex % 50)) {
             globalScene.phaseManager.pushNew("ModifierRewardPhase", modifierTypes.GOLDEN_POKEBALL);
           }
-          if (globalScene.gameMode.isEndless && !(globalScene.currentBattle.waveIndex % 50)) {
+          if (gameMode.isEndless && !(currentWaveIndex % 50)) {
             globalScene.phaseManager.pushNew(
               "ModifierRewardPhase",
-              !(globalScene.currentBattle.waveIndex % 250) ? modifierTypes.VOUCHER_PREMIUM : modifierTypes.VOUCHER_PLUS,
+              !(currentWaveIndex % 250) ? modifierTypes.VOUCHER_PREMIUM : modifierTypes.VOUCHER_PLUS,
             );
             globalScene.phaseManager.pushNew("AddEnemyBuffModifierPhase");
           }
         }
 
-        if (globalScene.gameMode.hasRandomBiomes || globalScene.isNewBiome()) {
+        if (gameMode.hasRandomBiomes || globalScene.isNewBiome()) {
           globalScene.phaseManager.pushNew("SelectBiomePhase");
         }
 
         globalScene.phaseManager.pushNew("NewBattlePhase");
       } else {
         globalScene.currentBattle.battleType = BattleType.CLEAR;
-        globalScene.score += globalScene.gameMode.getClearScoreBonus();
+        globalScene.score += gameMode.getClearScoreBonus();
         globalScene.updateScoreText();
         globalScene.phaseManager.pushNew("GameOverPhase", true);
       }
@@ -126,18 +120,4 @@ export class VictoryPhase extends PokemonPhase {
 
     this.end();
   }
-
-  /**
-   * If this wave is a fixed battle with special custom modifier rewards,
-   * will pass those settings to the upcoming {@linkcode SelectModifierPhase}`.
-   */
-  getFixedBattleCustomModifiers(): CustomModifierSettings | undefined {
-    const gameMode = globalScene.gameMode;
-    const waveIndex = globalScene.currentBattle.waveIndex;
-    if (gameMode.isFixedBattle(waveIndex)) {
-      return gameMode.getFixedBattle(waveIndex).customModifierRewardSettings;
-    }
-
-    return undefined;
-  }
 }

src/plugins/api/pokerogue-session-savedata-api.ts

@@ -56,15 +56,15 @@ export class PokerogueSessionSavedataApi extends ApiBase {
 
   /**
    * Update a session savedata.
-   * @param params The {@linkcode UpdateSessionSavedataRequest} to send
+   * @param params - The request to send
-   * @param rawSavedata The raw savedata (as `string`)
+   * @param rawSavedata - The raw, unencrypted savedata
    * @returns An error message if something went wrong
    */
-  public async update(params: UpdateSessionSavedataRequest, rawSavedata: string) {
+  public async update(params: UpdateSessionSavedataRequest, rawSavedata: string): Promise<string> {
     try {
       const urlSearchParams = this.toUrlSearchParams(params);
-      const response = await this.doPost(`/savedata/session/update?${urlSearchParams}`, rawSavedata);
 
+      const response = await this.doPost(`/savedata/session/update?${urlSearchParams}`, rawSavedata);
       return await response.text();
     } catch (err) {
       console.warn("Could not update session savedata!", err);

src/system/achv.ts

@@ -448,6 +448,8 @@ export function getAchievementDescription(localizationKey: string): string {
       return i18next.t("achv:FLIP_STATS.description", { context: genderStr });
     case "FLIP_INVERSE":
       return i18next.t("achv:FLIP_INVERSE.description", { context: genderStr });
+    case "NUZLOCKE":
+      return i18next.t("achv:NUZLOCKE.description", { context: genderStr });
     case "BREEDERS_IN_SPACE":
       return i18next.t("achv:BREEDERS_IN_SPACE.description", {
         context: genderStr,

src/system/game-data.ts

@@ -128,7 +128,8 @@ export interface SessionSaveData {
   battleType: BattleType;
   trainer: TrainerData;
   gameVersion: string;
-  runNameText: string;
+  /** The player-chosen name of the run */
+  name: string;
   timestamp: number;
   challenges: ChallengeData[];
   mysteryEncounterType: MysteryEncounterType | -1; // Only defined when current wave is ME,
@@ -986,51 +987,45 @@ export class GameData {
   }
 
   async renameSession(slotId: number, newName: string): Promise<boolean> {
-    return new Promise(async resolve => {
+    if (slotId < 0) {
-      if (slotId < 0) {
+      return false;
-        return resolve(false);
+    }
-      }
+    if (newName === "") {
-      const sessionData: SessionSaveData | null = await this.getSession(slotId);
+      return true;
+    }
+    const sessionData: SessionSaveData | null = await this.getSession(slotId);
 
-      if (!sessionData) {
+    if (!sessionData) {
-        return resolve(false);
+      return false;
-      }
+    }
 
-      if (newName === "") {
+    sessionData.name = newName;
-        return resolve(true);
+    // update timestamp by 1 to ensure the session is saved
-      }
+    sessionData.timestamp += 1;
+    const updatedDataStr = JSON.stringify(sessionData);
+    const encrypted = encrypt(updatedDataStr, bypassLogin);
+    const secretId = this.secretId;
+    const trainerId = this.trainerId;
 
-      sessionData.runNameText = newName;
+    if (bypassLogin) {
-      const updatedDataStr = JSON.stringify(sessionData);
+      localStorage.setItem(
-      const encrypted = encrypt(updatedDataStr, bypassLogin);
+        `sessionData${slotId ? slotId : ""}_${loggedInUser?.username}`,
-      const secretId = this.secretId;
+        encrypt(updatedDataStr, bypassLogin),
-      const trainerId = this.trainerId;
+      );
+      return true;
+    }
 
-      if (bypassLogin) {
+    const response = await pokerogueApi.savedata.session.update(
-        localStorage.setItem(
+      { slot: slotId, trainerId, secretId, clientSessionId },
-          `sessionData${slotId ? slotId : ""}_${loggedInUser?.username}`,
+      updatedDataStr,
-          encrypt(updatedDataStr, bypassLogin),
+    );
-        );
+
-        resolve(true);
+    if (response) {
-        return;
+      return false;
-      }
+    }
-      pokerogueApi.savedata.session
+    localStorage.setItem(`sessionData${slotId ? slotId : ""}_${loggedInUser?.username}`, encrypted);
-        .update({ slot: slotId, trainerId, secretId, clientSessionId }, encrypted)
+    const success = await updateUserInfo();
-        .then(error => {
+    return !(success !== null && !success);
-          if (error) {
-            console.error("Failed to update session name:", error);
-            resolve(false);
-          } else {
-            localStorage.setItem(`sessionData${slotId ? slotId : ""}_${loggedInUser?.username}`, encrypted);
-            updateUserInfo().then(success => {
-              if (success !== null && !success) {
-                return resolve(false);
-              }
-            });
-            resolve(true);
-          }
-        });
-    });
   }
 
   loadSession(slotId: number, sessionData?: SessionSaveData): Promise<boolean> {

src/ui/party-ui-handler.ts

@@ -2142,7 +2142,12 @@ class PartyCancelButton extends Phaser.GameObjects.Container {
 
     this.partyCancelPb = partyCancelPb;
 
-    const partyCancelText = addTextObject(-10, -7, i18next.t("partyUiHandler:cancel"), TextStyle.PARTY_CANCEL_BUTTON);
+    const partyCancelText = addTextObject(
+      -10,
+      -7,
+      i18next.t("partyUiHandler:cancelButton"),
+      TextStyle.PARTY_CANCEL_BUTTON,
+    );
     this.add(partyCancelText);
   }
 

src/ui/pokedex-ui-handler.ts

@@ -410,6 +410,11 @@ export class PokedexUiHandler extends MessageUiHandler {
       new DropDownLabel(i18next.t("filterBar:hasHiddenAbility"), undefined, DropDownState.ON),
       new DropDownLabel(i18next.t("filterBar:noHiddenAbility"), undefined, DropDownState.EXCLUDE),
     ];
+    const seenSpeciesLabels = [
+      new DropDownLabel(i18next.t("filterBar:seenSpecies"), undefined, DropDownState.OFF),
+      new DropDownLabel(i18next.t("filterBar:isSeen"), undefined, DropDownState.ON),
+      new DropDownLabel(i18next.t("filterBar:isUnseen"), undefined, DropDownState.EXCLUDE),
+    ];
     const eggLabels = [
       new DropDownLabel(i18next.t("filterBar:egg"), undefined, DropDownState.OFF),
       new DropDownLabel(i18next.t("filterBar:eggPurchasable"), undefined, DropDownState.ON),
@@ -423,6 +428,7 @@ export class PokedexUiHandler extends MessageUiHandler {
       new DropDownOption("FAVORITE", favoriteLabels),
       new DropDownOption("WIN", winLabels),
       new DropDownOption("HIDDEN_ABILITY", hiddenAbilityLabels),
+      new DropDownOption("SEEN_SPECIES", seenSpeciesLabels),
       new DropDownOption("EGG", eggLabels),
       new DropDownOption("POKERUS", pokerusLabels),
     ];
@@ -792,13 +798,15 @@ export class PokedexUiHandler extends MessageUiHandler {
     this.starterSelectMessageBoxContainer.setVisible(!!text?.length);
   }
 
-  isSeen(species: PokemonSpecies, dexEntry: DexEntry): boolean {
+  isSeen(species: PokemonSpecies, dexEntry: DexEntry, seenFilter?: boolean): boolean {
     if (dexEntry?.seenAttr) {
       return true;
     }
-
+    if (!seenFilter) {
-    const starterDexEntry = globalScene.gameData.dexData[this.getStarterSpeciesId(species.speciesId)];
+      const starterDexEntry = globalScene.gameData.dexData[this.getStarterSpeciesId(species.speciesId)];
-    return !!starterDexEntry?.caughtAttr;
+      return !!starterDexEntry?.caughtAttr;
+    }
+    return false;
   }
 
   /**
@@ -1617,6 +1625,21 @@ export class PokedexUiHandler extends MessageUiHandler {
         }
       });
 
+      // Seen Filter
+      const dexEntry = globalScene.gameData.dexData[species.speciesId];
+      const isItSeen = this.isSeen(species, dexEntry, true);
+      const fitsSeen = this.filterBar.getVals(DropDownColumn.MISC).some(misc => {
+        if (misc.val === "SEEN_SPECIES" && misc.state === DropDownState.ON) {
+          return isItSeen;
+        }
+        if (misc.val === "SEEN_SPECIES" && misc.state === DropDownState.EXCLUDE) {
+          return !isItSeen;
+        }
+        if (misc.val === "SEEN_SPECIES" && misc.state === DropDownState.OFF) {
+          return true;
+        }
+      });
+
       // Egg Purchasable Filter
       const isEggPurchasable = this.isSameSpeciesEggAvailable(species.speciesId);
       const fitsEgg = this.filterBar.getVals(DropDownColumn.MISC).some(misc => {
@@ -1658,6 +1681,7 @@ export class PokedexUiHandler extends MessageUiHandler {
         fitsFavorite &&
         fitsWin &&
         fitsHA &&
+        fitsSeen &&
         fitsEgg &&
         fitsPokerus
       ) {

src/ui/run-info-ui-handler.ts

@@ -208,9 +208,10 @@ export class RunInfoUiHandler extends UiHandler {
     headerText.setOrigin(0, 0);
     headerText.setPositionRelative(headerBg, 8, 4);
     this.runContainer.add(headerText);
-    const runName = addTextObject(0, 0, this.runInfo.runNameText, TextStyle.WINDOW);
+    const runName = addTextObject(0, 0, this.runInfo.name, TextStyle.WINDOW);
     runName.setOrigin(0, 0);
-    runName.setPositionRelative(headerBg, 60, 4);
+    const runNameX = headerText.width / 6 + headerText.x + 4;
+    runName.setPositionRelative(headerBg, runNameX, 4);
     this.runContainer.add(runName);
   }
 

src/ui/save-slot-select-ui-handler.ts

@@ -377,7 +377,7 @@ export class SaveSlotSelectUiHandler extends MessageUiHandler {
         "select_cursor_highlight_thick",
         undefined,
         294,
-        this.sessionSlots[prevSlotIndex ?? 0]?.saveData?.runNameText ? 50 : 60,
+        this.sessionSlots[prevSlotIndex ?? 0]?.saveData?.name ? 50 : 60,
         6,
         6,
         6,
@@ -553,10 +553,10 @@ class SessionSlot extends Phaser.GameObjects.Container {
   }
 
   async setupWithData(data: SessionSaveData) {
-    const hasName = data?.runNameText;
+    const hasName = data?.name;
     this.remove(this.loadingLabel, true);
     if (hasName) {
-      const nameLabel = addTextObject(8, 5, data.runNameText, TextStyle.WINDOW);
+      const nameLabel = addTextObject(8, 5, data.name, TextStyle.WINDOW);
       this.add(nameLabel);
     } else {
       const fallbackName = this.decideFallback(data);

src/utils/data.ts

@@ -45,17 +45,17 @@ export function deepMergeSpriteData(dest: object, source: object) {
 }
 
 export function encrypt(data: string, bypassLogin: boolean): string {
-  return (bypassLogin
+  if (bypassLogin) {
-    ? (data: string) => btoa(encodeURIComponent(data))
+    return btoa(encodeURIComponent(data));
-    : (data: string) => AES.encrypt(data, saveKey))(data) as unknown as string; // TODO: is this correct?
+  }
+  return AES.encrypt(data, saveKey).toString();
 }
 
 export function decrypt(data: string, bypassLogin: boolean): string {
-  return (
+  if (bypassLogin) {
-    bypassLogin
+    return decodeURIComponent(atob(data));
-      ? (data: string) => decodeURIComponent(atob(data))
+  }
-      : (data: string) => AES.decrypt(data, saveKey).toString(enc.Utf8)
+  return AES.decrypt(data, saveKey).toString(enc.Utf8);
-  )(data);
 }
 
 // the latest data saved/loaded for the Starter Preferences. Required to reduce read/writes. Initialize as "{}", since this is the default value and no data needs to be stored if present.

test/@types/vitest.d.ts

@@ -2,21 +2,24 @@ import "vitest";
 
 import type { TerrainType } from "#app/data/terrain";
 import type Overrides from "#app/overrides";
-import type { ArenaTag, ArenaTagTypeMap } from "#data/arena-tag";
+import type { ArenaTag } from "#data/arena-tag";
+import type { PositionalTag } from "#data/positional-tags/positional-tag";
 import type { AbilityId } from "#enums/ability-id";
 import type { ArenaTagSide } from "#enums/arena-tag-side";
 import type { ArenaTagType } from "#enums/arena-tag-type";
 import type { BattlerTagType } from "#enums/battler-tag-type";
 import type { MoveId } from "#enums/move-id";
 import type { PokemonType } from "#enums/pokemon-type";
+import type { PositionalTagType } from "#enums/positional-tag-type";
 import type { BattleStat, EffectiveStat, Stat } from "#enums/stat";
 import type { StatusEffect } from "#enums/status-effect";
 import type { WeatherType } from "#enums/weather-type";
 import type { Arena } from "#field/arena";
 import type { Pokemon } from "#field/pokemon";
 import type { PokemonMove } from "#moves/pokemon-move";
-import type { OneOther } from "#test/@types/test-helpers";
+import type { toHaveArenaTagOptions } from "#test/test-utils/matchers/to-have-arena-tag";
-import type { ToHaveEffectiveStatMatcherOptions } from "#test/test-utils/matchers/to-have-effective-stat";
+import type { toHaveEffectiveStatOptions } from "#test/test-utils/matchers/to-have-effective-stat";
+import type { toHavePositionalTagOptions } from "#test/test-utils/matchers/to-have-positional-tag";
 import type { expectedStatusType } from "#test/test-utils/matchers/to-have-status-effect";
 import type { toHaveTypesOptions } from "#test/test-utils/matchers/to-have-types";
 import type { TurnMove } from "#types/turn-move";
@@ -25,7 +28,7 @@ import type { toDmgValue } from "utils/common";
 import type { expect } from "vitest";
 
 declare module "vitest" {
-  interface Assertion {
+  interface Assertion<T> {
     /**
      * Check whether an array contains EXACTLY the given items (in any order).
      *
@@ -35,46 +38,9 @@ declare module "vitest" {
      * @param expected - The expected contents of the array, in any order
      * @see {@linkcode expect.arrayContaining}
      */
-    toEqualArrayUnsorted<E>(expected: E[]): void;
+    toEqualArrayUnsorted(expected: T[]): void;
 
-    /**
+    // #region Arena Matchers
-     * Check whether a {@linkcode Pokemon}'s current typing includes the given types.
-     *
-     * @param expected - The expected types (in any order)
-     * @param options - The options passed to the matcher
-     */
-    toHaveTypes(expected: PokemonType[], options?: toHaveTypesOptions): void;
-    toHaveTypes(expected: [PokemonType, ...PokemonType[]], options?: toHaveTypesOptions): void;
-
-    /**
-     * Matcher to check the contents of a {@linkcode Pokemon}'s move history.
-     *
-     * @param expectedValue - The expected value; can be a {@linkcode MoveId} or a partially filled {@linkcode TurnMove}
-     * containing the desired properties to check
-     * @param index - The index of the move history entry to check, in order from most recent to least recent.
-     * Default `0` (last used move)
-     * @see {@linkcode Pokemon.getLastXMoves}
-     */
-    toHaveUsedMove(expected: MoveId | AtLeastOne<TurnMove>, index?: number): void;
-
-    /**
-     * Check whether a {@linkcode Pokemon}'s effective stat is as expected
-     * (checked after all stat value modifications).
-     *
-     * @param stat - The {@linkcode EffectiveStat} to check
-     * @param expectedValue - The expected value of {@linkcode stat}
-     * @param options - (Optional) The {@linkcode ToHaveEffectiveStatMatcherOptions}
-     * @remarks
-     * If you want to check the stat **before** modifiers are applied, use {@linkcode Pokemon.getStat} instead.
-     */
-    toHaveEffectiveStat(stat: EffectiveStat, expectedValue: number, options?: ToHaveEffectiveStatMatcherOptions): void;
-
-    /**
-     * Check whether a {@linkcode Pokemon} has taken a specific amount of damage.
-     * @param expectedDamageTaken - The expected amount of damage taken
-     * @param roundDown - Whether to round down {@linkcode expectedDamageTaken} with {@linkcode toDmgValue}; default `true`
-     */
-    toHaveTakenDamage(expectedDamageTaken: number, roundDown?: boolean): void;
 
     /**
      * Check whether the current {@linkcode WeatherType} is as expected.
@@ -90,26 +56,59 @@ declare module "vitest" {
 
     /**
      * Check whether the current {@linkcode Arena} contains the given {@linkcode ArenaTag}.
-     *
+     * @param expectedTag - A partially-filled {@linkcode ArenaTag} containing the desired properties
-     * @param expectedType - A partially-filled {@linkcode ArenaTag} containing the desired properties
      */
-    toHaveArenaTag<T extends ArenaTagType>(
+    toHaveArenaTag<A extends ArenaTagType>(expectedTag: toHaveArenaTagOptions<A>): void;
-      expectedType: OneOther<ArenaTagTypeMap[T], "tagType" | "side"> & { tagType: T }, // intersection required bc this doesn't preserve T
-    ): void;
     /**
      * Check whether the current {@linkcode Arena} contains the given {@linkcode ArenaTag}.
-     *
      * @param expectedType - The {@linkcode ArenaTagType} of the desired tag
-     * @param side - The {@linkcode ArenaTagSide | side of the field} the tag should affect, or
+     * @param side - The {@linkcode ArenaTagSide | side(s) of the field} the tag should affect; default {@linkcode ArenaTagSide.BOTH}
-     * {@linkcode ArenaTagSide.BOTH} to check both sides;
-     * default `ArenaTagSide.BOTH`
      */
     toHaveArenaTag(expectedType: ArenaTagType, side?: ArenaTagSide): void;
 
     /**
-     * Check whether a {@linkcode Pokemon} is at full HP.
+     * Check whether the current {@linkcode Arena} contains the given {@linkcode PositionalTag}.
+     * @param expectedTag - A partially-filled `PositionalTag` containing the desired properties
      */
-    toHaveFullHp(): void;
+    toHavePositionalTag<P extends PositionalTagType>(expectedTag: toHavePositionalTagOptions<P>): void;
+    /**
+     * Check whether the current {@linkcode Arena} contains the given number of {@linkcode PositionalTag}s.
+     * @param expectedType - The {@linkcode PositionalTagType} of the desired tag
+     * @param count - The number of instances of {@linkcode expectedType} that should be active;
+     * defaults to `1` and must be within the range `[0, 4]`
+     */
+    toHavePositionalTag(expectedType: PositionalTagType, count?: number): void;
+
+    // #endregion Arena Matchers
+
+    // #region Pokemon Matchers
+
+    /**
+     * Check whether a {@linkcode Pokemon}'s current typing includes the given types.
+     * @param expectedTypes - The expected {@linkcode PokemonType}s to check against; must have length `>0`
+     * @param options - The {@linkcode toHaveTypesOptions | options} passed to the matcher
+     */
+    toHaveTypes(expectedTypes: PokemonType[], options?: toHaveTypesOptions): void;
+
+    /**
+     * Check whether a {@linkcode Pokemon} has used a move matching the given criteria.
+     * @param expectedMove - The {@linkcode MoveId} the Pokemon is expected to have used,
+     * or a partially filled {@linkcode TurnMove} containing the desired properties to check
+     * @param index - The index of the move history entry to check, in order from most recent to least recent; default `0`
+     * @see {@linkcode Pokemon.getLastXMoves}
+     */
+    toHaveUsedMove(expectedMove: MoveId | AtLeastOne<TurnMove>, index?: number): void;
+
+    /**
+     * Check whether a {@linkcode Pokemon}'s effective stat is as expected
+     * (checked after all stat value modifications).
+     * @param stat - The {@linkcode EffectiveStat} to check
+     * @param expectedValue - The expected value of {@linkcode stat}
+     * @param options - The {@linkcode toHaveEffectiveStatOptions | options} passed to the matcher
+     * @remarks
+     * If you want to check the stat **before** modifiers are applied, use {@linkcode Pokemon.getStat} instead.
+     */
+    toHaveEffectiveStat(stat: EffectiveStat, expectedValue: number, options?: toHaveEffectiveStatOptions): void;
 
     /**
      * Check whether a {@linkcode Pokemon} has a specific {@linkcode StatusEffect | non-volatile status effect}.
@@ -133,7 +132,7 @@ declare module "vitest" {
 
     /**
      * Check whether a {@linkcode Pokemon} has applied a specific {@linkcode AbilityId}.
-     * @param expectedAbilityId - The expected {@linkcode AbilityId}
+     * @param expectedAbilityId - The `AbilityId` to check for
      */
     toHaveAbilityApplied(expectedAbilityId: AbilityId): void;
 
@@ -143,24 +142,36 @@ declare module "vitest" {
      */
     toHaveHp(expectedHp: number): void;
 
+    /**
+     * Check whether a {@linkcode Pokemon} has taken a specific amount of damage.
+     * @param expectedDamageTaken - The expected amount of damage taken
+     * @param roundDown - Whether to round down `expectedDamageTaken` with {@linkcode toDmgValue}; default `true`
+     */
+    toHaveTakenDamage(expectedDamageTaken: number, roundDown?: boolean): void;
+
     /**
      * Check whether a {@linkcode Pokemon} is currently fainted (as determined by {@linkcode Pokemon.isFainted}).
      * @remarks
-     * When checking whether an enemy wild Pokemon is fainted, one must reference it in a variable _before_ the fainting effect occurs
+     * When checking whether an enemy wild Pokemon is fainted, one must store a reference to it in a variable _before_ the fainting effect occurs.
-     * as otherwise the Pokemon will be GC'ed and rendered `undefined`.
+     * Otherwise, the Pokemon will be removed from the field and garbage collected.
      */
     toHaveFainted(): void;
 
+    /**
+     * Check whether a {@linkcode Pokemon} is at full HP.
+     */
+    toHaveFullHp(): void;
     /**
      * Check whether a {@linkcode Pokemon} has consumed the given amount of PP for one of its moves.
-     * @param expectedValue - The {@linkcode MoveId} of the {@linkcode PokemonMove} that should have consumed PP
+     * @param moveId - The {@linkcode MoveId} corresponding to the {@linkcode PokemonMove} that should have consumed PP
      * @param ppUsed - The numerical amount of PP that should have been consumed,
      * or `all` to indicate the move should be _out_ of PP
      * @remarks
-     * If the Pokemon's moveset has been set via {@linkcode Overrides.MOVESET_OVERRIDE}/{@linkcode Overrides.ENEMY_MOVESET_OVERRIDE},
+     * If the Pokemon's moveset has been set via {@linkcode Overrides.MOVESET_OVERRIDE}/{@linkcode Overrides.ENEMY_MOVESET_OVERRIDE}
-     * does not contain {@linkcode expectedMove}
+     * or does not contain exactly one copy of `moveId`, this will fail the test.
-     * or contains the desired move more than once, this will fail the test.
      */
-    toHaveUsedPP(expectedMove: MoveId, ppUsed: number | "all"): void;
+    toHaveUsedPP(moveId: MoveId, ppUsed: number | "all"): void;
+
+    // #endregion Pokemon Matchers
   }
 }

test/challenges/limited-catch.test.ts

@@ -1,8 +1,10 @@
 import { AbilityId } from "#enums/ability-id";
 import { Challenges } from "#enums/challenges";
 import { MoveId } from "#enums/move-id";
+import { MysteryEncounterType } from "#enums/mystery-encounter-type";
 import { PokeballType } from "#enums/pokeball";
 import { SpeciesId } from "#enums/species-id";
+import { runMysteryEncounterToEnd } from "#test/mystery-encounter/encounter-test-utils";
 import { GameManager } from "#test/test-utils/game-manager";
 import Phaser from "phaser";
 import { afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
@@ -52,4 +54,18 @@ describe("Challenges - Limited Catch", () => {
 
     expect(game.scene.getPlayerParty()).toHaveLength(1);
   });
+
+  it("should allow gift Pokémon from Mystery Encounters to be added to party", async () => {
+    game.override
+      .mysteryEncounterChance(100)
+      .mysteryEncounter(MysteryEncounterType.THE_POKEMON_SALESMAN)
+      .startingWave(12);
+    game.scene.money = 20000;
+
+    await game.challengeMode.runToSummon([SpeciesId.NUZLEAF]);
+
+    await runMysteryEncounterToEnd(game, 1);
+
+    expect(game.scene.getPlayerParty()).toHaveLength(2);
+  });
 });

test/challenges/limited-support.test.ts

@@ -3,6 +3,7 @@ import { Challenges } from "#enums/challenges";
 import { MoveId } from "#enums/move-id";
 import { SpeciesId } from "#enums/species-id";
 import { UiMode } from "#enums/ui-mode";
+import { ExpBoosterModifier } from "#modifiers/modifier";
 import { GameManager } from "#test/test-utils/game-manager";
 import { ModifierSelectUiHandler } from "#ui/modifier-select-ui-handler";
 import Phaser from "phaser";
@@ -75,6 +76,7 @@ describe("Challenges - Limited Support", () => {
     await game.doKillOpponents();
     await game.toNextWave();
 
+    expect(game.scene.getModifiers(ExpBoosterModifier)).toHaveLength(1);
     expect(playerPokemon).not.toHaveFullHp();
 
     game.move.use(MoveId.SPLASH);

test/matchers.setup.ts

@@ -6,6 +6,7 @@ import { toHaveEffectiveStat } from "#test/test-utils/matchers/to-have-effective
 import { toHaveFainted } from "#test/test-utils/matchers/to-have-fainted";
 import { toHaveFullHp } from "#test/test-utils/matchers/to-have-full-hp";
 import { toHaveHp } from "#test/test-utils/matchers/to-have-hp";
+import { toHavePositionalTag } from "#test/test-utils/matchers/to-have-positional-tag";
 import { toHaveStatStage } from "#test/test-utils/matchers/to-have-stat-stage";
 import { toHaveStatusEffect } from "#test/test-utils/matchers/to-have-status-effect";
 import { toHaveTakenDamage } from "#test/test-utils/matchers/to-have-taken-damage";
@@ -23,19 +24,20 @@ import { expect } from "vitest";
 
 expect.extend({
   toEqualArrayUnsorted,
-  toHaveTypes,
-  toHaveUsedMove,
-  toHaveEffectiveStat,
-  toHaveTakenDamage,
   toHaveWeather,
   toHaveTerrain,
   toHaveArenaTag,
-  toHaveFullHp,
+  toHavePositionalTag,
+  toHaveTypes,
+  toHaveUsedMove,
+  toHaveEffectiveStat,
   toHaveStatusEffect,
   toHaveStatStage,
   toHaveBattlerTag,
   toHaveAbilityApplied,
   toHaveHp,
+  toHaveTakenDamage,
+  toHaveFullHp,
   toHaveFainted,
   toHaveUsedPP,
 });

test/moves/wish.test.ts

@@ -39,15 +39,6 @@ describe("Move - Wish", () => {
       .enemyLevel(100);
   });
 
-  /**
-   * Expect that wish is active with the specified number of attacks.
-   * @param numAttacks - The number of wish instances that should be queued; default `1`
-   */
-  function expectWishActive(numAttacks = 1) {
-    const wishes = game.scene.arena.positionalTagManager["tags"].filter(t => t.tagType === PositionalTagType.WISH);
-    expect(wishes).toHaveLength(numAttacks);
-  }
-
   it("should heal the Pokemon in the current slot for 50% of the user's maximum HP", async () => {
     await game.classicMode.startBattle([SpeciesId.ALOMOMOLA, SpeciesId.BLISSEY]);
 
@@ -58,19 +49,19 @@ describe("Move - Wish", () => {
     game.move.use(MoveId.WISH);
     await game.toNextTurn();
 
-    expectWishActive();
+    expect(game).toHavePositionalTag(PositionalTagType.WISH);
 
     game.doSwitchPokemon(1);
     await game.toEndOfTurn();
 
-    expectWishActive(0);
+    expect(game).toHavePositionalTag(PositionalTagType.WISH, 0);
     expect(game.textInterceptor.logs).toContain(
       i18next.t("arenaTag:wishTagOnAdd", {
         pokemonNameWithAffix: getPokemonNameWithAffix(alomomola),
       }),
     );
-    expect(alomomola.hp).toBe(1);
+    expect(alomomola).toHaveHp(1);
-    expect(blissey.hp).toBe(toDmgValue(alomomola.getMaxHp() / 2) + 1);
+    expect(blissey).toHaveHp(toDmgValue(alomomola.getMaxHp() / 2) + 1);
   });
 
   it("should work if the user has full HP, but not if it already has an active Wish", async () => {
@@ -82,13 +73,13 @@ describe("Move - Wish", () => {
     game.move.use(MoveId.WISH);
     await game.toNextTurn();
 
-    expectWishActive();
+    expect(game).toHavePositionalTag(PositionalTagType.WISH);
 
     game.move.use(MoveId.WISH);
     await game.toEndOfTurn();
 
     expect(alomomola.hp).toBe(toDmgValue(alomomola.getMaxHp() / 2) + 1);
-    expect(alomomola.getLastXMoves()[0].result).toBe(MoveResult.FAIL);
+    expect(alomomola).toHaveUsedMove({ result: MoveResult.FAIL });
   });
 
   it("should function independently of Future Sight", async () => {
@@ -103,7 +94,8 @@ describe("Move - Wish", () => {
     await game.setTurnOrder([BattlerIndex.ENEMY, BattlerIndex.PLAYER]);
     await game.toNextTurn();
 
-    expectWishActive(1);
+    expect(game).toHavePositionalTag(PositionalTagType.WISH);
+    expect(game).toHavePositionalTag(PositionalTagType.DELAYED_ATTACK);
   });
 
   it("should work in double battles and trigger in order of creation", async () => {
@@ -127,7 +119,7 @@ describe("Move - Wish", () => {
     await game.setTurnOrder(oldOrder.map(p => p.getBattlerIndex()));
     await game.toNextTurn();
 
-    expectWishActive(4);
+    expect(game).toHavePositionalTag(PositionalTagType.WISH, 4);
 
     // Lower speed to change turn order
     alomomola.setStatStage(Stat.SPD, 6);
@@ -141,7 +133,7 @@ describe("Move - Wish", () => {
     await game.phaseInterceptor.to("PositionalTagPhase");
 
     // all wishes have activated and added healing phases
-    expectWishActive(0);
+    expect(game).toHavePositionalTag(PositionalTagType.WISH, 0);
 
     const healPhases = game.scene.phaseManager.phaseQueue.filter(p => p.is("PokemonHealPhase"));
     expect(healPhases).toHaveLength(4);
@@ -165,14 +157,14 @@ describe("Move - Wish", () => {
     game.move.use(MoveId.WISH, BattlerIndex.PLAYER_2);
     await game.toNextTurn();
 
-    expectWishActive();
+    expect(game).toHavePositionalTag(PositionalTagType.WISH);
 
     game.move.use(MoveId.SPLASH, BattlerIndex.PLAYER);
     game.move.use(MoveId.MEMENTO, BattlerIndex.PLAYER_2, BattlerIndex.ENEMY_2);
     await game.toEndOfTurn();
 
     // Wish went away without doing anything
-    expectWishActive(0);
+    expect(game).toHavePositionalTag(PositionalTagType.WISH, 0);
     expect(game.textInterceptor.logs).not.toContain(
       i18next.t("arenaTag:wishTagOnAdd", {
         pokemonNameWithAffix: getPokemonNameWithAffix(blissey),

test/test-utils/matchers/to-equal-array-unsorted.ts

@@ -1,4 +1,5 @@
 import { getOnelineDiffStr } from "#test/test-utils/string-utils";
+import { receivedStr } from "#test/test-utils/test-utils";
 import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 
 /**
@@ -14,22 +15,22 @@ export function toEqualArrayUnsorted(
 ): SyncExpectationResult {
   if (!Array.isArray(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected an array, but got ${this.utils.stringify(received)}!`,
+      message: () => `Expected to receive an array, but got ${receivedStr(received)}!`,
     };
   }
 
   if (received.length !== expected.length) {
     return {
       pass: false,
-      message: () => `Expected to receive array of length ${received.length}, but got ${expected.length} instead!`,
+      message: () => `Expected to receive an array of length ${received.length}, but got ${expected.length} instead!`,
-      actual: received,
       expected,
+      actual: received,
     };
   }
 
-  const actualSorted = received.slice().sort();
+  const actualSorted = received.toSorted();
-  const expectedSorted = expected.slice().sort();
+  const expectedSorted = expected.toSorted();
   const pass = this.equals(actualSorted, expectedSorted, [...this.customTesters, this.utils.iterableEquality]);
 
   const actualStr = getOnelineDiffStr.call(this, actualSorted);

test/test-utils/matchers/to-have-ability-applied.ts

@@ -21,8 +21,8 @@ export function toHaveAbilityApplied(
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected to recieve a Pokemon, but got ${receivedStr(received)}!`,
+      message: () => `Expected to receive a Pokemon, but got ${receivedStr(received)}!`,
     };
   }
 

test/test-utils/matchers/to-have-arena-tag.ts

@@ -1,20 +1,22 @@
 import type { ArenaTag, ArenaTagTypeMap } from "#data/arena-tag";
 import type { ArenaTagSide } from "#enums/arena-tag-side";
-import { ArenaTagType } from "#enums/arena-tag-type";
+import type { ArenaTagType } from "#enums/arena-tag-type";
 import type { OneOther } from "#test/@types/test-helpers";
 // biome-ignore lint/correctness/noUnusedImports: TSDoc
 import type { GameManager } from "#test/test-utils/game-manager";
-import { getEnumStr, getOnelineDiffStr, stringifyEnumArray } from "#test/test-utils/string-utils";
+import { getOnelineDiffStr } from "#test/test-utils/string-utils";
 import { isGameManagerInstance, receivedStr } from "#test/test-utils/test-utils";
-import type { NonFunctionPropertiesRecursive } from "#types/type-helpers";
 import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 
-export type toHaveArenaTagOptions<T extends ArenaTagType> = OneOther<ArenaTagTypeMap[T], "tagType">;
+// intersection required to preserve T for inferences
+export type toHaveArenaTagOptions<T extends ArenaTagType> = OneOther<ArenaTagTypeMap[T], "tagType" | "side"> & {
+  tagType: T;
+};
 
 /**
  * Matcher to check if the {@linkcode Arena} has a given {@linkcode ArenaTag} active.
  * @param received - The object to check. Should be the current {@linkcode GameManager}.
- * @param expectedType - The {@linkcode ArenaTagType} of the desired tag, or a partially-filled object
+ * @param expectedTag - The `ArenaTagType` of the desired tag, or a partially-filled object
  * containing the desired properties
  * @param side - The {@linkcode ArenaTagSide | side of the field} the tag should affect, or
  * {@linkcode ArenaTagSide.BOTH} to check both sides
@@ -23,58 +25,53 @@ export type toHaveArenaTagOptions<T extends ArenaTagType> = OneOther<ArenaTagTyp
 export function toHaveArenaTag<T extends ArenaTagType>(
   this: MatcherState,
   received: unknown,
-  // simplified types used for brevity; full overloads are in `vitest.d.ts`
+  expectedTag: T | toHaveArenaTagOptions<T>,
-  expectedType: T | (Partial<NonFunctionPropertiesRecursive<ArenaTag>> & { tagType: T; side: ArenaTagSide }),
   side?: ArenaTagSide,
 ): SyncExpectationResult {
   if (!isGameManagerInstance(received)) {
     return {
       pass: this.isNot,
-      message: () => `Expected to recieve a GameManager, but got ${receivedStr(received)}!`,
+      message: () => `Expected to receive a GameManager, but got ${receivedStr(received)}!`,
     };
   }
 
   if (!received.scene?.arena) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected GameManager.${received.scene ? "scene" : "scene.arena"} to be defined!`,
+      message: () => `Expected GameManager.${received.scene ? "scene.arena" : "scene"} to be defined!`,
     };
   }
 
-  if (typeof expectedType === "string") {
+  // Coerce lone `tagType`s into objects
-    // Coerce lone `tagType`s into objects
+  // Bangs are ok as we enforce safety via overloads
-    // Bangs are ok as we enforce safety via overloads
+  // @ts-expect-error - Typescript is being stupid as tag type and side will always exist
-    expectedType = { tagType: expectedType, side: side! };
+  const etag: Partial<ArenaTag> & { tagType: T; side: ArenaTagSide } =
-  }
+    typeof expectedTag === "object" ? expectedTag : { tagType: expectedTag, side: side! };
 
   // We need to get all tags for the case of checking properties of a tag present on both sides of the arena
-  const tags = received.scene.arena.findTagsOnSide(t => t.tagType === expectedType.tagType, expectedType.side);
+  const tags = received.scene.arena.findTagsOnSide(t => t.tagType === etag.tagType, etag.side);
-  if (!tags.length) {
+  if (tags.length === 0) {
-    const expectedStr = getEnumStr(ArenaTagType, expectedType.tagType);
     return {
       pass: false,
-      message: () => `Expected the arena to have a tag matching ${expectedStr}, but it didn't!`,
+      message: () => `Expected the Arena to have a tag of type ${etag.tagType}, but it didn't!`,
-      expected: getEnumStr(ArenaTagType, expectedType.tagType),
+      expected: etag.tagType,
-      actual: stringifyEnumArray(
+      actual: received.scene.arena.tags.map(t => t.tagType),
-        ArenaTagType,
-        received.scene.arena.tags.map(t => t.tagType),
-      ),
     };
   }
 
   // Pass if any of the matching tags meet our criteria
   const pass = tags.some(tag =>
-    this.equals(tag, expectedType, [...this.customTesters, this.utils.subsetEquality, this.utils.iterableEquality]),
+    this.equals(tag, expectedTag, [...this.customTesters, this.utils.subsetEquality, this.utils.iterableEquality]),
   );
 
-  const expectedStr = getOnelineDiffStr.call(this, expectedType);
+  const expectedStr = getOnelineDiffStr.call(this, expectedTag);
   return {
     pass,
     message: () =>
       pass
-        ? `Expected the arena to NOT have a tag matching ${expectedStr}, but it did!`
+        ? `Expected the Arena to NOT have a tag matching ${expectedStr}, but it did!`
-        : `Expected the arena to have a tag matching ${expectedStr}, but it didn't!`,
+        : `Expected the Arena to have a tag matching ${expectedStr}, but it didn't!`,
-    expected: expectedType,
+    expected: expectedTag,
     actual: tags,
   };
 }

test/test-utils/matchers/to-have-effective-stat.ts

@@ -6,7 +6,7 @@ import { getStatName } from "#test/test-utils/string-utils";
 import { isPokemonInstance, receivedStr } from "#test/test-utils/test-utils";
 import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 
-export interface ToHaveEffectiveStatMatcherOptions {
+export interface toHaveEffectiveStatOptions {
   /**
    * The target {@linkcode Pokemon}
    * @see {@linkcode Pokemon.getEffectiveStat}
@@ -30,7 +30,7 @@ export interface ToHaveEffectiveStatMatcherOptions {
  * @param received - The object to check. Should be a {@linkcode Pokemon}
  * @param stat - The {@linkcode EffectiveStat} to check
  * @param expectedValue - The expected value of the {@linkcode stat}
- * @param options - The {@linkcode ToHaveEffectiveStatMatcherOptions}
+ * @param options - The {@linkcode toHaveEffectiveStatOptions}
  * @returns Whether the matcher passed
  */
 export function toHaveEffectiveStat(
@@ -38,11 +38,11 @@ export function toHaveEffectiveStat(
   received: unknown,
   stat: EffectiveStat,
   expectedValue: number,
-  { enemy, move, isCritical = false }: ToHaveEffectiveStatMatcherOptions = {},
+  { enemy, move, isCritical = false }: toHaveEffectiveStatOptions = {},
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }

test/test-utils/matchers/to-have-fainted.ts

@@ -12,7 +12,7 @@ import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 export function toHaveFainted(this: MatcherState, received: unknown): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }

test/test-utils/matchers/to-have-full-hp.ts

@@ -12,7 +12,7 @@ import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 export function toHaveFullHp(this: MatcherState, received: unknown): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }

test/test-utils/matchers/to-have-hp.ts

@@ -13,7 +13,7 @@ import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 export function toHaveHp(this: MatcherState, received: unknown, expectedHp: number): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }

test/test-utils/matchers/to-have-positional-tag.ts

@@ -0,0 +1,107 @@
+// biome-ignore-start lint/correctness/noUnusedImports: TSDoc
+import type { GameManager } from "#test/test-utils/game-manager";
+// biome-ignore-end lint/correctness/noUnusedImports: TSDoc
+
+import type { serializedPosTagMap } from "#data/positional-tags/load-positional-tag";
+import type { PositionalTagType } from "#enums/positional-tag-type";
+import type { OneOther } from "#test/@types/test-helpers";
+import { getOnelineDiffStr } from "#test/test-utils/string-utils";
+import { isGameManagerInstance, receivedStr } from "#test/test-utils/test-utils";
+import { toTitleCase } from "#utils/strings";
+import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
+
+export type toHavePositionalTagOptions<P extends PositionalTagType> = OneOther<serializedPosTagMap[P], "tagType"> & {
+  tagType: P;
+};
+
+/**
+ * Matcher to check if the {@linkcode Arena} has a certain number of {@linkcode PositionalTag}s active.
+ * @param received - The object to check. Should be the current {@linkcode GameManager}
+ * @param expectedTag - The {@linkcode PositionalTagType} of the desired tag, or a partially-filled {@linkcode PositionalTag}
+ * containing the desired properties
+ * @param count - The number of tags that should be active; defaults to `1` and must be within the range `[0, 4]`
+ * @returns The result of the matching
+ */
+export function toHavePositionalTag<P extends PositionalTagType>(
+  this: MatcherState,
+  received: unknown,
+  expectedTag: P | toHavePositionalTagOptions<P>,
+  count = 1,
+): SyncExpectationResult {
+  if (!isGameManagerInstance(received)) {
+    return {
+      pass: this.isNot,
+      message: () => `Expected to receive a GameManager, but got ${receivedStr(received)}!`,
+    };
+  }
+
+  if (!received.scene?.arena?.positionalTagManager) {
+    return {
+      pass: this.isNot,
+      message: () =>
+        `Expected GameManager.${received.scene?.arena ? "scene.arena.positionalTagManager" : received.scene ? "scene.arena" : "scene"} to be defined!`,
+    };
+  }
+
+  // TODO: Increase limit if triple battles are added
+  if (count < 0 || count > 4) {
+    return {
+      pass: this.isNot,
+      message: () => `Expected count to be between 0 and 4, but got ${count} instead!`,
+    };
+  }
+
+  const allTags = received.scene.arena.positionalTagManager.tags;
+  const tagType = typeof expectedTag === "string" ? expectedTag : expectedTag.tagType;
+  const matchingTags = allTags.filter(t => t.tagType === tagType);
+
+  // If checking exclusively tag type, check solely the number of matching tags on field
+  if (typeof expectedTag === "string") {
+    const pass = matchingTags.length === count;
+    const expectedStr = getPosTagStr(expectedTag);
+
+    return {
+      pass,
+      message: () =>
+        pass
+          ? `Expected the Arena to NOT have ${count} ${expectedStr} active, but it did!`
+          : `Expected the Arena to have ${count} ${expectedStr} active, but got ${matchingTags.length} instead!`,
+      expected: expectedTag,
+      actual: allTags,
+    };
+  }
+
+  // Check for equality with the provided object
+  if (matchingTags.length === 0) {
+    return {
+      pass: false,
+      message: () => `Expected the Arena to have a tag of type ${expectedTag.tagType}, but it didn't!`,
+      expected: expectedTag.tagType,
+      actual: received.scene.arena.tags.map(t => t.tagType),
+    };
+  }
+
+  // Pass if any of the matching tags meet the criteria
+  const pass = matchingTags.some(tag =>
+    this.equals(tag, expectedTag, [...this.customTesters, this.utils.subsetEquality, this.utils.iterableEquality]),
+  );
+
+  const expectedStr = getOnelineDiffStr.call(this, expectedTag);
+  return {
+    pass,
+    message: () =>
+      pass
+        ? `Expected the Arena to NOT have a tag matching ${expectedStr}, but it did!`
+        : `Expected the Arena to have a tag matching ${expectedStr}, but it didn't!`,
+    expected: expectedTag,
+    actual: matchingTags,
+  };
+}
+
+function getPosTagStr(pType: PositionalTagType, count = 1): string {
+  let ret = toTitleCase(pType) + "Tag";
+  if (count > 1) {
+    ret += "s";
+  }
+  return ret;
+}

test/test-utils/matchers/to-have-stat-stage.ts

@@ -23,14 +23,14 @@ export function toHaveStatStage(
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }
 
   if (expectedStage < -6 || expectedStage > 6) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected ${expectedStage} to be within the range [-6, 6]!`,
     };
   }

test/test-utils/matchers/to-have-status-effect.ts

@@ -28,7 +28,7 @@ export function toHaveStatusEffect(
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }

test/test-utils/matchers/to-have-taken-damage.ts

@@ -24,7 +24,7 @@ export function toHaveTakenDamage(
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }

test/test-utils/matchers/to-have-terrain.ts

@@ -20,15 +20,15 @@ export function toHaveTerrain(
 ): SyncExpectationResult {
   if (!isGameManagerInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected GameManager, but got ${receivedStr(received)}!`,
+      message: () => `Expected to receive a GameManager, but got ${receivedStr(received)}!`,
     };
   }
 
   if (!received.scene?.arena) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected GameManager.${received.scene ? "scene" : "scene.arena"} to be defined!`,
+      message: () => `Expected GameManager.${received.scene ? "scene.arena" : "scene"} to be defined!`,
     };
   }
 
@@ -41,8 +41,8 @@ export function toHaveTerrain(
     pass,
     message: () =>
       pass
-        ? `Expected Arena to NOT have ${expectedStr} active, but it did!`
+        ? `Expected the Arena to NOT have ${expectedStr} active, but it did!`
-        : `Expected Arena to have ${expectedStr} active, but got ${actualStr} instead!`,
+        : `Expected the Arena to have ${expectedStr} active, but got ${actualStr} instead!`,
     expected: expectedTerrainType,
     actual,
   };

test/test-utils/matchers/to-have-types.ts

@@ -7,10 +7,16 @@ import { isPokemonInstance, receivedStr } from "../test-utils";
 
 export interface toHaveTypesOptions {
   /**
-   * Whether to enforce exact matches (`true`) or superset matches (`false`).
+   * Value dictating the strength of the enforced typing match.
-   * @defaultValue `true`
+   *
+   * Possible values (in ascending order of strength) are:
+   * - `"ordered"`: Enforce that the {@linkcode Pokemon}'s types are identical **and in the same order**
+   * - `"unordered"`: Enforce that the {@linkcode Pokemon}'s types are identical **without checking order**
+   * - `"superset"`: Enforce that the {@linkcode Pokemon}'s types are **a superset of** the expected types
+   * (all must be present, but extras can be there)
+   * @defaultValue `"unordered"`
    */
-  exact?: boolean;
+  mode?: "ordered" | "unordered" | "superset";
   /**
    * Optional arguments to pass to {@linkcode Pokemon.getTypes}.
    */
@@ -18,35 +24,54 @@ export interface toHaveTypesOptions {
 }
 
 /**
- * Matcher that checks if an array contains exactly the given items, disregarding order.
+ * Matcher that checks if a Pokemon's typing is as expected.
- * @param received - The object to check. Should be an array of one or more {@linkcode PokemonType}s.
+ * @param received - The object to check. Should be a {@linkcode Pokemon}
- * @param options - The {@linkcode toHaveTypesOptions | options} for this matcher
+ * @param expectedTypes - An array of one or more {@linkcode PokemonType}s to compare against.
+ * @param mode - The mode to perform the matching in.
+ * Possible values (in ascending order of strength) are:
+ * - `"ordered"`: Enforce that the {@linkcode Pokemon}'s types are identical **and in the same order**
+ * - `"unordered"`: Enforce that the {@linkcode Pokemon}'s types are identical **without checking order**
+ * - `"superset"`: Enforce that the {@linkcode Pokemon}'s types are **a superset of** the expected types
+ * (all must be present, but extras can be there)
+ *
+ * Default `unordered`
+ * @param args - Extra arguments passed to {@linkcode Pokemon.getTypes}
  * @returns The result of the matching
  */
 export function toHaveTypes(
   this: MatcherState,
   received: unknown,
-  expected: [PokemonType, ...PokemonType[]],
+  expectedTypes: [PokemonType, ...PokemonType[]],
-  options: toHaveTypesOptions = {},
+  { mode = "unordered", args = [] }: toHaveTypesOptions = {},
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected to recieve a Pokémon, but got ${receivedStr(received)}!`,
+      message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }
 
-  const actualTypes = received.getTypes(...(options.args ?? [])).sort();
+  // Return early if no types were passed in
-  const expectedTypes = expected.slice().sort();
+  if (expectedTypes.length === 0) {
+    return {
+      pass: this.isNot,
+      message: () => "Expected to receive a non-empty array of PokemonTypes!",
+    };
+  }
+
+  // Avoid sorting the types if strict ordering is desired
+  const actualSorted = mode === "ordered" ? received.getTypes(...args) : received.getTypes(...args).toSorted();
+  const expectedSorted = mode === "ordered" ? expectedTypes : expectedTypes.toSorted();
 
   // Exact matches do not care about subset equality
-  const matchers = options.exact
+  const matchers =
-    ? [...this.customTesters, this.utils.iterableEquality]
+    mode === "superset"
-    : [...this.customTesters, this.utils.subsetEquality, this.utils.iterableEquality];
+      ? [...this.customTesters, this.utils.iterableEquality]
-  const pass = this.equals(actualTypes, expectedTypes, matchers);
+      : [...this.customTesters, this.utils.subsetEquality, this.utils.iterableEquality];
+  const pass = this.equals(actualSorted, expectedSorted, matchers);
 
-  const actualStr = stringifyEnumArray(PokemonType, actualTypes);
+  const actualStr = stringifyEnumArray(PokemonType, actualSorted);
-  const expectedStr = stringifyEnumArray(PokemonType, expectedTypes);
+  const expectedStr = stringifyEnumArray(PokemonType, expectedSorted);
   const pkmName = getPokemonNameWithAffix(received);
 
   return {
@@ -55,7 +80,7 @@ export function toHaveTypes(
       pass
         ? `Expected ${pkmName} to NOT have types ${expectedStr}, but it did!`
         : `Expected ${pkmName} to have types ${expectedStr}, but got ${actualStr} instead!`,
-    expected: expectedTypes,
+    expected: expectedSorted,
-    actual: actualTypes,
+    actual: actualSorted,
   };
 }

test/test-utils/matchers/to-have-used-move.ts

@@ -13,7 +13,7 @@ import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 /**
  * Matcher to check the contents of a {@linkcode Pokemon}'s move history.
  * @param received - The actual value received. Should be a {@linkcode Pokemon}
- * @param expectedValue - The {@linkcode MoveId} the Pokemon is expected to have used,
+ * @param expectedMove - The {@linkcode MoveId} the Pokemon is expected to have used,
  * or a partially filled {@linkcode TurnMove} containing the desired properties to check
  * @param index - The index of the move history entry to check, in order from most recent to least recent.
  * Default `0` (last used move)
@@ -22,12 +22,12 @@ import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 export function toHaveUsedMove(
   this: MatcherState,
   received: unknown,
-  expectedResult: MoveId | AtLeastOne<TurnMove>,
+  expectedMove: MoveId | AtLeastOne<TurnMove>,
   index = 0,
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }
@@ -37,34 +37,33 @@ export function toHaveUsedMove(
 
   if (move === undefined) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected ${pkmName} to have used ${index + 1} moves, but it didn't!`,
       actual: received.getLastXMoves(-1),
     };
   }
 
   // Coerce to a `TurnMove`
-  if (typeof expectedResult === "number") {
+  if (typeof expectedMove === "number") {
-    expectedResult = { move: expectedResult };
+    expectedMove = { move: expectedMove };
   }
 
   const moveIndexStr = index === 0 ? "last move" : `${getOrdinal(index)} most recent move`;
 
-  const pass = this.equals(move, expectedResult, [
+  const pass = this.equals(move, expectedMove, [
     ...this.customTesters,
     this.utils.subsetEquality,
     this.utils.iterableEquality,
   ]);
 
-  const expectedStr = getOnelineDiffStr.call(this, expectedResult);
+  const expectedStr = getOnelineDiffStr.call(this, expectedMove);
   return {
     pass,
     message: () =>
       pass
         ? `Expected ${pkmName}'s ${moveIndexStr} to NOT match ${expectedStr}, but it did!`
-        : // Replace newlines with spaces to preserve one-line ness
+        : `Expected ${pkmName}'s ${moveIndexStr} to match ${expectedStr}, but it didn't!`,
-          `Expected ${pkmName}'s ${moveIndexStr} to match ${expectedStr}, but it didn't!`,
+    expected: expectedMove,
-    expected: expectedResult,
     actual: move,
   };
 }

test/test-utils/matchers/to-have-used-pp.ts

@@ -13,7 +13,7 @@ import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 /**
  * Matcher to check the amount of PP consumed by a {@linkcode Pokemon}.
  * @param received - The actual value received. Should be a {@linkcode Pokemon}
- * @param expectedValue - The {@linkcode MoveId} that should have consumed PP
+ * @param moveId - The {@linkcode MoveId} that should have consumed PP
  * @param ppUsed - The numerical amount of PP that should have been consumed,
  * or `all` to indicate the move should be _out_ of PP
  * @returns Whether the matcher passed
@@ -23,12 +23,12 @@ import type { MatcherState, SyncExpectationResult } from "@vitest/expect";
 export function toHaveUsedPP(
   this: MatcherState,
   received: unknown,
-  expectedMove: MoveId,
+  moveId: MoveId,
   ppUsed: number | "all",
 ): SyncExpectationResult {
   if (!isPokemonInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () => `Expected to receive a Pokémon, but got ${receivedStr(received)}!`,
     };
   }
@@ -36,22 +36,22 @@ export function toHaveUsedPP(
   const override = received.isPlayer() ? Overrides.MOVESET_OVERRIDE : Overrides.ENEMY_MOVESET_OVERRIDE;
   if (coerceArray(override).length > 0) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () =>
         `Cannot test for PP consumption with ${received.isPlayer() ? "player" : "enemy"} moveset overrides active!`,
     };
   }
 
   const pkmName = getPokemonNameWithAffix(received);
-  const moveStr = getEnumStr(MoveId, expectedMove);
+  const moveStr = getEnumStr(MoveId, moveId);
 
-  const movesetMoves = received.getMoveset().filter(pm => pm.moveId === expectedMove);
+  const movesetMoves = received.getMoveset().filter(pm => pm.moveId === moveId);
   if (movesetMoves.length !== 1) {
     return {
-      pass: false,
+      pass: this.isNot,
       message: () =>
         `Expected MoveId.${moveStr} to appear in ${pkmName}'s moveset exactly once, but got ${movesetMoves.length} times!`,
-      expected: expectedMove,
+      expected: moveId,
       actual: received.getMoveset(),
     };
   }

test/test-utils/matchers/to-have-weather.ts

@@ -20,15 +20,15 @@ export function toHaveWeather(
 ): SyncExpectationResult {
   if (!isGameManagerInstance(received)) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected GameManager, but got ${receivedStr(received)}!`,
+      message: () => `Expected to receive a GameManager, but got ${receivedStr(received)}!`,
     };
   }
 
   if (!received.scene?.arena) {
     return {
-      pass: false,
+      pass: this.isNot,
-      message: () => `Expected GameManager.${received.scene ? "scene" : "scene.arena"} to be defined!`,
+      message: () => `Expected GameManager.${received.scene ? "scene.arena" : "scene"} to be defined!`,
     };
   }
 
@@ -41,8 +41,8 @@ export function toHaveWeather(
     pass,
     message: () =>
       pass
-        ? `Expected Arena to NOT have ${expectedStr} weather active, but it did!`
+        ? `Expected the Arena to NOT have ${expectedStr} weather active, but it did!`
-        : `Expected Arena to have ${expectedStr} weather active, but got ${actualStr} instead!`,
+        : `Expected the Arena to have ${expectedStr} weather active, but got ${actualStr} instead!`,
     expected: expectedWeatherType,
     actual,
   };

test/test-utils/string-utils.ts

@@ -34,10 +34,10 @@ interface getEnumStrOptions {
  * @returns The stringified representation of `val` as dictated by the options.
  * @example
  * ```ts
- * enum fakeEnum {
+ * enum testEnum {
- *   ONE: 1,
+ *   ONE = 1,
- *   TWO: 2,
+ *   TWO = 2,
- *   THREE: 3,
+ *   THREE = 3,
  * }
  * getEnumStr(fakeEnum, fakeEnum.ONE); // Output: "ONE (=1)"
  * getEnumStr(fakeEnum, fakeEnum.TWO, {casing: "Title", prefix: "fakeEnum.", suffix: "!!!"}); // Output: "fakeEnum.TWO!!! (=2)"
@@ -174,10 +174,14 @@ export function getStatName(s: Stat): string {
  * Convert an object into a oneline diff to be shown in an error message.
  * @param obj - The object to return the oneline diff of
  * @returns The updated diff
+ * @example
+ * ```ts
+ * const diff = getOnelineDiffStr.call(this, obj)
+ * ```
  */
 export function getOnelineDiffStr(this: MatcherState, obj: unknown): string {
   return this.utils
     .stringify(obj, undefined, { maxLength: 35, indent: 0, printBasicPrototype: false })
     .replace(/\n/g, " ") // Replace newlines with spaces
-    .replace(/,(\s*)}$/g, "$1}");
+    .replace(/,(\s*)}$/g, "$1}"); // Trim trailing commas
 }