工坊手册

主题

Game ​

概览 ​

字段值
KindService · 服务 Service
Realmcommon

继承关系 ​

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

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

Game 是游戏对象树的根节点，也是全局唯一可用的顶层对象，负责承载全部服务与单位的创建入口。它通过 GetService 按名称取得全局服务，通过 CreateUnit 按类型创建场景或界面单位，并提供 IsLoaded、BindToClose、SetClipboardText、GenerateGUID 等基础能力。此外还会广播 Loaded 与 ServerRestartScheduled 两个本地事件，用于感知加载完成和服务器重启安排。

适用场景 ​

常见于脚本初始化阶段获取各类服务对象，例如用 game:GetService 取得服务后调用其接口；也用于创建场景单位，例如传入名称与属性表调用 game:CreateUnit("WorldUnit", {...}) 生成单位并挂到场景中。服务器关闭前注册收尾逻辑同样依赖它的 BindToClose。

使用要点 ​

全局变量 game 本身即为 Game 实例，可直接调用方法，无需再次通过 GetService 获取自身。先调用 game:GetService("ServiceName") 拿到所需服务，再在服务实例上调用其公开函数；创建单位时使用 game:CreateUnit("UnitName", values) 并设置 Parent 指向 World、PlayerGui 或已有容器。可用 game:IsLoaded() 判断加载状态，用 game:GenerateGUID() 生成唯一标识，用 game:SetClipboardText(text) 写入剪贴板，并用 Connect 监听 Loaded 事件执行加载完成后的初始化。

注意事项 ​

Game 是全局对象树的根节点，全局变量 game 即为 Game 实例，无需通过 GetService 获取。通过 game:GetService("ServiceName") 可获取各类全局服务实例。CreateUnit 用于创建场景或 UI 单位，通常需显式设置 Parent 到 World、PlayerGui 或已有容器；EUI 控件创建仍属于 Unit 创建流程，EUIManager 只负责管理/查找/挂载既有 UI 节点。UnitId 为系统保留键，传入会被忽略。

代码示例 ​

通过 game 获取服务并创建单位 ​

lua
-- @runtime client
-- game 是全局根对象，直接使用即可（不要 local game = game:GetService("Game")）
local World = game:GetService("World")

-- 创建一个 WorldUnit 并设置 Parent
local worldUnit = game:CreateUnit("WorldUnit", { Parent = World })
if worldUnit ~= nil then
    print('已创建 WorldUnit:', worldUnit)
end

-- 获取其他服务
local Players = game:GetService("Players")
print('Players 服务:', Players)

关联类型 ​

事件 (2) ​

Loaded ​

签名：Loaded() 触发：local

客户端初始单位与属性加载完成时触发的事件。

示例代码

监听客户端加载完成事件

lua
-- @runtime client
-- 获取 Game 实例（全局变量 game 即为 Game 实例）

local connection = game.Loaded:Once(function()
    print("客户端加载完成，可以安全访问场景单位和服务")
    -- 加载完成后执行后续逻辑，例如获取 World 服务
    local world = game:GetService("World")
    if world then
        print("成功获取 World 服务")
    end
end)
-- 注意：Once 会在触发后自动断开，无需手动 Disconnect

ServerRestartScheduled ​

签名：ServerRestartScheduled(restartTime: Int, closeReason: SpaceCloseReason, attributes: Map) 触发：local

Game 服务的服务器重启计划事件。当服务器被安排重启时在服务器侧触发，并向回调提供计划重启时间 restartTime、关闭来源 closeReason 以及自定义属性 attributes。

回调参数类型说明
restartTimeInt计划重启的时间戳,实际重启可能会稍晚于此预计时间，但不会早于此时间
closeReasonSpaceCloseReason触发服务器重启的原因,参见枚举Enum.SpaceCloseReason
attributesMap提供的重启事件自定义元数据，根据它可以定制特殊的逻辑，默认是一个空的字典

示例代码

在服务端监听计划重启

lua
-- @runtime server
game.ServerRestartScheduled:Once(function(restartTime, closeReason, attributes)
    print('计划重启时间戳:', restartTime)
    print('关闭原因:', closeReason)
    for key, value in pairs(attributes) do
        print('附加属性:', key, value)
    end
end)

函数 (6) ​

GetService ​

签名：GetService(serviceName: String) -> Unit | nil (对应的服务实例对象)

按公开服务名称获取全局服务实例。

⚙ 示例和文档中不要使用 CollectionService；需要给 Unit 打标签、查找标签对象或监听标签变化时使用 TagService。

参数类型说明
serviceNameString要获取的公开服务名称，如 "World"、"Players"、"PhysicsService"、"TagService"、"RunService" 等。

返回值 Unit | nil (对应的服务实例对象)

示例代码

获取音效服务并播放 2D 音效

lua
-- @runtime client
local soundService = game:GetService('SoundService')
local soundUnit = soundService:Play2D(
    'official://audio/10001',
    80,
    1.0,
    false,
    false,
    3.0
)
print('创建的 SoundUnit:', soundUnit)

CreateUnit ​

签名：CreateUnit(unitType: String, values?: Table) -> Unit | nil (新创建的单位实例，创建失败时返回 nil)

在 Game 服务上创建指定类型的 Unit 实例。第一个参数 unitType 为字符串形式的单位类型名，第二个参数 values 为可选的属性初始值表，用于在创建时一并设置该单位的属性。返回新创建的单位实例，创建失败时返回 nil。

参数类型说明
unitTypeString要创建的单位类型名称，如 "WorldUnit"、"ModelUnit"、"EffectUnit" 等
values?Table初始化属性键值表。可填写的属性键来自对应 unitType 的 API 文档（即该类型及其继承链上声明的属性），例如 { Name = "box", Position = Vector3.New(0, 10, 0), Parent = world }。注意：UnitId 为系统保留键，传入会被忽略；本方法不会自动设置 Parent，需显式指定。具体支持哪些属性以该单位类型 API 文档中列出的属性为准。

返回值 Unit | nil (新创建的单位实例，创建失败时返回 nil)

示例代码

通过全局 game 创建单位

lua
-- @runtime client
local World = game:GetService('World')
local unit = game:CreateUnit('WorldUnit', {
    Name = 'MyUnit',
    Position = Vector3.New(10, 0, 0),
    Parent = World,
})
if unit ~= nil then
    print('单位创建成功:', unit.Name)
end

IsLoaded ​

签名：IsLoaded() -> Bool (是否已完成初始加载)

判断客户端是否已完成初始加载。在加载完成后，游戏场景和资源才可安全访问。

返回值 Bool (是否已完成初始加载)

示例代码

检查客户端是否加载完成

lua
-- @runtime client
-- 获取 Game 实例

local loaded = game:IsLoaded()

if loaded then
    print("客户端已加载完成")
else
    print("客户端尚未加载完成")
end

BindToClose ​

签名：BindToClose(callback: Function) -> void

注册一个回调函数，该函数会在服务器即将关闭时被调用。可用于在服务器关闭前执行清理工作，例如保存数据或通知玩家。

⚙ BindToClose 仅用于服务端关闭流程。callback 可接收关闭原因，但 CloseReason 枚举尚未进入当前公开 Surface；可用 tostring(closeReason) 记录诊断，不要比较自行猜测的枚举成员。服务器最多等待约 30 秒完成关闭回调。

参数类型说明
callbackFunction如果绑定的函数接受一个参数，则传递Enum.CloseReason，指定服务器关闭的原因。

返回值 void

示例代码

在服务端注册关闭回调

lua
-- @runtime server
game:BindToClose(function(closeReason)
    print('服务器即将关闭，原因:', tostring(closeReason))
    -- 在关闭等待窗口内完成必要的保存与清理
end)

SetClipboardText ​

签名：SetClipboardText(text: String) -> void

将指定文本内容复制到系统剪贴板，方便玩家粘贴使用。

参数类型说明
textString要复制到剪切板的字符串。

返回值 void

示例代码

调用 SetClipboardText

lua
-- @runtime client

local text = "示例文本"  -- String
game:SetClipboardText(text)
print("已调用 SetClipboardText", text)

GenerateGUID ​

签名：GenerateGUID() -> String (唯一编号)

Game 的 GenerateGUID 函数用于生成一个唯一编号，返回值为 String 类型。该函数不需要传入任何参数，调用后即可得到一个可用作标识的字符串。

返回值 String (唯一编号)

示例代码

生成全局唯一编号并校验唯一性

lua
-- @runtime client
-- Game 是全局对象树的根节点，全局变量 game 即为 Game 实例，无需通过 GetService 获取
local gameRoot = game
-- 连续生成两个唯一编号，用于给动态创建的对象打上互不重复的标识
local guid1 = gameRoot:GenerateGUID()
local guid2 = gameRoot:GenerateGUID()
-- 消费返回值：打印结果，并确认两次生成的结果互不相同
print("第一个唯一编号:", guid1)
print("第二个唯一编号:", guid2)
print("两次生成的编号是否不同:", guid1 ~= guid2)