Trait ScriptTrait

pub trait ScriptTrait: BaseScript + ComponentProvider {
    // Provided methods
    fn on_init(&mut self, ctx: &mut ScriptContext<'_, '_, '_>) { ... }
    fn on_start(&mut self, ctx: &mut ScriptContext<'_, '_, '_>) { ... }
    fn on_deinit(&mut self, ctx: &mut ScriptDeinitContext<'_, '_, '_>) { ... }
    fn on_os_event(
        &mut self,
        event: &Event<()>,
        ctx: &mut ScriptContext<'_, '_, '_>,
    ) { ... }
    fn on_update(&mut self, ctx: &mut ScriptContext<'_, '_, '_>) { ... }
    fn on_message(
        &mut self,
        message: &mut dyn ScriptMessagePayload,
        ctx: &mut ScriptMessageContext<'_, '_, '_>,
    ) { ... }
}

Script is a set predefined methods that are called on various stages by the engine. It is used to add custom behaviour to game entities.

Provided Methods

fn on_init(&mut self, ctx: &mut ScriptContext<'_, '_, '_>)

The method is called when the script wasn’t initialized yet. It is guaranteed to be called once, and before any other methods of the script.

Important

The method will not be called in case if you serialized initialized script instance and then loaded the instance. Internal flag will tell the engine that the script is initialized and this method will not be called. This is intentional design decision to be able to create save files in games. If you need a method that will be called in any case, use ScriptTrait::on_start.

fn on_start(&mut self, ctx: &mut ScriptContext<'_, '_, '_>)

The method is called after ScriptTrait::on_init, but in separate pass, which means that all script instances are already initialized. However, if implementor of this method creates a new node with a script, there will be a second pass of initialization. The method is guaranteed to be called once.

fn on_deinit(&mut self, ctx: &mut ScriptDeinitContext<'_, '_, '_>)

The method is called when the script is about to be destroyed. It is guaranteed to be called last.

fn on_os_event( &mut self, event: &Event<()>, ctx: &mut ScriptContext<'_, '_, '_>, )

Called when there is an event from the OS. The method allows you to “listen” for events coming from the main window of your game. It could be used to react to pressed keys, mouse movements, etc.

fn on_update(&mut self, ctx: &mut ScriptContext<'_, '_, '_>)

Performs a single update tick of the script. The method may be called multiple times per frame, but it is guaranteed that the rate of call is stable and by default it will be called 60 times per second, but can be changed by using crate::engine::executor::Executor::set_desired_update_rate method.

fn on_message( &mut self, message: &mut dyn ScriptMessagePayload, ctx: &mut ScriptMessageContext<'_, '_, '_>, )

Allows you to react to certain script messages. It could be used for communication between scripts; to bypass borrowing issues. If you need to receive messages of a particular type, you must subscribe to a type explicitly. Usually it is done in ScriptTrait::on_start method:

use fyrox_impl::{
    core::{reflect::prelude::*, uuid::Uuid, visitor::prelude::*, type_traits::prelude::*},
    core::TypeUuidProvider,
    script::ScriptTrait,
    script::{ScriptContext, ScriptMessageContext, ScriptMessagePayload},
};

struct Message;

#[derive(Reflect, Visit, Debug, Clone, ComponentProvider)]
struct MyScript {}


impl ScriptTrait for MyScript {
    fn on_start(&mut self, ctx: &mut ScriptContext) {
        // Subscription is mandatory to receive any message of the type!
        ctx.message_dispatcher.subscribe_to::<Message>(ctx.handle)
    }

    fn on_message(
        &mut self,
        message: &mut dyn ScriptMessagePayload,
        ctx: &mut ScriptMessageContext,
    ) {
        if let Some(message) = message.downcast_ref::<Message>() {
            // Do something.
        }
    }
}

Implementors