toonBlocks.package
- ..
- .metadata175 B
- README.md5.7 KB
- block.yaml2.6 KB
- preview.png355 KB
This package holds more than this page lists. See all of its files in its world.
README.md
Toon ramp (styleBlock, Light)
Ramp shading for the whole frame: the light on every surface picks its colour from a five-stop colour ramp, from deep shadow to full light, blended or stepped like cel paint, and the whole ramp switches with one call.
Settings: rampDark (#1a1733), rampShadow (#615c99), rampMid (#c7b3bd), rampLight (#fff2db), rampHigh (#fffff5), shadowAt (0.25), midAt (0.5), lightAt (0.78), hard (0.75), softness (0.02), rampStrength (1), shape (0.9), shadeLevel (0.3), castBelow (0.8), fullLight (1), keepLightColour (0.5), smoothLight (0.85). Low quality smooths the light with four taps per ring instead of eight.
It reads and cleans the light as Toon bands does: the frame divided by the surface's base colour in display values (a share of fullLight), smoothed over the same surface, and redrawn by shape as a clean two-level light from the scene's sun (full where the surface faces the sun and the light that arrived is above castBelow, shadeLevel elsewhere). While shape redraws it, the ramp reads that light fully smoothed (the dense 8 x 8 mean; smoothLight matters only with shape 0), holds the shadow colour up to where Toon bands' first band edge lies at its defaults (0.38 of the way from shade to full sun) and spreads the stops above over the rest, and on the high tier takes, for each pixel, the lower of the middle of its row of three and the middle of its column of three, so a hairline seam between two parts of a figure, or one pixel, does not take the next colour alone. That light, 0 to 1, then picks a colour from the ramp: rampDark at 0, rampShadow at shadowAt, rampMid at midAt, rampLight at lightAt, rampHigh at 1. hard 0 blends through the stops, 1 steps from one to the next halfway between them, each step softness wide. The ramp's colours are light, not paint: they multiply the surface's own colour, so every object keeps its colour and the ramp says what colour its light and shadow are. rampStrength below 1 keeps the ramp's brightness and lets go of its colour.
The package ships thirteen ramps (ToonBlocks.ramps() lists them): classicCel, warmCool, goldenHour, sunset, moonlight, pastelAnime, storybook, candy, autumn, noir, comicTwoTone, plasticCG and toxicSciFi. ToonBlocks.setRamp("sunset") puts one on every toonRamp entry in the scene's stack (one synced change each, so every player sees it) and on every object painted with ToonMaterial.paint; ToonBlocks.currentRamp() names the ramp the first entry wears. A ramp of your own is a <name>.toonRamp folder (see the toonRamp asset type). From Toon bands: StyleKit.swap("light", "toonRamp"), then ToonBlocks.setRamp(id).
What it gives up in motion
The ramp is picked again every frame from the light that arrived, so colours stay on their surfaces under any camera move and follow moving and animated things; nothing slides. A moving sun or lamp moves the colour steps across surfaces, sweeping rather than fading when hard is high. The sun's direction reaches the block about once a second, so under a moving sun the clean light's terminator moves in small steps; lower shape for a fast sun. Normals are rebuilt from depth, so low-polygon rounded shapes show their facets as steps, and the terminator can flicker by a pixel on thin parts and silhouettes. Switching the ramp is instant, for every player at once.
How it treats content
- Opaque things: shaded through the ramp by the light that reached them, each keeping its own colour and texture under the ramp's light colours.
- Transparent things (glass, water): read as the surface behind with the pane's tint and reflections counted as light, so glass or water can shift what is behind to a darker or brighter ramp colour.
- Particles and smoke: counted as light on the surface behind: a glow lifts it up the ramp, smoke pulls it down toward the shadow colours. Leave effects that must keep their own colour out by name with
StyleKit.options({ exclude = { ... } }). - Sky: never touched.
- Fog: the ramp is picked from the fogged light, so far surfaces drift toward the ramp's middle colours and fog's own colour survives only as light colour. In heavy fog lower
shape, or limit the block with a depth mask. - Skinned characters: shaded every frame, so the ramp follows every pose; a coarse body shows its facets.
ToonMaterial.paint(heroId, { ramp = "sunset" })puts a character on the same ramp inside its own material, with its exact normals; keep this block off it with a group mask. - Foliage: each alpha-tested leaf is shaded on its own; normals rebuilt across a mass of leaves are noisy, so a canopy breaks into scattered ramp colours. Lower
shapeor keep foliage out with a group mask. - World text: a label is shaded like any surface and takes the ramp's colours: white words in shade turn the shadow colour. Leave labels out by name:
StyleKit.options({ exclude = { "labelName" } }). - Black stays black: no light stays no light (the ramp only colours light that arrived) and it returns through
sk_finish, so with every light off the frame is black whateverrampDarkis.
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.