The bonus system of VCMI is a set of mechanisms that make handling of different bonuses for heroes, towns, players and units easier. The system consists of a set of nodes representing objects that can be a source or a subject of a bonus and two directed acyclic graphs (DAGs) representing inheritance and propagation of bonuses.
Here is a brief sketch of the system (black arrows indicate the direction of inheritance and red arrows the direction of propagation):
Propagation and inheritance
Assuming the graph of bonus system is temporarily not changing, the bonuses are propagated as follows:
- We take all bonuses by precedence in red DAG (more accurate description is not yet specified) and using their propagators we apply them to appropriate red children. Propagators default to none.
- We take all bonuses by precedence in black DAG (more accurate description to be specified) and apply them to all black children with respect to limiters. A limiter can specify that inheritance should be stopped at a certain node, default is to propagate to all black children.
Operations on the graph
There are two basic types of operations that can be performed on the graph:
Adding a new node
When adding a new node, it has to be attached to some other part of system. When node is attached to a new black parent, the propagation system is triggered and works as follows:
- For the attached node and its all red ancestors
- For every bonus
- Call propagator giving the new descendant -> then attach appropriately bonuses to the red descendant of attached node (or the node itself).
- For every bonus
Deleting an existing node
Analogically to the adding a new node, just remove propagated bonuses instead of adding them. Then update the hierarchy.
Calculating the total value of a bonus