概要
このガイドでは、PicoPixel のスプライトについて必要なことを一通り説明します。スプライトとは何か、いつ使うべきか、自分で段階的に作る方法、画面上の出来事に反応させる方法、そして同じものを二度作らなくて済むように再利用する方法です。
アニメーション経験は不要です。画像をドラッグ＆ドロップできるなら、スプライトを作れます。
スプライトとは
スプライトは、複数のアニメーションを保持し、好きなタイミングで切り替えられる 1 つの PicoPixel ウィジェットです。各アニメーションは モード または 状態 と呼ばれます。たとえば "Idle"、"Running"、"Happy" です。
ビデオゲームのキャラクターのように考えてください。画面上では 1 つのキャラクターですが、状況に応じて歩いたり、跳んだり、手を振ったりします。スプライトも同じです。1 つのウィジェットに複数の動きを持たせ、必要なものを再生できます。
PicoPixel の強力なイベントエディタを使えば、条件に応じて状態を切り替え、スプライトに命を吹き込めます。
例：アニメーションキャラクターがある場合、または ESP32 や他の LVGL アプリ向けに自分だけのスタックチャンの表情を作りたい場合、1 つのスプライトで "Running"、"Thinking"、"Failed" などのモードを条件付きで切り替えられます。別々のウィジェットを大量に扱う必要はありません。
技術的には、LVGL は異なる状態を持つスプライトをネイティブにはサポートしていません。そのため、LVGL アニメーション画像ウィジェットをベースに独自実装しました。状態ごとの切り替え処理を自分で実装せずに使えます。
スプライトを使う場面
すべての画像をスプライトにする必要はありません。判断の目安は次の通りです。
- 1 枚の静止画像？ 通常の Image を使います。動かないものにスプライトは大げさです。
- 永遠にループする 1 つのアニメーション（回転するローダーなど）？ Animated Image を使います。よりシンプルで軽量です。
- 状況に応じて変化するもの、タスク成功時に笑う顔、待機から走行に切り替わるキャラクターなど？ それこそ スプライト の出番です。
目安として、グラフィックに複数の表情や動作があり、それを切り替えたいならスプライトを選びます。
スプライトの作り方
- "Sprite" ウィジェットを選択します。右サイドバーでそのスプライトの最初のモードを追加できます。たとえば最初の状態は "Idle" かもしれません。あとでトリガーを設定するときに分かるよう、各状態には明確な名前を付けます。
- 画像シーケンス、つまりこのモードを構成するフレーム一式をアップロードします。各フレームは 1 枚の画像で、順番に再生するとパラパラ漫画のようにアニメーションになります。
- その状態専用の再生時間を調整できます。再生時間を長くするとゆっくり、短くすると速く動きます。
- 別の状態を追加します。最低 2 つのモードが必要です。1 つのアニメーションだけでよい場合は、Animated Image ウィジェットが適しています。使い分けの説明もご覧ください。
- Events タブのイベントエディタを使って、条件に応じて異なる状態をトリガーし切り替えます。これがスプライトに生命感を与えます。次のセクションで詳しく説明します。
スプライトのすべてのモードで、すべての画像またはフレームは完全に同じ寸法でなければなりません。あるフレームが 64×64、別のフレームが 80×80 だと正しく揃いません。アップロード前にサイズを合わせてください。
フレーム数と画像サイズは、デバイスのメモリに合わせて調整してください。滑らかさや細かさを求めて増やすほど、メモリも多く使います。書き込み後に表示されない場合は、よくある問題をご覧ください。
スプライトに命を吹き込む
1 つの状態しか表示しないスプライトは、あまり役に立ちません。使いどころに合わせて、いつ モードを切り替えるかを設定しましょう。それを行うのがイベントエディタです。
考え方は単純です。何かが起きたら、状態を切り替える。 そのきっかけ（ボタン押下、値の変化、タイマーなど）を選べば、あとは PicoPixel が処理します。
典型的な例：
- スプライトはデフォルトで "Idle" 状態から始まります。
- イベントエディタでイベントを追加します。ボタンが押されたらスプライトを "Running" 状態に切り替える、という内容です。
- もう 1 つイベントを追加します。タスクが完了したら "Happy"（または "Idle" に戻す）へ切り替えます。
これで完了です。コードを書かなくても、スプライトはユーザー操作に反応します。こうしたイベントをいくつでもつなげて、本当に表情豊かなウィジェットを作れます。
小さく始めましょう。まず 2 つの状態を行き来させ、プレビューで正しく見えることを確認してから、満足したら状態を増やします。
スプライトを再利用する方法
スプライトを作ったら、毎回ゼロから作り直したくはないはずです。Library 機能を使えば一度保存し、任意のプロジェクトに入れられます。
- 完成したスプライトウィジェットを右クリックし、"Add Library Widget" をクリックします。
- Assets タブのライブラリに再利用可能な項目が作られます。すぐ使えるウィジェットの自分用棚だと考えてください。
- そのライブラリをプロジェクト間で移動したり、チームメイトと共有したりするには、Library に移動して Export をクリックします。
- 新しいプロジェクトを作るときや既存ワークスペースを開くとき、そのライブラリをインポートしてスプライトを直接置けます。作り直しは不要です。
- フレーム、再生時間、状態は元のコピーから完全に同期されるので、どこで使っても同じように動きます。
よくある問題
デバイスに書き込むとスプライトが表示されない。
- ほとんどの場合はメモリ問題です。デバイスにはスプライトの画像フレームを保持する十分な RAM が必要です。
- これは LVGL 設定で決まるもので、PicoPixel が代わりに変更できるものではありません。具体的なボードに依存します。
- 書き出された
README.mdファイルにこの点が記載されるので、AI アシスタントが組み込みデバイス向けの SDK/LVGL 設定更新を手伝えます。
フレームがずれて見える、または跳ねる。
- すべての状態のすべてのフレームが完全に同じ寸法であることを確認してください。数ピクセルの違いでも位置合わせが崩れます。
アニメーションが速すぎる、または遅すぎる。
- 該当状態の再生時間を調整します。各状態には独自の再生時間があるため、個別に調整が必要な場合があります。
スプライトを保存できない / もう 1 つ状態を求められる。
- スプライトには最低 2 つの状態が必要です。1 つしかない場合は 2 つ目を追加するか、Animated Image ウィジェットに切り替えてください。
