# 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):

## Contents

## 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 node is attached to a new black parent ^{[1]}, 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

TBD- ↑ the only possibility -> adding parent is the same as adding a child to it