Ok, so some explanations on how stuff works now and some of my thoughts on how it should work in foreseeable future...
Stats:Stats in PyTFall are what you'd expect them to be, they describe characters capabilities and compare characters to one another.
Logic:- stats (current base value)
- item mod (modifications by items)
- min (minimum)
- max (top cap)
- level max (top cap by characters level)
mod is required to prevent stuff like this:
You have a character with attack of 90 and max attack of 100.
You equip a sword adding 50 more points.
The total (max) is capped with 100.
However when the sword is removed... stat needs to be reverted back to 90 and not become 50 (100 - 50). Also if a character has gained a point, it needs to become 91 and not be lost due to max cap.
min = self-explanatory.
max = absolute maximum the stat is capable of.
level max = absolute maximum a stat is capable of at current level. This is a way to ensure that seriously powerful items cannot be used fully by a weak character (but would still max them out and be useful to them). Every time a level is gained by a character, lvl_max goes up by 5 and normal max by 2. At the start level_max is lower than the max and stats are capped off with that but as character progresses, lvl_max overtakes (and eventually leaves hopelessly behind) normal max and becomes irrelevant, at that point any item can be used to it's fullest potential. Obviously items can only modify normal max or this system would not work. So a sword that adds 100 to max and 100 to attack is of VERY limited use to a noob character while lethal in hands of an advanced one.
Our stats code does all of the above and more:- it handles death (and ends the game at ANY point automatically if main characters health reaches 0 (*In case of other characters, it removes them from MCs team, employment/ownership, actions/locations))
- it handles level-ups (we use D&D based system but our (true) progression is somewhat more linear at this development stage)
- it handles bonuses from a complex system of traits (part of the bonuses, some are handled by character class (such as those from added effects))
- it automatically restores health, mp and vitality every time new level is reached by any character
what's more, this is used by mobs, complex characters, simple characters, main character (also very different from the rest).
I am not going to go into what every stat is responsible for because even if I do, in a game this complex it will STILL mean different things to different people. So it's up to content creators to play the game, get the feel of stats and decide how to proceed with the content.