Struct bevy::app::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.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

examples/shader/texture_binding_array.rs (line 46)

    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

examples/shader/compute_shader_game_of_life.rs (line 113)

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

    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/shader/gpu_readback.rs (line 88)

    fn finish(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();
        app.insert_resource(MainWorldReceiver(r));

        let render_app = app.sub_app_mut(RenderApp);
        render_app
            .insert_resource(RenderWorldSender(s))
            .init_resource::<ComputePipeline>()
            .init_resource::<Buffers>()
            .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>)),
                    // We need to run it after the render graph is done
                    // because this needs to happen after submit()
                    map_and_read_buffer.after(RenderSet::Render),
                ),
            );

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

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

    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/shader/gpu_readback.rs (line 69)

    fn finish(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();
        app.insert_resource(MainWorldReceiver(r));

        let render_app = app.sub_app_mut(RenderApp);
        render_app
            .insert_resource(RenderWorldSender(s))
            .init_resource::<ComputePipeline>()
            .init_resource::<Buffers>()
            .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>)),
                    // We need to run it after the render graph is done
                    // because this needs to happen after submit()
                    map_and_read_buffer.after(RenderSet::Render),
                ),
            );

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

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

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

examples/shader/post_processing.rs (line 107)

    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/shader_instancing.rs (line 87)

    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/2d/mesh2d_manual.rs (line 293)

    fn build(&self, app: &mut App) {
        // Load our custom shader
        let mut shaders = app.world_mut().resource_mut::<Assets<Shader>>();
        shaders.insert(
            &COLORED_MESH2D_SHADER_HANDLE,
            Shader::from_wgsl(COLORED_MESH2D_SHADER, file!()),
        );

        // Register our custom draw function, and add our render systems
        app.get_sub_app_mut(RenderApp)
            .unwrap()
            .add_render_command::<Transparent2d, DrawColoredMesh2d>()
            .init_resource::<SpecializedRenderPipelines<ColoredMesh2dPipeline>>()
            .init_resource::<RenderColoredMesh2dInstances>()
            .add_systems(
                ExtractSchedule,
                extract_colored_mesh2d.after(extract_mesh2d),
            )
            .add_systems(Render, queue_colored_mesh2d.in_set(RenderSet::QueueMeshes));
    }

    fn finish(&self, app: &mut App) {
        // Register our custom pipeline
        app.get_sub_app_mut(RenderApp)
            .unwrap()
            .init_resource::<ColoredMesh2dPipeline>();
    }

examples/shader/custom_phase_item.rs (line 187)

fn main() {
    let mut app = App::new();
    app.add_plugins(DefaultPlugins)
        .add_plugins(ExtractComponentPlugin::<CustomRenderedEntity>::default())
        .add_systems(Startup, setup)
        // Make sure to tell Bevy to check our entity for visibility. Bevy won't
        // do this by default, for efficiency reasons.
        .add_systems(
            PostUpdate,
            view::check_visibility::<WithCustomRenderedEntity>
                .in_set(VisibilitySystems::CheckVisibility),
        );

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

examples/shader/gpu_readback.rs (line 70)

    fn finish(&self, app: &mut App) {
        let (s, r) = crossbeam_channel::unbounded();
        app.insert_resource(MainWorldReceiver(r));

        let render_app = app.sub_app_mut(RenderApp);
        render_app
            .insert_resource(RenderWorldSender(s))
            .init_resource::<ComputePipeline>()
            .init_resource::<Buffers>()
            .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>)),
                    // We need to run it after the render graph is done
                    // because this needs to happen after submit()
                    map_and_read_buffer.after(RenderSet::Render),
                ),
            );

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

pub fn add_systems<M>( &mut self, schedule: impl ScheduleLabel, systems: impl IntoSystemConfigs<M>, ) -> &mut SubApp

See App::add_systems.

Examples found in repository

examples/stress_tests/many_lights.rs (line 164)

    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/shader/shader_instancing.rs (lines 88-94)

    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/games/loading_screen.rs (line 336)

        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(bevy::render::RenderApp)
                .add_systems(ExtractSchedule, update_pipelines_ready);
        }

examples/shader/compute_shader_game_of_life.rs (lines 108-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 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/2d/mesh2d_manual.rs (lines 295-298)

    fn build(&self, app: &mut App) {
        // Load our custom shader
        let mut shaders = app.world_mut().resource_mut::<Assets<Shader>>();
        shaders.insert(
            &COLORED_MESH2D_SHADER_HANDLE,
            Shader::from_wgsl(COLORED_MESH2D_SHADER, file!()),
        );

        // Register our custom draw function, and add our render systems
        app.get_sub_app_mut(RenderApp)
            .unwrap()
            .add_render_command::<Transparent2d, DrawColoredMesh2d>()
            .init_resource::<SpecializedRenderPipelines<ColoredMesh2dPipeline>>()
            .init_resource::<RenderColoredMesh2dInstances>()
            .add_systems(
                ExtractSchedule,
                extract_colored_mesh2d.after(extract_mesh2d),
            )
            .add_systems(Render, queue_colored_mesh2d.in_set(RenderSet::QueueMeshes));
    }

Additional examples can be found in:

• examples/shader/custom_phase_item.rs
• examples/shader/gpu_readback.rs

pub fn register_system<I, O, M, S>(&mut self, system: S) -> SystemId<I, O>

where I: 'static, O: 'static, S: IntoSystem<I, O, M> + 'static,

See App::register_system.

pub fn configure_sets( &mut self, schedule: impl ScheduleLabel, sets: impl IntoSystemSetConfigs, ) -> &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,

Available on crate feature bevy_reflect only.

See App::register_type.

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

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

Available on crate feature bevy_reflect only.

See App::register_type_data.

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.

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