SceneGui

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

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

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

场景界面服务负责管理以三维世界坐标为基准的界面系统，可在一个世界坐标点生成界面节点，也可把界面节点挂接到具体单位并令其随单位显示。它还向外暴露场景专用的 EuiManager，方便统一检索和操作场景界面树。由它创建的节点本质上是容器，需要填充 EUI 控件后才具备可见外观。

适用场景

适合实现跟随单位的头顶名牌、血条或投影在场景某处的交互面板等世界空间界面；一般先取得服务实例，再按需创建静态位置或单位绑定的界面节点。

使用要点

通过 game:GetService("SceneGui") 获取服务后，调用 CreateSceneNodeAtPosition 在世界坐标生成一个独立界面节点，或调用 CreateSceneNodeAttachUnit 将节点挂到某个单位的指定挂点上并传递偏移与是否继承可见性。节点创建后向其添加 EUITextLabel、EUIImage 等可见 EUI 控件，再调整 EUISceneNode 的位置与大小使内容出现在目标区域；若需全局管理场景界面，可经由 EuiManager 访问界面管理器。

注意事项

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

代码示例

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

-- @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	类型	默认值	说明
EuiManager	EUIManager	-	获取 SceneGui 关联的 EUI 管理器实例。

关联类型

• Unit
• EUIManager

函数 (2)

CreateSceneNodeAtPosition

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

在指定世界坐标处创建场景UI节点，可传入可选的配置表，并返回创建出的场景UI节点对象。

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

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

示例代码

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

-- @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 可用)

在指定单位的指定挂点上创建场景UI节点，可设置相对挂点的偏移量以及是否继承单位的可见状态，可选传入配置表。

参数	类型	说明
Unit	Unit	挂接单位
Socket	String	挂点名称
Offset	Vector3	相对挂点的偏移
InheritVisible	Bool	是否跟随单位可见性
nodeInfo?	Table	可选的节点配置信息

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

示例代码

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

-- @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