Resource PYVGC - Pokémon Champions focused Python Package

[voozde]

Hello everybody. My nickname is Voozde and I would like to introduce you to my Pokémon-related Project, named pyvgc.​

---

-tentative logo, I am also looking into artists to draw a good one-​

---

Introduction
​

pyvgc is a personal, Python-focused data science project for which the main aim is to support Pokémon Champions calculations and functionality.

It is available as a Python package in PyPI repository, as well as a public GitHub project. For a quick startup guide, you can consult the examples file in the repository. It does not require any additional libraries.

It came up essentially as an answer to “how come there’s no Python Package maintained for Pokémon with how useful that could be for Data Science / other Pokémon related projects”. So, I set out to develop it and put it out there, in a pretty basic manner. Its current focus is Pokémon Champions. Plus, current Pokémon livestreams and players are getting more into Data Study and optimizations, so I think that this kind of Python Package can be beneficial for the community in many ways.

I am still undergoing some testing + building proper documentation (docstrings, sphinx, etc), as well as better coding conventions for readability and maintainability, but I think that the basic utility of the package is at a state where I can promote it in its Alpha version.

The goal of the project is to have Pokémon, items, and everything that Pokémon Champions integrates as a long-time focused project, keeping tabs on regulations, balance changes, and other adjustments, for easier calculations and maybe further projects that use this package as a baseline. Essentially, it is meant to be updated over time and extend with the game itself. There isn’t any similar project out there in PyPI repositories. If there is, I missed it.​

Disclaimers and Background
​

Most of the current projects I’ve seen being posted / promoted are Teambuilder analyzers, Replay analyzers, etc., but I’ve noticed that amongst them there is not an easy accessible Python package for Pokémon / Pokémon Champions data Science Purposes. I would also like to stress, due to recent developments in the community and competitive scene, that this project’s focus is a data science focused Python project, not a bot or anything of the sort.

I’ve spent some weeks with my initial implementation, combining the skills learned in my master’s in computer science, overall VGC personal enjoyment, Data Science background, Python knowledge, and the assistance of Github Copilot, which randomly decided to set itself on GPT-5.6-Luna. All of this is stated in official documentation and project references for clarity and transparency regarding AI policies.

For the curation of my data, I have scraped well-known Pokémon resources to build my inner CSV files that contain most data (movepool, descriptions, regulation available items, Pokémon and their stats, etc). I have documented the original sources in the code, but it's mostly from Serebii. Despite this, it still needs further manual, expert curation and revision, as even when posting this I'm reviewing potential errors (regular Typloshion does not learn Infernal Parade...)

Lastly, as it is currently undergoing early development, some naming conventions and logics may be changed, so please keep an eye on future official documentation in case you do decide to implement the current version in your personal projects.​

Current Version and State
​

In it’s current Alpha state, I think the code / package is at a suitable point so that it can both be:

1. Released as a Python Package under version 0.0.2.3.
2. Update and shared the code on GitHub as a potentially cooperative project with other members of the community.

If you fork the project and would like to reference this first version, I would appreciate it. I will update some disclaimers later on the official code / releases for regal reasons if I need to, as I’m still kind of new to these things.

The current main focus of pyvgc is Pokémon Champions. The coding up until the day I post this here, November 2nd, has the main 3 regulations currently released, m-a, m-b, and m-c.

You can basically:

• Create Pokémon instances, changing their stats, types and natures, according to their current regulation implementation
• Calculate Damage rolls vs other Pokémon (critical hit logic included, as well as % done to the Pokémon when full HP)
• Apply various modifiers (helping hand, screens, etc)
• Stat boosts / debuffs.
• Use various custom functions (signature move lookup, move distribution, etc). If you design on your own, you could make customized functions (speed tiers, move pool sizes, ko range lookup, ev spread optimization, etc)
• Package is overall designed for suitability and adaptability.

As a particular coding example, functioning from the package, you can perform certain actions like this. In this snippet, we would run every attacking move a Reg M-A Modest (?) Incineroar knows against a somewhat bulky Venusaur, and study from there if we can or cannot get the K.O. As such, we can run quick, powerful lookups on potential optimizations, or extended data gathering on entire regulations / mons.

from pyvgc import load_regulation

regulation_ma = load_regulation("M-A") #m-a, m-b and m-c currently supported.
print(regulation_ma)

    dummy = regulation_ma.load_pokemon(
        "Incineroar",
        nature="Modest",
        stat_training={"hp": 32,
                       "attack": 2,
                       "defense": 16,
                       "special_attack": 0,
                       "special_defense": 3,
                       "speed": 0},
        item="Sitrus Berry"
    )

    target = regulation_ma.load_pokemon(
        "Venusaur",
        nature="Bold",
        stat_training={"hp": 32,
                       "attack": 0,
                       "defense": 32,
                       "special_attack": 0,
                       "special_defense": 2,
                       "speed": 0},
        item="Leftovers"
    )

    for move in dummy.moves:
        print(f"Move: {move.name}, Type: {move.type}, Power: {move.base_power}")

    dummy_damage_movepool = [move for move in dummy.moves if move.base_power != None and move.category != "Status"]

    for move in dummy_damage_movepool:
        print(move.name, move.type, move.base_power)
        damage = regulation_ma.battle_logic.calculate_damage(
            dummy,
            target,
            power=move.base_power,
            move_type=move.type,
            special=(move.category == "Special"),
        )
        print(f"Damage from {dummy.name} using {move.name} to {target.name}: {damage}")

I've designed the current code to be both scalable and readable, using various classes such as Pokémon, Items, Moves, Regulations and Battle Logics. The idea is to encapsulate various ways of processing the game to fit multiple logics and situations, so that support for all of them is possible.

For example, this way we can keep separate a current logic (say Cartridge_Champions_2026) and differentiate it from future formula changes or varying implementations instead of messy coding. Currently there are three logic templates (cartridge, simulator, and singles, as this last one has various custom modifiers), setting up ahead of future changes.

Please refer to the examples file in the repository if you want to see what could be done with the package for a practical approach. More examples and guides are planned for the future.

Development and Future Steps
​

Even though the full calculator is not available, thanks to how it's defined you can customize your attacks to "suit" the circumstances.

1. For example, hyper beam with Sylveon would be a Normal Attack due to Pixilate not being coded, but you can force a Sylveon to use a hyper-beam base power move, using its special attack, and coding it as a Fairy Type move.​
2. Same for other moves and conditions, such as Guts doubling power (you can set it up manually)​
3. You can also define Pokémon not currently in the game, by setting their stats and types.​

Currently, there is plenty in the package that is not implemented, including but not limited to:

• Status effects.
• Weathers and Terrains.
• Ability implementation.
• Item functionality.
• Dynamax, TeraType, Z-Moves, etc.

I plan to implement and make this package better over time. My goal for version 1.0 (very far away) is to at least have a full replication of the damage calculator in an import so that it can be seamlessly integrated and no manual workarounds are needed.

This would require logic implementation of the current abilities and items in each regulation, as well as additional code covering / unittesting use cases I may have skipped on or not defined yet.

Currently, this is a side, solo-developer project, with the assistance of AI, so I expect progress to be slow to guarantee its quality and proper usage.

Ending Remarks
​

I believe I have presented my project, pyvgc, in the best way that I can. I hope that you find it useful / interesting.

You may contact me in this forum, or under my alias in Discord or Github for this project. If you'd like to collaborate or are interested in the project, you are welcome to contact me / open a PR or fork the project to best suit their needs. I welcome all feedback to improve and make the project better.

Lastly, if the moderation team has any issues with my post, or needs further information, please feel free to contact me. I will update this post / thread in the future with newer updates or information as it is needed.

Thank you kindly for your time reading this post. Please feel free to ask any questions you may have and I’ll respond to the best of my ability.

PD: Updating / Formatting this post if needed for better readability.​

​

Version Update List (still trying to come up with good changelog policy)

Ver 0.0.2.4 -> Updated on 2026-11-02 (yyyy/mm/dd). :

• Fixed an issue with the Type Table. Ground had a 2x modifier on Ice. Corrected and updated.​
• Fixed some regulation imports​
• Updated Github Repository with more files for easier installation​
• Added minimal damage roll of 1 on attacks that do not have immunities (the nerd-of-now calculator did not have this functionality)​
• Other minor changes and fixes. Updated to both GitHub and PyPI (ver 0.0.2.4)​

Ver 0.0.2.5 -> Updated on 2026-11-02 (yyyy/mm/dd). :

• Fixed some circular imports and other issues preventing examples.py from working properly on fresh installation.​