Log inGet started
World

Comic Book Looks: Halftone, Ben-Day, Noir Ink and Panels

Branchmain
Branchesmain
Commit79e4166043

README.md

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

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.

BlockSlotWhat it doesStarts from
dotScreenToneRound 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
dotOnSurfacesToneThe round dot screen laid on surfaces, staying on things as the camera moves.shape 0, cellPx 8, angle 45
benDayTintToneFlat, 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
benDayOnSurfacesToneThe flat Ben-Day tints laid on surfaces.cellPx 7, levels 3, flatten 0.85, gamma 0.8, maxCover 0.6
squareDotScreenToneSquare dots that grow with darkness until they close into solid ink, on the page.shape 1, cellPx 7, angle 45
squareDotOnSurfacesToneThe square dot screen on surfaces.shape 1, cellPx 8
diamondDotScreenToneDiamond dots that meet as an exact checkerboard at half tone, on the page.shape 2, cellPx 7, angle 0
diamondDotOnSurfacesToneThe diamond dot screen on surfaces.shape 2, cellPx 8, angle 0
chainDotScreenToneChain (elliptical) dots that link into chains in the middle tones, for smooth skin and sky gradients, on the page.shape 3, cellPx 7
chainDotOnSurfacesToneThe chain dot screen on surfaces.shape 3, cellPx 8
lineScreenToneParallel lines that thicken with darkness, like a mezzotint or line-screen print, on the page.shape 4, cellPx 6, angle 30
lineOnSurfacesToneThe line screen on surfaces.shape 4, cellPx 7, angle 30
crossLineScreenToneA grid of crossed lines that thicken with darkness, on the page.shape 5, cellPx 7
crossLineOnSurfacesToneThe cross-line screen on surfaces.shape 5, cellPx 8
newsprintScreenToneA 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
newsprintOnSurfacesToneThe coarse newspaper screen on surfaces.cellPx 13, gain 0.55, rough 0.6, maxCover 0.9, flatten 0.7
processFourColourColourFour-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
processFourColourOnSurfacesColourFour-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.

SettingRange (default)What it does
shape0 to 5 (0)0 round, 1 square, 2 diamond, 3 chain, 4 line, 5 cross-line.
onSurfaces0 or 1 (0)0 a page screen that holds still on the screen; 1 a screen laid on the surfaces.
cellPx3 to 48 (7)Screen pitch in reference pixels (1080p). A screen on surfaces keeps about this size at any distance.
cellCm0 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.
inkcolour (near black)The ink colour of the dots.
amount0 to 1 (1)How strongly the dots print.
light0 to 1 (0.88)Brightness above which no ink prints.
dark0 to 1 (0.08)Brightness below which the screen prints its fullest cover.
gamma0.2 to 4 (1)Below 1 more dots in the middle tones, above 1 fewer.
maxCover0 to 1 (0.85)The most of a cell ink covers in the darkest places (1 prints solid).
levels0 to 8 (0)Ben-Day tints: above 0 snaps tone to this many flat, even tints. 0 keeps tone continuous.
gain0 to 1 (0)Dot gain: ink spreading into the paper, most in the middle tones.
rough0 to 1 (0)Ragged dot edges from the paper grain and a fine stable noise.
flatten0 to 1 (0.6)How much of the picture's own shading is lifted out so the dots carry the shade.
print0 to 1 (0)0 lays dots over the picture; 1 rebuilds the picture as one ink on blank paper.
keepColour0 to 1 (0)0 prints the ink colour; 1 prints each dot in the picture's own colour (coloured dots).
sky0 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.

SettingRange (default)What it does
onSurfaces0 or 1 (0)Page screens or screens on surfaces.
cellPx3 to 48 (6)Screen pitch of every plate, reference pixels.
anglesfour degrees (15, 75, 0, 45)Cyan, magenta, yellow and black plate angles. 30 degrees apart makes small round rosettes.
cyan, magenta, yellow, blackcoloursThe process inks.
blackGen0 to 1 (0.6)How much grey moves into the black plate: 0 muddy three-colour darks, 1 crisp black darks.
levels0 to 8 (0)Above 0 snaps each plate to this many flat tints (4 gives 0, 25, 50, 75 and 100 percent).
gain0 to 1 (0.15)Dot gain.
rough0 to 1 (0.15)Ragged dot edges.
offsetCMfloat4 (0)Misregistration of the cyan (x, y) and magenta (z, w) plates, reference pixels. A still offset, never a jitter.
offsetYKfloat4 (0)Misregistration of the yellow (x, y) and black (z, w) plates.
density0.3 to 1.5 (1)How heavily the colour plates are inked.
sky0 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:

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.

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:

#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);
FunctionWhat 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.