tecs.assets

Acquires assets without blocking the host, and owns what a caller holds.

A load returns the asset. There is no future, no promise and no callback in the game-facing signature: a request that cannot answer at once parks its coroutine through nupp.suspension and resumes with the answer, so the same call reads the same way inside a frame system and inside a startup script.

local loader = app.assets
local handle, reason = loader:request(tecs.assets.bytes, "levels/one.json")
if handle == nil then
    return nil, reason
end
local text <const> = handle:value() as string
handle:release()

Application creates app.assets and shuts it down after world shutdown. Standalone tools may use newAssets and must call shutdown themselves. Settled handles remain valid until their owners release them; stopping the loader cancels acquisitions, not those existing holds.

Inside a system the same two lines suspend the logical update rather than the thread, and the host renders the frames that pass while the file is read. Where no suspension handler is installed, the built-in driver runs the readiness pumps on this thread and the call still returns the asset.

What this module owns, and what it does not#

This is orchestration: requesting, sharing an acquisition between callers that want the same thing, counting holds, replacing a payload in place and reporting a failure to the call that asked for it. Reading bytes, decoding pixels, uploading a texture and freeing a native allocation belong to a Kind, which supplies a Job per acquisition and a release for the payload it produced. A GPU service registers a kind whose job issues its own upload command; nothing about textures is written here.

Failure#

An invalid argument raises at the call: an empty path, a released handle, a loader that has shut down. A load that could not produce its asset answers nil, reason from request, whether it failed before parking or hours later. The readiness pump never raises a load failure of its own, because the call that asked for the asset is the only place the reason means anything; the pump resumes that call and lets it return the pair its signature promises.

Holds and residency#

A Handle is a hold, not a cache entry. Two requests for one path that overlap share one acquisition and receive holds on one handle, because decoding the same file twice at once duplicates work without producing another result. A request made after the first settles acquires again: nothing here retains a settled asset behind the caller's back, and the payload lives exactly as long as the holds on it.

release gives up one hold, and the last one frees the payload through the kind. Releasing a handle already down to nothing does nothing, so a shutdown path need not know whether something else got there first.

Replacement#

reload acquires the same path again and swaps the result into a handle every holder already has, then frees what it displaced. The handle's identity does not change and its revision advances, which is what a consumer holding device state keyed on the handle watches to know its copy is stale. A failed reload leaves the resident payload exactly as it was and answers false, reason.

record Assets ...

entries: {[string]: Entry}

order: {Entry}

inFlight: integer

residentCount: integer

serial: integer

drainers: {Waiter}

pump: suspension.Source?

open: boolean

request: function(self: Assets, kind: Kind, path: string): (Handle?, string?)

reload: function(self: Assets, kind: Kind, handle: Handle): (boolean, string?)

drain: function(exclusive self: Assets): (boolean, string?)

pending: function(borrows self: Assets): integer

resident: function(borrows self: Assets): integer

running: function(borrows self: Assets): boolean

shutdown: function(exclusive self: Assets): nil

record Handle ...

path: string

kind: string

refs: integer

payload: any?

replacements: integer

free: (function(value: any): nil)?

owner: Assets

value: function(borrows self: Handle): any?

resident: function(borrows self: Handle): boolean

revision: function(borrows self: Handle): integer

holds: function(borrows self: Handle): integer

retain: function(exclusive self: Handle): nil

release: function(exclusive self: Handle): nil

record Job ...

poll: function(): (Status, any?, string?)

cancel: function(): nil

record Kind ...

name: string

open: function(path: string): (Job?, string?)

release: (function(value: any): nil)?

type Status = "pending" | "ready" | "failed"

function newAssets(): Assets

function readJob(path: string): Job?, string?

const bytes: Kind

const DOCUMENT

const FONT

const IMAGE

const MODEL

const SHADER

const SOUND