wrapper-plant 新植物擴充設計

日期：2026-06-11 狀態：已確認，依三批漸進實作

背景

wrapper-plant 目前有七種植物：grass（草叢）、flower（野花）、vine（垂藤）、sprout（新芽）、ivy（攀藤）、twig（垂枝）、posy（矮花叢），皆為水彩野地風。本設計規劃後續擴充方向，依實作成本分三層，並排定三批實作順序。

架構關鍵：PlantKind（骨架分支）與 PlantPresetName（preset 名稱）分離，新 preset 可重用現有 kind，零繪製改動即可長出新植物。

三層菜單

第一層：純參數組合（只加 preset 設定）

植物	重用 kind	樣貌
垂柳簾 willow	vine	自頂部整排垂下的細長綠簾，葉細密、色淡、垂感強
雛菊 daisy	flower	細瓣多數（10~14 瓣）純白小菊，黃花心
三色堇圃 pansy	posy	posy 紫黃撞色變體，色盤更濃
角落灌木 bush	twig	placement 改 bottom-corners，多莖密葉填滿角落

第二層：小幅骨架擴充（createStemList 加分支）

植物	新 kind	擴充內容
蕨類 fern	fern	拱形長莖 + 沿莖密集對生小葉、尺寸沿莖遞減；現有 tipCurl 蕨芽舒展機制與其相得益彰
蘆葦 reed	reed	極長直立近乎不彎的莖，葉少而細長貼莖
酢漿草 clover	clover	短莖頂端 3~4 片心形葉繞圈，借用花朵 petalList 結構放葉印章，低機率四葉彩蛋

第三層：新繪製機制（render-plant / watercolor-stamps 動刀）

植物	新機制	備註
薰衣草 lavender	「花穗」器官：沿莖上段串生小花點	同一機制解鎖狗尾草、麥穗、鈴蘭整族穗狀植物，投資報酬率最高
蒲公英 dandelion	種子球印章 + plant-particles 連動	風吹或滑鼠掠過時種子飄散，互動彩蛋
鈴蘭 lily-of-the-valley	垂掛鈴鐺花	與花穗共用沿莖佈點邏輯，排在 lavender 之後
蘑菇 mushroom	全新傘蓋印章 + 矮胖骨架	成本最高、與莖葉系統共用度最低，暫緩

實作批次

第一批：垂柳簾 + 雛菊（純參數）

• plant-presets.ts：PlantPresetName 加 'willow' | 'daisy'，新增兩個 preset 物件並註冊到 plantPresetMap。PlantKind 不變。
• willow：kind vine、placement top，莖長 80~160、低 wobble 頻率營造柔順垂墜，葉多而小、色淡，flowerChance 約 0.05。vine kind 在 createPlantField 已強制垂直懸掛，直接受益。
• daisy：kind flower、placement bottom，petalCount 10~14、細長白瓣（petal 印章共用，靠色盤與數量區分）、黃花心。
• 範例與文件：examples/basic-usage.vue 選單補上兩項，元件文件同步更新。

第二批：蕨類（骨架擴充）

• PlantKind 加 'fern'。
• create-plant.ts：
  • createStemList 加 fern 分支：隨機選邊的拱形傾斜（lean 約 ±0.5~0.9），droop 與 lean 同號形成圓拱。
  • createStem 葉片生成加 fern 特例（仿 sprout 特例的寫法）：自 t 0.15~0.9 密集對生小葉，尺寸沿莖遞減、openAngle 較大，模擬羽狀複葉。
• preset：placement bottom-corners，tipCurl 調高（2 以上），生長時蕨芽舒展為視覺亮點。
• 渲染管線不動，重用現有 leaf 印章。

第三批：薰衣草（花穗機制）

• plant-presets.ts：PlantPreset 加選用欄位 spike（佈點區間 regionRange、花點數 dotCountRange、花點大小 dotSizeRange）。
• create-plant.ts：createStem 依 spike 設定沿莖上段產生花點列表（含各自的 growthOrder 與印章索引），存於 PlantStem。
• render-plant.ts：葉片之後、花朵之前繪製花穗，花點隨莖生長依序浮現，重用 samplePathAt 取附著點。
• watercolor-stamps.ts：視效果決定重用縮小的 petal 印章或新增小橢圓花點印章，優先嘗試重用。
• 後續鈴蘭、狗尾草直接吃此機制，僅需新 preset 與微調。

驗證方式

• vue-tsc 型別檢查通過。
• 透過 examples/basic-usage.vue 逐一切換新 preset 目視確認：生長動畫、風吹擺動、容器圓角錨點皆正常。
• 確認 calculateCanvasPadding 對長莖植物（willow、fern）的外擴範圍足夠，不裁切。

不做的事（YAGNI）

• 垂柳簾 willow：實作後試用發現自頂部垂下的長簾過度遮擋內容，已移除。

• 蘑菇：傘蓋結構與莖葉系統共用度低，等穗狀植物族完成後再評估。

• 蒲公英互動：依賴花穗批次之外的粒子連動，列為日後彩蛋，不納入前三批。