zzstat 0.1.4

A deterministic, hardcode-free stat calculation engine designed for MMORPGs
Documentation

zzstat

A deterministic, hardcode-free stat calculation engine designed for MMORPGs.

Features

  • 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
  • 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

Core Concepts

Stat Pipeline

Stats flow through a simple pipeline:

[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

Quick Start

Add to your Cargo.toml:

[dependencies]
zzstat = "0.1.0"

Example

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

Examples

The examples/ directory contains several example programs:

  • basic.rs - Basic stat resolution with sources and transforms
  • dependencies.rs - Stats that depend on other stats
  • complex.rs - Complex character stat system
  • cycle_detection.rs - Error handling for circular dependencies
  • context.rs - Using StatContext for conditional calculations

Run examples with:

cargo run --example basic
cargo run --example dependencies
cargo run --example complex

See examples/README.md for more details.

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

License

This project is licensed under the MIT License. See LICENSE file for details.