捐赠 爱心图标 GitHub 仓库

创建示例

大多数 Bevy 中的示例 旨在清楚地展示单个功能、一组紧密相关的较小功能，或展示如何完成特定任务（例如资产加载、创建自定义着色器或测试您的应用程序）。在极少数情况下，创建新的“游戏”示例是合理的，以便演示新的功能，这些功能以一种难以孤立地展示或需要额外集成测试的方式打开一类复杂的功能。

Bevy 中的示例应该：

  1. 工作： 它们必须编译并运行，并且其中任何故意引入的错误都应该是明显的（通过测试、简单结果或清晰显示的行为）。
  2. 清晰： 它们必须使用描述性的变量名、进行格式化并适当地添加注释。尽力展示最佳实践，但不要掩盖示例的重点。
  3. 相关： 它们应该通过注释或变量名解释它们的作用以及这对游戏开发者如何有用。
  4. 最小化： 它们的大小和复杂程度不应超过满足示例目标所需的程度。

当您添加新的示例时，请确保更新 examples/README.md 中的新的示例，并将该示例添加到根 Cargo.toml 文件中。运行 cargo run -p build-templated-pages -- build-example-page 以自动执行此操作。在描述中使用大量的关键词：这些关键词通常用于搜索特定示例。请查看 示例样式指南，以帮助确保您的示例样式与我们现有的样式一致。

更复杂的演示功能也受到欢迎，但这些功能应该提交到 bevy-assets。

样式指南

创建或更新示例时，请遵守以下指南。

组织

  1. 示例应该位于 /examples 的适当子文件夹中。
  2. 如果可能，示例应该是一个单独的文件。
  3. 资产位于 /assets 中。尽量避免添加新的资产，除非严格必要，以保持存储库的大小。不要添加“大型”资产文件。
  4. 每个示例都应尝试遵循以下顺序：
    1. 导入
    2. 一个 fn main() 块
    3. 示例逻辑
  5. 尝试以与实际代码相同的格式构建应用程序/插件。
  6. 示例通常不应该进行测试，因为这些测试不能直接被 Bevy 用户重用。

风格偏好

  1. 使用简单、描述性的变量名。
    1. 避免使用 MyComponent 之类的名称，而应使用更具描述性的术语，例如 Events。
    2. 优先使用单字母区分符（例如 EventsA 和 EventsB），而不是无意义的词语（例如 EventsFoo 和 EventsBar）。
    3. 尽可能避免在变量名中重复变量的类型。例如，Color 应该优先于 ColorComponent。
  2. 优先使用 bevy::prelude::* 和 bevy::sub_crate::* 的全局导入，而不是使用粒度导入（为了简洁起见）。
  3. 使用一致的注释样式
    1. /// 文档注释应该位于 #[derive(Trait)] 调用之上。
    2. // 注释通常应该位于要注释的代码行之上，而不是放在代码行内。
    3. 避免使用 /* */ 块注释，即使在编写长注释时也是如此。
    4. 在注释中使用 `variable_name` 代码块来表示您正在引用特定的类型和变量。
    5. 注释以大写字母开头；如果注释是句子结构，则以句点结尾。
  4. 使用注释来组织无法合理地重构为单独函数的较长、复杂的代码段。
  5. 避免使变量 pub，除非您的示例需要这样做。

代码约定

  1. 将可配置的值（“魔术数字”）重构为具有清晰名称的常量。
  2. 优先使用 for 循环而不是 .for_each。后者更快（目前），但对于初学者来说不太清楚、不太符合习惯用法，而且灵活性也更差。
  3. 在适当的地方使用 .single 和 .single_mut。
  4. 在查询中，优先使用 With<T> 过滤器，而不是使用 &T 实际获取未使用的數據。
  5. 当您在一个系统中需要多个查询时，优先使用 With 和 Without 的不相交查询，而不是参数集。
  6. 优先使用具有命名字段的结构，而不是元组结构，除非是单字段包装器类型。
  7. 对于应用程序/调度/等等的标签，优先使用枚举标签，而不是字符串标签。

视觉指南

示例可能会在 示例展示 中显示，一致的样式有助于保持示例整洁。

  1. 除非绝对必要，否则使用默认的 ClearColor 和 WindowResolution。
  2. "指令文本" 应该使用默认的字体、颜色和大小。它应该从窗口边缘内缩 12 像素。

"功能"示例

这些示例以清晰、最小的方式演示了特定引擎功能的使用。

  1. 重点在一个示例中演示一个功能。
  2. 尝试使您的名称与特定游戏的上下文分离，并将重点放在您正在演示的功能上。
  3. 在有选择的情况下，展示完成相同任务的良好替代方法，并解释为什么您可能更喜欢一种方法而不是另一种方法。
  4. 示例在运行时应该具有可见的效果，无论是命令行还是图形窗口。

"游戏"示例

这些示例展示了如何以一种连贯的方式在 Bevy 中构建简单的游戏。

  1. 每个示例都位于 /examples/games 文件夹中。
  2. 目标是达到最小但可行的状态：游戏应该可以玩，并且没有明显的错误，但不需要进行完善、添加功能或过分有趣。
  3. 重点关注代码质量并为用户展示良好、可扩展的模式。
    1. 充分利用枚举和状态来组织您的游戏逻辑。
    2. 尽可能保持组件大小，但不能更小：组件上的所有数据通常应该一次访问。
    3. 保持系统大小：它们应该有明确的单一目的。
    4. 尽可能避免跨类似实体重复逻辑，通过共享系统和组件来实现这一点。
  4. 使用 /// 文档注释来解释每个函数/结构的作用，就好像示例是完善的生产代码库的一部分一样。
  5. 将您的代码安排在同一个文件中的模块中，以允许简单的代码折叠/组织。
改善此页面