Mirrors/bevy
2
0
Fork 0
mirror of https://github.com/bevyengine/bevy synced 2024-11-10 07:04:33 +00:00
Code Issues Projects Releases Packages Wiki Activity

Plugin guidelines (#1250)

Browse source 
* add plugin guidelines
* refactor features list
This commit is contained in:
François 2021-02-01 05:19:10 +01:00 committed by GitHub
parent 81809c71ce
commit cf5f3b5008
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 145 additions and 77 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
README.md
View file

@ -87,6 +87,12 @@ This [list][cargo_features] outlines the different cargo features supported by B
[cargo_features]: docs/cargo_features.md
## [Third Party Plugins][plugin_guidelines]
Plugins are very welcome to extend Bevy's features. [Guidelines][plugin_guidelines] are available to help integration and usage.
[plugin_guidelines]: docs/plugins_guidelines.md
## Thanks and Alternatives
Additionally, we would like to thank the [Amethyst](https://github.com/amethyst/amethyst), [macroquad](https://github.com/not-fl3/macroquad), [coffee](https://github.com/hecrj/coffee), [ggez](https://github.com/ggez/ggez), [rg3d](https://github.com/mrDIMAS/rg3d), and [Piston](https://github.com/PistonDevelopers/piston) projects for providing solid examples of game engine development in Rust. If you are looking for a Rust game engine, it is worth considering all of your options. Each engine has different design goals, and some will likely resonate with you more than others.

98
docs/cargo_features.md
View file

@ -2,81 +2,29 @@
## Default Features
### bevy_audio
Audio support. Support for all audio formats depends on this.
### bevy_gilrs
Adds gamepad support.
### bevy_gltf
[glTF](https://www.khronos.org/gltf/) support.
### bevy_winit
GUI support.
### bevy_wgpu
Make use of GPU via [WebGPU](https://gpuweb.github.io/gpuweb/) support.
### render
The render pipeline and all render related plugins.
### bevy_dynamic_plugins
Plugins for dynamic loading (libloading)
### png
PNG picture format support.
### hdr
[HDR](https://en.wikipedia.org/wiki/High_dynamic_range) support.
### mp3
MP3 audio format support.
### x11
Make GUI applications use X11 protocol. You could enable wayland feature to override this.
|feature name|description|
|-|-|
|bevy_audio|Audio support. Support for all audio formats depends on this.|
|bevy_dynamic_plugins|Plugins for dynamic loading (libloading)|
|bevy_gilrs|Adds gamepad support.|
|bevy_gltf|[glTF](https://www.khronos.org/gltf/) support.|
|bevy_winit|GUI support.|
|bevy_wgpu|Make use of GPU via [WebGPU](https://gpuweb.github.io/gpuweb/) support.|
|render|The render pipeline and all render related plugins.|
|png|PNG picture format support.|
|hdr|[HDR](https://en.wikipedia.org/wiki/High_dynamic_range) support.|
|mp3|MP3 audio format support.|
|x11|Make GUI applications use X11 protocol. You could enable wayland feature to override this.|
## Optional Features
### trace
Enables system tracing (useful in tandem wit a feature like trace_chrome)
### trace_chrome
Enables [tracing-chrome](https://github.com/thoren-d/tracing-chrome) as bevy_log output. This allows you to visualize system execution.
### wgpu_trace
For tracing wgpu.
### flac
FLAC audio format support. It's included in bevy_audio feature.
### wav
WAV audio format support.
### vorbis
Vorbis audio format support.
### wayland
Enable this to use Wayland display server protocol other than X11.
### subpixel_glyph_atlas
Enable this to cache glyphs using subpixel accuracy. This increases texture
memory usage as each position requires a separate sprite in the glyph atlas, but
provide more accurate character spacing.
|feature name|description|
|-|-|
|trace|Enables system tracing (useful in tandem wit a feature like trace_chrome)|
|trace_chrome|Enables [tracing-chrome](https://github.com/thoren-d/tracing-chrome) as bevy_log output. This allows you to visualize system execution.|
|wgpu_trace|For tracing wgpu.|
|flac|FLAC audio format support. It's included in bevy_audio feature.|
|wav|WAV audio format support.|
|vorbis|Vorbis audio format support.|
|wayland|Enable this to use Wayland display server protocol other than X11.|
|subpixel_glyph_atlas|Enable this to cache glyphs using subpixel accuracy. This increases texture memory usage as each position requires a separate sprite in the glyph atlas, but provide more accurate character spacing.|

114
docs/plugins_guidelines.md Normal file
View file

@ -0,0 +1,114 @@
# Third Party Plugin Guidelines
Bevy has a plug and play architecture, where you can easily add plugins for new features, or replace built-in plugins with your own.
This document targets plugin authors.
## Checklist
* [ ] [Pick a reasonable, descriptive name](#naming)
* [ ] [Bevy/plugin version support table](#bevy-version-supported)
* [ ] [Turn off default Bevy features](#bevy-features)
* [ ] [Choose a Bevy git/master tracking badge](#master-branch-tracking)
* [ ] [Pick a license](#licensing)
* [ ] [Remove unnecessary or redundant dependencies](#small-crate-size)
* [ ] [Add cargo tests and CI](#tests-and-ci)
* [ ] [Documentation and examples](#documentation-and-examples)
* [ ] [Publish your plugin](#publishing-your-plugin)
* [ ] [Promote your plugin](#promotion)
## Naming
You are free to use a `bevy_xxx` name for your plugin, with the caveat "please be reasonable". If you are about to claim a generic name like `bevy_animation`, `bevy_color`, or `bevy_editor`... please ask first. The rational is explained [here](https://github.com/bevyengine/bevy/discussions/1202#discussioncomment-258907).
## Promotion
You can promote your plugin in Bevy's [communities](https://github.com/bevyengine/bevy#community):
* Add it to [Awesome Bevy](https://github.com/bevyengine/awesome-bevy)
* Announce it on [Discord](https://discord.gg/gMUk5Ph), in channel `#showcase`
* Announce it on [Reddit](https://reddit.com/r/bevy)
## Bevy Version Supported
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.4|0.3|
|0.3|0.1|
## Bevy Features
You should disable Bevy features that you don't use. This is because with Cargo, features are additive. Features that are enabled for Bevy in your plugin can't be disabled by someone using your plugin. You can find the list of features [here](cargo_features.md).
```
bevy = { version = "0.4", default-features = false, features = ["..."] }
```
## Master Branch Tracking
If you intend to track Bevy's master branch, you can specify the latest commit you support in your cargo.toml file:
```
bevy = { version = "0.4", git = "https://github.com/bevyengine/bevy", rev="509b138e8fa3ea250393de40c33cc857c72134d3", 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 using the dependency from [crates.io](https://crates.io), the git dependency will be used otherwise.
Bevy is evolving very fast. You can use one of these badges to communicate to your users how closely you intend to track Bevy's master branch.
|<div style="width:100px">badge</div>|<div style="width:200px">description</div>|code|
|-|-|-|
|[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-master-lightblue)](https://github.com/bevyengine/bevy/blob/master/docs/plugins_guidelines.md#master-branch-tracking)|I intend to track master as much as I can|`[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-master-lightblue)](https://github.com/bevyengine/bevy/blob/master/docs/plugins_guidelines.md#master-branch-tracking)`|
|[![Bevy tracking](https://img.shields.io/badge/Bevy%20tracking-released%20version-lightblue)](https://github.com/bevyengine/bevy/blob/master/docs/plugins_guidelines.md#master-released%20version-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/master/docs/plugins_guidelines.md#master-released%20version-tracking)`|
## General Advices for a Rust Crate
This advice is valid for any Rust crate.
### Licensing
Rust projects are often dual licensed with [MIT and Apache 2.0](https://www.rust-lang.org/policies/licenses). Bevy is licensed with [MIT](https://github.com/bevyengine/bevy/blob/master/LICENSE). Those are great options to license your plugin.
### Small Crate Size
To avoid long build times in your crate and in projects using your plugin, you should aim for a small crate size:
* Disable Bevy features that you don't use
* Avoid large dependencies
* Put optional functionality and dependencies behind a feature
### Documentation and Examples
Documentation and examples are very useful for a crate.
In the case of a plugin for Bevy, a few screenshots or movies/animated GIFs from your examples can really help understanding what your plugin can do.
Additionally, it can be helpful to list:
* Stages added by the plugin
* Systems used
* New components available
### Tests and CI
Tests are always good! For CI, you can check [this example](https://github.com/actions-rs/meta/blob/master/recipes/quickstart.md) for a quickstart 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/cf0e9f9968bb1bceb92a61cd773478675d35cbd6/.github/workflows/ci.yml#L39). 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.
### 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 file 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)`|

4
examples/README.md
View file

@ -10,11 +10,11 @@ cargo run --features wayland --example hello_world
### ⚠️ Note: for users of releases on crates.io,
Due to changes and additions to APIs, there are often differences between the development examples and the released versions of Bevy on crates.io.
If you are using a release version from [crates.io](https://crates.io/crates/bevy), view the examples by checking out the appropriate git tag, e.g., users of `0.3` should use the examples on [https://github.com/bevyengine/bevy/tree/v0.3.0/examples](https://github.com/bevyengine/bevy/tree/v0.3.0/examples)
If you are using a release version from [crates.io](https://crates.io/crates/bevy), view the examples by checking out the appropriate git tag, e.g., users of `0.4` should use the examples on [https://github.com/bevyengine/bevy/tree/v0.4.0/examples](https://github.com/bevyengine/bevy/tree/v0.4.0/examples)
If you have cloned bevy's repo locally, `git checkout` with the appropriate version tag.
```
git checkout v0.3.0
git checkout v0.4.0
```
---