pub struct App { /* private fields */ }
Expand description
App
is the primary API for writing user applications. It automates the setup of a
standard lifecycle and provides interface glue for plugins.
A single App
can contain multiple SubApp
instances, but App
methods only affect
the “main” one. To access a particular SubApp
, use get_sub_app
or get_sub_app_mut
.
§Examples
Here is a simple “Hello World” Bevy app:
fn main() {
App::new()
.add_systems(Update, hello_world_system)
.run();
}
fn hello_world_system() {
println!("hello world");
}
Implementations§
source§impl App
impl App
sourcepub fn new() -> App
pub fn new() -> App
Creates a new App
with some default structure to enable core engine features.
This is the preferred constructor for most use cases.
sourcepub fn empty() -> App
pub fn empty() -> App
Creates a new empty App
with minimal default configuration.
Use this constructor if you want to customize scheduling, exit handling, cleanup, etc.
sourcepub fn update(&mut self)
pub fn update(&mut self)
Runs the default schedules of all sub-apps (starting with the “main” app) once.
sourcepub fn run(&mut self) -> AppExit
pub fn run(&mut self) -> AppExit
Runs the App
by calling its runner.
This will (re)build the App
first. For general usage, see the example on the item
level documentation.
§Caveats
Calls to App::run()
will never return on iOS and Web.
Headless apps can generally expect this method to return control to the caller when it completes, but that is not the case for windowed apps. Windowed apps are typically driven by an event loop and some platforms expect the program to terminate when the event loop ends.
By default, Bevy uses the winit
crate for window creation.
§Panics
Panics if not all plugins have been built.
sourcepub fn set_runner(
&mut self,
f: impl FnOnce(App) -> AppExit + 'static
) -> &mut Self
pub fn set_runner( &mut self, f: impl FnOnce(App) -> AppExit + 'static ) -> &mut Self
Sets the function that will be called when the app is run.
The runner function f
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) -> AppExit {
loop {
println!("In main loop");
app.update();
if let Some(exit) = app.should_exit() {
return exit;
}
}
}
App::new()
.set_runner(my_runner);
sourcepub fn plugins_state(&mut self) -> PluginsState
pub fn plugins_state(&mut self) -> PluginsState
Returns the state of all plugins. This is usually called by the event loop, but can be
useful for situations where you want to use App::update
.
sourcepub fn finish(&mut self)
pub fn finish(&mut self)
Runs Plugin::finish
for each plugin. This is usually called by the event loop once all
plugins are ready, but can be useful for situations where you want to use App::update
.
sourcepub fn cleanup(&mut self)
pub fn cleanup(&mut self)
Runs Plugin::cleanup
for each plugin. This is usually called by the event loop after
App::finish
, but can be useful for situations where you want to use App::update
.
sourcepub fn add_systems<M>(
&mut self,
schedule: impl ScheduleLabel,
systems: impl IntoSystemConfigs<M>
) -> &mut Self
pub fn add_systems<M>( &mut self, schedule: impl ScheduleLabel, systems: impl IntoSystemConfigs<M> ) -> &mut Self
sourcepub fn register_system<I: 'static, O: 'static, M, S: IntoSystem<I, O, M> + 'static>(
&mut self,
system: S
) -> SystemId<I, O>
pub fn register_system<I: 'static, O: 'static, M, S: IntoSystem<I, O, M> + 'static>( &mut self, system: S ) -> SystemId<I, O>
Registers a system and returns a SystemId
so it can later be called by World::run_system
.
It’s possible to register the same systems more than once, they’ll be stored separately.
This is different from adding systems to a Schedule
with App::add_systems
,
because the SystemId
that is returned can be used anywhere in the World
to run the associated system.
This allows for running systems in a push-based fashion.
Using a Schedule
is still preferred for most cases
due to its better performance and ability to run non-conflicting systems simultaneously.
sourcepub fn configure_sets(
&mut self,
schedule: impl ScheduleLabel,
sets: impl IntoSystemSetConfigs
) -> &mut Self
pub fn configure_sets( &mut self, schedule: impl ScheduleLabel, sets: impl IntoSystemSetConfigs ) -> &mut Self
Configures a collection of system sets in the provided schedule, adding any sets that do not exist.
sourcepub fn add_event<T>(&mut self) -> &mut Selfwhere
T: Event,
pub fn add_event<T>(&mut self) -> &mut Selfwhere
T: Event,
Initializes T
event handling by inserting an event queue resource (Events::<T>
)
and scheduling an event_update_system
in First
.
See Events
for information on how to define events.
§Examples
app.add_event::<MyEvent>();
sourcepub fn insert_resource<R: Resource>(&mut self, resource: R) -> &mut Self
pub fn insert_resource<R: Resource>(&mut self, resource: R) -> &mut Self
Inserts the Resource
into the app, overwriting any existing resource of the same type.
There is also an init_resource
for resources that have
Default
or FromWorld
implementations.
§Examples
#[derive(Resource)]
struct MyCounter {
counter: usize,
}
App::new()
.insert_resource(MyCounter { counter: 0 });
sourcepub fn init_resource<R: Resource + FromWorld>(&mut self) -> &mut Self
pub fn init_resource<R: Resource + FromWorld>(&mut self) -> &mut Self
Inserts the Resource
, initialized with its default value, into the app,
if there is no existing instance of R
.
R
must implement FromWorld
.
If R
implements Default
, FromWorld
will be automatically implemented and
initialize the Resource
with Default::default
.
§Examples
#[derive(Resource)]
struct MyCounter {
counter: usize,
}
impl Default for MyCounter {
fn default() -> MyCounter {
MyCounter {
counter: 100
}
}
}
App::new()
.init_resource::<MyCounter>();
sourcepub fn insert_non_send_resource<R: 'static>(&mut self, resource: R) -> &mut Self
pub fn insert_non_send_resource<R: 'static>(&mut self, resource: R) -> &mut Self
Inserts the !Send
resource into the app, overwriting any existing resource
of the same type.
There is also an init_non_send_resource
for
resources that implement Default
§Examples
struct MyCounter {
counter: usize,
}
App::new()
.insert_non_send_resource(MyCounter { counter: 0 });
sourcepub fn init_non_send_resource<R: 'static + FromWorld>(&mut self) -> &mut Self
pub fn init_non_send_resource<R: 'static + FromWorld>(&mut self) -> &mut Self
sourcepub fn is_plugin_added<T>(&self) -> boolwhere
T: Plugin,
pub fn is_plugin_added<T>(&self) -> boolwhere
T: Plugin,
Returns true
if the Plugin
has already been added.
sourcepub fn get_added_plugins<T>(&self) -> Vec<&T>where
T: Plugin,
pub fn get_added_plugins<T>(&self) -> Vec<&T>where
T: Plugin,
Returns a vector of references to all plugins of type T
that have been added.
This can be used to read the settings of any existing plugins.
This vector will be empty 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;
sourcepub fn add_plugins<M>(&mut self, plugins: impl Plugins<M>) -> &mut Self
pub fn add_plugins<M>(&mut self, plugins: impl Plugins<M>) -> &mut Self
Installs a Plugin
collection.
Bevy prioritizes modularity as a core principle. All engine features are implemented as plugins, even the complex ones like rendering.
Plugin
s can be grouped into a set by using a PluginGroup
.
There are built-in PluginGroup
s that provide core engine functionality.
The PluginGroup
s 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
.
You can also specify a group of Plugin
s by using a tuple over Plugin
s and
PluginGroup
s. See Plugins
for more details.
§Examples
App::new()
.add_plugins(MinimalPlugins);
App::new()
.add_plugins((MinimalPlugins, LogPlugin));
§Panics
Panics if one of the plugins had already been added to the application.
sourcepub fn register_type<T: GetTypeRegistration>(&mut self) -> &mut Self
pub fn register_type<T: GetTypeRegistration>(&mut self) -> &mut Self
Registers the type T
in the TypeRegistry
resource,
adding reflect data as specified in the Reflect
derive:
#[derive(Component, Serialize, Deserialize, Reflect)]
#[reflect(Component, Serialize, Deserialize)] // will register ReflectComponent, ReflectSerialize, ReflectDeserialize
See bevy_reflect::TypeRegistry::register
for more information.
sourcepub fn register_type_data<T: Reflect + TypePath, D: TypeData + FromType<T>>(
&mut self
) -> &mut Self
pub fn register_type_data<T: Reflect + TypePath, D: TypeData + FromType<T>>( &mut self ) -> &mut Self
Associates type data D
with type T
in the TypeRegistry
resource.
Most of the time 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>();
sourcepub fn sub_app_mut(&mut self, label: impl AppLabel) -> &mut SubApp
pub fn sub_app_mut(&mut self, label: impl AppLabel) -> &mut SubApp
sourcepub fn get_sub_app(&self, label: impl AppLabel) -> Option<&SubApp>
pub fn get_sub_app(&self, label: impl AppLabel) -> Option<&SubApp>
Returns a reference to the SubApp
with the given label, if it exists.
sourcepub fn get_sub_app_mut(&mut self, label: impl AppLabel) -> Option<&mut SubApp>
pub fn get_sub_app_mut(&mut self, label: impl AppLabel) -> Option<&mut SubApp>
Returns a mutable reference to the SubApp
with the given label, if it exists.
sourcepub fn insert_sub_app(&mut self, label: impl AppLabel, sub_app: SubApp)
pub fn insert_sub_app(&mut self, label: impl AppLabel, sub_app: SubApp)
Inserts a SubApp
with the given label.
sourcepub fn remove_sub_app(&mut self, label: impl AppLabel) -> Option<SubApp>
pub fn remove_sub_app(&mut self, label: impl AppLabel) -> Option<SubApp>
Removes the SubApp
with the given label, if it exists.
sourcepub fn update_sub_app_by_label(&mut self, label: impl AppLabel)
pub fn update_sub_app_by_label(&mut self, label: impl AppLabel)
Extract data from the main world into the SubApp
with the given label and perform an update if it exists.
sourcepub fn add_schedule(&mut self, schedule: Schedule) -> &mut Self
pub fn add_schedule(&mut self, schedule: Schedule) -> &mut Self
Inserts a new schedule
under the provided label
, overwriting any existing
schedule with the same label.
sourcepub fn init_schedule(&mut self, label: impl ScheduleLabel) -> &mut Self
pub fn init_schedule(&mut self, label: impl ScheduleLabel) -> &mut Self
Initializes an empty schedule
under the provided label
, if it does not exist.
See add_schedule
to insert an existing schedule.
sourcepub fn get_schedule(&self, label: impl ScheduleLabel) -> Option<&Schedule>
pub fn get_schedule(&self, label: impl ScheduleLabel) -> Option<&Schedule>
Returns a reference to the Schedule
with the provided label
if it exists.
sourcepub fn get_schedule_mut(
&mut self,
label: impl ScheduleLabel
) -> Option<&mut Schedule>
pub fn get_schedule_mut( &mut self, label: impl ScheduleLabel ) -> Option<&mut Schedule>
Returns a mutable reference to the Schedule
with the provided label
if it exists.
sourcepub fn edit_schedule(
&mut self,
label: impl ScheduleLabel,
f: impl FnMut(&mut Schedule)
) -> &mut Self
pub fn edit_schedule( &mut self, label: impl ScheduleLabel, f: impl FnMut(&mut Schedule) ) -> &mut Self
Runs function f
with the Schedule
associated with label
.
Note: This will create the schedule if it does not already exist.
sourcepub fn configure_schedules(
&mut self,
schedule_build_settings: ScheduleBuildSettings
) -> &mut Self
pub fn configure_schedules( &mut self, schedule_build_settings: ScheduleBuildSettings ) -> &mut Self
Applies the provided ScheduleBuildSettings
to all schedules.
sourcepub fn allow_ambiguous_component<T: Component>(&mut self) -> &mut Self
pub fn allow_ambiguous_component<T: Component>(&mut self) -> &mut Self
When doing ambiguity checking this
ignores systems that are ambiguous on Component
T.
This settings only applies to the main world. To apply this to other worlds call the corresponding method on World
§Example
#[derive(Component)]
struct A;
// these systems are ambiguous on A
fn system_1(_: Query<&mut A>) {}
fn system_2(_: Query<&A>) {}
let mut app = App::new();
app.configure_schedules(ScheduleBuildSettings {
ambiguity_detection: LogLevel::Error,
..default()
});
app.add_systems(Update, ( system_1, system_2 ));
app.allow_ambiguous_component::<A>();
// running the app does not error.
app.update();
sourcepub fn allow_ambiguous_resource<T: Resource>(&mut self) -> &mut Self
pub fn allow_ambiguous_resource<T: Resource>(&mut self) -> &mut Self
When doing ambiguity checking this
ignores systems that are ambiguous on Resource
T.
This settings only applies to the main world. To apply this to other worlds call the corresponding method on World
§Example
#[derive(Resource)]
struct R;
// these systems are ambiguous on R
fn system_1(_: ResMut<R>) {}
fn system_2(_: Res<R>) {}
let mut app = App::new();
app.configure_schedules(ScheduleBuildSettings {
ambiguity_detection: LogLevel::Error,
..default()
});
app.insert_resource(R);
app.add_systems(Update, ( system_1, system_2 ));
app.allow_ambiguous_resource::<R>();
// running the app does not error.
app.update();
sourcepub fn ignore_ambiguity<M1, M2, S1, S2>(
&mut self,
schedule: impl ScheduleLabel,
a: S1,
b: S2
) -> &mut Selfwhere
S1: IntoSystemSet<M1>,
S2: IntoSystemSet<M2>,
pub fn ignore_ambiguity<M1, M2, S1, S2>(
&mut self,
schedule: impl ScheduleLabel,
a: S1,
b: S2
) -> &mut Selfwhere
S1: IntoSystemSet<M1>,
S2: IntoSystemSet<M2>,
Suppress warnings and errors that would result from systems in these sets having ambiguities
(conflicting access but indeterminate order) with systems in set
.
When possible, do this directly in the .add_systems(Update, a.ambiguous_with(b))
call.
However, sometimes two independent plugins A
and B
are reported as ambiguous, which you
can only suppress as the consumer of both.
sourcepub fn should_exit(&self) -> Option<AppExit>
pub fn should_exit(&self) -> Option<AppExit>
Trait Implementations§
Auto Trait Implementations§
impl !Freeze for App
impl !RefUnwindSafe for App
impl !Send for App
impl !Sync for App
impl Unpin for App
impl !UnwindSafe for App
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§fn into_any(self: Box<T>) -> Box<dyn Any>
fn into_any(self: Box<T>) -> Box<dyn Any>
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
.source§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
.source§fn as_any(&self) -> &(dyn Any + 'static)
fn as_any(&self) -> &(dyn Any + 'static)
&Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s.source§fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
&mut Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &mut Any
’s vtable from &mut Trait
’s.source§impl<T> FromWorld for Twhere
T: Default,
impl<T> FromWorld for Twhere
T: Default,
source§fn from_world(_world: &mut World) -> T
fn from_world(_world: &mut World) -> T
Self
using data from the given World
.