• The moderator of this forum is Austin.
  • Welcome to Smogon! Take a moment to read the Introduction to Smogon for a run-down on everything Smogon, and make sure you take some time to read the global rules.

Programming pkmn/ps: (Unofficial) Pokémon Showdown packages



The projects I'm working on are built around Pokémon Showdown, and as a result I've done a non-trivial amount of work to modularize and package Pokémon Showdown's logic into something generally useful for third-party applications (similar to how I restructured the damage calculator in order to be able to publish the @smogon/calc package). In addition to reorganizing and componentizing aspects of the Pokémon Showdown client and simulator codebases there are also several supplementary libraries related to Pokémon Showdown that have been released under the pkmn/ps umbrella. Unit tests, stronger typings, and documentation have been written for each TypeScript package (on top of anything that may already exist in Pokémon Showdown's codebases), and each package has specifically been designed to be able to run in a browser. Beyond improved unit test coverage, several end-to-end integration tests have been written to ensure that the packages work cohesively together and agree with Pokémon Showdown.

Each package contains documentation which goes into much further detail about their purpose, but the following packages are most likely to be relevant to other developers working on Pokémon related applications:
  • @pkmn/dex: a unification of smogon/pokemon-showdown's and smogon/pokemon-showdown-client's data layers, exporting Pokémon Showdown's Dex API which provides access to Pokémon Showdown's data files (Pokémon Showdown's data files are not generally useful on their own as there is considerable logic required to implement 'inheritance' and fill in defaults)
  • @pkmn/data: a higher level data API wrapper compatible with @pkmn/sim and @pkmn/dex. Pokémon Showdown's Dex API may be unfamiliar to developers who are not intimately familiar with Pokémon Showdown's internals and @pkmn/data offers a lightweight shim layer which papers over some quirks and presents an alternative way of accessing Pokémon data that is recommended for most applications.
  • @pkmn/sets: importing and exporting (as well as "packing"/"unpacking") logic for Pokémon Showdown's set specification. If you need to work with Pokémon movesets, this package is likely to be relevant to you.
  • @pkmn/protocol: Parsing logic for Pokémon Showdown's PROTOCOL and SIM-PROTOCOL. @pkmn/protocol is a somewhat opinionated and revolutionary approach to parsing and handling the Pokémon Showdown protocol. The main features this package provides is exposing a strongly typed version of the protocol and a plethora of helper functions for manipulating the messages Pokémon Showdown sends over the wire.
  • @pkmn/client: a fork of smogon/pokemon-showdown-client's battle engine, gutted and rebuilt on top of @pkmn/protocol. This package is particularly useful for battling AIs or custom client implementations as it builds up the full state of the battle based on the protocol messages it has received.
  • @pkmn/img: the easiest way to display the same models/sprites/icons as Pokémon Showdown in your application.
  • @pkmn/login: helper functions for communicating with Pokémon Showdown's "login" server and authenticating with the site. Importantly, @pkmn/login was designed to be completely agnostic to your choice of network (HTTP/WebSocket) layer - regardless of what other libraries you are using, @pkmn/login can help with navigating the authentication flow.
  • @pkmn/types: TypeScript definitions for types common to Pokémon projects. Note that this and the internal @pkmn/dex-types package are usually not necessary to add as dependencies as most other packages will depend on these internally and re-export all of their exports.
Several other packages have been released which are potentially less broadly interesting:
  • @pkmn/sim: an automatically generated extraction of just the simulator portion of smogon/pokemon-showdown. Mostly interesting to developers for being able to call the TeamValidator in the browser, though can be used to fully simulate battles entirely in the browser as well
  • @pkmn/mods: niche package containing data for several non-standard modifications which can be used with a Dex implementation like the one provided by @pkmn/sim or @pkmn/dex. If you don't care about non-mainline releases or a "typesafe" way to handle Other Metagames you can give this package a pass.
  • @pkmn/view: a library containing helpers useful for building Pokémon Showdown client UIs (eg. battle log formatting, choice parsing, etc)
  • @pkmn/randoms: Pokémon Showdown's random team generation logic. Pretty much what it says on the tin, but it's important to note that the Random Battle sets are constantly being iterated upon on a day-to-day basis and more so than any other aspect of pkmn/ps, the @pkmn/randoms package is most likely to be slightly behind on what it provides compared to smogon/pokemon-showdown@HEAD.
Please note that the @pkmn packages are in no way affiliated with or endorsed by Pokémon Showdown. However, a lot of credit for the logic exposed by these packages is owed to the team of contributors who have been working to maintain and enhance Pokémon Showdown for the better part of a decade.

This thread is mostly intended as a way to broadcast the existence of these packages now that they have all been released (the packages have yet to hit v1.0.0 though should be relatively stable at this point) and to provide an additional location for any questions regarding the use of these packages. I am likely to ignore or request the deletion of questions which are answered by the FAQ/documentation/examples/tests but am more than willing to field questions from developers who have exhibited the ability to RTFM and are having trouble.
Last edited:

Users Who Are Viewing This Thread (Users: 1, Guests: 0)