asset_on_register

Drives the optional onRegister(self) assetType lifecycle hook — the surface that lets an asset instance run code exactly once when it first registers, operating on the per-instance ref (self). This is what makes "write an asset into the world → it takes effect live, no restart" work for content that registers into a runtime registry (editor panels, and anything else that opts in).

A type opts in by exporting onRegister from its behavior.luau. The hook fires exactly once per instance:

• On engine.onWorldLoaded — a batched sweep over every world instance of every type that implements onRegister, yielding every 32 instances so a large instance count never stalls a frame. The @builtin library (/zero/source/libs/) is excluded.
• On live asset.create — the create path calls M.fireFor(ref) on the freshly-created instance.

A per-VM once-guard keyed by the instance's VFS path ensures the two triggers can't double-register the same instance.

Exports

• M.fireFor(ref, onRegisterFn?) -> boolean — fire one instance's onRegister(self) hook exactly once. Resolves the type's hook from ref.type when onRegisterFn isn't supplied. Idempotent: a second call on the same instance is a no-op. Returns true if the hook fired this call.
• M.sweep() — batched sweep: fire onRegister once for every world instance of every registered type that implements it. Yields, so it must run inside a task. Safe to call repeatedly.
• M.install() — install the world-loaded sweep. Idempotent. Runs the sweep on a system task so it ticks through pause and never blocks the caller.