Programming Damage Calculator API

[Nineage]

Now for something that 95% of Smogon's users won't care at all about but maybe some of my fellow sweaty nerds in this forum will appreciate!

tl;dr There is an API for Pokemon damage calculations at
https://calc-api.herokuapp.com/calc-api

The Backstory
Basically, TheFenderStory and I have been working on various technical projects which required damage calculations run and we realized that we were kind of writing the same tedious code over and over again, and that often running such a complicated group of checks and calculations over and over was probably suboptimal. We realized that an efficient way to solve the problem was an external API for Pokemon damage calculation.

What it is
This API allows you to post a request which contains two Pokemon's movesets and a move (in the format given below), and it will run the damage calculation and return some information about how much damage the move will do. The code is basically just a modified, condensed version of the Pokemon Showdown! Damage Calculator which we all know and love, so most of the credit should go to Austin and the other contributors.

How to use it
Easy! Just make a post method to the URL below. Example implementation with JQuery (obviously this request can be made in all sorts of ways):

$.post("https://calc-api.herokuapp.com/calc-api", {
    attacker: attackerObject,
    defender: defenderObject,
    move: "Leaf Storm",
},
function (data, status) {
    //Do something with the data
});

Both attacker and defender object should look something like this:

attackerObject = {
    "species": "Serperior", //species name AS IT IS IN THE POKEDEX  [REQUIRED]
    "ability": "Contrary", //ability [REQUIRED]
    "item": "Leftovers",  //item [REQUIRED]
    "level": 100, //level [REQUIRED], must be a number
    "nature": "Modest", //not required, defaults to serious
    "evs": {"spa": 252, "spe": 252},  //not required, defaults to 0 in all stats. Valid stats are "hp", "atk", "spa", "def", "spd", "spe"
    "ivs": {"atk": 0} //not required, defaults to 31 in any stat not specified
}

The response comes in two parts. The first is data, which will be in an object like this:

{
    "damage": Array[16], //All 16 possible damage rolls, in exact HP numbers
    "description": String, //the description of the calc, e.g. '0+ SpA Serperior Leaf Storm vs. 116 HP  / 76 SpD Eviolite Vullaby'
    "kochance": String, //the calculated KO chance as a string, e.g. 'guaranteed 3HKO'
    "min": Number, //minimum damage percentage as a number, e.g. '16.4'
    "max": Number //maximum damage percentage as a number, e.g. '31.2'
}

The second part is the status, which will either be "success", or an error code (404, 502, etc).

What is missing
There's a few things that I would love to add that don't really work at the moment

• Multi-hit moves are more complicated, and at the moment just assume a single hit or else don't return any damage at all, which is obviously suboptimal
• Z-moves don't work
• Open-source: at the moment this code is not open-source. I will work on cleaning it up to the point where we can release it publicly someday (tm).

Obviously, there might be some other things missing or broken...let us know what doesn't work and we will try to fix it!

What this means
I hope that some of you will try and use this calculator api for code projects. Some general ideas that could use it:

• Damage calculator bot as a quick way to calc damages in game
• bRMT bot that can rate teams by pushing lots of requests through the api to calculate how a team fares against various metagame threats
• Something that analyzes EV spreads for whether they are optimal...?

This is my first attempt (and to my knowledge, Fender's too) at making something like this, so please let me know if there are any issues, or anything you'd like to see added!

 

[cosine180]

Is this up to date?

 

[mrona217]

Are you still working on this? I'd love to see the code and maybe even help out.

 

[pre]

The official damage calculator was refactored such that the logic and mechanics have been separated from the UI and are now available in a package on NPM, @pokemon-showdown/calc. If you're writing a program in Javascript (or Typescript), this can included as a dependency by your project to utilize the same logic powering calc.pokemonshowdown.com. The main entry point is the calculate method which provides a similar API as the OP:

function calculate(
  gen: Generation,
  attacker: Pokemon,
  defender: Pokemon,
  move: Move,
  field?: Field
) { ... }

Perhaps Nineage would consider hosting this version behind his API endpoint (which is still very useful for non-JS projects) as it would hopefully make his life easier, as it will be kept up to date with bug fixes (as well as updated for the upcoming generation 8 etc).

 

[Nineage]

The official damage calculator was refactored such that the logic and mechanics have been separated from the UI and are now available in a package on NPM, @pokemon-showdown/calc. If you're writing a program in Javascript (or Typescript), this can included as a dependency by your project to utilize the same logic powering calc.pokemonshowdown.com. The main entry point is the calculate method which provides a similar API as the OP:

function calculate(
  gen: Generation,
  attacker: Pokemon,
  defender: Pokemon,
  move: Move,
  field?: Field
) { ... }

Perhaps Nineage would consider hosting this version behind his API endpoint (which is still very useful for non-JS projects) as it would hopefully make his life easier, as it will be kept up to date with bug fixes (as well as updated for the upcoming generation 8 etc).

This seems very useful - TheFenderStory and I will get on it when we both have time. Expect updates somewhat soon!

 

[Wheaties]

Could you set up a dummy attacker/defender with these tools/APIs?

I am thinking about building a general type coverage checking application for a whole team of Pokemon and the core concept of it is that I basically create a dummy attack of each type, use it on each pokemon of the team and then add up the totals to see what the team is weak against. Conversely, I would use every move of every team member against a dummy target of every possible type, look at the damage and display it in a table so you can see what types the team is most effective against. There are some nuances like attacks coming off of a typeless pokemon and physical/special attacks, but does this concept sound doable with these tools?

 

[Lanceybear]

Could you set up a dummy attacker/defender with these tools/APIs?

I am thinking about building a general type coverage checking application for a whole team of Pokemon and the core concept of it is that I basically create a dummy attack of each type, use it on each pokemon of the team and then add up the totals to see what the team is weak against. Conversely, I would use every move of every team member against a dummy target of every possible type, look at the damage and display it in a table so you can see what types the team is most effective against. There are some nuances like attacks coming off of a typeless pokemon and physical/special attacks, but does this concept sound doable with these tools?

Hello Wheaties,

For the application you are describing, an API for pulling damaging calculations given a Pokemon's moves, evs, etc. is a incredibly valuable tool. The reason being that this API allows one to streamline these calculations in a robust manner. By robust I mean that these calculations can be generated automatically with as little hard-coding as possible.

This tool not only allows you to generate damage calculations on a given Pokemon using different moves, like you have explained, but you also have the ability to generate these calculations with a particular check/counter in mind. For instance, a Pokemon on your team may be able to take a Hydro Pump from a Magikarp, but taking a Hydro Pump from a Specs Keldeo is a different story.

In essence, the application you are describing is generating the state space for a given Pokemon team given common check/counters in a particular metagame. I will define what a state space is below:

Think of our environment as the set of all possible legal actions that are allowed for a given Pokemon battle. The environment can also be thought of as the domain for a Pokemon battle. An action is a legal move (which is either a Pokemon's attack or a switch to another Pokemon) that allows our Pokemon team to interact with the environment. The result of a set of two actions (one for the player and one for the opponent) generates a state of a Pokemon Battle, which can be thought of as a snapshot of a particular Pokemon Battle. The state space is a set of states for a given instance of time in a Pokemon Battle (think of time in this case as turn numbers). The state space is also a subset of the environment.

Generating state spaces is a very powerful tool as it is the basis for a sub-field of Artificial Intelligence known as Reinforcement Learning. The goal of this learning problem is to generate a policy (a sequence of actions) that maximizes an agent's reward (by agent I mean bot) over time in a given complex environment. The important thing to take away is that the damage calculator API allows for the state space of a given Pokemon Battle to be approximated, which in return makes Reinforcement Learning possible in Pokemon.

Reinforcement Learning with respect to Pokemon is my field of research. If anyone has any questions or concerns about this topic, feel free to send me a private message.