gameplay
Generated Rust API reference for byte_engine.
Module gameplay
World-level gameplay objects and transform coordination.
Applications create renderables, lights, cameras, and physics bodies through
the factories of their world scope, so rendering and physics receive the same
lifecycle messages on the routes each message type names.
transform::Transform and Anchor provide the shared spatial model for
gameplay objects. Scene and SceneNode group entities so a level can be
destroyed as a unit, which SceneGraph carries out.
Quick Reference
| Item | Kind | Description |
|---|---|---|
pathfinding | mod | Graph search, navigation meshes, and XZ-plane path finding. |
tasks | mod | Gameplay tasks: async gameplay logic, such as a character's life or a round's phases, that the application's tick polls. |
Interval | struct | |
Runtime | struct | |
Tasks | struct |
Modules
pathfinding— Graph search, navigation meshes, and XZ-plane path finding.tasks— Gameplay tasks: async gameplay logic, such as a character's life or a round's phases, that the application's tick
Structs
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>
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 = ()