Cache

描述：

  用于管理各种游戏资源缓存的单例类。

Cache.ResourceType

类型： 枚举。

描述：

  可以被缓存的各种资源类型。

签名：

enum ResourceType
	"Bone"
	"Spine"
	"Texture"
	"SVG"
	"Clip"
	"Frame"
	"Model"
	"Particle"
	"Shader"
	"Font"
	"Sound"
end

Cache.ResourceTypeSafeUnload

类型： 枚举。

描述：

  可以从缓存中被安全卸载的各种资源类型。

签名：

enum ResourceTypeSafeUnload
	"Texture"
	"SVG"
	"Clip"
	"Frame"
	"Model"
	"Particle"
	"Shader"
	"Font"
	"Sound"
	"Spine"
end

load

类型： 函数。

描述：

  使用阻塞的操作将资源文件加载到缓存中。

签名：

load: function(self: Cache, filename: string): boolean

参数：

参数名	类型	描述
filename	string	要加载的资源文件的名称。

返回值：

返回类型	描述
boolean	如果资源文件成功加载，则返回 true，否则返回 false。

loadAsync

类型： 函数。

描述：

  使用异步方式将资源文件加载到缓存中。

签名：

loadAsync: function(self: Cache, filename: string | {string}, handler?: function(progress: number)): boolean

用法示例：

thread(function()
	local success = Cache:loadAsync("file.png")
	if success then
		print("游戏资源已加载到内存中")
	end
end)

参数：

参数名	类型	描述
filename	string	{string}
handler	function	[可选] 加载进度回调函数。progress 参数是一个介于0和1之间的数字，表示加载进度的百分比。

返回值：

返回类型	描述
boolean	如果资源文件成功加载，则返回 true，否则返回 false。

getLoadState

类型： 函数。

描述：

  获取 Model3D 或环境资源的加载状态。

签名：

getLoadState: function(self: Cache, filename: string): LoadState

getLoadDiagnostics

返回按模型解析路径保存的最近一次加载报告，格式为 version=1 的 JSON 字符串。此查询不会触发加载；同步 Cache.load、异步 Cache.loadAsync 和 Model3D 加载尝试后使用同一接口。

getLoadDiagnostics: function(self: Cache, filename: string): string

local report = assert(require("json").decode(Cache:getLoadDiagnostics("assets/Fox.glb")))
for _, diagnostic in ipairs(report.diagnostics) do
    print(diagnostic.code, diagnostic.resourcePath, diagnostic.textureSlot, diagnostic.message)
end

报告包含 version（当前为 1）、modelPath、state、diagnostics。state 为 none、loading、ready、failed 或 cancelled。每条诊断含 code、severity（error/warning）、stage、resourcePath、textureSlot、imageIndex、materialIndex、message。不适用的上下文字段为 JSON null；索引从 0 开始；纹理槽使用材质属性路径，例如 pbrMetallicRoughness.baseColorTexture。嵌入贴图的资源路径为模型路径。message 供阅读，程序应按 code 分支，不解析消息文本。

报告按解析路径隔离，并发加载不同模型不会混用诊断。完成或取消时先发布状态，再调用处理函数。返回字符串是独立快照；重试开启新报告，成功后清除旧错误；缓存命中保留原成功导入中的警告。ready 仍可能含 NO_RENDERABLE_GEOMETRY、EXTENSION_VALIDATION_RELAXED、TEXTURE_DIMENSIONS_UNSUPPORTED 等警告，不代表所有请求的材质特性均已渲染。

常见错误码包括 RESOURCE_NOT_FOUND、RESOURCE_READ_FAILED、RESOURCE_URI_INVALID、GLTF_PARSE_FAILED、GLTF_VALIDATION_FAILED、BUFFER_MISSING、BUFFER_TOO_SHORT、IMAGE_BUFFER_RANGE、IMAGE_DECODE_FAILED、GPU_UPLOAD_FAILED、LOAD_CANCELLED。缺失或损坏贴图会指出使用该图像的各材质槽。无法细分资源的 GPU 错误，其槽和索引为 null。环境资源失败以 ENVIRONMENT_LOAD_FAILED 保留原因。

原纯文本错误查询已移除；从 diagnostics 中 severity=error 的条目读取原因，统一使用这一错误报告接口。getLoadState 保留为轻量状态轮询接口。

cancelLoad

类型： 函数。

描述：

  取消进行中的 Model3D 或环境资源加载。

签名：

cancelLoad: function(self: Cache, filename: string): boolean

update

类型： 函数。

描述：

  更新缓存中已加载资源文件的内容。 如果资源文件名称对应的项不存在于缓存中，则会将新资源内容添加到缓存中。

签名：

update: function(self: Cache, filename: string, content: string)

参数：

参数名	类型	描述
filename	string	要更新的资源文件名称。
content	string	新的资源内容。

update

类型： 函数。

描述：

  更新缓存中指定文件名的纹理对象。 如果 filename 对应的纹理对象不存在于缓存中，则将其添加到缓存中。

签名：

update: function(self: Cache, filename: string, texture: Texture2D)

参数：

参数名	类型	描述
filename	string	要更新的纹理的名称。
texture	Texture2D	文件的新纹理对象。

unload

类型： 函数。

描述：

  从缓存中强制卸载一类资源。

签名：

unload: function(self: Cache, type: ResourceTypeSafeUnload): boolean

参数：

参数名	类型	描述
type	ResourceTypeSafeUnload	要卸载的资源类型。

返回值：

返回类型	描述
boolean	如果资源成功卸载，则返回 true，否则返回 false。

unload

类型： 函数。

描述：

  从缓存中强制卸载一个资源文件。

签名：

unload: function(self: Cache, filename: string): boolean

参数：

参数名	类型	描述
filename	string	要卸载的资源文件名称。

返回值：

返回类型	描述
boolean	如果资源文件成功被卸载，则返回 true，否则返回 false。

unload

类型： 函数。

描述：

  从缓存中强制卸载所有资源文件。

签名：

unload: function(self: Cache)

removeUnused

类型： 函数。

描述：

  按资源类型从缓存中删除所有未被使用（未被引用）的资源。

签名：

removeUnused: function(self: Cache, type: ResourceType)

参数：

参数名	类型	描述
type	ResourceType	要删除的资源类型。

removeUnused

类型： 函数。

描述：

  从缓存中删除所有未被使用（未被引用）的资源。

签名：

removeUnused: function(self: Cache)