Crate bevy_yoetz

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:

1. 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.
2. The systems that check the rules need to be able to pass data to the systems act upon the decisions.
3. 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>::default());

#[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(
    Update,
    (
        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(
    Update,
    (
        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

• prelude

Structs

• YoetzPlugin
  Add systems for processing a YoetzSuggestion.

Enums

• YoetzSystemSet
  System sets to put suggestion systems and action systems in.