NCP Damage Calculator

Compute Pokémon Champions damage ranges and speed lines with the bundled NCP VGC Damage Calculator core. Use exact calculations whenever a claim depends on damage, KO, survival, or move order.

Workflow

1. Resolve Chinese or Japanese names through $pokemon-champions-dex; the NCP wrapper itself uses English calculator keys.
2. Run the wrapper's resolve command to align canonical English names to exact NCP keys.
3. Supply the actual item, ability, nature, SP spread, stat stages, status, and relevant field state.
4. Use the damage API for a concrete attack, or the speed API for one Pokémon, a table, or a direct comparison.
5. Report assumptions with the result. A successful calculation does not establish Champions legality.

Damage

Run one calculation with JSON on stdin or use batch with a JSON array:

@'
{
  "attacker": {
    "name": "Mega Metagross",
    "ability": "Tough Claws",
    "item": "Metagrossite",
    "nature": "Jolly",
    "sps": {"hp": 2, "atk": 32, "def": 0, "spa": 0, "spd": 0, "spe": 32},
    "moves": ["Earthquake"]
  },
  "defender": {
    "name": "Mega Raichu Y",
    "ability": "No Guard",
    "item": "Raichunite Y",
    "nature": "Timid",
    "sps": {"hp": 2, "atk": 0, "def": 0, "spa": 32, "spd": 0, "spe": 32},
    "moves": ["Zap Cannon"]
  },
  "move": "Earthquake",
  "field": {}
}
'@ | python scripts\ncp-calc-api.py

The result includes all rolls, percentage rolls, min/max values, defender HP, and the calculator description.

Speed

Query one speed line:

@'
{"name":"Mega Staraptor"}
'@ | python scripts\ncp-speedline-api.py

Query a filtered table or compare two complete speed states. compare also reports move order under Trick Room:

@'
{"filters":{"type":"Flying","speedMin":170},"limit":20}
'@ | python scripts\ncp-speedline-api.py table
@'
{"a":{"name":"Garchomp","nature":"Jolly","sps":{"spe":32}},
 "b":{"name":"Archaludon","nature":"Modest","item":"Choice Scarf","sps":{"spe":32}}}
'@ | python scripts\ncp-speedline-api.py compare

Name Resolution

Do not scan vendored data files manually. Resolve calculator keys through the CLI; --kind defaults to pokemon:

'["garchomp","Rotom Wash","Mega Charizard X"]' | python scripts\ncp-calc-api.py resolve
'["close combat","earthquake"]'                | python scripts\ncp-calc-api.py resolve --kind move
'["choice scarf","lifeorb"]'                   | python scripts\ncp-calc-api.py resolve --kind item
'["roughskin","intimidate"]'                   | python scripts\ncp-calc-api.py resolve --kind ability

Contract

Treat the executable schemas as authoritative for commands, input fields, output fields, and errors:

python scripts\ncp-calc-api.py schema
python scripts\ncp-speedline-api.py schema

Read references/api.md when field options, batch shapes, speed modifiers, or a complete example are needed. It is explanatory documentation, not a second contract.

Caveats

• The wrapper vendors, rather than reimplements, the NCP core. Attribution and its upstream license are in references/upstream-LICENSE.
• The Python CLIs host that vendored JavaScript in-process via quickjs-ng (python -m pip install -r requirements.txt), so no Node runtime is needed. If quickjs-ng is not installed, those same Python entries automatically delegate to the Node CLIs (node scripts\ncp-calc-api.js / ncp-speedline-api.js); calculation and query results are identical.
• It targets Pokémon Champions at level 50 with Champions stat points; canonical keys are hp/atk/def/spa/spd/spe.
• NCP contains entries beyond the Champions-legal roster. Use $pokemon-champions-team or the dex for legality.
• Damage results model the fields exposed by the API, not every possible residual or multi-turn effect.
• Speed defaults are 31 Speed IV, 32 Speed SP, and a positive Speed nature unless explicitly replaced.