[spydon]

Description

Adds a flame wait command to flame_cli that blocks until a condition holds in the running game, or until a timeout is reached, so that scripts and AI agents don't need sleep loops and guessed timings. For example, tap a button and then wait until the game over overlay is shown:

flame input tap 400,300
flame wait overlay GameOver

The conditions are subcommands, like overlay show and input tap:

• wait component <type pattern>: a component whose type matches the regular expression exists, matched case insensitively like tree --filter. --id matches a single component, --count waits for an exact number of matches, --at-least for a minimum number, and --gone until nothing matches, which covers waiting until a component is removed (flame wait component --id 123 --gone). --where "position.x > 100" compares a numeric attribute from the same data that tree and inspect return (position.x, position.y, size.x, size.y, scale.x, scale.y, angle and priority), and can be given several times.
• wait overlay <name>: the overlay is shown, or hidden with --hidden. An unregistered overlay fails right away with 65.
• wait paused and wait resumed: the game loop is paused or running.

All of them take --timeout (10 seconds by default, 0 checks once and works as an assertion), --interval (0.2 seconds by default) and --json. When the condition holds, the command prints what matched, for example the matching components with their ids and attributes, and exits with 0. When the timeout is reached first it says what it found instead, for example Timed out after 10 seconds waiting for a component with a type matching enemy, found 0., and exits with 75 (ExitCode.tempFail), which is added to the documented exit codes. A game that doesn't answer a check in time, for example because it is stopped at a breakpoint, also fails with 75 instead of blocking the command past its timeout.

The command polls the existing getComponentTree, getOverlays and getPaused service extensions over one connection, so nothing changes on the game side. The clock is injectable through a WaitClock passed to FlameCommandRunner, so the tests are fast and deterministic.

To support this:

• FlameCommand takes an optional connect, and the runner passes its connector to the wait command, so that commands talking to a game can be tested with a fake connection.
• FlameConnection.call now reports a closed connection, which is what happens when the game stops while a command is waiting, as The game is no longer running with exit code 69, instead of the generic 70 error. FlameConnection.withService creates a connection from an existing VmService, which the tests use.
• findComponentNodes in component_tree.dart returns the matching nodes of the tree.

The command is documented in the CLI docs and the readme.

Checklist

• I have followed the Contributor Guide when preparing my PR.
• I have updated/added tests for ALL new/updated/fixed functionality.
• I have updated/added relevant documentation in docs and added dartdoc comments with ///.
• [-] I have updated/added relevant examples in examples or docs.

Breaking Change?

• Yes, this PR is a breaking change.
• No, this PR is not a breaking change.

Related Issues

Part of #4131