bevy_alchemy 0.3.0

An experimental, status effects-as-entities system for Bevy.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82

# Bevy Alchemy

[![Version](https://img.shields.io/crates/v/bevy_alchemy)](https://crates.io/crates/bevy_alchemy)
[![Docs](https://img.shields.io/docsrs/bevy_alchemy)](https://docs.rs/bevy_alchemy)
![License](https://img.shields.io/crates/l/bevy_alchemy)

An experimental, status effects-as-entities system for Bevy.

### Applying Effects
Effects can be applied using `with_effect` or `with_effects` (similar to `with_child` and `with_children` respectively).
```rust ignore
commands.entity(target).with_effect(EffectBundle {
    name: Name::new("Effect"),
    bundle: MyEffect,
    ..default()
});
```
They can also be added using spawn-style syntax.
```rust ignore
commands.spawn((
    Name::new("Target"),
    EffectedBy::spawn(EffectBundle {
        name: Name::new("Effect"),
        bundle: MyEffect,
        ..default()
    }),
));
```

### Effect Modes
For some effects it makes sense to allow stacking, so a single entity could be effected by an effect multiple times.
Other effects should only be applied once, either replacing or merging with the previous one. 
This behaviour can be selected using an effect's `MergeMode`, which has the following cases:

| Mode   | Behaviour                                                                               |
|--------|-----------------------------------------------------------------------------------------|
| Stack  | Multiple of the same effect can exist at once.                                          |
| Insert | New applications will overwrite the existing one.                                       |
| Merge  | New applications are merged with the existing one, using a configurable merge function. |

Effects are considered the same if they have the same name.

### Implementing Effects
Effects can be implemented using simple systems. Below is an excerpt from the poison example.
```rust ignore
/// Runs every frame and deals the poison damage.
fn deal_poison_damage(
    effects: Query<(&Effecting, &Delay, &Poison)>,
    mut targets: Query<&mut Health>,
) {
    for (target, delay, poison) in effects {
        // We wait until the delay finishes to apply the damage.
        if !delay.timer.is_finished() {
            continue;
        }

        // Skip if the target doesn't have health.
        let Ok(mut health) = targets.get_mut(target.0) else {
            continue;
        };

        // Otherwise, deal the damage.
        health.0 -= poison.damage;
    }
}
```

### Utility Components
A handful of components are included that are intended to make it easier to create common effects.

| Component      | Description                                                                   |
|----------------|-------------------------------------------------------------------------------|
| `Lifetime`     | A timer that despawns the effect when the timer finishes.                     |
| `Delay`        | A repeating timer used for the delay between effect applications.             |
| `EffectStacks` | Tracks the number of times a merge-mode effect has been applied to an entity. |

### Bevy Version Compatibility

| Bevy   | Bevy Alchemy  |
|--------|---------------|
| `0.18` | `0.2` - `0.3` |
| `0.17` | `0.1`         |