存儲數據
插件要保存兩類數據:服主編輯的設置,以及插件自己寫入的數據,例如玩家的家或積分。本指南把設置放進配置文件,把數據保存在鍵值數據庫中, 最後介紹 SQL 的用法去哪裡查。
示例使用 JavaScript;API 在每種語言中都相同(在 Lua 中直接調用類,不寫 new)。路徑相對於服務器文件夾。把插件的文件放在它自己的文件夾
plugins/<插件名>/ 中,也就是插件在 mods/ 中的文件夾(見插件與引擎)。
配置文件中的設置
1. 帶默認內容打開文件
new JsonConfigFile(path, default) 打開一個 JSON 文件;文件不存在時,用默認內容創建它:
const conf = new JsonConfigFile("plugins/MyPlugin/config.json", JSON.stringify({
welcome: "Welcome to the server!",
reward: 1,
}));路徑中的文件夾會在需要時創建。如果文件無法打開,構造函數會拋出錯誤。
2. 讀取設置
conf.get(name, default) 返回某項設置的值,缺少該項時返回默認值:
const welcome = conf.get("welcome", "Welcome!");
const reward = conf.get("reward", 1);
mc.listen("onJoin", (player) => {
player.tell(welcome);
});conf.init(name, default) 一次完成兩件事:返回設置的值,缺少該項時把默認值寫進文件。用它給已有的文件添加設置很方便:
const maxHomes = conf.init("maxHomes", 3);3. 寫入與重新加載
conf.set(name, value) 修改一項設置並立即寫入文件;conf.delete(name) 刪除一項。值可以是數字、字符串、布爾值、數組和對象。
配置對象從內存中讀取。服主在服務器運行時編輯了文件,就調用 conf.reload() 重新讀取,例如通過一個控制台命令:
mc.regConsoleCmd("reloadconf", "Reloads the configuration of MyPlugin", (args) => {
conf.reload();
log("Configuration reloaded.");
});new IniConfigFile(path, default) 以同樣的方式處理帶分節的 INI 文件:conf.init(section, name, default)、conf.getStr、
conf.getInt、conf.getFloat、conf.getBool。見配置文件 API。
鍵值數據庫中的數據
對於插件自己寫入的數據,使用鍵值數據庫:它把值保存在名稱之下,存放在一個文件夾中,不需要供人編輯的文件。
1. 打開數據庫
const db = new KVDatabase("plugins/MyPlugin/data");路徑是一個文件夾,需要時會被創建。如果那裡已經有數據庫,就打開它。如果數據庫無法打開,構造函數返回 Null。
2. 寫入和讀取值
db.set(name, value) 保存一個值,db.get(name) 返回它(不存在時為 Null),db.delete(name) 刪除它,db.listKey()
返回所有名稱。值可以是數字、字符串、布爾值、數組和對象。下面的插件以 XUID 為鍵統計每個玩家的來訪次數:
mc.listen("onJoin", (player) => {
const key = `visits.${player.xuid}`;
const visits = (db.get(key) ?? 0) + 1;
db.set(key, visits);
player.tell(`This is your visit number ${visits}.`);
});以玩家的 XUID(player.xuid)而不是名字作為鍵來保存玩家的數據。
3. 插件卸載時關閉它
ll.onUnload(() => {
db.close();
});close 之後不要再使用這個數據庫。見數據庫 API。
SQL 數據庫
對於表格形式的數據,用 new DBSession(type, params) 打開一個 SQL 會話:"sqlite3" 用於數據庫文件,"mysql" 用於 MySQL
服務器。對來自玩家的值使用預處理語句:
const session = new DBSession("sqlite3", { path: "plugins/MyPlugin/data.db" });
session.exec("CREATE TABLE IF NOT EXISTS visits (xuid TEXT, time TEXT)");
mc.listen("onJoin", (player) => {
const stmt = session.prepare("INSERT INTO visits VALUES (?, ?)");
stmt.bind([player.xuid, system.getTimeStr()]);
stmt.execute();
});SQL API 的函數失敗時會拋出錯誤:在 JavaScript 中用 try … catch,在 Lua 中用 pcall。數據庫 API
介紹了連接參數、session.query 和預處理語句。