From 8f87b6b84bb53e10acc2ff194a8fbc654260228c Mon Sep 17 00:00:00 2001 From: Guangcong Luo Date: Thu, 10 Jun 2021 15:01:24 -0700 Subject: [PATCH] Move packed team docs out of PROTOCOL.md Packed team docs are now standardiszed in sim/TEAMS.md (Also a bunch of smaller documentation improvements.) --- COMMANDLINE.md | 42 ++++++++++++++-------------- PROTOCOL.md | 68 ++++------------------------------------------ data/FORMES.md | 4 +-- sim/DEX.md | 4 ++- sim/NONSTANDARD.md | 2 +- sim/TEAMS.md | 62 +++++++++++++++++++++++++++++++++++++++--- 6 files changed, 89 insertions(+), 93 deletions(-) diff --git a/COMMANDLINE.md b/COMMANDLINE.md index 127ae5c7d0..03c1d67385 100644 --- a/COMMANDLINE.md +++ b/COMMANDLINE.md @@ -17,55 +17,53 @@ Afterwards, you can use any of the following commands: Supported commands ------------------ -Note: Commands that ask for a team want the team in [packed team format][packed-teams] or JSON format. Teambuilder export format is not supported. - - [packed-teams]: ./PROTOCOL.md#team-format +Note: Commands that ask for a team want the team in [packed team format](./sim/TEAMS.md#packed-format) or JSON format. Teambuilder export format is not supported. `./pokemon-showdown start [--skip-build] [PORT]` -: Starts a PS server on the specified port -: (Defaults to the port setting in config/config.js) -: (The port setting in config/config.js defaults to 8000) +- Starts a PS server on the specified port + (Defaults to the port setting in config/config.js) + (The port setting in config/config.js defaults to 8000) -: Using Pokémon Showdown as a server is documented at: -: [server/README.md](./server/README.md) + Using Pokémon Showdown as a server is documented at: + [server/README.md](./server/README.md) -: (You do not need to use `./build` when using PS as a server; it will -: be run automatically for you unless you use `--skip-build`.) + (You do not need to use `./build` when using PS as a server; it will + be run automatically for you unless you use `--skip-build`.) `./pokemon-showdown generate-team [FORMAT-ID [RANDOM-SEED]]` -: Generates a random team, and writes it to stdout in packed team format -: (Format defaults to "gen7randombattle") +- Generates a random team, and writes it to stdout in packed team format + (Format defaults to "gen7randombattle") `./pokemon-showdown validate-team [FORMAT-ID]` -: Reads a team in any format from stdin, and validates it -: - If valid: exits with code 0 -: - If invalid: writes errors to stderr, exits with code 1 +- Reads a team in any format from stdin, and validates it + - If valid: exits with code 0 + - If invalid: writes errors to stderr, exits with code 1 `./pokemon-showdown simulate-battle` -: Simulates a battle, taking input to stdin and writing output to stdout +- Simulates a battle, taking input to stdin and writing output to stdout -: Using Pokémon Showdown as a command-line simulator is documented at: -: [sim/README.md](./README.md) + Using Pokémon Showdown as a command-line simulator is documented at: + [sim/README.md](./README.md) `./pokemon-showdown json-team` -: Reads a team in any format from stdin, writes the unpacked JSON to stdout +- Reads a team in any format from stdin, writes the unpacked JSON to stdout `./pokemon-showdown pack-team` -: Reads a team in any format from stdin, writes the packed team to stdout +- Reads a team in any format from stdin, writes the packed team to stdout `./pokemon-showdown export-team` -: Reads a team in any format from stdin, writes the exported (human-readable) team to stdout +- Reads a team in any format from stdin, writes the exported (human-readable) team to stdout `./pokemon-showdown help` -: Displays this reference +- Displays this reference Piping diff --git a/PROTOCOL.md b/PROTOCOL.md index e9ffc8db7b..41125fb20d 100644 --- a/PROTOCOL.md +++ b/PROTOCOL.md @@ -459,7 +459,7 @@ To accept a challenge you received from someone, send: /utm TEAM /accept USERNAME -Teams are in packed format (see "Team format" below). `TEAM` can also be +Teams are in [packed format](./sim/TEAMS.md#packed-format). `TEAM` can also be `null`, if the format doesn't require user-built teams, such as Random Battle. Invalid teams will send a `|popup|` with validation errors, and the `/accept` @@ -496,67 +496,9 @@ To cancel searching, send: ### Team format -Pokémon Showdown's main way of representing teams is in packed format. This -format is implemented in `Teams.pack` and `Teams.unpack` in `sim/teams.ts`. +Pokémon Showdown always sends teams over the protocol in packed format. For +details about how to convert and read this format, see [sim/TEAMS.md](./sim/TEAMS.md). If you're not using JavaScript and don't want to reimplement these conversions, -[Pokémon Showdown's command-line client][command-line] can convert between packed teams and -JSON using standard IO. - - [command-line]: ./COMMANDLINE.md - -If you really want to write your own converter, the format looks something like -this: - -``` -Lumineon||focussash|1|defog,scald,icebeam,uturn||85,85,85,85,85,85||||83|] -Glaceon||lifeorb||toxic,hiddenpowerground,shadowball,icebeam||81,,85,85,85,85||,0,,,,||83|] -Crabominable||choiceband|1|closecombat,earthquake,stoneedge,icehammer||85,85,85,85,85,85||||83|] -Toxicroak||lifeorb|1|drainpunch,suckerpunch,gunkshot,substitute||85,85,85,85,85,85||||79|] -Bouffalant||choiceband||earthquake,megahorn,headcharge,superpower||85,85,85,85,85,85||||83|] -Qwilfish||blacksludge|H|thunderwave,destinybond,liquidation,painsplit||85,85,85,85,85,85||||83| -``` - -(Line breaks added for readability - this is all one line normally.) - -The format is a list of pokemon delimited by `]`, where every Pokémon is: - -``` -NICKNAME|SPECIES|ITEM|ABILITY|MOVES|NATURE|EVS|GENDER|IVS|SHINY|LEVEL|HAPPINESS,POKEBALL,HIDDENPOWERTYPE -``` - -- `SPECIES` is left blank if it's identical to `NICKNAME` - -- `ABILITY` is `0`, `1`, or `H` if it's the ability from the corresponding slot - for the Pokémon. It can also be an ability string, for Hackmons etc. - -- `MOVES` is a comma-separated list of move IDs. - -- `NATURE` left blank means Serious, except in Gen 1-2, where it means no Nature. - -- `EVS` and `IVS` are comma-separated in standard order: - HP, Atk, Def, SpA, SpD, Spe. EVs left blank are 0, IVs left blank are 31. - If all EVs or IVs are blank, the commas can all be left off. - -- `EVS` represent AVs in Pokémon Let's Go. - -- `IVS` represent DVs in Gen 1-2. The IV will be divided by 2 and rounded down, - to become DVs (so the default of 31 IVs is converted to 15 DVs). - -- `IVS` is post-hyper-training: pre-hyper-training IVs are represented in - `HIDDENPOWERTYPE` - -- `SHINY` is `S` for shiny, and blank for non-shiny. - -- `LEVEL` is left blank for level 100. - -- `HAPPINESS` is left blank for 255. - -- `POKEBALL` is left blank if it's a regular Poké Ball. - -- `HIDDENPOWERTYPE` is left blank if the Pokémon is not Hyper Trained, if - Hyper Training doesn't affect IVs, or if it's represented by a move in - the moves list. - -- If `POKEBALL` and `HIDDENPOWERTYPE` are both blank, the commas will be left - off. +[Pokémon Showdown's command-line client](./COMMANDLINE.md) can convert between +packed teams and JSON using standard IO. diff --git a/data/FORMES.md b/data/FORMES.md index 15d33b3364..9c1228d7e2 100644 --- a/data/FORMES.md +++ b/data/FORMES.md @@ -51,9 +51,9 @@ Cosmetic formes are not listed in the `otherFormes` array, only in the `cosmetic `{name: "Gastrodon", baseForme: "West", cosmeticFormes: ["gastodoneast"]}` -You will still be able to get a data entry for a cosmetic forme with `species.get` as normal, though: +You will still be able to get a data entry for a cosmetic forme with `Dex.species.get` as normal, though, such as `Dex.species.get('gastrodon-east')`: -`{name: "Gastodon-East", forme: "East", baseSpecies: "Gastrodon"}` +`{name: "Gastrodon-East", forme: "East", baseSpecies: "Gastrodon"}` Visual formes diff --git a/sim/DEX.md b/sim/DEX.md index 628e964b7b..413d46c14e 100644 --- a/sim/DEX.md +++ b/sim/DEX.md @@ -30,7 +30,7 @@ const {Dex} = require('pokemon-showdown'); const frobnicate = Dex.moves.get('frobnicate'); console.log(frobnicate.exists); // prints false -console.log(missingno.isNonstandard); // prints 'Custom' +console.log(frobnicate.isNonstandard); // prints 'Custom' const tomohawk = Dex.species.get('tomohawk'); console.log(tomohawk.exists); // prints true @@ -69,6 +69,8 @@ Return values have not been stabilized yet. Use the TypeScript definitions if yo `dex: ModdedDex` ---------------- +Remember: `dex` refers to either `Dex` or `Dex.mod(modID)`. + `dex.moves.get(moveName: string): Move` * Gets information about a move. `moveName` can have any capitalization or whitespace. [This includes nonstandard information](#nonstandard-information). diff --git a/sim/NONSTANDARD.md b/sim/NONSTANDARD.md index bf58429bf4..9ad9707be1 100644 --- a/sim/NONSTANDARD.md +++ b/sim/NONSTANDARD.md @@ -39,7 +39,7 @@ These have `thing.isNonstandard === 'Past' || thing.isNonstandard === 'Future' | Pokéstar Pokémon ---------------- -Gen 5 had a minigame called ["Pokéstar Studios"][https://bulbapedia.bulbagarden.net/wiki/Pok%C3%A9star_Studios], where you could fight robots and aliens and other non-Pokémon in Pokémon battles. These are treated as Pokémon in the Black 2 and White 2 game data. +Gen 5 had a minigame called ["Pokéstar Studios"](https://bulbapedia.bulbagarden.net/wiki/Pok%C3%A9star_Studios), where you could fight robots and aliens and other non-Pokémon in Pokémon battles. These are treated as Pokémon in the Black 2 and White 2 game data. Examples include: diff --git a/sim/TEAMS.md b/sim/TEAMS.md index cdaf53df83..b3f6b199a8 100644 --- a/sim/TEAMS.md +++ b/sim/TEAMS.md @@ -157,14 +157,62 @@ Packed format Packed format looks like this: ``` -Articuno||leftovers|pressure|icebeam,hurricane,substitute,roost|Modest|252,,,252,4,||,,,30,30,|||]Ludicolo||lifeorb|swiftswim|surf,gigadrain,icebeam,raindance|Modest|4,,,252,,252|||||]Volbeat||damprock|prankster|tailglow,batonpass,encore,raindance|Bold|248,,252,,8,|M||||]Seismitoad||lifeorb|swiftswim|hydropump,earthpower,stealthrock,raindance|Modest|,,,252,4,252|||||]Alomomola||damprock|regenerator|wish,protect,toxic,raindance|Bold|252,,252,,4,|||||]Armaldo||leftovers|swiftswim|xscissor,stoneedge,aquatail,rapidspin|Adamant|128,252,4,,,124||||| +Articuno||leftovers|pressure|icebeam,hurricane,substitute,roost|Modest|252,,,252,4,||,,,30,30,|||] +Ludicolo||lifeorb|swiftswim|surf,gigadrain,icebeam,raindance|Modest|4,,,252,,252|||||] +Volbeat||damprock|prankster|tailglow,batonpass,encore,raindance|Bold|248,,252,,8,|M||||] +Seismitoad||lifeorb|swiftswim|hydropump,earthpower,stealthrock,raindance|Modest|,,,252,4,252|||||] +Alomomola||damprock|regenerator|wish,protect,toxic,raindance|Bold|252,,252,,4,|||||] +Armaldo||leftovers|swiftswim|xscissor,stoneedge,aquatail,rapidspin|Adamant|128,252,4,,,124||||| ``` +(Line breaks added for readability - this is all one line normally.) + +The format is a list of pokemon delimited by `]`, where every Pokémon is: + +``` +NICKNAME|SPECIES|ITEM|ABILITY|MOVES|NATURE|EVS|GENDER|IVS|SHINY|LEVEL|HAPPINESS,POKEBALL,HIDDENPOWERTYPE +``` + +- `SPECIES` is left blank if it's identical to `NICKNAME` + +- `ABILITY` is `0`, `1`, or `H` if it's the ability from the corresponding slot + for the Pokémon. It can also be an ability string, for Hackmons etc. + +- `MOVES` is a comma-separated list of move IDs. + +- `NATURE` left blank means Serious, except in Gen 1-2, where it means no Nature. + +- `EVS` and `IVS` are comma-separated in standard order: + HP, Atk, Def, SpA, SpD, Spe. EVs left blank are 0, IVs left blank are 31. + If all EVs or IVs are blank, the commas can all be left off. + +- `EVS` represent AVs in Pokémon Let's Go. + +- `IVS` represent DVs in Gen 1-2. The IV will be divided by 2 and rounded down, + to become DVs (so the default of 31 IVs is converted to 15 DVs). + +- `IVS` is post-hyper-training: pre-hyper-training IVs are represented in + `HIDDENPOWERTYPE` + +- `SHINY` is `S` for shiny, and blank for non-shiny. + +- `LEVEL` is left blank for level 100. + +- `HAPPINESS` is left blank for 255. + +- `POKEBALL` is left blank if it's a regular Poké Ball. + +- `HIDDENPOWERTYPE` is left blank if the Pokémon is not Hyper Trained, if + Hyper Training doesn't affect IVs, or if it's represented by a move in + the moves list. + +- If `POKEBALL` and `HIDDENPOWERTYPE` are both blank, the commas will be left + off. + + Converting between formats -------------------------- -API: - `Teams.unpack(packedTeam: string): PokemonSet[]` - Converts a packed team to a JSON team @@ -230,4 +278,10 @@ const output = validator.validateTeam( `output` will be an array of problems, if it's not a legal team, or `null`, if it's a legal team. -If you're not using JavaScript, use the commandline API: [COMMANDLINE.md](./../COMMANDLINE.md) + +Command-line API +---------------- + +If you're not using JavaScript, all of these APIs (conversion, generating random teams, validating teams) are available via the commandline API: [COMMANDLINE.md](./../COMMANDLINE.md). + +They use standard IO, so any programming language supporting fork/exec should be able to call into them.