Module table 

Table data structures and encoding/decoding for Total War game data.

Overview

This module provides the core abstraction for working with structured table data in Total War games. Tables are the primary format for storing game data like units, buildings, technologies, factions, and thousands of other data types. They function similarly to database tables with typed columns and rows of data.

Table Data Flow

┌──────────────┐
│  DB File     │  Binary format on disk
│  (Header +   │  Contains: version, GUID, entry count
│   Table Data)│
└──────┬───────┘
       │ decode (requires Definition from schema)
       ↓
┌──────────────┐
│ TableInMemory│  In-memory representation
│ (Rows of     │  Vec<Vec<DecodedData>>
│  DecodedData)│
└──────┬───────┘
       │ export/import
       ↓
┌──────────────┐
│ TSV/SQL/etc  │  Human-readable formats
└──────────────┘

Key Components

Table Trait

The Table trait defines the interface for all table-like structures. It provides:

• Access to table metadata (name, definition, patches)
• Row data access (immutable and mutable)
• Column queries and row generation
• Data validation and replacement

DecodedData Enum

The DecodedData enum represents all possible data types in Total War tables:

• Primitives: Boolean, integers (I16/I32/I64), floats (F32/F64)
• Strings: UTF-8 (StringU8) and UTF-16 (StringU16)
• Optional types: OptionalI16/I32/I64, OptionalStringU8/U16
• Special types: ColourRGB (merged R/G/B values), SequenceU16/U32 (binary blobs)

TableInMemory

The concrete implementation of the Table trait for in-memory table manipulation. Supports encoding/decoding to/from binary format, TSV import/export, and SQL operations.

Encoding/Decoding

Tables are encoded in a binary format defined by a Definition from the schema system:

1. Decoding Process:

   • Read table header (version, GUID, entry count) from DB file
   • Use Definition to determine column structure and types
   • Decode each row according to field types
   • Apply postprocessing (bitwise fields, enums, color merging)

2. Encoding Process:

   • Apply preprocessing (split colors, encode enums, combine bitwise fields)
   • Write each field according to its type
   • Update DB file header with entry count

Special Field Types

Bitwise Fields

Integer fields marked as “bitwise” in the definition are split into multiple boolean columns:

Binary: single i32 with flags 0b00001011
Decoded: multiple boolean columns [true, true, false, true]

Enum Fields

Integer fields with enum values defined in the schema show string values:

Binary: i32 value 2
Decoded: StringU8("cavalry") based on enum mapping

Split Color Fields

RGB color components are merged into a single ColourRGB field:

Binary: three i32 fields (red=255, green=128, blue=0)
Decoded: single ColourRGB("#FF8000")

Usage Example

use rpfm_lib::files::table::{Table, DecodedData};
use rpfm_lib::files::table::local::TableInMemory;
use rpfm_lib::schema::Definition;

// Decode a table
let mut table = TableInMemory::decode(&mut reader, &definition, &name, &patches)?;

// Access rows
for row in table.data().iter() {
    if let DecodedData::StringU8(name) = &row[0] {
        println!("Row name: {}", name);
    }
}

// Modify data
let mut new_row = table.new_row();
new_row[0] = DecodedData::StringU8("new_unit".to_string());
table.data_mut().push(new_row);

// Encode back to binary
table.encode(&mut writer)?;

Integration

This module integrates with:

• Schema module: Provides Definition for table structure
• DB module: Container format for table data with headers
• Binary module: Low-level I/O operations
• Assembly Kit: Import/export of official modding tools data

See Also

• local::TableInMemory - Main implementation
• DecodedData - Data type enum
• crate::files::db - DB file container format
• crate::schema::Definition - Table schema definitions

Modules

local

In-memory table implementation with import/export capabilities.

Enums

DecodedData

Runtime representation of table cell data supporting 16 different data types.

Traits

Table

Abstract interface for table-like data structures.

Functions

encode_table

Encodes table data from decoded format back to binary.