sprite とは？

何ですか？

sprite は、複数のアニメーションを保持し、好きなタイミングで切り替えられる 1 つの PicoPixel widget です。各アニメーションは mode または state と呼ばれます。たとえば "Idle"、"Running"、"Happy" です。

ビデオゲームのキャラクターのように考えてください。画面上では 1 つのキャラクターですが、状況に応じて歩いたり、跳んだり、手を振ったりします。sprite も同じです。1 つの widget、多くの見た目、どれを再生するかはあなたが決めます。

PicoPixel の強力な event editor を使えば、さまざまな state をトリガーして sprite に命を吹き込めます。

例：アニメーションキャラクターがある場合、または ESP32 や他の LVGL アプリ向けに自分の stack-chan 顔を作りたい場合、1 つの sprite で "Running"、"Thinking"、"Failed" などの mode を条件付きで切り替えられます。別々の widget を大量に扱う必要はありません。

いつ sprite を使うべき？

すべての画像を sprite にする必要はありません。判断の目安は次の通りです。

• 1 枚の静止画像？ 通常の Image を使います。動かないものに sprite は大げさです。
• 永遠にループする 1 つのアニメーション（回転するローダーなど）？ Animated Image を使います。よりシンプルで軽量です。
• 状況に応じて変化するもの、タスク成功時に笑う顔、idle から running に切り替わるキャラクターなど？ それこそ sprite の出番です。

目安として、グラフィックに複数の "mood" や "behavior" があり、それを切り替えたいなら sprite を選びます。

sprite の作り方

1. "Sprite" widget を選択します。右サイドバーでその sprite の最初の mode を追加できます。たとえば最初の state は "Idle" かもしれません。あとで triggers を設定するときに分かるよう、各 state には明確な名前を付けます。
2. 画像シーケンス、つまりこの mode を構成するフレーム一式をアップロードします。各フレームは 1 枚の画像で、順番に再生するとパラパラ漫画のようにアニメーションになります。
   • その state 専用の duration を調整できます。長い duration はゆっくり、短い duration は速く再生します。
3. 別の state を追加します。最低 2 つの mode が必要です。（1 つのアニメーションだけでよいなら、Animated Image widget の方が適しています。上の When should I use a sprite? を参照してください。）
4. Events tab/editor を使って、条件に応じて異なる state をトリガーし切り替えます。これが sprite に生命感を与えます。次のセクションで詳しく説明します。

sprite に命を吹き込む

1 つの state しか表示しない sprite は、あまり役に立ちません。魔法が起きるのは、いつ 切り替えるかを伝えるときです。それを行うのが Events editor です。

考え方は単純です。何かが起きたら、state を切り替える。 その "something"（ボタン押下、値の変化、タイマーなど）を選べば、あとは PicoPixel が処理します。

典型的な例：

1. sprite はデフォルトで "Idle" state から始まります。
2. Events editor でイベントを追加します。ボタンが押されたら sprite を "Running" state に切り替える、という内容です。
3. もう 1 つイベントを追加します。タスクが完了したら "Happy"（または "Idle" に戻す）へ切り替えます。

これで完了です。コードを書かなくても、sprite はユーザー操作に反応します。こうしたイベントをいくつでもつなげて、本当に表情豊かな widgets を作れます。

sprite を再利用する方法

sprite を作ったら、毎回ゼロから作り直したくはないはずです。Library 機能を使えば一度保存し、任意のプロジェクトに入れられます。

1. 完成した sprite widget を右クリックし、"Add Library Widget" をクリックします。
   • Assets タブの library に再利用可能な項目が作られます。すぐ使える widget の自分用棚だと考えてください。
2. その library をプロジェクト間で移動したり、チームメイトと共有したりするには、Library に移動して Export をクリックします。
3. 新しいプロジェクトを作るときや既存 workspace を開くとき、その library を import して sprite を直接置けます。作り直しは不要です。
   • frames、durations、states は元のコピーから完全に同期されるので、どこで使っても同じように動きます。

よくある問題

デバイスに書き込むと sprite が表示されない。

• ほとんどの場合はメモリ問題です。デバイスには sprite の画像フレームを保持する十分な RAM が必要です。
• これは LVGL 設定で決まるもので、PicoPixel が代わりに変更できるものではありません。具体的なボードに依存します。
• 書き出された README.md ファイルにこの点が記載されるので、AI assistant が組み込みデバイス向けの SDK/LVGL 設定更新を手伝えます。

フレームがずれて見える、または跳ねる。

• すべての state のすべてのフレームが完全に同じ寸法であることを確認してください。数ピクセルの違いでも位置合わせが崩れます。

アニメーションが速すぎる、または遅すぎる。

• 該当 state の duration を調整します。各 state には独自の duration があるため、個別に調整が必要な場合があります。

sprite を保存できない / もう 1 つ state を求められる。

• sprite には最低 2 つの state が必要です。1 つしかない場合は 2 つ目を追加するか、Animated Image widget に切り替えてください。