Bonfire Game Engine

To ensure stability on Android, it is recommended to disable Impeller. Add the following <meta-data> tag inside the <application> tag of your AndroidManifest.xml file.

<meta-data
    android:name="io.flutter.embedding.android.EnableImpeller"
    android:value="false" />

When building your Bonfire game for the Web, use the canvaskit renderer to ensure optimal performance and compatibility.

flutter build web --web-renderer=canvaskit

The MatrixLayer class (used within MatrixMapGenerator.generate) includes an axisInverted property.

• If axisInverted is false (default): The generator treats the matrix as matrix[x][y].
• If axisInverted is true: The generator treats the matrix as matrix[y][x]. This is useful for mapping standard 2D arrays where the first index represents the row (Y) and the second represents the column (X).

The ListenerGameWidget is a StatefulWidget responsible for attaching a Flame Game instance into the Flutter widget tree. It handles the game lifecycle (loading, mounting, resizing), input detection (pointer, keyboard, mouse), and provides mechanisms for loading states, error handling, and UI overlays.

To use it, provide an instance of your game class to the game parameter. You can also provide a loadingBuilder to show a widget while the game is loading and an errorBuilder to handle errors during the onLoad phase.

// Inside a State...
late MyGameClass game;

@override
void initState() {
  super.initState();
  game = MyGameClass();
}

// ...

@override
Widget build(BuildContext context) {
  return ListenerGameWidget(
    game: game,
  );
}

Use these builders to improve the user experience during the game's initialization phase:

• loadingBuilder: A GameLoadingWidgetBuilder that returns a widget to be displayed while the game's onLoad and onMount futures are resolving. Defaults to an empty Container().
• errorBuilder: A GameErrorWidgetBuilder that returns a widget if an error occurs during the onLoad method. If not provided, errors are propagated up the Flutter tree.

Control how the game receives user input:

• focusNode: A FocusNode to control the game's focus. If omitted, an internal node is used.
• autofocus: A bool that determines if the focusNode should request focus once the game is mounted. Defaults to true.
• mouseCursor: A MouseCursor to be used when hovering over the game area.
• initialActiveOverlays: A List<String> of overlay keys that should be active immediately upon mounting.

Customize the visual environment surrounding the game:

• backgroundBuilder: A WidgetBuilder that provides a widget tree to be built behind the game elements but in front of the Game.backgroundColor.
• textDirection: Sets the TextDirection (e.g., TextDirection.ltr) for text elements within the game context.

The following packages extend Bonfire's functionality:

• bonfire_bloc: Integration with the BLoC pattern for state management.
• bonfire_spine: Integration with Spine for 2D skeletal animation.

You can render Flutter widget layers over the game surface using the overlayBuilderMap. To use overlays, your game subclass must be mixed with HasWidgetsOverlay.

1. Define the overlays in the overlayBuilderMap using a Map<String, OverlayWidgetBuilder<T>> where the key is the overlay name.
2. Control the visibility of these overlays using the Game.overlays property (e.g., game.overlays.add('PauseMenu')).

Example of defining a 'PauseMenu' overlay:

final game = MyGame();

Widget build(BuildContext context) {
  return ListenerGameWidget(
    game: game,
    overlayBuilderMap: {
      'PauseMenu': (ctx, game) {
        return Text('A pause menu');
      },
    },
  );
}

// To show the menu:
// game.overlays.add('PauseMenu');