//! # 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 derive_more::{Add, Sub}; use serde::{Deserialize, Serialize}; use uuid::Uuid; use crate::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, /// 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. temp_stats: OverallStats, /// 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. /// Use with caution, as this can produce catastrophic results /// (e.g., an ever-erupting terrain). Recurring, /// Modifies the attached entity's stats only while present. /// Removed when the entity is removed. Common for leaders, /// temporary events, or terrain. WhenPresent, /// Permanently modifies stats; the change persists after /// the event ends. #[default] PermanentEffectToApply, /// Indicates that a permanent effect has already been applied. /// Useful for bookkeeping when a long-lasting event applies /// its effect only once. PermanentEffectApplied, } /// 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, }