Module matched_combat 

This module contains the implementation of the Matched Combat file format for Total War games.

Matched combat files define synchronized combat animations between units, specifying which animation files to use, what conditions must be met, and how units transition during the animation sequence. These files control cinematic melee combat interactions where units perform matched animations together (e.g., sword duels, executions, grapples).

File Format

Matched combat files (.bin) contain entries that define combat animation sequences. Each entry specifies:

• Animation participants (multiple units involved in the sequence)
• Entity-specific animation files and metadata
• Selection weights for animation variety
• Filters to determine when animations can be used (unit types, equipment, etc.)
• State transitions (alive to dead, alive to alive, etc.)
• Team assignments for participants

Versions

The format has multiple versions with game-specific variations:

• Version 1 (Three Kingdoms): Basic matched combat system
• Version 1 (Warhammer 3): Extended with mount animations
• Version 3: Further expanded format

File Locations

Matched combat files are typically found in:

• animations/matched_combat/*.bin
• animations/database/matched/*.bin
• animations/database/trigger/*.bin

Usage Example

use rpfm_lib::files::{Decodeable, matched_combat::*};

// Decode a matched combat file
let mut data = std::io::Cursor::new(file_data);
let extra_data = Some(DecodeableExtraData {
    game_info: Some(game_info),
    ..Default::default()
});
let matched = MatchedCombat::decode(&mut data, &extra_data)?;

// Access combat entries
for entry in matched.entries() {
    println!("Combat ID: {}", entry.id());
    for participant in entry.participants() {
        println!("Team: {}", participant.team());
    }
}

Structs

Entity

An entity’s animation data for matched combat.

EntityBundle

A bundle of animation entities that can be selected together.

Filter

A filter condition for determining when an animation can be used.

MatchedCombat

Represents a matched combat file decoded in memory.

MatchedEntry

A single matched combat animation entry.

Participant

A participant in a matched combat animation sequence.

State

State transition for a participant during the matched combat sequence.

Enums

StateParticipant

Possible states for a participant in a matched combat animation.

Constants

BASE_PATHS

Matched combat files go under these folders.

EXTENSION

Extension of MatchedCombat files.