Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zkat/big-brain
Utility AI library for the Bevy game engine
https://github.com/zkat/big-brain
bevy
Last synced: 1 day ago
JSON representation
Utility AI library for the Bevy game engine
- Host: GitHub
- URL: https://github.com/zkat/big-brain
- Owner: zkat
- License: other
- Created: 2020-07-11T01:08:31.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-30T18:56:43.000Z (about 2 months ago)
- Last Synced: 2025-01-15T19:08:21.426Z (9 days ago)
- Topics: bevy
- Language: Rust
- Homepage:
- Size: 571 KB
- Stars: 1,105
- Watchers: 13
- Forks: 66
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
Awesome Lists containing this project
README
# `big-brain``
[](https://crates.io/crates/big-brain)
[](https://docs.rs/big-brain)
[](./LICENSE.md)
`big-brain` is a [Utility
AI](https://en.wikipedia.org/wiki/Utility_system) library for games, built
for the [Bevy Game Engine](https://bevyengine.org/)
It lets you define complex, intricate AI behaviors for your entities based
on their perception of the world. Definitions are heavily data-driven,
using plain Rust, and you only need to program Scorers (entities that look
at your game world and come up with a Score), and Actions (entities that
perform actual behaviors upon the world). No other code is needed for
actual AI behavior.
See [the documentation](https://docs.rs/big-brain) for more details.
#### Features
* Highly concurrent/parallelizable evaluation.
* Integrates smoothly with Bevy.
* Proven game AI model.
* Highly composable and reusable.
* State machine-style continuous actions/behaviors.
* Action cancellation.
#### Example
As a developer, you write application-dependent code to define
[`Scorers`](#scorers) and [`Actions`](#actions), and then put it all
together like building blocks, using [`Thinkers`](#thinkers) that will
define the actual behavior.
##### Scorers
`Scorer`s are entities that look at the world and evaluate into `Score`
values. You can think of them as the "eyes" of the AI system. They're a
highly-parallel way of being able to look at the `World` and use it to
make some decisions later.
```rust
use bevy::prelude::*;
use big_brain::prelude::*;
#[derive(Debug, Clone, Component, ScorerBuilder)]
pub struct Thirsty;
pub fn thirsty_scorer_system(
thirsts: Query<&Thirst>,
mut query: Query<(&Actor, &mut Score), With>,
) {
for (Actor(actor), mut score) in query.iter_mut() {
if let Ok(thirst) = thirsts.get(*actor) {
score.set(thirst.thirst);
}
}
}
```
##### Actions
`Action`s are the actual things your entities will _do_. They are
connected to `ActionState`s that represent the current execution state of
the state machine.
```rust
use bevy::prelude::*;
use big_brain::prelude::*;
#[derive(Debug, Clone, Component, ActionBuilder)]
pub struct Drink;
fn drink_action_system(
mut thirsts: Query<&mut Thirst>,
mut query: Query<(&Actor, &mut ActionState), With>,
) {
for (Actor(actor), mut state) in query.iter_mut() {
if let Ok(mut thirst) = thirsts.get_mut(*actor) {
match *state {
ActionState::Requested => {
thirst.thirst = 10.0;
*state = ActionState::Success;
}
ActionState::Cancelled => {
*state = ActionState::Failure;
}
_ => {}
}
}
}
}
```
##### Thinkers
Finally, you can use it when define the `Thinker`, which you can attach as
a regular Component:
```rust
fn spawn_entity(cmd: &mut Commands) {
cmd.spawn((
Thirst(70.0, 2.0),
Thinker::build()
.picker(FirstToScore { threshold: 0.8 })
.when(Thirsty, Drink),
));
}
```
##### App
Once all that's done, we just add our systems and off we go!
```rust
fn main() {
App::new()
.add_plugins(DefaultPlugins)
.add_plugins(BigBrainPlugin::new(PreUpdate))
.add_systems(Startup, init_entities)
.add_systems(Update, thirst_system)
.add_systems(PreUpdate, drink_action_system.in_set(BigBrainSet::Actions))
.add_systems(PreUpdate, thirsty_scorer_system.in_set(BigBrainSet::Scorers))
.run();
}
```
#### bevy version and MSRV
The current version of `big-brain` is compatible with `bevy` 0.14.0.
The Minimum Supported Rust Version for `big-brain` should be considered to
be the same as `bevy`'s, which as of the time of this writing was "the
latest stable release".
#### Reflection
All relevant `big-brain` types implement the bevy `Reflect` trait, so you
should be able to get some useful display info while using things like
[`bevy_inspector_egui`](https://crates.io/crates/bevy_inspector_egui).
This implementation should **not** be considered stable, and individual
fields made visible may change at **any time** and not be considered
towards semver. Please use this feature **only for debugging**.
#### Contributing
1. Install the latest Rust toolchain (stable supported).
2. `cargo run --example thirst`
3. Happy hacking!
#### License
This project is licensed under [the Apache-2.0 License](LICENSE.md).