製作像素吉祥物

一個吉祥物是一個單一的 SVG 檔案，包含像素藝術與 CSS 步驟動畫。它可以有數個狀態（閒置、快樂、睡覺、走路、攻擊……），每個狀態對應根元素上的一個 CSS 類別：<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），或如果系統因 shim 而阻擋直接使用 python，則使用 uv run python。建構腳本需要匯入工具組，因此執行時需將 <kit> 加入 PYTHONPATH：

PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg

$env:PYTHONPATH = "<kit>"; python make_<name>.py <name>.svg

preview.py 和工作室不需要設定 PYTHONPATH；工作室會為其執行的建構腳本自動設定。

SVG 的必要條件

每個根類別對應一個狀態。使用 .<state> .part{...} 選擇器來定義每個狀態的樣式；類別名稱即為使用者定義的狀態名稱（小寫、連字號）。建構腳本會在根元素上寫入一個預設狀態（s.svg(..., state="idle")），因此檔案在瀏覽器或 <img> 標籤中會自行播放動畫；應用程式可透過改變根元素的類別來切換狀態。如果未指定任何狀態，則建立一個：idle。
將所有顏色定義在其專屬的 <style> 區塊中的 CSS 類別內。CSS 變數（var(--accent,#hex)）僅能在 <style> 區塊中使用，絕不能作為 fill= 屬性的值。
使用 steps(1) 的關鍵幀進行動畫，這些關鍵幀以整個像素格為單位移動（在基於像素格的 viewBox 中，如 translateY(-1px)）或控制透明度閃爍。
必須包含 <title>（替代文字），且不能有 <script>、on…= 事件處理屬性，以及任何外部圖片、字型或連結，以確保在任何地方顯示都是安全的。
使用根元素上的 width/height 設定繪製尺寸，該尺寸必須是網格尺寸的整數倍：例如 32 個像素格對應 128 像素（每個像素格 4 像素），20 個像素格對應 80 像素。
除非使用者特別要求，否則應尊重減少動畫偏好設定：@media (prefers-reduced-motion:reduce){*{animation:none!important}}。

工作流程

確定吉祥物的本質、其狀態以及 3 到 5 個核心識別特徵。 詢問在 128 像素的尺寸下，是什麼讓它容易被認出來，然後精準地誇大這些特徵，並捨棄其他所有細節。詢問它需要哪些狀態；如果沒有答案，則建立一個閒置循環。由使用者的想法決定，而非此處的範例。如果使用者分享其他藝術家的作品，只能作為方向參考（例如比例、輪廓風格、特定特徵的繪製方式）：絕對不要複製他們的像素，也絕對不要將受版權保護的角色放入會分享或發布的建構中。

在下列表格中找到它的類型。 表格說明了要分成哪些部分（每個部分獨立動畫）以及哪些部分可以承載次級運動，這是讓吉祥物感覺有生命、而不只是一個彈跳貼紙的關鍵。

類型	典型識別特徵	部分（由後到前）	次級運動
人形角色	髮型和髮色、眼睛、一個飾品、服裝、手持物品	`hair-back`、`body`、`head`（臉、瀏海、前髮）、`prop`	頭部上下/左右晃動、頭髮的跟隨運動、道具擺動
動物	耳朵、花紋、尾巴、口鼻部、眼睛顏色	`tail`、`body`、`ears`（嵌套在頭部內）、`head`	耳朵拍動、尾巴搖晃、頭部傾斜
物體（燈、杯子、植物、掃地機器人）	輪廓、一個標誌性細節	`back`（電線、底座）、`body`、`face`（繪製在其上的臉）、`moving bits`	蒸氣或葉子搖動、燈光閃爍、輪子轉動
生物 / 軟膠怪 / 機器人	輪廓、一個奇特特徵（角、天線、護目鏡、發光）	`back`、`body`、`head`、`appendage`	擠壓和拉伸、天線搖晃、發光閃爍

沒有臉的吉祥物仍然需要可讀的狀態：透過改變姿勢、特效和速度來代替表情變化。

選擇畫布尺寸。 20×20 適用於特徵簡單的形狀；32×32 適用於具有多個特徵或需要表達情緒的臉部。對於角色，裁切到胸部或腰部：臉部和識別特徵比腿部更需要空間。每個像素格繪製為 4 像素。
複製範本 <kit>/example_mascot.py（Miso，一隻具有三個狀態的貓）到吉祥物資料夾中的 make_<name>.py，設定 NAME，並替換形狀和狀態。保留建構腳本：SVG 是建構的輸出。保留範本的最後一步 apply_overrides(...)：它會套用使用者從工作室進行的手動編輯（步驟 10），確保重建時不會遺失這些編輯。
由後到前繪製，每個獨立移動的物件作為一個部分。將附肢嵌套在其所附著的物體內（例如耳朵在頭部內），這樣它會跟隨該部分的運動，同時仍能獨立移動。工具組工具：rect、ellipse、polygon（耳朵、魚鰭、角）、path（尾巴、電線、莖）、line、zigzag_bottom（頭髮或邊緣鋸齒）、paint(..., only=...) 用於在現有形狀上繪製細節、shade_edges 用於陰影和邊緣。最後呼叫一次 s.outline()，讓每個部分都擁有自己的輪廓。對於有頭髮的角色，請遵循 LESSONS.md 中的「有頭髮的角色」章節。
每個狀態一個臉部（或姿勢），透過透明度規則切換群組：預設為 f-open，再加上適合每個狀態的其他群組。當表情在形狀上有所不同時（而不僅僅是顏色），反應效果最好：閉合的 ^ ^ 眼睛、半閉的眼睛、張開的嘴、一條陰影帶。繪製在瀏海角色上的臉部應跳過頭髮的像素格。
- 讓每個狀態適合角色。當某個狀態不適合它們時，提問並提供角色自身故事中的時刻：一個標誌性的手勢或場景。大的輪廓變化在 128 像素下是可讀的；小的細節（一個 2 像素的寶石、一張開合的小嘴）則不然。
- 一個狀態可以交換整個部分，而不僅僅是臉部：例如配件的戴與不戴、睡覺時拉下帽子。將每個可交換的部件設為獨立的部分，並使用 .<state> .part{opacity:…} 來隱藏或顯示它。將每個此類規則限定在某個狀態內，以便其他狀態保留其部分。
- 當使用者不確定時，與其爭論單一選擇，不如建立多個替代方案：讓建構腳本接受一個變體名稱作為參數，分別建構到各自的檔案，然後並排展示。保留使用者喜歡的變體：一個參數就能還原。
特效使用 s.fx(name, cls, frames)：閃光、速度線、Z 字、搖晃標記、汗水滴。這些幀會變成 s1、s2……，以便以不同步的方式進行動畫。
動作：使用 steps(1) 關鍵幀和整格移動（像素藝術應該要一格一格地跳，而不是滑動）。整個角色位於一個 .rig 群組中，可以跳動或搖晃；在此基礎上：
- 頭部獨立上下、左右晃動或點頭（最多 2 個像素格）；
- 附肢（頭髮、耳朵、尾巴、天線）最晚延遲四分之一個週期跟隨；延遲半個週期會使它們跑到另一側，看起來像殘影；
- 道具和移動部件可以稍微偏離節拍。一個閒置循環應該是緩慢而小幅的：呼吸、眨眼、尾巴搖動。
在展示給任何人看之前，先建構並查看它（指令如同「執行腳本」章節）：
```
PYTHONPATH="<kit>" python3 make_<name>.py <name>.svg
python3 <kit>/preview.py <name>.svg sheet.png
```
然後查看 sheet.png：從左到右，每個狀態一個靜止幀。預覽僅顯示靜止姿勢。要查看動畫，請在背景啟動工作室，並在瀏覽器中開啟 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）：工作室會保留一份未修改的副本和編輯內容在 SVG 旁的 <name>_studio/ 目錄中，並將結果寫入 SVG。在使用者編輯後，請先閱讀他們的覆寫檔案和重建後的預覽，再進行任何其他更改，並判斷某個編輯是否看起來像是意外（例如一個遠離其他像素的孤立像素）。
交付成品：告知使用者 SVG 的路徑、預設播放的狀態，以及如何切換到其他狀態（設定根元素的類別；<img> 無法做到，因此需要在應用程式中透過內嵌 SVG 或使用 <object> 或 <iframe> 載入 SVG 來切換狀態）。

profile.json（適用於顯示吉祥物的應用程式）

應用程式可能需要的不僅僅是根類別：例如根元素上的 CSS 變數、額外的類別、固定的狀態標籤。將 profile.json 放置在 <kit> 目錄中（與 preview.py 相鄰），可以告知預覽和工作室相關資訊。每個鍵都是可選的：

{
  "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/ 目錄。此技能本身不附帶任何 profile.json。

此技能包含的檔案

檔案	說明
`LESSONS.md`	記錄了哪些方法有效、哪些無效，包含原因和解決方法。請先閱讀。
`scripts/pixelkit.py`	包含形狀（矩形、橢圓、多邊形、路徑、線條）、部件、陰影、逐部件輪廓、SVG 輸出等功能。
`scripts/example_mascot.py`	Miso：一個 32×32 的貓，具有閒置、快樂和睡覺三種狀態；是您要複製的範本。
`scripts/preview.py`	產生 PNG 圖表，每個狀態一個靜止幀，僅使用標準函式庫。
`scripts/pixel_overrides.py`	將手動編輯套用至完成的 SVG；建構腳本應在最後呼叫它。
`scripts/studio/`	包含 `server.py` 和 `site/`：適用於任何吉祥物的每個狀態動畫展示，以及一個像素編輯器。僅限本地端使用（127.0.0.1）。

像素吉祥物製作工具