從 ASCII 鯊魚
到部落格錦鯉池

原始專案：stackedlol/ascii-sharks

原版是用 TypeScript 寫成的海洋動畫，不依賴任何外部套件，以 MIT 授權公開。錦鯉池的程式改寫自這個專案，檔案開頭保留原作者的授權聲明。

// 原版：一隻雙髻鯊
new OceanEngine(canvas, [{ kind: "hammerhead", size: 1 }]);

// Blog 首頁：五種錦鯉
new OceanEngine(canvas, roster, {
  koi: true, cell: 9, theme, avoid,
  ignoreReducedMotion: true,
});

錦鯉池改了什麼

改動時的注意事項

錦鯉池已經用在個人網站首頁、Works 作品索引與 Blog 首頁。之後要調整錦鯉、換造型，或是引用原始專案的新版本，請先確認以下幾點。

1. 1

   保留授權聲明

   koi-pond.js 檔案開頭保留原作者的 MIT 授權全文，對外介紹時註明改寫自 stackedlol/ascii-sharks。之後若引用原始專案的新版本，同樣要保留授權聲明。

2. 2

   引擎只有一份，三頁一起換版本號

   三個頁面都載入 components/koi-pond/koi-pond.js?v=20261114a。修改引擎之後，三頁的 ?v= 要改成同一個新值，否則瀏覽器會繼續使用快取裡的舊版。GitHub 上的「Check Blog home for CMS」檢查也會比對三頁的版本號是否一致。

3. 3

   各頁自己設定要避開的文字

   錦鯉遇到 avoid 清單裡的元素會轉開，每一頁的清單不同，Blog 首頁是標題、引言與「最新文章」這一列。在水面上新增沒有底色的文字時，要加進該頁的清單；有底色的區塊不用加入，錦鯉會從下面游過。

4. 4

   Blog 首頁也是 CMS 發文的對象

   CMS 發文時會直接改寫 share/blog/index.html。調整錦鯉的設定時，不要動到發文插入點、#postGrid 與文章區塊的結構、SEO 區段與 </head>。改完在 repo 根目錄執行 scripts/blog-home/check_blog_home.py，推送或開 PR 時 GitHub 也會自動再檢查一次。

5. 5

   維持延後執行

   錦鯉用 <script type="module"> 載入，網頁文字先顯示，錦鯉才開始執行。不要改成一般的同步 script，也不要在錦鯉載入之前把頁面內容藏起來。

6. 6

   改之前先在手機量測

   手機 Lighthouse 實測時，有錦鯉是 39 分與 47 分，擋掉錦鯉是 48 分；在節流的手機環境下，錦鯉約增加 0.5 至 1.7 秒的主執行緒阻塞時間。要增加小魚數量、造型或效果之前，先在手機量測一次。

7. 7

   減少動態效果的設定

   目前設定 ignoreReducedMotion: true，錦鯉不跟隨系統的「減少動態效果」設定，一律自動播放。原版在這項設定下會停止動畫，日後若要改回，拿掉這個選項即可。

8. 8

   共用檔案要登記部署清單

   components/koi-pond/ 是由部署流程複製到網站的共用資料夾。新增共用資料夾或搬動路徑時，要登記在 .github/scripts/pages-overlay.json，正式網站才會有這些檔案。