Byte Engine Docs
View on docs.rs

gameplay

Generated Rust API reference for byte_engine.

byte_engine / gameplay


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

ItemKindDescription
pathfindingmodGraph search, navigation meshes, and XZ-plane path finding.
tasksmodGameplay tasks: async gameplay logic, such as a character's life or a round's phases, that the application's tick polls.
Intervalstruct
Runtimestruct
Tasksstruct

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) -> 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>

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>

On this page