Modding

Modding

Lees de status van het hoofdmenu en de geselecteerde lokale personagenaam via de Lua-runtime. Beide query's gebruiken dezelfde native gegevens als Modloader en hebben geen toegang tot de wereld nodig.

Vereisten

Schakel de mod in en geef de runtime-mogelijkheid op in mod.json:

{
  "capabilities": ["runtime"]
}

Stel voor deze clientquery's targets in extended.mod.json in op ["client"]. Roep de functies aan vanuit actieve runtime-callbacks zoals on_load en on_update. runtime.phase == "ingame" geeft aan dat de modruntime is gestart en bevestigt niet dat de gamewereld is betreden. Geen van beide query's vereist een uitvoeringsprofiel. Andere wereldbewerkingen hebben hun eigen vereisten.

Het hoofdmenu detecteren

local in_menu, reason = runtime.is_main_menu()

Retourwaarde	Betekenis
true, nil	Het hoofdmenu is bevestigd, inclusief de selectie van personage, wereld en server.
false, nil	Een andere oorspronkelijke gamestatus is gevalideerd.
nil, reason	De status is onbekend, verandert of de query is niet beschikbaar.

Controleer expliciet of in_menu == true of in_menu == false. nil is geen bevestigde status. Alleen false bevestigt ook niet dat een wereld leesbaar is. Controleer de benodigde bewerking afzonderlijk, bijvoorbeeld runtime.has("runtime.ecs.read").

De personagenaam lezen

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

name, nil retourneert de naam van het personage dat in het lokale hoofdmenu is geselecteerd als UTF-8-tekenreeks. Unicode-tekens, zoals in Ikiju 育樹, blijven behouden. nil, reason betekent dat er nog geen naam beschikbaar is, of dat toegang niet beschikbaar of niet toegestaan is.

De mod kiest zelf een terugvalnaam. De API voegt geen standaardwaarde toe en gebruikt niet de handmatige naamselectie van Modloader. De waarde identificeert geen externe speler en is geen SteamID of Steam-weergavenaam. Een dedicated server heeft geen lokale clientpersonagenaam.

Gedeelde cache

Lua en Modloader lezen dezelfde native cache. De bestaande runtimetick vernieuwt de menustatus. De bestaande menu-integratie legt de naam vast zodra de eerste selectie beschikbaar is en opnieuw wanneer de selectie of naammetadata verandert. Lua-query's starten geen aparte detectie en lezen geen logboeken.

De laatst succesvol vastgelegde naam blijft in de cache nadat je een wereld bent binnengegaan. Een naam in de cache bevestigt dus niet dat het menu open is. runtime.has("runtime.is_main_menu") en runtime.has("runtime.player.name") geven de beschikbaarheid van elke query aan. runtime.status(...) geeft ook een reden.

Voorbeeld voor src/mod.lua

Dit voorbeeld leest de cache bij het laden en daarna elke 500 ms. Het kiest een terugvalnaam en registreert alleen wijzigingen:

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