---
title: "shader"
description: "Shader compilation: turning authored WGSL into registered GPU programs, and the reusable modules those programs include."
section: "API Reference"
slug: "api-shader"
canonical: "https://origozero.ai/docs/api-shader"
updated: "2026-10-20T13:15:36.991951721+00:00"
tags: ["api", "reference"]
---

# shader

Shader compilation — turning authored WGSL into registered GPU programs, and the reusable modules those programs include.

```lua
require("@builtin::modules.api.engine.shader") -- shader (also available as global 'shader')
```

The `shader` namespace: 12 functions.

## globals/shader/compile {#globals-shader-compile}

```lua
shader.compile(keys: string | { string }, opts: { [string]: any }) -> boolean
```

Compile a zero-scaffolding SURFACE shader: the author wrote only
`vertex()` / `fragment()` and declared its material properties, and the
engine generates the group(1) material interface plus every render-mode
entry point. Compiles once and registers the result under its key.

**Parameters**

- `keys` `string | { string }` — The shader key (`guid@checksum` of the version compiled), alone or
as a one-element array.
- `opts` `{ [string]: any }` — `{ source, domain?, properties?, replaces? }` — the author's WGSL,
its `@domain`, the declared property schema, and the key this shader
compiled under before its source changed, whose materials move to the new
key.

**Returns** `boolean` — True when the compile was queued.

```lua
local m = asset.meta(ref); shader.compile(m.guid .. "@" .. m.checksum, { source = wgsl, properties = props })
```

## globals/shader/forget {#globals-shader-forget}

```lua
shader.forget(keys: string | { string }) -> boolean
```

Drop what a removed shader registered under its key: its programs and
their variants, the composed WGSL, the compile status and the diagnostic.
The pipelines built from those programs are evicted and the materials
drawing through them re-prepare.

**Parameters**

- `keys` `string | { string }` — The shader key (`guid@checksum`), alone or in an array.

**Returns** `boolean` — True when the removal was queued.

```lua
local m = asset.meta(ref); shader.forget(m.guid .. "@" .. m.checksum)
```

## globals/shader/registerModule {#globals-shader-registermodule}

```lua
shader.registerModule(keys: string | { string }, source: string) -> boolean
```

Register a block of WGSL other shaders include. Every key names the same
source, so a shader includes it by whichever name it holds — its guid, its
identity, or an alias. Registering again replaces it, and the shaders that
include it recompile.

**Parameters**

- `keys` `string | { string }` — One key, or the array of keys this module answers to.
- `source` `string` — The module's WGSL.

**Returns** `boolean` — True when the registration was queued.

```lua
shader.registerModule({ ref.guid, ref.identity }, wgsl)
```

## globals/shader/status {#globals-shader-status}

```lua
shader.status(name: string) -> (string, string?)
```

A shader's latest compile outcome, without reading the engine log:
`"compiled"`, `"failed"` (with the compiler error second), or `"pending"`.
Compilation is async, so a `"pending"` straight after a write means ask
again next frame.

**Parameters**

- `name` `string` — The key it compiled under (`guid@checksum`), or a reference to a
shader asset (identity, path, guid), which reaches the key of the version
that reference resolves to now.

**Returns** `(string, string?)` — Status, and the compiler error when it failed.

```lua
local status, err = shader.status("myShader")
```

## modules/shader/compile {#modules-shader-compile}

```lua
compile(keys: string | { string }, opts: { [string]: any }): boolean
```

Compile a zero-scaffolding SURFACE shader: the author wrote only
`vertex()` / `fragment()` and declared its material properties, and the
engine generates the group(1) material interface plus every render-mode
entry point. Compiles once and registers the result under its key.

**Parameters**

- `keys` `string | { string }` — The shader key (`guid@checksum` of the version compiled), alone or
as a one-element array.
- `opts` `{ [string]: any }` — `{ source, domain?, properties?, replaces? }` — the author's WGSL,
its `@domain`, the declared property schema, and the key this shader
compiled under before its source changed, whose materials move to the new
key.

```lua
local m = asset.meta(ref); shader.compile(m.guid .. "@" .. m.checksum, { source = wgsl, properties = props })
```

## modules/shader/forget {#modules-shader-forget}

```lua
forget(keys: string | { string }): boolean
```

Drop what a removed shader registered under its key: its programs and
their variants, the composed WGSL, the compile status and the diagnostic.
The pipelines built from those programs are evicted and the materials
drawing through them re-prepare.

**Parameters**

- `keys` `string | { string }` — The shader key (`guid@checksum`), alone or in an array.

```lua
local m = asset.meta(ref); shader.forget(m.guid .. "@" .. m.checksum)
```

## modules/shader/registerModule {#modules-shader-registermodule}

```lua
registerModule(keys: string | { string }, source: string): boolean
```

Register a block of WGSL other shaders include. Every key names the same
source, so a shader includes it by whichever name it holds — its guid, its
identity, or an alias. Registering again replaces it, and the shaders that
include it recompile.

**Parameters**

- `keys` `string | { string }` — One key, or the array of keys this module answers to.
- `source` `string` — The module's WGSL.

```lua
shader.registerModule({ ref.guid, ref.identity }, wgsl)
```

## modules/shader/status {#modules-shader-status}

```lua
status(name: string): (string, string?)
```

A shader's latest compile outcome, without reading the engine log:
`"compiled"`, `"failed"` (with the compiler error second), or `"pending"`.
Compilation is async, so a `"pending"` straight after a write means ask
again next frame.

**Parameters**

- `name` `string` — The key it compiled under (`guid@checksum`), or a reference to a
shader asset (identity, path, guid), which reaches the key of the version
that reference resolves to now.

```lua
local status, err = shader.status("myShader")
```

## typed/builtin//modules/api/engine/shader/shader/compile {#typed-builtin-modules-api-engine-shader-shader-compile}

```lua
shader.compile(keys: string | { string }, opts: { [string]: any }) -> boolean
```

Compile a zero-scaffolding SURFACE shader: the author wrote only
`vertex()` / `fragment()` and declared its material properties, and the
engine generates the group(1) material interface plus every render-mode
entry point. Compiles once and registers the result under its key.

**Parameters**

- `keys` `string | { string }` — The shader key (`guid@checksum` of the version compiled), alone or
as a one-element array.
- `opts` `{ [string]: any }` — `{ source, domain?, properties?, replaces? }` — the author's WGSL,
its `@domain`, the declared property schema, and the key this shader
compiled under before its source changed, whose materials move to the new
key.

**Returns** `boolean` — True when the compile was queued.

```lua
local m = asset.meta(ref); shader.compile(m.guid .. "@" .. m.checksum, { source = wgsl, properties = props })
```

## typed/builtin//modules/api/engine/shader/shader/forget {#typed-builtin-modules-api-engine-shader-shader-forget}

```lua
shader.forget(keys: string | { string }) -> boolean
```

Drop what a removed shader registered under its key: its programs and
their variants, the composed WGSL, the compile status and the diagnostic.
The pipelines built from those programs are evicted and the materials
drawing through them re-prepare.

**Parameters**

- `keys` `string | { string }` — The shader key (`guid@checksum`), alone or in an array.

**Returns** `boolean` — True when the removal was queued.

```lua
local m = asset.meta(ref); shader.forget(m.guid .. "@" .. m.checksum)
```

## typed/builtin//modules/api/engine/shader/shader/registerModule {#typed-builtin-modules-api-engine-shader-shader-registermodule}

```lua
shader.registerModule(keys: string | { string }, source: string) -> boolean
```

Register a block of WGSL other shaders include. Every key names the same
source, so a shader includes it by whichever name it holds — its guid, its
identity, or an alias. Registering again replaces it, and the shaders that
include it recompile.

**Parameters**

- `keys` `string | { string }` — One key, or the array of keys this module answers to.
- `source` `string` — The module's WGSL.

**Returns** `boolean` — True when the registration was queued.

```lua
shader.registerModule({ ref.guid, ref.identity }, wgsl)
```

## typed/builtin//modules/api/engine/shader/shader/status {#typed-builtin-modules-api-engine-shader-shader-status}

```lua
shader.status(name: string) -> (string, string?)
```

A shader's latest compile outcome, without reading the engine log:
`"compiled"`, `"failed"` (with the compiler error second), or `"pending"`.
Compilation is async, so a `"pending"` straight after a write means ask
again next frame.

**Parameters**

- `name` `string` — The key it compiled under (`guid@checksum`), or a reference to a
shader asset (identity, path, guid), which reaches the key of the version
that reference resolves to now.

**Returns** `(string, string?)` — Status, and the compiler error when it failed.

```lua
local status, err = shader.status("myShader")
```