概要
このガイドでは、PicoPixelでペットを使う方法を、ディレクトリからの選択から自分のプロジェクトへの組み込み、そしてハードウェアの動作への反応設定まで、ひと通り説明します。
このガイドは他の2つのガイドを直接の前提としています。基本的な概念を理解したい場合は、まずスプライトとは何か？をお読みください。独自のペットを公開したい場合は、ペットの投稿方法をご覧ください。この記事はその中間に位置します。つまり、すでに誰かが作ったペットを使うための実践的なチュートリアルです。
アニメーションの事前知識は不要です。「プロジェクトに追加」をクリックしてウィジェットをキャンバスにドラッグできれば、ESP32やLVGLプロジェクトに生き生きと反応するキャラクターを追加できます。
ペットとは何か？
ペットとはスプライトのことです。複数の異なるアニメーションを持ち、必要なときにそれらを切り替えられる単一のウィジェットです。各アニメーションはモード（状態またはフェーズとも呼ばれる）です。例えば「Idle」「Run right」「Jumping」などがあります。
CodexまたはPetdex形式のパックから提供されるペットは、通常9つのモードが初期状態で含まれています。例えば Idle、Run right、Run left、Waving、Jumping、Failed、Waiting、Running、Review などです。各モードはフレームの独自の小さなループで、どれをいつ再生するかはあなたが決めます。
これが基本的な考え方です。1つのウィジェット、多くの動作、あなたの条件によって切り替えられます。
技術的には、LVGLにはマルチステートスプライトのネイティブな概念はありません。LVGLのアニメーション画像ウィジェットの上に構築することで、すべてのモードが最初から接続された状態になっています。詳細な背景についてはスプライトとは何か？をご覧ください。
なぜペットを使うのか？
ペットは、ESP32やLVGLプロジェクトに命を吹き込むために存在します。静的な顔や単一のループアニメーションの代わりに、スプライトが反応します。デバイスで実際に起きていることに基づいてモードが切り替わります。
元のインスピレーションはコードコンパニオンです。Codex形式の画面で小さなキャラクターがコーディングセッションに反応する様子を想像してください。考えているときはアイドル状態、diffを読んでいるときは「Review」モード、ビルドが失敗したときは「Failed」になります。ペットはアプリの状態を映し出します。
PicoPixelはそれをさらに発展させています。**表現できるあらゆるアクションやトリガーをアニメーション化できます。**いくつかの例を挙げます。
- 温度の読み取り値がしきい値を超えたときにJumpingに切り替える。
- APIからデータを取得している間はRunningを再生し、レスポンスが届いたらIdleに戻る。
- センサーが動きを検出したときにWavingを発動させ、リクエストがタイムアウトしたときにFailedを表示する。
プロジェクトに表示する価値のある状態があれば、ペットはアニメーションコードを一切書かずにそれを表現する、素早く表現力豊かな方法です。
ディレクトリからペットを選ぶ
まずPicoPixelアカウントを作成し、picopixel.io/petsのペットディレクトリにアクセスします。
ギャラリーを閲覧して気に入ったキャラクターを見つけ、その詳細ページを開きます。
ペットの詳細ページでプロジェクトに追加をクリックします。PicoPixelがペットをインポートしてダッシュボードに直接追加します。セットアップもファイル管理も不要です。
追加されたものの確認
ペットを追加すると、そのペットが持つすべてのモードが事前に読み込まれたSpriteウィジェットを含む単一のプロジェクトが作成されます。開くとキャンバスにスプライトが表示され、右側のパネルにすべてのモードがリストされています。Idle、Run right、Run left、Waving、Jumping などが、それぞれのフレーム数と再生時間とともに表示されます。
Spriteウィジェット自体が初めての場合は、スプライトとは何か？ガイドでモード、フレーム、持続時間について詳しく説明しています。
Assetsタブに切り替えると、プロジェクトのローカルライブラリに再利用可能なコンポーネントとして保存された同じスプライトが見つかります。これが実際のプロジェクトにペットを移動させる際の鍵となります。
ペットを使う3つの方法
ペット自身のプロジェクトは実際には配信手段に過ぎません。実際に構築したいプロジェクトに組み込む方法が3つあります。
1. レイヤーをコピー＆ペーストする
最も手軽な方法：ペットプロジェクトのスプライトレイヤーを選択してコピーし、別のプロジェクトを開いてペーストします。スプライトはすべてのモードを保持したまま追加されます。一度だけ使う場合に最適です。このペットを1か所でしか使わないなら、これで完了です。
2. ペットをライブラリにする（再利用に推奨）
複数のワークスペースでペットを使う予定であれば、そのプロジェクトをライブラリにしましょう。ファイルを公開すると、このスプライトを含むアセットがチームのワークスペースのどこでもインポートできるようになります。
公開するには：
- ペットプロジェクトでAssetsタブを開き、ライブラリを追加を選択します。
- 公開をクリックします。
次に、別のプロジェクトから使用するには：
- 新規または既存のワークスペースを開きます。
- ライブラリを追加を選択します。
- 下図のように共有ライブラリリストからペットのライブラリをリンクします。
リンクすると、そのワークスペースのAssetsにスプライトが表示されます。キャンバスにドラッグ＆ドロップするだけで、そのペットのすべてのモードが使える状態で完全に事前設定された状態で読み込まれます。
ライブラリはチーム内での再利用を目的としており、世界に公開するためのものではありません。ライブラリに何が含まれるか、公開の仕組み、リンクされたライブラリがどこに表示されるかについては、ライブラリと再利用可能コンポーネントのガイドをご覧ください。
3. プロジェクトのプロパティをハードウェアに合わせて変更する
ペットプロジェクトのプロパティ（画面サイズ、ターゲットボード）をデバイスに合わせて編集し、直接そこでビルドすることもできます。これは機能しますが、推奨される方法ではありません。ペットと実際のプロジェクトの間のクリーンな分離が失われ、ペットプロジェクトはテンプレートではなくショーケースとして設定されています。まずオプション1または2を試してください。
接続：ペットを反応させる
Idleだけを再生するペットは大した働きをしません。本領を発揮するのはイベントエディターで、いつモードを切り替えるかを設定するときです。
パターンはシンプルです。何かが起きたとき、モードを切り替える。トリガー（ボタン押下、値の変化、タイマー）を選び、アクションSet Sprite Modeと再生するモードを指定します。
下のスクリーンショットでは、JUMP!ボタンにイベントを追加しました。クリックされると、アクションがスプライトのモードをJumpingに設定し、ボタンが押された瞬間にペットがジャンプします。
トリガーをプロジェクトが提供するもの（センサーの読み取り、APIコールの完了、タイマーの発火）に置き換えれば、同じ接続でペットがそれに反応します。トリガー、ソース、アクションの完全な解説についてはイベントエディターの使い方をご覧ください。
注意事項
実際のハードウェアでペットを見栄え良く、スムーズに動作させるためのポイントをいくつか紹介します。
- **使わないモードは削除する。**これは強く推奨されます。保持するモードが多いほど、より多くのフレームがメモリに保存され、未使用のものは純粋なオーバーヘッドになります。ストレージやメモリの制約があるボードでは特に重要です。トリガーする予定のないモードは削除しましょう。
- **イベントを忘れずに。**ペットは自分では何もしません。上でJUMP!ボタンを接続したように、再生したい各モードの条件をイベントエディターで追加してください。
- **デバイスのメモリに注意する。**アニメーション画像はフレームを保持するのに十分なRAMが必要です。エクスポートされたLVGLコードの
README.mdファイルをコーディングアシスタントに参照させてください（そこに記載されています）。または、アニメーション画像に十分なメモリを自分で確保してください。フラッシュ後にスプライトが表示されない場合、ほぼ間違いなくこれが原因です。
スプライトは重くなる可能性があります。小さなマイコンでは、9つのモードすべてと大きなフレームを持つペットがメモリを使い果たし、単純にレンダリングされないことがあります。実際に使うモードだけに絞り込み、LVGL設定がアニメーション画像に十分なRAMを割り当てていることを確認してください。
次のステップ
- スプライトとは何か？：ペットの背後にある概念——モード、フレーム、持続時間。
- イベントエディターの使い方：ペットを反応させるためのすべてのトリガーとアクション。
- ライブラリと再利用可能コンポーネントのガイド：ペットを一度公開してどこでも再利用する。
- ペットの投稿方法：独自のペットを作成してコミュニティと共有する。
- ペットギャラリー：コミュニティのペットを閲覧して別のペットを入手する。
