Modding

Modding

Leggi lo stato del menu principale e il nome del personaggio locale selezionato tramite il runtime Lua. Entrambe le query usano gli stessi dati nativi del Modloader e non richiedono accesso al mondo.

Prerequisiti

Abilita la mod e dichiara la capacità runtime in mod.json:

{
  "capabilities": ["runtime"]
}

Per queste query del client, imposta targets su ["client"] in extended.mod.json. Chiama le funzioni da callback runtime attivi, come on_load e on_update. runtime.phase == "ingame" indica che il runtime della mod è avviato e non conferma l'ingresso in un mondo. Nessuna delle due query richiede un profilo di esecuzione. Le altre operazioni nel mondo mantengono i propri requisiti.

Rilevare il menu principale

local in_menu, reason = runtime.is_main_menu()

Valore restituito	Significato
true, nil	Il menu principale è stato confermato, inclusa la selezione di personaggio, mondo e server.
false, nil	È stato convalidato un altro stato originale del gioco.
nil, reason	Lo stato è sconosciuto, sta cambiando oppure la query non è disponibile.

Controlla esplicitamente in_menu == true o in_menu == false. nil non è uno stato confermato. Anche false da solo non conferma che un mondo sia leggibile. Controlla separatamente l'operazione necessaria, ad esempio runtime.has("runtime.ecs.read").

Leggere il nome del personaggio

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

name, nil restituisce come stringa UTF-8 il nome del personaggio selezionato nel menu principale del client locale. I caratteri Unicode, come in Ikiju 育樹, vengono preservati. nil, reason significa che il nome non è ancora disponibile oppure che l'accesso non è disponibile o consentito.

La mod sceglie il proprio nome di fallback. L'API non inserisce un valore predefinito e non usa la selezione manuale del nome del Modloader. Il valore non identifica un giocatore remoto e non è né uno SteamID né un nome visualizzato da Steam. Un Dedicated Server non ha un nome di personaggio client locale.

Cache condivisa

Lua e il Modloader leggono la stessa cache nativa. Il tick runtime esistente aggiorna lo stato del menu. L'integrazione del menu esistente acquisisce il nome alla prima selezione disponibile e di nuovo quando cambiano la selezione o i metadati del nome. Le query Lua non avviano una ricerca separata e non leggono i log.

L'ultimo nome acquisito correttamente resta nella cache dopo l'ingresso in un mondo. Un nome in cache quindi non conferma che il menu sia aperto. runtime.has("runtime.is_main_menu") e runtime.has("runtime.player.name") indicano la disponibilità di ciascuna query. Anche runtime.status(...) fornisce una spiegazione.

Esempio per src/mod.lua

Questo esempio legge la cache al caricamento e poi ogni 500 ms. Sceglie un nome di fallback e registra solo le modifiche:

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