Porymap: a Qt map editor for the Pokemon generation 3 decompilations

What Porymap is for: drawing maps inside three specific decompilations

Porymap is a map editor built for a narrow and well defined set of targets: the Pokemon generation 3 decompilation projects, which the README names as pokeruby, pokeemerald and pokefirered. It is not a general purpose tile map editor, and it does not open arbitrary RPG Maker or Tiled projects. The point of the tool is that the map data of those decompilation projects lives in the project itself, as data and code that has to be edited accurately, and Porymap is the interface that makes that editing graphical.

The audience follows from the design. People who write these decompilations care about byte-exact reproduction of the original games, so a mapper that silently reformats map data or guesses at tile properties is worse than no mapper. The tool exists to remove the tedium of manual work while staying out of the way of the project's own conventions.

The implementation is C++ with a Qt interface, and the repository topics list tilesets and tileset editing alongside map editing and GUI, which tells you the tileset workflow is treated as a first-class part of the job rather than an afterthought. The project is not archived, and the last push was on 2026-10-07, so work on it is ongoing.

One structural detail is worth noting for anyone reading the repository: the tree contains a porymap.pro file, so the build is a qmake project, and there are separate include, src, forms, resources, docs and docsrc directories. That layout is the kind you get from a long-lived desktop application that grew alongside the decompilation scene it serves.

Getting the binary: Windows and macOS archives, source on Linux

The README splits the install story by platform, and the split is not cosmetic. Windows and macOS users can download Porymap and start working immediately, while Linux users must compile it from source.

For Windows the download link points at a zip in the project's releases:

https://github.com/huderlem/porymap/releases/latest/download/porymap-windows.zip

macOS has two separate archives, one for arm machines and one for Intel, which is a sign of how the build matrix has grown with the hardware transition:

https://github.com/huderlem/porymap/releases/latest/download/porymap-macos-latest.zip
https://github.com/huderlem/porymap/releases/latest/download/porymap-macos-15-intel.zip

The two macOS files are the arm build and the macOS 15 Intel build respectively. Older versions of Porymap remain downloadable from the releases page, which is useful when you are matching an editor to an older checkout of a decompilation project.

Linux is the sharp edge. The README states plainly that Linux users must compile Porymap from source, and points to INSTALL.md for the actual instructions. The README does not reproduce those commands, so the build sequence itself has to be taken from that file rather than guessed at. The repository contains a porymap.pro file, which tells you a qmake-based build is involved.

There is an escape hatch that the README mentions with a caveat worth reading twice. Linux users who do not want to compile can find Porymap on an external package repository such as Flathub or AUR, but the README warns that builds installed through an external package manager are not explicitly maintained by Porymap and may be out of date. That is the kind of staleness that bites when an editor needs to understand the current format of a map file.

Where the documentation lives and what it promises

Porymap does not keep its manual in the repository readme. The README points to a full online guide hosted on the project's pages, and the repository tree confirms that the manual source is kept alongside the code in a docsrc directory, with a separate docs directory for the rendered output. That separation matters for contributors, since the manual is versioned with the source rather than being a separate site.

The guide is the place to look for the actual workflow, and the README's own instruction is unambiguous: to get started, view the full online guide. For anyone evaluating the tool, that guide is the artifact to read before deciding, because the readme here is short by design and covers distribution rather than usage.

Two other files carry information a user will need. CHANGELOG.md is linked from the readme as the place to see what is new, so it substitutes for the release notes that many projects keep only in the hosting platform. RELEASE-README.txt sits at the top level as well, which by convention is the text attached to a packaged release. Neither file's contents are reproduced in the documentation available here, so the changelog is the place to confirm that a feature you care about exists in the version you are about to run.

The screenshots and preview images live under docsrc as well, inside a manual directory for the introduction, which suggests the guide walks through the interface from the opening screen outward rather than dropping readers into reference pages.

Release cadence and the gap between versions

The project ships tagged releases on a readable schedule: 6.2.0 on 2025-08-08, 6.3.0 on 2025-12-26 and 6.3.1 on 2026-04-12. That is three releases in roughly nine months, with the gap between the two 6.3 releases looking like a maintenance patch rather than a feature drop.

The last push to the repository, 2026-10-07, falls some months after the 6.3.1 release date. In other words the development branch has been moving since the last tagged build, which is normal for an application of this kind, and it has a practical consequence: the binaries in the releases folder are not the same thing as the current master branch. If you need a recent change, you are in source-build territory, and on Linux that is already the only option.

This also determines how you should think about the external packages. A Flathub or AUR build can lag both the last release and the branch, and the readme's warning about such builds not being maintained by the project is consistent with the observed gap between the 2026-04-12 release and the 2026-10-07 push. The safe sequence is to check the changelog for the version you have against the version the decompilation project expects, and to compile from source if they differ and the format matters to you.

Licence and what it means for a modding workflow

Porymap is released under the LGPL-3.0 licence. That is the permissive-but-copyleft end of the free software licences: the licence carries obligations around how the library is redistributed, while permitting use in your own work. It is worth understanding, though, that the licence of the editor and the licence of the game data you edit are two separate things. A map you draw in Porymap and save into a decompilation project carries whatever licence that project uses, and the editor's licence does not grant or restrict rights in the output.

For the typical user, the practical effect of LGPL-3.0 is that there is no cost to using Porymap, no per-seat licensing, and no requirement to buy anything to work on a personal decompilation. The obligation bites mainly on whoever distributes a modified build of the editor itself, such as a packager shipping a patched binary through Flathub or AUR, who must honour the terms the LGPL attaches to that redistribution. A packager who only republishes the upstream binary avoids most of that, but that is a question for the packager and not for the mapper.

Nothing in the documentation available here imposes additional terms, and no registration, activation or telemetry requirement is mentioned. The tool is a plain offline desktop application that writes files into a project directory.

Where Porymap is the wrong choice

The clearest wrong-tool case is general tile map work. Porymap is built around the map and tileset formats of the generation 3 decompilations, so an artist who wants to make maps for a different engine, or for a personal project of their own, gets an editor whose assumptions do not apply and whose output is not portable. Tiled and other general map editors exist for that case, and the difference in approach is the whole point: a general editor treats every tile layer as generic data, while Porymap is expected to know about the specific tile properties and object formats the decompilations use.

The second wrong-tool case is Linux without the willingness to build. The README is direct that Linux users must compile from source, and while Flathub and AUR packages exist, the readme explicitly says they are not maintained by the project and may be out of date. On Linux the honest options are to build it or to accept a package of unknown freshness.

The third case is a project that is not one of the three. The readme names pokeruby, pokeemerald and pokefirered and nothing else, and Porymap is not described as a generic editor with pluggable backends. If your work targets a different decompilation, the readme gives no basis for assuming support.

The last case is the volume case. Porymap is a GUI application aimed at making individual map edits less painful. If the goal is to transform thousands of maps programmatically, nothing in the documentation describes a scripting interface, a batch mode or a command line, so the tool would have to be driven by hand.

Editorial conclusion

Porymap fits rom hackers working inside the pokeruby, pokeemerald or pokefirered decompilations who would rather draw a map than edit one by hand, and it is a poor fit for general tile map work or for anyone unwilling to build from source on Linux. Verify first that the build you install matches your decompilation project, that the online guide at huderlem.github.io/porymap/ covers the feature you need, and, on Linux, that the Flathub or AUR package you are tempted to use is not stale relative to the 6.3.1 release.

Frequently asked questions

Official sources

1. huderlem/porymap on GitHub
2. License: LGPL-3.0
3. Project website
4. README
5. Releases