Comic Book Looks: Halftone, Ben-Day, Noir Ink and Panels
README.md
comicPanels
Lay your game out in comic panels. A styleKit Medium block, panelPage, draws the page over any look: panels, gutters, a page margin and inked borders. The ComicPanels module switches between seventeen layouts with one call, from a full splash to slanted action panels and borderless bleeds, with eight border styles (among them a double rule, a jagged action edge and a dashed flashback line), named gutter colours, caption boxes (narration, note, shout, whisper, sound effects and a cover masthead) and whole page presets (a superhero splash, a newspaper strip, a pulp cover, a manga action page and a noir night) that set look, layout, border, gutter and captions in one call.
A page can show the game's one camera through its panels, or several: panels with a framing (close-up, reverse, wide, low angle, overhead, side) get an extra camera that follows each player's own character, on that player's machine. Every player sees the same page layout; each player's extra panels show their own character.
Version 1.1.0. Needs styleKit 1.8.3 and toneScreens 1.0.10. The page presets name comicBlocks looks, so install comicBlocks too for those.
Install
Search ZeroMind for comicPanels and install the package from the ZeroMind panel (or with zeromind.install and its guid). The panelPage block registers at once; the module is require("~comicPanels.ComicPanels").
Quick start
Start with ComicPanels.on(). It lays the page a newcomer should see first (ComicPanels.DEFAULT): slantedAction panels with a hand-inked brush border on a white page, and each panel with a framing gets an extra camera that follows the player. Under goldenAgeFourColour it is the classic superhero page. Or take a whole designed page in one call:
local ComicPanels = require("~comicPanels.ComicPanels")
ComicPanels.on() -- the default page over whatever look is on
ComicPanels.applyPage("superheroSplash") -- or look + layout + border + gutter + captions at once
ComicPanels.applyPage("pulpCover") -- newspaperStrip, pulpCover, mangaAction, noirNight
ComicPanels.caption(1, "Meanwhile, at the oasis...") -- a narration box on the first panel
ComicPanels.caption(2, "Bam!", { style = "sfx", at = "middle" })
ComicPanels.off() -- back to one frame (captions go with it)
Each part on its own:
local ComicPanels = require("~comicPanels.ComicPanels")
local StyleKit = require("~styleKit.StyleKit")
StyleKit.applyLook("goldenAgeFourColour") -- any look (comicBlocks or any Cookbook look)
ComicPanels.setLayout("threeTier") -- one camera seen through three tiers of panels
ComicPanels.setCameras("several") -- panels with a framing get their own camera
ComicPanels.setBorder("brush") -- a brush-inked border
ComicPanels.setGutter("cream") -- cream gutters
ComicPanels.setLayout("slantedAction", { gutterPx = 22 }) -- another layout, wider gutters
ComicPanels.applyLook("comicNoir") -- change look and keep the page over it
ComicPanels.off() -- back to the plain frame
setLayout is safe to run again: it creates the page entry (id panels) the first time and changes it after that.
The layouts
Panels are given as four corners on the page from 0 to 1, top left first. view is what a panel shows when cameras are several; with single, every panel shows the game's own view under it.
| Layout | Panels | View per panel |
|---|---|---|
splash | One big panel inside a margin. | main |
splashInset | A full splash with a small inset over its lower right corner. | main, closeUp |
twoUp | Two tall panels side by side. | main, reverse |
threeTier | A wide establishing tier, a middle tier split in two, a full-width bottom tier. | wide, closeUp, side, main |
fourGrid | Four equal panels, two by two. | main, closeUp, overhead, lowAngle |
newspaperStrip | Three panels in one row across the middle, like a daily strip. | wide, main, closeUp |
tallSplit | One tall panel left, two stacked right. | main, closeUp, overhead |
slantedAction | A wide top panel with a sloping bottom edge, then two panels split by a leaning gutter. | wide, closeUp, main |
slantedDuel | Two panels split by one steep diagonal gutter, for a face-off. | main, reverse |
bleed | Panels running off the page edges, no border, no margin, gutters only. | main, closeUp, wide |
bleedInset | One picture bleeding off every edge with a bordered inset over its upper left. | main, closeUp |
bigTopRow | A big panel across the top two thirds and a row of three below. | main, closeUp, side, overhead |
New in 1.1.0, for action scenes and covers:
| Layout | Panels | View per panel |
|---|---|---|
zigzagStrike | Three full-width panels whose gutters lean one way then the other; jagged border by default. | wide, main, closeUp |
fourSlash | Four tall panels cut by leaning gutters, a rapid flurry read left to right. | lowAngle, closeUp, main, side |
insetTrio | A full splash with three small insets down its right edge. | main, closeUp, lowAngle, side |
mangaStack | Two panels across the top, then two full-width panels cut by a steep slanted gutter. | main, closeUp, wide, lowAngle |
coverSplash | A magazine cover: one big picture under a deep masthead band, with a corner panel; heavy border by default. | main, closeUp |
ComicPanels.layouts() lists them (each { id, name, summary, panels, bleed, border }), ComicPanels.layout(id) gives one. A layout plans at most three extra views; fourSlash and insetTrio draw three and show the main view in the rest.
Borders
ComicPanels.setBorder(name), or border = name in setLayout: clean (the default, an even black rule), brush (swells and thins like a loaded brush), rough (a ragged hand-cut edge), heavy (a thick black frame), double (two thin rules), jagged (a sawtooth edge, like panels cut by an impact), dashed (the broken line comics use for a flashback or a dream) and none. borderPx sets the weight. The last three are new in 1.1.0.
Captions
Caption boxes sit on the panels, are kept in the synced page so every player sees the same ones, and are drawn by each machine as screen UI after the look, so they always read.
ComicPanels.on() -- captions need a page
ComicPanels.caption(1, "Meanwhile...") -- narration (the default style), top left of panel 1
ComicPanels.caption(3, "Pow!", { style = "sfx", at = "middle" }) -- a sound effect over the middle of panel 3
ComicPanels.caption(1, "Thrilling Tales", { style = "masthead", at = "above" }) -- a cover title in the band above the panel
ComicPanels.caption(1, nil) -- take panel 1's top caption away
ComicPanels.clearCaptions()
| Style | Looks like |
|---|---|
narration | The classic yellow box with capitals: "MEANWHILE..." |
note | A white box with plain text: a quieter voice, a noir monologue |
shout | A tilted red box with heavy white capitals: an alarm, a battle cry |
whisper | A dashed box in small grey italics: a thought, a flashback |
sfx | No box: huge tilted yellow letters with a black outline (POW!, BAM!) |
masthead | No box: a cover title, for at = "above" on coverSplash |
at is top (the default), bottom, middle or above; a panel holds one caption per place, so a second call there replaces the first. Captions stay through a layout change and go with off() or clearCaptions(). ComicPanels.CAPTION_STYLES holds the colours and sizes; add your own entry there for a style of your own.
Page presets
A page preset is a look, a layout, a border, a gutter and captions in one synced call: ComicPanels.applyPage(id). ComicPanels.pages() lists them. Each needs comicBlocks for its look and returns false with a reason if the look is not installed.
| Page | Look | Layout, border, gutter | Captions |
|---|---|---|---|
superheroSplash | goldenAgeFourColour | slantedAction, brush, white | none |
newspaperStrip | dailyStrip | newspaperStrip, clean, newsprint | a narration box |
pulpCover | pulpCover | coverSplash, heavy, red | a masthead title and a shouted tagline |
mangaAction | mangaScreentone | mangaStack, clean, white | a sound effect |
noirNight | comicNoir | bleedInset, clean, black | a hard-boiled monologue |
Add your own: ComicPanels.PAGES.myPage = { name = "...", look = "...", layout = "...", cameras = "several", border = "...", gutter = "...", captions = { ... } } and table.insert(ComicPanels.PAGE_ORDER, "myPage").
Keys and buttons: ComicControls
Add the comicPanels.ComicControls component to any entity and every player gets keys and on-screen buttons: ] / [ next and previous look, P panels on and off, L next layout, B next border, K next page preset. Every press is one synced change.
local e = entity.spawn("ComicControls")
e.component.add("comicPanels.ComicControls", {}) -- every comicBlocks look
e.component.add("comicPanels.ComicControls", { looks = "goldenAgeFourColour,comicNoir,popArtDots" }) -- or just these
Its source (ComicControls.component/init.luau) is short and meant to be copied when you want buttons of your own.
Which applyLook?
ComicPanels.applyLook(id) changes the look and keeps the page (and matches the extra views' print to the new look). StyleKit.applyLook(id) replaces the whole stack, page included. In a game with panels, change looks through ComicPanels.applyLook; use StyleKit.applyLook when there are no panels or you want a clean slate. ComicPanels.applyPage(id) sets look and page together.
Your own layout
ComicPanels.define({
id = "heroIntro", name = "Hero intro", summary = "A low angle splash with a close-up strip down the right.",
panels = {
{ corners = { { 0, 0 }, { 0.72, 0 }, { 0.72, 1 }, { 0, 1 } }, view = "lowAngle" },
{ corners = { { 0.72, 0 }, { 1, 0 }, { 1, 0.5 }, { 0.72, 0.5 } }, view = "closeUp" },
{ corners = { { 0.72, 0.5 }, { 1, 0.5 }, { 1, 1 }, { 0.72, 1 } }, view = "main" },
},
})
ComicPanels.setLayout("heroIntro", { cameras = "several" })
One to six panels; later panels draw over earlier ones. bleed = true drops the margin and border = "none" (any border name) sets the layout's own border. define lives in the module, so run it on every machine (from a module or component every peer loads), not from a one-off console call.
The block
| Block | Slot | What it does |
|---|---|---|
panelPage | Medium | Lays the frame into panels with gutters, a margin and inked borders; panels show the game's view or a published extra view (panelView1 to panelView3) with a print treatment of its own. |
Its settings (ComicPanels writes all of them for you; StyleKit.set("panels", { ... }) tunes one directly):
| Setting | What it does |
|---|---|
count | How many panels, 0 to 6. |
p1a .. p6b | Panel corners: a is top left (x, y) and top right (z, w), b bottom right and bottom left. |
sources, sourcesB | What panels 1 to 4 (and 5, 6) show: 0 the game's view, 1 to 3 that extra view. |
gutter, border | Gutter and margin colour, border colour. |
borderPx (3), gutterPx (16), marginPx (22) | Widths in reference pixels (1080p). |
borderStyle | 0 clean, 1 brush, 2 rough, 3 heavy black, 4 none. |
viewInk (0.8), viewLevels (4), viewDots (0.6), viewMono (0), viewScreenPx (7) | The extra views' print treatment: ink edge, flat tints, dot screen in the shadows, black and white, dot pitch. |
mainCentre | How a panel showing the main view frames it: z 0 shows the part of the view under the panel, z 1 shows the part around (x, y) at the same scale. |
The shared settings
ComicPanels.setLayout(id, opts) takes:
| Option | What it does |
|---|---|
cameras | "single" (default): every panel shows the game's one view. "several": panels with a framing get a per-player extra camera (at most three distinct framings per layout). Kept between calls. |
border | clean, brush, rough, heavy, none (ComicPanels.BORDERS). Kept between calls unless the layout has its own. |
gutter | A name in ComicPanels.GUTTERS (white, cream, newsprint, black, red, blue, yellow, grey) or "#rrggbb". Kept between calls. |
borderColour | "#rrggbb" for the border ink. |
borderPx, gutterPx, marginPx | Widths in reference pixels. marginPx defaults to 22, or 0 for a bleed layout. |
viewScale | The extra views' resolution relative to their panel on screen, 0.25 to 1 (default 0.5). Lower costs less. |
viewEvery | Extra views take turns: each redraws every this many frames, staggered (1 every frame, 2 the default, up to 4). A panel holds its last picture in between. Two views at 2 cost about what one did at 1. |
The camera framings (ComicPanels.FRAMINGS, listed by ComicPanels.framings()) are placed relative to the player's body and its facing:
| Framing | Shot |
|---|---|
closeUp | The player's face, from the front. |
reverse | The player from the front, a little wider, looking back. |
wide | A high wide establishing shot behind and above. |
lowAngle | A heroic low angle, looking up at the player. |
overhead | Straight down from above. |
side | The player in profile. |
Each framing is { eye = { right, up, forward }, at = { right, up, forward }, fov }; change one in a module every peer loads, for example ComicPanels.FRAMINGS.closeUp.fov = 28.
The rest of the API
| Call | What it does |
|---|---|
ComicPanels.setLayout(id, opts?) | Lay the view into a layout; false for an unknown id. |
ComicPanels.setCameras("single" | "several") | Change the camera mode and keep the layout. |
ComicPanels.setBorder(style) | Change the border style; false when no page is shown. |
ComicPanels.setGutter(colour) | Change the gutter colour; false when no page is shown. |
ComicPanels.matchLook() | Match the extra views' print treatment to the look now in the stack (ComicPanels.TREATMENTS). |
ComicPanels.applyLook(id) | Apply a whole look and keep the page (and every other Medium entry) over it, then match the treatment. |
ComicPanels.plan(layoutId, cameras) | The extra views a layout asks for and the source each panel shows. |
ComicPanels.off() | Remove the page entry; the frame is the plain view again. |
ComicPanels.state() | { layout, cameras, border, gutter, enabled, viewScale, viewEvery, framings, captions }. |
ComicPanels.on(opts?) | Lay ComicPanels.DEFAULT (slantedAction, several cameras, brush, white); opts overrides any part. |
ComicPanels.applyPage(id) / pages() | Apply a page preset / list them. |
ComicPanels.caption(panel, text, opts?) / captions() / clearCaptions() | Lay, read and clear caption boxes. |
ComicPanels.views() | The extra views this machine draws now (framing and texture size). |
Swapping
- A layout for a layout:
ComicPanels.setLayout("fourGrid")keeps the camera mode, border and gutter you set. - A look under the page:
ComicPanels.applyLook("dailyStrip"). A plainStyleKit.applyLookreplaces the page too, unless you keep the Medium slot:StyleKit.applyLook("dailyStrip", { keep = { "medium" } }), thenComicPanels.matchLook(). - A look and your own line under the page:
StyleKit.applyLook("goldenAgeFourColour", { keep = { "line", "medium" } }), thenComicPanels.matchLook()(ComicPanels.applyLooktakes nokeepof its own).
Stacking with the Style Cookbook
The page is the Medium slot, the last in the stack, so every other block draws first and the page frames the finished picture. It sits over any look:
StyleKit.applyLook("comicInkCel") -- toonBlocks
ComicPanels.setLayout("splashInset", { cameras = "several", border = "brush" })
StyleKit.applyLook("pictureBook") -- watercolorBlocks (optional: install it yourself)
ComicPanels.setLayout("bleed") -- a picture-book spread with no borders
StyleKit.applyLook("noirInk") -- inkBlocks (optional: install it yourself)
ComicPanels.setLayout("slantedDuel", { gutter = "black", border = "none" })
Other Medium blocks (starterBlocks softGrain, vignette) can share the slot; they are laid over the page by strength, so a vignette darkens the gutters too. Put the page last with StyleKit.move("panels", n) if you want the grain inside the panels only.
Multiplayer
- The page is shared. It is one entry in the synced
StyleStack, so every player sees the same layout, border and gutter, and it is saved with the scene. Whichever player sets it, it reaches everyone already in the world and everyone who joins later. - The extra cameras are each player's own. Every machine draws its own extra views: it spawns its cameras locally (never synced), each following that machine's own player avatar and rendering into a texture published with
StyleKit.publishInputaspanelView1topanelView3. Player A's close-up shows A, player B's shows B. - How each machine knows to draw them.
setLayoutspawns one syncedComicPanelsrunner with itsComicPagecomponent in the same spawn message, so a machine never receives the runner without the component, and a player who joins later gets the whole runner. TheComicPanelsmodule drives the cameras once per machine, however many runners the scene holds. And because a runner spawned during play can still fail to reach a machine, every machine that has the module loaded checks once a second in play: if the page asks for extra views and nothing there has drawn them for 1.5 seconds, it gives itself a local runner. Nobody has to set the layout again. - With
cameras = "single"nothing is spawned on any machine.
Tested with two players (14 November 2026, the desert showcase, two clients in one play session). Both saw the same look at every step, and a look changed on either machine changed both. The second player, joining after the first, set a layout with two extra views; the first player, who had not touched panels, got the same layout with two working views of their own (cameras 2.0 m and 13.1 m from their own player), with nobody setting it again. When only the second player moved 25 m, their cameras followed them and the first player's stayed with the first player. Also tested: a machine holding the runner without its component (what the first player's machine held when its panels went black in 1.0.10) gets its views back within 3 seconds, and a second runner, or a stale one from an older release, no longer switches anyone's views off.
Quality and cost
The page itself is one full-frame pass. Each extra view is a full render of the scene from another camera into a texture sized to its panel times viewScale, so a layout with three framings costs up to three extra scene renders on every machine. Lower viewScale (0.35 or 0.25) or raise viewEvery on slow machines or phones; cameras = "single" costs only the page 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.
Panels: the page is cheap, each extra view is a whole extra render of the scene. Change with the default look on, at the defaults (views take turns, viewEvery = 2, at half resolution, viewScale = 0.5), steady on/off rounds, same busy desert at 1080p:
| Panels | GPU, whole frame | Engine-thread CPU |
|---|---|---|
Page only (cameras = "single", any layout) | +0.1 ms (the page pass; three rounds +0.66, +0.03, -0.29) | no measurable change |
| 1 extra view | +1.4 ms (six rounds, +0.7 to +2.0) | +6.6 ms (six rounds, +1.3 to +9.3) |
| 2 extra views | +2.7 ms (three rounds, +2.4 to +2.9) | +18 ms (three rounds, +14 to +22) |
Each extra view costs what your scene costs to draw again: here about 1.2 to 1.4 ms of GPU per view, and on the CPU side a second culling and submission of every object, which in this scene of thousands of things is the larger bill (about 6 ms for the first view and about 11 ms more for the second). In a lighter scene both are smaller. A package cannot let a second camera share the main camera's shadows or culling (engine settings are world-wide), so the levers are the view settings: raise viewEvery to 3 or 4 (each view redraws less often), lower viewScale (0.35 or 0.25: less GPU, the same CPU), or keep cameras = "single" for busy gameplay and use extra views for showcase moments, cutscenes and quieter scenes. Cameras reach 250 m (ComicPanels.VIEW_FAR).
The looks under the page, for reference (GPU stack passes at 1080p in the same scene): goldenAgeFourColour 0.41 ms, modernFlatColour 0.28, misprintedPulp 0.47, oneColourSpot 0.65, twoColourSpotPrint 0.72, sundayStrip 0.86, dailyStrip 0.87, comicNoir 1.05, popArtDots 1.18; comicBlocks' README has the whole-frame and CPU numbers.
Web: not measured. The browser build could not be run from this engine (it runs natively and starts only native clients), so no browser frame was timed; the extra views are ordinary scene renders on WebGPU and cost what your scene costs to draw there.
Known limits
- Extra views do not get the look's own blocks. The look stack runs only on the presented frame, never on a camera that renders into a texture (styleKit Known limit, #17427).
panelPagegives extra views a print treatment of its own (flat tints, a dot screen in the shadows or black and white, and an ink edge) matched to the look by name inComicPanels.TREATMENTS; a look not in that table gets thedefaulttreatment. RunComicPanels.matchLook()after changing the look by hand. - At most six panels and three extra views. A layout asking for more than three distinct framings shows the main view in the rest.
- Extra views need a local player avatar. In a scene without players, or before the avatar spawns, the extra cameras stay where they were made.
- The main view is not re-framed per panel by default. A panel showing the main view is a window onto the part of the view under it.
ComicPanels.setLayout(id, { centreMain = true })shows the middle of the view in it instead; that shifts the finished picture, so a later screen-space pass (an ink line drawn after the page) can leave a faint outline at the unshifted place. - Screen UI is drawn after the stack, on top of the page and gutters, unchanged: place HUD elements so they do not sit on a gutter you care about.
- Small world text in extra views gets the ink edge and may be hard to read.
- Custom layouts and framings are module state. Define them in code every machine runs.
- Black extra panels. Up to 1.0.10, a player already in the world could see the extra panels turn solid black when another player set the layout: the runner that drives each machine's cameras reached that machine without its component (or not at all), so nothing there drew the views until that player set the layout themselves. Fixed in 1.0.11 (see Multiplayer). Separately, the engine can refuse a render-to-texture camera's draws on a client that has only just joined while its terrain textures are still loading ("texture has been destroyed"): engine issue #24473, filed on 13 November 2026 and still open. It shows as a black stretch in the extra panels on that client, and it was seen again on 14 November. Switching the views off and on (
C, orComicPanels.setCameras("single")then"several") brings them back. If extra panels still read black, check that the machine has panel cameras (ComicPanels.views()lists what it draws) before blaming the renderer.
Tests
The package ships tests/comicPanelsTests.testSuite: the panel page passes styleKit's block check in the Medium slot, all seventeen layouts lay out in one change and read back, each layout plans at most three per-player extra views, borders, gutters and cameras switch by name, a look change keeps the page, on the presented frame the gutter shows at the margin and the page comes off cleanly, and the extra views survive several runners and a runner without its component (the 1.0.10 black-panels case: one driver per machine, and a component-less runner does not block setLayout), and captions, page presets, on() and every border style set and read back. Run it with zero tests run comicPanelsTests. 8 of 8 pass in the world it ships from, and in a fresh world that has just installed the package.
Removing it
ComicPanels.off() removes the page entry and stops the extra cameras on every machine; the look under it stays. StyleKit.clear() removes the whole look with the page. Deleting the ComicPanels entity removes the synced settings.