Crate bevy_stat_query

Crate bevy_stat_query 

Source
Expand description

§bevy-stat-query

Crates.io Docs Bevy tracking

Versatile RPG stat system for the bevy engine.

§Overview

In order to represent stats, stat buffs and stat queries in an ECS, bevy_stat_query exclusively uses unordered operations to represent stats, this includes add, multiply, min, max and or.

For instance if we want to evaluate a character’s strength, taken into account buffs and debuffs this can look something like this:

clamp((42 + 4 + 7 + (-4)) * 2 * 0.75, 1, 99)

Note how the order of evaluation doesn’t matter, which fits perfectly into the “insert component and have effect” usage pattern of the ECS.

§Qualified Stats

We describe each stat as a Qualifier and a Stat. Stat is a noun like strength or damage and Qualifier are adjectives that describes what this Stat can be applied to.

For example in fire magic damage, (fire, magic) is the Qualifier, damage is the Stat.

§Modifier and Query

There are actually two types of stats, modifier and query.

A modifier is something alone the lines of

Increase (fire, magic) damage by 5.

While a query is

This attack does (fire, magic) damage.

When querying for (fire, magic) damage, all modifiers that boosts damage, fire damage, magic damage or (fire, magic) damage can apply to this query. While modifier that boosts a different qualifier ice damage or a different stat fire defense does not apply to this query.

In bevy_stat_query, a modifier is represented as (Qualifier, Stat, Value) while a query is represented as (QualifierQuery, Stat).

  • Conditional Modifiers

A common trope in fantasy games is the modifier elemental damage, which applies to any of fire, ice, etc. In Qualifier this is the any_of field.

  • Exact Query

Imagine we have an effect like this:

Add 50% of the character's magic damage to physical damage.

In order to avoid duplication, since effects boosting damage applies to both, we can use QualifierQuery::exact.

§Traits

Qualifier is usually a bitflags implementing QualifierFlag, Stat is usually an enum deriving Stat.

An app usually has a single QualifierFlag but multiple Stat implementors, since each Stat can associate to a different type. For example strength and magic can be a i32, hp can be a f32, is_dragon can be a bool etc.

Different types of stats can still query each other via Querier to model effects like

If user is a dragon, increase damage by 50%.

§StatStream and QueryStream

In order for components to contribute to stats, you must implement QueryStream. StatStream can be used if no additional querying is needed. A Component that implements StatStream is automatically a QueryStream.

In order to use QueryStream, mark queryable entities as StatEntity. Then add StatEntities to you system and join it with various QueryStreams.

fn stat_query(
    entities: StatEntities,
    stat_maps: StatQuery<StatMap>,
    weapons: StatQuery<Weapon>,
    buffs: ChildQuery<Buff>,
) {
    let querier = entities.join(&stat_maps).join(&weapons).join(&buffs);
    let damage = querier.eval_stat(&MyQualifier::Magic, &MyStat::Damage).unwrap();
}

Using bevy_stat_query is significantly easier if you have access to &mut World. One-shot systems are recommended to perform queries.

§Relations

StatStream and QueryStream provides the stream_relation function that makes it easier to implement relation based effects like

Increase damage of all allies within 3 yards by 5.

Checkout one of our examples on how to implement this.

§Versions

bevybevy-stat-query
0.150.1 - latest

§License

Licensed under either of

at your option.

§Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Re-exports§

pub use operations::StatValue;

Modules§

operations
rounding
types

Macros§

match_stat
Downcast StatValuePair to a concrete pair of stat and value.
vtable
Construct a reference to a static StatVTable with serialization support.

Structs§

ChildQuery
SystemParam for querying QueryStreams on entities referenced by a component like Children.
ChildQueryMut
SystemParam for querying QueryStreams on entities referenced by a component like Children.
Fraction
Represents a fractional number.
GlobalStatDefaults
Resource that stores default StatValues per Stat.
GlobalStatRelations
Resource that stores global StatStreams that runs on every query.
JoinedQuerier
NoopQuerier
A Querier that does not provide the ability to query other entities.
Qualifier
Data side qualifier for a stat.
Querier
An erased type that can query for stats on entities in the world.
StatDeserializers
Resource containing a name to instance map of Stats.
StatEntities
A root SystemParam that curates all entities marked as StatEntity.
StatEntity
The core marker component. Stat querying is only allowed on entities marked as StatEntity.
StatMap
A type erased storage component of qualified stats.
StatQuery
SystemParam for querying a QueryStream.
StatQueryMut
SystemParam for querying a QueryStream.
StatVTable
A vtable of dynamic functions on Stat::Value.
StatValuePair
A pair of stat and value in a query.

Enums§

Attribute
Represents either a string or a typed enum.
QualifierQuery
Query version of Qualifier.

Statics§

STAT_DESERIALIZERS

Traits§

EntityReference
A component that references other entities, like Children.
Flags
A type that can be treated as flags.
Float
Trait for a floating point number or a Fraction.
Int
Trait for an integer.
NumCast
Number
QualifierFlag
A flags like Qualifier for stats, normally bitflags or a set.
QueryStream
A set of Components and external SystemParams that provide stat modifiers for an Entity.
Shareable
Alias for Clone + Debug + Send + Sync + 'static.
Stat
Implement this on your types to qualify them as a Stat.
StatExtension
Extension on World and App
StatStream
An isolated item that provides stat modifiers to a stat query.

Derive Macros§

Attribute
Allow the type to convert to Attribute.
Stat
Derive macro for Stat.