pub struct App {
pub world: World,
pub runner: Box<dyn Fn(App) + 'static, Global>,
pub schedule: Schedule,
/* private fields */
}
Expand description
Containers 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.
Apps are constructed with the builder pattern.
Example
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.
See Schedule::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 App where
S: Stage,
pub fn add_stage<S>(&mut self, label: impl StageLabel, stage: S) -> &mut App where
S: Stage,
pub fn add_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
pub fn add_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
pub fn add_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
pub fn add_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
pub fn add_startup_stage<S>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
pub fn add_startup_stage<S>(
&mut self,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
Adds a Stage
with the given label
to the last position of the
startup schedule.
Example
app.add_startup_stage("my_startup_stage", SystemStage::parallel());
pub fn add_startup_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
pub fn add_startup_stage_after<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
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.
Example
app.add_startup_stage_after(
StartupStage::Startup,
"my_startup_stage",
SystemStage::parallel()
);
pub fn add_startup_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
S: Stage,
pub fn add_startup_stage_before<S>(
&mut self,
target: impl StageLabel,
label: impl StageLabel,
stage: S
) -> &mut App where
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.
Example
app.add_startup_stage_before(
StartupStage::Startup,
"my_startup_stage",
SystemStage::parallel()
);
pub fn stage<T, F>(&mut self, label: impl StageLabel, func: F) -> &mut App where
T: Stage,
F: FnOnce(&mut T) -> &mut T,
pub fn stage<T, F>(&mut self, label: impl StageLabel, func: F) -> &mut App where
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 Schedule::stage
for more details.
Example
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.
Example
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.
Example
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 for every frame, see
add_system
. - For adding a system to specific stage, see
add_system_to_stage
.
Example
fn my_startup_system(_commands: Commands) {
println!("My startup system");
}
App::new()
.add_startup_system(my_startup_system.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
Example
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.
Example
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.
Example
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 App where
T: StateData,
pub fn add_state<T>(&mut self, initial: T) -> &mut App where
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 App where
T: StateData,
pub fn add_state_to_stage<T>(
&mut self,
stage: impl StageLabel,
initial: T
) -> &mut App where
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.
Example
let app = App::empty().add_default_stages();
pub fn insert_resource<T>(&mut self, resource: T) -> &mut App where
T: Resource,
pub fn insert_resource<T>(&mut self, resource: T) -> &mut App where
T: 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. Resources must be added to Bevy Apps
before using them. This happens with insert_resource
.
See also init_resource
for resources that implement Default
or FromWorld
.
Example
struct MyCounter {
counter: usize,
}
App::new()
.insert_resource(MyCounter { counter: 0 });
pub fn insert_non_send_resource<T>(&mut self, resource: T) -> &mut App where
T: 'static,
pub fn insert_non_send_resource<T>(&mut self, resource: T) -> &mut App where
T: '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 must
be non-send.
Example
struct MyCounter {
counter: usize,
}
App::new()
.insert_non_send_resource(MyCounter { counter: 0 });
pub fn init_resource<R>(&mut self) -> &mut App where
R: 'static + FromWorld + Send + Sync,
pub fn init_resource<R>(&mut self) -> &mut App where
R: 'static + FromWorld + Send + Sync,
Initialize a resource in the current App
, if it does not exist yet
If the resource already exists, nothing happens.
Adds a resource that implements Default
or FromWorld
trait.
Example
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 App where
R: 'static + FromWorld,
pub fn init_non_send_resource<R>(&mut self) -> &mut App where
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 responsibility of the runner
function to provide it.
The runner function is usually not set manually, but by Bevy integrated plugins (e.g. winit plugin).
Example
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 App where
T: Plugin,
pub fn add_plugin<T>(&mut self, plugin: T) -> &mut App where
T: Plugin,
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
.
Example
App::new().add_plugin(bevy_log::LogPlugin::default());
pub fn add_plugins<T>(&mut self, group: T) -> &mut App where
T: PluginGroup,
pub fn add_plugins<T>(&mut self, group: T) -> &mut App where
T: PluginGroup,
Adds a group of plugins
Bevy plugins can be grouped into a set of plugins. Bevy provides
built-in PluginGroups
that provide core engine functionality.
The plugin groups available by default are DefaultPlugins
and MinimalPlugins
.
Example
App::new()
.add_plugins(MinimalPlugins);
pub fn add_plugins_with<T, F>(&mut self, group: T, func: F) -> &mut App where
T: PluginGroup,
F: FnOnce(&mut PluginGroupBuilder) -> &mut PluginGroupBuilder,
pub fn add_plugins_with<T, F>(&mut self, group: T, func: F) -> &mut App where
T: PluginGroup,
F: FnOnce(&mut PluginGroupBuilder) -> &mut PluginGroupBuilder,
Adds a group of plugins with an initializer method
Can be used to add a group of plugins, where the group is modified before insertion into Bevy application. For example, you can add extra plugins at a specific place in the plugin group, or deactivate specific plugins while keeping the rest.
Example
App::new()
.add_plugins_with(DefaultPlugins, |group| {
group.add_before::<bevy_log::LogPlugin, _>(MyOwnPlugin)
});
pub fn register_type<T>(&mut self) -> &mut App where
T: GetTypeRegistration,
pub fn register_type<T>(&mut self) -> &mut App where
T: GetTypeRegistration,
Adds the type T
to the type registry resource.
pub fn add_sub_app(
&mut self,
label: impl AppLabel,
app: App,
f: impl Fn(&mut World, &mut App) + 'static
) -> &mut App
pub fn add_sub_app(
&mut self,
label: impl AppLabel,
app: App,
f: 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
Retrieves a “sub app” stored inside this App. This will panic if the sub app does not exist.
pub fn get_sub_app_mut(
&mut self,
label: impl AppLabel
) -> Result<&mut App, impl AppLabel>
pub fn get_sub_app_mut(
&mut self,
label: impl AppLabel
) -> Result<&mut App, impl AppLabel>
Trait Implementations
impl AddAsset for App
impl AddAsset for App
pub fn add_asset<T>(&mut self) -> &mut App where
T: Asset,
pub fn init_asset_loader<T>(&mut self) -> &mut App where
T: AssetLoader + FromWorld,
pub fn add_asset_loader<T>(&mut self, loader: T) -> &mut App where
T: AssetLoader,
impl AddRenderCommand for App
impl AddRenderCommand for App
pub fn add_render_command<P, C>(&mut self) -> &mut App where
P: PhaseItem,
C: 'static + RenderCommand<P> + Send + Sync,
<<C as RenderCommand<P>>::Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
pub fn add_render_command<P, C>(&mut self) -> &mut App where
P: PhaseItem,
C: 'static + RenderCommand<P> + Send + Sync,
<<C as RenderCommand<P>>::Param as SystemParam>::Fetch: ReadOnlySystemParamFetch,
Adds the 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
sourceimpl<T> BorrowMut<T> for T where
T: ?Sized,
impl<T> BorrowMut<T> for T where
T: ?Sized,
const: unstable · sourcepub fn borrow_mut(&mut self) -> &mut T
pub fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
impl<T> Downcast for T where
T: Any,
impl<T> Downcast for T where
T: Any,
pub fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>ⓘNotable traits for Box<F, A>impl<F, A> Future for Box<F, A> where
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;
pub fn into_any(self: Box<T, Global>) -> Box<dyn Any + 'static, Global>ⓘNotable traits for Box<F, A>impl<F, A> Future for Box<F, A> where
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;
F: Future + Unpin + ?Sized,
A: Allocator + 'static, type Output = <F as Future>::Output;impl<I, A> Iterator for Box<I, A> where
I: Iterator + ?Sized,
A: Allocator, type Item = <I as Iterator>::Item;
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
pub fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
pub fn into_any_rc(self: Rc<T>) -> Rc<dyn Any + 'static>
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
pub fn as_any(&self) -> &(dyn Any + 'static)
pub fn as_any(&self) -> &(dyn Any + 'static)
Convert &Trait
(where Trait: Downcast
) to &Any
. This is needed since Rust cannot
generate &Any
’s vtable from &Trait
’s. Read more
pub fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
pub fn as_any_mut(&mut self) -> &mut (dyn Any + 'static)
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
impl<T> FromWorld for T where
T: Default,
impl<T> FromWorld for T where
T: Default,
pub fn from_world(_world: &mut World) -> T
pub fn from_world(_world: &mut World) -> T
Creates Self
using data from the given World
sourceimpl<T> Instrument for T
impl<T> Instrument for T
sourcefn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn instrument(self, span: Span) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
sourcefn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
fn in_current_span(self) -> Instrumented<Self>ⓘNotable traits for Instrumented<T>impl<T> Future for Instrumented<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
impl<V, T> VZip<V> for T where
V: MultiLane<T>,
pub fn vzip(self) -> V
sourceimpl<T> WithSubscriber for T
impl<T> WithSubscriber for T
sourcefn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
where
S: Into<Dispatch>,
T: Future, type Output = <T as Future>::Output;
Attaches the provided Subscriber
to this type, returning a
WithDispatch
wrapper. Read more
sourcefn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
fn with_current_subscriber(self) -> WithDispatch<Self>ⓘNotable traits for WithDispatch<T>impl<T> Future for WithDispatch<T> where
T: Future, type Output = <T as Future>::Output;
T: Future, type Output = <T as Future>::Output;
Attaches the current default Subscriber
to this type, returning a
WithDispatch
wrapper. Read more