Rename on_replace/Replace to on_discard/Discard

[jonas-meyer]

Objective

• Rename lifecycle “Replace” hooks/events to “Discard” to reflect actual semantics (fires on overwrite, remove, and despawn), and free up “Replace” for a future true replacement event. Addresses Make lifecycle events ordering and meaning more intuitive #20729.

Solution

• Renamed Replace/on_replace to Discard/on_discard across hooks, observers, events, derive macros, docs, examples, and tests.
• Updated UI compile‑fail expectations and added OnDiscard doc alias on Discard for discoverability.

Testing

• cargo run -p ci -- compile-fail
• cargo test -p bevy_ecs --lib --tests --features bevy_ecs/track_location (fails locally due to missing bevy_ecs/debug feature in two tests that assert full system names)

[Copilot]

Pull request overview

This PR renames the "Replace" lifecycle event and hooks to "Discard" to better reflect their actual semantics—they fire when a component is discarded (overwritten, removed, or during despawn), not just when replaced. This addresses issue #20729 by freeing up the "Replace" name for a future true replacement-only event while improving semantic clarity.

Changes:

• Renamed Replace to Discard and on_replace to on_discard across all lifecycle hooks, observers, events, and derive macro attributes
• Updated documentation and comments to reflect the new terminology throughout the codebase
• Added doc aliases (OnReplace, Replace) to the Discard struct for backward compatibility in documentation search

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
examples/ecs/immutable_components.rs	Updated component hook attribute and function names from on_replace to on_discard
examples/ecs/component_hooks.rs	Updated example documentation and hook registration to use on_discard
crates/bevy_ecs/src/world/mod.rs	Updated imports and event key registration from REPLACE to DISCARD
crates/bevy_ecs/src/world/entity_access/world_mut.rs	Updated lifecycle trigger calls and imports from Replace to Discard
crates/bevy_ecs/src/world/entity_access/mod.rs	Updated test component hooks and observers from on_replace to on_discard
crates/bevy_ecs/src/world/deferred_world.rs	Renamed trigger_on_replace to trigger_on_discard and updated related logic
crates/bevy_ecs/src/relationship/related_methods.rs	Updated test observer type from Replace to Discard
crates/bevy_ecs/src/relationship/mod.rs	Updated documentation and hook method names in Relationship trait
crates/bevy_ecs/src/observer/mod.rs	Updated test observers from Replace to Discard
crates/bevy_ecs/src/observer/centralized_storage.rs	Renamed cached observers field and updated documentation
crates/bevy_ecs/src/lifecycle.rs	Renamed Replace struct to Discard, updated REPLACE constant to DISCARD, added doc aliases
crates/bevy_ecs/src/lib.rs	Updated prelude exports from Replace to Discard
crates/bevy_ecs/src/hierarchy.rs	Updated test comment from on_replace to on_discard
crates/bevy_ecs/src/component/mod.rs	Updated Component trait method and documentation from on_replace to on_discard
crates/bevy_ecs/src/component/info.rs	Updated flag insertion from ON_REPLACE_HOOK to ON_DISCARD_HOOK
crates/bevy_ecs/src/bundle/tests.rs	Updated test hooks from on_replace to on_discard
crates/bevy_ecs/src/bundle/remove.rs	Updated bundle removal triggers from Replace to Discard
crates/bevy_ecs/src/bundle/insert.rs	Updated bundle insertion triggers from Replace to Discard
crates/bevy_ecs/src/archetype.rs	Renamed archetype flags and methods from replace to discard
crates/bevy_ecs/macros/src/lib.rs	Updated macro documentation from on_replace to on_discard
crates/bevy_ecs/macros/src/component.rs	Updated derive macro to generate on_discard instead of on_replace
crates/bevy_ecs/compile_fail/tests/ui/component_hook_relationship.stderr	Updated expected error messages to reference on_discard
crates/bevy_ecs/compile_fail/tests/ui/component_hook_relationship.rs	Updated test attributes from on_replace to on_discard

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.