How to express branching dialogue with Bevy ECS?

[johan-overbye]

I'm new to Bevy and somewhat new to Rust, and I'm evaluating Bevy for a dialogue-based RPG.

I'm trying to express branching dialogues with Bevy's ECS. Getting a rudimentary data structure in place was straightforward, but I'm unclear on how to access the components of a specific entity, in this case the next statement after the user chooses a reply. I feel like I'm missing something fundamental here. Is this even the right way to frame the problem in Bevy?

Here is my code so far, defining a rudimentary data structure and creating some dummy data:

use bevy::prelude::*;

#[derive(Component)]
struct Character
{
    name: String
}

#[derive(Component)]
struct Statement
{
    text: String,
    speaker: Option<Entity>,
    next: Option<Entity>
}

struct Choice
{
    text: String,
    next: Option<Entity>
}

#[derive(Component)]
struct Junction
{
    choices: Vec<Choice>
}

fn add_entities(mut commands: Commands) {
    let character = commands.spawn().insert(Character{name: "Character name".to_string()}).id();
    let char_statement = commands.spawn().insert(Statement{text: "Character statement.".to_string(), speaker: Some(character), next: None})
        .insert(Junction{ choices: vec!(
            Choice{text: "Choice 1.".to_string(), next: None},
            Choice{text: "Choice 2.".to_string(), next: None})
        })
        .id();
    let first_statement = commands.spawn().insert(Statement{text: "Narration statement.".to_string(), speaker: None, next: Some(char_statement)}).id();
}

[ickshonpe]

I implemented something similar for cutscenes in one of my projects, I'm not sure how practical it is etc though.
A more granular design might fit more naturally with Bevy's ECS. For instance, the components like Character, Statement, Junction, Choice and Junction could be empty Marker Components, and Name, Text, Speaker, Next and Choices could be POD newtype components.

To access the individual entities and their components you can use queries:

#[derive(Resource)]
struct CurrentNarrationNode(Option<Entity>);

fn statement_system(
    mut node: ResMut<CurrentNarrationNode>,  
    statements: Query<&Statement>,
    characters: Query<&Character>,
) {
    if let Some(statement) = node.0.and_then(|id| statements.get(id).ok()) {
        let name = statement.speaker
            .and_then(|id| characters.get(id).ok())
            .map(|character| character.name.as_str())
            .unwrap_or("unnamed");
        println!("{name}: {}", statement.text);
        node.0 = statement.next;
    }
}

[nicopap]

This answer is appropriate, but let me add 2 cents.

If you find the .and_then and map and all those functional combinators a bit too overwhelming, you have alternatives:

1. Do not make stuff Option<T> when they are not optional. If you are coming from another language, you might be familiar with initializing structs with nulls, add the value later and generally assume those values are always present. Please do not do this in Rust, just initialize all fields when constructing the struct.
2. Instead of using Option<T>, define your own enum. Here, I'd suggest something like

enum Speaker {
  Narrator,
  Character(Entity),
}

You can then define a method on Speaker (for example name(&self, query: &Query<&Character>) -> &str) this way, you don't have to deal with map_or, unwrap_or and other nonsense.

For next, it seems that an Option<Entity> is reasonable.

3. Use the ? operator. This code has a slightly different behavior from @ickshonpe solution, but I find it cleaner:

fn statement_system(
  mut node: ResMut<CurrentNarrationNode>,  
  statements: Query<&Statement>,
  characters: Query<&Character>,
) {
  let set_node = || {
    let statement = statements.get(node.0?).ok()?;
    let name = characters.get(statement.speaker?)
      .map_or("unnamed", |ch| ch.name.as_str());
    println!("{name}: {}", statement.text);
    node.0 = statement.next;
  };
  set_node();
}

Using my sysfail crate you can shorten it to:

#[quick_sysfail]
fn statement_system(
  mut node: ResMut<CurrentNarrationNode>,  
  statements: Query<&Statement>,
  characters: Query<&Character>,
) {
  let statement = statements.get(node.0?).ok()?;
  let name = characters.get(statement.speaker?)
    .map_or("unnamed", |ch| ch.name.as_str());
  println!("{name}: {}", statement.text);
  node.0 = statement.next;
}

[johan-overbye]

Thanks a lot, both answers are very helpful!

Query's get method is the main thing I was missing here.

Do not make stuff Option when they are not optional.

Absolutely. Good point about the Speaker enum.

One follow-up question to you both: Intuitively it seems wrong to say "give me all the statements" and then extract the single one I actually want. Is this intended usage of the Query system? Is it going to be performant if/when I have tens of thousands of statements?

[ickshonpe]

The query doesn't retrieve any components until you ask for them. So this would be terrible

fn terrible_system(
    mut node: ResMut<CurrentNarrationNode>,  
    statements: Query<(Entity, &Statement)>,
    ) {
    if let Some(node) = node.0.unwrap() {
        for (entity, statement) in statements.iter() {
            if node == entity {
                // retrieves potentially 10s of 1000s of components
            }
        }
    }
}

but using

if let Ok(statement) = statements.get(entity) {
    // .. 
}

only retrieves the components of the given entity.

That said, the Bevy ECS is really, really fast. Uselessly iterating through ten thousand components a couple of times a frame won't necessarily affect the player experience at all.

[johan-overbye]

OK, that makes sense. Thanks!