Bonus system

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:

1. 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.
2. 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).

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

TBD