CgEventsRoguelike

專門為 Roguelike 遊戲設計的事件表擴充包。把「卡片定義 + 卡片實體容器」這兩件事拆開做透徹，讓所有「抽卡、發牌、戰利品池、商店進貨、背包合成、保底機制」都能用 GUI 動作組合出來。

它解決的是什麼問題

Roguelike 遊戲的核心循環不外乎兩件事：

1. 這張卡是什麼？ —— 火球的傷害是多少、稀有度是哪一級、抽到的權重是多少（卡片的種類定義）。
2. 這張卡現在在誰那邊？ —— 在抽牌堆、手牌、棄牌堆、玩家擁有清單、商店貨架、背包（卡片實體的容器與流轉）。

純事件表要做這兩件事，得手算總權重、用迴圈累減、處理不重複、動態維護容器，還得區分「種類」與「實體」（手上兩張一模一樣的卡）。對只熟悉 GUI 的創作者來說門檻很高。

CgEventsRoguelike 把上述能力切成兩個正交模組：

• 卡片字典（Catalog） —— 定義「有哪些卡種」的字典。每個卡種有 kindId、weight（抽中機率）、maxCopies（持有上限）、data（基礎資料）。三種抽法：等權抽樣、保底抽、分層抽。
• 牌堆（Stack） —— 裝實體卡片的容器（有序、可重複）。每張卡有自動的 instanceId，可獨立攜帶 data（用來表達升級、詞綴等實體狀態）。
• 橋接動詞 —— 一個動作從字典加權抽 N 個 → 自動生成實體推入牌堆。
• 「順便推入牌堆」可選模式 —— 6 個抽法動作都可勾選，抽完直接寫進指定牌堆。少寫一個動作、多人時少送一次封包。

適合什麼場景

STS 三堆戰鬥：永久牌組 → 戰前複製到抽牌堆 + 洗牌 → 抽 5 進手牌 → 打牌進棄牌堆 → 結束回合洗回。

升級三選一：技能字典中加權抽 3 個 kindId 不重複當候選 → 玩家選一張 → 進入「玩家技能」牌堆。同卡多次選到可以堆疊（用 data 表達升級狀態）。

戰利品池跨玩家共池：一個戰利品池配上「每個玩家擁有」的對照堆 + 字典裡的同種上限（普通×5、稀有×1）→ 玩家點抽即可，自動避開達上限的卡種。

商店每日進貨：開店時從字典加權抽 3 件商品到貨架 → 玩家點商品買走 → 對應格子變空 → 補貨按鈕清空貨架重抽。

背包合成：玩家背包中數鐵 ≥1 且水 ≥1 才能合成藥水 → 消耗素材 → 推入藥水。檢查 + 否則觸發 處理素材不足。

保底抽卡：「保底：抽卡」一個動作搞定，自動維護進度變數，達 N 次未中強制保底。

分層戰利品：「分層抽」一個動作搞定。先依權重選池（普通 70% / 稀有 25% / 傳說 5%），再從該池內抽。深度感由開發者用「卡片字典：設定權重」動態調整即可。

牌堆構築：玩家擁有的牌組就是一個 Stack，新獲得的卡 push 進去，刪除 / 升級單張靠 instanceId 精準操作。

設計理念

字典 vs 容器分離。字典回答「卡種長什麼樣」、容器回答「現在誰拿著哪幾張」。這個切法讓「抽卡 → 生成實體 → 進入容器」變成 3 個獨立可組合的步驟，而不是糾纏成一團。

實體有 instanceId。Stack 內每張卡有獨立 instanceId（自動生成，全域唯一），可以表達「兩張一模一樣的火球」、「升級到不同等級的同卡」、「精準刪除某張」等情境，不會跟 kindId 混淆。

資料欄位（data）支援 GUI 編輯。建立卡種或升級單張時不必手寫 JSON 字串，直接用 GUI 加列（key + 型別 + 值）即可。

錯誤訊息就是教學。用錯時控制台跳出帶建議的中文警告（開發模式才顯示），引導用正確的元件組合。

動作不做條件判斷。所有分支邏輯靠檢查 + 「否則觸發事件」，這是事件表本來就推薦的條件分支寫法。

一個最直接的例子

升級三選一（用橋接動詞）：

1. 建立技能字典（一次性，定義有哪些技能）
2. 玩家升級時：「橋接：從字典生成實體進牌堆」抽 3 個不重複到「候選」牌堆
3. UI 顯示 3 個按鈕對應 3 張候選 → 玩家點選 → 該張 Transfer 到「玩家技能」

整個流程都是 GUI 動作組合，不用碰一行程式碼。

開始使用

• 5 分鐘上手教學：見同目錄下 TUTORIAL.md
• 完整互動範例：CgEventsRoguelike 模組專案 下 test/examples/
  • basic_draw.events：基本抽 / 打 / 自動洗回
  • loot_pool.events：跨玩家共池戰利品（依字典 maxCopies 過濾）
  • level_up_choice.events：升級三選一 + 升級單張
  • deck_battle.events：STS 戰鬥三堆完整循環
  • shop.events：商店進貨 / 買走 / 補貨
  • crafting.events：背包合成（多素材 Check + 消耗 + 產出）
  • pity_draw.events：保底抽卡（CatalogPityRollRL 一個動作搞定）
  • pity_draw_legacy.events：舊版保底寫法（5 個 event 拼裝），保留供新舊對照
  • tier_loot.events：分層戰利品（CatalogTierRollRL + 順便推入戰利品包）
• 元件分類：事件表編輯器中位於 Roguelike / 卡片字典（含 保底、分層抽 子分類）、Roguelike / 牌堆、Roguelike / 橋接

作者

cook1470