Bow to your Sensei! ๐โโ๏ธ๐โโ๏ธ๐งโโก๏ธ๐งโโก๏ธ๐งโโก๏ธ
PakFu is a modern, cross-platform PAK/WAD file manager forged in the dojo of C++20 โ๏ธ and the ancient arts of Qt6 ๐ (Widgets or QML). It exists to bring balance to chaotic archives: browse ๐งญ, preview ๐, extract ๐งค, rebuild ๐ ๏ธ, and automate ๐งโโ๏ธ via CLI.
This project is still training under the waterfall ๐ฆ๐ฅ (early development). Expect rapid evolution, occasional shin bruises, and increasingly disciplined PAKs.
- GUI: Qt6 Widgets or QML ๐ชโจ
- CLI: first-class, scriptable, and always respected ๐งโ๐ปโก
- Targets: Windows ๐ช, macOS ๐, Linux ๐ง (no platform favoritism in my dojo)
- Build: Meson + Ninja ๐ฅท๐ ๏ธ
- Deliver a modern, intuitive UI that feels fast, clean, and confident ๐งผโก๐ง
- Provide a first-class CLI for automation, pipelines, and batch wizardry ๐ช๐งฐ
- Run consistently on Windows/macOS/Linux ๐งโโ๏ธ๐
- Understand and preview common PAK-adjacent file types ๐๏ธโ๐จ๏ธ๐
- Images:
pcx,wal,mip,dds,lmp,png,tga,jpg๐ผ๏ธ๐จ - Audio:
wav,ogg,mp3๐๐ถ - Video:
cin,roq,ogv๐๏ธ๐ฟ - Models:
mdl,md2,md3,iqm,md5mesh,lwo,obj๐ง๐งฉ - Maps:
bsp(Quake/Quake II/Quake III/Quake Live) ๐บ๏ธ๐งญ - Text/config:
cfgand similar plain-text formats ๐งพ๐๏ธ
- Images:
- Tune 3D previews with grid/floor/none options, themed/grey/custom backgrounds, and wireframe/textured toggles
- Quake II previews honor
_glow.pngglow maps for textures and models - Stay responsive for large archives (no freezing in the middle of a roundhouse kick) ๐ฅถโก๏ธ๐ฅ
- Guard official game archives with a default-on Pure PAK Protector preference ๐ก๏ธ๐ฆ
- Keep C++ code clean, portable, and documented (minimal OS-specific sorcery) ๐ง ๐งน๐งพ
PakFu treats *.pk3, *.pk4, and *.pkz as ZIP-based packs (same container, different extension).
Common conventions:
*.pk3: id Tech 3 packs (Quake III Arena / Quake Live, etc.)*.pk4: id Tech 4 packs (Doom 3 / Quake 4, etc.)*.pkz: ZIP-based packs used by some games/mods (handled like PK3/ZIP)
These packs are supported anywhere PakFu supports ZIP:
- Open/browse/preview/extract in the GUI
- List/info/extract in the CLI (
--cli) - Rebuild/write via File โ Save / Save Asโฆ (uses a vendored
minizbackend)
./build/src/pakfu --cli --info path/to/archive.pk3
./build/src/pakfu --cli --list path/to/archive.pk4
./build/src/pakfu --cli --extract -o out_dir path/to/archive.pkzQuake Live Beta used an XOR-obfuscated PK3. PakFu can transparently decode these when reading, and can encode them when writing:
- Auto-detect on open: if a
*.pk3looks like a Quake Live Beta encrypted ZIP header, PakFu decodes it to a temporary ZIP for reading/listing/extraction.- CLI tip:
--cli --infoprintsQuake Live encrypted PK3: yeswhen detected.
- CLI tip:
- Decode (encrypted โ normal PK3): open the encrypted
*.pk3, then File โ Save Asโฆ โPK3 (ZIP) (*.pk3) - Encode (normal โ QL Beta encrypted PK3): open any ZIP-based pack, then File โ Save Asโฆ โ
PK3 (Quake Live encrypted) (*.pk3) - Note: encode/decode is the same XOR stream operation (historical obfuscation, not real security).
- Deep editing of complex proprietary binary formats ๐งโโ๏ธ๐ฆ
- Bundling game-specific proprietary tooling ๐ณ๏ธ๐
- Platform-exclusive UI tricks that break cross-platform harmony ๐งจ๐ฅ
- UI must be Qt6 Widgets or QML. No alternate frameworks. Ever. ๐๐ช
- Must remain cross-platform; avoid OS-locked dependencies ๐งโโ๏ธ๐
- CLI remains supported and documented ๐งพ๐งโ๐ป
- File format support must be modular and additive ๐งฉโ
- Docs must evolve with behavior (a silent Sensei is a bad Sensei) ๐ฃ๐
- C++ (modern, prefer C++20) โ๏ธ
- Qt6 (Widgets/QML) ๐
- Meson + Ninja ๐ฅท๐ ๏ธ
PakFu checks GitHub Releases for new scrolls (updates) ๐งพโจ. Configure the repo at Meson setup time so the updater knows which mountain to climb ๐๏ธ๐:
-Dgithub_repo=owner/name๐งญ-Dupdate_channel=stable|beta|dev๐งช
Release assets should include platform-appropriate packages ๐ (installers preferred ๐งฐโ , archives supported ๐ฆ๐).
See docs/RELEASES.md for versioning and release automation details ๐งพ๐ค.
See docs/DEPENDENCIES.md for the current baseline and planned format loaders ๐๐.
The dojo provides a helper script that finds Qt's qmake6 and builds with Ninja:
pwsh -NoProfile -File scripts/meson_build.ps1On Windows, the script also deploys the required Qt runtime DLLs into build/src/ so build/src/pakfu.exe runs without needing to add Qt to PATH.
meson setup build --backend ninja -Dgithub_repo=owner/name -Dupdate_channel=stable
meson compile -C build- Use File โ Open Archiveโฆ or File โ Open Folderโฆ (opens in a tab).
- Drag archives or folders onto the window to open them.
- Drag files/folders into an open archive tab to add them.
- Drag items out of PakFu to copy them to your file manager (exports via temp files).
- Most archive actions also work on folders (pass a directory path instead of an archive file).
PakFu uses Game Sets to store per-game defaults:
- Default directory (for file dialogs / common workflows)
- Palette selection (for game-specific previews)
- Launch settings (executable + args)
If Game Sets are already configured, PakFu opens directly into the main window. If none are configured yet, the Game Sets window appears on startup. In the main window, use the Game drop-down to switch sets instantly, or choose Configure Game Setsโฆ to edit/auto-detect. When opening an archive, PakFu will try to auto-select the most likely Game Set based on the archiveโs path and nearby install markers. Auto-detect checks installs in priority order: Steam โ GOG.com โ EOS.
Supported auto-detect games:
- Quake
- Quake Rerelease
- Quake II
- Quake II Rerelease
- Quake III Arena
- Quake Live
- Quake 4
./build/src/pakfu
./build/src/pakfu --cli --help
./build/src/pakfu --cli --check-updatesOn Windows, use:
.\build\src\pakfu.exe
.\build\src\pakfu.exe --cli --helpGame Sets can also be managed via CLI:
./build/src/pakfu --cli --list-game-sets
./build/src/pakfu --cli --auto-detect-game-sets
./build/src/pakfu --cli --select-game-set quake2
./build/src/pakfu --cli --select-game-set quake3_arena
./build/src/pakfu --cli --select-game-set quake_live
./build/src/pakfu --cli --select-game-set quake4- License: GPLv3 ๐๐ง
- Disclaimer: Use at your own risk. No warranty. No mercy. ๐ฅ
โ ๏ธ ๐
This repository is intentionally minimal right now. As features arrive, keep the dojo rules aligned with the design and build choices ๐งโโ๏ธ๐ฆโจ.