# toonMaterials: Ink and Gouache
**24 toon and cel-shaded materials for the Swatchbook material library (materialLibraryKit), all one cosy cartoon style: the same light bands, one shared palette, one ink outline colour and weight, so a brick wall, a grass path, a wooden door and a tree in one scene read as one cartoon.**
Version 1.0.11. Depends on materialLibraryKit 1.4.3 (Swatchbook, the current material library) and nothing else; installing this package brings the library along. Once installed, every toon material is in the library's list, picker and swatch gallery on every player's machine, with no setup code.
## Guides in this package
Two guides ship inside the package, so every world that installs it has them. Open them in the engine's guides by their full path (the short name alone does not open, engine issue #22286):
- **How to make my game look like a cartoon: cel shading with ink outlines** (`toonMaterials.package/guides/makeYourGameLookLikeACartoon`): what the kit is, putting a toon material on something, finding materials by family and swapping them, how the ink outline works and what its settings do, how it behaves with several players, and how it combines with the toon versions in the metals, sci-fi, fantasy, organic, synthetics and translucent collections.
- **Make a cartoon game scene from an empty world: a cel-shaded village with ink outlines, step by step** (`toonMaterials.package/guides/buildACelShadedCartoonVillage`): from an empty world to a small cartoon level with two characters, props and ground, all cel-shaded with ink outlines; then the whole village swapped between the four families with one word, and the bands and outlines turned up or down for every player.
ZeroMind search does not find guides inside a package yet (ZeroMind#3099, engine #22181): read them from the installed package, or search this world's guides from the engine.
## Install and put the first material on a cube
Install **toonMaterials** from ZeroMind (search "toonMaterials" or "Ink and Gouache"). Then, in an empty world, from the console or any script:
```luau
local Materials = require("~materialLibraryKit.Materials")
local ToonInk = require("~toonMaterials.ToonInk")
-- synced: the cube exists for every player, so every player sees its material and its ink
local cube = entity.spawn("toonCube", { synced = true, components = { Model = { model = "cube" } } })
cube.localPosition = { 0, 1, 3 }
assert(Materials.apply(cube, "toonMetal")) -- cel-shaded riveted steel, for every player
assert(ToonInk.set(cube, true)) -- the dark ink outline, for every player
```
`Materials.apply` and `ToonInk.set` return `ok, err`; the `assert` stops with the reason instead of leaving the cube grey. To take it away again: `Materials.clear(cube)`, `ToonInk.set(cube, false)`, `entity.despawn(cube.id)`. Swap the look by changing one word: `Materials.apply(cube, "toonBrick")`.
## Use it together with the material library
Installing toonMaterials brings the material library (materialLibraryKit 1.4.3, the current release) with it, so the toon set works on its own. To add other material collections, or the library's own guides, tools and gallery, install **materialLibraryKit** from ZeroMind as well, before or after toonMaterials:
```bash
zero zeromind installAsset aafbaae5-5d94-4661-b8d4-688eeed11d1b # toonMaterials
zero zeromind installAsset 0d7f3e76-0699-44fd-b0ac-2cb37822b648 # materialLibraryKit
```
Either order leaves one material library in the world, the current one, and `require("~materialLibraryKit.Materials")` answers with it; the toon materials appear in it beside its calibration shelf and apply as above. One thing to do when toonMaterials is already in the world and you install materialLibraryKit on top of it: reload the world once afterwards. Until you do, the library reports problems for some of its own calibration materials and lists fewer of them, and an outline that another player switches on or off is not picked up on your machine (engine issue #22328, see "Known limits" and "Fresh install"). Check the library with:
```luau
local Materials = require("~materialLibraryKit.Materials")
for _, c in Materials.collections() do print(c.name, c.version, c.count) end -- calibration 1.4.2 20, toon 1.0.7 24
```
Up to 1.0.5 this package pinned materialLibraryKit 1.3.1. A world that installed one of those releases and then the current library holds two packages named `materialLibraryKit`, and the engine refuses to choose between them, so `require("~materialLibraryKit.Materials")` fails. Update toonMaterials to the current release (`zero zeromind update /zero/source/toonMaterials.package`) or remove the old library copy, so one library is left.
## Texture memory
**26.7 MB for all 24 materials** (GPU memory, mipmaps included; UASTC, which the engine turns into BC7 on desktop and ASTC on phones). The flat set, the water and the glow use no textures at all. The 24 reference pictures the gallery hangs add 8.0 MB (34.7 MB with them). The heaviest single material is 2.7 MB, far inside the web's per-material limit (24 MiB), and every one passes the library's web check (`Checks.budget`): 2 sampled textures each (the web limit is 9), no storage buffers, nothing over 1024 px.
## The materials
Every material is tagged `toon`, `cartoon`, `stylised` and `outline-ready`, plus what it is (category and kind), its style family (`cel`, `flat`, `hand-painted` or `gradient`, and `family-cel` / `family-flat` / `family-painted` / `family-gradient`), its tile size (`tile-<metres>m`), `glowing` or `not-glowing`, `animated` (with what moves) or `not-animated`, how many textures it binds (`0-textures`, `1-texture`, `2-textures`) and their cost (`textures-none`, `textures-light`, `textures-medium`, `textures-heavy`), `cel-shaded` and `3-bands` (the shared default) on the banded families, `gradient-mapped` on the ramps, `painted light` or `no baked light`, `seamless`, `metallic` or `non-metallic`, and search words.
Tile is the metres one texture repeat covers (1 unit = 1 m). Seamless means `Checks.seams`, tiled 4 x 4, passes on the render and on every texture's opposite edges: all 18 textured and patterned materials pass (the 5 flat colours and the glow have no pattern to tile).
| Name | Material | Kind, family | Tile | Glows | Moves | Textures (memory) | Real size |
|---|---|---|---|---|---|---|---|
| `toonMetal` | Toon metal | steel plate, cel | 1 m | no | no | albedo + normal 512 (683 KB) | plates 500 x 250 mm, rivets 22 mm on a 125 mm pitch |
| `toonWood` | Toon wood | timber, cel | 1 m | no | no | albedo + normal 512 (683 KB) | grain lines 4 to 8 mm wide, knots 30 to 60 mm |
| `toonStone` | Toon stone | flagstone, cel | 2 m | no | no | albedo + normal 1024 (2.7 MB) | flagstones 250 to 600 mm across, joints 25 mm |
| `toonMasonry` | Toon masonry blocks | ashlar, cel | 2 m | no | no | albedo + normal 1024 (2.7 MB) | blocks 400 to 800 mm long on 333 mm courses, joints 20 mm |
| `toonBrick` | Toon brick | brick, cel | 1 m | no | no | albedo + normal 512 (683 KB) | bricks 215 x 65 mm, mortar 10 mm (a standard brick on 75 mm courses) |
| `toonPlanks` | Toon planks | planks, cel | 2 m | no | no | albedo + normal 1024 (2.7 MB) | boards 180 mm wide, 0.6 to 1.4 m long, gaps 8 mm, nails 12 mm |
| `toonGrass` | Toon grass | grass, cel | 2 m | no | no | albedo + normal 1024 (2.7 MB) | tufts 60 to 140 mm, blades 8 mm |
| `toonDirt` | Toon dirt | dirt, cel | 2 m | no | no | albedo + normal 1024 (2.7 MB) | pebbles 15 to 60 mm, patches 200 to 500 mm |
| `toonSand` | Toon sand | sand, cel | 2 m | no | no | albedo + normal 1024 (2.7 MB) | ripples on a 125 mm spacing, specks 5 to 12 mm |
| `toonRock` | Toon rock | rock, cel | 2 m | no | no | albedo + normal 1024 (2.7 MB) | facets 200 to 700 mm, cracks 12 to 30 mm |
| `flatRoofRed` | Flat roof red | roof red, flat | 1 m | no | no | none (0) | one colour, no texture |
| `flatLeafGreen` | Flat leaf green | leaf green, flat | 1 m | no | no | none (0) | one colour, no texture |
| `flatWallCream` | Flat wall cream | wall cream, flat | 1 m | no | no | none (0) | one colour, no texture |
| `flatWaterTeal` | Flat water teal | water teal, flat | 1 m | no | no | none (0) | one colour, no texture |
| `flatTrunkBrown` | Flat trunk brown | trunk brown, flat | 1 m | no | no | none (0) | one colour, no texture |
| `paintedGrass` | Hand-painted grass | grass, hand-painted | 2 m | no | no | albedo 1024 (1.3 MB) | brush strokes 40 to 120 mm, clumps 150 to 300 mm |
| `paintedStoneWall` | Hand-painted stone wall | stone wall, hand-painted | 2 m | no | no | albedo 1024 (1.3 MB) | stones 200 to 450 mm, joints 30 mm |
| `paintedPlanks` | Hand-painted planks | planks, hand-painted | 2 m | no | no | albedo 1024 (1.3 MB) | boards 200 mm wide, gaps 10 mm |
| `paintedRoofTiles` | Hand-painted roof tiles | roof tiles, hand-painted | 1 m | no | no | albedo 512 (341 KB) | tiles 200 mm wide on 125 mm rows |
| `paintedFoliage` | Hand-painted foliage | foliage, hand-painted | 1 m | no | no | albedo 512 (341 KB) | leaf clusters 100 to 220 mm |
| `rampBrass` | Two-tone brass | brass, gradient | 1 m | no | no | albedo + normal 512 (683 KB) | hammered dimples 30 to 60 mm |
| `rampFoliage` | Gradient foliage | foliage, gradient | 1 m | no | no | albedo + normal 512 (683 KB) | leaf clusters 90 to 200 mm |
| `rampWater` | Gradient water | water, gradient | 4 m | no | rippling, flowing | none (0) | ripple rings 0.3 to 1 m, foam lines 20 mm |
| `rampWarmGlow` | Warm glow | warm glow, gradient | 1 m | yes | pulsing | none (0) | glow cells 120 to 250 mm |
### Which set paints its light into the colour
Only the **hand-painted set** has shading painted into the colour: `paintedGrass`, `paintedStoneWall`, `paintedPlanks`, `paintedRoofTiles` and `paintedFoliage` (lit tops, shaded undersides and hollows, brush-stroke light, as hand-painted games do). Their light bands are softer and their shadow lighter, so the painted shade and the scene's light do not darken twice. Every other material carries flat palette colours and drawn ink lines only, with no light or shadow in its colour; the relief of the cel and gradient sets (bevels, facets, grooves, dimples, leaf domes) lives in a normal map, so the shared light bands follow it.
### Every material's tags
- `toonMetal`: toon, cartoon, stylised, metal, steel plate, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-medium, tiled, seamless, metallic, steel, iron, plates, rivets, riveted, shiny
- `toonWood`: toon, cartoon, stylised, wood, timber, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-medium, tiled, seamless, non-metallic, beam, grain, knots, door, post
- `toonStone`: toon, cartoon, stylised, stone, flagstone, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-heavy, tiled, seamless, non-metallic, paving, path, slabs, courtyard
- `toonMasonry`: toon, cartoon, stylised, stone, ashlar, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-heavy, tiled, seamless, non-metallic, masonry, blocks, castle, wall, cut stone
- `toonBrick`: toon, cartoon, stylised, masonry, brick, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-medium, tiled, seamless, non-metallic, bricks, running bond, wall, chimney, house
- `toonPlanks`: toon, cartoon, stylised, wood, planks, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-heavy, tiled, seamless, non-metallic, boards, floor, deck, nails, fence
- `toonGrass`: toon, cartoon, stylised, ground, grass, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-heavy, tiled, seamless, non-metallic, lawn, meadow, hills, field, green
- `toonDirt`: toon, cartoon, stylised, ground, dirt, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-heavy, tiled, seamless, non-metallic, earth, soil, path, track, pebbles, brown
- `toonSand`: toon, cartoon, stylised, ground, sand, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-heavy, tiled, seamless, non-metallic, beach, desert, dunes, ripples, shore
- `toonRock`: toon, cartoon, stylised, ground, rock, cel, family-cel, cel-shaded, 3-bands, no baked light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-heavy, tiled, seamless, non-metallic, cliff, boulder, crag, mountain, cracks, grey
- `flatRoofRed`: toon, cartoon, stylised, flat colour, roof red, flat, family-flat, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 0-textures, textures-none, non-metallic, red, roof, low poly, solid
- `flatLeafGreen`: toon, cartoon, stylised, flat colour, leaf green, flat, family-flat, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 0-textures, textures-none, non-metallic, green, leaf, tree, bush, low poly, solid
- `flatWallCream`: toon, cartoon, stylised, flat colour, wall cream, flat, family-flat, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 0-textures, textures-none, non-metallic, cream, wall, plaster, house, low poly, solid
- `flatWaterTeal`: toon, cartoon, stylised, flat colour, water teal, flat, family-flat, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 0-textures, textures-none, non-metallic, teal, water, pond, lake, low poly, solid
- `flatTrunkBrown`: toon, cartoon, stylised, flat colour, trunk brown, flat, family-flat, cel-shaded, 3-bands, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 0-textures, textures-none, non-metallic, brown, trunk, tree, wood, low poly, solid
- `paintedGrass`: toon, cartoon, stylised, ground, grass, hand-painted, family-painted, cel-shaded, 3-bands, painted light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 1-texture, textures-medium, tiled, seamless, non-metallic, lawn, meadow, painted, painterly, brush strokes
- `paintedStoneWall`: toon, cartoon, stylised, stone, stone wall, hand-painted, family-painted, cel-shaded, 3-bands, painted light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 1-texture, textures-medium, tiled, seamless, non-metallic, wall, rubble, cobble, painted, painterly, brush strokes
- `paintedPlanks`: toon, cartoon, stylised, wood, planks, hand-painted, family-painted, cel-shaded, 3-bands, painted light, tile-2m, outline-ready, ink outline, not-glowing, not-animated, 1-texture, textures-medium, tiled, seamless, non-metallic, boards, painted, painterly, brush strokes, floor
- `paintedRoofTiles`: toon, cartoon, stylised, roof, roof tiles, hand-painted, family-painted, cel-shaded, 3-bands, painted light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 1-texture, textures-light, tiled, seamless, non-metallic, tiles, shingles, cottage, red, painted, painterly
- `paintedFoliage`: toon, cartoon, stylised, foliage, hand-painted, family-painted, cel-shaded, 3-bands, painted light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 1-texture, textures-light, tiled, seamless, non-metallic, leaves, tree crown, bush, hedge, painted, painterly
- `rampBrass`: toon, cartoon, stylised, metal, brass, gradient, family-gradient, gradient-mapped, colour ramp, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-medium, tiled, seamless, metallic, gold, shiny, polished, two-tone
- `rampFoliage`: toon, cartoon, stylised, foliage, gradient, family-gradient, gradient-mapped, colour ramp, no baked light, tile-1m, outline-ready, ink outline, not-glowing, not-animated, 2-textures, textures-medium, tiled, seamless, non-metallic, leaves, tree, bush, ramp
- `rampWater`: toon, cartoon, stylised, water, gradient, family-gradient, gradient-mapped, colour ramp, no baked light, tile-4m, outline-ready, ink outline, not-glowing, animated, rippling, flowing, 0-textures, textures-none, non-metallic, pond, lake, river, sea, ripples
- `rampWarmGlow`: toon, cartoon, stylised, glow, warm glow, gradient, family-gradient, gradient-mapped, colour ramp, no baked light, tile-1m, outline-ready, ink outline, glowing, emissive, animated, pulsing, 0-textures, textures-none, non-metallic, lantern, window, ember, warm, light, magic
### Vertex colours
A mesh that carries its own vertex colours (a procedural plant, a low-poly prop painted per vertex) can wear one cel material for all of them: make a material on `toonMaterials.shaders.toonSurface` with `vertex_tint = 1` and a white `base_color`, and every vertex's colour goes through the same light bands, rim and shadow tint as the library's own materials. `vertex_tint` is 0 on all 24 library materials, so meshes without vertex colours, or with colours meant for something else, are unaffected.
## Outlines and the shared look
**The ink outline.** Every material works with the ink outline on and with it off; the outline belongs to the object, not the material. Switching it on is all it takes, on a fresh start and on every player's screen: the package starts the outline on every machine that loads the world (see "How the outline starts" below), so there is nothing to prepare.
- `ToonInk.set(object, true / false)` switches one object's outline (and every part of it with a `Model`) for every player, late joiners included. `ToonInk.isOn(object)` reads it.
- A `ToonProp` component on a scene object outlines it from the scene file (`outline = true`) and maps its toon material by world position at its real tile size (`worldScale = true`), so a cube stretched into a 6 m wall shows its bricks at real size on every face. The toon corner is built this way.
- `ToonInk.add(object)` outlines on this machine only (for local objects such as the gallery's swatches).
The outline is an inverted hull drawn by the `toonInk` render feature: depth-tested against the scene, so a line never shows through a wall in front of it, and pushed out by the ink weight in real centimetres (3 cm by default) along a blend of each vertex normal and the direction from the mesh's middle, so a cube gets one closed line all the way round its silhouette. Being real thickness, it is the same weight on a small prop and on a whole house, and thins on screen with distance like any other edge.
**How the outline starts.** The engine compiles a shader on demand, when a material first waits on it, and nothing else in a world draws with the outline shader. So the package ships one small startup asset, `outline.toonStartup` (asset type `toonStartup`). The engine runs that type's load hook on every machine that loads the world: at world load, on install, and when the asset arrives from another player. The hook loads `ToonInk` and calls `ToonInk.start()`, which:
- opens the shared outline switch channel and asks the room for the switches already made, so a player who joins later, or whose machine opens the channel late, gets every outline already switched on;
- starts the `toonInk` render feature. From its first frame the feature makes its outline material on the shader's current key. That wait is what makes the engine compile the outline shader, which takes a fraction of a second, so the shader is ready before the first outline is switched on. Once a second the feature checks that its material is still on the program the engine holds for the shader, and remakes it when the shader has changed.
`ToonInk.start()` is safe to call again, and runs by itself whenever `ToonInk` is required.
**One place for the whole set's look** is `ToonLook`:
```luau
local ToonLook = require("~toonMaterials.ToonLook")
ToonLook.set({ bands = 4 }) -- four light bands on every cel, flat and hand-painted material, for every player
ToonLook.set({ outlines = false }) -- every ink outline off, for every player
ToonLook.reset() -- back to the defaults
print(ToonLook.get().bands)
```
`set` also takes `shadowLift` (how much light the darkest band keeps, default 0.45) and `rim` (the thin pale rim, default 0.18).
**The ink weight is fixed.** Every outline is drawn 3 cm thick, the same on every object for every player. `ToonLook` also stores and shares an `inkWidth` setting, but changing it does not change the line you see: a live change to the outline material's weight does not reach the drawn line (engine issue #21428). So `ToonLook.set` changes the bands, the shadow, the rim and whether outlines are on, and the outline keeps its 3 cm weight. Changes are shared through the library's `Sync`, newest write wins, and a player who joins later gets the current look. To change the defaults themselves, edit `ToonLook.DEFAULTS` and the palette (`ToonLook.PALETTE_HEX`, sRGB) and run `require("~toonMaterials.ToonCatalog").build()` (after `require("~toonMaterials.ToonRecipes").bakeAll()` when the palette changed), which writes them into every material file.
## The gallery and the toon corner
This world opens in the library's swatch gallery on the ring holding every toon material: each bay shows its material on a cube, a sphere, a shader ball and a cylinder (the cube and sphere outlined, the shader ball and cylinder plain, so each bay shows the material with the outline on and off), a floor tile and wall at real size, its reference picture beside it, and a label on one shared grid that reads from the spawn (name, kind, family and tile, textures and memory, whether it glows or moves). The toolbar switches the six lighting looks for everyone. Ahead and to the left of the spawn, in an 11 m opening of the ring (so it hides none of the labels from any spawn spot), stands a little toon corner made only from these materials: a brick cottage with a hand-painted tiled roof, a plank door and a glowing window, a stone path, a tree, grass, dirt, sand, rocks and a pond, outlines on.
In a scene of your own, in its `content()`:
```luau
local ToonGallery = require("~toonMaterials.ToonGallery")
local ToonCorner = require("~toonMaterials.ToonCorner")
entity.spawn("Gallery").component.add("ToonShowcase", { driveGallery = true, lighting = "daylight", ringGap = 11 })
local spot, facing = ToonGallery.gapSpot(11, 1.2) -- the opening ringGap leaves in the ring
ToonCorner.build({ position = spot, facing = facing }) -- the corner stands in it, facing the middle
```
## How they were made
- **Reference pictures first.** Every material has `references/<id>`, a picture generated before the material was drawn (a sample of the surface and a cube and sphere wearing it). Each material was compared with its picture side by side in the Daylight and the dark Moonlight looks and changed where they differed (the rock re-cut into big cliff facets, the painted grass and leaves redrawn, the water's ripples and the glow's core redone). A second pass in 1.0.1 closed what still differed: the brass now runs from deep bronze to bright gold with a white glint through a sky and ground reflection split, the painted stone wall's stones are the picture's mid blue-grey in charcoal joints, the darkest band is darker so the three bands read on every sphere, and the ink is one bold line all the way round as in the pictures.
- **Baked procedurally in Luau** by `ToonBaker` (forked from fantasyMaterials' FantasyBaker, MIT) and `ToonRecipes`, from the shared palette, at real size. Every map is periodic over one repeat, so it tiles by construction. `ToonEntries` is the single definition of every material; `ToonCatalog.build()` writes the materials and the collection.
- **One shader**, `toonSurface`, for all 24 (cel, painted and gradient modes; based on organicMaterials' `toonOrganic`, MIT), and `toonInk` for the outline (after the engine's `outline_hull`).
- **Searched and reused:** the library core and its checks, gallery, picker and lighting looks; the engine's `cel_shaded` material and `extended_material` shader (bands only, no shared tint or rim, so not used directly) and `outline_hull`; the toon shaders of the organic, sci-fi, woods, stone, metals and fabrics collections. The engine's screen-space outline was not used because it draws through walls in front of an object. Nothing from the other collections is a dependency.
## Tests
```luau
asset.resolve("toonMaterials.tests.toonMaterials", "testSuite"):run()
```
Seven quick tests on the library core's checks: all 24 registered and tagged, each reads as what it is (palette hues, flat colours, a legible render per family), seams on three tiled materials, the texture budget, the shared look changing all 24 at once, the outline switches, and the outline being ready with no setup (the startup asset ran, the feature is live, its material is on a compiled program within a few seconds, and a switch arriving from another player outlines the object here and takes it off again). Each runs inside the library's `Sync.isolate()`, so nothing reaches other players, and the gallery stands as it was afterwards: when a suite ends, the engine's test runner hands the world back and then lets go of what the run drew, which can blank the plaques' text, so `ToonShowcase` makes its own labels again 10 s after any gallery build. On 2026-11-01, on engine library d574006 (the one the engine runs), the suite passed 7 of 7 twice in a row in this world, and the gallery's plaques read normally afterwards; earlier that day, on engine library e70ec37, 1.0.5 passed twice in a row here and in a new world holding only the published package. The engine's runner logs about 150 to 220 "entity(...) returned nil" lines per run from its own sweep for leftover entities; they come from the runner, not from this package, and fail nothing.
## Fresh install
Installing toonMaterials puts two packages in your world. toonMaterials itself lands at `/source/toonMaterials.package`. The material library it needs, materialLibraryKit 1.4.2, comes along with it and lands in a folder of its own, `/source/deps/<world>/materialLibraryKit.package`, where `<world>` is the id of the world the library is published from (`a8c1db81-44f9-4da4-a9a5-4dc8095cdd7f`). The `deps/` folder is where an install keeps the packages it brought along for another one: leave it in place, toonMaterials needs it. Nothing else comes with it, no copies of the engine's shaders or other engine parts, because the package is published from a world on the engine library the engine runs. If you later install materialLibraryKit on its own as well, the library moves to `/source/materialLibraryKit.package`, the `deps/` folder goes away and the world still holds one library. **Then reload the world.** Until you do, the library reports problems for some of its own calibration materials (such as "material .../materialLibraryKit.package/materials/albedoRange.material does not resolve") and lists fewer than its 20, and these problems do not go away by waiting. Reloading the world clears them, and also makes outline switches from other players arrive again (#22328, see "Known limits"). Running `require("~materialLibraryKit.Materials").refresh()` also clears the library's problems.
Checked on 2026-11-01 by installing 1.0.7 from ZeroMind into a new, empty world (1.0.8 to 1.0.11 change only the texts and the materialLibraryKit release): the install brought exactly those two packages, `Materials.collections()` listed `calibration 1.4.2 20` and `toon 1.0.7 24` with no problems, and the first example above ran as written: the cube wore `toonMetal` and its ink outline, `Materials.apply(cube, "toonBrick")` swapped it, and `ToonInk.set(cube, false)` and `true` took the outline off and put it back. Installing materialLibraryKit on top was checked again on 2026-11-01 in two more new worlds, each with 0 problems, 20 calibration and 24 toon materials before it. It left one library at `/source/materialLibraryKit.package` and no `deps/` folder, but right after it the library reported problems for its own calibration materials, starting with `albedoRange` (3 in one world, with 17 of the 20 calibration materials listed; 10 in the other, with 10 listed). In the first world they were still there after 4 minutes; `Materials.refresh()` then brought it back to 0 problems and 20 calibration materials. In the second world, leaving it and opening it again (a reload) brought it back to 0 problems and 20 calibration materials. The example guide was followed step by step in another new world (see its own page for what it builds).
## Multiplayer
Applied materials (`Materials.apply`), outline switches (`ToonInk.set`), the shared look (`ToonLook.set`) and the lighting look go through the library's `Sync`, so every player sees the same, and a player who joins later is sent the current state. The outline is drawn by each player's own machine; the startup asset makes sure every machine listens for the switches and draws them, in any world that installed the package (after installing materialLibraryKit on top of toonMaterials, reload the world once first: #22328 in "Known limits"). The water and the glow animate from the shader's own clock on each machine, so they cost no traffic. The gallery and its boards are local and rebuilt the same on every machine. Another player is stood in for in the tests (a switch arriving through `Sync` from outside), since two engines signed in to one account join a room as one player (#14448).
## Gallery frame rate
- **Web (browser): 38 fps median (p50)**, 36 to 41 fps over two runs, measured by the world's owner in Chrome on a busy desktop with the whole 24-bay gallery and the toon corner standing. The gallery's own upkeep is what costs the frame in the browser (#20750); materials on ordinary scene objects in your own world do not carry it.
- **Desktop engine:** 60 to 85 fps (12 to 17 ms a frame) for the same scene.
## Known limits
Engine issues are listed by their number at github.com/OrigoZero/zero.
- **Gallery frame rate on the web (#20750).** The gallery is about 270 local entities, and the engine's per-frame upkeep of them dominates the frame in the browser: 38 fps median (36 to 41) measured in Chrome. In your own world, with the materials on ordinary scene objects, that does not apply.
- **No browser check by the author (#20946).** An agent on the desktop engine cannot start a web engine, so this release was prepared and checked on the desktop engine; the web frame rate above is the owner's measurement.
- **Long waits (#19849).** A full re-bake (`ToonRecipes.bakeAll()`) takes about 90 s and a check sweep many seconds; some calls answer late.
- **Reload the world after installing the material library on top (#22328).** When materialLibraryKit is installed on its own after toonMaterials is already in the world (the library moves from `deps/` to `/source/materialLibraryKit.package`), an outline switch sent by another player is not picked up on that machine until the world is reloaded: the object stays as it was on your screen while it changes on theirs. Reload the world once after installing the library on top; from then on outline switches arrive as usual. Until the reload, the library also reports problems for some of its own calibration materials and lists fewer than 20 of them; they do not clear by waiting, and the reload (or `Materials.refresh()`) clears them (see "Fresh install"). The same install also logs a "package collision" error (#20868). It is harmless: one library is left and it works.
- **Slow installs with several dependencies (#21420).** Installing several material collections in one call can run past a call's time limit with only some of them landed; install them one at a time.
- **Guides are not found by ZeroMind search yet (ZeroMind#3099, engine #22181).** The two guides ship inside the package and open in the engine once it is installed; a ZeroMind search does not reach them.
- **Open a guide by its full path (#22286).** `toonMaterials.package/guides/makeYourGameLookLikeACartoon` opens; the short guide name alone does not.
- **The ZeroMind description can lag a release (#19258).** After a release the description on ZeroMind can still show the previous README for a while; this README in the package is the current one.
- **Reloading the scene can save runtime things (#21023).** The gallery's swatches are temporary and rebuilt each time; check the scene file before committing after a reload.
- **Flat labels read from the front only (#21224).** The gallery's plaques face the middle of the ring; from behind a bay they read mirrored.
- **Self-lit surfaces in the debug views (#21225).** `toonSurface` does its own lighting, so the capture tool's albedo, roughness and metallic passes draw these materials magenta; the library's seam check falls back to the final render for them. Their final and normal views are right.
- **Gallery labels (#22336).** A test run can leave the gallery's plaques drawing blank text: the test runner lets go of what the run drew a few seconds after it ends. `ToonShowcase` makes its own labels again 10 s after any gallery build, which brings them back. A Text3D label whose text and size are rewritten after it first drew can also keep its first text on screen beside the new one, so `ToonShowcase` never rewrites the library's labels: it parks them out of sight and draws its own, each made once with its final text.
- **A push can report a timeout and still land (#21025).** Check the world's commits before pushing again.
- **The ink weight does not change live (#21428).** Setting `ToonLook.set({ inkWidth = ... })` is stored and shared, but the outline keeps drawing at 3 cm: a property change on the outline material does not reach the drawn line. The weight is the same 3 cm on every object and every player.
- **The outline is a hull.** It outlines silhouettes, not creases inside a shape, and a flat single-sided surface (a floor tile seen from above) has no outline. Its weight is real thickness (centimetres), so it thins on screen with distance.
- **No outline on skinned characters.** The outline is drawn for parts with a `Model`. An animated, skinned character (such as the engine's Fox) takes a toon material but no ink outline; characters built from plain model parts (such as the engine's alien) take both.
- **The outline shader compiles on demand.** The engine compiles a shader only when a material waits on it. Up to 1.0.1 nothing did that for the outline shader on a fresh start, so outlines stayed invisible until something prepared it by hand, and other players never saw them. Since 1.0.2 the outline feature makes its material on the shader's key from its first frame, on every machine, which is what asks for the compile. A material also keeps the program it was made with, and a render feature can draw nothing after an engine restart (#21424), so the feature checks once a second and remakes its material on the program the engine holds.
- **Keep `outline.toonStartup` in the package.** It is what starts the outline on every machine. Without it, only machines whose own code requires `ToonInk` hear the switches and draw outlines.
- **World mapping is per face direction.** `ToonProp`'s `worldScale` projects along the main axis of each face, so on a sphere the pattern meets itself at the diagonals.
## Version history
- **1.0.11 (2026-11-08):** built against materialLibraryKit 1.4.3 and the current engine library, so an install no longer carries an older copy of either. No material changed.
- **1.0.10 (2026-11-01):** the package description says how to install the package and how to use it first. Nothing else changed.
- **1.0.9 (2026-11-01):** README fix. "Fresh install" said that after installing materialLibraryKit on top the library's problems clear by themselves after a few seconds. They do not: they stay until the world is reloaded (or `Materials.refresh()` runs), and the README now says that is the step to take, in "Fresh install", "Use it together with the material library" and the #22328 known limit. Everything else is unchanged.
- **1.0.8 (2026-11-01):** text fixes only. "Fresh install" now says what an install really puts in a world: toonMaterials, and the material library in a folder of its own under `/source/deps/` (it said, wrongly, that no `deps/` folder was made). "Use it together with the material library", the multiplayer section, the how-to guide and the package description point to a new known limit: after installing materialLibraryKit on top of toonMaterials, reload the world once (#22328). The gallery labels limit cites the open issue #22336. Materials, shaders, code, tests and the material library are unchanged, so the toon collection and the material files still say 1.0.7.
- **1.0.7 (2026-11-01):** no copies of engine parts. 1.0.6 was published from a world on an older engine library (e70ec37) than the engine now runs, so installing it put five copies of engine parts (the lit and unlit shaders, the shadow pieces and the engine bindings) in a `deps/` folder. This world is now on the engine library the engine runs (d574006) and 1.0.7 is published from it: a fresh install brings toonMaterials and the material library and nothing else. The version every place shows is 1.0.7. Materials, colours, outline, guides, the material library (1.4.2) and texture memory are unchanged.
- **1.0.6 (2026-11-01):** moved onto the current material library, materialLibraryKit 1.4.2 (was 1.3.1). Before, installing toonMaterials and then the current library left two packages named `materialLibraryKit` in the world and the library could not be used at all; now either order leaves one library, the current one. New README section "Use it together with the material library". The version every place shows is the release: the toon collection, `Materials.collections()` and the material files said 1.0.3 and now say 1.0.6. The 7 tests pass on the new library. Materials, colours, outline, guides and texture memory are unchanged.
- **1.0.5 (2026-11-01):** two guides ship in the package: "How to make my game look like a cartoon" and "Make a cartoon game scene from an empty world" (a cel-shaded village with characters, props and ground). Rechecked on today's engine library (e70ec37): the first example and all 7 tests pass, twice in a row, here and in a new world. The gallery's plaques no longer stay blank after a test run (today's test runner lets go of what a run drew after it ends; `ToonShowcase` now makes its labels again 10 s after any gallery build). Text fixes: `ToonProp` (not a `ToonOutline` that never existed) outlines a scene object from the scene file; the known limits name skinned characters, which take no outline. Materials, colours, outline, the bands and texture memory are unchanged.
- **1.0.4 (2026-10-31):** `toonSurface` takes vertex colours when asked: a new `vertex_tint` property (0 by default, so every existing material looks exactly as before) multiplies the mesh's vertex colours into the colour at 1. One cel material can then paint a whole mesh whose vertices carry their own colours, such as procedurally built plants (cropsKit's cosy look uses it). Nothing else changed.
- **1.0.3 (2026-10-27):** a clean start. `ToonInk` started the outline renderer while it was still loading, and the renderer's code requires `ToonInk`, so every fresh start logged two "cyclic require detected" errors and a warning that the renderer could not start, until a later switch started it. `ToonInk` now opens its switch channel at load and starts the renderer one frame later. The README and the world description no longer promise a live change of the ink weight: it stays at 3 cm (engine issue #21428, now in the known limits). Materials, colours, outline switching, the bands and texture memory are unchanged.
- **1.0.2 (2026-10-27):** the outline shows by itself, for everyone. On a fresh start the outline shader was never compiled, because the engine compiles on demand and the outline feature only made its material once a compiled program existed, so it waited forever. Other players' machines also never loaded the outline module, so they never drew the rim. Now the new `outline.toonStartup` asset (type `toonStartup`) starts `ToonInk` on every machine at world load. Its channel asks the room for the switches already made, and the outline feature makes its material on the shader's key from its first frame, which has the shader compiled within a fraction of a second. A seventh test checks both. Materials, colours, outline switching, the shared look and texture memory are unchanged.
- **1.0.1 (2026-10-27):** the review fixes. The ink outline is one closed line all the way round every shape, pushed out by 3 cm of real thickness in the shader's object-space hook. In 1.0.0 it was written in the clip-space hook, which the render feature's geometry pass never runs, so only the hull's back faces peeked out on one edge; and after an engine restart the outline material could wait forever for its shader, which left the outlines invisible. The feature now binds its material to the shader's current program, and the gallery and `ToonProp` put their ink back by themselves if a reload drops it. The gallery's labels are the showcase's own, made once with their final text, so no plaque shows the library's text underneath. The darkest light band keeps less light (0.45, was 0.6) under a calmer cool tint, so the bands read on every sphere. Two-tone brass runs from deep bronze to bright gold with a white glint; the hand-painted stone wall is mid blue-grey as in its picture. The corner's tree crown is all foliage (the plain green blob is gone). The corner stands in an opening of the gallery ring (`ToonShowcase`'s new `ringGap`, `ToonGallery.gapSpot`), so every label reads from every spawn spot. `ToonProp` puts an object's ink back by itself if a module reload drops it. Same 24 materials, names, tags and texture memory.
- **1.0.0 (2026-10-27):** first release: the 24 materials, their reference pictures, `toonSurface` and `toonInk`, `ToonLook`, `ToonInk`, `ToonProp`, `ToonShowcase`, `ToonCorner` and the six tests.
# impactFrames: anime impact frames and smears for any look
**Anime and manga hit impact frames for any game**, shown on every player's screen at once and safe for photosensitive players by default (at most three full-screen flashes a second). Nine styles: inverted flash, black and white negative, radial burst, colour pop, speed lines, white flash, slash, a held hit pose and a sumi-e ink splash, plus smears that stretch a fast swing. Works with any look, anime or not.
**Get started:** install impactFrames, then where a hit is decided
```luau
require("~impactFrames.ImpactFrames").play("speedBurst", { entity = target })
```
It brings styleKit and frameTiming along. Version 1.1.1; the history is at the end.
## First impact in a few minutes
1. Install **impactFrames** from ZeroMind (search "anime impact frames"); it brings styleKit and frameTiming along.
2. Call it where a hit is decided, on that one machine (in play, the owner of the attacker), for example from a component's own hit handler:
```luau
local ImpactFrames = require("~impactFrames.ImpactFrames")
-- inside your component, when this attacker's hit connects with `target`
local function onHit(target: any, heavy: boolean)
if heavy then
ImpactFrames.play("slash", { entity = target, angle = 0.5 })
else
ImpactFrames.play("speedBurst", { entity = target })
end
end
```
To see one straight away, run `require("~impactFrames.ImpactFrames").play("radialBurst", { screen = { 0.5, 0.5 }, duration = 3, localOnly = true })` with the `execute` tool and capture it with `capture { source = "presented" }` while it shows (styleKit draws on the presented frame only).
3. For smears, add the `Smear` component to a fast object (a sword, a ball, a dashing player): it smears it whenever it moves faster than `minSpeed` (9 m/s).
4. Already using juiceKit for shake and hitstop? `ImpactFrames.rideJuice(require("juiceKit.juice"))` once, and every juice hit brings its impact frame along (see Riding along with juiceKit).
## Impact styles
| Style | What it draws | Counts as a flash |
|---|---|---|
| `invert` | The whole picture as a hard, cold negative, sparse pale rays out of the hit. | yes |
| `silhouette` | Subjects as flat shapes: `variant` `"blackOnWhite"` (default), `"whiteOnBlack"`, or `"redWhite"` (black subjects on white with red rays behind them). Subjects found by depth (`split = "depth"`, what stands nearer than the hit plus a few metres) or by brightness (`"luma"`). | yes |
| `radialBurst` | Bold rays and a shock ring bursting from the hit over a darkened negative ground; `variant = "rays"` keeps the picture and draws the rays only. | yes (`"rays"`: no) |
| `colourFlip` | The picture's tones as three flat colours: ink darks, a red middle band, pale lights; `variant = "reversed"` flips the tones. | yes |
| `speedBurst` | Thin ink focus lines closing in from the edges on the hit, a clear oval around it. | no |
| `whiteFlash` | The frame blown out to white, brightest at the hit, subjects left as a faint grey print. | yes |
| `slash` | A bright blade cut across the frame through the hit at `angle` (radians on screen, default 0.6), the picture on each side knocked apart along the cut and pushed to two flat tones, thin accent echoes beside the blade. `variant = "light"` reverses the tones. | yes |
| `holdPose` | The held hit pose: the character hit (`entity`) and the `attacker`, when given, freeze on the drawing of the hit while their movement, physics and the controls run on (frameTiming's `holdPose`), framed by a few bold dark wedges with a wide clear space round the hit (since 1.0.8; before, the same fine lines as `speedBurst`, so the two could not be told apart). | no |
| `inkSplash` | Sumi-e ink on paper: the picture washed to black ink, a dry brush stroke torn through the hit at `angle`, and with `variant` `"splash"` (default) a ragged burst of ink with splatter spokes and drops; `"stroke"` is the stroke alone. Ink and paper only, never red, for bloodless takedowns and final blows. | yes |
`ImpactFrames.play(style, opts)` options:
- `at` (a world point), `entity` or `screen` (`{ u, v }`, 0 to 1 from the top left): where the hit is. Each player's machine projects a world point through its own camera at the moment the hit starts.
- `strength` (0 to 1, default 1), `duration` (seconds; defaults: invert 0.125, silhouette 0.17, radialBurst 0.25, colourFlip 0.125, speedBurst 0.35, whiteFlash 0.1, slash 0.2, holdPose 0.28).
- `variant`, `split` as in the table; `angle` (slash); `attacker` (holdPose); colours `ink`, `paper`, `accent` (`"#rrggbb"` or `{ r, g, b }`); `settings` (any raw block setting, e.g. `{ lines = 90, lineWidth = 0.3, clear = 0.2 }`); `seed` (the drawings, the same on every machine).
- `delay` (seconds: every machine starts at the same future moment), `localOnly` (this screen only), `downgrade = false` (drop a flash over the budget instead of drawing the rays variant).
**Drawn on the held clock.** A hit is laid once, with its start on styleKit's held clock (the stack's `holdRate`, drawings a second: 8 for TV anime, 12 for 80s OVA and action), and the shader steps its rays and lines and fades it on that clock by itself. Nothing is written while it shows, its lines step like drawn animation rather than crawling per frame, and an impact keeps the look's own drawing rate.
Up to three impacts show at once; a fourth replaces the oldest. `ImpactFrames.stop()` takes them all off; `active()` lists them; `stats()` counts plays, flashes drawn, downgraded and dropped, sent and received.
## Riding along with juiceKit (Juicebox)
impactFrames does not remake camera shake, hitstop, squash or sparks: juiceKit does those. A game that already plays juiceKit presets gets impact frames on its hits with one line, once, on every machine (a component's `start`, or the scene's entrypoint):
```luau
ImpactFrames.rideJuice(require("juiceKit.juice"))
```
From then on every `Juice.play(preset, target)` this machine makes for a mapped preset also plays its impact frame on the same target, sent to every player like any `play` (on this screen only when the juice play is `scope = "local"`), under the same flash limit. The map (`ImpactFrames.JUICE_MAP`): `punch` and `hitLight` speed lines, `hitHeavy` radial burst, `hitCritical` black and white silhouette, `explosionSmall` white flash, `explosionLarge` invert, `death` colour pop. Change it with `rideJuice(Juice, { map = { hitCritical = "slash", punch = false } })`; `strength` scales every ridden impact (0.9). `ImpactFrames.stopRidingJuice()` puts `Juice.play` back exactly; `ridingJuice()` reports the map and how many impacts it played.
The other way round works too: `ImpactFrames.onHit(fn)` calls `fn(style, hit)` for every impact a machine draws (its own and other players', `hit` = `{ at, entity, screen, strength, variant }`), so `ImpactFrames.onHit(function(_, hit) Juice.play("hitstopLight", nil, { scope = "local" }) end)` hangs juiceKit's hitstop off every impact.
## Smears
`Smears.play(entity, style, opts)`, per object:
- `stretch`: the object drawn once, stretched back along its motion over the ground it just covered (and thinned across it), while the real one is hidden for those frames (0.06 s).
- `multiples`: `count` (3) ghost copies at the places it just passed, fading toward `colour` (a pale blue white), the farthest going first (0.12 s).
- `streaks`: `count` (7) speed lines behind it in `colour` (a warm white), of random lengths and offsets around its outline (0.16 s).
`opts`: `velocity` (m/s; a `Smear` component on the object measures it when left out), `duration`, `count`, `length` (1), `colour`, `seed`, `localOnly`. Ghosts are temporary, unsynced copies of the object's meshes (its `Model`s and its children's), so they work on any object without setup and are never saved.
The `Smear` component smears its object whenever it moves faster than `minSpeed`, at most once per `cooldown` (0.15 s) so a long fast move smears in beats: `style` `stretchAndStreaks` (default), `multiplesAndStreaks`, `stretch`, `multiples` or `streaks`; `count`, `length`, `colour`; `inEdit` to see it while moving things by hand.
## Photosensitivity
On by default, for every player, and not something a world can turn up:
- **At most 3 full-screen flashes in any one second.** A flash is any impact that changes most of the screen's brightness: `invert`, `silhouette`, `radialBurst` (its default flipping form), `colourFlip` and `whiteFlash`. Every flash takes a token from a rolling one-second window on each player's machine (the hits of every player count against the same screen). When the window holds 3, a further flash is **downgraded** to the radial burst's rays-only form (no brightness flip, the picture kept underneath, at 80 percent) or, with `downgrade = false`, **dropped**. The cap cannot be raised above 3; `maxFlashesPerSecond` only lowers it, and 0 turns every flash into the rays-only form.
- **Never a saturated red screen.** The colours that fill large areas (`ink`, `paper`) are held to a saturation of 0.35 by ImpactFrames and, in the shader, to a red share of r+g+b of at most 0.65 (WCAG 2.3.1 counts 0.8 and above as saturated red); the colour flip's red middle band uses the accent held the same way. Saturated accent red is only drawn as rays and lines over part of the frame.
- **Smears that cover a large area spend from the same budget**: a smear of an object filling more than about a third of the screen's height takes a flash token, and is left out when none is left.
- **Gentle mode, per player.** `ImpactFrames.setSafety({ gentle = true })` draws every flash at low contrast, tinted toward the picture, only around the hit (its edges fade out by a third of the screen), at 60 percent strength, twice as long with a gradual fade, and halves the ghosts and lines of smears. Non-flashing styles are softened a little too.
- **Settings are the player's own.** `ImpactFrames.setSafety({ maxFlashesPerSecond = 0..3, gentle = bool })` applies on this machine only and is saved in the player's own store (`runtime_data.player(...)`, path `prefs/impactFrames`) when they are signed in, so it follows them to the next session; `ImpactFrames.safety()` reads it. Put a toggle in your settings menu that calls it. The engine's own System settings menu cannot take world settings, so the toggle is the world's to show.
- **Measured, from what is drawn.** `ImpactFrames.flashLog()` lists the moment each full-screen flash was laid on this screen and the most that started inside any one second. In the showcase, in play, ten flashing hits landing in the same frame drew 3 flashes (7 became rays), ten hits a tenth of a second apart drew 3, and ten presses of E at the training dummy never drew more than 3 inside any second. The test suite checks the first two on every run.
- **Measured under heavy load (12 November 2026, showcase, in play, impactFrames 1.0.3 on styleKit 1.7.8):** 30 hits of mixed styles in one frame, then 3 hits every frame for four seconds, 144 hits in 5.7 seconds in all, drew 12 full-screen flashes, never more than 3 starting inside any one second (`flashLog().maxInAnySecond` = 3: three at the start, then three at 1.04 s, two at 2.09 s and one at 2.35 s, two at 3.16 s and one at 3.53 s). Every other hit was drawn as its non-flashing rays form.
What is not guaranteed: juiceKit's own screen flashes (from a preset you play in `onHit`) go through juiceKit, not this limiter; turn its flash off in the preset or rely on its reduce-motion setting. Full-screen effects other packages draw are not counted unless they call `ImpactFrames.takeFlash()`.
## Multiplayer
`ImpactFrames.play` on one machine sends one small reliable message (`impactFrames.play`: the style, the hit's world point or synced entity, the options, the seed and the start time in wall-clock UTC) to every other player in the room. Each machine projects the hit through its own camera, draws the same drawings (same seed) and starts at the same moment: a message that arrives late starts part way into the hit, one that arrives after the hit ended is dropped. `delay = 0.08` starts every machine at the same future moment, the sender included, for a hit landing on every screen in the same frame. Call `play` on ONE machine per hit (where the hit is decided, usually the attacker's owner); `localOnly = true` keeps it on this screen (a hit only this player feels, a menu preview). Each receiving player's own limiter and gentle setting apply to what they see.
Smears: the `Smear` component runs on every machine from the object's own motion and sends nothing. `Smears.play` on a synced object is sent the same way (`impactFrames.smear`) unless `localOnly`.
Checked with two players in one play session of the showcase (12 November 2026): a `radialBurst` played on the first player's machine reached `onHit` on both machines, a `speedBurst` played there with `localOnly = true` reached the first player only, and both machines drew through `setLocalEntry` (`ImpactFrames.mode()` = `"localEntry"`), so nothing of a hit entered the shared stack.
## Cost
- **Idle.** With styleKit 1.7.0 or later nothing of impactFrames is in the stack until a hit plays, and it is taken off when the hit ends: an idle world pays no GPU for it. With an older styleKit one dormant entry sits in the shared stack between hits (see Known limits); its pass leaves at once while no hit shows, but the stack still runs it every frame.
- **Active:** one full-screen post-process pass per showing impact (one shader for all eight styles), measured in the Anime Looks showcase at 2097 x 1453 on the development machine's GPU at about the cost of a finish pass (0.2 to 0.3 ms there; the scene's own sky pass costs 0.39 ms on the same GPU). The settings are written once per hit, not per drawing.
- Measure on your device: `zero profiler gpu` while an impact shows (`ImpactFrames.play("radialBurst", { screen = { 0.5, 0.5 }, duration = 5, localOnly = true })`), the row `post.sk.impactFrames...`.
## Known limits
- **Two copies of styleKit in one world.** A game that held an older styleKit when impactFrames was installed keeps that copy, and it goes on drawing the scene's stack; a hit laid through impactFrames' own copy is then never drawn. `ImpactFrames.play` notices (the shared stack holds live entries its own copy draws none of, for more than 3 s), warns once and returns false with the reason, instead of reporting a hit nobody sees. Updating the game's styleKit afterwards, or reinstalling, does not merge the two copies (checked on Summit Sprint, which held styleKit 1.4.4; reported to ZeroMind as 01M77X5XNF6KAJ8TWXWCEB91J4), so update the Style Cookbook packages before installing impactFrames.
- **A styleKit older than 1.7.0 needs one entry in the shared stack.** impactFrames lays its blocks on each machine only with `StyleKit.setLocalEntry`, which this world sent to the Style Cookbook as pull request #10 and the Cookbook released in styleKit 1.7.0. On an older styleKit (which has only `setLocal`, settings over an entry already in the shared stack) the first hit adds one dormant entry (`impactFrames`, drawing nothing between hits) to the scene's stack, and hits are drawn by laying settings over it on each machine; `ImpactFrames.prepareStack()` adds it ahead of time, `ImpactFrames.mode()` says which way this world draws. In that mode only one impact shows at a time (the newest).
- **First hit after an idle spell may land a frame late.** With no other look, styleKit starts its render feature on the first impact and releases it after the last.
- **Each frame is redone from scratch.** A styleKit render feature redoes all its work every frame (engine issue #24548), so an active impact costs its full pass on every frame it shows, held drawing or not.
- **A setting written before the shader finishes compiling reads back as the default** (engine #22741): the very first hit after the world opens can show with default colours for its first drawing.
- **No history, motion vectors or normals.** Post effects get no history, velocity or normal inputs (engine issue #17427), so smears are drawn with ghost geometry rather than a screen-space smear along motion vectors, and the silhouette splits subjects by depth or brightness rather than by object.
- **Draw order and blending are the stack's.** A render feature cannot choose the depth of its pass in the frame or its blend state (engine issues #24550, #24551): impact frames draw after every styleKit block and before the UI, never over the UI and never under a particular block.
- **juiceKit's own screen flash is juiceKit's.** A juice preset that flashes the screen (its `flash` piece) goes through juiceKit, not this limiter; turn its flash off in the preset, or rely on juiceKit's reduce-motion setting, when it rides along.
- **The hit point is projected once**, when the hit starts; a hit of a few tenths of a second does not follow an entity that moves across the screen during it.
- **The held hit pose holds skeletons** (the drawn pose of a skinned character); a rigid prop's mesh is not frozen.
- **Transparent things and particles** are not in the depth, so the depth silhouette treats them as what is behind them.
- **Smear ghosts copy `Model` meshes only.** Skinned characters (`SkinnedModel`) are not copied by `stretch` and `multiples`; use `streaks` on them, or smear a weapon or limb that is a `Model`.
- **A stretched smear relies on a non-uniformly scaled, rotated parent** to shear the copy along the motion; it reads correctly for compact objects and loosely for long thin ones moving along their length.
## Contents
- `ImpactFrames` (module): `play`, `stop`, `active`, `styles`, `stats`, `resetStats`, `onHit`, `rideJuice`, `stopRidingJuice`, `ridingJuice`, `setSafety`, `safety`, `takeFlash`, `receive`, `prepareStack`, `mode`, `setDryRun`, `laid`, `step`, `ensureDriver`.
- `Smears` (module): `play`, `noteVelocity`, `stats`, `clear`, `step`.
- `Smear` (component): smears its object on speed.
- `ImpactFramesDriver` (component): the per-frame step, spawned for you on a hidden temporary entity.
- `blocks/`: the seven Medium-slot style blocks (`impactInvert`, `impactSilhouette`, `impactRadialBurst`, `impactColourFlip`, `impactSpeedBurst`, `impactWhiteFlash`, `impactSlash`) on one shader, `impactFrame.shader`. Each passes `StyleKit.checkBlock`. (`holdPose` draws with the speed burst block, with its own few bold wedges.)
- `tests/impactFrames.testSuite`: the limiter, every style playing and ending, a hit laid once on the held clock, riding along with juiceKit, gentle mode, the colour guard, another player's hit starting at its sent moment, and every smear style (impacts as a dry run that draws nothing, so it is safe on any screen; `ImpactFrames.setDryRun(true)` gives your own tests the same).
## Version history
Now **1.1.1** (1.1.1: the inkSplash block ships with its metadata; 1.1.0: a new `inkSplash` style, a sumi-e frame for a bloodless decisive blow: the picture washed to black ink on paper, a dry brush stroke torn through the hit and, as `variant = "splash"`, a burst of ink with splatter and drops (`"stroke"` is the stroke alone); ink and paper only, never red; made for takedownKit's ink-splash presentation; 1.0.9: a short description and a lead that says what it gives and how to start, with the history moved here; `ImpactFrames.VERSION` reports the package's version again (it said 1.0.6); 1.0.8: `holdPose` frames the frozen character with a few bold wedges, so it no longer looks like `speedBurst` in the moment of a hit; 1.0.7 moves to styleKit 1.7.9, which costs the engine less per frame; 1.0.6 moved to frameTiming 1.0.3, whose timing any player can set) (on styleKit 1.7.9, the Style Cookbook release of 2026-11-12, which has `setLocalEntry`, so each impact is laid on each machine with nothing dormant in the shared stack; 1.0.1 added `flashLog()`, the measured flash count, and its test). Works with any styleKit look (anime, watercolor, pencil, none at all): each impact is a styleKit Medium-slot block laid on each player's machine for the few frames it shows. Built on **styleKit** (the blocks) and **frameTiming** (the held hit pose); rides along with **juiceKit** (the Juicebox kit) when a game uses it, without depending on it.