/** * Simulator State * Pokemon Showdown - http://pokemonshowdown.com/ * * Helper functions for serializing Battle instances to JSON and back. * * (You might also consider using input logs instead.) * * @license MIT */ import { Battle } from './battle'; import { Dex } from './dex'; import { Field } from './field'; import { Pokemon } from './pokemon'; import { PRNG } from './prng'; import { type Choice, Side } from './side'; // The simulator supports up to 24 different Pokemon on a team. Serialization // uses letters instead of numbers to indicate indices/positions, but where // the simulator only gives a position to active Pokemon, serialization // uses letters for every Pokemon on a team. Active pokemon will still // have the same letter as their position would indicate, but non-active // team members are filled in with subsequent letters. const POSITIONS = 'abcdefghijklmnopqrstuvwx'; // Several types we serialize as 'references' in the form '[Type]' because // they are either circular or they are (or at least, should be) immutable // and thus can simply be reconsituted as needed. // NOTE: Species is not strictly immutable as some OM formats rely on an // onModifySpecies event - deserialization is not possible for such formats. type Referable = Battle | Field | Side | Pokemon | Condition | Ability | Item | Move | Species; // Certain fields are either redundant (transient caches, constants, duplicate // information) or require special treatment. These sets contain the specific // keys which we skip during default (de)serialization and (the keys which) // need special treatment from these sets are then handled manually. const BATTLE = new Set([ 'dex', 'gen', 'ruleTable', 'id', 'log', 'inherit', 'format', 'teamGenerator', 'HIT_SUBSTITUTE', 'NOT_FAIL', 'FAIL', 'SILENT_FAIL', 'field', 'sides', 'prng', 'hints', 'deserialized', 'queue', 'actions', ]); const FIELD = new Set(['id', 'battle']); const SIDE = new Set(['battle', 'team', 'pokemon', 'choice', 'activeRequest']); const POKEMON = new Set([ 'side', 'battle', 'set', 'name', 'fullname', 'id', 'happiness', 'level', 'pokeball', 'baseMoveSlots', ]); const CHOICE = new Set(['switchIns']); const ACTIVE_MOVE = new Set(['move']); export const State = new class { // REFERABLE is used to determine which objects are of the Referable type by // comparing their constructors. Unfortunately, we need to set this dynamically // due to circular module dependencies on Battle and Field instead // of simply initializing it as a const. See isReferable for where this // gets lazily created on demand. REFERABLE?: Set; serializeBattle(battle: Battle): /* Battle */ AnyObject { const state: /* Battle */ AnyObject = this.serialize(battle, BATTLE, battle); state.field = this.serializeField(battle.field); state.sides = new Array(battle.sides.length); for (const [i, side] of battle.sides.entries()) { state.sides[i] = this.serializeSide(side); } state.prng = battle.prng.getSeed(); state.hints = Array.from(battle.hints); // We treat log specially because we only set it back on Battle after everything // else has been deserialized to avoid anything accidentally `add`-ing to it. state.log = battle.log; state.queue = this.serializeWithRefs(battle.queue.list, battle); state.formatid = battle.format.id; return state; } // Deserialization can only really be done on the root Battle object as // the leaf nodes like Side or Pokemon contain backreferences to Battle // but don't contain the information to fill it in because the cycles in // the graph have been serialized as references. Once deserialzized, the // Battle can then be restarted (and provided with a `send` function for // receiving updates). deserializeBattle(serialized: string | /* Battle */ AnyObject): Battle { const state: /* Battle */ AnyObject = typeof serialized === 'string' ? JSON.parse(serialized) : serialized; const options = { formatid: state.formatid, seed: state.prngSeed, rated: state.rated, debug: state.debugMode, // We need to tell the Battle that we're creating that it's been // deserialized so that it allows us to populate it correctly and // doesn't attempt to start playing out until we're ready. deserialized: true, strictChoices: state.strictChoices, }; for (const side of state.sides) { // When we instantiate the Battle again we need the pokemon to be in // the correct order they were in at the start of the Battle which was // serialized. See serializeSide below for an explanation about the // encoding format used deserializeSide for where we reorder the Side's // pokemon to match their ordering at the point of serialization. const team = side.team.split(side.team.length > 9 ? ',' : ''); // @ts-expect-error index signature options[side.id] = { name: side.name, avatar: side.avatar, team: team.map((p: string) => side.pokemon[Number(p) - 1].set), }; } // We create the Battle, allowing it to instantiate the Field/Side/Pokemon // objects for us. The objects it creates will be incorrect, but we descend // down through the fields and repopulate all of the objects with the // correct state afterwards. const battle = new Battle(options); // Calling `new Battle(...)` means side.pokemon is ordered to match what it // was at the start of the battle (state.team), but we need to order the Pokemon // back in their correct order based on how the battle has progressed. We need // do to this before making any deserialization calls so that `fromRef` will // be correct. for (const [i, s] of state.sides.entries()) { const side = battle.sides[i]; const ordered = new Array(side.pokemon.length); const team = s.team.split(s.team.length > 9 ? ',' : ''); for (const [j, pos] of team.entries()) { ordered[Number(pos) - 1] = side.pokemon[j]; } side.pokemon = ordered; } this.deserialize(state, battle, BATTLE, battle); this.deserializeField(state.field, battle.field); let activeRequests = false; for (const [i, side] of state.sides.entries()) { this.deserializeSide(side, battle.sides[i]); activeRequests = activeRequests || side.activeRequest === undefined; } // Since battle.getRequests depends on the state of each side we can't combine // this loop with the one above which deserializes the sides. We also only do this // if there are any active requests, not only to avoid have to recompute request // states we wouldnt be using, but also because battle.getRequests will mutate // state on occasion (eg. `pokemon.getMoves` sets `pokemon.trapped = true` if locked). if (activeRequests) { const requests = battle.getRequests(battle.requestState); for (const [i, side] of state.sides.entries()) { battle.sides[i].activeRequest = side.activeRequest === null ? null : requests[i]; } } battle.prng = new PRNG(state.prng); const queue = this.deserializeWithRefs(state.queue, battle); battle.queue.list = queue; (battle as any).hints = new Set(state.hints); (battle as any).log = state.log; return battle; } // Direct comparsions of serialized state will be flakey as the timestamp // protocol message |t:| can diverge between two different runs over the same state. // State must first be normalized before it is comparable. normalize(state: AnyObject) { state.log = this.normalizeLog(state.log); return state; } normalizeLog(log?: null | string | string[]) { if (!log) return log; const normalized = (typeof log === 'string' ? log.split('\n') : log).map(line => line.startsWith(`|t:|`) ? `|t:|` : line); return (typeof log === 'string' ? normalized.join('\n') : normalized); } serializeField(field: Field): /* Field */ AnyObject { return this.serialize(field, FIELD, field.battle); } deserializeField(state: /* Field */ AnyObject, field: Field) { this.deserialize(state, field, FIELD, field.battle); } serializeSide(side: Side): /* Side */ AnyObject { const state: /* Side */ AnyObject = this.serialize(side, SIDE, side.battle); state.pokemon = new Array(side.pokemon.length); const team = new Array(side.pokemon.length); for (const [i, pokemon] of side.pokemon.entries()) { state.pokemon[i] = this.serializePokemon(pokemon); team[side.team.indexOf(pokemon.set)] = i + 1; } // We encode the team such that it could be used as a valid `/team` command // during decoding to transform the current ordering of the serialized Side's // pokemon array into the original team ordering at the start of the battle. // This is *not* the same as the original `/team` command used to order the // pokemon in team preview, but this encoding results in the most intuitive // and readable debugging of the raw JSON, so we're willing to add a small // amount of complexity to the encoding/decoding process to accommodate this. state.team = team.join(team.length > 9 ? ',' : ''); state.choice = this.serializeChoice(side.choice, side.battle); // If activeRequest is null we encode it as a tombstone indicator to ensure // that during serialization when we recompute the activeRequest we don't turn // `activeRequest = null` into `activeRequest = { wait: true, ... }`. if (side.activeRequest === null) state.activeRequest = null; return state; } deserializeSide(state: /* Side */ AnyObject, side: Side) { this.deserialize(state, side, SIDE, side.battle); for (const [i, pokemon] of state.pokemon.entries()) { this.deserializePokemon(pokemon, side.pokemon[i]); } this.deserializeChoice(state.choice, side.choice, side.battle); } serializePokemon(pokemon: Pokemon): /* Pokemon */ AnyObject { const state: /* Pokemon */ AnyObject = this.serialize(pokemon, POKEMON, pokemon.battle); state.set = pokemon.set; // Only serialize the baseMoveSlots if they differ from moveSlots. We could get fancy and // only serialize the diff and its index but thats overkill for a pretty niche case anyway. if (pokemon.baseMoveSlots.length !== pokemon.moveSlots.length || !pokemon.baseMoveSlots.every((ms, i) => ms === pokemon.moveSlots[i])) { state.baseMoveSlots = this.serializeWithRefs(pokemon.baseMoveSlots, pokemon.battle); } return state; } deserializePokemon(state: /* Pokemon */ AnyObject, pokemon: Pokemon) { this.deserialize(state, pokemon, POKEMON, pokemon.battle); (pokemon as any).set = state.set; // baseMoveSlots and moveSlots need to point to the same objects (ie. identity, not equality). // If we serialized the baseMoveSlots, replace any that match moveSlots to preserve the // identity relationship requirement. let baseMoveSlots; if (state.baseMoveSlots) { baseMoveSlots = this.deserializeWithRefs(state.baseMoveSlots, pokemon.battle); for (const [i, baseMoveSlot] of baseMoveSlots.entries()) { const moveSlot = pokemon.moveSlots[i]; if (moveSlot.id === baseMoveSlot.id && !moveSlot.virtual) { baseMoveSlots[i] = moveSlot; } } } else { baseMoveSlots = pokemon.moveSlots.slice(); } (pokemon as any).baseMoveSlots = baseMoveSlots; if (state.showCure === undefined) pokemon.showCure = undefined; } serializeChoice(choice: Choice, battle: Battle): /* Choice */ AnyObject { const state: /* Choice */ AnyObject = this.serialize(choice, CHOICE, battle); state.switchIns = Array.from(choice.switchIns); return state; } deserializeChoice(state: /* Choice */ AnyObject, choice: Choice, battle: Battle) { this.deserialize(state, choice, CHOICE, battle); choice.switchIns = new Set(state.switchIns); } // Simply looking for a 'hit' field to determine if an object is an ActiveMove or not seems // pretty fragile, but its no different than what the simulator is doing. We go further and // also check if the object has an 'id', as that's what we will intrepret as the Move. isActiveMove(obj: AnyObject): obj is ActiveMove { return obj.hasOwnProperty('hit') && (obj.hasOwnProperty('id') || obj.hasOwnProperty('move')); } // ActiveMove is somewhat problematic (#5415) as it sometimes extends a Move and adds on // some mutable fields. We'd like to avoid displaying all the readonly fields of Move // (which in theory should not be changed by the ActiveMove...), so we collapse them // into a 'move: [Move:...]' reference. If isActiveMove returns a false positive *and* // and object contains an 'id' field matching a Move *and* it contains fields with the // same name as said Move then we'll miss them during serialization and won't // deserialize properly. This is unlikely to be the case, and would probably indicate // a bug in the simulator if it ever happened, but if not, the isActiveMove check can // be extended. serializeActiveMove(move: ActiveMove, battle: Battle): /* ActiveMove */ AnyObject { const base = battle.dex.moves.get(move.id); const skip = new Set([...ACTIVE_MOVE]); for (const [key, value] of Object.entries(base)) { // This should really be a deepEquals check to see if anything on ActiveMove was // modified from the base Move, but that ends up being expensive and mostly unnecessary // as ActiveMove currently only mutates its simple fields (eg. `type`, `target`) anyway. // @ts-expect-error index signature if (typeof value === 'object' || move[key] === value) skip.add(key); } const state: /* ActiveMove */ AnyObject = this.serialize(move, skip, battle); state.move = `[Move:${move.id}]`; return state; } deserializeActiveMove(state: /* ActiveMove */ AnyObject, battle: Battle): ActiveMove { const move = battle.dex.getActiveMove(this.fromRef(state.move, battle)! as Move); this.deserialize(state, move, ACTIVE_MOVE, battle); return move; } serializeWithRefs(obj: unknown, battle: Battle): unknown { switch (typeof obj) { case 'function': return undefined; // elide functions case 'undefined': case 'boolean': case 'number': case 'string': return obj; case 'object': if (obj === null) return null; if (Array.isArray(obj)) { const arr = new Array(obj.length); for (const [i, o] of obj.entries()) { arr[i] = this.serializeWithRefs(o, battle); } return arr; } if (this.isActiveMove(obj)) return this.serializeActiveMove(obj, battle); if (this.isReferable(obj)) return this.toRef(obj); if (obj.constructor !== Object) { // If we're getting this error, some 'special' field has been added to // an object and we need to update the logic in this file to handle it. // The most common case it that someone added a Set/Map which probably // needs to be serialized as an Array/Object respectively - see how // Battle 'hints' or Choice 'switchIns' are handled (and you will likely // need to add the new field to the respective skip constant). throw new TypeError(`Unsupported type ${obj.constructor.name}: ${obj as any}`); } const o: any = {}; for (const [key, value] of Object.entries(obj)) { o[key] = this.serializeWithRefs(value, battle); } return o; default: throw new TypeError(`Unexpected typeof === '${typeof obj}': ${obj}`); } } deserializeWithRefs(obj: unknown, battle: Battle) { switch (typeof obj) { case 'undefined': case 'boolean': case 'number': return obj; case 'string': return this.fromRef(obj, battle) || obj; case 'object': if (obj === null) return null; if (Array.isArray(obj)) { const arr = new Array(obj.length); for (const [i, o] of obj.entries()) { arr[i] = this.deserializeWithRefs(o, battle); } return arr; } if (this.isActiveMove(obj)) return this.deserializeActiveMove(obj, battle); const o: any = {}; for (const [key, value] of Object.entries(obj)) { o[key] = this.deserializeWithRefs(value, battle); } return o; case 'function': // lol wtf default: throw new TypeError(`Unexpected typeof === '${typeof obj}': ${obj}`); } } isReferable(obj: object): obj is Referable { // NOTE: see explanation on the declaration above for why this must be defined lazily. if (!this.REFERABLE) { this.REFERABLE = new Set([ Battle, Field, Side, Pokemon, Dex.Condition, Dex.Ability, Dex.Item, Dex.Move, Dex.Species, ]); } return this.REFERABLE.has(obj.constructor); } toRef(obj: Referable): string { // Pokemon's 'id' is not only more verbose than a position, it also isn't guaranteed // to be uniquely identifying in custom games without Nickname/Species Clause. const id = obj instanceof Pokemon ? `${obj.side.id}${POSITIONS[obj.position]}` : `${obj.id}`; return `[${obj.constructor.name}${id ? ':' : ''}${id}]`; } fromRef(ref: string, battle: Battle): Referable | undefined { // References are sort of fragile - we're mostly just counting on there // being a low chance that some string field in a simulator object will not // 'look' like one. However, it also needs to match one of the Referable // class types to be decode, so we're probably OK. We could make the reference // markers more esoteric with additional sigils etc to avoid collisions, but // we're making a conscious decision to favor readability over robustness. if (!ref.startsWith('[') && !ref.endsWith(']')) return undefined; ref = ref.substring(1, ref.length - 1); // There's only one instance of these thus they don't need an id to differentiate. if (ref === 'Battle') return battle; if (ref === 'Field') return battle.field; const [type, id] = ref.split(':'); switch (type) { case 'Side': return battle.sides[Number(id[1]) - 1]; case 'Pokemon': return battle.sides[Number(id[1]) - 1].pokemon[POSITIONS.indexOf(id[2])]; case 'Ability': return battle.dex.abilities.get(id); case 'Item': return battle.dex.items.get(id); case 'Move': return battle.dex.moves.get(id); case 'Condition': return battle.dex.conditions.get(id); case 'Species': return battle.dex.species.get(id); default: return undefined; // maybe we actually got unlucky and its a string } } serialize(obj: object, skip: Set, battle: Battle): AnyObject { const state: AnyObject = {}; for (const [key, value] of Object.entries(obj)) { if (skip.has(key)) continue; const val = this.serializeWithRefs(value, battle); // JSON.stringify will get rid of keys with undefined values anyway, but // we also do it here so that assert.deepEqual works on battle.toJSON(). if (typeof val !== 'undefined') state[key] = val; } return state; } deserialize(state: AnyObject, obj: object, skip: Set, battle: Battle) { for (const [key, value] of Object.entries(state)) { if (skip.has(key)) continue; // @ts-expect-error index signature obj[key] = this.deserializeWithRefs(value, battle); } } };