Source-only native static recompilation of Killzone: Liberation v1.20 (UCUS-98646) for Windows 10/11 x64 and Apple Silicon macOS. The project translates the PSP Allegrex module to C and links it with a game-specific HLE runtime.
Windows builds use clang-cl with Direct3D 12 or Vulkan, XAudio2, Media Foundation, and SDL3. Apple Silicon builds use native arm64 code, AppKit, SDL3, VideoToolbox, and Vulkan over Metal through MoltenVK. Both platforms share the same recompiled game code, PSP-compatible savedata, input system, software reference renderer, and optional twin-stick controls.
This project is not affiliated with or endorsed by Guerrilla or Sony Interactive Entertainment. It does not distribute a game executable, generated game code, disc data, saves, or other game assets.
Important
This repository publishes source, not a ready-to-play .exe or .app.
Build the program locally and combine it with a supported disc image that
you legally own. Generated game code, disc data, and copyrighted game assets
must remain on your computer and must not be uploaded or committed.
Note
Related project: Killzone: Liberation Blender add-on
imports maps, static and skinned models, armatures, materials, and PSP
textures from your own game ISO or extracted .core lumps. It is maintained
separately and does not include game data.
| Area | Current state |
|---|---|
| Platform | Windows 10/11 x64 executable and Apple Silicon macOS arm64 app |
| Gameplay | Tutorial and Mission 1 paths have been completed on Windows; deterministic menu, movie, and live Mission 1 routes pass on macOS; full-game validation remains in progress |
| Graphics | D3D12, Vulkan, and software on Windows; Vulkan through MoltenVK/Metal and software on macOS; hardware renderers support 1x-8x internal rendering, 1x-5x xBRZ, and SMAA 1x High |
| Audio/video | XAudio2 and Media Foundation on Windows; SDL3 audio and VideoToolbox on macOS; shared SAS/ATRAC support |
| Input | Keyboard/mouse, SDL gamepads, native remapping, hot-plug recovery, and optional twin-stick controls |
| Saves | PSP-compatible secure savedata is implemented; full-game validation remains in progress |
| Online | Original infrastructure services are gone; ad-hoc multiplayer is not implemented |
| Distribution | Source release only; the executable/app and generated game image are built locally |
This is a working port, not yet a fully validated replacement for the original game. Chapters 2-4, challenges, user-supplied Chapter 5, and long soak testing remain release-validation work.
- Native x64 executable built with clang-cl.
- Direct3D 12 is the default renderer; Vulkan and a software reference renderer are also available.
- D3D12 supports variable-rate shading, 1x-8x internal rendering, 1x-5x xBRZ, SMAA 1x High, and persistent pipeline data.
- Native graphics/controller dialogs, XAudio2 output, and Media Foundation H.264 movie decoding.
- Portable settings remain beside the locally built executable.
- Native arm64 executable and scheduler fibers with guarded stacks; no
deprecated macOS
ucontextdependency. - Retina-aware Vulkan presentation through MoltenVK and Metal, including display-scale changes and F11 or Control-Command-F fullscreen.
- Automatic M-series quality profiles plus complete Manual control over internal resolution, xBRZ texture scaling, and SMAA.
- Native AppKit ISO picker, graphics settings, controller remapper, alerts, on-screen keyboard, and persistent Application Support paths.
- SDL3 audio and gamepad lifecycle handling plus hardware-required VideoToolbox H.264 movie decoding.
- Project documentation index
- Graphics and input configuration reference
- Remaining work and release gates
- Evidence-backed technical findings
- Original architecture and implementation plan
- Development archive
- Credits and third-party provenance
No game disc, executable, generated game C, or game asset is distributed by this project. You must provide your own legally obtained copy of the supported community-distributed US v1.20 image:
- Size:
568,498,176bytes - SHA-1:
5bc4fc8cd8d72c9c2e7c1c03a4325a29bed6e69a
This is not byte-identical to Redump's retail USA disc, which is
581,632,000 bytes with SHA-1
dda1a72c28ccdd8ddd2f3cbfd2fa3188962b0458. See
research/kzl_provenance.txt.
The retail v1.00 disc is not interchangeable with v1.20 generated code. Supporting it requires a separate verified extraction configuration, generated translation units, addresses, and overrides. Bypassing the v1.20 identity check does not produce a valid v1.00 build.
Extraction verifies that identity and the hashes of every required file.
Do not upload or commit the ISO, PRX, PSP.DAT, generated C, savedata, or
CHAPTER5.BIN; the repository ignore rules intentionally exclude them,
including the local memstick/ tree. This project does not provide or help
locate copyrighted game data.
- Git with submodule support
- Python 3.11 or newer (the tested Apple setup uses Homebrew Python 3.13)
- CMake 3.25 or newer and Ninja
- Windows 10 or 11 x64
- Visual Studio 2022 Build Tools with:
- clang-cl/LLVM tools
- MSVC v143 libraries
- Windows 11 SDK
- Vulkan SDK for the combined D3D12/Vulkan preset. A standard
C:\VulkanSDK\<version>installation is detected automatically. - DirectX Shader Compiler (
dxc.exe) only when regenerating the checked-in D3D12 shaders
PIX for Windows is optional but recommended for GPU debugging. The standard
Windows preset downloads the official pinned SDL3 VC development package when
SDL3 is not already discoverable by CMake. Set KZL_FETCH_SDL3=OFF and provide
SDL3_DIR to require a local package instead.
- An Apple Silicon Mac (M1 or newer)
- macOS with Xcode Command Line Tools
- Homebrew
xcode-select --install
brew install cmake ninja python@3.13 pkg-config \
sdl3 vulkan-loader vulkan-headers molten-vkThe CMake preset targets macOS 13 and arm64. The effective deployment floor of a locally packaged app can be higher when locally installed Homebrew libraries were built for a newer macOS release. A protected release matrix with appropriately built dependencies is still required before publishing a minimum supported macOS version.
Clone the project and its runtime submodule:
git clone --recurse-submodules https://github.com/Tzeentchnet/KillzoneLiberation-Recomp.git
cd KillzoneLiberation-Recomp
Extract and verify the disc, then generate the translated C and relocated
image. Everything written under build/ remains local and ignored:
Generation uses the measured boot call-target audit to place observed
functions in /O2 translation units and all other game functions in /O1
units. Release builds retain precise, non-contracting floating point on both
platforms. Windows startup enables x86 flush-to-zero and
denormals-are-zero to match the PSP's single-precision mode.
Run these commands from PowerShell:
python tools\kzl\extract.py C:\path\to\Killzone_Liberation_v1.20_US.ISO
python tools\kzl\gen.pyFrom a Visual Studio x64 developer shell, configure and build the combined D3D12/Vulkan executable:
cmake --preset clang-cl
cmake --build --preset clang-cl --target kzl_driverThe dependency-free software reference build uses a separate preset:
cmake --preset clang-cl-software
cmake --build --preset clang-cl-software --target kzl_driverAutomatic rendering selects D3D12 when it is compiled in. Launch the combined build with the supported ISO:
$env:PSP_ISO = 'C:\path\to\Killzone_Liberation_v1.20_US.ISO'
out\build\clang-cl\kzl.exe --boot `
build\kzl\gen\kzl_image.bin 08804000 08804000 none --guiThe executable validates the ISO size and SHA-1 before allocating guest memory. A missing or different image exits with an explicit supported-version error.
PYTHON="$(brew --prefix python@3.13)/bin/python3.13"
"$PYTHON" tools/kzl/extract.py \
/path/to/Killzone_Liberation_v1.20_US.ISO
"$PYTHON" tools/kzl/gen.pyConfigure the native arm64 build and create the local app:
cmake --preset macos-arm64
cmake --build --preset macos-arm64 --target kzl_app
open "out/build/macos-arm64/Killzone Liberation.app"The first launch opens a native picker for the verified v1.20 image, followed by the graphics and controller settings. The ISO remains external to the app and is revalidated before guest memory is allocated.
The clang-cl preset builds a native x64 executable with D3D12, Vulkan, and
the software reference renderer. D3D12 is selected automatically and is the
recommended Windows path. Both hardware renderers support 1x-8x internal
resolution, 1x-5x xBRZ texture scaling, and SMAA 1x High. D3D12 can use
variable-rate shading on supported GPUs; Manual mode exposes full-rate shading
for maximum image quality.
Windows audio uses XAudio2, movie video uses Media Foundation H.264 decoding,
and SDL3 provides the window and gamepad layer. The locally generated
kzl_image.bin, runtime assets, and fonts are copied beside kzl.exe; the ISO
remains external and is resolved through PSP_ISO.
The preset builds an arm64 Mach-O executable and selects the SDL3/Vulkan
renderer. MoltenVK translates that Vulkan work to Metal; this is the supported
Metal-backed path rather than a separate native Metal renderer.
The Vulkan window renders at the Mac display's native backing resolution,
recreates its swapchain when the drawable or display scale changes, and
supports both F11 and Control-Command-F for fullscreen. Its optional
three-pass SMAA 1x High post-process runs at the selected internal resolution.
New Mac configurations use deterministic Automatic quality. The policy
selects a conservative Apple-GPU tier, caps it to useful drawable detail and
Vulkan limits, and logs the choice; Manual retains complete control.
M1/M2 use 2x (3x for Pro/Max/Ultra), M3/M4 use 3x (4x for
Pro/Max/Ultra), and the measured M5 profile uses 4x with SMAA. Unknown devices
fall back to 2x. xBRZ remains a manual option because its measured warm-up
cost is not yet suitable for an automatic default.
The Vulkan path also persists its GE and SMAA pipeline cache under Application
Support. Cache files are accepted only for the matching device, driver,
pipeline-cache UUID, shader set, and cache schema, then replaced atomically at
clean shutdown.
At scaled internal resolutions, capable Vulkan devices upload logical
framebuffer data once and expand it with an exact nearest GPU blit instead of
CPU-expanding the host transfer. The CPU path remains available for
diagnostic A/B runs.
The macOS preset intentionally remains generic arm64 without LTO. On measured
M5 Mission 1 runs, AppleClang ThinLTO increased native guest execution time by
about 19% and grew the executable by about 96 MiB. -mcpu=apple-m1 changed
native execution time by about -2.4% but produced no repeatable frame-time or
pacing improvement. Both experiments remained pixel-exact and were rejected
rather than becoming release defaults.
Rebuild or refresh the Finder-launchable app after changing the executable, generated game image, runtime assets, or packaging:
cmake --build --preset macos-arm64 --target kzl_app
open "out/build/macos-arm64/Killzone Liberation.app"The app embeds SDL3, the Vulkan loader, MoltenVK, free fonts, runtime assets, and the locally generated image. It does not copy or embed the ISO. The local bundle is ad-hoc signed, checks that no disc image was included, and launches without Homebrew library or Vulkan environment paths. Its third-party libraries inherit the OS compatibility of the locally installed packages; the protected M1 release matrix is still required before publishing a minimum supported macOS claim.
Homebrew's Vulkan loader normally discovers MoltenVK automatically. If device enumeration fails, point the loader at its ICD explicitly:
export VK_ICD_FILENAMES="$(brew --prefix molten-vk)/etc/vulkan/icd.d/MoltenVK_icd.json"The first Finder launch opens a native picker for the verified v1.20 image,
then native graphics and controller settings. The selected ISO path is stored
under Application Support; PSP_ISO remains the highest-priority automation
override. The command-line development path remains available:
export PSP_ISO=/path/to/Killzone_Liberation_v1.20_US.ISO
out/build/macos-arm64/kzl --boot \
build/kzl/gen/kzl_image.bin 08804000 08804000 none --guiSome prerelease macOS SDK text stubs contain an arm64e.x1 architecture that
older Apple linkers reject. If that exact linker error occurs and an older SDK
is installed, configure with it explicitly:
cmake --preset macos-arm64 \
-DCMAKE_OSX_SYSROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdkBounded menu, movie, and live Mission 1 movement routes have been verified
with the Vulkan GE renderer through MoltenVK on Apple Silicon. New macOS
graphics configurations use the Automatic policy described above; legacy
files migrate to Manual and retain their exact values. Select Manual and set
internal_resolution = 1, or use SR_VK_SCALE=1, to force native resolution
for diagnostics. Higher resolutions can be slower. On an Apple M5, one
normally paced first-mission test averaged
30.312, 29.979, and 29.843 game presentations/s at 2x, 3x, and 4x,
respectively, with texture scaling off. The 3x and 4x results are close to
nominal 30 FPS but do not reach 30 FPS exactly. Other scenes and hardware may
perform differently; the entire game has not been validated.
On macOS, PSMF H.264 movie video uses VideoToolbox with hardware acceleration
required and verified; ATRAC movie audio uses the shared decoder and SDL3
output. On Apple M5, a complete intro returned to the title screen with
2,432 video frames and 1,735 ATRAC frames decoded; the maximum active
audio/video timestamp separation was 8,360 ticks (about 93 ms). This is not an
end-to-end audio synchronization measurement. An independent full-file decode
produced 2,435 video and 1,752 audio frames; the in-game HLE stops earlier at
the movie's logical tail. Set SR_MPEGLOG=1 to log decoder selection and movie
playback. If hardware decoding is unavailable, the decoder reports an error
rather than silently using software.
PSP text entry uses a native AppKit prompt on macOS. The scheduler maps PSP
threads to a native arm64 fiber context with guarded, demand-paged stacks. The
switch preserves the AArch64 nonvolatile integer registers, ABI-required SIMD
lanes, stack/frame/link registers, FPCR, and FPSR without relying on Apple's
deprecated ucontext API.
Native sleep/wake notifications pause and resume SDL audio, rebase scheduler
pacing so time asleep is not replayed as a catch-up burst, and force a redraw.
SDL foreground, focus, minimize, display, and controller hot-plug events clear
stale input and reopen another connected gamepad when available.
Both platforms provide native graphics and controller dialogs and use the same portable INI format.
The first windowed run opens the graphics and controller settings. Reopen both dialogs or only the controller remapper with:
out\build\clang-cl\kzl.exe --configure
out\build\clang-cl\kzl.exe --configure-inputNew Windows configurations use D3D12 and Manual quality:
renderer = d3d12
quality = manual
internal_resolution = 2
texture_scale = 1
d3d12_full_rate = 0
anti_aliasing = off
skip_startup = offgraphics.ini and input.ini are stored beside kzl.exe. Set PSP_ISO to
the supported disc image before launching the game.
The first app launch opens the ISO picker, graphics settings, and controller settings. From a development build, reopen both dialogs or only the controller remapper with:
out/build/macos-arm64/kzl --configure
out/build/macos-arm64/kzl --configure-inputNew configurations use renderer = vk and quality = auto. Existing
configuration files without a quality entry migrate to Manual and keep
their exact resolution, texture, and anti-aliasing values.
Mutable Mac files live under
~/Library/Application Support/KZLRecomp/: graphics.ini, input.ini,
launcher.ini, and the shared ms0 tree. Existing sibling graphics and input
files are copied there only when the destination does not already exist.
SR_SETTINGS_DIR, the explicit config variables, SR_FSDIR,
SR_MEMSTICK, and PSP_ISO continue to isolate automation.
The controller dialog's Play Game button saves pending bindings and starts
the game with the selected graphics settings. The build copies
kzl_image.bin beside the development executable and, on macOS, into the
locally built app's resources. The ISO remains external and is revalidated
before use.
D3D12 is the recommended Windows renderer; Vulkan is the production renderer
on macOS. Both support 1x-8x internal resolution, 1x-5x xBRZ texture scaling,
and SMAA 1x High. A pixel-exact software reference renderer remains available
for diagnostics. input.ini holds keyboard, mouse, gamepad, analog, and
experimental opt-in twin-stick settings.
See docs/CONFIGURATION.md for the full graphics dialog reference, the 4K path, the controller remapper, and the twin-stick preset.
The public CI workflow runs on Windows x64 using only tracked source and synthetic fixtures. The same Python coverage can be run locally on either platform.
On Windows:
python -m unittest discover -s tools\tests -p "test_*.py"
python -m unittest `
external\psp-recomp\tools\tests\test_codegen_dispatch.py `
external\psp-recomp\tools\tests\test_ppmdiff.py `
external\psp-recomp\tools\tests\test_tracediff.py
python tools\kzl\content_audit.pyOn macOS:
PYTHON="$(brew --prefix python@3.13)/bin/python3.13"
"$PYTHON" -m unittest discover -s tools/tests -p "test_*.py"
"$PYTHON" -m unittest \
external/psp-recomp/tools/tests/test_codegen_dispatch.py \
external/psp-recomp/tools/tests/test_ppmdiff.py \
external/psp-recomp/tools/tests/test_tracediff.py
"$PYTHON" tools/kzl/content_audit.pyThe runtime-only build compiles every redistributable runtime source without generated game code:
On Windows, use the same configuration as public CI:
cmake -S . -B out\build\runtime-only -G Ninja `
-DCMAKE_BUILD_TYPE=Release `
-DCMAKE_C_COMPILER=clang-cl `
-DCMAKE_CXX_COMPILER=clang-cl `
-DKZL_RUNTIME_ONLY=ON `
-DBUILD_TESTING=OFF
cmake --build out\build\runtime-only --target kzl_runtime_compileOn Apple Silicon macOS, use the runtime preset:
cmake --preset macos-arm64-runtime
cmake --build --preset macos-arm64-runtime --target kzl_runtime_compileFull HLE, renderer, movie/audio, and protected 50-frame comparison tests require
locally generated code and a user-supplied disc; they are run only on the
trusted self-hosted workflow.
That workflow also compares the runtime's unique interpreter-fallback targets
against config/kzl_dispatch_misses.txt; the supported capture currently
allows no generated-dispatch misses.
Three scheduler CPU windows are also compared instruction-for-instruction
against the patched PPSSPP interpreter using
config/kzl_scheduler_trace_points.txt; trace files remain protected and only
the JSON pass/fail summary is retained.
docs/- plan, task list, findings, and development historyconfig/- pinned disc/module configuration and codegen overridestools/kzl/- extraction, archive, trace, and golden-frame toolsresearch/- reproducible static/runtime analysis reportsexternal/psp-recomp/- pinned recompiler/runtime forkbuild/andout/- ignored local generated/build output
Every v* tag is published with a deterministic corresponding-source zip
containing the parent tree and the exact pinned external/psp-recomp tree.
Use that attached -source.zip rather than GitHub's automatically generated
source archive, which records only the submodule gitlink. The
release workflow refuses dirty or mismatched
trees and runs the content audit before publishing.
Build the same archive locally from a clean checkout with:
# Windows
python tools\kzl\source_bundle.py --version v0.1.0
# macOS
python3 tools/kzl/source_bundle.py --version v0.1.0
No redistributable game executable is currently published: generated game code and the required game data remain user-supplied and outside this repository.
Project-authored and PPSSPP-derived code is licensed GPL-2.0-or-later; see LICENSE. The secure-savedata path includes GPL-3.0-or-later libkirk, so linked binaries must comply with GPL-3.0-or-later. The license covers this project's source, not the original game or its assets.
Third-party provenance and separately licensed components are documented in CREDITS.md and external/psp-recomp/CREDITS.md.