An experimental, status effects-as-entities system for Bevy.
1# Bevy Alchemy
2
3[](https://crates.io/crates/bevy_alchemy)
4[](https://docs.rs/bevy_alchemy)
5
6
7An experimental, status effects-as-entities system for Bevy.
8
9### Applying Effects
10Effects can be applied using `with_effect` or `with_effects` (similar to `with_child` and `with_children` respectively).
11```rust ignore
12commands.entity(target).with_effect((Name::new("Effect"), MyEffect));
13```
14They can also be added using spawn-style syntax.
15```rust ignore
16commands.spawn((
17 Name::new("Target"),
18 EffectedBy::spawn(
19 Effect((Name::new("Effect"), MyEffect))
20 ),
21));
22```
23
24Note that these methods *might* spawn a new entity, depending on what effects are already applied to the target.
25
26### Effect Modes
27For some effects it makes sense to allow stacking, so a single entity could be effected by an effect multiple times.
28Other effects should only be applied once, either replacing or merging with the previous one.
29This behaviour can be selected using an effect's `MergeMode`, which has the following cases:
30
31| Mode | Behaviour |
32|--------|-----------------------------------------------------------------------------------------|
33| Stack | Multiple of the same effect can exist at once. |
34| Insert | New applications will overwrite the existing one. |
35| Merge | New applications are merged with the existing one, using a configurable merge function. |
36
37Effects are considered the same if they have the same name.
38
39### Implementing Effects
40Effects can be implemented using simple systems. Below is an excerpt from the poison example.
41```rust ignore
42/// Runs every frame and deals the poison damage.
43fn deal_poison_damage(
44 effects: Query<(&Effecting, &Delay, &Poison)>,
45 mut targets: Query<&mut Health>,
46) {
47 for (target, delay, poison) in effects {
48 // We wait until the delay finishes to apply the damage.
49 if !delay.timer.is_finished() {
50 continue;
51 }
52
53 // Skip if the target doesn't have health.
54 let Ok(mut health) = targets.get_mut(target.0) else {
55 continue;
56 };
57
58 // Otherwise, deal the damage.
59 health.0 -= poison.damage;
60 }
61}
62```
63
64### Utility Components
65A handful of components are included that are intended to make it easier to create common effects.
66
67| Component | Description |
68|----------------|-------------------------------------------------------------------------------|
69| `Lifetime` | A timer that despawns the effect when the timer finishes. |
70| `Delay` | A repeating timer used for the delay between effect applications. |
71| `EffectStacks` | Tracks the number of times a merge-mode effect has been applied to an entity. |
72
73### Bevy Version Compatibility
74
75| Bevy | Bevy Alchemy |
76|--------|---------------|
77| `0.18` | `0.2` - `0.5` |
78| `0.17` | `0.1` |