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::tickresolves at the next tick with the simulation time since the wait began.Tasks::sleepresolves once that much simulation time has passed.Tasks::everymakes anInterval, whoseInterval::nextresolves at a fixed rate of simulation time, for work that doesn't need every tick, such as an agent re-planning its route.DefaultListener::recvresolves with a channel's next message. A task keeps its own listeners, so it reads the same channels a system would.Tasks::withresolves 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
| Item | Kind | Description |
|---|---|---|
Runtime | struct | The Runtime struct keeps gameplay tasks alive between simulation steps and lends them state while polled. |
Tasks | struct | The Tasks struct is the handle gameplay tasks spawn and wait on time through. |
Tick | struct | The Tick struct is the future [Tasks::tick] returns. |
Sleep | struct | The Sleep struct is the future [Tasks::sleep] returns. |
Interval | struct | 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. |
IntervalTick | struct | The 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) -> SelfRelated:
MessageScopeCreates a runtime whose tasks end with the entities of
worldthey were spawned on.Next, spawn tasks through
Self::spawn. -
fn tasks<S: 'static>(&self) -> Tasks<S>Related:
TasksReturns a handle for tasks that reach context of type
SthroughTasks::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:
TasksStarts a task with the handle it waits and spawns children through.
createbuilds the future now;Self::pollfirst polls it. Lend context of typeSwhen polling. -
fn spawn_on<S: 'static, F: Future<Output = ()> + 'static>(&mut self, owner: Handle, create: impl FnOnce(Tasks<S>) -> F)Related:
TasksStarts an entity's task with its own handle; deleting
ownercancels the task and drops its future.createbuilds the future now. Next, callSelf::pollwith context of typeSto run it. -
fn advance(&mut self, time: Time)Related:
TimeStarts a tick: ends the tasks of deleted entities, moves the clock by
time's delta, and wakes the taskswaiting 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 thatpasses 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::advanceand again after each stage whose messages tasks wait for, such as an animationstep 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
Taskshandles to it. That cycle would keepthem 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
futureas a task that runs until it returns. It is first polled in the current or next -
fn spawn_on(&self, owner: Handle, future: impl Future<Output = ()> + 'static)Starts
futureas a task that also ends, dropping its future, when the world deletesowner.Spawn an entity's behavior on the entity, so deleting it cancels whatever the behavior was waiting for.
-
fn now(&self) -> MediaTimeRelated:
MediaTimeReturns the simulation time: the sum of every delta
Runtime::advancereceived. -
fn tick(&self) -> Tick<S>Related:
TickReturns 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>Returns a future that resolves once
durationof simulation time has passed since its first poll. -
fn every(&self, period: MediaTime) -> Interval<S>Returns an interval that fires every
periodof simulation time, starting one period from now.Keep the interval across a task's loop and await
Interval::nextin it. Spread many intervals of the sameperiod across ticks with
Interval::phase.Panics
Panics when
periodisn't greater than zero. -
fn with<R>(&self, read: impl FnOnce(&mut S) -> R) -> impl Future<Output = R>Returns a future that runs
readon 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 islent 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) -> SelfRelated:
MediaTimeDelays 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
offsetis negative. -
fn set_period(&mut self, period: MediaTime)Related:
MediaTimeChanges 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
periodisn't greater than zero. -
fn next(&mut self) -> IntervalTick<'_, S>Related:
IntervalTickReturns 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.