Log inGet started
Package

toonBlocks.package

This package holds more than this page lists. See all of its files in its world.

README.md

Toon bands (styleBlock, Light)

Cel shading for the whole frame with no material edits: the light on every surface cut into a chosen number of hard flat bands, with tinted shadows, clean anti-aliased band edges and cast shadows that stay shadows.

Settings: bands (3), shadowLift (0.65), keepShade (0), shadowTint (#9e99db), bias (0.05), softness (0.015), topBoost (1), shape (0.9), shadeLevel (0.3), castBelow (0.8), fullLight (1), keepLightColour (0.5), smoothLight (0.85). Low quality smooths nothing (smoothLight 0).

It reads the light the scene sent at each pixel as the frame divided by the surface's base colour (the deferred renderer's copy), both in display values, so texture cancels and the sun, its shadows, the ambient and every lamp are left; fullLight is how much of that counts as full light. smoothLight mixes in the mean of two rings of taps (3 and 8 reference pixels, only taps on the same surface by depth), so normal-map grain and occlusion speckle do not cut islands into the bands. shape then redraws the light as a clean two-level toon light from the scene's sun: full where the surface faces the sun (its normal rebuilt from depth) and the light that arrived is above castBelow of full light, shadeLevel elsewhere, never more than four times the light that arrived; with no sun in the scene it changes nothing. The result is cut into bands levels (edges moved by bias, each edge softness wide), the darkest band keeps shadowLift of the light and turns toward shadowTint, the top band is scaled by topBoost, and the surface's base colour is put back lit by keepLightColour of the light's own colour. The sky and pixels whose base colour is black are left as they are; on the forward renderer, which keeps no base colour copy, it judges the light by brightness alone and goes half way.

keepShade (0 by default, off) keeps a surface's own colour in the shadow band. The shadow band is the base colour times shadowLift and shadowTint, which on its own paints a surface at about 40 percent of its colour, however much light the scene really gave it. Under a strong sky light a wall turned from the sun shows at nearly its full colour, and that 40 percent turns orange brick walls and a red tile roof dark brown. Raise keepShade (0.7 was the 1.0.4 to 1.0.9 default) and the shadow band is lifted toward that share of the brightness the scene showed there, keeping its tint and hue, at most two thirds of the way to the next band and only inside the shadow band; cast shadows and dark scenes, which the scene itself left dark, stay dark, and black stays black. How far it lifts follows a steady 8 x 8 mean of the scene's light smoothly: nothing until the scene asks for a third of the way, all two thirds from two thirds on. It is not clean on a figure: the lift is read from the scene's light, which carries pixel-level noise at silhouettes and seams (texture, the coarser copies the blocks read), and wherever a figure's shade asks for less than the full lift that noise shows as specks inside the shadow band. From an editor camera 3 m from the showcase figure (1920 x 1080), 0.7 flecks the figure more than 0 does, some of it where 0 is one flat tone (the counts are in the package README, 1.1.2). That is why it is off by default: at 0 the band is exactly as cut. Use it on walls and props under a strong sky, the case it is for, and keep it off a stage whose figures are seen close. (1.0.9 lifted in crisp whole thirds; wherever a figure's shade sat near a step, that noise tipped it pixel by pixel into a comb along the figure's edges and dark flecks inside the band. Up to 1.0.8 the floor followed the scene's brightness pixel by pixel over every band and drew a soft terminator's climb over the darker lit bands.)

starterBlocks' Stepped light (lightBands) is the light, cheap version: one pass that steps brightness over base colour into bands, and a bandedToon material. Toon bands goes further: the light read in display values, smoothing against normal-map grain, a clean light from the sun's direction with cast shadows kept, tinted shadows, band bias and anti-aliased edges, the ramp, wrap, rim and highlight blocks beside it, and a material version (ToonMaterial.paint, the toonLit shader). Both are Light blocks, so they swap in one change: StyleKit.swap("light", "lightBands").

What it gives up in motion

Bands are cut again every frame from the light that arrived, so they stay on their surfaces under pan, dolly, orbit and zoom and follow moving and animated things exactly; nothing slides. When the sun or a lamp moves, a band edge sweeps across a surface instead of fading, as cel shading does. The sun's direction reaches the block about once a second (styleKit reads it on that rhythm), so under a moving sun (a day cycle) the clean light's terminator moves in small steps about once a second; lower shape for a fast sun. Normals are rebuilt from depth rather than taken from the mesh, so a low-polygon rounded shape shows its facets as steps in the clean light, and the terminator can flicker by a pixel along thin parts and silhouettes. On the low tier, with no smoothing, fine texture in the light (occlusion speckle) can cut small islands into the bands that crawl as the camera moves.

How it treats content

  • Opaque things: banded by the light that reached them, each keeping its own colour and texture; shadows tinted toward shadowTint (with keepShade raised, the shadow band is lifted toward that share of what the scene showed, so a shaded wall keeps its colour); cast shadows read as shade.
  • Transparent things (glass, water): they keep no base colour of their own, so the pixel is read as the surface behind with the pane's tint, reflections and highlights counted as light on it. A tinted pane or deep water can drop what is behind into a lower band, and a bright reflection can step it into the top band.
  • Particles and smoke: counted as light on the surface behind: sparks and glows lift it into a brighter band, smoke dims it toward the shadow band, with a hard edge where they cross a band edge. Leave effects that must stay soft out by name: StyleKit.options({ exclude = { "Sparks" } }).
  • Sky: never touched.
  • Fog: the cut is made on the fogged light. Fog lightens dark surfaces and dims bright ones with distance, so far surfaces drift toward one middle band and a shaded far wall can read as lit; fog's colour survives only as the light's colour. In heavy fog lower shape, or limit the block with a depth mask.
  • Skinned characters: banded every frame, so bands follow every pose; a coarse body shows its facets in the clean sun light. For a character banded by its own exact normals, paint it with ToonMaterial.paint and keep this block off it with a group mask.
  • Foliage: alpha-tested leaves have depth and base colour and are banded leaf by leaf; normals rebuilt across a mass of leaves are noisy, so a canopy breaks into scattered lit and shaded leaves rather than one shaded mass. Lower shape or keep foliage out with a group mask.
  • World text: a label is a surface like any other and is banded: white words in shade turn toward the shadow tint. Leave labels a player must read out by name: StyleKit.options({ exclude = { "labelName" } }).
  • Black stays black: no light stays no light (the bands only exist where light arrived) and it returns through sk_finish, so with every light off the frame is black.

Known limits

  • It runs on the whole frame after antialiasing, so offscreen captures, mirrors and render-to-texture cameras do not show it (#17427).
  • Per-object settings (a style channel or a game role) reach it through the shared object mask, at most eight distinct settings a scene. A per-object value cannot reach a geometry pass, so a per-object look that needs one draws passes of its own (#24549).
  • Its passes are queued again every frame, even when nothing changed (#24548).

The package README's Known limits lists the rest.