epoch_forge/lib_efo/src/stats.rs

772 lines
29 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

//! 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.
#![deny(clippy::missing_docs_in_private_items)]
use crate::{entity::EntityIdentifier, error::EpochError, thin_newtype, utils::RngLevel};
use cli_table::{CellStruct, Color, Style, Table};
use colored::Colorize;
use derive_more::{Add, Display, Mul, Sub};
use rand::{Rng, distr::Distribution, rngs::ThreadRng};
use serde::{Deserialize, Serialize};
use uuid::Uuid;
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, 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.
#[table(title = "DEM", customize_fn = "color_cell_categories")]
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.
#[table(title = "POP", customize_fn = "color_cell")]
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`.
#[table(title = "GRW", customize_fn = "color_cell")]
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).
#[table(title = "CRM", customize_fn = "color_cell")]
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).
#[table(title = "HPY", customize_fn = "color_cell")]
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.
#[table(title = "ECO", customize_fn = "color_cell_categories")]
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`.
#[table(title = "FOD", customize_fn = "color_cell")]
pub food: GenericStat,
/// Strength of the industry.
///
/// **Purpose** - Industrial production capacity.
/// **Effect** - Drives tax revenue and unit production.
/// **Source** - `industry = factory_output + tech_level`.
#[table(title = "IND", customize_fn = "color_cell")]
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`.
#[table(title = "SCI", customize_fn = "color_cell")]
pub science: GenericStat,
/// Trade volume / exports.
///
/// **Purpose** - Measure of export activity.
/// **Effect** - Influences influence and wealth.
/// **Source** - `trade = trade_network_output`.
#[table(title = "TRD", customize_fn = "color_cell")]
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.
// #[table(title = "SOC", color = "Color::Blue", bold, customize_fn = "color_cell")]
// 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)`.
// #[table(title = "CLU", customize_fn = "color_cell")]
// 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)`.
// #[table(title = "EDU", customize_fn = "color_cell")]
// pub education: GenericStat,
// /// Tourism revenue.
// ///
// /// **Purpose** - Income generated by visitors.
// /// **Effect** - Provides an additional income stream.
// /// **Source** - `tourism = number_of_tourists x price_per_tourist`.
// #[table(title = "TOR", customize_fn = "color_cell")]
// 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 x population`.
// #[table(title = "INF", customize_fn = "color_cell")]
// 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.
#[table(title = "MIL", customize_fn = "color_cell_categories")]
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.
#[table(title = "ARM", customize_fn = "color_cell")]
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) x tech_bonus x training_bonus`.
#[table(title = "STR", customize_fn = "color_cell")]
pub strength: GenericStat,
/// Defensive bonus from fortifications.
///
/// **Purpose** - Wall and tower defenses.
/// **Effect** - Adds a multiplier to overall defense.
/// **Source** - `fortification = Σ(fortification_building_bonus)`.
#[table(title = "FRT", customize_fn = "color_cell")]
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`.
#[table(title = "THR", customize_fn = "color_cell")]
pub threat: GenericStat,
// ──────────────────────── Infrastructure ────────────────────────
/// Total infrastructure power.
///
/// **Purpose** - Overall built-environment capacity.
/// **Effect** - Supports population size and efficiency.
/// **Source** - Sum of all infrastructure components.
#[table(title = "IFR", customize_fn = "color_cell_categories")]
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)`.
#[table(title = "BUR", customize_fn = "color_cell")]
pub bureaucracy: GenericStat,
/// Transportation level.
///
/// **Purpose** - Availability and quality of transport infrastructure.
/// **Effect** - Impacts logistics, mobility, and trade.
/// **Source** - `transportation = Σ(transport_building_output)`.
#[table(title = "TRP", customize_fn = "color_cell")]
pub transportation: GenericStat,
/// Sprawl / urban density.
///
/// **Purpose** - Measure of city sprawl and clutter.
/// **Effect** - Affects health, happiness, and infrastructure efficiency.
/// **Source** - `sprawl = Σ(sprawl_factor)`.
#[table(title = "SPR", customize_fn = "color_cell")]
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.).
#[table(title = "HLT", customize_fn = "color_cell")]
pub health: GenericStat,
}
/// Color the base cells
fn color_cell(cell: CellStruct, value: &GenericStat) -> CellStruct {
match (**value).cmp(&0) {
std::cmp::Ordering::Less => cell.foreground_color(Some(Color::Red)),
std::cmp::Ordering::Equal => cell,
std::cmp::Ordering::Greater => cell, //.foreground_color(Some(Color::Green)),
}
}
/// Color the cell categories
fn color_cell_categories(cell: CellStruct, value: &GenericStat) -> CellStruct {
match (**value).cmp(&0) {
std::cmp::Ordering::Less => cell.foreground_color(Some(Color::Red)).bold(true),
std::cmp::Ordering::Equal => cell.foreground_color(Some(Color::Blue)).bold(true),
std::cmp::Ordering::Greater => cell.foreground_color(Some(Color::Green)).bold(true),
}
}
impl OverallStats {
/// Create Stats with a given rng distribution
pub(crate) fn create_rng(
rng: &RngLevel,
mut rng_t: &mut ThreadRng,
) -> Result<OverallStats, EpochError> {
let r = rng.to_rng()?;
let mut overall_stats = Self {
demographics: 0.into(),
population: (r.sample(&mut rng_t) as isize).into(),
growth_rate: (r.sample(&mut rng_t) as isize).into(),
crime: (r.sample(&mut rng_t) as isize).into(),
happiness: (r.sample(&mut rng_t) as isize).into(),
economy: 0.into(),
food: (r.sample(&mut rng_t) as isize).into(),
industry: (r.sample(&mut rng_t) as isize).into(),
science: (r.sample(&mut rng_t) as isize).into(),
trade: (r.sample(&mut rng_t) as isize).into(),
military: 0.into(),
army: (r.sample(&mut rng_t) as isize).into(),
strength: (r.sample(&mut rng_t) as isize).into(),
fortification: (r.sample(&mut rng_t) as isize).into(),
threat: (r.sample(&mut rng_t) as isize).into(),
infrastructure: 0.into(),
bureaucracy: (r.sample(&mut rng_t) as isize).into(),
transportation: (r.sample(&mut rng_t) as isize).into(),
sprawl: (r.sample(&mut rng_t) as isize).into(),
health: (r.sample(&mut rng_t) as isize).into(),
};
overall_stats.update();
Ok(overall_stats)
}
/// Updates the inner meta values
// TODO: Force the use of this ?
pub fn update(&mut self) {
self.demographics =
(*(self.population + self.growth_rate + self.happiness - self.crime) / 4).into();
self.economy = (*(self.food + self.industry + self.trade + self.science) / 4).into();
self.military =
(*(self.army + self.strength + self.fortification + self.threat) / 4).into();
self.infrastructure =
(*(self.bureaucracy + self.transportation + self.sprawl + self.health) / 4).into();
}
/// Updates with events
/// Updates with leader
/// etc.
// TODO: Fill this
#[allow(dead_code)]
fn apply_exteriors(&mut self) {}
#[cfg(test)]
pub(crate) fn linear(base: isize) -> OverallStats {
use crate::stats;
Self {
demographics: stats::GenericStat(1 + base),
population: stats::GenericStat(2 + base),
growth_rate: stats::GenericStat(3 + base),
crime: stats::GenericStat(4 + base),
happiness: stats::GenericStat(5 + base),
economy: stats::GenericStat(6 + base),
food: stats::GenericStat(7 + base),
industry: stats::GenericStat(8 + base),
science: stats::GenericStat(9 + base),
trade: stats::GenericStat(10 + base),
military: stats::GenericStat(11 + base),
army: stats::GenericStat(12 + base),
strength: stats::GenericStat(13 + base),
fortification: stats::GenericStat(14 + base),
threat: stats::GenericStat(15 + base),
infrastructure: stats::GenericStat(16 + base),
bureaucracy: stats::GenericStat(17 + base),
transportation: stats::GenericStat(18 + base),
sprawl: stats::GenericStat(19 + base),
health: stats::GenericStat(20 + base),
}
}
}
/// 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: Option<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<String>,
// /// 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: Option<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: Option<FactionId>,
/// UIDs of all entities the entity is linked to (roads, trade routes,
/// alliances, war declarations, etc.).
pub links: Vec<TypedLink>,
/// 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: GenericStat,
/// The reach of the entity, wether local or worldly
///
/// **Purpose** - Event validation
pub reach: Reach,
}
/// A generic stat pair with (ListStats, GenericStat), used mainly for clap
/// Accepts two forms
/// 1. "cri 10" (two separate tokens)
/// 2. "cri:10" (one token with a separator)
#[derive(Debug, Serialize, Deserialize, Clone)]
pub struct StatPair {
/// The stat selected
pub stat: ListStats,
/// The value of the modifier
pub value: GenericStat,
}
/// A two-dimensional point on the world map.
///
/// The struct is a thin wrapper around a pair of `isize` values
/// representing the X and Y coordinates.
#[derive(Debug, Default, Serialize, Deserialize, Clone, Add, Sub, Mul)]
pub struct Position(isize, isize);
/// A grid-aligned position used for chunk look-ups.
///
/// A `PositionGrid` stores the coordinates of a chunk in the world
/// grid. Each component is the index of the chunk in the X and Y
/// direction.
#[derive(Debug, Default, Serialize, Deserialize, Clone, Add, Sub, Mul)]
pub struct PositionGrid(isize, isize);
/// The size of the whole world in pixels.
///
/// These constants are internal to the module; they are not part
/// of the public API.
// TODO(9): Change to be at least initialized with the world ?
const GRID_SIZE: (i32, i32) = (1920, 1080);
/// The size of one world chunk in pixels.
const CHUNK_SIZE: isize = 200;
impl Position {
/// Calculates the Euclidean distance between two points.
///
/// The distance is computed in the 2-D Euclidean space.
pub fn distance(&self, other: &Self) -> isize {
((self.0 - other.0).pow(2) + (self.1 - other.1).pow(2)).isqrt()
}
/// Converts this point to its corresponding grid position.
///
/// The conversion divides the world coordinates by the
/// `CHUNK_SIZE` to obtain the chunk indices.
pub fn to_grid_distance(&self) -> PositionGrid {
PositionGrid(self.0 / CHUNK_SIZE, self.1 / CHUNK_SIZE)
}
/// Returns the inner tuple representation of the position.
///
/// This is a convenience method to obtain the raw `(isize, isize)`
/// coordinates without wrapping them in the struct.
pub fn to_inner(&self) -> (isize, isize) {
(self.0, self.1)
}
/// Generates a random position within the world bounds.
///
/// The position is chosen uniformly at random using the supplied
/// random number generator.
pub fn create_rng(r: &mut ThreadRng) -> Result<Self, EpochError> {
let x = r.random_range(0..GRID_SIZE.0);
let y = r.random_range(0..GRID_SIZE.1);
Ok(Self(x as isize, y as isize))
}
}
impl PositionGrid {
/// Calculates the Euclidean distance between two grid positions.
///
/// The distance is computed by converting both grid positions to
/// world coordinates and then using `Position::distance`.
pub fn distance(&self, other: &PositionGrid) -> isize {
self.to_position().distance(&other.to_position())
}
/// Converts the grid coordinates to world coordinates.
///
/// Each component is multiplied by `CHUNK_SIZE` to obtain the
/// corresponding world position.
pub fn to_position(&self) -> Position {
Position(CHUNK_SIZE * self.0, CHUNK_SIZE * self.1)
}
}
/// 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,
}
impl From<OverallStats> for SummaryStats {
fn from(value: OverallStats) -> Self {
Self {
demographics: value.demographics,
economy: value.economy,
military: value.military,
infrastructure: value.infrastructure,
}
}
}
/// Bridge between the CLI and the statistics logic.
///
/// Helps convert clap arguments to OverallStats
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[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, Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum EntityType {
Character,
Player,
Town,
/// A calamity. Serialized as `Monster` for repository compatibility.
#[serde(rename = "Monster")]
Calamity,
Organization,
Blocker,
#[default]
Event,
}
/// Trait to implement some symbol representations
pub trait Symbols {
/// Have a small Symbol to resume it
fn to_symbol(&self) -> String;
/// Have the shortest display possible
fn to_shortest(&self) -> String {
self.to_symbol()
}
}
// impl<T: Symbols> Display for T {
// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
// write!(f, "{}", self.to_symbol())
// }
// }
// A stat that is shown to the player *and* can be modified manually.
thin_newtype!(GenericStat, isize, derives: [Add, Sub]);
thin_newtype!(TownId, Uuid);
thin_newtype!(CharacterId, Uuid);
thin_newtype!(FactionId, usize, derives: [Add, Sub]);
#[derive(Copy, Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Display, Default)]
/// A typed link between two entities.
///
/// A link is a lightweight association that ties an entity's **identifier**
/// (`id`) to a *semantic role* (`role`). The role is expressed by the
/// [`Role`] enum and defines what the link actually means in the
/// domain model.
#[display("{}{}({}{})",role, role.to_symbol(),other_id.to_symbol(), other_type.to_symbol())]
pub struct TypedLink {
/// The UUID of the entity that is linked.
///
/// The link is *unidirectional*; the `TypedLink` itself does not
/// keep a back-reference to the source entity.
pub other_id: Uuid,
/// The semantic role that this link plays.
///
/// For example, a link with `Role::Capital` indicates that the entity
/// identified by `id` is the capital of the entity that owns the link.
pub role: Role,
/// The Type of the entity linked
///
/// Even if it can mostly be inferred, some edge cases can be squashed
/// early in exchange of some data storred
pub other_type: EntityType,
}
impl TypedLink {
/// Simple initializer for the TypedLink type
pub fn new(other_id: Uuid, role: Role, other_type: EntityType) -> Self {
Self {
other_id,
role,
other_type,
}
}
}
#[derive(Copy, Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Display, Default)]
/// Semantic role of a link.
///
/// The role encodes *what the link represents* in the model. The
/// variants are intentionally limited to the most common use-cases,
/// but the enum can be extended if the domain evolves.
pub enum Role {
/// The linked entity has governing authority over the link owner
Govern,
/// The linked entity is the capital of the link owner
Capital,
#[default]
/// No role has been assigned.
Undefined,
}
// --- TRAITS ---------------------------------------------------------------
/// A stat is a *game value* that can be converted to two different
/// normalised ranges - a 100-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_100(&self) -> isize {
(self.get_value().clamp(0, 120) - 10).min(100)
}
/// Convert the raw integer to a 10-point scale.
fn to_10(&self) -> isize {
self.to_100() / 10
}
/// 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<dyn GameStat>`.
/// `None` if the key does not exist.
fn get_val(&self, key: &str) -> Option<Box<dyn GameStat>>;
}
/// Represents a position that can be identified in three different ways.
///
/// The string format is deliberately simple and is designed to be easy to write
/// by hand while still being unambiguous to a machine.
///
/// | Variant | Syntax in a string |
/// |---------|--------------------|
/// | `Exact` | `X,Y` |
/// | `Grid` | `~X,Y` or `gX,Y` |
/// | `Id` | `@{uuid}` |
#[derive(Debug, Clone)]
pub enum PositionIdentifier {
/// Exact position specified as `X,Y`.
Exact(Position),
/// Grid-aligned position specified as `~X,Y` or `gX,Y`.
Grid(PositionGrid),
/// Reference to an epoch by UUID, written as `@{uuid}`.
Id(EntityIdentifier),
}
#[derive(Debug, Clone, Default, Serialize, Deserialize)]
/// The reach of the entity
pub enum Reach {
/// The entity can affect **any** target - no positional or faction
/// restrictions. Use this when the effect is truly global.
Global,
/// The entity has a *limited* area of effect. The `usize` usually
/// represents the radius around the entity's position that the effect covers.
Local(usize),
/// The entity can only affect members of a particular faction.
Faction(FactionId),
// /// The entity only affect a specific entity
// Entity(EntityIdentifier),
/// No reach - the entity should not be applied globally.
#[default]
None,
}
/// A description of how a value should be updated.
///
/// The enum is intentionally tiny – only the three actions that
/// matter in our state‑diff engine. Each variant is documented
/// with a short, practical example so you know exactly when
/// you’d pick it.
///
/// The enum is `Copy`, so you can freely pass it around without
/// ownership worries. The `From<&str>` implementation below
/// lets you read the operation name from configuration files or
/// CLI flags:
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum Modification {
/// The modification will be a *delta*, i.e. an increment.
///
/// For numeric values this is equivalent to adding the new
/// value to the existing one. For collections it usually
/// means “append”.
Delta,
/// The modification will *replace* the existing value.
///
/// This is a hard overwrite: the old value is dropped
/// entirely and the new one is written in its place.
Replace,
/// The modification will *reset* the underlying value.
///
/// For plain types this is typically a default/zero value.
/// For `Option<T>` it sets the field to `None`. It can
/// also be interpreted as “delete the field entirely”.
Delete,
}