Vendor dependencies for 0.3.0 release

vendor/bevy/examples/app/custom_loop.rs

@@ -0,0 +1,49 @@
+//! This example demonstrates you can create a custom runner (to update an app manually). It reads
+//! lines from stdin and prints them from within the ecs.
+
+use bevy::{app::AppExit, prelude::*};
+use std::io;
+
+#[derive(Resource)]
+struct Input(String);
+
+fn my_runner(mut app: App) -> AppExit {
+    // Finalize plugin building, including running any necessary clean-up.
+    // This is normally completed by the default runner.
+    app.finish();
+    app.cleanup();
+
+    println!("Type stuff into the console");
+    for line in io::stdin().lines() {
+        {
+            let mut input = app.world_mut().resource_mut::<Input>();
+            input.0 = line.unwrap();
+        }
+        app.update();
+
+        if let Some(exit) = app.should_exit() {
+            return exit;
+        }
+    }
+
+    AppExit::Success
+}
+
+fn print_system(input: Res<Input>) {
+    println!("You typed: {}", input.0);
+}
+
+fn exit_system(input: Res<Input>, mut exit_event: EventWriter<AppExit>) {
+    if input.0 == "exit" {
+        exit_event.write(AppExit::Success);
+    }
+}
+
+// AppExit implements `Termination` so we can return it from main.
+fn main() -> AppExit {
+    App::new()
+        .insert_resource(Input(String::new()))
+        .set_runner(my_runner)
+        .add_systems(Update, (print_system, exit_system))
+        .run()
+}

vendor/bevy/examples/app/drag_and_drop.rs

@@ -0,0 +1,16 @@
+//! An example that shows how to handle drag and drop of files in an app.
+
+use bevy::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins)
+        .add_systems(Update, file_drag_and_drop_system)
+        .run();
+}
+
+fn file_drag_and_drop_system(mut events: EventReader<FileDragAndDrop>) {
+    for event in events.read() {
+        info!("{:?}", event);
+    }
+}

vendor/bevy/examples/app/empty.rs

@@ -0,0 +1,7 @@
+//! An empty application (does nothing)
+
+use bevy::prelude::*;
+
+fn main() {
+    App::new().run();
+}

vendor/bevy/examples/app/empty_defaults.rs

@@ -0,0 +1,7 @@
+//! An empty application with default plugins.
+
+use bevy::prelude::*;
+
+fn main() {
+    App::new().add_plugins(DefaultPlugins).run();
+}

vendor/bevy/examples/app/headless.rs

@@ -0,0 +1,62 @@
+//! This example shows how to configure the `ScheduleRunnerPlugin` to run your
+//! application without windowing. You can completely remove rendering / windowing
+//! Plugin code from bevy by making your import look like this in your Cargo.toml.
+//!
+//! ```toml
+//! [dependencies]
+//! bevy = { version = "*", default-features = false }
+//! # replace "*" with the most recent version of bevy
+//! ```
+//!
+//! And then enabling the features you need.
+//! See the full list: <https://docs.rs/bevy/latest/bevy/#cargo-features>
+use bevy::{app::ScheduleRunnerPlugin, log::LogPlugin, prelude::*};
+use core::time::Duration;
+
+fn main() {
+    if cfg!(feature = "bevy_window") {
+        println!("This example is running with the bevy_window feature enabled and will not run headless.");
+        println!("Disable the default features and rerun the example to run headless.");
+        println!("To do so, run:");
+        println!();
+        println!("    cargo run --example headless --no-default-features");
+        return;
+    }
+
+    // This app runs once
+    App::new()
+        .add_plugins(DefaultPlugins.set(ScheduleRunnerPlugin::run_once()))
+        .add_systems(Update, hello_world_system)
+        .run();
+
+    // This app loops forever at 60 fps
+    App::new()
+        .add_plugins(
+            DefaultPlugins
+                .set(ScheduleRunnerPlugin::run_loop(Duration::from_secs_f64(
+                    1.0 / 60.0,
+                )))
+                // The log and ctrl+c plugin can only be registered once globally,
+                // which means we need to disable it here, because it was already registered with the
+                // app that runs once.
+                .disable::<LogPlugin>(),
+        )
+        .add_systems(Update, counter)
+        .run();
+}
+
+fn hello_world_system() {
+    println!("hello world");
+}
+
+fn counter(mut state: Local<CounterState>) {
+    if state.count % 60 == 0 {
+        println!("{}", state.count);
+    }
+    state.count += 1;
+}
+
+#[derive(Default)]
+struct CounterState {
+    count: u32,
+}

vendor/bevy/examples/app/headless_renderer.rs

@@ -0,0 +1,547 @@
+//! This example illustrates how to make headless renderer
+//! derived from: <https://sotrh.github.io/learn-wgpu/showcase/windowless/#a-triangle-without-a-window>
+//! It follows this steps:
+//! 1. Render from camera to gpu-image render target
+//! 2. Copy from gpu image to buffer using `ImageCopyDriver` node in `RenderGraph`
+//! 3. Copy from buffer to channel using `receive_image_from_buffer` after `RenderSet::Render`
+//! 4. Save from channel to random named file using `scene::update` at `PostUpdate` in `MainWorld`
+//! 5. Exit if `single_image` setting is set
+
+use bevy::{
+    app::{AppExit, ScheduleRunnerPlugin},
+    core_pipeline::tonemapping::Tonemapping,
+    image::TextureFormatPixelInfo,
+    prelude::*,
+    render::{
+        camera::RenderTarget,
+        render_asset::{RenderAssetUsages, RenderAssets},
+        render_graph::{self, NodeRunError, RenderGraph, RenderGraphContext, RenderLabel},
+        render_resource::{
+            Buffer, BufferDescriptor, BufferUsages, CommandEncoderDescriptor, Extent3d, Maintain,
+            MapMode, TexelCopyBufferInfo, TexelCopyBufferLayout, TextureDimension, TextureFormat,
+            TextureUsages,
+        },
+        renderer::{RenderContext, RenderDevice, RenderQueue},
+        Extract, Render, RenderApp, RenderSet,
+    },
+    winit::WinitPlugin,
+};
+use crossbeam_channel::{Receiver, Sender};
+use std::{
+    ops::{Deref, DerefMut},
+    path::PathBuf,
+    sync::{
+        atomic::{AtomicBool, Ordering},
+        Arc,
+    },
+    time::Duration,
+};
+
+// To communicate between the main world and the render world we need a channel.
+// Since the main world and render world run in parallel, there will always be a frame of latency
+// between the data sent from the render world and the data received in the main world
+//
+// frame n => render world sends data through the channel at the end of the frame
+// frame n + 1 => main world receives the data
+//
+// Receiver and Sender are kept in resources because there is single camera and single target
+// That's why there is single images role, if you want to differentiate images
+// from different cameras, you should keep Receiver in ImageCopier and Sender in ImageToSave
+// or send some id with data
+
+/// This will receive asynchronously any data sent from the render world
+#[derive(Resource, Deref)]
+struct MainWorldReceiver(Receiver<Vec<u8>>);
+
+/// This will send asynchronously any data to the main world
+#[derive(Resource, Deref)]
+struct RenderWorldSender(Sender<Vec<u8>>);
+
+// Parameters of resulting image
+struct AppConfig {
+    width: u32,
+    height: u32,
+    single_image: bool,
+}
+
+fn main() {
+    let config = AppConfig {
+        width: 1920,
+        height: 1080,
+        single_image: true,
+    };
+
+    // setup frame capture
+    App::new()
+        .insert_resource(SceneController::new(
+            config.width,
+            config.height,
+            config.single_image,
+        ))
+        .insert_resource(ClearColor(Color::srgb_u8(0, 0, 0)))
+        .add_plugins(
+            DefaultPlugins
+                .set(ImagePlugin::default_nearest())
+                // Not strictly necessary, as the inclusion of ScheduleRunnerPlugin below
+                // replaces the bevy_winit app runner and so a window is never created.
+                .set(WindowPlugin {
+                    primary_window: None,
+                    ..default()
+                })
+                // WinitPlugin will panic in environments without a display server.
+                .disable::<WinitPlugin>(),
+        )
+        .add_plugins(ImageCopyPlugin)
+        // headless frame capture
+        .add_plugins(CaptureFramePlugin)
+        // ScheduleRunnerPlugin provides an alternative to the default bevy_winit app runner, which
+        // manages the loop without creating a window.
+        .add_plugins(ScheduleRunnerPlugin::run_loop(
+            // Run 60 times per second.
+            Duration::from_secs_f64(1.0 / 60.0),
+        ))
+        .init_resource::<SceneController>()
+        .add_systems(Startup, setup)
+        .run();
+}
+
+/// Capture image settings and state
+#[derive(Debug, Default, Resource)]
+struct SceneController {
+    state: SceneState,
+    name: String,
+    width: u32,
+    height: u32,
+    single_image: bool,
+}
+
+impl SceneController {
+    pub fn new(width: u32, height: u32, single_image: bool) -> SceneController {
+        SceneController {
+            state: SceneState::BuildScene,
+            name: String::from(""),
+            width,
+            height,
+            single_image,
+        }
+    }
+}
+
+/// Capture image state
+#[derive(Debug, Default)]
+enum SceneState {
+    #[default]
+    // State before any rendering
+    BuildScene,
+    // Rendering state, stores the number of frames remaining before saving the image
+    Render(u32),
+}
+
+fn setup(
+    mut commands: Commands,
+    mut meshes: ResMut<Assets<Mesh>>,
+    mut materials: ResMut<Assets<StandardMaterial>>,
+    mut images: ResMut<Assets<Image>>,
+    mut scene_controller: ResMut<SceneController>,
+    render_device: Res<RenderDevice>,
+) {
+    let render_target = setup_render_target(
+        &mut commands,
+        &mut images,
+        &render_device,
+        &mut scene_controller,
+        // pre_roll_frames should be big enough for full scene render,
+        // but the bigger it is, the longer example will run.
+        // To visualize stages of scene rendering change this param to 0
+        // and change AppConfig::single_image to false in main
+        // Stages are:
+        // 1. Transparent image
+        // 2. Few black box images
+        // 3. Fully rendered scene images
+        // Exact number depends on device speed, device load and scene size
+        40,
+        "main_scene".into(),
+    );
+
+    // Scene example for non black box picture
+    // circular base
+    commands.spawn((
+        Mesh3d(meshes.add(Circle::new(4.0))),
+        MeshMaterial3d(materials.add(Color::WHITE)),
+        Transform::from_rotation(Quat::from_rotation_x(-std::f32::consts::FRAC_PI_2)),
+    ));
+    // cube
+    commands.spawn((
+        Mesh3d(meshes.add(Cuboid::new(1.0, 1.0, 1.0))),
+        MeshMaterial3d(materials.add(Color::srgb_u8(124, 144, 255))),
+        Transform::from_xyz(0.0, 0.5, 0.0),
+    ));
+    // light
+    commands.spawn((
+        PointLight {
+            shadows_enabled: true,
+            ..default()
+        },
+        Transform::from_xyz(4.0, 8.0, 4.0),
+    ));
+
+    commands.spawn((
+        Camera3d::default(),
+        Camera {
+            // render to image
+            target: render_target,
+            ..default()
+        },
+        Tonemapping::None,
+        Transform::from_xyz(-2.5, 4.5, 9.0).looking_at(Vec3::ZERO, Vec3::Y),
+    ));
+}
+
+/// Plugin for Render world part of work
+pub struct ImageCopyPlugin;
+impl Plugin for ImageCopyPlugin {
+    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));
+    }
+}
+
+/// Setups render target and cpu image for saving, changes scene state into render mode
+fn setup_render_target(
+    commands: &mut Commands,
+    images: &mut ResMut<Assets<Image>>,
+    render_device: &Res<RenderDevice>,
+    scene_controller: &mut ResMut<SceneController>,
+    pre_roll_frames: u32,
+    scene_name: String,
+) -> RenderTarget {
+    let size = Extent3d {
+        width: scene_controller.width,
+        height: scene_controller.height,
+        ..Default::default()
+    };
+
+    // This is the texture that will be rendered to.
+    let mut render_target_image = Image::new_fill(
+        size,
+        TextureDimension::D2,
+        &[0; 4],
+        TextureFormat::bevy_default(),
+        RenderAssetUsages::default(),
+    );
+    render_target_image.texture_descriptor.usage |=
+        TextureUsages::COPY_SRC | TextureUsages::RENDER_ATTACHMENT | TextureUsages::TEXTURE_BINDING;
+    let render_target_image_handle = images.add(render_target_image);
+
+    // This is the texture that will be copied to.
+    let cpu_image = Image::new_fill(
+        size,
+        TextureDimension::D2,
+        &[0; 4],
+        TextureFormat::bevy_default(),
+        RenderAssetUsages::default(),
+    );
+    let cpu_image_handle = images.add(cpu_image);
+
+    commands.spawn(ImageCopier::new(
+        render_target_image_handle.clone(),
+        size,
+        render_device,
+    ));
+
+    commands.spawn(ImageToSave(cpu_image_handle));
+
+    scene_controller.state = SceneState::Render(pre_roll_frames);
+    scene_controller.name = scene_name;
+    RenderTarget::Image(render_target_image_handle.into())
+}
+
+/// Setups image saver
+pub struct CaptureFramePlugin;
+impl Plugin for CaptureFramePlugin {
+    fn build(&self, app: &mut App) {
+        info!("Adding CaptureFramePlugin");
+        app.add_systems(PostUpdate, update);
+    }
+}
+
+/// `ImageCopier` aggregator in `RenderWorld`
+#[derive(Clone, Default, Resource, Deref, DerefMut)]
+struct ImageCopiers(pub Vec<ImageCopier>);
+
+/// Used by `ImageCopyDriver` for copying from render target to buffer
+#[derive(Clone, Component)]
+struct ImageCopier {
+    buffer: Buffer,
+    enabled: Arc<AtomicBool>,
+    src_image: Handle<Image>,
+}
+
+impl ImageCopier {
+    pub fn new(
+        src_image: Handle<Image>,
+        size: Extent3d,
+        render_device: &RenderDevice,
+    ) -> ImageCopier {
+        let padded_bytes_per_row =
+            RenderDevice::align_copy_bytes_per_row((size.width) as usize) * 4;
+
+        let cpu_buffer = render_device.create_buffer(&BufferDescriptor {
+            label: None,
+            size: padded_bytes_per_row as u64 * size.height as u64,
+            usage: BufferUsages::MAP_READ | BufferUsages::COPY_DST,
+            mapped_at_creation: false,
+        });
+
+        ImageCopier {
+            buffer: cpu_buffer,
+            src_image,
+            enabled: Arc::new(AtomicBool::new(true)),
+        }
+    }
+
+    pub fn enabled(&self) -> bool {
+        self.enabled.load(Ordering::Relaxed)
+    }
+}
+
+/// Extracting `ImageCopier`s into render world, because `ImageCopyDriver` accesses them
+fn image_copy_extract(mut commands: Commands, image_copiers: Extract<Query<&ImageCopier>>) {
+    commands.insert_resource(ImageCopiers(
+        image_copiers.iter().cloned().collect::<Vec<ImageCopier>>(),
+    ));
+}
+
+/// `RenderGraph` label for `ImageCopyDriver`
+#[derive(Debug, PartialEq, Eq, Clone, Hash, RenderLabel)]
+struct ImageCopy;
+
+/// `RenderGraph` node
+#[derive(Default)]
+struct ImageCopyDriver;
+
+// Copies image content from render target to buffer
+impl render_graph::Node for ImageCopyDriver {
+    fn run(
+        &self,
+        _graph: &mut RenderGraphContext,
+        render_context: &mut RenderContext,
+        world: &World,
+    ) -> Result<(), NodeRunError> {
+        let image_copiers = world.get_resource::<ImageCopiers>().unwrap();
+        let gpu_images = world
+            .get_resource::<RenderAssets<bevy::render::texture::GpuImage>>()
+            .unwrap();
+
+        for image_copier in image_copiers.iter() {
+            if !image_copier.enabled() {
+                continue;
+            }
+
+            let src_image = gpu_images.get(&image_copier.src_image).unwrap();
+
+            let mut encoder = render_context
+                .render_device()
+                .create_command_encoder(&CommandEncoderDescriptor::default());
+
+            let block_dimensions = src_image.texture_format.block_dimensions();
+            let block_size = src_image.texture_format.block_copy_size(None).unwrap();
+
+            // Calculating correct size of image row because
+            // copy_texture_to_buffer can copy image only by rows aligned wgpu::COPY_BYTES_PER_ROW_ALIGNMENT
+            // That's why image in buffer can be little bit wider
+            // This should be taken into account at copy from buffer stage
+            let padded_bytes_per_row = RenderDevice::align_copy_bytes_per_row(
+                (src_image.size.width as usize / block_dimensions.0 as usize) * block_size as usize,
+            );
+
+            encoder.copy_texture_to_buffer(
+                src_image.texture.as_image_copy(),
+                TexelCopyBufferInfo {
+                    buffer: &image_copier.buffer,
+                    layout: TexelCopyBufferLayout {
+                        offset: 0,
+                        bytes_per_row: Some(
+                            std::num::NonZero::<u32>::new(padded_bytes_per_row as u32)
+                                .unwrap()
+                                .into(),
+                        ),
+                        rows_per_image: None,
+                    },
+                },
+                src_image.size,
+            );
+
+            let render_queue = world.get_resource::<RenderQueue>().unwrap();
+            render_queue.submit(std::iter::once(encoder.finish()));
+        }
+
+        Ok(())
+    }
+}
+
+/// runs in render world after Render stage to send image from buffer via channel (receiver is in main world)
+fn receive_image_from_buffer(
+    image_copiers: Res<ImageCopiers>,
+    render_device: Res<RenderDevice>,
+    sender: Res<RenderWorldSender>,
+) {
+    for image_copier in image_copiers.0.iter() {
+        if !image_copier.enabled() {
+            continue;
+        }
+
+        // Finally time to get our data back from the gpu.
+        // First we get a buffer slice which represents a chunk of the buffer (which we
+        // can't access yet).
+        // We want the whole thing so use unbounded range.
+        let buffer_slice = image_copier.buffer.slice(..);
+
+        // Now things get complicated. WebGPU, for safety reasons, only allows either the GPU
+        // or CPU to access a buffer's contents at a time. We need to "map" the buffer which means
+        // flipping ownership of the buffer over to the CPU and making access legal. We do this
+        // with `BufferSlice::map_async`.
+        //
+        // The problem is that map_async is not an async function so we can't await it. What
+        // we need to do instead is pass in a closure that will be executed when the slice is
+        // either mapped or the mapping has failed.
+        //
+        // The problem with this is that we don't have a reliable way to wait in the main
+        // code for the buffer to be mapped and even worse, calling get_mapped_range or
+        // get_mapped_range_mut prematurely will cause a panic, not return an error.
+        //
+        // Using channels solves this as awaiting the receiving of a message from
+        // the passed closure will force the outside code to wait. It also doesn't hurt
+        // if the closure finishes before the outside code catches up as the message is
+        // buffered and receiving will just pick that up.
+        //
+        // It may also be worth noting that although on native, the usage of asynchronous
+        // channels is wholly unnecessary, for the sake of portability to Wasm
+        // we'll use async channels that work on both native and Wasm.
+
+        let (s, r) = crossbeam_channel::bounded(1);
+
+        // Maps the buffer so it can be read on the cpu
+        buffer_slice.map_async(MapMode::Read, move |r| match r {
+            // This will execute once the gpu is ready, so after the call to poll()
+            Ok(r) => s.send(r).expect("Failed to send map update"),
+            Err(err) => panic!("Failed to map buffer {err}"),
+        });
+
+        // In order for the mapping to be completed, one of three things must happen.
+        // One of those can be calling `Device::poll`. This isn't necessary on the web as devices
+        // are polled automatically but natively, we need to make sure this happens manually.
+        // `Maintain::Wait` will cause the thread to wait on native but not on WebGpu.
+
+        // This blocks until the gpu is done executing everything
+        render_device.poll(Maintain::wait()).panic_on_timeout();
+
+        // This blocks until the buffer is mapped
+        r.recv().expect("Failed to receive the map_async message");
+
+        // This could fail on app exit, if Main world clears resources (including receiver) while Render world still renders
+        let _ = sender.send(buffer_slice.get_mapped_range().to_vec());
+
+        // We need to make sure all `BufferView`'s are dropped before we do what we're about
+        // to do.
+        // Unmap so that we can copy to the staging buffer in the next iteration.
+        image_copier.buffer.unmap();
+    }
+}
+
+/// CPU-side image for saving
+#[derive(Component, Deref, DerefMut)]
+struct ImageToSave(Handle<Image>);
+
+// Takes from channel image content sent from render world and saves it to disk
+fn update(
+    images_to_save: Query<&ImageToSave>,
+    receiver: Res<MainWorldReceiver>,
+    mut images: ResMut<Assets<Image>>,
+    mut scene_controller: ResMut<SceneController>,
+    mut app_exit_writer: EventWriter<AppExit>,
+    mut file_number: Local<u32>,
+) {
+    if let SceneState::Render(n) = scene_controller.state {
+        if n < 1 {
+            // We don't want to block the main world on this,
+            // so we use try_recv which attempts to receive without blocking
+            let mut image_data = Vec::new();
+            while let Ok(data) = receiver.try_recv() {
+                // image generation could be faster than saving to fs,
+                // that's why use only last of them
+                image_data = data;
+            }
+            if !image_data.is_empty() {
+                for image in images_to_save.iter() {
+                    // Fill correct data from channel to image
+                    let img_bytes = images.get_mut(image.id()).unwrap();
+
+                    // We need to ensure that this works regardless of the image dimensions
+                    // If the image became wider when copying from the texture to the buffer,
+                    // then the data is reduced to its original size when copying from the buffer to the image.
+                    let row_bytes = img_bytes.width() as usize
+                        * img_bytes.texture_descriptor.format.pixel_size();
+                    let aligned_row_bytes = RenderDevice::align_copy_bytes_per_row(row_bytes);
+                    if row_bytes == aligned_row_bytes {
+                        img_bytes.data.as_mut().unwrap().clone_from(&image_data);
+                    } else {
+                        // shrink data to original image size
+                        img_bytes.data = Some(
+                            image_data
+                                .chunks(aligned_row_bytes)
+                                .take(img_bytes.height() as usize)
+                                .flat_map(|row| &row[..row_bytes.min(row.len())])
+                                .cloned()
+                                .collect(),
+                        );
+                    }
+
+                    // Create RGBA Image Buffer
+                    let img = match img_bytes.clone().try_into_dynamic() {
+                        Ok(img) => img.to_rgba8(),
+                        Err(e) => panic!("Failed to create image buffer {e:?}"),
+                    };
+
+                    // Prepare directory for images, test_images in bevy folder is used here for example
+                    // You should choose the path depending on your needs
+                    let images_dir = PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("test_images");
+                    info!("Saving image to: {images_dir:?}");
+                    std::fs::create_dir_all(&images_dir).unwrap();
+
+                    // Choose filename starting from 000.png
+                    let image_path = images_dir.join(format!("{:03}.png", file_number.deref()));
+                    *file_number.deref_mut() += 1;
+
+                    // Finally saving image to file, this heavy blocking operation is kept here
+                    // for example simplicity, but in real app you should move it to a separate task
+                    if let Err(e) = img.save(image_path) {
+                        panic!("Failed to save image: {e}");
+                    };
+                }
+                if scene_controller.single_image {
+                    app_exit_writer.write(AppExit::Success);
+                }
+            }
+        } else {
+            // clears channel for skipped frames
+            while receiver.try_recv().is_ok() {}
+            scene_controller.state = SceneState::Render(n - 1);
+        }
+    }
+}

vendor/bevy/examples/app/log_layers.rs

@@ -0,0 +1,58 @@
+//! This example illustrates how to add custom log layers in bevy.
+
+use bevy::{
+    log::{
+        tracing::{self, Subscriber},
+        tracing_subscriber::Layer,
+        BoxedLayer,
+    },
+    prelude::*,
+};
+
+struct CustomLayer;
+
+impl<S: Subscriber> Layer<S> for CustomLayer {
+    fn on_event(
+        &self,
+        event: &tracing::Event<'_>,
+        _ctx: bevy::log::tracing_subscriber::layer::Context<'_, S>,
+    ) {
+        println!("Got event!");
+        println!("  level={}", event.metadata().level());
+        println!("  target={}", event.metadata().target());
+        println!("  name={}", event.metadata().name());
+    }
+}
+
+// We don't need App for this example, as we are just printing log information.
+// For an example that uses App, see log_layers_ecs.
+fn custom_layer(_app: &mut App) -> Option<BoxedLayer> {
+    // You can provide multiple layers like this, since Vec<Layer> is also a layer:
+    Some(Box::new(vec![
+        bevy::log::tracing_subscriber::fmt::layer()
+            .with_file(true)
+            .boxed(),
+        CustomLayer.boxed(),
+    ]))
+}
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins.set(bevy::log::LogPlugin {
+            custom_layer,
+
+            ..default()
+        }))
+        .add_systems(Update, log_system)
+        .run();
+}
+
+fn log_system() {
+    // here is how you write new logs at each "log level" (in "most important" to
+    // "least important" order)
+    error!("something failed");
+    warn!("something bad happened that isn't a failure, but thats worth calling out");
+    info!("helpful information that is worth printing by default");
+    debug!("helpful for debugging");
+    trace!("very noisy");
+}

vendor/bevy/examples/app/log_layers_ecs.rs

@@ -0,0 +1,171 @@
+//! This example illustrates how to transfer log events from the [`Layer`] to Bevy's ECS.
+//!
+//! The way we will do this is via a [`mpsc`] channel. [`mpsc`] channels allow 2 unrelated
+//! parts of the program to communicate (in this case, [`Layer`]s and Bevy's ECS).
+//!
+//! Inside the `custom_layer` function we will create a [`mpsc::Sender`] and a [`mpsc::Receiver`] from a
+//! [`mpsc::channel`]. The [`Sender`](mpsc::Sender) will go into the `AdvancedLayer` and the [`Receiver`](mpsc::Receiver) will
+//! go into a non-send resource called `LogEvents` (It has to be non-send because [`Receiver`](mpsc::Receiver) is [`!Sync`](Sync)).
+//! From there we will use `transfer_log_events` to transfer log events from `LogEvents` to an ECS event called `LogEvent`.
+//!
+//! Finally, after all that we can access the `LogEvent` event from our systems and use it.
+//! In this example we build a simple log viewer.
+
+use std::sync::mpsc;
+
+use bevy::{
+    log::{
+        tracing::{self, Subscriber},
+        tracing_subscriber::{self, Layer},
+        BoxedLayer, Level,
+    },
+    prelude::*,
+};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins.set(bevy::log::LogPlugin {
+            // Show logs all the way up to the trace level, but only for logs
+            // produced by this example.
+            level: Level::TRACE,
+            filter: "warn,log_layers_ecs=trace".to_string(),
+            custom_layer,
+        }))
+        .add_systems(Startup, (log_system, setup))
+        .add_systems(Update, print_logs)
+        .run();
+}
+
+/// A basic message. This is what we will be sending from the [`CaptureLayer`] to [`CapturedLogEvents`] non-send resource.
+#[derive(Debug, Event)]
+struct LogEvent {
+    message: String,
+    level: Level,
+}
+
+/// This non-send resource temporarily stores [`LogEvent`]s before they are
+/// written to [`Events<LogEvent>`] by [`transfer_log_events`].
+#[derive(Deref, DerefMut)]
+struct CapturedLogEvents(mpsc::Receiver<LogEvent>);
+
+/// Transfers information from the `LogEvents` resource to [`Events<LogEvent>`](LogEvent).
+fn transfer_log_events(
+    receiver: NonSend<CapturedLogEvents>,
+    mut log_events: EventWriter<LogEvent>,
+) {
+    // Make sure to use `try_iter()` and not `iter()` to prevent blocking.
+    log_events.write_batch(receiver.try_iter());
+}
+
+/// This is the [`Layer`] that we will use to capture log events and then send them to Bevy's
+/// ECS via it's [`mpsc::Sender`].
+struct CaptureLayer {
+    sender: mpsc::Sender<LogEvent>,
+}
+impl<S: Subscriber> Layer<S> for CaptureLayer {
+    fn on_event(
+        &self,
+        event: &tracing::Event<'_>,
+        _ctx: tracing_subscriber::layer::Context<'_, S>,
+    ) {
+        // In order to obtain the log message, we have to create a struct that implements
+        // Visit and holds a reference to our string. Then we use the `record` method and
+        // the struct to modify the reference to hold the message string.
+        let mut message = None;
+        event.record(&mut CaptureLayerVisitor(&mut message));
+        if let Some(message) = message {
+            let metadata = event.metadata();
+
+            self.sender
+                .send(LogEvent {
+                    message,
+                    level: *metadata.level(),
+                })
+                .expect("LogEvents resource no longer exists!");
+        }
+    }
+}
+
+/// A [`Visit`](tracing::field::Visit)or that records log messages that are transferred to [`CaptureLayer`].
+struct CaptureLayerVisitor<'a>(&'a mut Option<String>);
+impl tracing::field::Visit for CaptureLayerVisitor<'_> {
+    fn record_debug(&mut self, field: &tracing::field::Field, value: &dyn std::fmt::Debug) {
+        // This if statement filters out unneeded events sometimes show up
+        if field.name() == "message" {
+            *self.0 = Some(format!("{value:?}"));
+        }
+    }
+}
+fn custom_layer(app: &mut App) -> Option<BoxedLayer> {
+    let (sender, receiver) = mpsc::channel();
+
+    let layer = CaptureLayer { sender };
+    let resource = CapturedLogEvents(receiver);
+
+    app.insert_non_send_resource(resource);
+    app.add_event::<LogEvent>();
+    app.add_systems(Update, transfer_log_events);
+
+    Some(layer.boxed())
+}
+
+fn log_system() {
+    // Here is how you write new logs at each "log level" (in "most important" to
+    // "least important" order)
+    error!("Something failed");
+    warn!("Something bad happened that isn't a failure, but thats worth calling out");
+    info!("Helpful information that is worth printing by default");
+    debug!("Helpful for debugging");
+    trace!("Very noisy");
+}
+
+#[derive(Component)]
+struct LogViewerRoot;
+
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+
+    commands.spawn((
+        Node {
+            width: Val::Vw(100.0),
+            height: Val::Vh(100.0),
+            flex_direction: FlexDirection::Column,
+            padding: UiRect::all(Val::Px(12.)),
+            ..default()
+        },
+        LogViewerRoot,
+    ));
+}
+
+// This is how we can read our LogEvents.
+// In this example we are reading the LogEvents and inserting them as text into our log viewer.
+fn print_logs(
+    mut events: EventReader<LogEvent>,
+    mut commands: Commands,
+    log_viewer_root: Single<Entity, With<LogViewerRoot>>,
+) {
+    let root_entity = *log_viewer_root;
+
+    commands.entity(root_entity).with_children(|child| {
+        for event in events.read() {
+            child.spawn(Text::default()).with_children(|child| {
+                child.spawn((
+                    TextSpan::new(format!("{:5} ", event.level)),
+                    TextColor(level_color(&event.level)),
+                ));
+                child.spawn(TextSpan::new(&event.message));
+            });
+        }
+    });
+}
+
+fn level_color(level: &Level) -> Color {
+    use bevy::color::palettes::tailwind::*;
+    Color::from(match *level {
+        Level::WARN => ORANGE_400,
+        Level::ERROR => RED_400,
+        Level::INFO => GREEN_400,
+        Level::TRACE => PURPLE_400,
+        Level::DEBUG => BLUE_400,
+    })
+}

vendor/bevy/examples/app/logs.rs

@@ -0,0 +1,81 @@
+//! This example illustrates how to use logs in bevy.
+
+use bevy::{log::once, prelude::*};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins.set(bevy::log::LogPlugin {
+            // Uncomment this to override the default log settings:
+            // level: bevy::log::Level::TRACE,
+            // filter: "wgpu=warn,bevy_ecs=info".to_string(),
+            ..default()
+        }))
+        .add_systems(Startup, setup)
+        .add_systems(Update, log_system)
+        .add_systems(Update, log_once_system)
+        .add_systems(Update, panic_on_p)
+        .run();
+}
+
+fn setup(mut commands: Commands) {
+    commands.spawn(Camera2d);
+    commands.spawn((
+        Text::new("Press P to panic"),
+        Node {
+            position_type: PositionType::Absolute,
+            top: Val::Px(12.0),
+            left: Val::Px(12.0),
+            ..default()
+        },
+    ));
+}
+
+fn panic_on_p(keys: Res<ButtonInput<KeyCode>>) {
+    if keys.just_pressed(KeyCode::KeyP) {
+        panic!("P pressed, panicking");
+    }
+}
+
+fn log_system() {
+    // here is how you write new logs at each "log level" (in "least important" to "most important"
+    // order)
+    trace!("very noisy");
+    debug!("helpful for debugging");
+    info!("helpful information that is worth printing by default");
+    warn!("something bad happened that isn't a failure, but thats worth calling out");
+    error!("something failed");
+
+    // by default, trace and debug logs are ignored because they are "noisy"
+    // you can control what level is logged by setting up the LogPlugin
+    // alternatively you can set the log level via the RUST_LOG=LEVEL environment variable
+    // ex: RUST_LOG=trace, RUST_LOG=info,bevy_ecs=warn
+    // the format used here is super flexible. check out this documentation for more info:
+    // https://docs.rs/tracing-subscriber/*/tracing_subscriber/filter/struct.EnvFilter.html
+}
+
+fn log_once_system() {
+    // The 'once' variants of each log level are useful when a system is called every frame,
+    // but we still wish to inform the user only once. In other words, use these to prevent spam :)
+
+    trace_once!("one time noisy message");
+    debug_once!("one time debug message");
+    info_once!("some info which is printed only once");
+    warn_once!("some warning we wish to call out only once");
+    error_once!("some error we wish to report only once");
+
+    for i in 0..10 {
+        info_once!("logs once per call site, so this works just fine: {}", i);
+    }
+
+    // you can also use the `once!` macro directly,
+    // in situations where you want to do something expensive only once
+    // within the context of a continuous system.
+    once!({
+        info!("doing expensive things");
+        let mut a: u64 = 0;
+        for i in 0..100000000 {
+            a += i;
+        }
+        info!("result of some expensive one time calculation: {}", a);
+    });
+}

vendor/bevy/examples/app/no_renderer.rs

@@ -0,0 +1,25 @@
+//! An application that runs with default plugins and displays an empty
+//! window, but without an actual renderer.
+//! This can be very useful for integration tests or CI.
+//!
+//! See also the `headless` example which does not display a window.
+
+use bevy::{
+    prelude::*,
+    render::{settings::WgpuSettings, RenderPlugin},
+};
+
+fn main() {
+    App::new()
+        .add_plugins(
+            DefaultPlugins.set(RenderPlugin {
+                render_creation: WgpuSettings {
+                    backends: None,
+                    ..default()
+                }
+                .into(),
+                ..default()
+            }),
+        )
+        .run();
+}

vendor/bevy/examples/app/plugin.rs

@@ -0,0 +1,52 @@
+//! Demonstrates the creation and registration of a custom plugin.
+//!
+//! Plugins are the foundation of Bevy. They are scoped sets of components, resources, and systems
+//! that provide a specific piece of functionality (generally the smaller the scope, the better).
+//! This example illustrates how to create a simple plugin that prints out a message.
+
+use bevy::prelude::*;
+use core::time::Duration;
+
+fn main() {
+    App::new()
+        // plugins are registered as part of the "app building" process
+        .add_plugins((
+            DefaultPlugins,
+            PrintMessagePlugin {
+                wait_duration: Duration::from_secs(1),
+                message: "This is an example plugin".to_string(),
+            },
+        ))
+        .run();
+}
+
+// This "print message plugin" prints a `message` every `wait_duration`
+struct PrintMessagePlugin {
+    // Put your plugin configuration here
+    wait_duration: Duration,
+    message: String,
+}
+
+impl Plugin for PrintMessagePlugin {
+    // this is where we set up our plugin
+    fn build(&self, app: &mut App) {
+        let state = PrintMessageState {
+            message: self.message.clone(),
+            timer: Timer::new(self.wait_duration, TimerMode::Repeating),
+        };
+        app.insert_resource(state)
+            .add_systems(Update, print_message_system);
+    }
+}
+
+#[derive(Resource)]
+struct PrintMessageState {
+    message: String,
+    timer: Timer,
+}
+
+fn print_message_system(mut state: ResMut<PrintMessageState>, time: Res<Time>) {
+    if state.timer.tick(time.delta()).finished() {
+        info!("{}", state.message);
+    }
+}

vendor/bevy/examples/app/plugin_group.rs

@@ -0,0 +1,59 @@
+//! Demonstrates the creation and registration of a custom plugin group.
+//! [`PluginGroup`]s are a way to group sets of plugins that should be registered together.
+
+use bevy::{app::PluginGroupBuilder, prelude::*};
+
+fn main() {
+    App::new()
+        .add_plugins((
+            // Two PluginGroups that are included with bevy are DefaultPlugins and MinimalPlugins
+            DefaultPlugins,
+            // Adding a plugin group adds all plugins in the group by default
+            HelloWorldPlugins,
+        ))
+        // You can also modify a PluginGroup (such as disabling plugins) like this:
+        // .add_plugins(
+        //     HelloWorldPlugins
+        //         .build()
+        //         .disable::<PrintWorldPlugin>()
+        //         .add_before::<PrintHelloPlugin>(
+        //             bevy::diagnostic::LogDiagnosticsPlugin::default(),
+        //         ),
+        // )
+        .run();
+}
+
+/// A group of plugins that produce the "hello world" behavior
+pub struct HelloWorldPlugins;
+
+impl PluginGroup for HelloWorldPlugins {
+    fn build(self) -> PluginGroupBuilder {
+        PluginGroupBuilder::start::<Self>()
+            .add(PrintHelloPlugin)
+            .add(PrintWorldPlugin)
+    }
+}
+
+struct PrintHelloPlugin;
+
+impl Plugin for PrintHelloPlugin {
+    fn build(&self, app: &mut App) {
+        app.add_systems(Update, print_hello_system);
+    }
+}
+
+fn print_hello_system() {
+    info!("hello");
+}
+
+struct PrintWorldPlugin;
+
+impl Plugin for PrintWorldPlugin {
+    fn build(&self, app: &mut App) {
+        app.add_systems(Update, print_world_system);
+    }
+}
+
+fn print_world_system() {
+    info!("world");
+}

vendor/bevy/examples/app/return_after_run.rs

@@ -0,0 +1,27 @@
+//! Shows how to return to the calling function after a windowed Bevy app has exited.
+//!
+//! In windowed *Bevy* applications, executing code below a call to `App::run()` is
+//! not recommended because:
+//! - `App::run()` will never return on iOS and Web.
+//! - It is not possible to recreate a window after the event loop has been terminated.
+
+use bevy::prelude::*;
+
+fn main() {
+    println!("Running Bevy App");
+    App::new()
+        .add_plugins(DefaultPlugins.set(WindowPlugin {
+            primary_window: Some(Window {
+                title: "Close the window to return to the main function".into(),
+                ..default()
+            }),
+            ..default()
+        }))
+        .add_systems(Update, system)
+        .run();
+    println!("Bevy App has exited. We are back in our main function.");
+}
+
+fn system() {
+    info!("Logging from Bevy App");
+}

vendor/bevy/examples/app/thread_pool_resources.rs

@@ -0,0 +1,12 @@
+//! This example illustrates how to customize the thread pool used internally (e.g. to only use a
+//! certain number of threads).
+
+use bevy::prelude::*;
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins.set(TaskPoolPlugin {
+            task_pool_options: TaskPoolOptions::with_num_threads(4),
+        }))
+        .run();
+}

vendor/bevy/examples/app/without_winit.rs

@@ -0,0 +1,14 @@
+//! Create an application without winit (runs single time, no event loop).
+
+use bevy::{prelude::*, winit::WinitPlugin};
+
+fn main() {
+    App::new()
+        .add_plugins(DefaultPlugins.build().disable::<WinitPlugin>())
+        .add_systems(Update, setup_system)
+        .run();
+}
+
+fn setup_system(mut commands: Commands) {
+    commands.spawn(Camera3d::default());
+}