Trait fyrox::plugin::Plugin

pub trait Plugin: BasePlugin {
    // Provided methods
    fn on_deinit(&mut self, context: PluginContext<'_, '_>) { ... }
    fn update(&mut self, context: &mut PluginContext<'_, '_>) { ... }
    fn on_os_event(&mut self, event: &Event<()>, context: PluginContext<'_, '_>) { ... }
    fn on_graphics_context_initialized(
        &mut self,
        context: PluginContext<'_, '_>
    ) { ... }
    fn before_rendering(&mut self, context: PluginContext<'_, '_>) { ... }
    fn on_graphics_context_destroyed(&mut self, context: PluginContext<'_, '_>) { ... }
    fn on_ui_message(
        &mut self,
        context: &mut PluginContext<'_, '_>,
        message: &UiMessage
    ) { ... }
    fn on_scene_begin_loading(
        &mut self,
        path: &Path,
        context: &mut PluginContext<'_, '_>
    ) { ... }
    fn on_scene_loaded(
        &mut self,
        path: &Path,
        scene: Handle<Scene>,
        data: &[u8],
        context: &mut PluginContext<'_, '_>
    ) { ... }
    fn on_scene_loading_failed(
        &mut self,
        path: &Path,
        error: &VisitError,
        context: &mut PluginContext<'_, '_>
    ) { ... }
}

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

Static vs dynamic plugins

Every plugin must be linked statically to ensure that everything is memory safe. There was some long research about hot reloading and dynamic plugins (in DLLs) and it turned out that they’re not guaranteed to be memory safe because Rust does not have stable ABI. When a plugin compiled into DLL, Rust compiler is free to reorder struct members in any way it needs to. It is not guaranteed that two projects that uses the same library will have compatible ABI. This fact indicates that you either have to use static linking of your plugins or provide C interface to every part of the engine and “communicate” with plugin using C interface with C ABI (which is standardized and guaranteed to be compatible). The main problem with C interface is boilerplate code and the need to mark every structure “visible” through C interface with #[repr(C)] attribute which is not always easy and even possible (because some structures could be re-exported from dependencies). These are the main reasons why the engine uses static plugins.

Example

use fyrox::{
    core::{pool::Handle},
    plugin::{Plugin, PluginContext, PluginRegistrationContext},
    scene::Scene,
    event::Event
};
use std::str::FromStr;

#[derive(Default)]
struct MyPlugin {}

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

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

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

Provided Methods

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

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<'_, '_>)

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

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

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<'_, '_>)

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<'_, '_>)

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<'_, '_>)

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

fn on_ui_message( &mut self, context: &mut PluginContext<'_, '_>, message: &UiMessage )

The method will be called when there is any message from main user interface instance of the engine.

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

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<'_, '_> )

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<'_, '_> )

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.

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