This document collects implementation and runtime details that are useful for contributors, packagers, extension authors, and advanced troubleshooting. The end-user feature summary lives in the repository README.
PakFu is organized around a shared non-UI core with two front ends:
- Desktop GUI: Qt6 Widgets main window, workspace tab, archive tabs, preview panes, standalone viewers, preferences, update UI, and platform integration.
- CLI: headless archive, conversion, validation, extension, update, and diagnostic workflows.
- Core library: archive backends, format parsers, conversion helpers, search indexing, game-profile logic, and extension host contracts.
The build system remains Meson and Ninja. Source-build instructions live in
docs/BUILDING.md.
Supported package backends include:
- directory input
- PAK and SiN SPAK
- ZIP-family archives: ZIP, PK3, PK4, PKZ
- Quake Live Beta encrypted PK3 decode/encode
- Doom 3 BFG
.resources - WAD2, WAD3, Doom IWAD/PWAD
Archive tabs track selection, mounted archive layers, pending modifications, view mode, preview state, and Pure PAK Protector read-only decisions. Folder input is treated as an archive-like source for listing, previewing, extraction, and comparison.
This section keeps filetype-level details out of the README while preserving a
quick technical reference for contributors and advanced users. For fixture-backed
status, implementation notes, and evidence, use
docs/SUPPORT_MATRIX.md.
| Type | Extensions | Open/List | Extract | Save/Rebuild |
|---|---|---|---|---|
| Folder input | directory path | Yes | Yes | N/A |
| PAK/SIN | pak, sin |
Yes | Yes | Yes |
| ZIP family | zip, pk3, pk4, pkz |
Yes | Yes | Yes |
| Quake Live Beta encrypted PK3 | pk3 |
Yes | Yes | Yes |
| Doom 3 BFG resources | resources |
Yes | Yes | No |
| WAD2 | wad, wad2 |
Yes | Yes | Yes |
| WAD3 | wad3 |
Yes | Yes | No |
| Doom IWAD/PWAD | wad |
Yes | Yes | No |
| Area | Examples |
|---|---|
| Images and textures | pcx, wal, png, tga, jpg, jpeg, bmp, gif, tif, tiff, swl, m8, m32, mip, lmp, dds, ftx |
| Audio | wav, ogg, mp3, idwav |
| Video and cinematics | cin, roq, bik, ogv, mp4, mkv, avi, webm |
| Models | mdl, md2, fm, md3, mdc, md4, mdr, skb, skd, mdm, glm, iqm, md5mesh, tan, obj, lwo, blwo |
| Maps and compiled geometry | bsp, proc, map |
| idTech inspectors | spr, sp2, spr2, bk, os, dm2, aas, qvm, progs.dat, tag, mdx, mds, skc, ska, fontdat, ttf, otf |
| Text and scripts | cfg, shader, menu, def, mtr, ent, qc, json, xml, and similar plain-text assets |
Notes:
- Audio and backend video playback depend on the Qt Multimedia backend and installed codecs.
- Indexed texture formats use embedded or game palettes when the format requires them.
- Some package formats are intentionally read-only until a safe writer exists.
PakFu routes selected entries to specialized preview paths:
- image and texture loaders, including palette-aware indexed formats
- Qt Multimedia playback for backend-supported audio/video
- built-in CIN and ROQ cinematic decoding
- model loaders and 3D preview widgets
- BSP and idTech4 PROC geometry previews
- script/config text preview with syntax highlighting
- font, sprite, bytecode, demo, shader, and binary metadata inspectors
Heavy previews use background work, temp export caching, timing metrics, and resolution caps where needed to keep the UI responsive.
3D previews can use Vulkan when available at build time and OpenGL as the portable fallback. The runtime preferences surface renderer, field of view, grid/background, wireframe/textured defaults, BSP lightmaps, smoothing, animation, and related preview controls.
The GUI conversion workspace and CLI --convert action share the same C++
conversion layer.
Implemented conversion areas include:
- image conversion across supported image preview formats and writer formats
- palette-aware outputs for PCX, WAL, SWL, MIP, LMP, FTX, and DDS paths
- CIN/ROQ frame export with optional WAV audio
- IDWAV decode to WAV when the embedded codec is supported
- backend-only media copy/metadata fallback
- BSP-to-MAP best-effort export
- Doom IWAD/PWAD map-lump export to UDMF/TEXTMAP
.map
See docs/SUPPORT_MATRIX.md for current support evidence.
Extensions are manifest-driven external commands. PakFu discovers manifests from
default search roots plus any CLI --plugin-dir values, validates command
capabilities, and runs commands with an explicit JSON context.
Capabilities describe whether an extension may read selected entries, request generated imports, or interact with the current archive context. The GUI can offer write-back import flows after host validation. The CLI reports requested imports but does not automatically apply write-back.
See docs/EXTENSIONS.md and
examples/extensions/ for the manifest schema and
example commands.
Runtime update checks use GitHub Releases. GUI checks run after the main window opens so network latency does not block startup.
Build-time updater defaults are Meson options:
-Dgithub_repo=themuffinator/PakFu
-Dupdate_channel=stableRuntime CLI overrides:
pakfu --cli --check-updates --update-repo owner/name --update-channel stableDownloaded GUI update assets are checked against release-manifest size and
SHA-256 data before PakFu opens the download folder or starts an installer
handoff. Full release rules live in docs/RELEASES.md.
| Variable | Purpose |
|---|---|
PAKFU_CRASH_DIR |
Override crash output directory for session logs and crash artifacts. |
PAKFU_DISABLE_QT_MESSAGE_HOOK |
Disable Qt log interception for troubleshooting. |
PAKFU_DEBUG_MEDIA |
Enable extra media diagnostics in logs. |
PAKFU_AUTO_PLAY_ON_OPEN |
Auto-start playback when opening videos. |
PAKFU_FORCE_QT_FILE_DIALOG |
Force Qt's non-native file dialog implementation. |
PAKFU_ALLOW_MULTI_INSTANCE |
Disable single-instance behavior and allow multiple app instances. |
PAKFU_SMOKE_TABS |
Run tab smoke test automation on startup. Intended for debug and CI use. |
QT_MEDIA_BACKEND |
Override Qt Multimedia backend selection. |
When porting, translating, or deriving format logic from another project, keep license-compatible attribution near the code or in documentation and link the source repository or revision when practical.
Heretic II references should credit
0lvin/heretic2. Existing support and
dependency documentation contains additional per-format attribution notes.
docs/BUILDING.md: source builds, tests, and packaging.docs/CLI.md: command-line reference.docs/CORE_LIBRARY.md: public non-UI source-level API.docs/DEPENDENCIES.md: library and toolchain inventory.docs/SUPPORT_MATRIX.md: format support evidence.docs/RELEASES.md: versioning, assets, updater manifest, and CI workflows.