Byte Engine Docs
View on docs.rs

application

Generated Rust API reference for byte_engine.

byte_engine / application


Module application

Application lifecycle and composition.

Use BaseApplication when building a custom runtime that only needs parameter handling and frame-local storage. Headed applications should start with GraphicsApplication and choose either default_setup or individual graphics setup functions.

The triangle example demonstrates the standard setup path, while the window example demonstrates selecting only one setup component.

Contents

Quick Reference

ItemKindDescription
applicationmodThe minimal process configuration shared by higher-level runtimes.
threadmodWorker-thread support for application-owned subsystems.
wakermodWakes the application loop while it waits for window events.
graphicsmodHeaded application runtime and graphics setup entry points.
BaseApplicationstruct
LoopWakerstruct
TimestructThe [Time] struct provides frame timing to application systems without exposing the lifecycle clock owned by the application.
ParameterstructThe [Parameter] struct represents one application configuration value from code, the environment, or command-line arguments.
EventsenumThe [Events] enum defines messages shared with application-owned worker threads.

Modules

  • application — The minimal process configuration shared by higher-level runtimes.
  • thread — Worker-thread support for application-owned subsystems.
  • waker — Wakes the application loop while it waits for window events.
  • graphics — Headed application runtime and graphics setup entry points.

Structs

BaseApplication

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

Defined in crates/byte-engine/src/application/application.rs:26-39

The BaseApplication struct provides shared process configuration and frame-local storage for application implementations.

Embed it in a specialized application rather than using it as a complete game loop. GraphicsApplication uses the established headed composition pattern.

Implementations

  • fn new(name: &str, parameters: &[Parameter]) -> BaseApplication

    Related: Parameter, BaseApplication

    Creates the process configuration with the specified name and configuration parameters.

    Parameters may be overridden by the project's config.json, then by BE_* environment variables, and then by

    --name=value command-line arguments. In an environment variable's name, _ stands for - and __ for .,

    so BE_PHYSICS__STEP_LANES sets physics.step-lanes. See parameters_from_json for the file's format.

    Applications are

    singletons: this also installs the process logger and the tracing subscriber that feeds span times into

    Self::metrics.

    Configuration

    • log.level: Sets the most verbose log level that is printed: trace, debug, info, warn, error, or off.

    • trace: Prints every tracing span and event at DEBUG or less verbose levels to standard output.

    With the tracy Cargo feature, spans and logs also stream to a connected Tracy profiler.

  • fn get_name(&self) -> &str

    Returns the name of the application.

  • fn metrics(&self) -> &Arc<Metrics>

    Related: Metrics

    Returns the per-tick performance samples every tracing span of the process reports into.

    Register GPU or custom metrics on it with Metrics::register; the runtime that owns the tick calls

    Metrics::end_tick.

  • fn messages(&self) -> &MessageScope

    Related: MessageScope

    Returns the application message scope, where application-wide routes such as window events live.

    Next, call MessageScope::channel or MessageScope::factory to add an application-defined route.

  • fn message_bus(&self) -> &MessageBus

    Related: MessageBus

    Returns the shared fixed-storage message bus for diagnostics and new scopes.

    Next, call MessageBus::new_scope to isolate routes owned by another subsystem, such as a world.

  • fn events(&self) -> &DefaultChannel<Events>

    Related: Events

    Returns the channel of application lifecycle events. Ctrl-C and tools post Events::Close here, and

    worker threads subscribe to it to learn when to stop.

  • fn next_event(&mut self) -> Option<Events>

    Related: Events

    Reads the next lifecycle event for the runtime that owns the loop, which stops on Events::Close.

  • fn parameters(&self) -> &[Parameter]

    Related: Parameter

    Returns the resolved startup parameters after code, environment, and command-line precedence.

    Next, hand a system its subtree with Parameters::scope.

Trait Implementations

impl ArchivePointee for BaseApplication
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for BaseApplication
impl Downcast for BaseApplication
  • 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 BaseApplication
impl LayoutRaw for BaseApplication
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for BaseApplication
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for BaseApplication
  • type Metadata = ()
impl Read for BaseApplication
impl WithSubscriber for BaseApplication

LoopWaker

struct LoopWaker();

Defined in crates/byte-engine/src/application/waker.rs:19

The LoopWaker struct makes a waiting application loop run its next tick.

Take one with GraphicsApplication::waker, hand it to whatever changes state the loop cannot observe through window events, and call Self::wake from any thread afterwards. Wakes are coalesced, and waking a loop that is not waiting only costs two atomic operations. A LoopWaker also converts into a std::task::Waker for futures that must run inside the loop's own tick.

Implementations

  • fn wake(&self)

    Makes the application loop run its next tick without waiting for an event.

Trait Implementations

impl ArchivePointee for LoopWaker
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for LoopWaker
impl Clone for LoopWaker
  • fn clone(&self) -> LoopWaker

    Related: LoopWaker

impl Default for LoopWaker
  • fn default() -> LoopWaker

    Related: LoopWaker

impl Downcast for LoopWaker
  • 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 DowncastSync for LoopWaker
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for LoopWaker
impl LayoutRaw for LoopWaker
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for LoopWaker
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for LoopWaker
  • type Metadata = ()
impl Read for LoopWaker
impl<R> ReadPrimitive for LoopWaker
impl WithSubscriber for LoopWaker

Time

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

Defined in crates/byte-engine/src/application/mod.rs:29-32

The Time struct provides frame timing to application systems without exposing the lifecycle clock owned by the application.

Implementations

  • fn new(elapsed: MediaTime, delta: MediaTime) -> Self

    Related: MediaTime

    Creates frame timing data for systems that run inside an application tick.

  • fn elapsed(&self) -> MediaTime

    Related: MediaTime

    Returns the total time since the application started.

  • fn delta(&self) -> MediaTime

    Related: MediaTime

    Returns the time since the previous application tick.

Trait Implementations

impl ArchivePointee for Time
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Time
impl Clone for Time
  • fn clone(&self) -> Time

    Related: Time

impl Copy for Time
impl Debug for Time
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for Time
  • 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 DowncastSync for Time
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Instrument for Time
impl LayoutRaw for Time
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Time
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl Pointee for Time
  • type Metadata = ()
impl Read for Time
impl WithSubscriber for Time

Parameter

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

Defined in crates/byte-engine/src/application/mod.rs:54-57

The Parameter struct represents one application configuration value from code, the environment, or command-line arguments.

Implementations

  • fn new(name: &str, value: &str) -> Self

    Creates a parameter from borrowed name and value strings.

  • fn new_string(name: String, value: String) -> Self

    Creates a parameter from owned name and value strings.

  • fn is(&self, name: &str) -> bool

    Returns whether this parameter has the requested name.

  • fn as_bool(&self) -> Option<bool>

    Parses the parameter's value as a bool.

    Returns Some(true) for true, TRUE, or 1. Returns Some(false) for

    false, FALSE, or 0. Returns None for all other values.

  • fn as_bool_simple(&self) -> bool

    Parses the parameter as a Boolean value and returns false if parsing fails.

    Use Self::as_bool when the caller must distinguish false from an

    invalid value.

  • fn parse<T: std::str::FromStr>(&self) -> Result<T, ParameterError>

    Related: ParameterError

    Parses the parameter's value for a setting of type T.

    Each caller chooses its own policy for an invalid value: ignore it with .ok(), or stop with

    .unwrap_or_else(|error| panic!("{error}")).

    Errors

    Returns ParameterError naming the parameter and the rejected value when T cannot parse it.

  • fn name(&self) -> &str

    Returns the parameter name used by application configuration lookup.

  • fn value(&self) -> &str

    Returns the raw parameter value before caller-specific parsing.

Trait Implementations

impl ArchivePointee for Parameter
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Parameter
impl Clone for Parameter
  • fn clone(&self) -> Parameter

    Related: Parameter

impl Debug for Parameter
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for Parameter
  • 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 DowncastSync for Parameter
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for Parameter
impl<K> Equivalent for Parameter
  • fn equivalent(&self, key: &K) -> bool
impl Hash for Parameter
  • fn hash<__H: hash::Hasher>(&self, state: &mut __H)
impl Instrument for Parameter
impl LayoutRaw for Parameter
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Parameter
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for Parameter
  • fn eq(&self, other: &Parameter) -> bool

    Related: Parameter

impl Pointee for Parameter
  • type Metadata = ()
impl Read for Parameter
impl StructuralPartialEq for Parameter
impl WithSubscriber for Parameter

Enums

Events

enum Events {
    Close,
}

Defined in crates/byte-engine/src/application/mod.rs:130-133

The Events enum defines messages shared with application-owned worker threads.

Variants

  • Close

    Requests that the application close.

Trait Implementations

impl ArchivePointee for Events
  • type ArchivedMetadata = ()
  • fn pointer_metadata(_: &<T as ArchivePointee>::ArchivedMetadata) -> <T as Pointee>::Metadata
impl<ST> CastableFrom for Events
impl Clone for Events
  • fn clone(&self) -> Events

    Related: Events

impl Copy for Events
impl Debug for Events
  • fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result
impl Downcast for Events
  • 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 DowncastSync for Events
  • fn into_any_arc(self: Arc<T>) -> Arc<dyn Any + Send + Sync>
impl Eq for Events
impl<K> Equivalent for Events
  • fn equivalent(&self, key: &K) -> bool
impl Instrument for Events
impl LayoutRaw for Events
  • fn layout_raw(_: <T as Pointee>::Metadata) -> Result<Layout, LayoutError>
impl<T, N1> Niching for Events
  • unsafe fn is_niched(niched: *const NichedOption<T, N1>) -> bool
  • fn resolve_niched(out: Place<NichedOption<T, N1>>)
impl PartialEq for Events
  • fn eq(&self, other: &Events) -> bool

    Related: Events

impl Pointee for Events
  • type Metadata = ()
impl Read for Events
impl StructuralPartialEq for Events
impl WithSubscriber for Events

On this page

Module applicationContentsQuick ReferenceModulesStructsBaseApplicationImplementationsConfigurationTrait Implementationsimpl ArchivePointee for BaseApplicationimpl<ST> CastableFrom for BaseApplicationimpl Downcast for BaseApplicationimpl Instrument for BaseApplicationimpl LayoutRaw for BaseApplicationimpl<T, N1> Niching for BaseApplicationimpl Pointee for BaseApplicationimpl Read for BaseApplicationimpl WithSubscriber for BaseApplicationLoopWakerImplementationsTrait Implementationsimpl ArchivePointee for LoopWakerimpl<ST> CastableFrom for LoopWakerimpl Clone for LoopWakerimpl Default for LoopWakerimpl Downcast for LoopWakerimpl DowncastSync for LoopWakerimpl Instrument for LoopWakerimpl LayoutRaw for LoopWakerimpl<T, N1> Niching for LoopWakerimpl Pointee for LoopWakerimpl Read for LoopWakerimpl<R> ReadPrimitive for LoopWakerimpl WithSubscriber for LoopWakerTimeImplementationsTrait Implementationsimpl ArchivePointee for Timeimpl<ST> CastableFrom for Timeimpl Clone for Timeimpl Copy for Timeimpl Debug for Timeimpl Downcast for Timeimpl DowncastSync for Timeimpl Instrument for Timeimpl LayoutRaw for Timeimpl<T, N1> Niching for Timeimpl Pointee for Timeimpl Read for Timeimpl WithSubscriber for TimeParameterImplementationsErrorsTrait Implementationsimpl ArchivePointee for Parameterimpl<ST> CastableFrom for Parameterimpl Clone for Parameterimpl Debug for Parameterimpl Downcast for Parameterimpl DowncastSync for Parameterimpl Eq for Parameterimpl<K> Equivalent for Parameterimpl Hash for Parameterimpl Instrument for Parameterimpl LayoutRaw for Parameterimpl<T, N1> Niching for Parameterimpl PartialEq for Parameterimpl Pointee for Parameterimpl Read for Parameterimpl StructuralPartialEq for Parameterimpl WithSubscriber for ParameterEnumsEventsVariantsTrait Implementationsimpl ArchivePointee for Eventsimpl<ST> CastableFrom for Eventsimpl Clone for Eventsimpl Copy for Eventsimpl Debug for Eventsimpl Downcast for Eventsimpl DowncastSync for Eventsimpl Eq for Eventsimpl<K> Equivalent for Eventsimpl Instrument for Eventsimpl LayoutRaw for Eventsimpl<T, N1> Niching for Eventsimpl PartialEq for Eventsimpl Pointee for Eventsimpl Read for Eventsimpl StructuralPartialEq for Eventsimpl WithSubscriber for Events