Cache

Description:

  A singleton cache instance for various game resources.

Cache.ResourceType

Type: Enumeration.

Description:

  An enum that defines the various types of resources that can be loaded into the cache.

Signature:

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

Cache.ResourceTypeSafeUnload

Type: Enumeration.

Description:

  An enum that defines the various types of resources that can be safely unloaded from the cache.

Signature:

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

load

Type: Function.

Description:

  Loads a file into the cache with a blocking operation.

Signature:

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

Parameters:

Parameter	Type	Description
filename	string	The name of the file to load.

Returns:

Return Type	Description
boolean	True if the file was loaded successfully, false otherwise.

loadAsync

Type: Function.

Description:

  Loads a file into the cache asynchronously.

Signature:

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

Usage:

thread(function()
	local success = Cache:loadAsync("file.png")
	if success then
		print("Game resource is loaded into memory")
	end
end)

Parameters:

Parameter	Type	Description
filenames	string	{string}
handler	function	[optional] A callback function that is invoked when the file is loaded. The progress parameter is a number between 0 and 1.

Returns:

Return Type	Description
boolean	True if the files were loaded successfully, false otherwise.

getLoadState

Type: Function.

Description:

  Gets the Model3D or environment load state.

Signature:

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

getLoadDiagnostics

Returns a version-1 JSON snapshot of the latest load for the resolved model path. Calling this getter does not load a resource. Use the same API after Cache.load, Cache.loadAsync, or a Model3D loading attempt.

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

The report has version (currently 1), modelPath, state, and diagnostics. State is none, loading, ready, failed, or cancelled. Each diagnostic contains code, severity (error or warning), stage, resourcePath, textureSlot, imageIndex, materialIndex, and message. Context fields are JSON null when not applicable. Texture slots use material property paths, for example pbrMetallicRoughness.baseColorTexture; indices are zero-based. An embedded image uses the model path as its resource path. Messages are descriptive; branch on codes, not message text.

Reports are stored per resolved path. Concurrent loads of different paths cannot replace each other's diagnostics. Completion and cancellation publish the state before invoking handlers. A returned JSON string is an owning snapshot. Retrying starts a fresh report; successful retries clear previous errors. Cache hits preserve warnings from the original successful import. Ready resources may contain warnings, such as NO_RENDERABLE_GEOMETRY, EXTENSION_VALIDATION_RELAXED, or TEXTURE_DIMENSIONS_UNSUPPORTED; ready does not imply every requested material feature was rendered.

Common error codes include 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, and LOAD_CANCELLED. Missing/corrupt images identify every material slot using that image. GPU errors without more specific resource context have null indices/slot. Environment failures retain their reason with ENVIRONMENT_LOAD_FAILED.

The former plain-text error getter has been removed. Obtain error reasons from diagnostics with severity error; the structured report is the single error-reporting API. getLoadState remains a lightweight polling API.

cancelLoad

Type: Function.

Description:

  Cancels an active Model3D or environment load.

Signature:

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

update

Type: Function.

Description:

  Updates the content of a file loaded in the cache. If the item of filename does not exist in the cache, a new file content will be added into the cache.

Signature:

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

Parameters:

Parameter	Type	Description
filename	string	The name of the file to update.
content	string	The new content for the file.

update

Type: Function.

Description:

  Updates the texture object of the specific filename loaded in the cache. If the texture object of filename does not exist in the cache, it will be added into the cache.

Signature:

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

Parameters:

Parameter	Type	Description
filename	string	The name of the texture to update.
texture	Texture2D	The new texture object for the file.

unload

Type: Function.

Description:

  Unloads a resource from the cache.

Signature:

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

Parameters:

Parameter	Type	Description
type	ResourceTypeSafeUnload	The type of resource to unload.

Returns:

Return Type	Description
boolean	True if the resource was unloaded successfully, false otherwise.

unload

Type: Function.

Description:

  Unloads a resource from the cache.

Signature:

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

Parameters:

Parameter	Type	Description
filename	string	The name of the file to unload.

Returns:

Return Type	Description
boolean	True if the resource was unloaded successfully, false otherwise.

unload

Type: Function.

Description:

  Unloads all resources from the cache.

Signature:

unload: function(self: Cache)

removeUnused

Type: Function.

Description:

  Removes all unused resources (not being referenced) of the given type from the cache.

Signature:

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

Parameters:

Parameter	Type	Description
type	ResourceType	The type of resource to remove.

removeUnused

Type: Function.

Description:

  Removes all unused resources (not being referenced) from the cache.

Signature:

removeUnused: function(self: Cache)