Teams — Pokémon Team Packing, Parsing, and Export

The Teams object handles all serialisation and deserialisation of Pokémon team data. Its two most-used methods, Teams.pack and Teams.unpack, convert between a structured PokemonSet[] array and the compact pipe-delimited packed string that Pokémon Showdown uses for storage and network transfer. A separate human-readable export format (Smogon showdown format) is handled by Teams.exportSet / Teams.export / Teams.import. The Teams namespace also declares the PokemonSet, FullPokemonSet, and Team interfaces that appear throughout the codebase.

battle-teams.ts carries the MIT license and has no external runtime dependencies beyond battle-dex.ts and battle-dex-data.ts.

Type Declarations

`Teams.PokemonSet`

A sparse representation of a team member — only species and moves are required; all other fields fall back to game defaults when omitted.

export interface PokemonSet extends Partial<FullPokemonSet> {
  species: string;   // required
  moves: string[];   // required
}

species

string

required

Species name (including forme if applicable), e.g. "Gardevoir", "Rotom-Wash".

moves

string[]

required

Array of move names. Up to four in standard play.

name

string

Nickname. Defaults to the base species name (without forme), matching in-game behaviour. Omit or set to '' to use the default.

item

string

Held item name. Defaults to no item.

ability

string

Ability name. Required from Gen 3 onward; omitting it is an error in most formats.

nature

Dex.NatureName

One of the 25 nature names. Required from Gen 3 onward.

gender

string

'M', 'F', or ''. Defaults to a random legal gender (not subject to gender ratio).

evs

Partial<Dex.StatsTable>

EV spread. Omitted EVs default to 252 in standard formats, 200 in Let’s Go, and 0 in Gen 1–2. Pass { hp: 0, atk: 0, def: 0, spa: 0, spd: 0, spe: 0 } to explicitly set all to zero.

ivs

Dex.StatsTable

IV spread. Defaults to all 31s, except for stats implied by Hidden Power type or Gyro Ball.

level

number

Level. Defaults to 100 in standard formats, 50 in VGC-style, and 5 in Little Cup.

shiny

boolean

Shiny flag. Defaults to false.

happiness

number

Happiness value (0–255). Defaults to 255 unless Frustration is in the move list, in which case 0.

pokeball

string

Poké Ball name. Defaults to the event-required ball if applicable, otherwise Poké Ball.

hpType

string

Hidden Power type. Defaults to the type determined by the IVs.

dynamaxLevel

number

Dynamax level (0–10). Defaults to 10.

gigantamax

boolean

Whether to use the Gigantamax form if available. Defaults to false.

teraType

string

Tera type for Gen 9. Defaults to the Pokémon’s primary type.

`Teams.FullPokemonSet`

The maximal representation of a team member, with all fields that a PokemonSet can carry. Some fields remain optional because they have inherent defaults (for example item, ability, nature). The comment on each field documents the rule used to fill in omitted values.

export interface FullPokemonSet {
  name: string;
  species: string;
  item?: string;
  ability?: string;
  moves: string[];
  nature?: Dex.NatureName;
  gender?: string;
  evs: Partial<Dex.StatsTable>;
  ivs: Dex.StatsTable;
  level: number;
  shiny: boolean;
  happiness: number;
  pokeball: string;
  hpType?: string;
  dynamaxLevel?: number;
  gigantamax?: boolean;
  teraType?: string;
}

`Teams.Team`

A metadata wrapper around a packed team string, used by the teambuilder and storage layer.

export interface Team {
  name: string;
  format: ID;
  folder: string;
  packedTeam: string;  // may be wrong if `.uploaded?.notLoaded`
  isBox: boolean;
}

name

string

Display name for the team (e.g. "My OU Team").

format

Format ID this team is intended for (e.g. 'gen9ou').

folder

string

Folder path in the teambuilder’s tree. Empty string for root.

packedTeam

string

The packed team string (see format specification below).

isBox

boolean

true for the special “box” team used by Random Battle and similar formats.

Packed Team Format

The packed format is designed for compact storage and network transfer. Each Pokémon set is a pipe-delimited (|) record; sets are separated by ].

name|species|item|ability|move1,move2,move3,move4|nature|hp,atk,def,spa,spd,spe|gender|hp,atk,def,spa,spd,spe|shiny|level|happiness[,hpType,pokeball,gigantamax,dynamaxLevel,teraType]

Field order (positional)

Position	Field	Notes
0	`name`	Display name. If identical to species after `packName`, omitted in field 1
1	`species`	Omitted (empty string) if same as name after normalisation
2	`item`	Empty string for no item
3	`ability`	Empty string for no ability
4	`moves`	Comma-separated, non-alphanumeric chars stripped via `packName`
5	`nature`	Empty string if absent
6	EVs	Comma-separated `hp,atk,def,spa,spd,spe`; entirely omitted (`	`) if all zero
7	`gender`	`'M'`, `'F'`, or `''`
8	IVs	Comma-separated; fields are empty for 31, non-31 values are explicit
9	`shiny`	`'S'` if shiny, otherwise `''`
10	`level`	Omitted if 100
11	`happiness[,hpType,pokeball,gigantamax,dynamaxLevel,teraType]`	Extended suffix — comma-separated, only included if at least one is non-default

Real Packed Team Example

Gardevoir||ChoiceScarf|Trace|Moonblast,Psychic,Trick,Healing Wish|Timid|,,,252,,252||F|||,,,,,
]Landorus-Therian||RockyHelmet|Intimidate|StealthRock,Earthquake,UPunch,Defog|Impish|252,,252,,,|||||,,,,,

Breaking down the first set:

Name: Gardevoir (same as species → species field is empty)
Item: ChoiceScarf
Ability: Trace
Moves: Moonblast,Psychic,Trick,HealingWish (spaces stripped)
Nature: Timid
EVs: ,,,252,,252 (only SpA 252 and Spe 252)
Gender: F
IVs: (empty = all 31)
Shiny: ''
Level: '' (100)

`Teams` Object Methods

`Teams.pack(team)`

Serialises a PokemonSet[] to the packed string format. Returns '' for a null input.

pack(team: Teams.PokemonSet[] | null): string

team

Teams.PokemonSet[] | null

required

Array of set objects. Passing null returns an empty string.

Implementation details

Field separators are |; set separators are ].
Names and move names are normalised via packName (strips non-alphanumeric characters, preserves case unlike toID).
EVs are omitted entirely when all six are zero.
IVs: each field is empty when the value is 31 or undefined.
Level is omitted when it equals 100.
Happiness is omitted when it equals 255.
The extended suffix (fields 12–16: hpType, pokeball, gigantamax, dynamaxLevel, teraType) is only appended when at least one is non-default.

`Teams.unpack(buf)`

Deserialises a packed team string into a PokemonSet[]. Returns [] for an empty string.

unpack(buf: string): Teams.PokemonSet[]

buf

string

required

A packed team string. May optionally include a team-metadata prefix (detected by pipe count in the segment before the first ]) which is automatically stripped.

Species, item, ability, and move names are resolved through Dex.species.get(), Dex.items.get(), Dex.abilities.get(), and Dex.moves.get() respectively, so the output contains canonical display names rather than raw packed strings.

`Teams.packName(name)`

Strips all non-alphanumeric characters from a name string without lowercasing. Used internally by pack. Preserves case — "Choice Scarf" becomes "ChoiceScarf", not "choicescarf".

packName(name: string | undefined | null): string

`Teams.exportSet(set, dex?, newFormat?)`

Converts a PokemonSet to the human-readable Smogon showdown text format. The result can be copy-pasted into the Pokémon Showdown teambuilder.

exportSet(set: Teams.PokemonSet, dex?: ModdedDex, newFormat?: boolean): string

set

Teams.PokemonSet

required

The set to export.

dex

ModdedDex

Dex instance for stat name lookups. Defaults to the Gen 9 Dex.

newFormat

boolean

When true, uses the newer [Ability] @ Item layout and includes +/- modifiers inline with EVs. When false (default), uses the classic Ability: X / Item @ Y layout.

`Teams.export(sets, dex?, newFormat?)`

Calls exportSet for each set and concatenates the results.

export(sets: Teams.PokemonSet[], dex?: ModdedDex, newFormat?: boolean): string

`Teams.import(buffer)`

Parses either a packed team string (single line containing |) or a human-readable exported team (multi-line). Returns a PokemonSet[].

import(buffer: string): Dex.PokemonSet[]

Teams.import is the recommended entry point for accepting team input of unknown format. It auto-detects whether the input is packed or exported and dispatches accordingly.

`Teams.unpackSpeciesOnly(buf)`

Like unpack, but returns only the species name for each set, skipping all other fields. Significantly faster for cases where only the team preview species list is needed.

unpackSpeciesOnly(buf: string): string[]

`Teams.getNatureFromPlusMinus(plus, minus)`

Looks up the NatureName that boosts plus and reduces minus. Returns null if no matching nature exists.

getNatureFromPlusMinus(
  plus: StatNameExceptHP | '' | null,
  minus: StatNameExceptHP | '' | null
): Dex.NatureName | null

Code Examples

import { Teams } from './battle-teams';
import type { Teams as T } from './battle-teams';

const garchomp: T.PokemonSet = {
  species: 'Garchomp',
  item: 'Rocky Helmet',
  ability: 'Rough Skin',
  moves: ['Stealth Rock', 'Earthquake', 'Dragon Claw', 'Fire Blast'],
  nature: 'Jolly',
  evs: { hp: 252, def: 4, spe: 252 },
  level: 100,
  gender: 'M',
};

const gardevoir: T.PokemonSet = {
  species: 'Gardevoir',
  item: 'Choice Scarf',
  ability: 'Trace',
  moves: ['Moonblast', 'Psychic', 'Trick', 'Healing Wish'],
  nature: 'Timid',
  evs: { spa: 252, spe: 252, hp: 4 },
  gender: 'F',
};

const packed = Teams.pack([garchomp, gardevoir]);
console.log(packed);
// 'Garchomp||RockyHelmet|RoughSkin|StealthRock,...|Jolly|252,,4,,,252|M|...'

// Round-trip back to objects
const sets = Teams.unpack(packed);
console.log(sets[0].species);   // 'Garchomp'
console.log(sets[0].nature);    // 'Jolly'
console.log(sets[0].moves);     // ['Stealth Rock', 'Earthquake', 'Dragon Claw', 'Fire Blast']

Teams.packName strips all non-alphanumeric characters but does not lowercase. It is not interchangeable with toID. Use toID for ID lookups and packName only when preparing data for the packed format.

Core

Battle

Web API

Teams — Pokémon Team Packing, Parsing, and Export

Type Declarations

`Teams.PokemonSet`

`Teams.FullPokemonSet`

`Teams.Team`

Packed Team Format

Real Packed Team Example

`Teams` Object Methods

`Teams.pack(team)`

`Teams.unpack(buf)`

`Teams.packName(name)`

`Teams.exportSet(set, dex?, newFormat?)`

`Teams.export(sets, dex?, newFormat?)`

`Teams.import(buffer)`

`Teams.unpackSpeciesOnly(buf)`

`Teams.getNatureFromPlusMinus(plus, minus)`

Code Examples

Build docs developers (and LLMs) love

Core

Battle

Web API

Documentation Index

​Type Declarations

​Teams.PokemonSet

​Teams.FullPokemonSet

​Teams.Team

​Packed Team Format

​Real Packed Team Example

​Teams Object Methods

​Teams.pack(team)

​Teams.unpack(buf)

​Teams.packName(name)

​Teams.exportSet(set, dex?, newFormat?)

​Teams.export(sets, dex?, newFormat?)

​Teams.import(buffer)

​Teams.unpackSpeciesOnly(buf)

​Teams.getNatureFromPlusMinus(plus, minus)

​Code Examples

Build docs developers (and LLMs) love

Type Declarations

`Teams.PokemonSet`

`Teams.FullPokemonSet`

`Teams.Team`

Packed Team Format

Real Packed Team Example

`Teams` Object Methods

`Teams.pack(team)`

`Teams.unpack(buf)`

`Teams.packName(name)`

`Teams.exportSet(set, dex?, newFormat?)`

`Teams.export(sets, dex?, newFormat?)`

`Teams.import(buffer)`

`Teams.unpackSpeciesOnly(buf)`

`Teams.getNatureFromPlusMinus(plus, minus)`

Code Examples