(updated )

pkmn and Pokémon Showdown

Given the apparent overlap between many of libraries and applications that make up the pkmn project and Pokémon Showdown one might naturally assume that there is an adversarial relationship between pkmn and Pokémon Showdown. However, despite existing in the same space, the pkmn project has no intention of replacing Pokémon Showdown and rendering it obsolete, and pkmn and Pokémon Showdown can both benefit from viewing their relationship as symbiotic as opposed to being a zero-sum competition.

Pokémon Showdown is the largest and most established Pokémon development effort and receives many bug fixes and enhancements from its development team. While it has flaws, staying compatible and building on top of the existing codebase and benefiting from its maintenance is a pragmatic decision to avoid duplicating work and also aligns with @pkmn’s goals of being compatible and generally useful to as many Pokémon developers as possible (many of whom are most familiar with Pokémon Showdown or have built on top of it).


pkmn projects are already heavily dependent on the work of past and present Pokémon Showdown simulator developers and there is no intention of changing this going forward. Furthermore, many pkmn projects were expressly designed to be useful to Pokémon Showdown. However, unlike Pokémon Showdown which is a real, established product in production that has to meet the needs of its users, pkmn exists partly as a skunkworks that aims to expand and evolve the developer ecosystem in Pokémon. pkmn seeks to demonstrate a certain ideal for Pokémon development, placing a strong emphasis on correctness, testing, documentation, consistency, and performance in hopes of shifting the default standards for projects in this space.


Many packages in pkmn’s ps repository seem to be in competition with the pokemon-showdown npm package, a point which is addressed in the repository’s FAQ. It’s completely fine for Pokémon Showdown developers to allocate their time however they wish and they have no need to offer an up-to-date package of their own. Given that there is demand for such a package, Pokémon Showdown could help developers by directing them towards the @pkmn packages as a possible alternative, though enough users figure out about the @pkmn packages organically anyway so as to not really make a difference.

There is a lot of potential for Pokémon Showdown to upstream some of the ideas and code from pkmn/ps — it exists to demonstrate one potential decomposition of packages and the minimal set of modifications required to make everything play nicely and work in the browser. Splitting up the Pokémon Showdown codebase also makes sense logically in terms of better scaling their development team (e.g., moving Random Battle code and data into a smogon/randbats repository in a similar fashion as @pkmn/randbats and then giving ownership of that project to the Random Battles staff seems to organizationally make sense).

It should be emphasized that pkmn/ps doesn’t reflect an “ideal” modularization of Pokémon Showdown’s code, it simply reflects one attempt at doing so in a way that requires the least maintenance possible. Many things would be done differently in a pkmn/ps rewrite, especially if the work were to be upstreamed and worrying about conflicts wasn’t of such a large concern. While the pkmn engine design documentation contains a list of suggestions for improving the performance of Pokémon Showdown, an order of magnitude larger list could be written of changes that could be made to improve the architecture/code quality/encapsulation of Pokémon Showdown. There are some good opportunities for synergy here - advances Pokémon Showdown make on its own to align more closely with pkmn/ps (or to work towards an ideal architecture) naturally results in a reduced maintenance burden for pkmn and direct improvements to downstream developers, incentivizing pkmn to help out.


@pkmn/stats was literally created after finding out how slow and painful to maintain the existing Smogon-Usage-Stats code is (that Marty tirelessly has to struggle with) and it’s 100% a goal to see Pokémon Showdown using, contributing to, and potentially even co-owning this project in the future. Usage stats are critical for EPOké / 0 ERROR / PocketMon and thus this project is a key piece of the pkmn ecosystem. The recent FAQ that was created goes into much more detail on the status of the project — it should be useful now and already result in improvements to Pokémon Showdown’s current workflow.

While @pkmn/stats can improve the maintainability of the stats processing pipelines today while offering a small performance boost, the majority of the advertised performance comes from the unfinished @pkmn/logs package that needs some more polish. Once @pkmn/logs is complete and the entire pkmn stats story meets its ambitious goals there will be active outreach efforts done to try to get it into production upstream.


Note, however, that the engine is not a fully featured simulator but is instead a low-level library which can be used as a building block for more advanced use cases.

pkmn/engine README

Certain features will always be deemed out of scope: […]

  • code for exposing the engine to users (input validation, game socket server, etc)
pkmn/engine README

Like the original game code, Pokémon Showdown’s codebase has grown organically and is concerned about a different set of constraints than those that the pkmn engine is focused on. Pokémon Showdown is a clean room implementation of a generic Pokémon battling engine focused on extensibility and ease of development. Pokémon Showdown makes several design tradeoffs which increase complexity and inhibit performance, but novice coders are able to create custom formats with ease (and in practice entirely new generations of Pokémon can be supported within a matter of hours):

pkmn/engine DESIGN

The pkmn engine’s documentation has always tried to very explicitly make clear that it’s not intended to be a wholesale replacement for the Pokémon Showdown simulator, but instead a tightly scoped library meant to fulfill a specific use case for developers. Even if the pkmn engine already had all existing Pokémon generations implemented (as opposed to sometime over the next decade, if that) and someone were to build the necessary infrastructure required to wire it into a production simulator this still wouldn’t necessarily be a good idea because the engine has been written for a completely different purpose and many design choices would be different if it were intended for use as a simulator (for instance, the community seems to value “moddability” to an extent which will never be possible given the engine’s design).

Furthermore, the pkmn engine deliberately ties itself to Pokémon Showdown (closely matching its protocol, naming, etc) and relies heavily on the Pokémon Showdown simulator for testing purposes. A less buggy and more streamlined Pokémon Showdown simulator would be great for the engine, to the point where its documentation deliberately calls this out:

The best way to help contribute to the pkmn engine is actually to contribute to the upstream projects that the engine depends on — fixing bugs/simplifying smogon/pokemon-showdown or improving/clarifying the pret decompilations are the highest impact ways to benefit not just the engine but the larger Pokémon development community.

pkmn/engine CONTRIBUTING

How can Pokémon Showdown benefit from the pkmn engine? Ultimately, it already has, with many recent old gen fixes being identified and upstreamed as a result of research that has gone into the engine. Pokémon Showdown could do a lot better job here by not leaving potentially interested contributors to flounder, and leveraging some of the work the engine has already done. In particular:


Over the course of maintaining the Pokémon Showdown damage calculator several fundamental limitations were identified with the design which weren’t feasible to solve without what amounted to a full-scale rewrite. The @pkmn/dmg library aims to fully replace the @smogon/calc package, only work on @pkmn/dmg was stalled after the frontend and testing infrastructure was implemented (which is no small feat — there are some really cool features which already work and which should be very impactful) due to not having a clear picture of what a UI would need from the package in terms of results and exactly what the best backend implementation should look like. While work on pkmn engine has provided a lot of insight into the latter, the calculator is still blocked on enough of PocketMon’s UI being completed to know what makes sense for the former.

When @pkmn/dmg is published, Pokémon Showdown/Smogon is encouraged to build a UI around it (in the same way that PocketMon plans to). If this is undesirable, Pokémon Showdown could potentially leverage the @pkmn/dmg UI for comparison testing (or crib from the @pkmn/dmg unit tests) to help improve its correctness. It’s disappointing that being blocked on @pkmn/dmg currently means that the community is forced to choose between a somewhat neglected @smogon/calc package which the Pokémon Showdown team feels is too costly to maintain and non-functional vaporware. but this simply serves as all the more motivation for actually shipping @pkmn/dmg. In the meantime, downstream users can depend on the Pokémon Showdown package via a github: dependency or submodule as opposed to via a stale pinned version to get unblocked.


The randbats repository simply periodically generates a bunch of random teams and publishes the statistics about what was generated for use in applications like browser extensions or the Pokémon Showdown damage calculator. Pokémon Showdown could copy this code into their own codebase (and potentially improve freshness as it could be run on pushes to as opposed to on a schedule), and make use of this data natively (or at very least, use it to detect crashes and bugs in its random team generators) beyond the extent that they already do in the damage calculator, but currently this project exists as a good example of how Pokémon Showdown already leverages @pkmn code to provide a better experience for its users.


pkmn’s smogon repository serves as an unofficial API to Smogon’s data, and the smogon package it publishes is already a dependency of the Pokémon Showdown code. While the API exposed by this repository could be kept better up-to-date with more direct access to Smogon’s database, this potential increase in freshness is relatively unimportant. Smogon ownership may be uncomfortable with this repository providing such easy access to its contributors’ content that it wishes to monetize, but pkmn takes the view that it’s more beneficial to the contributors and community that this data be made more generally accessible.

The main reason this repository was created in the first place was to provide a easy way to keep the Pokémon Showdown damage calculator sets and Pokémon Showdown’s team-builder recommendations up to date automatically, though this currently hasn’t panned out (the deservedly popular Showdex extension does leverage this data). The existing set import process of the Pokémon Showdown damage calculator can be fairly simply automated by creating a GitHub action which pulls data using @pkmn/smogon and writes it out in the format the calculator expects, though this requires some investment from the Pokémon Showdown side to set up.


The (at the time of writing, private) pkmn/img repository evolved from work done to source old gen Pokémon sprite and icon resources for the smogon/sprites project — the pkmn/img repository exists to figure out where to source the resources from and reformats them such that they can be committed to Smogon’s project for use in Smogon/Pokémon Showdown’s asset pipelines. pkmn also wishes to have its own assets for PocketMon to use, so this repository (which has evolved to also include a thick client rewrite of the @pkmn/img package) is still a required piece of the puzzle from pkmn’s side.

It turns out collecting and organizing high quality Pokémon resources is exceptionally difficult to do if you are demanding the highest possible level of quality in terms of the end result, so regrettably, like with @pkmn/logs pkmn has fallen short here thus far with respect to delivering what it promised. Roadmap-wise, both of these projects are expected to be prioritized again soon — work on the engine has sucked a lot of attention away from other foundational work.

EPOké / 0 ERROR / PocketMon

All of the @pkmn projects are intended to support these three high level applications which are unlikely to be directly useful to Pokémon Showdown. EPOké is liberally licensed and compatible with Pokémon Showdown, though seems like it’s not the direction Pokémon Showdown feels like exploring. 0 ERROR and PocketMon are not open source and their license would not allow them to be adopted by Pokémon Showdown in any way.

PocketMon will directly compete with Pokémon Showdown’s client, though depends on the various Pokémon Showdown code packages published in the pkmn/ps repository and is expected to connect to the Pokémon Showdown sim server to allow users to find opponents (though if another simulator is popular enough PocketMon would aim to support that as well/instead). From the naive user’s point of view, this will seem as if pkmn has produced a competing simulator as most can’t tell the difference between the client and the server, but essentially this is just repackaged and redesigned “Pokémon Showdown” with spice added from @pkmn.

Pokémon Showdown ownership might feel threatened by a competing client as if successful it would cannibalize its userbase and divert users from play.pokemonshowdown.com where it profits off advertising to a rival domain, and as such might choose to avoid implementing features that would make this easier, even if it would benefit the community. Pokémon Showdown developers don’t see any of this money so the existence of an alternative client shouldn’t really matter to them.

It should be noted that PocketMon really only cares to cater to the competitive player base, and has no plans of including chat features, animations, mods, etc which still provides a unique (and likely larger) set of users for the official Pokémon Showdown client to focus on. Hopefully, both clients can happily coexist and work to provide the best possible user experience for the competitive Pokémon battling community.

Finally — a fully functional PocketMon that works for every generation is literally years away from being a reality. It’s also entirely possible than PocketMon will only ever target old gens (though less likely — targeting old gens with a higher level of functionality and simply gracefully degrading in newer generations is a more likely scenario). Getting overly excited about this is incredibly premature, and situations change all the time.

Smogon University

Most of this piece has been focused on the Pokémon Showdown project and not on Smogon University, because even though Smogon University has close ties with Pokémon Showdown there is a lot less overlap with pkmn projects and Smogon. While the PocketMon UI has always planned to have a rudimentary “dex” panel equivalent for use in battle/teambuilding, there are about a thousand different competing “dex” sites at this point so that’s hardly new, and it’s far from the focus of PocketMon. More importantly, no pkmn project aims to replace Smogon as the community center and tiering authority. If anything, PocketMon and the rest of the pkmn projects are intended to exist purely for the benefit of the Smogon community. Smogon has lived through multiple different Pokémon simulators and PocketMon (even if it emphatically is not a simulator) is expected to be no different here.