//! Module that holds all statistics for an entity and the helper methods that operate on them. //! //! The statistics are grouped into thematic sections (Demographics, Economy, Social, Military, //! Infrastructure). Each field is a `GenericStat`, an internal wrapper around a numeric value //! that provides convenience methods such as `max()`, `clamp()`, and arithmetic ops. //! //! The documentation for each field follows the same three‑part template: //! * **Purpose** – What the stat represents. //! * **Effect** – Gameplay consequence of the stat. //! * **Source** – Formula or function that generates the stat value. #![allow(dead_code)] #![deny(clippy::missing_docs_in_private_items)] use cli_table::Table; use colored::Colorize; use derive_more::Display; use serde::{Deserialize, Serialize}; use crate::thin_newtype; mod implementations; /// Aggregated statistics for a single entity. /// /// The struct is intentionally flat to keep access fast; the fields are logically grouped /// by comment blocks that describe each thematic section. #[derive(Debug, Clone, Default, Serialize, Deserialize)] // Derive more #[derive(Table)] // #[derive(Add, Sub)] pub struct OverallStats { // ──────────────────────── Demographics ──────────────────────── /// Total economic health of the entity. /// /// **Purpose** – A single value summarizing all economic indicators. /// **Effect** – Drives tax revenue, spending power, and overall economic influence. /// **Source** – Sum of `industry`, `science`, `trade`, and other economic contributors. pub demographics: GenericStat, /// Population count. /// /// **Purpose** – The number of citizens living in the entity. /// **Effect** – Determines resource consumption, tax base, and potential unrest. /// **Source** – Updated by the growth/decay formulas each turn. pub population: GenericStat, /// Per‑turn change in population. /// /// **Purpose** – The growth rate of the population. /// **Effect** – Predicts future needs and signals potential social unrest. /// **Source** – Derived from `population`, `happiness`, and `stability`. pub growth_rate: GenericStat, /// Crime level (0–1 scale). /// /// **Purpose** – How frequently crimes occur. /// **Effect** – Can trigger riots and reduce stability. /// **Source** – Result of the crime function (influenced by class disparity and law enforcement). pub crime: GenericStat, /// Base happiness of the population (0–1 scale). /// /// **Purpose** – A measure of citizen contentment. /// **Effect** – Influences productivity, tax compliance, and unrest. /// **Source** – Output of the happiness function (affected by class, war, infrastructure). pub happiness: GenericStat, // ──────────────────────── Economy ──────────────────────── /// Aggregate economic health of the entity. /// /// **Purpose** – A single value summarizing all economic metrics. /// **Effect** – Drives revenue, spending, and empire‑wide economic influence. /// **Source** – Sum of `food`, `industry`, `science`, `trade`, etc. pub economy: GenericStat, /// Food produced by the entity. /// /// **Purpose** – Amount of consumable resources available. /// **Effect** – Keeps the population alive and productive. /// **Source** – `food = farm_yield + tech_level`. pub food: GenericStat, /// Strength of the industry. /// /// **Purpose** – Industrial production capacity. /// **Effect** – Drives tax revenue and unit production. /// **Source** – `industry = factory_output + tech_level`. pub industry: GenericStat, /// Scientific output. /// /// **Purpose** – Rate of research progress. /// **Effect** – Determines how quickly new technologies are unlocked. /// **Source** – `science = research_center_output + tech_level`. pub science: GenericStat, /// Trade volume / exports. /// /// **Purpose** – Measure of export activity. /// **Effect** – Influences influence and wealth. /// **Source** – `trade = trade_network_output`. pub trade: GenericStat, // // ──────────────────────── Social ──────────────────────── // /// Overall social prestige. // /// // /// **Purpose** – Reflects the cultural standing of the entity. // /// **Effect** – Affects diplomacy and citizen morale. // /// **Source** – Sum of `culture`, `education`, `tourism`, etc. // pub social: GenericStat, // /// Cultural output from arts, theatres, museums, etc. // /// // /// **Purpose** – Measure of cultural production. // /// **Effect** – Drives tourism, prestige, and happiness. // /// **Source** – `culture = Σ(cultural_building_output)`. // pub culture: GenericStat, // /// Level of education/literacy. // /// // /// **Purpose** – Measure of the citizenry’s knowledge. // /// **Effect** – Improves productivity, science output, and reduces unrest. // /// **Source** – `education = Σ(education_building_output)`. // pub education: GenericStat, // /// Tourism revenue. // /// // /// **Purpose** – Income generated by visitors. // /// **Effect** – Provides an additional income stream. // /// **Source** – `tourism = number_of_tourists × price_per_tourist`. // pub tourism: GenericStat, // /// Cultural influence over the region. // /// // /// **Purpose** – Measure of soft power. // /// **Effect** – Grants diplomatic bonuses and increases sway in the empire. // /// **Source** – `influence = culture × population`. // pub influence: GenericStat, // ──────────────────────── Military ──────────────────────── /// Overall military power. /// /// **Purpose** – Composite measure of combat capability. /// **Effect** – Determines defensive and offensive strength. /// **Source** – Sum of `army`, `strength`, `fortification`, etc. pub military: GenericStat, /// Number of battle‑ready units. /// /// **Purpose** – Size of the active army. /// **Effect** – Directly dictates defense and attack potential. /// **Source** – Sum of all trained and equipped units. pub army: GenericStat, /// Composite strength of the army. /// /// **Purpose** – Tech, training, and equipment bonuses aggregated. /// **Effect** – Determines combat effectiveness and required force to defeat an enemy. /// **Source** – `strength = Σ(unit_strength) × tech_bonus × training_bonus`. pub strength: GenericStat, /// Defensive bonus from fortifications. /// /// **Purpose** – Wall and tower defenses. /// **Effect** – Adds a multiplier to overall defense. /// **Source** – `fortification = Σ(fortification_building_bonus)`. pub fortification: GenericStat, /// Threat level facing the entity. /// /// **Purpose** – Likelihood of being attacked. /// **Effect** – Triggers early warning alerts and strategic decisions. /// **Source** – `threat = (enemy_proximity + enemy_strength) / defense`. pub threat: GenericStat, // ──────────────────────── Infrastructure ──────────────────────── /// Total infrastructure power. /// /// **Purpose** – Overall built‑environment capacity. /// **Effect** – Supports population size and efficiency. /// **Source** – Sum of all infrastructure components. pub infrastructure: GenericStat, /// Bureaucratic power. /// /// **Purpose** – Efficiency of the city’s administrative machinery. /// **Effect** – Improves resource management and policy implementation. /// **Source** – `bureaucracy = Σ(bureaucracy_building_output)`. pub bureaucracy: GenericStat, /// Transportation level. /// /// **Purpose** – Availability and quality of transport infrastructure. /// **Effect** – Impacts logistics, mobility, and trade. /// **Source** – `transportation = Σ(transport_building_output)`. pub transportation: GenericStat, /// Sprawl / urban density. /// /// **Purpose** – Measure of city sprawl and clutter. /// **Effect** – Affects health, happiness, and infrastructure efficiency. /// **Source** – `sprawl = Σ(sprawl_factor)`. pub sprawl: GenericStat, /// Health infrastructure quality. /// /// **Purpose** – Public health capacity. /// **Effect** – Affects population health and can generate unrest. /// **Source** – `health = output_of_health_function` (influenced by sanitation, disease spread, etc.). pub health: GenericStat, } /// Strategic context and meta‑data for an entity. /// /// All fields are intentionally simple – the logic that interprets them /// lives in separate modules (e.g. `map`, `network`, `governance`). #[derive(Debug, Clone, Default, Serialize, Deserialize)] pub struct MetaStats { // ──── Location & Spatial Data (hidden) ─────────────────────────────── /// Cartesian coordinates of the entity on the world map. /// /// **Purpose** – Position of the entity in the simulation grid. /// **Effect** – Used for distance calculations, visibility, and /// map‑based event logic. /// **Source** – Supplied by the map generator. pub position: Position, /// Identifier for the capital pub capital: TownId, // /// List of nearby resource nodes (mines, forests, farms, etc.). // /// // /// **Purpose** – Resource map around the entity. // /// **Effect** – Drives the entity’s specialization and determines // /// the default output mix. // /// **Source** – `resources = filter(resource_list, distance ≤ detection_radius)`. // pub resources: Vec, // /// The entity’s chosen specialization tag // /// (e.g., “Agricultural Hub”, “Industrial Center”). // /// // /// **Purpose** – Identity that dictates default production multipliers. // /// **Effect** – Alters output curves and trade attractiveness. // /// **Source** – `specialization = tag_assigned_by_player_or_ai`. // pub specialization: String, // ──── Strategic Positioning (hidden + public) ───────────────────── /// Current governor or leader assigned to the entity. /// /// **Purpose** – Leadership identity. /// **Effect** – Adds personal bonuses and may modify policies /// or diplomatic stance. /// **Source** – `governor = selected_leader_uuid`. pub governor: CharacterId, // /// The entity’s classification (capital, trade hub, frontier post, etc.). // /// // /// **Purpose** – Functional role within the empire. // /// **Effect** – Alters base production, tax rates, and // /// certain event probabilities. // /// **Source** – `role = tag_assigned_by_player_or_ai`. // pub role: String, /// The faction or empire to which the entity currently belongs. /// /// **Purpose** – Political affiliation. /// **Effect** – Determines diplomatic relations, war status, /// and access to empire‑wide bonuses. /// **Source** – `faction = current_faction_uuid`. pub faction: FactionId, /// UIDs of all entities the entity is linked to (roads, trade routes, /// alliances, war declarations, etc.). /// /// **Purpose** – Connectivity network. /// **Effect** – Influences economic, military, and diplomatic /// interactions. /// **Source** – `links = Vec` collected from the entity’s /// network manager. pub links: Vec, /// Prestige / reputation of the entity in the eyes of the empire /// and foreign powers. /// /// **Purpose** – Social standing metric. /// **Effect** – Affects diplomatic influence, trade bonuses, /// and event outcomes. /// **Source** – `prestige = calculate_prestige(...)`. pub prestige: usize, } /// Structure used to indicate position, possess nice helper methods to use as is in the program #[derive(Debug, Default, Serialize, Deserialize, Clone)] pub struct Position(isize, isize); impl Position { /// The euclidian distance between two points fn distance(&self, other: &Self) -> isize { ((self.0 - other.0).pow(2) + (self.1 * other.1).pow(2)).isqrt() } /// The position in grid coordinates fn to_grid_distance(&self) -> (isize, isize) { (self.0 / 200, self.1 / 200) } } /// A summary of the stats, only for display purposes #[allow(clippy::missing_docs_in_private_items)] #[derive(Table)] pub struct SummaryStats { #[table(title = "Demo")] demographics: GenericStat, #[table(title = "Eco")] economy: GenericStat, // #[table(title = "Social")] // social: GenericStat, #[table(title = "Milit")] military: GenericStat, #[table(title = "Infra")] infrastructure: GenericStat, } /// Bridge between the CLI and the statistics logic. #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] #[allow(missing_docs)] pub enum ListStats { Demographics, Population, Growthrate, Crime, Happiness, Economy, Food, Industry, Science, Trade, Social, Culture, Education, Tourism, Influence, Military, Army, Strength, Fortification, Threat, Infrastructure, Bureaucracy, Transportation, Sprawl, Health, } /// The list of all types of entities #[allow(missing_docs)] #[derive(Serialize, Deserialize)] pub enum EntityType { Character, Player, Town, Monster, Blocker, Event, } // A stat that is shown to the player *and* can be modified manually. thin_newtype!(GenericStat, isize); thin_newtype!(TownId, usize); thin_newtype!(CharacterId, usize); thin_newtype!(FactionId, usize); // --- TRAITS --------------------------------------------------------------- /// A stat is a *game value* that can be converted to two different /// normalised ranges – a 50‑point range for “gaming” logic and a /// 10‑point range for “roll & UI” logic. The trait also exposes the /// underlying raw value and its visibility. /// // TODO[7]: Change this with Deref+From pub trait GameStat { /// Convert the raw integer to a 50‑point scale. fn to_50(&self) -> isize { (self.get_value().clamp(0, 70) - 10).min(50) } /// Convert the raw integer to a 10‑point scale. fn to_10(&self) -> isize { self.to_50() / 5 } /// As a colored delta (when the stat is used as a delta) fn to_delta(&self) -> String { let get_value = self.get_value(); if get_value < 0 { format!("{}", get_value.to_string().red()) } else { format!("{}", get_value.to_string().green()) } } /// Return the raw integer value, always bound to 0-70 fn get_value(&self) -> isize; /// Return the raw integer value, always bound to 0-70 fn change_value(&mut self, value: isize); /// Create a Gamestat from it's underlying value fn from_value(value: isize) -> Self where Self: Sized; } /// Trait for objects that can expose a stat via a string key. /// The trait returns a *boxed* trait object so callers do not need to know /// the concrete type that was stored. pub trait Accessible { /// Return the requested stat as a `Box`. /// `None` if the key does not exist. fn get_val(&self, key: &str) -> Option>; } // pub trait Displayable { // fn summary(&self) -> String; // fn full_description(&self) -> String; // }