PDX Flag Builder

A tool for building flags for Victoria 3 and Europa Universalis 5. It reads the coats of arms, patterns and emblems of the game and of your mods, draws a flag exactly as its script describes it, and lets you edit it and save it back to the game's script files.

It runs on Windows and Linux.

Usage

Installation

Download the zip for your system from the releases page, extract it anywhere and run pdx-flag-builder.

On Linux the tool needs a distribution with glibc 2.38 or newer, such as Ubuntu 24.04, Debian 13 or Fedora 39, and its file dialogs need zenity or kdialog, one of which most desktops already have.

Setup

The tool reads its flags and textures from the game and from your mods:

1. Open Settings (Ctrl+,).
2. Click Add Folder and then Browse..., and pick the game's game folder or the root folder of a mod.
3. Add as many folders as you like. A folder further down the list overrides the ones above it, the way a mod overrides the game.
4. Click Save.

Finding a flag

Databases → Flag Database lists every coat of arms that was found, with a preview. Databases → Texture Database lists the patterns and emblems. Type into the search box to narrow a list down, and click a column header to sort it.

Click a flag to open it. File → New Flag starts from an empty one.

The folders are read when the tool starts and whenever the settings are saved. Databases → Reload reads them again, for files that changed since: a mod edited by hand, or written by another tool.

Editing

The Layers panel lists the coat of arms and its layers. Click one to edit it in the Selected Layer panel:

• The coat of arms has its name, its pattern and its colours.
• A coloured emblem has its texture, its colours, a mask that limits it to one colour of the pattern, and its placements: position, scale and rotation.
• A textured emblem is drawn in the colours of its own texture, so it has no colours of its own, but it can be masked like any other emblem.
• A sub flag draws another coat of arms, with an offset and a scale. The colours you give it are handed to that coat of arms in place of its own, so the same one can be drawn in the colours of whichever flag it is part of.

Add layers with Add Layer, or straight from the texture database with Add as Layer and Set as Pattern, or from the flag database with Add as Sub Flag. The arrows next to a layer move it up and down; the layers further down are drawn on top.

Number fields are changed by dragging across them. Double-click one to type a number instead. Hold Shift while dragging for bigger steps, Alt for finer ones.

To move a placement with the keyboard, click the flag and use the arrow keys:

Keys	Effect
Arrow keys	Move the selected placement
Ctrl + arrow keys	Scale it
Alt + left and right	Turn it
Shift with any of them	Ten times bigger steps

Ctrl+Z undoes and Ctrl+Y redoes.

Seeing it as the game will

Preview → Victoria 3 and Preview → Europa Universalis 5 open the flag the way each game shows a country's: as the cloth it hangs one on, and at each of the sizes it draws a flat one at.

Victoria 3 draws a flag at 96 x 64 down to 27 x 18 and frames it from outside with the border of the country's rank, which Rank Border chooses. Europa Universalis 5 draws it at 180 x 120 down to 22 x 14, frames it from the outside in, and has a round flag cut to a mask. Both shade every flag with a picture they multiply over it, and both hang one on the same waving cloth.

All of that is read from the games' own files, so a set of folders with only mods in it shows the flags on their own, and the window says which files it did not find and where they belong.

Saving and exporting

Menu entry	Effect
File → Save (Ctrl+S)	Writes the flag back into the file it came from. Only its own definition changes; the rest of the file stays as it is.
File → Save To File... (Ctrl+Shift+S)	Puts the flag into a file of your choosing, replacing a flag of the same name in it or adding it at the end.
File → Copy Script	Copies the flag's script to the clipboard.
File → Export Image...	Saves the flag as a 768 × 512 PNG image.

Values a file wrote with @variables or @[expressions] are saved as the numbers they came to.

Renaming a flag and saving it asks what the new name means: Rename gives the definition it was read from the new name, and Add as New Flag leaves that one as it is and writes the flag beside it. That is the way to build a variant of a coat of arms, for one form of government or one ideology, from the flag it starts out as.

The tool asks before it throws away unsaved changes.

Settings

Settings → Interface Scale makes the whole interface larger for high resolution displays. View → Reset Layout puts the panels back where they started.

Settings are stored in %AppData%\pdx-flag-builder on Windows and in ~/.config/pdx-flag-builder on Linux.

Building

The tool is written in Go and draws with raylib and Dear ImGui. Both are C and C++ libraries that are compiled along with it, so a C and C++ compiler is needed as well as Go.

The game's files are read by pdx-parser-go, which knows the script language of the Paradox games, how a game and its mods are combined, and how a coat of arms is written. To build against a checkout of it next to this one, rather than the released version, put a go.work beside this file:

go work init . ../pdx-parser-go

The first build compiles raylib and Dear ImGui and takes a few minutes. Later builds use Go's build cache and take seconds.

Windows

1. Install Go, in the version go.mod asks for or newer.

2. Install a MinGW-w64 toolchain, for example w64devkit or the one that comes with MSYS2, and put its bin folder on PATH so that gcc can be found.

3. Build:

   build.bat

   The executable lands in bin\windows.

Linux

1. Install Go, in the version go.mod asks for or newer.

2. Install a compiler and the OpenGL, X11 and Wayland development files. On Debian and Ubuntu:

   sudo apt-get install build-essential libgl1-mesa-dev xorg-dev libwayland-dev libxkbcommon-dev

3. Build:

   ./build.sh

   The executable lands in bin/linux.

Makefile

With make installed, the Makefile covers the everyday tasks:

Command	Effect
make build	Builds a development executable into bin/
make run	Builds it and starts it
make release	Builds an optimised executable, without a console window on Windows
make msix	Packs a Microsoft Store package on Windows, see below
make test	Runs the tests
make uitest	Runs the interface tests as well, which open a hidden window and so need a display
make vet	Checks the code with go vet

Microsoft Store package

packaging/msix/build-msix.ps1 builds the Windows executable and packs it into an MSIX package for the Microsoft Store, in bin/msix. It needs the Windows SDK, whose makeappx and makepri do the packing, besides Go and MinGW:

powershell -ExecutionPolicy Bypass -File packaging\msix\build-msix.ps1

The package takes its version from the code, so running it on a release commit packs that release. It is not signed; the Store signs what it publishes.

Tests

The tests that read a real installation run when PDX_GAME_DIR points at a game or mod folder:

PDX_GAME_DIR="/path/to/Victoria 3/game" go test ./...