# 格田收割記（Harvest Clicker）遊戲規格書

> 文件版本：4.3
> 文件狀態：核心玩法、樹木林業、第一階段裝飾、農夫氣氛、限時活動、帳號分享與跨裝置即時同步皆已實作。
> 目標平台：桌面與行動版現代瀏覽器。

## 文件使用方式

本文件改為「總覽＋主題規格」結構。各主題文件只描述單一系統的規則、數值、介面與驗收方式；程式中的數值不再散落於核心邏輯，而是由靜態設定檔載入。

| 主題 | 詳細規格 |
|---|---|
| 核心循環、土地與初始狀態 | [00-核心循環與土地.md](spec/00-核心循環與土地.md) |
| 種植、作物與樹木 | [01-種植與作物.md](spec/01-種植與作物.md) |
| 工具與手動收割 | [02-工具與手動收割.md](spec/02-工具與手動收割.md) |
| 自動收割與灑水 | [03-自動化設備.md](spec/03-自動化設備.md) |
| 肥料與生長倍率 | [04-肥料.md](spec/04-肥料.md) |
| 裝飾第一階段 | [05-裝飾第一階段.md](spec/05-裝飾第一階段.md) |
| 農夫角色與農場氣氛 | [08-農夫角色與農場氣氛.md](spec/08-農夫角色與農場氣氛.md) |
| 介面、動畫與音效 | [06-介面與回饋.md](spec/06-介面與回饋.md) |
| 儲存、離線結算與驗收 | [07-儲存與驗收.md](spec/07-儲存與驗收.md) |
| 限時活動 | [09-限時活動.md](spec/09-限時活動.md) |
| 帳號分享與即時同步 | [10-帳號分享與即時同步.md](spec/10-帳號分享與即時同步.md) |
| 素材來源與授權 | [ASSET-CREDITS.md](ASSET-CREDITS.md) |

## 核心定位

《格田收割記》是單人點擊／放置農場。玩家從中央 9×9 的成熟雜草開始，使用小刀收割取得金幣，逐步購買工具、種子、土地、自動化設備與肥料。植物與設備在玩家離線時仍依同一條時間軸成長與運作。

核心循環：

    植物成熟 → 點擊造成傷害 → HP 歸零並發放金幣
         ↑                                  ↓
    離線生長／灌溉 ← 購買種子、土地、工具與自動設備

## 目前實作資料來源

| 設定類型 | 靜態檔案 | 使用者 |
|---|---|---|
| 棋盤、土地、存檔版本與倍率 | [game-config.js](game-config.js) | game-core.js |
| 作物、樹木與種子價格 | [data/plants.js](data/plants.js) | game-core.js、script.js |
| 手動農具 | [data/tools.js](data/tools.js) | game-core.js、script.js |
| 自動收割機、灑水器 | [data/automation.js](data/automation.js) | game-core.js、script.js |
| 一次性肥料 | [data/fertilizers.js](data/fertilizers.js) | game-core.js、script.js |
| 裝飾商品與邊界槽位 | [data/decorations.js](data/decorations.js) | 第一階段裝飾模組 |

所有靜態檔案在 game-core.js 前由 index.html 以 script 載入。修改數值時，優先修改對應資料檔與主題規格，不直接修改核心運算。

## 全域規則

- 所有金額顯示為「數字＋$」；內部資料以非負安全整數保存。
- 一般作物種子一次播滿一塊 3×3 土地；樹木種子一次只種植一棵。
- 樹木以完整正方形占地，規模由 1×1 到最多 5×5；偶數尺寸以選取格作為中央定位點的左上格。
- 工具、設備與樹木的作用範圍超出棋盤或未購土地時，無效格會被裁切；樹木則必須完整放在已購土地內。
- 裝飾第一階段不佔用種植格，改放在種植格邊界線與交叉點。
- 購買、收割、播種、施肥、裝備、配置設備與土地後立即存檔。
- 只有正式登入帳號顯示分享功能；每個帳號使用固定唯讀網址，後續成功存檔會自動同步最新農場狀態。訪客只能拖曳、縮放與查看，不能修改或儲存。
- 正式帳號的所有裝置會監聽同一份私人農場存檔；種植、施肥與配置自動設備會立即上傳，其他裝置收到較新的版本後自動更新畫面。兩邊同時操作時必須提示玩家處理版本衝突，不可靜默覆蓋尚未同步的本機進度。
- 每月活動獎勵以存檔內的活動 ID 去重；目前活動會送 1 份緋櫻果樹種子，先放入包包，不會自動種下。

## 版本與相容性

- 目前 Schema：v4。
- v3 的 15×15 農場會自動遷移到 27×27。
- 舊版曾以 3×3 種下的樹木會載入時合併為單棵樹，避免重複收成。
- 新增設定檔時，必須維持舊有 id、存檔鍵名與既有商品數值，除非另有版本遷移規格。

## 實作完成矩陣

| 系統 | 已完成內容 | 主要程式／設定 |
|---|---|---|
| 核心循環 | 收割、金幣、成長、購地與離線補算 | `game-core.js`、`data/plants.js`、`game-config.js` |
| 手動工具 | 17 種工具、不同範圍、工具游標、揮動與分離音效 | `data/tools.js`、`script.js` |
| 種植與樹木 | 21 種一般作物、10 種 1×1～5×5 樹木、根節點收成 | `data/plants.js` |
| 自動化 | 7 種收割機、5 種灑水器、蛇形逐格行進、設備 focus／管理 | `data/automation.js`、`script.js` |
| 肥料 | 10 種一次性肥料、當下生效、多層生長倍率相乘、撒肥車動畫 | `data/fertilizers.js`、`game-core.js`、`script.js` |
| 裝飾 | 10 種 edge／corner gap grid 裝飾、深度遮擋與收納 | `data/decorations.js`、`script.js` |
| 農場氣氛 | 農夫隨機行走、鋤田、澆水、休息、唱歌與環境景觀 | `script.js` |
| 帳號與分享 | 永久帳號固定唯讀連結、公開狀態鏡像、撤銷分享 | `firebase-runtime.js`、`share-utils.js` |
| 跨裝置同步 | 私人存檔即時監聽、版本衝突提示、較新版本保護 | `firebase-runtime.js`、`script.js` |
| 限時活動 | 一個月緋櫻果樹種子、一次領取、跨裝置去重 | `game-config.js`、`game-core.js` |