Trait veloren_rtsim::ai::Action

pub trait Action<S = (), R = ()>: Any + Send + Sync {
    // Required methods
    fn is_same(&self, other: &Self) -> bool
       where Self: Sized;
    fn dyn_is_same(&self, other: &dyn Action<S, R>) -> bool;
    fn backtrace(&self, bt: &mut Vec<String>);
    fn reset(&mut self);
    fn tick(&mut self, ctx: &mut NpcCtx<'_>, state: &mut S) -> ControlFlow<R>;

    // Provided methods
    fn dyn_is_same_sized(&self, other: &dyn Action<S, R>) -> bool
       where Self: Sized { ... }
    fn then<A1: Action<S, R1>, R1>(self, other: A1) -> Then<Self, A1, R>
       where Self: Sized { ... }
    fn repeat(self) -> Repeat<Self, R>
       where Self: Sized { ... }
    fn stop_if<P: Predicate + Clone>(self, p: P) -> StopIf<Self, P>
       where Self: Sized { ... }
    fn interrupt_with<A1: Action<S, R1>, R1, F: Fn(&mut NpcCtx<'_>, &mut S) -> Option<A1> + Send + Sync + 'static>(
        self,
        f: F,
    ) -> InterruptWith<Self, F, A1, R1>
       where Self: Sized { ... }
    fn map<F: Fn(R, &mut S) -> R1, R1>(self, f: F) -> Map<Self, F, R>
       where Self: Sized { ... }
    fn boxed(self) -> Box<dyn Action<S, R>>
       where Self: Sized { ... }
    fn with_state<S0>(self, s: S) -> WithState<Self, S, S0>
       where Self: Sized,
             S: Clone { ... }
    fn map_state<S0, F>(self, f: F) -> MapState<Self, F, S, S0>
       where F: Fn(&mut S0) -> &mut S,
             Self: Sized { ... }
    fn debug<F, T>(self, mk_info: F) -> Debug<Self, F, T>
       where Self: Sized { ... }
    fn l<Rhs>(self) -> Either<Self, Rhs>
       where Self: Sized { ... }
    fn r<Lhs>(self) -> Either<Lhs, Self>
       where Self: Sized { ... }
}

A trait that describes ‘actions’: long-running tasks performed by rtsim NPCs. These can be as simple as walking in a straight line between two locations or as complex as taking part in an adventure with players or performing an entire daily work schedule.

Actions are built up from smaller sub-actions via the combinator methods defined on this trait, and with the standalone functions in this module. Using these combinators, in a similar manner to using the Iterator API, it is possible to construct arbitrarily complex actions including behaviour trees (see choose and watch) and other forms of moment-by-moment decision-making.

On completion, actions may produce a value, denoted by the type parameter R. For example, an action may communicate whether it was successful or unsuccessful through this completion value.

You should not need to implement this trait yourself when writing AI code. If you find yourself wanting to implement it, please discuss with the core dev team first.

Required Methods

fn is_same(&self, other: &Self) -> bool

where Self: Sized,

Returns true if the action should be considered the ‘same’ (i.e: achieving the same objective) as another. In general, the AI system will try to avoid switching (and therefore restarting) tasks when the new task is the ‘same’ as the old one.

fn dyn_is_same(&self, other: &dyn Action<S, R>) -> bool

Like Action::is_same, but allows for dynamic dispatch.

fn backtrace(&self, bt: &mut Vec<String>)

Generate a backtrace for the action. The action should recursively push all of the tasks it is currently performing.

fn reset(&mut self)

Reset the action to its initial state such that it can be repeated.

fn tick(&mut self, ctx: &mut NpcCtx<'_>, state: &mut S) -> ControlFlow<R>

Perform the action for the current tick.

Provided Methods

fn dyn_is_same_sized(&self, other: &dyn Action<S, R>) -> bool

where Self: Sized,

Like Action::is_same, but allows for dynamic dispatch.

fn then<A1: Action<S, R1>, R1>(self, other: A1) -> Then<Self, A1, R>

where Self: Sized,

Create an action that chains together two sub-actions, one after the other.

Example

// Walk toward an enemy NPC and, once done, attack the enemy NPC
goto(enemy_npc).then(attack(enemy_npc))

fn repeat(self) -> Repeat<Self, R>

where Self: Sized,

Create an action that repeats a sub-action indefinitely.

Example

// Endlessly collect flax from the environment
find_and_collect(ChunkResource::Flax).repeat()

fn stop_if<P: Predicate + Clone>(self, p: P) -> StopIf<Self, P>

where Self: Sized,

Stop the sub-action suddenly if a condition is reached.

Example

// Keep going on adventures until your 111th birthday
go_on_an_adventure().repeat().stop_if(|ctx| ctx.npc.age > 111.0)

fn interrupt_with<A1: Action<S, R1>, R1, F: Fn(&mut NpcCtx<'_>, &mut S) -> Option<A1> + Send + Sync + 'static>( self, f: F, ) -> InterruptWith<Self, F, A1, R1>

where Self: Sized,

Pause an action to possibly perform another action.

Example

// Keep going on adventures until your 111th birthday
walk_to_the_shops()
    .interrupt_with(|ctx| if ctx.npc.is_hungry() {
        Some(eat_food())
    } else {
        None
    })

fn map<F: Fn(R, &mut S) -> R1, R1>(self, f: F) -> Map<Self, F, R>

where Self: Sized,

Map the completion value of this action to something else.

fn boxed(self) -> Box<dyn Action<S, R>>

where Self: Sized,

Box the action. Often used to perform type erasure, such as when you want to return one of many actions (each with different types) from the same function.

Note that Either can often be used to unify mismatched types without the need for boxing.

Example

// Error! Type mismatch between branches
if npc.is_too_tired() {
    goto(npc.home)
} else {
    go_on_an_adventure()
}

// All fine
if npc.is_too_tired() {
    goto(npc.home).boxed()
} else {
    go_on_an_adventure().boxed()
}

fn with_state<S0>(self, s: S) -> WithState<Self, S, S0>

where Self: Sized, S: Clone,

Set the state for child actions.

Note that state is reset when repeated.

Example

just(|_, state: &mut i32| *state += 2)
    // Outputs 5
    .then(just(|_, state: &mut i32| println!("{state}")))
    .with_state(3)

fn map_state<S0, F>(self, f: F) -> MapState<Self, F, S, S0>

where F: Fn(&mut S0) -> &mut S, Self: Sized,

Map the current state for child actions, this map expects the return value to have the same lifetime as the input state.

Example

// Goes forward 5 steps
just(|_, state: &mut i32| go_forward(*state))
    .map_state(|state: &mut (i32, i32)| &mut state.1)
    .with_state((14, 5))

fn debug<F, T>(self, mk_info: F) -> Debug<Self, F, T>

where Self: Sized,

Add debugging information to the action that will be visible when using the /npc_info command.

Example

goto(npc.home).debug(|| "Going home")

fn l<Rhs>(self) -> Either<Self, Rhs>

where Self: Sized,

fn r<Lhs>(self) -> Either<Lhs, Self>

where Self: Sized,

Trait Implementations

impl<S: State, R: 'static> Action<S, R> for Box<dyn Action<S, R>>

fn is_same(&self, other: &Self) -> bool

Returns true if the action should be considered the ‘same’ (i.e: achieving the same objective) as another. In general, the AI system will try to avoid switching (and therefore restarting) tasks when the new task is the ‘same’ as the old one.

fn dyn_is_same(&self, other: &dyn Action<S, R>) -> bool

Like Action::is_same, but allows for dynamic dispatch.

fn backtrace(&self, bt: &mut Vec<String>)

Generate a backtrace for the action. The action should recursively push all of the tasks it is currently performing.

fn reset(&mut self)

Reset the action to its initial state such that it can be repeated.

fn tick(&mut self, ctx: &mut NpcCtx<'_>, state: &mut S) -> ControlFlow<R>

Perform the action for the current tick.

fn dyn_is_same_sized(&self, other: &dyn Action<S, R>) -> bool

where Self: Sized,

Like Action::is_same, but allows for dynamic dispatch.

fn then<A1: Action<S, R1>, R1>(self, other: A1) -> Then<Self, A1, R>

where Self: Sized,

Create an action that chains together two sub-actions, one after the other.

fn repeat(self) -> Repeat<Self, R>

where Self: Sized,

Create an action that repeats a sub-action indefinitely.

fn stop_if<P: Predicate + Clone>(self, p: P) -> StopIf<Self, P>

where Self: Sized,

Stop the sub-action suddenly if a condition is reached.

fn interrupt_with<A1: Action<S, R1>, R1, F: Fn(&mut NpcCtx<'_>, &mut S) -> Option<A1> + Send + Sync + 'static>( self, f: F, ) -> InterruptWith<Self, F, A1, R1>

where Self: Sized,

Pause an action to possibly perform another action.

fn map<F: Fn(R, &mut S) -> R1, R1>(self, f: F) -> Map<Self, F, R>

where Self: Sized,

Map the completion value of this action to something else.

fn boxed(self) -> Box<dyn Action<S, R>>

where Self: Sized,

Box the action. Often used to perform type erasure, such as when you want to return one of many actions (each with different types) from the same function.

fn with_state<S0>(self, s: S) -> WithState<Self, S, S0>

where Self: Sized, S: Clone,

Set the state for child actions.

fn map_state<S0, F>(self, f: F) -> MapState<Self, F, S, S0>

where F: Fn(&mut S0) -> &mut S, Self: Sized,

Map the current state for child actions, this map expects the return value to have the same lifetime as the input state.

fn debug<F, T>(self, mk_info: F) -> Debug<Self, F, T>

where Self: Sized,

Add debugging information to the action that will be visible when using the /npc_info command.

fn l<Rhs>(self) -> Either<Self, Rhs>

where Self: Sized,

fn r<Lhs>(self) -> Either<Lhs, Self>

where Self: Sized,

Implementations on Foreign Types

impl<S: State, R: 'static> Action<S, R> for Box<dyn Action<S, R>>

fn is_same(&self, other: &Self) -> bool

fn dyn_is_same(&self, other: &dyn Action<S, R>) -> bool

fn backtrace(&self, bt: &mut Vec<String>)

fn reset(&mut self)

fn tick(&mut self, ctx: &mut NpcCtx<'_>, state: &mut S) -> ControlFlow<R>

impl<S: State, R: 'static, A: Action<S, R>, B: Action<S, R>> Action<S, R> for Either<A, B>

fn is_same(&self, other: &Self) -> bool

fn dyn_is_same(&self, other: &dyn Action<S, R>) -> bool

fn backtrace(&self, bt: &mut Vec<String>)

fn reset(&mut self)

fn tick(&mut self, ctx: &mut NpcCtx<'_>, state: &mut S) -> ControlFlow<R>

Implementors

impl<S0: State, S: State, R, A: Action<S, R>> Action<S0, R> for WithState<A, S, S0>

impl<S0: State, S: State, R, A: Action<S, R>, F: Fn(&mut S0) -> &mut S + Send + Sync + 'static> Action<S0, R> for MapState<A, F, S, S0>

impl<S: 'static, A: Action<S, R>, F: Fn() -> T + Send + Sync + 'static, R: Send + Sync + 'static, T: Send + Sync + Display + 'static> Action<S, R> for Debug<A, F, T>

impl<S: State> Action<S> for Finish

impl<S: State, A0: Action<S, R0>, A1: Action<S, R1>, F: Fn(&mut NpcCtx<'_>, &mut S) -> Option<A1> + Send + Sync + 'static, R0: Send + Sync + 'static, R1: Send + Sync + 'static> Action<S, R0> for InterruptWith<A0, F, A1, R1>

impl<S: State, A0: Action<S, R0>, A1: Action<S, R1>, R0: Send + Sync + 'static, R1: Send + Sync + 'static> Action<S, R1> for Then<A0, A1, R0>

impl<S: State, A: Action<S, R>, F: Fn(R, &mut S) -> R1 + Send + Sync + 'static, R: Send + Sync + 'static, R1> Action<S, R1> for Map<A, F, R>

impl<S: State, A: Action<S, R>, P: Predicate + Clone + Send + Sync + 'static, R> Action<S, Option<R>> for StopIf<A, P>

impl<S: State, F: Fn(&mut NpcCtx<'_>, &mut S) -> Node<S, R> + Send + Sync + 'static, R: 'static> Action<S, R> for Tree<S, F, R>

impl<S: State, R: Send + Sync + 'static, A: Action<S, R>> Action<S, !> for Repeat<A, R>

impl<S: State, R: Send + Sync + 'static, F: Fn(&mut NpcCtx<'_>, &mut S) -> Option<A> + Send + Sync + 'static, A: Action<S, R>> Action<S> for Until<F, A, R>

impl<S: State, R: Send + Sync + 'static, F: Fn(&mut NpcCtx<'_>, &mut S) -> A + Send + Sync + 'static, A: Action<S, R>> Action<S, R> for Now<F, A>

impl<S: State, R: Send + Sync + 'static, F: Fn(&mut NpcCtx<'_>, &mut S) -> R + Send + Sync + 'static> Action<S, R> for Just<F, R>

impl<S: State, R: Send + Sync + 'static, I: Iterator<Item = A> + Clone + Send + Sync + 'static, A: Action<S, R>> Action<S> for Sequence<I, A, R>