//! # Entity System //! //! The `Entity` type represents any object that can participate in the game world. //! It encapsulates runtime statistics, temporary bonuses, and metadata, //! along with information about its lifetime and the nature of its effects. //! //! The design intentionally groups behaviour into two primary components, //! `OverallStats` and `MetaStats`. The `entity_type` field is a placeholder //! for future trait-based dispatch - the enum will eventually be replaced //! by a type-safe system. For the moment it provides a quick lookup for //! logic that distinguishes creatures, items, terrain, etc. //! use std::str::FromStr; use derive_more::{Add, Display, Sub}; use serde::{Deserialize, Serialize}; use uuid::Uuid; use crate::{ error::EpochError, stats::{EntityType, MetaStats, OverallStats}, }; pub mod implementations; /// An entity that can be present in the game world. /// /// Entities are mutable only through the entity system's public API. /// Their fields are private to prevent accidental state corruption. #[derive(Serialize, Deserialize, Debug, Clone, Default)] pub struct Entity { /// The name of the entity pub name: String, /// A short description of the entity pub description: String, /// The global identifier for the entity pub id: Uuid, /// Runtime statistics that determine the entity's behaviour. /// /// These values are updated by the game loop and reflect the /// entity's current state (e.g., health, speed, attack). stats: OverallStats, /// Temporary statistics that include bonuses from events, /// leaders, or other temporary modifiers. /// /// `temp_stats` is recalculated each turn and does not persist /// beyond the entity's lifetime. #[serde(skip)] temp_stats: Option, /// Non-statistical metadata such as name, rarity, and faction. /// /// This information is not directly part of the entity's combat /// calculations but is useful for UI and logic. metadata: MetaStats, /// The categorical type of the entity. /// /// Currently an enum that distinguishes creatures, items, /// terrain, etc. It will be phased out in favor of a trait-based /// system for greater type safety. pub entity_type: EntityType, /// The lifetime of the entity within the game world. /// /// The game loop checks this value during each tick to decide /// whether to keep or remove the entity. duration: EntityDuration, /// Describes the effect applied by the entity. /// /// This determines when the effect is applied and whether it /// persists after the entity is removed. effect_nature: EffectApplication, /// Limits that clamp any stat changes caused by the entity's effect. effect_bounds: EffectBounds, } /// Limits for the maximum and minimum value that an effect may /// modify a statistic. The bounds are applied after the effect has /// been calculated to keep stats within a sane range. /// /// `min` and `max` are inclusive. #[derive(Debug, Serialize, Deserialize, Clone, Default, Add, Sub)] #[allow(missing_docs)] pub struct EffectBounds { pub min: usize, pub max: usize, } /// How the entity's effect is applied over time. #[derive(Debug, Serialize, Deserialize, Clone, Default)] pub enum EffectApplication { /// Repeatedly applied every turn while the entity is present. Recurring, /// Modifies the attached entity's stats only while present. WhenPresent, /// Permanently modifies stats #[default] PermanentEffectToApply, /// Indicates that a permanent effect has already been applied. PermanentEffectApplied, } impl FromStr for EffectApplication { type Err = EpochError; fn from_str(s: &str) -> Result { match s { _ if s.starts_with("re") => Ok(EffectApplication::Recurring), _ if s.starts_with("wh") => Ok(EffectApplication::WhenPresent), _ if s.contains("present") => Ok(EffectApplication::WhenPresent), _ if s.contains("toap") => Ok(EffectApplication::WhenPresent), _ if s.starts_with("appl") => Ok(EffectApplication::WhenPresent), "done" | "ok" => Ok(EffectApplication::PermanentEffectApplied), "todo" => Ok(EffectApplication::PermanentEffectToApply), _ => Err(EpochError::ParsingArgument { argument_parsed: s.to_string(), while_parsing: "EffectApplication", }), } } } /// Represents how long an entity remains active in the world. #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq, Default)] pub enum EntityDuration { /// The entity persists until it is explicitly destroyed. Permanent, /// The entity remains for a fixed number of turns. /// The counter is decremented each tick and the entity becomes /// `Done` once it reaches zero. Duration(usize), /// The entity's lifecycle has finished and it should no longer /// be updated. This variant is typically used for one-off /// events or buffs that expire after their final turn. #[default] Done, } /// An identifier that can be supplied on the command line. /// /// The enum is deliberately small so it can be used as a Clap argument type. /// It accepts **either** /// * a plain name (e.g. `"bob"`), or /// * a UUID that is prefixed with an `@` (e.g. `"@3f4c6b7e-d4d1-4b3f-a7a4-0d5c6b8e1f9b"`). /// /// The two variants are kept separate so that downstream code can decide /// whether it should treat the value as a human-readable name or a /// machine-identifiable UUID. #[derive(Debug, Clone, PartialEq, Eq, Display)] pub enum EntityIdentifier { /// A human-readable name. Name(String), /// A UUID that was supplied with a leading `@`. The `@` is stripped /// when the enum is constructed - only the raw UUID string is stored. Id(String), } #[allow(clippy::unwrap_used)] #[cfg(test)] mod test;