Add a timer-powered DelayedCommand for delayed ECS actions

[alice-i-cecile]

Objective

• Being able to delay effects until a later point in time is a helpful tool for gameplay logic.
• Doing so in a generalized way is surprisingly tricky.
• Fixes Add a TimedCommands SystemParam for easier delayed operations #15129

Solution

Create a DelayedCommand command, which wraps another command, moves it into the world as an entity, and then ticks down until it's time to evaluate, despawning itself.

An equivalent DelayedEntityCommand is also provided to allow for easier usage with entity commands.

TODO

• get to a functioning proof of concept
  • we can't send arbitrary Boxed commands, because Commands::queue requires HandleError
  • HandleError is not dyn compatible, so we cannot simply add it to the box via a helper trait
  • I didn't want to just pass around FnOnce closures, because then you can't use this for commands that store data
  • maybe we can make HandleError dyn compatible?
  • maybe we can somehow just not handle errors at all?
  • we could add a generic instead of boxing, and then split apart the command from the timer? You need the split to be able to tick all these timers in a single system
  • a generic would also want a dedicated queue_delayed API for usability
• make sure this works for both fixed and virtual time
• add an EntityCommand variant
• beef up the docs
• add this to the Bevy book
• write draft release notes

[alice-i-cecile]

Having written up a problem description, I'm reasonably confident that the generic is the least fragile and complex option. And also the most likely to work! It is extremely annoying that boxed commands were broken by error handling (or maybe they never worked), but that's not this PR's problem to solve TBH.

[ItsDoot]

This feels weird to me. Why not have users spawn/insert it like other components? We don't impl Command for Observer, for example.

[alice-i-cecile]

Oh, that's an interesting API idea 🤔

[ItsDoot]

We'll also want to support delayed commands in both Update and FixedUpdate. Currently this seems to only cover Update.

[cBournhonesque]

There's a perf cost to this; maybe we could have a pre-existing entities that gets re-used?
(and eventually it would be on a resource when resource-as-components lands)

[alice-i-cecile]

I think I'm alright with the performance cost here. Better inspectability + cancellation + a simpler implementation is worth it IMO.

I don't expect this to be super hot, and users can comfortably add their own abstraction if it is.

[tacuna]

In my similar implementation it does not tick down but has the delay as a point in the future (initialized as: timer.elapsed() + duration). So instead of ticking down it just compares

let current_time = time.elapsed();
for (entity, delayed_command) in &delayed_commands {
    if delayed_command.delay <= current_time {
        commands.entity(entity).queue(EvaluateDelayedCommand);
    }
}

upside, you can have the query as none mut and have no math operations. Not sure there are any downsides.

[alice-i-cecile]

Oh that's super clever. Good idea!

[chescock]

If you make it an immutable component, you could even index it using a priority queue so that you only need to check the time of the next delayed command! Although if we're expecting these commands to frequently be despawned or have their timers changed then you might have to remove them from the queue early.

[chescock]

• we can't send arbitrary Boxed commands

In case it helps: you can convert an impl Command into a Box<dyn FnOnce> by calling apply in a closure:

fn command_to_boxed_fn(command: impl Command) -> Box<dyn FnOnce(&mut World) + Send + 'static> {
    Box::new(|world| command.apply(world))
}

And Box<dyn FnOnce> is a Command.

It is extremely annoying that boxed commands were broken by error handling (or maybe they never worked)

I think they never worked, and the issue is that Command::apply takes self by value. Rust uses some unstable magic to make Box<dyn FnOnce> work.

The blanket impl<C: Command> HandleError for C means commands that return () already impl HandleError, so error handling shouldn't have changed anything.

[laundmo]

I've had a look at this, and i don't really like the API it provides. Having to manually instantiate and pass command structs to it is a bit clunky.

Instead, i came up with a draft which allows using the same Commands API people are used to. This is currently working in one of my projects.

The idea stems from the fact that all commands which Commands creates are written to a command queue, so if we make a new Commands with our own queue, and then store it somewhere (a component, in this case), its very easy to later just... append all those stored commands to the current command queue. Theoretically its possible to do this with a chained API as well, like commands.delayed(duration).spawn(), but that makes it basically impossible to delay multiple commands, some of them entity-commands, for the same duration (a feture which the usage of CommandQueue gets us for free).

Usage:

let ent = commands.spawn_empty();
commands.delayed(Duration::from_secs(5), move |mut c|{
    c.entity(ent).despawn();
});

Implementation:

struct DelayedCommands<C: FnOnce(Commands) + Send + Sync + 'static> {
    delay: Duration,
    write_commands: C,
}
trait DelayedCommandsExt {
    fn delayed(
        &mut self,
        delay: Duration,
        write_commands: impl FnOnce(Commands) + Send + Sync + 'static,
    );
}
impl DelayedCommandsExt for Commands<'_, '_> {
    fn delayed(
        &mut self,
        delay: Duration,
        write_commands: impl FnOnce(Commands) + Send + Sync + 'static,
    ) {
        self.queue(DelayedCommands {
            delay,
            write_commands,
        });
    }
}
impl<C: FnOnce(Commands) + Send + Sync + 'static> Command for DelayedCommands<C> {
    fn apply(self, world: &mut World) {
        let mut command_queue = CommandQueue::default();
        (self.write_commands)(Commands::new(&mut command_queue, world));
        world.spawn(DelayedCommandQueue(
            Timer::new(self.delay, TimerMode::Once),
            command_queue,
        ));
        println!("spawned delayed command queue");
    }
}

#[derive(Component)]
struct DelayedCommandQueue(Timer, CommandQueue);

fn command_after(
    cmds: Query<(Entity, &mut DelayedCommandQueue)>,
    time: Res<Time>,
    mut commands: Commands,
) {
    for (e, mut cmd) in cmds {
        if cmd.0.tick(time.delta()).just_finished() {
            commands.append(&mut cmd.1);
            commands.entity(e).despawn();
        }
    }
}

[github-actions]

It looks like your PR has been selected for a highlight in the next release blog post, but you didn't provide a release note.

Please review the instructions for writing release notes, then expand or revise the content in the release notes directory to showcase your changes.

[laundmo]

@alice-i-cecile are the changed labels a way to ask/nudge me to make a new PR with my version or...?

[alice-i-cecile]

@alice-i-cecile are the changed labels a way to ask/nudge me to make a new PR with my version or...?

This would be nice! It's also a way to signal that I'm not immediately going to return to this work, so others are welcome to pick it up.