Unofficial URPG Replay Schema



This documentation is not complete. You can contact me via Discord (JacenBoy#8374) if you have any questions.

Overview

The Showdown Replay Engine is fairly simple to learn, and also fairly easy to automate. However, it does have a number of complexities and quirks that need to be taken into account. As a way to decrease the barrier to entry for developers, I have created the Replay Schema as an intermediary between developers and the Showdown engine.

The Replay Schema is a JSON implementation of the Showdown engine. The goal is to create a more developer-friendly format for scripting replays. This will make aurtomating replays, as well as scripting them by hand, easier for everyone.

Why use this schema?

As mentioned before, the Showdown Replay Engine isn't especially difficult to use. Why complicate things by creating an extra step in the process? There are a number of reasons why I believe creating this schema is worth the effort.

  1. Ease of use

    JSON is a much more friendly to use format then the Showdown engine's protocol. JSON is a widely adopted standard that is much more structured than the rudimentery format used by the Showdown engine. I believe this will make it easier for someone will little experience to be able to make an application compatible with the Showdown engine.

  2. User choice

    The easier, more structured, and more widely adopted format means there is a possibility of multiple competing replay scripting systems to be created. This kind of competition means a better user experience, as a user can look at the various options and choose the one that works best for them.

  3. Flexibility

    The Replay Schema, while built specifically for use with the Showdown engine, could be adapted for use with other custom engines, or even used on its own as a fully customized URPG replay engine. This means we aren't limited to a single replay solution, and can adapt to changes and adavncements in the research of replays.

Specifications

This schema is still in development. If you have any questions about what will be included in the schema, please contact me via Discord.

Current Version
1.0.0-a1 (About versioning)
Required Properties
battler1, battler2, referee, rules, battle
Optional Properties
preview

Battler Objects

Name(s)
battler1, battler2
Required Properties
name, stats, icon, team
Optional Properties
None

Each battle must have exactly two battler objects, named battler1 and battler2. These objects hold information such as username, stats, and the team of Pokemon used in the battle. battler1 will always be on the viewer's side of the battlefield, and Battler2 will always be on the opposite side. Each battle must have exactly two battler ojects, named exactly as noted. Multi battles are not currently supported by the schema.

Battler Properties

Name
name
Type
String
Required?
Yes

The username of the battler.

Name
stats
Type
String (URI)
Required?
Yes

A link to the stats of the battler.

Name
icon
Type
Integer
Required?
Yes

A number corresponding to the icon on the Pokemon Showdown avatar sheet used to identify the battler.

Name
team
Type
Array
Required?
Yes

The team of Pokémon used by the battler. See notes on the Pokémon object below.

Referee Object

Name(s)
referee
Required Properties
name, log
Optional Properties
None

Each battle must have exactly one referee object, named referee. This holds the username of the ref, as well as a link to the battle log. A battle involving multiple refs is currently unsupported. It is recommended that the username of the ref who posted the battle log be used in this scenario.

Referee Properties

Name
name
Type
String
Required?
Yes

The username of the referee.

Name
log
Type
String (URI)
Required?
Yes

A link to the post in the referee's battle log corresponding to the battle being scripted.

Rules Object

Name(s)
rules
Required Properties
size, style, generation
Optional Properties
clauses

The various rules and clauses affecting the battle.

Rules Properties

Name
size
Type
String
Required?
Yes

The number of Pokémon taking part in the battle (e.g. "2v2")

Name
style
Type
String
Required?
Yes

The mode (SM, RSE, etc.), privacy (Public/Private), and team format (Open, Preview, etc.) used for the battle.

Name
generation
Type
Integer
Required?
Yes

The generation number that the mechanics of the battle use.

Name
clauses
Type
Array
Required?
No

The clauses in effect for the battle. The clauses are defined using one-word keywords.

A prototype of the schema is currently available to view or download. Note that the contents of the prototype my change quickly and without warning.

Joining the project

If you have questions, comments, or suggestions regarding this schema, you can contact JacenBoy#8374 on Discord.