工坊手册

主题

UI 节点导出与脚本访问 ​

UI 编辑器中创建的控件，在脚本里通过控件名称定位：先拿到 UI 根节点，再用 FindFirstChild 在节点树上按名称查找对应实例。

本文涵盖：

  1. UI 节点数据的导出流程
  2. 客户端脚本如何按名称获取 UI 控件
  3. 按钮等控件的交互事件处理
  4. 客户端与服务端通过 RemoteEvent 通信

导出 UI 节点数据 ​

UI 编辑器中的控件会导出为一份完整的节点树信息，用于查看工程里的控件层级结构，也可以作为 AI 助手的上下文资料。

脚本访问控件不依赖导出结果，只需要知道控件名称即可，详见下方「在客户端定位 UI 控件」。

导出步骤 ​

  1. 打开脚本工程（VSCode），点击左侧的【插件】侧边栏。

  2. 选择【导出数据】。

  3. 导出成功后，在【浏览】侧边栏可以看到工程里新增了一个 data 文件夹，其中是导出的 UI 节点树信息。

WARNING

  • UI 编辑器中控件名称必须唯一。FindFirstChild 只会返回第一个匹配到的节点，重名会导致脚本取到错误的控件。
  • UI 编辑器内修改控件名称、新增 / 删除控件后，建议重新导出，让节点树信息与工程保持一致。

在客户端定位 UI 控件 ​

UI 控件的访问只能在客户端（client/main.lua 或 client/ 下的脚本）进行。

关键服务与对象 ​

Players ​

Players 服务管理所有连接到当前服务器的玩家对象，提供玩家查找、用户信息查询（性别和头像缩略图）以及聊天样式设置等能力。

API 参考：Players

LocalPlayer ​

Players.LocalPlayer 仅在客户端有值，并且是当前客户端的玩家实例。服务端读到的是 nil。

API 参考：Player

EuiManager ​

UI 控件实例统一由 Players.LocalPlayer.PlayerGui.EuiManager 管理。通过 EuiManager:GetRootNode() 拿到 UI 根节点，再调用节点的 FindFirstChild(name, true) 按控件名查找子节点。

API 参考：EUIManager · EUINodeBase

通用获取代码 ​

在 client/main.lua 中编写访问 UI 控件的工具函数：

lua
local Players = game:GetService("Players")

-- 获取 EUI 管理器
local function GetEUI()
    local lp = Players.LocalPlayer
    if not lp then return nil end
    return lp.PlayerGui.EuiManager
end

-- 按控件名查找节点
-- Recursive = true：递归查找整棵 UI 树；层级明确时也可传 false 只查直接子节点
local function FindUINode(name)
    local euiMgr = GetEUI()
    if not euiMgr then return nil end
    local root = euiMgr:GetRootNode()
    if not root then return nil end
    return root:FindFirstChild(name, true)
end

-- 获取 UI 编辑器里创建的控件实例
local LabelTime = FindUINode("LabelTime")
local LabelPoint = FindUINode("LabelPoint")
print("[ShaoTest] 找到文本框对象:", LabelTime, LabelPoint)

运行游戏后在输出窗看到对应日志，即表示关联成功。

WARNING

Players.LocalPlayer 在客户端启动初期可能为 nil，所以 GetEUI 加了空值判断。上面的示例写在 client/main.lua 顶层，是为了脚本加载后立刻能在输出窗看到日志、快速确认关联是否成功；正式逻辑中建议把节点查找放进事件回调，或用 TimerService:CreateTimer 延迟到界面加载完成后再取——部分设备在顶层立即查找可能因 UI 尚未加载完成而拿到 nil。

按钮交互 ​

监听点击事件 ​

EUIButton 实例提供 OnClicked 事件，玩家点击按钮时触发。

lua
local BtnReset = FindUINode("BtnReset")
BtnReset.OnClicked:Connect(function()
    -- 这里写按钮点击后的客户端逻辑
end)

按钮控件的创建方式与可配置属性见 UI 编辑器基础 - 控件类型。

修改控件属性 ​

通过设置控件实例的属性可以动态修改 UI 显示，例如修改文本框内容：

lua
LabelTime.Text = "倒计时: 60"
LabelPoint.Text = "当前得分：0"

各控件的可写属性详见 UI 编辑器基础 - 控件类型 或对应 API 文档。

客户端 / 服务端通信（RemoteEvent） ​

UI 控件只能在客户端访问，但游戏的核心逻辑（玩家数据、玩法状态等）通常在服务端运行。当 UI 操作需要触发服务端行为（例如点击按钮重置球体）时，需要通过 RemoteEvent 通信。

RemoteEvent 简介 ​

RemoteEvent 是用于客户端与服务端之间双向通信的全局机制，支持：

  • 服务端 → 客户端：服务端可以向所有玩家或指定玩家发送消息。
  • 客户端 → 服务端：客户端可以将玩家的输入操作上报给服务端。

事件信号：

信号触发端说明
OnClientEvent客户端收到服务端发来的消息
OnServerEvent服务端收到客户端发来的消息（带 player 参数）

发送方法：

方法调用端说明
:FireServer(...)客户端调用把消息发到服务端
:FireClient(player, ...)服务端调用把消息发到指定玩家客户端
:FireAllClients(...)服务端调用把消息发到所有客户端

WARNING

RemoteEvent 通过 RemoteEvent.New("eventId") 构造实例。客户端和服务端使用相同的 eventId 创建返回的是各自独立的实例对象，它们都会响应对应端同名实例发出的事件通知。

API 参考：RemoteEvent

示例：点击按钮重置球体 ​

下面以"点击 UI 重置按钮 → 服务端重置球体位置"为例，展示完整通信流程。

客户端（client/main.lua）：

lua
local BtnReset = FindUINode("BtnReset")
local gameResetRE = RemoteEvent.New("GameReset")

BtnReset.OnClicked:Connect(function()
    gameResetRE:FireServer() -- 把按钮点击事件转发给服务端
end)

服务端（server/main.lua）：

lua
local gameResetRE = RemoteEvent.New("GameReset")

gameResetRE.OnServerEvent:Connect(function(player)
    -- player 参数是触发的玩家实例
    ResetBall() -- 调用服务端的重置逻辑
end)