Survival / Adventure 可正常參加
- Survival / Adventure：可報到、互動、回答與計分。
- Creative / Spectator：玩法互動與回答會被拒絕，並顯示原因。
- OP / 管理員 / 主播：只要遊戲模式合格，也能和一般玩家一樣參加。
- Console：可執行管理操作，但不是參賽玩家。
Minecraft 26.2
目前 production 主要支援版本
Minecraft 26.3
同一套 1.0.0 邏輯與資料格式
玩家免安裝
純伺服器端 Fabric 模組
Asia/Taipei 04:00
長期活動預設重置基準
Player quick start
玩家先看這裡
玩家不用處理安裝與管理指令。只要使用合格遊戲模式、完成報到，活動狀態與提示都由模組提供。
報到、進度與長期活動
/moonfest join
/moonfest progress
/moonfest daily
/moonfest daily claim
/moonfest weekly
/moonfest contribution
/moonfest workshop submit
/moonfest leaderboard [weekly|monthly|lifetime|all-time|season]
/moonfest season
分隊規則：1–2 名玩家維持單一合作隊伍；3 名以上使用
max(2, ceil(players/5)) 建立隊伍，每隊最多 5 人且人數差不超過 1。允許 late join 時，遲到玩家加入當下最小隊伍；重連會恢復原 participant/team，replacement 不會補回離線期間已錯過的歷史分數。
Main event
核心活動怎麼走
主活動由管理員控制階段切換；料理、尋寶、燈謎、計分與最終結算由 MiharuMoonfest 管理。
IDLE→
OPEN→
COOKING→
TREASURE→
RIDDLE→
SHOWCASE→
FINISHED
OPEN
報到與準備
管理員先執行 /moonfest doctor 與 /moonfest open；玩家使用 /moonfest join 報到，並可隨時查看 /moonfest progress。
COOKING
料理提交
依設定站點與允許物品提交。開始需執行 /moonfest begin 後再 /moonfest confirm。
TREASURE
月兔尋寶
核心尋寶至少配置 10 個安全節點，每場 deterministic 選出 3 個。隊伍對同一節點只計一次團隊分，但個人進度仍會保存。
RIDDLE
六題燈謎
每場固定 6 題，題庫至少要有 6 題有效內容。玩家可點擊選項或使用 /moonfest answer <option>；具 timeout / BossBar，同隊同題只會有一次有效計分。
SHOWCASE
展示與凍結結算
進入 SHOWCASE 前會凍結 settlement；之後展示或通知即使失敗，也不會再改變競賽結果。
FINISHED
完成、發獎與保存
執行 /moonfest finish 與 /moonfest confirm，完成最終保存與獎勵流程。
Always on
長期活動
Daily、Weekly、月度貢獻、工坊、排行榜與 Season 都使用持久化狀態；每日／每週／月度窗口由設定 timezone 與 reset hour 決定。
每日任務
預設 daily pool 包含 COOKING、GATHERING、TREASURE，不預設 RIDDLE daily。玩家使用 /moonfest daily 查看，再以 /moonfest daily claim 領取。
每週尋寶
weekly treasure node pool 至少 10 個節點，每個週期 deterministic 選固定 3 個，完成條件為 3/3；跨週會重置 selection 與進度。
月度貢獻
/moonfest contribution 顯示個人、全服、下一里程碑與剩餘需求。提交與獎勵使用持久化交易與 RewardLedger，失敗時 fail-closed。
月餅工坊
依序檢查 Gate、資格、每日限制、材料與輸出後才執行交易。玩家使用 /moonfest workshop submit，可見 lore 與提示由訊息設定提供。
排行榜
支援 weekly、monthly、lifetime、all-time 與 season 視角；玩家可用 /moonfest leaderboard 查詢。
季節內容
Season 由 season.json 驅動。啟用中的 season 若配置專屬題庫會優先使用；inactive 或未配置時才回退 evergreen 題庫。
Operations
管理員安裝與啟動
目前正式伺服器以 26.2 為主。未來升級 26.3 時切換成對應 JAR；兩個版本使用同一套 1.0.0 邏輯與資料格式。
Minecraft 26.2 · Production
MiharuMoonfest-1.0.0+mc26.2.jar
Fabric API 0.160.0+26.2 · Adventure 7.1.1
Minecraft 26.3 · Supported
MiharuMoonfest-1.0.0+mc26.3.jar
Fabric API 0.161.0+26.3 · Adventure 7.2.0
放入正確版本的 JAR
26.2 與 26.3 不要混用。兩版都使用 Fabric Loader 0.19.5 與 Java 25。
啟動一次產生設定
首次啟動後建立 config/miharu-moonfest/。
完成活動內容設定
確認世界、活動範圍、站點、至少 10 個核心尋寶節點、至少 6 題有效燈謎、獎勵與長期活動設定。
Doctor 通過後才開活動
先執行 /moonfest setup show、/moonfest doctor；有 ERROR 時不可開活動。確認後再啟用並執行 /moonfest open。
版本升級原則：正式伺服器從 26.2 升到 26.3 時，先正常備份世界、設定與
data/miharu-moonfest/，再更換成 26.3 JAR。模組資料格式設計為直接銜接，不需要為升版重置活動資料。
Safety & permissions
權限、確認與設定安全
管理權限與玩家玩法資格分離；高影響操作使用 request / confirm，避免誤操作直接改變活動狀態。
高影響操作需要確認
/moonfest cancel 只會取消目前唯一可判定的待確認操作；若同一操作者存在多個候選，系統會拒絕猜測。Recovery 的 resume / abort 同樣走 request / confirm。
設定文字不能任意執行命令
設定內容不能直接注入任意 run_command；可執行的 command action 由 Java 端可信上下文建立，並受到白名單限制。
Feature gate
功能開關與 Reload
Feature Gate 用於正式控制長期功能；進行中的核心活動或 ACTIVE / PENDING_ENABLE Gate 會阻擋可能改變當前規則語意的 reload。
/moonfest feature list
/moonfest feature <feature> request <target> <reason>
/moonfest feature <feature> confirm
/moonfest feature <feature> cancel <reason>
舊式
/moonfest feature enable|disable <feature> 僅作安全 alias，仍不會繞過確認流程。
Recovery & durability
Restart、資料與獎勵復原
活動中的重啟不會默默恢復計分。核心 session、長期資料與獎勵發放都有各自的 durable 狀態，遇到不確定結果時採 fail-closed。
重啟後先檢查，再恢復
活動進行中重啟會進入 RECOVERY，不會自動繼續計分。不要刪除 PersistentState 跳過復原。
/moonfest status
/moonfest doctor
/moonfest resume
重要資料位置
- 核心 session / recovery：Minecraft PersistentState
- 長期活動：
data/miharu-moonfest/longterm.json，dataVersion=8 - 主活動 reward delivery：
data/miharu-moonfest/reward-delivery-journal.json - Audit：
logs/miharu-moonfest/audit-YYYY-MM-DD.jsonl
v8 durable snapshot
v7 狀態升級前會先建立 .v7.bak 再遷移。無法理解的未來版本、語意異常、載入或寫入失敗都會 fail-closed。
不確定就不重複發
主活動 journal 記錄 delivery begin / apply / delivered / done；若 inventory fingerprint 讓結果無法確認，狀態會進入 AMBIGUOUS。長期貢獻與工坊也以 transaction fingerprint / RewardLedger 防止重複材料或獎勵。
遇到 AMBIGUOUS：不要手改狀態檔後直接繼續，也不要強制重送。先備份 state 與 audit，再進行人工查核。
Go live checklist
上線前與活動後
正式場次前只需把關必要狀態；活動結束後確認 durable state 與 audit，並留下完整備份。
確認狀態健康
/moonfest doctor
/moonfest status
Doctor 有 ERROR 時不要開活動；確認 JAR 與伺服器版本一致，再進入 open / begin 流程。
確認結算並備份
- 確認主活動狀態為 FINISHED。
- 抽查 RewardLedger、reward delivery journal 與 audit。
- 備份 world PersistentState。
- 備份
data/miharu-moonfest/。
目前建議：正式伺服器繼續使用 Minecraft/Fabric 26.2 與
MiharuMoonfest-1.0.0+mc26.2.jar。未來伺服器升級 26.3，再切換為 MiharuMoonfest-1.0.0+mc26.3.jar 並依正常升版流程先完成備份。