LANTERNHOLD — Art Bible

Status: iteration 1 first draft.

• No reference image exists yet (docs/reference/inspiration.png is missing). Direction below comes from the written brief. Once the image arrives, re-check §2 and §4 against it.
• Canonical palette: docs/art/palette.hex.
• Mockups so far: art/mockups/m01_palette_swatch.png.

The look in one line: warm light against cool dark. An indigo night, amber windows and firelight, cyan wisps and crystal, and violet only where something is wrong. Most of the richness comes from systems (lighting, palette, particles, weather, parallax), not from drawings. The asset set is small. The renderer makes it rich.

1. Resolution, tiles, sprites, camera

1.1 Screen and tiles

• Internal resolution: 480 × 270 px, 16:9. Every element (world, UI, text) renders at this one pixel grid. Never mix pixel scales.
• Output: integer scale only (×2 = 960×540, ×3 = 1440×810, ×4 = 1920×1080, ×8 = 4K), with black letterbox for non-integer windows. Nearest-neighbor filtering only.
• Tile: 8 × 8 px. The view is 60 × 33.75 tiles, so the whole surface of the island (60–76 tiles wide) is roughly one screen wide, like a diorama.

1.2 Sprite sizes

Sizes are frame size in px. Anchor is bottom-center unless noted.

1.3 Camera

• Follows the player with a dead-zone of 64 × 40 px and lerp 0.15 per frame. The position is snapped to whole internal pixels, so there's no sub-pixel shimmer.
• Look-down: hold Down to shift the view 80 px. In shafts, the camera leads 40 px in the direction of travel.
• Map view: 1 px per tile for the whole island (128 × 256), with any lens overlay.
• No zoom. Pixel scale is sacred.

2. Palette

64 colors in 8 ramps × 8 shades (dark to light, index = ramp·8 + shade). Each ramp is hue-shifted: dark ends lean indigo and light ends lean warm or cyan by role. Mockup m01 confirmed every ramp is monotonic in OKLab lightness.

2.1 Palette rules

1. No color outside the palette ever reaches the screen. This includes lighting, UI, particles and warp effects (§3). There is no pure black and no pure white.
2. Violet means wrong. R4 shades ≥ 3 are reserved for flux, corruption, roots, the Heart, and error and warning states. Nothing cozy uses R4.
3. Danger is violet, never red. The palette has no true red, and R2 shades 1–3 are rust-brown.
4. Warm vs cool is a gameplay signal. R2 highlights mean warm light (safety from entities). R3 highlights mean cool light (flux suppression). Never use R2 or R3 shades ≥ 5 on non-emissive decoration.
5. Value hierarchy:
   • Interactive foreground tiles use shades 2–5.
   • Background walls use the same ramp at −2 shades (minimum 0).
   • Distant parallax uses only R0 and R1 shades 0–3.
   • Emissives use shades 6–7.
   • Gameplay-critical objects (machines, lamps, chests) must keep a shade difference of ≥ 2 from the tile behind them.
6. Per-sprite budget: at most 12 colors and at most 4 ramps. Tiles use at most 6 colors from at most 2 ramps.

2.2 Essence signature colors

Pipes, glyphs and jars show essences in these colors. The glyph shape is always the primary identifier; color is secondary, for colorblind safety.

Identity colors are set in data/essences.json and don't change per seed.

2.3 Depth shifts (by zone)

Each stratum is a lighting zone with its own ambient floor, darkness target ramp and allowed terrain ramps. Terrain gets fewer hues with depth, so lights and flux pop harder the deeper you go.

2.4 Warp shifts

All warp shifts are post-LUT index remaps, so they stay palette-compliant.

Warp effects never appear inside the hearth sanctuary.

3. Lighting model (central system)

Light is mood and gameplay at once, so a single model drives both.

3.1 Gameplay light (from the sim)

Per tile, a warm and a cool level (0–15), computed by the sim (GDD §6.4).

3.2 Render light field

1. Upload the tile light grid as an RG8 texture (warm, cool). Sample it bilinearly at tile centers, which gives a smooth falloff per pixel.
2. Convert to 8 render levels: l = level/15 · 7.
3. Quantize with a 4 × 4 Bayer ordered dither anchored to world pixel coordinates (not screen coordinates), so the dither doesn't crawl when the camera moves: L = clamp(floor(l + (bayer/16 − 0.47)), 0, 7).
4. Flame flicker: the warm level of flame sources is modulated ±1 (on the 0–15 scale) by stepped 1D noise at 8 Hz. Wisp light breathes ±1 at 0.5 Hz.

3.3 The LUT (palette-locked lighting)

Every on-screen pixel is: albedo palette index + zone + warm level W (0–7) + cool level K (0–7) → output palette index, through a precomputed lookup table.

• LUT texture: 64 albedo × (7 zones × 8 W × 8 K), so 64 × 448 in R8UI.
• Built offline by lanternforge lut:

for zone z, albedo i, W in 0..7, K in 0..7:
    A = srgb_to_linear(P[i])
    E = amb[z] + (W/7)^1.4 · 1.8 · lin(R2·6) + (K/7)^1.4 · 1.5 · lin(R3·6)
    c = clamp(A ⊙ E, 0, 1)
    j = argmin_j  ΔOKLab(c, P[j]) + penalty(i, j, W, K)
    penalty = 0    if ramp(j) ∈ {ramp(i), darkRamp[z]}
            = 0    if W > K and ramp(j) = R2,  or  K > W and ramp(j) = R3
            = 0.04 otherwise
    post-pass: enforce monotonic lightness in W and in K
               (if L(lut[W][K]) < L(lut[W−1][K]), copy the previous value)

• Emissive pixels (a per-pixel flag from sprite metadata) skip the LUT and output their albedo. Window panes, flames, wisps, charged crystal cores, pilot lights and root-blooms are emissive.
• Result: a lantern-lit stone wall turns into amber-tinged stone shades, a wisp-lit wall into teal-tinged ones, and a dark wall into indigo silhouette. AI-generated and procedural assets go through the same LUT, which is what makes them sit together (Milestone 1, acceptance 4).

3.4 Darkness rendering

• Cells with no light and no ambient resolve to the zone's darkness ramp shades 0–1. Darkness has shape: explored solid tiles next to explored air keep a 1 px R0·2 "memory edge", so caves read as remembered outlines.
• Unexplored cells are flat R0·0.
• Real entities take 2 levels from the light field in their own cells (the sim does this), so they cut shadows into lamp glow. Hallucinations don't (GDD §6.6).

3.5 Atmosphere and halos

• Parallax layers sample the light field at 35% strength at their world position. Air around a lit window glows amber against the sky with no bloom shader.
• Rain particles sample at 100%, so rain turns amber as it falls past a window and teal past a wisp. This is a signature cozy image, and it costs nothing.
• Fog and mist sample at 60%.

3.6 Implementation (WebGL2)

1. Index pass: draw all world sprites and tiles into an R8UI color target holding the palette index, plus an R8 flags target (emissive, entity, UI, unlit). Use integer positions only.
2. Resolve pass (full-screen): read the index, flags, light texture (bilinear), zone texture (tile resolution, nearest), Bayer texture, LUT texture and palette texture. Output RGB.
3. Post-index remap: warp effects, the tide fog, lens overlays (overlays are drawn as indices with the "unlit" flag).
4. UI pass: the same index buffer with the unlit flag, so UI is palette-exact.

This pipeline is the M1 renderer. Mockup M02 (planned) will prototype the LUT in Python before the build.

4. Environment

4.1 Sky (code)

• A vertical gradient across R0·5 (top) → R0·2 (horizon band) with dithered transitions. The sky darkens with depth: below the surface line it becomes cave darkness.
• Stars: 180 per screen-width of sky in 3 sizes (1 px R1·5, 1 px R1·7, plus-shapes R1·6/7). They twinkle by palette cycling between shades 5 and 7 with a random 2–6 s period.
• Moon: a 40 px disc, R1·5–7, with procedural craters (3–5 discs of R1·5). Phase is drawn with a terminator ellipse. The halo is a dithered R0·6/R0·7 ring 10 px wide, which matches m01. The moon's reflection in the pond is a column of R1·6 dashes.

4.2 Clouds (code)

Three layers built from two octaves of value noise, thresholded into 3 bands:

• Far (R1·0–1, parallax 0.1): wide, slow, 2 px/s.
• Mid (R1·1–2 with R1·3 moonlit tops, parallax 0.3): 5 px/s.
• Near (rare, R1·2–3, parallax 1.15, partly transparent with dither): wisps of cloud that cross in front of the island.

Wind sets direction and speed (×(1 + strength)). Rain fronts darken the layers by one shade and cover the moon.

Poisoned clouds (gameplay signal, GDD §15.3): when the flux reservoir R is high, cloud bands swap their R1 shades for the same shades of R4 (one band per 2,000 motes of R). A violet sky means the next rain will carry vented flux back down.

4.3 Rain (code)

• Streaks 1 × 3 px (light) or 1 × 4 px (heavy), slanted 1 px per 4 px of fall at wind ≥ 2.
• Two depth layers: the far layer is R1·2 and isn't lit; the near layer is R1·3 and lit by the light field (§3.5).
• A 2-frame splash on solid tops. Roofs drip in a column at the eaves.
• Budget: 400 drops at intensity 3.

4.4 Parallax stack

Distant islands (code) are procedural silhouettes 20–60 px wide in R0·3–4 with a dangling root fringe and 1–2 window dots of R2·6. One window goes dark every 3 Nights (GDD §13.2).

4.5 The void below

• A gradient from R0·2 to R0·0 below the island.
• The underside fringe has dangling roots (R4·1) swaying ±1 px.
• Occasionally (1 per 5 min) a "deep shape" drifts past: a large, soft R0·0 silhouette against R0·1, parallax 0.2, gone in 20 s. Pure atmosphere.
• The Visitor (code): a 320 × 96 noise silhouette crossing the void at parallax 0.4, which hides stars and clouds behind it.

4.6 Tilt rendering

The island stays grid-aligned. Every procedural background layer (sky gradient, stars, clouds, distant islands, horizon) is evaluated in rotated coordinates at −θ around the screen center. Because these layers are procedural, rotation stays crisp with no rotated textures and no jaggies. Hanging lamps and chains swing to stay vertical in world space.

4.7 Strata looks

5. Characters, creatures and entities

5.1 Silhouette rules

• Every character must read as a black silhouette at 1×.
• Living things are rounded (cozy).
• Golems are blocky and slightly wrong: limbs too short, a head that doesn't sit centered.
• Void entities are shapes of absence: bodies of R0·0, edged with a 1 px R4·2 or R4·3 rim, with exactly two 1 px R1·6 eye glints at most. Never teeth, blood, flesh or wounds.

5.2 Animation frame counts

Frame rates are in fps; animation is stepped.

6. Machines and pipes: the visual language of automation

6.1 Materials (fixed ramp per material)

• Brass: R2·3–5
• Iron: R6·2–5
• Glass: R3·2–4 with an R1·6 highlight pixel
• Wood: R5·2–5
• Bone: R5·5–7
• Root: R4·1–3

6.2 Silhouette by function

Each function owns one silhouette family, so a player can identify a machine from its shape alone at 1×.

6.3 Pilot light

Every machine has a 2 × 2 pilot light at its top-right, which is emissive:

6.4 Working motion

Code overlays add 2–4 frame motion only while a machine is working: bubbles rising in glass (2 px, R3·6), a flame (3 frames), and a gear (5 × 5, 4 rotation frames drawn by code). A machine that isn't moving isn't working. That's the single most important readability rule.

6.5 Pipes (code, 8 × 8 autotile, 16 connection masks)

• A 4 px-wide iron body: R6·3 casing, R6·5 top highlight, R6·1 underside.
• A 2 px window down the center shows the fluid in its signature color, alternating shades s and s−1 in 2 px dashes. The dashes move along the flow at a speed proportional to throughput.
• An empty pipe shows an R0·1 window.
• The locked fluid type is always shown by a 1 px rivet at each joint in the type color.
• A blocked junction shows a blinking R4·6 cross.

6.6 Containers and golem routes

• Jars and cisterns: a fill level shown as colored rows inside the glass (8 steps).
• Golem routes: shown with the chalk tool held, as a dotted R1·6 line with numbered waypoint chalk marks (3 × 5 digits). Arranger spirals use R1·5 chalk too: a 5 × 5 spiral with a single R4·5 pixel at the center.

6.7 Lamps

• Each lamp body is a sprite. Its flame or light is a separate emissive overlay.
• A starved or guttered lamp shows a cold R6·2 wick.
• A straining lamp flickers its light-field level and its flame overlay stutters.

7. Flux, mutation and warp visuals: eerie, never gory

7.1 Air flux (no lens)

Particles in R4, never solid color:

7.2 Soil and water flux

• Soil flux > 150: procedural violet veins (R4·3 one-pixel crack paths) over the tile. At > 280, the veins pulse.
• Water flux: the water surface shade shifts from R0·4/R3·3 toward R4·3/R4·2 as dissolved flux rises. The pond's moon reflection fades.

7.3 Crystal taint

Charge < 0.5 swaps the R3 shades for R4 shades of the same index, and the emissive core dims to R4·5.

7.4 Mutation (palette and shape, never flesh)

• Turned: 30–50% of R7 pixels swap to R4 shades of the same index, and 1–3 extra "eye" pixels (R3·7 with an R0·0 pupil pixel beside them) are stamped onto bark, wheat heads or frog backs. Shapes stretch 1–2 px taller.
• Hollowed: interior pixels become R0·0, keeping a 1 px rim of the original ramp, as if the organism were a hole shaped like itself. Hollowed organisms give off a faint R4·2 shimmer.

7.5 Hallucinations

Identical sprites, but they never darken light, never appear in reflections, and never leave a flux wake. The visual rules guarantee the tells (GDD §6.6). There are no "glitch" shaders and no chromatic aberration. The pixel grid always stays intact.

7.6 Collapse and cracks

• Cracks: 3 overlay stages of R0·0 one-pixel crack lines.
• Dust: 1 px R5·5 particles falling.
• Collapse: a 1 px screen shake for 0.3 s.

8. UI style, fonts and icons

• Panels: parchment (R5·6 fill, R5·7 highlight row) with ink text (R0·1), a 1 px brass frame (R2·4, with R2·3 on the shadow side) and a 1 px R0·0 drop shadow. 9-slice with 4 px corners, drawn by code.
• Selection: a 1 px R3·5 outline that pulses to R3·6.
• Warnings: R4·5 with a glyph. Never red.

8.1 Fonts (no CC0, no purchase)

Fonts are defined as bitmap data in data/fonts/*.json (glyph rows as strings), and the build agent authors them.

• Lantern 5×7: proportional, 3–5 px advance, 7 px cap height, 2 px descenders, 10 px line height. All UI text. Printable ASCII plus ° · — … ✓ ✗ ←→↑↓.
• Wick 3×5: digits, uppercase and +−%/:. Stack counts and machine numbers.
• Keeper Hand: Lantern 5×7 with a 1 px shear every 3 rows (generated by code) and ink in R5·1. Used for journals and the Keeper's Log. Warped keepers' text uses R4·4 ink with a ±1 px vertical jitter per glyph.

8.2 Icons

• Item icons: 12 × 12, one ramp-consistent sprite each, with outlines by the lanternforge rule.
• Essence glyphs: 7 × 7 one-pixel stroke glyphs, drawn by code from stroke specs in data/glyphs.json. Each primal has a simple form (Ember is a flame tick, Dew a droplet, Loam a square, Breath three lines, Glim a star, Hush a crescent). Compounds combine strokes. Tier rings: 9 × 9 circle segments, one per tier.

8.3 HUD placement (480 × 270)

Lenses use their own overlay inks: flux in R4, light in R2 and R3, structure in R6.

9. Animation and effects guidelines

1. Stepped animation only: 8–12 fps for characters and 4–8 fps for machines. No sub-pixel sprite motion; positions are whole internal pixels.
2. Never rotate or scale sprites. Pre-draw frames, or use procedural geometry (§4.6).
3. Palette cycling (shifting indices within a ramp) is the main ambient-animation tool: water shimmer, star twinkle, crystal sparkle, root pulse, Heart breath, pipe flow.
4. Particle budget: 2,000 live particles. Every particle is 1–2 px, palette-indexed and lit through the LUT unless it's emissive.
5. Light is an animation. Flame flicker, wisp breathing and lamp strain are changes in the light field, not sprite changes.
6. No flashes faster than 3 Hz, nothing full-screen, and screen shake of at most 1 px. New threats fade in over at least 3 s (sim rule) and are never instant.
7. Effects list:
   • lamp ignition (light grows over 1 s)
   • wisp catch (a 6-pixel sparkle)
   • successful Crucible test (a ring of R3·6 pixels expanding 8 px)
   • failed test (a violet puff of 30 haze particles)
   • gleaner theft (the item icon fades as it's carried)
   • arrangement (chalk spiral draws in over 1 s)
   • crack, collapse, tide rise (the fog edge advances), rain splash
   • the Visitor's passage

10. Production plan (no purchased or commissioned assets)

10.1 Methods

• (a) Code: runtime-generated visuals, effects, UI.
• (b) Procedural: tiles and plants generated from rules, deterministic by seed. The tile generator lives in TS (shared with runtime variation) and can export an atlas PNG for review and compliance checks.
• (c) AI + lanternforge: text-to-image generation followed by the automated cleanup in §10.4.
• (d) Hand edit by the owner: at most 20 assets; 18 are allocated in §10.3.
• CC0: none planned. The fonts are custom. Any future CC0 asset needs a DECISIONS.md entry.

10.2 Full asset list

Each row belongs to exactly one milestone (i4 split the old multi-milestone rows; see sims/S10_scope.results.md). "×N" counts distinct assets. Tiles count as one type each, because their variants and autotile edges come from rules.

Cut from 1.0 (i4, GDD §19): A09 The Visitor (gameplay cut; the A08 "deep shapes" keep the atmosphere), the Root golem body, the Lure, the Root Graft, and the Glowfruit Lamp.

10.3 Hand-edit budget (≤ 20; 18 allocated)

10.4 The cleanup tool: lanternforge (the build agent must create it)

Python 3.11+, Pillow, NumPy. Deterministic, with pytest coverage for every step.

CLI

lanternforge clean   <in.png> --spec <spec.json> --out <out.png>   # AI image -> game sprite
lanternforge check   <dir>                                        # CI gate, nonzero on failure
lanternforge lut     --zones data/zones.json --out assets/lut.png # §3.3
lanternforge preview <sprite.png> --tiles <atlas.png> --light hearth|wisp|dark --out <png>
lanternforge sheet   <dir> --out <contact.png>                    # review sheets, blind tests

Spec (per asset)

{ "id": "alembic", "size": [16, 24], "frames": 1, "anchor": "bottom-center",
  "ramps": ["EMBER", "STONE", "GLIM", "EARTH"], "max_colors": 12,
  "max_shades_per_ramp": 4, "outline": "selective", "background": "magenta",
  "emissive": { "auto": true, "force_rects": [], "exclude_rects": [] } }

clean pipeline (in order)

1. Key out the background. Remove pixels within ΔOKLab 0.12 of #ff00ff and despill magenta-tinted edge pixels toward their neighbors. If the input has real alpha, use it.
2. Crop to the alpha bounding box.
3. Detect the grid. If the image is pseudo-pixel-art, estimate its block size b from 2 to 32 by maximizing the autocorrelation of horizontal and vertical gradient energy at period b, then take the median color of each block. Otherwise, resize to fit the target (minus a 1 px outline margin) with an area-average in linear light.
4. Place in the frame by the anchor rule.
5. Binarize alpha at 0.5. Fill 1 px holes surrounded by ≥ 6 opaque pixels.
6. Quantize. Deterministic k-means in OKLab (k = max_colors, k-means++ with seed 0), then map each centroid to the nearest palette color among the allowed ramps. Ramp coherence: inside each ramp, the clusters' luminance order must map to increasing shades (resolve collisions by shifting shades), and clusters that map to the same index merge. If a ramp uses more than max_shades_per_ramp shades, merge its closest adjacent shades.
7. Clean up.
   • Orphans: a non-emissive pixel that differs from all 8 neighbors takes the mode of its neighbors.
   • Outline jaggies: remove doubled L-corners on 1 px outlines.
   • Thin-feature warning: flag any part narrower than 2 px whose total area is under 6 px.
8. Outline (selective). Every transparent pixel that is 4-adjacent to the opaque sprite becomes outline. Its color is shade max(0, s−3) of the adjacent interior pixel's ramp, or max(0, s−2) when that interior pixel faces top-left (the light side). The interior is never black-lined. The same rule applies to tile edges (B-assets: exposed top edges get a +1 highlight, exposed sides and bottoms get −2 or −3), so sprites and tiles share one edge language.
9. Emissive mask. Automatically mark interior (non-outline) pixels at R2·6–7, R3·6–7, R1·7, plus anything in force_rects, minus exclude_rects.
10. Export an indexed PNG (PLTE = the 64 colors plus index 64 transparent via tRNS) and <id>.meta.json containing size, frames, anchor, the emissive mask (RLE), ramps used and color count.
11. Report a before/after/preview strip at ×4 plus warnings: colors merged, contrast against the stratum's tiles below 2 shades, thin features.

check (CI) — every PNG under /assets must:

• use only palette indices;
• have binary alpha;
• match its declared size and frames;
• stay within its color and ramp budget;
• follow the outline rule (every opaque pixel that touches transparency is outline-class);
• have a meta file.

Prompt template (works with any text-to-image model):

Pixel art game sprite of {subject}, side view, {W}×{H} pixel sprite shown at 16× with hard square pixels, limited palette of {ramp words: e.g. "warm brass, slate iron, teal glass"}, flat even lighting from the top left, no cast shadow, no glow, no background scenery, solid flat magenta #FF00FF background, centered, full object visible, cozy dark-fantasy alchemy, clean readable silhouette. Negative: anti-aliasing, gradients, blur, glow, bloom, text, watermark, frame, 3D render, photo.

Generate 4–8 candidates, pick the one with the best silhouette, run clean, then preview it under the 3 lights.

The albedo rule: AI sprites are unlit albedo. The engine applies the night look through the LUT. Never prompt for "night", "moonlit" or "glowing". Emissive parts come from the mask.

10.5 Why this style survives a small asset set

• Strict palette plus LUT lighting: every asset, whatever its source, ends up as the same 64 colors under the same light, so cohesion is mechanical rather than artistic.
• 8 px tiles at 480 × 270: small sprites are cheap to generate and forgiving to clean up.
• Richness from systems: about 40 code-driven effects (sky, moon, rain, halos, wisps, haze, water, palette cycling) make up most of the screen at any moment. On a typical surface frame, about 60% of pixels come from code or procedural layers. [UNVERIFIED: M04 cross-section mockup must measure this.]

11. Planned mockups