Byte Engine Docs
View on docs.rs

tasks

Generated Rust API reference for byte_engine.

byte_engine / gameplay / tasks


Module tasks

Gameplay tasks: async gameplay logic, such as a character's life or a round's phases, that the application's tick polls.

GraphicsApplication owns the runtime and advances its clock once per simulation step. Access it through GraphicsApplication::runtime, start tasks with Runtime::spawn or Runtime::spawn_on, then call Runtime::poll with your state before and after the systems whose messages tasks await. A task can wait for animation root motion or a ray query's answer and continue in the same tick. Applications without graphics can own a Runtime directly.

Tasks wait on time through Tasks, and on everything else through the message bus:

  • Tasks::tick resolves at the next tick with the simulation time since the wait began.
  • Tasks::sleep resolves once that much simulation time has passed.
  • Tasks::every makes an Interval, whose Interval::next resolves at a fixed rate of simulation time, for work that doesn't need every tick, such as an agent re-planning its route.
  • DefaultListener::recv resolves with a channel's next message. A task keeps its own listeners, so it reads the same channels a system would.
  • Tasks::with resolves on its first poll with the state lent to the poll.

Tasks never read wall-clock time. The clock moves only by the deltas Runtime::advance receives, so pausing, slowing, or fixing the step happens in one place, and every task polled in a tick reads the same time.

Waits and cancellation

A wait stays registered only while its task keeps polling the future that made it: every poll numbers the task, and a wait the latest poll did not register again no longer wakes the task. Dropping a wait future, as the losing branch of a select! is, cancels it that way, and the runtime removes the waits a poll dropped once that poll ends. A task that ends leaves no waits behind. Combinators that poll every live branch on each poll, such as select! and join!, keep their branches registered. Do not hold a pending wait in a combinator that polls only woken branches.

A Tasks::tick first polled in a poll takes over the tick wait the same task dropped in that poll, so a task that selects over channel messages and ticks in a loop still counts every tick while messages keep winning, and a task that switches from one loop to another mid-tick resolves the new loop's tick in the same poll.

Next, spawn the first entity behaviors with Runtime::spawn_on.

Contents

Quick Reference

ItemKindDescription
RuntimestructThe Runtime struct keeps gameplay tasks alive between simulation steps and lends them state while polled.
TasksstructThe Tasks struct is the handle gameplay tasks spawn and wait on time through.
TickstructThe Tick struct is the future [Tasks::tick] returns.
SleepstructThe Sleep struct is the future [Tasks::sleep] returns.
IntervalstructThe Interval struct keeps a task's fixed-rate schedule between its waits, so work such as re-planning a route runs a few times a second instead of every tick.
IntervalTickstructThe IntervalTick struct is the future [Interval::next] returns.
and!macro
perform!macro

Structs

Runtime

struct Runtime {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/gameplay/tasks.rs:174-185

The Runtime struct keeps gameplay tasks alive between simulation steps and lends them state while polled.

Create it on the world scope with Self::new, spawn tasks through Self::spawn, and from each tick call Self::advance once and Self::poll after every stage whose output tasks wait for. Tasks run on the thread that polls, one at a time, in the order they were woken, so the same inputs replay the same way.

Implementations

  • fn new(world: &MessageScope) -> Self

    Related: MessageScope

    Creates a runtime whose tasks end with the entities of world they were spawned on.

    Next, spawn tasks through Self::spawn.

  • fn tasks<S: 'static>(&self) -> Tasks<S>

    Related: Tasks

    Returns a handle for tasks that reach context of type S through Tasks::with.

    Clone it into each task, then lend the same context type through Self::poll.

  • fn spawn<S: 'static, F: Future<Output = ()> + 'static>(&mut self, create: impl FnOnce(Tasks<S>) -> F)

    Related: Tasks

    Starts a task with the handle it waits and spawns children through.

    create builds the future now; Self::poll first polls it. Lend context of type S when polling.

  • fn spawn_on<S: 'static, F: Future<Output = ()> + 'static>(&mut self, owner: Handle, create: impl FnOnce(Tasks<S>) -> F)

    Related: Tasks

    Starts an entity's task with its own handle; deleting owner cancels the task and drops its future.

    create builds the future now. Next, call Self::poll with context of type S to run it.

  • fn advance(&mut self, time: Time)

    Related: Time

    Starts a tick: ends the tasks of deleted entities, moves the clock by time's delta, and wakes the tasks

    waiting for a tick and those whose sleep is due.

    Call it once per tick, before the tick's first Self::poll. Only the delta counts, so a paused tick that

    passes a zero delta still resolves tick waits, with zero, while sleeps hold.

  • fn poll<C: 'static>(&mut self, context: &mut C)

    Polls every woken task, including the tasks those polls spawn or wake, lending each poll context.

    Call it after Self::advance and again after each stage whose messages tasks wait for, such as an animation

    step whose root motion a character awaits.

Trait Implementations

impl ArchivePointee for Runtime
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Runtime
impl Downcast for Runtime
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl Drop for Runtime
  • fn drop(&mut self)

    Drops every future the runtime still keeps.

    Tasks not yet polled live in the shared state, and they may hold Tasks handles to it. That cycle would keep

    them alive after the runtime is gone, so they are dropped here, with the shared state released, until their

    destructors spawn nothing more.

impl Instrument for Runtime
impl LayoutRaw for Runtime
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Runtime
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Runtime
  • type Metadata = ()
impl Read for Runtime
impl WithSubscriber for Runtime

Tasks<S>

struct Tasks<S> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/gameplay/tasks.rs:403-406

The Tasks struct is the handle gameplay tasks spawn and wait on time through.

Get it from Runtime::tasks and clone it into each task; clones share one runtime. Its wait futures must be polled by the runtime that made it, inside one of its tasks.

Implementations

  • fn spawn(&self, future: impl Future<Output = ()> + 'static)

    Starts future as a task that runs until it returns. It is first polled in the current or next

    Runtime::poll.

  • fn spawn_on(&self, owner: Handle, future: impl Future<Output = ()> + 'static)

    Starts future as a task that also ends, dropping its future, when the world deletes owner.

    Spawn an entity's behavior on the entity, so deleting it cancels whatever the behavior was waiting for.

  • fn now(&self) -> MediaTime

    Related: MediaTime

    Returns the simulation time: the sum of every delta Runtime::advance received.

  • fn tick(&self) -> Tick<S>

    Related: Tick

    Returns a future that resolves at the next tick with the simulation time since the wait began.

    A task that waited on something else for a few ticks gets all of them, so time-based motion moves by the time

    that passed rather than the last tick's delta.

  • fn sleep(&self, duration: MediaTime) -> Sleep<S>

    Related: MediaTime, Sleep

    Returns a future that resolves once duration of simulation time has passed since its first poll.

  • fn every(&self, period: MediaTime) -> Interval<S>

    Related: MediaTime, Interval

    Returns an interval that fires every period of simulation time, starting one period from now.

    Keep the interval across a task's loop and await Interval::next in it. Spread many intervals of the same

    period across ticks with Interval::phase.

    Panics

    Panics when period isn't greater than zero.

  • fn with<R>(&self, read: impl FnOnce(&mut S) -> R) -> impl Future<Output = R>

    Returns a future that runs read on its first poll with the context the runtime lends its tasks.

    The future is ready at once; awaiting it only reaches the context. Keep the borrow inside read: the context is

    lent to one poll at a time.

Trait Implementations

impl ArchivePointee for Tasks<S>
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Tasks<S>
impl<S> Clone for Tasks<S>
  • fn clone(&self) -> Self
impl Downcast for Tasks<S>
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl Instrument for Tasks<S>
impl LayoutRaw for Tasks<S>
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Tasks<S>
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Tasks<S>
  • type Metadata = ()
impl Read for Tasks<S>
impl WithSubscriber for Tasks<S>

Tick<S>

struct Tick<S> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/gameplay/tasks.rs:496-501

The Tick struct is the future Tasks::tick returns.

Trait Implementations

impl ArchivePointee for Tick<S>
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Tick<S>
impl Downcast for Tick<S>
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl<S: 'static> FusedFuture for Tick<S>
  • fn is_terminated(&self) -> bool
impl<S: 'static> Future for Tick<S>
  • type Output = MediaTime
  • fn poll(self: Pin<&mut Self>, _: &mut std::task::Context<'_>) -> Poll<MediaTime>

    Related: MediaTime

impl FutureExt for Tick<S>
impl Instrument for Tick<S>
impl IntoFuture for Tick<S>
  • type Output = <F as Future>::Output
  • type IntoFuture = F
  • fn into_future(self) -> <F as IntoFuture>::IntoFuture
impl LayoutRaw for Tick<S>
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Tick<S>
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Tick<S>
  • type Metadata = ()
impl Read for Tick<S>
impl<S> Unpin for Tick<S>
impl WithSubscriber for Tick<S>

Sleep<S>

struct Sleep<S> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/gameplay/tasks.rs:575-581

The Sleep struct is the future Tasks::sleep returns.

Trait Implementations

impl ArchivePointee for Sleep<S>
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Sleep<S>
impl Downcast for Sleep<S>
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl<S> Drop for Sleep<S>
  • fn drop(&mut self)
impl<S: 'static> FusedFuture for Sleep<S>
  • fn is_terminated(&self) -> bool
impl<S: 'static> Future for Sleep<S>
  • type Output = ()
  • fn poll(self: Pin<&mut Self>, _: &mut std::task::Context<'_>) -> Poll<()>
impl FutureExt for Sleep<S>
impl Instrument for Sleep<S>
impl IntoFuture for Sleep<S>
  • type Output = <F as Future>::Output
  • type IntoFuture = F
  • fn into_future(self) -> <F as IntoFuture>::IntoFuture
impl LayoutRaw for Sleep<S>
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Sleep<S>
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Sleep<S>
  • type Metadata = ()
impl Read for Sleep<S>
impl<S> Unpin for Sleep<S>
impl WithSubscriber for Sleep<S>

Interval<S>

struct Interval<S> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/gameplay/tasks.rs:621-629

The Interval struct keeps a task's fixed-rate schedule between its waits, so work such as re-planning a route runs a few times a second instead of every tick.

Make it with Tasks::every before a task's loop and await Self::next inside it, or use next as a perform! each wait. The schedule lives here rather than in the wait futures, so a wait that loses a select! keeps its deadline for the next one.

Implementations

  • fn phase(self, offset: MediaTime) -> Self

    Related: MediaTime

    Delays every deadline of the interval by offset.

    Give the intervals of many entities different offsets within one period, so their fires land on different ticks

    instead of the same one. Derive the offset from the entity, not from a random source, to keep runs repeatable.

    Panics

    Panics when offset is negative.

  • fn set_period(&mut self, period: MediaTime)

    Related: MediaTime

    Changes the time between deadlines, counting the next deadline from the latest one the interval passed.

    Use it to make an agent think less often as it moves away from the player. A next deadline that has already

    passed resolves the next wait at once, or at the next advance that moves simulation time when the interval

    already fired in this one.

    Panics

    Panics when period isn't greater than zero.

  • fn next(&mut self) -> IntervalTick<'_, S>

    Related: IntervalTick

    Returns a future that resolves at the interval's next deadline with the simulation time since its previous fire.

    A fire passes every deadline simulation time reached, so a task that waited on something else for several

    periods fires once, with all the time that passed.

Trait Implementations

impl ArchivePointee for Interval<S>
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Interval<S>
impl Downcast for Interval<S>
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl Instrument for Interval<S>
impl LayoutRaw for Interval<S>
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Interval<S>
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Interval<S>
  • type Metadata = ()
impl Read for Interval<S>
impl WithSubscriber for Interval<S>

IntervalTick<'a, S>

struct IntervalTick<'a, S> {
    // [REDACTED: Private Fields]
}

Defined in crates/byte-engine/src/gameplay/tasks.rs:677-682

The IntervalTick struct is the future Interval::next returns.

Trait Implementations

impl ArchivePointee for IntervalTick<'a, S>
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for IntervalTick<'a, S>
impl Downcast for IntervalTick<'a, S>
  • fn into_any(self: Box<T>) -> Box<dyn Any>
  • fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
  • fn as_any(&self) -> &dyn Any
  • fn as_any_mut(&mut self) -> &mut dyn Any
impl<S> Drop for IntervalTick<'_, S>
  • fn drop(&mut self)
impl<S: 'static> FusedFuture for IntervalTick<'_, S>
  • fn is_terminated(&self) -> bool
impl<S: 'static> Future for IntervalTick<'_, S>
  • type Output = MediaTime
  • fn poll(self: Pin<&mut Self>, _: &mut std::task::Context<'_>) -> Poll<MediaTime>

    Related: MediaTime

impl FutureExt for IntervalTick<'a, S>
impl Instrument for IntervalTick<'a, S>
impl IntoFuture for IntervalTick<'a, S>
  • type Output = <F as Future>::Output
  • type IntoFuture = F
  • fn into_future(self) -> <F as IntoFuture>::IntoFuture
impl LayoutRaw for IntervalTick<'a, S>
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for IntervalTick<'a, S>
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for IntervalTick<'a, S>
  • type Metadata = ()
impl Read for IntervalTick<'a, S>
impl<S> Unpin for IntervalTick<'_, S>
impl WithSubscriber for IntervalTick<'a, S>

Macros

and!

Defined in crates/byte-engine/src/gameplay/tasks.rs:81-102

Awaits related activities in written order, discarding their results.

Use this inside a perform! branch for activities that belong to the same update. Each expression is created only after the previous one finishes, so successive calls can borrow the same mutable state. If an activity suspends, the group suspends there; later activities start when it finishes.

Write when future => { activities } to run activities only if the event is ready at that point. The event is polled once in the current task's context, then dropped. A pending event skips its activities without suspending the group. Event futures must tolerate cancellation; keep their underlying listener or state between updates. The body uses the same awaited activity syntax, and can suspend once selected, just like an ordinary activity.

perform!

Defined in crates/byte-engine/src/gameplay/tasks.rs:119-164

Repeats async branches, checking their waits in written order.

Write when future => { actions } to handle an event, or each value = future => { actions } to handle repeated updates and use their results. Wait expressions are rebuilt for each selection and fused automatically. The first ready wait chooses the branch, whose actions run to completion before another branch is chosen. An await inside those actions can suspend the entire performance. Use break to end it or return to end the enclosing task.

Add always { actions } for a shared step before each selection, including the first. It runs again after a selected branch finishes, and may await while borrowing the same state as the branches. It does not run in parallel with a branch or while a nested performance is active. break and return leave immediately.

Nest a performance inside a branch to replace the outer activities until that inner performance ends. The original select_biased! branch syntax is also accepted; fuse those futures yourself.

On this page

Module tasksWaits and cancellationContentsQuick ReferenceStructsRuntimeImplementationsTrait Implementationsimpl ArchivePointee for Runtimeimpl<ST> CastableFrom for Runtimeimpl Downcast for Runtimeimpl Drop for Runtimeimpl Instrument for Runtimeimpl LayoutRaw for Runtimeimpl<T, N1> Niching for Runtimeimpl Pointee for Runtimeimpl Read for Runtimeimpl WithSubscriber for RuntimeTasks<S>ImplementationsPanicsTrait Implementationsimpl ArchivePointee for Tasks<S>impl<ST> CastableFrom for Tasks<S>impl<S> Clone for Tasks<S>impl Downcast for Tasks<S>impl Instrument for Tasks<S>impl LayoutRaw for Tasks<S>impl<T, N1> Niching for Tasks<S>impl Pointee for Tasks<S>impl Read for Tasks<S>impl WithSubscriber for Tasks<S>Tick<S>Trait Implementationsimpl ArchivePointee for Tick<S>impl<ST> CastableFrom for Tick<S>impl Downcast for Tick<S>impl<S: 'static> FusedFuture for Tick<S>impl<S: 'static> Future for Tick<S>impl FutureExt for Tick<S>impl Instrument for Tick<S>impl IntoFuture for Tick<S>impl LayoutRaw for Tick<S>impl<T, N1> Niching for Tick<S>impl Pointee for Tick<S>impl Read for Tick<S>impl<S> Unpin for Tick<S>impl WithSubscriber for Tick<S>Sleep<S>Trait Implementationsimpl ArchivePointee for Sleep<S>impl<ST> CastableFrom for Sleep<S>impl Downcast for Sleep<S>impl<S> Drop for Sleep<S>impl<S: 'static> FusedFuture for Sleep<S>impl<S: 'static> Future for Sleep<S>impl FutureExt for Sleep<S>impl Instrument for Sleep<S>impl IntoFuture for Sleep<S>impl LayoutRaw for Sleep<S>impl<T, N1> Niching for Sleep<S>impl Pointee for Sleep<S>impl Read for Sleep<S>impl<S> Unpin for Sleep<S>impl WithSubscriber for Sleep<S>Interval<S>ImplementationsPanicsPanicsTrait Implementationsimpl ArchivePointee for Interval<S>impl<ST> CastableFrom for Interval<S>impl Downcast for Interval<S>impl Instrument for Interval<S>impl LayoutRaw for Interval<S>impl<T, N1> Niching for Interval<S>impl Pointee for Interval<S>impl Read for Interval<S>impl WithSubscriber for Interval<S>IntervalTick<'a, S>Trait Implementationsimpl ArchivePointee for IntervalTick<'a, S>impl<ST> CastableFrom for IntervalTick<'a, S>impl Downcast for IntervalTick<'a, S>impl<S> Drop for IntervalTick<'_, S>impl<S: 'static> FusedFuture for IntervalTick<'_, S>impl<S: 'static> Future for IntervalTick<'_, S>impl FutureExt for IntervalTick<'a, S>impl Instrument for IntervalTick<'a, S>impl IntoFuture for IntervalTick<'a, S>impl LayoutRaw for IntervalTick<'a, S>impl<T, N1> Niching for IntervalTick<'a, S>impl Pointee for IntervalTick<'a, S>impl Read for IntervalTick<'a, S>impl<S> Unpin for IntervalTick<'_, S>impl WithSubscriber for IntervalTick<'a, S>Macrosand!perform!