hlviewer-kz

JavaScript library for viewing GoldSrc maps and playing replays entirely in the browser.

This is a fork maintained by kreedz.com, based on hlviewer.js by Stefan Stojković (MIT). Source: github.com/kreedzcom/hlviewer.js. It adds native KRPZ (.krpz) replay support for the cs16kz KZ plugin and kz-global-api.

Upstream live demo: skyrim.github.io/hlviewer.js

Supported formats

Extension	Description
.dem	GoldSrc demo replays (original hlviewer.js behaviour)
.krpz	KZ KRPZ replays — zstd-compressed, column-major body from cs16kz
.bsp	Map-only viewing

Both .dem and .krpz use the same playback engine after parsing. KRPZ replays do not embed audio; footstep sounds are synthesized during playback using the same logic as kz_replay_pb.cpp in the cs16kz plugin (ground + speed threshold, jump-hold reset, plr_sound cooldown, alternating pl_step1–pl_step4).

Installation

Build from source:

npm install
npm run build

Include the built files from dist/:

<link rel="stylesheet" href="path/to/hlviewer-kz.css">
<script src="path/to/hlviewer.min.js"></script>

Or link the package from a local path / private registry (used by kreedz.com):

"hlviewer-kz": "file:../hlviewer.js"

Quick start

Create a container with explicit width and height:

<div id="hlv-target" style="width:800px; height:600px"></div>

Initialize the viewer with asset paths:

const hlv = HLViewer.init('#hlv-target', {
  paths: {
    base:    '/',
    replays: 'res/replays',
    maps:    'res/maps',
    wads:    'res/wads',
    skies:   'res/skies',
    sounds:  'res/sounds'
  },
  replayCameraMode: 'pov' // 'pov' (first person) or 'entity' (third person)
})

Load a replay or map by extension:

hlv.load('some_file.dem')   // GoldSrc demo
hlv.load('some_file.krpz')  // KZ KRPZ replay
hlv.load('some_map.bsp')    // map only

KRPZ streaming API

For server-side replay delivery (e.g. kreedz.com), bytes can be loaded without a .krpz filename in the URL:

// Opaque stream URL (token-based, no file extension exposed)
hlv.loadKrpzStream('/viewer/replay/stream/<token>')

// Prefetched ArrayBuffer (e.g. after a session POST)
hlv.loadKrpzFromBuffer(arrayBuffer)

On load, the viewer emits a krpzmetadata event with playerName and mapName parsed from the replay header.

KRPZ asset requirements

When playing .krpz files you need:

• Map BSP — {mapName}.bsp on the configured maps path (name comes from the replay header)
• WADs / skies — same as for .dem, depending on the map (embedded textures may avoid WADs)
• Footstep sounds — player/pl_step1.wav … pl_step4.wav on the sounds path (synthesized during playback)

See docs/KRPZ_Format.md for format details and camera options.

Local development

Place test assets under res/ (gitignored). Then:

npm run dev    # Vite dev server — open index.html demo
npm test       # vitest (KRPZ codec + footstep tests)
npm run build  # tsc + vite library build → dist/

The dev server returns real 404s for missing /res/* files so failed asset loads do not block playback.

Documentation

File	Contents
docs/KRPZ_Format.md	KRPZ playback behaviour, config, parser layout
NOTICES.md	Upstream and dependency attribution

Binary format specification: cs16kz replay format.

License

MIT — see LICENSE. Fork modifications are © kreedz.com; original hlviewer.js © Stefan Stojković.