pkmn’s higher-level open core projects are all built on top of a set of composable open source libraries published under the @pkmn namespace. While these libraries were originally created to serve as intermediate building blocks for EPOké, 0 ERROR and PocketMon, these packages are also intended to be generally useful to other developers working on Pokémon projects. All of these projects follow the same general high level principles (which are sometimes at odds with one another):
- MIT Licensed. While not all pkmn projects use this license, all published
@pkmnpackages do. - Semantic versioning. All
@pkmnprojects are semantically versioned (though note point #4 about major-version-0packages). - Minimize scope. Prefer smaller and more targeted packages to the extent that it makes sense - most should be around 500-2000 lines and serve a specific purpose.
- Minimize dependencies. Prefer zero dependencies, followed by depending on a minimal subset of other
@pkmnpackages followed by depending on external packages which also follow similar principles. - Maximize general use. Prefer depending on interfaces as opposed to specific implementations of libraries, maximize for the ability to be used by a wide range of consumers. To this end, it should also be possible to depend on a package in a browser
<script>tag and have it work. - Maximize composability between
@pkmnprojects. Using two@pkmnprojects together with each other should be intuitive and simple. While projects should still be generally useful on their own,@pkmnoptimizes for the standard case of interoperability within the namespace. - Tested. All
@pkmnprojects should have unit tests, and PRs should always include tests. - Uniform. All code in the
@pkmnnamespace should look similar (style, naming, structure).
At at lower level, @pkmn packages prioritize the following, in rough order:
- Accuracy with respect to cartridge mechanics
- Consistency at all levels (projects, APIs, naming, code)
- Compatibility with other Pokémon projects
- Completeness of support for Pokémon edge cases
Developers can be reached on Discord (pkmn.cc/dev). Bugs should be filed against the respective projects within the GitHub org. All open source @pkmn packages are open to design suggestions and alternative use cases, though the solution proposed may involve the creation of a new package which extends or enhances an existing package.
FAQ
Pokémon Showdown!
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).
Mods
Unlike Pokémon Showdown, @pkmn packages don’t intend to ever provide first class support for mods (non-canonical data or mechanics). @pkmn wishes to avoid complicating its internals by overgeneralizing or drifting away from actual cartridge mechanics by including support for mods directly. However, developers should be able to achieve much the same thing by building on top (wrapping the packages) or by providing their own data with non-canonical information underneath. Allowances are made where possible to enable overriding and extending functionality as part of @pkmn’s goals to maximize general usefulness. However, support for these ‘hooks’ for mods is a secondary priority and are only supported in places where it has zero impact on the common use case.
Style
@pkmn packages favor a terse style which is a sort of amalgam of Pokémon Showdown’s and Google’s style guidelines. These are enforced by the @pkmn ESLint config - style questions and modifications should be directed to the shared config wherever possible. Notable choices:
- prefer
undefinedovernull - favor compact code and leave braces off of short
ifstatements - 100 character line width, spaces over tabs
- if a developer is confused by the code it should either be restructured, commented, or both
Credit
pkmn strongly values appropriately crediting those who contribute by any means, from development and research to testing and bug reporting. Contributors should always strive to acknowledge those who helped them, no matter how small the contribution and regardless of whether or not they have a GitHub/Smogon/etc account. It costs nothing and doesn’t detract in any way from your contribution to credit those who helped you, but not doing so discourages collaboration and reflects poorly on you.