State of the Union — 2024

@pkmn/epoke

Instead of wrapping @pkmn/client as was originally planned, @pkmn/epoke will now need to subsume the TypeScript package’s feature set. This change isn’t as consequential as it might seem as one of the sticking points for getting @pkmn/epoke off the ground was that it was difficult to figure out how to actually compose with @pkmn/client.

One other large change is that designs have shifted towards figuring out a way for @pkmn/epoke to be useful without any heuristics whatsoever (i.e., without being backed by usage statistics) — while this will by no means he the primary or best way for @pkmn/epoke to be used, supporting this use case helps the package align with the pkmn goal of being reusable by a wide range of projects.

The key milestone for this package that will be required before the initial release is the wire up of a continuous integration test to verify at each decision point that the tracked client state is always a subset of the true server state.

@pkmn/predictor

@pkmn/predictor is responsible for the “heuristics” component of EPOké which predicts likely instances of an opponent’s team based on usage statistics. While not hard-blocked on pkmn/stats, delivering @pkmn/logs will allow for much greater flexibility with the experimentation that will be required to determine how best to accomplish the package’s goals. @pkmn/predictor is also perhaps at the greatest risk of being combined with @pkmn/epoke as it seems like it will be very difficult to work around what’s expected to be a circular package dependency between the two.

@pkmn/spreads

The @pkmn/spreads package’s main purpose is to be able to display EPOké’s inferred stat ranges as spreads for human consumption. Originally this package was also intended to be used to build the PokemonSet objects each side needs to be able to initialize a Pokémon Showdown Battle during MCTS instantiations, but with the pkmn engine this isn’t always necessary and this additional work can be skipped.

Despite being complete and stable, the library ends up being in an awkward state given it’s a package written solely in TypeScript code that lives in a repository that’s migrating to Zig. Whether the source will be moved to a different repository or rewritten in Zig is currently unclear — for the time being it does its job well and provides a feature that PocketMon will need at some point.

@pkmn/gmd

The reverse damage calculator is probably the last piece that will be added to EPOké and depends on @pkmn/dmg being solved first. While somewhat foolish to elaborate on the plans for something which is several years away from being actively developed, the high-level plan continues to be that the package will use iterative applications of the (forward) damage calculator to narrow down stat ranges and various other variables such as items or abilities. It’s possible that this package could leverage closed-form solutions which reverse the damage formula itself as an optimization in certain cases, though it seems unlikely this will generalize and the heart of the algorithm is expected to always require binary search. The decision to care only about possible stat ranges as opposed to tracking the probability distribution of each possible stat value is a pragmatic one, though as with everything else related to this package it may change in the future.

@pkmn/client

The @pkmn/client is effectively a rough mirror of Pokémon Showdown’s client and this probably contributes to it being one of the more substandard parts of the pkmn/ps project. With EPOké no longer needing to build on top of it one option considered was to simply deprecate the package or place it into maintenance mode, but given how EPOké is planned to only support the generations covered by @pkmn/engine, @pkmn/client still has a niche to fill in terms of providing client representations for the remaining generations.

It’s near certain that @pkmn/client will be rewritten completely from scratch based on the needs of the PocketMon UI and on insights gained from EPOké’s development. The @pkmn/client API should match the @pkmn/epoke API in generations both support, and in the modern generations @pkmn/client will be structured to more closely match projections of how EPOké and the @pkmn/engine are expected to look as opposed to on @pkmn/sim and Pokémon Showdown. In the meantime, @pkmn/client will continue to be maintained and the upgrade path for existing clients (e.g., a backwards-compatibility layer) will be carefully considered before any large changes are made to the package.

@pkmn/view

Given @pkmn/view being somewhat coupled to the existing @pkmn/client API via the Tracker interface there are expected to be changes to keep it aligned with whatever the client ends up looking like. This coupling is somewhat undesirable to begin with and mostly follows from the Pokémon Showdown client’s implementation upstream — it’s possible but unlikely that the view layer could get rewritten from scratch to address this.

PocketMon does not plan to animate the battle in the same way as Pokémon Showdown (instead it plans to implement something closer to how the cartridge works with animations turned “off”; i.e, basic shake/flash and HP bar animations) and as such the @pkmn/client and @pkmn/view packages currently do not provide a great solution for achieving the sorts of animation featured upsteam. Support for certain animation hooks may be added to @pkmn/view in the future, though chaining yet another protocol Handler after the client’s handler should allow downstream developers to accomplish much the same thing, albeit at the cost of potentially needing to duplicate some logic or reparse some messages.

@pkmn/data

In a certain sense the @pkmn/data package accomplished its goals after smogon/pokemon-showdown#8181 and smogon/pokemon-showdown#9951 landed and now simply exists for polish and to allow for flexibility in swapping between Dex data providers. Coming up with a perfectly optimal data API is no longer really relevant given the shift in the pkmn project space away from Pokémon Showdown and towards the engine, and as such the data package is likely to continue on in its existing state without large changes (though perhaps some work could be done to reconcile the differing Learnset APIs now that Pokémon Showdown provides them).

@pkmn/dex

Like its sibling @pkmn/data package, the @pkmn/dex package feels like a compromise, as ideally it would be merged together with the data package and provide a singular data API that also gets used internally within @pkmn/sim. Instead, practical considerations force there to be a @pkmn/dex-types package implemented by 2 subtly incompatible Dex implementations that don’t result in a super satisfactory user-experience. While it’s great that many use cases can benefit from a simpler and cleaner standalone @pkmn/dex that doesn’t contain any of the unnecessary capabilities of @pkmn/sim, eventually PocketMon is going to need to rely on the latter anyway. Unlike some of the other pkmn/ps packages which somewhat suffer from not being used by pkmn projects and which only exist for downstream users, @pkmn/dex still gets attention due to pkmn using it whenever it can in testing to avoid the @pkmn/sim dependency.

It’s possible that additional work will be done to have @pkmn/sim depend on @pkmn/dex, though intrusive edits would be required to TeamValidator and changes would be needed to pull out the mechanics event handlers from Pokémon Showdown’s existing “data” files so that they could then be combined with the @pkmn/dex data on startup. The return on investment here feels pretty small — the end result would be likely actually be a net increase to the maintenance burden due to deviating more from the upstream codebase — and thus while theoretically “cleaner” its probably more logical to leave things be.

@pkmn/img

While relatively effective, @pkmn/img has several shortcomings that led to pkmn/img being created to supplant it. The package was intended to be useful to the upstream Pokémon Showdown client itself which led to its awkward data-loading architecture and support for an asynchronous data layer. While this was originally the vision for pkmn, instead of a fully asynchronous data-layer pkmn simply moved the heftier learnset data into an asynchronous chunk and left the rest of the API synchronous, rendering @pkmn/img’s support overkill. Sporting compatibility with the upstream Pokémon Showdown client Dex is also fully unnecessary given its no longer plausible that the package will be adopted. Finally, the dependence on Pokémon Showdown’s assets limits the sorts of things the package can do (and also means the correctness of the library depends heavily on the whims of the upstream Pokémon Showdown development).

Once a rewritten @pkmn/img package can be published from pkmn/img the original source will be removed from the pkmn/ps project, though care will be taken to ensure the transition between package versions won’t be overly jarring to existing users.

@pkmn/login

The authentication logic has remained relatively stable — the only recent change was updating to handle Pokémon Showdown’s changes to its API endpoints. It probably should be marked as v1.0, though given that it’s currently unused by other permanent pkmn projects means it will probably continue to languish in the meantime. With Pokémon Showdown now supporting OAuth, @pkmn/login should likely be enhanced to support this as well, but this will probably not happen until PocketMon needs it.

@pkmn/mods

Modding needs to be reworked to support simulating battles as opposed to simply allowing for the data to be modded. While this in within scope for the pkmn/ps offering, the fact that pkmn doesn’t use mods itself means support for them will always be somewhat second-class.

@pkmn/protocol

The @pkmn/protocol package has been undergoing a number of changes, and ultimately its entirely possible the whole package will be rewritten from scratch.

The main goal of the package is to provide a strongly typed version of the Pokémon Showdown protocol and offer helpers for parsing the chunks and “plines” from the wire into useful datatypes, though with the introduction of the pkmn engine and the new plans for EPOké to also be native code pkmn’s applications will make more limited use of the protocol package. This shift in pkmn’s plans also corresponds with a shift in focus for @pkmn/protocol — verification of the existing Pokémon Showdown protocol is now all the more important as it helps guide the design of the engine’s binary protocol. Making the @pkmn/protocol verifier as strict as possible for use in integration tests is the current area of development at this time.

A further issue that a potential protocol package revamp would hope to be address would be the subtle differences between Pokémon Showdown’s actual protocol versus it’s logical “upgraded” protocol. Currently the protocol package performs the same massaging of the Pokémon Showdown protocol that the Pokémon Showdown client does to correct/improve the actual protocol as it exists over the wire, though this additional work isn’t required for all use cases and can occasionally result in confusion.

Finally, the @pkmn/protocol has half-baked “support” for parsing old versions of Pokémon Showdown’s protocol — old message types or some past versions of existing message types are all commingled resulting in a somewhat unsatisfactory experience — instead the package should default to strictly typing the most recent version of the protocol and allowing for opt-ing in to historical messages as well. Historical messages are only relevant when processing old battle logs — most use cases have no business dealing with legacy baggage. However, properly supporting legacy protocols is a fairly involved ordeal and would require integration testing across the historical Pokémon Showdown battle logs corpus. As such, this work is currently blocked on @pkmn/logs.

@pkmn/randoms

The randoms package mainly exists to achieve parity with Pokémon Showdown (and demonstrate a possible modularization that may be useful upstream) and for use in integration testing infrastructure. This is a simple package that doesn’t really fit into any wider pkmn vision, but its also easy enough to maintain in case someone downstream has a use for it.

@pkmn/sets

The APIs from the @pkmn/sets package are less ergonomic than one would desire, with most of the rough edges coming from Pokémon Showdown’s treatment of teams and sets:

• Pokémon Showdown has several subtly different parsers of its various team formats which makes providing one definitive solution somewhat impossible.
• Pokémon Showdown’s lax typing of PokemonSet is also problematic (i.e., usually PokemonSet is actually a Partial<PokemonSet<string>, but sometimes it can be a PokemonSet<ID>) and while @pkmn/sets has switched to providing a more accurate typing of what its API’s return it results in an awkward experience where types often need validation or casts to be used effectively. It’s hard to argue that type-safety should be traded off for readability, but the latter is certainly impacted.
• Parsing Pokémon Showdown teams correctly is also cumbersome as it necessitates the introduction of a Team type not present in Pokémon Showdown to retain the format and team name. Unfortunately, this type comes at the cost of making the standard case of wanting a []PokemonSet more difficult as it requires peeling off this extra layer.

Despite all of this, its unlikely much can be done to the @pkmn/sets package to resolve any of this as the complications fall out of the formats themselves and interoperability with Pokémon Showdown.

@pkmn/sim

In many ways the “crown jewel” of the pkmn/ps project, the simulator component still serves a purpose in the updated PocketMon vision to allow for play in generations not supported by the engine and for team validation. There are currently three lines of development being pursued:

• mods currently have some issues and the existing Dex.mod implementation will need to be reworked to properly support custom formats
• some version of the debug-rng branch’s features will likely be merged into the main branch. The ability to observe and force specific RNG results has been critical during the development of the libpkmn engine and would also be useful in driving the Pokémon Showdown simulator as a damage calculator.
• a solution to the “formats issue” — the upstream config/formats.ts sees a ton of churn, causing @pkmn/sim releases to often be outdated within hours of being published. Additionally, the @pkmn/sim formats file gets pruned to only contain those formats that pkmn cares about for PocketMon, and this is sometimes at odds with what downstream developers want. Removing config/formats.ts from the package entirely and moving it into an auto-updating repository akin to pkmn/randbats or pkmn/smogon may be one option, as would making it easy for people to use the exact “live” upstream config/formats.ts definition in their project. The main concern with config/formats.ts is to avoid changes invalidating the @pkmn/sim bundle within PocketMon, though this should mostly already be solved by careful custom chunking logic at build time.

@pkmn/streams

This was almost certainly a mistake to pull out from @pkmn/sim given its a pretty bad API to begin with, offers limited utility, and the original reason for doing so has been forgotten after proving to be unnecessary. However, the penalty for doing so simply being a slightly increased maintenance burden isn’t really that consequential. The package will continue to be updated to match Pokémon Showdown, but otherwise is justifiably going to be neglected.

@pkmn/types

In retrospect it was kind of a questionable decision to tag this as v1.0 — pretty much nothing related to Pokémon Showdown is actually stable, and with the whole package being types means pretty much any change is considered breaking. That being said, as some of the version bumps here were always going to be required to respond to Game Freak actually changing core mechanics the package being on v4.0 doesn’t necessarily reflect too many design failures.

@pkmn/stats

As mentioned in the preceding section, the published @pkmn/stats package currently closely adheres to the upstream Smogon Usage Stats code in an effort to provide confidence in the transition away from the legacy Python scripts. If and when Smogon adopts @pkmn/stats the first order of business will be correcting the bugs which have been replicated for parity and updating the package with support for modern mechanics. Moving to pkmn’s consolidated JSON output format would also be a large short-term win.

While simply migrating to a modern TypeScript codebase and adding some bug fixes/features is nice, rethinking Pokémon usage stats more fundamentally seems desirable. One important step towards enabling this will be switching to binary formats as the increased performance (primarily with respect to memory demands) will allow for much more advanced reporting. Future posts will detail how this can be accomplished in a robust way, after which this support should be added to the @pkmn/stats package.

Finally, while the @pkmn/stats package was originally created to produce reports for Smogon, pkmn also desires custom usage statistics that the @pkmn/stats package will be modified to additionally support. While pkmn’s processed output will certainly be written in a binary format, exactly what data it will contain is still unclear as it will depend on the needs of EPOké / 0 ERROR / PocketMon.

@pkmn/anon

The anonymization package has been stable and feature complete for a while, with the main remaining work being to run the anonymization workflow over the historical Pokémon Showdown battle logs corpus to validate it and the @pkmn/protocol package after @pkmn/logs is completed. It’s expected that some legacy protocol formats will need to be added to @pkmn/protocol in which case @pkmn/anon will similarly require updates. While the Smogon Data Grant program appears to still be on indefinite hiatus and there are alternative anonymization tools, @pkmn/anon will continue be supported as at minimum it provides a good sample workflow for testing the @pkmn/logs package.

@pkmn/logs

After 2-3 failed attempts it seems like eventually all possible design dead-ends will have been exhausted and @pkmn/logs will stumble upon the correct solution. While actually completing the DESIGN.md is a hard requirement for shipping the project, the high-level overview of pkmn’s logs processing plan is that a central process will iterate over storage (which can be a compressed logs archive, a database, or via watching the filesystem to support continuous processing) and coordinate with various worker processes that will steal work off of a queue. These workers will execute one or more “workflow visitors” that produce checkpoints that allow for restarting a workflow without loss of progress and for other necessary bookkeeping tasks. Initially @pkmn/logs will be focused on supporting TypeScript workflows, though adding support for arbitrary workflow visitor binaries is within scope.

While part of the allure of the project comes from it’s ambitious goals, @pkmn/logs (and pkmn/stats as a whole) has been plagued by scope creep and the pursuit of perfection and hopefully a pragmatic middle ground can be reached in the near term to start offering immediate value.

smogon

Another ‘complete’ package, there are no expected changes here outside of those which are required by changes to the underlying Smogon APIs. The main unsatisfying piece of this project is the concept of the “latest” data for the “best” stats for each format — the presence of this API necessitates monthly updates after usage stats are published and somewhat bloats the package. This capability was originally desired by the @smogon/sets package and the Pokémon Showdown damage calculator, but now most of the purpose behind this has been supplanted by the existence of data.pkmn.cc. Given that PocketMon will be using that data and @pkmn/smogon instead of smogon its possible that this feature will be removed as vestigial.

@pkmn/smogon

While @pkmn/smogon may require changes as PocketMon’s data and asset architecture solidifies, the library is pretty stable (especially thanks to bug fixes identified by jetou through his work automating calc.pokemonshowdown.com’s set import feature) and fairly simple, with most of the complexity offloaded to the periodic jobs which update the actual data. This simplicity almost works against it, as most consumers of data.pkmn.cc tend to just grab the data directly through HTTP requests which is slightly problematic as it means they’re more liable to breakages if they aren’t using the latest @pkmn/smogon client.