ピクセルマスコットの作成
マスコットは、CSSステップアニメーションを備えたドット絵の1つのSVGファイルです。複数の状態（アイドル、ハッピー、スリープ、歩く、攻撃…）を持つことができ、それぞれがルート要素のクラスになります：<svg class="happy"> は happy 状態を再生します。マスコットはコードで構築し、何百もの <rect> を手動編集することはありません。このスキルの scripts/ フォルダー（以下 <kit>）には、小さなキットと実例が含まれています。すべてPython標準ライブラリで、インストールは不要です。
何かを描く前に、このファイルと同じディレクトリにある LESSONS.md を読んでください。そこには、最初のマスコット作成中に発生した問題と、その症状、原因、修正方法がリストされており、それを読まずに進めるとほとんどの問題が再発します。
ファイルの配置場所
ユーザーにマスコットをどこに保存するか尋ねてください。特に希望がなければ、~/pixel-mascots/<name>/（Windowsでは %USERPROFILE%\pixel-mascots\<name>\）を使用します：
| ファイル | 説明 |
|---|---|
make_<name>.py | ビルダー：すべての変更はここを編集して再実行します |
<name>.svg | ビルド出力、マスコット本体 |
<name>_overrides.json | スタジオからのユーザーの手動編集。ビルダーによって最後に適用されます |
sheet.png | プレビュー、各状態の静止フレーム |
<name> は小文字の英字、数字、ハイフンのみです。ユーザーのファイルを決して <kit> に置かないでください。これはインストールされたプラグインに属し、アップデート時に置き換えられます。
スクリプトの実行
マシンにあるPythonを使用します：python3（macOS、Linux）、python（Windows）、または uv run python（シムが素の python をブロックしている場合）。ビルダーはキットをインポートするため、実行時に <kit> を PYTHONPATH に設定します：
PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg
$env:PYTHONPATH = "<kit>"; python make_<name>.py <name>.svg
preview.py とスタジオは PYTHONPATH を必要としません。スタジオは実行するビルダーに対してそれ自身で設定します。
SVGが満たすべき条件
- ルートクラスごとに1つの状態。各状態は
.<state> .part{...}セレクターでスタイル設定します。クラス名はユーザーの状態名（小文字、ハイフン区切り）です。ビルダーはデフォルトの状態をルートに書き込みます（s.svg(..., state="idle")）。これにより、ファイルはブラウザや<img>で単独でアニメーションし、アプリはルートのクラスを変更することで別の状態を表示できます。状態が指定されていない場合は、1つ作成します：idle。 - すべての色を、自身の
<style>内のCSSクラスに配置します。CSS変数（var(--accent,#hex)）はその中でのみ機能し、fill=属性としては使用できません。 - セル全体を移動する（セルの viewBox 内での
translateY(-1px)）か、不透明度を点滅させるsteps(1)キーフレームでアニメーションします。 <title>（代替テキスト）を持ち、<script>、on…=、外部画像、フォント、リンクがないため、どこに表示しても安全です。- 描画サイズはルートの
width/heightで設定し、グリッドの整数倍にします：128 px で32セル（1セル4 px）、80 px で20セル。 - ユーザーが特に指定しない限り、動きの抑制を尊重します：
@media (prefers-reduced-motion:reduce){*{animation:none!important}}。
ワークフロー
-
マスコットの種類、状態、および3〜5のアイデンティティ特徴を特定します。 128 px で何が認識可能かを尋ね、それだけを誇張し、他はすべて削除します。どの状態が必要か尋ねます。回答がない場合は、アイドルループを1つ作成します。ユーザーのアイデアが決定します。ユーザーが他のアーティストの作品を共有した場合、方向性（プロポーション、アウトラインスタイル、特徴の描き方）のみを参考にし、ピクセルをコピーしたり、著作権で保護されたキャラクターを共有・公開されるビルドに入れたりしないでください。
-
この表からタイプを見つけます。 どのパーツに分割するか（各パーツは独立してアニメーションします）と、二次的な動きを運べるものを示します。これにより、マスコットが単に跳ねるシールではなく、生きているように感じられます。
タイプ 典型的なアイデンティティ特徴 パーツ（後ろから前へ） 二次的な動き 人型キャラクター 髪型と色、目、アクセサリー1つ、服装、持っているアイテム hair-back、body、head（顔、前髪、前髪の房）、prop頭の上下動/うなずき、髪のフォロースルー、プロップの揺れ 動物 耳、模様、尾、口吻、目の色 tail、body、ears（頭にネスト）、head耳のパタパタ、尾の振り、頭の傾き 物体（ランプ、マグカップ、植物、ロボット掃除機） シルエット、1つの特徴的なディテール back（ケーブル、スタンド）、body、face（描かれた顔）、moving bits蒸気や葉の揺れ、ライトの点滅、車輪のステップ クリーチャー / ブロブ / ロボット シルエット、1つの奇妙な特徴（角、アンテナ、バイザー、グロー） back、body、head、appendage押しつぶしと伸張、アンテナのぐらつき、グローの点滅 顔のないマスコットでも、読み取り可能な状態が必要です：表情の代わりに、ポーズ、エフェクト、速度を変更します。
-
キャンバスを選択します。 特徴が少ない単純な形状には20×20、複数の特徴や表情が必要な顔があるものには32×32。キャラクターの場合は、胸または腰で切り取ります：顔とアイデンティティ特徴に、脚よりもスペースが必要です。1セル4 px で描画します。
-
テンプレートをコピーします、
<kit>/example_mascot.py（Miso、3つの状態を持つ猫）をマスコットのフォルダーのmake_<name>.pyにコピーし、NAMEを設定し、形状と状態を置き換えます。ビルダーは維持します：SVGはビルド出力です。テンプレートの最後のステップ、apply_overrides(...)を維持します：これにより、スタジオからのユーザーの手動編集（ステップ10）が適用され、再ビルド時に失われることはありません。 -
後ろから前に描画します、独立して動くものごとに1つのパーツ。付属物は、それが取り付けられているものの中にネストします（耳は頭の中）。これにより、そのパーツの動きに追従しつつ、独立して動くことができます。キットツール：
rect、ellipse、polygon（耳、ヒレ、角）、path（尾、ケーブル、茎）、line、zigzag_bottom（髪やフリンジの端）、paint(..., only=...)で既存の形状に詳細を描画、shade_edgesで影とエッジ。最後にs.outline()を1回呼び出し、すべてのパーツが独自のアウトラインを持つようにします。髪のあるキャラクターの場合は、LESSONS.mdの「髪のあるキャラクター」に従ってください。 -
状態ごとに1つの顔（またはポーズ）、不透明度ルールで切り替えられるグループとして：
f-openをデフォルトとし、各状態に合うものを追加。反応は、色だけでなく形状が異なるときに最もよく読み取れます：閉じた^ ^の目、半分閉じた目、開いた口、影の帯。前髪のあるキャラクターに描かれた顔は、髪のセルをスキップします。- 各状態をキャラクターに合わせます。状態がキャラクターに合わない場合は尋ね、キャラクター独自のストーリーから瞬間を提供します：特徴的なジェスチャーやシーン。128 px では大きなシルエットの変化が読み取れますが、小さな詳細（2ピクセルの宝石、開閉する口）は読み取れません。
- 状態は顔だけでなく、パーツ全体を入れ替えることができます：アクセサリーのオン/オフ、睡眠時の帽子を下げる。交換可能なピースはそれぞれ独自のパーツにし、
.<state> .part{opacity:…}で表示/非表示にします。すべてのルールを状態にスコープし、他の状態がパーツを維持するようにします。 - ユーザーが確信がない場合は、1つに議論するのではなく、代替案を構築します：ビルダーがバリアント名を引数として受け取り、それぞれを独自のファイルにビルドし、並べて表示します。ユーザーが気に入ったバリアントを保持します：戻すのは1つの引数で行えるようにします。
-
エフェクト
s.fx(name, cls, frames)を使用：きらめき、スピード線、Z、よろめきマーク、汗の滴。フレームはs1、s2… になり、ずれてアニメーションします。 -
モーション：
steps(1)キーフレームとセル全体の移動（ドット絵はステップし、滑らかに動くべきではありません）。全身は.rigグループに配置され、ホップまたは揺れます。その上に：- 頭は独立して上下、傾き、うなずきます（最大2セル）。
- 付属物（髪、耳、尾、アンテナ）は、最大で4分の1サイクル遅れて追従します。半サイクルでは反対側に配置され、軌跡として読み取られます。
- 小道具と動くビットは、少しずれて実行されます。 アイドルループはゆっくりと小さく：呼吸、まばたき、尾。
-
ビルドして確認する、誰かに見せる前に（コマンドは「スクリプトの実行」を参照）：
PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg python3 <kit>/preview.py <name>.svg sheet.pngその後、
sheet.pngを確認します：左から右に、状態ごとに1つの静止画。プレビューは静止ポーズのみを表示します。動きを見るには、スタジオをバックグラウンドで起動し、ブラウザでhttp://127.0.0.1:8765/を開きます（組み込みブラウザペインがある場合はそれを使用します）：python3 <kit>/studio/server.py --svg <name>.svg --build make_<name>.py各状態がそれぞれのフレームでアニメーションしているのが表示されます。
--states a,bで状態を選択・順序付け（デフォルト：CSSが使用するすべての状態を、最初に出現した順序で）、--portでポートを変更します。ユーザーはスクリーンショットからレビューし、問題を赤でマークすることがよくあります：マークを、知っている特徴（目の行、口）に合わせてセルにマッピングし、それに沿って再描画します。見た目に変更がないはずのリファクタリングの後は、古いバージョンと新しいバージョンをビルドし、ファイルをバイト単位で比較します（cmpまたはfc /b）。 -
手動編集。 ユーザーが自分でピクセルを修正したい場合、スタジオの
/editor.htmlに送ります：状態ごとにペイント、消去、色選択、元に戻し、保存。保存すると<name>_overrides.jsonが書き込まれ、再ビルドされます。各ピクセルはパーツに属し、それとともに移動します。エディタはどのパーツとどの状態がピクセルを表示するかを示します。ビルダーのないマスコットでも機能します（--buildを省略）：スタジオは untouched コピーと編集内容を SVG の隣の<name>_studio/に保持し、結果を SVG に書き込みます。ユーザーの編集後、他のものを変更する前に、オーバーライドファイルと再ビルドされたプレビューを読み取り、編集が偶発的と思われる場合（残りから遠く離れた孤立ピクセル）は指摘します。 -
引き渡し：SVGの場所、デフォルトで再生される状態、別の状態を表示する方法（ルートのクラスを設定する。
<img>ではできないため、状態を切り替えるアプリはSVGをインライン化するか、<object>または<iframe>にロードします）を伝えます。
profile.json（マスコットを表示するアプリ用）
アプリはルートクラス以上のものを必要とする場合があります：ルートのCSS変数、追加のクラス、固定状態ラベル。<kit> 内の preview.py の隣に配置された profile.json は、プレビューとスタジオに指示します。すべてのキーはオプションです：
{
"states": [{ "class": "happy", "name": "happy", "label": "happy · on success", "style": "--speed:.5s" }],
"rootClass": "always-animate",
"swatches": { "var": "--accent", "label": "accent", "colors": ["#8FA8E8", "#ED93B1"] },
"workdir": "~/my-app/studio"
}
states は順序、ボタン名、キャプション、および状態ごとのルートスタイルを固定します。rootClass はすべてのフレームでルートに追加されます。swatches はCSS変数を設定するカラーボタンを追加します。workdir はビルダーのないマスコットの場合、<name>_studio/ を置き換えます。このプラグインは何も出荷しません。
このスキルのファイル
| ファイル | 説明 |
|---|---|
LESSONS.md | 機能したことと機能しなかったこと、原因と修正方法。最初に読むこと。 |
scripts/pixelkit.py | 形状（rect、ellipse、polygon、path、line）、パーツ、シェーディング、パーツごとのアウトライン、SVG出力。 |
scripts/example_mascot.py | Miso：アイドル、ハッピー、スリープを持つ32×32の猫。コピーするテンプレート。 |
scripts/preview.py | PNGシート、状態ごとに1つの静止フレーム、標準ライブラリのみ。 |
scripts/pixel_overrides.py | 完成したSVGに手動編集を適用します。ビルダーは最後にこれを呼び出します。 |
scripts/studio/ | server.py + site/：すべての状態のアニメーションとピクセルエディタ。任意のマスコットで動作します。ローカルのみ（127.0.0.1）。 |