Expand description
Author-defined effect registries and active effect state.
effects is a horizontal gameplay-definition layer. It does not ship
poison, speed, regeneration, potion, survival, or player-specific behavior.
The game author defines effect ids, metadata, tags, stacks, durations, and
the systems that interpret active effects.
The framework provides three generic pieces:
EffectRegistry— author-defined metadata for effects.ActiveEffectSet— runtime effect instances, usable globally or as a component on any entity.EffectApplied/EffectExpiredplus helper functions for Bevy systems that want to react to effect lifecycle changes.
§Example
use bevy::ecs::message::MessageWriter;
use bevy::prelude::*;
use voxel_framework::effects::{
ActiveEffectSet, EffectApplied, EffectDefinition, EffectRegistry, VoxelEffectsPlugin,
apply_effect,
};
fn register_effects(mut effects: ResMut<EffectRegistry>) {
effects
.register(
EffectDefinition::new("low_oxygen")
.named("Low Oxygen")
.duration_secs(10.0)
.max_stacks(3)
.tag("space_suit"),
)
.expect("effect id should be unique");
}
fn apply_low_oxygen(
registry: Res<EffectRegistry>,
mut active: ResMut<ActiveEffectSet>,
mut applied: MessageWriter<EffectApplied>,
) {
apply_effect("low_oxygen", ®istry, &mut active, &mut applied)
.expect("effect should exist");
}
App::new()
.add_plugins(MinimalPlugins)
.add_plugins(VoxelEffectsPlugin)
.add_systems(Startup, register_effects)
.add_systems(Update, apply_low_oxygen);Structs§
- Active
Effect Set - Active author-defined effect instances.
- Effect
Applied - Message emitted by
apply_effectandapply_effect_instance. - Effect
Definition - Author-defined effect metadata.
- Effect
Definition Snapshot - Serializable snapshot of one author-defined effect definition.
- Effect
Expired - Message emitted by
tick_effectswhen finite effects expire. - Effect
Id - Stable identifier for an author-defined effect.
- Effect
Instance - Runtime instance of an author-defined effect.
- Effect
Instance Snapshot - Serializable snapshot of one active effect instance.
- Effect
Registry - Registry of author-defined effect definitions.
- Voxel
Effects Plugin - Horizontal plugin that initializes author-defined effect resources.
Enums§
- Effect
Error - Errors returned by effect registries and active effect sets.
Functions§
- apply_
effect - Applies an effect and emits
EffectApplied. - apply_
effect_ instance - Applies an explicit effect instance and emits
EffectApplied. - tick_
effects - Advances finite effect durations and emits
EffectExpiredfor each expired effect.