Materials and the render graph

This guide covers the material family that ships today, how a scene becomes draw calls (render lists, §64–§66), and — honestly — how much of §57's unified material model and §63's render graph exists at the tip. Short version (rewritten 2026-08-29; the previous one predated every landing below and still called PBR, shadows and the render graph "staged"): the §57 Material base is complete, five material classes ship — §59's metallic-roughness StandardMaterial and §60's graph-driven NodeMaterial (RFC 0001) included — the §63 render graph runs linear scene, custom and §70 effect passes, §68 lighting covers a directional light plus up to eight punctual lights with one §69 shadow tier, and two GPU backends (WebGL 2 and WebGPU) consume the same render list.

The shipped materials

Five material classes (four/materials) over a §57-complete Material base, plus one instanced path for particles. This section said "two material classes" and omitted LitMaterial until 2026-08-05, and "three" until 2026-08-29 — StandardMaterial (R-13, 2026-08-08) and NodeMaterial (RFC 0001, 2026-08-28) had landed:

import { SpriteMaterial, UnlitMaterial } from "fourJS/materials";
import { Renderable, Sprite, Texture } from "fourJS/render";
import { planeGeometry } from "fourJS/geometry";

// Flat colour, straight (non-premultiplied) RGBA in 0..1 (§60a, §66):
const slab = new Renderable(
  planeGeometry({ width: 2, height: 1 }),
  new UnlitMaterial({ color: [0.16, 0.18, 0.24, 1] }),
);

// Recolour in place; setColor announces the change:
slab.material.setColor(0.1, 0.52, 0.45, 1);

// A textured quad. The texture is an RGBA8 buffer you own:
const texture = new Texture({ width: 6, height: 12, data: rgbaBytes });
const badge = new Sprite(new SpriteMaterial({ texture, tint: [1, 1, 1, 1] }), {
  width: 0.5,
  height: 1,
  anchor: { x: 0, y: 0 },
  renderLayer: 1, // draw after opaque shapes — sprites blend (§66)
});

The family, member by member:

• UnlitMaterial — one colour (optionally a texture map and vertex colours), no lights.
• SpriteMaterial — the sampled texture and a straight-RGBA tint; frame regions live on the Sprite node itself (below).
• LitMaterial — colour-only, mirroring UnlitMaterial, shaded by §68's directional light, Scene.ambientLight, and — since R-17 (2026-08-09) — up to eight point and spot lights (MAX_PUNCTUAL_LIGHTS, packages/render/src/lights.ts; this paragraph named only the one directional light until 2026-08-29). It needs geometry carrying the optional normals attribute — boxGeometry and planeGeometry generate per-face normals; 2D shapes stay unlit and position-only.
• StandardMaterial — §59's metallic-roughness workflow (R-13, 2026-08-08): baseColor (plus an optional map), metalness, roughness, emissive. normalMap and occlusionMap are staged with recorded reasons (no tangent attribute yet; one texture unit per draw), and §59's physical extensions belong to a PhysicalMaterial that does not exist — see standard-material.ts.
• NodeMaterial — §60's shader-graph member (RFC 0001, 2026-08-28): shading is a serializable graph of closed operators, never a source string (§57's ShaderMaterial is permanently unshipped — spec revision 1.11). Unlit at this tier; the custom shaders guide is the full story.

The base itself carries §57's shared render state on every member — opacity, transparent, blendMode ("normal", "additive", "multiply", "screen"), depthTest, depthWrite, colorWrite, and stencil (R-7, 2026-08-11) — with defaults that reproduce the pre-base frame byte-for-byte.

Particles use ParticleRenderable (see the performance guide); geometry comes from four/geometry's boxGeometry, planeGeometry, and circleGeometry2D.

On WebGL 2, four of the backend's pipelines are registration seams (2026-09-11, the registerSkinningPipeline() shape): call registerShadowPipeline() before a light's castShadow can produce a map, registerEffectPipeline() before a RenderGraph copy / grade / output-transform pass will draw, registerParticlePipeline() before a ParticleRenderable is drawn, and registerStandardPipeline() before a StandardMaterial surface is drawn (an owner decision — §59 is a core family, and the seam still pays for itself in every bundle that shades with LitMaterial alone). Each is one explicit call at application setup, never an import side effect; an unregistered feature is skipped with one development warning naming the call (shadows fall back to unshadowed lighting; effects, particles and standard surfaces to absence — never a Lambert stand-in), and a bundle that never calls one carries none of that pipeline. §60 graph effects go through registerNodeMaterialPipeline() instead. WebGPU compiles all four eagerly.

import {
  registerEffectPipeline,
  registerParticlePipeline,
  registerShadowPipeline,
  registerStandardPipeline,
  registerWebglRenderer,
} from "fourJS/render-webgl";

registerWebglRenderer();
registerShadowPipeline(); // §69: the depth-only caster pass
registerEffectPipeline(); // §70: copy, colour grade, output transform
registerParticlePipeline(); // §36: instanced billboards, trails, R-32 appearance
registerStandardPipeline(); // §59: the metallic-roughness surface

Facts of this tier worth knowing before you fight them:

• Blending on shapes and meshes is opt-in per material. The base's transparent: false default leaves blending off; set transparent: true (with opacity and a blendMode) to blend. Sprites and particles blend by construction, flag or no flag. This bullet said blending was "enabled for sprites and particles only" and that an unlit material's alpha "never reaches a blend equation" until 2026-08-29 — stale since §57's base landed 2026-08-06.
• Announce in-place colour edits. setColor bumps material.version; writing components directly into the colour array requires a material.markDirty() after (the discipline unlit-material.ts records). This bullet claimed an in-place edit was "picked up next frame without touching material.version" until 2026-08-29.
• Atlases work through sprite.frame. §55's frame sub-rectangle landed as R-29 (2026-08-08): a texel-space region, validated against the texture it indexes (§85), and changing it costs no geometry re-upload — which is what sprite flip-book animation needs. Named atlas containers and sprite animation clips are staged with reasons in sprite.ts. This bullet described cutting each atlas cell into its own small Texture as "the documented workaround" for an unlanded frame until 2026-08-29.

From scene to draw calls (§64–§66)

There is no retained display list to manage. Each frame the renderer walks the scene into a sorted render list:

import { buildInterpolatedRenderList, buildRenderList } from "fourJS/render";

const list = buildRenderList(scene, []); // live transforms
buildInterpolatedRenderList(scene, poses, alpha, list); // §43 render poses

For a skinned mesh the same call also refreshes the joint palette. Local poses interpolate (position lerp, rotation slerp), then Skeleton.update(skinRoot, worldOf) runs the palette product inverse(skinRootWorld) · boneWorld · inverseBind[i]. Palettes are never matrix-lerped — a 90° joint at alpha = 0.5 is a 45° slerp, not the average of two matrices — and nothing is written back into node.transform (§42). The live-transform path (buildRenderList) calls update(skinRoot) with no provider. See fixed-step simulation for the pose buffer, and tests/integration/interpolated-skin-palettes.test.ts for the two-bone consumer check.

Items sort by §66's keys 1, 2 and 5 — renderLayer, then opaque before transparent (the material's transparent flag, since 2026-08-06), then renderOrder — and because Array.prototype.sort is stable, equal keys fall back to generation (scene-graph) order: later siblings draw on top. §66's other two keys ship as separate, opt-in verbs, for the recorded reason that both permute co-planar draws a 2D scene depends on (render-list.ts): key 3 (pipeline/material grouping) is groupRenderListByPipeline, and key 4 (depth) is sortRenderListByDepth on the per-view derived list (view-list.ts, R-8, 2026-08-09 — which is also where frustum culling landed). This paragraph claimed a default sort "by render layer, then kind (opaque unlit first, then blended sprites, then particles), then material" until 2026-08-05; no such comparator has ever existed, and until 2026-08-29 the correction overshot by claiming the sort was renderLayer/renderOrder "and nothing else". The backend does track the _current_ pipeline and only re-binds a program when the kind changes — a per-run state-change saving on an already-ordered list, not a sort.

Two GPU backends consume the list (this paragraph named only one until 2026-08-29): the WebGL 2 backend (WebglRenderer, four/render-webgl) and the WebGPU backend (WebgpuRenderer, four/render-webgpu), both with cached GPU resources keyed by object identity and version; a particle item becomes exactly one instanced draw whatever its count.

Renderer (§61) is the backend-independent interface; NullRenderer is the headless implementation the determinism suites use. A backend registers itself into @fourjs/render's §62 registry only when the application calls its register*Renderer() — four/application itself imports no backend at runtime, which is what keeps headless bundles free of GL (R-2/A-8).

Honest state of the rest

When the staged remainders land they are required to slot beneath the same Renderer interface and render-list contract, so scene code written against today's tier does not change.

Practical guidance

• Author colours as straight-alpha RGBA in 0…1 and keep a palette; the examples' colour-discipline notes exist because tests read hue. Blending on shapes is a deliberate opt-in (transparent: true), not a default — a scene that never opts in renders byte-identically to the pre-§57 tier.
• Overlap is resolved by depth: push scenery behind bodies (negative Z) and marks in front, rather than relying on draw order.
• One material instance per logical surface; share materials across nodes that recolour together (the glyph cache in examples/ui-demo shares one material per distinct glyph cell). Sharing also feeds §65's opt-in batching, which merges only runs that share a material instance.

Cross-references

• §55, §57–§60, §60a, §61–§66, §68–§70 — the normative text.
• Custom shaders (§60), the performance guide (§86, batching numbers), and docs/COMPATIBILITY.md section 2 (the per-backend §62 tables).
• examples/first-2d-scene (sprites + text), examples/ui-demo (skins over unlit quads), examples/particles-demo (instanced batching).