Struct SubApp

pub struct SubApp {
    pub update_schedule: Option<Interned<dyn ScheduleLabel>>,
    /* private fields */
}

A secondary application with its own World. These can run independently of each other.

These are useful for situations where certain processes (e.g. a render thread) need to be kept separate from the main application.

Example

#[derive(Resource, Default)]
struct Val(pub i32);

#[derive(Debug, Clone, Copy, Hash, PartialEq, Eq, AppLabel)]
struct ExampleApp;

// Create an app with a certain resource.
let mut app = App::new();
app.insert_resource(Val(10));

// Create a sub-app with the same resource and a single schedule.
let mut sub_app = SubApp::new();
sub_app.update_schedule = Some(Main.intern());
sub_app.insert_resource(Val(100));

// Setup an extract function to copy the resource's value in the main world.
sub_app.set_extract(|main_world, sub_world| {
    sub_world.resource_mut::<Val>().0 = main_world.resource::<Val>().0;
});

// Schedule a system that will verify extraction is working.
sub_app.add_systems(Main, |counter: Res<Val>| {
    // The value will be copied during extraction, so we should see 10 instead of 100.
    assert_eq!(counter.0, 10);
});

// Add the sub-app to the main app.
app.insert_sub_app(ExampleApp, sub_app);

// Update the application once (using the default runner).
app.run();

Fields

update_schedule: Option<Interned<dyn ScheduleLabel>>

The schedule that will be run by update.

Implementations

impl SubApp

pub fn new() -> SubApp

Returns a default, empty SubApp.

pub fn world(&self) -> &World

Returns a reference to the World.

Examples found in repository

tests/ecs/ambiguity_detection.rs (line 73)

fn count_ambiguities(sub_app: &SubApp) -> AmbiguitiesCount {
    let schedules = sub_app.world().resource::<Schedules>();
    let mut ambiguities = <HashMap<_, _>>::default();
    for (_, schedule) in schedules.iter() {
        let ambiguities_in_schedule = schedule.graph().conflicting_systems().len();
        ambiguities.insert(schedule.label(), ambiguities_in_schedule);
    }
    AmbiguitiesCount(ambiguities)
}

examples/shader/texture_binding_array.rs (line 50)

    fn finish(&self, app: &mut App) {
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };

        let render_device = render_app.world().resource::<RenderDevice>();

        // Check if the device support the required feature. If not, exit the example.
        // In a real application, you should setup a fallback for the missing feature
        if !render_device
            .features()
            .contains(WgpuFeatures::SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING)
        {
            error!(
                "Render device doesn't support feature \
SAMPLED_TEXTURE_AND_STORAGE_BUFFER_ARRAY_NON_UNIFORM_INDEXING, \
which is required for texture binding arrays"
            );
            exit(1);
        }
    }

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

Returns a mutable reference to the World.

Examples found in repository

tests/ecs/ambiguity_detection.rs (line 60)

fn configure_ambiguity_detection(sub_app: &mut SubApp) {
    let mut schedules = sub_app.world_mut().resource_mut::<Schedules>();
    for (_, schedule) in schedules.iter_mut() {
        schedule.set_build_settings(ScheduleBuildSettings {
            // NOTE: you can change this to `LogLevel::Ignore` to easily see the current number of ambiguities.
            ambiguity_detection: LogLevel::Warn,
            use_shortnames: false,
            ..default()
        });
    }
}

examples/shader/gpu_readback.rs (line 59)

    fn finish(&self, app: &mut App) {
        let render_app = app.sub_app_mut(RenderApp);
        render_app.init_resource::<ComputePipeline>().add_systems(
            Render,
            prepare_bind_group
                .in_set(RenderSet::PrepareBindGroups)
                // We don't need to recreate the bind group every frame
                .run_if(not(resource_exists::<GpuBufferBindGroup>)),
        );

        // Add the compute node as a top level node to the render graph
        // This means it will only execute once per frame
        render_app
            .world_mut()
            .resource_mut::<RenderGraph>()
            .add_node(ComputeNodeLabel, ComputeNode::default());
    }

examples/shader/compute_shader_game_of_life.rs (line 111)

    fn build(&self, app: &mut App) {
        // Extract the game of life image resource from the main world into the render world
        // for operation on by the compute shader and display on the sprite.
        app.add_plugins(ExtractResourcePlugin::<GameOfLifeImages>::default());
        let render_app = app.sub_app_mut(RenderApp);
        render_app.add_systems(
            Render,
            prepare_bind_group.in_set(RenderSet::PrepareBindGroups),
        );

        let mut render_graph = render_app.world_mut().resource_mut::<RenderGraph>();
        render_graph.add_node(GameOfLifeLabel, GameOfLifeNode::default());
        render_graph.add_node_edge(GameOfLifeLabel, bevy::render::graph::CameraDriverLabel);
    }

examples/app/headless_renderer.rs (line 210)

    fn build(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();

        let render_app = app
            .insert_resource(MainWorldReceiver(r))
            .sub_app_mut(RenderApp);

        let mut graph = render_app.world_mut().resource_mut::<RenderGraph>();
        graph.add_node(ImageCopy, ImageCopyDriver);
        graph.add_node_edge(bevy::render::graph::CameraDriverLabel, ImageCopy);

        render_app
            .insert_resource(RenderWorldSender(s))
            // Make ImageCopiers accessible in RenderWorld system and plugin
            .add_systems(ExtractSchedule, image_copy_extract)
            // Receives image data from buffer to channel
            // so we need to run it after the render graph is done
            .add_systems(Render, receive_image_from_buffer.after(RenderSet::Render));
    }

pub fn run_default_schedule(&mut self)

Runs the default schedule.

Does not clear internal trackers used for change detection.

pub fn update(&mut self)

Runs the default schedule and updates internal component trackers.

pub fn extract(&mut self, world: &mut World)

Extracts data from world into the app’s world using the registered extract method.

Note: There is no default extract method. Calling extract does nothing if set_extract has not been called.

pub fn set_extract<F>(&mut self, extract: F) -> &mut SubApp

where F: Fn(&mut World, &mut World) + Send + 'static,

Sets the method that will be called by extract.

The first argument is the World to extract data from, the second argument is the app World.

pub fn take_extract( &mut self, ) -> Option<Box<dyn Fn(&mut World, &mut World) + Send>>

Take the function that will be called by extract out of the app, if any was set, and replace it with None.

If you use Bevy, bevy_render will set a default extract function used to extract data from the main world into the render world as part of the Extract phase. In that case, you cannot replace it with your own function. Instead, take the Bevy default function with this, and install your own instead which calls the Bevy default.

let default_fn = app.take_extract();
app.set_extract(move |main, render| {
    // Do pre-extract custom logic
    // [...]

    // Call Bevy's default, which executes the Extract phase
    if let Some(f) = default_fn.as_ref() {
        f(main, render);
    }

    // Do post-extract custom logic
    // [...]
});

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

where R: Resource,

See App::insert_resource.

Examples found in repository

examples/app/headless_renderer.rs (line 215)

    fn build(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();

        let render_app = app
            .insert_resource(MainWorldReceiver(r))
            .sub_app_mut(RenderApp);

        let mut graph = render_app.world_mut().resource_mut::<RenderGraph>();
        graph.add_node(ImageCopy, ImageCopyDriver);
        graph.add_node_edge(bevy::render::graph::CameraDriverLabel, ImageCopy);

        render_app
            .insert_resource(RenderWorldSender(s))
            // Make ImageCopiers accessible in RenderWorld system and plugin
            .add_systems(ExtractSchedule, image_copy_extract)
            // Receives image data from buffer to channel
            // so we need to run it after the render graph is done
            .add_systems(Render, receive_image_from_buffer.after(RenderSet::Render));
    }

examples/3d/occlusion_culling.rs (line 265)

    fn finish(&self, app: &mut App) {
        // Create the `SavedIndirectParameters` resource that we're going to use
        // to communicate between the thread that the GPU-to-CPU readback
        // callback runs on and the main application threads. This resource is
        // atomically reference counted. We store one reference to the
        // `SavedIndirectParameters` in the main app and another reference in
        // the render app.
        let saved_indirect_parameters = SavedIndirectParameters::from_world(app.world_mut());
        app.insert_resource(saved_indirect_parameters.clone());

        // Fetch the render app.
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };

        render_app
            // Insert another reference to the `SavedIndirectParameters`.
            .insert_resource(saved_indirect_parameters);
    }

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

where R: Resource + FromWorld,

See App::init_resource.

Examples found in repository

examples/shader/compute_shader_game_of_life.rs (line 118)

    fn finish(&self, app: &mut App) {
        let render_app = app.sub_app_mut(RenderApp);
        render_app.init_resource::<GameOfLifePipeline>();
    }

examples/shader/custom_post_processing.rs (line 109)

    fn finish(&self, app: &mut App) {
        // We need to get the render app from the main app
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };

        render_app
            // Initialize the pipeline
            .init_resource::<PostProcessPipeline>();
    }

examples/shader/custom_shader_instancing.rs (line 103)

    fn build(&self, app: &mut App) {
        app.add_plugins(ExtractComponentPlugin::<InstanceMaterialData>::default());
        app.sub_app_mut(RenderApp)
            .add_render_command::<Transparent3d, DrawCustom>()
            .init_resource::<SpecializedMeshPipelines<CustomPipeline>>()
            .add_systems(
                Render,
                (
                    queue_custom.in_set(RenderSet::QueueMeshes),
                    prepare_instance_buffers.in_set(RenderSet::PrepareResources),
                ),
            );
    }

    fn finish(&self, app: &mut App) {
        app.sub_app_mut(RenderApp).init_resource::<CustomPipeline>();
    }

examples/shader/gpu_readback.rs (line 48)

    fn finish(&self, app: &mut App) {
        let render_app = app.sub_app_mut(RenderApp);
        render_app.init_resource::<ComputePipeline>().add_systems(
            Render,
            prepare_bind_group
                .in_set(RenderSet::PrepareBindGroups)
                // We don't need to recreate the bind group every frame
                .run_if(not(resource_exists::<GpuBufferBindGroup>)),
        );

        // Add the compute node as a top level node to the render graph
        // This means it will only execute once per frame
        render_app
            .world_mut()
            .resource_mut::<RenderGraph>()
            .add_node(ComputeNodeLabel, ComputeNode::default());
    }

examples/shader/specialized_mesh_pipeline.rs (line 118)

    fn build(&self, app: &mut App) {
        app.add_plugins(ExtractComponentPlugin::<CustomRenderedEntity>::default());

        // We make sure to add these to the render app, not the main app.
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };
        render_app
            // This is needed to tell bevy about your custom pipeline
            .init_resource::<SpecializedMeshPipelines<CustomMeshPipeline>>()
            // We need to use a custom draw command so we need to register it
            .add_render_command::<Opaque3d, DrawSpecializedPipelineCommands>()
            .add_systems(Render, queue_custom_mesh_pipeline.in_set(RenderSet::Queue));
    }

    fn finish(&self, app: &mut App) {
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };
        // Creating this pipeline needs the RenderDevice and RenderQueue
        // which are only available once rendering plugins are initialized.
        render_app.init_resource::<CustomMeshPipeline>();
    }

examples/shader/custom_phase_item.rs (line 178)

fn main() {
    let mut app = App::new();
    app.add_plugins(DefaultPlugins)
        .add_plugins(ExtractComponentPlugin::<CustomRenderedEntity>::default())
        .add_systems(Startup, setup);

    // We make sure to add these to the render app, not the main app.
    app.get_sub_app_mut(RenderApp)
        .unwrap()
        .init_resource::<CustomPhasePipeline>()
        .init_resource::<SpecializedRenderPipelines<CustomPhasePipeline>>()
        .add_render_command::<Opaque3d, DrawCustomPhaseItemCommands>()
        .add_systems(
            Render,
            prepare_custom_phase_item_buffers.in_set(RenderSet::Prepare),
        )
        .add_systems(Render, queue_custom_phase_item.in_set(RenderSet::Queue));

    app.run();
}

Additional examples can be found in:

• examples/2d/mesh2d_manual.rs
• examples/shader/custom_render_phase.rs
• examples/3d/occlusion_culling.rs

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

See App::add_systems.

Examples found in repository

examples/stress_tests/many_lights.rs (line 161)

    fn build(&self, app: &mut App) {
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };

        render_app.add_systems(Render, print_visible_light_count.in_set(RenderSet::Prepare));
    }

examples/games/loading_screen.rs (line 292)

        fn build(&self, app: &mut App) {
            app.insert_resource(PipelinesReady::default());

            // In order to gain access to the pipelines status, we have to
            // go into the `RenderApp`, grab the resource from the main App
            // and then update the pipelines status from there.
            // Writing between these Apps can only be done through the
            // `ExtractSchedule`.
            app.sub_app_mut(RenderApp)
                .add_systems(ExtractSchedule, update_pipelines_ready);
        }

examples/shader/custom_shader_instancing.rs (lines 104-110)

    fn build(&self, app: &mut App) {
        app.add_plugins(ExtractComponentPlugin::<InstanceMaterialData>::default());
        app.sub_app_mut(RenderApp)
            .add_render_command::<Transparent3d, DrawCustom>()
            .init_resource::<SpecializedMeshPipelines<CustomPipeline>>()
            .add_systems(
                Render,
                (
                    queue_custom.in_set(RenderSet::QueueMeshes),
                    prepare_instance_buffers.in_set(RenderSet::PrepareResources),
                ),
            );
    }

examples/shader/gpu_readback.rs (lines 48-54)

    fn finish(&self, app: &mut App) {
        let render_app = app.sub_app_mut(RenderApp);
        render_app.init_resource::<ComputePipeline>().add_systems(
            Render,
            prepare_bind_group
                .in_set(RenderSet::PrepareBindGroups)
                // We don't need to recreate the bind group every frame
                .run_if(not(resource_exists::<GpuBufferBindGroup>)),
        );

        // Add the compute node as a top level node to the render graph
        // This means it will only execute once per frame
        render_app
            .world_mut()
            .resource_mut::<RenderGraph>()
            .add_node(ComputeNodeLabel, ComputeNode::default());
    }

examples/shader/specialized_mesh_pipeline.rs (line 121)

    fn build(&self, app: &mut App) {
        app.add_plugins(ExtractComponentPlugin::<CustomRenderedEntity>::default());

        // We make sure to add these to the render app, not the main app.
        let Some(render_app) = app.get_sub_app_mut(RenderApp) else {
            return;
        };
        render_app
            // This is needed to tell bevy about your custom pipeline
            .init_resource::<SpecializedMeshPipelines<CustomMeshPipeline>>()
            // We need to use a custom draw command so we need to register it
            .add_render_command::<Opaque3d, DrawSpecializedPipelineCommands>()
            .add_systems(Render, queue_custom_mesh_pipeline.in_set(RenderSet::Queue));
    }

examples/shader/compute_shader_game_of_life.rs (lines 106-109)

    fn build(&self, app: &mut App) {
        // Extract the game of life image resource from the main world into the render world
        // for operation on by the compute shader and display on the sprite.
        app.add_plugins(ExtractResourcePlugin::<GameOfLifeImages>::default());
        let render_app = app.sub_app_mut(RenderApp);
        render_app.add_systems(
            Render,
            prepare_bind_group.in_set(RenderSet::PrepareBindGroups),
        );

        let mut render_graph = render_app.world_mut().resource_mut::<RenderGraph>();
        render_graph.add_node(GameOfLifeLabel, GameOfLifeNode::default());
        render_graph.add_node_edge(GameOfLifeLabel, bevy::render::graph::CameraDriverLabel);
    }

Additional examples can be found in:

• examples/shader/custom_phase_item.rs
• examples/app/headless_renderer.rs
• examples/2d/mesh2d_manual.rs
• examples/shader/custom_render_phase.rs
• examples/3d/occlusion_culling.rs

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,

See App::register_system.

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

See App::configure_sets.

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

See App::add_schedule.

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

See App::init_schedule.

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

See App::get_schedule.

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

See App::get_schedule_mut.

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

See App::edit_schedule.

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

See App::configure_schedules.

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

where T: Component,

See App::allow_ambiguous_component.

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

where T: Resource,

See App::allow_ambiguous_resource.

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

where S1: IntoSystemSet<M1>, S2: IntoSystemSet<M2>,

See App::ignore_ambiguity.

pub fn add_event<T>(&mut self) -> &mut SubApp

where T: Event,

See App::add_event.

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

See App::add_plugins.

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

where T: Plugin,

See App::is_plugin_added.

pub fn get_added_plugins<T>(&self) -> Vec<&T>

where T: Plugin,

See App::get_added_plugins.

pub fn plugins_state(&mut self) -> PluginsState

Return the state of plugins.

pub fn finish(&mut self)

Runs Plugin::finish for each plugin.

pub fn cleanup(&mut self)

Runs Plugin::cleanup for each plugin.

pub fn register_type<T>(&mut self) -> &mut SubApp

where T: GetTypeRegistration,

See App::register_type.

pub fn register_type_data<T, D>(&mut self) -> &mut SubApp

where T: Reflect + TypePath, D: TypeData + FromType<T>,

See App::register_type_data.

pub fn register_function<F, Marker>(&mut self, function: F) -> &mut SubApp

where F: IntoFunction<'static, Marker> + 'static,

See App::register_function.

pub fn register_function_with_name<F, Marker>( &mut self, name: impl Into<Cow<'static, str>>, function: F, ) -> &mut SubApp

where F: IntoFunction<'static, Marker> + 'static,

See App::register_function_with_name.

Trait Implementations

impl AddRenderCommand for SubApp

fn add_render_command<P, C>(&mut self) -> &mut SubApp

where P: PhaseItem, C: RenderCommand<P> + Send + Sync + 'static, <C as RenderCommand<P>>::Param: ReadOnlySystemParam,

Adds the RenderCommand for the specified render phase to the app.

impl AppExtStates for SubApp

fn init_state<S>(&mut self) -> &mut SubApp

where S: FreelyMutableState + FromWorld,

Initializes a State with standard starting values.

fn insert_state<S>(&mut self, state: S) -> &mut SubApp

where S: FreelyMutableState,

Inserts a specific State to the current App and overrides any State previously added of the same type.

fn add_computed_state<S>(&mut self) -> &mut SubApp

where S: ComputedStates,

Sets up a type implementing ComputedStates.

fn add_sub_state<S>(&mut self) -> &mut SubApp

where S: SubStates,

Sets up a type implementing SubStates.

fn enable_state_scoped_entities<S>(&mut self) -> &mut SubApp

where S: States,

Enable state-scoped entity clearing for state S.

fn register_type_state<S>(&mut self) -> &mut SubApp

where S: States + FromReflect + GetTypeRegistration + Typed,

Registers the state type T using App::register_type, and adds ReflectState type data to T in the type registry.

fn register_type_mutable_state<S>(&mut self) -> &mut SubApp

where S: FreelyMutableState + FromReflect + GetTypeRegistration + Typed,

Registers the state type T using App::register_type, and adds crate::reflect::ReflectState and crate::reflect::ReflectFreelyMutableState type data to T in the type registry.

impl Debug for SubApp

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for SubApp

fn default() -> SubApp

Returns the “default value” for a type.

impl RegisterDiagnostic for SubApp

fn register_diagnostic(&mut self, diagnostic: Diagnostic) -> &mut SubApp

Register a new Diagnostic with an App.

impl RenderGraphApp for SubApp

fn add_render_graph_node<T>( &mut self, sub_graph: impl RenderSubGraph, node_label: impl RenderLabel, ) -> &mut SubApp

where T: Node + FromWorld,

Add a Node to the RenderGraph:

fn add_render_graph_edges<const N: usize>( &mut self, sub_graph: impl RenderSubGraph, edges: impl IntoRenderNodeArray<N>, ) -> &mut SubApp

Automatically add the required node edges based on the given ordering

fn add_render_graph_edge( &mut self, sub_graph: impl RenderSubGraph, output_node: impl RenderLabel, input_node: impl RenderLabel, ) -> &mut SubApp

Add node edge to the specified graph

fn add_render_sub_graph( &mut self, sub_graph: impl RenderSubGraph, ) -> &mut SubApp

impl StateScopedEventsAppExt for SubApp

fn add_state_scoped_event<E>( &mut self, state: impl FreelyMutableState, ) -> &mut SubApp

where E: Event,

Adds an Event that is automatically cleaned up when leaving the specified state.