Crate bevy_alchemy 

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

commands.entity(target).with_effect(EffectBundle {
    name: Name::new("Effect"),
    bundle: MyEffect,
    ..default()
});

They can also be added using spawn-style syntax.

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.

/// 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;
    }
}

Timers

Two timers are added by the crate:

1. Lifetime - Despawns the effect when the timer ends.
2. Delay - A repeating timer used for the delay between effect applications.

Bevy Version Compatibility

Bevy	Bevy Alchemy
0.17	0.1

Structs

AddEffectCommand

Applies an effect to a target entity. This might spawn a new entity, depending on what effects are already applied to the target.

AlchemyPlugin

Setup required types and systems for bevy_alchemy.

Delay

A repeating timer used for the delay between effect applications.

EffectBundle

A “bundle” of components/settings used when applying an effect. Due to technical limitations, this doesn’t actually implement Bundle. Instead, purpose build commands (with_effect) or related spawners (EffectedBy::spawn) should be used.

EffectMergeRegistry

Stores the effect merge logic for each registered component. New components can be registered by providing a EffectMergeFn to the register method. This function will be run whenever an effect is applied twice to the same entity with EffectMode::Merge.

EffectSpawner

Uses commands to apply effects to a specific target entity.

EffectedBy

Stores all the status effects that are effecting this entity.

Effecting

Stores the entity that is being effected by this status effect.

Lifetime

Despawns the entity when the timer finishes.

Enums

EffectMode

Describes the logic used when multiple of the same effect are applied to an entity.

TimerMergeMode

Controls the merge behaviour of a timer when its effect is merged.

Traits

EffectCommandsExt

An extension trait for adding effect methods to EntityCommands.

EffectTimer

A timer which is used for status effects and includes a TimerMergeMode.

Functions

register_timer_merge_functions

Registers the default merge logic for Lifetime and Delay.

Type Aliases

EffectMergeFn

A function used to merge effects with EffectMode::Merge, which must be registered in the registry.