工坊手册

主题

SceneGui ​

概览 ​

字段值
KindService · 服务 Service
Realmcommon

继承关系 ​

  • Unit（4 属性 / 25 函数 / 6 事件）
    • [SceneGui]（1 属性 / 2 函数）

> Service 继承 Unit 仅表示运行时类型关系；作者可用 API 以当前 Service 页面显式列出的成员为准，不自动包含 Unit 的创建、层级或销毁能力。

SceneGui 是场景界面服务，负责在三维世界坐标中创建 EUI 界面节点，或把界面节点挂接到指定单位的骨骼挂点上。它通过 EuiManager 属性对外提供 EUI 管理器，并以 CreateSceneNodeAtPosition 与 CreateSceneNodeAttachUnit 作为创建场景节点的两个入口。

适用场景 ​

需要让界面表现跟随某个单位一起移动时，可用 CreateSceneNodeAttachUnit 把节点挂接到该单位上；当界面需要固定在场景中的某个世界位置时，则使用 CreateSceneNodeAtPosition。

使用要点 ​

先通过 game:GetService("SceneGui") 获取服务实例，再调用 CreateSceneNodeAtPosition 传入 Vector3 世界坐标，或调用 CreateSceneNodeAttachUnit 传入目标单位、挂点名称、偏移向量与是否继承可见性，两者都会返回 EUISceneNode。拿到节点后需向其添加可见的界面控件子节点并设置节点的 Visible，界面才会真正显示；也可通过该服务的 EuiManager 属性取得管理器做后续管理。

注意事项 ​

CreateSceneNodeAtPosition/CreateSceneNodeAttachUnit 创建的 SceneNode 是 UI 容器节点，本身没有可见外观——必须向其添加 EUI 控件子节点（如 EUITextLabel/EUIImage）并设置可见属性后才会显示。创建后若屏幕上看不到表现，请检查：1) 父 SceneNode 是否 Visible=true；2) 是否已添加可见子控件；3) 子控件的 Position/Size 是否在屏幕范围内。

代码示例 ​

创建场景 UI 节点并安全附着到角色 ​

lua
-- @runtime client
local World = game:GetService("World")
local SceneGui = game:GetService('SceneGui')
local Players = game:GetService('Players')
local localPlayerRef = Players.LocalPlayer
if localPlayerRef == nil then return end
local rootNode = localPlayerRef.PlayerGui.EuiManager:GetRootNode()

local nodeInfo = {}
local worldNode = SceneGui:CreateSceneNodeAtPosition(Vector3.New(0, 5, 0), nodeInfo)
if worldNode ~= nil then
    worldNode.Visible = true
    local worldLabel = World:CreateUnit("EUITextLabel", { Parent = rootNode })
    if worldLabel ~= nil then
        worldLabel.Parent = worldNode
        worldLabel.Text = '世界坐标提示'
        worldLabel.FontSize = 24
    end
    print('世界坐标场景 UI 路径:', worldNode:GetFullPath())
end

local localPlayer = Players.LocalPlayer
local character = localPlayer ~= nil and localPlayer.Character or nil
if character ~= nil then
    local attachedNode = SceneGui:CreateSceneNodeAttachUnit(
        character, 'Head', Vector3.New(0, 2, 0), true, nodeInfo)
    if attachedNode ~= nil then
        attachedNode.Visible = true
        local attachedLabel = World:CreateUnit("EUITextLabel", { Parent = rootNode })
        if attachedLabel ~= nil then
            attachedLabel.Parent = attachedNode
            attachedLabel.Text = '角色头顶提示'
            attachedLabel.FontSize = 24
        end
        print('角色挂载场景 UI 路径:', attachedNode:GetFullPath())
    end
else
    print('本地玩家角色尚未创建，跳过角色挂载示例')
end

属性 (1) ​

Name类型默认值说明
EuiManagerEUIManager-SceneGui 服务的 EuiManager 属性，类型为 EUIManager，用于获取与 SceneGui 关联的 EUI 管理器对象。该属性为只读属性，作者可通过它访问 EUI 管理器提供的节点查询、节点创建与设备分辨率获取等能力。

关联类型 ​

函数 (2) ​

CreateSceneNodeAtPosition ​

签名：CreateSceneNodeAtPosition(position: Vector3, nodeInfo?: Table) -> EUISceneNode (创建的场景 UI 节点；调用前需确保 EuiManager 可用)

CreateSceneNodeAtPosition 是 SceneGui 服务提供的函数，用于在指定的世界坐标位置上创建一个场景 UI 节点。调用时传入 Vector3 类型的 position 确定节点在世界中的位置，并可选择通过 nodeInfo 表补充节点初始化信息，函数返回创建出的 EUISceneNode 节点对象。

参数类型说明
positionVector33D世界坐标位置
nodeInfo?Table可选的节点配置信息

返回值 EUISceneNode (创建的场景 UI 节点；调用前需确保 EuiManager 可用)

示例代码

在世界坐标创建场景 UI 节点

lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local rootNode = localPlayer.PlayerGui.EuiManager:GetRootNode()
local sceneGui = game:GetService('SceneGui')
local nodeInfo = {}
local worldPos = Vector3.New(0, 5, 0)

local sceneNode = sceneGui:CreateSceneNodeAtPosition(worldPos, nodeInfo)
if sceneNode ~= nil then
    sceneNode.Visible = true
    local label = World:CreateUnit("EUITextLabel", { Parent = rootNode })
    if label ~= nil then
        label.Parent = sceneNode
        label.Text = '场景提示'
        label.FontSize = 24
    end
    print('场景 UI 路径:', sceneNode:GetFullPath())
end

CreateSceneNodeAttachUnit ​

签名：CreateSceneNodeAttachUnit(Unit: Unit, Socket: String, Offset: Vector3, InheritVisible: Bool, nodeInfo?: Table) -> EUISceneNode (创建的场景 UI 节点；调用前需确保 EuiManager 可用)

CreateSceneNodeAttachUnit 是 SceneGui 服务提供的函数，用于在指定单位的挂点上创建一个场景 UI 节点。调用时需要给出单位、挂点名称、相对偏移以及是否继承可见性，并可选择通过 nodeInfo 表补充节点初始化信息，函数返回创建出的 EUISceneNode 节点对象。

参数类型说明
UnitUnit挂接单位
SocketString挂点名称
OffsetVector3相对挂点的偏移
InheritVisibleBool是否跟随单位可见性
nodeInfo?Table可选的节点配置信息

返回值 EUISceneNode (创建的场景 UI 节点；调用前需确保 EuiManager 可用)

示例代码

把场景 UI 节点挂到角色头顶

lua
-- @runtime client
local Players = game:GetService("Players")
local World = game:GetService("World")
local localPlayerRef = Players.LocalPlayer
if localPlayerRef == nil then return end
local rootNode = localPlayerRef.PlayerGui.EuiManager:GetRootNode()
local sceneGui = game:GetService('SceneGui')
local players = game:GetService('Players')
local localPlayer = players.LocalPlayer
local targetUnit = localPlayer ~= nil and localPlayer.Character or nil

if targetUnit ~= nil then
    local nodeInfo = {}
    local sceneNode = sceneGui:CreateSceneNodeAttachUnit(targetUnit, 'Head', Vector3.New(0, 2, 0), true, nodeInfo)
    if sceneNode ~= nil then
        sceneNode.Visible = true
        local label = World:CreateUnit("EUITextLabel", { Parent = rootNode })
        if label ~= nil then
            label.Parent = sceneNode
            label.Text = '角色头顶提示'
            label.FontSize = 24
        end
        print('已挂接场景 UI 路径:', sceneNode:GetFullPath())
    end
end