Modding

Modding

通過 Lua 運行時讀取主菜單狀態和當前選中的本地角色名稱。這兩個查詢使用與 Modloader 相同的原生數據，無需訪問世界。

前置條件

啟用模組，並在 mod.json 中聲明 runtime 能力：

{
  "capabilities": ["runtime"]
}

對於這些客戶端查詢，請在 extended.mod.json 中將 targets 設為 ["client"]。從活動的運行時回調（例如 on_load 和 on_update）調用這些函數。runtime.phase == "ingame" 表示模組運行時已啟動，但不能確認已進入世界。這兩個查詢都不需要執行配置文件。其他世界操作仍有各自的要求。

檢測主菜單

local in_menu, reason = runtime.is_main_menu()

返回值	含義
true, nil	已確認處於主菜單，包括角色、世界和服務器選擇界面。
false, nil	已驗證為遊戲的其他原始狀態。
nil, reason	狀態未知、正在變化，或查詢不可用。

請明確檢查 in_menu == true 或 in_menu == false。nil 不代表已確認的狀態。單獨的 false 也不能確認世界可讀取。請另外檢查所需操作，例如 runtime.has("runtime.ecs.read")。

讀取角色名稱

local name, reason = runtime.player.name()
local display_name = name or "Flameborn"

name, nil 會以 UTF-8 字符串形式返回在本地客戶端主菜單中選中的角色名稱。Ikiju 育樹 這樣的 Unicode 字符會保留。nil, reason 表示名稱尚不可用，或當前無法訪問或不允許訪問。

模組自行選擇備用名稱。API 不會插入默認名稱，也不會使用 Modloader 的手動名稱選擇。此值不代表遠程玩家，也不是 SteamID 或 Steam 顯示名稱。專用服務器沒有本地客戶端角色名稱。

共享緩存

Lua 和 Modloader 讀取同一個原生緩存。現有運行時 tick 會刷新菜單狀態。現有菜單集成會在首次選擇可用時獲取名稱，並在選擇或名稱元數據變化時再次獲取。Lua 查詢不會啟動單獨的發現過程，也不會讀取日誌。

進入世界後，最近一次成功獲取的名稱仍會保留在緩存中。因此，緩存中存在名稱並不能確認菜單仍處於打開狀態。runtime.has("runtime.is_main_menu") 和 runtime.has("runtime.player.name") 會報告各自查詢是否可用。runtime.status(...) 也會提供原因。

src/mod.lua 示例

此示例會在加載時讀取緩存，之後每 500 毫秒讀取一次。它會選擇備用名稱，並且只記錄變化：

runtime.require("runtime.lifecycle")

local previous_message = nil

local function refresh()
    local in_menu = runtime.is_main_menu()
    local name = runtime.player.name()
    local state = "unknown"
    if in_menu == true then
        state = "menu"
    elseif in_menu == false then
        state = "other"
    end

    local message = state .. ": " .. (name or "Flameborn")
    if message ~= previous_message then
        previous_message = message
        shroudforge.log.info(message)
    end
end

return {
    on_load = refresh,
    on_update = function()
        refresh()
    end,
    update_interval_ms = 500,
}