Skip to main content

dayzmake_core/navmesh/
capture.rs

1//! `.dzgeo` capture files (spec 3.8): the world params and the tiles of a run, so a run can be
2//! replayed without a server.
3//!
4//! Layout, little-endian: `DZGC`, `u32 version = 1`, a block (`u32 size`, bytes) with the world params
5//! payload (without the protocol version), then one block per tile (the message-5 payload).
6
7use std::collections::BTreeMap;
8use std::fs::File;
9use std::io::{self, BufReader, Read, Seek, SeekFrom, Write};
10use std::path::{Path, PathBuf};
11use std::sync::{Mutex, PoisonError};
12
13use crate::error::ErrorExt;
14use crate::navmesh::client::{MAX_FRAME, read_chunked};
15use crate::navmesh::generate::clip_range;
16use crate::navmesh::wire::{TileInput, WorldParams};
17use crate::warning::{Warning, WarningSink};
18
19const MAGIC: &[u8; 4] = b"DZGC";
20const VERSION: u32 = 1;
21
22/// A capture read from a `.dzgeo` file.
23#[derive(Debug, Clone, PartialEq, Default)]
24pub struct Capture {
25    params: WorldParams,
26    tiles: Vec<TileInput>,
27}
28
29/// Reads a `u32` or reports `None` at a clean or partial end of the stream.
30fn read_u32_opt(r: &mut impl Read) -> io::Result<Option<u32>> {
31    let mut buf = [0u8; 4];
32    let mut got = 0;
33    while got < buf.len() {
34        let Some(rest) = buf.get_mut(got..) else {
35            break;
36        };
37        match r.read(rest) {
38            Ok(0) => return Ok(None),
39            Ok(n) => got += n,
40            Err(e) if e.kind() == io::ErrorKind::Interrupted => {}
41            Err(e) => return Err(e),
42        }
43    }
44    Ok(Some(u32::from_le_bytes(buf)))
45}
46
47/// Reads one block. `None` when the stream ends before the block is complete.
48fn read_block(r: &mut impl Read) -> io::Result<Option<Vec<u8>>> {
49    let Some(size) = read_u32_opt(r)? else {
50        return Ok(None);
51    };
52    if size > MAX_FRAME {
53        return Err(error!("invalid capture block size {size}"));
54    }
55    let len = usize::try_from(size).map_err(|_| error!("invalid capture block size {size}"))?;
56    match read_chunked(r, len) {
57        Ok(bytes) => Ok(Some(bytes)),
58        Err(e) if e.kind() == io::ErrorKind::UnexpectedEof => Ok(None),
59        Err(e) => Err(e),
60    }
61}
62
63impl Capture {
64    /// Reads a capture. A capture cut short keeps every complete tile; a partial trailing block is
65    /// ignored. A tile captured twice keeps the later copy; tiles are sorted by `(z, x)`.
66    ///
67    /// Every record is parsed, so one malformed record fails the whole read. [`CaptureFile`] parses a
68    /// record only when its tile is asked for, and so fails only that tile (the tile of a run is
69    /// reported as failed, the others are built).
70    ///
71    /// # Errors
72    ///
73    /// "not a capture file" (bad magic), "unsupported capture version N", "capture truncated" (cut
74    /// before the world block is complete), "invalid capture block size N" (above 1 GiB), and the
75    /// errors of [`WorldParams::parse`] and [`TileInput::parse`] for a complete but malformed block.
76    pub fn read(r: &mut impl Read) -> io::Result<Self> {
77        let mut magic = Vec::new();
78        r.take(4).read_to_end(&mut magic)?;
79        if magic != MAGIC {
80            return Err(error!("not a capture file"));
81        }
82        let truncated = || error!("capture truncated");
83        let version = read_u32_opt(r)?.ok_or_else(truncated)?;
84        if version != VERSION {
85            return Err(error!("unsupported capture version {version}"));
86        }
87        let block = read_block(r)?.ok_or_else(truncated)?;
88        let params = WorldParams::parse(&block).prepend_error("capture world params")?;
89        let mut tiles: BTreeMap<(i32, i32), TileInput> = BTreeMap::new();
90        let mut index = 0usize;
91        while let Some(block) = read_block(r)? {
92            let tile =
93                TileInput::parse(&block).prepend_error(format!("capture tile record {index}"))?;
94            tiles.insert((tile.z, tile.x), tile);
95            index += 1;
96        }
97        Ok(Self {
98            params,
99            tiles: tiles.into_values().collect(),
100        })
101    }
102
103    /// The world params.
104    #[must_use]
105    pub fn params(&self) -> &WorldParams {
106        &self.params
107    }
108
109    /// The tiles, sorted by `(z, x)`.
110    #[must_use]
111    pub fn tiles(&self) -> &[TileInput] {
112        &self.tiles
113    }
114
115    /// The captured tile `(x, z)`.
116    #[must_use]
117    pub fn tile(&self, x: i32, z: i32) -> Option<&TileInput> {
118        self.tiles
119            .binary_search_by_key(&(z, x), |t| (t.z, t.x))
120            .ok()
121            .and_then(|i| self.tiles.get(i))
122    }
123}
124
125/// Where one tile record of a capture file lies.
126#[derive(Debug, Clone, Copy)]
127struct Record {
128    /// Offset of the payload (after the block's size field).
129    offset: u64,
130    /// Payload size.
131    size: u32,
132}
133
134/// The most tiles a [`CaptureFile`] indexes (the size of the largest plan of the generator).
135const MAX_INDEXED: usize = 1 << 22;
136
137/// What a [`CaptureFile`] can be read from: a file, or anything seekable.
138trait ReadSeek: Read + Seek + Send {}
139impl<T: Read + Seek + Send> ReadSeek for T {}
140
141/// Options of [`CaptureFile::open`] and [`CaptureFile::from_reader`].
142#[derive(Debug, Clone, Default)]
143#[non_exhaustive]
144pub struct CaptureFileOptions {
145    /// Index only the tiles in this range `[x0, z0, x1, z1]` (clipped to the world like the range of
146    /// [`generate`](crate::navmesh::generate::generate); a negative upper bound means the end of the grid).
147    /// `None`: every tile of the world grid. Tiles outside the range read as absent.
148    pub range: Option<[i32; 4]>,
149}
150
151impl CaptureFileOptions {
152    /// Options that index the whole capture.
153    #[must_use]
154    pub fn new() -> Self {
155        Self::default()
156    }
157
158    /// Index only the tiles in `range`.
159    #[must_use]
160    pub fn range(mut self, range: Option<[i32; 4]>) -> Self {
161        self.range = range;
162        self
163    }
164}
165
166/// A capture that is indexed, not loaded: opening reads the world params and the `(x, z)` of every
167/// record (8 bytes each, skipping the rest by seeking), and [`CaptureFile::tile`] reads one record on
168/// demand. Memory is proportional to the number of indexed tiles (at most the range) plus the tiles in
169/// flight, so a range of a multi-gigabyte capture needs only the tiles of that range. The format is the
170/// one of [`Capture`]; use [`Capture::read`] only for small captures that you want in memory.
171pub struct CaptureFile {
172    params: WorldParams,
173    index: BTreeMap<(i32, i32), Record>,
174    file: Mutex<Box<dyn ReadSeek>>,
175    path: Option<PathBuf>,
176    /// The part of the grid that was indexed (`None`: the requested range was empty).
177    indexed: Option<[i32; 4]>,
178}
179
180impl std::fmt::Debug for CaptureFile {
181    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
182        f.debug_struct("CaptureFile")
183            .field("tiles", &self.index.len())
184            .field("path", &self.path)
185            .finish_non_exhaustive()
186    }
187}
188
189impl CaptureFile {
190    /// Opens and indexes the capture file at `path`; see [`CaptureFile::from_reader`].
191    ///
192    /// # Errors
193    ///
194    /// The file cannot be opened, and the errors of [`CaptureFile::from_reader`].
195    pub fn open(
196        path: &Path,
197        options: &CaptureFileOptions,
198        warnings: &mut dyn WarningSink,
199    ) -> io::Result<Self> {
200        let mut capture = Self::from_reader(File::open(path)?, options, warnings)?;
201        capture.path = Some(path.to_path_buf());
202        Ok(capture)
203    }
204
205    /// Indexes a capture read from `reader`. A capture cut short keeps every complete record; a partial
206    /// trailing block is ignored. A tile captured twice keeps the later copy. Records outside the world
207    /// grid are ignored (one note says how many); records outside `options.range` are skipped. The
208    /// records are not parsed here: a malformed record is reported by [`CaptureFile::tile`], and fails
209    /// that tile only (not the whole capture, as [`Capture::read`] does). The records are counted, not
210    /// the tiles: a capture with more records than the world has tiles is refused even if some of them
211    /// repeat a tile (a recording never writes a tile twice).
212    ///
213    /// # Errors
214    ///
215    /// The errors of [`Capture::read`] for the header and the world block, "invalid capture block size
216    /// N", "message truncated" for a record too short to hold its coordinates, "capture has more
217    /// records than the world has tiles" and "too many tiles to index".
218    pub fn from_reader<R: Read + Seek + Send + 'static>(
219        reader: R,
220        options: &CaptureFileOptions,
221        warnings: &mut dyn WarningSink,
222    ) -> io::Result<Self> {
223        let mut reader: Box<dyn ReadSeek> = Box::new(reader);
224        let len = reader.seek(SeekFrom::End(0))?;
225        reader.seek(SeekFrom::Start(0))?;
226        let mut r = BufReader::new(reader);
227        let truncated = || error!("capture truncated");
228        let mut magic = [0u8; 4];
229        if r.read_exact(&mut magic).is_err() || &magic != MAGIC {
230            return Err(error!("not a capture file"));
231        }
232        let version = read_u32_opt(&mut r)?.ok_or_else(truncated)?;
233        if version != VERSION {
234            return Err(error!("unsupported capture version {version}"));
235        }
236        let block = read_block(&mut r)?.ok_or_else(truncated)?;
237        let params = WorldParams::parse(&block).prepend_error("capture world params")?;
238        let (tiles_x, tiles_z) = (params.world.tiles_x, params.world.tiles_z);
239        let wanted = clip_range(options.range, tiles_x, tiles_z);
240        let max_records = u64::try_from(i64::from(tiles_x) * i64::from(tiles_z)).unwrap_or(0);
241        // 4 (magic) + 4 (version) + 4 (size) + the world block.
242        let mut pos = u64::try_from(block.len())
243            .ok()
244            .and_then(|n| n.checked_add(12))
245            .ok_or_else(truncated)?;
246        let mut index = BTreeMap::new();
247        let (mut n, mut outside) = (0u64, 0u64);
248        while let Some(size) = read_u32_opt(&mut r)? {
249            if size > MAX_FRAME {
250                return Err(error!("invalid capture block size {size}"));
251            }
252            let start = pos.checked_add(4).ok_or_else(truncated)?;
253            let end = start.checked_add(u64::from(size)).ok_or_else(truncated)?;
254            if end > len {
255                break;
256            }
257            if size < 8 {
258                return Err(error!("capture tile record {n}: message truncated"));
259            }
260            n += 1;
261            if n > max_records {
262                return Err(error!(
263                    "capture has more records than the world has tiles ({max_records})"
264                ));
265            }
266            let mut coords = [0u8; 8];
267            r.read_exact(&mut coords)
268                .map_err(|_| error!("capture tile record {}: message truncated", n - 1))?;
269            let x = i32::from_le_bytes([coords[0], coords[1], coords[2], coords[3]]);
270            let z = i32::from_le_bytes([coords[4], coords[5], coords[6], coords[7]]);
271            r.seek_relative(i64::from(size) - 8)?;
272            pos = end;
273            if !(0..tiles_x).contains(&x) || !(0..tiles_z).contains(&z) {
274                outside += 1;
275            } else if wanted
276                .is_some_and(|[x0, z0, x1, z1]| (x0..=x1).contains(&x) && (z0..=z1).contains(&z))
277            {
278                index.insert(
279                    (z, x),
280                    Record {
281                        offset: start,
282                        size,
283                    },
284                );
285                if index.len() > MAX_INDEXED {
286                    return Err(error!(
287                        "too many tiles to index (limit {MAX_INDEXED}); give a range"
288                    ));
289                }
290            }
291        }
292        if outside > 0 {
293            warnings.warn(Warning::note(format!(
294                "capture: {outside} records outside the world grid were ignored"
295            )));
296        }
297        Ok(Self {
298            params,
299            index,
300            file: Mutex::new(r.into_inner()),
301            path: None,
302            indexed: wanted,
303        })
304    }
305
306    /// The part of the world grid that was indexed, `[x0, z0, x1, z1]` inclusive: the range the file was
307    /// opened with, clipped to the grid. `None` when that range was empty.
308    #[must_use]
309    pub fn indexed_range(&self) -> Option<[i32; 4]> {
310        self.indexed
311    }
312
313    /// Whether every tile of `range` (clipped to the grid like the range of a run; `None` is the whole
314    /// grid) was indexed, so that a tile this capture does not return is really missing from the file.
315    #[must_use]
316    pub fn covers(&self, range: Option<[i32; 4]>) -> bool {
317        let (tiles_x, tiles_z) = (self.params.world.tiles_x, self.params.world.tiles_z);
318        match (clip_range(range, tiles_x, tiles_z), self.indexed) {
319            (Some([x0, z0, x1, z1]), Some([ix0, iz0, ix1, iz1])) => {
320                x0 >= ix0 && z0 >= iz0 && x1 <= ix1 && z1 <= iz1
321            }
322            (None, _) => true,
323            (Some(_), None) => false,
324        }
325    }
326
327    /// The path of the file this was opened from; `None` for [`CaptureFile::from_reader`].
328    #[must_use]
329    pub fn path(&self) -> Option<&Path> {
330        self.path.as_deref()
331    }
332
333    /// The world params.
334    #[must_use]
335    pub fn params(&self) -> &WorldParams {
336        &self.params
337    }
338
339    /// The number of tiles indexed.
340    #[must_use]
341    pub fn len(&self) -> usize {
342        self.index.len()
343    }
344
345    /// Whether no tile is indexed.
346    #[must_use]
347    pub fn is_empty(&self) -> bool {
348        self.index.is_empty()
349    }
350
351    /// The bounding range `[x0, z0, x1, z1]` of the indexed tiles, `None` when there is none.
352    #[must_use]
353    pub fn bounds(&self) -> Option<[i32; 4]> {
354        let mut keys = self.index.keys();
355        let &(z, x) = keys.next()?;
356        let mut r = [x, z, x, z];
357        for &(z, x) in keys {
358            r = [r[0].min(x), r[1].min(z), r[2].max(x), r[3].max(z)];
359        }
360        Some(r)
361    }
362
363    /// Reads and parses tile `(x, z)`; `None` when the capture (or the indexed range) lacks it.
364    ///
365    /// # Errors
366    ///
367    /// A read error keeps its kind (the file may be unreadable at the moment); a malformed record is
368    /// [`io::ErrorKind::InvalidData`] with the errors of [`TileInput::parse`].
369    pub fn tile(&self, x: i32, z: i32) -> io::Result<Option<TileInput>> {
370        let Some(rec) = self.index.get(&(z, x)) else {
371            return Ok(None);
372        };
373        let len = usize::try_from(rec.size).map_err(|_| error!("invalid capture block size"))?;
374        let bytes = {
375            let mut file = self.file.lock().unwrap_or_else(PoisonError::into_inner);
376            file.seek(SeekFrom::Start(rec.offset))
377                .and_then(|_| read_chunked(&mut *file, len))
378        }
379        .map_err(|e| io::Error::new(e.kind(), format!("capture tile ({x},{z}): {e}")))?;
380        TileInput::parse(&bytes).map(Some).map_err(|e| {
381            io::Error::new(
382                io::ErrorKind::InvalidData,
383                format!("capture tile ({x},{z}): {e}"),
384            )
385        })
386    }
387}
388
389/// Writes a capture, flushing after every tile so a crashed run keeps its prefix.
390#[derive(Debug)]
391pub struct CaptureWriter<W: Write> {
392    w: W,
393}
394
395fn write_block(w: &mut impl Write, bytes: &[u8]) -> io::Result<()> {
396    let size = u32::try_from(bytes.len())
397        .ok()
398        .filter(|n| *n <= MAX_FRAME)
399        .ok_or_else(|| error!("capture block too large"))?;
400    let mut out = Vec::with_capacity(bytes.len() + 4);
401    out.extend_from_slice(&size.to_le_bytes());
402    out.extend_from_slice(bytes);
403    w.write_all(&out)?;
404    w.flush()
405}
406
407impl<W: Write> CaptureWriter<W> {
408    /// Writes the header and the world params block.
409    ///
410    /// # Errors
411    ///
412    /// Fails when writing fails.
413    pub fn new(mut w: W, params: &WorldParams) -> io::Result<Self> {
414        w.write_all(MAGIC)?;
415        w.write_all(&VERSION.to_le_bytes())?;
416        write_block(&mut w, &params.encode())?;
417        Ok(Self { w })
418    }
419
420    /// Appends one tile and flushes.
421    ///
422    /// # Errors
423    ///
424    /// Fails when writing fails or the tile is larger than 1 GiB.
425    pub fn add(&mut self, tile: &TileInput) -> io::Result<()> {
426        write_block(&mut self.w, &tile.encode())
427    }
428}