PublishService

资产发布服务，提供本地文件（图片 / 音频 / 模型 / 全景图）与已导入模型的上传、批量发布与进度查询，并支持资源地图别名（上传时传 info.Alias 自动登记「别名 → 资源 Uri」，别名表随地图持久化，运行时经 MapData:...

概览

资产发布服务，负责把本机图片、音频、模型、特效与全景图等素材上传为可在项目中引用的资产，并额外提供动画与天空盒等专项发布通道。它还维护「别名到资源地址」的映射，配套批量发布、发布进度查询与最近一次错误信息读取，便于统一管理资源导入流程。

Get by:

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

函数

PublishAsync

异步上传资产，接收本地文件路径 filePath，可选传入信息表 info 与回调函数 callback，函数本身不返回结果。

参数

参数	类型	说明
filePath	String	要上传的本地文件路径
info	Table	上传信息：Name（资源名称，可选）、Description（描述，可选）、Tags（标签数组，可选）、Alias（资源别名，可选，上传成功后登记到地图自定义数据）
callback	Function	callback(success, result)：成功 result 为 { AssetId, Uri }（图片另含 Width/Height）；失败 result 为 { Operation, ErrorCode, ErrorMessage }

异步发布本地图片

-- @runtime editor
local publishService = editor:GetService("PublishService")
local function publishImage(filePath)
    if type(filePath) ~= "string" or filePath == "" then return end
    publishService:PublishAsync(filePath, { Name = "示例图片" }, function(ok, result)
        if ok then
            print("资产 URI:", result.Uri, "资产 ID:", result.AssetId)
        else
            print("上传失败:", result.ErrorCode, result.ErrorMessage)
        end
    end)
end
-- 仅定义函数；调用方确认要发布后，显式传入真实本机图片路径调用 publishImage(filePath)。

PublishSync

同步上传资产，接收本地文件路径 filePath 与可选的信息表 info，并直接返回上传结果表。成功时返回包含 AssetId 与 Uri 的表，图片资源还会包含 Width 与 Height；失败时返回包含 Operation、ErrorCode 与 ErrorMessage 的表。

注意： 成功返回含 AssetId、Uri 的结果表；失败或超时返回含 Operation、ErrorCode、ErrorMessage 的错误表。

参数

参数	类型	说明
filePath	String	要上传的本地文件路径
info	Table	上传信息：Name（资源名称，可选）、Description（描述，可选）、Tags（标签数组，可选）、Alias（资源别名，可选，上传成功后登记到地图自定义数据）

返回值

类型	说明
Table	上传结果：成功返回 { AssetId, Uri }（图片另含 Width/Height）；失败返回 { Operation, ErrorCode, ErrorMessage }

同步发布并区分成功与错误

-- @runtime editor
local publishService = editor:GetService("PublishService")
local function publishImageSync(filePath)
    if type(filePath) ~= "string" or filePath == "" then return end
    local result = publishService:PublishSync(filePath, { Name = "示例图片" })
    if result.ErrorCode ~= nil then
        print("上传失败:", result.ErrorCode, result.ErrorMessage)
    else
        print("资产 URI:", result.Uri, "资产 ID:", result.AssetId)
    end
end
-- 仅定义函数；调用方确认要发布后，显式传入真实本机图片路径调用 publishImageSync(filePath)。

GetPublishProgress

查询当前发布流程的上传进度，返回一个进度信息表，其中包含进度数值、当前步骤名称以及是否正在上传等字段，可用于向玩家或开发者展示发布状态。

返回值

类型	说明
Table	进度信息：{ Progress = number, StepName = string, IsPublishing = boolean }

读取发布进度字段

-- @runtime editor
local publishService = editor:GetService("PublishService")
local progress = publishService:GetPublishProgress()
if progress ~= nil then
    print("进度:", progress.Progress, "步骤:", progress.StepName, "上传中:", progress.IsPublishing)
end

GetLastPublishError

获取上次上传错误。无参数调用，返回失败原因字符串；没有失败时返回空字符串。

返回值

类型	说明
String	失败原因，无失败时返回空字符串

查看上一次发布错误

-- @runtime editor
local publishService = editor:GetService("PublishService")
local errorMessage = publishService:GetLastPublishError()
if errorMessage ~= nil and errorMessage ~= "" then
    print("上次发布错误:", errorMessage)
end

PublishAssetsBatch

批量上传资产，一次性提交 items 数组中的多个上传项，并返回与输入同序的结果数组。结果数组每项包含 Success 字段表示该项是否成功：成功时 Result 为包含 AssetId 与 Uri 的表，图片资源还会包含 Width 与 Height；失败时 Result 为包含 Operation、ErrorCode 与 ErrorMessage 的表。

参数

参数	类型	说明
items	Array	上传项数组，每项：{ Type = "image" | "audio" | "mesh" | "fbx" | "effect", LocalPath = 本地文件路径, MeshName = 已导入模型名（仅 mesh）, Info = { Name, Description, Tags, Alias }（可选，Alias 为资源别名） }

返回值

类型	说明
Array	与输入同序的数组，每项 { Success = 是否成功, Result = { AssetId, Uri, Width?, Height? }（图片含宽高）或 { Operation, ErrorCode, ErrorMessage } }

批量发布并逐项检查结果

-- @runtime editor
local publishService = editor:GetService("PublishService")
local function publishConfiguredAssets(items)
    if type(items) ~= "table" or #items == 0 then return end
    local results = publishService:PublishAssetsBatch(items)
    for _, item in ipairs(results or {}) do
        if item.Success then
            print("资产 URI:", item.Result.Uri, "资产 ID:", item.Result.AssetId)
        else
            print("上传失败:", item.Result.ErrorCode, item.Result.ErrorMessage)
        end
    end
end
-- 仅定义函数；调用方准备含 Type、真实 LocalPath 和可选 Info 的上传项数组后，显式调用 publishConfiguredAssets(items)。

PublishAnimationAsync

异步上传独立的骨骼动画，将本地 FBX 动画文件提交为可在项目中使用的动画资产。调用时传入动画文件路径 fbxPath，可选传入描述信息表 info 与回调函数 callback，函数本身不返回结果。

参数

参数	类型	说明
fbxPath	String	动画 FBX 文件路径
info	Table	{ Name（资源名称，可选）, Alias（地图资源别名，可选） }
callback	Function	callback(success, result)：成功 result 为 { AssetId, Uri }；失败为 { Operation, ErrorCode, ErrorMessage }

异步发布骨骼动画

-- @runtime editor
local publishService = editor:GetService("PublishService")
local function publishAnimation(fbxPath)
    if type(fbxPath) ~= "string" or fbxPath == "" then return end
    publishService:PublishAnimationAsync(fbxPath, { Name = "示例动画" }, function(ok, result)
        if ok then
            print("动画 URI:", result.Uri, "资产 ID:", result.AssetId)
        else
            print("发布失败:", result.ErrorCode, result.ErrorMessage)
        end
    end)
end
-- 仅定义函数；调用方确认要发布后，显式传入真实动画 FBX 路径调用 publishAnimation(fbxPath)。

PublishSkybox

上传天空盒，将本地全景图文件 panoramaPath 提交为天空盒资产，可选传入信息表 info 与回调函数 callback，函数本身不返回结果。

参数

参数	类型	说明
panoramaPath	String	本地全景图文件路径（png/jpg/jpeg/tga/exr/hdr/dds/bmp，宽高比 2:1）
info	Table	{ Name(可选，默认文件名), Brightness(可选，默认 2.0), Description(可选), Tags(可选), Alias(可选，资源别名) }
callback	Function	callback(success, result)：成功 result 为 { AssetId, Uri }（天空盒主资产）

异步发布全景天空盒

-- @runtime editor
local publishService = editor:GetService("PublishService")
local function publishPanorama(panoramaPath)
    if type(panoramaPath) ~= "string" or panoramaPath == "" then return end
    publishService:PublishSkybox(panoramaPath, { Name = "示例天空盒" }, function(ok, result)
        if ok then
            print("天空盒 URI:", result.Uri, "资产 ID:", result.AssetId)
        else
            print("发布失败:", result.ErrorCode, result.ErrorMessage)
        end
    end)
end
-- 仅定义函数；调用方确认要发布后，显式传入真实本机 2:1 全景图路径调用 publishPanorama(panoramaPath)。

RegisterAssetAlias

登记资源别名。接收别名 alias 与目标资源 Uri 两个字符串参数，返回布尔值表示是否登记成功。

参数

参数	类型	说明
alias	String	开发者自定义的资源别名（地图内唯一，重复登记即改指向）
uri	String	别名指向的资源 Uri（custom://xxx）；传裸 assetId 会自动补 custom:// 前缀

返回值

类型	说明
Boolean	登记成功返回 true；alias/uri 为空或 不可用返回 false

为已发布资源登记别名

-- @runtime editor
local publishService = editor:GetService("PublishService")
local function registerPublishedAlias(alias, uri)
    if type(alias) ~= "string" or alias == "" then return false end
    if type(uri) ~= "string" or uri == "" then return false end
    return publishService:RegisterAssetAlias(alias, uri)
end
-- 在取得真实资产 URI 后调用 registerPublishedAlias(alias, uri)

ResolveAssetAlias

查询资源别名。接收别名 alias 参数，返回该别名指向的资源 Uri（custom://xxx）；别名不存在时返回 nil。

参数

参数	类型	说明
alias	String	要查询的资源别名

返回值

类型	说明
String	别名指向的资源 Uri（custom://xxx）；别名不存在时返回 nil

解析已有资源别名

-- @runtime editor
local publishService = editor:GetService("PublishService")
local aliases = publishService:GetAssetAliasMap()
for alias in pairs(aliases or {}) do
    print(alias, publishService:ResolveAssetAlias(alias))
end

GetAssetAliasMap

获取全部资源别名。无参数调用，返回「别名 → 资源 Uri」的映射表；没有别名时返回空表。

返回值

类型	说明
Table	别名 → 资源 Uri 的映射表；无别名时返回空表

遍历资源别名映射

-- @runtime editor
local publishService = editor:GetService("PublishService")
local aliases = publishService:GetAssetAliasMap()
if aliases ~= nil then
    for alias, uri in pairs(aliases) do
        print(alias, uri)
    end
end

RemoveAssetAlias

删除资源别名。接收别名 alias 参数，返回布尔值表示是否删除成功。

注意： 会删除地图中的已有别名；调用前应确认目标 alias，不使用可能命中真实数据的固定别名作自动示例。

参数

参数	类型	说明
alias	String	要删除的资源别名

返回值

类型	说明
Boolean	删除成功返回 true；别名不存在或 不可用返回 false