rpfm_extensions/startpos/world/writer/

characters.rs

//---------------------------------------------------------------------------//
// Copyright (c) 2017-2026 Ismael Gutiérrez González. All rights reserved.
//
// This file is part of the Rusted PackFile Manager (RPFM) project,
// which can be found here: https://github.com/Frodo45127/rpfm.
//
// This file is licensed under the MIT license, which can be found here:
// https://github.com/Frodo45127/rpfm/blob/master/LICENSE.
//---------------------------------------------------------------------------//

//! Writer of the characters of a faction (`FACTION/CHARACTER_ARRAY`).
//!
//! The game draws some values from its RNG (art sets, birth seasons, colonels' ages and names): this writer picks
//! valid ones deterministically.
//!
//! `CHARACTER_DETAILS:CAMPAIGN_EFFECT_BUNDLES+2` is written 0. The game sets it to a random 1 to 3 from its RNG, when it's
//! still 0, in a character's post-load initialisation (Thrones' `empire.retail.dll`, FUN_107d00d0, next to the
//! political party it may pick): most of its startpos characters have 0 (369 of 387 in Thrones, 578 of 599 in
//! Attila's main campaign), so it's left for the game to draw. It's also the leader's number in Thrones' header (`^+5`).

use std::collections::HashMap;
use std::f32::consts::PI;
use std::ops::RangeInclusive;

use rpfm_lib::error::Result;
use rpfm_lib::files::esf::{Coordinates2DNode, NodeType, RecordNode};

use super::forces::{ForcePlan, PlannedCharacter};
use super::government::PostPlan;
use super::sight::{write_line_of_sight, SightPlan};
use super::{child, WorldInputs, WorldPlan};
use crate::startpos::layout::{child_path, StartposLayout};
use crate::startpos::coords::HexCell;
use crate::startpos::tables::{Row, StartposTables};
use crate::startpos::vision::Vision;
use crate::startpos::world::agents::{agent_abilities, agent_attributes, experience_rank, skill_set, starting_skills, ABILITIES, ATTRIBUTES};
use crate::startpos::world::bodyguards::{bodyguard, Bodyguard};
use crate::startpos::world::characters::{birth_year, loyalty, loyalty_range, placement, political_party, Placement};
use crate::startpos::world::government::{faction_leader, political_parties, PoliticalParty};
use crate::startpos::world::{CampaignIndex, CharacterEntry, FactionEntry, NAME_COLUMNS};

#[path = "family.rs"] pub(crate) mod family;

#[cfg(test)] #[path = "characters_test.rs"] mod characters_test;

/// Path of the characters of a faction.
const CHARACTER_ARRAY_PATH: &str = "CAMPAIGN_STARTPOS/CAMPAIGN_ENV/CAMPAIGN_MODEL/WORLD/FACTION_ARRAY/FACTION/CHARACTER_ARRAY";

/// Path of a character.
const CHARACTER_PATH: &str = "CAMPAIGN_STARTPOS/CAMPAIGN_ENV/CAMPAIGN_MODEL/WORLD/FACTION_ARRAY/FACTION/CHARACTER_ARRAY/CHARACTER";

/// Path of a character's details.
const DETAILS_PATH: &str = "CAMPAIGN_STARTPOS/CAMPAIGN_ENV/CAMPAIGN_MODEL/WORLD/FACTION_ARRAY/FACTION/CHARACTER_ARRAY/CHARACTER/CHARACTER_DETAILS";


/// Agent type of the generated garrison commanders.
pub(crate) const COLONEL_AGENT: &str = "colonel";

/// Agent type of the generals.
pub(crate) const GENERAL_AGENT: &str = "general";

/// Age of the generated colonels (the game draws it from its RNG).
const COLONEL_AGE: u32 = 30;

/// Localisation key prefix of the character names.
pub(crate) const NAME_KEY_PREFIX: &str = "names_name_";

/// Suffix the startpos adds to the art set of a character (`CHARACTER_DETAILS` #34).
const ART_SET_SUFFIX: &str = "0";

/// Skills Thrones' layout has room for in a character's skill list (the most its startpos has).
const MAX_LISTED_SKILLS: usize = 2;

/// Campaign variable of the rounds a character holds an office before losing it hurts his loyalty. Taking a post sets
/// `LINE_OF_SIGHT+18` to the turn plus it (Thrones' `empire.retail.dll`, FUN_1079bbf0): its value for post holders
/// at the start (Attila 4, Thrones 1).
const OFFICE_ROUNDS_VARIABLE: &str = "rounds_to_hold_office_before_loss_hits_loyalty";

//---------------------------------------------------------------------------//
//                              Types
//---------------------------------------------------------------------------//

/// Writes the characters of the factions.
pub struct CharacterWriter<'a, 'b> {

    /// Tables, startpos rows and layouts.
    inputs: &'b WorldInputs<'a>,

    /// Characters and forces of the world.
    forces: &'b ForcePlan<'a>,

    /// Government posts of the factions.
    posts: &'b PostPlan,

    /// Vision of the world.
    sight: &'b SightPlan,

    /// `start_pos_characters` rows, by id.
    rows: HashMap<String, Row<'a>>,

    /// Traits of each character (trait key and points of its level), by `start_pos_characters` id.
    traits: HashMap<String, Vec<(String, i64)>>,

    /// Rounds a character holds an office before losing it hurts his loyalty (see [`OFFICE_ROUNDS_VARIABLE`]).
    office_rounds: u32,

    /// Range the table loyalty is clamped to (see [`loyalty_range`]).
    loyalty_range: RangeInclusive<i64>,

    /// Skills of each character (`start_pos_character_skills`: skill key and level), by `start_pos_characters` id,
    /// sorted by key: the game keeps them in an ordered map.
    skills: HashMap<String, Vec<(String, u32)>>,

    /// Move points and line of sight of each agent type.
    agents: HashMap<String, (u32, f32)>,

    /// Art sets of the campaign.
    art_sets: Vec<ArtSet>,

    /// Default bodyguard of each faction's generals, by faction key.
    bodyguards: HashMap<String, Option<Bodyguard>>,

    /// Political parties of each faction, by faction key.
    parties: HashMap<String, Vec<PoliticalParty>>,

    /// Family member id of each planned character, by position in the plan.
    family_ids: Vec<u32>,

    /// Family member id of each table character, living or dead, by `start_pos_characters` id.
    entry_family_ids: HashMap<String, u32>,

    /// The campaign's start year.
    start_year: u32,
}

/// An art set a character can use (`campaign_character_art_sets`).
#[derive(Debug, Clone)]
struct ArtSet {
    id: String,
    agent: String,
    is_male: bool,
    faction: String,
    subculture: String,
    culture: String,
    is_custom: bool,
}

/// Who a `CHARACTER_DETAILS` record describes: a character of the world, or a dead one of the family tree.
struct DetailsSubject<'r> {

    /// Path of the record.
    path: &'r str,

    /// The character's faction.
    faction: &'r FactionEntry,

    /// The faction the character was created in.
    origin: &'r FactionEntry,

    /// The character's table entry, `None` for colonels.
    entry: Option<&'r CharacterEntry>,

    /// Runtime id of the character, 0 for the dead.
    character_id: u32,

    /// Family member id of the character.
    family_id: u32,

    /// Death year and death type code, for the dead.
    death: Option<(u32, i32)>,

    /// Bodyguard of a general without a force.
    bodyguard: Option<Bodyguard>,
}

/// What the writer needs to know about a character, from its table row or as a generated colonel.
struct CharacterInfo<'r> {
    agent: String,
    is_male: bool,
    birth_year: u32,
    row: Option<&'r Row<'r>>,
}

//---------------------------------------------------------------------------//
//                              Implementations
//---------------------------------------------------------------------------//

impl<'a, 'b> CharacterWriter<'a, 'b> {

    /// Prepares the writer of the characters.
    ///
    /// # Arguments
    ///
    /// * `inputs` - Tables, startpos rows and layouts.
    /// * `plan` - Order of the factions and regions.
    /// * `forces` - Characters and forces of the world.
    /// * `posts` - Government posts of the factions.
    /// * `sight` - Vision of the world.
    ///
    /// # Errors
    ///
    /// Returns an error if a table or column is missing.
    pub fn new(inputs: &'b WorldInputs<'a>, plan: &WorldPlan<'a>, forces: &'b ForcePlan<'a>, posts: &'b PostPlan, sight: &'b SightPlan) -> Result<Self> {
        let tables = inputs.tables;
        let mut rows = HashMap::new();
        for row in tables.table("start_pos_characters")?.rows() {
            rows.insert(row.str("ID")?.into_owned(), row);
        }

        let mut levels = HashMap::new();
        for row in tables.table("character_trait_levels")?.rows() {
            levels.insert(row.str("key")?.into_owned(), (row.str("trait")?.into_owned(), row.int("threshold_points")?));
        }
        let mut traits = HashMap::<String, Vec<(String, i64)>>::new();
        for row in tables.table("start_pos_character_traits")?.rows() {
            if let Some(level) = levels.get(row.str("trait_level")?.as_ref()) {
                traits.entry(row.str("character_id")?.into_owned()).or_default().push(level.clone());
            }
        }

        let skills = character_skills(tables)?;
        let mut office_rounds = 0;
        for row in tables.table("campaign_variables")?.rows() {
            if row.str("variable_key")? == OFFICE_ROUNDS_VARIABLE {
                office_rounds = row.number("value")?.max(0.0) as u32;
            }
        }

        let mut agents = HashMap::new();
        for row in tables.table("agents")?.rows() {
            agents.insert(row.str("key")?.into_owned(), (u32::try_from(row.int("move_points")?).unwrap_or_default(), row.number("line_of_sight")? as f32));
        }

        let mut groups = vec![];
        for row in tables.table("campaign_character_art_sets_group_junctions")?.rows() {
            if row.str("campaign")? == *inputs.index.campaign() {
                groups.push(row.str("group")?.into_owned());
            }
        }
        let mut art_sets = vec![];
        for row in tables.table("campaign_character_art_sets")?.rows() {
            if groups.contains(&row.str("group")?.into_owned()) {
                art_sets.push(ArtSet {
                    id: row.str("art_set_id")?.into_owned(),
                    agent: row.str("agent_type")?.into_owned(),
                    is_male: row.bool("is_male")?,
                    faction: row.str("faction")?.into_owned(),
                    subculture: row.str("subculture")?.into_owned(),
                    culture: row.str("culture")?.into_owned(),
                    is_custom: row.bool("is_custom")?,
                });
            }
        }

        let mut bodyguards = HashMap::new();
        let mut parties = HashMap::new();
        for faction in plan.factions() {
            bodyguards.insert(faction.key().to_owned(), bodyguard(tables, faction, false)?);
            parties.insert(faction.key().to_owned(), political_parties(tables, faction.key())?);
        }

        let (family_ids, entry_family_ids) = family_ids(inputs.index, plan, forces);
        Ok(Self {
            family_ids,
            entry_family_ids,
            start_year: super::armies::start_year(inputs)?,
            inputs,
            forces,
            posts,
            sight,
            rows,
            traits,
            skills,
            office_rounds,
            loyalty_range: loyalty_range(tables)?,
            agents,
            art_sets,
            bodyguards,
            parties,
        })
    }

    /// Writes the characters of a faction.
    ///
    /// # Errors
    ///
    /// Returns an error if a table, column or layout is missing.
    pub fn write_character_array(&self, faction: &FactionEntry) -> Result<RecordNode> {
        let mut array = self.inputs.layout.builder(CHARACTER_ARRAY_PATH)?;
        for position in self.forces.character_positions(faction.key()) {
            let character = &self.forces.characters()[position];
            array.push_group()?.set_record("CHARACTER", Some(self.write_character(position, character)?))?;
        }
        array.build()
    }

    /// Writes a character: its position, ids, details and the post it holds.
    fn write_character(&self, position: usize, character: &PlannedCharacter) -> Result<RecordNode> {
        let layout = self.inputs.layout;
        let info = self.info(character)?;
        let (move_points, line_of_sight) = self.agents.get(&info.agent).copied().unwrap_or_default();
        let (world, cell) = self.position(character)?;
        let force = character.force().map(|force| &self.forces.forces()[force]);
        let post = character.entry().and_then(|entry| self.posts.post_of(entry.id()));

        let mut coordinates = Coordinates2DNode::default();
        coordinates.set_x(world.0);
        coordinates.set_y(world.1);
        let mut locomotable = child(layout, CHARACTER_PATH, "LOCOMOTABLE")?;
        locomotable.group()?
            .set("^+1", NodeType::Coord2d(coordinates))?
            .set_u32("^+2", u32::from(cell.x()))?
            .set_u32("^+3", u32::from(cell.y()))?
            .set_f32("^+4", PI)?
            .set_u32("^+6", move_points)?
            .set_u32("^+7", move_points)?;

        let override_unit = character.entry().map(|entry| entry.override_general_unit().as_str()).unwrap_or_default();
        let mut record = layout.builder(CHARACTER_PATH)?;
        record.group()?
            .set_record("LOCOMOTABLE", Some(locomotable.build()?))?
            .set_u32("LOCOMOTABLE+1", character.id())?
            .set_record("CHARACTER_DETAILS", Some(self.write_details(&self.subject(position, character, &info), &info)?))?
            .set_str("CHARACTER_DETAILS+1", &info.agent)?
            .set_u32("CHARACTER_DETAILS+2", force.map(|force| force.id()).unwrap_or_default())?
            .set_u32("CHARACTER_DETAILS+3", force.and_then(|force| force.commander_unit_id()).unwrap_or_default())?
            .set_u32("CHARACTER_DETAILS+6", post.unwrap_or_default())?
            .set_f32("LINE_OF_SIGHT+4", line_of_sight)?
            .set_str("LINE_OF_SIGHT+16", override_unit)?
            .set_u32("LINE_OF_SIGHT+18", if post.is_some() { self.office_rounds } else { 0 })?
            .set_bool("LINE_OF_SIGHT+19", post.is_some())?
            .set_record("LINE_OF_SIGHT", Some(write_line_of_sight(layout, CHARACTER_PATH, self.sight.grid(), self.vision(character)?.as_ref())?))?;
        record.build()
    }

    /// Returns what the details of a character of the world are written from.
    fn subject<'r>(&'r self, position: usize, character: &'r PlannedCharacter, info: &CharacterInfo) -> DetailsSubject<'r> {
        let faction = character.faction();
        let bodyguard = self.bodyguards.get(faction.key()).cloned().flatten().filter(|_| info.agent != COLONEL_AGENT && character.force().is_none());
        DetailsSubject {
            path: DETAILS_PATH,
            faction,
            origin: character.origin(),
            entry: character.entry(),
            character_id: character.id(),
            family_id: self.family_ids[position],
            death: None,
            bodyguard,
        }
    }

    /// Writes the details of a character: names, birth (and death), traits, abilities, skills, art set and bodyguard.
    fn write_details(&self, subject: &DetailsSubject, info: &CharacterInfo) -> Result<RecordNode> {
        let layout = self.inputs.layout;
        let (path, faction) = (subject.path, subject.faction);
        let row = info.row;

        let mut birth = child(layout, path, "DATE")?;
        birth.group()?.set_u32("^+1", info.birth_year)?;

        // Family tree members never list their traits, though Thrones' tables give some.
        let trait_path = format!("{path}/TRAITS/TRAIT");
        let mut traits = child(layout, &format!("{path}/TRAITS"), "TRAIT")?;
        let listed = layout.record(&trait_path).is_some_and(|record| record.has_slot("^+1"));
        let character_traits = subject.entry.filter(|_| listed).and_then(|entry| self.traits.get(entry.id())).map(Vec::as_slice).unwrap_or_default();
        for (key, points) in character_traits {
            traits.push_group()?
                .set_str("^+1", key)?
                .set_i32("^+2", i32::try_from(*points).unwrap_or_default())?;
        }
        let mut traits_record = child(layout, path, "TRAITS")?;
        traits_record.group()?.set_record("TRAIT", Some(traits.build()?))?;

        let mut abilities = child(layout, path, "AGENT_ABILITIES")?;
        for (ability, enabled) in ABILITIES.iter().zip(agent_abilities(self.inputs.tables, &info.agent)?) {
            abilities.push_group()?.set_str("^+1", ability)?.set_bool("^+2", enabled)?;
        }
        let mut attributes = child(layout, path, "AGENT_ATTRIBUTES")?;
        for (attribute, value) in ATTRIBUTES.iter().zip(agent_attributes(self.inputs.tables, &info.agent)?) {
            attributes.push_group()?.set_str("^+1", attribute)?.set_i32("^+2", i32::try_from(value).unwrap_or_default())?;
        }

        let set_key = skill_set(self.inputs.tables, self.inputs.index, &info.agent, faction)?.unwrap_or_default();
        let mut skills_block = child(layout, &format!("{path}/CAMPAIGN_SKILLS"), "CAMPAIGN_SKILLS_BLOCK")?;
        for skill in starting_skills(self.inputs.tables, self.inputs.index, &set_key, faction)? {
            skills_block.push_group()?
                .set_str("^+1", &skill.skill)?
                .set_u32("^+2", skill.tier)?
                .set_f32("^+3", skill.indent)?
                .set_u32("^+4", skill.points)?;
        }
        let experience = row.map(|row| row.int("xp")).transpose()?.unwrap_or_default();
        let (rank, skill_points) = experience_rank(self.inputs.tables, self.inputs.index, &info.agent, experience)?;
        let mut skills = child(layout, path, "CAMPAIGN_SKILLS")?;
        skills.group()?
            .set_str("^+2", &set_key)?
            .set_u32("^+5", rank)?
            .set_u32("^+6", skill_points)?
            .set_u32("^+7", u32::try_from(experience).unwrap_or_default())?
            .set_bool("^+4", info.is_male)?
            .set_record("CAMPAIGN_SKILLS_BLOCK", Some(skills_block.build()?))?;

        let seed = if subject.character_id != 0 { subject.character_id } else { subject.family_id };
        let art_set = self.art_set(faction, info, seed);
        let mut art_set_info = child(layout, path, "CHARACTER_DETAILS_ART_SET_INFO")?;
        art_set_info.group()?
            .set_str("^+1", faction.key())?
            .set_str("^+2", faction.culture())?
            .set_str("^+3", faction.subculture())?
            .set_str("^+4", art_set_agent(&info.agent))?
            .set_str("^+5", art_set)?;

        let mut record = layout.builder(path)?;
        let group = record.group()?;
        if let Some((year, code)) = subject.death {
            let mut death = child(layout, path, "DATE@2")?;
            death.group()?.set_u32("^+1", year)?;
            group.set_record("DATE@2", Some(death.build()?))?.set_i32("DATE@2+1", code)?;
        }
        group.set_record("TRAITS", Some(traits_record.build()?))?
            .set_record("CHARACTER_NAME", Some(self.write_name(path, subject.entry)?))?
            .set_record("DATE", Some(birth.build()?))?
            .set_str("DATE@2+2", faction.key())?
            .set_u32("DATE@2+3", subject.character_id)?
            .set_record("AGENT_ABILITIES", Some(abilities.build()?))?
            .set_record("AGENT_ATTRIBUTES", Some(attributes.build()?))?
            .set_bool("AGENT_ATTRIBUTES+3", info.is_male)?
            .set_str("AGENT_ATTRIBUTES+6", &info.agent)?
            .set_record("CAMPAIGN_SKILLS", Some(skills.build()?))?
            .set_record("CHARACTER_DETAILS_ART_SET_INFO", Some(art_set_info.build()?))?
            .set_record("GENERAL_BODYGUARD_DETAILS", Some(self.write_bodyguard(path, subject.bodyguard.as_ref())?))?
            .set_u32("GENERAL_BODYGUARD_DETAILS+1", subject.family_id)?
            .set_str("GENERAL_BODYGUARD_DETAILS+6", &format!("{art_set}{ART_SET_SUFFIX}"))?
            .set_str("GENERAL_BODYGUARD_DETAILS+8", subject.origin.key())?;

        // Thrones lists the living characters' skills (followers, backgrounds) as a count and key-level pairs; the
        // dead of the family tree list none.
        if let (Some(entry), None) = (subject.entry, subject.death) {
            let skills = self.skills.get(entry.id().as_str()).map(Vec::as_slice).unwrap_or_default();
            group.set_u32("GENERAL_BODYGUARD_DETAILS+11", u32::try_from(skills.len()).unwrap_or_default())?;
            for slot in 0..MAX_LISTED_SKILLS {
                let (key, level) = (format!("GENERAL_BODYGUARD_DETAILS+{}", 12 + 2 * slot), format!("GENERAL_BODYGUARD_DETAILS+{}", 13 + 2 * slot));
                match skills.get(slot) {
                    Some((skill, skill_level)) => { group.set_str(&key, skill)?.set_u32(&level, *skill_level)?; },
                    None => { group.unset(&key)?.unset(&level)?; },
                }
            }
        }

        if let (Some(row), Some(entry)) = (row, subject.entry) {
            let row_party = row.str("political_party")?;
            let party = political_party(entry, info.is_male, entry.widowed(), &row_party, self.parties.get(faction.key()).map(Vec::as_slice).unwrap_or_default());
            let group = record.group()?;

            // Thrones has no ambition, so its party comes right after the effect bundles' id.
            if layout.record(path).is_some_and(|details| details.has_slot("CAMPAIGN_EFFECT_BUNDLES+5")) {
                let ambition = if subject.death.is_some() { 0 } else { u32::try_from(row.int("ambition")?).unwrap_or_default() };
                group.set_u32("CAMPAIGN_EFFECT_BUNDLES+3", ambition)?.set_str("CAMPAIGN_EFFECT_BUNDLES+4", party)?;
            } else {
                group.set_str("CAMPAIGN_EFFECT_BUNDLES+3", party)?;
            }
            group.set_bool("GENERAL_BODYGUARD_DETAILS+2", row.bool("immortal")?)?
                .set_i32("GENERAL_BODYGUARD_DETAILS+4", i32::try_from(loyalty(entry, &self.loyalty_range)).unwrap_or_default())?;
        }
        record.build()
    }

    /// Writes the names of a character (`CHARACTER_NAME`) under a parent record. See [`write_character_name`].
    pub(super) fn write_name(&self, parent: &str, character: Option<&CharacterEntry>) -> Result<RecordNode> {
        write_character_name(self.inputs.layout, parent, character)
    }

    /// Writes the bodyguard of a character: the faction's default one for generals without a force, empty otherwise
    /// (a general's force holds its bodyguard as a unit).
    ///
    /// # Arguments
    ///
    /// * `details_path` - Path of the character's details.
    /// * `default` - The bodyguard, if the character keeps one.
    fn write_bodyguard(&self, details_path: &str, default: Option<&Bodyguard>) -> Result<RecordNode> {
        let path = format!("{details_path}/GENERAL_BODYGUARD_DETAILS");
        let mut record = self.inputs.layout.builder(&path)?;
        // Characters without a bodyguard (in a force, or colonels) keep only an empty unit key.
        let Some(default) = default else {
            record.group()?.set_str("^+1", "")?
                .unset("^+2")?.unset("^+3")?.unset("^+4")?.unset("^+5")?.unset("^+6")?
                .set_record("UNIT_STATISTICS_BONUSES", None)?;
            return record.build();
        };

        // The unit's details are only there when the character keeps its bodyguard.
        let bonuses = self.inputs.layout.default_record(&child_path(&path, "UNIT_STATISTICS_BONUSES"))?;
        record.group()?
            .set_str("^+1", default.unit())?
            .set_u32("^+2", default.men())?
            .set_u32("^+3", default.men())?
            .set_u32("^+4", 0)?
            .set_u32("^+5", 0)?
            .set_f32("^+6", 0.0)?
            .set_record("UNIT_STATISTICS_BONUSES", Some(bonuses))?;
        record.build()
    }

    /// Returns the family member id of a faction's progenitor (`start_pos_characters.progenitor`, living or dead), or
    /// 0 if it has none.
    pub fn progenitor_family_id(&self, faction: &FactionEntry) -> u32 {
        self.inputs.index.characters_of(faction.key())
            .find(|entry| entry.progenitor())
            .and_then(|entry| self.entry_family_ids.get(entry.id()))
            .copied()
            .unwrap_or_default()
    }

    /// Returns what a character sees: a disk of its agent's sight radius around it. Generals without a force don't
    /// see anything.
    ///
    /// # Errors
    ///
    /// Returns an error if a table or column is missing.
    pub fn vision(&self, character: &PlannedCharacter) -> Result<Option<Vision>> {
        let agent = self.info(character)?.agent;
        if agent == GENERAL_AGENT && character.force().is_none() {
            return Ok(None);
        }
        let (_, line_of_sight) = self.agents.get(&agent).copied().unwrap_or_default();
        let (position, _) = self.position(character)?;
        Ok(Some(self.sight.grid().disk(position, line_of_sight)))
    }

    /// Returns the planned characters of a faction.
    pub fn characters_of<'s>(&'s self, faction: &FactionEntry) -> impl Iterator<Item = &'s PlannedCharacter<'a>> + 's {
        self.forces.characters_of(faction.key())
    }

    /// Returns the runtime id of a character of the world, by its `start_pos_characters` id.
    pub fn runtime_id(&self, character: &str) -> Option<u32> {
        self.forces.characters().iter().find(|planned| planned.entry().is_some_and(|entry| *entry.id() == character)).map(|planned| planned.id())
    }

    /// Returns the runtime id of a faction's leader, if it has one.
    pub fn leader_id(&self, faction: &FactionEntry) -> Option<u32> {
        let leader = faction_leader(self.inputs.index, faction.key())?;
        self.forces.characters_of(faction.key()).find(|character| character.entry() == Some(leader)).map(|character| character.id())
    }

    /// Returns the agent type, gender, birth year and table row of a character.
    fn info<'r>(&'r self, character: &PlannedCharacter) -> Result<CharacterInfo<'r>> {
        let Some(entry) = character.entry() else {
            return Ok(CharacterInfo { agent: COLONEL_AGENT.to_owned(), is_male: true, birth_year: self.start_year.saturating_sub(COLONEL_AGE), row: None });
        };
        let row = self.rows.get(entry.id());
        Ok(CharacterInfo {
            agent: entry.agent().to_owned(),
            is_male: row.map(|row| row.bool("is_male")).transpose()?.unwrap_or(true),
            birth_year: u32::try_from(birth_year(i64::from(self.start_year), entry)).unwrap_or_default(),
            row,
        })
    }

    /// Returns the art set of a character (see [`pick_art_set`]).
    fn art_set(&self, faction: &FactionEntry, info: &CharacterInfo, seed: u32) -> &str {
        let portrait = info.row.and_then(|row| row.str("portrait_id").ok()).unwrap_or_default();
        pick_art_set(&self.art_sets, faction, &info.agent, info.is_male, &portrait, seed)
    }

    /// Returns the world position and cell of a character.
    ///
    /// Colonels stand on their settlement. Table characters stand on their starting cell, their linked settlement,
    /// their faction's first general (factions without capital), or off the map.
    pub(super) fn position(&self, character: &PlannedCharacter) -> Result<((f32, f32), HexCell)> {
        let settlement_cell = |region: &str| self.inputs.settlements.iter()
            .find(|settlement| settlement.region() == region)
            .and_then(|settlement| settlement.slots().first())
            .and_then(|slot| slot.position());
        let scale = self.inputs.region_map.scale();
        let at = |cell: Option<HexCell>| cell.map(|cell| (scale.world_position(cell), cell)).unwrap_or_default();

        let Some(entry) = character.entry() else {
            let region = character.force().and_then(|force| self.forces.forces()[force].region().clone()).unwrap_or_default();
            return Ok(at(settlement_cell(&region)));
        };

        Ok(match placement(self.inputs.tables, self.inputs.index, entry)? {
            Placement::Cell(cell) => at(Some(cell)),
            Placement::Settlement(region) => at(settlement_cell(&region)),
            Placement::FirstArmy => {
                let first_general = self.forces.characters_of(character.faction().key())
                    .find(|other| other.force().is_some() && other.entry().is_some_and(|other| other.id() != entry.id()));
                match first_general {
                    Some(general) => self.position(general)?,
                    None => Default::default(),
                }
            },
            Placement::OffMap => Default::default(),
        })
    }
}

/// Returns the agent type whose art sets a character uses: colonels look like generals.
fn art_set_agent(agent: &str) -> &str {
    if agent == COLONEL_AGENT { GENERAL_AGENT } else { agent }
}

/// Returns the family member ids: of every planned character (by position in the plan), and of every table
/// character, living or dead (by `start_pos_characters` id). The counter numbers each faction's table characters
/// (the living ones, then the dead ones, which only appear in the family tree), then the colonels.
fn family_ids(index: &CampaignIndex, plan: &WorldPlan, forces: &ForcePlan) -> (Vec<u32>, HashMap<String, u32>) {
    let mut ids = vec![0; forces.characters().len()];
    let mut by_entry = HashMap::new();
    let mut next_id = 1;
    for faction in plan.factions() {
        for (position, character) in forces.characters().iter().enumerate() {
            if let Some(entry) = character.entry().filter(|_| character.origin().key() == faction.key()) {
                ids[position] = next_id;
                by_entry.insert(entry.id().to_owned(), next_id);
                next_id += 1;
            }
        }
        for entry in index.characters_of(faction.key()).filter(|entry| !entry.death_type().is_empty()) {
            by_entry.insert(entry.id().to_owned(), next_id);
            next_id += 1;
        }
    }
    for (position, character) in forces.characters().iter().enumerate() {
        if character.entry().is_none() {
            ids[position] = next_id;
            next_id += 1;
        }
    }
    (ids, by_entry)
}

/// Writes the names of a character (`CHARACTER_NAME`) under a parent record: one block per name kind, with the name's
/// localisation key if it has one. Nameless characters get the same blocks, all of kind 0.
///
/// # Arguments
///
/// * `layout` - Record layouts of the game.
/// * `parent` - Path of the record holding the names.
/// * `character` - The character, or `None` for a nameless one.
///
/// # Errors
///
/// Returns an error if the layout lacks the records.
pub(crate) fn write_character_name(layout: &StartposLayout, parent: &str, character: Option<&CharacterEntry>) -> Result<RecordNode> {
    let names_path = format!("{parent}/CHARACTER_NAME/NAMES_BLOCK");
    let mut blocks = child(layout, &format!("{parent}/CHARACTER_NAME"), "NAMES_BLOCK")?;
    for kind in 0..NAME_COLUMNS.len() {
        let name = character.and_then(|character| character.names().get(kind)).map(String::as_str).unwrap_or_default();
        let mut localisation = child(layout, &names_path, "CAMPAIGN_LOCALISATION")?;
        if name.is_empty() {
            localisation.group()?.set_str("^+1", "")?;
        } else {
            localisation.group()?.set_str("^+1", &format!("{NAME_KEY_PREFIX}{name}"))?.unset("^+2")?;
        }
        blocks.push_group()?
            .set_record("CAMPAIGN_LOCALISATION", Some(localisation.build()?))?
            .set_i32("CAMPAIGN_LOCALISATION+1", if character.is_some() { i32::try_from(kind).unwrap_or_default() } else { 0 })?;
    }

    let mut record = child(layout, parent, "CHARACTER_NAME")?;
    record.group()?.set_record("NAMES_BLOCK", Some(blocks.build()?))?;
    record.build()
}

/// Returns the art set of a character: the campaign's art set its `portrait_id` names, if any, else one of the
/// campaign's art sets that aren't custom for its agent type and gender, of its faction, subculture (sets without
/// faction) or culture (sets without faction and subculture). The game draws one at random; this takes them in turns
/// by `seed` (the character's runtime id, or family id for the dead). Verified on Thrones (9 of 9 portrait ids) and
/// Attila's main campaign (19 of 21: the other two name another campaign's art sets).
fn pick_art_set<'s>(art_sets: &'s [ArtSet], faction: &FactionEntry, agent: &str, is_male: bool, portrait: &str, seed: u32) -> &'s str {
    if let Some(art_set) = art_sets.iter().find(|art_set| !portrait.is_empty() && art_set.id == portrait) {
        return &art_set.id;
    }
    let candidates = art_sets.iter()
        .filter(|art_set| !art_set.is_custom && art_set.agent == art_set_agent(agent) && art_set.is_male == is_male)
        .filter(|art_set| art_set.faction == *faction.key()
            || (art_set.faction.is_empty() && art_set.subculture == *faction.subculture())
            || (art_set.faction.is_empty() && art_set.subculture.is_empty() && art_set.culture == *faction.culture()))
        .collect::<Vec<_>>();
    candidates.get(seed as usize % candidates.len().max(1)).map(|art_set| art_set.id.as_str()).unwrap_or_default()
}

/// Returns the skills of each character (`start_pos_character_skills`: skill key and level), by `start_pos_characters`
/// id, sorted by key: the game keeps them in an ordered map. Verified on Thrones: 141 of 148 living characters with
/// skills; the other 7 list none, for reasons not found.
///
/// # Errors
///
/// Returns an error if the table or a column is missing.
fn character_skills(tables: &StartposTables) -> Result<HashMap<String, Vec<(String, u32)>>> {
    let mut skills = HashMap::<String, Vec<(String, u32)>>::new();
    for row in tables.table("start_pos_character_skills")?.rows() {
        let level = u32::try_from(row.int("level")?).unwrap_or_default();
        skills.entry(row.str("id")?.into_owned()).or_default().push((row.str("skill")?.into_owned(), level));
    }
    for list in skills.values_mut() {
        list.sort();
    }
    Ok(skills)
}