概要
このガイドでは、ギャラリーでペットを選び、自分のプロジェクトに追加し、デバイスの状態に反応させるまでの手順を説明します。
関連するガイドも 2 つあります。基本的な概念を理解したい場合は、まずスプライトとは何か？をお読みください。独自のペットを公開したい場合は、ペットの投稿方法をご覧ください。この記事では、すでに作られているペットを自分のプロジェクトで使う手順を紹介します。
アニメーションの事前知識は不要です。「プロジェクトに追加」をクリックしてウィジェットをキャンバスにドラッグできれば、ESP32やLVGLプロジェクトに生き生きと反応するキャラクターを追加できます。
ペットとは何か？
ペットとはスプライトのことです。複数の異なるアニメーションを持ち、必要なときにそれらを切り替えられる単一のウィジェットです。各アニメーションはモード（状態またはフェーズとも呼ばれる）です。例えば「Idle」「Run right」「Jumping」などがあります。
CodexまたはPetdex形式のパックから提供されるペットは、通常9つのモードが初期状態で含まれています。例えば Idle、Run right、Run left、Waving、Jumping、Failed、Waiting、Running、Review などです。各モードはそれぞれのフレームを繰り返すアニメーションで、どれをいつ再生するかはあなたが決めます。
1 つのウィジェットで複数の動作を管理し、設定した条件に応じて切り替えられるのが特徴です。
LVGL は、複数の状態を持つスプライトを標準では提供していません。PicoPixel では、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タブを開き、Add libraryを選択します。
- Publishをクリックします。
次に、別のプロジェクトから使用するには：
- 新規または既存のワークスペースを開きます。
- Add libraryを選択します。
- 下図のようにSHARED LIBRARIESリストからペットのライブラリをリンクします。
リンクすると、そのワークスペースのAssetsにスプライトが表示されます。キャンバスにドラッグ＆ドロップするだけで、すべてのモードが設定された状態で追加されます。
ライブラリはチーム内での再利用を目的としており、一般公開するためのものではありません。ライブラリに含まれる内容、チーム内での共有の仕組み、リンクされたライブラリがどこに表示されるかについては、ライブラリと再利用可能コンポーネントのガイドをご覧ください。
3. プロジェクトのプロパティをハードウェアに合わせて変更する
ペットプロジェクトのプロパティ（画面サイズ、ターゲットボード）をデバイスに合わせて編集し、直接そこでビルドすることもできます。これは機能しますが、推奨される方法ではありません。ペットの元データと製品の UI を別々に管理しにくくなるためです。ペットのプロジェクトは、実機用のひな型ではなく見本として用意されています。まずオプション1または2を試してください。
接続：ペットを反応させる
ペットを操作や状態の変化に反応させるには、イベントエディタでモードを切り替える条件を設定します。
パターンはシンプルです。何かが起きたとき、モードを切り替える。トリガー（ボタン押下、値の変化、タイマー）を選び、アクションSet Sprite Modeと再生するモードを指定します。
下のスクリーンショットでは、JUMP!ボタンにイベントを追加しました。クリックされると、アクションがスプライトのモードをJumpingに設定し、ボタンが押された瞬間にペットがジャンプします。
トリガーをプロジェクトが提供するもの（センサーの読み取り、APIコールの完了、タイマーの発火）に置き換えれば、同じ接続でペットがそれに反応します。トリガー、ソース、アクションの完全な解説についてはイベントエディターの使い方をご覧ください。
注意事項
実際のハードウェアでペットを見栄え良く、スムーズに動作させるためのポイントをいくつか紹介します。
- **使わないモードは削除する。**これはメモリ節約に効果があります。保持するモードが多いほど、より多くのフレームがメモリに保存され、未使用のものは不要なメモリ消費になります。ストレージやメモリの制約があるボードでは特に重要です。トリガーする予定のないモードは削除しましょう。
- **イベントを忘れずに。**ペットは自分では何もしません。上でJUMP!ボタンを接続したように、再生したい各モードの条件をイベントエディターで追加してください。
- **デバイスのメモリに注意する。**アニメーション画像はフレームを保持するのに十分なRAMが必要です。エクスポートされたLVGLコードの
README.mdファイルをコーディングアシスタントに参照させてください（そこに記載されています）。または、アニメーション画像に十分なメモリを自分で確保してください。実機への書き込み後にスプライトが表示されない場合、ほぼ間違いなくこれが原因です。
スプライトは重くなる可能性があります。小さなマイコンでは、9つのモードすべてと大きなフレームを持つペットがメモリを使い果たし、画面に表示されなくなることがあります。実際に使うモードだけに絞り込み、LVGL設定がアニメーション画像に十分なRAMを割り当てていることを確認してください。
次のステップ
- スプライトとは何か？：モード、フレーム、再生時間の基本。
- イベントエディターの使い方：ペットを反応させるためのすべてのトリガーとアクション。
- ライブラリと再利用可能コンポーネントのガイド：ペットを一度共有してどこでも再利用する。
- ペットの投稿方法：独自のペットを作成してコミュニティと共有する。
- ペットギャラリー：コミュニティのペットを閲覧して別のペットを入手する。
