An experimental, status effects-as-entities system for Bevy.
Start on readme
+73
-2
+72
-1
README.md
+72
-1
README.md
···
1
1
# Bevy Alchemy
2
2
3
-
An experimental, status effects-as-entities system for Bevy.
3
+
[](https://crates.io/crates/bevy_alchemy)
4
+
[](https://docs.rs/bevy_alchemy)
5
+
6
+
7
+
An experimental, status effects-as-entities system for Bevy.
8
+
9
+
### Applying Effects
10
+
Effects can be applied using `with_effect` or `with_effects` (similar to `with_child` and `with_children` respectively).
11
+
```rust ignore
12
+
commands.entity(target).with_effect(EffectBundle {
13
+
name: Name::new("Effect"),
14
+
bundle: MyEffect,
15
+
..default()
16
+
});
17
+
```
18
+
They can also be added using spawn-style syntax.
19
+
```rust ignore
20
+
commands.spawn((
21
+
Name::new("Target"),
22
+
EffectedBy::spawn(EffectBundle {
23
+
name: Name::new("Effect"),
24
+
bundle: MyEffect,
25
+
..default()
26
+
}),
27
+
));
28
+
```
29
+
30
+
### Effect Modes
31
+
For some effects it makes sense to allow stacking, so a single entity could be effected multiple times at once.
32
+
For others, each effect should only be applied once.
33
+
34
+
Both behaviours are supported, and can be selected using an effect's `MergeMode`.
35
+
36
+
| Mode | Behaviour |
37
+
|--------|-----------------------------------------------------------------------------------------|
38
+
| Stack | Multiple of the same effect can exist at once. |
39
+
| Insert | New applications will overwrite the existing one. |
40
+
| Merge | New applications are merged with the existing one, using a configurable merge function. |
41
+
42
+
### Implementing Effects
43
+
Effects can be implemented using simple systems. Below is an excerpt from the poison example.
44
+
```rust ignore
45
+
/// Runs every frame and deals the poison damage.
46
+
fn deal_poison_damage(
47
+
effects: Query<(&Effecting, &Delay, &Poison)>,
48
+
mut targets: Query<&mut Health>,
49
+
) {
50
+
for (target, delay, poison) in effects {
51
+
// We wait until the delay finishes to apply the damage.
52
+
if !delay.timer.is_finished() {
53
+
continue;
54
+
}
55
+
56
+
// Skip if the target doesn't have health.
57
+
let Ok(mut health) = targets.get_mut(target.0) else {
58
+
continue;
59
+
};
60
+
61
+
// Otherwise, deal the damage.
62
+
health.0 -= poison.damage;
63
+
}
64
+
}
65
+
```
66
+
67
+
### Examples
68
+
69
+
70
+
### Bevy Version Compatibility
71
+
72
+
| Bevy | Bevy Alchemy |
73
+
|--------|--------------|
74
+
| `0.17` | `0.1` |