epoch_forge/lib_efo/src/entity.rs

127 lines
4.4 KiB
Rust

//! # 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,
}