pokeemerald-expansion

Important: DO NOT use GitHub's "Download Zip" option. Using this option will not download the commit history required to update your expansion version or merge other feature branches. Instead, please read this guide to learn how to fork the repository and clone locally from there.

What is pokeemerald-expansion?

pokeemerald-expansion is a decomp hack base project based off pret's pokeemerald decompilation project. It's recommended that any new projects that plan on using it, to clone this repository instead of pret's vanilla repository, as we regurlarly incorporate pret's documentation changes. This is NOT a standalone romhack, and as such, most features will be unavailable and/or unbalanced if played as is.

If you use pokeemerald-expansion in your hack, please add RHH (Rom Hacking Hideout) to your credits list. Optionally, you can list the version used, so it can help players know what features to expect. You can phrase it as the following:

Based off RHH's pokeemerald-expansion v1.8.0 https://github.com/rh-hideout/pokeemerald-expansion/

What features are included?

IMPORTANT❗❗ Read through these to learn what features you can toggle:
Upgraded battle engine.
- Gen5+ damage calculation.
- 2v2 Wild battles support.
- 1v2/2v1 battles support.
- Fairy Type (configurable).
- Physical/Special/Status Category (configurable).
- New moves and abilities up to Scarlet and Violet.
  - Custom Contest data up to SwSh, newer moves are WIP. (source)
- Battle gimmick support:
  - Mega Evolution
  - Primal Reversion
  - Ultra Burst
  - Z-Moves
    - Gen 8+ damaging moves are given power extrapolated from Gen 7.
    - Gen 8+ status moves have no additional effects, like Healing Wish.
  - Dynamax and Gigantamax
- Initial battle parameters
  - Queueing stat boosts (aka, Totem Boosts)
  - Setting Terrains.
- Mid-turn speed recalculation.
- Quick Poké Ball selection in Wild Battles
  - Hold R to change selection with the D-Pad.
  - Press R to use last selected Poké Ball.
- Run option shortcut
- Faster battle intro - Message and animation/cry happens at the same time.
- Faster HP drain.
- Battle Debug menu.
  - Accessed by pressing Select on the "Fight/Bag/Pokémon/Run" menu.
- Option to use AI flags in wild Pokémon battles.
- FRLG/Gen4+ whiteout money calculation.
- Configurable experience settings
  - Experience on catch.
  - Splitting experience.
  - Trainer experience.
  - Scaled experience.
  - Unevolved experience boost.
- Frostbite.
  - Doesn't replace freezing unless a config is enabled, so you can mix and match.
- Critical capture.
- Removed badge boosts (configurable).
- Recalculating stats at the end of every battle.
- Level 100 Pokémon can earn EVs.
- Inverse battle support.
- TONS of other features listed here.
Full Trainer customization
- Nickname, EVs, IVs, moves, ability, ball, friendship, nature, gender, shininess.
- Custom tag battle support (teaming up an NPC in a double battle).
- Sliding trainer messages.
- Upgraded Trainer AI
  - Considers newer move effects.
  - New flag options to let you customize the intelligence of your trainers.
  - Faster calculations.
- Specify Poké Balls by Trainer class.
Pokémon Species from Generations 1-9.
- Simplified process to add new Pokémon.
- Option to disable unwanted families.
- Updated sprites to DS style.
- Updated stats, types, abilities and egg groups (configurable).
- Updated Hoenn's Regional Dex to match ORAS' (configurable).
- Updated National Dex incorporating the new species.
- Sprite and animation visualizer.
  - Accesible by pressing Select on a Pokémon's Summary screen.
- Gen4+ evolution methods, with some changes:
  - Mossy Rock, Icy Rock and Magnetic Field locations match ORAS'.
    - Leaf, Ice and Thunder Stones may also be used.
  - Inkay just needs level 30 to evolve.
    - You can't physically have both the RTC and gyroscope, so we skip this requirement.
  - Sylveon uses Gen8+'s evolution method (friendship + Fairy Move).
  - Option to use hold evolution items directly like stones.
- Hidden Abilities.
  - Available via Ability Patch.
  - Compatible with Ghoul's DexNav branch.
- All gender differences.
  - Custom female icons for female Hippopotas Hippowdon, Pikachu and Wobbufett
- 3 Perfect IVs on Legendaries, Mythicals and Ultra Beasts.
Customizable form change tables. Full list of methods here.
- Item holding (eg. Giratina/Arceus)
- Item using (eg. Oricorio)
  - Time of day option for Shaymin
- Fainting
- Battle begin and end (eg. Xerneas)
  - Move change option for Zacian/Zamazenta
- Battle end in terrains (eg. Burmy)
- Switched in battle (eg. Palafin)
- HP Threshold (eg. Darmanitan)
- Weather (eg. Castform)
- End of turn (eg. Morpeko)
- Time of day (eg. Shaymin)
- Fusions (eg. Kyurem)
Breeding Improvements
- Incense Baby Pokémon now happen automatically (configurable).
- Level 1 eggs (configurable).
- Poké Ball inheriting (configurable).
- Egg Move Transfer, including Mirror Herb (configurable).
- Nature inheriting 100% of the time with Everstone (configurable)
- Gen6+ Ability inheriting (configurable).
Items from newer Generations. Full list here.
- Gen 6+ Exp. Share (configurable)
- Berserk Gene
- Most battle items from Gen 4+
- Existing item data but missing effects:
  - Gimmighoul Coin
  - Booster Energy
  - Tera Shards
  - Tera Orb
Feature branches incorporated (with permission):
- RHH intro credits by @Xhyzi.
  - A small signature from all of us to show the collective effort in the project :)
- Overworld debug by @TheXaman
  - May be disabled.
  - Accesible by pressing R + Start in the overworld by default.
  - Additional features:
    - Clear Boxes: cleans every Pokémon from the Boxes.
    - Hatch an Egg: lets you choose an Egg in your party and immediately hatch it.
- HGSS Pokédex by @TheXaman
  - May be disabled.
  - Additional features:
    - Support for new evolution methods.
    - Dark Mode.
- Nature Colors in summary screen by @DizzyEggg
- Dynamic Multichoice by @SBird1337
- Saveblock Cleansing by @ghoulslash
Other features
- Pressing B while holding a Pokémon drops them like in modern games (configurable).
- Running indoors (configurable).
- Configurable overworld poison damage.
- Configurable flags for disabling Wild encounters and Trainer battles.
- Configurable flags for forcing or disabling Shinies.
- Reusable TM (configurable).
- B2W2+ Repel system that also supports LGPE's Lures
- Gen6+'s EV cap.
- All bugfixes from pret included.
- Fixed overworld snow effect.

There are some mechanics, moves and abilities that are missing and being developed. Check the project's milestones to see which ones.

Documentation on features can be found here

If I already have a project based on regular pokeemerald, can I use pokeemerald-expansion?

Yes! Keep in mind that we keep up with pret's documentation of pokeemerald, which means that if your project a bit old, you might get merge conflicts that you need to solve manually.

If you haven't set up a remote, run the command git remote add RHH https://github.com/rh-hideout/pokeemerald-expansion.
Once you have your remote set up, run the command git pull RHH master.

With this, you'll get the latest version of pokeemerald-expansion, plus a couple of bugfixes that haven't been released into the next patch version :)

How do I update my version of pokeemerald-expansion?

If you haven't set up a remote, run the command git remote add RHH https://github.com/rh-hideout/pokeemerald-expansion.
Check your current version.
- You can check in the debug menu's Utilities -> Expansion Version option.
- If the option is not available, you possibly have version 1.6.2 or older. In that case, please check the changelogs to determine your version based on the features available on your repository.
Once you have your remote set up, run the command git pull RHH expansion/X.Y.Z, replacing X, Y and Z with the digits of the respective version you want to update to (eg, to update to 1.8.4, use git pull RHH expansion/1.8.4).
- Important: If you are several versions behind, we recommend updating one minor version at a time, skipping directly to the latest patch version (eg, 1.5.3 -> 1.6.2 -> 1.7.4 and so on)
Alternatively, you can update to unreleased versions of the expansion.
- master (stable): It contains unreleased bugfixes that will come in the next patch version. To merge, use git pull RHH master.
- upcoming (unstable, with potential bugs): It contains unreleased features that will come in the next minor version. To merge, use git pull RHH upcoming.

Please consider crediting the entire list of contributors in your project, as they have all worked hard to develop this project :)

There's a bug in the project. How do I let you guys know?

Please submit any issues with the project here. Make sure that the issue wasn't reported by someone else by searching using the filters.

Can I contribute even if I'm not a member of ROM Hacking Hideout?

Yes! Contributions are welcome via Pull Requests and they will be reviewed by maintainers. Don't feel discouraged if we take a bit to review your PR, we'll get to it.

Who maintains the project?

The project was originally started by DizzyEgg alongside other contributors.

The project has now gotten larger and DizzyEgg is now maintaining the project as part of the ROM Hacking Hideout community. Some members of this community are taking on larger roles to help maintain the project.

What is the ROM Hacking Hideout?

A Discord-based ROM hacking community that has many members who hack using the disassembly and decompilation projects for Pokémon. Quite a few contributors to the original feature branches by DizzyEgg were members of ROM Hacking Hideout. You can call it RHH for short!

Click here to join the RHH Discord Server!

Instructions

These instructions explain how to set up the tools required to build pokeemerald Expansion, which assembles the source files into a ROM (pokeemerald.gba).

These instructions come with notes which can be expanded by clicking the "Note..." text. In general, you should not need to open these unless if you get an error or if you need additional clarification.

If you run into trouble, ask for help on Discord or IRC (see README.md).

Windows

Windows has instructions for building with three possible terminals, providing 3 different options in case the user stumbles upon unexpected errors.

Windows 10/11 (WSL1) (Fastest, highly recommended, Windows 10 and 11 only)
Windows (msys2) (Second fastest)
Windows (Cygwin) (Slowest)

Unscientific benchmarks suggest msys2 is 2x slower than WSL1, and Cygwin is 5-6x slower than WSL1.

Note for advanced users: WSL2...

WSL2 is an option and is even faster than WSL1 if files are stored on the WSL2 file system, but some tools may have trouble interacting with the WSL2 file system over the network drive. For example, tools which use Qt versions before 5.15.2 such as porymap may have problems with parsing the \wsl$ network drive path.

All of the Windows instructions assume that the default drive is C:\. If this differs to your actual drive letter, then replace C with the correct drive letter when reading the instructions.

A note of caution: As Windows 7 is officially unsupported by Microsoft and Windows 8 has very little usage, some maintainers are unwilling to maintain the Windows 7/8 instructions. Thus, these instructions may break in the future with fixes taking longer than fixes to the Windows 10 instructions.

Windows 10/11 (WSL1)

WSL1 is the preferred terminal to build pokeemerald Expansion. The following instructions will explain how to install WSL1 (referred to interchangeably as WSL).

If WSL (Debian or Ubuntu) is not installed, then go to Installing WSL1.
Otherwise, if WSL is installed, but it hasn't previously been set up for another decompilation project, then go to Setting up WSL1.
Otherwise, open WSL and go to Choosing where to store pokeemerald Expansion (WSL1).

Installing WSL1

Open Windows Powershell as Administrator, and run the following command (Right Click or Shift+Insert is paste in the Powershell).
```
dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
```
Once the process finishes, restart your machine.
The next step is to choose and install a Linux distribution from the Microsoft Store. The following instructions will assume Ubuntu as the Linux distribution of choice.

Note for advanced users...

You can pick a preferred Linux distribution, but setup instructions may differ. Debian should work with the given instructions, but has not been tested.
Open the Microsoft Store Linux Selection, click Ubuntu, then click Get, which will install the Ubuntu distribution.

Notes...

Note 1: If a dialog pops up asking for you to sign into a Microsoft Account, then just close the dialog. Note 2: If the link does not work, then open the Microsoft Store manually, and search for the Ubuntu app (choose the one with no version number).

Setting up WSL1

Some tips before proceeding:

In WSL, Copy and Paste is either done via
- right-click (selection + right click to Copy, right click with no selection to Paste)
- Ctrl+Shift+C/Ctrl+Shift+V (enabled by right-clicking the title bar, going to Properties, then checking the checkbox next to "Use Ctrl+Shift+C/V as Copy/Paste").
Some of the commands that you'll run will ask for your WSL password and/or confirmation to perform the stated action. This is to be expected, just enter your WSL password and/or the yes action when necessary.

Open Ubuntu (e.g. using Search).
WSL/Ubuntu will set up its own installation when it runs for the first time. Once WSL/Ubuntu finishes installing, it will ask for a username and password (to be input in).

Note...

When typing in the password, there will be no visible response, but the terminal will still read in input.
Update WSL/Ubuntu before continuing. Do this by running the following command. These commands will likely take a long time to finish:
```
sudo apt update && sudo apt upgrade
```

Note: If the repository you plan to build has an older revision of the INSTALL.md, then follow the legacy WSL1 instructions from here.

Certain packages are required to build pokeemerald Expansion. Install these packages by running the following command:
```
sudo apt install build-essential binutils-arm-none-eabi gcc-arm-none-eabi libnewlib-arm-none-eabi git libpng-dev
```
Note...

If the above command does not work, try the above command but replacing apt with apt-get.

This will install GCC v10 on Ubuntu 22.04. pokeemerald Expansion works with GCC v10, but remote repositories and the RHH Team use GCC v13 for stricter error-checking. If you want to upgrade from v10 to v13, also follow the devkitpro install instructions.

Installing devkitARM on WSL1

Change directory to somewhere you can download a package, such as C:\Users\<user>\Downloads (the Downloads location for most users). To do so, enter this command, where *<user> is your Windows username:
```
cd /mnt/c/Users/<user>/Downloads
```
Once the directory has been changed, run the following commands to install devkitARM.
```
sudo apt install wget
wget https://apt.devkitpro.org/install-devkitpro-pacman
chmod +x ./install-devkitpro-pacman
sudo ./install-devkitpro-pacman
sudo dkp-pacman -S gba-dev
```
The last command will ask for the selection of packages to install. Just press Enter to install all of them, followed by entering Y to proceed with the installation.
Run the following command to set devkitPro related environment variables (alternatively, close and re-open WSL):
```
source /etc/profile.d/devkit-env.sh
```

devkitARM is now installed.

Installing Python on WSL1

To install Python on WSL1, simply run the following commands:

sudo apt update && sudo apt upgrade
sudo apt install python3

Python is now installed.

Choosing where to store pokeemerald Expansion (WSL1)

WSL has its own file system that's not natively accessible from Windows, but Windows files are accessible from WSL. So you're going to want to store pokeemerald Expansion within Windows.

For example, say you want to store pokeemerald Expansion in C:\Users\<user>\Desktop\decomps. First, ensure that the folder already exists. Then, enter this command to change directory to said folder, where <user> is your Windows username:

cd /mnt/c/Users/<user>/Desktop/decomps

Notes...

Note 1: The Windows C:\ drive is called /mnt/c/ in WSL. Note 2: If the path has spaces, then the path must be wrapped with quotations, e.g. cd "/mnt/c/users/<user>/Desktop/decomp folder". Note 3: Windows path names are case-insensitive so adhering to capitalization isn't needed

If this works, then proceed to Installation.

Otherwise, ask for help on Discord or IRC (see README.md), or continue reading below for Windows instructions using msys2.

Windows (msys2)

If devkitARM is not installed, then go to Installing devkitARM.
If devkitARM is installed, but msys2 hasn't previously been set up for another decompilation project, then go to Setting up msys2.
Otherwise, open msys2 and go to Choosing where to store pokeemerald Expansion (msys2).

Installing devkitARM

Download the devkitPro installer here.
Run the devkitPro installer. In the "Choose Components" screen, uncheck everything except GBA Development unless if you plan to install other devkitPro components for other purposes. Keep the install location as C:\devkitPro and leave the Start Menu option unchanged.

Setting up msys2

Note that in msys2, Copy is Ctrl+Insert and Paste is Shift+Insert.

Open msys2 at C:\devkitPro\msys2\msys2_shell.bat.
Certain packages are required to build pokeemerald Expansion. Install these by running the following two commands:
```
pacman -Sy msys2-keyring
pacman -S make gcc zlib-devel git
```
Note...

The commands will ask for confirmation, just enter the yes action when prompted.
Download libpng.
Change directory to where libpng was downloaded. By default, msys2 will start in the current user's profile folder, located at C:\Users\⁠<user>, where <user> is your Windows username. In most cases, libpng should be saved within a subfolder of the profile folder. For example, if libpng was saved to C:\Users\<user>\Downloads (the Downloads location for most users), enter this command:
```
cd Downloads
```
Notes...

Note 1: While not shown, msys uses forward slashes / instead of backwards slashes \ as the directory separator. Note 2: If the path has spaces, then the path must be wrapped with quotations, e.g. cd "Downloads/My Downloads". Note 3: Windows path names are case-insensitive so adhering to capitalization isn’t needed. Note 4: If libpng was saved elsewhere, you will need to specify the full path to where libpng was downloaded, e.g. cd c:/devkitpro/msys2 if it was saved there.

Run the following commands to uncompress and install libpng.

tar xf libpng-1.6.37.tar.xz
cd libpng-1.6.37
./configure --prefix=/usr
make check
make install

Then finally, run the following command to change back to the user profile folder.
```
cd
```

Installing Python on msys2

To install Python on msys2, simply run the following commands:

pacman -S mingw-w64-x86_64-python3

Python is now installed.

Choosing where to store pokeemerald Expansion (msys2)

At this point, you can choose a folder to store pokeemerald Expansion into. If you're okay with storing pokeemerald Expansion in the user profile folder, then proceed to Installation. Otherwise, you'll need to account for where pokeemerald Expansion is stored when changing directory to the pokeemerald-expansion folder.

For example, if you want to store pokeemerald Expansion in C:\Users\<user>\Desktop\decomps (where <user> is your Windows username), enter this command:

cd Desktop/decomps

If this works, then proceed to Installation.

Otherwise, ask for help on Discord or IRC (see README.md), or continue reading below for Windows instructions using Cygwin.

Windows (Cygwin)

If devkitARM is not installed, then follow the instructions used to install devkitARM for the msys2 setup before continuing. Remember to not continue following the msys2 instructions by mistake!
- If Cygwin is not installed, or does not have all of the required packages installed, then go to Installing Cygwin.
- If Cygwin is installed, but is not configured to work with devkitARM, then go to Configuring devkitARM for Cygwin.
- Otherwise, open Cygwin and go to Choosing where to store pokeemerald Expansion (Cygwin)

Installing Cygwin

Download Cygwin: setup-x86_64.exe for 64-bit Windows, setup-x86.exe for 32-bit.
Run the Cygwin setup. Within the Cygwin setup, leave the default settings until the "Choose A Download Site" screen.
At "Choose a Download Site", select any mirror within the Available Download Sites.
At "Select Packages", set the view to "Full" (top left) and search for the following packages:
- make
- git
- gcc-core
- gcc-g++
- libpng-devel
To quickly find these, use the search bar and type the name of each package. Ensure that the selected package name is the exact same as the one you're trying to download, e.g. cmake is NOT the same as make.
For each package, double click on the text that says "Skip" next to each package to select the most recent version to install. If the text says anything other than "Skip", (e.g. Keep or a version number), then the package is or will be installed and you don't need to do anything.
Once all required packages have been selected, finish the installation.

Configuring devkitARM for Cygwin

Note that in Cygwin, Copy is Ctrl+Insert and Paste is Shift+Insert.

Open Cygwin.

Run the following commands to configure devkitPro to work with Cygwin.

export DEVKITPRO=/cygdrive/c/devkitpro
echo export DEVKITPRO=$DEVKITPRO >> ~/.bashrc
export DEVKITARM=$DEVKITPRO/devkitARM
echo export DEVKITARM=$DEVKITARM >> ~/.bashrc

Note...

Replace the drive letter c with the actual drive letter if it is not c.

Choosing where to store pokeemerald Expansion (Cygwin)

Cygwin has its own file system that's within Windows, at C:\cygwin64\home\<user>. If you don't want to store pokeemerald Expansion there, you'll need to account for where ppokeemerald Expansion is stored when changing directory to the pokeemerald-expansion folder.

For example, if you want to store pokeemerald Expansion in C:\Users\<user>\Desktop\decomps, enter this command, where <user> is your Windows username:

cd c:/Users/<user>/Desktop/decomps

Note that the directory must exist in Windows. If you want to store pokeemerald Expansion in a dedicated folder that doesn't exist (e.g. the example provided above), then create the folder (e.g. using Windows Explorer) before executing the cd command.

Notes...

Note 1: If the path has spaces, then the path must be wrapped with quotations, e.g. cd "c:/users/<user>/Desktop/decomp folder". Note 2: Windows path names are case-insensitive so adhering to capitalization isn't needed

If this works, then proceed to Installation. Otherwise, ask for help on Discord or IRC (see README.md).

macOS

If the Xcode Command Line Tools are not installed, download the tools here, open your Terminal, and run the following command:
```
xcode-select --install
```
- If libpng is not installed, then go to Installing libpng (macOS).
- If pkg-config is not installed, then go to Installing pkg-config (macos).
- If devkitARM is not installed, then go to Installing devkitARM (macOS).
- Otherwise, open the Terminal and go to Choosing where to store pokeemerald Expansion (macOS)

Installing libpng (macOS)

Note for advanced users...

This guide installs libpng via Homebrew as it is the easiest method, however advanced users can install libpng through other means if they so desire.

Open the Terminal.
If Homebrew is not installed, then install Homebrew by following the instructions on the website.
Run the following command to install libpng.
```
brew install libpng
```
libpng is now installed.

Continue to Installing pkg-config (macOS) if pkg-config is not installed. Otherwise, continue to Installing devkitARM (macOS) if devkitARM is not installed.

If both pkg-config and devkitARM are already installed, go to Choosing where to store pokeemerald Expansion (macOS).

Installing pkg-config (macOS)

Note for advanced users...

This guide installs pkg-config via Homebrew as it is the easiest method, however advanced users can install pkg-config through other means if they so desire.

Open the Terminal.
If Homebrew is not installed, then install Homebrew by following the instructions on the website.
Run the following command to install libpng.
```
brew install pkg-config
```
pkg-config is now installed.

Continue to Installing devkitARM (macOS) if devkitARM is not installed, otherwise, go to Choosing where to store pokeemerald Expansion (macOS).

Installing devkitARM (macOS)

Download the devkitpro-pacman-installer.pkg package from here.
Open the package to install devkitPro pacman.
In the Terminal, run the following commands to install devkitARM:
```
sudo dkp-pacman -Sy
sudo dkp-pacman -S gba-dev
sudo dkp-pacman -S devkitarm-rules
```
The command with gba-dev will ask for the selection of packages to install. Just press Enter to install all of them, followed by entering Y to proceed with the installation.

After the tools are installed, devkitARM must now be made accessible from anywhere by the system. To do so, run the following commands:

export DEVKITPRO=/opt/devkitpro
echo "export DEVKITPRO=$DEVKITPRO" >> ~/.zshrc
export DEVKITARM=$DEVKITPRO/devkitARM
echo "export DEVKITARM=$DEVKITARM" >> ~/.zshrc

echo "if [ -f ~/.zshrc ]; then . ~/.zshrc; fi" >> ~/.zprofile

Note: Starting with macOS 10.15, the default Unix shell is now zsh. If you migrated from an older version of macOS, you might still be using bash. You can check my running echo $0 in the terminal.

If your terminal is using bash instead of zsh...

export DEVKITPRO=/opt/devkitpro
echo "export DEVKITPRO=$DEVKITPRO" >> ~/.bashrc
export DEVKITARM=$DEVKITPRO/devkitARM
echo "export DEVKITARM=$DEVKITARM" >> ~/.bashrc

echo "if [ -f ~/.bashrc ]; then . ~/.bashrc; fi" >> ~/.bash_profile

Installing Python (macOS)

Download the latest Python package from here.
Open the package to install Python.

Python is now installed.

Choosing where to store pokeemerald Expansion (macOS)

At this point, you can choose a folder to store pokeemerald Expansion into. If you're okay with storing pokeemerald Expansion in the user folder, then proceed to Installation. Otherwise, you'll need to account for where pokeemerald Expansion is stored when changing directory to the pokeemerald-expansion folder.

For example, if you want to store pokeemerald Expansion in ~/Desktop/decomps, enter this command to change directory to the desired folder:

cd Desktop/decomps

Note that the directory must exist in the folder system. If you want to store pokeemerald Expansion in a dedicated folder that doesn't exist (e.g. the example provided above), then create the folder (e.g. using Finder) before executing the cd command.

Note...

Note: If the path has spaces, then the path must be wrapped with quotations, e.g. cd "Desktop/decomp folder"

If this works, then proceed to Installation. Otherwise, ask for help on Discord or IRC (see README.md).

Linux

Open Terminal and enter the following commands, depending on which distro you're using.

Debian/Ubuntu-based distributions

Run the following command to install the necessary packages:

sudo apt install build-essential binutils-arm-none-eabi gcc-arm-none-eabi libnewlib-arm-none-eabi git libpng-dev

Then proceed to Choosing where to store pokeemerald Expansion (Linux).

Note for legacy repos...

If the repository you plan to build has an older revision of the INSTALL.md, then you will have to install devkitARM. Install all the above packages except for the arm-none-eabi packages, and follow the instructions to install devkitARM on Debian/Ubuntu-based distributions.

Installing devkitARM on Debian/Ubuntu-based distributions

Change directory to somewhere you can download a packages, like a Downloads folder. Then, run the following commands to install devkitARM:
```
wget https://apt.devkitpro.org/install-devkitpro-pacman
chmod +x ./install-devkitpro-pacman
sudo ./install-devkitpro-pacman
sudo dkp-pacman -S gba-dev
```
The last command will ask for the selection of packages to install. Just press Enter to install all of them, followed by entering Y to proceed with the installation.
Run the following command to set devkitPro related environment variables (alternatively, close and re-open the Terminal):
```
source /etc/profile.d/devkit-env.sh
```

devkitARM is now installed.

Arch Linux

Run this command as root to install the necessary packages:

pacman -S base-devel arm-none-eabi-binutils arm-none-eabi-gcc arm-none-eabi-newlib git libpng

Installing devkitARM on Arch Linux

Follow devkitPro's instructions to configure pacman to download devkitPro packages.
Install gba-dev: run the following command as root.
```
pacman -S gba-dev
```
This will ask for the selection of packages to install. Just press Enter to install all of them, followed by entering Y to proceed with the installation.
Run the following command to set devkitPro related environment variables (alternatively, close and re-open the Terminal):
```
source /etc/profile.d/devkit-env.sh
```

devkitARM is now installed.

Then proceed to Choosing where to store pokeemerald Expansion (Linux).

Other distributions

(Specific instructions for other distributions would be greatly appreciated!)

Try to find the required software in its repositories:
- gcc
- g++
- make
- git
- libpng-dev
Follow the instructions here to install devkitPro pacman. As a reminder, the goal is to configure an existing pacman installation to recognize devkitPro's repositories.
Once devkitPro pacman is configured, run the following commands:
```
sudo pacman -Sy
sudo pacman -S gba-dev
```
The last command will ask for the selection of packages to install. Just press Enter to install all of them, followed by entering Y to proceed with the installation.

Installing Python in Linux

Installing Python depends on your distribution, please refere to the instructions here.

Choosing where to store pokeemerald Expansion (Linux)

At this point, you can choose a folder to store pokeemerald Expansion into. If so, you'll have to account for the modified folder path when changing directory to the pokeemerald-expansion folder.

If this works, then proceed to Installation. Otherwise, ask for help on Discord or IRC (see README.md).

Installation

Note for Windows users...

Consider adding an exception for the pokeemerald-expansion and/or decomps folder in Windows Security using these instructions. This prevents Microsoft Defender from scanning them which might improve performance while building.

If pokeemerald Expansion is not already downloaded (some users may prefer to download pokeemerald Expansion via a git client like GitHub Desktop), run:
```
git clone https://github.com/rh-hideout/pokeemerald-expansion
```
Note for WSL1...
If you get an error stating fatal: could not set 'core.filemode' to 'false', then run the following commands:
```
cd
sudo umount /mnt/c
sudo mount -t drvfs C: /mnt/c -o metadata,noatime
cd <folder where pokeemerald-expansion is to be stored>
```
Where <folder where pokeemerald-expansion is to be stored> is the path of the folder where you chose to store pokeemerald Expansion. Then run the git clone command again.

Now you're ready to build pokeemerald Expansion.

Build pokeemerald Expansion

If you aren't in the pokeemerald-expansion directory already, then change directory to the pokeemerald-expansion folder:

cd pokeemerald-expansion

To build pokeemerald.gba (Note: to speed up builds, see Parallel builds):

make

If it has built successfully you will have the output file pokeemerald.gba in your project folder.

Note for Windows...

> If you switched terminals since the last build (e.g. from msys2 to WSL1), you must run `make clean-tools` once before any subsequent `make` commands.

Building guidance

Parallel builds

See the GNU docs and this Stack Exchange thread for more information.

To speed up building, first get the value of nproc by running the following command:

nproc

Builds can then be sped up by running the following command:

make -j<output of nproc>

Replace <output of nproc> with the number that the nproc command returned.

nproc is not available on macOS. The alternative is sysctl -n hw.ncpu (relevant Stack Overflow thread).

Other toolchains

To build using a toolchain other than devkitARM, override the TOOLCHAIN environment variable with the path to your toolchain, which must contain the subdirectory bin.

make TOOLCHAIN="/path/to/toolchain/here"

The following is an example:

make TOOLCHAIN="/usr/local/arm-none-eabi"

To compile the modern target with this toolchain, the subdirectories lib, include, and arm-none-eabi must also be present.

Building with debug info

To build pokeemerald.elf with debug symbols under a modern toolchain:

make DINFO=1

Note that this is not necessary for a non-modern (agbcc) build since those are built with debug symbols by default.

agbcc

Deprecated; installing agbcc is optional since 1.7.0.

Install agbcc into pokeemerald-expansion. The commands to run depend on certain conditions. You should only follow one of the listed instructions:

If agbcc has not been built before in the folder where you chose to store pokeemerald Expansion, run the following commands to build and install it into pokeemerald-expansion:
```
git clone https://github.com/pret/agbcc
cd agbcc
./build.sh
./install.sh ../pokeemerald-expansion
```
Otherwise, if agbcc has been built before (e.g. if the git clone above fails), but was last built on a different terminal than the one currently used (only relevant to Windows, e.g. switching from msys2 to WSL1), then run the following commands to build and install it into pokeemerald-expansion:
```
cd agbcc
git clean -fX
./build.sh
./install.sh ../pokeemerald-expansion
```
Otherwise, if agbcc has been built before on the same terminal, run the following commands to install agbcc into pokeemerald-expansion:
```
cd agbcc
./install.sh ../pokeemerald-expansion
```
Note...

If building agbcc or pokeemerald results in an error, try deleting the agbcc folder and re-installing agbcc as if it has not been built before.

Once agbcc is installed, change directory back to the base directory where pokeemerald-expansion and agbcc are stored:
```
cd ..
```
To compile with agbcc:
```
make agbcc
```

Useful additional tools

porymap for viewing and editing maps
poryscript for scripting (VS Code extension)
Tilemap Studio for viewing and editing tilemaps

Setting up WSL1 (Legacy Portion)

Certain packages are required to build pokeemerald. Install these packages by running the following command:
```
sudo apt install build-essential git libpng-dev gdebi-core
```
Note: If the above command does not work, try the above command but replacing apt with apt-get.
Once the packages have finished installing, download the devkitPro pacman package here. The file to download is devkitpro-pacman.amd64.deb.
WSL has its own file system that's not accessible from Windows, but Windows files are accessible from WSL. To install the devkitPro package, you'll need to change to the current working directory where the package file was saved.

For example, if the package file was saved to C:\Users\<user>\Downloads (the Downloads location for most users), enter this command, where <user> is your Windows username:
```
cd /mnt/c/Users/<user>/Downloads
```
Note 1: The Windows C:\ drive is called /mnt/c/ in WSL. Note 2: If the path has spaces, then the path must be wrapped with quotations, e.g. cd "/mnt/c/users/<user>/Downloads folder". Note 3: Windows path names are case-insensitive so adhering to capitalization isn't needed
Once the directory has been changed to the folder containing the devkitPro pacman package, run the following commands to install devkitARM.
```
sudo gdebi devkitpro-pacman.amd64.deb
sudo dkp-pacman -Sy
sudo dkp-pacman -S gba-dev
```
The last command will ask for the selection of packages to install. Just press Enter to install all of them, followed by entering Y to proceed with the installation.

Note: devkitpro-pacman.amd64.deb is the expected filename of the devkitPro package downloaded (for the first command). If the downloaded package filename differs, then use that filename instead.
Run the following command to set devkitPro related environment variables (alternatively, close and re-open WSL):
```
source /etc/profile.d/devkit-env.sh
```

Proceed to Choosing where to store pokeemerald (WSL1) of the current INSTALL.md.

Pokeemerald-Expansion Changelogs

1.8.x

Version 1.8.4 - Bugfix Release 🧹
Version 1.8.3 - Bugfix Release 🧹
Version 1.8.2 - Bugfix Release 🧹
Version 1.8.1 - HOTFIX Release 🔥
Version 1.8.0 - Feature Release ✨

1.7.x

Version 1.7.4 - Bugfix Release 🧹
Version 1.7.3 - Bugfix Release 🧹
Version 1.7.2 - Bugfix Release 🧹
Version 1.7.1 - Bugfix Release 🧹
Version 1.7.0 - Feature Release ✨

1.6.x

Version 1.6.2 - Bugfix Release 🧹
Version 1.6.1 - HOTFIX Release 🔥
Version 1.6.0 - Feature Release ✨

1.5.x

Version 1.5.3 - HOTFIX Release 🔥
Version 1.5.2 - Bugfix Release 🧹
Version 1.5.1 - Bugfix Release 🧹
Version 1.5.0 - Feature Release ✨

1.4.x

Version 1.4.3 - Bugfix Release 🧹
Version 1.4.2 - Bugfix Release 🧹
Version 1.4.1 - HOTFIX Release 🔥
Version 1.4.0 - Feature Release ✨

1.3.x

Version 1.3.0 - Feature Release ✨

1.2.x

Version 1.2.0 - Feature Release ✨

1.1.x

Version 1.1.1 - Bugfix Release 🧹
Version 1.1.0 - Feature Release ✨

1.0.x

Version 1.0.0 - Feature Release ✨

Pre-1.0.x:

Version 0.9.0 - Retroactive Version 🦕

Version 1.8.4

## How to update
- If you haven't set up a remote, run the command `git remote add RHH https://github.com/rh-hideout/pokeemerald-expansion`.
- Once you have your remote set up, run the command `git pull RHH expansion/1.8.4`.

🌋 IMPORTANT CHANGES 🌋

Reverted Guillotine feature branch by @AsparagusEduardo:

This was a runtime decapitalization branch introduced silently in version 1.8.0. We didn't properly announce as it was hastily merged and we were hoping that future versions of it would have fixed issues that we encountered after the merge. However, issues kept piling on and we felt the need to revert it as it was also silently breaking other features as well.
We will work on an alternate decapitalization option in the future.

💥 Softlock/Crash fixes 💥

Fixed softlock caused by Destiny Bond triggering after Explosion by @AlexOn1ine in https://github.com/rh-hideout/pokeemerald-expansion/pull/4516
Fixed softlock caused by Future Sight trying to hit a fainted target by @AlexOn1ine in https://github.com/rh-hideout/pokeemerald-expansion/pull/4543
Fixed softlock caused by Galvanized Explosion being absorbed by Volt Absorb by @AlexOn1ine in https://github.com/rh-hideout/pokeemerald-expansion/pull/4601
Fixed softlock caused by Flinging a Razor Fang when the target had already moved by @hedara90 in https://github.com/rh-hideout/pokeemerald-expansion/pull/4625

pokeemerald-expansion

Important: DO NOT use GitHub's "Download Zip" option. Using this option will not download the commit history required to update your expansion version or merge other feature branches. Instead, please read this guide to learn how to fork the repository and clone locally from there.

Please consider crediting the entire list of contributors in your project, as they have all worked hard to develop this project :)

Version 1.8.4 - Bugfix Release 🧹

Version 1.8.3 - Bugfix Release 🧹

Version 1.8.2 - Bugfix Release 🧹

Version 1.8.1 - HOTFIX Release 🔥

Version 1.8.0 - Feature Release ✨

Version 1.7.4 - Bugfix Release 🧹

Version 1.7.3 - Bugfix Release 🧹

Version 1.7.2 - Bugfix Release 🧹

Version 1.7.1 - Bugfix Release 🧹

Version 1.7.0 - Feature Release ✨

Version 1.6.2 - Bugfix Release 🧹

Version 1.6.1 - HOTFIX Release 🔥

Version 1.6.0 - Feature Release ✨

Version 1.5.3 - HOTFIX Release 🔥

Version 1.5.2 - Bugfix Release 🧹

Version 1.5.1 - Bugfix Release 🧹

Version 1.5.0 - Feature Release ✨

Version 1.4.3 - Bugfix Release 🧹

Version 1.4.2 - Bugfix Release 🧹

Version 1.4.1 - HOTFIX Release 🔥

Version 1.4.0 - Feature Release ✨

Version 1.3.0 - Feature Release ✨

Version 1.2.0 - Feature Release ✨

Version 1.1.1 - Bugfix Release 🧹

Version 1.1.0 - Feature Release ✨

Version 1.0.0 - Feature Release ✨

Version 0.9.0 - Retroactive Version 🦕

Reverted Guillotine feature branch by @AsparagusEduardo: