Crate immediate_stats

Expand description

Game stats that reset every frame, inspired by immediate mode GUI.

This makes it easy to implement temporary buffs/debuffs, and effects that change over time. Using a derive macro, stat resets are propagated to any stat fields, making it easy to compose stats into more complex objects.

#[derive(StatContainer)]
struct Speed(Stat);

fn main() {
    let mut speed = Speed(Stat::new(10)); // Set base speed to 10.
     
    loop {
        speed.0 *= 2.0; // Applies a multiplier to the final result.
        speed.0 += 5; // Adds a bonus to the final result.
        // The order does not matter, bonuses are always applied before multipliers.
        assert_eq!(speed.0.total(), 30); // (10 + 5) * 2 = 30

        speed.reset_modifiers(); // Reset speed back to 10.
    }
}

§Bevy

There is build-in integration with the Bevy Engine via the bevy feature flag. This adds systems for resetting StatContainer components and resources.

#[derive(StatContainer, Component, Resource, Default)]
struct Speed(Stat);

fn main() {
    App::new()
        .add_plugins((
            ImmediateStatsPlugin,
            ResetComponentPlugin::<Speed>::new(),
            ResetResourcePlugin::<Speed>::new(),
        ))
        .run();
}

§Bevy Auto Plugin

If you use Bevy Auto Plugin, you can also use the bevy_auto_plugin feature flag. This automatically registers the required system(s) by leveraging the existing auto_component and auto_resource macros.

fn main() {
    App::new().add_plugins((ImmediateStatsPlugin, MyPlugin)).run();
}

#[derive(AutoPlugin)]
#[auto_plugin(impl_plugin_trait)]
struct MyPlugin;

// `StatContainer` derive hooks into the existing `auto_component` and `auto_resource` macros.
#[derive(StatContainer, Component, Resource)]
#[auto_component(plugin = MyPlugin)] // Adds `reset_component_modifiers` system.
#[auto_resource(plugin = MyPlugin)] // Adds `reset_resource_modifiers` system.
struct Speed(Stat);

§Version Compatibility

Bevy	Immediate Stats
`0.16`	`0.1` - `0.2`

Structs§

ImmediateStatsPlugin: Configures system ordering and registers types with the Bevy type registry.
Modifier: Modifier values that can be applied to a Stat.
PauseStatReset: Prevents all StatContainers on an entity from getting reset by ResetComponentPlugin.
ReflectStatContainer: A type generated by the #[reflect_trait] macro for the StatContainer trait.
ResetComponentPlugin: Calls reset_modifiers on all T components. This can be paused on a per-entity basis using the PauseStatReset component.
ResetResourcePlugin: Calls reset_modifiers on the T resource, if it exists.
Stat: A stat that resets to a base value every iteration.

Enums§

StatSystems: A SystemSet for ordering Immediate Stats operations. Recommend configuration can be added via the ImmediateStatsPlugin.

Traits§

StatContainer: Types that contain stats that need to be reset.

Functions§

reset_component_modifiers: Calls reset_modifiers on all T components. This can be paused on a per-entity basis using the PauseStatReset component.
reset_resource_modifiers: Calls reset_modifiers on the T resource, if it exists.

Derive Macros§

StatContainer: Implements reset_modifiers by propagating the call down to any stat fields.