Repository navigation
"order" of Pokémon forms is shared between unrelated species #1569
Description
At present, the order column of the pokemon_forms.csv is mostly just an incrementing list that groups all forms of the same species together. This makes it very inconvenient to insert new forms for pre-existing Pokémon, as every subsequent entry needs to have its order incremented.
However, while the list at first appears to be an incrementing list (with a unique value per form), this is not actually the case (as I discovered in #1532). The documentation does note
Multiple forms may have equal order, in which case they should fall back on sorting by name.
The first major group of non-unique entries is Alcremie. The Alcremie forms have distinct order values for each Cream, but each Cream shares the same order value across Sweets. So alcremie-vanilla-cream-berry-sweet is 1256 and alcremie-ruby-cream-berry-sweet is 1257, but alcremie-vanilla-cream-love-sweet is also 1256.
However, after Alcremie, there are a bunch of DLC Sword & Shield Pokémon, Hisui Pokémon, and Paldean Pokémon that share order values with Gigantamax Pokémon and forms introduced in Hisui and Paldea. Some examples:
| order | Entry 1 | Entry 2 |
|---|---|---|
| 1292 | eternatus-eternamax | venusaur-gmax |
| 1293 | kubfu | charizard-gmax |
| 1294 | urshifu-single-strike | blastoise-gmax |
| 1313 | fuecoco | flapple-gmax |
| 1314 | crocalor | appletun-gmax |
| 1327 | rabsca | growlithe-hisui |
| 1328 | greavard | arcanine-hisui |
| 1373 | naclstack | miraidon-aquatic-mode |
| 1374 | garganacl | miraidon-glide-mode |
Proposal
My proposal is that the order column do something similar to what Pokémon Champions does internally: Concatenate a National Pokédex number and a form ID to produce a unique identifier for a specific form of a Pokémon. For example, Venusaur (Pokédex #3) would be form ID 00003000, while Mega Venusaur would be form ID 00003001, and Charmander (Pokédex #4) would be form ID 0004000. (Since these are integers, the leading 0's would be stripped, but I've included them here to illustrate how the numeric identifiers are based on Pokédex numbers.)
This could even replace the existing id column of the pokemon_forms.csv table, and the order column could just be deprecated.
Activity
jemarq04 commentedon Jun 24, 2026
I definitely like the idea of using this Champions' method for producing a unique identitier, but modifying our existing IDs to match that would require an enormous refactor that I'm not sure we need. I do, however, think we should definitely update the
orderfield (and its documentation) to use this new identifier so that things can be ordered nicely from our API! I mentioned this in the PR, but this is a great idea!magical commentedon Jun 24, 2026
There used to be scripts to maintain the order column, e.g. https://github.com/PokeAPI/pokedex/blob/master-pokeapi/scripts/set_pokemon_order_columns.sql
SnorlaxMonster commentedon Jun 25, 2026
That's fair. If it's just a matter of updating the foreign key in all of the tables it appears in, I think that would be reasonably doable via a script. But it looks like these ID numbers are also used as filenames in the cries and sprites submodules, and I imagine there are other more subtle places relying on these ID numbers. Maybe something to consider for API v3 (if that is ever created).
Anyway, I can certainly create a PR updating the order field in this way, since that has strong support.
nunesvictor commentedon Jul 4, 2026
I don’t know if my issue is related to this but I was wondering why some forms are out of order with the pre-evolution forms. Ex: zubat, golbat and crobat are together while mankey and primeape are separated from annihilape. Is this a bug or there’s a reason I’m not seeing?