# 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.
```luau
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
| id | looks like |
|---|---|
| `watercolor` | Soft transparent washes, pigment pooled in the shadows and at the edges, cold-press paper granulation, blooms with tide lines, warm light thinning to paper. |
| `ink` | Bold black brush contour, hatching then cross-hatching into solid black, over a pale sumi wash. |
| `pencil` | Graphite hatching in three layers that lean with the light, blended graphite under them, a sketchy double contour, paper-white highlights. |
| `toon` | Three hard cel bands with cool shadows, a hard specular blob, a rim, a thick dark outline. |
| `anime` | Clean two-band cel shading, a bright rim light, a specular streak, a thin coloured line. |
| `comic` | Punchy primaries, Ben-Day halftone dots growing into the shadows, light colour dots, a heavy ink outline. |
| `paperCutout` | Flat stacked paper layers in a few colours, torn white paper edges, a drop shadow under each layer, paper fibre. |
| `pixel` | Object-space blocks, a five-step palette, ordered dithering between three light levels, a crisp dark rim. |
| `charcoal` | Smudged charcoal on toned paper with the grain showing through the darks, white chalk highlights. |
| `crayon` | Waxy saturated strokes broken by the paper tooth, darker crayon scribbled in the shadows. |
| `oilPaint` | Thick impasto dabs that follow the form, warm lights and cool shadows, grooves and bristle ridges catching the light, canvas weave. |
| `stainedGlass` | Jewel-coloured panes glowing with light, held in thick black lead. A strongly coloured object keeps its own hue. |
| `blueprint` | Cyanotype blue with a measured grid, white edge lines and faint section hatching. |
| `neon` | A near-black body outlined in glowing tubes of its own hue (or a vivid one for a neutral object), scan bands rising through it. |
| `woodblock` | Ukiyo-e print: a printer's few inks on washi, wood grain, an indigo bokashi gradient across the top, black key lines. |
| `chalk` | Pastel chalk on a dark slate board, gritty strokes building up in the light. |
| `pointillism` | Seurat dots of pure colour on a cream ground: violet dots in the shadow, warm ones in the light. |
| `marker` | Alcohol 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)
| id | how the two share the object |
|---|---|
| `split` | A wavy line across the object: medium A above it, medium B below, with an ink seam. |
| `dissolve` | Large noise patches of each medium, drifting slowly. |
| `stripes` | Wide diagonal bands alternating between the two. |
| `fillLine` | The colour and shading of A with the contour, hatching and line work of B. |
| `pulse` | The whole object crossfades from A to B and back, revealed through soft noise. |
| `halves` | The left half in A, the right half in B, in the object's own space. |
| `bleed` | A 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
```luau
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:
```luau
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:
```luau
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
| Medium | Drawn by | Blocks |
|---|---|---|
| watercolor | watercolorBlocks | `wcWash`, `wcGranulation`, `wcEdgeDarken` |
| ink | inkBlocks | `inkWash`, `inkPenLine` |
| pencil | pencilBlocks | `graphiteHBShade`, `graphiteHBLine` |
| toon | toonBlocks | `toonBands`, `celFill`, `toonOutline` |
| anime | animeBlocks | `animeCelTV`, `animeRimThinWarm`, `animeLineTV` |
| comic | comicBlocks + styleKit | `modernFlatPalette`, `newsprintScreen` (5 px dots), `depthLine` |
| paperCutout | paperBlocks + starterBlocks | `cardSurface`, `posterize`, `depthLine` |
| pixel | retroMaterials + styleKit | the `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.
| What | Engine CPU | GPU (timed passes) | Rate with the machine to itself |
|---|---|---|---|
| published renderer, high tier, enemies casting shadows | 32 ms | 124 ms | 31 fps |
| published renderer, high tier, enemies casting no shadow | 31 ms | 66 ms | 32 fps (CPU bound) |
| published renderer, low tier (`Medium.setQuality("low")` and `StyleKit.setQuality("low")`, the web profile), enemies casting no shadow | 22 ms | 51 ms | 46 fps |
Where the GPU time goes (median per frame, same scene):
| Pass | Cost |
|---|---|
| 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, pixel | each 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) mean | engine CPU mean |
|---|---|---|
| looks off | 17.1 ms | 13.6 ms |
| quality `high` | 18.9 ms | 15.6 ms |
| quality `low` | 17.1 ms | 15.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):
| medium | extra texture taps | noise evaluations (high / low) | notes |
|---|---|---|---|
| toon, anime | 0 | 0 / 0 | cheapest |
| neon, blueprint, marker, woodblock | 0 | 1–4 / 1–2 | woodblock loops over 8 inks |
| ink, pencil, crayon, chalk | 0 | 12–20 / 4–6 | hatching: 2 planes × 2 detail levels |
| comic, pixel, paperCutout | 0 | 4–8 / 3–4 | |
| charcoal, oilPaint | 0 | 8–12 / 6–8 | |
| watercolor | 0 | about 30 / 10 | cold-press paper (Worley) only at high |
| stainedGlass, pointillism | 0 | 1 Worley (9 cells) + 2 fbm | |
| any hybrid | n/a | both 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.