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_app
s.
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 Stage
s set to be run in a linear order.
Implementations§
§impl App
impl App
pub 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.
pub fn empty() -> App
pub fn empty() -> App
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.
pub fn update(&mut self)
pub fn update(&mut self)
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.
pub fn run(&mut self)
pub fn run(&mut self)
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.
pub fn add_stage<S>(&mut self, label: impl StageLabel, stage: S) -> &mut Appwhere
S: Stage,
pub fn add_stage<S>(&mut self, label: impl StageLabel, stage: S) -> &mut Appwhere
S: Stage,
pub fn add_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
pub fn add_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
pub fn add_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
pub fn add_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
pub fn add_startup_stage<S>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
pub fn add_startup_stage<S>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
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());
pub fn add_startup_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
pub fn add_startup_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
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()
);
pub fn add_startup_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
pub fn add_startup_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Appwhere
S: Stage,
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()
);
pub fn stage<T, F>(&mut self, label: impl StageLabel, func: F) -> &mut Appwhere
T: Stage,
F: FnOnce(&mut T) -> &mut T,
pub fn stage<T, F>(&mut self, label: impl StageLabel, func: F) -> &mut Appwhere
T: Stage,
F: FnOnce(&mut T) -> &mut T,
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)
});
pub fn add_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
pub fn add_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
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);
pub fn add_system_set(&mut self, system_set: SystemSet) -> &mut App
pub fn add_system_set(&mut self, system_set: SystemSet) -> &mut App
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),
);
pub fn add_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
pub fn add_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
pub fn add_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut App
pub fn add_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut App
pub fn add_startup_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
pub fn add_startup_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
Adds a system to the startup stage of the app’s Schedule
.
- For adding a system that runs every frame, see
add_system
. - For adding a system to a specific stage, see
add_system_to_stage
.
Examples
fn my_startup_system(_commands: Commands) {
println!("My startup system");
}
App::new()
.add_startup_system(my_startup_system);
pub fn add_startup_system_set(&mut self, system_set: SystemSet) -> &mut App
pub fn add_startup_system_set(&mut self, system_set: SystemSet) -> &mut App
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),
);
pub fn add_startup_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
pub fn add_startup_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut App
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);
pub fn add_startup_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut App
pub fn add_startup_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut App
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),
);
pub fn add_state<T>(&mut self, initial: T) -> &mut Appwhere
T: StateData,
pub fn add_state<T>(&mut self, initial: T) -> &mut Appwhere
T: StateData,
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.
pub fn add_state_to_stage<T>(
&mut self,
stage: impl StageLabel,
initial: T
) -> &mut Appwhere
T: StateData,
pub fn add_state_to_stage<T>(
&mut self,
stage: impl StageLabel,
initial: T
) -> &mut Appwhere
T: StateData,
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.
pub fn add_default_stages(&mut self) -> &mut App
pub fn add_default_stages(&mut self) -> &mut App
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
enum
s.
Examples
let app = App::empty().add_default_stages();
pub fn add_event<T>(&mut self) -> &mut Appwhere
T: Event,
pub fn add_event<T>(&mut self) -> &mut Appwhere
T: Event,
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>();
pub fn insert_resource<R>(&mut self, resource: R) -> &mut Appwhere
R: Resource,
pub fn insert_resource<R>(&mut self, resource: R) -> &mut Appwhere
R: Resource,
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. Resource
s must be added to Bevy apps
before using them. This happens with insert_resource
.
See init_resource
for Resource
s that implement Default
or FromWorld
.
Examples
#[derive(Resource)]
struct MyCounter {
counter: usize,
}
App::new()
.insert_resource(MyCounter { counter: 0 });
pub fn insert_non_send_resource<R>(&mut self, resource: R) -> &mut Appwhere
R: 'static,
pub fn insert_non_send_resource<R>(&mut self, resource: R) -> &mut Appwhere
R: 'static,
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 });
pub fn init_resource<R>(&mut self) -> &mut Appwhere
R: Resource + FromWorld,
pub fn init_resource<R>(&mut self) -> &mut Appwhere
R: Resource + FromWorld,
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>();
pub fn init_non_send_resource<R>(&mut self) -> &mut Appwhere
R: 'static + FromWorld,
pub fn init_non_send_resource<R>(&mut self) -> &mut Appwhere
R: 'static + FromWorld,
pub fn set_runner(&mut self, run_fn: impl Fn(App) + 'static) -> &mut App
pub fn set_runner(&mut self, run_fn: impl Fn(App) + 'static) -> &mut App
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);
pub fn add_plugin<T>(&mut self, plugin: T) -> &mut Appwhere
T: Plugin,
pub fn add_plugin<T>(&mut self, plugin: T) -> &mut Appwhere
T: Plugin,
Adds a single Plugin
.
One of Bevy’s core principles is modularity. All Bevy engine features are implemented
as Plugin
s. This includes internal features like the renderer.
Bevy also provides a few sets of default Plugin
s. See add_plugins
.
Examples
App::new().add_plugin(bevy_log::LogPlugin::default());
Panics
Panics if the plugin was already added to the application.
pub fn is_plugin_added<T>(&self) -> boolwhere
T: Plugin,
pub fn is_plugin_added<T>(&self) -> boolwhere
T: Plugin,
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.
pub fn get_added_plugins<T>(&self) -> Vec<&T, Global> ⓘwhere
T: Plugin,
pub fn get_added_plugins<T>(&self) -> Vec<&T, Global> ⓘwhere
T: Plugin,
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;
pub fn add_plugins<T>(&mut self, group: T) -> &mut Appwhere
T: PluginGroup,
pub fn add_plugins<T>(&mut self, group: T) -> &mut Appwhere
T: PluginGroup,
Adds a group of Plugin
s.
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
.
Examples
App::new()
.add_plugins(MinimalPlugins);
Panics
Panics if one of the plugin in the group was already added to the application.
pub fn register_type<T>(&mut self) -> &mut Appwhere
T: GetTypeRegistration,
pub fn register_type<T>(&mut self) -> &mut Appwhere
T: GetTypeRegistration,
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
].
pub fn register_type_data<T, D>(&mut self) -> &mut Appwhere
T: 'static + Reflect,
D: TypeData + FromType<T>,
pub fn register_type_data<T, D>(&mut self) -> &mut Appwhere
T: 'static + Reflect,
D: TypeData + FromType<T>,
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
].
pub fn add_sub_app(
&mut self,
label: impl AppLabel,
app: App,
sub_app_runner: impl Fn(&mut World, &mut App) + 'static
) -> &mut App
pub fn add_sub_app(
&mut self,
label: impl AppLabel,
app: App,
sub_app_runner: impl Fn(&mut World, &mut App) + 'static
) -> &mut App
pub fn sub_app_mut(&mut self, label: impl AppLabel) -> &mut App
pub fn sub_app_mut(&mut self, label: impl AppLabel) -> &mut App
pub fn get_sub_app_mut(
&mut self,
label: impl AppLabel
) -> Result<&mut App, AppLabelId>
pub fn get_sub_app_mut(
&mut self,
label: impl AppLabel
) -> Result<&mut App, AppLabelId>
Trait Implementations§
§impl AddAsset for App
impl AddAsset for App
§fn add_asset<T>(&mut self) -> &mut Appwhere
T: Asset,
fn add_asset<T>(&mut self) -> &mut Appwhere
T: Asset,
T
as a supported asset in the application. Read more§fn register_asset_reflect<T>(&mut self) -> &mut Appwhere
T: Asset + Reflect + FromReflect + GetTypeRegistration,
fn register_asset_reflect<T>(&mut self) -> &mut Appwhere
T: Asset + Reflect + FromReflect + GetTypeRegistration,
T
using [App::register]
,
and adds ReflectAsset
type data to T
and ReflectHandle
type data to Handle<T>
in the type registry. Read more§fn add_debug_asset<T>(&mut self) -> &mut Appwhere
T: Clone + Asset,
fn add_debug_asset<T>(&mut self) -> &mut Appwhere
T: Clone + Asset,
T
as a supported internal asset in the application. Read more§fn init_asset_loader<T>(&mut self) -> &mut Appwhere
T: AssetLoader + FromWorld,
fn init_asset_loader<T>(&mut self) -> &mut Appwhere
T: AssetLoader + FromWorld,
T
using default values. Read more§fn init_debug_asset_loader<T>(&mut self) -> &mut Appwhere
T: AssetLoader + FromWorld,
fn init_debug_asset_loader<T>(&mut self) -> &mut Appwhere
T: AssetLoader + FromWorld,
T
for internal assets using default values. Read more§fn add_asset_loader<T>(&mut self, loader: T) -> &mut Appwhere
T: AssetLoader,
fn add_asset_loader<T>(&mut self, loader: T) -> &mut Appwhere
T: AssetLoader,
§impl AddRenderCommand for App
impl AddRenderCommand for App
§fn add_render_command<P, C>(&mut self) -> &mut Appwhere
P: PhaseItem,
C: 'static + RenderCommand<P> + Send + Sync,
<<C as RenderCommand<P>>::Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
fn add_render_command<P, C>(&mut self) -> &mut Appwhere
P: PhaseItem,
C: 'static + RenderCommand<P> + Send + Sync,
<<C as RenderCommand<P>>::Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
RenderCommand
for the specified RenderPhase
to the app.Auto Trait Implementations§
impl !RefUnwindSafe for App
impl !Send for App
impl !Sync for App
impl Unpin for App
impl !UnwindSafe for App
Blanket Implementations§
§impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
impl<T, U> AsBindGroupShaderType<U> for Twhere
U: ShaderType,
&'a T: for<'a> Into<U>,
§fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
fn as_bind_group_shader_type(&self, _images: &RenderAssets<Image>) -> U
T
ShaderType
for self
. When used in AsBindGroup
derives, it is safe to assume that all images in self
exist. Read more§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
§fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>
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§fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
Rc<Trait>
(where Trait: Downcast
) to Rc<Any>
. Rc<Any>
can then be
further downcast
into Rc<ConcreteType>
where ConcreteType
implements Trait
. Read more§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. Read more§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. Read more§impl<T> FromWorld for Twhere
T: Default,
impl<T> FromWorld for Twhere
T: Default,
§fn from_world(_world: &mut World) -> T
fn from_world(_world: &mut World) -> T
Self
using data from the given World