feat: Add input, world snapshot and diff commands to flame_cli - #4057
Merged
Merged
Conversation
spydon
added this pull request to stack #4058
September 25, 2026 16:13
4 of 5 tasks
spydon
force-pushed
the
feat/flame-cli-input
branch
2 times, most recently
from
September 30, 2026 13:05
e649860 to
7eb2be4
Compare
spydon
force-pushed
the
feat/flame-cli-input
branch
2 times, most recently
from
September 30, 2026 13:14
bde7eda to
a96f31c
Compare
erickzanardo
approved these changes
Sep 30, 2026
A new InputConnector delivers synthetic taps, drags and key presses through the game's dispatchers. getGameSnapshot can render the world directly, in full or for a rect in world coordinates, and snapshotting the World component now renders its children. The diff command compares two PNG images and reports the differing pixels and their bounding rectangle.
The categories sort alphabetically in the order the commands are typically used: launching, observing, pausing and changing, and playing the game.
spydon
force-pushed
the
feat/flame-cli-input
branch
from
September 30, 2026 14:55
a96f31c to
4bae36c
Compare
spydon
added a commit
that referenced
this pull request
Sep 30, 2026
…e style command (#4059) Stacked on #4057. This brings the scaffolding of [ignite_cli](https://pub.dev/packages/ignite_cli) into `flame_cli` as `flame create`, structured like `flutter create`: no interactive prompts, a positional output directory, sensible defaults and options to change them. ```shell flame create my_game cd my_game flame run ``` How it works: - `flutter create --empty` generates the platform folders and the `pubspec.yaml`, with `--project-name`, `--org`, `--description`, `--platforms` and `--overwrite` passed through. - The files of the chosen template (`--template simple|basics|example`, `basics` by default) are written on top, plus an `analysis_options.yaml` that includes `flame_lint`. - `flutter pub remove flutter_lints` and `flutter pub add flame dev:flame_lint [dev:flame_test] [--packages ...]` set up the dependencies. Using `pub add` means the game always starts on the newest compatible versions, without a version list baked into the CLI or fetched from pub.dev the way ignite did. `--flame-version ^1.30.0` pins a constraint when needed. - The project name defaults to the directory name and is validated with the same rules as `flutter create` (a lowercase Dart identifier that is not a keyword or a clashing package name), with a suggestion when it is invalid. An existing project is not touched without `--overwrite`. The three templates are updated versions of ignite's: - `simple`: an empty `FlameGame` in a `GameWidget`. - `basics`: a world with a component that starts moving when tapped, and a `FlameTester` widget test for it. - `example`: a small complete game over a few files: a world, a camera with a score in the viewport, a player steered with the arrow keys or by tapping, stars to collect through collision detection, and four `testWithGame` tests. The command shows up in a new "Creating a game" group at the top of `flame --help`. Tests use a fake `flutter` process and check the exact command sequence, the written files, the options, the overwrite guard, the validation and the failure path. I also created a game from each template with the real `flutter`: all three pass `flutter analyze`, `basics` and `example` pass `flutter test`, and the example runs under `flame run` on `flutter-tester`.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Stacked on #4056. This turns the CLI from an observer into something that can play test a game,
and gives agents a way to compare snapshots that does not rely on eyeballing two images.
InputConnectorinflameregistersext.flame_devtools.tap,dragandkey. Tapsand drags are delivered through the game's
MultiTapDispatcherandMultiDragScaleDispatcher,so they reach
TapCallbacksandDragCallbackscomponents with the same propagation as realinput, in canvas coordinates (the same as the pixels of a snapshot). Keys go to
onKeyEventofa
HasKeyboardHandlerComponentsorKeyboardEventsgame, withpress,downandupactions. Key names are matched against the
LogicalKeyboardKeynames without regard to case,spaces and underscores (
arrowLeft,Arrow Left,space,a,digit1). A missing mixin isreported as an invalid parameters error instead of silently doing nothing.
flame input tap <x,y>,flame input drag <x,y> <x,y> [--steps N]andflame input key <name> [--down|--up]call those.getGameSnapshottakesworld=trueorrect=x,y,w,hto render the world directly without thecamera, so off screen components are visible. Without a rect the image covers the bounding
rectangle of all the position components in the world.
flame snapshot --worldand--rectexpose it. Snapshotting theWorldcomponent itself used to give a blank 100x100image, since
World.renderTreeis a no-op, it now renders the world's children the same way.flame diff <before.png> <after.png> [--output diff.png] [--threshold N] [--exit-code]reports the percentage of differing pixels and the bounding rectangle of the change, and can
write an image with the changes in red on a dimmed copy of the second image. This adds the
imagepackage as a dependency offlame_cli.Tests cover the input connector with real components (tap position, drag steps, key down and up
with the pressed set, the missing mixin messages, key name lookup), world bounds and world
snapshots, the diff algorithm and command, and the usage errors of the new commands. Verified
end to end on the
flutter-testerdevice: a tap toggled a component's color andflame diffreported exactly the 200x100 rectangle at 300,250 with exit code 1, a drag and arrow keys moved
the component, and
--worldand--rectrendered an off screen component.Checklist
docsand added dartdoc comments with///.examplesordocs.Breaking Change?
Related Issues