Expand description
Yoetz - A Rule Based AI Plugin for the Bevy Game Engine
Yoetz (“advisor” in Hebrew) is a rule based AI plugin for Bevy, structured around the following tenets:
- There is no need to build special data structures for calculating the transitions and the scores when representing these mechanisms as code inside user systems is both more flexible and simpler to use.
- The systems that check the rules need to be able to pass data to the systems act upon the decisions.
- Enacting the decision should be done with the ECS. If the action that the rules mechanism decided to do is reflected by components, it becomes easy to write different systems that perform the various possible actions.
§Quick Start
Define the various actions the AI can do with an enum that derives YoetzSuggestion
, and add
a YoetzPlugin
for it:
app.add_plugins(YoetzPlugin::<AiBehavior>::new(FixedUpdate));
#[derive(YoetzSuggestion)]
enum AiBehavior {
DoNothing,
Attack {
#[yoetz(key)]
target_to_attack: Entity,
},
}
Give YoetzAdvisor
to the AI controlled entities:
commands.spawn((
// The argument to `new` is a bonus for maintaining the current action.
YoetzAdvisor::<AiBehavior>::new(2.0),
OtherComponentsForThisEntity,
));
Add under YoetzSystemSet::Suggest
systems that check for the various rules and generate
suggestions with scores:
app.add_systems(
FixedUpdate,
(
make_ai_entities_do_nothing,
give_targets_to_ai_entities,
)
.in_set(YoetzSystemSet::Suggest),
);
fn make_ai_entities_do_nothing(mut query: Query<&mut YoetzAdvisor<AiBehavior>>) {
for mut advisor in query.iter_mut() {
// A constant suggestion, so that if nothing else beats this score the entity will
// still have a behavior to execute.
advisor.suggest(0.0, AiBehavior::DoNothing);
}
}
fn give_targets_to_ai_entities(
mut query: Query<(&mut YoetzAdvisor<AiBehavior>, &GlobalTransform)>,
targets_query: Query<(Entity, &GlobalTransform), With<Attackable>>,
) {
for (mut advisor, ai_transform) in query.iter_mut() {
for (target_entity, target_transorm) in targets_query.iter() {
let distance = ai_transform.translation().distance(target_transorm.translation());
advisor.suggest(
// The closer the target, the more desirable it is to attack it. If the
// distance is more than 10, the score will get below 0 and the DoNothing
// suggestion will be used instead.
10.0 - distance,
AiBehavior::Attack {
target_to_attack: target_entity,
},
);
}
}
}
Add under YoetzSystemSet::Act
systems that performs these actions. These systems use
components that are generated by the YoetzSuggestion
macro and are added and removed automatically by YoetzPlugin
:
app.add_systems(
FixedUpdate,
(
perform_do_nothing,
perform_attack,
)
.in_set(YoetzSystemSet::Act),
);
fn perform_do_nothing(query: Query<&AiBehaviorDoNothing>) {
for _do_nothing in query.iter() {
// Do... nothing. This whole function is kind of pointless.
}
}
fn perform_attack(mut query: Query<(&mut Attacker, &AiBehaviorAttack)>) {
for (mut attacker, attack_behavior) in query.iter_mut() {
attacker.attack(attack_behavior.target_to_attack);
}
}
Re-exports§
pub use bevy;
Modules§
Structs§
- Add systems for processing a
YoetzSuggestion
.
Enums§
- System sets to put suggestion systems and action systems in.