Warn when unit () is inserted as a value

[ChristopherBiscardi]

What problem does this solve or what need does it fill?

This program (note: look_at) appears to insert a Transform, but actually inserts a unit value because Transform::look_at doesn't return a Transform.
This results in the debug system never finding the non-existent Transform at best, and getting a default Transform if another Component that requires a Transform inserts a Default value (such as Mesh3d).

use bevy::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_systems(Startup, startup)
        .add_systems(Update, debug)
        .run();
}

fn debug(entities: Query<(&Name, &Transform)>) {
    for (name, transform) in &entities {
        if ["Parent"].contains(&name.as_str()) {
            info!(?name, transform=?transform.translation);
        }
    }
}

fn startup(mut commands: Commands) {
    commands.spawn((
        Name::new("Parent"),
        Transform::from_xyz(10.0, 0.0, 0.0)
            .look_at(Vec3::ZERO, Vec3::Y),
    ));
}

What solution would you like?

• functions that accept exclusive references and return (), like Transform::look_at, should link to versions that return Self like Transform::looking_at if applicable in the documentation
• A warning should be logged if () is inserted as a component value, instead of just ignoring it

What alternative(s) have you considered?

The bevy linter includes a lint for this called unit_in_bundle with a very similar Transform example in the showcase. We could encourage use of the bevy linter instead.

[alice-i-cecile]

I would be open to adding a debug-gated warning here, but the linter feels like the right design to me.

[alice-i-cecile]

We could potentially make this a compile error actually, by splitting Bundle along the lines of #19761. I'm not convinced we should though: I think that doing so would seriously complicate generic code.

[ChristopherBiscardi]

The Bundle docs list World::spawn_batch as a valid use case for inserting unit

unit, otherwise known as (), is a Bundle containing no components (since it can also be considered as the empty tuple). This can be useful for spawning large numbers of empty entities using World::spawn_batch.

https://docs.rs/bevy/0.17.0-rc.2/bevy/ecs/bundle/trait.Bundle.html

---

I'm going to close this since its an officially documented use case to "insert/spawn unit", and we have the linter available to suggest people use on their projects, which will become my default recommendation moving forward.