[Pokeemerald] Setting Up Your Environment on Windows!



I had previously written a tutorial on setting up Visual Studio Code with the disassemblies. As that is now slightly outdated, I’ve decided to write a new one with a focus on Pokeemerald. While this is written with Pokeemerald in mind, some concepts may apply to other GBA related projects. I will also keep updating this over time as opposed to writing a new document.

I will only be covering Windows in this tutorial. (Other OSes may be covered in a separate tutorial.) Pokeemerald also has a good document on the installation of the needed prerequisites, please feel free to review that document in addition to this one.

Windows will tend to be the OS that most people will use. You will be able to do most of what you need on Windows but the usual complaint is slower compile times. This is usually due to different Anti-virus software on windows scanning files actively and you may want to consider turning off any real time scanning in favor of improved compile times. On windows, I recommend using WSL for building pokeemerald.

This document will assume that you are familiar with VScode, Git, and etc. You should still be able to follow along if you have never used these, but I recommend learning more about them separately.

Setting up WSL

Installing WSL is actually fairly simple and I don’t see much need for me to cover something that Microsoft supports themselves. Please follow the instructions here. I will be using Ubuntu as my distro of choice, but these instructions should work for other WSL distros.

Installation of libraries in WSL

Once you have WSL installed it should be smooth sailing. Run the below to install any updates there may be for your distro.

sudo apt -y update && sudo apt -y upgrade

Once the updates are completed, run the below to install the libraries you will need to clone and build pokemerald.

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


Validating Installation

Testing everything that has been installed up until now is actually very easy. Simply open a command line window and run the below commands. These commands will clone Pokeemerald/agbcc and attempt to build a ROM.

git clone https://github.com/pret/pokeemerald
git clone https://github.com/pret/agbcc

cd agbcc
./install.sh ../pokeemerald

cd ../pokeemerald

make compare

The build may take a while and the length of time can depend on your computer and OS. If everything is successful, you should get something similar to the below.

If you got some sort of error instead of the above, I suggest trying to fix it before proceeding. Also please note that doing this is actually a good test to make sure your environment is working in the future. I think everyone at some point will have to troubleshoot why their project is not building, but you should always be able to clone and build the clean Pokeemerald repo.

If you like, you may delete the files that were created by this, or keep them if you want to work with the clean Pokemerald repo. We only cloned and built this to test that everything is installed correctly up until this point.

Install Visual Studio Code

Visual Studio Code is a code editor, by Microsoft, that is open source, Multi-Platform, and supports everything we need for the disassemblies.

It can be downloaded here. The installation is straight forward so I won’t really cover it here. Should you run into any issues with the installation, there are plenty of places to reach out for help.

Install Extensions

Once Visual Studio Code is installed, you can install extensions to improve it’s functionality. Please look at the following extensions, they can all be installed from within Visual Studio Code.

C/C++ for Visual Studio Code – Required

This extension adds C/C++ to Visual Studio Code. This is required for the disassemblies.

ARM – Optional

This extension adds syntax highlighting for ASM files. This extension isn’t required, but is very nice to have.

Native Debug – Optional

This extension adds GDB support to Visual Studio Code. This extension isn’t required, but is necessary if you want to use source level debugging.

GitLens — Git supercharged – Optional

This extension adds some nice git related features. This extension isn’t required, but if you are going to be using Git I highly recommend this extension. Please note that you will need Git to be installed for this extension.

Setting Up Your Repository

Now that you have VScode and your environment set up, you will have to do a few things to to set up your repository to properly take advantage of VScode. You will have to do these things for every Pokemerald repository you plan to work with.

Clone Your Repository

The first thing you will need to do is clone the repository you will want to work with. You can even work with the “clean” version of Pokeemerald that we used to validate our set up. I personally only clone and build the Pokeemerald from PRET as a test of my environment. There are plenty of repositories out that that have created new things on top of Pokemerald. I would personally recommend the pokeemerald-expansion repository as this contains new Pokemon, Items, and Attacks which most people would want to add anyway. This will be used in the following examples, but it does not matter which repo you use.

Clone and test build your repo similar to how we did before.

git clone https://github.com/rh-hideout/pokeemerald-expansion.git
git clone https://github.com/pret/agbcc

cd agbcc
./install.sh ../pokeemerald-expansion

cd ../pokeemerald-expansion

make -j32

Setup Your .vscode Folder

If you have worked with vscode before, you’ll know there are files that you can create to configure things in your workspace. To make this as easy as possible, I have created a repository called pokemerald-vscode that contains the files you need.

Run the below in wsl from within your repository.

cd ..
git clone https://github.com/Gamer2020/pokeemerald-vscode
cp pokeemerald-vscode/.vscode-wsl/ pokeemerald-expansion/.vscode/ -r

Opening and Testing Your Repository in VScode

Now you just need to open and test your repository in vscode. The easiest way is to right click on the folder and click on “Open with Code” in the menu.

Once opened, you should be able to run the tasks contained in the .vscode folder.

Below is a basic explanation of each task.

Install agbccReclones agbcc to the parent directory, builds, and installs it in your repo.
Update pokeemerald-vscodeReclones pokeemerald-vscode to the parent directory, and installs it in your repo.
Build DebugBuilds the ROM with debug options enabled.
Build ReleaseBuilds the ROM for release. (No debug options.)
Build ToolsBuilds the tools in the tools folder.
Clean Runs a "make clean"
mGBA_runLaunches the built ROM in mGBA.
mGBA_debugLaunches the build ROM in mGBA with debug enabled.

Please note that you will have to edit the folder location for mGBA to reflect your location. Please update the below line in the settings.json file.

"mgba_file": "\"/mnt/c/Program Files/mGBA/mGBA.exe\"",

For source level debugging, you will also need the arm-none-eabi-gdb.exe file from DevkitARM. Edit the below line in settings.json to match your location.

"gdb_file": "C:/Tools/arm-none-eabi-gdb/arm-none-eabi-gdb.exe",

Testing Source Level Debugging

One of the advantages of using VScode with pokeemerald is that we can finally have source level debugging. In certain situations this can be a useful feature to have working. If you updated the locations for mGBA and arm-none-eabi-gdb then you are all set.

  1. Run the “Build Debug” task.
  2. Set a breakpoint. (I like to use the title screen for this.)
  3. Run the “mGBA_debug”
  4. Press F5 to start debugging.
  5. Play until where you set the breakpoint and make sure the debugger brings you to the breakpoint when it is hit.


That is pretty much it for this tutorial. That should cover what people will need to set up their environment for Pokeemerald in VScode. This is not meant to go in depth but more to provide the proper steps to set everything up. I recommend getting familiar with VScode as it has many useful features once you get used to it.

Edit History

8/27/2021 – Initial release. More updates to come!