pub trait Plugin: Downcast + Any + Send + Sync {
// Required method
fn build(&self, app: &mut App);
// Provided methods
fn ready(&self, _app: &App) -> bool { ... }
fn finish(&self, _app: &mut App) { ... }
fn cleanup(&self, _app: &mut App) { ... }
fn name(&self) -> &str { ... }
fn is_unique(&self) -> bool { ... }
}Expand description
A collection of Bevy app logic and configuration.
Plugins configure an App. When an App registers a plugin,
the plugin’s Plugin::build function is run. By default, a plugin
can only be added once to an App.
If the plugin may need to be added twice or more, the function is_unique()
should be overridden to return false. Plugins are considered duplicate if they have the same
name(). The default name() implementation returns the type name, which means
generic plugins with different type parameters will not be considered duplicates.
Lifecycle of a plugin
When adding a plugin to an App:
- the app calls
Plugin::buildimmediately, and register the plugin - once the app started, it will wait for all registered
Plugin::readyto returntrue - it will then call all registered
Plugin::finish - and call all registered
Plugin::cleanup
Defining a plugin.
Most plugins are simply functions that add configuration to an App.
App::new().add_plugins(my_plugin).run();
// This function implements `Plugin`, along with every other `fn(&mut App)`.
pub fn my_plugin(app: &mut App) {
app.add_systems(Update, hello_world);
}For more advanced use cases, the Plugin trait can be implemented manually for a type.
pub struct AccessibilityPlugin {
pub flicker_damping: bool,
// ...
}
impl Plugin for AccessibilityPlugin {
fn build(&self, app: &mut App) {
if self.flicker_damping {
app.add_systems(PostUpdate, damp_flickering);
}
}
}Required Methods§
Provided Methods§
sourcefn ready(&self, _app: &App) -> bool
fn ready(&self, _app: &App) -> bool
Has the plugin finished its setup? This can be useful for plugins that need something
asynchronous to happen before they can finish their setup, like the initialization of a renderer.
Once the plugin is ready, finish should be called.
sourcefn finish(&self, _app: &mut App)
fn finish(&self, _app: &mut App)
Finish adding this plugin to the App, once all plugins registered are ready. This can
be useful for plugins that depends on another plugin asynchronous setup, like the renderer.
sourcefn cleanup(&self, _app: &mut App)
fn cleanup(&self, _app: &mut App)
Runs after all plugins are built and finished, but before the app schedule is executed. This can be useful if you have some resource that other plugins need during their build step, but after build you want to remove it and send it to another thread.
Implementations§
source§impl dyn Plugin
impl dyn Plugin
sourcepub fn is<__T>(&self) -> boolwhere
__T: Plugin,
pub fn is<__T>(&self) -> boolwhere
__T: Plugin,
Returns true if the trait object wraps an object of type __T.
sourcepub fn downcast<__T>(self: Box<dyn Plugin>) -> Result<Box<__T>, Box<dyn Plugin>>where
__T: Plugin,
pub fn downcast<__T>(self: Box<dyn Plugin>) -> Result<Box<__T>, Box<dyn Plugin>>where
__T: Plugin,
Returns a boxed object from a boxed trait object if the underlying object is of type
__T. Returns the original boxed trait if it isn’t.
sourcepub fn downcast_rc<__T>(self: Rc<dyn Plugin>) -> Result<Rc<__T>, Rc<dyn Plugin>>where
__T: Plugin,
pub fn downcast_rc<__T>(self: Rc<dyn Plugin>) -> Result<Rc<__T>, Rc<dyn Plugin>>where
__T: Plugin,
Returns an Rc-ed object from an Rc-ed trait object if the underlying object is of
type __T. Returns the original Rc-ed trait if it isn’t.
sourcepub fn downcast_ref<__T>(&self) -> Option<&__T>where
__T: Plugin,
pub fn downcast_ref<__T>(&self) -> Option<&__T>where
__T: Plugin,
Returns a reference to the object within the trait object if it is of type __T, or
None if it isn’t.
sourcepub fn downcast_mut<__T>(&mut self) -> Option<&mut __T>where
__T: Plugin,
pub fn downcast_mut<__T>(&mut self) -> Option<&mut __T>where
__T: Plugin,
Returns a mutable reference to the object within the trait object if it is of type
__T, or None if it isn’t.