作者動畫 (Author an anim)
動畫模組 (anim) 是一個檔案 <kebab-name>@<major>.<minor>.yaml,包含四個鍵:t(字面值 c)、j(ES 模組)、s(CSS)、h(HTML/SVG)。宿主播放器會搭配一個全域 G API 來執行它,該 API 提供歌曲的音節、單詞、行、段落和節拍。你的工作是將一個簡短需求轉換為這樣的檔案,使其在搜尋/暫停/調整大小/切換主題時保持正確、清晰可讀且美觀。以下路徑相對於此 skill/ 目錄。
最重要的規則
- 影格是播放時間的純函數。
render(t)必須在播放到達t或用戶拖曳到t時繪製相同的畫面。不能使用Math.random、Date.now、累積積分或「上一影格發生了什麼」等會被搜尋跳過的狀態。所有內容都必須源自歌曲資料、種子和t。 - 兩個部分。 在一個橫幅註解上方,是一個導出的、不依賴 DOM 的純粹部分(
buildPlan、frameAt、輔助函數;可進行單元測試),然後是一個精簡的瀏覽器部分(export default function (G, shadowRoot, config)),僅負責連接和繪製。請參閱guides/architecture.md。 - 在
default中註冊,在INIT中讀取歌曲資料。G.on/G.off/G.onFrame只能在default內部使用。G.map/forEach/lookup/iterator/relayout只能在INIT觸發後使用(在INIT處理常式中,或在後續的render等回呼中),絕不能在default本身中使用。訂閱G.on(G.TYPE.TICK, render)以處理播放;G.onFrame({ render, reset })涵蓋 SEEK/PLAY/PAUSE/RESIZE 和 UNINIT。 - 使用
G.dispose/G.listen進行清理。 從default返回的函數將被忽略。釋放 WebGL(使用forceContextLoss)、監聽器、計時器、攝影機。 - 顏色存在於 CSS 中,而非
c.v中。 在:host上設定淺色值,在[data-bs-theme=dark] { }中設定深色覆寫;Canvas 使用 g-lib 的cssColors讀取它們。兩個主題都必須看起來經過設計。 - 不要手動實作 g-lib 已有的功能(clamp、lerp、緩動函數、基於種子的亂數產生器、Canvas 適配、彈簧、文字佈局、物件池等)。從精確標籤的固定版本導入;在編寫任何輔助函數之前,請先查看
pitfalls/dont-hand-roll.md和spec/g-lib.md。 - 可讀性優先於特效。 活躍的音節在淺色和深色主題下,在手機和筆記型電腦上,都必須清晰可讀,並支援長行、中日韓 (CJK) 字元、從右到左 (RTL) 的語言和緬甸文。大範圍閃爍的頻率必須保持在 3 Hz 以下(
guides/accessibility.md)。 - 少量的型別化選項。
c和cSchema是純文字字面值;每個選項都應有可見的效果。
工作流程(搭配 repo 工具)
- 需求簡述。 根據
guides/design-brief.md撰寫設計需求簡述:一個強而有力的物理畫面;機制;哪些事件驅動什麼(同步圖);結構(主歌/副歌/節拍);可讀性方案;選項;陷阱。使用其選擇表選擇後端。拒絕那些無法保持可讀性的想法。 - 架構建立。 執行
npm run new -- <name> --backend canvas2d|svg|dom|three(或手動複製templates/<backend>.yaml並取代__NAME__)。 - 閱讀一次:
spec/module-format.md、pitfalls/general.md、你選擇的後端在pitfalls/backends.md中的章節、pitfalls/dont-hand-roll.md。僅透過下方的路由表打開其他文件。 - 實作:先實作純粹的部分(時間到狀態的轉換),然後是精簡的瀏覽器部分。
- 驗證。 執行
npm run validate -- anims/<file>.yaml。修正所有錯誤;在文件區塊中證明每個警告的合理性,或修正它。 - 檢查。 執行
npm run check -- anims/<file>.yaml會以無頭模式掛載 13 首邊界案例歌曲,評分符合性表格,並將 PNG 寫入out/<name>/目錄。打開這些 PNG(手機/筆電,淺色/深色主題)。一個綠色表格搭配一個難看或無法閱讀的影格就是失敗。如果「搜尋純粹性」行出現 WARN,表示畫面依賴於歷史狀態:請修正它,或在文件區塊中證明其合理性(例如刻意模擬)。 - 預覽(可選)。執行
npm run preview -- anims/<file>.yaml來播放、拖曳進度條、切換主題和調整選項。 - 審查:根據
guides/quality-rubric.md(20 個問題)進行審查,然後交付一個 YAML 檔案和一份簡短報告(檔案名稱、最終檢查表、需求簡述中未決的決策、你刻意沒有實作的事項)。不要提交out/目錄或測試工具。
無工具模式(聊天模型,無 shell)
跳過步驟 2、5-7。從匹配的範本文字開始,在你的推理中撰寫設計需求簡述,然後在回答之前,逐行將你的程式碼與 pitfalls/general.md、後端章節以及 20 個問題的評分量表進行比對。只輸出一個圍籬程式碼區塊中的 YAML 檔案,並提及哪些評分量表項目你因無法執行而無法驗證(搜尋純粹性、主題切換、調整大小)。
路由表:僅在觸發條件適用時打開文件
| 當你即將... | 閱讀文件... |
|---|---|
| 決定要建構什麼;選擇一個後端 | guides/design-brief.md |
| 佈局檔案;命名階段;撰寫文件區塊 | guides/architecture.md |
使用任何 G.* 呼叫、事件選項或 ID 範圍 | spec/events.md, spec/event-shapes.md, spec/g.d.ts |
| 新增選項、顏色、主題 | spec/config.md |
| 使用時間工具、文字測量、Canvas 輔助函數、生命週期 | spec/utilities.md |
| 將行分割為顯示行、文字換行 | spec/relayout.md, guides/patterns-text.md |
| 根據音節/行/節拍觸發事件;預先生成;暫停;彈簧 | guides/patterns-timing.md |
| 調整、高亮或設定文字樣式;非拉丁文字 | guides/patterns-text.md |
| 編寫渲染程式碼(DOM, SVG, Canvas, Three, Simulation, Layers) | guides/patterns-render.md, pitfalls/backends.md |
| 攝影機、地形、群體、包裝、程序化 3D | guides/techniques.md, pitfalls/techniques.md |
| 使用照片或攝影機 | spec/image-input.md |
| 建立遊戲(autoPlay false, score, states) | guides/games.md |
| 使用任何 g-lib 輔助函數 | spec/g-lib.md |
| 對閃爍、動態、對比度感到不確定 | guides/accessibility.md |
| 完成 | guides/quality-rubric.md |
最小範例(不要交付此範例;從範本開始)
"t": |-
c
"j": |
import { hash01 } from 'https://cdn.jsdelivr.net/gh/prjctg/[email protected]/index.js';
/* [email protected]: <一行>
* 1. <編號的設計主張:機制及其拒絕的誘人錯誤答案> */
export function frameAt(plan, t) { /* 純粹 */ }
/* 瀏覽器部分。此線以上的所有內容刻意不依賴 DOM。 */
export default function (G, shadowRoot, config) {
const cfg = G.cfg(config, { channel: G.cfg.int(0) });
let ready = false;
const render = (t) => { if (!ready) return; /* 繪製 frameAt(plan, t) */ };
G.on(G.TYPE.INIT, () => { ready = true; /* 此處可使用 G.map(...) */ });
G.on(G.TYPE.TICK, render);
G.onFrame({ render, reset() { ready = false; } });
}
export const c = { v: { fadeMs: 150 }, m: [{ s: 'fadeMs', t: 'fadeMs' }] };
export const cSchema = [{ i: 'fadeMs', n: '淡化 (毫秒)', t: 'int', mn: 0, mx: 2000 }];
"s": |
:host { display: block; --ink: var(--inkColor, #111); }
[data-bs-theme=dark] { --ink: var(--inkColor, #eee); }
"h": |
<canvas id="c"></canvas>
j、s、h 包含原始文字(永遠不要用反引號或引號包裹)。t 使用 |-。檔案名稱包含版本號;切勿原地編輯已發佈的版本。