Merge branch 'flame-engine:main' into main

doc/bridge_packages/flame_console/flame_console.md

@@ -0,0 +1,109 @@
+# flame_console
+
+Flame Console is a terminal overlay for Flame games which allows developers to debug and interact
+with their games.
+
+It offers an overlay that can be plugged in to your `GameWidget` which when activated will show a
+terminal-like interface written with Flutter widgets where commands can be executed to see
+information about the running game and components, or perform actions.
+
+It comes with a set of built-in commands, but it is also possible to add custom commands.
+
+
+## Usage
+
+Flame Console is an overlay, so to use it, you will need to register it in your game widget.
+
+Then, showing the overlay is up to you, below we see an example of a floating action button that will
+show the console when pressed.
+
+```dart
+@override
+Widget build(BuildContext context) {
+  return Scaffold(
+    body: GameWidget(
+      game: _game,
+      overlayBuilderMap: {
+        'console': (BuildContext context, MyGame game) => ConsoleView(
+              game: game,
+              onClose: () {
+                _game.overlays.remove('console');
+              },
+            ),
+      },
+    ),
+    floatingActionButton: FloatingActionButton(
+      heroTag: 'console_button',
+      onPressed: () {
+        _game.overlays.add('console');
+      },
+      child: const Icon(Icons.developer_mode),
+    ),
+  );
+}
+```
+
+
+## Built-in commands
+
+- `help` - List available commands and their usage.
+- `ls` - List components.
+- `rm` - Remove components.
+- `debug` - Toggle debug mode on components.
+- `pause` - Pauses the game loop.
+- `resume` -Resumes the game loop.
+
+
+## Custom commands
+
+ Custom commands can be created by extending the `ConsoleCommand` class and adding them to the
+ the `customCommands` list in the `ConsoleView` widget.
+
+ ```dart
+class MyCustomCommand extends ConsoleCommand<MyGame> {
+  MyCustomCommand();
+
+  @override
+  String get name => 'my_command';
+
+  @override
+  String get description => 'Description of my command';
+
+  // The execute method is supposed to return a tuple where the first
+  // element is an error message in case of failure, and the second
+  // element is the output of the command.
+  @override
+  (String?, String) execute(MyGame game, List<String> args) {
+    // do something on the game
+    return (null, 'Hello World');
+  }
+}
+```
+
+Then when creating the `ConsoleView` widget, add the custom command to the `customCommands` list.
+
+```dart
+ConsoleView(
+  game: game,
+  onClose: () {
+    _game.overlays.remove('console');
+  },
+  customCommands: [MyCustomCommand()],
+),
+```
+
+
+## Customizing the console UI
+
+The console look and feel can also be customized. When creating the `ConsoleView` widget, there are
+a couple of properties that can be used to customize it:
+
+- `containerBuilder`: It is used to created the decorated container where the history and the
+command input is displayed.
+- `cursorBuilder`: It is used to create the cursor widget.
+- `historyBuilder`: It is used to create the scrolling element of the history, by default a simple
+`SingleChildScrollView` is used.
+- `cursorColor`: The color of the cursor. Can be used when just wanting to change the color
+of the cursor.
+- `textStyle`: The text style of the console.
+

packages/flame_console/.gitignore

@@ -0,0 +1,29 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+# Libraries should not include pubspec.lock, per https://dart.dev/guides/libraries/private-files#pubspeclock.
+/pubspec.lock
+**/doc/api/
+.dart_tool/
+build/

packages/flame_console/.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "5874a72aa4c779a02553007c47dacbefba2374dc"
+  channel: "stable"
+
+project_type: package

packages/flame_console/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+* First release

packages/flame_console/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2021 Blue Fire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

packages/flame_console/README.md

@@ -0,0 +1,7 @@
+# Flame Console 💻
+
+Terminal overlay for Flame games which allows developers to debug and interact with their running games.
+
+Check out the documentation
+[here](https://docs.flame-engine.org/latest/bridge_packages/flame_console/flame_console.html) for
+more information.

packages/flame_console/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flame_lint/analysis_options_with_dcm.yaml

packages/flame_console/example/.gitignore

@@ -0,0 +1,45 @@
+# Miscellaneous
+*.class
+*.log
+*.pyc
+*.swp
+.DS_Store
+.atom/
+.buildlog/
+.history
+.svn/
+migrate_working_dir/
+
+# IntelliJ related
+*.iml
+*.ipr
+*.iws
+.idea/
+
+# The .vscode folder contains launch configuration and tasks you configure in
+# VS Code which you may wish to be included in version control, so this line
+# is commented out by default.
+#.vscode/
+
+# Flutter/Dart/Pub related
+**/doc/api/
+**/ios/Flutter/.last_build_id
+.dart_tool/
+.flutter-plugins
+.flutter-plugins-dependencies
+.pub-cache/
+.pub/
+/build/
+
+# Symbolication related
+app.*.symbols
+
+# Obfuscation related
+app.*.map.json
+
+# Android Studio will place build artifacts here
+/android/app/debug
+/android/app/profile
+/android/app/release
+
+devtools_options.yaml

packages/flame_console/example/.metadata

@@ -0,0 +1,30 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: "5874a72aa4c779a02553007c47dacbefba2374dc"
+  channel: "stable"
+
+project_type: app
+
+# Tracks metadata for the flutter migrate command
+migration:
+  platforms:
+    - platform: root
+      create_revision: 5874a72aa4c779a02553007c47dacbefba2374dc
+      base_revision: 5874a72aa4c779a02553007c47dacbefba2374dc
+    - platform: web
+      create_revision: 5874a72aa4c779a02553007c47dacbefba2374dc
+      base_revision: 5874a72aa4c779a02553007c47dacbefba2374dc
+
+  # User provided section
+
+  # List of Local paths (relative to this file) that should be
+  # ignored by the migrate tool.
+  #
+  # Files that are not part of the templates will be ignored by default.
+  unmanaged_files:
+    - 'lib/main.dart'
+    - 'ios/Runner.xcodeproj/project.pbxproj'

packages/flame_console/example/README.md

@@ -0,0 +1,3 @@
+# flame_console example
+
+Example of using the flame console package

packages/flame_console/example/analysis_options.yaml

@@ -0,0 +1 @@
+include: package:flame_lint/analysis_options_with_dcm.yaml

packages/flame_console/example/lib/game.dart

@@ -0,0 +1,90 @@
+import 'dart:async';
+
+import 'package:flame/collisions.dart';
+import 'package:flame/components.dart';
+import 'package:flame/effects.dart';
+import 'package:flame/events.dart';
+import 'package:flame/game.dart';
+import 'package:flame/palette.dart';
+
+class MyGame extends FlameGame with HasKeyboardHandlerComponents {
+  @override
+  FutureOr<void> onLoad() async {
+    await super.onLoad();
+
+    world.addAll([
+      RectangleComponent(
+        position: Vector2(100, 0),
+        size: Vector2(100, 100),
+        paint: BasicPalette.white.paint(),
+        children: [
+          RectangleHitbox.relative(
+            Vector2.all(0.8),
+            parentSize: Vector2(100, 100),
+          ),
+          SequenceEffect(
+            [
+              MoveEffect.by(
+                Vector2(-200, 0),
+                LinearEffectController(1),
+              ),
+              MoveEffect.by(
+                Vector2(200, 0),
+                LinearEffectController(1),
+              ),
+            ],
+            infinite: true,
+          ),
+        ],
+      ),
+      RectangleComponent(
+        position: Vector2(200, 100),
+        size: Vector2(100, 100),
+        paint: BasicPalette.white.paint(),
+        children: [
+          RectangleHitbox.relative(
+            Vector2.all(0.4),
+            parentSize: Vector2(100, 100),
+          ),
+          SequenceEffect(
+            [
+              MoveEffect.by(
+                Vector2(-200, 0),
+                LinearEffectController(1),
+              ),
+              MoveEffect.by(
+                Vector2(200, 0),
+                LinearEffectController(1),
+              ),
+            ],
+            infinite: true,
+          ),
+        ],
+      ),
+      RectangleComponent(
+        position: Vector2(300, 200),
+        size: Vector2(100, 100),
+        paint: BasicPalette.white.paint(),
+        children: [
+          RectangleHitbox.relative(
+            Vector2.all(0.2),
+            parentSize: Vector2(100, 100),
+          ),
+          SequenceEffect(
+            [
+              MoveEffect.by(
+                Vector2(-200, 0),
+                LinearEffectController(1),
+              ),
+              MoveEffect.by(
+                Vector2(200, 0),
+                LinearEffectController(1),
+              ),
+            ],
+            infinite: true,
+          ),
+        ],
+      ),
+    ]);
+  }
+}