快速入门
捐赠 爱心图标 GitHub 仓库

构建 Bevy 生态系统

Bevy 采用即插即用架构，您可以轻松添加插件以实现新功能，或使用自己的插件代替内置插件。您还可以创建第三方插件供其他人在其应用程序中使用。

有鉴于此，本页提供了一些在编写第三方插件时可能会有用的基本信息。

命名

您可以自由地为您的插件使用 `bevy_xxx` 名称，但请保持合理。如果您打算使用像 `bevy_animation`、`bevy_color` 或 `bevy_editor` 这样的通用名称，请先咨询。其原因在 这里 解释。

许可

Bevy 采用 MIT 或 Apache 2.0 双重许可，您可以选择其中一个。大多数其他 Rust 项目（包括 Rust 本身）也使用这种双重许可方法。仅 MIT 许可非常流行，您可能很想只使用它（Bevy 以前也只有 MIT 许可），但有 充分理由 包含这两种许可。我们强烈建议您为 Bevy 插件和箱子使用双重 MIT / Apache 2.0 许可。

  • 包含 Apache 2.0 许可选项可显著降低在已发布游戏中进行适当许可合规性的难度和样板代码，因为您只需要包含一份 Apache 2.0 许可即可。
  • 提供与 Bevy 和 Rust 的最大兼容性，使您更容易将更改上游。

Rust API 和 Cargo SemVer 指南

虽然它们只是指南，但查看和考虑 Rust API 指南 和 Cargo SemVer 兼容性约定 对于如何编写 API 以及将哪些更改视为破坏性更改或兼容性更改的建议非常有用。

通用插件类型

允许用户为插件提供通用类型可能很有用。这可以使他们能够为要使用的组件编写自定义逻辑；为插件提供一个标记组件以记录它应该对哪个实体执行一些逻辑；添加插件应该监听的事件；或者插件应该使用的资源（如果要通过类型别名将插件应用于同一类型的多个资源，这很有用）。

您可以像这样定义一个通用插件

// Example plugin with a generic type
pub struct YourPlugin<T> {
    pub phantom_t: PhantomData<T>,
}

// Implementation of YourPlugin as a Plugin with
// a generic type parameter of the `Component` trait.
impl<T: Component> Plugin for YourPlugin<T> {
    fn build(&self, app: &mut App) {
        app.add_systems(Startup, example_system::<T>);
    }

    // …your other logic here…
}

impl<T> YourPlugin<T> {
    pub fn new() -> Self {
        Self::default()
    }

    // …your other logic here…
}

impl<T> Default for YourPlugin<T> {
    fn default() -> Self {
        Self {
            phantom_t: PhantomData,
        }
    }
}

// Example component.
#[derive(Component)]
pub struct Something;

// Example system using the generic type parameter
// of `Component` trait.
pub fn example_system<T: Component>(query: Query<&T>) {
    for _example_component in &query {
        // …do something…
    }
}

一个使用通用插件的典型例子是 Bevy 细胞自动机插件。

小包大小

为了避免插件及其使用插件的项目出现长时间的构建时间，您应该尽量保持较小的包大小。

  • 仅包含您绝对需要的 Bevy 功能。

    功能是累加的——在插件中启用的 Bevy 功能不能被使用插件的人禁用。

    您应该在 `Cargo.toml` 文件中添加 `default-features = false` 到 Bevy 依赖项，并手动指定您需要的功能。

    您可以在 这里 找到 Bevy 功能的列表。

  • 避免引入新的大型依赖项。

  • 使用 `cargo tree` 或 `cargo-deny` 确保依赖项没有重复。

  • 将可选功能和依赖项放在 cargo 功能 后面。

测试和 CI

测试永远是好事！对于 CI，您可以查看 这个示例 以了解使用 GitHub Actions 的快速入门。由于 Bevy 有额外的 Linux 依赖项，您应该在构建项目之前安装它们（Bevy 的做法就是这样）。即使您没有很多（或根本没有）测试，设置 CI 也会编译检查您的插件，并确保基本质量水平。

指示兼容版本

指示您的插件的哪个版本与哪个版本的 Bevy 兼容，这对于您的用户来说可能会有所帮助。一些用户可能出于各种原因使用旧版本的 Bevy。您可以帮助他们找到应该使用的插件版本。这可以在您的 README 中以简单的表格形式显示，其中包含每个版本的 Bevy 及其对应的兼容插件版本。

| bevy  | bevy_awesome_plugin |
|-------|---------------------|
| 0.13  | 0.3                 |
| 0.12  | 0.1                 |

主分支跟踪

Bevy 发展得很快。主分支上经常出现新功能，但尚未发布。您的插件可能依赖于 Bevy 主分支或最新版本。您也可以在不同的分支上进行这两种操作（例如，有一个 `bevy_main` 分支）。

如果您打算跟踪 Bevy 的主分支，您可以在 `Cargo.toml` 文件中指定您支持的最新提交。

bevy = { version = "0.5", git = "https://github.com/bevyengine/bevy", rev = "9788b386c7846c99978ab5c1a33698ec5a471d84", default-features = false }

您可以 将依赖项指定为版本和 Git。如果依赖项是从 crates.io 拉取的，将使用版本。否则，将使用 Git 依赖项。

您可以使用以下徽章之一来告诉用户您打算跟踪 Bevy 的主分支的程度。

Following released Bevy versions

[![Following released Bevy versions](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://bevy.rust-lang.net.cn/learn/quick-start/plugin-development/#main-branch-tracking)

Following Bevy's main branch

[![Following Bevy's main branch](https://img.shields.io/badge/Bevy%20tracking-main-lightblue)](https://bevy.rust-lang.net.cn/learn/quick-start/plugin-development/#main-branch-tracking)

文档和示例

文档和示例对于箱子非常有用。

在 Bevy 插件的情况下，来自示例的几个屏幕截图或电影/动画 GIF 可以真正帮助理解插件的功能。

此外，列出以下内容可能会有所帮助：

  • 插件提供的 SystemSets，以及它们的执行顺序（如果很重要）。
  • 插件提供的组件。

发布您的插件

您可以在 `[package]` 部分的 `Cargo.toml` 清单文件中添加一些 额外的字段

一旦箱子发布到 crates.io，您就可以在 `README.md` 中添加两个徽章以方便链接

crates.io

[![crates.io](https://img.shields.io/crates/v/bevy_awesome_plugin)](https://crates.io/crates/bevy_awesome_plugin)

docs.rs

[![docs.rs](https://docs.rs/bevy_awesome_plugin/badge.svg)](https://docs.rs/bevy_awesome_plugin)

推广

您可以在 Bevy 的 社区 中推广您的插件。

改善此页面