GK3HD

This project's goal is to modernize Gabriel Knight 3 while faithfully preserving its original look and feel, using its highest supported resolution of 1024×768 as the visual reference.

Features

Features and fixes

• 🖥️ Select modern resolutions from the in-game menu
• 🗺️ Restored SIDNEY and driving map functionality at modern resolutions
• ⌨️ Improved keyboard camera controls that transition from precise to fast
• 📐 UI scaled to match the 1024×768 reference
• 💿 Removed the game's disc drive requirement

Graphics improvements

• ⚙️ Highest-quality graphics settings by default
• 🔍 Added support for and enabled anisotropic filtering by default
• 🖼️ 99.63% of textures (>1024 pixels) upscaled at 4× resolution with SeedVR2 3B
• 🔤 90% of font atlases reconstructed at 4× resolution for sharper text
• 🎬 Cinematics upscaled at 4× resolution, with a smoother 60 fps Sierra logo
• 📍 Corrected location alignment with background on the driving map
• 👁️ Corrected facial feature alignment for 4× textures
• 🎨 Corrected gamma and colors to match the original game's native rendering

Performance and compatibility improvements

• ⚡ Modern Vulkan rendering with a GK3-tuned DXVK-Sarek build
• 🚀 Faster high-resolution rendering with fewer readbacks and less overhead
• 🧩 Support for the Steam and GOG editions
• 🐧 Experimental Linux and Steam Deck support through Proton

Install and use

Warning

gk3hd is currently considered beta software.

Tip

On Linux, select Proton 9.0 in GK3's Steam Properties → Compatibility. Close GK3 and exit Steam, then run the commands below (in Desktop Mode on Steam Deck).

Install uv, then run this from a terminal on Windows or on Linux with Steam and Proton:

uvx gk3hd install  # Install renderer, patch `GK3.exe`, and download/install textures and videos
uvx gk3hd status
uvx gk3hd uninstall

Installation selects the current display resolution and finds Steam libraries automatically. Windows requires Vulkan-capable graphics drivers. Nonstandard game locations can use --game-dir PATH (protected Windows folders may require an elevated terminal).

Advanced use

Use gk3hd --help for an overview of all top-level commands.

Patch the game

uvx gk3hd patch list               # Browse patch groups and individual patches
uvx gk3hd patch install --dry-run  # Preview without changing the game
uvx gk3hd patch install            # Apply the recommended executable patches
uvx gk3hd patch verify             # Verify patches and game settings
uvx gk3hd patch uninstall          # Restore the original executable and settings

This leaves the renderer and textures untouched. Game location and display resolution are detected automatically; override them with --game-dir PATH and --resolution 3840x2160. Use --group GROUP or repeat --patch PATCH_ID to choose patches from patch list. The two groups are recommended (default) and testing (recommended patches plus skipping all movies). --dry-run lists the exact patches, including dependencies, without changing the game.

Build and install the renderer

Install the published renderer independently, or build our modified DXVK-Sarek renderer locally:

uvx gk3hd renderer build            # Download source, build and test in `<GAME>/gk3hd/renderer/`
uvx gk3hd renderer install --local  # Reinstall the last verified local build
uvx gk3hd renderer verify           # Check the DLL and its platform settings
uvx gk3hd renderer uninstall        # Restore the previous renderer and settings (uninstall patches first)

Close GK3 before installation or removal. No manual copying or registry editing is needed. Building requires the Windows C++ toolchain, activated automatically from a normal terminal; install the result with renderer install --local. Builds live under <GAME>/gk3hd/renderer/; matching verified builds are reused. The game is detected automatically; use --game-dir PATH to select another installation. install --local finds that game's last verified build, regardless of your current directory. See the native build requirements. Use renderer download to download only, or renderer install --dll PATH to select a local DLL. renderer uninstall restores the previous settings after executable patches have been removed.

Extract, upscale, and install textures

To extract and upscale the original textures locally, use a persistent tool installation:

uv tool install "gk3hd[upscale]" --torch-backend auto
gk3hd textures extract          # Extract BMPs from game archives to `<GAME>/gk3hd/textures/original/`
gk3hd textures analyze          # Classify textures and write `<GAME>/gk3hd/textures/texture-analysis.json`
gk3hd textures upscale          # Apply each texture's pipeline and write PNGs to `<GAME>/gk3hd/textures/upscaled/`
gk3hd textures pack             # Bundle PNGs into a versioned texture-pack ZIP (or ZIP parts)
gk3hd textures install --local  # Convert the local pack to BMPs in `<GAME>/gk3hd/textures/installed/` and enable in `GK3.ini`
gk3hd textures verify           # Verify installed textures and their `GK3.ini` configuration
gk3hd textures uninstall        # Remove installed textures and restore the previous `GK3.ini`

These commands discover GK3 automatically and keep every texture stage under gk3hd/textures/ in the game directory: extracted BMPs in original/, the shared texture-analysis.json beside the stage directories, release-ready PNGs in upscaled/, and game-ready BMPs in installed/.

uv's automatic PyTorch backend selection uses a supported GPU when one is available and otherwise falls back to CPU. CPU upscaling works, but is much slower. Project checkouts select PyTorch's CUDA build on Windows automatically.

Extract, upscale, and install videos

The default gk3hd install includes videos. Manage them independently with:

uvx gk3hd videos install    # Download videos and private codecs to `<GAME>/gk3hd/videos/installed/`
uvx gk3hd videos verify     # Verify installed videos, codecs and original source identities
uvx gk3hd videos uninstall  # Remove replacements and codecs, leaving originals untouched

Apply the recommended game patches before playing replacement videos. No system codecs, compiler or additional Python dependencies are needed to install a published pack on Windows or Linux/Proton.

To generate a pack yourself, use the same gk3hd[upscale] tool installation as for textures:

gk3hd videos extract          # Copy original videos to `<GAME>/gk3hd/videos/original/`
gk3hd videos upscale          # Restore cinematics at 4× into `<GAME>/gk3hd/videos/upscaled/`
gk3hd videos build            # Build the private player in `<GAME>/gk3hd/videos/player/` (Windows toolchain)
gk3hd videos pack             # Bundle videos and our player adapter into a versioned ZIP (or ZIP parts)
gk3hd videos install --local  # Install the local pack from `<GAME>/gk3hd/videos/`

Extraction is optional: upscale uses the originals in Data/ if no extracted folder exists. Use --video intro.bik to process one video, or repeat --video for a selection. Verified outputs are reused when resuming.

Note

Cinematics use SeedVR2 3B, without original-image blending, and AV1 CRF 24 (10-bit 4:4:4) with lossless FLAC audio in MKV files. Scene cuts separate temporal inference. Sources at 16 fps or less use independent-frame restoration to avoid motion trails. Approximately 15 fps cinematics, including the Sierra logo, additionally use RIFE to reach 60 fps. Other frame rates and audio timing are preserved. SIDNEY's technical animations retain their original pixels and transparency. Local generation needs a capable GPU, time and disk space.

Development

Test

From a checkout:

uv run poe lint                   # Formatting, lint, types and spelling
uv run poe test                   # Fast tests; never launches GK3
uv run poe test --slow            # Also test reconstruction and native patch execution
uv run poe coverage               # Both suites with coverage (slower instrumentation)
uv run poe visual                 # 12 views: ten day-one scenes, SIDNEY and the driving map
uv run poe visual --suite medium  # 25 views across all three days, including key interfaces
uv run poe visual --suite large   # 100 views: varied locations, characters and interface states
uv run poe visual -k driving      # Select the driving interaction checks

CI runs both portable suites on Linux. Windows API tests run automatically on Windows and are excluded elsewhere. Neither suite needs the game or downloads AI models; slow tests use small, representative fixtures, not the full texture catalog. To run only slow tests, use uv run poe test --slow -m slow.

Visual tests require a patched game with its renderer and textures installed. They compare original textures at 1024×768 against the mod at 4K, using one generated save and curated camera recipes; your own saves are left untouched. The sets are nested: medium includes small, and large includes medium. Medium also covers inventory, the driving map, SIDNEY, save/restore, the title and a timeblock. Large adds more interface states and locations. Captures and animated WebPs go to ignored build/visual/, not your game folder. Resume an interrupted run with --resume build/visual/<run>; unchanged, verified world captures are reused. Start a new run after changing the game, assets or camera recipes. Passing capture checks does not replace reviewing the images for visual fidelity. Use uv run --extra upscale gk3hd textures review to compare texture pipeline alternatives.

Release

Commit your changes on main using conventional commits. From a clean checkout, choose which assets to include:

uv run gk3hd package draft             # New package; reuse published assets
uv run gk3hd package draft --textures  # Also pack/upload the local upscaled PNGs
uv run gk3hd package draft --renderer  # Also upload the last verified local renderer build
uv run gk3hd package draft --videos    # Also pack/upload local videos and the verified player
# Combine --textures, --renderer and --videos as needed

Generate/review changed textures with textures analyze and textures upscale, build a changed renderer with renderer build, or generate videos with videos upscale and build their player with videos build, before drafting. The video pack includes our player adapter. Installation fetches pinned LAV codecs and their notices directly from upstream. No DLLs belong in Git.

The draft command uses Commitizen to bump the version, runs normal checks, commits release metadata, pushes the tag, and uploads a GitHub draft. Don't run cz bump, textures pack or videos pack separately. Review and publish the draft on GitHub to publish to PyPI. Keep older asset releases available for pinned packs and renderer builds. package verify checks that the published assets match their recorded identities.

Gallery

Note

Gameplay comparisons alternate between the original at 1024×768 and GK3HD at 4K. Cinematic comparisons alternate between original frames and their 4× upscales. Open an image to inspect it at full resolution.