zzstat 0.1.4

A deterministic, hardcode-free stat calculation engine designed for MMORPGs
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86

//! # zzstat - Deterministic, Hardcode-Free MMORPG Stat Engine
//!
//! A stat calculation engine designed for MMORPGs that provides:
//! - **Deterministic** stat resolution (same input → same output)
//! - **Hardcode-free** design (no built-in stat names like "HP" or "ATK")
//! - **Event-driven** resolution (only resolves when invalidated)
//! - **Phase-based** transformation pipeline
//!
//! ## Core Concepts
//!
//! ### Stat Pipeline
//!
//! Stats flow through a simple pipeline:
//!
//! ```text
//! [StatSource] → [StatTransform] → [ResolvedStat]
//! ```
//!
//! 1. **Sources** produce base values (additive)
//! 2. **Transforms** modify values (can depend on other stats)
//! 3. **ResolvedStat** contains the final value with full breakdown
//!
//! ### Key Features
//!
//! - **Dependency Graph**: Automatically resolves dependencies in correct order
//! - **Cycle Detection**: Prevents circular dependencies
//! - **Caching**: Resolved stats are cached until invalidated
//! - **Context-Aware**: Supports conditional calculations via `StatContext`
//! - **Debug-Friendly**: Full breakdown of sources and transforms
//!
//! ## Example
//!
//! ```rust
//! use zzstat::*;
//! use zzstat::source::ConstantSource;
//! use zzstat::transform::MultiplicativeTransform;
//!
//! let mut resolver = StatResolver::new();
//! let hp_id = StatId::from_str("HP");
//!
//! // Register sources (additive)
//! resolver.register_source(hp_id.clone(), Box::new(ConstantSource(100.0)));
//! resolver.register_source(hp_id.clone(), Box::new(ConstantSource(50.0)));
//!
//! // Register transform
//! resolver.register_transform(hp_id.clone(), Box::new(MultiplicativeTransform::new(1.5)));
//!
//! // Resolve
//! let context = StatContext::new();
//! let resolved = resolver.resolve(&hp_id, &context).unwrap();
//! assert_eq!(resolved.value, 225.0); // (100 + 50) * 1.5
//! ```
//!
//! ## Modules
//!
//! - [`stat_id`] - Stat identifier type
//! - [`source`] - Stat sources (produce base values)
//! - [`transform`] - Stat transforms (modify values)
//! - [`resolver`] - Main stat resolver
//! - [`resolved`] - Resolved stat results
//! - [`context`] - Context for conditional calculations
//! - [`graph`] - Dependency graph management
//! - [`error`] - Error types

pub mod context;
pub mod error;
pub mod graph;
pub mod resolved;
pub mod resolver;
pub mod source;
pub mod stat_id;
pub mod transform;

// Re-export main types for convenience
pub use context::StatContext;
pub use error::StatError;
pub use resolved::ResolvedStat;
pub use resolver::StatResolver;
pub use stat_id::StatId;

// Re-export common sources and transforms
pub use source::{ConstantSource, MapSource, StatSource};
pub use transform::{
    AdditiveTransform, ClampTransform, ConditionalTransform, MultiplicativeTransform,
    ScalingTransform, StatTransform,
};