fennel_plugins/lib.rs
1//! # Plugins
2//! This crate provides a simple trait for creating plugins within the Fennel engine.
3//! Plugins allow to extend the capabilities of the engine, and also are an essential piece of it,
4//! as plugins are the backbone for most of the engine's features.
5//!
6//! An example is the `fennel_core::plugin::GraphicsPlugin` plugin, which provides the most important
7//! part of the engine, the graphics.
8
9use std::collections::HashMap;
10use specs::prelude::{Resource, ResourceId};
11use specs::shred::cell::AtomicRefCell;
12
13/// A trait that all plugins must implement in order to be inserted into `App`
14///
15/// # Example
16/// ```
17/// use specs::World;
18/// use fennel_plugins::Plugin;
19/// struct MyCoolPlugin;
20///
21/// impl Plugin for MyCoolPlugin {
22/// fn prepare(&mut self, _world: *mut World) -> anyhow::Result<()> {
23/// // initialize your plugin here
24/// Ok(())
25/// }
26///
27/// fn update(&mut self, delta_time: f64) -> anyhow::Result<()> {
28/// // update your plugin state
29/// Ok(())
30/// }
31///
32/// fn name(&self) -> &'static str {
33/// "my_cool_plugin"
34/// }
35/// }
36/// ```
37pub trait Plugin {
38 /// Prepare/initialize the plugin, return a result of this
39 fn prepare(&mut self, dependencies: HashMap<String, &AtomicRefCell<Box<dyn Resource>>>) -> anyhow::Result<()>;
40 /// Update the plugin state, return a result of this
41 fn update(&mut self, delta_time: f64) -> anyhow::Result<()>;
42 /// Return a list of your resource dependencies here or an empty [`Vec`] if you don't need any resources.
43 /// Use the [`ResourceId::new`] function to acquire a [`ResourceId`] instance.
44 ///
45 /// Usually you want the dependency to be an [`Arc`], [`Rc`] or some sort of channel receiver/sender,
46 /// as under the hood `fennel_engine` clones the resource.
47 fn resource_dependencies(&mut self) -> HashMap<String, ResourceId>;
48 /// Return the plugin's name; must be unique and not change
49 fn name(&self) -> &'static str;
50}