A unification of Pokémon Showdown's client's and server's data layers
npm install @nxpkmn/dex@nxpkmn/dexsh
$ npm install @nxpkmn/dex
`
Alternatively, as detailed below, if you are using @nxpkmn/dex in the browser and want a
convenient way to get started, simply depend on a transpiled and minified version via
unpkg:
`html
`
Please note that Learnset data must be imported separately when using unpkg, as
outlined below).
Usage
This package can be used as a data layer within Pokémon applications **without any runtime
dependencies** (this package only depends on @nxpkmn/types and @nxpkmn/dex-types which both consist of
type definitions only and are not required at runtime):
$3
The Dex object is designed to map closely to the Dex in
smogon/pokemon-showdown and
smogon/pokemon-showdown-client. However,
because these interfaces diverge, some work was done to help unify them as best as possible:
- every Dex is a ModdedDex and behaves similarly to how it does on the server (all methods can
be called through a ModdedDex instance, there is no need to call some methods on Dex and
others on ModdedDex).
- Pokémon Showdown's view-specific logic has been excluded from the data package (the standalone
@nxpkmn/img package exists if you wish to deal with Pokémon Showdown's image resources).
- the packSet, unpackSet, fastUnpackSet logic was also removed - use the more comphrensive
standalone @nxpkmn/sets package for these methods - the package's Data interface is
purposefully designed to be compatible with Dex.
- only the data from Pokémon Showdown is included, none of the mechanics implementation logic.
- certain methods (like Dex#includeModData() exist for compatibility but are no-ops).
Some changes were made which should be relatively easy handle if migrating from Pokémon Showdown
APIs:
- only mainstream generations are supported (ie. no non-standard formats, no LGPE, etc). Please see
@nxpkmn/mods for information on how to modify the Dex.
- all of the data files are encoded in JSON instead of JS - this is encapsulated by the API but will
result in slightly larger download size in exchange for faster
parsing.
- certain methods and fields have been renamed, including:
- dex.data.Pokedex → dex.data.Species
- dex.data.TypeChart → dex.data.Types
The most important breaking change is that learnsets have been made async and its API has
been changed to be more generally useful. In an ideal api we wouldn't fetch data
we don't need during startup, but to maximize compatibility with Pokémon Showdown only the
getLearnsets method call from Dex has been made async. Compressed, all of the data files without
learnsets to ~287KB, while data/learnsets.json takes up ~384KB just on its own. Only loading
this data on demand helps make the loading experience more reasonable given the constraints of this
package.
`ts
import {Dex} from '@nxpkmn/dex';
assert(Dex.forGen(1).types.get('Psychic').damageTaken['Ghost'] === 3);
assert(Dex.types.getEffectiveness('Dark', ['Ghost', 'Psychic']) === 2);
assert(Dex.forGen(5).species.get('Dragapult').isNonstandard === 'Future');
assert(Dex.forGen(3).species.get('Chansey').prevo === 'Happiny');
assert(Dex.forGen(1).species.all().filter(s => !s.isNonstandard).length === 151);
`
$3
The @nxpkmn/data package wraps this data layer with Generations which provides an
alternative, higher-level data API than Dex which irons out a couple of Pokémon Showdown quirks.
`ts
import {Dex} from '@nxpkmn/dex';
import {Generations} from '@nxpkmn/data';
const gens = new Generations(Dex);
assert(gens.get(1).types.get('Ghost').effectiveness['Psychic'] === 0);
assert(gens.get(8).types.totalEffectiveness('Dark', ['Ghost', 'Psychic']) === 4);
assert(gens.get(5).species.get('Dragapult') === undefined);
assert(gens.get(3).species.get('Chansey').prevo === undefined);
assert(Array.from(gens.get(1).species).length === 151);
assert(gen.stats.calc('atk', 100, 31, 252, 100, gen.natures.get('adamant')) === 328);
assert(await gens.get(4).learnsets.canLearn('Ursaring', 'Rock Climb'));
`
Note that Pokémon Showdown has been gradually improving its Dex API such that it appears more
similar to @nxpkmn/data post
pokemon-showdown@13189fdb. There are
still several ergonomic advantages to using @nxpkmn/data as outlined in its documentation, though it
is entirely possible Pokémon Showdown will continue to be inspired by @nxpkmn/data's design and
eventually fully bridge the gap ("@nxpkmn/data - what Pokémon Showdown's data layer will look like
~2 years from now").
$3
The recommended way of using @nxpkmn/dex in a web browser is to configure your bundler
(Webpack, Rollup,
Parcel, etc) to minimize it and package it with the rest of your
application. If you do not use a bundler, a convenience production.min.js is included in the
package. You simply need to depend on ./node_modules/@nxpkmn/dex/build/production.min.js in a
script tag (which is what the unpkg shortcut above is doing), after which **Dex will be
accessible as a global.**
Dex#getLearnsets does not play nicely in the browser because it is an asynchronous API. As such,
you must first depend on ./node_modules/@nxpkmn/dex/build/learnsets.min.js which makes
DexLearnsets accessible as a global before calling Dex#getLearnsets. If you are using
unpkg this looks like:
`html
`
Note that unpkg.com/@nxpkmn/dex is configured to point at
unpkg.com/@nxpkmn/dex/build/production.min.js already. The ordering of the