Trait Plugin 

pub trait Plugin:
    PluginAsAny
    + Visit
    + Reflect {
    // Provided methods
    fn register(&self, context: PluginRegistrationContext<'_>) -> GameResult { ... }
    fn register_property_editors(
        &self,
        editors: Arc<PropertyEditorDefinitionContainer>,
    ) { ... }
    fn init(
        &mut self,
        scene_path: Option<&str>,
        context: PluginContext<'_, '_>,
    ) -> GameResult { ... }
    fn on_loaded(&mut self, context: PluginContext<'_, '_>) -> GameResult { ... }
    fn on_deinit(&mut self, context: PluginContext<'_, '_>) -> GameResult { ... }
    fn update(&mut self, context: &mut PluginContext<'_, '_>) -> GameResult { ... }
    fn post_update(&mut self, context: &mut PluginContext<'_, '_>) -> GameResult { ... }
    fn on_os_event(
        &mut self,
        event: &Event<()>,
        context: PluginContext<'_, '_>,
    ) -> GameResult { ... }
    fn on_graphics_context_initialized(
        &mut self,
        context: PluginContext<'_, '_>,
    ) -> GameResult { ... }
    fn before_rendering(&mut self, context: PluginContext<'_, '_>) -> GameResult { ... }
    fn on_graphics_context_destroyed(
        &mut self,
        context: PluginContext<'_, '_>,
    ) -> GameResult { ... }
    fn on_ui_message(
        &mut self,
        context: &mut PluginContext<'_, '_>,
        message: &UiMessage,
        ui_handle: Handle<UserInterface>,
    ) -> GameResult { ... }
    fn on_scene_begin_loading(
        &mut self,
        path: &Path,
        context: &mut PluginContext<'_, '_>,
    ) -> GameResult { ... }
    fn on_scene_loaded(
        &mut self,
        path: &Path,
        scene: Handle<Scene>,
        data: &[u8],
        context: &mut PluginContext<'_, '_>,
    ) -> GameResult { ... }
    fn on_scene_loading_failed(
        &mut self,
        path: &Path,
        error: &VisitError,
        context: &mut PluginContext<'_, '_>,
    ) -> GameResult { ... }
    fn on_game_error(
        &mut self,
        context: &mut PluginContext<'_, '_>,
        error: &GameError,
    ) -> bool { ... }
}

Plugin is a convenient interface that allow you to extend engine’s functionality.

Example

#[derive(Default, Visit, Reflect, Debug)]
#[reflect(non_cloneable)]
struct MyPlugin {}

impl Plugin for MyPlugin {
    fn on_deinit(&mut self, context: PluginContext) -> GameResult {
        // The method is called when the plugin is disabling.
        // The implementation is optional.
        Ok(())
    }

    fn update(&mut self, context: &mut PluginContext) -> GameResult {
        // The method is called on every frame, it is guaranteed to have fixed update rate.
        // The implementation is optional.
        Ok(())
    }

    fn on_os_event(&mut self, event: &Event<()>, context: PluginContext) -> GameResult {
        // The method is called when the main window receives an event from the OS.
        Ok(())
    }
}

Error Handling

Every plugin method returns GameResult (which is a simple wrapper over Result<(), GameError>), this helps to reduce the amount of boilerplate code related to error handling. There are a number of errors that can be automatically handled via ? operator. All supported error types listed in error::GameError enum.

The following code snippet shows the most common use cases for error handling:

#[derive(Default, Visit, Reflect, Debug)]
#[reflect(non_cloneable)]
struct MyPlugin {
    scene: Handle<Scene>,
    player: Handle<Node>,
}

impl Plugin for MyPlugin {
    fn update(&mut self, context: &mut PluginContext) -> GameResult {
        // 1. This is the old approach.
        match context.scenes.try_get(self.scene) {
            Ok(scene) => match scene.graph.try_get(self.player) {
                Ok(player) => {
                    println!("Player name is: {}", player.name());
                }
                Err(error) => {
                    err!("Unable to borrow the player. Reason: {error}")
                }
            },
            Err(error) => {
                err!("Unable to borrow the scene. Reason: {error}")
            }
        }

        // 2. This is the same code as above, but with shortcuts for easier error handling.
        // Message report is will be something like this:
        // `An error occurred during update plugin method call. Reason: <error message>`.
        let scene = context.scenes.try_get(self.scene)?;
        let player = scene.graph.try_get(self.player)?;
        println!("Player name is: {}", player.name());

        Ok(())
    }
}

Provided Methods

fn register(&self, context: PluginRegistrationContext<'_>) -> GameResult

The method is called when the plugin constructor was just registered in the engine. The main use of this method is to register scripts and custom scene graph nodes in SerializationContext.

fn register_property_editors( &self, editors: Arc<PropertyEditorDefinitionContainer>, )

This method is used to register property editors for your game types; to make them editable in the editor.

fn init( &mut self, scene_path: Option<&str>, context: PluginContext<'_, '_>, ) -> GameResult

This method is used to initialize your plugin.

fn on_loaded(&mut self, context: PluginContext<'_, '_>) -> GameResult

This method is called when your plugin was re-loaded from a dynamic library. It could be used to restore some runtime state, that cannot be serialized. This method is called only for dynamic plugins! It is guaranteed to be called after all plugins were constructed, so the cross-plugins interactions are possible.

fn on_deinit(&mut self, context: PluginContext<'_, '_>) -> GameResult

The method is called before plugin will be disabled. It should be used for clean up, or some additional actions.

fn update(&mut self, context: &mut PluginContext<'_, '_>) -> GameResult

Updates the plugin internals at fixed rate (see PluginContext::dt parameter for more info).

fn post_update(&mut self, context: &mut PluginContext<'_, '_>) -> GameResult

called after all Plugin and Script updates

fn on_os_event( &mut self, event: &Event<()>, context: PluginContext<'_, '_>, ) -> GameResult

The method is called when the main window receives an event from the OS. The main use of the method is to respond to some external events, for example an event from keyboard or gamepad. See Event docs for more info.

fn on_graphics_context_initialized( &mut self, context: PluginContext<'_, '_>, ) -> GameResult

The method is called when a graphics context was successfully created. It could be useful to catch the moment when it was just created and do something in response.

fn before_rendering(&mut self, context: PluginContext<'_, '_>) -> GameResult

The method is called before the actual frame rendering. It could be useful to render off-screen data (render something to texture, that can be used later in the main frame).

fn on_graphics_context_destroyed( &mut self, context: PluginContext<'_, '_>, ) -> GameResult

The method is called when the current graphics context was destroyed.

fn on_ui_message( &mut self, context: &mut PluginContext<'_, '_>, message: &UiMessage, ui_handle: Handle<UserInterface>, ) -> GameResult

The method will be called when there is any message from a user interface (UI) instance of the engine. Use ui_handle parameter to find out from which UI the message has come from.

fn on_scene_begin_loading( &mut self, path: &Path, context: &mut PluginContext<'_, '_>, ) -> GameResult

This method is called when the engine starts loading a scene from the given path. It could be used to “catch” the moment when the scene is about to be loaded; to show a progress bar for example. See AsyncSceneLoader docs for usage example.

fn on_scene_loaded( &mut self, path: &Path, scene: Handle<Scene>, data: &[u8], context: &mut PluginContext<'_, '_>, ) -> GameResult

This method is called when the engine finishes loading a scene from the given path. Use this method if you need do something with a newly loaded scene. See AsyncSceneLoader docs for usage example.

fn on_scene_loading_failed( &mut self, path: &Path, error: &VisitError, context: &mut PluginContext<'_, '_>, ) -> GameResult

This method is called when the engine finishes loading a scene from the given path with some error. This method could be used to report any issues to a user.

fn on_game_error( &mut self, context: &mut PluginContext<'_, '_>, error: &GameError, ) -> bool

This method is called when a game error has occurred, allowing you to perform some specific action to react to it (for example - to show an error message UI in your game).

Important notes

This method is called at the end of the current frame, and before that, the engine collects all the errors into a queue and then processes them one by one. This means that this method won’t be called immediately when an error was returned by any of your plugin or script methods, but instead the processing will be delayed to the end of the frame.

The error passed by a reference here instead of by-value, because there could be multiple plugins that can handle the error. This might seem counterintuitive, but remember that GameError can occur during script execution, which is not a part of a plugin and its methods executed separately, outside the plugin routines.

Error handling

This method should return true if the error was handled and no logging is needed, otherwise it should return false and in this case, the error will be logged by the engine. When true is returned by the plugin, the error won’t be passed to any other plugins. By default, this method returns false, which means that it does not handle any errors and the engine will log the errors as usual.

Implementations

impl dyn Plugin

pub fn cast<T: Plugin>(&self) -> Option<&T>

Performs downcasting to a particular type.

pub fn cast_mut<T: Plugin>(&mut self) -> Option<&mut T>

Performs downcasting to a particular type.

Implementors