Bitbucket is a code hosting site with unlimited public and private repositories. We're also free for small teams!

Close

PyPKM - Pokémon File Manipulation

Introduction

PyPKM is a Python package for creating, editing, and manipulating individual Pokémon file data (commonly referred to as PKM or .pkm files). The goal of this project is to allow a cross-platform way to easily work with these files.

PyPKM supports generation IV and generation V PKM files.

Installation

To install PyPKM, download and unarchive the package from its git repository. Then, you can either cd into the newly-created directory and run python setup.py install to install in your global Python path, or you can enter the directory and manually copy the pypkm subdirectory to a place in your Python path. PyPKM requires Construct==2.06 to parse file data.

Usage

First, import the pypkm package:

>>> import pypkm

Then, create or load a PKM file (making sure to specify the file's game generation):

# Create from scratch
>>> my_pkm = pypkm.new(gen=4)

# Load from data
>>> pkm_data = open('/path/to/MyPokemon.pkm', 'r').read()
>>> my_pkm = pypkm.load(gen=4, data=pkm_data)

From here, you can edit your Pokémon's data by calling attributes of the my_pkm instance. For example, to give your Pokémon the Leftovers item to hold:

>>> my_pkm.item = 234

To teach your Pokémon the Roar of Time move:

>>> my_pkm.moves.move1 = 459

To see your Pokémon trainer's secret ID:

>>> my_pkm.ot_secret_id
65534

You might even want to change your Pokémon's species all together:

>>> my_pkm.id = 94

As you can tell, you need to know the correct index number for most editing. A proper API reference will be made available in time. Until then, refer to the Struct declaration in pypkm.structs.

If you have GTS data, you can edit that as well:

>>> gts_data = open('/path/to/gts_pkm.pkm.proper', 'r').open()
>>> proper_pkm = pypkm.load(gen=4, data=gts_data)

>>> proper_pkm.level
5

>>> proper_pkm.ot_name
u'Trainer'

PyPKM also handles converting data. You can convert PC box data to party data, to/from GTS server-sent data, and to/from GTS client-sent data. The list of conversion methods are as follows:

  • .togen5() - converts Gen 4 data to Gen 5
  • .toparty() - adds battle data
  • .togtsserver() - converts to data sent by the GTS server
  • .togtsclient() - converts to data sent by the DS
  • .topkm() - converts GTS data to a Pkm object

If you've edited the data, you probably want to save. PyPKM does not handle saving data; you must save the file yourself. However, to convert an object into a string of byte data:

# you can call tostring() to return byte data
>>> my_pkm.tostring()

Contribute

If you'd like to contribute, you can do so at my git repository. I'd love to hear any bugs or feature requests you have.

Thanks

The folks at Project Pokemon for all of their research into the structure of Pokémon data.

maxg for answering my questions.

Veekun for looking over my code, introducing me to Construct, and providing an awesome database of Pokémon information.

Stephen Anthony Uy for his pycrypto module. Somehow I came across this module whilst looking for a way to encrypt and decrypt Pokémon data, and it's been a huge help (the shuffle() function comes directly from his work).

Recent activity

ceol

Commits by ceol were pushed to ceol/pypkm

e1e37c2 - removed gen 1,2,3 structs/adapters for the time being
ceol

Commits by ceol were pushed to ceol/pypkm

96afea5 - removed unnecessary shuffling of party data
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.