ReplicatedFirst

ReplicatedFirst 优先复制仓库服务。管理优先复制容器下的所有 Unit，提供查找、创建等操作。

概览

ReplicatedFirst 是优先复制服务容器，其子单位会在客户端加入时优先复制，适合放置加载初期需要访问的关键资源。

Get by:

-- @runtime editor
local service = editor:GetService("ReplicatedFirst")

函数

FindFirstChild

在 ReplicatedFirst 容器下按名称查找第一个匹配的子单位。

参数

参数	类型	说明
name	String	要查找的单位名称

返回值

类型	说明
Unit	找到的单位；未找到时返回 nil

按名称查找优先复制单位并处理未命中

-- @runtime editor
-- 获取 SE 编辑器专属的优先复制仓库服务
local replicatedFirst = editor:GetService("ReplicatedFirst")

-- 1. 先取出容器下所有单位句柄，作为未命中时的参考信息
local units = replicatedFirst:GetDescendants()
print("ReplicatedFirst 单位数量:", #units)

-- 2. 按名称查找目标单位，未找到时返回 nil
local targetName = "LoadingScreen"
local target = replicatedFirst:FindFirstChild(targetName)
if target ~= nil then
    print("已找到目标单位:", tostring(target))
else
    print("未找到名为 " .. targetName .. " 的单位，请确认该单位已挂到 ReplicatedFirst 下")
    for index, unit in ipairs(units) do
        print("当前可选单位 " .. index .. ":", tostring(unit))
    end
end

GetDescendants

获取 ReplicatedFirst 容器下的所有单位，并以数组形式返回。

返回值

类型	说明
Array	容器下的所有单位数组

枚举优先复制容器内的所有单位并按名称复核

-- @runtime editor
local replicatedFirst = editor:GetService("ReplicatedFirst")

-- 1. 一次性取出容器下的所有单位句柄
local units = replicatedFirst:GetDescendants()
print("优先复制容器单位总数:", #units)

if #units == 0 then
    print("容器当前为空：可向 ReplicatedFirst 下放入加载界面脚本、初始化配置等优先复制资源")
else
    for index, unit in ipairs(units) do
        print("第 " .. index .. " 个单位:", tostring(unit))
    end

    -- 2. 通过按名称查找复核枚举结果能否取回
    local probeName = "LoadingScreen"
    local found = replicatedFirst:FindFirstChild(probeName)
    if found ~= nil then
        print("按名称复核成功:", probeName)
    else
        print("按名称复核未命中:", probeName)
    end
end

CreateAsset

在 ReplicatedFirst 容器中按资产内容 ID 创建资产单位，并返回本次创建出的单位数组。

参数

参数	类型	说明
contentId	String	预设资产 ID，可通过 PrefabService:CreatePrefab 创建后获取
pos	Vector3	创建位置（世界坐标）
options	Table	创建选项：rot（旋转）、scale（缩放），均为可选

返回值

类型	说明
Array	创建的单位数组

用项目预设 ID 创建优先复制资源

-- @runtime editor
local storage = editor:GetService("ReplicatedFirst")
local function createFromAsset(assetId)
    if assetId == nil or assetId == "" then return end
    local units = storage:CreateAsset(assetId, Vector3.New(0, 0, 0))
    for _, unit in ipairs(units or {}) do
        print("已创建:", unit)
    end
end
-- 把项目中的真实预设资源 ID 传给 createFromAsset

CreateUnit

在 ReplicatedFirst 容器中按单位类型名创建单位，并返回创建出的单位数组。

参数

参数	类型	说明
unitType	String	要创建的单位类型名称（如 WorldUnit、ModelUnit）
values	Table	创建参数：Position（位置）、Rotation（旋转）、Scale（缩放）、AssetId（直接指定预设资产 ID），均为可选

返回值

类型	说明
Array	创建的单位数组；该类型无可用预设且未传 AssetId 时返回空数组

创建 WorldUnit 并清理

-- @runtime editor
local storage = editor:GetService("ReplicatedFirst")
local units = storage:CreateUnit("WorldUnit", {})
for _, unit in ipairs(units or {}) do
    print("已创建:", unit)
    unit:Destroy()
end

GetUnitsByUnitType

在 ReplicatedFirst 容器中按单位类型名筛选单位，并返回匹配到的单位数组。

参数

参数	类型	说明
unitType	String	要查询的单位类型名称
exact	Bool	是否精确匹配；false 时同时返回继承子类型

返回值

类型	说明
Array	匹配到的单位数组，无匹配时返回空数组

查询 WorldUnit

-- @runtime editor
local storage = editor:GetService("ReplicatedFirst")
local units = storage:GetUnitsByUnitType("WorldUnit", true)
print("数量:", #units)