vgc_data_wrapper

Documents are still WIP. If faced any problem please leave an issue.

Purpose

Damage calculator is not a new thing in VGC world, but AFAIK most of the implementations are tightly coupled with designated UI logic, which makes other developers hard to reuse the calculation part and difficult to refactor (which is exactly why I start this project). It's becomes a problem when we want to build a localize version (i.e. avoid English) or just want an independent calculator component in the application. During the process, it becomes clear that lots of resources in VGC are scatted everywhere. For example, meta data from Pokemon Showdown can be found at Smogon site while meta data from tournament comes from other source. Hence I aim to build this package as an all-in-1 tool kit, which is kinda too ambitious for now.

Installation

// npm
npm i vgc_data_wrapper
// yarn
yarn add vgc_data_wrapper
// pnpm
pnpm add vgc_data_wrapper
// bun
bun add vgc_data_wrapper

How to use

General Usage: Setup a battle and let pokemons fight.

import { Pokemon, Battle, createMove } from 'vgc_data_wrapper'

<!-- You can manually set essential infomation to start calculation. Unset properties will be set with default values.  -->
const flutterMane = new Pokemon({
    types: ["Fairy", "Ghost"],
    stats: {
        specialAttack: 155,
    },
})

<!-- Or you can create a new Pokemon instance without any input and then init with id, which will fetch related infomation from PokeAPI.  -->
const incineroar = new Pokemon()
await incineroar.initWithId(727)


<!-- Move doesn't have a class since its doesn't need own method. Even base power calculation is related with field status or pokemon. -->
const moonblast = createMove({
    type: "Fairy",
    base: 95,
    category: "Special",
})

const battle = new Battle({
    attacker: flutterMane,
    defender: incineroar,
    move: moonblast
})

const damageResult = battle.getDamage();
<!-- { rolls: Array<{ number: number, percentage: number}>, koChange: number } -->

API explain

Pokemon

Property	Type	Optional	Default Value	Description
id	number	Y	-	Pokemon ID from national dex
level	number	N	50	Affect stat & damage calculation;
types	[Type] / [Type, Type]	N	["Normal"]	Fire, Water, etc.
baseStat	Stat	N	100(for each key)	Explain
effortValues	Stat	N	0(for each key)	Explain
individualValues	Stat	N	31(for each key)	Explain
stat	Stat	Y	-	Derived from baseStat, EV, IV and level. The real stat in game.
statStage	StatStages	N	0(for each key)	Pokemon can boost or drop stat and affect result of damage calc. The multiplier is based on the fraction 2/2 while each boost adds to the top & each drop adds to the bottom
nature	Nature	Y	-	Boost 1 stat by 1.1 or lower 1 stat by 0.9
weight	number	N	0	Affect some damage calcs like Grass knot
ability	Ability	Y	-	Ability list is stored at data/ability.json
item	Item	Y	-	Item list is stored at data/item.json
teraType	Type & Stellar	Y	-	null mean not in tera form.
gender	Male & Female & Unknown	N	Unknown	Affect Rivalry calc
status	Status	N	Healthy	Status condition, ex: Burned, Poisoned, etc.
flags	PokemonFlags	Y	-	Certain conditions that affects calculation, ex. Helping Hand, Power Spot, Light Screen, etc.

Methods

Name	Param	Return	Description
getStats	-	Stat	Get all stats for pokemon. If stats are not manually set initially, full stat will be derived from base stat, EV, IV and nature.
getStat	key: keyof Stat	number	Get certain stat(hp, atk, etc.) from pokemon. If stat is not set, then stat will be calculated from BS, EV, IV and nature.
setFlag	flags: Flag	-	Update flags for pokemon. Ex, light screen is set up
toggleTera	(true, type) / (false)	-	tera or cancel tera for this pokemon
initWIthId	(id: number, options?: Options)	-	Using this method to init pokemon base stat, weight and other properties by fetching from PokeAPI. Advanced options can be passed in as second argument.
setNature	nature: Nature	-	update nature

• Other properties can be updated directly without using specific method for now.

Stat & StatStages

const statProps = [
	"hp",
	"attack",
	"defense",
	"specialAttack",
	"specialDefense",
	"speed",
] as const;

export type Stat = {
	[key in (typeof statProps)[number]]: number;
};

type StatStages = Omit<Stat, "hp">;

Nature

type Nature = {
	plus?: keyof StatStages;
	minus?: keyof StatStages;
};

Battle

Property	Type	Optional	Default Value	Description
attacker	Pokemon	N	-	Pokemon attacking
defender	Pokemon	N	-	Pokemon defending
move	Move	N	-	Move used when calculate damage
field	BattleFieldStatus	Y	{}	Flags related to whole field like weather, aura, etc.

Methods

Name	Param	Return	Description
getDamage	-	DamageResult	Get damage results from given attacker, defender, move and field
setField	field: Partial	void	update field, ex. change weather.
setPokemon	(type: "attacker" | "defender", pokemon: Pokemon )	-	set attacker/defender
swapPokemons	-	-	swap attacker and defender

Move

type MoveCategory = "Special" | "Physical";

type MoveTarget = "selectedTarget" | "allAdjacentFoes" | "allAdjacent";

export type Move = {
	id: number; // default 0
	base: number; // default 0
	type: Type;  // default Normal
	flags?: Flags<
		| "hasRecoil"
		| "hasSecondary"
		| "isContact"
		| "isPunch"
		| "isSound"
		| "isSlicing"
		| "isBite"
		| "isPulse"
		| "isMultihit"
		| "isPriority"
		| "isCriticalHit"
	>;
	target: MoveTarget; // default selectedTarget
	category: MoveCategory; // default Physical
	repeatTimes?: number;
};

BattleFieldStatus

type Weather = "Sun" | "Rain" | "Sand" | "Snow";

type Terrain = "Electric" | "Grassy" | "Misty" | "Psychic";

type Aura = "Fairy" | "Dark";

type Ruin = "Tablets" | "Sword" | "Vessel" | "Beads";

export type BattleFieldStatus = Partial<{
	weather: Weather;
	terrain: Terrain;
	aura: Array<Aura>;
	ruin: Array<Ruin>;
	isDouble: boolean;
}>;

DamageResult

export type DamageResult = {
	rolls: Array<{
		number: number;       // how much the move do to defender
		percentage: number;   // how much % the move do to defender
	}>;
	koChance: number;       // How likely the move will ko defender
};

createMove

Name	Param	Return	Description
createMove	move: Partial	Move	Helper function to generate move. Provides default values for base, target, type, category and id

getEffectivenessOnPokemon

Name	Param	Return	Description
getEffectivenessOnPokemon	(moveType: Type, pokemonTypes: Array)	number	Calculate how certain move is effectivve on target pokemon.

Roadmap

• usage data
  • Smogon has lots of usage information from Pokemon Showdown ready to be utilized but in txt or chaos json form.
  • Plan to add some wrapper functions to simplify the process and help developers emphasize on analyzing the data.
• tournament data
  • Plenty of online tours are hosted on Limitless, which has a public API to fetch results and teams.
  • Ideally I want to add results from official tournaments but I don't have easy way to grab results automatically for now.