工坊手册

主题

World ​

概览 ​

字段值
KindService · 服务 Service
Realmcommon

继承关系 ​

继承成员 ​

3 个来源 / 11 属性 / 35 函数 / 6 事件

World 是 3D 世界的宿主服务，负责容纳所有存在于场景中的单位对象，例如 WorldUnit、ModelUnit、EffectUnit 等。当这些单位作为 World 的后代时，它们处于活跃状态：具有物理属性的单位会被渲染、参与物理模拟并与其他单位及世界交互；脱离 World 层级的对象不会被渲染，也不会参与物理计算，直到重新挂载到 World 树中。World 还承担创建单位、加载资源、提供服务器时间以及响应自定义事件等职责。

适用场景 ​

在客户端或服务端需要创建并挂载场景单位、加载预设资源、读取服务器时间或获取自定义事件信号时，通过 game:GetService("World") 获取世界根容器。

使用要点 ​

先获取 local world = game:GetService("World")，再调用 world:CreateUnit(unitType, values)。World:CreateUnit 与全局 game:CreateUnit 的 Parent 规则不同，不要混写 receiver。

注意事项 ​

World:CreateUnit 在 values 省略 Parent 时会把新单位默认挂载到当前 World；若需要挂到其他容器，应显式传入 Parent。全局 game:CreateUnit 不会自动设置 Parent，使用时通常需显式指定。单位从 World 树移除后会停止渲染和物理模拟，重新挂载后可恢复。

代码示例 ​

创建临时单位并读取服务器时间 ​

lua
-- @runtime client
local world = game:GetService('World')
local unit = world:CreateUnit('WorldUnit', {
    Name = 'TemporaryWorldUnit',
    Position = Vector3.New(0, 5, 0),
})
if unit ~= nil then print('单位创建成功:', unit.Name) end
print('当前服务器时间:', world:GetServerTime())
if unit ~= nil then unit:Destroy() end

属性 (1) ​

Name类型默认值说明
CurrentCameraCameraUnit-当前激活的相机实例。

关联类型 ​

函数 (4) ​

CreateUnit ​

签名：CreateUnit(unitType: String, values?: Table) -> Unit (新创建的单位实例)

在世界中创建并返回一个单位实例。unitType 为要创建的单位类型名称，可选的 values 表用于提供创建参数，方法返回新创建的单位实例。

参数类型说明
unitTypeString要创建的单位类型名称，如 "WorldUnit"、"ModelUnit"、"EffectUnit" 等
values?Table初始化属性键值表。省略 Parent 时默认挂载到当前 World；若需挂到其他容器，应显式传入 Parent。可填写字段以目标 unitType 及其继承链的公开属性为准。

返回值 Unit (新创建的单位实例)

示例代码

创建并清理临时世界单位

lua
-- @runtime client
local world = game:GetService('World')
local unit = world:CreateUnit('WorldUnit', { Name = 'TemporaryUnit' })
if unit ~= nil then
    print('已创建:', unit.Name)
    unit:Destroy()
end

CreateAsset ​

签名：CreateAsset(assetId: String) -> Array<Unit> (Units)

根据传入的资源 ID 加载对应的资源，并返回由该资源生成的一组单位实例。

参数类型说明
assetIdString资产预设ID

返回值 Array<Unit> (Units)

示例代码

加载预设并清理本次创建的单位

lua
-- @runtime client
local world = game:GetService('World')
local function loadAndInspectAsset(assetId)
    if assetId == nil or assetId == '' then return end
    local units = world:CreateAsset(assetId)
    print('加载单位数量:', units and #units or 0)
    for _, unit in ipairs(units or {}) do
        unit:Destroy()
    end
end
-- 调用方把项目配置中的真实预设资源 ID 传给 loadAndInspectAsset

GetServerTime ​

签名：GetServerTime() -> Float (服务器时间，单位为秒)

获取当前服务器时间，单位为秒。

返回值 Float (服务器时间，单位为秒)

示例代码

获取服务器时间并输出

lua
-- @runtime client
-- 获取 World 服务实例
local world = game:GetService("World")

-- 获取当前服务器时间（秒）
local serverTime = world:GetServerTime()

-- 输出服务器时间
print("当前服务器时间:", serverTime, "秒")

GetCustomEventSignal ​

签名：GetCustomEventSignal(eventName: String) -> Signal (自定义事件信号)

获取一个全局自定义事件的信号对象，用于监听或触发跨脚本通信。

参数类型说明
eventNameString自定义事件名

返回值 Signal (自定义事件信号)

示例代码

获取自定义事件信号并监听（判空保护）

lua
-- @runtime client
local world = game:GetService('World')
local signal = world:GetCustomEventSignal('MyCustomEvent')
if signal == nil then
    print('自定义事件不存在，请先确认事件名已注册')
    return
end
signal:Connect(function(data)
    print('收到自定义事件，数据:', tostring(data))
end)
print('已开始监听 MyCustomEvent 事件')