Woodblock Print Looks: Ukiyo-e and Shin-hanga Style Blocks
README.md
ukiyoeBlocks: make your game look like a Japanese woodblock print
Turn any 3D scene into a running, moving Japanese woodblock print, in the classic ukiyo-e manner (flat colour, no shadows, bold carved outlines) or the later shin-hanga manner (real light, rain and dusk mood flattened into a few colour blocks). Every piece is a styleKit look block, so it stacks and swaps with every Style Cookbook block: a woodblock key line over a Cookbook paper, ukiyo-e plus film grain, a watercolor wash under a carved line.
Put the look on a scene in a few minutes
- Install ukiyoeBlocks from ZeroMind (it brings styleKit, inkBlocks and styleRoles).
- Run, from any script or the console:
local Woodblock = require("~ukiyoeBlocks.Woodblock")
Woodblock.apply("classicLandscape") -- the whole look, for every player
That is the whole setup, and it works in any scene. A scene tells the look where its water is with Woodblock.setWater (and setLake for a lake); a scene that never says has no water, so its ground keeps the print's own colours and nothing is banded as water. If your world has water:
Woodblock.setWater(seaHeight) -- the world height of your sea surface
Woodblock.setLake(y, x, z, radius) -- a round lake at its own height, if you have one
- Press play and walk. That is the whole setup: the look lives on the scene's synced
StyleStack, so every player sees it, a late joiner gets it, and it is saved with the scene.
Then switch anything with one change:
Woodblock.apply("nightRainShinHanga") -- another whole look
Woodblock.useLine("wornLine") -- another key line
Woodblock.usePalette("fadedOld") -- another palette
Woodblock.timeOfDay("dusk") -- dawn, day, dusk, night sky and water
Woodblock.weather("snow") -- rain, snow or clear: real Cloudburst weather in the ink looks
Woodblock.give(playerBody, "hero") -- hero, enemy, friendly (crowd), boss, pickup ...
Woodblock.useLight("shinHanga") -- the Light slot: "ukiyoe" (no cast shadows) or "shinHanga"
Woodblock.age(0.6) -- age the whole print over any look; false takes it off
Woodblock.quality("high") -- every player's stack resolution: medium (default, full resolution), high, low, auto
Woodblock.clear() -- back to the plain render
What is in it
Light (Light slot): lightUkiyoe (the flat light of a classic print: the sun casts no shadows on any player's machine while it is on, and the remaining shading is evened toward one level) and lightShinHanga (real light, shadow and mood kept, softened, the shadow side printed cool). Every look carries one.
Key lines (Line slot), all one shader so they swap with settings intact: keyLine (bold sumi key line), hairLine (fine hairline), brushCutLine (tapering brush-cut), colourLine (line in a deep shade of the colour it bounds), wornLine (worn, broken line of an old block). Weight is varied the way a block is cut: heavy outer contours where depth jumps, fine lines on faces, hands and folds, thinner with distance.
Flat colour (Fill slot): flatUkiyoe (surface colour only: no shading and no cast shadows at all), flatShinHanga (real light cut into three colour blocks, cool indigo shadows), flatShinHangaNight (a night print in two deep indigo blocks: the palette's shadow ink where the light does not reach and its moonlit blue where it does, so the sun's or moon's cast shadows stay visible as the darker block; only vivid accents such as lanterns, a vermilion gate or a costume keep their own warm ink, and lanterns, fires and lit windows keep their glow).
How a colour finds its ink: each surface's colour is averaged over a small patch (so a mottled texture reads as one colour) and printed in the nearest ink of the palette, matched in a perceptual colour space hue first: browns, wood and earth go to the palette's earth ink (yellow ochre in the classic palette), reds to vermilion, greens to willow, blues to Prussian blue or indigo, skin to pale pink. Dull warm mid-tones (bark, leaf litter, dirt, thatch) are cut in the earth ink outright, so ground never prints pink or violet. Greys never take a hue: they print in sumi, the palette's shadow ink, its air tint or bare paper. Each pixel takes exactly one ink (no blended seam between two), and after light, night level and distance have changed a colour it is settled on an ink again (the fill's settle setting), so a saturated colour the palette lacks (a magenta kimono) prints in the nearest ink at any time of day. Where the scene renders black, the print uses sumi. Only a pixel that is itself bright (a lantern, a lit window) keeps a glow, and that glow is printed in its own ink. Lines are cut crisp (the line blocks' crisp setting), so a line edge is sumi or the colour beside it, never an in-between. Measured with the package's InkCheck module on the showcase village by day: 93% of pixels sit within a small step of the palette's inks, its shadow, its air or the sky bands at the default tier (57% before 1.0.13), and about 90% in fast mode by day and at dusk.
Weather (1.1.0: real weather from Cloudburst): the blocks no longer print falling rain or snow on the screen. A look that wants rain or snow (nightRainShinHanga, snowScene, or Woodblock.weather("rain" | "snow")) drives the Cloudburst weather kit: install Cloudburst from ZeroMind beside ukiyoeBlocks (without it the looks print no falling weather and Woodblock.weather returns false with the reason). Rain falls in Cloudburst's ink / woodblock look (long even inked lines) with ink splashes, and snow as its big round flakes: drops stop under roofs, splash where they land, wet the ground and are the same for every player. A scene that already runs Cloudburst keeps its own weather entity and every Woodblock.apply switches it to the ink looks; a scene with none gets a synced WoodblockWeather entity the first time a look asks for rain or snow. A look that asks for no weather clears weather a woodblock look made and leaves a world's own weather falling. WoodblockWeather is the bridge (want, inkLooks, kind), and a look states its weather in look.yaml as weather: { kind, intensity }. Snow lies on everything that faces up but never on the sea or a lake (it is told where the water is by setWater and setLake).
No black frames: a look's shaders compile in the background once a scene with a look loads (Woodblock.warmShaders(), called by the look's helpers), and fast mode switches to its effect only once it has compiled, so switching a look, the weather or the time of day never waits on a compile.
Palettes (pigment sets): classicPrint (indigo, Prussian blue, vermilion, ochre, sumi, paper white), deepBlue (blue landscape), fadedOld (faded old print), nightPrint, snowPrint, warmDusk.
Bokashi (Fill slot), graded wiped colour bands on whatever sky the world has and on water deepening away from the shore: bokashiDawn, bokashiDay, bokashiDusk, bokashiNight, bokashiShore (water only).
Patterns: waveCrests (curling waves with foam claws, their rows kept about 34 pixels apart at any distance so they read from a player's eye height as well as from above), scrollClouds, mistBands, snowCover (snow lying on roofs, ground and everything facing up, and on tree canopies and hedges on every face not turned down). The rainStrokes and snowFlakes blocks of 1.0 are gone: falling rain and snow are Cloudburst weather, and a stack saved with them is cleaned of them by the next Woodblock.weather call.
Paper and wood (Ground slot): washiFresh, washiAged (yellowed, foxed, browned edges), woodgrainStrong, barenRubbed (rubbing marks). They publish the shared ground and paper field, so inkBlocks lines feather on washi and every Cookbook paper swaps in for them.
Print touches: misregister (a slight registration offset that holds still), printMargin (bare paper margin, border line and a blank title box: nothing is ever written in it).
Whole looks (one change each), with pictures and a short description of the four main ones in docs/looks.md: classicLandscape, nightRainShinHanga, snowScene, seaAndWave, actorPrint (bold figure print), deepBlue, warmDusk, fadedAntique, mistyMountain, dawnLake.
Readability: the woodblock role set: the hero in a bold vermilion-edged line with a warm glaze, enemies in the heaviest indigo-black line with a cold glaze, the crowd (friendly) in a finer, quieter line. Woodblock.apply turns it on.
Every look uses the same entry ids (fill, bokashi, clouds, mist, waves, snow, register, line, paper, rain, flakes, margin), so StyleKit.swap("paper", "paperKraft") or StyleKit.add("softGrain") mixes Cookbook blocks in with one change (install paperBlocks for the papers and starterBlocks for softGrain first; inkBlocks comes with ukiyoeBlocks).
Guides and workflow
- How to make my game look like a Japanese woodblock print (
guides/how-to-make-a-woodblock-print-look). - Example: a small ninja stealth level in woodblock print style (
guides/example-ninja-stealth-level). - Workflow woodblockWorld: turns an existing scene into the look step by step, with the undo for every change:
zero workflow start --name woodblockWorld --args '{"subject":"scenes.main","look":"classicLandscape"}'.
Fast mode: the whole look in one pass
Woodblock.fast(true) -- every player: the look drawn by ONE screen effect (0.43 ms GPU, no script)
Woodblock.fast(false) -- back to the full block stack
Fast mode derives its settings from the woodblock look on the stack (palette, line, sky, water, curling wave crests and foam, lying snow, paper, registration, margin, weather, the night ceiling) and switches the stack entries off; switching looks, time of day or weather while it is on updates it. It matches colours to the inks with the same rules as the full stack. It reads only the frame and depth, so it has no per-object roles; cast shadows are kept as neutral value (the sky's blue tint is taken out of them) rather than removed. Use the full stack for close-up character work and fast mode where the budget matters (the browser, large crowds). The showcase toggles it with F. Woodblock.fast(false) switches off every fast-mode helper in the scene and gives the stack back, and Woodblock.clear() takes fast mode off with the look; on every machine the fast effect is checked once a second against the helpers and comes off when none is on, so it can never stay on screen over the full look (1.0.14). A look change while fast mode is on redraws fast mode in the new look; after fast mode is off, a look change draws only the full stack.
Fast mode is an engine screen effect, so it draws through game cameras (play mode, any player camera) and not through the editor's own fly camera, which draws without screen effects; the full stack draws in both.
Quality and cost
- Lines are found from depth and normals every frame, at least about a drawn pixel wide, and taper and wear are calmed on objects with a role, so outlines hold on a walking character.
- Still lines on a still picture. The engine's temporal antialiasing (TAA, on in new worlds) moves the camera by a different sub-pixel offset every frame in a cycle of eight and averages the frames before any look is drawn, so lines found in the frame would step a pixel with it and shimmer. While a woodblock look is on, every player's machine stands TAA aside (the
WoodblockLighthelper,steadyLines), and hands it back unchanged when the look is cleared. The carved line covers the edges a print shows. SetsteadyLines = falseon the helper to keep TAA. - Rain and snow are sparse and sized in reference pixels; wave and grain patterns fade before they get finer than a set number of pixels: nothing fills the view with fine stripes, and nothing flashes.
- Cost, desktop (the engine's own GPU timestamps,
zero profiler gpu, in the showcase valley: about 2,850 things plus 9,300 instanced props, 2097 x 1409 pixels, every styleKit pass summed):- Full Night Rain stack at the default woodblock tier (
medium, full resolution): about 2.0 ms;"high"2.3 ms. Every woodblock look sets the tier on every player's machine through the syncedWoodblockLighthelper.Woodblock.quality("low")draws the stack at half resolution (0.64 ms), but the upscale softens every line edge into in-between colours that are not in the palette (77% of pixels on the inks instead of 93%); for a budget under 1 ms use fast mode, which keeps to the inks."auto"lets each device choose. - Fast mode (one effect, no roles): 0.43 ms.
- Script: about 0.2 to 0.3 ms of styleKit script a frame (the per-frame queueing below).
- Full Night Rain stack at the default woodblock tier (
- Cost, browser: not measured. This package was built and measured in the native desktop engine; no browser engine could be reached from that session, so there is no browser number to give. Measure it yourself in the browser build with
tools.use("profiler", "gpu", 120)after the look has run for 15 seconds, summing thepost.sk.*andcompute.styleKit.*rows;docs/performance.mdexplains the reading.
Tests
asset.resolve("ukiyoeBlocks", "testSuite"):run() checks every block (28) against styleKit's block rules and its slot, that every look applies in one change with its palette, that every palette loads, that the API's swaps are one change each, that water is kept while each look brings its own weather, that the role set is picked, that a scene without water prints none, and that the 1.0.13 promises hold (fills settle on inks, crisp lines, full resolution by default, night blocks and shadows, straight rain, snow off water, every shader warmed). It saves the stack first and puts it back. Run it in edit mode; it swaps scenes while it runs.
Known limits
- Full-frame marks (taper, wear, grain, snow edges) slide a little on moving things; characters with a role get steady lines.
- Lines are recomputed from the depth every frame. Geometry that moves on its own (trees and grass in the wind, the ocean's waves) moves its lines with it; still things keep still lines.
- With
steadyLineson, TAA is off while a look is on, so geometry edges no line covers (thin foliage far away) keep a one-pixel staircase. A world that runs a temporal upscale (which owns the jitter itself) keeps its jitter, and lines there step with it. - Water is found from two bodies per scene: the sea (
Woodblock.setWater, any extent, waves up towaveHeightmetres) and one round lake at its own height (Woodblock.setLake). A third body of water, or a river on a slope, is not banded. - The ukiyo-e light removes cast shadows by asking the scene's sun not to cast them (only the sun: lanterns and other local lights keep theirs). On the forward render path, which keeps no surface colour, the fill also estimates surface colour from the frame, so a little shading from the light's direction stays.
- Engine limits this package works around, as filed:
- #24548: every pass is queued again every frame, even when nothing changed, which is most of the styleKit script time above.
- #24549: a geometry pass carries no per-object value, so roles reach the blocks through styleKit's shared object mask (at most eight distinct role settings a scene).
- #24550: a pass reads the scene's depth only when it also writes the scene picture, so the lines and the role mask test depth in their own shaders.
- #24551: an unknown blend name draws as replace, so every woodblock block writes its full result and relies on no other blend.