docs for the console

doc/bridge_packages/flame_console/flame_console.md

@@ -0,0 +1,105 @@
+# 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 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, 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 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() : super('my_command', '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: {
+    'custom_cmd': 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/README.md

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