用途
该技能用于在 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,本文件不新增事件类型。
- 官方文档页面保持在无版本站点上。