# animeBlocks: anime looks you stack from parts
**Make any 3D game look like anime.** Seven ready looks (TV anime, 80s OVA, soft modern, chibi, action, night city, golden hour), each built from parts you swap with one call: a cel light, a rim, a highlight shape, an ink line, a film finish and a painted anime sky. The look lives in the scene, so every player sees the same thing, and it stacks with every Style Cookbook block (anime on paper, an ink wash line, a watercolour sky).
**Get started:** install animeBlocks, then run once
```luau
require("~animeBlocks.AnimeBlocks").apply("tvAnime", { sky = true, timing = true })
```
It brings styleKit, toonBlocks, paintedSkies (painted skies) and frameTiming (animation on twos) along. For hit impact frames, install **impactFrames** too. Version 1.0.23; the history is at the end.
## Your scene in anime in five minutes
1. In ZeroMind search "anime look" and install **animeBlocks** into your world (it can take a minute: it brings four packages along, engine #21420). **If your world already uses a Style Cookbook package** (styleKit, toonBlocks, inkBlocks, paperBlocks, watercolorBlocks, styleRoles and so on), update those first, before installing animeBlocks (`zeromind.update` on each, or the ZeroMind panel's updates), so animeBlocks finds the styleKit it needs already there and the world keeps one copy. Installed the other way round, the world keeps two copies of styleKit: the look still shows, but impact frames are never drawn, and updating or reinstalling afterwards does not merge the two (see Known limits). `AnimeBlocks.check()` says whether this is the case, and `apply` warns about it.
2. Run this once, from the `execute` tool or any script (it is saved with the scene):
```luau
local AnimeBlocks = require("~animeBlocks.AnimeBlocks")
AnimeBlocks.apply("tvAnime", { sky = true, timing = true })
```
3. Press play. Every player who joins (from your scene's normal player setup: nothing about them changes) sees the same look, because the look lives on a synced `StyleStack` entity in the scene. `sky = true` puts the look's painted sky in the scene (it replaces the engine sky while it is there); `timing = true` sets the look's frame timing as the scene default.
4. Swap a part: `AnimeBlocks.useLine("animeLine80s")`. Swap the whole look: `AnimeBlocks.apply("ova80s", { sky = true })`. Take it all off: `AnimeBlocks.remove()` clears the stack, takes the painted sky off (the scene's own sky and light come back) and takes the scene-wide frame timing off, for every player; characters you put on a timing yourself with `FrameTiming.set` keep it (`FrameTiming.clear(e)` takes that off).
5. On a tight budget: `AnimeBlocks.fast(true)` draws the whole look with one engine screen effect (about 1.3 ms of the engine's own time on average at 2097 x 1409 with 2,500 things, 0.5 ms of it GPU, but not under 1 ms every time; it keeps the tones, highlight shape, rim, silhouette line and grade, and gives up the inner lines, film finishes and per-character controls, see What it costs).
Look at it with `capture { source = "presented" }`: offscreen captures show the scene without the look.
### In a new world, in this order
1. **Install** animeBlocks (and impactFrames for hits) from ZeroMind.
2. **Apply a look:** `AnimeBlocks.apply("actionAnime", { sky = true, timing = true })`. Every look reads well with no options at all; `sky` and `timing` add the sky and the drawing rate it was made with.
3. **Set each character** that needs it: `AnimeBlocks.setCharacter(hero, { clean = 1 })` keeps a face lit, `AnimeBlocks.markHair(hair)` and `AnimeBlocks.addHairShine()` add the ring on hair. Skip this for crowds: the look already covers everyone.
4. **Add timing and hits:** `timing = true` above puts every character on the look's timing at once; `FrameTiming.set(hero, "ones")` changes one. Hits: `ImpactFrames.play("speedBurst", { entity = target })` (which style for which hit: the guide "Anime look for an action game").
5. **Check it worked:** `AnimeBlocks.check()` answers true, the message `apply` returned names the sky and timing it set (see "Did the sky take?"), and `capture { source = "presented" }` shows the look.
**Did the sky take?** `apply(id, { sky = true })` lists `sky <preset>` in the message it returns only when the painted sky really went on, and `require("~paintedSkies.PaintedSkies").current().preset` names it. If it did not take, the message has no `sky` part, the log says `AnimeBlocks: sky <id> not set` with the number of presets paintedSkies found, and you keep seeing the scene's own engine sky (often a plain gradient). Found no presets at all means an old paintedSkies install: update paintedSkies (1.0.5 or later).
**Lots of characters?** Nothing to change: the look is drawn over the whole frame, so it costs the same for one character or two hundred. What does grow per character is per-character controls in the default look (`setCharacter`, hair marks, objects kept as rendered): keep those for heroes. Set the timing once for the scene (`timing = true`) rather than on each character. In a browser, or when the frame is tight, use `AnimeBlocks.fast(true)`.
## The ready-made looks
| Look | In one line | Light | Rim | Highlight | Line | Finish | Sky, timing |
|---|---|---|---|---|---|---|---|
| `tvAnime` | A TV anime episode: hard two-tone cel shading, lavender shadows, a thin black line. | `animeCelTV` | `animeRimThinWarm` | `animeStreak` | `animeLineTV` | `finishClean` | `clearBlue`, twos |
| `ova80s` | A 1980s OVA on film: deep violet shadows with a second highlight step, a heavy contour, grain, halation and soft bloom. | `animeCel80s` | `animeRimBackLight` (amber) | `animeStreak` | `animeLine80s` | `finishFilm80s` | `toweringClouds`, threes |
| `softModernAnime` | A current anime film: three soft tones, a faint grey line, glowing light. | `animeCelSoft` | `animeRimBackLight` (soft) | `animeRoundGlint` | `animeLineSoft` | `finishSoftBloom` | `summerClouds`, ones |
| `chibiAnime` | Cute chibi: soft round light, pale peach shadows, lit faces, round coloured lines. | `animeCelChibi` | `animeRimThinWarm` (pink) | `animeRoundGlint` | `animeLineColour` | `finishSoftBloom` (pastel) | `pastelDawn`, twos |
| `actionAnime` | A fight scene: punchy three tones, hot highlights, a wide back light, brushy action lines. | `animeCelAction` | `animeRimBackLight` | `animeBladeShine` | `animeLineAction` | `finishClean` (contrasty) | `summerClouds`, mixedAction |
| `nightCityAnime` | A neon night city: blue night light, magenta neon rims, coloured lines, bloom round every light. | `animeCelNight` | `animeRimColour` | `animeStarGlint` | `animeLineColour` | `finishSoftBloom` (strong) | `neonNight80s`, twos |
| `goldenHourAnime` | The golden hour of an emotional film scene: warm gold light, plum shadows, a glowing back light, a crescent glint, warm bloom. | `animeCelGolden` | `animeRimBackLight` (warm) | `animeCrescent` | `animeLineColour` | `finishSoftBloom` (warm) | `goldenSunset`, twos |
Each has a short guide ("TV anime look", "80s OVA anime look", "Soft modern anime look", "Chibi anime look", "Action anime look", "Night city anime look", "Golden hour anime look") and is a `styleLook`, so `StyleKit.applyLook("ova80s")` applies the stack alone.
### The four main looks beside what they are
Pictures taken on 12 November 2026 in the forest plaza showcase, from the player's view in play (presented frames); each is in the Anime Looks world's gallery and in its `media/` folder.
- **TV anime** (`media/look_tvAnime.texture/look_tvAnime.jpg`). What it is: the look of a weekly TV episode, painted fast and flat: every surface is either lit or in shadow with nothing between, the shadow is a cool lavender rather than grey, the line is thin, even and black, and highlights are simple hard shapes. What the picture shows: the stone, the coat and the balls cut into one lit tone and one lavender shadow, a thin black outline on every silhouette, a double streak on the red ball.
- **80s OVA** (`media/look_ova80s.texture/look_ova80s.jpg`, under its towering clouds sky). What it is: a 1980s straight-to-video release shot on film: hand-painted cels with hard, deep violet shadows and strong saturated colour, a heavy dark contour, a warm back light, and a film print you can see: grain, an orange halation glow bleeding round bright light, soft bloom. What the picture shows: a heavy contour round the character and the balls, saturated red, visible grain over the whole frame, orange halation round every bright gap in the trees, hard violet cels on the stone.
- **Soft modern anime** (`media/look_softModern.texture/look_softModern.jpg`). What it is: a current anime film: three soft tones with gradient edges, gently coloured shadows, a fine grey line that fades with distance, small round catch-light glints and a glow of light diffusion over everything. What the picture shows: softer shadow edges than TV anime, a fainter and thinner line, a round glint on each ball, a slight glow on bright parts.
- **Chibi** (`media/look_chibi.texture/look_chibi.jpg`). What it is: cute super-deformed comedy: pastel colour, soft round light, warm peach shadows that never go dark, coloured lines instead of black ones, everything friendly. What the picture shows: the whole plaza in pale pastel pink and peach, no dark shadow anywhere, outlines tinted from each object's own colour (rose on the stone, brown on the boots), a round white glint.
A whole-look switch can show the previous look's settings for a few seconds while the new effects settle (see Known limits); every picture was taken after it settled.
## The parts
Every part is a family of blocks that run one shader with their own defaults, so any block of a family swaps for any other with one change (`StyleKit.swap(entry, block)`, or `{ keepSettings = true }` to carry tuning across). Each block's README lists every setting it takes and what it does, how it treats every kind of content, and what it gives up in motion; `StyleKit.settingsOf("<block>")` gives the same with defaults and ranges.
### Cel light (`light` entry, Light slot), `AnimeBlocks.useLight(id)`
| Block | What it is |
|---|---|
| `animeCelTV` | Two-tone hard shadow: every surface lit or in shadow, cool lavender shadows. |
| `animeCelSoft` | Soft three-tone ramp with a soft gradient edge. |
| `animeCelPastel` | Pastel modern: light rose shadows that stay coloured, never grey. |
| `animeCel80s` | Hard-edged 80s OVA cels with a second, lighter highlight step. |
| `animeCelChibi` | Soft round chibi: two warm tones, a very soft wide edge, peach shadows that never go dark. |
| `animeCelAction` | Punchy action: three hard tones, deep cool shadows, a hot highlight step. |
| `animeCelGolden` | Warm golden-hour light for emotional scenes. |
| `animeCelNight` | Blue night light with the lit side still readable. |
Settings that matter: `tones` (2 or 3), `shadowAt`, `deepAt`, `edge` (0.01 a hard cel edge, 0.1 a soft gradient), `litColour`, `shadowColour`, `deepColour`, `shadowSaturation` (shadows richer in colour than the light), `highStep` and `highAt` (the second highlight step), `warmth`, `faceClean` and `faceShadow` (clean faces), `shape`, `shadeLevel`, `castBelow` (how the light is redrawn cleanly from the sun, toonBlocks' toon light), `fullLight`, `keepLightColour`, and a built-in rim (`rimWidth`, `rimStrength`, `rimColour`, `rimSide`; off unless `lean` folds the rim into it).
### Rim (`rim` entry), `AnimeBlocks.useRim(id)`
| Block | What it is |
|---|---|
| `animeRimThinWarm` | A thin, hard band of warm light along every silhouette. |
| `animeRimBackLight` | A wide pale back light on the side turned from the sun. |
| `animeRimColour` | A hard band of coloured light (magenta; set `colour` to any hue). |
Built on the Style Cookbook's `toonRim` (the same edge search, settings and light model, so it swaps with `toonRim`), plus `hardness` (a flat painted band) and `fadeStart`/`fadeEnd` (rims fade with distance, so far foliage does not glitter).
### Highlight shape (`shine` entry), `AnimeBlocks.useShine(id)`
| Block | What it is |
|---|---|
| `animeStreak` | The hard double streak of 80s OVA cels. |
| `animeBladeShine` | One long blade-shaped sliver, pointed at both ends. |
| `animeHairShine` | The ring of light across hair, its edge cut into teeth (put it on hair: see Faces and characters). |
| `animeRoundGlint` | A round catch-light disc with a small second dot. |
| `animeStarGlint` | A four-point star glint. |
| `animeCrescent` | A crescent of light along the lit edge of a round form. |
Settings: `shape`, `size`, `colour`, `strength`, `tintByColour`, `litAbove`, `bandHeight`, `zigzag`, `zigzagCount`, `angle`, `starSize`, `curvedOnly` (shapes only on round forms), `edgeSoftness`, `fullLight`.
### Ink line (`line` entry, Line slot), `AnimeBlocks.useLine(id)`
| Block | What it is |
|---|---|
| `animeLineTV` | A thin, even black line. |
| `animeLine80s` | A heavy dark OVA contour. |
| `animeLineSoft` | A faint, soft grey modern line. |
| `animeLineColour` | Coloured lines that take their tint from the surface they outline. |
| `animeLineAction` | A brushy action line that boils on the held clock. |
Every line is thicker on the silhouette (`width`) than inside (`innerWidth`, creases and folds) and thinner further away (`fadeStart`, `fadeEnd`, `farWidth`); `tint` 0 is black ink, 1 a darker shade of the surface's own colour. `useLine` switches every other Line entry off, so nothing is outlined twice, and the line steps aside where toonBlocks' ink already draws (`skipInk`).
### Film finish (`finish` entry, Medium slot), `AnimeBlocks.useFinish(id)`
| Block | What it is |
|---|---|
| `finishFilm80s` | The 80s OVA film print: grain, warm halation glowing round bright lights, soft bloom, milky blacks. |
| `finishSoftBloom` | The glowing light diffusion of current anime films. |
| `finishTV90s` | A 90s episode on a TV set: soft colour bleed, a little grain (no scan lines or flicker). |
| `finishClean` | Crisp and clean digital anime: a touch of contrast and sharpening, no grain and no glow. The cheapest finish: its own shader reads no soft field. |
Settings: `bloom`, `bloomRadius`, `bloomThreshold`, `bloomColour`, `halation`, `halationColour`, `grain`, `grainSize`, `chromaBleed`, `softness`, `sharpen`, `lift`, `liftColour`, `tint`, `saturation`, `contrast`, `vignette`. Grain is renewed on the held clock at a low, even contrast, never as a flicker.
### Painted sky (paintedSkies)
`require("~paintedSkies.PaintedSkies").use("goldenSunset")`: ten presets painted like anime background art (`summerClouds`, `toweringClouds`, `clearBlue`, `goldenSunset`, `pastelDawn`, `purpleDusk`, `starryNight`, `rainyGrey`, `storm`, `neonNight80s`), cross-fading for every player. It works beside a day and night kit (Skyclock, worldClockKit): set the kit's `skyMode` to `"off"` and the PaintedSky's `followClock` to true, and the painted sky follows its time of day and weather. See the paintedSkies README.
## Stacking with the Style Cookbook
The paper, the ink wash line and the watercolour sky are Style Cookbook blocks: install **paperBlocks**, **inkBlocks** and **watercolorBlocks** from ZeroMind beside animeBlocks for them (search for them by name: "paperBlocks", "inkBlocks", "watercolorBlocks"); every other Cookbook package stacks the same way. animeBlocks follows the Cookbook's current releases, so they share one styleKit.
```luau
local StyleKit = AnimeBlocks.StyleKit -- the styleKit animeBlocks runs on
AnimeBlocks.apply("softModernAnime")
StyleKit.add("paperColdPress", { id = "paper" }) -- anime with paper underneath (paperBlocks)
StyleKit.swap("paper", "paperKraft") -- one change swaps the paper
AnimeBlocks.useLine("inkBrushLine") -- an ink wash line instead of the anime line (inkBlocks)
AnimeBlocks.useLine("animeLineTV") -- and back
local skyOnly = { kind = "depth", near = 600, far = 100000, soft = 0.1 } -- the sky lies at the camera's far distance
StyleKit.add("wcWash", { id = "skyWash", mask = skyOnly }) -- a watercolour sky (watercolorBlocks): the wash,
StyleKit.add("wcGranulation", { id = "skyGrain", mask = skyOnly }) -- its pigment granulation
StyleKit.add("wcColdPress", { id = "skyPaper", mask = skyOnly }) -- and cold-press paper, on the sky alone
AnimeBlocks.useLight("toonRamp") -- toonBlocks' colour ramp under the anime line
```
A wash alone barely shows on a smooth sky gradient: the granulation and the paper are what make it read as watercolour. The anime light and line keep everything nearer than the sky.
Measured in the showcase on 12 November 2026 (presented frames, TV anime, the summer clouds sky): `media/combo_alone.texture/combo_alone.jpg` (anime alone), `media/combo_paper.texture/combo_paper.jpg` (cold-press paper under the anime light: the grain sits on the stone, the balls and the coat), `media/combo_inkline.texture/combo_inkline.jpg` (inkBlocks' brush line in place of the anime line, the cel light unchanged) and `media/combo_wcsky.texture/combo_wcsky.jpg` (the watercolour sky above, the anime forest below), in the Anime Looks world's gallery.
Every change is one synced write, so it swaps live for every player.
## Faces and characters
```luau
AnimeBlocks.setCharacter(hero, { clean = 1, line = 0.7, highlights = false })
AnimeBlocks.markHair(heroHair); AnimeBlocks.addHairShine()
```
- `clean` (0 to 1) keeps a character's face and skin lit, with at most one soft shadow tone (the light's `faceShadow`): less shadow on a face. `-1` gives it back.
- `line` scales its ink line: `0.7` thinner, `0` none, `-1` back to the look's.
- `highlights = false` keeps every highlight shape off it (and keeps them off when the look changes); `true` puts them back.
- `markHair` and `addHairShine` put the ring of light on hair objects only.
These are per object, synced and saved with the scene (they ride styleKit's `StyleChannel` and its third object group). **What the engine does not allow yet:** a character's own shadow colour, rim colour, line colour or highlight shape. The look is drawn over the whole frame, and a geometry pass gives its material no per-object value (engine #24549), so a truly per-character look needs a pass of its own per character. The way round today: a second entry for a group, `StyleKit.add("animeRimColour", { id = "heroRim", variant = "hero" })` with `StyleKit.setChannel(hero, { variant = "hero" })`, draws that part on the hero only.
## Timing and hits
- **On twos and threes:** `require("~frameTiming.FrameTiming").set(hero, "twos")`, or `AnimeBlocks.apply(id, { timing = true })` for the scene default. The drawn pose steps while the game runs at full speed (measured: see the frameTiming README).
- **Impact frames and smears:** install impactFrames; `ImpactFrames.play("slash", { entity = target })`. The guide "Anime look for an action game" walks through a small action level, its fighter and its hits.
## Multiplayer
The stack, the sky, the per-character channels and the timings are all synced scene state, so every player sees the same look, the same sky and the same drawings, and a player who joins late gets them with the scene. A part swapped by any player swaps for everyone, and since 1.0.9 so does a sky or a frame timing picked by any player (paintedSkies 1.0.3 and frameTiming 1.0.3 send a change from a player who does not own the synced sky or timing entity, the host usually, to its owner, who applies it for everyone, the way styleKit already did for the stack): `PaintedSkies.use`, `AnimeBlocks.apply(id, { sky = true, timing = true })`, `FrameTiming.setDefault`, the showcase's sky and look pads, and `AnimeBlocks.remove()` all work from any player. Players come from the scene's own `PlayerPrototype`; the look never spawns or edits a player.
Checked with two players in one play session of the showcase (12 November 2026): after the first player applied `chibiAnime` with its sky, the second player's stack held the same five entries (`animeCelChibi`, `animeRimThinWarm`, `animeRoundGlint`, `animeLineColour`, `finishSoftBloom`) and the same `pastelDawn` sky. Hits are impactFrames' to send: a shared hit reached both players, a `localOnly` one only the player who played it (see the impactFrames README).
## Seen in a real game: Summit Sprint
The campaign's 3D platformer Summit Sprint, restyled as TV anime in a scratch copy on 12 November 2026 (the original was left alone): `media/summit_before.texture/summit_before.jpg` is the game as it shipped under its Cookbook toon look, `media/summit_tvAnime.texture/summit_tvAnime.jpg` the same view in play after `AnimeBlocks.apply("tvAnime", { sky = true, timing = true })` (lit and lavender cel tones on the player, a streak highlight, thin black lines on the walkway and trees, the HUD untouched), and `media/summit_hit.texture/summit_hit.jpg` an impact frame (`radialBurst`, rays) landing on it. The game's own Cookbook packages were updated first, then animeBlocks and impactFrames installed: done the other way round, the hits were never drawn (see Known limits). The guide "Anime look for an action game" walks through it.
## What it costs
> **Fast is not under 1 ms reliably.** Measured on the development machine at 2097 x 1409 with 2,500 things (four rounds of off, fast, off, default, off, 10 s windows, the engine's own CPU + GPU time), fast cost **-0.36, -0.66, 2.21 and 4.15 ms** a frame over the look being off: **1.33 ms on average** (0.80 ms CPU, 0.53 ms GPU), under 1 ms in only two rounds of four. The default cost 4.47 to 7.20 ms (5.44 ms on average). Most of fast's cost is the engine's fixed price for any screen effect (about 0.6 ms of CPU and 0.3 ms of GPU, with the depth copy of engine #24971), which no change to the look itself can remove; fast's own pass is 0.19 ms of GPU at that size. Pick fast to spend about a quarter of what the default spends, not to stay under 1 ms. In a browser (1.0.17, about 840 x 632), fast cost about nothing measurable and the default about 2.6 ms of GPU, so there fast is the setting to pick when the budget is tight. The details are below.
Two settings:
- **Default** (every look as applied): the look is a styleKit stack of full-screen passes after the scene is drawn. The rim and highlight shape are folded into the cel light's pass (`AnimeBlocks.fold`), so three anime passes run (light, line, finish) plus styleKit's shared ones.
- **Fast** (`AnimeBlocks.fast(true)`, or `AnimeBlocks.apply(id, { fast = true })`, since 1.0.13): the whole look is drawn by **one engine screen effect**, `animeFast`, on every player's machine, and every stack entry is switched off, so styleKit runs nothing at all: no render feature, no passes, no script per frame. The effect takes its tones from the look's light, its line colour, width and opacity from the line, its highlight shape, size, angle and colour from the highlight part, its rim width, side, colour and tint from the rim part (since 1.0.16; a folded rim and highlight count, as every look folds them), and a clean finish's saturation and contrast.
**What fast keeps:** two flat tones with the look's tinted, richer shadow colour; the look's highlight shape (streak, blade, round glint, crescent or hair band) on curved lit surfaces, as in the default (since 1.0.16); the rim light inside lit silhouettes, with the look's width and side (since 1.0.16); a silhouette ink line in the look's colour and width; and the clean finish's saturation and contrast.
**What fast gives up.** It reads only the frame and its depth, never the g-buffer, so it cannot tell a dark material from a shadow: the scene's own smooth shading is flattened by a set share and cut into two tones by a normal rebuilt from depth and the sun (taken across about a fortieth of the screen, so a low-poly ball shades smoothly rather than in facets, at the price of softer tone edges on small detail), and cast shadows keep the scene's own darkness rather than the flat shadow tone. The line follows silhouettes only, at an even width (no inner creases or folds, no thicker-near line, no brush or broken stroke). The star glint draws as a round glint (its arms would need many more reads). No third tone or highlight step, no film grain, halation, bloom or TV finish (the colour grade stays). No per-character face, line or highlight controls, no objects kept as rendered (`exclude`), no masks, no held boil, and it does not stack with other Style Cookbook blocks (paper, ink wash, watercolour sky). Foliage gets busier lines than in the default. The parts stay in the stack switched off, so swaps still work (they rebuild the fast settings) and `fast(false)` switches every part that was on back on. Use the default whenever the frame budget allows it.
### Measured: what the engine itself spends, look off against look on
`AnimeBlocks.measureEngine()` is the method (since 1.0.16 it measures the way the world's owner checked it); run it in play in the window that shows the game. It reads `profiler.cost`: the engine thread's **own CPU time** (its thread clock, so time other programs hold the cores is not counted) and the engine's **own GPU time** (the GPU time the driver books to the engine's process), never the wall clock, because this computer is shared with other busy programs. It fills the scene to 2,500 things (a tenth of them moving), keeps the window's own size and the game's own frame rate, and measures 10 s per window in the order off, fast, off, default, off, twice, waiting 4 s after each change; each look is compared with the mean of the off windows on either side of it. Every window is checked before it is used: off must have neither the fast effect nor a styleKit pass, fast the fast effect and no styleKit pass, default styleKit passes and no fast effect (1.0.13 published figures taken while "off" still had the fast effect on; 1.0.14 fixed that and added this check).
Measured on 12 November 2026 in the Anime Looks showcase (forest plaza, `tvAnime`, 2,500 things), animeBlocks 1.0.16 on styleKit 1.7.9, in the desktop editor on the development machine, **drawn at 2097 x 1409** (the editor window's size; about 1.4 times the pixels of 1080p), 14 to 21 frames a second, every window verified. Two runs of `measureEngine()`, so four rounds; cost over off, engine's own time per frame:
| `tvAnime` at 2097 x 1409 | Round 1 | Round 2 | Round 3 | Round 4 | Mean |
|---|---|---|---|---|---|
| **Fast**, CPU + GPU | -0.85 + 0.50 = **-0.36 ms** | -0.60 - 0.06 = **-0.66 ms** | 1.06 + 1.15 = **2.21 ms** | 3.61 + 0.54 = **4.15 ms** | 0.80 + 0.53 = **1.33 ms** |
| Default, CPU + GPU | 2.73 + 2.14 = 4.86 ms | 4.51 + 2.69 = 7.20 ms | 3.20 + 2.01 = 5.21 ms | 2.25 + 2.23 = 4.47 ms | 3.17 + 2.27 = 5.44 ms |
**Fast is not under 1 ms every time on this machine.** It came out under 1 ms in two rounds of four and over it in the other two, and its mean over the four is 1.33 ms (0.80 ms of CPU and 0.53 ms of GPU). The world's owner, measuring the same way at the same size with 1.0.15 (fast without the highlight and rim), saw 0.77 ms and 2.27 ms: the same pattern. **No single round can be expected to land within 0.15 ms of these figures:** with the same protocol on the same machine, one round of fast differs from the next by up to 4.8 ms, almost all of it CPU, because the "off" windows themselves move by several milliseconds with what else the machine is doing (one "off" window dropped to 10 frames a second on its own). The GPU side is steadier: fast 0.53 ms (rounds from -0.06 to 1.15 ms), the default 2.27 ms (rounds from 2.01 to 2.69 ms, and the owner saw 1.83 and 1.94 ms). Read the CPU figures as "somewhere from nothing to a few milliseconds", and compare looks by the GPU column and by many rounds.
**The default costs far more than the earlier 0.65 ms of GPU suggested**: that figure was taken at 1920 x 1080 with the frame rate held at 20; at the window's own size and frame rate it is about 2.3 ms of GPU and about 3 ms of CPU.
Where fast's cost goes: by the engine's own GPU timestamps, its pass is about 0.04 ms at 1080p before 1.0.16 (1.0.16 reads the depth thirteen times a pixel instead of five for the highlight, the rim and the smooth normal) and the copy of the scene depth it reads about 0.03 ms; it runs no script per frame (it reads the sun's direction once a second). The rest is the engine's own cost of having a screen effect at all: one bare engine screen effect with no script measured about +0.6 ms of engine CPU and +0.2 ms of GPU here (see Known limits).
The engine's own frame breakdown (`profiler.record`, typical frames, look on minus off) put a styleKit stack's CPU at about 1.1 ms in the 1.0.11 measurement: the deferred renderer's late stage 0.35 ms (it does more as soon as a pass runs between lighting and compositing: the copy of base colour and normals the cel light needs, and the plaza's object mask, about 0.2 ms of it), styleKit's script in the render feature tick 0.22 ms, frame-graph building for the passes 0.13 ms, the frame finish 0.17 ms, compositing route 0.08 ms, the engine's per-frame survey of registered screen effects 0.08 ms, garbage collection 0.06 ms and the post chain 0.04 ms.
Earlier versions quoted 1.12 ms for the old fast setting (0.85 ms GPU + 0.27 ms script): that counted only the GPU timestamps of the look's own passes and styleKit's own script counter, not the engine's work around the passes.
The cost does not grow with the number of things in the scene, except for objects kept as rendered or given per-character controls in the default: every part is a full-screen pass, and the script side reads no entities. It grows with the number of pixels.
**`AnimeBlocks.measure()`** still answers the GPU time of the default stack's own passes from the engine's GPU timing window (back-to-back windows of 64 frames, `gpuMs`, `gpuFrames`, `gpuRange`, `fps`) and styleKit's script counter: useful to compare two looks pass by pass, but it leaves out the engine's own work around the passes, so use `measureEngine` for what a look really costs. Run either in the client that shows the game: an offscreen client resolves no GPU timings.
**In a browser (animeBlocks 1.0.17): fast costs about nothing measurable, the default about 2.6 ms of GPU a frame.** Measured by the world's owner, not by an agent: an agent cannot start a browser engine from the editor (engine #20946), and the engine reports no browser frame time from inside (#24706), so no agent measurement is given. How: a web browser running the engine's web build, this showcase in play filled to 2,500 things, **the scene drawn at about 840 x 632**, held at 10 frames a second, 10 s per sample in the order off, fast, off, default, off, two rounds, the engine's own GPU time per frame:
| Round | Off | Fast | Off | Default | Off | Fast over off | Default over off |
|---|---|---|---|---|---|---|---|
| 1 | 8.91 ms | 10.08 ms | 9.82 ms | 11.52 ms | 8.98 ms | +0.72 ms | +2.12 ms |
| 2 | 6.27 ms | 7.09 ms | 9.40 ms | 12.76 ms | 10.04 ms | -0.75 ms | +3.04 ms |
Each look is compared with the mean of the off samples on either side of it. **Fast: +0.72 and -0.75 ms, about 0.0 ms on average, within the noise** (the off samples alone run from 6.27 to 10.04 ms). **Default: +2.12 and +3.04 ms, about 2.6 ms on average.** The CPU could not be read (the off samples alone ran from 38 to 49 ms). So in a browser fast is the cheaper setting, as on desktop, and by more: **when the frame budget is tight in a browser, use fast.** (The figures 1.0.15 printed here, fast about +2.0 ms and the default about +0.8 ms of GPU, were measured with that version and no longer hold: since 1.0.16 fast draws the highlight and rim too and skips its far-away reads, and 1.0.17 was measured above.)
Other ways to spend less in the default:
- `finishClean` runs its own copy of the finish shader, `animeFinishClean`, which reads no soft field (two passes fewer than the film finishes).
- Keep `exclude` lists short: the object mask is a pass between lighting and compositing, which the deferred renderer pays for (about 0.2 ms of engine CPU on the plaza).
- `StyleKit.setQuality("low")` is meant to halve the chain's resolution; on this machine it did not change any anime pass's cost, so it is not counted on here.
## Known limits
- **Two copies of styleKit in one world.** A game that held an older styleKit (from another Style Cookbook package) when animeBlocks was installed keeps that copy, and the installer gives animeBlocks a second one. The game's copy goes on drawing the scene: the look still shows, because the stack is shared scene state, but impactFrames' hits (laid on each machine through animeBlocks' copy) are never drawn, and when the game's copy predates styleKit 1.5 the anime shaders fail to compile against its older shader library. Found restyling Summit Sprint (styleKit 1.4.4). Updating the game's styleKit afterwards, or uninstalling and reinstalling animeBlocks, does not merge the two (both copies at 1.7.8 still ran separately; reported to ZeroMind as 01M77X5XNF6KAJ8TWXWCEB91J4), and a package cannot reach the other copy itself because the publish gate refuses a computed `require`. So update the Cookbook packages before installing animeBlocks. `AnimeBlocks.check()` and a warning a few seconds after `apply` say when a world is split, and impactFrames' `play` returns false with the same reason instead of reporting a hit nobody sees.
- **A whole-look switch can show the previous look's settings for a few seconds.** Blocks of one family share one shader, and a new effect's settings only take hold once it has compiled (engine #22741, styleKit writes them every frame for its first three seconds). In the editor at 8 frames a second, switching from soft modern anime to chibi showed soft modern's colours for about 20 seconds before the chibi pastel settled; switching one part, or a game running at full frame rate, settles far sooner.
- **Fast reads only the frame and its depth** (one engine screen effect, no g-buffer): it cannot tell a dark material from a shadow, cast shadows keep the scene's own darkness, the line has no inner creases and an even width, the star glint draws as a round glint, and there are no film finishes, per-character controls, kept-as-rendered objects or stacking with other Cookbook blocks. It keeps the highlight shape and the rim (since 1.0.16). See What it costs for the whole list.
- **Fast is not under 1 ms every time on the development machine**: at 2097 x 1409 its cost over off was -0.36, -0.66, 2.21 and 4.15 ms in four rounds (mean 1.33 ms: 0.80 ms of CPU, 0.53 ms of GPU), and one round can differ from the next by several milliseconds of CPU, so no single measurement is expected to come within 0.15 ms of the mean. See What it costs.
- **Most of what fast costs is the engine's own cost of a screen effect (engine #24971: the scene depth is copied every frame while a screen effect is on).** One bare engine screen effect with no script measured about +0.6 ms of engine CPU and +0.2 ms of GPU here, against fast's mean of 0.80 ms of CPU and 0.53 ms of GPU at 2097 x 1409; the depth copy itself is about 0.03 ms of GPU at 1080p by the engine's timestamps (fast's own pass about 0.04 ms at 1080p before 1.0.16, 0.19 ms at 2097 x 1409 in 1.0.17), so most of the bare effect's cost is engine CPU around the copy and the effect chain. In a browser (1.0.17, about 840 x 632) fast measured about 0.0 ms of GPU over off, within the noise, against about 2.6 ms for the default. (#24971 could not be opened from the editor, so its share here is what was measured, not what the issue states.) In the default, about 0.35 ms of engine CPU is the deferred renderer's late stage doing more once any pass runs between lighting and compositing (reported to ZeroMind; no engine issue number). Fast pays none of the #24548 share.
- **Every pass is queued again every frame, even when nothing changed** (engine #24548). styleKit 1.7.9 hands the engine the same passes again instead of rebuilding them, but queuing them is still script work each frame: in the default the render feature tick is about 0.22 ms of the look's engine CPU (about a fifth of the 1.1 ms the engine's frame breakdown attributes to a styleKit stack), and the frame graph built for those passes another 0.13 ms. Fast runs no stack, so it does not pay this.
- **Per-character values need their own pass** (engine #24549): see Faces and characters for what is per object today.
- **A pass that writes only its own target reads no scene depth** unless it also writes the scene colour (engine #24550), which is why every part is a full-frame styleKit block rather than a lighter pass of its own.
- **An unknown blend mode draws as replace with no error** (engine #24551): animeBlocks only uses styleKit's own composite.
- **A setting written before its shader finishes compiling reads back as the default** (engine #22741): the first frame after the world opens can show default tones; it settles within a few frames.
- **Transparent things and particles are not in the depth**, so they get no line or rim and are toned as what is behind them.
- **Adding a setting to a block's shader while the look is on** needs `StyleKit.clear()` and the look applied again (its uniform buffer keeps the old size until the effect is made again).
- **The description on ZeroMind can lag a release** (engine #19258).
## Built on
- **styleKit** (Style Cookbook): the stack, slots, looks, masks, the style channel, the held clock. Every block here follows its block rules (`StyleKit.checkBlock`).
- **toonBlocks** (Style Cookbook): the cel light reads light the way toonBlocks' toon light does (`toonLight`, `toonFrame` shader modules), the rims are its `toonRim` model, and its `softAnime` look was the starting point for the soft modern look.
- **paperBlocks, inkBlocks, watercolorBlocks** (Style Cookbook): stack under and beside the anime parts.
- **paintedSkies** and **frameTiming** (this world), **impactFrames** (this world, optional), **juiceKit** (Juicebox; impactFrames rides along with it).
- Showcase: **forestKit** (the forest), the **apprentice** avatar (a published character kit).
## Contents
- `AnimeBlocks` (module): `apply`, `looks`, `useLight`, `useRim`, `useShine`, `useLine`, `useFinish`, `setCharacter`, `cleanFace`, `markHair`, `addHairShine`, `fold` and `folded` (the rim and highlight drawn inside the light pass), `set` (change a part, folded or not), `fast` and `isFast` (the whole look as one engine screen effect, about 1.3 ms of the engine's own time on average at 2097 x 1409, see What it costs), `measureEngine` (what a look costs the engine itself, look off against on), `lean` (the old name of `fold`), `describe`, `remove`, `measure` (what the look costs on this machine, over at least 300 frames by default, in whole 64-frame windows); `LOOKS`, `ORDER`, `PARTS`.
- `blocks/`: 26 blocks on six shaders (`animeCel`, `animeRim`, `animeShine`, `animeLine`, `animeFinish`, and `animeFinishClean` for `finishClean`), the fast setting's own screen effect `animeFast`, and two shader modules the rim and highlight passes share with the cel light (`animeRimCore`, `animeShineCore`).
- `AnimeFast` (component): draws the fast setting on every player's machine from a synced holder entity `AnimeFast`, which `fast(true)` makes.
- `looks/`: the seven whole looks.
- `guides/`: "How to make an anime look", "Anime look for an action game" and one per look.
- `workflows/animeWorld`: turns an existing scene, world or kit into an anime look step by step, with the undo for every change.
- `tests/animeBlocks.testSuite`: block rules, families, looks, one-part swaps, Cookbook stacking, per-character controls.
- `docs/`: the shared text of each family's block READMEs.
## Version history
Now **1.0.23** (1.0.23: a short description and a lead that says what it gives and how to start, with the history moved here; 1.0.22: a seventh look, `goldenHourAnime`, the golden hour of an emotional film scene; action anime and night city no longer sink into black under trees or at night; the 80s OVA's film finish no longer blooms a bright sky to white; on paintedSkies 1.0.6 (brighter night skies, a warm purple dusk) and impactFrames 1.0.8; the README gives the first steps in order, how to tell the sky took and what to do with lots of characters; 1.0.21: `apply(id, { sky = true })` reports a sky only when one was really set (from a pull request by an installer, released as 1.0.20, which also corrected the description of `fast`), and on paintedSkies 1.0.5, which brings its presets and its shader when another package installs it; the fast effect finds its shader wherever animeBlocks is installed; 1.0.19: `AnimeBlocks.VERSION` reports the package's version again (it had said 1.0.10 since 1.0.10), and a test keeps the two together; 1.0.18: the browser figures and advice match 1.0.17 as measured in a browser: fast costs about nothing measurable there, the default about 2.6 ms of GPU, so in a browser use fast when the budget is tight; nothing else changed; 1.0.17: fast skips its smooth-normal reads past 30 m and its rim reads past 45 m, where the rim has faded out as in the default (its pass 0.20 to 0.19 ms of GPU at 2097 x 1409), and What it costs opens with a plain warning that fast is not under 1 ms reliably; 1.0.16: fast draws the look's highlight shape and rim again, with a smooth normal so low-poly round things do not shade in facets; `measureEngine` measures the way the owner checked it (off, fast, off, default, off at the window's own size, twice); What it costs gives every round at the size it was drawn, honestly: fast is not under 1 ms every time; the browser figures are the owner's at 840 x 632; 1.0.15 adds the browser measurement, which cannot show the look's cost in the development web build; 1.0.14 fixed `remove()` and `apply(id, { fast = false })` leaving the fast effect on, which made 1.0.13's measured cost of fast wrong; `measureEngine` now checks every window is in the state it measures and caps at 20 fps; fast measured again: about 0.2 ms of GPU and 0.75 ms of engine CPU, give or take 0.55, see What it costs; 1.0.13 made fast one engine screen effect with no styleKit stack; 1.0.12 corrected the quick-start and the guide to the measured cost of fast mode; 1.0.11, what the look really costs: `AnimeBlocks.measureEngine()` measures the engine's own CPU and GPU time with the look off and on, see What it costs; on styleKit 1.7.9, the Style Cookbook release of 2026-11-12 that halves the passes of the fast look and replays still frames; 1.0.10 added fast mode, `AnimeBlocks.fast(true)`, the whole look in one anime pass; 1.0.9 folded the rim and highlight into the light pass and made `remove()` take off the painted sky and the scene timing; on toonBlocks 1.4.2). Installing animeBlocks brings **styleKit**, **toonBlocks**, **paintedSkies** (painted anime skies) and **frameTiming** (animation on twos and threes) along. For hit impact frames and smears, install **impactFrames** too.
# 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.
# paintedSkies
**Hand-painted anime skies for any world**, like anime background art: towering summer cumulonimbus, clear blue, golden sunset, pastel dawn, warm dusk, starry night with a milky way and moon, rainy grey, storm and an 80s neon city night. Ten presets, swapped with one call; the sky also lights the scene to match, and every player sees the same sky. Stands on its own: no other package needed.
**Get started:** install paintedSkies, then
```luau
require("~paintedSkies.PaintedSkies").use("summerClouds")
```
Version 1.0.7 (1.0.7: a short description and a lead that says what it gives and how to start; 1.0.6: brighter night skies and a warm purple dusk; 1.0.5: its presets and shader arrive when another package installs it).
## How it is painted
Big, cinematic, hand-painted skies like anime background art, for any world.
Towering summer cumulonimbus with bright white tops and blue-grey painted
shading, clean blue gradients, golden sunsets with pink-lit clouds, pastel
dawns, warm dusks with an orange horizon and the first stars, deep starry nights with a milky way
and moon, rainy grey overcast, and an 80s anime city night with a neon horizon
glow and a skyline. Everything is painted per pixel by one sky shader:
cumulus are stacks of round billows lit like balls and posterised into soft
painted bands with brush grain, with a cel rim on the edges toward the sun and
haze toward the horizon.
It stands on its own: no other package is needed.
## First example (a fresh world, a few minutes)
1. Install paintedSkies from ZeroMind (search "painted anime sky").
2. In your scene's `build.luau`, inside `content()`:
```lua
local skyEnt = entity.spawn("PaintedSky")
skyEnt.component.add("PaintedSky", { preset = "summerClouds" })
```
3. The sky appears at once in the editor. Change `preset` in the Inspector, or
from any script during play:
```lua
local Skies = require("~paintedSkies.PaintedSkies")
Skies.use("goldenSunset") -- cross-fades for every player
```
Remove any other sky component (`Skybox`, `ProceduralSky`) from the scene:
the engine shows whichever sky was set up last. The package also ships
`paintedSkiesGallery`, a meadow scene under a PaintedSky, to look at the
presets.
## Presets
| id | what it is |
|---|---|
| `summerClouds` | The classic anime summer sky: towering cumulonimbus, deep saturated blue, white tops, blue-grey shading. |
| `clearBlue` | Clean blue gradient, faint high wisps, bright sun. |
| `goldenSunset` | Orange and gold horizon, pink-lit clouds, a low sun disc. |
| `pastelDawn` | Pink, peach and lavender, soft low cloud banks. |
| `purpleDusk` | Warm dusk after sunset: an orange horizon under deep indigo, crescent moon, first stars (since 1.0.6; before, violet and magenta, too close to `neonNight80s`). |
| `starryNight` | Deep navy, dense painted star field, milky way band, full moon. |
| `rainyGrey` | Overcast, layered grey stratus, muted colour. |
| `storm` | A gathering storm: slate-violet cumulonimbus towers, a dark rolling deck and a pale break of light low on the horizon (no lightning flashes). |
| `toweringClouds` | The big anime-film summer sky: a deep blue gradient and enormous sunlit cumulonimbus towers on the horizon. |
| `neonNight80s` | 80s anime city night: magenta into a cyan horizon glow, purple haze, big sparkling stars, distant lit skyline. |
`Skies.presets()` lists every preset the world has, yours included.
### Your own presets
A preset is a `.data` asset bound to the `skyPreset` contract: a
`values.yaml` holding only the fields that differ from the defaults (colours
as sRGB hex, angles in degrees). Copy one from `presets/`, rename the folder,
and it is listed and usable by its folder name:
```yaml
contract: skyPreset
values:
label: Alien noon
zenith: "#2a0a5a"
horizon: "#7affc8"
towers: 0.9
cloudShade: "#5a3a8a"
```
Every field and its range is in `skyPreset.dataType/README.md`.
## The component: `PaintedSky`
| Field | Default | Meaning |
|---|---|---|
| `preset` | `summerClouds` | The preset shown. |
| `matchLighting` | `true` | Set the scene's directional light (direction, colour, intensity) and ambient light to the preset's suggestion. |
| `transition` | `2.5` | Seconds a change cross-fades over during play (0 = at once; in edit mode changes are always instant). |
| `overrides` | `{}` | Preset fields replaced on top of the preset, e.g. `{ towers = 1, sunElevation = 20 }`. |
| `followClock` | `false` | Follow a day-night kit: the sky changes with its time of day and weather (see below). |
| `clockPresets` | dawn `pastelDawn`, day `summerClouds`, dusk `goldenSunset`, night `starryNight`, overcast `rainyGrey`, storm `storm` | The preset for each time of day and weather while following. |
All fields are Synced and saved with the scene. `sky:use(id)` on the
component is the same as setting `preset` and clearing `overrides`.
## With a day and night kit (Skyclock / worldClockKit)
paintedSkies works beside the day-night kits people already use rather than
replacing them. With **worldClockKit** (the Skyclock kit) in the scene:
1. On the kit's `WorldClock`, set `skyMode = "off"`: the kit keeps its shared
clock, weather, sun, moon and lamps, and leaves the sky to you.
2. On the `PaintedSky`, set `followClock = true`.
The painted sky now follows the kit: pastel dawn, summer clouds by day, a
golden sunset at dusk, a starry night, grey overcast in rain, cloud, snow and
fog, and the storm sky in storms, cross-fading over at least six seconds. Change
the pairing with `clockPresets` (`{ day = "toweringClouds" }`). Every machine
reads the kit's synced clock and weather off its `WorldClock` component, so
every player sees the same sky with no extra traffic, and paintedSkies needs
nothing of the kit installed. While following, `matchLighting` is left to the
kit, which lights the scene. Any other day-night system: leave `followClock`
off and call `Skies.use(id)` when your time of day changes.
## The module: `require("~paintedSkies.PaintedSkies")`
| Call | Does |
|---|---|
| `use(id, { transition?, keepOverrides? })` | Swap the whole sky for every player. Spawns a synced PaintedSky entity if the scene has none. Returns false for an unknown id. |
| `presets()` | Sorted list of preset ids. |
| `current()` | `{ preset, values, overrides }` of the sky being shown. |
| `set(overrides)` | Change preset fields on top of the current preset, shared. `set({})` clears them. |
| `clear()` | Take the painted sky off for every player: the PaintedSky entity goes, the scene's own sky shows again, and every machine puts back the sun and ambient light the scene had before the sky set them (`matchLighting`). Any player can call it. |
| `preset(id)` | The resolved values of one preset (defaults filled in). |
| `toProperties(values)` | The sky shader properties those values produce. |
## Multiplayer
The PaintedSky fields are Synced: `use`, `set` and Inspector edits replicate
to every player, and every peer paints the same sky from the same preset
(clouds drift on the shared world clock). `matchLighting` writes the scene's
sun and ambient light on each peer from the same values, so lighting agrees.
Any player can change the sky (since 1.0.3). The PaintedSky entity belongs to
one player, usually the room's host, and only its owner can write it, so
`use`, `set` and `clear` on any other player's machine send the change to the
room on the `paintedSkies.op` channel and the owner applies it for everyone.
Before 1.0.3 a sky picked by a player who was not the host was accepted on
that machine and changed nothing.
## Cost
One fullscreen sky pass, no textures, no render targets, no extra draw calls,
and no per-frame Luau work while the sky holds still (properties are written
only on a change or during a cross-fade). Per pixel it evaluates the gradient
and stars, and where a preset turns them on: a 3x3 cell search of sphere
billows at two scales for the towering clouds (only between the horizon and
the tallest tower) and for deck puffs (only above the horizon), and a
5-octave fbm for stratus and wisps. Layers at 0 are skipped, so `clearBlue`,
`purpleDusk` and `starryNight` are the cheapest and `summerClouds` the
dearest.
GPU time of the sky pass, measured in the Anime Looks showcase at 2097 x 1453
on the development machine's GPU (`zero profiler gpu`, row `scene.sky`):
0.39 to 0.40 ms with `clearBlue` and `storm` up, where the engine's own
deferred lighting pass took 2.16 ms on the same frame. The sky pass only
draws where no geometry covers the screen, so a scene seen through trees
pays for less of it. Read yours with `zero profiler gpu`.
## Known limits
- **Engine issue #4701 (a runtime sky change is not followed by the sky
pass).** The package never swaps the sky material: it creates ONE runtime
material (`paintedSkies.sky`) once, binds it once through the native Sky
component, and every preset change or cross-fade pushes property values
onto that same material with `renderer.material.setProperty`. Runtime swaps
(`use`, `set`, Inspector edits, cross-fades) are followed every time.
- **One sky per scene.** The engine draws the sky that was set up last; a
scene that also carries `Skybox`/`ProceduralSky` should drop them. Removing
a PaintedSky does not hand the sky back to an older sky component: the
engine falls back to its default sky until another sky is set up.
- **Clouds are painted, not volumetric.** They are a backdrop: flying into
them or above them does not work, and they do not cast shadows on the world.
- **Ground below the horizon** is painted as a plain colour band; it is meant
to sit behind your terrain.
- **Cross-fades need play mode** (the component's `update` drives them); in
edit mode a change shows at once.
- **Towering-cloud presets cost more per sky pixel** than a plain gradient
(`summerClouds`, `toweringClouds` and `storm` search a grid of billows).
- **followClock reads the kit's `WorldClock` by its component**, found by
the name `WorldClock` or a scan at most every ten seconds; a kit that
names its clock differently is found within ten seconds of appearing.
- **`lighting.get` and a content sky.** The PaintedSky carries `kind` and
`material` fields only so the engine's `lighting.get` tool can read it
(reported upstream); a sky restore through `lighting.setSky` logs that no
material matches `paintedSkies.sky`, which is harmless.