ncp-damage-calculator git:20260710.66eec11A

Immutable. This exact content is served forever at /api/v1/blob/39abdd6dc43b682d.

---
name: ncp-damage-calculator
description: Run Pokémon Champions damage and speed-line calculations using the bundled NCP VGC Damage Calculator formulas. Use when the request asks for a concrete damage, KO, survival, or speed-order calculation between specified Pokemon, moves, spreads, field states, items, abilities, or stat stages. For broad team-building or tuning, use the team skill first and let it delegate exact calc checks. Chinese examples include "X用Y打Z多少", "X能确一/二确Z吗", "Z吃得下X的Y吗", "X快过Z吗", "多少SP能快过/抗住". English examples include "calc X's move into Y", "does this OHKO/2HKO", "can Y survive this hit", "does X outspeed Y", "what spread reaches this benchmark". Japanese examples include "XのYでZにどれくらい入る？", "確定一発/二発？", "ZはYを耐える？", "XはZを抜ける？", "このラインに必要なSPは？".
---

# NCP Damage Calculator

Compute Pokemon 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 Pokemon, 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:

```powershell
@'
{
  "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": {}
}
'@ | node scripts\ncp-calc-api.js
```

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

## Speed

Query one speed line:

```powershell
@'
{"name":"Mega Staraptor"}
'@ | node scripts\ncp-speedline-api.js
```

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

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

## Name Resolution

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

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

## Contract

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

```powershell
node scripts\ncp-calc-api.js schema
node scripts\ncp-speedline-api.js 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`.
- It targets Pokemon 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.