Custom shaders

When the built-in material types aren’t enough, vgai lets you register a custom material definition and reference it by name from a scene — a first-class registry entry, not an escape hatch bolted onto a component.

The custom material flow.

The MaterialDef contract

A custom material is a MaterialDef (packages/engine/src/scene/material-registry.ts):

interface MaterialDef {
  build(uniforms: Record<string, unknown>): THREE.Material;
  update?(dt: number, material: THREE.Material, uniforms: Record<string, unknown>): void;
}

• build(uniforms) returns a real THREE.Material — typically a ShaderMaterial with your GLSL, or a configured stock material. Authored uniforms from the scene are passed in.
• update?(dt, material, uniforms) optionally ticks self-animating uniforms each frame (e.g. uTime for flowing water).

Register the def by name; a scene then declares { type: 'custom', def: '<name>', uniforms: {…} }.

The Water example

packages/engine/src/scene/materials/water.ts is the shipped reference def: a ShaderMaterial with a vertex shader that displaces a surface with summed sine waves driven by a uTime uniform, and an update that advances uTime. It’s the model to copy for your own shaders.

Status: partial — no inline GLSL in scene files

Custom materials must be registered defs. Writing raw GLSL directly inside a .vscn.json is not supported today (it’s a known gap in the rendering roadmap). Author your shader as a MaterialDef in code and reference it by name.

See also

• Materials — the built-in material types.
• What’s New / Roadmap — the inline-shader gap and other rendering plans.
• Scene Schema reference — the custom material fields.