feat(time): allow cancelling delayed commands by Daedalus-Icarus · Pull Request #24179 · bevyengine/bevy

Daedalus-Icarus · 2026-05-07T21:11:46Z

Objective

Fixes Add the ability to cancel delayed commands #24175.
Allow users to cancel delayed commands without querying for internal delayed command queue entities manually.

Solution

Added DelayedCommandHandle, which wraps the entity tracking a delayed command queue and can cancel it via try_despawn.
Added duration_with_handle and secs_with_handle while keeping the existing duration and secs APIs unchanged.
Preallocate the delayed queue entity when the delayed queue is created, then insert DelayedCommandQueue into that entity when delayed commands are submitted.
Updated the delayed commands release note with the cancellable API.

Testing

Added delayed_queues_can_be_cancelled, which queues a delayed spawn, cancels the handle, advances time, and confirms the spawn never runs.
Ran git diff --check.
Could not run cargo test -p bevy_time delayed_queues_can_be_cancelled locally because this environment does not have cargo or rustfmt installed.

Showcase

fn queue_spawn(mut commands: Commands) {
    let handle = {
        let mut delayed = commands.delayed();
        let (mut after_one_second, handle) = delayed.secs_with_handle(1.0);
        after_one_second.spawn(DummyComponent);
        handle
    };

    handle.cancel(&mut commands);
}

alice-i-cecile · 2026-05-07T21:43:20Z

@Runi-c, I would value your review here.

alice-i-cecile · 2026-05-07T21:57:07Z

    delayed.secs(1.5).entity(entity).insert(DummyComponent);
 }
+
+fn cancellable_delayed_spawn(mut commands: Commands) {


This example is not realistic enough to teach the pattern properly: we want to gesture at some sort of "conditionally cancel" pattern.

alice-i-cecile · 2026-05-07T21:58:22Z

@@ -18,6 +18,17 @@ fn delayed_spawn_then_insert(mut commands: Commands) {
    let entity = delayed.secs(0.5).spawn_empty().id();
    delayed.secs(1.5).entity(entity).insert(DummyComponent);
 }


Note: I'd be happy to land this in 0.19, but won't block on it. You may need to rewrite or cut the release notes later if it misses the window.

We can add this in a later release candidate though: it's additive and minor.

alice-i-cecile · 2026-05-07T21:59:03Z

    #[doc(hidden)]
-    pub use crate::{DelayedCommandsExt, Fixed, Real, Time, Timer, TimerMode, Virtual};
+    pub use crate::{
+        DelayedCommandHandle, DelayedCommandsExt, Fixed, Real, Time, Timer, TimerMode, Virtual,


DelayedCommandHandle is definitely not common enough that it should be in the prelude :)

alice-i-cecile · 2026-05-07T22:00:49Z

+    queue: CommandQueue,
+}
+
+/// A handle that can be used to cancel delayed commands.


I think we might want to steer clear of the term "handle" specifically here. It's common in async contexts, but it means something totally different in the context of Bevy because of asset handles. Is there a synonym we can use?

alice-i-cecile · 2026-05-07T22:02:04Z

+    /// Return a [`Commands`] whose commands will be delayed by `duration`, and
+    /// a handle that can be used to cancel them.
+    ///
+    /// Commands queued for the same `duration` share a queue and will return


This is extremely surprising, and IMO a bug. It would be good to avoid this, but if not, we should at least document how to avoid working around it (I think by generating two instances of DelayedCommands?).

alice-i-cecile · 2026-05-07T22:03:11Z

+    /// Commands queued for the same `duration` share a queue and will return
+    /// the same handle.
+    #[must_use = "The returned Commands must be used to submit commands with this delay."]
+    pub fn duration_with_handle(


This duplication is a code smell that will lead to a combinatorial explosion of methods. We should instead have one with_handle method or the like that gets chained on.

The pattern we want to copy is EntityCommands::id()

See above for notes on naming. Handle is particularly confusing as a term here.

alice-i-cecile · 2026-05-07T22:05:31Z

+
+/// A handle that can be used to cancel delayed commands.
+///
+/// This handle represents a [`DelayedCommandQueue`] entity. Despawning the


These docs would benefit from some grounded advice on why you might want to cancel delayed commands in the context of game dev, and a dedicated doc test showing the end-to-end pattern.

alice-i-cecile

Nice! I quite like this, but there are some things to clean up before we merge.

Easier than I expected overall; good work :)

alice-i-cecile · 2026-05-07T22:08:40Z

    }
+
+    #[test]
+    fn delayed_queues_can_be_cancelled() {


It would be nice to test the idempotency of repeated cancellations, and the cancellation of commands that have already fired. Those should already pass, but they're tricky race condition bugs that we should protect against defensively.

Runi-c · 2026-05-07T22:17:07Z

+            let handle = {
+                let mut delayed_cmds = commands.delayed();
+                let (mut delayed, handle) = delayed_cmds.secs_with_handle(0.1);
+                delayed.spawn(DummyComponent);


Note that the entity for this spawn command is allocated immediately. If the delayed command is then canceled, the allocated entity is never spawned nor freed for reuse. This was what stopped me from adding cancelling to the original PR and I don't see a solution here.

Could you track this in the handle, and then free it? You'd need a Vec, since there could be multiple entities queued up.

This is quite complex: see #18670 and the code added there for more context on exactly how Bevy's entity lifecycle works :)

The key API you'll need to clean up the memory leak of user entities is Entities::free_many :)

Tracking it in the handle might be possible but there needs to be a proxy or facade for Commands::spawn and Commands::spawn_empty in order to "catch" allocations and somehow send/store them in the handle. As far as I can tell no other commands have this pre-allocation behavior (right now anyway! this would need to be carefully documented so future additions don't leak entities)

alice-i-cecile · 2026-05-07T22:59:04Z

This is the Github profile of NewN on Discord, who was previously warned for submitting AI generated code in opposition to our AI Policy. They were banned from Discord due to hostility and pushiness when confronted on this. They have been blocked from this repo and reported to Github as a result.

The discussion here is still useful here: I would welcome attempts to do it properly, but you will need to manually reconstruct this work from scratch to be compliant with our policy.

feat(time): allow cancelling delayed commands

f02b0f3

github-project-automation Bot added this to ECS May 7, 2026

github-project-automation Bot moved this to Needs SME Triage in ECS May 7, 2026

alice-i-cecile reviewed May 7, 2026

View reviewed changes

alice-i-cecile requested changes May 7, 2026

View reviewed changes

alice-i-cecile reviewed May 7, 2026

View reviewed changes

Runi-c reviewed May 7, 2026

View reviewed changes

alice-i-cecile added S-Adopt-Me The original PR author has no intent to complete this work. Pick me up! and removed S-Needs-Review Needs reviewer attention (from anyone!) to move forward labels May 7, 2026

alice-i-cecile closed this May 7, 2026

github-project-automation Bot moved this from Needs SME Triage to Done in ECS May 7, 2026

alice-i-cecile mentioned this pull request May 7, 2026

Add the ability to cancel delayed commands #24175

Open

Uh oh!

Uh oh!

Conversation

Daedalus-Icarus commented May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Objective

Solution

Testing

Showcase

Uh oh!

alice-i-cecile commented May 7, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alice-i-cecile May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alice-i-cecile left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Runi-c May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Runi-c May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

alice-i-cecile commented May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Daedalus-Icarus commented May 7, 2026 •

edited

Loading

alice-i-cecile May 7, 2026 •

edited

Loading

Runi-c May 7, 2026 •

edited

Loading

Runi-c May 7, 2026 •

edited

Loading