【Flame 學習筆記】GameWidget 元件介紹

【Flame 學習筆記】系列文章目錄：連結

【Flutter 學習筆記】線上課程教學影片：連結

【Flutter 學習筆記】系列文章目錄：連結

在 Flutter 開發中，若你想要將遊戲實例嵌入到 Flutter 的 widget 樹中，GameWidget 是一個不可或缺的工具。這個 widget 不僅功能強大，還能作為你 Flutter 應用程式的根部件，讓我們一起來看看如何使用它。

基本用法

使用 GameWidget 的最簡單方式如下：

void main() {
  runApp(
    GameWidget(game: MyGame()),
  );
}

這段程式碼展示了如何將 MyGame 的實例傳遞給 GameWidget，並將其作為應用程式的根部件。值得注意的是，GameWidget 也可以被嵌入到 widget 樹的任意深度，這意味著在同一個應用程式中可以有多個 GameWidget 實例。

佈局行為

GameWidget 的佈局行為是自動擴展以填滿所有可用空間。因此，當它作為根部件使用時，應用程式將會全螢幕顯示；而在其他佈局 widget 中使用時，它也會盡可能佔用空間。

結構支援功能

除了承載遊戲實例外，GameWidget 還提供了一些結構支援功能，包括：

• loadingBuilder：在遊戲加載時顯示的 widget。
• errorBuilder：當遊戲發生錯誤時顯示的 widget。
• backgroundBuilder：在遊戲後面繪製裝飾的 widget。
• overlayBuilderMap：在遊戲上方繪製一個或多個 widget。

需要注意的是，GameWidget 不會裁剪其畫布的內容，這意味著遊戲可能會在邊界外繪製（這取決於使用的相機）。如果不希望這樣，可以考慮將 widget 包裝在 Flutter 的 ClipRect 中。

建構子

GameWidget 提供了兩個建構子：

1. GameWidget：用於渲染提供的遊戲實例。

   GameWidget({required this.game, ...})

2. GameWidget.controlled：這個建構子會創建並擁有一個遊戲實例，使用提供的 gameFactory。

   GameWidget.controlled({required this.gameFactory, ...})
   

這個建構子特別適合當你想將 GameWidget 放入另一個 widget 中，但又不想自己儲存遊戲實例的情況。例如：

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Container(
      padding: EdgeInsets.all(20),
      child: GameWidget.controlled(
        gameFactory: MyGame.new,
      ),
    );
  }
}

屬性介紹

• game：要渲染的遊戲實例，若使用 controlled 建構子則為 null。
• gameFactory：創建遊戲的函數。
• textDirection：遊戲中文字元素的方向。
• loadingBuilder：加載時顯示的 widget，預設為空的 Container。
• errorBuilder：加載過程中出現錯誤時顯示的 widget。
• backgroundBuilder：在遊戲元素和背景顏色之間構建的 widget 樹。
• overlayBuilderMap：可在遊戲表面上顯示的 widget 集合。
• initialActiveOverlays：遊戲啟動時顯示的 overlay 列表。
• focusNode：控制遊戲焦點的 FocusNode。
• autofocus：遊戲掛載後是否請求焦點，預設為 true。
• mouseCursor：當鼠標懸停在遊戲畫布上時的鼠標形狀。
• addRepaintBoundary：遊戲是否應該假設 RepaintBoundary 的行為，預設為 true。