rm2k-lib 1.2.0

Reads and writes the RPG Maker 2000/2003 LCF binary formats (LDB, LMU, LMT, LSD).
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
//! Per-field wire codecs.
//!
//! Every LCF field kind (compressed integer, raw byte string, packed primitive array, nested
//! struct, indexed struct list) implements [`LcfField`]. The schema macro needs no type knowledge:
//! it emits `match chunk.id { 0x01 => obj.name = LcfField::read(...) }`, and the codec is chosen
//! at compile time with no runtime dispatch table.
//!
//! **Reading is infallible**: [`LcfField::read`] returns a value, never a `Result`. A malformed
//! field keeps its default and pushes a [`Diagnostic`](crate::diag::Diagnostic); it cannot abort
//! the parse. Generated readers stay free of error propagation, and real files depend on this
//! leniency. A caller wanting rejection passes a [`StrictSink`](crate::diag::StrictSink); the
//! *loader* stops at the next chunk boundary, not the field read.

use crate::{
    cursor::{ChunkIter, Ctx, Cursor},
    diag::DiagKind,
    engine::Engine,
    sink::Sink,
    wire,
};
use alloc::{borrow::Cow, vec::Vec};

/// A borrowed or owned run of bytes from a file.
///
/// **Not a string.** LCF records no encoding, so this crate does not pretend to know one (see the
/// crate docs). The bytes are whatever the authoring machine's codepage produced: commonly
/// Shift-JIS or CP1252, but the format does not say which.
///
/// Borrows from the input until [`into_owned`](DbStr::into_owned), so loading copies no text.
#[derive(Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)]
pub struct DbStr<'a>(Cow<'a, [u8]>);

impl<'a> DbStr<'a> {
    /// Borrow a run of bytes.
    #[must_use]
    #[inline]
    pub const fn from_bytes(bytes: &'a [u8]) -> Self {
        Self(Cow::Borrowed(bytes))
    }

    /// Take ownership of a run of bytes.
    #[must_use]
    #[inline]
    pub const fn from_vec(bytes: Vec<u8>) -> Self {
        Self(Cow::Owned(bytes))
    }

    /// The bytes, exactly as they appeared in the file.
    #[must_use]
    #[inline]
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Length in bytes.
    #[must_use]
    #[inline]
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Whether the field is empty. Empty is the default for every string field, so the writer elides it.
    #[must_use]
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// Detach from the input buffer.
    #[must_use]
    pub fn into_owned(self) -> DbStr<'static> {
        DbStr(Cow::Owned(self.0.into_owned()))
    }

    /// Interpret as UTF-8, if it happens to be valid.
    ///
    /// Returns `None` otherwise, including for most non-English games. Meant for incidentally-ASCII
    /// values like a filename or identifier; it is not an encoding layer.
    #[must_use]
    #[inline]
    pub fn as_utf8(&self) -> Option<&str> {
        core::str::from_utf8(&self.0).ok()
    }
}

impl<'a> From<&'a [u8]> for DbStr<'a> {
    #[inline]
    fn from(bytes: &'a [u8]) -> Self {
        Self::from_bytes(bytes)
    }
}

/// Enumerate a struct's own string fields, by name.
///
/// Translation tools need to ask "what text does this actor hold, and what is each piece called",
/// and doing it by hand means naming all 127 fields of `Terms`.
///
/// One struct's own string fields, no recursion: nesting is already reachable through typed access.
pub trait Strings<'a> {
    /// Call `f` once per string field, with the field's name and value.
    fn visit_strings(&self, f: &mut dyn FnMut(&'static str, &DbStr<'a>));
}

/// A run of booleans stored one byte per element.
///
/// The wire form is one byte per boolean. Only the separate flag bundles are bit-packed.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct BitArray<'a>(Cow<'a, [u8]>);

impl<'a> BitArray<'a> {
    /// Borrow the raw bytes.
    #[must_use]
    #[inline]
    pub const fn from_bytes(bytes: &'a [u8]) -> Self {
        Self(Cow::Borrowed(bytes))
    }

    /// Take ownership of the raw bytes, one per boolean.
    #[must_use]
    #[inline]
    pub const fn from_vec(bytes: Vec<u8>) -> Self {
        Self(Cow::Owned(bytes))
    }

    /// Number of booleans.
    #[must_use]
    #[inline]
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Whether there are no booleans.
    #[must_use]
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// The boolean at `index`, or `None` if out of range.
    #[must_use]
    #[inline]
    pub fn get(&self, index: usize) -> Option<bool> {
        self.0.get(index).map(|&b| b != 0)
    }

    /// Iterate the booleans.
    pub fn iter(&self) -> impl Iterator<Item = bool> + '_ {
        self.0.iter().map(|&b| b != 0)
    }

    /// The underlying bytes.
    #[must_use]
    #[inline]
    pub fn as_bytes(&self) -> &[u8] {
        &self.0
    }

    /// Detach from the input buffer.
    #[must_use]
    pub fn into_owned(self) -> BitArray<'static> {
        BitArray(Cow::Owned(self.0.into_owned()))
    }
}

/// A field that can be read from a chunk payload and written back.
pub trait LcfField<'a>: Sized {
    /// Decode from a chunk payload sliced to exactly this field's bytes.
    ///
    /// `owner` and `id` are only used to locate diagnostics.
    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self;

    /// The value this field holds when its chunk is absent and the schema gives no explicit
    /// default.
    ///
    /// Engine-dependent (nested defaults are, and the writer elides fields equal to their default),
    /// so getting it wrong changes the emitted bytes, not just the observed value.
    fn field_default(engine: Engine) -> Self;

    /// Encoded length in bytes, which the two-pass writer emits as the chunk's length prefix.
    fn lcf_size(&self, engine: Engine) -> u32;

    /// Whether `self` differs from `other` in its written form; the writer elides a field equal to
    /// its default. Plain `!=`, except floats compare by bits: `-0.0 == 0.0`, so `!=` would drop a
    /// stored `-0.0` and break the round trip.
    #[inline]
    fn lcf_differs(&self, other: &Self) -> bool
    where
        Self: PartialEq,
    {
        self != other
    }

    /// Number of elements, for array-like fields.
    ///
    /// Used only by companion `count`/`size` chunks and their elision test. Scalar fields have no
    /// companion, so `0` is never observed for them.
    #[inline]
    fn element_count(&self) -> u32 {
        0
    }

    /// Append the encoded payload.
    ///
    /// # Errors
    ///
    /// Propagates the sink's error. Infallible for `Vec<u8>`.
    fn write<S: Sink>(&self, sink: &mut S, engine: Engine) -> Result<(), S::Error>;
}

/// Report that a payload had bytes the field did not consume.
#[inline]
fn check_consumed(cur: &Cursor<'_>, ctx: &mut Ctx<'_>, owner: &'static str, id: u32) {
    if !cur.is_empty() {
        ctx.report(owner, id, cur.offset(), DiagKind::TrailingBytes);
    }
}

impl<'a> LcfField<'a> for i32 {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        0
    }

    #[inline]
    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        let mut cur = Cursor::new(data);
        let value = cur.varint_lenient(ctx, owner, id);
        check_consumed(&cur, ctx, owner, id);
        value
    }

    #[inline]
    fn lcf_size(&self, _engine: Engine) -> u32 {
        wire::varint_len(*self as u32)
    }

    #[inline]
    fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
        wire::write_varint(sink, *self as u32)
    }
}

impl<'a> LcfField<'a> for bool {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        false
    }

    #[inline]
    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        <i32 as LcfField>::read(data, ctx, owner, id) > 0
    }

    #[inline]
    fn lcf_size(&self, _engine: Engine) -> u32 {
        1
    }

    #[inline]
    fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
        sink.write(&[u8::from(*self)])
    }
}

/// Generate a codec for a fixed-width little-endian primitive.
macro_rules! impl_fixed_field {
    ($ty:ty, $size:literal, $read:ident) => {
        impl<'a> LcfField<'a> for $ty {
            #[inline]
            fn field_default(_engine: Engine) -> Self {
                <$ty>::default()
            }

            #[inline]
            fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
                let mut cur = Cursor::new(data);
                match cur.$read() {
                    Some(value) => {
                        check_consumed(&cur, ctx, owner, id);
                        value
                    }
                    None => {
                        ctx.report(owner, id, cur.offset(), DiagKind::ShortChunk);
                        Self::default()
                    }
                }
            }

            #[inline]
            fn lcf_size(&self, _engine: Engine) -> u32 {
                $size
            }

            #[inline]
            fn lcf_differs(&self, other: &Self) -> bool {
                self.to_le_bytes() != other.to_le_bytes()
            }

            #[inline]
            fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
                sink.write(&self.to_le_bytes())
            }
        }
    };
}

impl_fixed_field!(i16, 2, i16_le);
impl_fixed_field!(u32, 4, u32_le);
impl_fixed_field!(f64, 8, f64_le);

impl<'a> LcfField<'a> for u8 {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        0
    }

    #[inline]
    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        match data.first() {
            Some(&byte) => byte,
            None => {
                ctx.report(owner, id, 0, DiagKind::ShortChunk);
                0
            }
        }
    }

    #[inline]
    fn lcf_size(&self, _engine: Engine) -> u32 {
        1
    }

    #[inline]
    fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
        sink.write(&[*self])
    }
}

impl<'a> LcfField<'a> for i8 {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        0
    }

    #[inline]
    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        <u8 as LcfField>::read(data, ctx, owner, id) as Self
    }

    #[inline]
    fn lcf_size(&self, _engine: Engine) -> u32 {
        1
    }

    #[inline]
    fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
        sink.write(&[*self as u8])
    }
}

impl<'a> LcfField<'a> for DbStr<'a> {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        Self::from_bytes(&[])
    }

    #[inline]
    fn read(data: &'a [u8], _ctx: &mut Ctx<'_>, _owner: &'static str, _id: u32) -> Self {
        // The chunk length *is* the string length; there is no inner prefix. Zero-copy.
        Self::from_bytes(data)
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn lcf_size(&self, _engine: Engine) -> u32 {
        self.0.len() as u32
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn element_count(&self) -> u32 {
        self.0.len() as u32
    }

    #[inline]
    fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
        sink.write(&self.0)
    }
}

impl<'a> LcfField<'a> for BitArray<'a> {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        Self::from_bytes(&[])
    }

    #[inline]
    fn read(data: &'a [u8], _ctx: &mut Ctx<'_>, _owner: &'static str, _id: u32) -> Self {
        Self::from_bytes(data)
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn lcf_size(&self, _engine: Engine) -> u32 {
        self.0.len() as u32
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn element_count(&self) -> u32 {
        self.0.len() as u32
    }

    #[inline]
    fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
        sink.write(&self.0)
    }
}

/// A primitive that appears inside a raw packed array.
///
/// Packed arrays have no element count: count is chunk length divided by element size. A payload
/// that is not a whole multiple is truncated and reported as [`DiagKind::RaggedArray`].
pub trait PackedPrim: Sized + Copy {
    /// Bytes per element on the wire.
    const SIZE: usize;
    /// Decode one element from exactly `SIZE` bytes.
    fn decode(bytes: &[u8]) -> Self;
    /// Encode one element.
    fn encode(self, out: &mut [u8; 8]) -> usize;
}

impl PackedPrim for u8 {
    const SIZE: usize = 1;
    #[inline]
    fn decode(bytes: &[u8]) -> Self {
        bytes[0]
    }
    #[inline]
    fn encode(self, out: &mut [u8; 8]) -> usize {
        out[0] = self;
        1
    }
}

impl PackedPrim for i16 {
    const SIZE: usize = 2;
    #[inline]
    fn decode(bytes: &[u8]) -> Self {
        Self::from_le_bytes([bytes[0], bytes[1]])
    }
    #[inline]
    fn encode(self, out: &mut [u8; 8]) -> usize {
        out[..2].copy_from_slice(&self.to_le_bytes());
        2
    }
}

impl PackedPrim for i32 {
    const SIZE: usize = 4;
    #[inline]
    fn decode(bytes: &[u8]) -> Self {
        Self::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])
    }
    #[inline]
    fn encode(self, out: &mut [u8; 8]) -> usize {
        out[..4].copy_from_slice(&self.to_le_bytes());
        4
    }
}

impl PackedPrim for u32 {
    const SIZE: usize = 4;
    #[inline]
    fn decode(bytes: &[u8]) -> Self {
        Self::from_le_bytes([bytes[0], bytes[1], bytes[2], bytes[3]])
    }
    #[inline]
    fn encode(self, out: &mut [u8; 8]) -> usize {
        out[..4].copy_from_slice(&self.to_le_bytes());
        4
    }
}

/// A raw packed array of a fixed-width primitive.
///
/// A newtype, not a bare `Vec<T>`, so it cannot collide with the indexed struct list codec:
/// `Vec<i16>` and `Vec<Learning>` are both `Vec`s to the type system but different wire formats.
/// The type keeps the schema honest about which one a field is.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct Packed<T>(pub Vec<T>);

impl<T> core::ops::Deref for Packed<T> {
    type Target = Vec<T>;
    #[inline]
    fn deref(&self) -> &Vec<T> {
        &self.0
    }
}

impl<'a, T: PackedPrim> LcfField<'a> for Packed<T> {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        Self(Vec::new())
    }

    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        let count = data.len() / T::SIZE;
        if data.len() % T::SIZE != 0 {
            ctx.report(owner, id, 0, DiagKind::RaggedArray);
        }
        let mut out = Vec::with_capacity(count);
        for i in 0..count {
            out.push(T::decode(&data[i * T::SIZE..]));
        }
        Self(out)
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn lcf_size(&self, _engine: Engine) -> u32 {
        (self.0.len() * T::SIZE) as u32
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn element_count(&self) -> u32 {
        self.0.len() as u32
    }

    fn write<S: Sink>(&self, sink: &mut S, _engine: Engine) -> Result<(), S::Error> {
        let mut buf = [0u8; 8];
        for &value in &self.0 {
            let n = value.encode(&mut buf);
            sink.write(&buf[..n])?;
        }
        Ok(())
    }
}

/// A struct serialised as a chunk stream.
///
/// Implemented by the schema macro for every one of the format's chunked structs.
pub trait LcfStruct<'a>: Sized {
    /// Name used to locate diagnostics, e.g. `"Actor"`.
    const NAME: &'static str;

    /// The value every field holds before any chunk is read.
    ///
    /// Engine-dependent because ~30 fields have different 2000 and 2003 defaults.
    /// Replaces `StructDefault<S>::make(bool)` and `rpg::Actor::Setup(bool)`.
    fn defaults(engine: Engine) -> Self;

    /// Apply one chunk.
    ///
    /// Returns the id of the field that consumed it: the chunk's own id, or for a companion
    /// size/count chunk, its sibling's. `None` means unclaimed; [`read_stream`](LcfStruct::read_stream)
    /// keeps it verbatim as an [`UnknownChunk`] anchored to the last recognised field.
    fn apply_chunk(&mut self, id: u32, data: &'a [u8], ctx: &mut Ctx<'_>) -> Option<u32>;

    /// The chunks no field claimed, kept so they can be written back.
    fn unknown_chunks(&self) -> &UnknownChunks;

    /// The chunks no field claimed, mutably.
    fn unknown_chunks_mut(&mut self) -> &mut UnknownChunks;

    /// Encoded length of the struct's body, excluding any terminating zero.
    ///
    /// Derived from [`write_body`](LcfStruct::write_body) rather than generated separately.
    fn body_size(&self, engine: Engine) -> u32 {
        let mut counter = crate::sink::CountSink::new();
        // `CountSink::Error` is `Infallible`, so this cannot fail.
        let _ = self.write_body(&mut counter, engine);
        counter.len() as u32
    }

    /// Append the struct's body, excluding any terminating zero.
    ///
    /// # Errors
    ///
    /// Propagates the sink's error.
    fn write_body<S: Sink>(&self, sink: &mut S, engine: Engine) -> Result<(), S::Error>;

    /// Read a whole struct from a chunk stream.
    fn read_stream(chunks: &mut ChunkIter<'a>, ctx: &mut Ctx<'_>) -> Self {
        let mut obj = Self::defaults(ctx.engine);
        // See `UnknownChunk::anchor`: 0 terminates a chunk stream, so it is free to mean "no
        // recognised chunk has been seen yet".
        let mut anchor = 0u32;
        while let Some(chunk) = chunks.next(ctx, Self::NAME) {
            match obj.apply_chunk(chunk.id, chunk.data, ctx) {
                Some(field_id) => anchor = field_id,
                None => {
                    // Still a diagnostic - the chunk is preserved, not understood.
                    ctx.report(Self::NAME, chunk.id, chunk.offset, DiagKind::UnknownChunk);
                    obj.unknown_chunks_mut().0.push(UnknownChunk {
                        data: chunk.data.to_vec(),
                        id: chunk.id,
                        anchor,
                    });
                }
            }
            if ctx.should_abort() {
                break;
            }
        }
        obj
    }
}

/// Any chunked struct is also a field: a nested struct's payload is just another chunk stream.
impl<'a, T: LcfStruct<'a>> LcfField<'a> for T {
    #[inline]
    fn field_default(engine: Engine) -> Self {
        T::defaults(engine)
    }

    #[inline]
    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, _owner: &'static str, _id: u32) -> Self {
        let mut chunks = ChunkIter::new(data, 0);
        T::read_stream(&mut chunks, ctx)
    }

    #[inline]
    fn lcf_size(&self, engine: Engine) -> u32 {
        // +1 for the terminating zero id, which nested structs always carry.
        self.body_size(engine) + 1
    }

    #[inline]
    fn write<S: Sink>(&self, sink: &mut S, engine: Engine) -> Result<(), S::Error> {
        self.write_body(sink, engine)?;
        sink.write(&[0])
    }
}

// Tests live in `tests/field.rs`: `LcfField`, `DbStr`, `BitArray` and `Packed` are all `pub`, so
// black-box tests reach everything here.

/// A chunked struct that carries a leading id.
pub trait LcfIndexed<'a>: LcfStruct<'a> {
    /// The element's id, as stored ahead of its chunk stream.
    fn id(&self) -> i32;
    /// Set the element's id.
    fn set_id(&mut self, id: i32);
}

/// A list of indexed structs: `varint(count)`, then per element `varint(id)` and a chunk stream.
///
/// A newtype rather than a bare `Vec<T>` for the same reason as [`Packed`]: `Vec<i16>` and
/// `Vec<Learning>` are indistinguishable to the type system but are completely different wire
/// formats, so the schema states which one it means.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct List<T>(pub Vec<T>);

impl<T> core::ops::Deref for List<T> {
    type Target = Vec<T>;
    #[inline]
    fn deref(&self) -> &Vec<T> {
        &self.0
    }
}

impl<T> core::ops::DerefMut for List<T> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Vec<T> {
        &mut self.0
    }
}

impl<'a, T: LcfIndexed<'a>> List<T> {
    /// Reads a list from a shared cursor, leaving it after the last element. `TreeMap` embeds a
    /// `MapInfo` list straight in the file stream, not in a length-prefixed chunk, so the caller
    /// must keep reading from the same position.
    pub fn read_inline(cur: &mut Cursor<'a>, ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        let count = cur.varint_lenient(ctx, owner, id);

        // The count is attacker-controlled, so it must not reach `with_capacity` unchecked. Each
        // element costs at least two bytes on the wire (an id and a terminator), which bounds how
        // many can possibly be present.
        let max_possible = cur.remaining_len() / 2 + 1;
        let count = (count.max(0) as usize).min(max_possible);
        let mut out = Vec::with_capacity(count);

        for _ in 0..count {
            if cur.is_empty() {
                ctx.report(owner, id, cur.offset(), DiagKind::ShortChunk);
                break;
            }
            let elem_id = cur.varint_lenient(ctx, owner, id);
            let mut chunks = ChunkIter::from_cursor(cur.clone());
            let mut elem = T::read_stream(&mut chunks, ctx);
            elem.set_id(elem_id);
            *cur = chunks.into_cursor();
            out.push(elem);
            if ctx.should_abort() {
                break;
            }
        }

        Self(out)
    }
}

impl<'a, T: LcfIndexed<'a>> LcfField<'a> for List<T> {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        Self(Vec::new())
    }

    #[inline]
    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        let mut cur = Cursor::new(data);
        Self::read_inline(&mut cur, ctx, owner, id)
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn element_count(&self) -> u32 {
        self.0.len() as u32
    }

    #[allow(clippy::cast_possible_truncation)]
    fn lcf_size(&self, engine: Engine) -> u32 {
        let mut total = wire::varint_len(self.0.len() as u32);
        for elem in &self.0 {
            // id + body + terminating zero
            total += wire::varint_len(elem.id() as u32) + elem.body_size(engine) + 1;
        }
        total
    }

    #[allow(clippy::cast_possible_truncation)]
    fn write<S: Sink>(&self, sink: &mut S, engine: Engine) -> Result<(), S::Error> {
        wire::write_varint(sink, self.0.len() as u32)?;
        for elem in &self.0 {
            wire::write_varint(sink, elem.id() as u32)?;
            elem.write_body(sink, engine)?;
            sink.write(&[0])?;
        }
        Ok(())
    }
}

/// A list of structs that carry **no** id: `varint(count)` then bare chunk streams.
///
/// liblcf picks this over [`List`] with a SFINAE probe for an `ID` member (`IDChecker<T>`,
/// `src/reader_struct.h:539`). Exactly one schema type needs it, `SaveEasyRpgText` (an EasyRPG
/// extension). Getting it wrong would shift every element by one compressed integer, so it is a
/// distinct type, not a runtime flag.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct UnindexedList<T>(pub Vec<T>);

impl<T> core::ops::Deref for UnindexedList<T> {
    type Target = Vec<T>;
    #[inline]
    fn deref(&self) -> &Vec<T> {
        &self.0
    }
}

impl<T> core::ops::DerefMut for UnindexedList<T> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Vec<T> {
        &mut self.0
    }
}

impl<'a, T: LcfStruct<'a>> LcfField<'a> for UnindexedList<T> {
    #[inline]
    fn field_default(_engine: Engine) -> Self {
        Self(Vec::new())
    }

    fn read(data: &'a [u8], ctx: &mut Ctx<'_>, owner: &'static str, id: u32) -> Self {
        let mut cur = Cursor::new(data);
        let count = cur.varint_lenient(ctx, owner, id);

        // The count is attacker-controlled; each element costs at least one byte (a terminator),
        // which bounds how many can actually be present.
        let count = (count.max(0) as usize).min(cur.remaining_len() + 1);
        let mut out = Vec::with_capacity(count);

        for _ in 0..count {
            if cur.is_empty() {
                ctx.report(owner, id, cur.offset(), DiagKind::ShortChunk);
                break;
            }
            let mut chunks = ChunkIter::from_cursor(cur);
            out.push(T::read_stream(&mut chunks, ctx));
            cur = chunks.into_cursor();
            if ctx.should_abort() {
                break;
            }
        }

        Self(out)
    }

    #[allow(clippy::cast_possible_truncation)]
    fn lcf_size(&self, engine: Engine) -> u32 {
        let mut total = wire::varint_len(self.0.len() as u32);
        for elem in &self.0 {
            total += elem.body_size(engine) + 1;
        }
        total
    }

    #[allow(clippy::cast_possible_truncation)]
    fn write<S: Sink>(&self, sink: &mut S, engine: Engine) -> Result<(), S::Error> {
        wire::write_varint(sink, self.0.len() as u32)?;
        for elem in &self.0 {
            elem.write_body(sink, engine)?;
            sink.write(&[0])?;
        }
        Ok(())
    }

    #[inline]
    #[allow(clippy::cast_possible_truncation)]
    fn element_count(&self) -> u32 {
        self.0.len() as u32
    }
}

/// A chunk whose id no field of the owning struct claims.
///
/// RPG Maker's forward-compatibility story is "write chunks the reader may not know". Files in the
/// wild carry ids this schema lacks (a later `RPG_RT` build, an EasyRPG extension, a third-party
/// editor). Dropping them would make load/save lossy for the files we understand least, so they
/// are kept verbatim and written back.
///
/// The payload is raw bytes: with no schema entry there is nothing to say whether it is an
/// integer, a string, or a nested chunk stream, since LCF chunks carry no type tag (see the
/// [schema docs](crate::schema)).
///
/// **Owns its bytes**, unlike the other field kinds. Twenty-odd schema structs borrow nothing and
/// carry no lifetime parameter; adding one just for unknown chunks would be a far larger break than
/// a copy on a path that is empty for well-formed files.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
pub struct UnknownChunk {
    /// The payload, exactly as it appeared. Never interpreted.
    pub data: Vec<u8>,
    /// The chunk id, as read.
    pub id: u32,
    /// Id of the last *recognised* field seen before this chunk, or `0` if it came before any.
    ///
    /// Puts the chunk back where it was found. Anchoring beats sorting by id: the schema's
    /// declaration order is liblcf's emission order, which is not ascending in seven structs
    /// (`Enemy`, `SaveSystem`, `SavePicture`, ...), so sorting would move unknown chunks across
    /// known ones.
    ///
    /// `0` means "before everything": a zero id terminates a chunk stream, so it is never a field's id.
    pub anchor: u32,
}

/// The unrecognised chunks of one struct, in the order they were read.
///
/// Empty for a well-formed file this schema fully covers - the common case, where it costs one
/// `Vec` header per struct and no allocation at all.
#[derive(Clone, Debug, Default, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
#[cfg_attr(feature = "serde", serde(transparent))]
pub struct UnknownChunks(pub Vec<UnknownChunk>);

impl UnknownChunks {
    /// An empty set. Allocates nothing.
    #[must_use]
    #[inline]
    pub const fn new() -> Self {
        Self(Vec::new())
    }

    /// Whether the struct had no unrecognised chunks.
    ///
    /// Spelled out rather than left to `Deref` because the schema macro names it as a
    /// `serde(skip_serializing_if)` path, which needs a real inherent method.
    #[must_use]
    #[inline]
    pub fn is_empty(&self) -> bool {
        self.0.is_empty()
    }

    /// How many were kept.
    #[must_use]
    #[inline]
    pub fn len(&self) -> usize {
        self.0.len()
    }

    /// Write back every chunk anchored to `anchor`, header and payload, in read order.
    ///
    /// Called once per field, so the empty-case early-out keeps files without unknown chunks to one
    /// predictable branch per field. The length prefix is recomputed from the payload, so an edited
    /// `data` still emits a consistent chunk.
    ///
    /// # Errors
    ///
    /// Propagates the sink's error.
    #[allow(clippy::cast_possible_truncation)]
    pub fn write_anchored<S: Sink>(&self, sink: &mut S, anchor: u32) -> Result<(), S::Error> {
        if self.0.is_empty() {
            return Ok(());
        }
        for chunk in self.0.iter().filter(|chunk| chunk.anchor == anchor) {
            wire::write_varint(sink, chunk.id)?;
            wire::write_varint(sink, chunk.data.len() as u32)?;
            sink.write(&chunk.data)?;
        }
        Ok(())
    }
}

impl core::ops::Deref for UnknownChunks {
    type Target = Vec<UnknownChunk>;
    #[inline]
    fn deref(&self) -> &Vec<UnknownChunk> {
        &self.0
    }
}

impl core::ops::DerefMut for UnknownChunks {
    #[inline]
    fn deref_mut(&mut self) -> &mut Vec<UnknownChunk> {
        &mut self.0
    }
}