Struct bevy::ecs::system::Res

pub struct Res<'w, T>
where
    T: Resource + ?Sized,
{ /* private fields */ }

Shared borrow of a Resource.

See the Resource documentation for usage.

If you need a unique mutable borrow, use ResMut instead.

Panics

Panics when used as a SystemParameter if the resource does not exist.

Use Option<Res<T>> instead if the resource might not always exist.

Implementations

impl<'w, T> Res<'w, T>

where T: Resource,

pub fn clone(this: &Res<'w, T>) -> Res<'w, T>

Copies a reference to a resource.

Note that unless you actually need an instance of Res<T>, you should prefer to just convert it to &T which can be freely copied.

pub fn into_inner(self) -> &'w T

Due to lifetime limitations of the Deref trait, this method can be used to obtain a reference of the Resource with a lifetime bound to 'w instead of the lifetime of the struct itself.

Examples found in repository

examples/stress_tests/bevymark.rs (line 167)

fn scheduled_spawner(
    mut commands: Commands,
    args: Res<Args>,
    windows: Query<&Window>,
    mut scheduled: ResMut<BirdScheduled>,
    mut counter: ResMut<BevyCounter>,
    bird_resources: ResMut<BirdResources>,
) {
    let window = windows.single();

    if scheduled.waves > 0 {
        let bird_resources = bird_resources.into_inner();
        spawn_birds(
            &mut commands,
            args.into_inner(),
            &window.resolution,
            &mut counter,
            scheduled.per_wave,
            bird_resources,
            None,
            scheduled.waves - 1,
        );

        scheduled.waves -= 1;
    }
}

#[derive(Resource)]
struct BirdResources {
    textures: Vec<Handle<Image>>,
    materials: Vec<Handle<ColorMaterial>>,
    quad: Mesh2dHandle,
    color_rng: ChaCha8Rng,
    material_rng: ChaCha8Rng,
    velocity_rng: ChaCha8Rng,
    transform_rng: ChaCha8Rng,
}

#[derive(Component)]
struct StatsText;

#[allow(clippy::too_many_arguments)]
fn setup(
    mut commands: Commands,
    args: Res<Args>,
    asset_server: Res<AssetServer>,
    mut meshes: ResMut<Assets<Mesh>>,
    material_assets: ResMut<Assets<ColorMaterial>>,
    images: ResMut<Assets<Image>>,
    windows: Query<&Window>,
    counter: ResMut<BevyCounter>,
) {
    warn!(include_str!("warning_string.txt"));

    let args = args.into_inner();
    let images = images.into_inner();

    let mut textures = Vec::with_capacity(args.material_texture_count.max(1));
    if matches!(args.mode, Mode::Sprite) || args.material_texture_count > 0 {
        textures.push(asset_server.load("branding/icon.png"));
    }
    init_textures(&mut textures, args, images);

    let material_assets = material_assets.into_inner();
    let materials = init_materials(args, &textures, material_assets);

    let mut bird_resources = BirdResources {
        textures,
        materials,
        quad: meshes
            .add(Rectangle::from_size(Vec2::splat(BIRD_TEXTURE_SIZE as f32)))
            .into(),
        // We're seeding the PRNG here to make this example deterministic for testing purposes.
        // This isn't strictly required in practical use unless you need your app to be deterministic.
        color_rng: ChaCha8Rng::seed_from_u64(42),
        material_rng: ChaCha8Rng::seed_from_u64(42),
        velocity_rng: ChaCha8Rng::seed_from_u64(42),
        transform_rng: ChaCha8Rng::seed_from_u64(42),
    };

    let text_section = move |color: Srgba, value: &str| {
        TextSection::new(
            value,
            TextStyle {
                font_size: 40.0,
                color: color.into(),
                ..default()
            },
        )
    };

    commands.spawn(Camera2dBundle::default());
    commands
        .spawn(NodeBundle {
            style: Style {
                position_type: PositionType::Absolute,
                padding: UiRect::all(Val::Px(5.0)),
                ..default()
            },
            z_index: ZIndex::Global(i32::MAX),
            background_color: Color::BLACK.with_alpha(0.75).into(),
            ..default()
        })
        .with_children(|c| {
            c.spawn((
                TextBundle::from_sections([
                    text_section(LIME, "Bird Count: "),
                    text_section(AQUA, ""),
                    text_section(LIME, "\nFPS (raw): "),
                    text_section(AQUA, ""),
                    text_section(LIME, "\nFPS (SMA): "),
                    text_section(AQUA, ""),
                    text_section(LIME, "\nFPS (EMA): "),
                    text_section(AQUA, ""),
                ]),
                StatsText,
            ));
        });

    let mut scheduled = BirdScheduled {
        per_wave: args.per_wave,
        waves: args.waves,
    };

    if args.benchmark {
        let counter = counter.into_inner();
        for wave in (0..scheduled.waves).rev() {
            spawn_birds(
                &mut commands,
                args,
                &windows.single().resolution,
                counter,
                scheduled.per_wave,
                &mut bird_resources,
                Some(wave),
                wave,
            );
        }
        scheduled.waves = 0;
    }
    commands.insert_resource(bird_resources);
    commands.insert_resource(scheduled);
}

#[allow(clippy::too_many_arguments)]
fn mouse_handler(
    mut commands: Commands,
    args: Res<Args>,
    time: Res<Time>,
    mouse_button_input: Res<ButtonInput<MouseButton>>,
    windows: Query<&Window>,
    bird_resources: ResMut<BirdResources>,
    mut counter: ResMut<BevyCounter>,
    mut rng: Local<Option<ChaCha8Rng>>,
    mut wave: Local<usize>,
) {
    if rng.is_none() {
        // We're seeding the PRNG here to make this example deterministic for testing purposes.
        // This isn't strictly required in practical use unless you need your app to be deterministic.
        *rng = Some(ChaCha8Rng::seed_from_u64(42));
    }
    let rng = rng.as_mut().unwrap();
    let window = windows.single();

    if mouse_button_input.just_released(MouseButton::Left) {
        counter.color = Color::linear_rgb(rng.gen(), rng.gen(), rng.gen());
    }

    if mouse_button_input.pressed(MouseButton::Left) {
        let spawn_count = (BIRDS_PER_SECOND as f64 * time.delta_seconds_f64()) as usize;
        spawn_birds(
            &mut commands,
            args.into_inner(),
            &window.resolution,
            &mut counter,
            spawn_count,
            bird_resources.into_inner(),
            None,
            *wave,
        );
        *wave += 1;
    }
}

examples/shader/custom_phase_item.rs (line 80)

    fn render<'w>(
        _: &P,
        _: ROQueryItem<'w, Self::ViewQuery>,
        _: Option<ROQueryItem<'w, Self::ItemQuery>>,
        custom_phase_item_buffers: SystemParamItem<'w, '_, Self::Param>,
        pass: &mut TrackedRenderPass<'w>,
    ) -> RenderCommandResult {
        // Borrow check workaround.
        let custom_phase_item_buffers = custom_phase_item_buffers.into_inner();

        // Tell the GPU where the vertices are.
        pass.set_vertex_buffer(
            0,
            custom_phase_item_buffers
                .vertices
                .buffer()
                .unwrap()
                .slice(..),
        );

        // Tell the GPU where the indices are.
        pass.set_index_buffer(
            custom_phase_item_buffers
                .indices
                .buffer()
                .unwrap()
                .slice(..),
            0,
            IndexFormat::Uint32,
        );

        // Draw one triangle (3 vertices).
        pass.draw_indexed(0..3, 0, 0..1);

        RenderCommandResult::Success
    }

examples/shader/shader_instancing.rs (line 257)

    fn render<'w>(
        item: &P,
        _view: (),
        instance_buffer: Option<&'w InstanceBuffer>,
        (meshes, render_mesh_instances): SystemParamItem<'w, '_, Self::Param>,
        pass: &mut TrackedRenderPass<'w>,
    ) -> RenderCommandResult {
        let Some(mesh_instance) = render_mesh_instances.render_mesh_queue_data(item.entity())
        else {
            return RenderCommandResult::Failure;
        };
        let Some(gpu_mesh) = meshes.into_inner().get(mesh_instance.mesh_asset_id) else {
            return RenderCommandResult::Failure;
        };
        let Some(instance_buffer) = instance_buffer else {
            return RenderCommandResult::Failure;
        };

        pass.set_vertex_buffer(0, gpu_mesh.vertex_buffer.slice(..));
        pass.set_vertex_buffer(1, instance_buffer.buffer.slice(..));

        match &gpu_mesh.buffer_info {
            GpuBufferInfo::Indexed {
                buffer,
                index_format,
                count,
            } => {
                pass.set_index_buffer(buffer.slice(..), 0, *index_format);
                pass.draw_indexed(0..*count, 0, 0..instance_buffer.length as u32);
            }
            GpuBufferInfo::NonIndexed => {
                pass.draw(0..gpu_mesh.vertex_count, 0..instance_buffer.length as u32);
            }
        }
        RenderCommandResult::Success
    }

examples/stress_tests/many_cubes.rs (line 140)

fn setup(
    mut commands: Commands,
    args: Res<Args>,
    mesh_assets: ResMut<Assets<Mesh>>,
    material_assets: ResMut<Assets<StandardMaterial>>,
    images: ResMut<Assets<Image>>,
) {
    warn!(include_str!("warning_string.txt"));

    let args = args.into_inner();
    let images = images.into_inner();
    let material_assets = material_assets.into_inner();
    let mesh_assets = mesh_assets.into_inner();

    let meshes = init_meshes(args, mesh_assets);

    let material_textures = init_textures(args, images);
    let materials = init_materials(args, &material_textures, material_assets);

    // We're seeding the PRNG here to make this example deterministic for testing purposes.
    // This isn't strictly required in practical use unless you need your app to be deterministic.
    let mut material_rng = ChaCha8Rng::seed_from_u64(42);
    match args.layout {
        Layout::Sphere => {
            // NOTE: This pattern is good for testing performance of culling as it provides roughly
            // the same number of visible meshes regardless of the viewing angle.
            const N_POINTS: usize = WIDTH * HEIGHT * 4;
            // NOTE: f64 is used to avoid precision issues that produce visual artifacts in the distribution
            let radius = WIDTH as f64 * 2.5;
            let golden_ratio = 0.5f64 * (1.0f64 + 5.0f64.sqrt());
            for i in 0..N_POINTS {
                let spherical_polar_theta_phi =
                    fibonacci_spiral_on_sphere(golden_ratio, i, N_POINTS);
                let unit_sphere_p = spherical_polar_to_cartesian(spherical_polar_theta_phi);
                let (mesh, transform) = meshes.choose(&mut material_rng).unwrap();
                let mut cube = commands.spawn(PbrBundle {
                    mesh: mesh.clone(),
                    material: materials.choose(&mut material_rng).unwrap().clone(),
                    transform: Transform::from_translation((radius * unit_sphere_p).as_vec3())
                        .looking_at(Vec3::ZERO, Vec3::Y)
                        .mul_transform(*transform),
                    ..default()
                });
                if args.no_frustum_culling {
                    cube.insert(NoFrustumCulling);
                }
                if args.no_automatic_batching {
                    cube.insert(NoAutomaticBatching);
                }
            }

            // camera
            let mut camera = commands.spawn(Camera3dBundle::default());
            if args.gpu_culling {
                camera.insert(GpuCulling);
            }
            if args.no_cpu_culling {
                camera.insert(NoCpuCulling);
            }

            // Inside-out box around the meshes onto which shadows are cast (though you cannot see them...)
            commands.spawn((
                PbrBundle {
                    mesh: mesh_assets.add(Cuboid::from_size(Vec3::splat(radius as f32 * 2.2))),
                    material: material_assets.add(StandardMaterial::from(Color::WHITE)),
                    transform: Transform::from_scale(-Vec3::ONE),
                    ..default()
                },
                NotShadowCaster,
            ));
        }
        _ => {
            // NOTE: This pattern is good for demonstrating that frustum culling is working correctly
            // as the number of visible meshes rises and falls depending on the viewing angle.
            let scale = 2.5;
            for x in 0..WIDTH {
                for y in 0..HEIGHT {
                    // introduce spaces to break any kind of moiré pattern
                    if x % 10 == 0 || y % 10 == 0 {
                        continue;
                    }
                    // cube
                    commands.spawn(PbrBundle {
                        mesh: meshes.choose(&mut material_rng).unwrap().0.clone(),
                        material: materials.choose(&mut material_rng).unwrap().clone(),
                        transform: Transform::from_xyz((x as f32) * scale, (y as f32) * scale, 0.0),
                        ..default()
                    });
                    commands.spawn(PbrBundle {
                        mesh: meshes.choose(&mut material_rng).unwrap().0.clone(),
                        material: materials.choose(&mut material_rng).unwrap().clone(),
                        transform: Transform::from_xyz(
                            (x as f32) * scale,
                            HEIGHT as f32 * scale,
                            (y as f32) * scale,
                        ),
                        ..default()
                    });
                    commands.spawn(PbrBundle {
                        mesh: meshes.choose(&mut material_rng).unwrap().0.clone(),
                        material: materials.choose(&mut material_rng).unwrap().clone(),
                        transform: Transform::from_xyz((x as f32) * scale, 0.0, (y as f32) * scale),
                        ..default()
                    });
                    commands.spawn(PbrBundle {
                        mesh: meshes.choose(&mut material_rng).unwrap().0.clone(),
                        material: materials.choose(&mut material_rng).unwrap().clone(),
                        transform: Transform::from_xyz(0.0, (x as f32) * scale, (y as f32) * scale),
                        ..default()
                    });
                }
            }
            // camera
            let center = 0.5 * scale * Vec3::new(WIDTH as f32, HEIGHT as f32, WIDTH as f32);
            commands.spawn(Camera3dBundle {
                transform: Transform::from_translation(center),
                ..default()
            });
            // Inside-out box around the meshes onto which shadows are cast (though you cannot see them...)
            commands.spawn((
                PbrBundle {
                    mesh: mesh_assets.add(Cuboid::from_size(2.0 * 1.1 * center)),
                    material: material_assets.add(StandardMaterial::from(Color::WHITE)),
                    transform: Transform::from_scale(-Vec3::ONE).with_translation(center),
                    ..default()
                },
                NotShadowCaster,
            ));
        }
    }

    commands.spawn(DirectionalLightBundle {
        directional_light: DirectionalLight {
            shadows_enabled: args.shadows,
            ..default()
        },
        transform: Transform::IDENTITY.looking_at(Vec3::new(0.0, -1.0, -1.0), Vec3::Y),
        ..default()
    });
}

Trait Implementations

impl<'w, T> AsRef<T> for Res<'w, T>

where T: Resource,

fn as_ref(&self) -> &T

Converts this type into a shared reference of the (usually inferred) input type.

impl<'w, T> Debug for Res<'w, T>

where T: Resource + Debug + ?Sized,

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

Formats the value using the given formatter.

impl<'w, T> Deref for Res<'w, T>

where T: Resource + ?Sized,

type Target = T

The resulting type after dereferencing.

fn deref(&self) -> &<Res<'w, T> as Deref>::Target

Dereferences the value.

impl<'w, T> DetectChanges for Res<'w, T>

where T: Resource + ?Sized,

fn is_added(&self) -> bool

Returns true if this value was added after the system last ran.

fn is_changed(&self) -> bool

Returns true if this value was added or mutably dereferenced either since the last time the system ran or, if the system never ran, since the beginning of the program.

fn last_changed(&self) -> Tick

Returns the change tick recording the time this data was most recently changed.

impl<'w, T> From<ResMut<'w, T>> for Res<'w, T>

where T: Resource,

fn from(res: ResMut<'w, T>) -> Res<'w, T>

Converts to this type from the input type.

impl<'w, 'a, T> IntoIterator for &'a Res<'w, T>

where T: Resource, &'a T: IntoIterator,

type Item = <&'a T as IntoIterator>::Item

The type of the elements being iterated over.

type IntoIter = <&'a T as IntoIterator>::IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> <&'a Res<'w, T> as IntoIterator>::IntoIter

Creates an iterator from a value.

impl<'a, T> SystemParam for Res<'a, T>

where T: Resource,

type State = ComponentId

Used to store data which persists across invocations of a system.

type Item<'w, 's> = Res<'w, T>

The item type returned when constructing this system param. The value of this associated type should be Self, instantiated with new lifetimes.

fn init_state( world: &mut World, system_meta: &mut SystemMeta, ) -> <Res<'a, T> as SystemParam>::State

Registers any World access used by this SystemParam and creates a new instance of this param’s State.

unsafe fn get_param<'w, 's>( _: &'s mut <Res<'a, T> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> <Res<'a, T> as SystemParam>::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

unsafe fn new_archetype( state: &mut Self::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

For the specified Archetype, registers the components accessed by this SystemParam (if applicable).a

fn apply(state: &mut Self::State, system_meta: &SystemMeta, world: &mut World)

Applies any deferred mutations stored in this SystemParam’s state. This is used to apply Commands during apply_deferred.

fn queue( state: &mut Self::State, system_meta: &SystemMeta, world: DeferredWorld<'_>, )

Queues any deferred mutations to be applied at the next apply_deferred.

impl<'a, T> ReadOnlySystemParam for Res<'a, T>

where T: Resource,