pub struct App {
pub world: World,
pub runner: Box<dyn Fn(App) + Send>,
pub default_schedule_label: BoxedScheduleLabel,
pub outer_schedule_label: BoxedScheduleLabel,
/* 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) + Send>
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
.
default_schedule_label: BoxedScheduleLabel
The schedule that systems are added to by default.
This is initially set to CoreSchedule::Main
.
outer_schedule_label: BoxedScheduleLabel
The schedule that controls the outer loop of schedule execution.
This is initially set to CoreSchedule::Outer
.
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.
This calls App::add_default_schedules
.
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 custom scheduling, 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 insert_sub_app
for more details.
The schedule run by this method is determined by the outer_schedule_label
field.
In normal usage, this is CoreSchedule::Outer
, which will run CoreSchedule::Startup
the first time the app is run, then CoreSchedule::Main
on every call of this method.
Panics
The active schedule of the app must be set before this method is called.
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.
run()
might not return
Calls to App::run()
might never return.
In simple and headless applications, one can expect that execution will
proceed, normally, after calling run()
but this is not the case for
windowed applications.
Windowed apps are typically driven by an event loop or message loop and some window-manager APIs expect programs to terminate when their primary window is closed and that event loop terminates – behaviour of processes that do not is often platform dependent or undocumented.
By default, Bevy uses the winit
crate for window creation. See
WinitSettings::return_from_run
for further discussion of this topic and for a mechanism to require that App::run()
does return – albeit one that carries its own caveats and disclaimers.
Panics
Panics if called from Plugin::build()
, because it would prevent other plugins to properly build.
sourcepub fn setup(&mut self)
pub fn setup(&mut self)
Run Plugin::setup
for each plugin. This is usually called by App::run
, but can
be useful for situations where you want to use App::update
.
sourcepub fn add_state<S: States>(&mut self) -> &mut Self
pub fn add_state<S: States>(&mut self) -> &mut Self
Adds State<S>
and NextState<S>
resources, OnEnter
and OnExit
schedules
for each state variant, an instance of apply_state_transition::<S>
in
CoreSet::StateTransitions
so that transitions happen before CoreSet::Update
and
a instance of run_enter_schedule::<S>
in CoreSet::StateTransitions
with a
run_once
condition to run the on enter schedule of the
initial state.
This also adds an OnUpdate
system set for each state variant,
which runs during CoreSet::Update
after the transitions are applied.
These system sets only run if the State<S>
resource matches the respective state variant.
If you would like to control how other systems run based on the current state,
you can emulate this behavior using the in_state
Condition
.
Note that you can also apply state transitions at other points in the schedule
by adding the apply_state_transition
system manually.
sourcepub fn add_system<M>(
&mut self,
system: impl IntoSystemAppConfig<M>
) -> &mut Self
pub fn add_system<M>( &mut self, system: impl IntoSystemAppConfig<M> ) -> &mut Self
Adds a system to the default system set and schedule of the app’s Schedules
.
Refer to the system module documentation to see how a system can be defined.
Examples
app.add_system(my_system);
sourcepub fn add_systems<M>(
&mut self,
systems: impl IntoSystemAppConfigs<M>
) -> &mut Self
pub fn add_systems<M>( &mut self, systems: impl IntoSystemAppConfigs<M> ) -> &mut Self
sourcepub fn add_startup_system<M>(
&mut self,
system: impl IntoSystemConfig<M>
) -> &mut Self
pub fn add_startup_system<M>( &mut self, system: impl IntoSystemConfig<M> ) -> &mut Self
Adds a system to CoreSchedule::Startup
.
These systems will run exactly once, at the start of the App
’s lifecycle.
To add a system that runs every frame, see add_system
.
Examples
fn my_startup_system(_commands: Commands) {
println!("My startup system");
}
App::new()
.add_startup_system(my_startup_system);
sourcepub fn add_startup_systems<M>(
&mut self,
systems: impl IntoSystemConfigs<M>
) -> &mut Self
pub fn add_startup_systems<M>( &mut self, systems: impl IntoSystemConfigs<M> ) -> &mut Self
Adds a collection of systems to CoreSchedule::Startup
.
Examples
app.add_startup_systems((
startup_system_a,
startup_system_b,
startup_system_c,
));
sourcepub fn configure_set(&mut self, set: impl IntoSystemSetConfig) -> &mut Self
pub fn configure_set(&mut self, set: impl IntoSystemSetConfig) -> &mut Self
Configures a system set in the default schedule, adding the set if it does not exist.
sourcepub fn configure_sets(&mut self, sets: impl IntoSystemSetConfigs) -> &mut Self
pub fn configure_sets(&mut self, sets: impl IntoSystemSetConfigs) -> &mut Self
Configures a collection of system sets in the default schedule, adding any sets that do not exist.
sourcepub fn add_default_schedules(&mut self) -> &mut Self
pub fn add_default_schedules(&mut self) -> &mut Self
Adds standardized schedules and labels to an App
.
Adding these schedules is necessary to make almost all core engine features work.
This is typically done implicitly by calling App::default
, which is in turn called by
App::new
.
The schedules added are defined in the CoreSchedule
enum,
and have a starting configuration defined by:
CoreSchedule::Outer
: usesCoreSchedule::outer_schedule
CoreSchedule::Startup
: usesStartupSet::base_schedule
CoreSchedule::Main
: usesCoreSet::base_schedule
CoreSchedule::FixedUpdate
: no starting configuration
Examples
use bevy_app::App;
use bevy_ecs::schedule::Schedules;
let app = App::empty()
.init_resource::<Schedules>()
.add_default_schedules()
.update();
sourcepub fn add_simple_outer_schedule(&mut self) -> &mut Self
pub fn add_simple_outer_schedule(&mut self) -> &mut Self
adds a single threaded outer schedule to the App
that just runs the main schedule
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 CoreSet::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 + Send) -> &mut Self
pub fn set_runner(&mut self, run_fn: impl Fn(App) + 'static + Send) -> &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 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>
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 an existing sub app into the app
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 a sub app from the app. Returns None
if the label doesn’t exist.
sourcepub fn add_schedule(
&mut self,
label: impl ScheduleLabel,
schedule: Schedule
) -> &mut Self
pub fn add_schedule( &mut self, label: impl ScheduleLabel, schedule: Schedule ) -> &mut Self
sourcepub fn init_schedule(&mut self, label: impl ScheduleLabel) -> &mut Self
pub fn init_schedule(&mut self, label: impl ScheduleLabel) -> &mut Self
Initializes a new empty schedule
to the App
under the provided label
if it does not exists.
See App::add_schedule
to pass in a pre-constructed schedule.
sourcepub fn get_schedule(&self, label: impl ScheduleLabel) -> Option<&Schedule>
pub fn get_schedule(&self, label: impl ScheduleLabel) -> Option<&Schedule>
Gets read-only access 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>
Gets read-write access to a 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
Applies the function to the Schedule
associated with label
.
Note: This will create the schedule if it does not already exist.
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
.source§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
.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