Modding

Modding

Lua ランタイムを使って、メインメニューの状態と選択中のローカルキャラクター名を読み取ります。どちらのクエリも Modloader と同じネイティブデータを使用し、ワールドへのアクセスは必要ありません。

前提条件

Mod を有効にし、mod.json で runtime 機能を宣言します。

{
  "capabilities": ["runtime"]
}

クライアント向けのこれらのクエリでは、extended.mod.json の targets を ["client"] に設定します。on_load や on_update など、実行中のランタイムコールバックから関数を呼び出します。runtime.phase == "ingame" は Mod のランタイムが起動したことを示しますが、ワールドへの参加は確認しません。どちらのクエリにも実行プロファイルは必要ありません。ワールドを操作するその他の機能には、それぞれ別の要件があります。

メインメニューを検出する

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 は、名前がまだ取得できない、またはアクセスできない、許可されていないことを示します。

フォールバック名は Mod が独自に選びます。API はデフォルト名を挿入せず、Modloader の手動選択名も使用しません。この値はリモートプレイヤーを識別するものではなく、SteamID や Steam の表示名でもありません。Dedicated Server にはローカルクライアントのキャラクター名はありません。

共有キャッシュ

Lua と Modloader は同じネイティブキャッシュを読み取ります。既存のランタイム tick がメニュー状態を更新します。既存のメニュー連携は、最初に選択可能になったときと、選択または名前のメタデータが変化したときに名前を取得します。Lua クエリは別の検出処理を開始せず、ログも読み取りません。

最後に正常取得した名前は、ワールド参加後もキャッシュに残ります。そのためキャッシュに名前があってもメニューが開いているとは限りません。runtime.has("runtime.is_main_menu") と runtime.has("runtime.player.name") は、それぞれのクエリが利用可能かを示します。runtime.status(...) も理由を返します。

src/mod.lua の例

この例ではロード時と、その後 500 ms ごとにキャッシュを読み取ります。フォールバック名を選び、変更があった場合だけログに記録します。

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,
}