shader Module

Public Luau surface over the __shader Internal FFI namespace — turning authored WGSL into registered GPU programs, and the reusable modules those programs include.

Purpose

A shader is authored as a .shader or .computeShader asset and compiled by that assetType; a .shaderModule is WGSL other shaders include rather than copy. The entry points here are what those assetTypes are built on. Content reaches a shader through a reference to it, so an author normally meets this module only through the asset that calls it.

Each function registers one compiled program under every key it was given — guid, identity, alias — so a shader can be included or dispatched by whichever name the including content happens to hold.

Usage

The assetType compiles the surface shader it owns, registering it under both of its names at once:

local ref = asset.resolve("@builtin::shaders.water", "shader")
shader.compile({ ref.guid, ref.identity }, {
    source = vfs.read(ref.path .. "/shader.wgsl"),
    properties = props,
})

Compilation is asynchronous, so the outcome is asked for rather than returned:

local status, err = shader.status(ref.guid)
if status == "failed" then
    log.error("water shader: " .. tostring(err))
end

A "pending" immediately after a write means the compile has not finished — ask again next frame.

WGSL that other shaders include is registered the same way, and registering again replaces it and recompiles every shader that includes it:

local mod = asset.resolve("@builtin::shaderModules.pbr_shading", "shaderModule")
shader.registerModule({ mod.guid, mod.identity }, vfs.read(mod.path .. "/module.wgsl"))

Include literals are resolved against the including asset's own path before the source reaches the compiler — see modules/shader_includes.