SuperAPI AI 工具集

bevy-dialogue-system

编程与开发

查看项目

更新于 10-16 11:40

技能介绍

用途

该技能用于在 Bevy 0.20 中组织对话数据。当台词、选项或说话者 ID 需要推进时加载。注意:渲染台词本身属于 bevy-ui-text 的职责,本技能不负责富文本渲染。

主要能力

  • 使用 Resource 存放运行范围内的台词表(如 bevy-data-resources),而不是 autoload。
  • 使用自定义 Component 保存台词 ID 与说话者 ID;当前台词索引存放在 Component 上。
  • 在 Update 或固定时间步上修改这些组件;当伤害必须早于死亡结算时使用 .chain() 排序。
  • 一次性事实(命中、拾取、任务推进)通过 bevy-events-messaging 处理,本文件不新增事件类型名。
  • 选项作为台词上的数据存在;当所需标志缺失时隐藏该选项。

使用方式

在 Cargo.toml 中引入依赖:

[dependencies]
bevy = "0.20"

ECS 结构示例:

#[derive(Clone)]
struct LineDef {
    speaker: &'static str,
    text: &'static str,
    next: Option<usize>,
}

#[derive(Resource)]
struct DialogueTable {
    lines: Vec<LineDef>,
}

#[derive(Component)]
struct LineMark {
    index: usize,
    open: bool,
}

fn advance_line(
    keys: Res<ButtonInput<KeyCode>>,
    table: Res<DialogueTable>,
    mut marks: Query<&mut LineMark>,
) {
    if !keys.just_pressed(KeyCode::Space) {
        return;
    }
    for mut mark in &mut marks {
        if !mark.open {
            continue;
        }
        let Some(line) = table.lines.get(mark.index) else {
            mark.open = false;
            continue;
        };
        match line.next {
            Some(next) => mark.index = next,
            None => mark.open = false,
        }
    }
}

fn spawn_conversation(mut commands: Commands) {
    commands.insert_resource(DialogueTable {
        lines: vec![
            LineDef {
                speaker: "guide",
                text: "The gate opens at dusk.",
                next: Some(1),
            },
            LineDef {
                speaker: "guide",
                text: "Bring the key.",
                next: None,
            },
        ],
    });
    commands.spawn(LineMark {
        index: 0,
        open: true,
    });
}

pub struct DialoguePlugin;

impl Plugin for DialoguePlugin {
    fn build(&self, app: &mut App) {
        app.add_systems(Startup, spawn_conversation)
            .add_systems(Update, advance_line);
    }
}

选项是台词上的数据,当所需标志缺失时隐藏该选项:

#[derive(Clone)]
struct ChoiceDef {
    label: &'static str,
    next: usize,
    requires_flag: Option<&'static str>,
}

#[derive(Resource)]
struct ChoiceList {
    choices: Vec<ChoiceDef>,
}

#[derive(Resource, Default)]
struct StoryFlags {
    names: Vec<&'static str>,
}

#[derive(Component)]
struct LineMark {
    index: usize,
}

fn shown_choices(flags: &StoryFlags, list: &ChoiceList) -> Vec<usize> {
    list.choices
        .iter()
        .enumerate()
        .filter_map(|(index, choice)| match choice.requires_flag {
            Some(flag) if !flags.names.iter().any(|name| *name == flag) => None,
            _ => Some(index),
        })
        .collect()
}

fn choose_first(
    keys: Res<ButtonInput<KeyCode>>,
    flags: Res<StoryFlags>,
    list: Res<ChoiceList>,
    mut marks: Query<&mut LineMark>,
) {
    if !keys.just_pressed(KeyCode::Digit1) {
        return;
    }
    let Some(choice_index) = shown_choices(&flags, &list).first().copied() else {
        return;
    };
    let next = list.choices[choice_index].next;
    for mut mark in &mut marks {
        mark.index = next;
    }
}

fn open_choice(mut commands: Commands) {
    commands.spawn(LineMark { index: 0 });
}

pub struct ChoicePlugin;

impl Plugin for ChoicePlugin {
    fn build(&self, app: &mut App) {
        app.insert_resource(StoryFlags {
            names: vec!["has_key"],
        })
        .insert_resource(ChoiceList {
            choices: vec![
                ChoiceDef {
                    label: "Open the gate",
                    next: 2,
                    requires_flag: Some("has_key"),
                },
                ChoiceDef {
                    label: "Leave",
                    next: 3,
                    requires_flag: None,
                },
            ],
        })
        .add_systems(Startup, open_choice)
        .add_systems(Update, choose_first);
    }
}

状态归属与决策

状态归属规则:

  • 单个实体上的数据由 Component 持有,一个系统通过 Query 修改,运行在 Update 或 FixedMain。
  • 整个应用共享的一个值由 Resource 持有,一个系统修改;Startup 插入,之后由读取它的调度运行。
  • 生成由 Commands 负责,在 Startup 生成初始世界,运行时生成在后续调度。
  • 不能竞态的先后顺序由 .chain() 保证,仅链中的系统参与。
  • 插件边界由 Plugin 的 build 注册系统与资源,在应用运行前完成。

借用规则:两个系统都可变查询同一组件时,必须用 .chain() 排序,或拆分使只有一个写入。无关系统保持并行。

决策表:

  • 需要逐实体数据:用 Component + Query,不要用 Godot 节点脚本。
  • 需要应用级配置或时钟:用 Resource,不要复制到每个实体。
  • 需要稳定的模拟步长:用 FixedMain 和 Fixed 时钟,不要把模拟绑到原始帧 Update。
  • 需要启动生成:在 Startup 中用 Commands,不要从渲染系统生成。
  • 需要非共享状态的跨系统通知:使用 bevy-events-messaging 中的消息或观察者槽位,不要在本文件发明新事件类型。
  • 需要本技能之外的 API:加载拥有它的技能,不要编造 crate 或 API。

约束(NEVER)

  • 不要在文档 URL 中固定 /0.20.0/。原因:链接保持在 latest;0.20 目标在正文中只陈述一次。
  • 不要从两个无序系统可变查询同一组件。原因:调度会并行运行系统,除非用 .chain() 排序。
  • 不要把台词表复制到每个说话者上。原因:表是一个资源;台词索引是每个对话的组件。
  • 不要在这里发明物理、导航、网络或 XR crate。原因:本技能只命名有文档的 Bevy crate 和模块。
  • 不要在此机制中使用 Godot 节点、资源或信号类型。原因:Bevy 代码保持惯用 ECS,只使用有文档的 Bevy API。
  • 不要在 Bevy 代码中使用 Godot 类型。原因:Bevy 代码保持惯用 ECS,只使用有文档的 Bevy API。
  • 不要发明 API 或未命名的第三方 crate 作为所选求解器。原因:Bevy 代码保持惯用 ECS,只使用有文档的 Bevy API。

适用场景与限制

适用场景:Bevy 0.20 及以上游戏项目中需要管理对话台词、选项分支、说话者 ID 和故事标志的推进逻辑。

限制:

  • 目标版本为 Bevy 0.20+。
  • 富文本渲染属于 bevy-ui-text,本技能不负责。
  • 消息和观察者的 API 参见 bevy-events-messaging,本文件不新增事件类型。
  • 官方文档页面保持在无版本站点上。