跳到正文
本頁目錄

存儲數據

插件要保存兩類數據:服主編輯的設置,以及插件自己寫入的數據,例如玩家的家或積分。本指南把設置放進配置文件,把數據保存在鍵值數據庫中, 最後介紹 SQL 的用法去哪裡查。

示例使用 JavaScript;API 在每種語言中都相同(在 Lua 中直接調用類,不寫 new)。路徑相對於服務器文件夾。把插件的文件放在它自己的文件夾 plugins/<插件名>/ 中,也就是插件在 mods/ 中的文件夾(見插件與引擎)。

配置文件中的設置

1. 帶默認內容打開文件

new JsonConfigFile(path, default) 打開一個 JSON 文件;文件不存在時,用默認內容創建它:

JavaScript
const conf = new JsonConfigFile("plugins/MyPlugin/config.json", JSON.stringify({
    welcome: "Welcome to the server!",
    reward: 1,
}));

路徑中的文件夾會在需要時創建。如果文件無法打開,構造函數會拋出錯誤。

2. 讀取設置

conf.get(name, default) 返回某項設置的值,缺少該項時返回默認值:

JavaScript
const welcome = conf.get("welcome", "Welcome!");
const reward = conf.get("reward", 1);

mc.listen("onJoin", (player) => {
    player.tell(welcome);
});

conf.init(name, default) 一次完成兩件事:返回設置的值,缺少該項時把默認值寫進文件。用它給已有的文件添加設置很方便:

JavaScript
const maxHomes = conf.init("maxHomes", 3);

3. 寫入與重新加載

conf.set(name, value) 修改一項設置並立即寫入文件;conf.delete(name) 刪除一項。值可以是數字、字符串、布爾值、數組和對象。

配置對象從內存中讀取。服主在服務器運行時編輯了文件,就調用 conf.reload() 重新讀取,例如通過一個控制台命令:

JavaScript
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. 打開數據庫

JavaScript
const db = new KVDatabase("plugins/MyPlugin/data");

路徑是一個文件夾,需要時會被創建。如果那裡已經有數據庫,就打開它。如果數據庫無法打開,構造函數返回 Null。

2. 寫入和讀取值

db.set(name, value) 保存一個值,db.get(name) 返回它(不存在時為 Null),db.delete(name) 刪除它,db.listKey() 返回所有名稱。值可以是數字、字符串、布爾值、數組和對象。下面的插件以 XUID 為鍵統計每個玩家的來訪次數:

JavaScript
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. 插件卸載時關閉它

JavaScript
ll.onUnload(() => {
    db.close();
});

close 之後不要再使用這個數據庫。見數據庫 API。

SQL 數據庫

對於表格形式的數據,用 new DBSession(type, params) 打開一個 SQL 會話:"sqlite3" 用於數據庫文件,"mysql" 用於 MySQL 服務器。對來自玩家的值使用預處理語句:

JavaScript
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 和預處理語句。

存放數據的其他地方