Flame - Introduction

本記事はFlame公式ドキュメントを学習した内容を整理しています。

Flameとは

FlameはFlutterゲームエンジンでFlutterが提供するインフラストラクチャを活用しながら、プロジェクトの構築に必要なコードを簡素化する。

Flameはシンプルで効果的なゲームループの実装と、ゲームに必要な機能を提供する。入力、画像、スプライト、スプライトシート、アニメーションなどの操作、衝突検出とFCS(Flame Component System)と呼ばれるコンポーネントシステムを提供する。

GameWidget

GameWidgetは、FlutterウィジェットツリーにGameインスタンスを挿入するために使用されるFlutterウィジェットだ。

GameWidgetはFlutterアプリケーションのルーツとしても実行できる。

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

GameWidgetは通常のFlutterウィジェットであり、1つのアプリ内に複数のGameWidgetを持つこともできる。上のコードのようにルートウィジェットとして使用すると、アプリが全画面表示になる。

GameWidgetは次の機能をサポートする。

• loadingBuilder：ゲームのロード中に何か表示できる。
• errorBuilder：ゲームがエアーをスローした場合に表示できる。
• backgroundBuilder：ゲームの背景を描画できる。
• overlaBuilderMap：ゲームの上に1つ以上のウィジェットを描画できる。

FlameGameクラス

FlameGameクラスは、コンポーネントベースのゲームを実装する。このコンポーネントのシステムを、Flame Component Systemu（FCS）と呼ぶ。FlameGameクラスは、コンポーネントツリーがあり、ゲームに追加されたすべてのコンポーネントのupdateメソッドとrenderメソッドを呼び出す。

ライフサイクル

graph TB
    m1(onGameResize) --> m2(onLoad)
    m2(onLoad) --> m3(onMount)
    m3(onMount) --> m4(update)
    m4(update) --> m5(render)
    m5(render) --> m4(update)
    m5(render) -.-> m6(onRemoved)
    m6(onRemoved) -.-> m1
    classDef runOnce fill:#f6be00,stroke:#f6be00,color:#000000
    classDef runAdd fill:#523f00,stroke:#f6be00,color:#ffffff
    classDef runTick fill:#282828,stroke:#f6be00,color:#ffffff
    class m1 runAdd
    class m2,m3,m6 runOnce
    class m4,m5 runTick

FlameGameが最初にGameWidgetを追加されると、onGameResize、onLoad、onMountの順で呼び出される。その後ゲームティックごとにupdateとrenderが順番に呼び出される。FlameGameがGameWidgetから削除されるとonRemoveが呼び出される。

onGameResizeは追加された時とリサイズされた時のみ、onLoadとonMountは最初の１回のみ、onRemoveは削除されるときの１回のみ、updateとrenderは毎ティックごとに呼び出される。

コンポーネント

graph TB
    c01(Component) --> c03(TimerComponent<br>ParticleComponent<br>SpriteBatchComponent)
    c01 --> c04(Effects<br>)
    c01 --> c05(PositionComponent)
    c01 --> c06(FlameGame)
    c02(Game) --> c06
    c05 --> c07(SpriteComponent<br>SpriteGroupComponent<br>SpriteAnimationComponent<br>SpriteAnimationGroupComponent<br>ParallaxComponent<br>IsoMetricTileMapComponent)
    c05 --> c08(HudMarginComponent)
    c05 --> c09(ButtonComponent<br>CustomPainterComponent<br>ShapeComponent<br>SpriteButtonComponent<br>TextComponent<br>TextBoxComponent<br>NineTileBoxCompnent)
    c08 --> c10(HudButtonComponent<br>JoysticComponent)
    classDef comp fill:#f6be00,stroke:#f6be00,color:#000000
    class c01,c02,c03,c04,c05,c06,c07,c08,c09,c10 comp

すべてのコンポーネントはComponent抽象クラスを継承し、他のコンポーネントを子として持つことができる。

子コンポーネントはaddメソッドを使って追加するかコンストラクターで渡して追加する。

コンポーネントのライフサイクル

コンポーネントのライフサイクルはFlameGameのライフルサイクルと似ている。

graph LR
    m1(onLoad) --> m2(onGameResieze)
    m2 --> m3(onMount)
    m3 --> m4(update)
    m4 --> m5(render)
    m5 --> m4
    m5 -.-> m6(onRemove)
    m6 -.-> m1
    classDef runOnce fill:#f6be00,stroke:#f6be00,color:#000000
    classDef runAdd fill:#523f00,stroke:#f6be00,color:#ffffff
    classDef runTick fill:#282828,stroke:#f6be00,color:#ffffff
    class m2 runAdd
    class m1,m3,m6 runOnce
    class m4,m5 runTick

onGameResizeメソッドは、画面のサイズが変更されるたびに呼び出される。コンポーネントツリーに追加されるときにonMountメソッドの前に呼び出される。

onRemoveメソッドは、コンポーネントがゲームから削除される前にコードを実行するようにオーバーライドできる。

onLoadメソッドをオーバーライドして、画像のロードなど、コンポーネントの非同期初期化コードを実行できる。１回のみ呼び出されるため、非同期コンストラクターと考えることができる。

onMountメソッドは、コンポーネントがゲームツリーにマウントされるたびに実行される。これは何度も実行される可能性があるため、late変数の初期化を行うべきではない。

onChildrenChangedメソッドは、子コンポーネントの変更を検出する必要がある場合、オーバーライドできる。子が親に追加される時と削除される時、その度に呼び出される。

コンポーネントのライプサイクル状態は次のゲッターで確認できる。

• isLoaded：現在のロード状態をブール値で返却する。
• loaded：ロードが完了するとFutureで返却する。
• isMounted：現在のマウント状態をブール値で返却する。
• mounted：マウントが完了するとFutureで返却する。
• isRemoved：現在の削除状態をブールで返却する。
• removed：削除が完了するとFutureで返却する。

Priority

すべてのコンポーネントにはpriorityプロパティがあり、CSSのz-indexのように使える。

コンポーネントツリーの中で並べ替え順序を決めるもので、優先順位を高くすると優先順の低いコンポーネントより上に描画される。