toonWrap.styleBlock
- .metadata163 B
- README.md4.1 KB
- block.yaml2.0 KB
- preview.png468 KB
README.md
Soft wrap light (styleBlock, Light)
Soft wrap-around light (half-Lambert) for the whole frame: the light wraps round the side turned from the sun so shapes stay readable in shadow, the darks lifted softly instead of cut, for a soft anime or storybook look.
Settings: wrap (0.8), wrapPower (2), shadowShape (0.6), litAbove (0.75), bands (0), softness (0.08), shadowLift (0.35), shadowTint (#bfb8eb), fullLight (1), keepLightColour (0.5), smoothLight (0.85). Low quality smooths the light with four taps per ring instead of eight.
It reads the light like the other toonBlocks light blocks (the frame divided by the base colour in display values, a share of fullLight, smoothed by smoothLight over two rings of taps on the same surface), then lifts the darks toward the light by wrap (0 the light as rendered, 1 the half-Lambert lift). Where a surface is below litAbove of full light (turned from the sun, or in cast shadow) the sun's half-Lambert term, wrapPower its curve, shapes it by shadowShape, from the sun's direction and the normal rebuilt from depth, so a sphere in shade still reads round. bands 2 or more cuts the wrapped light into that many soft bands (softness, shadowLift); 0 keeps a smooth gradient. The light turns toward shadowTint as it fades. It does not redraw a clean two-level sun light as Toon bands and Toon ramp do: the light keeps the scene's own shadows and gradients, only softened.
What it gives up in motion
Smooth and calm. The light is read again every frame, so nothing slides under any camera move and the shading follows moving and animated things. The wrap follows the sun, so a moving sun moves the soft terminator; the sun's direction reaches the block about once a second, so under a moving sun the shaping in shade shifts in small soft steps, which the smooth gradient hides well. With bands set, band edges sweep across surfaces as the light moves, like Toon bands but softer. Normals rebuilt from depth can show facets of low-polygon shapes in the shaped shade.
How it treats content
- Opaque things: lit softly with readable form in shade, each keeping its own colour and texture.
- Transparent things (glass, water): read as the surface behind with the pane's tint and reflections counted as light, so glass and water brighten or dim what is behind softly.
- Particles and smoke: counted as light on the surface behind: glows brighten it, smoke dims it, with no hard edge unless
bandsis set. - Sky: never touched.
- Fog: the wrap lifts the fogged light, so far surfaces lift a little more toward one soft value; fog's colour survives only as light colour. A depth mask keeps the block to the near ground if the haze flattens.
- Skinned characters: wrapped every frame, so the soft light follows every pose; shading in shade comes from normals rebuilt from depth, smooth on finely made bodies, faceted on coarse ones. The
toonLitmaterial's wrap mode (ToonMaterial.paint(heroId, { mode = "wrap" })) gives a character the same light from its exact normals. - Foliage: each leaf is softened on its own; the noisy normals across a canopy show less here than with hard bands, since nothing is cut.
- World text: a label is lit like any surface; dark words in shade are lifted a little. Leave labels out by name:
StyleKit.options({ exclude = { "labelName" } }). - Black stays black: no light stays no light (the wrap only lifts light that 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.