Struct Schema 

pub struct Schema { /* private fields */ }

Represents a complete schema file containing table definitions for a Total War game.

A Schema stores the structural definitions for all database tables in a Total War game. Each table can have multiple Definition versions, allowing the schema to support different versions of the same table across game patches.

Structure

• version: The structural version of the schema format itself (currently 5)
• definitions: A map of table names to their version history
• patches: Runtime modifications to field properties

Usage

use rpfm_lib::schema::Schema;
use std::path::Path;

let schema_path = Path::new("schemas/warhammer_3.ron");
let schema = Schema::load(schema_path, None)?;

// Get definitions for a specific table
if let Some(definitions) = schema.definitions_by_table_name("units_tables") {
    println!("Found {} versions of units_tables", definitions.len());
}

Implementations

impl Schema

pub fn version(&self) -> &u16

The structural version of the schema format.

This is incremented when the schema format itself changes in backwards-incompatible ways.

pub fn definitions(&self) -> &HashMap<String, Vec<Definition>>

Map of table names to their version definitions.

Each table can have multiple versions, stored as a Vec of Definition instances. Serialization orders this map alphabetically for consistent output.

pub fn patches(&self) -> &HashMap<String, DefinitionPatch>

Map of table names to their patches.

Patches allow runtime modification of field properties without changing the base schema. See DefinitionPatch for the patch structure.

impl Schema

pub fn version_mut(&mut self) -> &mut u16

The structural version of the schema format.

This is incremented when the schema format itself changes in backwards-incompatible ways.

pub fn definitions_mut(&mut self) -> &mut HashMap<String, Vec<Definition>>

Map of table names to their version definitions.

Each table can have multiple versions, stored as a Vec of Definition instances. Serialization orders this map alphabetically for consistent output.

pub fn patches_mut(&mut self) -> &mut HashMap<String, DefinitionPatch>

Map of table names to their patches.

Patches allow runtime modification of field properties without changing the base schema. See DefinitionPatch for the patch structure.

impl Schema

pub fn set_version(&mut self, val: u16) -> &mut Self

The structural version of the schema format.

This is incremented when the schema format itself changes in backwards-incompatible ways.

pub fn set_definitions( &mut self, val: HashMap<String, Vec<Definition>>, ) -> &mut Self

Map of table names to their version definitions.

Each table can have multiple versions, stored as a Vec of Definition instances. Serialization orders this map alphabetically for consistent output.

pub fn set_patches( &mut self, val: HashMap<String, DefinitionPatch>, ) -> &mut Self

Map of table names to their patches.

Patches allow runtime modification of field properties without changing the base schema. See DefinitionPatch for the patch structure.

impl Schema

Implementation of Schema.

pub fn save_patches( patches: &HashMap<String, DefinitionPatch>, path: &Path, ) -> Result<()>

Saves patches to a local patches file, merging with existing patches.

This function loads existing patches from the file, merges the provided patches with them, and writes the combined patch set back to the file in RON format.

Arguments

• patches - The patches to add or update
• path - Path to the local patches file (must exist)

Returns

Returns Ok if successful, or an error if:

• The file cannot be read or written
• The file contains invalid patch data

Example

use std::collections::HashMap;
use std::path::Path;
use rpfm_lib::schema::{Schema, DefinitionPatch};

let mut patches: HashMap<String, DefinitionPatch> = HashMap::new();
// Add patches...

Schema::save_patches(&patches, Path::new("my_patches.ron"))?;

pub fn remove_patches_for_table(table_name: &str, path: &Path) -> Result<()>

Removes all local patches for a specific table.

This function loads the patches file, removes all patches for the specified table, and writes the updated patch set back to the file.

Arguments

• table_name - Name of the table to remove patches for
• path - Path to the local patches file

Returns

Returns Ok if successful, even if no there were no patches to remove, or an error if file I/O fails.

pub fn remove_patches_for_table_and_field( table_name: &str, field_name: &str, path: &Path, ) -> Result<()>

Removes all local patches for a specific field in a table.

This function loads the patches file, removes all patches for the specified table’s field, and writes the updated patch set back to the file. Other fields in the table are unaffected.

Arguments

• table_name - Name of the table containing the field
• field_name - Name of the field to remove patches for
• path - Path to the local patches file

Returns

Returns Ok if successful, even if no there were no patches to remove, or an error if file I/O fails.

pub fn patch_value( &self, table_name: &str, column_name: &str, key: &str, ) -> Option<&String>

Retrieves a specific patch value for a table’s column.

Arguments

• table_name - Name of the table
• column_name - Name of the column
• key - Patch key (e.g., “is_key”, “default_value”)

Returns

Returns the patch value if found, or None otherwise.

pub fn patches_for_table(&self, table_name: &str) -> Option<&DefinitionPatch>

Retrieves all patches for a specific table.

Arguments

• table_name - Name of the table

Returns

Returns the table’s patches if found, or None otherwise.

pub fn add_patches_to_patch_set( patch_set: &mut HashMap<String, DefinitionPatch>, patches: &HashMap<String, DefinitionPatch>, )

Merges patches into an existing patch set.

This function adds the provided patches to the patch set, merging them with any existing patches. If a patch already exists for a table/column/key combination, it will be extended with the new values.

Arguments

• patch_set - The patch set to merge into (modified in place)
• patches - The patches to add

Note

After adding patches, you must re-retrieve any definitions you’ve already retrieved for the patches to take effect, as patches are applied when retrieving definitions.

pub fn add_definition(&mut self, table_name: &str, definition: &Definition)

Adds or updates a table definition in the schema.

If a definition with the same version already exists for this table, it will be replaced. Otherwise, the definition is added to the table’s version list.

Arguments

• table_name - Name of the table
• definition - The definition to add or update

pub fn remove_definition(&mut self, table_name: &str, version: i32)

Removes a specific table definition version from the schema.

Arguments

• table_name - Name of the table
• version - Version number of the definition to remove

pub fn definitions_by_table_name_cloned( &self, table_name: &str, ) -> Option<Vec<Definition>>

Returns a cloned copy of all definitions for a table.

Arguments

• table_name - Name of the table

Returns

Returns a cloned vector of all definitions for the table, or None if not found.

pub fn definitions_by_table_name( &self, table_name: &str, ) -> Option<&Vec<Definition>>

Returns a reference to all definitions for a table.

Arguments

• table_name - Name of the table

Returns

Returns a reference to the vector of definitions, or None if not found.

pub fn definitions_by_table_name_mut( &mut self, table_name: &str, ) -> Option<&mut Vec<Definition>>

Returns a mutable reference to all definitions for a table.

Arguments

• table_name - Name of the table

Returns

Returns a mutable reference to the vector of definitions, or None if not found.

pub fn definition_newer( &self, table_name: &str, candidates: &[Definition], ) -> Option<&Definition>

Returns the newest compatible definition for a table based on candidate versions.

This function first tries to find a definition matching the highest version number from the candidates (typically from a dependency database). If that fails, it falls back to the first (newest) definition in the schema.

Arguments

• table_name - Name of the table
• candidates - List of candidate definitions (typically from dependencies)

Returns

Returns the best matching definition, or None if the table is not found.

pub fn definition_by_name_and_version( &self, table_name: &str, table_version: i32, ) -> Option<&Definition>

Returns a reference to a specific table definition by name and version.

Arguments

• table_name - Name of the table
• table_version - Version number of the definition

Returns

Returns the definition if found, or None otherwise.

pub fn definition_by_name_and_version_mut( &mut self, table_name: &str, table_version: i32, ) -> Option<&mut Definition>

Returns a mutable reference to a specific table definition by name and version.

Arguments

• table_name - Name of the table
• table_version - Version number of the definition

Returns

Returns the definition if found, or None otherwise.

pub fn load(path: &Path, local_patches: Option<&Path>) -> Result<Self>

Loads a Schema from a RON file, optionally merging local patches.

This function loads a schema from a .ron file and applies any patches from both the schema itself and an optional local patches file. Patches from the local file are merged with schema patches and applied to all definitions.

Arguments

• path - Path to the schema .ron file
• local_patches - Optional path to a local patches file

Returns

Returns the loaded schema with all patches applied, or an error if loading fails.

pub fn load_json(path: &Path) -> Result<Self>

Loads a Schema from a JSON file.

Similar to load(), but reads from a JSON file instead of RON. Applies all patches from the schema to the definitions.

Arguments

• path - Path to the schema .json file

Returns

Returns the loaded schema with patches applied, or an error if loading fails.

pub fn save(&mut self, path: &Path) -> Result<()>

Saves the schema to a RON file.

This function saves the schema to a .ron file, automatically:

• Creating parent directories if needed
• Sorting definitions by version (newest first)
• Cleaning up invalid references
• Moving certain patches from definitions to schema patches

Arguments

• path - Path where the schema file should be saved

Returns

Returns Ok if saved successfully, or an error if file I/O fails.

pub fn save_json(&mut self, path: &Path) -> Result<()>

Saves the schema to a JSON file.

This function saves the schema to a .json file at the specified path, automatically:

• Creating parent directories if needed
• Changing the extension to .json
• Sorting definitions by version (newest first)
• Pretty-printing the JSON output

Arguments

• path - Path where the schema file should be saved (extension will be changed to .json)

Returns

Returns Ok if saved successfully, or an error if file I/O or serialization fails.

pub fn export_to_json(schema_folder_path: &Path) -> Result<()>

Exports all schema files in a folder to JSON format.

This function loads all schema files (.ron) for supported games from the specified folder and saves them as .json files in the same location. This is primarily used for compatibility with external tools that prefer JSON.

Arguments

• schema_folder_path - Path to the folder containing schema .ron files

Returns

Returns Ok if all schemas are successfully exported, or an error if any operation fails.

Note

This function processes schemas in parallel for better performance.

pub fn update( schema_path: &Path, schema_patches_path: &Path, game_name: &str, ) -> Result<()>

Updates a schema from a legacy format to the current format.

This function handles migration of schema files from older structural versions (e.g., v4) to the current structural version (v5). It automatically detects the schema version and applies the necessary transformations.

Arguments

• schema_path - Path to the schema file to update
• schema_patches_path - Path to the schema patches file
• game_name - Name of the game this schema is for

Returns

Returns Ok if the update succeeds, or an error if the update process fails.

pub fn referencing_columns_for_table( &self, table_name: &str, definition: &Definition, ) -> HashMap<String, HashMap<String, Vec<String>>>

Returns all columns that reference fields in the specified table.

This function searches through all table definitions in the schema to find fields that have foreign key references pointing to the provided table’s fields.

Arguments

• table_name - Name of the table to find references to
• definition - Definition of the table (used to get the field list)

Returns

Returns a map where:

• Keys are local field names from the provided definition
• Values are maps of table_name -> Vec<field_name> containing all referencing fields

Example

For a factions_tables table, this might return:

{
  "key": {
    "units_tables": ["faction_key"],
    "characters_tables": ["faction_key", "home_faction_key"]
  }
}

pub fn tables_and_columns_referencing_our_own( &self, table_name: &str, column_name: &str, fields: &[Field], localised_fields: &[Field], ) -> (BTreeMap<String, Vec<String>>, bool)

Returns all tables and columns that reference the specified column, and whether LOC files may be affected.

This function performs a recursive search to find all fields that reference the specified column, including indirect references (fields that reference fields that reference the target column). It also checks if changing the column would affect localisation keys.

Arguments

• table_name - Name of the table containing the column (with or without _tables suffix)
• column_name - Name of the column to find references to
• fields - The table’s field list
• localised_fields - The table’s localised field list

Returns

Returns a tuple of:

• A map of table_name -> Vec<field_name> containing all referencing fields (recursively)
• A boolean indicating if LOC files may need updates (true if the column is a key field and the table has localised fields)

Note

Recursion is supported for table references, but not for LOC field detection.

pub fn load_patches_from_str( patch: &str, ) -> Result<HashMap<String, DefinitionPatch>>

Loads patches from a RON-formatted string.

Arguments

• patch - RON-formatted string containing patches

Returns

Returns the parsed patches, or an error if the string is not valid RON.

pub fn load_definitions_from_str( definition: &str, ) -> Result<HashMap<String, Definition>>

Loads definitions from a RON-formatted string.

Arguments

• definition - RON-formatted string containing table definitions

Returns

Returns the parsed definitions, or an error if the string is not valid RON.

pub fn export_patches_to_str( patches: &HashMap<String, DefinitionPatch>, ) -> Result<String>

Exports patches to a RON-formatted string.

Arguments

• patches - The patches to export

Returns

Returns the RON-formatted string, or an error if serialization fails.

pub fn export_definitions_to_str( definitions: &HashMap<String, Definition>, ) -> Result<String>

Exports definitions to a RON-formatted string.

Arguments

• definitions - The definitions to export

Returns

Returns the RON-formatted string, or an error if serialization fails.

Trait Implementations

impl Clone for Schema

fn clone(&self) -> Schema

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Schema

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Schema

Default implementation of Schema.

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Schema

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Schema

fn eq(&self, other: &Schema) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Schema

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Schema

impl StructuralPartialEq for Schema