# ComicControls
Drop-in controls for a comic world: keys and on-screen buttons that cycle the look, the panel layout, the border and whole page presets, and turn the panels on and off. Add it to any entity in a scene:
```luau
local e = entity.spawn("ComicControls")
e.component.add("comicPanels.ComicControls", {})
```
| Key | Button | Does |
|---|---|---|
| `]` / `[` | Look | Next / previous comicBlocks look (keeps the panel page) |
| `P` | Panels | Panels on (`ComicPanels.on()`, the default page) or off |
| `L` | Layout | Next layout |
| `B` | Border | Next border style |
| `K` | Page | Next page preset (`ComicPanels.PAGE_ORDER`) |
Fields: `looks` (comma-separated look ids to cycle; empty cycles every installed comicBlocks look), `keys` and `buttons` (switch either off). Every press is one synced change, so every player sees the page any player picks; each machine draws its own buttons at the bottom left, after the look, so they always read. Its source is short and is meant to be copied into your own HUD when you want your own buttons.
# ComicPage
Holds the comic page's shared settings and, on every machine, runs that machine's own extra panel cameras. `ComicPanels.setLayout` puts it on a synced entity named `ComicPanels`; you do not normally add it by hand. It needs no sibling components, only styleKit with the `panelPage` block in the stack (which `ComicPanels` adds).
## Fields (synced)
| Field | Default | What it is |
|---|---|---|
| `layout` | `"splash"` | The layout id (`ComicPanels.layouts()`). |
| `cameras` | `"single"` | `single`: every panel shows the game's one view. `several`: panels with a framing get a per-player extra camera. |
| `border` | `""` | Border style name, empty for the layout's own. |
| `gutter` | `""` | Gutter colour name or `#rrggbb`, empty for the page default. |
| `shown` | `true` | Whether the page is shown. |
| `viewScale` | `0.75` | Resolution of the extra views relative to their panel on screen, 0.25 to 1. Lower costs less. |
## What it does each frame
When `shown` is on and `cameras` is `several`, it asks `ComicPanels.plan` which framings the layout needs (at most three). For each it spawns a local entity `ComicPanelCamera<n>` (network scope `OwnerOnly`, never synced) with a `Camera` of the framing's lens, rendering `all !ui !EditorUI !debug` into a texture sized to the panel's box on screen times `viewScale`, and publishes that texture to the style stack with `StyleKit.publishInput("panelView<n>", texture)`. Every frame it places each camera around the local player's avatar (`layers.active.players.localPlayer.avatar`) from the framing's eye and look-at offsets and the avatar's facing.
It rebuilds the cameras when the layout, framings, `viewScale` or screen size change, and removes them (withdrawing the inputs and destroying the textures) when the camera mode is `single`, the page is hidden, or the component is destroyed. In `single` mode it spawns nothing.
## Methods
- `views()`: the extra views on this machine, `{ { framing, width, height } }`.
## Multiplayer
The fields are synced, so every player sees the same page. The cameras are each machine's own and follow that machine's own player, so each player's close-up shows their own character. With no local avatar (a scene without players) the cameras stay where they were spawned.
# ComicPanels
The module that lays a game's view into comic panels. Game code, setup scripts and agents call it to pick a page layout, a camera mode, a border style and a gutter colour; it writes the `panelPage` block's settings into the scene's style stack (one entry, id `panels`, in the Medium slot) and keeps the same choices on a synced `ComicPanels` entity whose `ComicPage` component drives each machine's extra cameras.
```luau
local ComicPanels = require("~comicPanels.ComicPanels")
ComicPanels.setLayout("threeTier", { cameras = "several", border = "brush", gutter = "cream" })
ComicPanels.setLayout("splash") -- one camera, one panel
ComicPanels.off() -- back to the plain frame
```
## Functions
| Call | Returns | What it does |
|---|---|---|
| `setLayout(id, opts?)` | boolean | Lay the view into layout `id`. Creates the `ComicPanels` entity and the `panels` stack entry the first time, changes them after. `opts`: `cameras` (`"single"` or `"several"`), `border` (`clean`, `brush`, `rough`, `heavy`, `none`), `gutter` (a `GUTTERS` name or `"#rrggbb"`), `borderColour`, `borderPx`, `gutterPx`, `marginPx`, `viewScale` (0.25 to 1), `keepBorder` (false to drop the border you set before). Camera mode, border and gutter carry over from the last call when left out. `false` for an unknown layout. |
| `setCameras(mode)` | boolean | Change the camera mode and keep the current layout (or `splash` when none). |
| `setBorder(style)` | boolean | Change the border style; `false` for an unknown style or when no page is shown. |
| `setGutter(colour)` | boolean | Change the gutter colour; `false` when no page is shown. |
| `matchLook()` | boolean | Set the extra views' print treatment from `TREATMENTS` for the look now in the stack (`StyleKit.describe().look`), or `default`. |
| `applyLook(id)` | ok, err | `StyleKit.applyLook(id)`, keeping the Medium slot when a page is shown, then `matchLook()`. |
| `off()` | | Remove the `panels` entry and mark the page hidden, so every machine drops its extra cameras. |
| `state()` | table | `{ layout, cameras, border, gutter, enabled, viewScale }` from the synced entity. |
| `define(layout)` | | Add or replace a layout: `{ id, name, summary, panels = { { corners = { tl, tr, br, bl }, view } }, bleed?, border? }`, one to six panels, corners from 0 to 1 with the top left first. |
| `layouts()` | `{ Layout }` | Every layout, in the order defined. |
| `layout(id)` | Layout? | One layout. |
| `framings()` | `{ string }` | The camera framing names, sorted. |
| `plan(layoutId, cameras)` | views, sources | The extra views a layout asks for (one per distinct framing, at most three) and which source each panel shows (0 the main view, 1 to 3 an extra view). |
## Tables
- `LAYOUTS` (through `layouts()`): `splash`, `splashInset`, `twoUp`, `threeTier`, `fourGrid`, `newspaperStrip`, `tallSplit`, `slantedAction`, `slantedDuel`, `bleed`, `bleedInset`, `bigTopRow`.
- `BORDERS`: `clean` 0, `brush` 1, `rough` 2, `heavy` 3, `none` 4 (the block's `borderStyle`).
- `GUTTERS`: `white`, `cream`, `newsprint`, `black`, `red`, `blue`, `yellow`, `grey`.
- `FRAMINGS`: `closeUp`, `reverse`, `wide`, `lowAngle`, `overhead`, `side`, each `{ eye, at, fov, summary }` with offsets as (right, up, forward) metres from the player's body.
- `TREATMENTS`: the extra views' print treatment (`viewInk`, `viewLevels`, `viewDots`, `viewMono`, `viewScreenPx`) for `default` and each comicBlocks look.
- `ENTRY` (`"panels"`), `MAX_PANELS` (6), `MAX_VIEWS` (3), `VERSION`.
## Notes
- Layouts, framings and treatments are module state: a `define` or a change to `FRAMINGS` must run on every machine (in a module or component every peer loads).
- The extra views get the panel's own print treatment rather than the look's blocks, because the look stack runs only on the presented frame (styleKit Known limit #17427).
- `applyLook` takes no `keep` option; to keep a Line entry too, call `StyleKit.applyLook(id, { keep = { "line", "medium" } })` and then `matchLook()`.
The full-frame pass of comicPanels' panelPage block: panels, gutters, borders and extra views.
# Panel page (styleBlock, Medium)
Lays the game's view into comic panels with gutters and inked borders: splash pages, insets, tiers, slanted action panels and borderless bleeds, from one camera or with extra per-player views in their own panels. Set it up with the `ComicPanels` module (`ComicPanels.setLayout("threeTier")`), which writes every setting below for you; the block can also be tuned directly.
Settings: `count`, the panel corners `p1a` .. `p6b`, `sources` and `sourcesB` (which panel shows which view), `gutter` (warm white), `border` (near black), `borderPx` (3), `borderStyle` (0 clean), `gutterPx` (16), `marginPx` (22), and the extra views' print treatment `viewInk` (0.8), `viewLevels` (4), `viewDots` (0.6), `viewMono` (0), `viewScreenPx` (7).
The look stack runs only on the frame the player sees, never on a camera that renders into a texture (an engine limit, #17427), so an extra view cannot be drawn by the look's own blocks. This block gives extra views a print treatment of their own (flat tints, a dot screen in the shadows or black and white, and an ink edge), and ComicPanels picks the treatment to match the look in the stack.
## What it gives up in motion
Panels, gutters and borders are fixed on the screen like the page itself, so nothing slides or flickers; the picture moves inside each panel. Brush and rough borders are drawn from a fixed pattern along each edge and never boil. The extra views are live cameras at the panel's own resolution (scaled by ComicPanels' `viewScale`), so they move with the player like the main view; their dot screen holds still on the screen.
## How it treats content
- Opaque things: shown inside the panels; the gutters cover what lies under them.
- Transparent things (glass, water): shown as rendered inside the panels.
- Particles and smoke: shown as rendered; in extra views they get the view's print treatment.
- Sky: shown inside panels like everything else.
- Fog: shown as rendered.
- Skinned characters: shown inside panels; extra views frame the local player's own character.
- Foliage: shown as rendered; busy leaves in extra views get a busier ink edge.
- World text: world labels stay readable in the main view; in extra views small text gets the ink edge and may be hard to read.
- Black stays black: gutters are paper coloured by design (a page), but an unlit picture stays black inside its panel.
- Dim rooms: the panel page adds paper-coloured gutters around the picture, which is a frame and not light on the scene, so it does not ask for the dim guard.
- Screen UI: drawn after the stack, on top of the page, unchanged.
# comicPanels tests
Checks the package against styleKit's block rules and against what its docs promise, partly on the presented frame of a small set the suite builds itself (a white wall, a red box and a camera of its own), since the test runner empties the scene.
- **Rules:** the `panelPage` block is installed from comicPanels, passes `StyleKit.checkBlock` and sits in the Medium slot, so it lies over any look.
- **Seventeen layouts, one change each:** `ComicPanels.setLayout` takes every layout and the page reads it back with the layout's own panel count; the borderless bleed drops its margin and border; an unknown layout is refused.
- **Camera plan:** with one camera no extra views are planned; with several, each layout plans at most three extra views, one per distinct known framing, and every panel shows a view that exists.
- **Borders, gutters and cameras by name:** every border style and gutter colour switches in one call and reads back from `state()`, and so does the camera mode.
- **Looks and the page:** `ComicPanels.applyLook` changes the look and keeps the page; `off()` takes the page away (needs comicBlocks for the look).
- **Captions, pages and the default page:** a caption reads back from the page entry, a second at the same place replaces it, an unknown style is refused and `clearCaptions` empties them; `on()` lays `ComicPanels.DEFAULT`; every page preset whose look is installed sets look, layout, border, gutter and captions in one step.
- **On the frame:** a black gutter darkens the page margin and a white one lightens it while the picture stays in the panel, and taking the page off puts the frame back within 0.5 of 255.
The scene's shared stack, the viewport camera, and the test set are put back after each test. The synced `ComicPanels` runner entity a layout call makes is left in place: it keeps no state and idles once the page is off. Run with `zero tests run comicPanelsTests` or `asset.resolve("comicPanelsTests", "testSuite"):run()`.
## Known limits
The per-player extra cameras follow a local player's avatar, and the test runner runs in edit mode with no player, so the suite checks the camera plan rather than the rendered extra views. Those were checked in play in the showcase scene.
# toneScreens
Halftone and tone screens for styleKit: the dots and lines of printed pictures as stackable Tone blocks. Round dots, flat Ben-Day tints, square, diamond and chain dots, line and cross-line screens and a coarse newspaper screen, each in two forms: a **page screen** that holds still on the screen like a printed page, and a **screen on surfaces** that stays on things as the camera moves. Four-colour process (CMYK) plates separate the picture into cyan, magenta, yellow and black dot screens that form rosettes and can be printed out of register.
- Dot size really follows tone: the inked share of each cell equals the coverage the picture asks for.
- Screens never shimmer: where a screen would get too fine to draw, it melts into its flat tone first.
- Every screen block shares one shader and one set of settings, so any screen swaps for any other in one change.
- The screens are also a pure-math shader module (`shaders/halftone.shaderModule`) that any material or package can include.
The package depends on styleKit alone. Nothing in it is comic specific: it serves comic looks (comicBlocks builds on it), manga screentone, printed posters, newspaper photos and engravings alike.
Version 1.0.10. Needs styleKit 1.8.3. 1.0.10 fixes Ben-Day tints printing more than `maxCover`: the tints (`levels`) were even steps of the whole 0 to 1 range, so with two tints every middle tone jumped to half cover, where round dots touch in a hard black-and-white checker, and the darkest tint printed solid whatever `maxCover` said. They are now even steps of 0 to `maxCover`, so Ben-Day dots stay apart. Screens with `levels` 0 and screens with `maxCover` 1 print exactly as before. The examples that name toonBlocks, paperBlocks, starterBlocks or inkBlocks blocks need that Cookbook package installed (comicBlocks brings all but inkBlocks).
Published first as `halftoneScreens` 1.0.0; the same blocks, settings and shader module ship here under the name toneScreens, so a world on the old name swaps the install and changes nothing else (block ids are the same; a shader that includes the module includes `~toneScreens.shaders.halftone`).
## Install
Search ZeroMind for **toneScreens** and install the package from the ZeroMind panel (or with `zeromind.install` and its guid). Installing it registers every block with no code: they show in `StyleKit.blocks({ slot = "tone" })` at once.
## Quick start
```luau
local StyleKit = require("~styleKit.StyleKit")
StyleKit.add("dotScreen", { id = "screen" }) -- round dots, still on the page
StyleKit.swap("screen", "lineScreen") -- a line screen instead: one change
StyleKit.swap("screen", "dotOnSurfaces") -- dots that stay on things as the camera moves
StyleKit.set("screen", { cellPx = 10, angle = 30 }) -- coarser, at another angle
StyleKit.remove("screen") -- four-colour process is a Colour block, not a Tone one,
StyleKit.add("processFourColour", { id = "screen" }) -- so it replaces a tone screen by remove and add: plates and rosettes
StyleKit.set("screen", { offsetCM = { 1.5, 0, 0, -1.2 } }) -- print it a little out of register
StyleKit.remove("screen") -- the frame as it was
```
From the shell: `zero styleKit add dotScreen`, `zero styleKit swap screen lineScreen`, `zero styleKit set screen cellPx 10`.
`add` appends a new entry every time it runs; for setup code that may run again use `StyleKit.load` (it replaces the whole stack) or check `StyleKit.describe()` first.
## The blocks
Every block is in the Tone slot. Page screens hold still on the screen; the `...OnSurfaces` form of each lays the same screen on the surfaces of things.
| Block | Slot | What it does | Starts from |
|---|---|---|---|
| `dotScreen` | Tone | Round halftone dots on the page: dot size follows darkness, dots touch in a checker at half tone and open into white holes in the darks. | `shape` 0, `cellPx` 7, `angle` 45 |
| `dotOnSurfaces` | Tone | The round dot screen laid on surfaces, staying on things as the camera moves. | `shape` 0, `cellPx` 8, `angle` 45 |
| `benDayTint` | Tone | Flat, even Ben-Day tints on the page: each area is one even dot size picked from a few mechanical tints. | `shape` 0, `cellPx` 6, `levels` 3, `flatten` 0.85, `gamma` 0.8, `maxCover` 0.6 |
| `benDayOnSurfaces` | Tone | The flat Ben-Day tints laid on surfaces. | `cellPx` 7, `levels` 3, `flatten` 0.85, `gamma` 0.8, `maxCover` 0.6 |
| `squareDotScreen` | Tone | Square dots that grow with darkness until they close into solid ink, on the page. | `shape` 1, `cellPx` 7, `angle` 45 |
| `squareDotOnSurfaces` | Tone | The square dot screen on surfaces. | `shape` 1, `cellPx` 8 |
| `diamondDotScreen` | Tone | Diamond dots that meet as an exact checkerboard at half tone, on the page. | `shape` 2, `cellPx` 7, `angle` 0 |
| `diamondDotOnSurfaces` | Tone | The diamond dot screen on surfaces. | `shape` 2, `cellPx` 8, `angle` 0 |
| `chainDotScreen` | Tone | Chain (elliptical) dots that link into chains in the middle tones, for smooth skin and sky gradients, on the page. | `shape` 3, `cellPx` 7 |
| `chainDotOnSurfaces` | Tone | The chain dot screen on surfaces. | `shape` 3, `cellPx` 8 |
| `lineScreen` | Tone | Parallel lines that thicken with darkness, like a mezzotint or line-screen print, on the page. | `shape` 4, `cellPx` 6, `angle` 30 |
| `lineOnSurfaces` | Tone | The line screen on surfaces. | `shape` 4, `cellPx` 7, `angle` 30 |
| `crossLineScreen` | Tone | A grid of crossed lines that thicken with darkness, on the page. | `shape` 5, `cellPx` 7 |
| `crossLineOnSurfaces` | Tone | The cross-line screen on surfaces. | `shape` 5, `cellPx` 8 |
| `newsprintScreen` | Tone | A coarse newspaper halftone: big round dots at a low ruling, swollen by dot gain, with ragged edges, on the page. | `cellPx` 12, `gain` 0.55, `rough` 0.6, `maxCover` 0.9, `flatten` 0.7 |
| `newsprintOnSurfaces` | Tone | The coarse newspaper screen on surfaces. | `cellPx` 13, `gain` 0.55, `rough` 0.6, `maxCover` 0.9, `flatten` 0.7 |
| `processFourColour` | Colour | Four-colour process: the picture separated into cyan, magenta, yellow and black plates, each an angled dot screen, forming rosettes; plates can be printed out of register. Page screens. | `cellPx` 6, `angles` 15/75/0/45 |
| `processFourColourOnSurfaces` | Colour | Four-colour process with the plates laid on surfaces. | `cellPx` 7 |
Each block's own README (`StyleKit.block(id).path .. "/README.md"`) says what it gives up in motion and how it treats opaque things, transparent things, particles, sky, fog, skinned characters, foliage and world text.
## The shared settings
### Screen blocks (every block except the two process blocks)
All sixteen screen blocks draw through `blocks/screen.shader` and take the same settings. The block only changes the defaults.
| Setting | Range (default) | What it does |
|---|---|---|
| `shape` | 0 to 5 (0) | 0 round, 1 square, 2 diamond, 3 chain, 4 line, 5 cross-line. |
| `onSurfaces` | 0 or 1 (0) | 0 a page screen that holds still on the screen; 1 a screen laid on the surfaces. |
| `cellPx` | 3 to 48 (7) | Screen pitch in reference pixels (1080p). A screen on surfaces keeps about this size at any distance. |
| `cellCm` | 0 to 200 (0) | On surfaces only: above 0 sizes the screen in centimetres on things, so it shrinks with distance and melts into flat tone far away. |
| `angle` | -90 to 180 (45) | Screen angle in degrees. 45 is the classic single-screen angle; line screens read best at 30 to 60. |
| `ink` | colour (near black) | The ink colour of the dots. |
| `amount` | 0 to 1 (1) | How strongly the dots print. |
| `light` | 0 to 1 (0.88) | Brightness above which no ink prints. |
| `dark` | 0 to 1 (0.08) | Brightness below which the screen prints its fullest cover. |
| `gamma` | 0.2 to 4 (1) | Below 1 more dots in the middle tones, above 1 fewer. |
| `maxCover` | 0 to 1 (0.85) | The most of a cell ink covers in the darkest places (1 prints solid). |
| `levels` | 0 to 8 (0) | Ben-Day tints: above 0 snaps tone to this many flat, even tints. 0 keeps tone continuous. | Since 1.0.10 the tints are even steps of 0 to `maxCover`, so the darkest tint is `maxCover`.
| `gain` | 0 to 1 (0) | Dot gain: ink spreading into the paper, most in the middle tones. |
| `rough` | 0 to 1 (0) | Ragged dot edges from the paper grain and a fine stable noise. |
| `flatten` | 0 to 1 (0.6) | How much of the picture's own shading is lifted out so the dots carry the shade. |
| `print` | 0 to 1 (0) | 0 lays dots over the picture; 1 rebuilds the picture as one ink on blank paper. |
| `keepColour` | 0 to 1 (0) | 0 prints the ink colour; 1 prints each dot in the picture's own colour (coloured dots). |
| `sky` | 0 to 1 (1) | How much the screen prints on the sky. 0 keeps a clean sky. |
### Process blocks (`processFourColour`, `processFourColourOnSurfaces`)
Both draw through `blocks/process.shader`.
| Setting | Range (default) | What it does |
|---|---|---|
| `onSurfaces` | 0 or 1 (0) | Page screens or screens on surfaces. |
| `cellPx` | 3 to 48 (6) | Screen pitch of every plate, reference pixels. |
| `angles` | four degrees (15, 75, 0, 45) | Cyan, magenta, yellow and black plate angles. 30 degrees apart makes small round rosettes. |
| `cyan`, `magenta`, `yellow`, `black` | colours | The process inks. |
| `blackGen` | 0 to 1 (0.6) | How much grey moves into the black plate: 0 muddy three-colour darks, 1 crisp black darks. |
| `levels` | 0 to 8 (0) | Above 0 snaps each plate to this many flat tints (4 gives 0, 25, 50, 75 and 100 percent). |
| `gain` | 0 to 1 (0.15) | Dot gain. |
| `rough` | 0 to 1 (0.15) | Ragged dot edges. |
| `offsetCM` | float4 (0) | Misregistration of the cyan (x, y) and magenta (z, w) plates, reference pixels. A still offset, never a jitter. |
| `offsetYK` | float4 (0) | Misregistration of the yellow (x, y) and black (z, w) plates. |
| `density` | 0.3 to 1.5 (1) | How heavily the colour plates are inked. |
| `sky` | 0 to 1 (1) | How much the plates print on the sky. |
`StyleKit.settingsOf(id)` lists any block's settings with docs, defaults and ranges.
## Swapping
Any tone screen swaps for any other tone screen with one call, and swapping back restores the settings the old block had:
```luau
StyleKit.add("dotScreen", { id = "screen" }) -- a screen to start from
StyleKit.swap("screen", "chainDotScreen") -- the new block's own defaults
StyleKit.swap("screen", "crossLineScreen", { keepSettings = true }) -- carry your tuning (cellPx, light, dark, ink...) across
StyleKit.swap("screen", "dotOnSurfaces", { keepSettings = true }) -- page screen to surface screen, same tuning
```
Because every screen is the same shader, `StyleKit.set("screen", { shape = 2 })` or `{ onSurfaces = 1 }` also changes the screen in place; swapping blocks is the readable way, since `describe()` then names what is drawn. The process blocks (`processFourColour`, `processFourColourOnSurfaces`) are Colour blocks, not Tone, so a tone screen and a process block do not swap for each other (the swap is refused, naming both slots): `StyleKit.remove("screen")` and then `StyleKit.add` the other under the same id. The two process blocks swap for each other.
### Page screen or screen on surfaces?
- **Page screen** (`dotScreen`, `lineScreen`, ...): the dots never move, the picture moves under them. Nothing crawls or shimmers. This is how a printed page behaves, and it is the safe default for a fast camera.
- **Screen on surfaces** (`dotOnSurfaces`, ...): the dots stick to walls and floors and keep their size at any distance, so a pan carries them with the world. They slide on moving characters (the marks come from world position), and transparent things and particles take the screen of the surface behind them. Set `cellCm` above 0 for dots sized in the world that shrink with distance.
## Stacking with the Style Cookbook
A screen is the Tone slot: it sits after Fill (flat colour, washes, noir shapes) and before Line, Colour and Ground. Because the first Ground block publishes the shared paper, a screen's `rough` reads that paper's grain, so dots break on the same tooth the lines do.
```luau
local StyleKit = require("~styleKit.StyleKit")
-- Four-colour dots on newsprint under a bold comic line
StyleKit.load({
{ id = "fill", block = "celFill" }, -- toonBlocks: flat cel colour
{ id = "screen", block = "processFourColour", settings = { cellPx = 7, levels = 4, gain = 0.3 } },
{ id = "line", block = "toonComicLine" }, -- toonBlocks
{ id = "paper", block = "paperNewsprint" }, -- paperBlocks
}, { holdRate = 8 })
-- A screentone page: black and white, line screen in the greys, pen line, plain paper
StyleKit.load({
{ id = "screen", block = "lineScreen", settings = { cellPx = 5, angle = 45, flatten = 0.9 } },
{ id = "line", block = "inkPenLine" }, -- inkBlocks (optional: install it yourself)
{ id = "paper", block = "plainPaper" }, -- starterBlocks
{ id = "mono", block = "duotone" }, -- styleKit
})
-- Engraving: cross-line screen on surfaces over an ink wash
StyleKit.load({
{ id = "wash", block = "inkWash" }, -- inkBlocks (optional: install it yourself)
{ id = "screen", block = "crossLineOnSurfaces", settings = { cellPx = 6, amount = 0.7 } },
{ id = "line", block = "inkNibLine" }, -- inkBlocks (optional: install it yourself)
{ id = "paper", block = "paperParchment" }, -- paperBlocks
})
```
Two screens can share the Tone slot: the second is laid over the first by its strength and mask, for example a `dotScreen` everywhere and a `lineScreen` only in the distance with `StyleKit.setMask("far", { kind = "depth", near = 20, far = 1000, soft = 0.4 })`.
comicBlocks' looks are built on these screens and name the screen entry `screen`. In `sundayStrip`, `dailyStrip`, `popArtDots`, `oneColourSpot` and `twoColourSpotPrint` it is a tone screen, so `StyleKit.swap("screen", ...)` takes any of the 16 here. In `goldenAgeFourColour` and `misprintedPulp` it is four-colour process (Colour slot): it swaps only for `processFourColourOnSurfaces`, and a tone screen goes in by `StyleKit.remove("screen")` then `StyleKit.add("<screen>", { id = "screen" })`.
## Using the shader module
Any shader can draw the same screens:
```wgsl
#include "~toneScreens.shaders.halftone"
// coverage of a round 45 degree screen at screen position px, for a tone of 0.4
let c = ht_tone(luma, 0.88, 0.08, 1.0, 0.85);
let ink = ht_cover(px / cellPx, radians(45.0), 0, c, aa, 0.0, 0.0);
```
| Function | What it gives |
|---|---|
| `ht_cover(p, angle, shape, c, aa, rough, n)` | Ink coverage 0..1 at `p` (in cells) for wanted coverage `c`, antialiased over `aa` cells. |
| `ht_sd(q, shape, c)` | Signed distance to the ink edge, for blending two screens crisply. |
| `ht_rotate(p, a)` | Rotate a position into a screen's axes. |
| `ht_tone(luma, light, dark, gamma, maxCover)` | Wanted coverage from brightness. |
| `ht_tint(c, levels, soft)` | Snap a tone to a few even Ben-Day tints. |
| `ht_gain(c, gain)` | Dot gain. |
| `ht_cmyk(rgb, blackGen)` | Four-colour separation with grey component replacement. |
| `ht_lift(rgb, value)` | A colour at a lighter value with its hue kept. |
| `ht_melt(aa)` | How far a screen melts into flat tone at this cell size. |
| `ht_noise(p)`, `ht_hash(p)` | Small stable noise for ragged edges. |
The module has no bindings and depends on nothing, not even styleKit. Its README lists the same table.
## Multiplayer
The screens are entries in the scene's style stack, which lives on the synced `StyleStack` entity: every player sees the same screen with the same settings, and it is saved with the scene. The blocks keep no state of their own and change nothing on the clock. `StyleKit.setLocal(entry, settings)` lays settings over an entry on one machine only (for example a coarser screen for one player's accessibility setting), and `StyleKit.setLocalEntry(id, entry)` adds a whole local entry for a short effect.
## Quality and cost
Each screen block is one full-frame pass that reads the frame, depth, normals and the ground. A process block is also one pass: the four plates are drawn in the same pass. Screens on surfaces cost a little more than page screens (they reconstruct the surface position from depth). Larger `cellPx` costs nothing more. On the low tier styleKit draws the stack at its low settings; `StyleKit.setQuality("low")` shows what a phone sees and `StyleKit.timings()` gives milliseconds per pass.
### Measured cost
**How it was measured.** 14 November 2026, native desktop app on engine @builtin fbf1751, in the showcase's busy desert (desertKit's oasis valley with its terrain, palms and props, plus 2,500 extra lit boxes and balls in front of the camera from `showcase/LookCost`), drawn at exactly **1920 x 1080** (`viewport.setSize`). Only the engine's own frame cost, never wall clock (this machine was busy with other engines and builds the whole time):
- **GPU, stack passes:** every pass the look adds (its blocks plus styleKit's shared capture, prep, soft field and dim guard) from GPU timestamp queries, the median of each over 150 frames, summed. Repeated runs agree to 0.01 ms.
- **GPU, whole frame:** the engine's own GPU time per frame (`zero profiler cost`, drm_fdinfo) with the look on minus with it off, alternated many times: 25 short rounds plus 5 steady rounds (3 s settle, 8 s windows) for the default look, 15 for the heaviest. This is what a person timing "look off, look on" sees; it is a little above the passes because switching a look on also turns on the frame copies the passes read.
- **Engine-thread CPU:** the engine thread's own CPU time per frame (thread clock, not wall clock; the per-frame median, which ignores the spikes other processes cause), look on minus off, in the same steady rounds. A plain frame of this busy scene costs about 40 ms of engine-thread CPU on this development build, and single readings swing by ±2 to 4 ms, so a change smaller than about 1 ms cannot be told from noise. styleKit's own script work per frame is given beside it.
**Each screen at 1920 x 1080 in the busy scene** (stack pass alone): `dotScreen` and `benDayTint` 0.05 ms, `newsprintScreen` 0.05, `processFourColour` 0.13 (four plates in one pass), and every Tone block shares styleKit's dim guard (two passes, 0.08 ms, once for the whole stack). The screens on surfaces add their steady surface read. None of them adds measurable engine-thread CPU. Whole looks built from these, with whole-frame GPU and CPU, are in comicBlocks' README.
**Web: not measured.** The browser build could not be run from this engine (it runs natively and starts only native clients). The screens are the same WGSL on WebGPU, so on the same graphics card their GPU cost should be close to the numbers above; measure your target with `require("showcase.LookCost")` in the browser build.
## Known limits
- **Page screens hold still while the picture moves under them.** That is how print behaves; in a fast pan the eye reads it as a screen in front of the world. Use the `...OnSurfaces` form when the dots should travel with the world.
- **Screens on surfaces slide on moving characters.** The marks come from world position. Keep a character crisp with a group mask (`StyleKit.options({ groups = { { playerId } } })`, then `StyleKit.setMask("screen", { kind = "group", group = 1, invert = true })`).
- **Transparent things and particles are not in the depth**, so a screen on surfaces gives them the screen of the surface behind. Page screens are not affected.
- **Fine contrasty detail can beat against a fine screen.** Raise `cellPx` if it does.
- **World text collects ink.** Exclude labels a player must read: `StyleKit.options({ exclude = { labelId } })`.
- **Offscreen captures and render-to-texture cameras do not draw the stack** (styleKit's Known limits, #17427). Look at a screen with a presented capture.
- **The `dotOnSurfaces` block summary says it "holds still on the screen like a printed page"**; it is the on-surfaces form and stays on things as the camera moves (its `gives` line and README are right).
## Tests
The package ships `tests/toneScreensTests.testSuite`: every screen passes styleKit's block check in the Tone slot, every page screen has a screen on surfaces with the same settings, any screen swaps for any other in one change, and on the presented frame dot coverage follows tone, a still camera gives a still screen (four-colour misregistration included) and removing a screen puts the frame back exactly. Run it with `zero tests run toneScreensTests`. 6 of 6 pass in the world it ships from.
## Removing it
`StyleKit.remove("screen")` takes one screen off; `StyleKit.clear()` takes the whole look off. The package edits no material, so nothing else needs putting back.
# halftone (shader module)
The halftone and tone screens of toneScreens as pure math with no bindings: round, square, diamond, chain, line and cross-line screens whose inked share of a cell really equals the wanted coverage (dot size follows tone), flat Ben-Day style tints, dot gain (ink spreading into paper), ragged ink edges, four-colour process separation (CMYK with grey component replacement) and a melt to flat tone where a screen would get too fine to draw. Every block in toneScreens draws through it, and any surface material or other package (a manga screentone look, a printed poster material) can include it to draw the same dots: `#include "~toneScreens.shaders.halftone"`.
| Function | What it gives |
|---|---|
| `ht_cover(p, angle, shape, c, aa, rough, n)` | Ink coverage 0..1 at `p` (in screen cells) for wanted coverage `c`, antialiased over `aa` cells. Shapes: 0 round, 1 square, 2 diamond, 3 chain, 4 line, 5 cross-line. |
| `ht_sd(q, shape, c)` | Signed distance in cells to the ink edge (q already rotated): blend two screens in this form and they stay crisp. |
| `ht_rotate(p, a)` | Rotate a position into a screen's axes. |
| `ht_tone(luma, light, dark, gamma, maxCover)` | Wanted coverage from brightness. |
| `ht_tint(c, levels, soft)` | Snap a tone to a few even Ben-Day tints. |
| `ht_gain(c, gain)` | Dot gain: ink spreading into the paper, most in the middle tones. |
| `ht_cmyk(rgb, blackGen)` | Four-colour process separation. |
| `ht_lift(rgb, value)` | A colour at a lighter value with its hue kept, so dots carry the shade. |
| `ht_melt(aa)` | How far a screen melts into its flat tone at this cell size. |
| `ht_noise(p)`, `ht_hash(p)` | Small stable noise for ragged edges. |
It depends on nothing, not even styleKit, so it works in any shader.
# Ben-Day flat tint on surfaces (styleBlock, Tone)
Flat, even Ben-Day tints: each area is one even dot size picked from a few mechanical tints, the flat dot fills of old printed comics, laid on the surfaces so the dots stay on things as the camera moves.
Settings this block starts from: `shape` (0), `onSurfaces` (1), `angle` (45), `cellPx` (7), `flatten` (0.85), `gamma` (0.8), `levels` (3), `maxCover` (0.6). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Ben-Day flat tint (styleBlock, Tone)
Flat, even Ben-Day tints: each area is one even dot size picked from a few mechanical tints, the flat dot fills of old printed comics, holding still on the screen like a printed page.
Settings this block starts from: `shape` (0), `onSurfaces` (0), `angle` (45), `cellPx` (6), `flatten` (0.85), `gamma` (0.8), `levels` (3), `maxCover` (0.6). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Chain dot screen on surfaces (styleBlock, Tone)
A chain (elliptical) dot halftone screen on the surfaces of things: oval dots that link into chains in the middle tones for smooth skin and sky gradients, laid on the surfaces so it stays on things as the camera moves.
Settings this block starts from: `shape` (3), `onSurfaces` (1), `angle` (45), `cellPx` (8). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Chain dot screen (styleBlock, Tone)
A chain (elliptical) dot halftone screen on the page: oval dots that link into chains in the middle tones for smooth skin and sky gradients, holding still on the screen.
Settings this block starts from: `shape` (3), `onSurfaces` (0), `angle` (45), `cellPx` (7). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Cross-line screen on surfaces (styleBlock, Tone)
A cross-line screen on the surfaces of things: a grid of crossed lines that thicken with darkness, laid on the surfaces so it stays on things as the camera moves.
Settings this block starts from: `shape` (5), `onSurfaces` (1), `angle` (45), `cellPx` (8). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Cross-line screen (styleBlock, Tone)
A cross-line screen on the page: a grid of crossed lines that thicken with darkness, holding still on the screen.
Settings this block starts from: `shape` (5), `onSurfaces` (0), `angle` (45), `cellPx` (7). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Diamond dot screen on surfaces (styleBlock, Tone)
A diamond dot halftone screen on the surfaces of things: diamond dots grow with darkness and meet as an exact checkerboard at half tone, laid on the surfaces so it stays on things as the camera moves.
Settings this block starts from: `shape` (2), `onSurfaces` (1), `angle` (0), `cellPx` (8). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Diamond dot screen (styleBlock, Tone)
A diamond dot halftone screen on the page: diamond dots grow with darkness and meet as an exact checkerboard at half tone, holding still on the screen.
Settings this block starts from: `shape` (2), `onSurfaces` (0), `angle` (0), `cellPx` (7). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Round dot screen on surfaces (styleBlock, Tone)
A round halftone dot screen printed on the surfaces of things: dot size follows how dark each place is, the dots touch in a checker at half tone and open into white holes in the darks, and the dots are laid on the surfaces so they stay on things as the camera moves.
Settings this block starts from: `shape` (0), `onSurfaces` (1), `angle` (45), `cellPx` (8). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Round dot screen (styleBlock, Tone)
A round halftone dot screen printed on the page: dot size follows how dark each place is, the dots touch in a checker at half tone and open into white holes in the darks, and the screen holds still on the screen like a printed page.
Settings this block starts from: `shape` (0), `onSurfaces` (0), `angle` (45), `cellPx` (7). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Line screen on surfaces (styleBlock, Tone)
A line screen on the surfaces of things: parallel lines that thicken with darkness, like a mezzotint or line-screen print, laid on the surfaces so it stays on things as the camera moves.
Settings this block starts from: `shape` (4), `onSurfaces` (1), `angle` (30), `cellPx` (7). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Line screen (styleBlock, Tone)
A line screen on the page: parallel lines that thicken with darkness, like a mezzotint or line-screen print, holding still on the screen.
Settings this block starts from: `shape` (4), `onSurfaces` (0), `angle` (30), `cellPx` (6). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Coarse newspaper screen on surfaces (styleBlock, Tone)
A coarse newspaper halftone: big round dots at a low screen ruling, swollen by ink spreading into cheap paper with ragged edges, laid on the surfaces so it stays on things as the camera moves.
Settings this block starts from: `shape` (0), `onSurfaces` (1), `angle` (45), `cellPx` (13), `flatten` (0.7), `gain` (0.55), `maxCover` (0.9), `rough` (0.6). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Coarse newspaper screen (styleBlock, Tone)
A coarse newspaper halftone: big round dots at a low screen ruling, swollen by ink spreading into cheap paper with ragged edges, holding still on the screen.
Settings this block starts from: `shape` (0), `onSurfaces` (0), `angle` (45), `cellPx` (12), `flatten` (0.7), `gain` (0.55), `maxCover` (0.9), `rough` (0.6). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
The full-frame pass of toneScreens' four-colour process blocks (processFourColour and processFourColourOnSurfaces).
# Four-colour process (styleBlock, Colour)
It sits in the **Colour** slot (a colour choice: the inks the page is printed in) as a chain block with rank 90, so it prints whatever a palette before it made.
Four-colour process printing: the picture separated into cyan, magenta, yellow and black plates, each laid down as its own angled dot screen so they form the little rosettes of a printed comic page, holding still on the screen like a printed page; plates can be printed slightly out of register.
Settings: `cellPx` (6), `angles` (15, 75, 0, 45), `blackGen` (0.6), `levels` (0), `gain` (0.15), `rough` (0.15), `offsetCM` and `offsetYK` (no misregistration), `density` (1), the four inks and `sky` (1). Print it out of register with `StyleKit.set(entry, { offsetCM = { 1.5, 0, 0, -1.2 } })`.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; separated into four plates by colour; each plate's dots grow with how much of its ink the colour needs.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Four-colour process on surfaces (styleBlock, Colour)
It sits in the **Colour** slot (a colour choice: the inks the page is printed in) as a chain block with rank 90, so it prints whatever a palette before it made.
Four-colour process printing laid on the surfaces: cyan, magenta, yellow and black plates as angled dot screens forming rosettes, with the dots staying on things as the camera moves; plates can be printed slightly out of register.
Settings: `cellPx` (7), `angles` (15, 75, 0, 45), `blackGen` (0.6), `levels` (0), `gain` (0.15), `rough` (0.15), `offsetCM` and `offsetYK` (no misregistration), `density` (1), the four inks and `sky` (1). Print it out of register with `StyleKit.set(entry, { offsetCM = { 1.5, 0, 0, -1.2 } })`.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; separated into four plates by colour; each plate's dots grow with how much of its ink the colour needs.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
The full-frame pass every toneScreens screen block shares (page screens and screens on surfaces).
# Square dot screen on surfaces (styleBlock, Tone)
A square dot halftone screen on the surfaces of things: square dots grow with darkness until they close into solid ink, laid on the surfaces so it stays on things as the camera moves.
Settings this block starts from: `shape` (1), `onSurfaces` (1), `angle` (45), `cellPx` (8). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
The screen is laid on the surfaces (along each surface's main axis in styleKit's shared coordinates), so a pan, orbit or dolly does not drag it: the dots stay on the walls and floor. It keeps about the same dot size on screen at any distance by blending two neighbouring screen sizes on the surface, so as you walk closer the dots grow into the next size instead of swelling or sliding; in the narrow distance band where two sizes blend, dots take a mixed shape for a moment. A cell is never drawn smaller than about five pixels: where it would be (a floor grazing to the horizon) it melts into flat tone, so there is no moire or shimmer. On a moving skinned character the dots come from world position and slide across the body. Curved surfaces switch dot direction where their main axis changes, which shows as a seam. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them, with the coordinates of the opaque surface behind them.
- Particles and smoke: screened where they change the picture's brightness, with the coordinates of the surface behind them.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else; the dots slide on a moving body.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# Square dot screen (styleBlock, Tone)
A square dot halftone screen on the page: square dots grow with darkness until they close into solid ink, holding still on the screen.
Settings this block starts from: `shape` (1), `onSurfaces` (0), `angle` (45), `cellPx` (7). It shares every setting of the screen shader (see the package README), so any screen swaps for any other with `StyleKit.swap(entry, otherScreen, { keepSettings = true })` keeping your tuning.
## What it gives up in motion
This is a page screen: the dots hold still on the screen, like the dot screen of a printed page, while the picture moves under them. Nothing crawls or shimmers, because the screen never moves and its cells are at least a few pixels across at every resolution (sized in reference pixels). What moves is which dots are inked: as a shadow edge or a light crosses the screen, dots grow and shrink smoothly in place, never popping. Fine contrasty detail in the picture can beat against a fine screen; raise `cellPx` if it does. Nothing changes on the clock, so there is no flicker.
## How it treats content
- Opaque things: screened by their brightness; dark places get big dots or solid ink, light places little or none.
- Transparent things (glass, water): screened by the colour seen through them.
- Particles and smoke: screened where they change the picture's brightness.
- Sky: screened by its brightness, scaled by `sky` (set it to 0 to keep a clean sky).
- Fog: fog lightens things, so far away there are fewer dots.
- Skinned characters: screened like everything else.
- Foliage: screened; dense leaves can look busy, raise `cellPx` or lower `amount`.
- World text: dark letters collect ink; exclude labels a player must read (`StyleKit.options({ exclude = { ... } })`).
- Black stays black: dots only darken, they add no light.
- Dim rooms: kept dim; this is a Tone block, so the stack's dim guard holds a dark room as dark as it was rendered.
# steadySurface (shader module)
Surface coordinates for marks that stay on things, with the engine's antialiasing jitter taken back out. `ts_surface_plane(uv)` returns the same coordinates as styleKit's `sk_surface_plane` (world metres along the surface's main axis, or view-direction radians on the sky), but steady from frame to frame: crisp dots laid on it no longer flicker at their edges on a still camera.
Include it after styleKit's shared prelude in a full-screen (post-process) shader:
```wgsl
#include "~styleKit.shaders.skCommon"
#include "~toneScreens.shaders.steadySurface"
```
Call it from control flow every pixel takes alike (it takes screen derivatives). toneScreens' screens on surfaces and four-colour process on surfaces use it. Unlike `~toneScreens.shaders.halftone`, which is pure maths, this module needs styleKit's prelude.
Measured on a still camera in the showcase street: a black round-dot screen on surfaces went from 20.6 to 1.2 per-pixel standard deviation over ten frames (the untouched frame reads 0.5); on the sky, from 17.6 to 0.7.
# toneScreens tests
Checks the package against styleKit's block rules and against what its docs promise, partly on the presented frame of a small set the suite builds itself (a light wall, a dark wall and a camera of its own), since the test runner empties the scene.
- **Rules:** all eighteen screens are installed from toneScreens, pass `StyleKit.checkBlock` and sit in the Tone slot.
- **Two forms, one set of settings:** every page screen (holds still on the screen) has a screen on surfaces (stays on things) with exactly the same settings, so switching between them is one swap.
- **One change:** any screen swaps for any other in one `StyleKit.swap("screen", id)` that keeps the entry's id.
- **Dot size follows tone:** with the screen's paper lift and print fade off, the round, square, line and newspaper screens each take a larger share of the dark wall's brightness than of the light wall's.
- **Still screen:** on a still camera two settled frames a second apart match under the round, chain, cross-line and four-colour screens, misregistration included. Nothing crawls, shimmers or jitters on the clock.
- **Clean removal:** clearing a stack of screens puts the frame back within 0.5 of 255.
The scene's shared stack, the viewport camera and the test set are put back after each test. Run with `zero tests run toneScreensTests` or `asset.resolve("toneScreensTests", "testSuite"):run()`. It takes about a minute, most of it waiting for frames to settle.
## Known limits
The tests judge the frame by mean brightness over regions, which is what tone means for a screen; they do not count individual dots. Motion of the camera (surface screens staying on things) is covered by the Lookbook's motion numbers in styleKit, not here.