BUILD_YOUR_OWN.md
5951 bytes · Original / download
Build your own VPK
Work in progress, in active testing. Please report the bugs you find (see the end of this guide).
This repository does not contain the game's graphics, sounds or binary data, and it does not distribute builds. You make your own VPK from your own copy of the game:
- You need a dump of your Pokémon Emerald cartridge (
.gba, any language). The script only reads it to check that it is Pokémon Emerald; nothing is copied from it, stored or uploaded. - The script then downloads the game files of the
pret/pokeemerald decompilation (through
pokeemerald-multiplatform, the
version this port is built on) and checks every file against
tools/assets/manifest.txt. - It builds the VPK, and you install it on your PS Vita.
Do not share the VPK or the downloaded files: they contain Nintendo's game data.
Spanish version: COMPILA_TU_VPK.md.
What you need
- A Windows 10 or 11 PC with an internet connection and about 5 GB free.
- Your Pokémon Emerald dump (
.gba, 16 MB). - A PS Vita with HENkaku or Ensō and VitaShell.
Everything else (MSYS2, VitaSDK, Python, Git) is installed by the script.
1. Get the repository
Either clone it with Git:
git clone https://github.com/HctrRB/pokeemerald-vita-3ds.git C:\Emerald\pokeemerald-vita-3ds
or, without Git, use Code > Download ZIP on GitHub and extract it.
Put it in a folder whose path has no spaces or accents, for example
C:\Emerald\pokeemerald-vita-3ds. The build tools cannot handle them (the script checks and
stops), so C:\Users\Your Name\Downloads\... will not work. Avoid folders that OneDrive
syncs (often Documents and Desktop): the build writes thousands of files and the sync can
lock them.
2. Build
Double-click build_all.bat in the repository folder. A window asks for your .gba, and
the console window stays open at the end with the result. (If Windows warns that the file comes
from the internet, choose More info > Run anyway.)
Or, from PowerShell in the repository folder:
powershell.exe -ExecutionPolicy Bypass -File .\build_all.ps1 -Rom "C:\path\to\emerald.gba"
Any ROM path works, spaces included; without -Rom the window asks for it.
The script:
- installs MSYS2 in
C:\msys64if it is missing, and the packages the build needs; - installs VitaSDK in MSYS2 (
/usr/local/vitasdk) and the libraries the game uses (vitaGL, SDL2) if they are missing; - checks your dump and downloads the game files (about 9,000 files);
- builds the interface atlas and the tools, converts the game files and builds the VPK.
The first run downloads 1–2 GB and can take 20–40 minutes; later runs take a few minutes. The
result is EmeraldVita.vpk in the repository folder. Every step that is already done is
skipped, so you can run the script again after a failure.
Updating: git pull (or download the ZIP again over the same folder) and run
build_all.bat again. The ROM is only asked for the first time: when a new version needs other
game files, the script downloads them by itself.
3. Install
- Copy
EmeraldVita.vpkto the Vita (USB or FTP with VitaShell). - In VitaShell, press X on the VPK and install it (Enable unsafe homebrew must be on in HENkaku settings).
- The game shows up as Emerald Vita. Saves and settings live in
ux0:data/POKEVITA/.
Your own LiveArea art can go in vita/sce_sys_custom/ with the same file names as
vita/sce_sys/ (8-bit indexed PNGs); it is used instead of the neutral images.
Common errors
| Message | Fix |
|---|---|
This folder's path has spaces or special characters |
Move the repository folder to a simple path such as C:\Emerald\pokeemerald-vita-3ds. |
Permission denied / Device or resource busy while building |
Often OneDrive or an antivirus locking files: move the folder out of OneDrive, or run the script again. |
Could not download MSYS2 / MSYS2 did not install |
Install MSYS2 by hand from msys2.org in C:\msys64, then run the script again. |
not a Pokémon Emerald dump |
The file is not a Pokémon Emerald ROM, or it is damaged. It must be 16 MB. |
VitaSDK did not install / ... is still missing after vdpm install |
Usually a download that failed: run the script again. Otherwise see BUILD.md. |
vitaGL.h: No such file or directory |
Your copy of the script is older than the fix that installs vitaGL: update the repository (git pull or a new ZIP) and run build_all.ps1 again. |
running scripts is disabled on this system |
Start it exactly as shown above (powershell.exe -ExecutionPolicy Bypass -File ...). |
Building by hand
The script runs these steps; you can run them yourself in the MSYS2 MINGW64 shell, from the
repository folder (cd /c/Emerald/pokeemerald-vita-3ds):
- Packages and VitaSDK, once (the exact commands and pitfalls are in BUILD.md).
- The game files, once:
sh ./fetch_assets.sh /c/path/to/emerald.gba - The tools and the converted game files:
sh make -f make_tools.mk -j8 CC="gcc -static" CXX="g++ -static" make -f vita/assets.mk -j8 - The VPK:
./build_vita.sh→build-vita/pokeemerald.vpk.
Reporting bugs
This port is a work in progress in active testing. When something goes wrong, open an issue on GitHub with the Bug report template and include:
- what you were doing and what happened (a photo of the screen helps);
- the files
perf_summary.txt,perf_frames.csvand any*.logfromux0:data/POKEVITA/; - for a crash, the
.psp2dmpfile fromux0:data/(see DEBUGGING.md); - the commit you built (
git log -1 --oneline); - if the build failed, the last lines the script printed.