Smart Stats System

Every number in your game comes from somewhere. Attack is 46 because the

character has 20 base, an iron sword adds 20, and Rage adds 15%. Most stat

systems can compute that number. Almost none can tell you afterwards where it

came from.

Smart Stats System is built the other way around. The breakdown is not a debug

feature bolted on top, it is produced by the calculation itself, every time.

Ask a stat for its value and you get a number. Ask it for its breakdown and you

get every stage, every modifier, every source, and exactly what each one

contributed.

THE ORDER PROBLEM

A +15% buff and a +20 sword do not commute. Apply the percentage first and the

sword never gets buffed - the number is wrong, and nothing tells you. Which one

happens first is a design decision, and most stat assets leave it to whatever

order things happened to be added in.

Here it is fixed and documented: base, then flat, then percent-add, then

percent-multiply, then override, then clamp. Same inputs, same result, always,

no matter what order you added them in or which frame they arrived on.

WHAT YOU GET

- Stats with deterministic modifier stacking and live, readable breakdowns.

- Derived stats. Max Health = Constitution x 10, recalculated when anything

underneath it moves, with cycle detection that prints the path it found.

- Resources - health, mana, stamina - with maximums driven by stats, so a

health bar can explain its own capacity. Regeneration, limits, and a record

of what happened: the potion says 30, the bar moved 12, and here is why.

- Timed effects with four stacking policies and optional pulses, so poison

ticks a resource on its own clock. Stacks are real copies of the modifiers,

not a number multiplied by a count, so three stacks of x1.2 are x1.728.

- Save and load. Base values, resource balances, and live effects including

remaining time and stack counts. Loading returns a report that names anything

it could not restore instead of failing silently.

- Authoring in the Inspector. Build a derived stat as a row of steps and the

inspector prints both the formula it produced and the number it gives you

right now - without entering Play mode.

- Validation before Play. One window walks every character in your open scenes,

including disabled ones, and tells you what is wrong in a full sentence.

- Two connectors. Equipment as a named bundle of modifiers that attaches and

detaches cleanly, and stat requirements that return a reason rather than a

bool - including the full breakdown of the number that fell short.

NO DEPENDENCIES

No packages to install, no third-party libraries, no art, no fonts, no render

pipeline requirement. The core is plain C# with no reference to UnityEngine at

all, which is why the entire system can be verified without entering Play mode

- and why your CI can run it.

ON TESTING

403 tests ship inside the package. Every code example in the documentation is

one of them: if a snippet in the manual says the answer is 46, there is a test

asserting 46. Import the package, open the Test Runner, and run them yourself

on day one.

WHAT THIS IS NOT

Not a combat system. It computes numbers; it does not decide how damage is

applied. Not an RPG kit, not an ability or skill system, not a character

controller, not a UI framework. It does not own your game loop, your item data,

or your save format.

Known limits are written out in the FAQ rather than left for you to discover:

there are no PlayMode tests, no netcode testing, and no project-wide balancing

tools. What is promised is what is proven.