Bonsaibauer: Importing a new version from external source

2026-11-07T00:35:18Z

Importing a new version from external source

New page

<languages />



[[File:ShroudForge-Wiki-modding.svg|thumb|left|600px|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à <code>runtime</code> in <code>mod.json</code>:

<pre>
{
"capabilities": ["runtime"]
}
</pre>

Per queste query del client, imposta <code>targets</code> su <code>["client"]</code> in <code>extended.mod.json</code>. Chiama le funzioni da callback runtime attivi, come <code>on_load</code> e <code>on_update</code>. <code>runtime.phase == "ingame"</code> 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 ==

<pre>
local in_menu, reason = runtime.is_main_menu()
</pre>

{| class="wikitable"
! Valore restituito !! Significato
|-
| <code>true, nil</code> || Il menu principale è stato confermato, inclusa la selezione di personaggio, mondo e server.
|-
| <code>false, nil</code> || È stato convalidato un altro stato originale del gioco.
|-
| <code>nil, reason</code> || Lo stato è sconosciuto, sta cambiando oppure la query non è disponibile.
|}

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


== Leggere il nome del personaggio ==

<pre>
local name, reason = runtime.player.name()
local display_name = name or "Flameborn"
</pre>

<code>name, nil</code> restituisce come stringa UTF-8 il nome del personaggio selezionato nel menu principale del client locale. I caratteri Unicode, come in <code>Ikiju 育樹</code>, vengono preservati. <code>nil, reason</code> 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. <code>runtime.has("runtime.is_main_menu")</code> e <code>runtime.has("runtime.player.name")</code> indicano la disponibilità di ciascuna query. Anche <code>runtime.status(...)</code> fornisce una spiegazione.


== Esempio per <code>src/mod.lua</code> ==

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

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

[[Category:guide:Shroudforge]]

Modding/it - Revision history

Bonsaibauer: Importing a new version from external source