Plugins

A game based on Fyrox is a plugin to the engine and the editor. Plugin defines global application logic and provides a set of scripts, that can be used to assign custom logic to scene nodes.

Plugin is an "entry point" of your game, it has a fixed set of methods that can be used for initialization, update, OS event handling, etc. Every plugin is statically linked to the engine (and the editor), there is no support for hot-reloading due to lack of stable ABI in Rust. However, it is possible to not recompile the editor everytime - if you don't change data layout in your structures the editor will be able to compile your game and run it with the currently loaded scene, thus reducing amount of iterations. You can freely modify application logic and this won't affect the running editor.

The main purpose of the plugins is to hold and operate on some global application data, that can be used in scripts and provide a set of scripts to the engine. Plugins also have much wider access to engine internals, than scripts. For example, it is possible to change scenes, add render passes, change resolution, etc. which is not possible from scripts.

Structure

Plugin structure is defined by Plugin trait. Typical implementation can be generated by fyrox-template tool, and it looks something like this:

#![allow(unused)]
fn main() {
extern crate fyrox;
use fyrox::{
    core::{
        futures::executor::block_on,
        pool::Handle,
    },
    event::Event,
    event_loop::ControlFlow,
    gui::message::UiMessage,
    plugin::{Plugin, PluginConstructor, PluginContext, PluginRegistrationContext},
    scene::{Scene, SceneLoader},
};
use std::path::Path;

pub struct GameConstructor;

impl PluginConstructor for GameConstructor {
    fn register(&self, _context: PluginRegistrationContext) {
        // Register your scripts here.
    }

    fn create_instance(
        &self,
        scene_path: Option<&str>,
        context: PluginContext,
    ) -> Box<dyn Plugin> {
        Box::new(Game::new(scene_path, context))
    }
}

pub struct Game {
    scene: Handle<Scene>,
}

impl Game {
    pub fn new(scene_path: Option<&str>, context: PluginContext) -> Self {
        context
            .async_scene_loader
            .request(scene_path.unwrap_or("data/scene.rgs"));
            
        Self { 
            scene: Handle::NONE 
        }
    }
}

impl Plugin for Game {
    fn on_deinit(&mut self, _context: PluginContext) {
        // Do a cleanup here.
    }

    fn update(&mut self, _context: &mut PluginContext, _control_flow: &mut ControlFlow) {
        // Add your global update code here.
    }

    fn on_os_event(
        &mut self,
        _event: &Event<()>,
        _context: PluginContext,
        _control_flow: &mut ControlFlow,
    ) {
        // Do something on OS event here.
    }

    fn on_ui_message(
        &mut self,
        _context: &mut PluginContext,
        _message: &UiMessage,
        _control_flow: &mut ControlFlow,
    ) {
        // Handle UI events here.
    }
    
    fn on_scene_loaded(&mut self, _path: &Path, scene: Handle<Scene>, context: &mut PluginContext) {
        if self.scene.is_some() {
            context.scenes.remove(self.scene);
        }

        self.scene = scene;
    }
}
}

There are two major parts - GameConstructor and Game itself. GameConstructor implements PluginConstructor and it is responsible for script registration (fn register) and creating the actual game instance (fn create_instance).

register - called once on start allowing you to register your scripts. Important: You must register all your scripts here, otherwise the engine (and the editor) will know nothing about them. Also, you should register loaders for your custom resources here. See Custom Resource chapter more info.
create_instance - called once, allowing you to create actual game instance. It is guaranteed to be called once, but where it is called is implementation-defined. For example, the editor will not call this method, it does not create any game instance. The method has scene_path parameter, in short it is a path to a scene that is currently opened in the editor (it will be None if either there's no opened scene or your game was started outside the editor). It is described in Editor and Plugins section down below.

The game structure (struct Game) implements a Plugin trait which can execute actual game logic in one of its methods:

on_deinit - it is called when the game is about to shut down. Can be used for any clean up, for example logging that the game has closed.
update - it is called each frame at a stable rate (usually 60 Hz, but can be configured in the Executor) after the plugin is created and fully initialized. It is the main place where you should put object-independent game logic (such as user interface handling, global application state management, etc.), any other logic should be added via scripts.
on_os_event - it is called when the main application window receives an event from the operating system, it can be any event such as keyboard, mouse, game pad events or any other events. Please note that as for update method, you should put here only object-independent logic. Scripts can catch OS events too.
on_ui_message - it is called when there is a message from the user interface, it should be used to react to user actions (like pressed buttons, etc.)
on_graphics_context_initialized - it is called when a graphics context was successfully initialized. This method could be used to access the renderer (to change its quality settings, for instance). You can also access a main window instance and change its properties (such as title, size, resolution, etc.).
on_graphics_context_destroyed - it is called when the current graphics context was destroyed. It could happen on a small number of platforms, such as Android. Such platforms usually have some sort of suspension mode, in which you are not allowed to render graphics, to have a "window", etc.
before_rendering - it is called when the engine is about to render a new frame. This method is useful to perform offscreen rendering (for example - user interface).
on_scene_begin_loading - it is called when the engine starts to load a game scene. This method could be used to show a progress bar or some sort of loading screen, etc.
on_scene_loaded - it is called when the engine successfully loaded a game scene. This method could be used to add custom logic to do something with a newly loaded scene.

Control Flow

Some plugin methods provide access to ControlFlow variable, its main usage in the plugin is to give you ability to stop the game by some conditions. All you need to do is to set it to ControlFlow::Exit and the game will be closed. It also has other variants, but they don't have any particular usage in the plugins.

#![allow(unused)]
fn main() {
fn update(&mut self, _context: &mut PluginContext, control_flow: &mut ControlFlow) {
    if self.some_exit_condition {
        control_flow = ControlFlow::Exit;
    }
}
}

Plugin Context

Vast majority of methods accept PluginContext - it provides almost full access to engine entities, it has access to the renderer, scenes container, resource manager, user interface, main application window. Typical content of the context is something like this:

#![allow(unused)]
fn main() {
extern crate fyrox;
use fyrox::{
    engine::{SerializationContext, GraphicsContext, PerformanceStatistics, AsyncSceneLoader, ScriptProcessor},
    asset::manager::ResourceManager,
    gui::UserInterface,
    scene::SceneContainer,
    window::Window,
};
use std::sync::Arc;
pub struct PluginContext<'a, 'b> {
    pub scenes: &'a mut SceneContainer,
    pub resource_manager: &'a ResourceManager,
    pub user_interface: &'a mut UserInterface,
    pub graphics_context: &'a mut GraphicsContext,
    pub dt: f32,
    pub lag: &'b mut f32,
    pub serialization_context: &'a Arc<SerializationContext>,
    pub performance_statistics: &'a PerformanceStatistics,
    pub elapsed_time: f32,
    pub script_processor: &'a ScriptProcessor,
    pub async_scene_loader: &'a mut AsyncSceneLoader,
}
}

Amount of time (in seconds) that passed from creation of the engine. Keep in mind, that this value is not guaranteed to match real time. A user can change delta time with which the engine "ticks" and this delta time affects elapsed time.

scenes - a scene container, could be used to manage game scenes - add, remove, borrow. An example of scene loading is given in the previous code snippet in Game::new() method.
resource_manager - is used to load external resources (scenes, models, textures, animations, sound buffers, etc.) from different sources (disk, network storage on WebAssembly, etc.)
user_interface - use it to create user interface for your game, the interface is scene-independent and will remain the same even if there are multiple scenes created.
graphics_context - a reference to the graphics_context, it contains a reference to the window and the current renderer. It could be GraphicsContext::Uninitialized if your application is suspended (possible only on Android).
dt - a time passed since the last frame. The actual value is implementation-defined, but on current implementation it is equal to 1/60 of a second and does not change event if the frame rate is changing (the engine stabilizes update rate for the logic).
lag - a reference to the time accumulator, that holds remaining amount of time that should be used to update a plugin. A caller splits lag into multiple sub-steps using dt and thus stabilizes update rate. The main use of this variable, is to be able to reset lag when you're doing some heavy calculations in a game loop (i.e. loading a new level) so the engine won't try to "catch up" with all the time that was spent in heavy calculation.
serialization_context - it can be used to register scripts and custom scene nodes constructors at runtime.
performance_statistics - performance statistics from the last frame. To get a rendering performance statistics, use Renderer::get_statistics method, that could be obtained from the renderer instance in the current graphics context.
elapsed_time - amount of time (in seconds) that passed from creation of the engine. Keep in mind, that this value is not guaranteed to match real time. A user can change delta time with which the engine "ticks" and this delta time affects elapsed time.
script_processor - a reference to the current script processor instance, which could be used to access a list of scenes that supports scripts.
async_scene_loader - a reference to the current asynchronous scene loader instance. It could be used to request a new scene to be loaded.

Editor and Plugins

When you're running your game from the editor, it starts the game as a separate process and if there's a scene opened in the editor, it tells the game instance to load it on startup. Let's look closely at Game::new method:

#![allow(unused)]
fn main() {
extern crate fyrox;
use fyrox::{
    core::{futures::executor::block_on, pool::Handle},
    plugin::PluginContext,
    scene::{Scene, SceneLoader},
};
use std::path::Path;

struct Foo {
    scene: Handle<Scene>,
}

impl Foo {
pub fn new(scene_path: Option<&str>, context: PluginContext) -> Self {
    context
        .async_scene_loader
        .request(scene_path.unwrap_or("data/scene.rgs"));
        
    Self { 
        scene: Handle::NONE 
    }
}
}
}

The scene_path parameter is a path to a scene that is currently opened in the editor, your game should use it if you need to load a currently selected scene of the editor in your game. However, it is not strictly necessary - you may desire to start your game from a specific scene all the time, even when the game starts from the editor. If the parameter is None, then there is no scene loaded in the editor or the game was run outside the editor.

Fyrox Book

Plugins

Structure

Control Flow

Plugin Context

Editor and Plugins