pub struct App {
pub world: World,
pub runner: Box<dyn Fn(App)>,
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)>
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§
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.
This constructor should be used if you wish to provide a custom schedule, exit handling, cleanup, etc.
sourcepub 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.
sourcepub 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.
sourcepub fn add_stage<S: Stage>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut Self
pub fn add_stage<S: Stage>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut Self
sourcepub fn add_stage_after<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
pub fn add_stage_after<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
sourcepub fn add_stage_before<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
pub fn add_stage_before<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
sourcepub fn add_startup_stage<S: Stage>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut Self
pub fn add_startup_stage<S: Stage>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut Self
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());
sourcepub fn add_startup_stage_after<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
pub fn add_startup_stage_after<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
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()
);
sourcepub fn add_startup_stage_before<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
pub fn add_startup_stage_before<S: Stage>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut Self
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()
);
sourcepub fn stage<T: Stage, F: FnOnce(&mut T) -> &mut T>(
&mut self,
label: impl StageLabel,
func: F
) -> &mut Self
pub fn stage<T: Stage, F: FnOnce(&mut T) -> &mut T>(
&mut self,
label: impl StageLabel,
func: F
) -> &mut Self
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)
});
sourcepub fn add_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
pub fn add_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
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);
sourcepub fn add_system_set(&mut self, system_set: SystemSet) -> &mut Self
pub fn add_system_set(&mut self, system_set: SystemSet) -> &mut Self
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),
);
sourcepub fn add_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
pub fn add_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
sourcepub fn add_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut Self
pub fn add_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut Self
sourcepub fn add_startup_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
pub fn add_startup_system<Params>(
&mut self,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
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);
sourcepub fn add_startup_system_set(&mut self, system_set: SystemSet) -> &mut Self
pub fn add_startup_system_set(&mut self, system_set: SystemSet) -> &mut Self
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),
);
sourcepub fn add_startup_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
pub fn add_startup_system_to_stage<Params>(
&mut self,
stage_label: impl StageLabel,
system: impl IntoSystemDescriptor<Params>
) -> &mut Self
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);
sourcepub fn add_startup_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut Self
pub fn add_startup_system_set_to_stage(
&mut self,
stage_label: impl StageLabel,
system_set: SystemSet
) -> &mut Self
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),
);
sourcepub fn add_state<T>(&mut self, initial: T) -> &mut Selfwhere
T: StateData,
pub fn add_state<T>(&mut self, initial: T) -> &mut Selfwhere
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.
sourcepub fn add_state_to_stage<T>(
&mut self,
stage: impl StageLabel,
initial: T
) -> &mut Selfwhere
T: StateData,
pub fn add_state_to_stage<T>(
&mut self,
stage: impl StageLabel,
initial: T
) -> &mut Selfwhere
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.
sourcepub fn add_default_stages(&mut self) -> &mut Self
pub fn add_default_stages(&mut self) -> &mut Self
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();
sourcepub fn add_event<T>(&mut self) -> &mut Selfwhere
T: Event,
pub fn add_event<T>(&mut self) -> &mut Selfwhere
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>();
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 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 });
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 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 });
sourcepub fn init_resource<R: Resource + FromWorld>(&mut self) -> &mut Self
pub fn init_resource<R: Resource + FromWorld>(&mut self) -> &mut Self
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>();
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 set_runner(&mut self, run_fn: impl Fn(App) + 'static) -> &mut Self
pub fn set_runner(&mut self, run_fn: impl Fn(App) + 'static) -> &mut Self
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);
sourcepub fn add_plugin<T>(&mut self, plugin: T) -> &mut Selfwhere
T: Plugin,
pub fn add_plugin<T>(&mut self, plugin: T) -> &mut Selfwhere
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.
sourcepub 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.
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 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;
sourcepub fn add_plugins<T: PluginGroup>(&mut self, group: T) -> &mut Self
pub fn add_plugins<T: PluginGroup>(&mut self, group: T) -> &mut Self
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.
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(Reflect)]
#[reflect(Component, Serialize, Deserialize)] // will register ReflectComponent, ReflectSerialize, ReflectDeserialize
sourcepub fn register_type_data<T: Reflect + 'static, D: TypeData + FromType<T>>(
&mut self
) -> &mut Self
pub fn register_type_data<T: Reflect + 'static, D: TypeData + FromType<T>>(
&mut self
) -> &mut Self
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>();
sourcepub fn add_sub_app(
&mut self,
label: impl AppLabel,
app: App,
sub_app_runner: impl Fn(&mut World, &mut App) + 'static
) -> &mut Self
pub fn add_sub_app(
&mut self,
label: impl AppLabel,
app: App,
sub_app_runner: impl Fn(&mut World, &mut App) + 'static
) -> &mut Self
sourcepub fn sub_app_mut(&mut self, label: impl AppLabel) -> &mut App
pub fn sub_app_mut(&mut self, label: impl AppLabel) -> &mut App
sourcepub 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§
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§
source§impl<T> Downcast for Twhere
T: Any,
impl<T> Downcast for Twhere
T: Any,
source§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 moresource§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 moresource§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 moresource§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 moresource§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