readme.txt

July 15, 2026 ยท View on GitHub

TyrQuake (libretro)

A libretro core for Quake and its mission packs, based on TyrQuake 0.62 by Kevin Shanahan (aka. Tyrann) -- http://disenchant.net

TyrQuake is a conservative branch of the original Quake source code: it keeps the look and feel of the id Software originals while fixing bugs and adding carefully-scoped enhancements. This libretro port turns it into a core that runs inside RetroArch and other libretro frontends, with renderer, video, audio and input features layered on top of the faithful base engine.

Loading content

  • Load a .pak file (e.g. id1/pak0.pak) from a Quake data directory. The full directory layout around the pak is used, so custom content in the same game directory is picked up as usual.
  • Mission packs are detected automatically from the content path:
    • "hipnotic" -> Scourge of Armagon (-hipnotic)
    • "rogue" -> Dissolution of Eternity (-rogue)
    • "quoth" -> Quoth (-quoth)
  • Any other (non-id1) game directory is launched as a mod via -game, so total conversions and standalone mods work by loading their pak from inside their own directory.
  • Shareware, registered and mod paks are all supported.

Renderer backends

  • Software renderer: the classic 8-bit palettized span rasterizer, extended well beyond the original (see "Rendering features" below). Output is RGB565.
  • Vulkan hardware renderer (optional, RHI_HAVE_VULKAN=1 builds): uses the libretro Vulkan HW context. Presentation runs as a GPU compute dispatch (palette LUT expansion on the GPU) rather than a classic graphics pipeline.
  • Compute rendering option: on HW backends with compute support, the 3D view is rendered by a GPU port of Quake's software rasterizer (spans, affine texturing, surface cache, alias edge stepping) -- pixel-identical to the software renderer but offloaded to the GPU, which is much faster at high internal resolutions. When disabled, the HW backend uses traditional hardware rasterization instead.
  • "Auto" renderer selection picks the best hardware backend the frontend offers and falls back to software when no HW context is available.

Rendering features

All of these are available in the software renderer and exposed in the in-game Options -> Video menu (as well as via console cvars):

  • Internal resolutions from 320x200 up to 1920x1200 (45 presets), with sensible per-platform defaults (e.g. 400x240 on 3DS).
  • Dither filtering (ordered-dither texture sampling for a smoothed look without leaving the palette pipeline).
  • Colored lighting: Half-Life / Quake II-style RGB lighting in the software renderer, including support for .lit sidecar files (with header and size validation), plus a light-dither option.
  • Phong shading on models, tri-state: Off / Phong / Phong + specular.
  • Transparent liquids: independent alpha controls for water, lava, slime and teleporters, plus an underwater liquid-blend overlay.
  • Polygon subdivision: runtime tessellation of alias (model) meshes, up to 3 passes, to smooth out low-poly silhouettes.
  • Smooth animation and smooth movement: keyframe (r_lerpmodels) and transform (r_lerpmove) interpolation for fluid entity motion at high framerates.
  • Entity shadows.
  • Water warp with adjustable intensity (r_waterwarp_scale).
  • Level-of-detail (mip) control.
  • Aspect-ratio correction.
  • UI scaling (scr_uiscale): integer scaling of the 320x200-native HUD, menus and console at high resolutions.
  • Gamma, brightness and contrast controls.
  • Crosshair options.
  • Persistent gibs option (Options -> Game).
  • Chase camera / third-person view with camera-type selection and a first-person toggle in the menu.

Timing

  • Runs at fixed frametimes for consistent physics and demo playback.
  • Framerate is selectable from 10 to 600 fps, or "Auto", which queries the frontend's target refresh rate and matches it. (Values above 72 fps can expose original-engine timing quirks.)

Audio

  • Sound mixed at a selectable output rate: 32 / 44.1 / 48 / 96 kHz, or "Auto", which matches the frontend's reported target sample rate to bypass the frontend resampler entirely (lower latency, no extra filtering).
  • Float PCM output is negotiated with frontends that support it, with a transparent fallback to the standard 16-bit integer batch path.
  • Music-stream decode is float-based with bit-identical int16 results across platforms and FPUs.

Soundtrack / background music

  • CD-audio replacement: rips placed in a "music" directory inside the game directory (music/track02., etc.) play automatically as the level soundtrack.
  • WAV, FLAC and Ogg Vorbis are enabled by default; MP3, Opus, and tracker formats (MikMod, ModPlug, UMX) are available as build-time options.
  • Mod-supplied tracks take priority over id1 tracks of the same number, and file format is resolved per-track.
  • "music" console command for playing tracks manually.

Input

Four selectable input device types:

  • Gamepad Classic: original-style layout with a run-mode toggle.
  • Gamepad Classic Alt: alternative classic layout.
  • Gamepad Modern: dual-analog FPS layout (move + look on sticks).
  • Keyboard + Mouse: full keyboard support via the libretro keyboard callback plus relative mouse look with five mouse buttons (including wheel up/down). The console is reachable on ` / ~ / '.

Additional input features:

  • Configurable analog stick deadzone (0-30%).
  • Invert Y axis option.
  • Rumble support: strong motor feedback scaled by damage taken, weak motor pulses on item pickup.
  • Fully rebindable controls through the in-game Customize Controls menu.

Multiplayer

  • NetQuake UDP networking on platforms built with HAVE_NETWORKING=1: LAN games, server search and direct connect through the in-game Multiplayer menu, with cooperative and deathmatch game options (frag limits, time limits, skill, episode selection, including the mission-pack episode lists).
  • Local (loopback) games on all platforms.

Saves and memory

  • Native Quake save/load system; savegames are written to the frontend's save directory. (Libretro savestates are not currently implemented.)
  • The engine heap (hunk) is sized automatically from the memory the frontend reports as available (a quarter of free RAM, capped at 256 MB and never below the tuned per-platform default), so large modern maps and mods load on capable systems while low-memory platforms keep a conservative footprint.

Platforms

Builds for a wide range of libretro targets, including Windows (MinGW and MSVC toolchains as old as 2003), Linux, macOS, iOS/tvOS, Android, Emscripten (web), Nintendo Switch, Wii, Wii U, GameCube, 3DS, PlayStation Vita, PSP, PS3, Xbox / Xbox 360, Raspberry Pi and various embedded handhelds (GCW-Zero, Miyoo, RetroFW/Dingux).

Building

make

produces tyrquake_libretro for the host platform. Cross builds use the usual libretro conventions, e.g.:

make platform=vita
make platform=libnx

Optional build flags:

RHI_HAVE_VULKAN=1     enable the Vulkan renderer backend
                      (requires vendored Vulkan headers, see
                      deps/vulkan/README.md)
HAVE_NETWORKING=0/1   toggle UDP multiplayer support
USE_CODEC_MP3=1       enable MP3 soundtrack support
USE_CODEC_OPUS=1      enable Opus soundtrack support
USE_CODEC_MIKMOD=1    enable MikMod tracker music
USE_CODEC_MODPLUG=1   enable ModPlug tracker music
USE_CODEC_UMX=1       enable UMX tracker music

Credits and license

  • Quake is Copyright (C) 1996-1997 Id Software, Inc.
  • TyrQuake is developed by Kevin Shanahan (aka. Tyrann), http://disenchant.net
  • libretro port by the libretro team and contributors.

Distributed under the GNU General Public License, version 2 or later; see LICENSE.txt. The original id Software readme is preserved as readme-id.txt.