Log inGet started
World

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

Branchmain
Branchesmain
Commit79e4166043

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.

LayoutPanelsView per panel
splashOne big panel inside a margin.main
splashInsetA full splash with a small inset over its lower right corner.main, closeUp
twoUpTwo tall panels side by side.main, reverse
threeTierA wide establishing tier, a middle tier split in two, a full-width bottom tier.wide, closeUp, side, main
fourGridFour equal panels, two by two.main, closeUp, overhead, lowAngle
newspaperStripThree panels in one row across the middle, like a daily strip.wide, main, closeUp
tallSplitOne tall panel left, two stacked right.main, closeUp, overhead
slantedActionA wide top panel with a sloping bottom edge, then two panels split by a leaning gutter.wide, closeUp, main
slantedDuelTwo panels split by one steep diagonal gutter, for a face-off.main, reverse
bleedPanels running off the page edges, no border, no margin, gutters only.main, closeUp, wide
bleedInsetOne picture bleeding off every edge with a bordered inset over its upper left.main, closeUp
bigTopRowA 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:

LayoutPanelsView per panel
zigzagStrikeThree full-width panels whose gutters lean one way then the other; jagged border by default.wide, main, closeUp
fourSlashFour tall panels cut by leaning gutters, a rapid flurry read left to right.lowAngle, closeUp, main, side
insetTrioA full splash with three small insets down its right edge.main, closeUp, lowAngle, side
mangaStackTwo panels across the top, then two full-width panels cut by a steep slanted gutter.main, closeUp, wide, lowAngle
coverSplashA 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()
StyleLooks like
narrationThe classic yellow box with capitals: "MEANWHILE..."
noteA white box with plain text: a quieter voice, a noir monologue
shoutA tilted red box with heavy white capitals: an alarm, a battle cry
whisperA dashed box in small grey italics: a thought, a flashback
sfxNo box: huge tilted yellow letters with a black outline (POW!, BAM!)
mastheadNo 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.

PageLookLayout, border, gutterCaptions
superheroSplashgoldenAgeFourColourslantedAction, brush, whitenone
newspaperStripdailyStripnewspaperStrip, clean, newsprinta narration box
pulpCoverpulpCovercoverSplash, heavy, reda masthead title and a shouted tagline
mangaActionmangaScreentonemangaStack, clean, whitea sound effect
noirNightcomicNoirbleedInset, clean, blacka 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

BlockSlotWhat it does
panelPageMediumLays 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):

SettingWhat it does
countHow many panels, 0 to 6.
p1a .. p6bPanel corners: a is top left (x, y) and top right (z, w), b bottom right and bottom left.
sources, sourcesBWhat panels 1 to 4 (and 5, 6) show: 0 the game's view, 1 to 3 that extra view.
gutter, borderGutter and margin colour, border colour.
borderPx (3), gutterPx (16), marginPx (22)Widths in reference pixels (1080p).
borderStyle0 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.
mainCentreHow 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:

OptionWhat 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.
borderclean, brush, rough, heavy, none (ComicPanels.BORDERS). Kept between calls unless the layout has its own.
gutterA 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, marginPxWidths in reference pixels. marginPx defaults to 22, or 0 for a bleed layout.
viewScaleThe extra views' resolution relative to their panel on screen, 0.25 to 1 (default 0.5). Lower costs less.
viewEveryExtra 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:

FramingShot
closeUpThe player's face, from the front.
reverseThe player from the front, a little wider, looking back.
wideA high wide establishing shot behind and above.
lowAngleA heroic low angle, looking up at the player.
overheadStraight down from above.
sideThe 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

CallWhat 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 plain StyleKit.applyLook replaces the page too, unless you keep the Medium slot: StyleKit.applyLook("dailyStrip", { keep = { "medium" } }), then ComicPanels.matchLook().
  • A look and your own line under the page: StyleKit.applyLook("goldenAgeFourColour", { keep = { "line", "medium" } }), then ComicPanels.matchLook() (ComicPanels.applyLook takes no keep of 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.publishInput as panelView1 to panelView3. Player A's close-up shows A, player B's shows B.
  • How each machine knows to draw them. setLayout spawns one synced ComicPanels runner with its ComicPage component 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. The ComicPanels module 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:

PanelsGPU, whole frameEngine-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). panelPage gives 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 in ComicPanels.TREATMENTS; a look not in that table gets the default treatment. Run ComicPanels.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, or ComicPanels.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.