127 lines
4.4 KiB
Rust
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,
|
|
}
|