Style Cookbook: Mix Your Own Art Style from Stackable Look Blocks
- ..
- README.md8.8 KB
- about.yaml772 B
- behavior.luau5.1 KB
- type.yaml1.0 KB
README.md
styleBlock (asset type)
A styleBlock is one stackable piece of an art style. It sits in one of ten slots (Surface, Light, Fill, Tone, Line, Colour, Ground, Time, Raster, Medium), it states what it reads and what it writes, and the styleKit stack runs it over the whole frame after antialiasing. Any block swaps for any other block of its slot with no other change.
Folder shape
A block is a plain folder holding the block asset and its shader side by side:
blocks/posterize/
posterize.styleBlock/ the block: block.yaml, README.md, .metadata (all required)
posterize.shader/ the post-process shader the stack runs
posterizeField.shader/ optional: the shader that writes a shared field (Ground or Time blocks)
posterize.shaderModule/ optional: the piece a material includes for a chosen set of objects
Paths in block.yaml are relative to the plain folder. The shader sits beside the .styleBlock rather than inside it, because a shader nested inside another asset folder is not listed by the engine and could not be found without a computed lookup that would block publishing.
The quickest way to start one is StyleKit.newBlock("myTint", { slot = "colour" }) (written to /zero/source/myBlocks/myTint, or the folder you pass), which writes the whole folder, block and shader, and registers it at once. asset.create("styleBlock", name, { slot = "line" }) writes only the .styleBlock files; write the <name>.shader beside it yourself.
block.yaml
name: "Posterize"
slot: colour # surface light fill tone line colour ground time raster medium
version: "1.0.0"
summary: "Cuts the picture into a few flat tone steps."
reads: [frame] # frame depth normal albedo motion ground wobble clock mask soft pigments rendered paper sun
writes: [frame] # frame, and field:ground, field:paper (Ground) or field:wobble (Time) when it has a field
stacking: layer # optional: layer (default) or chain
rank: 10 # optional: StyleKit.add places it before the first block of its slot with a higher rank
keepDim: false # optional: true keeps a dim room dim under this block (the dim guard); defaults to true in the Tone slot, false elsewhere
shader: posterize.shader # relative to the plain folder
field: { name: ground, shader: plainPaperField.shader } # optional, Ground and Time only
include: posterize.shaderModule # optional
settings: # every non-sk_ property of the shader, with what it means
levels: "How many steps each channel keeps."
defaults: # optional: this block's own defaults over the shader's (many blocks, one shader)
levels: 4
quality: # optional per-tier overrides of settings
low: { samples: 4 }
A Ground block's field may also name a paper-field shader and say that it layers (styleKit 1.2.0):
field: { name: ground, shader: paperField.shader, paper: paperTakes.shader, layers: true }
writes: [frame, field:ground, field:paper]
paper: a shader that publishes the paper field (sk_paper: r thirst -1 hard-sized to +1 thirsty, 0 the standard sheet; g sheen; b fibre; a dark ground 0 to 1) for blocks that readpaper. It is run only when a live block reads it. A Ground block without one leaves the paper field neutral (every value 0). Addfield:papertowrites.layers: true: when this block is not the first Ground block in the stack, it lays its ground (and its paper field) over the one before by its strength and mask, instead of being ignored as a later field. Its field shaders receive the field before assk_ground/sk_paperand mix over it (sk_view.yis 1 when they are layered).
defaults lets several blocks share one shader (paperBlocks' seventeen papers run on one): each key must be a setting the shader declares, it overrides the shader's default for this block on every tier (quality overrides come after it, an entry's own settings last), and StyleKit.settingsOf(id) reports it as the block's default.
The shader's properties.yaml starts with the styleKit shared header (the sk_ properties) and then declares the block's own settings with their defaults and ranges. StyleKit.checkBlock(id) reports anything missing.
Stacking and rank
stacking: layer(the default): every block in a slot reads the slot's input, and later ones are laid over the earlier ones by strength and mask.stacking: chain: the block reads what the blocks before it in its slot made, so modifier blocks build on each other (a wash, then its granulation, then its darkened edges).rank: <number>:StyleKit.addplaces the block before the first block of its slot with a higher rank, so a chain lands in its intended order whatever order its blocks are added in. A block with no rank lands before the first block of its slot ranked 100 or more: give finishing blocks that must stay on top (a printed margin, a frame, weather laid over the picture)rank: 100and up withstacking: chain, and grain or a vignette added later goes under them instead of painting them out.
Keeping a dark scene dark (keepDim)
keepDim (styleKit 1.4.0) asks for the stack's dim guard. While any live block declares it, two small passes run after the chain: they measure the stack's result against the frame as rendered and scale the result down wherever it comes out brighter than a dim room was, so a shading block's sheet and the light between its marks never brighten a dim or unlit room. Every mark keeps its shape, and in daylight or a well lit room the guard hands the result on exactly unchanged.
- Leave it out on a Tone block: every Tone block keeps dim unless it says
keepDim: false. A new hatching, stipple or dots block gets the guard for free. - Set
keepDim: trueon a block in another slot that lays a light sheet or light marks over the picture. - Set
keepDim: falseon a Tone block that is meant to light up the dark (a glow, chalk marks on a black board).
Published inputs (styleKit 1.8.0)
Beyond the five extra inputs, a block can read a texture another package computes: list input:<name> under reads and declare an in_<name> texture after the shared header. The producer calls StyleKit.publishInput(name, texture) on each machine and draws it before the stack runs; with nothing published the block reads black. StyleKit.checkBlock refuses a read without its texture and a texture without its read. The guide "Writing your own style block" has the whole recipe.
Extra inputs
Five inputs come after the shared header, each declared straight after it and bound by the stack only when reads lists the matching word:
-
sk_soft(reads: soft): a half-resolution, depth-aware blur of what the block reads, never smearing a nearer thing over a farther one. Read it through theskSoftshader module (sk_soft_at,sk_soft_wide,sk_soft_depth,sk_soft_in_front). Its width is the stack optionsoftRadius. -
sk_pigments(reads: pigments): the scene's pigment set as a 16 x 1 palette. Read it through theskPigmentSetshader module (skg_has_set,skg_pigment,skg_shadow,skg_light,skg_air,skg_remix). -
sk_rendered(reads: rendered): the frame as it entered the stack, before any block changed it. Read it through theskRenderedshader module (sk_rendered_at). Its use is a light estimate againstsk_albedo(texture cancels out) or an original colour to restore. -
sk_paper(reads: paper, a texture, default black): the paper field the Ground blocks publish. Read it through theskPapershader module (sk_thirst,sk_sheen,sk_fibre,sk_dark_ground). Where no Ground block publishes it every value is 0, so the block draws as it did without it. A Ground block's own paper-field shader declares it to read the field laid before it, without listingpaperunder reads. -
sk_sun(reads: sun, a float4): the direction toward the scene's first directional light,w1 when it gives light. Read about once a second. Raking light and sheen use it.
StyleKit.checkBlock refuses a block that declares one of them without the word under reads, or lists the word without declaring the texture.
When an asset of this type registers on any machine (world load, install, a collaborator's new block arriving), the type's onRegister hands it to the styleKit library, so StyleKit.blocks() lists it and a stack can use it at once.
Known limits
- An asset of this type registers when the engine indexes its files, a moment after they are written.
- ZeroMind's description of this can lag one release behind what is installed (#19258).
The package README's Known limits lists the rest.