Log inGet started
Package

mediumKit.package

README.md

mediumKit: draw one object in watercolor, ink, pencil, pixel... or two media at once

Version 1.0.3 (Medium.VERSION).

1.0.3: a steady watcher. The watcher that re-paints objects whose meshes arrive late now checks young objects every third frame and every other object once a second, a slice per frame. A crowd of 128 painted objects no longer costs a spike twice a second (it showed as 3.7 ms of script time per frame in a profile).

1.0.2: the published renderer is the default. The eight core media (watercolor, ink, pencil, toon, anime, comic, paper cutout, pixel) are now drawn by the looks published for them: watercolorBlocks, inkBlocks, pencilBlocks, toonBlocks, animeBlocks, comicBlocks, paperBlocks with starterBlocks, and retroMaterials. Each look is gated to the objects in that medium through a styleKit style channel, so the rest of the scene keeps its look. The ten further media and the in-material blends below still draw with mediumKit's own mediumSurface shader, and Medium.setRenderer("shader") draws every medium that way as in 1.0.1. See "The published renderer" and "Frame budget" below.

mediumKit lets you draw one object in an art medium while the rest of the scene keeps its look, or draw one object in two media at once. Use it for a watercolor hero in a realistic level, an ink-drawn boss, pixel-art pickups, a tower defense where every race is a different art medium, or an enemy that is half comic and half stained glass.

It is material based. Every mesh under the object gets a shared runtime material on the mediumSurface shader, built from the material it already wears, so its own colours and texture are kept and read as paint. Marks are laid in the object's own space and sized to the pixels the object covers, so:

  • marks stay on walking, skinned and animated enemies instead of sliding over them;
  • every camera and every capture draws them, including offscreen, render-to-texture and minimaps;
  • there is no limit on how many objects carry a look, and objects with the same look share one material, so hundreds batch;
  • the rest of the scene is untouched. There is no full-screen pass.

Install

zero zeromind installAsset <mediumKit package guid>

or search ZeroMind for "mediumKit" / "draw one object in watercolor". It brings its shader dependencies: styleKit (noise and pigment mixing), watercolorBlocks (the watercolor paint rules and cold-press paper) and toonBlocks (the toon light model). Nothing is registered full-screen by installing.

local Medium = require("mediumKit.api")
Medium.apply(enemy, "watercolor")                         -- one medium
Medium.apply(tower, "ink", { tint = { 0.9, 0.2, 0.1 } })  -- with a team colour
Medium.applyHybrid(boss, "comic", "stainedGlass", "halves") -- two media at once
Medium.clear(enemy)                                        -- exactly as it was

The media

idlooks like
watercolorSoft transparent washes, pigment pooled in the shadows and at the edges, cold-press paper granulation, blooms with tide lines, warm light thinning to paper.
inkBold black brush contour, hatching then cross-hatching into solid black, over a pale sumi wash.
pencilGraphite hatching in three layers that lean with the light, blended graphite under them, a sketchy double contour, paper-white highlights.
toonThree hard cel bands with cool shadows, a hard specular blob, a rim, a thick dark outline.
animeClean two-band cel shading, a bright rim light, a specular streak, a thin coloured line.
comicPunchy primaries, Ben-Day halftone dots growing into the shadows, light colour dots, a heavy ink outline.
paperCutoutFlat stacked paper layers in a few colours, torn white paper edges, a drop shadow under each layer, paper fibre.
pixelObject-space blocks, a five-step palette, ordered dithering between three light levels, a crisp dark rim.
charcoalSmudged charcoal on toned paper with the grain showing through the darks, white chalk highlights.
crayonWaxy saturated strokes broken by the paper tooth, darker crayon scribbled in the shadows.
oilPaintThick impasto dabs that follow the form, warm lights and cool shadows, grooves and bristle ridges catching the light, canvas weave.
stainedGlassJewel-coloured panes glowing with light, held in thick black lead. A strongly coloured object keeps its own hue.
blueprintCyanotype blue with a measured grid, white edge lines and faint section hatching.
neonA near-black body outlined in glowing tubes of its own hue (or a vivid one for a neutral object), scan bands rising through it.
woodblockUkiyo-e print: a printer's few inks on washi, wood grain, an indigo bokashi gradient across the top, black key lines.
chalkPastel chalk on a dark slate board, gritty strokes building up in the light.
pointillismSeurat dots of pure colour on a cream ground: violet dots in the shadow, warm ones in the light.
markerAlcohol marker: streaky overlapping strokes, a second darker pass in the shadow, white paper highlights, fineliner edge.

Medium.media() returns { id, name, blurb, swatch = {r,g,b} } for each one, for menus and race pickers.

The blends (two media at once)

idhow the two share the object
splitA wavy line across the object: medium A above it, medium B below, with an ink seam.
dissolveLarge noise patches of each medium, drifting slowly.
stripesWide diagonal bands alternating between the two.
fillLineThe colour and shading of A with the contour, hatching and line work of B.
pulseThe whole object crossfades from A to B and back, revealed through soft noise.
halvesThe left half in A, the right half in B, in the object's own space.
bleedA at the core, B creeping in from the edges and breathing.

The default blend is halves. At a tower-defense camera (about 40 m away, looking down at 50–60°) it is the blend that reads as both media at a glance on every pair we tried. split puts mostly medium A on top, so from above you see one medium. stripes and dissolve read well on media of contrasting value (ink with watercolor, neon with chalk). fillLine is best up close. Change the default world-wide with Medium.setDefaultBlend(id), or by writing the world setting mediumKit.defaultBlend. Every hybrid that names no blend follows it.

API

local Medium = require("mediumKit.api")

Medium.apply(entity, mediumId, opts?) -> meshesPainted
-- opts: tint = {r,g,b} (0-1, replaces the object's own hue: team colours)
--       strength = 0..1 (0 = the plain object)
--       outline = true | false | nil (nil = the medium's own choice)
--       children = true (paint every mesh under the entity; false = only its own)
--       localOnly = true (paint this machine only; see Multiplayer)
Medium.applyHybrid(entity, mediumA, mediumB, blendId?, opts?) -- blendId nil = the world default
Medium.clear(entity)                 -- restores the original materials exactly
Medium.of(entity) -> { medium, mediumB, blend, tint, strength } | nil
Medium.media() -> { { id, name, blurb, swatch } }
Medium.blends() -> { { id, name, blurb } }
Medium.setDefaultBlend(id) / Medium.defaultBlend()
Medium.setQuality("high" | "low") / Medium.quality()
Medium.setOutlines("budget" | "screen" | "shader", max?) / Medium.outlines()   -- how outlines are drawn (default budget, 32)
Medium.setRenderer("published" | "shader") / Medium.renderer()   -- who draws the eight core media (default published)
Medium.recipes()                     -- each core medium's published package and blocks, and whether they are installed
Medium.define(id, def)               -- add your own medium (below)
Medium.stats()                       -- applies, skipped re-applies, materials, roots
Medium.clearAll()
Medium.VERSION

entity is an entity proxy or an id string.

Adding a medium: Medium.define

A preset of a built-in medium works alone and in hybrids:

Medium.define("frost", {
    base = "watercolor", name = "Frost", blurb = "Icy washes on blue paper",
    swatch = { r = 0.7, g = 0.85, b = 1 },
    paper = { 0.82, 0.9, 1.0, 0.9 },   -- r, g, b, how much it replaces the medium's paper / ground
    tweak = { 1.2, 1, 0.8, 1 },        -- mark scale, contrast, saturation, line amount
    outline = { color = { 0.1, 0.2, 0.4, 1 }, thickness = 2 },  -- or "dark" / "hue" / false
})
Medium.applyHybrid(golem, "frost", "ink")

A shader of your own works alone. Write a surface shader whose properties.yaml declares base_color (color), base_color_texture (texture), and optionally tint (color; a = how much it replaces the hue) and strength (float). Then:

Medium.define("lava", { shader = "myWorld.shaders.lavaSurface", properties = { glow = 2 }, name = "Lava", swatch = { r = 1, g = 0.3, b = 0 } })
Medium.apply(boss, "lava")

The kit fills in base_color, base_color_texture, tint and strength from the object. A hybrid naming a shader medium is not supported: give the medium a base instead. Copy mediumSurface.shader and add a branch to mk_medium() if you want a new built-in.

The component: mediumKit.MediumLook

Fields medium, mediumB, blend, tint ({r,g,b}), strength and outline (auto/on/off). Put it on any entity in a scene to author a look; it paints the entity and every mesh under it in edit and in play. An empty medium draws the object as it was.

The published renderer

MediumDrawn byBlocks
watercolorwatercolorBlockswcWash, wcGranulation, wcEdgeDarken
inkinkBlocksinkWash, inkPenLine
pencilpencilBlocksgraphiteHBShade, graphiteHBLine
toontoonBlockstoonBands, celFill, toonOutline
animeanimeBlocksanimeCelTV, animeRimThinWarm, animeLineTV
comiccomicBlocks + styleKitmodernFlatPalette, newsprintScreen (5 px dots), depthLine
paperCutoutpaperBlocks + starterBlockscardSurface, posterize, depthLine
pixelretroMaterials + styleKitthe retroPixel material on each mesh, then posterize

How it works: the host adds each medium's blocks to the scene's styleKit stack once, as entries that name the variant mk_<medium>. Every mesh drawn in that medium carries a StyleChannel with that variant, and an entry that names a variant draws only on objects of it. The rest of the scene is untouched.

  • Hybrids give each medium its own parts of the object: medium B takes the upper half of the meshes (alternate meshes for dissolve and stripes). An object with a single mesh keeps the in-material blend, since a channel holds one variant per object. A game that builds a hybrid from two models (Arts TD's hybrid towers) can simply apply each model in its own medium.
  • Limits: styleKit draws at most eight distinct channel settings, which is exactly the eight core media. Its look runs on the presented frame, so offscreen captures, render-to-texture and minimaps show these objects plain. Use setRenderer("shader") where those matter.
  • Custom media made with Medium.define and the ten further media always use the shader.

Nothing heavy crosses the wire: every peer builds its own materials.

  • Synced look (default). apply/applyHybrid/clear on a synced entity also write the synced MediumLook component, so every peer, including one that joins later, draws the same look. Only the owner (or anyone, for an unowned entity) may write it. On a peer that does not own the entity, the call paints locally and skips the write.
  • Every peer derives the look (localOnly = true). When the look already follows from synced game state every peer has (a creep kind, a turret def, a race), have each peer call Medium.apply(e, medium, { localOnly = true }) from that state. It paints this machine only and never writes MediumLook: no traffic and no refused writes on non-owners. This is the pattern for a tower defense whose enemies and towers are owned by the host. Re-applying is cheap, so calling it when the state changes or when a pooled entity is reused is fine.

Objects that come and go

  • Spawned later: call apply on spawn. A mesh that arrives under the entity later is painted the frame it appears, whether it is a bundle's parts spawned by an Asset component, a weapon attached, or a part streamed in. For the first 3 seconds after an apply the entity is checked every frame, and twice a second after that.
  • Pooled: re-applying the same look returns at once (about 7 µs). A different look switches the material on every mesh, clear puts the original back, and no material leaks, because materials are cached per look and source.
  • Many child meshes, skinned or static: every Model and SkinnedModel under the entity is painted. A nested entity with a look of its own keeps it. See-through materials (glass, water) are left as they are.
  • Despawned: the record is dropped automatically.

Performance (measured)

Frame budget of the published renderer (1.0.2)

Measured in Arts TD's Gallery of Media: 16 tower models (the eight core media and four two-model hybrids) and a parade of 112 skinned, walking enemies covering all eight media and four hybrid pairs, all on one screen. Native desktop app, development build, 1440x1405, on a shared machine that was also running the editor, so the wall time per frame (200 to 350 ms here) mostly measures waiting for the machine. The numbers to compare are the engine's own CPU and GPU time and the rate the engine reports it would hold with the machine to itself.

WhatEngine CPUGPU (timed passes)Rate with the machine to itself
published renderer, high tier, enemies casting shadows32 ms124 ms31 fps
published renderer, high tier, enemies casting no shadow31 ms66 ms32 fps (CPU bound)
published renderer, low tier (Medium.setQuality("low") and StyleKit.setQuality("low"), the web profile), enemies casting no shadow22 ms51 ms46 fps

Where the GPU time goes (median per frame, same scene):

PassCost
styleKit's object mask (one geometry pass per medium in use, shared by all media)about 18 ms, the same at both tiers
pencil (graphiteHBShade + graphiteHBLine)1.34 ms
toon (toonBands, celFill, toonOutline)0.21 ms
ink (inkWash, inkPenLine)0.14 ms
watercolor (wcWash, wcGranulation, wcEdgeDarken)0.10 ms
anime, comic, paper cutout, pixeleach below 0.13 ms (under the profiler's listed passes)

So the media themselves are cheap; the fixed cost is the object mask, and the biggest saving in a crowd is not mediumKit at all: switching shadow casting off on small skinned enemies (castsShadows = false) took the GPU from 124 to 66 ms. The in-material shader renderer (setRenderer("shader")) has no object mask and measured 78 ms GPU in the same scene before the shadow change.

Holding a frame-rate target. At full resolution most of the GPU time is the full-screen look passes, and they scale with the pixel count. Measured in the same scene at 2097x1409: the GPU passes took 51 ms at full resolution and 20 ms at 55% render scale (renderer.setResolutionScale(0.55)), with the low tier 17.5 ms. A game that wants 60 fps on the desktop should lower the render scale when frames run long; Arts TD's artsTD.budget does exactly that.

What was not measured: the web build and a tablet. No browser or tablet engine was connected while this was written, so "web profile" above means the low tier run on the native desktop app, not the browser. Per-medium costs on the web are not known; the order (pencil dearest, the rest well under a millisecond, the object mask the fixed cost) is expected to hold, but that is an expectation, not a measurement.

Earlier measurements (shader renderer)

Stress bench (scenes/bench.scene): 200 animated, walking mushroom brutes (skinned, about 17k triangles each) with all 18 media and all 7 blends on screen at once (a third of them hybrids), at 1920×1080. Measured with the profiler toolbox in a headless sub-client on this machine (a dev engine build, mostly efficiency cores):

frame (wall) meanengine CPU mean
looks off17.1 ms13.6 ms
quality high18.9 ms15.6 ms
quality low17.1 ms15.2 ms
  • 200 objects with 25 distinct looks use 54 materials: one per (source material, medium, tint, blend).
  • The kit's script cost per frame is the child watcher: under 0.1 ms for 200 roots. It never showed in profiler.hotspots. The bench's own walking script costs 1.95 ms.
  • Applying all 200 cold, materials created: 80 ms in total (0.4 ms each, a one-time cost). Re-applying the same look to all 200: 1.4 ms. Clearing all 200: 7.7 ms.
  • GPU pass timings could not be read in the headless sub-client (profiler.gpu resolves no frame there), so the GPU cost is given as per-pixel shader cost below. Measure it on your target with profiler.gpu.

Shader cost per pixel (every medium also pays the base: 2 texture taps (colour, plus a coarse one for pixel), the directional shadow lookup and the point-light loop):

mediumextra texture tapsnoise evaluations (high / low)notes
toon, anime00 / 0cheapest
neon, blueprint, marker, woodblock01–4 / 1–2woodblock loops over 8 inks
ink, pencil, crayon, chalk012–20 / 4–6hatching: 2 planes × 2 detail levels
comic, pixel, paperCutout04–8 / 3–4
charcoal, oilPaint08–12 / 6–8
watercolor0about 30 / 10cold-press paper (Worley) only at high
stainedGlass, pointillism01 Worley (9 cells) + 2 fbm
any hybridn/aboth media plus a mask (1–3 noise)about 2× a single medium

Medium.setQuality("low") lays marks on one plane at one detail level and skips the paper Worley. That roughly halves the noise work, which is the setting for web and mobile. A hybrid costs about two media, so on a weak GPU keep hybrids for bosses and elites.

Outlines (1.0.1). The engine's screen-space outline costs GPU time per outlined object: in Arts TD, 365 outlined enemies and towers cost about 65 ms of GPU a frame on a desktop. Medium.setOutlines("budget", 32) (the default) gives the first 32 outlined objects the screen outline and draws every other one's outline inside its material, as a silhouette edge in the same colour (the edge property of the surface shader). That brought the same scene to about 26 ms of GPU while every medium still reads. "shader" draws every outline in the material, and "screen" is the 1.0.0 behaviour.

Gallery and bench

  • scenes/gallery.scene (the startup scene): every medium on the mushroom brute and a ruined tower, labelled, plus a wing with every blend for watercolor + ink, toon + pixel and comic + stained glass. The gallery camera frames the media and the blend camera frames the blends.
  • scenes/bench.scene: the stress bench above. Enter play to set it walking.

Guides

  • How to draw one object in watercolor, ink or pixel art style while the rest of the scene keeps its look
  • Example: a two-medium boss and a painted village from an empty world

Known limits

  • One material per mesh. A mesh that draws several materials through sub-meshes takes the medium on the material its Model names.
  • Vertex colours are not kept. The surface uses the vertex colour channel to carry object-space position.
  • Rotations are not applied to part offsets. Hybrid masks on a multi-part rigid model add each part's offset from the root without rotating it. Single meshes, skinned characters and upright props are exact.
  • A mixed hierarchy can misplace the split. When a skinned body and rigid parts stand under one root, the split height can sit wrong.
  • Interior creases are suppressed at a distance. Creases from hard normal changes only draw when the object is large on screen (over about 420 px tall). At a distance the silhouette outline carries the shape.
  • Outlines are screen-space. They use the engine's jump-flood outline (@builtin::modules.outline): uniform pixel width, local to each peer, and they show in captures.
  • Shader edits need a re-apply. A material keeps the shader version it was made with. The kit notices a recompiled shader within half a second and repaints everything (a kit update does this).
  • Lanes 0 and 1 are taken. The per-instance shader lanes 0 and 1 of painted meshes are used by the kit. Lane 2, which instance_color uses, is free.
  • Custom shader media cannot be hybrids. Give the medium a base preset instead.