LuaDB - KCD2 Lua數據持久化模塊

LuaDB - KCD2 Lua數據持久化模塊，爲KCD2模組開發者提供基於SQLite的Lua數據持久化功能

LuaDB

🎯 **注意**：這是一個面向模組開發者的資源工具。普通玩家只有在其他模組需要時才需要下載此模組，否則它不會對您產生任何效果。

---

📥 安裝要求

• 需要 Ultimate ASI Loader（已包含在下載包中）
• 將此模組的 `.asi` 文件和 ASI 加載器（即 `.dll` 文件）放入遊戲的根目錄

**Linux用戶**：

在 Proton/Wine 中，將以下內容添加到 Steam 啓動選項：

WINEDLLOVERRIDES="dinput8=n,b" %command%

---

🚀 什麼是LuaDB？

**LuaDB** 是一個專爲 KCD2 模組開發者設計的 Lua 持久化模塊。它將 Lua 數據（包括表格、布爾值、數字和字符串）存儲在 SQLite 數據庫中，並提供兩種保存模式：

• **全局存儲** - 數據在所有遊戲存檔間持久化（獨立於遊戲存檔）
• **本地存儲** - 與遊戲存檔綁定，數據與特定的遊戲存檔文件關聯：
• 遊戲保存時自動**保存**數據
• 遊戲加載存檔時自動**加載**數據

---

💡 爲什麼需要這個模組？

在此模組出現之前，**沒有簡單安全的方法**在 KCD2 中持久化存儲 Lua 數據。模組開發者不得不依賴變通方案（如實體屬性），這些方法不可靠或功能有限。本模組通過以下特性解決了這個問題：

• **永久存儲**（即使在遊戲重啓後）
• **易於使用的 Lua API**（簡單的 `Set/Get` 和新的面向對象 `DB.Create` 接口）
• **安全性** - 存儲是外部的（保存在 kcd2db.db 文件中），最大限度地減少了數據損壞的風險
• **兩種存儲模式**（全局或存檔特定）
• **Lua 對象支持**（任何可由 json.lua 編碼的 Lua 對象）

---

👥 適合誰使用？

• **模組開發者**：需要持久化數據的模組的必備工具
• **普通玩家**：只有在模組需要時才需要安裝（單獨使用無效果）

---

⚙️ 功能特性

存儲 Lua 數據

• 使用 `DB.Create("ModName")` 爲您的模組創建數據庫對象
• 使用數據庫對象的 `Set` 方法存儲數據
• 數據在存儲時自動轉換爲 JSON，檢索時自動轉換回 Lua 對象

檢索數據

• 使用數據庫對象的 `Get` 方法檢索數據

調試工具

• `LuaDB.Dump()` - 將所有存儲的數據打印到控制台
• 日誌（kcd2db.log）和 SQLite 數據庫（kcd2db.db）

使用場景

• 保存**模組設置**（如按鍵綁定、配置）
• 存儲**玩家進度**（如自定義任務狀態）
• 持久化**庫存/服裝數據**（如保存的服裝）
• 存儲**複雜數據結構**，如表格和數組

---

📚 API 文檔

推薦使用方法

```lua

-- 創建數據庫實例（推薦用於大多數用例）

local myDB = DB.Create("MyModNamespace") -- 使用您的模組名稱或唯一標識符

-- 存儲 Lua 對象（包括嵌套表格）

myDB.Set("player_health", 85.6)

myDB:Set("has_dragon_sword", true) -- myDB 支持.call 和:call 語法

-- 檢索數據（自動轉換回 Lua 對象）

local health = myDB.Get("player_health")

```

主要方法

• **DB.Create("Your MOD")** - 創建命名空間實例，自動爲所有鍵添加前綴以減少鍵衝突
• **DB.Get(key)** - 獲取本地鍵值
• **DB.Set(key, value)** - 設置本地鍵值
• **DB.Del(key)** - 刪除本地鍵值
• **DB.Exi(key)** - 檢查本地鍵是否存在
• **DB.All()** - 獲取所有本地鍵值

全局 API

• **DB.GetG(key)** - 獲取全局鍵值
• **DB.SetG(key, value)** - 設置全局鍵值
• **DB.DelG(key)** - 刪除全局鍵值
• **DB.ExiG(key)** - 檢查全局鍵是否存在
• **DB.AllG()** - 獲取所有全局鍵值

快速訪問

• **DB("Your MOD")** - 等同於 DB.Create("Your MOD")
• **DB.L.key** / **DB.L["key"]** - 訪問本地鍵值，無衝突
• **DB.G.key** / **DB.G["key"]** - 訪問全局鍵值，無衝突

---

🔧 調試

• 使用 SQLite3 數據庫 `kcd2db.db`（位於遊戲根目錄）
• 操作日誌存儲在 `kcd2db.log`（位於遊戲根目錄）
• 如果使用 `-console` 啓動，調試輸出也會出現在單獨的控制台窗口中

---

⚠️ 重要注意事項

此模組大量使用了逆向工程的遊戲內部功能，可能會受到遊戲更新的影響。如果在遊戲更新後遇到崩潰問題，請嘗試刪除模組文件（或將 `.asi` 擴展名重命名以禁用）。

源碼位於 Github-kcd2db