Struct RanimApp 

pub struct RanimApp(App);

A project with plugin construction finalized.

Produced by RanimAppExt::build, which runs bevy’s plugin finish and cleanup exactly once. CLI and canvas/interactive preview hosts consume this project and may install render sub-apps into it. Offline render workers instead receive a selected Scene and its rendering configuration. This wrapper is no longer a plugin-construction target.

Tuple Fields

0: App

Implementations

impl RanimApp

pub fn into_inner(self) -> App

Consume the wrapper, returning the inner bevy app.

Methods from Deref<Target = App>

pub fn update(&mut self)

Runs the default schedules of all sub-apps (starting with the “main” app) once.

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.

pub fn set_runner( &mut self, f: impl FnOnce(App) -> AppExit + 'static, ) -> &mut App

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);

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.

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.

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.

pub fn add_systems<M>( &mut self, schedule: impl ScheduleLabel, systems: impl IntoScheduleConfigs<Box<dyn System<Out = (), In = ()>>, M>, ) -> &mut App

Adds one or more systems to the given schedule in this app’s [Schedules].

Examples

app.add_systems(Update, (system_a, system_b, system_c));
app.add_systems(Update, (system_a, system_b).run_if(should_run));

pub fn remove_systems_in_set<M>( &mut self, schedule: impl ScheduleLabel, set: impl IntoSystemSet<M>, policy: ScheduleCleanupPolicy, ) -> Result<usize, ScheduleError>

Removes all systems in a [SystemSet]. This will cause the schedule to be rebuilt when the schedule is run again and can be slow. A [ScheduleError] is returned if the schedule needs to be [Schedule::initialize]’d or the set is not found.

Note that this can remove all systems of a type if you pass the system to this function as systems implicitly create a set based on the system type.

Example

// add the system
app.add_systems(Update, system_a);

// remove the system
app.remove_systems_in_set(Update, system_a, ScheduleCleanupPolicy::RemoveSystemsOnly);

pub fn register_system<I, O, M>( &mut self, system: impl IntoSystem<I, O, M> + 'static, ) -> SystemId<I, O>

where I: SystemInput + 'static, O: 'static,

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.

pub fn register_tracked_system<I, O, M>( &mut self, system: impl IntoSystem<I, O, M> + 'static, ) -> SystemHandle<I, O>

where I: SystemInput + 'static, O: 'static,

Registers a system and returns a tracked SystemHandle so it can later be called by [World::run_system]. The system entity will be automatically queued for despawn when the last clone of the returned handle is dropped.

See [World::register_tracked_system] for more details.

pub fn configure_sets<M>( &mut self, schedule: impl ScheduleLabel, sets: impl IntoScheduleConfigs<Interned<dyn SystemSet>, M>, ) -> &mut App

Configures a collection of system sets in the provided schedule, adding any sets that do not exist.

pub fn add_message<M>(&mut self) -> &mut App

where M: Message,

Initializes [Message] handling for T by inserting a message queue resource ([Messages::<T>]).

See [Messages] for information on how to define messages.

Examples

app.add_message::<MyMessage>();

pub fn insert_resource<R>(&mut self, resource: R) -> &mut App

where R: Resource,

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 });

pub fn init_resource<R>(&mut self) -> &mut App

where R: Resource + FromWorld,

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>();

pub fn insert_non_send<R>(&mut self, resource: R) -> &mut App

where R: 'static,

Inserts the !Send data into the app, overwriting any existing data of the same type.

There is also an init_non_send for !Send data that implement Default

Examples

struct MyCounter {
    counter: usize,
}

App::new()
    .insert_non_send(MyCounter { counter: 0 });

pub fn init_non_send<R>(&mut self) -> &mut App

where R: 'static + FromWorld,

Inserts the !Send data 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.

pub fn is_plugin_added<T>(&self) -> bool

where T: Plugin,

Returns true if the Plugin has already been added.

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;

pub fn add_plugins<M>(&mut self, plugins: impl Plugins<M>) -> &mut App

Installs a Plugin collection.

Bevy prioritizes modularity as a core principle. All engine features are implemented as plugins, even the complex ones like rendering.

Plugins can be grouped into a set by using a PluginGroup.

There are built-in PluginGroups that provide core engine functionality. The PluginGroups 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 Plugins by using a tuple over Plugins and PluginGroups. 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.

pub fn register_required_components<T, R>(&mut self) -> &mut App

where T: Component, R: Component + Default,

Registers the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The Default constructor will be used for the creation of R. If a custom constructor is desired, use App::register_required_components_with instead.

For the non-panicking version, see App::try_register_required_components.

Note that requirements must currently be registered before T is inserted into the world for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.

Panics

Panics if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// Register B as required by A and C as required by B.
app.register_required_components::<A, B>();
app.register_required_components::<B, C>();

fn setup(mut commands: Commands) {
    // This will implicitly also insert B and C with their Default constructors.
    commands.spawn(A);
}

fn validate(query: Option<Single<(&A, &B, &C)>>) {
    let (a, b, c) = query.unwrap().into_inner();
    assert_eq!(b, &B(0));
    assert_eq!(c, &C(0));
}

pub fn register_required_components_with<T, R>( &mut self, constructor: impl Fn() -> R + 'static, ) -> &mut App

where T: Component, R: Component,

Registers the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The given constructor will be used for the creation of R. If a Default constructor is desired, use App::register_required_components instead.

For the non-panicking version, see App::try_register_required_components_with.

Note that requirements must currently be registered before T is inserted into the world for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.

Panics

Panics if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// Register B and C as required by A and C as required by B.
// A requiring C directly will overwrite the indirect requirement through B.
app.register_required_components::<A, B>();
app.register_required_components_with::<B, C>(|| C(1));
app.register_required_components_with::<A, C>(|| C(2));

fn setup(mut commands: Commands) {
    // This will implicitly also insert B with its Default constructor and C
    // with the custom constructor defined by A.
    commands.spawn(A);
}

fn validate(query: Option<Single<(&A, &B, &C)>>) {
    let (a, b, c) = query.unwrap().into_inner();
    assert_eq!(b, &B(0));
    assert_eq!(c, &C(2));
}

pub fn try_register_required_components<T, R>( &mut self, ) -> Result<(), RequiredComponentsError>

where T: Component, R: Component + Default,

Tries to register the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The Default constructor will be used for the creation of R. If a custom constructor is desired, use App::register_required_components_with instead.

For the panicking version, see App::register_required_components.

Note that requirements must currently be registered before T is inserted into the world for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.

Errors

Returns a [RequiredComponentsError] if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// Register B as required by A and C as required by B.
app.register_required_components::<A, B>();
app.register_required_components::<B, C>();

// Duplicate registration! This will fail.
assert!(app.try_register_required_components::<A, B>().is_err());

fn setup(mut commands: Commands) {
    // This will implicitly also insert B and C with their Default constructors.
    commands.spawn(A);
}

fn validate(query: Option<Single<(&A, &B, &C)>>) {
    let (a, b, c) = query.unwrap().into_inner();
    assert_eq!(b, &B(0));
    assert_eq!(c, &C(0));
}

pub fn try_register_required_components_with<T, R>( &mut self, constructor: impl Fn() -> R + 'static, ) -> Result<(), RequiredComponentsError>

where T: Component, R: Component,

Tries to register the given component R as a required component for T.

When T is added to an entity, R and its own required components will also be added if R was not already provided. The given constructor will be used for the creation of R. If a Default constructor is desired, use App::register_required_components instead.

For the panicking version, see App::register_required_components_with.

Note that requirements must currently be registered before T is inserted into the world for the first time. Commonly, this is done in plugins. This limitation may be fixed in the future.

Errors

Returns a [RequiredComponentsError] if R is already a directly required component for T, or if T has ever been added on an entity before the registration.

Indirect requirements through other components are allowed. In those cases, any existing requirements will only be overwritten if the new requirement is more specific.

Example

#[derive(Component)]
struct A;

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct B(usize);

#[derive(Component, Default, PartialEq, Eq, Debug)]
struct C(u32);

// Register B and C as required by A and C as required by B.
// A requiring C directly will overwrite the indirect requirement through B.
app.register_required_components::<A, B>();
app.register_required_components_with::<B, C>(|| C(1));
app.register_required_components_with::<A, C>(|| C(2));

// Duplicate registration! Even if the constructors were different, this would fail.
assert!(app.try_register_required_components_with::<B, C>(|| C(1)).is_err());

fn setup(mut commands: Commands) {
    // This will implicitly also insert B with its Default constructor and C
    // with the custom constructor defined by A.
    commands.spawn(A);
}

fn validate(query: Option<Single<(&A, &B, &C)>>) {
    let (a, b, c) = query.unwrap().into_inner();
    assert_eq!(b, &B(0));
    assert_eq!(c, &C(2));
}

pub fn register_disabling_component<C>(&mut self)

where C: Component,

Registers a component type as “disabling”, using default query filters to exclude entities with the component from queries.

Warning

As discussed in the module docs, this can have performance implications, as well as create interoperability issues, and should be used with caution.

pub fn world(&self) -> &World

Returns a reference to the main [SubApp]’s [World]. This is the same as calling app.main().world().

pub fn world_mut(&mut self) -> &mut World

Returns a mutable reference to the main [SubApp]’s [World]. This is the same as calling app.main_mut().world_mut().

pub fn main(&self) -> &SubApp

Returns a reference to the main [SubApp].

pub fn main_mut(&mut self) -> &mut SubApp

Returns a mutable reference to the main [SubApp].

pub fn sub_apps(&self) -> &SubApps

Returns a reference to the [SubApps] collection.

pub fn sub_apps_mut(&mut self) -> &mut SubApps

Returns a mutable reference to the [SubApps] collection.

pub fn sub_app(&self, label: impl AppLabel) -> &SubApp

Returns a reference to the [SubApp] with the given label.

Panics

Panics if the [SubApp] doesn’t exist.

pub fn sub_app_mut(&mut self, label: impl AppLabel) -> &mut SubApp

Returns a reference to the [SubApp] with the given label.

Panics

Panics if the [SubApp] doesn’t exist.

pub fn get_sub_app(&self, label: impl AppLabel) -> Option<&SubApp>

Returns a reference to the [SubApp] with the given label, if it exists.

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.

pub fn insert_sub_app(&mut self, label: impl AppLabel, sub_app: SubApp)

Inserts a [SubApp] with the given label.

pub fn remove_sub_app(&mut self, label: impl AppLabel) -> Option<SubApp>

Removes the [SubApp] with the given label, if it exists.

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.

pub fn add_schedule(&mut self, schedule: Schedule) -> &mut App

Inserts a new schedule under the provided label, overwriting any existing schedule with the same label.

pub fn init_schedule(&mut self, label: impl ScheduleLabel) -> &mut App

Initializes an empty schedule under the provided label, if it does not exist.

See add_schedule to insert an existing schedule.

pub fn get_schedule(&self, label: impl ScheduleLabel) -> Option<&Schedule>

Returns a reference to the [Schedule] with the provided label if it exists.

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.

pub fn edit_schedule( &mut self, label: impl ScheduleLabel, f: impl FnMut(&mut Schedule), ) -> &mut App

Runs function f with the [Schedule] associated with label.

Note: This will create the schedule if it does not already exist.

pub fn configure_schedules( &mut self, schedule_build_settings: ScheduleBuildSettings, ) -> &mut App

Applies the provided [ScheduleBuildSettings] to all schedules.

This mutates all currently present schedules, but does not apply to any custom schedules that might be added in the future.

pub fn allow_ambiguous_component<T>(&mut self) -> &mut App

where T: Component,

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();

pub fn allow_ambiguous_resource<T>(&mut self) -> &mut App

where T: Resource,

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();

pub fn ignore_ambiguity<M1, M2, S1, S2>( &mut self, schedule: impl ScheduleLabel, a: S1, b: S2, ) -> &mut App

where 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.

pub fn should_exit(&self) -> Option<AppExit>

Attempts to determine if an [AppExit] was raised since the last update.

Will attempt to return the first Error it encounters. This should be called after every update() otherwise you risk dropping possible [AppExit] events.

pub fn add_observer<M>(&mut self, observer: impl IntoObserver<M>) -> &mut App

Spawns an [Observer] entity, which will watch for and respond to the given event.

observer can be any system whose first parameter is [On].

Examples

app.add_observer(|event: On<Party>, friends: Query<Entity, With<Friend>>, mut commands: Commands| {
    if event.friends_allowed {
        for entity in friends.iter() {
            commands.trigger(Invite { entity } );
        }
    }
});

pub fn get_error_handler(&self) -> Option<fn(BevyError, ErrorContext)>

Gets the error handler to set for new supapps.

Note that the error handler of existing subapps may differ.

pub fn set_error_handler( &mut self, handler: fn(BevyError, ErrorContext), ) -> &mut App

Set the fallback error handler for the all subapps (including the main one and future ones) that do not have one.

May only be called once and should be set by the application, not by libraries.

The handler will be called when an error is produced and not otherwise handled.

Panics

Panics if called multiple times.

Example

App::new()
    .set_error_handler(warn)
    .add_plugins(MyPlugins)
    .run();

Trait Implementations

impl Deref for RanimApp

type Target = App

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl DerefMut for RanimApp

fn deref_mut(&mut self) -> &mut Self::Target

Mutably dereferences the value.