Proposal: Integrate PokePaste's syntax as a PSC standard

[immewnity]

The original Pokémon Standards Initiative started off trying to standardize on syntax for IVs/EVs. Since then, PokePastes have become the de-facto standard across the grassroots VGC scene, and seem to have everything that was desired then.

Here's an example PokePaste, from https://pokepast.es/6314d9d7554e9f59:

Tyranitar @ Weakness Policy  
Ability: Sand Stream  
Level: 50  
Shiny: Yes  
EVs: 236 HP / 132 Atk / 84 Def / 20 SpD / 36 Spe  
Adamant Nature  
- Rock Slide  
- Superpower  
- Lash Out  
- Protect  

Tapu Koko @ Shuca Berry  
Ability: Electric Surge  
Level: 50  
Shiny: Yes  
EVs: 236 HP / 12 Def / 92 SpA / 60 SpD / 108 Spe  
Timid Nature  
IVs: 0 Atk  
- Electroweb  
- Dazzling Gleam  
- Volt Switch  
- Protect  

Kartana @ Assault Vest  
Ability: Beast Boost  
Level: 50  
EVs: 116 HP / 4 Atk / 28 Def / 228 SpD / 132 Spe  
Careful Nature  
- Leaf Blade  
- Sacred Sword  
- Smart Strike  
- Aerial Ace  

Landorus-Therian (M) @ Choice Scarf  
Ability: Intimidate  
Level: 50  
EVs: 36 HP / 196 Atk / 4 Def / 20 SpD / 252 Spe  
Adamant Nature  
- Earthquake  
- Superpower  
- Rock Slide  
- U-turn  

Rotom-Heat @ Safety Goggles  
Ability: Levitate  
Level: 50  
EVs: 244 HP / 12 Def / 116 SpA / 4 SpD / 132 Spe  
Modest Nature  
IVs: 0 Atk  
- Overheat  
- Thunderbolt  
- Nasty Plot  
- Protect  

Gastrodon @ Sitrus Berry  
Ability: Storm Drain  
Level: 50  
EVs: 236 HP / 116 Def / 60 SpA / 84 SpD / 12 Spe  
Modest Nature  
IVs: 0 Atk  
- Ice Beam  
- Earth Power  
- Acid Armor  
- Recover

Full syntax is available at https://pokepast.es/syntax.html.

Please comment any concerns you may have with utilizing PokePaste's syntax as a standard.

[immewnity]

One concern I have is: How would this format apply to earlier games, especially before the Special split?

[MatiasOETamminen]

It's not the physical/special split that causes an issue but the DV/EV remake between Crystal and Ruby & Sapphire. However, given that you could maximize all the stats in Gen I&II, the whole row could just be omitted in those, as well as Ability, Nature, and Held item (for Gen I).

[MatiasOETamminen]

...and also, I'll second the proposal

[NoelDavies]

Representing PokelinkApp! I second this but the proposal should be defined a little better. Even if based on PokePaste.

[NoelDavies]

Representing PokelinkApp! I second this but the proposal should be defined a little better. Even if based on PokePaste.

A full example:

Ability: Sand Stream
Level: 50
Shiny: Yes
Happiness: 134
EVs: 236 HP / 132 Atk / 84 Def / 20 SpD / 36 Spe
IVs: 11 HP / 11 Atk / 16 Def / 18 SpA / 4 SpD / 12 Spe
Adamant Nature
- Rock Slide
- Superpower
- Lash Out
- Protect

Personally (Since Pokélink has a large implementation using these, alongside showdown, etc.) I'd like to expand upon this standard by adding:

• Pokerus
• Hidden power
• Pokerus
• Location Met
• Current/Max PP
• Current EXP value
• Current Form(e)
• Types
• Status
• Pokeball Caught in
• Is Egg

So a better example IMHO would be:

TTarrrrr (Charizard) (F) @ Weakness Policy
Ability: Sand Stream
Level: 50
Shiny: Yes
Pokerus: Yes
Location Met: Route 1
Caught In: Pokeball
Hidden Power: Ghost
Happiness: 134
Experience: 3135757708
Is Egg: No
Status: Par, Slp (2)
Current Form: Gmax
EVs: 236 HP / 132 Atk / 84 Def / 20 SpD / 36 Spe
IVs: 11 HP / 11 Atk / 16 Def / 18 SpA / 4 SpD / 12 Spe
Type 1: Fire
Type 2: Flying
Adamant Nature
- Rock Slide (29/30)
- Superpower (4/5)
- Lash Out (1/15)
- Protect (17/30)

Line By Line

Line 1 - Nickname, Species name, Gender, and Held Item

TTarrrrr (Charizard) (F) @ Weakness Policy

On a full use-case, this is represented by The nickname first TTarrrrr (Charizard) (F) @ Weakness Policy

Then the species name in parentheses TTarrrrr (Charizard) (F) @ Weakness Policy

Then the gender, again in parentheses TTarrrrr (Charizard) (F) @ Weakness Policy

After this, You'll see an an @ followed by a held item. TTarrrrr (Charizard) (F) @ Weakness Policy

Explained: No Nickname attached to the pokemon. In this case the nickname is removed from the front, and the parentheses no longer encase the species name of the pokemon like so: Charizard (F) @ Weakness Policy

Explained: Genderless Pokemon. In this case the Gender, and outer parentheses are removed (as gender is assumed genderless): TTarrrrr (Charizard) @ Weakness Policy

Explained: Gendered Pokemon. The options within the parentheses are M denoting Male, Or F denoting Female as seen below, respectively: TTarrrrr (Charizard) (M) @ Weakness Policy TTarrrrr (Charizard) (F) @ Weakness Policy

Explained: No Held Item In this case Everything after, and including the @ is removed like so: TTarrrrr (Charizard) (F)

Explained: No Held Item In this case Everything after, and including the @ is removed like so: TTarrrrr (Charizard) (F)

[NoelDavies]

More coming soon. I need sleep

[NoelDavies]

@immewnity would you prefer me to just add all this to a new PR?

[immewnity]

@immewnity would you prefer me to just add all this to a new PR?

That would be perfect, yes!

[NoelDavies]

This is being written up here https://github.com/NoelDavies/standards/blob/feature/PSC-03-team-text-format/drafts/docs/psc-003.md and will be submitted as a PR soon. Comments & feedback welcome!

[felixphew]

Oh, this is cool! Had no idea there was an effort to standardise such things, but if you're trying, I've both worked with, beaten my head against, and talked to other people about this format a whole bunch, so I have a few suggestions / things to take into account. I'm working on some stuff right now but will write my thoughts up shortly.

[NoelDavies]

would highly suggest checking out https://github.com/Pokemon-Standards-Consortium/meta first

[felixphew]

• I'm pretty sure we all intuitively know why keeping the existing PokePaste / Showdown / etc. text format is desirable, but to enumerate its advantages for sake of perpetuity:
  • Already supported by just about every tool under the sun. (This is the big one, but not the only one!)
  • Pretty compact given it's specialised for Pokemon use. Any format based on XML / JSON / YAML / etc., while also struggling with the other criteria, would necessarily be more verbose (YAML might get you close, but definitely not better).
  • Human-readable and human-modifiable. Technically it's probably also human-writable from scratch for an experienced person, but I don't think that's that important, whereas the ability to take a paste and change an ability, or an EV spread, or a move without opening up an editing tool is.
• The big downside, of course, is that it's a custom file format, necessitating the writing of a parser and/or serialiser to interact with it.
  • Of course, a well-written standards document makes this less of a challenge, and libraries in common languages would help even more.
  • To the best of my knowledge, nothing in the current grammar is ambiguous, but the "head line" (as PokePaste calls it) - the name / nickname? / sex? / item? line - is kind of slightly obnoxious to parse with conventional techniques (you basically have to handle name and nickname together OR the whole line together OR parse it right-to-left).

[felixphew]

Things I'd like to consider:

• Do we want to enforce an order of fields? (I'd say no, I see no reason to, but we should make that decision explicit.)
  • If we don't enforce a field order, do we want a canonical order of fields (so that a given set can have one canonicalised form)? If so, what should that order be? What Showdown uses (somewhat arbitrary)? Alphabetical (no semantic meaning and splits EVs / IVs / DVs from each other)?
• Do we want to allow arbitrary whitespace instead of just one space?
  • Most tools don't generate anything but the standard whitespace configurations except Showdown likes to generate random whitespace at the ends of lines, sometimes, for some reason.
  • Anyone know of any other scenarios where this happens?
• Re: @immewnity's question about pre SpA/SpD split and the DV era:
  • Showdown I think has handled this in a few different ways over the years? As of now, it emits DVs in the IVs line and emits Special in the SpA slot, but I could have sworn it used to emit "Spc" for Special.
  • PokePaste recognises "Spc" for "Special" in EV / IV lines, and recognises a "DV" line (but this is easy for PokePaste to do, as I don't have to do anything other than highlight the info).
  • No idea what any other tool does.
  • Advantages of Showdown's approach: no need for any transformation to make a set meaningful in any generation.
  • Disadvantages of Showdown's approach: what the file says =/= what the pokemon actually has.
  • This is the first thing I don't have a clear opinion on, but I do intuitively prefer "Spc" as a separate stat at least, and probably also DVs as a separate line.

[felixphew]

Your current standards document appears to be mostly just a documented example. While this is a good way to introduce the format to people, it doesn't really resolve any of the ambiguities that it currently faces. For those that have to actually implement this thing, I think it'd be useful to also have a more structured syntax definition, a BNF or something like it. (I have one that I wrote a while ago that I could update to suit.)

[NoelDavies]

• I'm pretty sure we all intuitively know why keeping the existing PokePaste / Showdown / etc. text format is desirable, but to enumerate its advantages for sake of perpetuity:

Agreed, I think we're aiming to standardise & hopefully add to it

• Already supported by just about every tool under the sun. (This is the big one, but not the only one!)

100%. I'll most probably be releasing the parser I build for Pokelink as a compliant open source example.

Do we want to enforce an order of fields? (I'd say no, I see no reason to, but we should make that decision explicit.) No, I don't think so either. Ideally each "line"/"attribute" should have a module/parser for that line that can declare it's support for the line (much like the specification pattern, or sometimes known as an implementation of a rules engine)

Disadvantages of Showdown's approach: what the file says =/= what the pokemon actually has.

what do you mean?

I think it'd be useful to also have a more structured syntax definition, a BNF or something like it. (I have one that I wrote a while ago that I could update to suit.)

can you expand on this? what do you mean by a BNF?

[felixphew]

can you expand on this? what do you mean by a BNF?

BNF or Backus-Naur Form is a way to express a formal grammar for a language - it's used a lot by people that develop programming languages, network protocols, and file formats. If you've ever read the appendix of an RFC that defines a protocol or file format, or read the formal spec for a programming language, you've probably seen some variant of BNF or another.

Here's what the first few lines of an ABNF spec for this syntax could look like (remember, there are a few variants on syntax here):

PASTE = SET *(NEWLINE NEWLINE SET) ;

SET = HEAD *(NEWLINE ATTR) *(NEWLINE MOVE) ;

ATTR = LABEL ": " VALUE ;

Specifying a language like this not only avoids ambiguity, but you can also take this representation and more or less write a parser directly from it. (There are even tools that do most of the work for you, although most of those don't work on the PokePaste syntax because of that wacky "head" line.

[NoelDavies]

Damn you I literally was about to post

Ignore me, "Backus-Naur form (BNF)". I understand it now

Literally 2 seconds before I was going to comment xD

[immewnity]

Your current standards document appears to be mostly just a documented example. While this is a good way to introduce the format to people, it doesn't really resolve any of the ambiguities that it currently faces. For those that have to actually implement this thing, I think it'd be useful to also have a more structured syntax definition, a BNF or something like it. (I have one that I wrote a while ago that I could update to suit.)

Oh absolutely, right now there's no document really, just a barebones page as a placeholder. A more structured definition like an RFC is the goal.

[zzo38]

(I represent the "Pokemon Text Battle" project, which unfortunately I have not made much work on, but maybe I will be able to do with help in future.)

I think that some suggestions of new fields are not necessary, but some may be helpful. My suggestions are:

• Add a Generation command (which is optionally added at the top of the file, and applies to all pokemons listed in the file). This command will be followed by a blank line.

• Forms are sometimes relevant but not always. Some have no effect, and some are decidable from the other data in the file, or are changed by other conditions in battle. However, in a few cases it might be necessary to specify the forms.

• Location met, pokeballs, number of experience points, etc are probably irrelevant. (Possibly a kind of "extension fields" may be possible if some people find this useful, e.g. some implementations that have a graphical display might display the pokeballs in different colours.)

• Specification of number of PP Up of each move.

• I dislike some of the abbrevations it uses, although it is probably too late to be changed, by now.

• Comment syntax (probably only on a line by itself).

• For IV/EV, generation I and II use different numbers than others, although as far as I remember (I cannot access Bulbapedia at this time to check), the numbers can be converted so that the same equations can be used. Which numbers should be specified, in this case?

• Sometimes the IV numbers and other things will be constrained by other specifications depending on the generation. For example, generation II will have the gender and Physical Attack IV from each other, and you might not have separate IV for Special Attack vs Special Defense. My proposal is that if some of the data is omitted, the others are automatically calculated; if they are specified, then the combination must be valid, and if they are not valid (e.g. unequal Special Attack and Special Defense in generation I) then it is an error.

• Unown's letters, Spinda's spots, etc: Whether or not this is applicable probably depends on the implementation. (My intention for Pokemon Text Battle is there is no need to specify them in the file; depending on the generation, they may either be automatically calculated and displayed to all players (possibly with an option to disable this feature for compatibility), or ignored entirely and not displayed. However, a graphical implementation might want to display them even if they cannot automatically be calculated, similarly than the pokeballs are.)