# MiCraft 2026 中秋活動模組開發計劃書 > 對應企劃：[mid-autumn-2026-plan.md](mid-autumn-2026-plan.md) > 專案代號：`MiharuMoonfest` > 版本策略：Fabric 伺服器端模組為主；Data Pack 僅作災難降級，不作正常活動流程 > 首發活動：2026-09-25 20:00–22:00（台灣時間） > 長期目標：首發後保留每日、每週、每月與每年中秋內容 ## 1. 技術目標與原則 ### 1.1 這次要交付真正可運行的模組 上一版把 Data Pack 定為主要方案，因此烤肉計分、尋寶與燈謎仍依賴場務。新版改為建立可建置的 `MiharuMoonfest` Fabric 伺服器端模組，正常活動只需要維運者執行一次 `/moonfest start`；回合切換、計分、任務判定、獎勵、排行榜和長期週期由模組自動處理。 Data Pack 與人工表格只保留為「伺服器故障時的最後降級路徑」。它們不再是正常活動的必要工作，也不要求場務在直播中逐項抄分。 Fabric 官方文件提供伺服器命令註冊與事件 callback 的開發路徑；本專案會使用這些公開 API，並在目標環境確認實際 package、mapping 與方法名稱，不直接複製未驗證的網路程式碼： - [Fabric Commands 26.2](https://docs.fabricmc.net/develop/commands/basics) - [Fabric Events 26.2](https://docs.fabricmc.net/develop/events) - [Fabric 建置模組指南](https://docs.fabricmc.net/develop/getting-started/building-a-mod) ### 1.2 硬性邊界 - 只部署在現有 MiCraft Fabric 伺服器；不為活動另開第二台伺服器。 - 先採伺服器端可用的原版物品、方塊、粒子、音效、Bossbar、Title 與資料元件；不註冊需要客戶端同步的新物品／新方塊／新實體／新維度。 - 不使用 Mixins 修改既有 Mod 的核心邏輯，除非日後有獨立需求與完整測試。 - 不加入外部 HTTP、YouTube 聊天室、付款驗證、網路服務或資料庫。 - 不全世界掃描；所有掃描限於設定的活動區、固定站點與線上玩家。 - 不生成無上限生物、掉落物或煙火；所有效果都可按場次清理。 - 不做爆炸破壞、強制死亡、鏡頭干擾、非自願 PvP 或會改變長期生存平衡的 Buff。 - 模組停用後，原有世界與既有 Mod 仍需正常載入；活動資料使用獨立命名空間。 ## 2. 功能範圍 ### 2.1 MVP：首發活動必須具備 | 功能 | 自動化內容 | 優先級 | |---|---|---:| | 活動狀態機 | 報到、烤肉、尋寶、燈謎、結算、長期模式的自動切換 | P0 | | 報到與分隊 | 驗證白名單／權限、一次性物資、依 UUID 防重複、平衡分隊 | P0 | | 烤肉站 | 只監看設定站點；驗證原版熟肉提交、消耗物品、累計隊伍分數 | P0 | | 尋寶節點 | 固定節點輪換、互動判定、個人與隊伍進度、冷卻 | P0 | | 自動燈謎 | 題庫選題、可點擊答案、首位有效答案、計分與結束 | P0 | | 結算獎勵 | 參與獎、隊伍獎、稱號／紀念物、發放冪等與離線補發 | P0 | | 安全控制 | 活動區限制、狀態清理、停止、重啟後恢復策略 | P0 | | 進度與排行榜 | 本場、本週、本月、累計統計；限制查詢範圍 | P0 | ### 2.2 長期內容：首發後保留 | 週期 | 內容 | 上限／規則 | |---|---|---| | 每日 | 月見委託：料理、採集或營地互動 | 每人每日一次 | | 每週 | 月兔尋寶：從安全固定節點輪換 | 每人每週一次完整獎勵 | | 每月 | 全服貢獻箱與共同里程碑 | 每人每日貢獻上限；每月重置共同進度 | | 每年 | 中秋季節模式與限定題庫 | 日期／時區／倍率由設定檔控制 | | 長期 | 個人完成次數、稱號、紀念物與分段排行榜 | 不提供永久戰鬥優勢 | ### 2.3 明確排除 - 巨型 Boss、自訂 AI、生物波次與客製掉落。 - 浮空跑酷、列車、低重力、強制傳送與 PvP 擂台。 - 直播聊天室即時投票、HTTP listener、外部登入與自動會員付款驗證。 - 需要玩家安裝客戶端 Mod／資源包才能看見或使用的註冊內容。 - 沒有測試與回復方案的臨時功能。 ## 3. 系統架構 ```text MiharuMoonfest ├─ MoonfestEntrypoint # server initializer；只註冊服務 ├─ command/ │ ├─ MoonfestCommand # /moonfest start|stop|status|reload │ └─ PlayerCommand # join|tasks|answer|progress ├─ session/ │ ├─ SessionManager # 首發活動狀態機與倒數 │ ├─ RoundScheduler # 自動進入下一回合 │ └─ RecoveryManager # 重啟與異常狀態處理 ├─ interaction/ │ ├─ CheckinHandler # 報到台互動 │ ├─ CookingStationHandler # 固定烤肉站與提交箱 │ ├─ TreasureNodeHandler # 固定節點輪換與互動 │ └─ RiddleHandler # 題庫與答案選擇 ├─ progression/ │ ├─ QuestService # 每日／每週／每月任務 │ ├─ ScoreService # 場次、隊伍與週期分數 │ ├─ LeaderboardService # 範圍有限的排行榜 │ └─ RewardService # 冪等發獎與待處理紀錄 ├─ storage/ │ ├─ PersistentStateStore # 世界／伺服器活動資料 │ ├─ PlayerProfileStore # UUID 對應的玩家長期進度 │ └─ RewardLedger # 發獎交易狀態 ├─ safety/ │ ├─ RegionGuard # 活動區與互動邊界 │ ├─ EntityAndItemLimiter # 效果與掉落數量上限 │ └─ CleanupService # 停止／換季／重啟清理 └─ config/ ├─ ConfigLoader # JSON schema／錯誤訊息／reload └─ ClockService # Asia/Taipei 與測試時鐘 ``` 模組之間不直接互相修改資料。`SessionManager` 只發出狀態，`ScoreService` 只記錄分數，`RewardService` 只處理已核准獎勵；這樣首發活動和長期任務可以共用邏輯而不互相污染。 ## 4. 設定檔設計 內容、座標、日期與獎勵必須設定檔驅動，之後新增題目／節點不需要改 Java： ```text config/miharu-moonfest/ ├─ server.json # 總開關、時區、玩家上限、活動區 ├─ locations.json # 報到台、烤肉站、提交箱、尋寶節點、賞月台 ├─ schedule.json # 首發流程與長期任務週期 ├─ quests.json # 每日／每週／每月任務池 ├─ riddles.json # 題目、答案選項、分數與難度 └─ rewards.json # 原版物品、數量、條件、每期上限 ``` ### `server.json` 最小欄位 ```json { "enabled": true, "timezone": "Asia/Taipei", "world": "", "maxPlayers": 10, "eventBounds": {"min": [0, 0, 0], "max": [0, 0, 0]}, "season": {"start": "2026-09-18", "end": "2026-10-04"} } ``` 上面的世界名稱、座標、玩家上限只是欄位示例，不能直接部署。`ConfigLoader` 必須在啟動前驗證：世界存在、min/max 合法、站點不重疊、獎勵物品 ID 可解析、日期有效、上限不超過維運核准值。 ## 5. 自動化流程規格 ### 5.1 正常首發流程 ```text /moonfest start ↓ 自動公告、初始化本場、開放報到 報到台互動 ↓ 自動驗證、記錄 UUID、發物資、平衡分隊 烤肉回合 ↓ 固定站點自動檢查提交箱、扣除物品、計分 尋寶回合 ↓ 固定節點自動輪換、互動即記錄、更新個人／隊伍進度 燈謎回合 ↓ 自動出題、答案按鈕／指令、首位正確者計分 結算 ↓ 自動鎖分、計算名次、發獎、寫入排行榜 月見生活季 ↓ 自動開放每日／每週／每月內容 ``` 正常流程不需要場務抄分，也不需要主持人輸入回合指令。主持人只負責解說與互動；維運者只需在正式活動開始前執行一次啟動。 ### 5.2 烤肉站 - `locations.json` 設定 2–3 個烤肉站，每站包含料理設備位置與提交容器位置。 - 模組只在 `COOKING` 狀態、只對設定站點檢查容器，不掃描其他箱子。 - MVP 白名單先只收原版熟牛肉、熟豬肉、熟羊肉、熟雞肉與熟兔肉；既有料理 Mod 物品必須在測試服確認 ID 與交易行為後才加入。 - 物品消耗、分數增加與提交紀錄在伺服器主執行緒完成，避免同時提交時重複計分。 - 每隊最多計入 16 份；超過上限的物品退回原提交箱或由模組標示為未計分，不直接刪除。 - 活動結束後自動鎖定提交箱並輸出本場摘要。 ### 5.3 月兔尋寶節點 - 場地事前配置最多 6 個原版互動節點，例如按鈕、告示牌或箱子。 - 模組依週次與固定 seed 選出有效節點，不做隨機世界生成。 - 每個節點對每位玩家只可完成一次；節點是否已完成、個人獎勵與隊伍分數分開記錄。 - 過期節點自動關閉，下一週重新開放，不需要場務換箱子。 ### 5.4 自動燈謎 - `riddles.json` 由內容負責人事前填寫，模組啟動時檢查題目至少有一個答案、正解索引合法、分數非負。 - 模組顯示題目與選項；玩家使用可點擊文字或 `/moonfest answer