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.