Struct Single

pub struct Single<'w, D, F = ()>
where
    D: QueryData,
    F: QueryFilter,
{ /* private fields */ }

System parameter that provides access to single entity’s components, much like Query::single/Query::single_mut.

This SystemParam fails validation if zero or more than one matching entity exists. This will cause the system to be skipped, according to the rules laid out in SystemParamValidationError.

Use Option<Single<D, F>> instead if zero or one matching entities can exist.

See Query for more details.

Implementations

impl<'w, D, F> Single<'w, D, F>

where D: QueryData, F: QueryFilter,

pub fn into_inner(self) -> <D as QueryData>::Item<'w>

Returns the inner item with ownership.

Examples found in repository

examples/animation/animation_events.rs (line 32)

fn edit_message(
    trigger: Trigger<MessageEvent>,
    text: Single<(&mut Text2d, &mut TextColor), With<MessageText>>,
) {
    let (mut text, mut color) = text.into_inner();
    text.0 = trigger.event().value.clone();
    color.0 = trigger.event().color;
}

examples/transforms/align.rs (line 141)

fn rotate_ship(ship: Single<(&mut Ship, &mut Transform)>, time: Res<Time>) {
    let (mut ship, mut ship_transform) = ship.into_inner();

    if !ship.in_motion {
        return;
    }

    let target_rotation = ship.target_transform.rotation;

    ship_transform
        .rotation
        .smooth_nudge(&target_rotation, 3.0, time.delta_secs());

    if ship_transform.rotation.angle_between(target_rotation) <= f32::EPSILON {
        ship.in_motion = false;
    }
}

examples/ui/relative_cursor_position.rs (line 70)

fn relative_cursor_position_system(
    relative_cursor_position: Single<&RelativeCursorPosition>,
    output_query: Single<(&mut Text, &mut TextColor)>,
) {
    let (mut output, mut text_color) = output_query.into_inner();

    **output = if let Some(relative_cursor_position) = relative_cursor_position.normalized {
        format!(
            "({:.1}, {:.1})",
            relative_cursor_position.x, relative_cursor_position.y
        )
    } else {
        "unknown".to_string()
    };

    text_color.0 = if relative_cursor_position.mouse_over() {
        Color::srgb(0.1, 0.9, 0.1)
    } else {
        Color::srgb(0.9, 0.1, 0.1)
    };
}

examples/math/custom_primitives.rs (line 273)

fn switch_cameras(
    current: Res<State<CameraActive>>,
    mut next: ResMut<NextState<CameraActive>>,
    camera: Single<(&mut Transform, &mut Projection)>,
) {
    let next_state = match current.get() {
        CameraActive::Dim2 => CameraActive::Dim3,
        CameraActive::Dim3 => CameraActive::Dim2,
    };
    next.set(next_state);

    let (mut transform, mut projection) = camera.into_inner();
    match next_state {
        CameraActive::Dim2 => {
            *transform = TRANSFORM_2D;
            *projection = PROJECTION_2D;
        }
        CameraActive::Dim3 => {
            *transform = TRANSFORM_3D;
            *projection = PROJECTION_3D;
        }
    };
}

examples/asset/alter_sprite.rs (line 113)

fn alter_handle(
    asset_server: Res<AssetServer>,
    right_bird: Single<(&mut Bird, &mut Sprite), Without<Left>>,
) {
    // Image handles, like other parts of the ECS, can be queried as mutable and modified at
    // runtime. We only spawned one bird without the `Left` marker component.
    let (mut bird, mut sprite) = right_bird.into_inner();

    // Switch to a new Bird variant
    bird.set_next_variant();

    // Modify the handle associated with the Bird on the right side. Note that we will only
    // have to load the same path from storage media once: repeated attempts will re-use the
    // asset.
    sprite.image = asset_server.load(bird.get_texture_path());
}

examples/math/render_primitives.rs (line 340)

fn update_active_cameras(
    state: Res<State<CameraActive>>,
    camera_2d: Single<(Entity, &mut Camera), With<Camera2d>>,
    camera_3d: Single<(Entity, &mut Camera), (With<Camera3d>, Without<Camera2d>)>,
    mut text: Query<&mut UiTargetCamera, With<HeaderNode>>,
) {
    let (entity_2d, mut cam_2d) = camera_2d.into_inner();
    let (entity_3d, mut cam_3d) = camera_3d.into_inner();
    let is_camera_2d_active = matches!(*state.get(), CameraActive::Dim2);

    cam_2d.is_active = is_camera_2d_active;
    cam_3d.is_active = !is_camera_2d_active;

    let active_camera = if is_camera_2d_active {
        entity_2d
    } else {
        entity_3d
    };

    text.iter_mut().for_each(|mut target_camera| {
        *target_camera = UiTargetCamera(active_camera);
    });
}

Additional examples can be found in:

• examples/asset/alter_mesh.rs
• examples/games/game_menu.rs
• examples/3d/motion_blur.rs
• examples/input/text_input.rs
• examples/2d/rotation.rs
• examples/camera/projection_zoom.rs
• examples/3d/auto_exposure.rs
• examples/camera/first_person_view_model.rs
• examples/games/breakout.rs
• examples/3d/blend_modes.rs
• examples/3d/anti_aliasing.rs
• examples/3d/bloom_3d.rs
• examples/3d/fog.rs
• examples/2d/bloom_2d.rs
• examples/3d/transmission.rs

Trait Implementations

impl<'w, D, F> Deref for Single<'w, D, F>

where D: QueryData, F: QueryFilter,

type Target = <D as QueryData>::Item<'w>

The resulting type after dereferencing.

fn deref(&self) -> &<Single<'w, D, F> as Deref>::Target

Dereferences the value.

impl<'w, D, F> DerefMut for Single<'w, D, F>

where D: QueryData, F: QueryFilter,

fn deref_mut(&mut self) -> &mut <Single<'w, D, F> as Deref>::Target

Mutably dereferences the value.

impl<'a, D, F> SystemParam for Single<'a, D, F>

where D: QueryData + 'static, F: QueryFilter + 'static,

type State = QueryState<D, F>

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

type Item<'w, 's> = Single<'w, D, F>

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, ) -> <Single<'a, D, F> as SystemParam>::State

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

unsafe fn new_archetype( state: &mut <Single<'a, D, F> as SystemParam>::State, archetype: &Archetype, system_meta: &mut SystemMeta, )

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

unsafe fn get_param<'w, 's>( state: &'s mut <Single<'a, D, F> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'w>, change_tick: Tick, ) -> <Single<'a, D, F> as SystemParam>::Item<'w, 's>

Creates a parameter to be passed into a SystemParamFunction.

unsafe fn validate_param( state: &<Single<'a, D, F> as SystemParam>::State, system_meta: &SystemMeta, world: UnsafeWorldCell<'_>, ) -> Result<(), SystemParamValidationError>

Validates that the param can be acquired by the get_param.

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

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

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

impl<'a, D, F> ReadOnlySystemParam for Single<'a, D, F>

where D: ReadOnlyQueryData + 'static, F: QueryFilter + 'static,