Forking a FLOSS Pokemon Project


  • frontier-team-builder
  • Jonathan Haack
  • Haack’s Networking
  • webmaster@haacksnetworking.org

//frontier-team-builder//


Latest Updates: https://wiki.haacksnetworking.org/doku.php?id=projects:frontier-team-builder

This tutorial is designed for users of Debian GNU/Linux who wish to self-host a version of PvPoke.com, an MIT licensed Pokémon GO project designed by KakunaMatata. The primary purposes of PvPoke.com are to allow lovers of the game to build a collection of Pokémon suited for battle, called a battle party and to provide rankings on Pokémon for particular cups, called metas. In my case, I run two Discord ‘servers’ dedicated to Pokémon battling and both communities have teams that I lead which create custom metas and then host Swiss tournaments (both team and individual) for these metas. A project like PvPoke.com provides a lot of value. It allows our meta development team to create well-built metas and helps participating trainers build battle parties that are well-suited for the associated tournaments that leverage those metas. For this reason, we decided to fork the project so that our meta team could use a development version to design future metas and a white-labeled and stripped down production version that would help our participants build for and participate in those metas. Additionally, I’ve developed a set of automated bash scripts, production readying/hardening steps, steps for maintaining, updating, and pulling from upstream for both the development and production isntances. Finally, I’ve also developed documentation on how to use the original project and/or our development and production versions that serve other grassroots Pokémon GO communities interested in doing something similar. The official project is maintained in a self-hosted Gitlab instance over at:


Now that you understand the context, the first step is to ensure you have a secure VPS accessible with ssh, a FEMP/LAMP stack or equivalent w/ LTS setup, and that you understand the basics of server hardening and/or management of services for public facing instances. If you do not, please begin by reading Apache Survival and then hit me up for next steps. So long as you have those in place, our first step is to clone the repository and then create a redirect rule. The redirect rule redirects traffic to the webroot to the sub-directory that the development project expects (and is also, for security reasons, hard coded to fail if/when it does not exist). Don’t worry, we’ll protect and/or harden both the development and production instances later in the tutorial. Henceforward my tutorial will assume Debian GNU/Linux and a LAMP stack; adjust accordingly for other stacks.

ssh root@domain.com
cd /var/www/development.domain.com/public_html/
cd /var/www/production.domain.com/public_html/
git clone https://github.com/pvpoke/pvpoke.git
sudo chmod -R 777 /var/www/development.domain.com/public_html/pvpoke/src/
sudo nano /etc/apache2/sites-available/development.domain.com.conf
sudo nano /etc/apache2/sites-available/production.domain.com.conf

Add the following the RedirectMatch rules just below DocumentRoot in both virtual host configuration files:

RedirectMatch ^/$ /pvpoke/src

This redirect is simple, stating that anything that requests *.domain.com be redirected to builder.domain.com/src/data. Next, let’s make sure to require authentication for the development version so that it is not accessible to the general public. We’ll create two different users, one for the webmaster and another for the team:

sudo htpasswd -c /etc/apache2/.security webmaster
sudo htpasswd /etc/apache2/.security devteam

Now, let’s activate these credentials by adjusting .htaccess as follows. Additionally, since this is public facing, let’s also uncomment the https redirect that’s already present in the .htaccess file.

sudo nano /var/www/development.domain.com/public_html/pvpoke/src/.htaccess

Find the following lines and un-comment them:

RewriteCond %{HTTPS} !=on
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]

If you are also using the www subdomain then un-comment those too (I am not). Next, at the very bottom of the file, add the following:

AuthType Basic
AuthName 'Please authenticate:'
AuthUserFile /etc/apache2/.security
Require valid-user

This takes care of password protecting the development instance and ensuring that LTS is enforced for all url requests. After that, it’s now time to set permissions for the production instance. To do that, let’s ensure we have some common read/write/execute permissions on the instance. These are recommendations and took me about 1-2 hours of code review to decide a) what was needed for things to function and b) what we could restrict without harming functionality. Here’s the script I came up with; make sure to adjust for the ”domain.com” and other settings unique to your workflow:

Next, we need to harden the production instance and/or optionally white-label it. To harden, we remove the development cog from footer.php and make write.php an empty file. Here’s the changes we made:

Now, the repository also has the ability to store overrides on moves and custom meta groups, however, this is optional and more of a choice specific to each meta development team.


At this point, the development and production virtual hosts are created, secured sufficiently, and/or optionally customized. From this point forward, the tutorial is no longer about how to set up the instances, but rather how to leverage those instances to create metas on the development instance and then migrate those development changes to production. In order to do this, one needs to have detailed understanding of how the upstream code from pvpoke.com works. For me, this took weeks of studying the code with a colleague of mine at Antimatter.GG gaming, meetings with the head developer of pvpoke.com, and a bit of trial and error. Once that was done, I created two scripts. The first one creates the pre-requisite back-end files needed for the creation of a new meta on the development instance, and the second one merges the metas you created in development back to production while preserving aforementioned white-labeling and hardening. Below, I’ve included the wiki post KakunaMatata made about how his stack works, the pre-requisite file creation script, and the merge to production script:

The scripts above assume a detailed understanding of the upstream code. The scripts above create the files needed for metas and migrate those from development to production. There are micro tasks involved that require independent study and expertise and are presumed levels of understanding for the intended audience. At this point in the tutorial, you should know how to create a development and production instance, create metas within the development instance, and migrate those changes to production.


At this point, we now need to know how to pull changes from upstream. If you are not familiar with the community, you might be wondering what changes we would be pulling. In addition to coding and/or optimizations that KakunaMatata might make to the stack, he also pushes changes that are global to the game including but not limited to move additions, move nerfs, move buffs, and/or other changes. These changes impact the relative ranking and simulated combinations that the meta and battle party features of the upstream project and fork utilize. In short, since the development instance is a git repository, teams need to pull the changes, resolve conflicts, and then merge those to production. Here are the steps from top to bottom for creating a meta, and then later updating the instance to reflect the new changes to the underlying Pokemon moves.


This should help any teams desiring to make a development and production instance and/or fork of PvPoke.com. Now, some meta developers might want to just create a locally hosted version and want to know how to create metas with as little fuss and muss as possible. If that’s so, then install the latest version of pvpoke.com to your localhost webroot. Once that’s done, change, create, and/or edit the following files according to how pvpoke.com works:

src/data/gamemaster/cups/name.json
src/data/gamemaster/formats.json [make sure no comma at end]
src/data/rankings/name/attackers/rankings-1500.json
src/data/rankings/name/chargers/rankings-1500.json
src/data/rankings/name/closers/rankings-1500.json
src/data/rankings/name/consistency/rankings-1500.json
src/data/rankings/name/leads/rankings-1500.json
src/data/rankings/name/overall/rankings-1500.json
src/data/rankings/name/switches/rankings-1500.json
src/data/groups/name/name.json [just put in top 100 from a simple sim]
src/data/overrides/name/1500.json [just leave [] at start]

Once these are created, do the following in the web GUI (under the development cog):

  1. compile (with group put in from step 10 above)
  2. override moves, import movesets, copy json to 11 above
  3. compile again
  4. ranker, simulate
  5. rankersandbox, simulate

Bear in mind, these are highly condensed instructions which assume knowledge of the underlying upstream code, familiarity with KakunaMatata’s wiki and meta development steps, and more. If you have questions, just reach out! Happy to help!


The next task is to make a php/json front end GUI version that allows our meta team to do all this with web-based tools! If you would like to view the repositories, just send me an email at jonathan@haacksnetworking.org. Oh yeah, to see our production instance, head over to:

Happy Hacking
-oemb1905

Leave a Reply

Your email address will not be published. Required fields are marked *

Close
JavaScript licenses