Bonsaibauer: Importing a new version from external source

2026-11-07T01:35:29Z

Importing a new version from external source

New page

<languages />



[[File:ShroudForge-Wiki-modding.svg|thumb|left|600px|Modding]]

 

通过 Lua 运行时读取主菜单状态和当前选中的本地角色名称。这两个查询使用与 Modloader 相同的原生数据，无需访问世界。


== 前置条件 ==

启用模组，并在 <code>mod.json</code> 中声明 <code>runtime</code> 能力：

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

对于这些客户端查询，请在 <code>extended.mod.json</code> 中将 <code>targets</code> 设为 <code>["client"]</code>。从活动的运行时回调（例如 <code>on_load</code> 和 <code>on_update</code>）调用这些函数。<code>runtime.phase == "ingame"</code> 表示模组运行时已启动，但不能确认已进入世界。这两个查询都不需要执行配置文件。其他世界操作仍有各自的要求。


== 检测主菜单 ==

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

{| class="wikitable"
! 返回值 !! 含义
|-
| <code>true, nil</code> || 已确认处于主菜单，包括角色、世界和服务器选择界面。
|-
| <code>false, nil</code> || 已验证为游戏的其他原始状态。
|-
| <code>nil, reason</code> || 状态未知、正在变化，或查询不可用。
|}

请明确检查 <code>in_menu == true</code> 或 <code>in_menu == false</code>。<code>nil</code> 不代表已确认的状态。单独的 <code>false</code> 也不能确认世界可读取。请另外检查所需操作，例如 <code>runtime.has("runtime.ecs.read")</code>。


== 读取角色名称 ==

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

<code>name, nil</code> 会以 UTF-8 字符串形式返回在本地客户端主菜单中选中的角色名称。<code>Ikiju 育樹</code> 这样的 Unicode 字符会保留。<code>nil, reason</code> 表示名称尚不可用，或当前无法访问或不允许访问。

模组自行选择备用名称。API 不会插入默认名称，也不会使用 Modloader 的手动名称选择。此值不代表远程玩家，也不是 SteamID 或 Steam 显示名称。专用服务器没有本地客户端角色名称。


== 共享缓存 ==

Lua 和 Modloader 读取同一个原生缓存。现有运行时 tick 会刷新菜单状态。现有菜单集成会在首次选择可用时获取名称，并在选择或名称元数据变化时再次获取。Lua 查询不会启动单独的发现过程，也不会读取日志。

进入世界后，最近一次成功获取的名称仍会保留在缓存中。因此，缓存中存在名称并不能确认菜单仍处于打开状态。<code>runtime.has("runtime.is_main_menu")</code> 和 <code>runtime.has("runtime.player.name")</code> 会报告各自查询是否可用。<code>runtime.status(...)</code> 也会提供原因。


== <code>src/mod.lua</code> 示例 ==

此示例会在加载时读取缓存，之后每 500 毫秒读取一次。它会选择备用名称，并且只记录变化：

<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/zh - Revision history

Bonsaibauer: Importing a new version from external source