Struct Executor

pub struct Executor { /* private fields */ }

Executor is a small wrapper that manages plugins and scripts for your game.

Implementations

impl Executor

pub const DEFAULT_UPDATE_RATE: f32 = 60f32

Default update rate in frames per second.

pub const DEFAULT_TIME_STEP: f32 = 0.0166666675f32

Default time step (in seconds).

pub fn from_params( event_loop: EventLoop<()>, graphics_context_params: GraphicsContextParams, ) -> Self

Creates new game executor using specified set of parameters. Much more flexible version of Executor::new.

pub fn new() -> Self

Creates new game executor using default window and with vsync turned on. For more flexible way to create an executor see Executor::from_params.

pub fn set_resource_hot_reloading_enabled(&mut self, enabled: bool)

Enables or disables hot reloading of changed resources (such as textures, shaders, scenes, etc.). Enabled by default.

Platform-specific

Does nothing on Android and WebAssembly, because these OSes does not have rich file system as PC.

pub fn is_resource_hot_reloading_enabled(&self) -> bool

Returns true if hot reloading of changed resources is enabled, false - otherwise.

pub fn set_headless(&mut self, headless: bool)

Defines whether the executor should initialize graphics context or not. Headless mode could be useful for game servers, where you don’t need to have a window, renderer, sound, etc. By default, headless mode is off.

pub fn is_headless(&self) -> bool

Returns true if the headless mode is turned on, false - otherwise.

pub fn set_throttle_threshold(&mut self, threshold: f32)

Sets the desired throttle threshold (in seconds), at which the engine will stop trying to stabilize the update rate of the game logic and will increase the time step. This option could be useful to prevent potential hang up of the game if its logic or rendering takes too much time at each frame. The default value is two default time steps (33.3(3) milliseconds or 0.0333(3) seconds).

Important notes

Physics could suffer from variable time step which may result in objects falling through the ground and some other nasty things. Throttle threshold should be at reasonably high levels (usually 2x-3x of the fixed time step).

pub fn throttle_threshold(&self) -> f32

Returns current throttle threshold. See Self::set_throttle_threshold docs for more info.

pub fn set_throttle_frame_interval(&mut self, interval: usize)

Sets the amount of frames (consecutive) that will be allowed to have lag spikes and the engine won’t modify time step for internal update calls during such interval. This setting allows the engine to ignore small lag spikes and do not fast-forward game logic using variable time step. Variable time step could be bad for physics, which may result in objects falling through the ground, etc. Default is 5 frames.

pub fn throttle_frame_interval(&self) -> usize

Returns current throttle frame interval. See Self::set_throttle_frame_interval docs for more info.

pub fn set_desired_update_rate(&mut self, update_rate: f32)

Sets the desired update rate in frames per second.

pub fn desired_update_rate(&self) -> f32

Returns desired update rate in frames per second.

pub fn add_plugin<P>(&mut self, plugin: P)

where P: Plugin + 'static,

Adds new plugin to the executor, the plugin will be enabled only on Executor::run.

pub fn run(self)

Runs the executor - starts your game.

Methods from Deref<Target = Engine>

pub fn initialize_graphics_context( &mut self, window_target: &EventLoopWindowTarget<()>, ) -> Result<(), EngineError>

Tries to initialize the graphics context. The method will attempt to use the info stored in graphics_context variable of the engine to attempt to initialize the graphics context. It will fail if the graphics context is already initialized as well as if there any platform-dependent error (for example your hardware does not support OpenGL 3.3 Core or OpenGL ES 3.0).

This method should be called on Event::Resumed of your game loop, however you can ignore it if you don’t need graphics context at all (for example - if you’re making game server).

pub fn destroy_graphics_context(&mut self) -> Result<(), EngineError>

Tries to destroy current graphics context. It will succeed only if the graphics_context is fully initialized. The method will try to save all possible runtime changes of the window, so the next Engine::initialize_graphics_context will result in the almost exact copy of the context that was made before destruction.

This method should be called on Event::Suspended of your game loop, however if you do not use any graphics context (for example - if you’re making a game server), then you can ignore this method completely.

pub fn set_frame_size( &mut self, new_size: (u32, u32), ) -> Result<(), FrameworkError>

Adjust size of the frame to be rendered. Must be called after the window size changes. Will update the renderer and GL context frame size.

pub fn elapsed_time(&self) -> f32

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.

pub fn update( &mut self, dt: f32, window_target: &EventLoopWindowTarget<()>, lag: &mut f32, switches: FxHashMap<Handle<Scene>, GraphUpdateSwitches>, )

Performs single update tick with given time delta. Engine internally will perform update of all scenes, sub-systems, user interface, etc. Must be called in order to get engine functioning.

Parameters

lag - is a reference to 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 doing some heavy calculations in a your 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. The engine does not use this variable itself, but the plugins attach may use it, that’s why you need to provide it. If you don’t use plugins, then put &mut 0.0 here.

pub fn handle_plugins_hot_reloading<F>( &mut self, dt: f32, window_target: &EventLoopWindowTarget<()>, lag: &mut f32, on_reloaded: F, )

where F: FnMut(&dyn Plugin),

Tries to hot-reload dynamic plugins marked for reloading.

Platform-specific

• Windows, Unix-like systems (Linux, macOS, FreeBSD, etc) - fully supported.
• WebAssembly - not supported
• Android - not supported

pub fn pre_update( &mut self, dt: f32, window_target: &EventLoopWindowTarget<()>, lag: &mut f32, switches: FxHashMap<Handle<Scene>, GraphUpdateSwitches>, )

Performs pre update for the engine.

Normally, this is called from Engine::update(). You should only call this manually if you don’t use that method.

Parameters

lag - is a reference to 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 doing some heavy calculations in a your 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. The engine does not use this variable itself, but the plugins attach may use it, that’s why you need to provide it. If you don’t use plugins, then put &mut 0.0 here.

pub fn post_update( &mut self, dt: f32, ui_update_switches: &UiUpdateSwitches, lag: &mut f32, window_target: &EventLoopWindowTarget<()>, )

Performs post update for the engine.

Normally, this is called from Engine::update(). You should only call this manually if you don’t use that method.

pub fn has_scripted_scene(&self, scene: Handle<Scene>) -> bool

Returns true if the scene is registered for script processing.

pub fn register_scripted_scene(&mut self, scene: Handle<Scene>)

Registers a scene for script processing.

pub fn handle_model_events(&mut self)

Handle hot-reloading of resources.

Normally, this is called from Engine::update(). You should only call this manually if you don’t use that method.

pub fn render(&mut self) -> Result<(), FrameworkError>

Performs rendering of single frame, must be called from your game loop, otherwise you won’t see anything.

pub fn add_plugin<P>(&mut self, plugin: P)

where P: Plugin + 'static,

Adds a new static plugin.

pub fn add_dynamic_plugin<P>( &mut self, path: P, reload_when_changed: bool, use_relative_paths: bool, ) -> Result<&dyn Plugin, String>

where P: AsRef<Path> + 'static,

Tries to add a new dynamic plugin. This method attempts to load a dynamic library by the given path and searches for fyrox_plugin function. This function is called to create a plugin instance. This method will fail if there’s no dynamic library at the given path or the fyrox_plugin function is not found.

Hot reloading

This method can enable hot reloading for the plugin, by setting reload_when_changed parameter to true. When enabled, the engine will clone the library to implementation-defined path and load it. It will setup file system watcher to receive changes from the OS and reload the plugin.

pub fn add_dynamic_plugin_custom<P>(&mut self, plugin: P) -> &dyn Plugin

where P: DynamicPlugin + 'static,

Adds a new abstract dynamic plugin

pub fn reload_plugin( &mut self, plugin_index: usize, dt: f32, window_target: &EventLoopWindowTarget<()>, lag: &mut f32, ) -> Result<(), String>

Tries to reload a specified plugin. This method tries to perform least invasive reloading, by only detaching parts from the scenes and engine internals, that belongs to reloadable plugin.

pub fn plugins(&self) -> &[PluginContainer]

Returns a reference to the plugins.

pub fn plugins_mut(&mut self) -> &mut [PluginContainer]

Returns a mutable reference to the plugins.

pub fn reload_dynamic_plugins<F>( &mut self, dt: f32, window_target: &EventLoopWindowTarget<()>, lag: &mut f32, on_reloaded: F, ) -> Result<(), String>

where F: FnMut(&dyn Plugin),

Tries to reload all dynamic plugins registered in the engine, that needs to be reloaded.

Trait Implementations

impl Default for Executor

fn default() -> Self

Returns the “default value” for a type.

impl DerefMut for Executor

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.

impl Deref for Executor

type Target = Engine

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.