# toonBlocks
Give your game a cel-shaded toon look by stacking blocks. Light blocks decide how surfaces take light: hard bands in any number, a colour ramp the shade picks its colour from (thirteen ramps to switch between with one change), soft half-Lambert wrap light that keeps shapes readable in shadow, a rim light round silhouettes and a hard stylized highlight. Fill blocks lay areas of colour flat with a chosen shadow colour, plain, hue-shifted or as two-tone poster paint. Line blocks draw a toon ink line round every object on the engine's own outline effect: depth correct (a wall or floor in front hides it), antialiased at full resolution, and the same cost for ten things or ten thousand, with an inverted hull on skinned characters so they get lines inside their silhouette too. Thirteen ink styles share one set of settings and are picked by one name: thin ink, fine pen, bold comic, brush-weighted, coloured from the object, tinted, soft grey pencil, white chalk for dark scenes, characters only, heavy poster contour, a white or black sticker border and one that thins with distance; per material, per object, or a style of its own on one object. The same toon light also goes inside chosen materials (a hero, a material collection). Seven whole looks apply in one change and then let you change any one part.
**Get started in three steps:**
1. On ZeroMind, search "toonBlocks" and install it into your world. It brings styleKit and every other package it needs.
2. Apply a whole toon look in one change: `require("~styleKit.StyleKit").applyLook("comicInkCel")` (or `saturdayMorning`, `softAnime`, `clearLine`, `thickSticker`, `ninetiesCG`, `pencilAnime`).
3. Change any one part of it in one change: `require("~styleKit.StyleKit").swap("light", "toonRamp")` (light, fill or line), and `StyleKit.clear()` gives the frame back exactly as rendered.
Every block is a styleKit block, so it stacks with inkBlocks, paperBlocks and watercolorBlocks, swaps for any other block in its slot with one change, and comes off leaving the frame exactly as it was.
Version 1.4.3. Pins styleKit 1.7.8 (style channels: one look, and players, enemies and pickups read apart under it) and is built on what styleKit 1.2.4 added (the scene's sun, swap memory, the drawn-ink tag that keeps outline ink out of every block's way).
## Install and use
Install **toonBlocks** from ZeroMind (search "toonBlocks" or "cel shading for my game"). It brings, whole, every package it lists as a dependency: **styleKit** (the look stack), **starterBlocks** (styleKit's simple blocks, `lightBands` among them), **lookbookKit** with its Lookbook scene (the test suite measures at the Lookbook's every-light-off moment) and **toonMaterials** with **materialLibraryKit** (the outline runtime asks toonMaterials whether an object already carries its own ink, so nothing is outlined twice). Checked from ZeroMind in brand new private worlds, release by release. 1.0.7: 1,474 files in about 2 s, every package above among them, the Lookbook scene included; the example below ran line by line exactly as written (the look applied with its 5 entries and 7 outline shells; every swap and `setRamp` answered `true`; the outline came back at the width it had, 2.2; `clear()` left the stack empty and the frame at exactly its unstyled brightness, 196.64 before and after); the test suite passed 10 of 10; and the example guide's outline lines, which name objects (`"showcaseCharacter"`, `"Star1"`), ran as written. 1.0.9: the suite passed 10 of 10 under a fresh world's default light and left the installed Lookbook exactly as it came. 1.1.1: 1,474 files in 13.9 s; the example below word for word (5 entries, 7 shells, every swap and `setRamp` `true`, the outline back at 2.2, the frame at 197.45 before and after `clear()`); the suite 11 of 11, twice. 1.1.2: 1,458 files in 29 s; the example below word for word (5 entries, 7 shells, every swap and `setRamp` `true`, the outline back at 2.2, the frame at 198.06 before and after `clear()`, 0 entries left); the suite 11 of 12: its close-up figure check failed on `toonRamp` (3 lone specks), which 1.1.3 fixes (see its entry). 1.1.3's own check from ZeroMind in a brand new world (the example below word for word, the suite twice) is recorded in the Style Cookbook world's NOTES.md, since a release cannot record its own install. Installs with several dependencies can take a while (#21420).
Then, in a fresh world with only toonBlocks installed, from the console or any script:
```luau
local StyleKit = require("~styleKit.StyleKit")
local ToonBlocks = require("~toonBlocks.ToonBlocks")
StyleKit.applyLook("comicInkCel") -- bands, rim, highlight, flat cel colour and an ink outline
StyleKit.swap("light", "toonRamp") -- ramp light instead of bands: one change
ToonBlocks.setRamp("sunset") -- the whole look at sunset: one change
StyleKit.swap("line", "toonComicLine") -- a bold comic ink line: one name
StyleKit.swap("line", "depthLine") -- styleKit's depth line instead of the toon ink
StyleKit.swap("line", "toonOutline") -- the toon ink back, with the width it had
StyleKit.clear() -- the frame exactly as rendered again
```
The stack lives on the scene's synced StyleStack, so every player sees the same look and the same outline widths, and it is saved with the scene. `StyleKit.blocks({ package = "toonBlocks" })` lists the blocks, `ToonBlocks.ramps()` the ramps, `StyleKit.looks()` the looks; in the shell, `zero styleKit list light` and `zero styleKit list --tag toon`.
## The blocks
| Block | Slot | What it does | Main settings (default) |
|---|---|---|---|
| `toonBands` | Light | The light on every surface cut into flat bands with tinted shadows and clean edges; `keepShade` can lift the shade so shaded surfaces keep their own colour | `bands` 3, `shadowLift` 0.65, `keepShade` 0 (off), `shadowTint`, `bias` 0.05, `softness` 0.015 |
| `toonRamp` | Light | The shade picks its colour from a five-stop ramp, blended or stepped | `rampDark` to `rampHigh`, `shadowAt` / `midAt` / `lightAt`, `hard` 0.75 |
| `toonWrap` | Light | Soft half-Lambert wrap light: darks lifted, form kept readable in shade | `wrap` 0.8, `wrapPower` 2, `shadowShape` 0.6, `bands` 0 (smooth) |
| `toonRim` | Light (chain) | A hard band of light round silhouettes, found from depth | `width` 4 px, `strength` 0.7, `side` 0, `fresnel` 0.5 |
| `toonHighlight` | Light (chain) | A hard-edged cut-out glint on the round parts and bevelled edges of sunlit things, on the side facing the viewer | `size` 0.55, `fromView` 0.5, `softness` 0.03, `strength` 0.85, `curvedOnly` 1, `curveReach` 5 |
| `celFill` | Fill | Each area of colour laid flat, light split into a lit tone and a chosen shadow colour | `flatten` 0.85, `shadowColour`, `shadowLevel` 0.6, `threshold` 0.42, `keepLight` 0 |
| `celHueShift` | Fill | The cel fill with shadows turned cooler and more saturated, lights a touch warmer | `hueShift` 0.07, `shadowSaturation` 1.3 |
| `celPoster` | Fill | Two-tone poster paint: flat colours cut into a few values, one hard shadow | `posterLevels` 3, `saturation` 1.3 |
| `toonOutline` | Line | A thin even ink line round every object | `width` 2.5 px, `units` 0 (screen) |
| `toonSticker` | Line | A thick white die-cut border with a thin dark edge | `width` 6 px white, `outerWidth` 1.5 dark |
| `toonStickerBlack` | Line | A thick black border | `width` 6 px black |
| `toonTintLine` | Line | A line in each object's own colour, darkened | `width` 1.6 px, `tint` 1, `tintDarken` 0.5 |
| `toonFarLine` | Line | A line that thins with distance | `width` 3.5 px, `fadeStart` 6 m, `fadeEnd` 60 m, `minWidth` 0.7 |
| `toonPenLine` | Line | A fine, even pen line | `width` 1.2 px |
| `toonComicLine` | Line | A bold comic line, thinning far away, a little brush weight | `width` 3.5 px, `brush` 0.25, `fadeStart` 25 m, `fadeEnd` 120 m, `minWidth` 1.5 |
| `toonBrushLine` | Line | A brush-weighted line: broad across the stroke, thin along it | `width` 3 px, `brush` 0.8, `brushAngle` 35 |
| `toonColourLine` | Line | A dark shade of each object's own colour, read at its edge | `width` 2 px, `tint` 1, `tintDarken` 0.5 |
| `toonPencilLine` | Line | A soft grey pencil line | `colour` #4a4a52, `width` 1.6 px, `softness` 0.8, `opacity` 0.75 |
| `toonChalkLine` | Line | A white chalk line for dark scenes | `colour` #f2efe6, `width` 2.4 px, `softness` 0.5, `opacity` 0.9 |
| `toonCharacterLine` | Line | A line on characters (skinned models) only | `width` 3 px, `targets` 1 |
| `toonPosterLine` | Line | A heavy poster contour | `width` 7 px, `minWidth` 3 |
The light blocks share `fullLight`, `keepLightColour` and (bands, ramp, wrap) `smoothLight`; bands, ramp and the fills share `shape`, `shadeLevel` and `castBelow`. The three fills share one set of settings, and so do the thirteen line blocks, so `StyleKit.swap(entry, id, { keepSettings = true })` carries tuning from one to the next. Every setting has a doc string: `StyleKit.settingsOf("toonBands")`.
### How the light is found
A full-frame block sees the finished frame, not the lights. Each light block divides the frame by the surface's base colour (both as the display shows them, so a sunlit surface always ranks above its own cast shadow) to get the light the scene sent, smooths away normal-map and occlusion grain on the same surface (`smoothLight`, a dense 8 x 8 pixel mean), and then redraws a clean toon light from the scene's sun, mixed in by `shape`: `shadeLevel` where a surface turns from the sun or the light that arrived says a cast shadow covers it, climbing to full where a surface faces the sun squarely, with open ground in sun three quarters of the way up. `toonBands` cuts its bands across that climb, so shade is always the darkest band, a round object passes through every band, and more bands step sunlit ground and walls too. So cast shadows stay where the scene put them, lamps and coloured light still count, and the bands follow shapes instead of texture. With no sun in the scene, `shape` changes nothing and the light is cut as it was rendered. The normal the light is drawn from is each surface's own shading normal (from the deferred renderer's copy), averaged over a dense 8 x 8 pixel square so a low-polygon round shape turns smoothly; on the forward path it is rebuilt from world positions four pixels apart.
### How starterBlocks' stepped light relates
starterBlocks' `lightBands` (Stepped light) is the simple version: one shader steps brightness over base colour into bands. It is cheap and stays a fine choice for a quick look. `toonBands` sits in the same Light slot and swaps with it in one change (`StyleKit.swap("light", "lightBands")`); it goes further where `lightBands` stops: tinted shadows, a band bias, anti-aliased edges, light read in display values so sun and shadow rank correctly, grain smoothed away, clean bands from the sun's direction with cast shadows kept, and a family around it (ramp, wrap, rim, highlight, the `toonLit` material). Nothing in toonBlocks repeats `lightBands`; use one or the other in the Light slot.
## Ramps
Thirteen ramps ship as `toonRamp` assets: `classicCel`, `warmCool`, `sunset`, `pastelAnime`, `comicTwoTone`, `noir`, `candy`, `toxicSciFi`, `autumn`, `moonlight`, `storybook`, `plasticCG` and `goldenHour`. A ramp is five colours of light (dark, shadow, mid, light, high) and where they sit; each multiplies the surface's own colour, so objects keep their colours and only their light and shadow change.
```luau
ToonBlocks.setRamp("moonlight") -- every toonRamp entry and every toon material, for every player
print(ToonBlocks.currentRamp()) -- "moonlight"
for _, r in ToonBlocks.ramps() do print(r.id, r.summary) end
```
Make your own with a folder `myRamp.toonRamp/` holding `ramp.yaml` (see the `toonRamp` type's README), a README and `.metadata`; it is listed as soon as it lands.
## Outlines
Since 1.2.0 the line blocks draw a toon ink line on the engine's own outline effect (its jump-flood seed and flood passes) with toonBlocks' own composite (`toonInkLine`) on top. Everything plain gets one shared line grown from the depth edges of the frame: wherever a surface stands a step in front of what is beside it, the line is drawn outside that silhouette, over what stands behind, so a wall or floor in front of an object hides its line, and nothing per object is kept or worked out. Skinned characters keep an inverted hull on their own skeleton, which bends with every pose and also draws the lines inside the body. Objects with ink of their own (an override, a per-object style, a masked group, toonMaterials' own ink) are drawn as small groups of their own.
- **Ink styles by name**: `StyleKit.swap("line", "toonPencilLine")`; all thirteen line blocks share their settings, so a style is a name and a set of defaults. The settings added in 1.2.0: `targets` (0 everything, 1 characters only, 2 everything but characters), `brush` and `brushAngle` (weight by direction), `softness` and `opacity`.
- **Width in screen units** (`units = 0`, the default): `width` in reference pixels (1080p). The push happens after the camera projection, so the line is that many pixels wide near, mid and far, on any screen size, and on animated characters. `toonFarLine` thins it from `fadeStart` to `fadeEnd` metres down to `minWidth`.
- **Width in world units** (`units = 1`): `width` in centimetres of real thickness, thinner with distance like any edge, never below `minWidth` pixels.
- **For one object** (the entity, its id or its name): `ToonBlocks.setObjectOutline(hero, { width = 5, colour = "#2a1030" })`, `ToonBlocks.setObjectOutline("Hero", { style = "toonChalkLine" })` (a style of its own), `false` for none, `nil` to follow the stack again (a synced `ToonOutline` component, saved with the scene; children follow their parent).
- **For one material**: `ToonBlocks.setMaterialOutline("toonBrick", { width = 4 })` gives every object wearing that material its own outline; `{ enabled = false }` leaves them without (a synced `ToonOutlineRules` entity).
- **Swapping**: the outline is an ordinary Line entry, so `StyleKit.swap("line", "inkPenLine")`, `"depthLine"` or `"sketchLine"` replaces it in one change and its line goes with it; swapping back puts back its settings.
- **No double ink**: objects that already carry their own ink (toonMaterials' `ToonInk` or a `ToonProp` with its outline on) are left to it while `skipOwnInk` is 1.
- **Strength and masks**: the entry's strength scales the width; its mask picks the objects (a group, a sphere by object position, or a depth band cut per pixel, inverted or not); the stack's left-out objects get none.
- **The ink stays ink**: the line marks its pixels in styleKit's drawn-ink mask (styleKit 1.4.23; character hulls tag theirs as before), so the light and fill blocks, and every other package's blocks, leave the line exactly as drawn: a white sticker border stays white.
- **What it costs to run** (1.2.1, measured): on one shared line the whole look takes about 0.3 ms a frame on the median frame (the outline about 0.06 to 0.1 ms of it) with 2,500 things, moving or still, and the number of things does not change it; each per-object ink style adds about 0.05 ms a frame, so the Ink Showcase's eight styles side by side cost about 0.7 to 0.8 ms (outline 0.4 to 0.5). Per-material rules and sphere masks bring back per-object work. "How to keep a toon look fast in a big game" has the table and how to measure your own level.
- **The line is tidied where a figure overlaps itself** (1.1.2): where one part of a figure lies over another (a waist plate over the hips, a panel on a shin) the shell's back meets the body behind it at almost the same depth, so the body hides most of it and the line comes out one pixel thin, in dashes, with single ink dots between. The outline entry's own pass reads the drawn-ink tag and tidies the line it finds: ink joined to nothing beyond a 9 x 9 square (a dot or a short dash) takes the paint round it, a one pixel thin stretch of line gets a second pixel below or right of it, a pinhole of paint inside the line is filled, and a one pixel sliver of paint caught against the line (a band or rim the ink covers most of) takes the middle of the paint round it. Lines, however thin or far, and a band or rim wider than a pixel keep their place. On the low tier and the forward path, which keep no base colour copy, the pass leaves the frame as it is.
## Toon light inside materials
```luau
local ToonMaterial = require("~toonBlocks.ToonMaterial")
ToonMaterial.paint(heroId) -- the stack's own toon light, inside the hero's materials
ToonMaterial.paint(heroId, { mode = "ramp", ramp = "sunset" })
ToonMaterial.fromMaterials("/zero/source/masonryMaterials.package/sets") -- toon copies of a whole set
ToonMaterial.unpaint(heroId, { removeFiles = true }) -- the originals back, the files gone
```
`paint` gives every Model and SkinnedModel under an object a derived `toonLit` material that keeps its base colour and texture and takes the toon light (bands, ramp or wrap, with rim and highlight) from the stack or from `opts`. It is lit by the scene's sun with its shadows, its ambient and every lamp, banded the same way as the full-frame blocks (both use the `toonLight` shader module). Originals are recorded on a synced `ToonSurface` component, so every player sees the same, and `unpaint` puts them back. To keep the full-frame light off a painted hero, put the hero in a mask group and give the light entry `mask = { kind = "group", group = 1, invert = true }`.
## Whole looks
| Look | Blocks |
|---|---|
| `saturdayMorning` (Saturday-morning cartoon) | `toonBands` 2 bands, `celFill` saturated, `toonOutline` 3.5 px |
| `comicInkCel` (Comic ink cel) | `toonBands`, `toonRim`, `toonHighlight`, `celFill`, `toonOutline` |
| `softAnime` (Soft anime) | `toonRamp` pastel, `toonRim` back light, `celHueShift`, `toonTintLine` |
| `clearLine` (Clear line) | `celFill` light two-tone, `toonOutline` 1.4 px even |
| `thickSticker` (Thick sticker) | `celPoster`, `toonSticker` |
| `ninetiesCG` (Nineties CG TV) | `toonRamp` plastic, `toonHighlight` hard |
| `pencilAnime` (Pencil anime) | `toonRamp` pastel, `celHueShift`, styleKit's `sketchLine` |
`StyleKit.applyLook("softAnime")` puts a whole look on; then change one part: `StyleKit.set("line", { width = 2.5 })`, `StyleKit.swap("light", "toonBands")`, `ToonBlocks.setRamp("candy")`.
## Mixing with ink and paper
A flat toon fill on brown kraft paper with an ink outline (needs paperBlocks):
```luau
StyleKit.load({
{ id = "fill", block = "celFill" },
{ id = "line", block = "toonOutline", settings = { width = 2 } },
{ id = "paper", block = "paperKraft" },
})
```
Soft anime ramp light with pencil lines instead of ink: `StyleKit.applyLook("softAnime")` then `StyleKit.swap("line", "sketchLine")`, or `StyleKit.applyLook("pencilAnime")`. With inkBlocks, `StyleKit.swap("line", "inkBrushLine")` puts a brush line on the cel look. The guides "toon light with ink lines and paper" and "how to make a cel-shaded look for my game" walk through more.
## Quality
`StyleKit.setQuality("low")` really changes the cost: `toonBands` reads the light unsmoothed (`smoothLight` 0), the light smoothing and the averaged normal read a 4 x 4 pixel square instead of 8 x 8, the cel fill's colour gathering takes 4 taps a ring instead of 8, the rim reads a 2 x 2 grid of depth instead of 4 x 4, the fill gathers over a smaller radius, and outlines are drawn only within `lowDistance` (45 m) of the camera. The Lookbook numbers below give the cost per pass on both tiers.
## Multiplayer
Everything that decides the look is synced state: the stack's entries and settings, the ramps put on them, each object's `ToonOutline`, the `ToonOutlineRules` entity and each painted object's `ToonSurface`. The line is drawn on every machine from its own frame and that synced state (character hulls are local and never saved), with widths in reference pixels of each player's own screen height, so every player sees the same look and the same outline widths. This engine checked one peer; two engines on one account collide as one player (#14448), so a two-player check needs two accounts.
## What is in the package
- `blocks/`: the 21 blocks, each with a picture (`preview.png`) of the same station in that block, and their 7 shaders (`toonBands`, `toonRamp`, `toonWrap`, `toonRim`, `toonHighlight`, `celFill`, `toonOutline`: the three fills share `celFill`'s and the thirteen line blocks `toonOutline`'s).
- `ramps/`: 13 `toonRamp` assets; `toonRamp.assetType`: the ramp type.
- `looks/`: 7 `styleLook` assets, each with a picture of the look.
- `shaders/`: `toonLight` (the shared light math), `toonFrame` (what a full-frame block reads), `toonHull` (the characters' hull material), `toonLit` (toon light in a material), and the ink line's `toonInkEdges`, `toonInkLine`, `toonInkSceneCopy` and `toonInkClear`.
- `ToonBlocks` (ramps, outlines per object and material), `ToonInkRuntime` (the ink line runtime; `ToonOutlines` is its old name and gives the same module), `OutlineBench` (a busy level and a per-frame meter), `ToonMaterial` (toon light in materials); components `ToonOutline`, `ToonOutlineRules`, `ToonSurface`.
- `guides/`: how to make a cel-shaded look for my game; tuning toon outlines and light for games; how to keep a toon look fast in a big game; toon light with ink lines and paper; example: a cartoon level with a cel-shaded look. `workflows/toonWorld.workflow`: give a game a cel-shaded look step by step, and undo it.
- `tests/toonBlocks.testSuite`.
## One object's own line: the style channel
The per-object outline is part of styleKit's style channel, the one setting every block reads, so a toon look and every other look treat a hero, an enemy or a coin by the same rule. An object's `StyleChannel` (or the game role it carries, read through the scene's role set from the styleRoles package) gives its toon ink:
- **line** as the ink's weight: the stack entry's width times it (2 draws a boss twice as heavy, 0 draws no line);
- **marks.line** as how much of the line reaches it (0 none, 0.5 a half-strength line);
- **ink** as its line colour (an enemy in dark red ink, the hero in deep navy);
- **value** as how much the line takes the object's own colour (a coin outlined in gold);
- **variant**: a toon Line entry naming a `variant` draws only on objects of it, and the entry naming none leaves those objects to it, so the player and the enemies can wear two different ink styles from one stack (`StyleKit.add("toonComicLine", { variant = "enemy" })`).
`ToonBlocks.setObjectOutline(entity, { weight = 2, colour = "#5a0010", tint = 0.4 })` writes those onto the object's channel; `false` lets no line through. The toon-only parts, an exact `width` with its `units` and an ink `style` of the object's own, stay on a `ToonOutline` component beside it and are laid over the channel field by field, so scenes made before 1.3.0 draw as they did. Characters keep their hulls, plain objects their screen-space rims; both read the channel. Every field is synced and saved with the scene.
## Known limits
Engine limits, numbered as in "How to keep a toon look fast in a big game" (details and numbers there), each with its tracked issue:
1. **A selection list costs every frame.** Tracked: #24548 (ZeroMind report `01M73CCJBX6411XN8R07AT2P53`).
2. **No per-object id in a shader.** Tracked: #24549 (ZeroMind report `01M73CCJCED5KSFGMZTFKXWXBM`).
3. **No change-only updates.** Tracked: #24450 (ZeroMind report `01M73CCJE1ZYVJJ600GTSP8DB4`).
4. **No "this material changed" signal.** Tracked: #24450 (ZeroMind report `01M73CCJESVR3B0B7DCRJ82TMD`).
5. **A screen pass sees the scene's depth only when it draws into the scene.** Tracked: #24550 (ZeroMind report `01M73CCJFMF1ZFQAJDE701QE7A`).
6. **The engine's outline composite (what the line can look like).** Tracked: #24449 (ZeroMind report `01M73CCJH4KMPNX8ACFFPC1PWS`).
7. **No crease lines.** Tracked: #24449 (ZeroMind report `01M73CCJHW548K2QP4PJC3B1A6`).
8. **`camera.viewData()` has no near and far planes.** Tracked: #24514 (ZeroMind report `01M73CCJK53V4RX4465BXDKJ0E`).
9. **Every pass is queued again every frame.** Tracked: #24548 (ZeroMind report `01M73CBNQWVMF5XWMD4KJAJ5MC`).
Every one of these now has a number in the engine team's tracker.
Limits of toonBlocks' own design, and other engine issues it works around:
10. **Glass gets no line**: see-through materials write no depth. By design; no engine issue.
11. **Per-material rules and sphere masks** bring back per-object work: objects are worked out a few a frame in a 0.4 ms budget while either is on the stack. By design; no engine issue.
12. **Why the hull is a copy and not a render pass**: a material drawn by a render feature's extra geometry pass is given the drawn object's own material in the vertex stage, so a hull drawn that way ignores its own width (toonMaterials' ink is a fixed 3 cm for that reason). toonBlocks draws its hulls in the normal draw path, where the width is exact. Tracked: #21428.
13. **Very thin or open meshes** (a plane, a single-sided leaf card) show no hull line: there is no back to push out. Foliage cards and particles are left to a depth line. By design; no engine issue.
14. **A hairline gap at a character's sharp creases at large widths**: skinned shells push along normals only. Flat-shaded characters wear a smoothed copy of their mesh (built once on every machine from the same bytes, corners that share a position share one averaged normal) so the shell does not fall into dashes; it is ready a moment after the shell appears. By design; no engine issue.
15. **Light from the frame**: a full-frame block reads light as frame over base colour; where the scene's lighting is very flat (strong ambient, a low sun) the clean sun light (`shape`) carries the look. Transparent things, the sky and the outline ink are left as rendered. By design; no engine issue.
16. **Post effects share no history and their stage order is not stated**: toonBlocks keeps no history of its own, so nothing depends on it. Tracked: #17427, #17426.
17. **One sun**: the look stack shades by the sun the renderer shades with (`lighting.sun()`), so a second directional light does not decide the toon light. By design (styleKit 1.4.22).
18. **A package's ZeroMind description can lag one release behind**, the web check is the person's to run and web frame rates differ. Tracked: #19258, #20946.
- **Other engine issues that apply here:** a per-object value cannot reach a geometry pass, so per-object looks go through styleKit's object mask (at most eight distinct settings) or need passes of their own (#24549); an unknown blend name draws as replace (#24551); a two-client editor sometimes refuses to load two different scenes at once (#24666, #24667); a world boot can wait about 30 s on a network handshake before content starts (#24669); installs with several dependencies are slow (#21420); two engines on one account collide as one player, so a two-player check needs two accounts (#14448).
## Removing it
`StyleKit.clear()` (or removing the toonBlocks entries) releases every shell and hull material; `ToonMaterial.unpaint(entity, { removeFiles = true })` puts painted materials back; `ToonBlocks.setObjectOutline(entity, nil)` and `ToonBlocks.setMaterialOutline(name, nil)` take the outline records away. The `toonWorld` workflow's last step does all of it.
## Lookbook numbers
Every block alone and every whole look, each measured twice on toonBlocks 1.1.2 on 2026-11-03 (09:52 to 10:28 UTC; `toonRim` again from 10:28 to 10:30, because its first run's view came out at 1922 x 1082), and `toonRamp` with the three looks built on it (Soft anime, Nineties CG, Pencil anime) measured twice again on 1.1.3 (11:59 to 12:08 UTC): their rows are 1.1.3's. Every run on the Lookbook's 26 second path, desktop GPU, styleKit 1.2.4, lookbookKit 1.0.14, the 3D view at exactly **1920 x 1080** (checked before every run), one discarded warm-up, no missed frames, both quality tiers, with exactly:
```luau
local Lookbook = require("~lookbookKit.Lookbook")
local r = Lookbook.measure({ stack = { { id = "light", block = "toonBands" } }, baseline = false })
print(r.stylized.all.warpedDiff, r.stylized.pan.warpedDiff, r.stylized.markStuck, r.stylized.zoomMarks.growth, r.passMs.high.total, r.passMs.low.total)
```
(a look's runs take its entries as `StyleKit.look(id).entries`). Every stack's two runs agree to 0.01 in the motion columns. The GPU columns did not repeat this time, and they are given as measured: the two runs of a stack differ by up to 1.26 ms on the high tier (Comic ink cel, 5.45 and 6.71) and 0.39 ms on the low (Pencil anime, 0.44 and 0.84), and blocks 1.1.2 did not change read higher than the same blocks did on this machine for 1.1.1 (`toonBands` 1.52 and 1.40 against 1.21, `toonWrap` 2.44 and 1.66 against 1.19). Read them as rough costs, not as a measurement that repeats. The four 1.1.3 stacks repeat to within 0.08 ms. The unstyled path reads 2.30 (warped difference, whole path), 6.57 (pan), 0.00 (marks), -0.53 (screen-stuck) and 7.88 (mark growth). How to read the columns is in paperBlocks' and lookbookKit's READMEs: warped difference is how much the picture swims once the camera's motion is taken out (lower is steadier), marks on things is the shower-door score (negative: the stack's marks stay on surfaces when the camera pans; positive: they stay on the screen), mark growth is how marks scale over a 10x zoom (about 1 keeps their size in the picture, about 10 grows with the things they sit on). The GPU columns are the style passes alone at the pan; the last column is how many outline shells were drawn.
| Stack | Run | Warped difference, whole path | Warped difference, pan | Marks on things | Screen-stuck in the pan | Mark growth over the 10x zoom | GPU ms high | GPU ms low | Outline shells |
|---|---|---|---|---|---|---|---|---|---|
| `toonBands` | 1 | 1.54 | 3.54 | +0.91 | -0.51 | 1.16 | 1.52 | 0.13 | 0 |
| `toonBands` | 2 | 1.54 | 3.54 | +0.91 | -0.51 | 1.16 | 1.40 | 0.11 | 0 |
| `toonRamp` | 1 | 1.64 | 3.92 | +0.90 | -0.51 | 1.11 | 1.21 | 0.14 | 0 |
| `toonRamp` | 2 | 1.64 | 3.92 | +0.90 | -0.51 | 1.11 | 1.21 | 0.14 | 0 |
| `toonWrap` | 1 | 2.28 | 6.20 | +0.36 | -0.52 | 1.00 | 2.44 | 0.29 | 0 |
| `toonWrap` | 2 | 2.27 | 6.20 | +0.36 | -0.52 | 1.00 | 1.66 | 0.26 | 0 |
| `toonRim` | 1 | 2.35 | 6.57 | +0.00 | -0.53 | 7.88 | 0.69 | 0.11 | 0 |
| `toonRim` | 2 | 2.35 | 6.57 | +0.00 | -0.53 | 7.88 | 0.70 | 0.17 | 0 |
| `toonHighlight` | 1 | 2.34 | 6.57 | +0.01 | -0.53 | 7.88 | 1.25 | 0.21 | 0 |
| `toonHighlight` | 2 | 2.34 | 6.57 | +0.01 | -0.53 | 7.88 | 1.29 | 0.23 | 0 |
| `celFill` | 1 | 1.38 | 2.55 | +0.83 | -0.53 | 2.27 | 2.48 | 0.52 | 0 |
| `celFill` | 2 | 1.38 | 2.55 | +0.83 | -0.53 | 2.27 | 2.86 | 0.43 | 0 |
| `celHueShift` | 1 | 1.38 | 2.58 | +0.83 | -0.53 | 2.21 | 3.23 | 0.49 | 0 |
| `celHueShift` | 2 | 1.38 | 2.58 | +0.83 | -0.53 | 2.21 | 2.68 | 0.26 | 0 |
| `celPoster` | 1 | 1.71 | 1.98 | +0.14 | -0.37 | 1.85 | 2.61 | 0.38 | 0 |
| `celPoster` | 2 | 1.71 | 1.98 | +0.14 | -0.37 | 1.85 | 2.78 | 0.40 | 0 |
| `toonOutline` | 1 | 2.43 | 6.57 | +0.00 | -0.53 | 7.88 | 0.35 | 0.10 | 7 |
| `toonOutline` | 2 | 2.43 | 6.57 | +0.00 | -0.53 | 7.88 | 0.20 | 0.08 | 7 |
| `toonSticker` | 1 | 2.45 | 6.57 | +0.00 | -0.53 | 7.88 | 0.21 | 0.09 | 14 |
| `toonSticker` | 2 | 2.45 | 6.57 | +0.00 | -0.53 | 7.88 | 0.28 | 0.06 | 14 |
| `toonStickerBlack` | 1 | 2.40 | 6.57 | +0.00 | -0.53 | 7.88 | 0.31 | 0.09 | 7 |
| `toonStickerBlack` | 2 | 2.41 | 6.57 | +0.00 | -0.53 | 7.88 | 0.19 | 0.06 | 7 |
| `toonTintLine` | 1 | 2.42 | 6.57 | +0.00 | -0.53 | 7.88 | 0.21 | 0.06 | 7 |
| `toonTintLine` | 2 | 2.42 | 6.57 | +0.00 | -0.53 | 7.88 | 0.17 | 0.06 | 7 |
| `toonFarLine` | 1 | 2.42 | 6.57 | +0.00 | -0.53 | 7.88 | 0.35 | 0.10 | 7 |
| `toonFarLine` | 2 | 2.42 | 6.57 | +0.00 | -0.53 | 7.88 | 0.35 | 0.10 | 7 |
| look `saturdayMorning` | 1 | 1.37 | 2.23 | +0.79 | -0.54 | 3.07 | 4.34 | 0.79 | 7 |
| look `saturdayMorning` | 2 | 1.37 | 2.23 | +0.79 | -0.54 | 3.07 | 4.62 | 0.79 | 7 |
| look `comicInkCel` | 1 | 1.24 | 1.89 | +0.82 | -0.50 | 4.87 | 5.45 | 1.14 | 7 |
| look `comicInkCel` | 2 | 1.24 | 1.89 | +0.82 | -0.50 | 4.87 | 6.71 | 1.13 | 7 |
| look `softAnime` | 1 | 1.34 | 2.36 | +0.84 | -0.52 | 2.51 | 4.42 | 0.51 | 7 |
| look `softAnime` | 2 | 1.34 | 2.36 | +0.84 | -0.52 | 2.51 | 4.34 | 0.52 | 7 |
| look `clearLine` | 1 | 1.35 | 2.27 | +0.78 | -0.54 | 3.08 | 2.37 | 0.30 | 7 |
| look `clearLine` | 2 | 1.35 | 2.27 | +0.78 | -0.54 | 3.08 | 2.37 | 0.29 | 7 |
| look `thickSticker` | 1 | 1.87 | 1.98 | +0.14 | -0.37 | 1.85 | 2.52 | 0.38 | 14 |
| look `thickSticker` | 2 | 1.87 | 1.98 | +0.14 | -0.37 | 1.85 | 3.32 | 0.68 | 14 |
| look `ninetiesCG` | 1 | 1.77 | 4.04 | +0.88 | -0.50 | 1.35 | 3.78 | 0.26 | 0 |
| look `ninetiesCG` | 2 | 1.77 | 4.04 | +0.88 | -0.50 | 1.35 | 3.80 | 0.26 | 0 |
| look `pencilAnime` | 1 | 1.41 | 2.36 | +0.84 | -0.52 | 2.50 | 3.91 | 0.45 | 0 |
| look `pencilAnime` | 2 | 1.41 | 2.36 | +0.84 | -0.52 | 2.50 | 3.91 | 0.45 | 0 |
What they say:
- **The toon light does not swim.** Bands, ramp, wrap, rim and highlight swim no more than the unstyled path (1.54 to 2.35 against 2.30): bands 1.54 (pan 3.54), ramp 1.64 (pan 3.92), wrap 2.27 and 2.28, highlight 2.34, rim 2.35. The cel and hue-shift fills calm it most (1.38), because flat colour has less texture to move, and the poster fill too (1.71, pan 1.98). The highlight's glints sit where shapes bend and add nothing over unstyled in the pan (6.57, the same as unstyled).
- **The shower-door score is positive for the full-frame bands, ramp and fills (+0.83 to +0.91)**, as it is for paperBlocks' papers at this view size; wrap reads +0.36, rim and highlight about zero (+0.00, +0.01), the poster fill +0.14. The toon light is drawn from the scene's own light and the sun's direction on each surface, so band edges sit on the surfaces by construction; screen-stuck stays at -0.51 to -0.53 for every light block (unstyled -0.53), -0.37 for the poster fill. Read it the way paperBlocks' README says: check sliding by eye with a slow pan.
- **Mark growth near 1** for bands, ramp and wrap (1.00 to 1.16) and 1.85 to 2.27 for the fills means the measure finds little fine detail left to compare once surfaces are laid flat, not that something is glued to the screen. Rim and highlight leave most of the picture as it was and read like unstyled (7.88).
- **Outlines are geometry, so the Lookbook's mark measures cannot see them**: the shells are part of the frame the stack receives, which is what the measure compares the stack's output against, so marks and growth read exactly as unstyled (0.00, 7.88). A hull line hugs its object by construction and cannot slide. Since 1.1.2 the outline entry's own pass tidies the drawn line (see Outlines), which changes a few pixels along every line, so warped difference reads 2.40 to 2.45 against the unstyled 2.30, the same in the pan (6.57). That pass costs 0.17 to 0.35 ms high and 0.06 to 0.10 ms low (0.04 and 0.02 to 0.03 before it tidied anything); the shells are drawn in the scene's own geometry pass (one draw per opaque object, two for the sticker), 7 objects on the Lookbook stage, so their cost is the scene's draw cost for those meshes again, not in this column.
- **Cost at 1920 x 1080**, as measured this time (see above: these did not repeat closely). Bands 1.40 and 1.52 ms on the high tier, ramp 1.21 in both runs (1.1.3), wrap 1.66 and 2.44, the highlight 1.25 and 1.29, the rim 0.69 and 0.70 (a dense 4 x 4 grid of depth taps); a fill 2.48 to 3.23 ms (it gathers the area's colour over two rings of 8 taps and reads the light and the normal over dense squares). On the low tier the same blocks cost 0.11 to 0.52 ms: the low tier runs at half resolution with 4 x 4 squares, 4 taps a ring and a 2 x 2 rim grid, and `toonBands` skips its light smoothing (0.11 and 0.13 ms low). Whole looks: 2.37 to 6.71 ms high, 0.26 to 1.14 ms low.
- **Whole looks swim less than the unstyled path** (1.24 to 1.87 against 2.30): Comic ink cel 1.24, Soft anime 1.34, Clear line 1.35, Saturday morning 1.37, Pencil anime 1.41, Nineties CG 1.77 (pan 4.04: it has no fill to flatten its surfaces) and Thick sticker 1.87 (calm pan 1.98: the poster fill).
- **Black stays black.** At the Lookbook's every-light-off moment the frame stays at the unstyled frame's black under every block and look, within an allowance of 1.5 on 0..255: the outline ink is seen only where light reaches it. The test suite checks every block and look.
- **Web frame rate** has not been measured from here (#20946): run `zero lookbook report` in the web build.
The runs are in `design/lookbook/toon_runs.json` in the Style Cookbook world.
## Version history
**1.4.2 (2026-11-12)**: pins lookbookKit 1.0.52, starterBlocks 1.0.49, styleKit 1.7.8 (styleKit 1.7.8 logs no second refusal for the old roles field on a scene saved before styleKit 1.5). Nothing else changed.
**1.4.1 (2026-11-12)**: pins lookbookKit 1.0.51, starterBlocks 1.0.48, styleKit 1.7.7 (styleKit 1.7.7: a role set or look another player changes reaches everyone in the session). Nothing else changed.
**1.4.0 (2026-11-12)**: outlines close where things touch, hand-set inks read clearly, and the log stays quiet. Thick outlines on round things showed a gap where a ball met the ground or the box it rested on: the edge pass marks only depth steps, and where a thing rests on another the depth flows on with no step, and the line was drawn only over what stands a step behind. A new line setting, `closeContacts`, closes them: the edge pass then also marks a contact (a pixel lying deeper than the pixels two above and below it, with level surface to its left and right), and the line composite draws round a contact on the side below it, so the outline closes under every ball and under a ball on a box, without flecking a box's vertical edges. It is on by default for the thick lines, where the gap shows (the white and black sticker borders and the poster contour), and off for the thinner ones: on a character's creases it adds a few specks (the outline-alone fleck check read 0.13 percent of the figure with it on, against its 0.1 percent limit), and a thin line shows no gap to close. Set `closeContacts = 1` on any line block to turn it on. An ink set by hand on an object (its style channel's ink) is drawn as set: under the toon game role set a pickup's line is mostly the object's own colour (its value, 0.8), and a hand-set ink came out pale; it now takes none of the object's colour. Objects that went (a bench or test clearing up) no longer make the ink log an error about a missing entity every frame: ids the role reach or an exclusion still names after their object went are skipped. The Paper cutout game look moved to paperBlocks 1.2.0, rebuilt from non-toon blocks, so toonBlocks no longer brings paperBlocks. New test: a hand-set ink on a pickup reads clearly under the toon set. Pins styleKit 1.7.6, starterBlocks 1.0.47 and lookbookKit 1.0.50.
**1.3.13 (2026-11-12)**: pins lookbookKit 1.0.49, paperBlocks 1.1.32, starterBlocks 1.0.46, styleKit 1.7.5 (styleKit 1.7.5: its checks pass where styleKit is installed alone). Nothing else changed.
**1.3.12 (2026-11-12)**: pins lookbookKit 1.0.48, paperBlocks 1.1.31, starterBlocks 1.0.45, styleKit 1.7.4 (styleKit 1.7.4: installs on its own into an empty world again). Nothing else changed.
**1.3.11 (2026-11-12)**: pins lookbookKit 1.0.47, paperBlocks 1.1.30, starterBlocks 1.0.44, styleKit 1.7.3 (styleKit 1.7.3: a role reaches what a kit draws in an object's place (pickupsKit's coins), and looks installed after the first scan are found). Nothing else changed.
**1.3.10 (2026-11-12)**: ships the **Paper cutout game** look (`paperCutoutGame`: matte card surfaces, two flat light bands, flat colour, a white die-cut sticker border round every object, on kraft paper), which lived only in the Style Cookbook world's own folders. styleRoles' read-apart test measures it as its paper look, and in a world that installed the packages alone `applyLook("paperCutoutGame")` found nothing, so that step measured the look before it. It needs paperBlocks' kraft paper, so toonBlocks now brings paperBlocks 1.1.29 (paperBlocks needs only styleKit). Nothing else changed.
**1.3.9 (2026-11-12)**: things nobody gave a role keep the look's own line. Under Comic ink cel with the arena shooter set, untagged lamp posts were drawn in the hazard line's orange (and in enemy red once the hazard line was removed): the toon ink reads the stack's entries from `StyleKit.describe()`, which reported no entry's variant, so every variant line a role set adds was drawn on everything and the last one won. Fixed in styleKit 1.7.0, which this pins; styleRoles' suite checks it on the frame. Known limits no longer cite #20750, which is closed. Pins styleKit 1.7.0, starterBlocks 1.0.43 and lookbookKit 1.0.46.
**1.3.8 (2026-11-11)**: pins lookbookKit 1.0.45 (lookbookKit 1.0.45 brings its Lookbook scene with it when it is installed as another package's dependency, so the toonBlocks, inkBlocks and paperBlocks unlit-frame tests and `zero lookbook` run in an installed world). Nothing else changed.
**1.3.7 (2026-11-11)**: pins lookbookKit 1.0.44, starterBlocks 1.0.42, styleKit 1.6.5 (styleKit 1.6.5 draws a newly switched-on look's settled picture from its first frames instead of a lighter, half-set one for two to four seconds; lookbookKit 1.0.44 finds its Lookbook scene where it is installed). Nothing else changed.
**1.3.6 (2026-11-11)**: per-object ink lines that share a style (role inks and widths, tint aside) are drawn together: each line draws only its mask, then one region map (`toonInkMerge`), one jump flood that skips a pixel's own region (`toonInkSeedId`, `toonInkFloodId`) and one composite with a twelve-entry palette (`toonInkLineId`) draw them all, and the region map stands in for the shared line's veto when every vetoed thing is one of them. 600 role holders in nine inks queue 22 ink passes a frame instead of 104, and the toon ink's script time with them falls from about 0.6 to about 0.26 ms on the median frame. Touching objects of different lines still get a line between them; lines of different styles keep a chain each. Every README in the package (each block, look, shader and guide) now ends with a Known limits section naming the engine issues that apply there. It also carries what was prepared as 1.3.5: the toon ink line starts by itself. A new `toonBlocksStartup` asset type and the one asset of it the package ships (`ink.toonBlocksStartup`) load `ToonBlocks` on every machine when a world with the package loads, the way toonMaterials starts its own ink. It starts the ink at every registration, so an engine that switches from one world to another starts it again in the new one. Before, the ink runtime only started when some other code loaded `ToonBlocks`, so in a world that had installed toonBlocks and nothing else the toon look came up with its bands and fills and no line at all, and no role lines either. Found by installing the look into a new world as a stranger would. Pins lookbookKit 1.0.43, starterBlocks 1.0.41, styleKit 1.6.3.
**1.3.4 (2026-11-11)**: the ink line of things with a style channel or a role reads each thing's own colour on the GPU at its silhouette, the way the shared line already did, instead of mixing it in on the CPU. A line used to be split into one group per material colour in the level, so 600 role holders in many colours made 49 lines and 212 render passes a frame; they now make one line per role ink (9 lines, 104 passes). Toon ink script time with 600 roles in the 2,500-thing bench fell from about 1.0 ms a frame to about 0.6 ms (median). Lines look the same: the role's ink, mixed with the thing's colour by the style's `tint`.
**1.3.3 (2026-11-11)**: pins lookbookKit 1.0.42, starterBlocks 1.0.40, styleKit 1.6.2 (styleKit 1.6.2 finds the scene's stack again when the one it held was removed (after a play restart a look or role set change failed with "the component this proxy names was removed")). Nothing else changed.
**1.3.2 (2026-11-11)**: a style channel test on styleKit's ChannelProbe (line weight and marks reach the toon blocks on the presented frame); pins lookbookKit 1.0.41, starterBlocks 1.0.39, styleKit 1.6.1.
**1.3.1 (2026-11-11)**: pins lookbookKit 1.0.40, starterBlocks 1.0.38, styleKit 1.5.1 (styleKit 1.5.1 keeps the scene's role set working in an editor that had an older styleKit open). Nothing else changed.
**1.3.0 (2026-11-11)**: the per-object outline is now part of styleKit's style channel. The ink reads each object's `StyleChannel` (or its game role through the scene's role set): its line weight scales the entry's width, how much of the line reaches it scales the ink's opacity, its ink colour colours the line and its value tints it with the object's own colour; a toon Line entry with a `variant` draws only on objects of it and the entry with none leaves them to it. `ToonBlocks.setObjectOutline` writes weight, colour, tint and draw onto the channel and keeps an exact width, units and ink style on `ToonOutline`, which the runtime lays over the channel, so older scenes draw as before. Pins styleKit 1.5.0, starterBlocks 1.0.37, lookbookKit 1.0.39.
**1.2.1 (2026-11-11)**: every block and look has a picture (`preview.png`, 640 x 360): the same station (a skinned character, a hard-edged house, a crate, a ball) under the Comic ink cel look with that block in its slot, or under the whole look, so a style can be chosen by looking at it. A per-object ink style that was taken off (`ToonBlocks.clearObjectOutline`, or a `ToonOutline` removed) while the stack briefly had no toon line no longer leaves its old ink group behind: such groups used to keep drawing objects in an ink they no longer wore. The Ink Showcase holds still in the editor and moves only in play (it used to move every editor frame, and the editor saved each move as an edit). the look costs what the guide says, measured on the median frame. Measured with 2,500 things (250 moving, 25 a second spawned and despawned, 10 recoloured): on one shared line (Comic ink cel) the whole look takes 0.29 ms on the median frame, the outline 0.06 ms of it (average 0.41, outline 0.09), standing still 0.33 ms; in the Ink Showcase with eight ink styles side by side 0.78 ms (outline 0.47; was 0.92 and 0.57 on 1.2.0), standing still 0.72 ms (was 0.89). Taken off the every-frame path: the shader-reload counters (every 30 frames), the per-object override read when things come and go (only when they arrive under an override, at most once a second; it cost about 2 ms up to four times a second, and up to 11 ms in one frame), and the camera guard of character hulls (every frame only within 6 m of the camera). `OutlineBench.measure` reports the median frame (`p50`, `toonP50`, `styleP50`), and the busy-level test is judged on it, so a machine busy with other work no longer fails it. The engine limits in Known limits are numbered and each names its tracked issue (#24449, #24450 and ZeroMind reports). Pins styleKit 1.4.24, starterBlocks 1.0.36, lookbookKit 1.0.38.
**1.2.0 (2026-11-10)**: the toon ink line on the engine's own outline effect, eight new ink styles, and no per-object work. The line is now drawn by the engine's jump-flood outline (seed and flood) with toonBlocks' own composite on top: one shared line grown from the depth edges of the frame for everything plain, depth correct (a wall or floor in front hides it, a cart passing behind a low wall keeps its line above the wall and none on its face), antialiased at full resolution, with width from the silhouette's own distance, brush weight by direction, a soft edge, opacity, a colour read on the GPU from the object at its edge, and black ink when nothing gives light. Plain objects are no longer tracked at all: a thing added after the look is on is inked the frame it appears, a removed one loses it the frame it goes, and a new material, a hidden mesh or a swapped mesh changes the line the same frame. Skinned characters keep their hull (inner lines). Eight new line blocks, all on the same settings: `toonPenLine`, `toonComicLine`, `toonBrushLine`, `toonColourLine`, `toonPencilLine`, `toonChalkLine`, `toonCharacterLine`, `toonPosterLine`; new shared settings `targets`, `brush`, `brushAngle`, `softness`, `opacity` (defaults keep every existing block's look). Per-object ink styles: `ToonBlocks.setObjectOutline(obj, { style = "toonChalkLine" })` and a synced `style` field on `ToonOutline`. The runtime is `ToonInkRuntime`; `ToonOutlines` is kept as its old name and gives the same module. Measured on a 2,561-object busy bench (250 moving, 25 a second spawned and despawned, 10 recoloured), script time of the toon look a frame: 1.43 ms on 1.1.29 (outline 1.07, style stack 0.36), 0.73 ms on 1.2.0 (outline 0.21, style stack 0.52). The suite now checks the line on screen (arrival, glass, hidden, removal, a material change updating a coloured line, a thing behind a wall having no line) instead of counting shells. New guide: how to keep a toon look fast in a big game. Pins styleKit 1.4.23, starterBlocks 1.0.35, lookbookKit 1.0.37.
**1.1.29 (2026-11-09)**: the outline costs nothing it does not need. Summit Sprint, a public platformer on toonBlocks, stalled for 250 to 490 ms every few seconds: the outline runtime walked every object in the scene once a second (`entity.findAll` plus a component read on each, with the shells counted in) and then walked every target again. That is gone. The runtime reads the engine's entity and field revisions each frame and works only when one moves: arrivals are found in the engine's index of Model and SkinnedModel components (gated to once every 30 frames and a quarter of a second, and to about one percent of the time while things keep arriving), objects that leave take their shells with them, a new material, visibility or mesh on a standing object is read from the engine's own render components (`MaterialRef`, `MeshInstance`) in chunks inside a 0.15 ms budget, and every shell is worked out and made inside a per-frame budget (0.4 ms of a 60 fps frame, 2.5 percent of a slower one, at most 1.5 ms). A plain shell is now a bare child holding the engine's mesh and material components (0.06 ms to make instead of 0.8 ms with a Model component); skinned shells are as before. Measured with the new `OutlineBench` (3,000 objects under Comic ink cel, 300 moving every frame, 30 a second spawned and despawned, 10 a second recoloured): 1.1.28 averaged 19.4 ms of look-stack script a frame with frames up to 329 ms; 1.1.29 averaged 0.80 ms (toonBlocks 0.49, styleKit 0.31) with a worst frame of 5.5 ms and none over 33 ms. The suite gains two checks: objects that arrive, change material, are hidden and leave get and lose their outline, and the busy bench stays within the bar (as a share of the frame, so a slow host is held to the same 1 ms of a 60 fps frame). New: `ToonOutlines.shellsOf(entity)`, `ToonOutlines.costTotal()`, `status().queued` and `status().prof`. Also carries pull request #9 (ToonOutlines requires styleKit by name, `~styleKit.StyleKit`, so it works wherever an install puts styleKit). The toon light follows the sun the renderer shades with (styleKit 1.4.22), which ends the two-suns limit. Pins styleKit 1.4.22, starterBlocks 1.0.34, lookbookKit 1.0.36. The look is unchanged: the engine's own outline gained its depth test and antialiasing during this round (#19385, #17484), and drawing the toon ink through it is the next step (see Known limits).
**1.1.28 (2026-11-08)**: moves to the engine's current built-in library (@builtin e89b9db), whose update rewrote small reference files inside the package (a world on an older built-in library is hidden from players). Pins styleKit 1.4.21, starterBlocks 1.0.33, lookbookKit 1.0.35. The package description now says what it gives you and how to install and use it. Nothing else changed.
**1.1.27 (2026-11-08)**: moves to the engine's current built-in library (@builtin edb50c2), whose update rewrote small reference files inside the package (a world on an older built-in library is hidden from players). Pins styleKit 1.4.20, starterBlocks 1.0.32 and lookbookKit 1.0.34. Also includes 1.1.26 (pull request #8), released from main with this version.
**1.1.26 (2026-11-08)**: A character's outline shell now follows the character's render layers whenever they change, not only when the shell is made. A first-person body hidden from its own camera after its shell existed (through death, the respawn and re-equipping) kept a visible shell, and a dead player's fallen body, lying outside the camera guard's column, filled the view with dark shapes. Seen in Frag Arena.
**1.1.25 (2026-11-08)**: pins toonMaterials 1.0.11 (was 1.0.4), which is built on materialLibraryKit 1.4.3 and the current engine library, so an install no longer carries an older material library or copies of engine shader modules. Nothing else changed.
**1.1.24 (2026-11-08)**: Outlines never cover a first-person camera: a character's outline shell takes the character's render layers (a camera that hides its own body hides its outline too), and a shell whose character holds the camera is switched off until the camera is 1.6 m clear, so the inside of the shell no longer shows as a big dark shape across the screen. Rescans re-walk the targets only when the set changed, and each object's outline settings are cached (cleared when the style stack changes), which removes 50 to 180 ms stalls in scenes with a few hundred outlined objects.
**1.1.23 (2026-11-08)**: moves to the engine's current built-in library (@builtin f4425a5), whose update rewrote small reference files inside the package (a world on an older built-in library is hidden from players). Pins styleKit 1.4.19, starterBlocks 1.0.31 and lookbookKit 1.0.33. Nothing else changed.
**1.1.22 (2026-11-08)**: moves to the engine's current built-in library (@builtin f39f044), whose update rewrote small reference files inside the package (a world on an older built-in library is hidden from players). Pins styleKit 1.4.18, starterBlocks 1.0.30 and lookbookKit 1.0.32. Nothing else changed.
**1.1.21 (2026-11-08)**: pins styleKit 1.4.15, starterBlocks 1.0.29 and lookbookKit 1.0.31. Nothing else changed.
**1.1.20 (2026-11-08)**: pins styleKit 1.4.14 (a look drawn again after a clear lands in the right place), starterBlocks 1.0.28 and lookbookKit 1.0.30. Nothing else changed.
**1.1.19 (2026-11-08)**: pins styleKit 1.4.13, starterBlocks 1.0.27 and lookbookKit 1.0.29. Nothing else changed.
**1.1.18 (2026-11-08)**: moves to the engine's current built-in library (@builtin f110cb3), whose update rewrote small reference files inside the package. Pins styleKit 1.4.12, starterBlocks 1.0.26, lookbookKit 1.0.28. Nothing else changed.
**1.1.17 (2026-11-08)**: moves to the engine's current built-in library (@builtin a29b227), whose update rewrote small reference files inside the package. Pins styleKit 1.4.11, starterBlocks 1.0.25, lookbookKit 1.0.27. Nothing else changed.
**1.1.16 (2026-11-08)**: moves to the engine's current built-in library (@builtin c61f473), whose update rewrote small reference files inside the package. Pins styleKit 1.4.10, starterBlocks 1.0.24, lookbookKit 1.0.26. Nothing else changed.
**1.1.15 (2026-11-07)**: moves to the engine's current built-in library (@builtin 7ca1f19), whose update rewrote small reference files inside the package. Pins styleKit 1.4.8, starterBlocks 1.0.23, lookbookKit 1.0.25. Nothing else changed.
**1.1.14 (2026-11-07)**: moves to the engine's current built-in library (@builtin fdc9a99), whose update rewrote small reference files inside the package. Pins styleKit 1.4.7, starterBlocks 1.0.22, lookbookKit 1.0.24. Nothing else changed.
**1.1.13 (2026-11-07)**: moves to the engine's current built-in library (@builtin 7e13a48), whose update rewrote small reference files inside the package. Pins styleKit 1.4.6, starterBlocks 1.0.21, lookbookKit 1.0.23. Nothing else changed.
**1.1.12 (2026-11-07)**: moves to the engine's current built-in library (@builtin 2809239), whose update rewrote small reference files inside the package. Pins lookbookKit 1.0.22, starterBlocks 1.0.20, styleKit 1.4.5. Nothing else changed.
**1.1.11 (2026-11-07)**: pins lookbookKit 1.0.21, whose marks score reads the stack's marks again (see its history). No block, look or shader changed.
**1.1.10 (2026-11-07)**: moves to the engine's current built-in library (@builtin 278f02f), whose update rewrote small reference files inside the package. No block, look or shader changed. Pins lookbookKit 1.0.20, starterBlocks 1.0.19, styleKit 1.4.4.
**1.1.9 (2026-11-07)**: moves to the engine's current built-in library (@builtin 6656162), whose update rewrote small reference files inside the package. No block, look or shader changed. Pins lookbookKit 1.0.19, starterBlocks 1.0.18, styleKit 1.4.3.
**1.1.8 (2026-11-07)**: moves to the engine's current built-in library (@builtin 808b4a1), whose update rewrote small reference files inside the package. Pins lookbookKit 1.0.18, starterBlocks 1.0.17, styleKit 1.4.2. No block, look or shader changed.
**1.1.7 (2026-11-07)**: moves its pins to styleKit 1.4.1, starterBlocks 1.0.16 and lookbookKit 1.0.17; no block changed.
**1.1.6 (2026-11-07)**: moves its styleKit pin to 1.4.0; no block changed.
**1.1.5 (2026-11-03)**: depends on styleKit 1.3.0, starterBlocks 1.0.14 and lookbookKit 1.0.15; no change to the blocks.
**1.1.4 (2026-11-03)**: documentation only. The README opens with three steps to install and use the package (search "toonBlocks" on ZeroMind and install it, `StyleKit.applyLook`, `StyleKit.swap`), checked as written in the Style Cookbook (the look applied with 5 entries, the light swapped to `toonRamp`, the stack empty after `clear()`). No block, shader, look or test changed from 1.1.3, and its numbers below stand for this release.
**1.1.3 (2026-11-03)**: `toonRamp` no longer lights stray dots in a figure's flat shade, at the cost it had before; the close-up figure check runs at a fixed view size and judges only what repeats.
- **What was wrong.** 1.1.2's own check from ZeroMind, in a brand new world, failed the close-up figure check: `toonRamp` left 3 lone specks on the figure, single pixels of 158 to 177 in shade that was 102 all round, so the suite passed 11 of 12 there (12 of 12 in the Style Cookbook). Probed pixel by pixel on the suite's figure: there the unstyled frame and `toonBands` are one flat tone, and the specks go away with `rampMid` set to the shadow colour or with `shape` 0, so the ramp's clean sun light was lifting single pixels to its mid stop. Two things together did it. The step from the shadow stop to the next lay only about 0.08 of the way from shade to full sun (`toonBands`' first band edge lies at 0.38), inside the faint sun a surface facing the sun keeps inside a cast shadow. And the light read there is uneven from pixel to pixel: the pixel's own share of the light, which decides how much sun gets into a cast shadow, and hairline seams one pixel wide where two parts of the figure meet, along which the averaged normal turns toward the sun.
- **The fix**, in three parts, each tried alone first (on the suite's close figure: the step moved alone left 1 lone speck, either filter alone 3, the two filters together 4, all three 0). The shade holds the shadow stop up to where its step lands on `toonBands`' first band edge at its defaults, worked out from the ramp's own `shadowAt`, `midAt` and `shadeLevel`, and the stops above spread over the rest. While `shape` redraws the light, the ramp reads it fully smoothed (`smoothLight` now matters to it only with `shape` 0). And on the high tier, near that step, each pixel takes the lower of the middle of its row of three and the middle of its column of three, which drops a one pixel hairline or a lone pixel and leaves every edge where it is. The low tier is as before.
- **What did not ship.** A first 1.1.3 that held only the first quarter of the span as shade was prepared and never published. The Style Cookbook's NOTES.md recorded counts for it (140 specks, 1 lone, 14 where `toonBands` is flat) that were taken while the look stack was shading by a second sun (below); they do not stand.
- **The close-up check**, run twice in the Style Cookbook on the released code, both runs giving the same numbers: `toonRamp` 0.04 percent of the figure, 0 lone; `toonBands` with `keepShade` 0 0.10 percent, 3 lone; the outline alone 0.06; Comic ink cel 0.19, 2 lone (0.14 away from its line).
- **From the editor camera** (as in 1.1.2, with the world clock's sun switched off for the shots, below), two sets at 1920 x 1080 and two at the editor's own 2097 x 1409 view, with `toonBands` and `keepShade` 0 in the same shots. At 1920 x 1080: `toonRamp` 112 specks (2 lone) and 130 (0), `toonBands` 215 (14) and 209 (6). At 2097 x 1409: `toonRamp` 196 (1 lone) and 178 (2), `toonBands` 338 (2) and 320 (1). Where `toonBands` is one flat tone, `toonRamp` has 12, 24, 26 and 45 specks; it draws four colour steps where three bands draw two edges. The published 1.1.2, counted the same way in the same session: 187 (1 lone) and 205 (2) at 1920 x 1080, 142 (2) and 131 (5) at 2097 x 1409. The two sets of each size do not repeat exactly: the figure's own pixel count changed between them (56,245 and 56,495 at 1920 x 1080), so it does not stand exactly still, and a few lone specks move from shot to shot. Over the four shots `toonRamp` had 5 lone specks against `toonBands`' 23; in one of them it had one more than `toonBands` (2 against 1).
- **Why the clock's sun was off.** styleKit gives every block the first directional light the lighting toolbox lists, by entity id. The showcase stage has two, its own sun and the world clock's, which lights nothing there; each time the clock's sun is made again it takes a new id, and when that id sorts first the toon blocks shade by its direction. So the same code counts very differently from one session to the next (1.1.2's ramp from this camera: 72 specks with 0 lone in one session, 187 and 205 with 1 and 2 in another), which is the likely reason counts taken at another time differ from these. This is styleKit's, not toonBlocks', and is left as it is (see Known limits).
- **The close-up check counts at a fixed size and judges only what repeats.** It sets the 3D view to 1920 x 1080 while it runs (its counts are pixel shares and the line is drawn in 1080p pixels: at a 3200 x 1756 view the outline alone read 0.11 percent and failed) and gives the view back afterwards. It no longer judges Comic ink cel's specks away from its line against `toonBands`' own plus 0.1 percent: `toonBands`' count there moved between 0.02 and 0.10 percent from run to run while Comic ink cel's stayed at 0.14 to 0.15 (its rim and glint edges), so that margin failed by chance once on this code. It judges the outline alone and lone specks: `toonRamp` may have at most 1, Comic ink cel no more than `toonBands` with `keepShade` 0 has or 2, whichever is more. (Comparing with `toonBands`' count exactly, as 1.1.2 did, failed by chance: `toonBands`' own lone count moved between 0 and 3 from run to run, and one full run on this code failed on Comic ink cel's 1 against its 0. 1.1.2's `toonRamp` had 3 or 4 there, 1.1.1's Comic ink cel 18 to 23.) It still fails on the 1.1.1 code (the outline alone 0.19 percent, Comic ink cel 23 lone specks, `toonRamp` 4, at 1920 x 1080).
- **Lookbook.** `toonRamp` and the three looks built on it measured twice again: `toonRamp` swims less (1.64 against 1.97, pan 3.92 against 4.99) and costs 1.21 ms on the high tier in both runs (1.1.2: 1.20 and 1.49), 0.14 ms on the low; Soft anime 4.34 and 4.42 ms, Pencil anime 3.91, Nineties CG 3.78 and 3.80 (1.1.2: 2.03).
- **Test suite**, in the Style Cookbook on this code: one full run passed 11 of 12, the close-up check failing on that chance comparison (Comic ink cel 1 lone speck, `toonBands` 0; `toonRamp` 0); the close-up check then passed with the limits above. The check from ZeroMind in a brand new world is recorded in NOTES.md (see the install note).
**1.1.2 (2026-11-03)**: Comic ink cel draws a figure seen close without ink dots; the outline is tidied where a figure overlaps itself; `toonRamp` reads its light the way `toonBands` does; every Lookbook row is measured again.
- **How it was counted.** From an editor camera 3 m off the showcase figure (at (0.9, 1.6, 3.8) looking at (0.55, 0.95, 0.9), 60 degrees, 1920 x 1080, the stage's sun at 16:30), on the presented frame. A speck is a pixel 6 of whose 8 neighbours differ from it by more than 6 of 255, all one way, counted on the figure only (the pixels that change when the figure is taken away, two in from its outline) and not where the unstyled frame already has one. A lone speck is one in flat paint: its ring of pixels two out lies within 4 code values of its middle all round. Each count below was taken twice, in two separate sets of shots, and both sets gave the same numbers.
- **What was wrong.** 1.1.1 at its defaults put 440 specks on the figure under Comic ink cel, 11 of them lone, against 244 (7 lone) for `toonBands` with `keepShade` 0; the outline alone put 221 there, 13 lone. Most sat on the outline's inner lines: where one pa
# toonLight (shader module)
The toon light model every toonBlocks light block and the `toonLit` material share: `tl_band_level` and `tl_band_light` (hard light bands, any count), `tl_ramp` (five-stop colour ramp, blended or stepped), `tl_wrap` (half-Lambert wrap-around light), `tl_rim` (rim light on either side), `tl_highlight` (a hard-edged stylized highlight), `tl_presence` (zero light stays zero), `tl_hue_rotate` and `tl_saturate`. Pure math with no bindings, so a full-frame block and a material shade by exactly the same rules. Include it with `#include "~toonBlocks.shaders.toonLight"`.
## Known limits
- A pass reads the scene's depth only when it also writes the scene picture (#24550), and an unknown blend name draws as replace (#24551).
- A per-object value cannot reach a geometry pass (#24549).
The package README's Known limits lists the rest.
# skCommon (shader module)
The prelude every styleKit block includes. It reads the shared inputs the stack fills each frame (the `sk_` properties of the styleKit shared header): one clock (`sk_time`, `sk_held`, `sk_step`), surface data copied once per frame (`sk_world`, `sk_dist`, `sk_normal`, `sk_albedo`), coordinates that stay on things (`sk_surface_coord`), the shared ground (`sk_ground_at`) and wobble (`sk_wobble_uv`), resolution-independent mark sizes (`sk_ref_uv`), the block's mask (`sk_weight`) and the one exit every block returns through (`sk_finish`: strength, mask, layer mode, and black stays black). Include it with `#include "~styleKit.shaders.skCommon"` after declaring the shared header.
## Known limits
- A pass reads the scene's depth only when it also writes the scene picture (#24550), and an unknown blend name draws as replace (#24551).
- A per-object value cannot reach a geometry pass (#24549).
The package README's Known limits lists the rest.
# toonFrame (shader module)
What a full-frame toonBlocks block reads at a pixel: `tf_read` returns the frame, its base colour, the light the scene sent as a share of full light (the frame divided by the base colour, so surface texture cancels) and the light's own colour; `tf_normal_at` the surface's shading normal at one pixel (the deferred renderer's copy, else rebuilt from world positions four pixels apart); `tf_normal` that normal averaged over a dense 8 x 8 pixel square on the same surface (4 x 4 on the low tier), so a round object, a low-polygon one included, turns smoothly and the light cut from it has clean band edges; `tf_smoothed_light` the light averaged over the same kind of dense square; `tf_shaped_light` the clean light from the scene's sun (`shape`, `shadeLevel`, `castBelow`), climbing from `shadeLevel` to full as a surface turns toward the sun, with open ground in sun three quarters of the way up; `tf_shaped_span` the two values that light takes in shade and in full sun, which a banding block cuts its bands across; `tf_sun_seen` whether the sun reaches the pixel. Pixels with no known base colour, the sky and the hull outlines' ink are marked unknown and left alone, and every gather leaves them out. Include after styleKit's `skCommon` and `~toonBlocks.shaders.toonLight`.
Every average here reads every pixel of its square once (bilinear taps on the corners between pixels). A few scattered taps would not do: on a mosaic of small facets or on textured ground each tap crosses an edge at a different pixel, so their mean steps from pixel to pixel, and a band, a cast shadow or a poster level cut from it comes out stippled.
## Known limits
- A pass reads the scene's depth only when it also writes the scene picture (#24550), and an unknown blend name draws as replace (#24551).
- A per-object value cannot reach a geometry pass (#24549).
The package README's Known limits lists the rest.
# styleKit
Build your own art style out of stackable look blocks: a look is a stack of small blocks (a wash, an ink line, a paper, a grain) that runs over the whole frame after antialiasing, lives in the scene and looks the same for every player.
Version 1.7.8.
## Install and use
Install **styleKit** from ZeroMind (search "styleKit" or "stackable art style blocks"). Installs with several dependencies can be slow (#21420), so give an install time to finish and check `/zero/source` for the package folder. Then, from the console or any script, stack one of each of the kit's four example blocks:
```luau
local StyleKit = require("~styleKit.StyleKit")
StyleKit.add("posterize") -- Colour: a few flat tone steps
StyleKit.add("duotone", { strength = 0.5 }) -- Colour: two inks, laid half over the posterize
StyleKit.add("depthLine") -- Line: a clean ink outline from depth
StyleKit.add("sketchLine", { strength = 0.6 }) -- Line: soft pencil strokes laid over the outline
print(#StyleKit.describe().entries) -- 4
StyleKit.clear() -- the frame is exactly as rendered again
```
No material is edited. The first `add` makes a synced `StyleStack` entity in the scene, so every player draws the same stack; put a `StyleStack` component in your scene's build to keep a look with the scene.
## The blocks in this package
| Block | Slot | What it does |
|---|---|---|
| `posterize` | Colour | Cuts the picture into a few flat tone steps, like a screen print. |
| `duotone` | Colour | Maps the picture onto a shadow ink and a light ink. |
| `roleGlaze` | Colour | Roles glaze: a transparent glaze of one colour over the objects of one group (a variant), keeping their light and shade. `StyleRoles.use` adds one per group from a role set's `glazes`, so a hero, the enemies and the pickups that share a material still read apart under any look. |
| `depthLine` | Line | A clean, one-sided ink outline from depth plus creases from normals. |
| `sketchLine` | Line | Soft, broken pencil strokes over shape and colour edges, redrawn on the held clock. |
| `sharedView` | Medium | A diagnostic for block authors: shows one shared input in place of the picture. |
Every block lists its slot and its tags (the words a person would search for: `watercolor`, `pencil`, `halftone`, `pixel art`, `chalk`), so you can pick blocks by tag with `StyleKit.blocks({ tag = "pencil" })` or `zero styleKit list --tag pencil`. A block's tags come from its `block.yaml` `tags:` list when it has one, otherwise from its `.metadata` tags.
More blocks come in their own packages and plug straight in: `starterBlocks` has a block for every slot (card surface, light bands, flat wash, surface dots, plain paper, dark board, line boil, chunky pixels, soft grain, vignette), `watercolorBlocks` has ten chained watercolor Fill blocks and a cold-press paper, with pigment sets, whole looks and a hero material, `inkBlocks` has five ink lines, four ink fills, ink colours and whole looks, and `paperBlocks` has seventeen papers (cold press, rough, hot press, rice, newsprint, kraft, parchment, canvas, board, blackboard, green chalkboard, black paper, aged sketchbook, toned grey and tan, ruled notebook, vellum) that publish the paper field and layer by region. `StyleKit.blocks()` lists every block installed. A package can also ship pigment sets (`pigmentSet` assets: `StyleKit.pigmentSets()`) and whole looks (`styleLook` assets: `StyleKit.looks()`) next to its blocks.
## How a stack works
A stack is an ordered list of entries `{ id, block, on, strength, mask, settings }` on a `StyleStack` component. Blocks sit in ten slots that always run in this order:
1. **Surface**: what things are made of.
2. **Light**: how surfaces take light.
3. **Fill**: how areas of colour are laid.
4. **Tone**: marks that carry shade.
5. **Line**: edges.
6. **Colour**: palette and grade.
7. **Ground**: what it is drawn on. The first Ground block publishes the shared ground (and the paper field, when it has one); a later Ground block whose field says `layers: true` lays its ground over the one before by its strength and mask.
8. **Time**: how motion is held. The first Time block publishes the shared wobble.
9. **Raster**: how the image is sampled.
10. **Medium**: what it is seen through.
Any slot can be empty. Any block swaps for any other block of its slot with no other change (`StyleKit.swap(entry, otherBlock)`); strength and mask stay. Inside a slot the list order decides: the first block reads the slot's input, and every later block in the same slot reads the same input and is laid over it by its strength and mask (`stacking: layer`, the default). So two Line blocks with weights 1 and 0.4 blend 60 / 40, and two Fill blocks with complementary masks split the frame. A block whose `block.yaml` says `stacking: chain` reads what the blocks before it in its slot made instead, so modifier blocks build on each other (a wash, then its granulation, then its darkened edges). A block's `rank: <number>` decides where `StyleKit.add` places it: before the first block of its slot with a higher rank, so a chain lands in its painting order whatever order its blocks are added in.
### Keeping a stack
A stack made with these calls is a live edit of the scene, like moving a prop. Save the scene (`layers.active:save()` or the editor's save) and the stack is in its `scene.json`: it comes back on every load and after a restart, the same for every player. `StyleKit.clear()` takes every block off the frame; to get the saved stack back, revert the scene (`tools.use("scene", "revert")`). `scene.reload` keeps live edits by saving them first, so a clear followed by a reload is a saved clear. Keep one StyleStack per scene.
### Shared by every block in a stack
- **One clock.** `sk_time()` and the held clock `sk_held()` / `sk_step()`, stepped at the stack's `holdRate` (8 per second by default). Every wobble and boil runs on the held clock.
- **One set of coordinates that stay on things.** `sk_surface_coord(uv, perMetre)` lays marks on surfaces from world position along each surface's main axis, and on the sky from the view direction, so a pan or a dolly does not drag them.
- **Surface data copied once per frame**: view distance, world position, normal and base colour (`sk_dist`, `sk_world`, `sk_normal`, `sk_albedo`).
- **One ground** (`sk_ground_at`): paper colour and grain height, published by the first Ground block (plain white paper with flat grain when there is none).
- **Layered grounds** (since 1.2.0): a later Ground block whose `block.yaml` field says `layers: true` lays its ground, and its paper field, over the one before by its strength and mask, so regions of a world sit on different papers: `StyleKit.add("paperParchment", { id = "mapRoom", mask = { kind = "sphere", center = { 30, 2, 10 }, radius = 6 } })`. A Ground block without `layers: true` publishes only when it is the first.
- **One paper field** (`sk_paper`, read through `skPaper`, since 1.2.0): how the sheet under each pixel takes paint and ink, for a block that lists `paper` under `reads`: `sk_thirst(uv)` (-1 hard-sized, 0 the standard sheet blocks are tuned on, +1 thirsty), `sk_sheen(uv)`, `sk_fibre(uv)` and `sk_dark_ground(uv)` (1 where the sheet is dark and the picture is made of light marks). A Ground block publishes it with a `field.paper` shader; where none does every value is 0, so a block reading it draws exactly as before. It is only made when some live block reads it. paperBlocks' papers publish it; watercolorBlocks' bleed and edge darkening and every inkBlocks block read it.
- **The scene's sun** (`sk_sun`, a float4, since 1.2.0): for a block that declares it and lists `sun` under `reads`, the direction toward the sun the renderer shades the scene with (`lighting.sun()`), `w` 1 when it gives light (0, and a default direction, when there is none). Read every frame as a table the engine keeps current (nothing in the scene is surveyed), and written to blocks only when its direction (to three decimals) or whether it lights actually changes, so a still sun costs nothing and a moving one reaches blocks on the next frame. Raking light on paper tooth and sheen use it.
- **One wobble** (`sk_wobble_uv`): an offset published by the first Time block (still when there is none). A wash and an ink line that both read it tremble together.
- **One pattern library** (`skPatterns`): noise, fractal noise, cells, dots, hatching, ordered threshold, triplanar noise for materials (`skp_triplanar_fbm`) and brush strokes (`skp_stroke`).
- **One soft field** (`sk_soft`, read through `skSoft`): a half-resolution, depth-aware blur of what a block reads, for a block that lists `soft` under `reads`. Each tap is tested against the centre surface's plane rebuilt from world positions, so a nearer thing is never smeared over a farther one. The stack makes it for the first block that reads it and makes it again whenever a later reader reads a different image; its width is the stack option `softRadius` (reference pixels, 10 by default).
- **One pigment set** (`sk_pigments`, read through `skPigmentSet`): the scene's palette of paints as a 16 x 1 texture, for a block that lists `pigments` under `reads`. `StyleKit.setPigments(id)` changes it for every block and every player at once; with none picked blocks keep the scene's own colours.
- **One rendered frame** (`sk_rendered`, read through `skRendered`): the frame as it entered the stack, for a block that lists `rendered` under `reads`. Light estimates read it against the base colour, so surface texture cancels instead of printing back as shade. With `sk_geo_normal` (a normal rebuilt from world positions, every tier) it lets a block judge light and shape on the low tier and the forward path too.
- **One way to mix paint** (`skPigment`): pigment mixing in transmittance and optical density (log space), two pigments in one wash, glazes that multiply, dilution toward the paper. Pure math, so a full-frame block and a material mix paint the same way.
- **Noise that stays on things and keeps its size** (`skAnchored`): triplanar noise on world position that stays on still things (`sk_anchored_fbm`, `sk_anchored_cells`), and noise that also keeps its size in the picture at any distance by blending two octaves by distance (`sk_scaled_fbm`, `sk_scaled_level`, `sk_surface_plane`, `sk_ref_metres`), for paper tooth, flecks and strokes. `sk_tooth(uv)` reads the shared paper's valleys (0 on a peak, 1 in a valley).
- **Chain stacking** inside a slot (`stacking: chain` and `rank` in `block.yaml`): later blocks build on what the ones before them made.
- **Many blocks, one shader** (`defaults:` in `block.yaml`, since 1.2.0): a block's own defaults over its shader's, so a family of blocks (paperBlocks' seventeen papers) shares one shader and each block is its own starting point. `StyleKit.settingsOf(id)` reports the block's defaults.
- **Swap memory** (since 1.2.0): each stack entry remembers the settings of every block it has held, so `StyleKit.swap("paper", "paperKraft")` then `StyleKit.swap("paper", "inkPaper")` puts back exactly the settings `inkPaper` had, and the frame returns exactly. The memory is kept on the entry in the synced stack, so it is shared and saved with the scene; `load` and `applyLook` write new entries without it.
- **One exit** (`sk_finish`): strength, mask, layer mode, and black stays black: a block never makes light where the frame had none.
- **Strokes for shading blocks** (`skStrokes`, since 1.3.0): hand-laid strokes that build up by tone, for any block that shades with marks (pencil, charcoal, hatching, scribbles). Since 1.4.0 every layer of strokes at one place shares the same patch grid and the same random slant, so layers keep exact angles to each other; outside crossed mode the first two layers run parallel (the second fills between the first) and darker layers cross at clear angles (60 degrees each way, then 30, then square), so soft strokes never beat into broad zebra bands. `sks_layer_d(p, n, tone, dpx, dpy, px_per_ref, st, k)` sizes the strokes across their own width on screen from the position's screen derivatives, so the spacing is the same number of pixels whichever way strokes run and however steeply a surface is seen; prefer it over `sks_layer` wherever derivatives are at hand. Since 1.4.1, `sks_edge_on(facing)` says how much of its stroke pattern a surface keeps from how squarely it faces the eye, and `sks_layer_mean(tone, st, k)` is the average coverage a layer gives: on a floor or a field seen at a low angle, patches of strokes squeeze into rows whose ends read as zebra bands, so mix each layer toward its average there and the ground keeps its value as even rubbed tone.
- **The dim guard** (since 1.4.0): keeps a dark scene dark. See the next section.
### Keep a dark scene dark: the dim guard
A shading block lays marks and a sheet over the picture, and in a dim room the sheet and the light between the marks can end up brighter than the room was. The dim guard stops that, so no shading block (hatching, stipple, dots, pencil, charcoal) brightens a dim or unlit room.
- **When it runs.** When any live block in the stack declares `keepDim`. Every Tone slot block does unless its `block.yaml` says `keepDim: false`; a block in another slot opts in with `keepDim: true`. So a new shading block in the Tone slot gets the guard for free.
- **What it does.** Two small passes after the chain. A meter at an eighth of the chain's resolution records the mean brightness of the stack's result and of the frame as rendered under each of its texels, plus how bright the rendered picture's brightest parts are (a power mean over a fixed 5 by 5 grid) and its overall mean. Then the guard scales the result down wherever, smoothed over about 36 pixels, it is brighter than the rendered frame there (with no allowance since 1.4.4; it was 0.006, about 1.5 of 255). Then it holds each pixel to at most a fifth above the rendered brightness on its darker side: the darkest of four small patches ten pixels off (left, right, above, below), never below the pixel's own rendered brightness. Bare sheet beside a pale prop in a dark-walled room is held to the wall it lies on instead of keeping the prop's brightness and glowing around it, the prop's own edge to the prop, and a patterned surface to its mean, so no texture prints back. It scales rather than clips, so every mark keeps its shape.
- **Only on a dim or unlit picture.** It lets go fully once the picture's mean is 0.42 or above, its brightest parts are at 0.55 or above and some light other than an ambient one is on (daylight, an overcast day, a well lit room), and is fully on below a mean of 0.30 or brightest parts of 0.40. A scene with no light switched on (the engine falls back to a default ambient) counts as unlit however bright that fallback draws it. In a lit frame it hands the result on exactly unchanged. A night street, or a room with dark walls under one lamp, has bright spots but a low mean, so it is guarded.
- **Cost.** Two small passes, only while a block that keeps dim is live. `StyleKit._status().dimGuard` reports whether it ran last frame.
Blocks registered before 1.4.0 (the registry survives hot reloads) get their `keepDim` filled in by the kit, so an upgrade needs no restart.
### Masks
`StyleKit.setMask(entry, mask)` limits a block:
- `{ kind = "depth", near = 0, far = 12, soft = 0.2 }`: by view distance in metres. The soft edges lie outside the band and scale with their own distance: the block fades in over `soft` x `near` metres before `near` and out over `soft` x `far` metres after `far`, so nothing nearer than `near` x (1 - `soft`) is touched, whatever `far` is. The sky lies at the viewing camera's far distance (its `Camera.far`, 8000 m by default): a band whose `far` reaches that distance takes the sky in, a shorter one leaves it out.
- `{ kind = "rect", rect = { x0, y0, x1, y1 } }`: a screen region in 0..1 (top left is 0, 0).
- `{ kind = "sphere", center = { x, y, z }, radius = 5 }`: a region of the world.
- `{ kind = "group", group = 1 }`: the objects in mask group 1, 2 or 3 (`StyleKit.options({ groups = { { id, id }, { id } } })`).
- `invert = true` flips any of them.
`StyleKit.options({ exclude = { "SignBoard" } })` leaves objects (and their children) exactly as rendered: a prop, a world label. Name them: an entry is an entity name or an id, and a scene should store names, because an id written into the stack does not survive the scene being saved and loaded again (the entity comes back under a new id). Entities that arrive later are picked up within half a second. Put labels on a card of their own (a plain white quad behind the words), so the area left out around them is card rather than the raw scene.
### Players, enemies and pickups under one look: style channels
A look treats every object the same unless the object says otherwise. A `StyleChannel` on an object (synced, saved with the scene) says how the look treats it and everything under it:
- **variant**: which variant of the look it gets. A stack entry that names a `variant` draws only on objects of it, and an entry of the same slot that names none leaves those objects to it, so two blocks share one slot by group: one ink for the player, a different ink for the enemies. `"asRendered"` leaves the object exactly as rendered (labels, in-world HUD, a screen inside the world).
- **line**: how heavy its lines and strokes are (1 as the look draws them, 2 twice as heavy, 0 none). Read by styleKit's `depthLine` and `sketchLine`, every inkBlocks line, pencilBlocks' lines (width) and shading (stroke density), and toonBlocks' ink (width).
- **marks**: how much of each kind of mark reaches it, 0 to 1: `line` (Line blocks), `tone` (Tone and Light blocks: hatching, dots, bands), `fill` (Fill, Surface and Colour blocks: washes, cel fills, posterize) and `paper` (Ground blocks: how much paper shows through). Every block honours this with no change of its own: the kit weighs each block by its kind of mark on each object. A block may name its kind in `block.yaml` (`marks: line | tone | fill | paper | none`); otherwise its slot decides, and the Time, Raster and Medium slots are screen-wide.
- **value**: one free value, 0 to 1, a block may use however it likes; 0 changes nothing. The shipped blocks read it as "how much of its own colour the object keeps": watercolorBlocks' wash keeps its colour brighter and purer, inkBlocks' wash keeps its colour through the ink, toonBlocks' ink takes its colour.
- **ink**: the colour of its line, for blocks that take one per object (toonBlocks' ink).
- **role**: a game role (`hero`, `enemy`, `pickup`, ...). The scene's role set fills in every field the object does not set itself. Role sets are `styleRoleSet` assets; the **styleRoles** package ships sixteen roles tuned for six kinds of look.
```luau
local StyleKit = require("~styleKit.StyleKit")
StyleKit.give(entity.findAll("Goblin")[1], "enemy") -- one thing, one change
StyleKit.setChannel(entity.findAll("Coin")[1], { marks = { tone = 0, paper = 0 }, value = 0.8 })
StyleKit.setChannel(entity.findAll("ScoreBoard")[1], { variant = "asRendered" })
StyleKit.add("depthLine", { id = "enemyInk", variant = "enemy", settings = { ink = "#6a0a0a", width = 2.4 } })
StyleKit.setRoles("toonGame") -- the whole game's roles, one change
print(StyleKit.channelOf(entity.findAll("Goblin")[1]).line)
```
An object with no channel, in a scene where none has one, draws exactly as before: the kit makes no object mask and gates no block. Every field is synced on the object's own entity, so every player sees the same roles on the same things, they survive a save and reload, and a change made in play (by any player; a write from a player who does not own the object goes to its owner) reaches everyone. A child with a channel of its own keeps its own; things attached under a role holder later are picked up within ten seconds (at once when its channel changes).
**How it runs.** Objects are grouped by what they ask for into at most eight distinct settings; each setting is one geometry pass into a small image of its own, and one pass packs them into the object mask every block reads (`sk_obj`). A block reads its object through `sk_chan_line(uv)`, `sk_chan_line_near(uv, r)` (the nearest surface within `r` reference pixels, so a line drawn just outside a silhouette belongs to the thing in front), `sk_chan_value(uv)`, `sk_chan_mark(uv, kind)` and `sk_chan_tagged(uv)` from `skCommon`; the gate by kind of mark and variant is applied inside `sk_weight`, so `sk_finish` honours it for every block. Measured on toonBlocks' busy bench (2,500 things, 250 moving, 25 a second spawned and despawned, Comic ink cel), look stack script time a frame:
| | The whole look (median) | average | Toon ink (median) | styleKit (median) |
|---|---|---|---|---|
| Roles off | 0.44 ms | 0.53 ms | 0.11 ms | 0.32 ms |
| 150 things with a role, toon game set | 0.63 ms | 0.78 ms | 0.17 ms | 0.44 ms |
| 600 things with a role, toon game set | 0.93 ms | 1.25 ms | 0.26 ms | 0.64 ms |
| 600 things with a role, before this release (toonBlocks 1.3.5, styleKit 1.6.3) | 1.33 ms | 2.29 ms | 0.60 ms | 0.55 ms |
Measured on 11 November 2026 with toonBlocks' busy bench (`design/roles/bench_roles.luau` in the Style Cookbook world): 2,500 things, 250 of them moving, 25 a second appearing and 25 disappearing, 10 recoloured a second, under the Comic ink cel look; script time the look spends each frame. It ran in a test client of its own drawing 14 to 17 frames a second on a shared, busy desktop, which overstates every per-frame number; your game on its own will measure lower. What changed: toonBlocks 1.3.6 draws every role ink through one shared flood (104 render passes a frame for 600 role holders in nine inks before, 22 now), and styleKit 1.6.4 rebuilds the role mask at most four times a second while roles keep changing. So the whole look stays under a millisecond on the median frame with 600 role holders, and well under one (about 0.6 ms) with the 150 or so a typical level gives roles to. What is left is mostly styleKit queuing its eight mask passes and their selection lists again every frame (#24548): with hundreds of role holders and a slow client the average frame can pass 1 ms. The GPU time of the look did not change measurably.
### Quality
The stack follows the device's quality tier (`renderer.qualityTier()`), and the tiers really change the cost:
- `high` and `medium`: every block pass and every shared input at full resolution. `medium` also applies each block's `quality.medium` settings where it states them.
- `low`: the shared inputs (surface data, ground, wobble) and the block chain itself run at half resolution, a quarter of the pixels for every pass, and blocks take their `quality.low` settings (fewer samples, fewer strokes). The copy of base colour and normals is made on `low` too, at that half resolution (since 1.1.4), so a block judges light and lays marks by the same rules on every tier and a look stays the same look; only the forward render path, which keeps no g-buffer, goes without it. The result is scaled up once at the end, before the UI; excluded objects are put back from the full-size frame, so they stay crisp. Measured on the Lookbook's textured wall at 2097 by 1409 with a wash, a sketch line, paper, boil and dots: 1.64 ms of block passes at full resolution, 0.30 ms on `low` (before the half-size copy, which adds one small compute pass).
On `low`, marks are drawn at half resolution and so are softer: the honest trade for running on a small device. `StyleKit.setQuality("low")` forces a tier on this machine; `StyleKit.setQuality(nil)` follows the device again. The Lookbook measures the cost per pass at each tier.
### Whole frame or inside a material
Every block works on the whole frame with no material edits. Where it means something, a block also ships a shader module a material includes for a chosen set of objects (`include:` in its `block.yaml`), for example starterBlocks' Stepped light, whose `bandedToon` shader bands a material by the same rule. Use a group mask to keep the full-frame pass off those objects.
## API
| Call | What it does |
|---|---|
| `StyleKit.blocks(filter?)` | Every block installed: `{ id, name, slot, tags, summary, reads, writes, settings, package, path }`. Filter by `slot`, `package`, `tag` (one tag or a list, all must match) or `text` (which also searches tags). In the shell: `zero styleKit list`, `zero styleKit list line`, `zero styleKit list --tag pencil`. |
| `StyleKit.block(id)` / `settingsOf(id)` | One block / its settings with docs, defaults (the block's own `defaults:` where it states them) and ranges. |
| `StyleKit.add(id, opts?)` | Add a block (`strength`, `mask`, `settings`, `id`, `index`). Returns `ok, entryId`. |
| `StyleKit.remove(entry)` | Remove an entry (by entry id, block id or position). |
| `StyleKit.swap(entry, id, opts?)` | Swap an entry's block for another of its slot; strength and mask stay. The entry remembers the settings of every block it held, so a block swapped back in gets exactly the settings it had (a block it never held starts from its defaults). `{ keepSettings = true }` carries the current settings across instead; `{ anySlot = true }` allows a swap across slots. |
| `StyleKit.move(entry, index)` | Reorder (orders blocks inside a slot). |
| `StyleKit.setStrength(entry, 0..1)` / `setOn(entry, bool)` | Weight / switch an entry. |
| `StyleKit.setMask(entry, mask?)` | Limit an entry by depth, region or group. |
| `StyleKit.set(entry, { name = value })` | Change settings. Colours take `"#rrggbb"`, `{ r, g, b }` or `{ r, g, b, a }`. |
| `StyleKit.load(entries, opts?)` / `clear()` | Replace the stack's blocks / empty the stack. `opts`: `holdRate`, `markScale`, `pigments`, `softRadius`, `look`; an option left out keeps the stack's current value, so to reproduce a look exactly pass all of its options or use `applyLook`. |
| `StyleKit.options({ holdRate, markScale, exclude, groups, active, pigments, softRadius })` | Stack-wide options. `pigments` is a pigment set id (`""` for none); `softRadius` is the soft field's width in reference pixels (2 to 40, default 10). |
| `StyleKit.pigmentSets(filter?)` / `pigmentSet(id)` | Every pigment set installed: `{ id, name, summary, tags, pigments = { { name, colour, granulation } }, shadow, light, air, package, path }`, filtered by `package`, `tag` or `text` / one set by id. |
| `StyleKit.setPigments(id)` | Pick the pigment set every block that reads pigments mixes from, for the whole stack and every player. `""` picks none, so blocks keep the scene's own colours. |
| `StyleKit.looks(filter?)` / `look(id)` | Every whole look installed (`styleLook` assets): `{ id, name, summary, tags, entries, pigments, holdRate, markScale, package, path }` / one look by id. |
| `StyleKit.applyLook(id, opts?)` | Apply a whole look in one change: its blocks replace the stack and its pigment set, hold rate, mark scale and soft radius are set with them. `{ keep = { "line" } }` keeps the entries of the slots named from the current stack. A look naming a block that is not installed is refused and nothing changes. |
| `StyleKit.describe()` | What is in the stack, in run order, its `pigments`, `look` and `softRadius`, and what the runtime drew last frame. |
| `StyleKit.checkBlock(id)` | Problems with a block against the block rules (empty when it passes). |
| `StyleKit.newBlock(name, { slot, folder })` | Write a working block of your own to start from. |
| `StyleKit.quality()` / `setQuality(tier?)` | The tier the stack draws at / force one here. |
| `StyleKit.setLocal(entry, settings?)` / `localSettings()` | Lay settings over one entry on this machine only, over its synced settings (a tint or a ramp for the level this player is on); nothing is synced or saved, `nil` takes them off / list what is laid here. |
| `StyleKit.setLocalEntry(id, entry?)` / `localEntries()` | Lay a whole entry on this machine only (`{ block, strength, on, mask, settings, variant }`), after the synced stack and ordered by slot like any other: for short local effects such as an impact frame on a hit, which a game keeps in step across players with a message of its own. Never synced or saved; works with no StyleStack in the scene; `nil` removes it. (Contributed by another account as pull request #10, ported onto 1.7.0.) |
| `StyleKit.publishInput(name, texture?)` / `inputs()` / `inputWanted(name)` | Publish a texture another package computes (a heat map, a sonar wave, a thickness map) on this machine for blocks that list `input:<name>` under reads and declare an `in_<name>` texture; `nil` withdraws it (blocks read black). `inputWanted` says whether a live block reads it now, so the producer works only then. Never synced or saved (1.8.0). |
| `StyleKit.setClock(fn?)` | Drive the stack's one clock (boil, grain, wobble) from your own time in seconds, for a cutscene, a recording or the Lookbook; `nil` returns to the shared clock (wall-clock UTC, the same held step on every player's machine). |
| `StyleKit.give(entity, role?)` | Give one object (and everything under it) a game role, for every player and saved with the scene; `nil` takes it away. |
| `StyleKit.setChannel(entity, fields)` / `channelOf(entity)` / `clearChannel(entity)` | Set how the look treats one object: `{ role, variant, line, marks = { line, tone, fill, paper }, value, ink, children }` (-1 or "" gives a field back to the role) / what it gets now, read through the scene's role set, and which object's channel reaches it / take its channel away. |
| `StyleKit.channels()` | Every object a channel reaches with what it gets, and a revision that moves when any of it changes (for runtimes that draw per object). |
| `StyleKit.setVariant(entry, variant?)` | Share a slot by group: the entry draws only on objects of that variant, and the entry of its slot naming none leaves them to it. `add` takes `variant` too. |
| `StyleKit.setRoles(id)` / `roles()` / `roleSets(filter?)` / `roleSet(id)` | Pick the role set for the whole scene and every player ("" follows the look, "none" reads no roles) / the set in use / every installed set / one set, with what it extends laid under it. |
| `StyleKit.lookRoles()` | The set the scene's look suits by itself: what a set written with `extends: look` (a set for a kind of game) is laid over. |
Writes go through the stack's owner, so in play any player can change the shared stack and every player sees the change. The `styleKit` toolbox offers the same from the shell (`zero styleKit list`, `zero styleKit stack`, `zero styleKit add posterize`).
## Writing a block
A block is a plain folder holding `<name>.styleBlock/` (block.yaml, README.md, .metadata) and its `<name>.shader/` (a post-process shader whose `properties.yaml` starts with the styleKit shared header). `newBlock` writes one that works and registers it at once:
```luau
local StyleKit = require("~styleKit.StyleKit")
local path = StyleKit.newBlock("warmTint", { slot = "medium", title = "Warm tint" })
print(path) -- /zero/source/myBlocks/warmTint/warmTint.styleBlock
StyleKit.add("warmTint", { strength = 0.6 }) -- a warm filter over the whole look
StyleKit.set("warmTint1", { tint = "#ffcf8a" }) -- its setting, like any block's
```
Then edit `/zero/source/myBlocks/warmTint/warmTint.shader/shader.wgsl` to make it do what you want; the stack picks up the change as you save. To share blocks, move their folders into the `blocks/` folder of a package of your own (a `<name>.package` folder with its `package.yaml`): a package that holds blocks adds them to every world that installs it, with no code. The guide "Writing your own style block" walks the whole shape every block follows.
A block that shades the picture (hatching, stipple, dots, a pencil shade) belongs in the Tone slot, where it is kept from brightening a dim room by the dim guard with no work of its own. A block in another slot that lays a light sheet or light marks over the picture can ask for the same with `keepDim: true` in its `block.yaml`; a Tone block that should be left alone in the dark says `keepDim: false`.
## Rules every block follows
- It states its slot, what it reads and what it writes, and takes over nothing it does not own (a Ground block alone writes the ground, a Time block alone the wobble).
- Every setting is named, documented in `block.yaml` and has a good default in its shader.
- Marks stay on things unless the medium really is a screen (pixels, grain, a vignette), and they run after antialiasing and upscaling.
- Wobble runs on the held clock.
- Its README says what it gives up in motion and how it treats opaque things, transparent things, particles, sky, fog, skinned characters, foliage and world text.
- With every light off the frame stays black (`sk_finish` holds every block to it), and a dim room stays dim (the dim guard holds every block that keeps dim to it).
- The UI is drawn after the stack, so it stays readable.
- No full-screen flashing above 3 Hz and no fine high-contrast stripes filling the view.
`StyleKit.checkBlock` and the `styleKit` test suite check the rules that can be read from files.
## Guides and workflow
This package carries its guides (search them with the `guides` tool or ZeroMind): combining blocks into your own art style, how to use styleKit, writing your own style block, and a worked example from an empty world to a small stylized game. The `restyleWorld` workflow gives an existing world, scene or kit a new look non-destructively, and the `styleKit` agent skill tells an agent what it can do with blocks.
## What a look costs
GPU milliseconds per frame of the style passes, 3D view drawing at 1893 x 1072 (98% of a 1920 x 1080 frame's pixels), measured with the Lookbook (`zero lookbook cost 1920 1080 true`) over its pan on a desktop GPU. The rest of the frame (scene, shadows, antialiasing) is not counted. Low quality runs the whole chain at half resolution.
| Look | High | Low |
|---|---|---|
| README example: posterize, duotone 0.5, depthLine, sketchLine 0.6 | 0.60 | 0.11 |
| Cookbook: flatWash, depthLine, plainPaper, lineBoil, softGrain 0.6 | 1.03 | 0.21 |
| Comic: lightBands, surfaceDots, depthLine, posterize | 0.41 | 0.10 |
| Chalk: depthLine, darkBoard | 0.43 | 0.10 |
| Retro: posterize, chunkyPixels, softGrain, vignette | 0.22 | 0.07 |
Each block alone, high / low: flatWash 0.45 / 0.07, sketchLine 0.32 / 0.06, darkBoard 0.24 / 0.07, plainPaper 0.23 / 0.07, depthLine 0.19 / 0.04, cardSurface 0.11 / 0.03, lightBands 0.09 / 0.03, surfaceDots 0.09 / 0.03, softGrain 0.09 / 0.03, lineBoil 0.06 / 0.02, chunkyPixels 0.06 / 0.02, posterize 0.05 / 0.02, duotone 0.04 / 0.02, vignette 0.04 / 0.02. A look costs a little less than its blocks added up, because the shared inputs (depth, surface coordinates, ground) are made once per frame for the whole stack.
**Frame rate and the web.** On the web the Cookbook look was measured at about 29 to 30 fps in the Cookbook scene (one sample 25), against about 43 fps with no look, and the low tier did not change it: the look cost about 10 ms a frame there while its passes took about 1 ms of GPU time. That measurement is of styleKit 1.0.6. The cost was not the shading but the work around it, which a browser pays several times over: 15 screen-sized images made up front whatever the look, 11 passes, and engine calls every frame for every effect. 1.0.7 cuts it, measured on desktop: the Cookbook look now makes 7 images on high and 5 on low (was 15), runs 9 passes on high and 8 on low (was 11), and spends 0.19 ms of Luau a frame on high and 0.12 ms on low (was 0.40 ms on both), so low now saves passes and Luau, not only pixels. **Whether 1.0.7 holds 30 fps on the web is not measured yet:** an agent cannot start a browser engine (#20946), and in the desktop editor the whole-frame rate swings more from the editor's own load than the look costs, so no desktop fps is quoted here. `zero lookbook report` now starts with the frame rate in the scene you are in (no look, the look on high, on low, measured in turns), so one run in the web build gives the answer. The web limits it may still meet are open engine issues: #20750 (web frame rate), #17441 (cost of scene-colour features) and #17478 (post tiers on mobile).
## How it runs
The `styleStack` render feature starts on a machine as soon as the scene's stack holds a live block (one that is on, has strength above 0 and is installed), on every player's machine alike. Each frame it copies the base colour and normal from the deferred g-buffer at `afterLighting`, then at `afterScenePost` (after antialiasing and the render-scale upscale, before the UI) it rebuilds world position and distance from depth, publishes the ground and wobble (only when a block of the look publishes them; otherwise blocks read a tiny constant image written every few seconds), runs each slot and hands the result to the screen, blending it over the frame as rendered so excluded objects stay as they were (one pass, no copy of the frame). When a live block keeps dim, the dim guard's two small passes (a meter at an eighth of the chain's resolution, then the guard) run between the last slot and the hand-off. A frame of the Cookbook look runs 9 passes: the copy of base colour and normals (only when a live block reads them, and never on the low tier), world position, the two shared fields, one pass per block, and the hand-off to the screen; the blocks read the scene directly, so there is no copy of the frame first. Only five screen-sized images are made up front (the chain's two, world position and the two fields); the rest are made the first time a look uses them (group masks, excluded objects, the base colour and normal copies). A frame in which nothing the stack draws from has moved (the stack, its options, the tier, the images, the camera anchor, the view, the channels) hands the engine the passes of the frame before as they were and skips the rest of its work; a held clock step writes only the clock. Otherwise the Luau work per frame is a few calls into the engine: uniforms, settings and mask groups are written only when the stack, the tier or the camera's frame inputs change, and the clock only when the held step moves. When the stack holds no live block (after `StyleKit.clear()`, or with every entry off) the kit lets everything of its own go within two frames: every block effect and its internal effects (the dim guard's two among them) are removed from the screen effect list, its screen targets, buffer and mask materials are freed, and the render feature itself ends. `StyleKit.holdsAnything()` then reads false, and the first block added brings it all back.
## Known limits
- **Offscreen captures and render-to-texture cameras do not draw the stack.** The stack runs at `afterScenePost`, which only the presented frame reaches, so `capture` with `source = "main"`, `"entity"` or `"position"` shows the unstyled scene; use `source = "presented"` or `renderer.presentedFrames`. Per-camera post: engine issues #66 and #17427.
- **Depth in a feature's fragment pass reads 0 after post.** `zero_scene_depth` is not bound to a render feature's fragment pass at `afterScenePost`, so the kit copies depth with a compute pass once per frame and blocks read that copy (#17427).
- **G-buffer channels are refused after post**, so base colour and normal are copied at `afterLighting`. On the forward path there is no base colour: Surface and Light blocks fall back to working from brightness alone.
- **Marks on moving objects.** Surface coordinates come from world position, so marks stay put on still things under any camera move, but slide across a moving skinned character or a moving prop. Object-space coordinates need per-object data a full-frame pass does not have, so marks that stay on a moving object can only be drawn inside its material: watercolorBlocks' `watercolorSurface` shader shows how, carrying the object's own position from `vertex_clip` (`local_position`) to the fragment in the vertex colour (applied with `WatercolorHero.paint`).
- **The soft field costs two half-resolution passes each time a reader reads a new image.** In a chain, a later block that reads `soft` reads a different picture from the first one, so the field is made again for it; keep soft readers few, or next to each other on the same input, on small devices.
- **Post effects get one pass each and no history** (#17427): a block cannot read the previous frame or its own last output, so nothing in a block can build up or settle over time.
- **Effect uniforms reset on recompile** without notice; the runtime renews its writes twice a second, so after a shader edit a setting can take up to half a second to come back.
- **One held clock for every player, as close as their clocks are set.** Since 1.1.3 the held clock runs on wall-clock UTC (caught to the frame from `os.time()` ticking over), so every machine shows the same boil step at the same moment; machines whose clocks are set by the network agree to a few hundredths of a second, so two screens differ only in that sliver around each step. A machine whose clock is set wrong boils out of step with the others. `StyleKit.setClock` drives it from a time of your choosing instead, so a cutscene or the Lookbook repeats exactly.
- **Transparent things and particles have no depth**, so lines and surface marks treat them as the opaque surface behind them; each block's README says how.
- **Stage order** (#17426, #17439): blocks rely on `afterScenePost` running after the TAA resolve and the upscale, as the engine documents today.
- **A full-screen pass cannot tell which object a pixel belongs to (#22178), and a geometry pass carries no per-object value (#24549).** Style channels are drawn as at most eight distinct settings, one geometry pass and one small image each, packed by one more pass into the object mask. Objects asking for the same thing share a setting, so a game's sixteen roles fit; a ninth distinct setting is left out (the objects it reaches draw as if they had no channel), and `StyleKit._status().parts` says how many were drawn. Colours per object (an enemy's ink) cannot ride the mask; blocks take them through a variant entry of their own (styleRoles adds one per coloured variant), and toonBlocks' ink, which draws per object, takes the channel's `ink` directly.
- **Every pass is queued again every frame (#24548).** Each mask setting's selection list costs a little script time per selected object every frame; with 600 role holders that is most of the 0.2 to 0.3 ms the channels add.
- **A pass reads no depth unless it also writes the scene picture (#24550)**, so the mask parts test against the scene's depth in their own shader, and a line block finds the object a line belongs to by looking at the nearest surface around it (`sk_chan_line_near`) rather than at a depth the mask pass kept.
- **An unknown blend draws as replace (#24551)**: the mask parts use `opaque` (each part is an image of its own), and nothing in the kit relies on another blend name.
- **A running editor that had styleKit 1.4 open keeps the StyleStack's old fields until it restarts.** It cannot read or write the stack's new `roles` field, so the role set lives on a `StyleRoleSet` component beside the stack (new in 1.5.1), which every client has at once; objects' channels (a component new in 1.5.0) replicate at once too.
- **Edit mode does not share live changes between two editors.** Roles given in one editor reach another through the saved scene; in play every change reaches every player at once.
- **One stack per scene.** With two StyleStack entities in a scene the kit draws the last one it found; keep one, and change it rather than adding a second.
- **After a scene switch** the engine can free the stack's screen targets; the runtime notices within about two seconds and rebuilds them, so the look can be missing for that moment.
- **Switching looks can show picture memory a little above where it began.** Two seconds after the last live block goes, the kit frees every screen image it made (checked with 1.4.4: four looks applied and cleared, five rounds). The engine keeps freed render scratch for reuse until its next collection, so between collections the texture memory reads one or a few screen images above the start (112, 136, 160, then back to 88 MB in one session); `renderer.collect()` brings it back to the same figure every round (64 MB there). It does not grow without end.
- **The dim guard keeps a dim room's level, not every pixel's.** It matches brightness smoothed over about 36 pixels and holds each pixel to a fifth above the render around it, so one light mark can still sit a little lighter than the render right under it while the area around it stays as dark as rendered. In a lit picture (brightest parts at 0.7 or above and a mean of 0.4 or above) it does nothing, so how a block treats daylight is up to the block.
- Post-process shaders have no preview image, so the shader previews in this package are absent.
- **Other engine issues that apply here:** the camera gives no near and far planes (#24514); a two-client editor sometimes refuses to load two different scenes at once (#24666, #24667); a world boot can wait about 30 s on a network handshake before content starts (#24669); installs with several dependencies are slow (#21420); the ZeroMind description can lag one release (#19258); the web build was not checked from here (#20946); two engines on one account collide as one player, so a two-player check needs two accounts (#14448).
## Version history
**1.8.3 (2026-11-13)**: a block added with no `rank` lands before the first block of its slot ranked 100 or more, so a finishing block (a printed margin, a frame, weather laid over the picture) that states `rank: 100` and up with `stacking: chain` stays on top when grain or a vignette is added after it. Before, the later block was appended last and, as a plain layer reading the slot's input, painted the margin out. Blocks with a rank, and every stack already saved, are placed as before.
**1.8.2 (2026-11-13)**: the sky distance a depth mask uses costs the render path nothing. The active camera, its entity and its Camera component were read from inside the render feature's frame (about twice a second: forced on the replay check and again on the full path), where those engine calls can cost far more than from a script: a profile of a 2-3 block look in a large world (about 2,900 entities) put about 24 ms of every second there. The render path now reads only the cached far distance; the lookup runs in a deferred task off the frame, at most every 2 seconds, and a replayed frame takes the full path as soon as the cached value differs from the one it was built with. A camera far-plane change is picked up within about 2 seconds; the frame drawn is unchanged.
**1.8.1 (2026-11-13)**: a still frame costs less script time. (1) A frame in which nothing moved now replays every frame instead of taking the full path every 15th frame: the periodic checks run on cadences of their own, spread over the frames, and send a frame down the full path only when one finds something moved. The renewal backstop (one effect every 30 frames) and the dim guard's rewrite are a few property writes on a replayed frame; each effect's shader-reload count is read in turn (about every 30 frames each); the lighting watch every 15 frames (a change takes the full path and reads the sun again); the sky distance every 60 frames; the neutral fields' backstop write keeps its 240-frame cadence. Target residency, the quality tier and a rebuilt device are read before the replay check as before, and a new effect settling, a driven clock, objects still awaited, a tier change, lost targets and any stack, option, view or channel change still take the full path. (2) A replayed frame allocates nothing: the live-entry list is kept per stack (ordered list, revision and registry), and the anchor and clock are made only when used. (3) The stack's 60-frame backstop copy of an unchanged stack replays like the list it copies (compared by content) instead of forcing a full frame. Measured on the Cookbook's main scene (5 entries, 9 passes, static camera, 12 s): forced full frames went from 58 to 0, mean styleKit render time from 0.20 to 0.17 ms a frame in a headless client; what is left on a replayed frame is almost all the engine's own per-pass enqueue (about 4 µs warm per pass). The frame drawn is unchanged.
**1.8.0 (2026-11-13)**: published inputs. A block can now read a texture another package computes on each machine: the producer calls `StyleKit.publishInput(name, texture)` and every block that lists `input:<name>` under `reads` gets it bound to its `in_<name>` texture (black while nobody publishes it); `StyleKit.inputs()` lists what is published and `StyleKit.inputWanted(name)` says whether a live block (synced stack or local entry) reads it now, so the producer only works while one does. `checkBlock` pairs each `input:` read with its `in_` texture and does not ask for a description or default for `in_` textures. Inputs are never synced or saved. Asked for by sensor-look blocks (thermal, sonar, x-ray) that read a heat map, a sonar wave and a thickness map made by other packages; before this a block could only read styleKit's own fields. The test suite gains "published inputs reach the blocks that read them"; the writing-a-style-block guide and the styleBlock type README describe it. Nothing changes for existing blocks.
**1.7.9 (2026-11-12)**: a look costs the engine less per frame. Measured with the engine's own CPU and GPU time (look off against on, 1920 x 1080, 2,500 things) on animeBlocks' one-pass TV anime look, which went from 10 passes to 5 and from about 0.33 to 0.19 ms of styleKit script a frame. (1) A frame in which nothing the stack draws from has moved (the stack, its local entries and options, the tier, the images, the camera's anchor, the view, the channels) hands the engine the previous frame's passes again and skips the rest of its work; a held clock step writes only `sk_clock`; every 15th frame, a frame with a new effect still settling, a driven clock and objects still awaited take the full path, so every periodic check keeps running. (2) The ground and wobble a look reads when no block of it publishes them are tiny constant images written every few seconds instead of two full-screen passes every frame. (3) Excluded objects: the hand-off blends the styled result over the screen, which still holds the frame as rendered, transparent where an object is kept, so there is no copy of the original frame and no copy before the hand-off (three passes become one; kept objects stay full size and crisp on every tier). (4) When the object mask only keeps objects as rendered (no mask group, no channel), the restore reads the exclusion's own part and the merge pass is skipped; when the merge does run it reads only the parts in use. (5) The stack's own effects are registered the first time a look uses them (the engine surveys every registered effect each frame): the TV anime look holds 4 instead of 10. Checked: excluded objects stay exactly as rendered (a pedestal and a ball excluded on animeBlocks' plaza), and the TV anime look looks as before.
**1.7.8 (2026-11-12)**: quieter on a scene saved before styleKit 1.5. Its StyleStack has no `roles` field (the role set lives on the `StyleRoleSet` component beside it), and setting a role set tried to write the old field as well, logging a refusal each time; once a read has found the field missing, the write is skipped. Found following the Summit Sprint example guide on a fresh fork. Nothing else changed.
**1.7.7 (2026-11-12)**: a role set or look that another player changes (or a pull brings) now reaches this machine at once. The asset type's change hook runs only on the machine that made the change, so every other player kept the old roles and looks until they reloaded; each registered role set and look is now watched, and a change arriving from elsewhere is read again. Checked with two clients: a role set edited in one was read in the other within the same session, with no restart. Nothing else changed.
**1.7.6 (2026-11-12)**: a style channel reports `inkByHand` when its ink was set on the object by hand rather than by its role, so runtimes can draw it as set (toonBlocks 1.4.0 mixes none of the object's own colour into it). Role sets take `noLook:`, the set one written with `extends: look` sits over while no look is on: styleRoles' sets for kinds of game name the toon game set, so a game's hero, enemies and pickups carry their groups (player, enemy, pickup, and with them the variant lines and glazes) from the start rather than only once a look is picked; before, with no look on, a game set gave its hero the variant `hero`, which no line or glaze targets. Nothing else changed.
**1.7.5 (2026-11-12)**: styleKit's checks pass in a world that holds only styleKit (or only styleRoles, which brings it). "Clearing puts the frame back as rendered" loaded starterBlocks' `plainPaper`, so where starterBlocks is not installed the load was refused, nothing drew and the check failed (since 1.7.4 a plain styleKit install no longer brings starterBlocks along); it now stacks styleKit's own `posterize`, `duotone` and `depthLine`. "Block defaults stand over the shader's" skipped itself unless another package's block stated defaults (paperBlocks); it now writes a throwaway block of its own whose block.yaml states `amount: 0.37` over the template shader's 0.5, checks it, and removes it, then checks every other installed block that states defaults. In a fresh world with only styleRoles installed the suite passed 13 of 13 twice, with nothing skipped (it was 11 passed, 1 failed, 1 skipped). No block, shader or runtime changed.
**1.7.4 (2026-11-12)**: styleKit (and everything that brings it, styleRoles first) installs into an empty world again. The styleKit agent skill listed the Lookbook (`lookbookKit.Lookbook`, `lookbookKit.lookbook`) among its dependencies, so every install of styleKit brought lookbookKit along under deps, and lookbookKit's own pin on starterBlocks could not be met there: a fresh world that installed only styleRoles refused it ("is not installed, because it does not run"). The Lookbook stays optional, as the skill and the restyle workflow already said (they use it only where a world has it); it is no longer a dependency. Nothing else changed.
**1.7.3 (2026-11-12)**: fixes on top of 1.7.2, which came in as pull request #12 (another account's, merged). The stand-in search 1.7.2 added ran one name search over the whole scene per object with a channel on every sweep, and every second for 15 s after roles arrive: 0.023 ms each in a 158-thing scene, so 14 ms a sweep with 600 roles, growing with the scene. It now builds one index of stand-ins per prefix with a single glob search (`pk_vis_*`), kept until anything spawns or despawns: 0.0035 ms. And `look(id)` / `pigmentSet(id)` scan again on a miss at most once every 2 s: the role set picker and the roles test ask for looks that are not installed on purpose, and each miss read every look and pigment set the world holds. Checked here: 40 coin stand-ins and their child meshes all take the pickup role.
**1.7.2 (2026-11-12)**: a role reaches pickupsKit coins (from the first second of play), and a look installed after the first scan is found.
- A style channel now also reaches an object's **stand-ins**: root entities named `<prefix><owner id>` that a kit draws in the object's place. pickupsKit pools every pickup's model as its own root, `pk_vis_<pickup id>`, so `StyleRoles.give(coin, "pickup")` (the guide's own example) reached nothing the coin draws: on a pencil level the coins stayed grey, with no gold glaze and no ochre line, while the hero and enemies took theirs. `pk_vis_` is registered by default; `StyleChannels.addStandInPrefix(prefix)` registers another kit's. For 15 seconds after channel owners arrive (a scene load, the start of play), subtrees are swept every second instead of every 10, since pickupsKit builds its visuals a frame or more after the pickups; without that, coins stayed grey for the first 10 seconds of play. On a 16-coin, 2-gem level, 52 of 52 coin and gem models took their role (0 before), and ReadApart's least distance read 19.3 with roles on and 2.5 with roles off.
- `look(id)` and `pigmentSet(id)` scan again on a miss. Looks were scanned once a session and then kept up by per-file registration, so a block package installed into its own folder after another install had first placed it under `deps/` (inkBlocks, brought by pencilBlocks, then installed itself) lost its looks in the move: `applyLook("comicInk")` answered "no look called comicInk" and the RoleSetSwitcher's Ink comic button switched the roles alone, until the editor restarted.
**1.7.0 (2026-11-12)**: groups that share a material read apart under every look, untagged things keep the plain line, and a look switched on never flashes black.
- New block **Roles glaze** (`roleGlaze`, Colour): a glaze of one colour over one variant's objects, keeping each surface's own value (a white surface takes a light tint of it, never paper white). Role sets gain `glazes:` beside `lines:` (merged through `extends` the same way), and styleRoles 1.3.0 adds one glaze per group. On a plain stage where one player, five enemies and five pickups share one white material, the least distance between the groups with roles on went from 4.0 to 18.9 under Picture book, 4.2 to 22.6 under Watercolor, 10.7 to 26.5 under Pencil sketch, 10.1 to 17.4 under Ink drawing, 11.5 to 19.4 under Comic ink and 20.2 to 43.0 under Paper cutout game (styleRoles' README has the table).
- `describe()` reports each entry's `variant`. It did not, and toonBlocks' ink reads its entries from there, so under a toon look every variant line a role set adds was drawn on every object, things with no role included, and the last one won: lamp posts nobody tagged came out in the arena shooter's hazard orange, and in enemy red once the hazard line was removed. Untagged things now keep the look's own line.
- A look's passes run only once every shader they use has compiled; until then the frame is shown as rendered (at most 4 s per new effect). A pass whose shader has not compiled draws nothing, and the next pass then read an image that was still black, so in a fresh engine, where a look's first compile takes seconds, switching to a look could flash the screen black.
- The dim guard lets an object whose style channel asks for a lighter line weight (under 1) lighten in proportion, so a light pencil on one object reads lighter than the rendered frame even in a dim picture (pencilBlocks' per-object weight test: weight 0.3 read 245 against 204 with no channel, where before the guard held it at the rendered 90).
- `StyleKit.setLocalEntry(id, entry?)` and `localEntries()`: a whole entry on this machine only, from pull request #10 (another account's, made on 1.5.1 with seven conflicts; ported by hand, the rest of that pull request was older copies of files this world has since moved on).
**1.6.5 (2026-11-11)**: A new effect's settings, frame values and sun are written every frame for its first three seconds. A value written before an effect's shader had compiled read as the shader's default (#22741) and was written again only by the every-30-frames backstop, one effect at a time, so a look switched on from nothing (a stack with a paper most of all) drew a lighter, half-set picture for two to four seconds and then snapped to the real one. It now draws the settled picture from its first frames (measured: FLIP 0.049 from the settled frame for the first 2.5 to 3.5 s before, 0.000 from the first sample after). Found by running every suite twice in a freshly installed world: paperBlocks' unpaint test and pencilBlocks' shadow-band test read the picture inside that window.
**1.6.4 (2026-11-11)**: the role mask is rebuilt at most four times a second while channels keep changing (enemies spawned and killed every frame in a busy level), where it was rebuilt on every frame something changed; a read for one object (`channelOf`) always sees the latest. With toonBlocks 1.3.6 this takes the look with 600 role holders from 1.33 to 0.93 ms on the median frame (table under Style channels). Every README in the package (each block, look, shader and guide) now ends with a Known limits section naming the engine issues that apply there. It also carries what was prepared as 1.6.3: a role or channel given to a player template (an entity holding a `PlayerPrototype`, such as the `Player` of the engine's player scene) now goes on the template's body, which is what the engine copies into the world for each player who joins. Before, `StyleRoles.give(entity.find("Player"), "hero")` reported success and read back as hero in edit, but the template itself is never in the world, so no actual player, late joiners included, carried the role. `setChannel`, `give`, `clearChannel` and `channelOf` all follow the template to its body. Found by installing the look into a new world and building a small scene from the engine's player template.
**1.6.2 (2026-11-11)**: a look, a block or a role set change works after a play restart. The kit held a handle to the scene's StyleStack across the restart; the old component still answered reads, so the kit kept using it, and every write failed with "the component this proxy names was removed". A write that fails that way now drops every held handle, finds the scene's stack again and runs once more. Found while checking styleRoles 1.1.0 on a fork of Summit Sprint.
**1.6.1 (2026-11-11)**: (released as 1.6.1 because the number 1.6.0 was already taken on ZeroMind) role sets for a kind of game. A set may write `extends: look` to sit over whichever set the scene's look suits (its line weights and inks over that set's, which keeps deciding tone, fill, paper and value), so one set works under every look and follows a look change by itself; variant lines merge the same way, variant by variant. `StyleKit.roleSet(id)` lays such a set over the current look's set, `StyleKit.lookRoles()` names that set, `StyleKit.EXTENDS_LOOK` is the word. New `ChannelProbe` module, a test helper that measures what one object's channel does to the presented frame (used by every block package's tests). A scene's script cost is unchanged (see What it costs).
**1.5.1 (2026-11-11)**: the scene's role set is kept on a `StyleRoleSet` component beside the StyleStack (and in the stack's `roles` field where a client has it). An editor that had styleKit 1.4 open when the update arrived keeps the stack's old fields until it restarts; there `StyleKit.setRoles` used to report success while the write failed, and reading the set logged an error every frame. Both work now. Found by installing the release into a fork of Summit Sprint.
**1.5.0 (2026-11-11)**: one look, and players, enemies and pickups read apart under it. A `StyleChannel` on any object (synced, saved, reaching everything under it) says which variant of the look it gets or `asRendered`, how heavy its line is, how much of the look's line, tone, fill and paper reaches it, one free value and an ink colour, or just names a game role the scene's role set fills in. A new asset type, `styleRoleSet`, holds role sets (with `extends:` for an author's own); `StyleKit.give`, `setChannel`, `channelOf`, `clearChannel`, `channels`, `setRoles`, `roles`, `roleSets`, `roleSet` and `setVariant`, and `variant` on `add`. The object mask (`sk_obj`) now packs exclusion, mask groups and each object's channel; every block is weighed by its kind of mark and its entry's variant inside `sk_weight`, so every installed block honours channels with no change; `sk_chan_*` helpers let a block read line weight and value; `depthLine` and `sketchLine` take the line weight. A scene with no channel draws exactly as before and makes no mask. Writes to another player's object go to its owner. `StyleKit.VERSION` says 1.5.0.
**1.4.24 (2026-11-10)**: less work every frame. The stack's entries are copied and put in order once per change (any property change on any machine moves the stack's revision) instead of every frame, with a fresh copy every 60 frames as a backstop; each effect's shader-reload counter (a name lookup) is read every 30 frames instead of every frame; the quality tier and the render targets' residency are checked every 15 frames (a rebuilt render device is still caught the frame it happens). Measured under toonBlocks' bench with 2,500 things, the style stack takes about 0.23 ms on the median frame on one shared line (0.33 ms with eight per-object ink styles, which was 0.33 ms with more variance on 1.4.23).
**1.4.23 (2026-11-10)**: nothing on a timer looks over the scene. The sun and the light rows are read only when a light or the sky changed (a native watch over the engine's Light and Sky components; before, the "is anything lit" check read the light rows once a second); a scene stack and the objects named in its groups are looked for again only when the entity set changed (before, twice a second while one was missing). The cached writes to every effect are renewed when the render device is