工坊手册

主题

World ​

概览 ​

字段值
KindService · 服务 Service
Realmcommon

继承关系 ​

继承成员 ​

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

World 是三维世界的根容器，负责承载并激活所有挂载在其下的单位对象，只有在 World 树内的单位才会被渲染并参与物理交互。它提供 CreateUnit 按类型动态创建单位、CreateAsset 依据资产标识批量生成单位，以及 GetServerTime 获取统一服务器时间和 GetCustomEventSignal 订阅命名自定义事件的能力。此外，通过 AOIType2 相关半径与销毁类型属性可以控制兴趣区域的流式加载范围，CurrentCamera 则直接暴露当前使用的相机单位。

适用场景 ​

在客户端或服务端需要创建并挂载场景单位、加载预设资源、读取服务器时间或获取自定义事件信号时，通过 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

属性 (5) ​

Name类型默认值说明
AOIType2StreamingMainRadiusFloat64World 服务上的 Streaming 主半径配置属性，类型为 Float，标题为“Streaming主半径”。该属性可读可写，用于设置世界中 Streaming 主半径的浮点数值。
AOIType2MinRadiusFloat100World 服务上的 AOI 第二类型最小半径（内圈）配置属性，类型为 Float，标题为“AOI内圈”。该属性可读可写，表示 AOI 内圈对应的半径数值。
AOIType2MaxRadiusFloat200World 服务上的 AOI 第二类型最大半径（外圈）配置属性，类型为 Float，标题为“AOI外圈”。该属性可读可写，表示 AOI 外圈对应的半径数值。
AOIDestroyTypeInt0 (Immediately)AOI 销毁类型，Meta 公开类型为 Int，并定义了对应的内联取值名称。
CurrentCameraCameraUnit-World 的 CurrentCamera 属性指向当前世界正在使用的相机实例，类型为 CameraUnit。通过该属性，脚本可以拿到场景当前的相机对象，并进一步访问或调整该相机实例上已公开的成员。

关联类型 ​

函数 (4) ​

CreateUnit ​

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

按单位类型名在 World 中创建一个基础单位实例，并可通过可选参数表传入初始属性。

参数类型说明
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 事件')