-
Notifications
You must be signed in to change notification settings - Fork 330
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add plugin development chapter to book #848
Merged
alice-i-cecile
merged 10 commits into
bevyengine:main
from
TrialDragon:298_add_plugin_development_chapter
Jan 7, 2024
Merged
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
7e88234
Migrate third party plugin guidelines
TrialDragon 262e5e3
Re-order plugin development contents
TrialDragon 71ffd34
Add Rust API and Cargo SemVer Guidelines
TrialDragon e9557f8
Add generic plugin types to plugin dev chapter
TrialDragon 0a70de9
Update plugin development chapter summary
TrialDragon d3463c8
Update wording of generic plugin types
TrialDragon ea80335
Update content/learn/book/plugin-development/_index.md
TrialDragon 401cfbc
Update content/learn/book/plugin-development/_index.md
TrialDragon dd6cee1
Fix grammar in plugin development chapter
TrialDragon 232a339
Fix grammar round two
TrialDragon File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,140 @@ | ||
+++ | ||
title = "Building Bevy's Ecosystem" | ||
weight = 3 | ||
sort_by = "weight" | ||
template = "docs-section.html" | ||
page_template = "docs-section.html" | ||
+++ | ||
|
||
Bevy has a plug-and-play architecture, where you can easily add plugins for new features or use your own plugins instead of the built-in ones. You can also create third-party plugins that others may use in their applications. | ||
|
||
With that in mind, this page provides some basic info that can be useful when authoring third-party plugins. | ||
|
||
## Naming | ||
|
||
You are free to use a `bevy_xxx` name for your plugin, but please be reasonable. If you are about to claim a generic name like `bevy_animation`, `bevy_color`, or `bevy_editor`, please ask first. The rationale is explained [here](https://github.com/bevyengine/bevy/discussions/1202#discussioncomment-258907) | ||
|
||
## Licensing | ||
|
||
Bevy is dual licensed under [MIT or Apache 2.0](https://www.rust-lang.org/policies/licenses), at your option. Most other Rust projects (including Rust itself) also use this dual-license approach. MIT-only is very popular, and you might be tempted to just use that (Bevy also used to be MIT-only), but there are [very good reasons](https://github.com/bevyengine/bevy/issues/2373) to include both licenses. We highly recommend using the dual MIT / Apache 2.0 license for your Bevy Plugins and crates: | ||
|
||
- Including the Apache 2.0 license option significantly reduces the difficulty and boilerplate of proper license compliance in published games because you only need to include one copy of the Apache 2.0 license. | ||
- Provides maximum compatibility with Bevy and Rust, making it easier to upstream your changes. | ||
|
||
## Rust API and Cargo SemVer Guidelines | ||
|
||
While they are only guidelines, it can be useful for you to look at and consider the [Rust API guidelines](https://rust-lang.github.io/api-guidelines/) and [Cargo SemVer compatibility conventions](https://doc.rust-lang.org/cargo/reference/semver.html) for recommendations on how to write your API and what to consider a breaking or compatible change. | ||
|
||
## Generic Plugin Types | ||
|
||
It can be useful to allow your users to supply generic types to your plugins. It can enable them to write custom logic for components to be used; give your plugin a marker component to note an entity it should do some logic to; add events that your plugin should listen for; or a resource your plugin should use (which is useful if you want to apply your plugin to multiple resources of the same type via type aliases.) | ||
|
||
You can define a generic plugin like so: | ||
|
||
```rust | ||
// example with a generic type that implements Component | ||
|
||
pub struct YourPlugin<T: Component> { | ||
pub phantom_t: PhantomData<T>, | ||
} | ||
|
||
impl<T: Component> Plugin for YourPlugin<T> { | ||
fn build(&self, app: &mut App) { | ||
app.add_systems(Startup, example_function::<T>); | ||
} | ||
|
||
// ... your other logic ... | ||
} | ||
|
||
// example function using your generics | ||
pub fn example_function<T: Component>(mut commands: Commands) { | ||
commands.spawn(T); | ||
// ... any other logic here ... | ||
} | ||
``` | ||
|
||
A prime example of generic plugins in use is the [Bevy Cellular Automaton Plugin](https://github.com/ManevilleF/bevy_life). | ||
|
||
## Small Crate Size | ||
|
||
To avoid long build times in your plugin and in projects using it, you should aim for a small crate size: | ||
|
||
- Disable Bevy features that you don't use: | ||
- Features are additive => Bevy features enabled in your plugin cannot be disabled by someone using your plugin | ||
- You can find Bevy's features [here](https://github.com/bevyengine/bevy/blob/main/docs/cargo_features.md). | ||
- Avoid large dependencies. | ||
- Put optional functionality and dependencies behind a feature. | ||
|
||
## Tests and CI | ||
|
||
Tests are always good! For CI, you can check out [this example](https://github.com/actions-rs/meta/blob/master/recipes/quickstart.md) for a quick start using GitHub Actions. As Bevy has additional Linux dependencies, you should install them before building your project ([here is how Bevy is doing it](https://github.com/bevyengine/bevy/blob/9788b386c7846c99978ab5c1a33698ec5a471d84/.github/workflows/ci.yml#L40)). Even if you don't have many (or any) tests, setting up CI will compile check your plugin and ensure a basic level of quality. | ||
|
||
## Indicate Compatible Versions | ||
|
||
Indicating which version of your plugin works with which version of Bevy can be helpful for your users. Some of your users may be using an older version of Bevy for any number of reasons. You can help them find which version of your plugin they should use. This can be shown as a simple table in your README with each version of Bevy and the corresponding compatible version of your plugin. | ||
|
||
| bevy | bevy_awesome_plugin | | ||
|------|---------------------| | ||
| 0.5 | 0.3 | | ||
| 0.4 | 0.1 | | ||
|
||
## Main Branch Tracking | ||
|
||
Bevy is evolving very fast. Regularly, new features are functioning on the main branch but have not yet been released. Your plugin might depend on Bevy Main or the latest release. You can also do both on different branches (e.g., have a `bevy_main` branch). | ||
|
||
If you intend to track Bevy's main branch, you can specify the latest commit you support in your `Cargo.toml` file: | ||
|
||
```toml | ||
bevy = { version = "0.5", git = "https://github.com/bevyengine/bevy", rev="9788b386c7846c99978ab5c1a33698ec5a471d84", default-features = false } | ||
``` | ||
|
||
You can specify the dependency [both as a version and with git](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#multiple-locations). The version will be used if the dependency is pulled from [crates.io](https://crates.io/). Otherwise, the git dependency will be used. | ||
|
||
You can use one of these badges to communicate to your users how closely you intend to track Bevy's main branch. | ||
|
||
<!-- MD033 - The Badges could be downsized, without the inline HTML due to the large code column --> | ||
<!-- markdownlint-disable-next-line MD033 --> | ||
|<div style="width:100px">badge</div>|<div style="width:200px">description</div>|code| | ||
|-|-|-| | ||
|[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-main-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)|I intend to track main as much as I can|`[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-main-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)`| | ||
|[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)|I will only follow released Bevy versions|`[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)`| | ||
|
||
## Documentation and Examples | ||
|
||
Documentation and examples are very useful for a crate. | ||
|
||
In the case of a Bevy plugin, a few screenshots or movies / animated GIFs from your examples can really help to understand what your plugin is capable of. | ||
|
||
Additionally, it can be helpful to list: | ||
|
||
- SystemSets available from your plugin. | ||
- (If important, also mention their execution order.) | ||
- Components available from your plugin. | ||
|
||
## Publishing Your Plugin | ||
|
||
There are some [extra fields](https://doc.rust-lang.org/cargo/reference/manifest.html) that you can add to your `Cargo.toml` manifest in the `[package]` section: | ||
|
||
|field|description| | ||
|-|-| | ||
|[`description`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field)|a description of the plugin| | ||
|[`repository`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-repository-field)|URL of the plugin source repository| | ||
|[`license`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields)|the plugin license| | ||
|[`keywords`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-keywords-field)|keywords for the plugin - `"bevy"` at least is a good idea here| | ||
|[`categories`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-categories-field)|categories of the plugin - see [the full list on crates.io](https://crates.io/categories)| | ||
|[`exclude`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields)|files to exclude from the released package - excluding the `assets` folder that you may have is a good idea, as well as any large files that are not needed by the plugin| | ||
|
||
Once a crate is published to [crates.io](https://crates.io), there are two badges that you can add to your `README.md` for easy links: | ||
|
||
|badge|code| | ||
|-|-| | ||
|[![crates.io](https://img.shields.io/crates/v/bevy)](https://crates.io/crates/bevy)|`[![crates.io](https://img.shields.io/crates/v/bevy_awesome_plugin)](https://crates.io/crates/bevy_awesome_plugin)`| | ||
|[![docs.rs](https://docs.rs/bevy/badge.svg)](https://docs.rs/bevy)|`[![docs.rs](https://docs.rs/bevy_awesome_plugin/badge.svg)](https://docs.rs/bevy_awesome_plugin)`| | ||
|
||
## Promotion | ||
|
||
You can promote your plugin in Bevy's [communities](https://github.com/bevyengine/bevy#community): | ||
|
||
- Add it as an [Asset on the official website](https://github.com/bevyengine/bevy-assets). | ||
- Announce it on [Discord](https://discord.gg/bevy), in the `#crates` channel. | ||
- Announce it on [Reddit](https://reddit.com/r/bevy). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this should explicitly mention the usage of
default-features = false
on the bevy dependency, as this could easily be forgotten.