Trait Action

pub trait Action:
    Downcast
    + Send
    + Sync
    + 'static {
    // Required methods
    fn is_finished(&self, agent: Entity, world: &World) -> bool;
    fn on_start(&mut self, agent: Entity, world: &mut World) -> bool;
    fn on_stop(
        &mut self,
        agent: Option<Entity>,
        world: &mut World,
        reason: StopReason,
    );

    // Provided methods
    fn on_add(&mut self, agent: Entity, world: &mut World) { ... }
    fn on_remove(&mut self, agent: Option<Entity>, world: &mut World) { ... }
    fn on_drop(
        self: Box<Self>,
        agent: Option<Entity>,
        world: &mut World,
        reason: DropReason,
    ) { ... }
    fn type_name(&self) -> &'static str { ... }
}

The trait that all actions must implement.

It contains various methods that together defines the lifecycle of an action. From this, you can create any action that can last as long as you like, and do as much as you like.

In general, the act of starting the action should happen inside on_start. This is especially true for despawning an agent. The other methods should be used for initializing and cleaning up. See below for more information.

⚠️ Warning

Since you are given a mutable World, you can in practice do anything. Depending on what you do, the logic for advancing the action queue might not work properly.

There are a few things you should keep in mind:

• If you want to despawn an agent as an action, this should be done in on_start.
• The execute and next methods should not be used, as that will immediately advance the action queue while inside any of the trait methods. Instead, you should return true in on_start.
• When adding new actions, you should set the start property to false. Otherwise, you will effectively call execute which, again, should not be used. At worst, you will cause a stack overflow if the action adds itself.

    fn on_start(&mut self, agent: Entity, world: &mut World) -> bool {
        world
            .actions(agent)
            .start(false) // Do not start next action
            .add((action_a, action_b, action_c));

        // Immediately advance the action queue
        true
    }

Required Methods

fn is_finished(&self, agent: Entity, world: &World) -> bool

Determines if an action is finished or not. Advances the action queue when returning true.

By default, this method is called every frame in the Last schedule.

fn on_start(&mut self, agent: Entity, world: &mut World) -> bool

The method that is called when an action is started.

Typically here you would insert components to agent or a new entity to make systems run. If you wish to despawn agent as an action, this is where you should do it.

Returning true here marks the action as already finished, and will immediately advance the action queue.

fn on_stop( &mut self, agent: Option<Entity>, world: &mut World, reason: StopReason, )

The method that is called when an action is stopped.

Typically here you would clean up any stuff from on_start, depending on the reason.

When paused, the action will be put back into the action queue again to the front. This means that it will start again when the next action is executed.

Provided Methods

fn on_add(&mut self, agent: Entity, world: &mut World)

The method that is called when an action is added to the queue.

You can think of this as the constructor, as it will only be called once.

Examples found in repository

examples/repeat.rs (line 52)

    fn on_add(&mut self, agent: Entity, world: &mut World) {
        self.action.on_add(agent, world);
    }

examples/parallel.rs (line 50)

    fn on_add(&mut self, agent: Entity, world: &mut World) {
        self.actions
            .iter_mut()
            .for_each(|action| action.on_add(agent, world));
    }

examples/sequence.rs (line 52)

    fn on_add(&mut self, agent: Entity, world: &mut World) {
        self.actions
            .iter_mut()
            .for_each(|action| action.on_add(agent, world));
    }

fn on_remove(&mut self, agent: Option<Entity>, world: &mut World)

The method that is called when an action is removed from the queue.

You can think of this as the destructor, as it will only be called once.

Examples found in repository

examples/repeat.rs (line 64)

    fn on_remove(&mut self, agent: Option<Entity>, world: &mut World) {
        self.action.on_remove(agent, world);
    }

examples/sequence.rs (line 65)

    fn on_remove(&mut self, agent: Option<Entity>, world: &mut World) {
        self.actions[self.index].on_remove(agent, world);
    }

    fn on_drop(mut self: Box<Self>, agent: Option<Entity>, world: &mut World, reason: DropReason) {
        self.index += 1;

        if self.index >= N {
            return;
        }

        if self.canceled || reason != DropReason::Done {
            for i in self.index..N {
                self.actions[i].on_remove(agent, world);
            }
            return;
        }

        let Some(agent) = agent else { return };

        world
            .actions(agent)
            .start(false)
            .order(AddOrder::Front)
            .add(self as BoxedAction);
    }

examples/parallel.rs (line 68)

    fn on_remove(&mut self, agent: Option<Entity>, world: &mut World) {
        self.actions
            .iter_mut()
            .for_each(|action| action.on_remove(agent, world));
    }

fn on_drop( self: Box<Self>, agent: Option<Entity>, world: &mut World, reason: DropReason, )

The last method that is called with full ownership.

This is useful for actions that might want to alter the behavior of the action queue. For example, a RepeatAction could keep readding itself to the action queue based on some counter.

fn type_name(&self) -> &'static str

Returns the type name of an action.

Implementations

impl dyn Action

pub fn is<__T: Action>(&self) -> bool

Returns true if the trait object wraps an object of type __T.

pub fn downcast<__T: Action>(self: Box<Self>) -> Result<Box<__T>, Box<Self>>

Returns a boxed object from a boxed trait object if the underlying object is of type __T. Returns the original boxed trait if it isn’t.

pub fn downcast_rc<__T: Action>(self: Rc<Self>) -> Result<Rc<__T>, Rc<Self>>

Returns an Rc-ed object from an Rc-ed trait object if the underlying object is of type __T. Returns the original Rc-ed trait if it isn’t.

pub fn downcast_ref<__T: Action>(&self) -> Option<&__T>

Returns a reference to the object within the trait object if it is of type __T, or None if it isn’t.

pub fn downcast_mut<__T: Action>(&mut self) -> Option<&mut __T>

Returns a mutable reference to the object within the trait object if it is of type __T, or None if it isn’t.

Implementors

impl<OnStart> Action for OnStart

where OnStart: FnMut(Entity, &mut World) -> bool + Send + Sync + 'static,