rakata_formats/gff/

reader.rs

//! GFF V3.2 binary reader.

use std::io::Read;

use rakata_core::{decode_text_strict, text_encoding_for_language, ResRef, StrRef};

use super::{
    binary, to_usize, FieldType, Gff, GffBinaryError, GffField, GffLocalizedString,
    GffLocalizedSubstring, GffStruct, GffValue, DEFAULT_TEXT_ENCODING, FIELD_ENTRY_SIZE,
    GFF_HEADER_SIZE, GFF_VERSION_V32, LABEL_SIZE, STRUCT_ENTRY_SIZE,
};

/// Reads a binary GFF file from a reader.
///
/// The stream is consumed from its current position.
///
/// # Errors
///
/// [`GffBinaryError::Io`] when the stream will not read to end, and whatever
/// [`read_gff_from_bytes`] reports for the bytes it collected.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(reader))
)]
pub fn read_gff<R: Read>(reader: &mut R) -> Result<Gff, GffBinaryError> {
    let mut bytes = Vec::new();
    reader.read_to_end(&mut bytes)?;
    crate::trace_debug!(bytes_len = bytes.len(), "read gff bytes from reader");
    read_gff_from_bytes(&bytes)
}

/// Reads a binary GFF file from bytes.
///
/// # Errors
///
/// [`GffBinaryError::InvalidVersion`] for a version other than `V3.2`. There
/// is no magic check: a GFF's first four bytes are its *file type*, which
/// varies per format, so a file that is not a GFF fails on its version or its
/// layout rather than on a signature.
///
/// [`GffBinaryError::InvalidHeader`] when the header is truncated or a table
/// offset overflows, and [`GffBinaryError::InvalidData`] for a tree that does
/// not hang together: a struct or field index past its table, a field-indices
/// run outside the index array, or a nesting depth past twice the struct
/// count. That bound is the cycle guard, and it is deliberately loose, since a
/// legitimate file can need more depth than it has structs.
///
/// [`GffBinaryError::InvalidFieldType`] for a type code this reader will not
/// guess at, [`GffBinaryError::TextDecoding`] for a string that is not valid
/// text in its declared encoding, and
/// [`GffBinaryError::UnsupportedLanguageEncoding`] for a localized string
/// whose language id maps to no codepage.
#[cfg_attr(
    feature = "tracing",
    tracing::instrument(level = "debug", skip(bytes), fields(bytes_len = bytes.len()))
)]
pub fn read_gff_from_bytes(bytes: &[u8]) -> Result<Gff, GffBinaryError> {
    let header = parse_header(bytes)?;
    let labels = read_labels(bytes, &header)?;
    let parser = GffParser {
        bytes,
        header,
        labels,
    };
    let root = parser.read_struct(0, 0)?;
    crate::trace_debug!(
        file_type = ?parser.header.file_type,
        struct_count = parser.header.struct_count,
        field_count = parser.header.field_count,
        label_count = parser.header.label_count,
        root_field_count = root.fields.len(),
        "parsed gff from bytes"
    );
    Ok(Gff {
        file_type: parser.header.file_type,
        root,
    })
}

#[derive(Debug, Clone, Copy)]
struct GffHeader {
    file_type: [u8; 4],
    struct_offset: usize,
    struct_count: usize,
    field_offset: usize,
    field_count: usize,
    label_offset: usize,
    label_count: usize,
    field_data_offset: usize,
    field_data_count: usize,
    field_indices_offset: usize,
    field_indices_count: usize,
    list_indices_offset: usize,
    list_indices_count: usize,
}

struct GffParser<'a> {
    bytes: &'a [u8],
    header: GffHeader,
    labels: Vec<super::GffLabel>,
}

impl<'a> GffParser<'a> {
    fn read_struct(&self, struct_index: usize, depth: usize) -> Result<GffStruct, GffBinaryError> {
        // Depth alternates struct -> field -> nested struct, growing by
        // one per hop. The longest legitimate acyclic path visits each
        // struct once and reads its fields, so max depth is
        // 2 * struct_count - 1. Use 2 * struct_count as the trip
        // bound (saturating for paranoia against malformed headers).
        let depth_limit = self.header.struct_count.saturating_mul(2);
        if depth > depth_limit {
            return Err(GffBinaryError::InvalidData(
                "detected nested struct cycle while reading".into(),
            ));
        }
        if struct_index >= self.header.struct_count {
            return Err(GffBinaryError::InvalidData(format!(
                "struct index {struct_index} out of range"
            )));
        }

        let base = self
            .header
            .struct_offset
            .checked_add(
                struct_index
                    .checked_mul(STRUCT_ENTRY_SIZE)
                    .ok_or_else(|| GffBinaryError::InvalidHeader("struct index overflow".into()))?,
            )
            .ok_or_else(|| GffBinaryError::InvalidHeader("struct base overflow".into()))?;
        let struct_id = read_i32(self.bytes, base)?;
        let data_or_offset = binary::read_u32(self.bytes, base + 4)?;
        let field_count = usize::try_from(binary::read_u32(self.bytes, base + 8)?)
            .map_err(|_| GffBinaryError::InvalidData("field count does not fit usize".into()))?;

        let mut fields = Vec::with_capacity(field_count);
        match field_count {
            0 => {}
            1 => {
                let field_index = usize::try_from(data_or_offset).map_err(|_| {
                    GffBinaryError::InvalidData("single field index does not fit usize".into())
                })?;
                fields.push(self.read_field(field_index, depth + 1)?);
            }
            _ => {
                let indices_rel_offset = usize::try_from(data_or_offset).map_err(|_| {
                    GffBinaryError::InvalidData("field indices offset does not fit usize".into())
                })?;
                let indices_size = field_count.checked_mul(4).ok_or_else(|| {
                    GffBinaryError::InvalidData("field indices size overflow".into())
                })?;
                if indices_rel_offset
                    .checked_add(indices_size)
                    .is_none_or(|end| end > self.header.field_indices_count)
                {
                    return Err(GffBinaryError::InvalidData(format!(
                        "field indices block out of range for struct {struct_index}"
                    )));
                }
                let indices_base = self
                    .header
                    .field_indices_offset
                    .checked_add(indices_rel_offset)
                    .ok_or_else(|| {
                        GffBinaryError::InvalidData("field indices absolute offset overflow".into())
                    })?;
                for i in 0..field_count {
                    let field_index =
                        usize::try_from(binary::read_u32(self.bytes, indices_base + i * 4)?)
                            .map_err(|_| {
                                GffBinaryError::InvalidData(
                                    "field index from field-indices table does not fit usize"
                                        .into(),
                                )
                            })?;
                    fields.push(self.read_field(field_index, depth + 1)?);
                }
            }
        }

        Ok(GffStruct { struct_id, fields })
    }

    fn read_field(&self, field_index: usize, depth: usize) -> Result<GffField, GffBinaryError> {
        if field_index >= self.header.field_count {
            return Err(GffBinaryError::InvalidData(format!(
                "field index {field_index} out of range"
            )));
        }
        let base = self
            .header
            .field_offset
            .checked_add(
                field_index
                    .checked_mul(FIELD_ENTRY_SIZE)
                    .ok_or_else(|| GffBinaryError::InvalidHeader("field index overflow".into()))?,
            )
            .ok_or_else(|| GffBinaryError::InvalidHeader("field base overflow".into()))?;

        let field_type_raw = binary::read_u32(self.bytes, base)?;
        let field_type = FieldType::try_from(field_type_raw)
            .map_err(|_| GffBinaryError::InvalidFieldType(field_type_raw))?;
        let label_index = usize::try_from(binary::read_u32(self.bytes, base + 4)?)
            .map_err(|_| GffBinaryError::InvalidData("label index does not fit usize".into()))?;
        let data_or_offset = binary::read_u32(self.bytes, base + 8)?;
        let label = *self.labels.get(label_index).ok_or_else(|| {
            GffBinaryError::InvalidData(format!("label index {label_index} out of range"))
        })?;

        let value = match field_type {
            FieldType::UInt8 => {
                GffValue::UInt8(u8::try_from(data_or_offset & 0xFF).expect("masked to 8 bits"))
            }
            FieldType::Int8 => {
                GffValue::Int8(i8::from_le_bytes([
                    u8::try_from(data_or_offset & 0xFF).expect("masked to 8 bits")
                ]))
            }
            FieldType::UInt16 => {
                GffValue::UInt16(u16::try_from(data_or_offset & 0xFFFF).expect("masked to 16 bits"))
            }
            FieldType::Int16 => GffValue::Int16(i16::from_le_bytes(
                u16::try_from(data_or_offset & 0xFFFF)
                    .expect("masked to 16 bits")
                    .to_le_bytes(),
            )),
            FieldType::UInt32 => GffValue::UInt32(data_or_offset),
            FieldType::Int32 => GffValue::Int32(i32::from_le_bytes(data_or_offset.to_le_bytes())),
            FieldType::Single => GffValue::Single(f32::from_bits(data_or_offset)),
            FieldType::UInt64 => GffValue::UInt64(read_u64_at_field_data(self, data_or_offset)?),
            FieldType::Int64 => GffValue::Int64(i64::from_le_bytes(
                read_u64_at_field_data(self, data_or_offset)?.to_le_bytes(),
            )),
            FieldType::Double => GffValue::Double(f64::from_bits(read_u64_at_field_data(
                self,
                data_or_offset,
            )?)),
            FieldType::String => GffValue::String(read_sized_string(
                self,
                data_or_offset,
                format!("field[{field_index}] string"),
            )?),
            FieldType::ResRef => {
                let raw = read_sized_string_u8(
                    self,
                    data_or_offset,
                    format!("field[{field_index}] resref"),
                )?;
                let resref = ResRef::new(&raw).map_err(|err| {
                    GffBinaryError::InvalidData(format!(
                        "field[{field_index}] resref `{raw}`: {err}"
                    ))
                })?;
                GffValue::ResRef(resref)
            }
            FieldType::LocalizedString => {
                GffValue::LocalizedString(read_localized_string(self, data_or_offset, field_index)?)
            }
            FieldType::Binary => GffValue::Binary(read_binary_blob(self, data_or_offset)?),
            FieldType::Struct => {
                let struct_index = usize::try_from(data_or_offset).map_err(|_| {
                    GffBinaryError::InvalidData("nested struct index does not fit usize".into())
                })?;
                GffValue::Struct(Box::new(self.read_struct(struct_index, depth + 1)?))
            }
            FieldType::List => GffValue::List(read_struct_list(self, data_or_offset, depth + 1)?),
            FieldType::Vector4 => GffValue::Vector4(read_vector4(self, data_or_offset)?),
            FieldType::Vector3 => GffValue::Vector3(read_vector3(self, data_or_offset)?),
        };

        Ok(GffField { label, value })
    }
}

fn parse_header(bytes: &[u8]) -> Result<GffHeader, GffBinaryError> {
    if bytes.len() < GFF_HEADER_SIZE {
        return Err(GffBinaryError::InvalidHeader(
            "file smaller than GFF header".into(),
        ));
    }
    let file_type = binary::read_fourcc(bytes, 0)?;
    let version = binary::read_fourcc(bytes, 4)?;
    binary::expect_fourcc(version, GFF_VERSION_V32).map_err(GffBinaryError::InvalidVersion)?;

    let struct_offset = to_usize(binary::read_u32(bytes, 8)?, "struct_offset")?;
    let struct_count = to_usize(binary::read_u32(bytes, 12)?, "struct_count")?;
    let field_offset = to_usize(binary::read_u32(bytes, 16)?, "field_offset")?;
    let field_count = to_usize(binary::read_u32(bytes, 20)?, "field_count")?;
    let label_offset = to_usize(binary::read_u32(bytes, 24)?, "label_offset")?;
    let label_count = to_usize(binary::read_u32(bytes, 28)?, "label_count")?;
    let field_data_offset = to_usize(binary::read_u32(bytes, 32)?, "field_data_offset")?;
    let field_data_count = to_usize(binary::read_u32(bytes, 36)?, "field_data_count")?;
    let field_indices_offset = to_usize(binary::read_u32(bytes, 40)?, "field_indices_offset")?;
    let field_indices_count = to_usize(binary::read_u32(bytes, 44)?, "field_indices_count")?;
    let list_indices_offset = to_usize(binary::read_u32(bytes, 48)?, "list_indices_offset")?;
    let list_indices_count = to_usize(binary::read_u32(bytes, 52)?, "list_indices_count")?;

    check_table_bounds(
        bytes.len(),
        struct_offset,
        struct_count
            .checked_mul(STRUCT_ENTRY_SIZE)
            .ok_or(GffBinaryError::InvalidHeader(
                "struct table size overflow".into(),
            ))?,
        "struct table",
    )?;
    check_table_bounds(
        bytes.len(),
        field_offset,
        field_count
            .checked_mul(FIELD_ENTRY_SIZE)
            .ok_or(GffBinaryError::InvalidHeader(
                "field table size overflow".into(),
            ))?,
        "field table",
    )?;
    check_table_bounds(
        bytes.len(),
        label_offset,
        label_count
            .checked_mul(LABEL_SIZE)
            .ok_or(GffBinaryError::InvalidHeader(
                "label table size overflow".into(),
            ))?,
        "label table",
    )?;
    check_table_bounds(
        bytes.len(),
        field_data_offset,
        field_data_count,
        "field data",
    )?;
    check_table_bounds(
        bytes.len(),
        field_indices_offset,
        field_indices_count,
        "field indices",
    )?;
    check_table_bounds(
        bytes.len(),
        list_indices_offset,
        list_indices_count,
        "list indices",
    )?;

    if struct_count == 0 {
        return Err(GffBinaryError::InvalidHeader(
            "struct table is empty (missing root struct)".into(),
        ));
    }

    Ok(GffHeader {
        file_type,
        struct_offset,
        struct_count,
        field_offset,
        field_count,
        label_offset,
        label_count,
        field_data_offset,
        field_data_count,
        field_indices_offset,
        field_indices_count,
        list_indices_offset,
        list_indices_count,
    })
}

fn read_labels(bytes: &[u8], header: &GffHeader) -> Result<Vec<super::GffLabel>, GffBinaryError> {
    let mut labels = Vec::with_capacity(header.label_count);
    for label_index in 0..header.label_count {
        let offset = header
            .label_offset
            .checked_add(
                label_index
                    .checked_mul(LABEL_SIZE)
                    .ok_or_else(|| GffBinaryError::InvalidHeader("label offset overflow".into()))?,
            )
            .ok_or_else(|| GffBinaryError::InvalidHeader("label base overflow".into()))?;
        let raw = bytes
            .get(offset..offset + LABEL_SIZE)
            .ok_or_else(|| GffBinaryError::InvalidHeader("label slice out of range".into()))?;
        let end = raw.iter().position(|byte| *byte == 0).unwrap_or(LABEL_SIZE);
        let label = decode_text_strict(&raw[..end], DEFAULT_TEXT_ENCODING).map_err(|source| {
            GffBinaryError::TextDecoding {
                context: format!("label[{label_index}]"),
                source,
            }
        })?;
        let gff_label = super::GffLabel::new(&label).map_err(|err| {
            GffBinaryError::InvalidData(format!("label[{label_index}] `{label}` is invalid: {err}"))
        })?;
        labels.push(gff_label);
    }
    Ok(labels)
}

fn read_u64_at_field_data(parser: &GffParser<'_>, offset: u32) -> Result<u64, GffBinaryError> {
    let offset = to_usize(offset, "field_data_offset")?;
    let absolute = parser
        .header
        .field_data_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("field data absolute offset overflow".into()))?;
    let end_rel = offset
        .checked_add(8)
        .ok_or_else(|| GffBinaryError::InvalidData("field data u64 end overflow".into()))?;
    if end_rel > parser.header.field_data_count {
        return Err(GffBinaryError::InvalidData(
            "field data u64 read out of range".into(),
        ));
    }
    Ok(binary::read_u64(parser.bytes, absolute)?)
}

fn read_sized_string(
    parser: &GffParser<'_>,
    offset: u32,
    context: String,
) -> Result<String, GffBinaryError> {
    let offset = to_usize(offset, "field_data_offset")?;
    let base = parser
        .header
        .field_data_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("string base overflow".into()))?;
    let len = to_usize(binary::read_u32(parser.bytes, base)?, "string_length")?;
    let data_rel_end = offset
        .checked_add(4)
        .and_then(|v| v.checked_add(len))
        .ok_or_else(|| GffBinaryError::InvalidData("string end overflow".into()))?;
    if data_rel_end > parser.header.field_data_count {
        return Err(GffBinaryError::InvalidData(
            "string payload exceeds field data bounds".into(),
        ));
    }
    let data_start = base + 4;
    let raw = parser
        .bytes
        .get(data_start..data_start + len)
        .ok_or_else(|| GffBinaryError::InvalidData("string bytes out of range".into()))?;
    decode_text_strict(raw, DEFAULT_TEXT_ENCODING)
        .map_err(|source| GffBinaryError::TextDecoding { context, source })
}

fn read_sized_string_u8(
    parser: &GffParser<'_>,
    offset: u32,
    context: String,
) -> Result<String, GffBinaryError> {
    let offset = to_usize(offset, "field_data_offset")?;
    let base = parser
        .header
        .field_data_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("resref base overflow".into()))?;
    let len =
        usize::from(*parser.bytes.get(base).ok_or_else(|| {
            GffBinaryError::InvalidData("resref length byte out of range".into())
        })?);
    let data_rel_end = offset
        .checked_add(1)
        .and_then(|v| v.checked_add(len))
        .ok_or_else(|| GffBinaryError::InvalidData("resref end overflow".into()))?;
    if data_rel_end > parser.header.field_data_count {
        return Err(GffBinaryError::InvalidData(
            "resref payload exceeds field data bounds".into(),
        ));
    }
    let data_start = base + 1;
    let raw = parser
        .bytes
        .get(data_start..data_start + len)
        .ok_or_else(|| GffBinaryError::InvalidData("resref bytes out of range".into()))?;
    decode_text_strict(raw, DEFAULT_TEXT_ENCODING)
        .map_err(|source| GffBinaryError::TextDecoding { context, source })
}

fn read_binary_blob(parser: &GffParser<'_>, offset: u32) -> Result<Vec<u8>, GffBinaryError> {
    let offset = to_usize(offset, "field_data_offset")?;
    let base = parser
        .header
        .field_data_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("binary base overflow".into()))?;
    let len = to_usize(binary::read_u32(parser.bytes, base)?, "binary_length")?;
    let data_rel_end = offset
        .checked_add(4)
        .and_then(|v| v.checked_add(len))
        .ok_or_else(|| GffBinaryError::InvalidData("binary end overflow".into()))?;
    if data_rel_end > parser.header.field_data_count {
        return Err(GffBinaryError::InvalidData(
            "binary payload exceeds field data bounds".into(),
        ));
    }
    let data_start = base + 4;
    let raw = parser
        .bytes
        .get(data_start..data_start + len)
        .ok_or_else(|| GffBinaryError::InvalidData("binary bytes out of range".into()))?;
    Ok(raw.to_vec())
}

fn read_vector4(parser: &GffParser<'_>, offset: u32) -> Result<[f32; 4], GffBinaryError> {
    let offset = to_usize(offset, "field_data_offset")?;
    let base = parser
        .header
        .field_data_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("vector4 base overflow".into()))?;
    let end_rel = offset
        .checked_add(16)
        .ok_or_else(|| GffBinaryError::InvalidData("vector4 end overflow".into()))?;
    if end_rel > parser.header.field_data_count {
        return Err(GffBinaryError::InvalidData(
            "vector4 exceeds field data bounds".into(),
        ));
    }
    Ok([
        binary::read_f32(parser.bytes, base)?,
        binary::read_f32(parser.bytes, base + 4)?,
        binary::read_f32(parser.bytes, base + 8)?,
        binary::read_f32(parser.bytes, base + 12)?,
    ])
}

fn read_vector3(parser: &GffParser<'_>, offset: u32) -> Result<[f32; 3], GffBinaryError> {
    let offset = to_usize(offset, "field_data_offset")?;
    let base = parser
        .header
        .field_data_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("vector3 base overflow".into()))?;
    let end_rel = offset
        .checked_add(12)
        .ok_or_else(|| GffBinaryError::InvalidData("vector3 end overflow".into()))?;
    if end_rel > parser.header.field_data_count {
        return Err(GffBinaryError::InvalidData(
            "vector3 exceeds field data bounds".into(),
        ));
    }
    Ok([
        binary::read_f32(parser.bytes, base)?,
        binary::read_f32(parser.bytes, base + 4)?,
        binary::read_f32(parser.bytes, base + 8)?,
    ])
}

fn read_struct_list(
    parser: &GffParser<'_>,
    offset: u32,
    depth: usize,
) -> Result<Vec<GffStruct>, GffBinaryError> {
    let offset = to_usize(offset, "list_indices_offset")?;
    let count_base = parser
        .header
        .list_indices_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("list base overflow".into()))?;
    if offset
        .checked_add(4)
        .is_none_or(|end| end > parser.header.list_indices_count)
    {
        return Err(GffBinaryError::InvalidData(
            "list count read out of range".into(),
        ));
    }
    let count = to_usize(binary::read_u32(parser.bytes, count_base)?, "list_count")?;
    let list_entries_size = count
        .checked_mul(4)
        .ok_or_else(|| GffBinaryError::InvalidData("list entries size overflow".into()))?;
    if offset
        .checked_add(4)
        .and_then(|v| v.checked_add(list_entries_size))
        .is_none_or(|end| end > parser.header.list_indices_count)
    {
        return Err(GffBinaryError::InvalidData(
            "list entries out of range".into(),
        ));
    }
    let mut out = Vec::with_capacity(count);
    let entries_base = count_base + 4;
    for index in 0..count {
        let struct_index = to_usize(
            binary::read_u32(parser.bytes, entries_base + index * 4)?,
            "list_struct_index",
        )?;
        out.push(parser.read_struct(struct_index, depth + 1)?);
    }
    Ok(out)
}

fn read_localized_string(
    parser: &GffParser<'_>,
    offset: u32,
    field_index: usize,
) -> Result<GffLocalizedString, GffBinaryError> {
    let offset = to_usize(offset, "field_data_offset")?;
    let base = parser
        .header
        .field_data_offset
        .checked_add(offset)
        .ok_or_else(|| GffBinaryError::InvalidData("locstring base overflow".into()))?;
    let total_size = to_usize(
        binary::read_u32(parser.bytes, base)?,
        "locstring_total_size",
    )?;
    let payload_rel_start = offset
        .checked_add(4)
        .ok_or_else(|| GffBinaryError::InvalidData("locstring payload start overflow".into()))?;
    let payload_rel_end = payload_rel_start
        .checked_add(total_size)
        .ok_or_else(|| GffBinaryError::InvalidData("locstring payload end overflow".into()))?;
    if payload_rel_end > parser.header.field_data_count {
        return Err(GffBinaryError::InvalidData(format!(
            "locstring payload out of range for field[{field_index}]"
        )));
    }

    let payload_start = base + 4;
    let string_ref = StrRef::from_raw(read_i32(parser.bytes, payload_start)?);
    let substring_count = to_usize(
        binary::read_u32(parser.bytes, payload_start + 4)?,
        "substring_count",
    )?;
    let mut cursor = payload_start + 8;
    let payload_end = payload_start + total_size;
    let mut substrings = Vec::with_capacity(substring_count);

    for substring_index in 0..substring_count {
        if cursor.checked_add(8).is_none_or(|end| end > payload_end) {
            return Err(GffBinaryError::InvalidData(format!(
                "locstring header truncated at substring {substring_index}"
            )));
        }
        let string_id = binary::read_u32(parser.bytes, cursor)?;
        let length = to_usize(
            binary::read_u32(parser.bytes, cursor + 4)?,
            "substring_length",
        )?;
        cursor += 8;
        if cursor
            .checked_add(length)
            .is_none_or(|end| end > payload_end)
        {
            return Err(GffBinaryError::InvalidData(format!(
                "locstring substring bytes out of range at index {substring_index}"
            )));
        }
        let bytes = parser.bytes.get(cursor..cursor + length).ok_or_else(|| {
            GffBinaryError::InvalidData("locstring substring slice invalid".into())
        })?;
        let language_id = string_id / 2;
        let encoding = text_encoding_for_language(language_id)
            // Optional enhancement track: language IDs 70..=72 remain
            // unsupported by default because they are not required for
            // vanilla K1/K2 parity.
            .map_err(|err| GffBinaryError::UnsupportedLanguageEncoding(err.language_id.raw()))?;
        let text =
            decode_text_strict(bytes, encoding).map_err(|source| GffBinaryError::TextDecoding {
                context: format!("field[{field_index}] locstring[{substring_index}]"),
                source,
            })?;
        substrings.push(GffLocalizedSubstring { string_id, text });
        cursor += length;
    }

    if cursor != payload_end {
        return Err(GffBinaryError::InvalidData(format!(
            "locstring payload has {} trailing bytes",
            payload_end - cursor
        )));
    }

    Ok(GffLocalizedString {
        string_ref,
        substrings,
    })
}

fn check_table_bounds(
    total_len: usize,
    offset: usize,
    size: usize,
    table_name: &str,
) -> Result<(), GffBinaryError> {
    binary::check_range_in_bounds(total_len, offset, size, table_name)?;
    Ok(())
}

fn read_i32(bytes: &[u8], offset: usize) -> Result<i32, GffBinaryError> {
    let bits = binary::read_u32(bytes, offset)?;
    Ok(i32::from_le_bytes(bits.to_le_bytes()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::gff::write_gff_to_vec;
    use crate::gff_label;

    const TEST_GFF: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/test.gff"
    ));
    const TEST_UTC: &[u8] = include_bytes!(concat!(
        env!("CARGO_MANIFEST_DIR"),
        "/../../fixtures/test.utc"
    ));

    #[test]
    fn roundtrip_gff_binary_with_all_core_field_variants() {
        let mut root = GffStruct::new(-1);
        root.push_field(gff_label!("uint8"), GffValue::UInt8(255));
        root.push_field(gff_label!("int8"), GffValue::Int8(-127));
        root.push_field(gff_label!("uint16"), GffValue::UInt16(65535));
        root.push_field(gff_label!("int16"), GffValue::Int16(-32768));
        root.push_field(gff_label!("uint32"), GffValue::UInt32(u32::MAX));
        root.push_field(gff_label!("int32"), GffValue::Int32(i32::MIN));
        root.push_field(gff_label!("uint64"), GffValue::UInt64(4_294_967_296));
        root.push_field(gff_label!("int64"), GffValue::Int64(2_147_483_647));
        root.push_field(gff_label!("single"), GffValue::Single(12.34567));
        root.push_field(gff_label!("double"), GffValue::Double(12.345678901234));
        root.push_field(
            gff_label!("string"),
            GffValue::String("abcdefghij123456789".into()),
        );
        root.push_field(gff_label!("resref"), GffValue::resref_lit("resref01"));
        root.push_field(
            gff_label!("locstring"),
            GffValue::LocalizedString(GffLocalizedString {
                string_ref: StrRef::invalid(),
                substrings: vec![
                    GffLocalizedSubstring {
                        string_id: 0,
                        text: "male_eng".into(),
                    },
                    GffLocalizedSubstring {
                        string_id: 5,
                        text: "fem_german".into(),
                    },
                ],
            }),
        );
        root.push_field(
            gff_label!("binary"),
            GffValue::Binary(b"binarydata".to_vec()),
        );
        root.push_field(
            gff_label!("orientation"),
            GffValue::Vector4([1.0, 2.0, 3.0, 4.0]),
        );
        root.push_field(
            gff_label!("position"),
            GffValue::Vector3([11.0, 22.0, 33.0]),
        );

        let mut child = GffStruct::new(0);
        child.push_field(gff_label!("child_uint8"), GffValue::UInt8(4));
        root.push_field(
            gff_label!("child_struct"),
            GffValue::Struct(Box::new(child)),
        );
        root.push_field(
            gff_label!("list"),
            GffValue::List(vec![GffStruct::new(1), GffStruct::new(2)]),
        );

        let original = Gff::generic(root);
        let bytes = write_gff_to_vec(&original).expect("write should succeed");
        let parsed = read_gff_from_bytes(&bytes).expect("read should succeed");
        assert_eq!(parsed, original);
    }

    #[test]
    fn parses_gff_fixture() {
        let gff = read_gff_from_bytes(TEST_GFF).expect("fixture should parse");
        assert_eq!(gff.file_type, *b"GFF ");

        assert_eq!(find_field(&gff.root, "uint8"), &GffValue::UInt8(255));
        assert_eq!(find_field(&gff.root, "int8"), &GffValue::Int8(-127));
        assert_eq!(find_field(&gff.root, "uint16"), &GffValue::UInt16(65535));
        assert_eq!(find_field(&gff.root, "int16"), &GffValue::Int16(-32768));
        assert_eq!(find_field(&gff.root, "uint32"), &GffValue::UInt32(u32::MAX));
        assert_eq!(find_field(&gff.root, "int32"), &GffValue::Int32(i32::MIN));
        assert_eq!(
            find_field(&gff.root, "uint64"),
            &GffValue::UInt64(4_294_967_296)
        );
        assert_eq!(
            find_field(&gff.root, "string"),
            &GffValue::String("abcdefghij123456789".into())
        );
        assert_eq!(
            find_field(&gff.root, "resref"),
            &GffValue::resref_lit("resref01")
        );
        match find_field(&gff.root, "locstring") {
            GffValue::LocalizedString(loc) => {
                assert_eq!(loc.string_ref, StrRef::invalid());
                assert_eq!(loc.substrings.len(), 2);
                assert_eq!(loc.substrings[0].text, "male_eng");
                assert_eq!(loc.substrings[1].text, "fem_german");
            }
            other => panic!("expected localized string, got {other:?}"),
        }
    }

    #[test]
    fn read_write_roundtrip_preserves_fixture_semantics() {
        let parsed = read_gff_from_bytes(TEST_GFF).expect("read should succeed");
        let bytes = write_gff_to_vec(&parsed).expect("write should succeed");
        let reparsed = read_gff_from_bytes(&bytes).expect("re-read should succeed");
        assert_eq!(reparsed, parsed);
    }

    #[test]
    fn writer_is_deterministic_for_parsed_fixture() {
        let parsed = read_gff_from_bytes(TEST_GFF).expect("fixture should parse");
        let first = write_gff_to_vec(&parsed).expect("first write should succeed");
        let second = write_gff_to_vec(&parsed).expect("second write should succeed");
        assert_eq!(first, second, "canonical GFF writer output drifted");
    }

    #[test]
    fn roundtrip_preserves_list_order_and_struct_ids() {
        let mut first = GffStruct::new(500);
        first.push_field(gff_label!("marker"), GffValue::UInt16(11));

        let mut second = GffStruct::new(2);
        second.push_field(gff_label!("marker"), GffValue::UInt16(22));

        let mut third = GffStruct::new(9_999);
        third.push_field(gff_label!("marker"), GffValue::UInt16(33));

        let mut root = GffStruct::new(-1);
        root.push_field(
            gff_label!("ordered"),
            GffValue::List(vec![first, second, third]),
        );

        let gff = Gff::generic(root);
        let bytes = write_gff_to_vec(&gff).expect("write should succeed");
        let reparsed = read_gff_from_bytes(&bytes).expect("read should succeed");

        let list = find_list(&reparsed.root, "ordered");
        assert_eq!(list_struct_ids(list), vec![500, 2, 9_999]);
        assert_eq!(list_u16_field(list, "marker"), vec![11, 22, 33]);
    }

    #[test]
    fn utc_fixture_roundtrip_preserves_list_indices_and_values() {
        let parsed = read_gff_from_bytes(TEST_UTC).expect("fixture should parse");
        let bytes = write_gff_to_vec(&parsed).expect("write should succeed");
        let reparsed = read_gff_from_bytes(&bytes).expect("re-read should succeed");

        for label in ["FeatList", "Equip_ItemList", "ItemList", "ClassList"] {
            assert_eq!(
                list_struct_ids(find_list(&parsed.root, label)),
                list_struct_ids(find_list(&reparsed.root, label)),
                "list struct_id order changed for {label}"
            );
        }

        assert_eq!(
            list_u16_field(find_list(&parsed.root, "FeatList"), "Feat"),
            list_u16_field(find_list(&reparsed.root, "FeatList"), "Feat")
        );
        assert_eq!(
            list_resref_field(find_list(&parsed.root, "Equip_ItemList"), "EquippedRes"),
            list_resref_field(find_list(&reparsed.root, "Equip_ItemList"), "EquippedRes")
        );
        assert_eq!(
            list_resref_field(find_list(&parsed.root, "ItemList"), "InventoryRes"),
            list_resref_field(find_list(&reparsed.root, "ItemList"), "InventoryRes")
        );
    }

    #[test]
    fn rejects_invalid_version() {
        let mut bytes = vec![0_u8; GFF_HEADER_SIZE];
        bytes[0..4].copy_from_slice(b"GFF ");
        bytes[4..8].copy_from_slice(b"V9.9");
        let err = read_gff_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, GffBinaryError::InvalidVersion(_)));
    }

    #[test]
    fn rejects_truncated_header() {
        let bytes = vec![0_u8; GFF_HEADER_SIZE - 1];
        let err = read_gff_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, GffBinaryError::InvalidHeader(_)));
    }

    #[test]
    fn rejects_unknown_field_type() {
        let mut bytes = TEST_GFF.to_vec();
        let field_offset = usize::try_from(u32::from_le_bytes(
            bytes[16..20].try_into().expect("field offset bytes"),
        ))
        .expect("offset fits in usize");
        bytes[field_offset..field_offset + 4].copy_from_slice(&99_u32.to_le_bytes());

        let err = read_gff_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, GffBinaryError::InvalidFieldType(99)));
    }

    #[test]
    fn surfaces_field_type_eighteen_rather_than_guessing() {
        // Code 18 is defined by the format but no file attests whether it
        // holds its value immediately or points into the field data, so
        // either branch would read a plausible number out of a region
        // nothing licenses.
        let mut bytes = TEST_GFF.to_vec();
        let field_offset = usize::try_from(u32::from_le_bytes(
            bytes[16..20].try_into().expect("field offset bytes"),
        ))
        .expect("offset fits in usize");
        bytes[field_offset..field_offset + 4].copy_from_slice(&18_u32.to_le_bytes());

        let err = read_gff_from_bytes(&bytes).expect_err("must fail");
        assert!(matches!(err, GffBinaryError::InvalidFieldType(18)));
    }

    #[test]
    fn accepts_two_struct_gff_with_nested_list_entry() {
        // Regression for a false-positive cycle-detection trip. A GFF
        // with only two structs total (root plus one list entry)
        // needs depth 3 to read the list entry's fields, so a depth
        // bound of `struct_count` rejects it with a bogus "detected
        // nested struct cycle". About a quarter of vanilla K1 .uti
        // blueprints hit this shape.
        let mut entry = GffStruct::new(0);
        entry.push_field(gff_label!("PropertyName"), GffValue::UInt16(11));
        entry.push_field(gff_label!("Subtype"), GffValue::UInt16(5));

        let mut root = GffStruct::new(-1);
        root.push_field(gff_label!("PropertiesList"), GffValue::List(vec![entry]));

        let gff = Gff::generic(root);
        let bytes = write_gff_to_vec(&gff).expect("write should succeed");
        let parsed = read_gff_from_bytes(&bytes).expect("two-struct GFF should parse");

        let GffValue::List(list) = find_field(&parsed.root, "PropertiesList") else {
            panic!("PropertiesList should be a list");
        };
        assert_eq!(list.len(), 1);
        assert_eq!(list[0].field("PropertyName"), Some(&GffValue::UInt16(11)));
    }

    #[test]
    fn writer_rejects_unsupported_locstring_language_ids() {
        let mut root = GffStruct::new(-1);
        root.push_field(
            gff_label!("locstring"),
            GffValue::LocalizedString(GffLocalizedString {
                string_ref: StrRef::invalid(),
                substrings: vec![GffLocalizedSubstring {
                    string_id: 140,
                    text: "test".into(),
                }],
            }),
        );
        let gff = Gff::generic(root);

        let err = write_gff_to_vec(&gff).expect_err("must fail");
        assert!(matches!(
            err,
            GffBinaryError::UnsupportedLanguageEncoding(70)
        ));
    }

    fn find_field<'a>(structure: &'a GffStruct, label: &str) -> &'a GffValue {
        structure
            .field(label)
            .unwrap_or_else(|| panic!("missing field {label}"))
    }

    fn find_list<'a>(structure: &'a GffStruct, label: &str) -> &'a [GffStruct] {
        match structure.field(label) {
            Some(GffValue::List(values)) => values.as_slice(),
            Some(other) => panic!("field {label} is not a list: {other:?}"),
            None => panic!("missing list field {label}"),
        }
    }

    fn list_struct_ids(list: &[GffStruct]) -> Vec<i32> {
        list.iter().map(|entry| entry.struct_id).collect::<Vec<_>>()
    }

    fn list_u16_field(list: &[GffStruct], label: &str) -> Vec<u16> {
        list.iter()
            .map(|entry| match entry.field(label) {
                Some(GffValue::UInt16(value)) => *value,
                Some(other) => panic!("field {label} is not UInt16: {other:?}"),
                None => panic!("missing field {label}"),
            })
            .collect::<Vec<_>>()
    }

    fn list_resref_field(list: &[GffStruct], label: &str) -> Vec<String> {
        list.iter()
            .map(|entry| match entry.field(label) {
                Some(GffValue::ResRef(value)) => value.to_string(),
                Some(other) => panic!("field {label} is not ResRef: {other:?}"),
                None => panic!("missing field {label}"),
            })
            .collect::<Vec<_>>()
    }
}