Contribution Guide - ds-pokemon-hacking/White2Upgrade GitHub Wiki

If you would like to contribute to this project, see below for instructions.

Contribution Rules

  • Be nice. We're all working together to create something great, let's also be great to each other in the process.
  • Absolutely no leaked source code, even if it is sanitized, should be used to complete this project. No exceptions.
  • Before your changes are merged, the changes you make must be thoroughly tested to prevent regressions wherever possible, and verified against a clean build. In other words, your changes should not break the game, and should be consistent from a completely fresh build (as if one was to clone the repo for the first time and build it, or run make clean then build the project).

Getting Started

The repository can be found here. Setup instructions can be found here

Directory Structure (subject to change)

  • data: Data that should end up in the game's ROMFS.
  • include: dependencies and header files that are used by files in src.
  • pmc: A prepatched version of PMC, our dynamic code loader, along with the files that are needed to use it. These files are for White 2, but can be supplanted with the corresponding patched ones from Black 2. At some point, the build process will be rewritten to directly patch the ARM9 of a supplied ROM with it, rather than just replacing the ARM9 with a prepatched version.
  • src: The source code for all of the patches. When building, these patches are compiled/assembled and linked together, creating a DLL for use with PMC. tools: The tools used as part of the build process for White2Upgrade. See the Makefile/*.mk files for where they are used.

Asset Formatting

Pokémon Battle Sprites

Brief

In Generation V, battle animation sprites are comprised of the following types of files:

  • NCLR, which is a set of colors that are used in the graphics.
  • NCGR, which is the sprite sheet that the game will render.
  • NCER, which defines the individual objects, or cells, that can later be stitched together to make animations. Cells are effectively bounding boxes that are used in tandem with the NCGR to create frames from a sprite sheet.
  • NANR, which defines cell animations. This allows you to stitch multiple cells together to create an animation (aka stitching multiple frames together). A common application of this would be selecting multiple cells that represent a single part going through an animation (such as a hand throwing a Pokéball), then ordering them such that the animation for that part plays out correctly.
  • NMCR, which defines a combination of cell animations (known as a multicell). This is where the animations defined in the NANR are stitched together to create a full animation. For example, this is often a combination of all body part animations for a Pokémon.
  • NMAR, which defines an animation based on the multicells/cell combinations. This is usually used for switching between multiple animation groups (for example, a Pokémon doing a special action after its main animation completes).
  • Sprite Collection (which specifies bounding boxes of the cells, amongst other things).

The game will load the aforementioned assets, and stitch them together at runtime to create the moving sprites that we all know and love. That being said, because this project is using the existing system, these types of files are required to be generated for sprites.

For the majority of Pokémon (as in, non-form Pokémon), 20 files are required to make a proper sprite entry.

  • 9 of them are the assets for the front sprite.
  • 9 of them are the assets for the back sprite.
  • 2 of them are the normal and shiny palettes, respectively.

Because of this, ARC 004 (which contains the Pokémon sprites) can be manually indexed fairly easily. The start of the $x$'th Pokémon's sprite files, $s_i(x)$, can be found with the following formula: $s_i(x) = 20 \times x$. In other words, for a given Pokémon dex number $x$, $20 \times x$ will get you the starting index of the Pokémon's sprite files within ARC 004. This formula does not include forms, as they are currently stored at the end of the NARC.

That being said, relative to the $x$'th Pokémon's starting entry (aka $20 \times x + b$, where $b$ is the relative file index specified below in the format "File $b$"), these are the files that are used:

Front Sprite

  • File 0: An LZ11-compressed NCGR that contains a 1D mapped static sprite(?).
  • File 1: Gender variation of ^, can be left empty.
  • File 2: An LZ11-compressed NCGR that contains a 2D mapped graphic. This graphic should contain sprite fragments that are to be used in creating the final sprite animation.
  • File 3: Gender variation of ^, can be left empty.
  • File 4: An NCER that contains the definitions for each sprite frame.
  • File 5: An NANR that contains the sprite frame animations.
  • File 6: A NMCR that contains the multicell definitions/animation combinations.
  • File 7: A NMAR that contains the order of animation combinations to display.
  • File 8: The "Sprite Collection" transformation file, used to define cell cropping.

Back Sprite

  • File 9: An LZ11-compressed NCGR that contains a compressed static sprite(?).
  • File 10: Gender variation of ^, can be left empty.
  • File 11: An LZ11-compressed NCGR that contains a 2D mapped graphic. This graphic should contain sprite fragments that are to be used in creating the final sprite animation.
  • File 12: Gender variation of ^, can be left empty.
  • File 13: An NCER that contains the definitions for each sprite frame.
  • File 14: An NANR that contains the sprite frame animations.
  • File 15: A NMCR that contains the multicell definitions/animation combinations.
  • File 16: A NMAR that contains the order of animation combinations to display.
  • File 17: The "Sprite Collection" transformation file, used to define cell cropping.

Both Sprites

  • File 18: The NCLR that contains the Normal color palette.
  • File 19: The NCLR that contains the Shiny color palette.

Creating

  • To create the sprite sheet, you can utilize a sprite editor such as LibreSprite, aseprite, or similar.
  • To convert the sprites into the game format, you can utilize NitroPaint and d5 utils to generate the corresponding Nitro formats. Note: For files that need to be LZ11 compressed, you must do so using a tool such as DSDecmp.

See the submission format below for exactly what files you want to generate.

Submitting

To contribute sprites to White2Upgrade, follow the below instructions. Note: These instructions may change depending on build system requirements.

  1. Create the aforementioned files. In short, you should have the following files ready to go (this is just an example listing to illustrate the point):
- File 0: 000_static_front_sprite_1d.ncgr.lz
- File 1: 001_static_front_sprite_1d_variation.ncgr.lz (can be empty)
- File 2: 002_front_sprite_sheet_2d.ncgr.lz
- File 3: 003_front_sprite_sheet_2d_variation.ncgr.lz  (can be empty)
- File 4: 004_front_sprite_cell_definitions.ncer
- File 5: 005_front_sprite_cell_animations.nanr
- File 6: 006_front_sprite_multicells.nmcr
- File 7: 007_front_sprite_multicell_animations.nmar
- File 8: 008_front_sprite_collection.bin
- File 9: 009_static_back_sprite_1d.ncgr.lz
- File 10: 010_static_back_sprite_1d_variation.ncgr.lz  (can be empty)
- File 11: 011_back_sprite_sheet_2d.ncgr.lz
- File 12: 012_back_sprite_sheet_2d_variation.ncgr.lz  (can be empty)
- File 13: 013_back_sprite_cell_definitions.ncer
- File 14: 014_back_sprite_cell_animations.nanr
- File 15: 015_back_sprite_multicells.nmcr
- File 16: 016_back_sprite_multicell_animations.nmar
- File 17: 017_back_sprite_collection.bin
- File 18: 018_normal_palette.nclr
- File 19: 019_shiny_palette.nclr
  1. Based on the national dex index of the Pokémon these sprites are for, rename the files you generated in step 1 according to the following format: 004_<20 * x, padded to 8 digits total>.bin.

For example, if I wanted to replace the files for Pokémon dex number 20 (reminder that $20 \times 20 = 400$), the new files I would have would be:

004_00000400.bin
004_00000401.bin
004_00000402.bin
004_00000403.bin
004_00000404.bin
004_00000405.bin
004_00000406.bin
004_00000407.bin
004_00000408.bin
004_00000409.bin
004_00000410.bin
004_00000411.bin
004_00000412.bin
004_00000413.bin
004_00000414.bin
004_00000415.bin
004_00000416.bin
004_00000417.bin
004_00000418.bin
004_00000419.bin
  1. Fork White2Upgrade, and clone it locally.
  2. Drag these files into the folder White2Upgrade/data/graphics/pokegra/battle_sprites in your White2Upgrade fork, replacing if necessary.
  3. Build White2Upgrade, and verify that the files you added work correctly in game and are to your liking.
  4. When ready, commit your changes then make a pull request.