Struct bevy_internal::app::prelude::App

source · 
pub struct App {
    pub world: World,
    pub runner: Box<dyn Fn(App) + 'static, Global>,
    pub schedule: Schedule,
    /* private fields */
}
Expand description

A container of app logic and data.

Bundles together the necessary elements like World and Schedule to create an ECS-based application. It also stores a pointer to a runner function. The runner is responsible for managing the application’s event loop and applying the Schedule to the World to drive application logic.

Examples

Here is a simple “Hello World” Bevy app:

fn main() {
   App::new()
       .add_system(hello_world_system)
       .run();
}

fn hello_world_system() {
   println!("hello world");
}

Fields§

§world: World

The main ECS World of the App. This stores and provides access to all the main data of the application. The systems of the App will run using this World. If additional separate World-Schedule pairs are needed, you can use sub_apps.

§runner: Box<dyn Fn(App) + 'static, Global>

The runner function is primarily responsible for managing the application’s event loop and advancing the Schedule. Typically, it is not configured manually, but set by one of Bevy’s built-in plugins. See bevy::winit::WinitPlugin and ScheduleRunnerPlugin.

§schedule: Schedule

A container of Stages set to be run in a linear order.

Implementations§

Creates a new App with some default structure to enable core engine features. This is the preferred constructor for most use cases.

Creates a new empty App with minimal default configuration.

This constructor should be used if you wish to provide a custom schedule, exit handling, cleanup, etc.

Advances the execution of the Schedule by one cycle.

This method also updates sub apps.

See add_sub_app and run_once for more details.

Starts the application by calling the app’s runner function.

Finalizes the App configuration. For general usage, see the example on the item level documentation.

Adds a Stage with the given label to the last position of the app’s Schedule.

Examples
#[derive(StageLabel)]
struct MyStage;
app.add_stage(MyStage, SystemStage::parallel());

Adds a Stage with the given label to the app’s Schedule, located immediately after the stage labeled by target.

Examples
#[derive(StageLabel)]
struct MyStage;
app.add_stage_after(CoreStage::Update, MyStage, SystemStage::parallel());

Adds a Stage with the given label to the app’s Schedule, located immediately before the stage labeled by target.

Examples
#[derive(StageLabel)]
struct MyStage;
app.add_stage_before(CoreStage::Update, MyStage, SystemStage::parallel());

Adds a Stage with the given label to the last position of the startup schedule.

Examples
#[derive(StageLabel)]
struct MyStartupStage;
app.add_startup_stage(MyStartupStage, SystemStage::parallel());

Adds a startup stage with the given label, immediately after the stage labeled by target.

The target label must refer to a stage inside the startup schedule.

Examples
#[derive(StageLabel)]
struct MyStartupStage;
app.add_startup_stage_after(
    StartupStage::Startup,
    MyStartupStage,
    SystemStage::parallel()
);

Adds a startup stage with the given label, immediately before the stage labeled by target.

The target label must refer to a stage inside the startup schedule.

Examples
#[derive(StageLabel)]
struct MyStartupStage;
app.add_startup_stage_before(
    StartupStage::Startup,
    MyStartupStage,
    SystemStage::parallel()
);

Fetches the Stage of type T marked with label from the Schedule, then executes the provided func passing the fetched stage to it as an argument.

The func argument should be a function or a closure that accepts a mutable reference to a struct implementing Stage and returns the same type. That means that it should also assume that the stage has already been fetched successfully.

See stage for more details.

Examples

Here the closure is used to add a system to the update stage:

app.stage(CoreStage::Update, |stage: &mut SystemStage| {
    stage.add_system(my_system)
});

Adds a system to the update stage of the app’s Schedule.

Refer to the system module documentation to see how a system can be defined.

Examples
app.add_system(my_system);

Adds a SystemSet to the update stage.

Examples
app.add_system_set(
    SystemSet::new()
        .with_system(system_a)
        .with_system(system_b)
        .with_system(system_c),
);

Adds a system to the Stage identified by stage_label.

Examples
app.add_system_to_stage(CoreStage::PostUpdate, my_system);

Adds a SystemSet to the Stage identified by stage_label.

Examples
app.add_system_set_to_stage(
    CoreStage::PostUpdate,
    SystemSet::new()
        .with_system(system_a)
        .with_system(system_b)
        .with_system(system_c),
);

Adds a system to the startup stage of the app’s Schedule.

Examples
fn my_startup_system(_commands: Commands) {
    println!("My startup system");
}

App::new()
    .add_startup_system(my_startup_system);

Adds a SystemSet to the startup stage.

Examples
app.add_startup_system_set(
    SystemSet::new()
        .with_system(startup_system_a)
        .with_system(startup_system_b)
        .with_system(startup_system_c),
);

Adds a system to the startup schedule, in the stage identified by stage_label.

stage_label must refer to a stage inside the startup schedule.

Examples
app.add_startup_system_to_stage(StartupStage::PreStartup, my_startup_system);

Adds a SystemSet to the startup schedule, in the stage identified by stage_label.

stage_label must refer to a stage inside the startup schedule.

Examples
app.add_startup_system_set_to_stage(
    StartupStage::PreStartup,
    SystemSet::new()
        .with_system(startup_system_a)
        .with_system(startup_system_b)
        .with_system(startup_system_c),
);

Adds a new State with the given initial value. This inserts a new State<T> resource and adds a new “driver” to CoreStage::Update. Each stage that uses State<T> for system run criteria needs a driver. If you need to use your state in a different stage, consider using Self::add_state_to_stage or manually adding State::get_driver to additional stages you need it in.

Adds a new State with the given initial value. This inserts a new State<T> resource and adds a new “driver” to the given stage. Each stage that uses State<T> for system run criteria needs a driver. If you need to use your state in more than one stage, consider manually adding State::get_driver to the stages you need it in.

Adds utility stages to the Schedule, giving it a standardized structure.

Adding those stages is necessary to make some core engine features work, like adding systems without specifying a stage, or registering events. This is however done by default by calling App::default, which is in turn called by App::new.

The stages

All the added stages, with the exception of the startup stage, run every time the schedule is invoked. The stages are the following, in order of execution:

  • First: Runs at the very start of the schedule execution cycle, even before the startup stage.
  • Startup: This is actually a schedule containing sub-stages. Runs only once when the app starts.
    • Pre-startup: Intended for systems that need to run before other startup systems.
    • Startup: The main startup stage. Startup systems are added here by default.
    • Post-startup: Intended for systems that need to run after other startup systems.
  • Pre-update: Often used by plugins to prepare their internal state before the update stage begins.
  • Update: Intended for user defined logic. Systems are added here by default.
  • Post-update: Often used by plugins to finalize their internal state after the world changes that happened during the update stage.
  • Last: Runs right before the end of the schedule execution cycle.

The labels for those stages are defined in the CoreStage and StartupStage enums.

Examples
let app = App::empty().add_default_stages();

Setup the application to manage events of type T.

This is done by adding a Resource of type Events::<T>, and inserting an update_system into CoreStage::First.

See Events for defining events.

Examples
app.add_event::<MyEvent>();

Inserts a Resource to the current App and overwrites any Resource previously added of the same type.

A Resource in Bevy represents globally unique data. Resources must be added to Bevy apps before using them. This happens with insert_resource.

See init_resource for Resources that implement Default or FromWorld.

Examples
#[derive(Resource)]
struct MyCounter {
    counter: usize,
}

App::new()
   .insert_resource(MyCounter { counter: 0 });

Inserts a non-send resource to the app.

You usually want to use insert_resource, but there are some special cases when a resource cannot be sent across threads.

Examples
struct MyCounter {
    counter: usize,
}

App::new()
    .insert_non_send_resource(MyCounter { counter: 0 });

Initialize a Resource with standard starting values by adding it to the World.

If the Resource already exists, nothing happens.

The Resource must implement the FromWorld trait. If the Default trait is implemented, the FromWorld trait will use the Default::default method to initialize the Resource.

Examples
#[derive(Resource)]
struct MyCounter {
    counter: usize,
}

impl Default for MyCounter {
    fn default() -> MyCounter {
        MyCounter {
            counter: 100
        }
    }
}

App::new()
    .init_resource::<MyCounter>();

Initialize a non-send Resource with standard starting values by adding it to the World.

The Resource must implement the FromWorld trait. If the Default trait is implemented, the FromWorld trait will use the Default::default method to initialize the Resource.

Sets the function that will be called when the app is run.

The runner function run_fn is called only once by App::run. If the presence of a main loop in the app is desired, it is the responsibility of the runner function to provide it.

The runner function is usually not set manually, but by Bevy integrated plugins (e.g. WinitPlugin).

Examples
fn my_runner(mut app: App) {
    loop {
        println!("In main loop");
        app.update();
    }
}

App::new()
    .set_runner(my_runner);

Adds a single Plugin.

One of Bevy’s core principles is modularity. All Bevy engine features are implemented as Plugins. This includes internal features like the renderer.

Bevy also provides a few sets of default Plugins. See add_plugins.

Examples
App::new().add_plugin(bevy_log::LogPlugin::default());
Panics

Panics if the plugin was already added to the application.

Checks if a Plugin has already been added.

This can be used by plugins to check if a plugin they depend upon has already been added.

Returns a vector of references to any plugins of type T that have been added.

This can be used to read the settings of any already added plugins. This vector will be length zero if no plugins of that type have been added. If multiple copies of the same plugin are added to the App, they will be listed in insertion order in this vector.

let default_sampler = app.get_added_plugins::<ImagePlugin>()[0].default_sampler;

Adds a group of Plugins.

Plugins can be grouped into a set by using a PluginGroup.

There are built-in PluginGroups that provide core engine functionality. The PluginGroups available by default are DefaultPlugins and MinimalPlugins.

To customize the plugins in the group (reorder, disable a plugin, add a new plugin before / after another plugin), call build() on the group, which will convert it to a PluginGroupBuilder.

Examples
App::new()
    .add_plugins(MinimalPlugins);
Panics

Panics if one of the plugin in the group was already added to the application.

Registers the type T in the TypeRegistry resource, adding reflect data as specified in the Reflect derive:

ⓘ
#[derive(Reflect)]
#[reflect(Component, Serialize, Deserialize)] // will register ReflectComponent, ReflectSerialize, ReflectDeserialize

See bevy_reflect::TypeRegistry::register.

Adds the type data D to type T in the TypeRegistry resource.

Most of the time App::register_type can be used instead to register a type you derived Reflect for. However, in cases where you want to add a piece of type data that was not included in the list of #[reflect(...)] type data in the derive, or where the type is generic and cannot register e.g. ReflectSerialize unconditionally without knowing the specific type parameters, this method can be used to insert additional type data.

Example
use bevy_app::App;
use bevy_reflect::{ReflectSerialize, ReflectDeserialize};

App::new()
    .register_type::<Option<String>>()
    .register_type_data::<Option<String>, ReflectSerialize>()
    .register_type_data::<Option<String>, ReflectDeserialize>();

See bevy_reflect::TypeRegistry::register_type_data.

Adds an App as a child of the current one.

The provided function f is called by the update method. The World parameter represents the main app world, while the App parameter is just a mutable reference to the SubApp itself.

Retrieves a SubApp stored inside this App.

Panics

Panics if the SubApp doesn’t exist.

Retrieves a SubApp inside this App with the given label, if it exists. Otherwise returns an Err containing the given label.

Retrieves a SubApp stored inside this App.

Panics

Panics if the SubApp doesn’t exist.

Retrieves a SubApp inside this App with the given label, if it exists. Otherwise returns an Err containing the given label.

Trait Implementations§

Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more
Convert Box<dyn Trait> (where Trait: Downcast) to Box<dyn Any>. Box<dyn Any> can then be further downcast into Box<ConcreteType> where ConcreteType implements Trait. Read more
Convert Rc<Trait> (where Trait: Downcast) to Rc<Any>. Rc<Any> can then be further downcast into Rc<ConcreteType> where ConcreteType implements Trait. Read more
Convert &Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &Any’s vtable from &Trait’s. Read more
Convert &mut Trait (where Trait: Downcast) to &Any. This is needed since Rust cannot generate &mut Any’s vtable from &mut Trait’s. Read more

Returns the argument unchanged.

Creates Self using data from the given World
Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.
Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more