# `herdingcats`
Deterministic rule orchestration for turn-based games.
Author: Madeline Prelee (mprelee@gmail.com)
## Overview
`herdingcats` is a generic engine for implementing deterministic, rule-driven turn-based systems.
It provides:
- Explicit priority-ordered rule execution
- Transactional state mutation
- Undo / redo
- Replay-safe hashing (FNV‑1a)
- Rule enable / disable
- Rule lifetimes (per-turn / per-trigger)
- Event cancellation
- Preview execution without committing state
- Static, enum-based event dispatch
- Compile-time enforced integer-backed priority
The engine is application-agnostic and does not prescribe game semantics.
---
## Core Model
The engine is parameterized over:
- `S` — game state
- `O` — operation type (`Operation<S>`)
- `E` — event enum
- `P` — priority enum (`#[repr(i32)]`, sealed)
State mutation occurs exclusively through `Operation`.
All irreversible transactions:
- Are logged
- Are undoable
- Update the replay hash
- Produce commit frames
---
## Determinism Guarantees
- No hidden state mutation
- No dynamic event dispatch
- No runtime type inspection
- No unordered rule execution
- Replay hash restored on undo / redo
- Preview execution does not mutate history
All ordering is explicit via priority.
---
## Intended Use
Designed for discrete, turn-based systems such as:
- Roguelikes
- Tactical strategy games
- Card systems
- Deterministic multiplayer simulations
- Digital board games
Not intended for:
- Real-time systems
- Physics simulations
- Dynamic scripting engines
- Freeform narrative interpretation
---
## Status
Pre‑1.0. API may change.
---
## License
MIT OR Apache-2.0
# AI Usage Policy (subject to change)
This codebase is being (co)written using AI frameworks and committed to
enforcing idiomatic rust patterns where-possible. It's more important
that the code adheres to good standards to the point where it is unclear
whether it was written by a knowledgeable Rust expert or a very good LLM.