File Format

Format and Compatibility

.dtr is the compressed replay format consumed by the DemoTracer CounterStrikeSharp loader and BotController native runtime.

The repository's .dtr format contract is canonical for byte offsets and parser implementation. This page explains the release gates users need when installing or upgrading.

Current Version Matrix

Contract	Current value
Magic	CSDTRREC
Writer format	.dtr v7
Runtime reader	.dtr v3 through v7
Endianness	Little-endian
Manifest ABI	17
BotController native ABI	16
v0.6.0 bundled native ABI minor	31
DemoTracer companion API	6
DemoTracer BotHider API	1

Existing v3-v7 replay files remain readable by v0.6.0; no reconversion is required solely for this upgrade. Replace the complete Playback Bundle so the managed and native components stay matched.

What Changed Across Replay Versions

Version	Notable capability
v3	Legacy movement/tick/subtick body; no projectile events.
v4	Added projectile metadata.
v5	Added play_start_tick_index and bounded freeze-time replay context.
v6	Added the high-fidelity metadata JSON blob.
v7	Added a section container plus optional command-frame and movement-extra sections.

The current writer preserves stored replay evidence without quantization or interpolation. f32, integer, subtick, projectile, command-frame, and UTF-8 JSON values retain their stored representation.

v7 Section Model

Every v7 file contains a header and section directory. Required sections hold:

• movement snapshots;
• per-tick metadata;
• subtick input records.

Optional sections may hold:

• projectile events;
• high-fidelity metadata;
• command frames;
• movement-extra data.

Unknown optional sections can be skipped by length. Required-section and row count mismatches must be rejected rather than guessed.

Manifest vs .dtr

Individual .dtr files are player/side/round replays. manifest.json is the higher-level contract that groups them and carries map, round, player, economy, chat, avatar, optional cosmetic, and compatibility metadata. Pool workflows add pool_manifest.json above multiple demo manifests.

Normal server playback should point dtr_go at the manifest, not load isolated .dtr files manually.

Compatibility Rules

• A manifest ABI mismatch is a hard error. Update the complete converter and Playback Bundle set.
• A BotController major ABI mismatch is a hard error. For v0.6.0, minor 31 adds replay-buffer release capability; older minors should be replaced.
• Companion plugins must target DemoTracer API 6.
• .dtr v7 requires a Playback Bundle with native ABI 16 support.
• Do not change magic, format layout, manifest ABI, or native/API contracts without an explicit version decision and matching documentation.

Check the installed runtime with:

dtr_runtime
dtr_doctor "<manifest.json>"

Parser Checklist

A third-party reader should:

1. verify CSDTRREC and the supported version range;
2. use little-endian fixed-width reads;
3. enforce bounded counts and section lengths;
4. reject duplicate required sections and row-count mismatches;
5. skip unknown optional v7 sections by their declared size;
6. preserve values losslessly when rewriting a replay.

Do not infer newer fields for older versions. Absent evidence must remain absent.