lib_efo/entity/implementations/

methods.rs

//! # Entity Methods
//!
//! This module implements the public API of the `Entity` struct.  
//! The API covers:
//! 1. **Statistical reporting** – pretty tables and pretty‑printed trees.  
//! 2. **Metadata manipulation** – links, links, governor/capital, prestige, etc.  
//! 3. **Stat modification** – strict, fuzzy, delta, and randomised changes.  
//! 4. **Entity creation** – deterministic or RNG‑based.  
//! 5. **Utility helpers** – position handling, identifier matching.

use cli_table::{Style, WithTitle};
use colored::*;
use rand::distr::Distribution;

use crate::{
    entity::*,
    epoch::EpochInfo,
    error::EpochError,
    items_table,
    stats::{self, Symbols},
    utils::RngLevel,
};
use uuid::Uuid;

impl Entity {
    // Display the entity's statistics in a pretty table.
    ///
    /// The table contains both the permanent and temporary statistics of the
    /// entity.  The table is formatted with a custom border and separator
    /// using the `cli_table` crate.
    ///
    /// # Returns
    /// A `Result` containing the table display on success, or an `EpochError` if the
    /// conversion to a table string fails.
    pub fn full_stats_to_table(&self) -> Result<cli_table::TableDisplay, EpochError> {
        let items = if let Some(t) = &self.temp_stats {
            vec![&self.stats, t]
        } else {
            vec![&self.stats]
        };
        self.stat_to_table(items)
    }

    /// Adds a link (UUID) to the entity's metadata.
    ///
    /// If `id_to_add` is already present in the `links` vector, this method does
    /// nothing - it silently ignores duplicates.  The method is idempotent: calling
    /// it repeatedly with the same UUID will not change the underlying state.
    pub fn add_to_links(&mut self, id_to_add: stats::TypedLink) {
        if !self.metadata.links.contains(&id_to_add) {
            self.metadata.links.push(id_to_add);
        }
    }

    /// Removes a link (UUID) from the entity's metadata.
    ///
    /// If the supplied `id_to_remove` exists in `self.metadata.links`, it is
    /// removed and returned wrapped in `Some`.  If the UUID is not present,
    /// the method returns `None` and leaves the link list unchanged.
    pub fn del_from_links(&mut self, id_to_remove: stats::TypedLink) -> Option<stats::TypedLink> {
        self.metadata
            .links
            .iter()
            .position(|id| *id == id_to_remove)
            .map(|pos| self.metadata.links.swap_remove(pos))
    }
    /// Display the entity's statistics in a pretty table (same format as
    /// `full_stats_to_table`).
    ///
    /// This method is provided for backward compatibility and forwards all
    /// work to `full_stats_to_table`.
    ///
    /// # Returns
    /// A `Result` containing the table display on success, or an `EpochError` if the
    /// conversion to a table string fails.
    pub fn stats_to_table(&self) -> Result<cli_table::TableDisplay, EpochError> {
        let items = if let Some(t) = &self.temp_stats {
            vec![t]
        } else {
            vec![&self.stats]
        };
        self.stat_to_table(items)
    }

    /// Reset the temporary stats to a given base value.
    ///
    /// Useful before performing an update: you can set the temporary stats to
    /// whatever snapshot you want to start from (or `None` to clear it).
    pub fn reset_temporary_stats_to(&mut self, other: Option<OverallStats>) {
        self.temp_stats = other;
    }

    /// Return an immutable reference to the entity’s live statistics.
    pub fn get_stats(&self) -> &OverallStats {
        &self.stats
    }
    /// Return an immutable reference to the temporary statistics snapshot,
    /// if one is currently stored.
    pub fn get_temp_stats(&self) -> &Option<OverallStats> {
        &self.temp_stats
    }

    /// Display the entity's statistics in a pretty table (same format as
    /// `full_stats_to_table`).
    ///
    /// This method is provided for backward compatibility and forwards all
    /// work to `full_stats_to_table`.
    ///
    /// # Returns
    /// A `Result` containing the table display on success, or an `EpochError` if the
    /// conversion to a table string fails.
    ///
    pub(crate) fn stat_to_table(
        &self,
        items: Vec<&OverallStats>,
    ) -> Result<cli_table::TableDisplay, EpochError> {
        items_table!(items, self.name.clone(), self.id)
    }

    /// Pretty-print the entity as a coloured tree.
    ///
    /// The output is a `String` that visualises the entity's metadata, type,
    /// duration, effect bounds, and any links.  Colours are applied using
    /// `colored::Colorize`.
    ///
    /// # Returns
    /// A `String` containing the formatted tree.
    pub fn to_pretty_tree(&self, epoch_info: &EpochInfo) -> String {
        // Helper that prefixes a line with the correct amount of vertical bars.
        pub(crate) fn indent(level: usize, line: &str) -> String {
            let bars = "│ ".repeat(level);
            format!(" {}{}", bars, line)
        }

        let mut out = String::new();

        out.push_str(&format!(
            "[{} {} 󰻾[{}]]\n",
            self.entity_type.to_symbol().blue().bold(),
            self.name.cyan().bold(),
            self.id.to_string().blue().bold()
        ));

        // ── Metadata section
        out.push_str(&indent(0, &format!("├─ {}\n", "metadata".green())));
        if let Some(capital) = self.metadata.capital {
            out.push_str(&indent(
                1,
                &format!(
                    "├─ {}: {}\n",
                    "capital".bright_green(),
                    implementations::uuid_to_symbol(*capital, epoch_info, &EntityType::Town)
                ),
            ));
        }
        if let Some(faction) = self.metadata.faction {
            out.push_str(&indent(
                1,
                &format!(
                    "├─ {} : {}{}\n",
                    "faction".bright_green(),
                    " ".yellow(),
                    faction.to_string().yellow(),
                ),
            ));
        }
        if let Some(governor) = self.metadata.governor {
            out.push_str(&indent(
                1,
                &format!(
                    "├─ {}: {}\n",
                    "governor".bright_green(),
                    implementations::uuid_to_symbol(*governor, epoch_info, &EntityType::Character)
                ),
            ));
        }
        if *self.metadata.prestige > 0 {
            out.push_str(&indent(
                1,
                &format!(
                    "├─ {}: {}{}\n",
                    "prestige".bright_green(),
                    self.metadata.prestige.to_string().yellow(),
                    " ".yellow()
                ),
            ));
        }
        out.push_str(&indent(
            1,
            &format!(
                "└─ {}: {}\n",
                "position".bright_green(),
                self.metadata.position.to_symbol()
            ),
        ));

        // ── Optional links
        if !self.metadata.links.is_empty() {
            out.push_str(&indent(0, &format!("├─ {}\n", "links".green())));
            for (i, link) in self.metadata.links.iter().enumerate() {
                let last = i == self.metadata.links.len() - 1;
                let symbol = if last { "└─" } else { "├─" };
                out.push_str(&indent(
                    1,
                    &format!(
                        "{} {}\n",
                        symbol,
                        implementations::uuid_to_symbol(
                            link.other_id,
                            epoch_info,
                            &link.other_type
                        )
                        .yellow()
                    ),
                ));
            }
        }
        // ── Other top-level fields
        out.push_str(&indent(
            0,
            &format!(
                "├─ {}: {}\n",
                "duration".green(),
                self.duration.to_symbol().yellow()
            ),
        ));
        out.push_str(&indent(
            0,
            &format!("├─ {}: {:?}\n", "effect_nature".green(), self.effect_nature),
        ));
        out.push_str(&indent(
            0,
            &format!(
                "└─ {}: {}",
                "effect_bounds".green(),
                self.effect_bounds.to_symbol()
            ),
        ));

        out
    }

    /// Create an entity using a specific RNG level.
    ///
    /// The entity is initialised with random statistics, a random position,
    /// and a random prestige value derived from the supplied `RngLevel`.
    ///
    /// # Arguments
    /// * `e_type` - The type of entity to create.
    /// * `rng` - The RNG level to use when generating random values.
    ///
    /// # Returns
    /// * `Ok(Self)` - The newly created entity.
    /// * `Err(EpochError)` - Propagated from any randomisation failure.
    ///
    pub fn create_rng(e_type: &EntityType, rng: &RngLevel) -> Result<Self, EpochError> {
        let mut r = rand::rng();
        Ok(Self {
            id: Uuid::new_v4(),
            stats: OverallStats::create_rng(rng, &mut r)?,
            temp_stats: None,
            metadata: MetaStats {
                prestige: stats::GenericStat(rng.to_rng()?.sample(&mut r) as isize),
                position: stats::Position::create_rng(&mut r)?,
                ..Default::default()
            },
            entity_type: *e_type,
            ..Default::default()
        })
    }

    /// Increment the time of the entity
    pub(crate) fn increment_time(&mut self) {
        match self.duration {
            EntityDuration::Permanent => (),
            EntityDuration::Duration(d) => {
                if d <= 1 {
                    self.duration = EntityDuration::Done;
                } else {
                    self.duration = EntityDuration::Duration(d.saturating_sub(1))
                }
            }
            EntityDuration::Done => (),
        }
    }
}