pokeemerald-vita-3ds
Native PS Vita port of pokeemerald with Emerald 3DS features (no ROM included)
| Type | Filename | Size |
|---|---|---|
| DIR | .github | — |
| DIR | asm | — |
| DIR | assets | — |
| DIR | constants | — |
| DIR | data | — |
| DIR | design | — |
| DIR | docs | — |
| DIR | graphics | — |
| DIR | include | — |
| DIR | sound | — |
| DIR | src | — |
| DIR | tools | — |
| DIR | vita | — |
| FILE | .editorconfig | 506 B |
| FILE | .gitattributes | 478 B |
| FILE | .gitignore | 1431 B |
| FILE | audio_rules.mk | 1771 B |
| FILE | build_all.bat | 327 B |
| FILE | build_all.ps1 | 6157 B |
| FILE | build_all.sh | 7519 B |
| FILE | build_vita.ps1 | 1128 B |
| FILE | build_vita.sh | 1935 B |
| FILE | charmap.txt | 22065 B |
| FILE | CMakeLists.txt | 15466 B |
| FILE | CONTRIBUTING.md | 3462 B |
| FILE | fetch_assets.ps1 | 1356 B |
| FILE | fetch_assets.sh | 4964 B |
| FILE | graphics_file_rules.mk | 26351 B |
| FILE | handoff.yaml | 9881 B |
| FILE | json_data_rules.mk | 1501 B |
| FILE | LICENSE | 2319 B |
| FILE | make_tools.mk | 575 B |
| FILE | map_data_rules.mk | 2439 B |
| FILE | memory.yaml | 6200 B |
| FILE | NOTICE.md | 5011 B |
| FILE | README.md | 15356 B |
| FILE | spritesheet_rules.mk | 20486 B |
README
Pokémon Emerald Vita 3DS
Unofficial native PS Vita port of Pokémon Emerald, built from the pret/pokeemerald decompilation. It is not an emulator: the game's C code is compiled for the Vita's ARM CPU, and a platform layer supplies what the GBA hardware did. On top of it, the port brings the features of Emerald 3DS to the Vita with vitaGL, plus an optional HD-2D visual mode and 25° camera angle inspired by Bravely Emerald:
- a 3D voxel overworld built live from the game's maps, with sun, shadows, day/night, weather, and an optional HD-2D post-processing mode;
- 3D battles on a stage taken from the map where the battle starts;
- a new touch interface over the 3D world that replaces the GBA menus and boxes, with six menu themes (including the new GBA skin as default);
- HGSS follower Pokémon, visible wild Pokémon in the overworld, an accelerated clock, time-based encounters and optional QoL extras.
The full list is under Features.
AI-assisted project. The code, build scripts and documentation were written with an AI coding assistant (Claude Code, by Anthropic) under the supervision of HctrRB, who sets the direction, reviews the changes and tests every build on a real PS Vita.
Legal notice. Pokémon and Pokémon Emerald are © Nintendo, Creatures Inc. and GAME FREAK inc. This project is not affiliated with or endorsed by them. This repository does not contain the game's graphics, sounds or binary data, nor any ROM: to build, you check a dump of your own cartridge and the game files are downloaded from the public decompilation (docs/BUILD_YOUR_OWN.md). Like every decompilation, the tree still holds the game's code and text in decompiled form. A built VPK contains Nintendo's data: do not distribute builds.
Screenshots
Visual modes: 3D Normal · 3D HD-2D · Classic 2D
| 3D Normal | 3D HD-2D | Classic 2D |
|---|---|---|
![]() |
![]() |
![]() |
New native touch UI (GBA theme)
| Pokédex | Party | Hub & START Menu |
|---|---|---|
![]() |
![]() |
![]() |
25° camera & overworld
| Town & water | Route 119 (rain & waterfall) | Tall grass & wild Pokémon |
|---|---|---|
![]() |
![]() |
![]() |
Features
3D world
- Voxel overworld built live from the game's maps: sun and shadows, day/night cycle, weather, water reflections, 3D buildings and trees. 30 or 60 FPS (OPTIONS > WORLD), plus classic 2D mode.
- HD-2D mode (OPTIONS > WORLD): tilt-shift depth of field, bloom and light emitters, split-tone colour grading and vignette, street lamp / cave lantern point lights, dynamic sun/moon light shafts, night fireflies, swaying foliage, 16×16 Sobel tile relief, soft contact shadows, HD-2D rain and adjustable camera angle (including 25°).
- 3D battles: the stage is picked from the map around the player, and the camera glides from the field into it.
- Visible wild Pokémon in the overworld (configurable density and encounter rate) with extended sprite palettes, fading smoothly into 3D battles.
- HGSS follower Pokémon, an accelerated clock and time-based encounters.
New interface
Drawn natively at 960×544 over the 3D world. Every screen works with the buttons and with touch (first tap selects, a second tap on the selection confirms).
- START menu: Pokédex (list, entry, cry, size, area), party (summary pages, switch, held items, field moves, move reorder), bag (pockets, sort, use / give / toss / register), PokéNav (map, Match Call, condition, ribbons), Fly map, trainer card, Nuzlocke tracker, options, save.
- PC boxes: withdraw, deposit, move POKéMON and items, release, marks, jump to a box, wallpapers (the game's own, Walda's included) and box names.
- Player's PC: item storage (withdraw, deposit, toss), mailbox and mail reading on the game's stationery, and room / Secret Base decoration.
- Scenes the scripts open: Poké Mart buy / sell and decoration shops, naming keyboard (player, rival, POKéMON, boxes), Easy Chat (mail, profile, battle messages, interviews, trendy saying, survey…), berry choice for the Berry Blender and Berry Crush, contest appeal choice, "choose a POKéMON" for the move tutor, the Day Care and other scripts, and the forget-move screen (level-up, HM/TM, Move Tutor).
- Battle: HUD with health plates, party balls, commands, moves with PP and type, targets in double battles, YES / NO, level-up stats and the Safari Zone; bag and party in battle (multi battles included); the Battle Pyramid bag.
- Field: dialogue box, YES / NO, choice lists (PC menus, NPC questions), money box, item obtained, PokéNav calls and zone signs, plus dialogue mirrors in 2D evolution, egg-hatch and trade scenes.
- Menu themes (OPTIONS > GENERAL > MENU COLOR): GBA (default), RED, EMERALD, CRYSTAL, TROPICAL and ROYAL. Each has its own colours, box shapes, bevels and font, and applies to every screen, the battle HUD and the zone signs.
Extras
Physical / special split, infinite TMs, running indoors, IV / EV pages, EXP Share and EXP multiplier, Nuzlocke rules, field HM shortcuts, button remapping.
Status
Work in progress, in active testing. Expect bugs, crashes and unfinished screens. If you find one, please open an issue with the bug report template: what you did, what happened, and the log files from
ux0:data/POKEVITA/. Feedback on screens that are missing or feel wrong is very welcome.
Performance: 60 FPS with drops to 55 at 333 / 166 MHz.
Not yet tested on a PS Vita
These parts build and run in the design mocks, but have not been checked on the console yet:
- The menu themes on every screen, the battle HUD in each theme, and the lighter TROPICAL font.
- PC boxes and the player's PC (item storage, mailbox / mail reading, room and Secret Base decoration), decoration shops, and the forget-move screen.
- Naming keyboard: new game, box names, nicknames, a POKéMON caught with a full party.
- Easy Chat in each of its uses, the berry choice and the contest appeal choice.
- Day Care and move tutor choice (the right POKéMON is taken, the screen fades back in).
- The dialogue box after PokéNav calls and YES / NO answers (it used to flicker).
- The words of the PC choice menus, larger POKéMON names in battle.
- The fade into wild battles in the 3D world.
- Wide buildings no longer vanishing and popping back at the screen's west edge when you walk away from them (Rustboro City).
- Mirrored dialogue boxes in 2D evolution, egg-hatch and trade scenes.
Known issues and gaps
Screens still on the GBA interface:
- The Pokédex entry shown after a catch (description and stats): the GBA text is drawn with no background over the 3D battle.
- The summary of a boxed POKéMON in the PC.
- Move Relearner / Move Deleter, and Contest / Battle Frontier party choice.
- The Battle Pyramid bag inside battles and its "bag full: choose what to drop" step.
- Easy Chat's Bard song and quiz screens.
- Link and recorded battles, Wally's catching tutorial and the Battle Arena judgment keep the GBA battle HUD.
- Other screens may be missing too: give feedback on the ones you find.
Visual glitches:
- Trainer and legendary battle transitions are the GBA ones and only partly show over the 3D world.
- Intro and title screen margins at 16:9 are broken (sprites cut at the GBA edge, streaks beside Rayquaza); a replacement is designed in docs/SCENES_16_9.md.
- Walda's FRIENDS wallpaper may draw without its frame.
3D world:
- Terrain generation bugs in some maps (they come from Emerald 3DS). Fixed so far: Route 119 (its long bridge), Lilycove City and Mirage Island; the rest are being fixed map by map.
- Black spots on the terrain in some places: holes in the relief mesh that show the background.
- Occasional frame drops in dense areas of the 3D overworld.
Stability:
- The menu can freeze sometimes. Debug logs written to the memory card while a menu is open are a suspected cause.
- Vita3K shows a black screen; test on hardware.
Repository layout
build_all.bat/.ps1/.sh one step from your dump to EmeraldVita.vpk
CMakeLists.txt, build_vita.ps1/.sh Vita build (preprocess → compile → link → SELF → VPK)
make_tools.mk, *_rules.mk, vita/ host tools, asset rules, link wrapper, LiveArea art
src/, include/, asm/, data/, the pokeemerald decompilation (game code and text data;
constants/ graphics/, sound/ and data binaries come from fetch_assets)
fetch_assets.sh/.ps1, tools/assets/ game files download (checks your ROM, then the manifest)
src/platform/ GBA hardware emulation and main loop
src/platform/voxel/ 3D voxel world
src/platform/ui/ the new interface (screens, widgets, themes)
src/platform/vita/ Vita-specific features (clock, encounters, extras, stage)
assets/ port data packed into the VPK (voxel, UI atlas, followers)
tools/ pret host tools, UI atlas builder (tools/ui2), follower packer, generators
design/stitch/ HTML mocks of the new interface
docs/ technical documentation
Build your own VPK
No builds are distributed: you make your own from your Pokémon Emerald cartridge. Full guide, with every command and the common errors: docs/BUILD_YOUR_OWN.md (en español: docs/COMPILA_TU_VPK.md).
You need a Windows 10/11 PC, your Pokémon Emerald dump (.gba, any language, 16 MB) and a
PS Vita with HENkaku or Ensō. Nothing else has to be installed by hand:
- Get the repository (
git clone, or Code > Download ZIP) into a folder with no spaces or accents in its path and not synced by OneDrive, e.g.C:\Emerald\pokeemerald-vita-3ds. - Double-click
build_all.batin that folder and choose your.gbain the window it opens (or runpowershell.exe -ExecutionPolicy Bypass -File .\build_all.ps1 -Rom <file>). It installs what is missing (MSYS2 inC:\msys64, its packages, VitaSDK with vitaGL and SDL2), checks your dump, downloads the game files and checks each one against tools/assets/manifest.txt (nothing is copied from the ROM), and builds everything. The first run takes 20–40 minutes. - Install
EmeraldVita.vpkwith VitaShell (Enable unsafe homebrew on in HENkaku settings). The game appears as Emerald Vita (title IDPKEM00001); saves and settings live inux0:data/POKEVITA/.
To update: git pull and run build_all.bat again (the ROM is only asked for the first time;
game files a new version needs are downloaded by themselves). The manual steps are in the guide
and in docs/BUILD.md.
Do not share the VPK or the downloaded files: they contain Nintendo's game data.
Controls
| Button | Action |
|---|---|
| Cross / Circle | A / B |
| D-pad or left stick | Move |
| L / R | L / R |
| START | Open or close the touch menu (field) |
| SELECT | Registered item |
| Triangle | Fast forward |
| Square | Options |
| Touch | Menu, battle action deck |
Buttons can be remapped in Options. Settings and saves live in ux0:data/POKEVITA/
(see docs/ARCHITECTURE.md).
Documentation
| Document | Covers |
|---|---|
| docs/BUILD_YOUR_OWN.md (español) | Make your own VPK from your cartridge, step by step |
| docs/BUILD.md | Toolchain, build steps, CMake options, installing and testing |
| docs/README.md | Index of the technical documentation |
| docs/ARCHITECTURE.md | Layers, boot, one frame, where things are, runtime files |
| docs/THREADS.md | Cores, pacing, who owns which data |
| docs/RENDERING.md | Presentation paths, voxel passes, GBA overlay, GPU rules |
| docs/VITA_UI.md | The user interface |
| docs/VOXEL_ENGINE.md | The 3D overworld |
| docs/SCENES_16_9.md | How GBA screens fill 16:9 |
| docs/ASSETS.md | Where every data file comes from |
| docs/DEBUGGING.md | Logs, per-frame telemetry, crash dumps |
| design/stitch/README.md | Design mocks of the new UI (Spanish) |
| CONTRIBUTING.md | Code standards and workflow |
| NOTICE.md | Licences of the ported code and credits |
Credits
- pret and contributors: the pokeemerald decompilation and its tools.
- Zallax and the Emerald 3DS contributors: Emerald 3DS, the source of most of what this port adds: the voxel world, the 3D battles, the followers, the extras and the look of the interface.
- marcoscodas: Bravely Emerald, visual design and shader reference for the HD-2D post-processing mode, point lights, light shafts, foliage sway, tile relief and 25° camera tilt.
- gradenGnostic and contributors: pokeemerald-multiplatform, the SDL2 platform layer and voxel renderer this port starts from.
- Rinnegatamante (vitaGL), the VitaSDK, SDL and Vita3K teams, and Niels Lohmann (nlohmann/json).
- HctrRB: project lead, supervision and hardware testing.
Legal
- Pokémon, Pokémon Emerald and all related names, characters, graphics, music and text are trademarks and copyrights of Nintendo, Creatures Inc. and GAME FREAK inc. This is a non-commercial fan project.
- This repository does not include the game's graphics, sounds or binary data, nor any ROM.
fetch_assetschecks a dump of the user's own cartridge and downloads those files from the public pret/pokeemerald decompilation (via pokeemerald-multiplatform); they remain the property of their owners. The decompiled code and text in this tree come from the same decompilation. Builds contain that material: don't upload, share or sell them. Use this project only with a legitimately owned copy of Pokémon Emerald. - Code licences differ by origin: MIT for the multiplatform layer and original Vita code (LICENSE), CC BY-NC-SA 4.0 for everything derived from Emerald 3DS. The full list is in NOTICE.md.
- Provided as is, without warranty. Rights holders can request changes or removal by opening an issue.








