commands.insert_if_new inserts Required Components also if not new

[lucidBrot]

Of the two ways of thinking about Required Components as discussed here, I am using Required Components to "include" other components at insertion, not to constantly require them. This seems to be the intent from the docs as well:

Components can specify Required Components. If some Component A requires Component B, then when A is inserted, B will also be initialized and inserted (if it was not manually specified).

But I've found that the required Component B is also inserted when A is not being inserted. What I did is this:

• Insert (A,B) as my_entity
• Remove B from my_entity
• Perform my_entity_commands.insert_if_new(A)
• Observe that, surprisingly, there is now a B, although the A was not inserted.

Bevy version and features

Bevy version: 0.18.1, default features

# rustup -V
info: The currently active `rustc` version is `rustc 1.94.0-nightly (31010ca61 2025-12-16)`

What you did

I'll attach the repro project files with a minimal test. Run cargo test to see it fail.

Repro.zip

What went wrong

I was expecting insert_if_new to have no effect if the provided Component is not new. Something like "it checks whether the Component exists on that Entity. If yes, it does nothing. If no, it inserts it and triggers hooks and required components appropriately".

What it does instead is it enforces the required Components even if the Component itself was already present. This is a logic bug in my code, where I have a Marker Component that should initially be present (achieved by #[require(ing it) and eventually gets removed.

Possible Workaround

I suspect I could work around this bug by using Component Hooks to perform the check myself. I did not check, but I would be surprised if the insertion hook would also be called without any insertion happening. When/if I try this, I will update this post.

Reproduction Test Case

mod repro3 {
    use bevy::prelude::*;
    #[derive(Component, Reflect, Default)]
    #[reflect(Component)]
    pub struct RequiredMarkerComponent {}

    #[derive(Reflect, Component, Default)]
    #[reflect(Component)]
    #[require(RequiredMarkerComponent)]
    pub(crate) struct MainComponent {}

    #[test]
    fn simple_insert_if_new_test() {
        // Create an empty world
        let mut world = World::new();
        // Spawn a new entity, with a Component and another, required, Component.
        let mut my_entity = world.spawn(MainComponent::default());

        // Remove the required Component.
        my_entity.remove::<RequiredMarkerComponent>();
        // Be very certain that we did remove the Marker Component
        assert!(my_entity.get::<RequiredMarkerComponent>().is_none());
        // Be very certain that we did not remove the other Component.
        my_entity
            .get::<MainComponent>()
            .expect("This component should still exist...");
        // Add the Component only if new (it's not new. this should do nothing.)
        my_entity.insert_if_new(MainComponent::default());
        match my_entity.get::<RequiredMarkerComponent>() {
            None => {
                // All good.
            }
            Some(_) => panic!(
                "This RequiredMarkerComponent should not exist, because the MainComponent was not new."
            ),
        }
    }
}

Is It a Bug?

I am of the opinion that this behavior is very unexpected and not as documented, but I see the possibility for the viewpoint that it is working as-intended too... If the consensus is actually that this is fine, I think it should still be documented clearer in the docs of insert_if_new() and Required Components.

[alice-i-cecile]

I suspect the check in insert_if_new is not occuring at the right time: this should not be happening.

[satyakwok]

@alice-i-cecile confirmed on main, and yes — the check is in the wrong place. Minimal repro:

#[derive(Component, Default)] struct ReqMarker;
#[derive(Component, Default)] #[require(ReqMarker)] struct Main;

let id = world.spawn(Main).id();
world.entity_mut(id).remove::<ReqMarker>();
world.entity_mut(id).insert_if_new(Main); // ReqMarker is back

Root cause: in BundleInfo::write_components the required-component loop initializes every entry of ArchetypeAfterBundleInsert.required_components unconditionally — unlike the explicit components above it, it never consults insert_mode. That cached list is built per (bundle, source archetype) edge in insert.rs as "required components not already in the source archetype", so under Keep a required component still gets added even when its requirer (Main) is already present.

The tricky bit: the cached required_components carries no link back to which explicit component required each entry, and the edge cache isn't keyed by insert_mode, so there's currently nowhere to express "skip this required component because its requirer wasn't newly inserted."

Two directions:

1. Coarse: under Keep, skip required components when none of the bundle's explicit components are newly added. Fixes this case, hot path untouched, but a mixed bundle would still over-add the required components of its already-present explicit components.
2. General: record at cache-build time whether a required component is only required by components already in the source archetype, and skip those under Keep. Precise, minimal hot-path cost (one bool per required component), but touches the cached structure.

I'd lean toward 2 since it's correct for mixed bundles. Happy to implement either — which do you prefer?

[alice-i-cecile]

Shouldn't the check be directly in the insert_if_new method, and immediately bail there? I haven't checked that code lately, so feel free to explain why I'm wrong and that won't work :)

[satyakwok]

That works for the simple case, but I don't think a bail inside insert_if_new itself fully covers it — two gaps:

1. Other Keep entry points. EntityWorldMut::insert_if_new isn't the only one: EntityCommands::insert_if_new, the insert_batch_if_new / try_insert_batch_if_new commands, and EntityCloner (allow-by-ids with InsertMode::Keep) all reach the same insertion path with InsertMode::Keep. A guard in just EntityWorldMut::insert_if_new would leave those still resurrecting required components, so the check probably wants to live where Keep is actually applied.

2. Mixed bundles. For a tuple like insert_if_new((A, B)) where A already exists and B is new, we can't bail the whole call — B (and B's required components) still need inserting, while A's required components must not be re-added. So a whole-bundle "all present → bail" fixes the single-component repro but not partial bundles.

Concretely, the root cause is that the required-components loop in BundleInfo::write_components initializes every entry of the cached ArchetypeAfterBundleInsert.required_components unconditionally, ignoring insert_mode (unlike the explicit components just above it). Gating that on Keep fixes every entry point at once. The wrinkle: the cached list doesn't record which explicit component required each entry, so the precise mixed-bundle fix means threading that requirer info (or its "already in source archetype" status) into the cache.

Happy to implement — do you want the full mixed-bundle-correct version, or is the common "all explicit components already present → skip required" guard enough for now (simpler, covers the repro + all Keep paths, but a partial bundle would still over-add)?