staticfx 2.0.0__py3-none-any.whl

staticfx/effects/builtin/terminal.py

@@ -0,0 +1,362 @@
+"""Retro computing: a boot log, decryption, a barcode scanner, circuit traces."""
+
+from __future__ import annotations
+
+import math
+import random
+
+from staticfx.core.color import clamp
+from staticfx.core.frame import Frame
+from staticfx.core.glyphs import HEX, tech_glyphs
+from staticfx.effects.base import Effect
+from staticfx.themes import Theme
+
+SERVICES = (
+    "udev",
+    "journald",
+    "network",
+    "dbus",
+    "cryptsetup",
+    "sshd",
+    "firewall",
+    "audio daemon",
+    "display manager",
+    "scheduler",
+    "time sync",
+    "kernel modules",
+    "power manager",
+    "entropy pool",
+    "mesh uplink",
+    "neural cache",
+)
+
+DEVICES = ("/dev/sda1", "/dev/nvme0n1p2", "/dev/mapper/root", "/dev/loop7", "/dev/sr0")
+
+WORDS = (
+    "ACCESS GRANTED KERNEL PAYLOAD ROOT DECRYPT SECTOR HANDSHAKE TOKEN BYPASS FIREWALL NODE SIGNAL"
+    " CIPHER BREACH UPLINK PROXY DAEMON SHELL EXPLOIT"
+).split()
+
+
+class TerminalBoot(Effect):
+    TOTAL_LINES = 90
+
+    def __init__(self, rng: random.Random, unicode: bool = False) -> None:
+        super().__init__(rng, unicode)
+        self.lines: list[str] = []
+        self.cooldown = 0.0
+        self.emitted = 0
+        self.hold = 0.0
+        self.memory = 0
+        self.t = 0.0
+
+    def on_resize(self) -> None:
+        self.lines = []
+        self.emitted = 0
+        self.hold = 0.0
+        self.memory = 0
+        self.cooldown = 0.0
+
+    def _next_line(self) -> str:
+        rng = self.rng
+        n = self.emitted
+
+        if n == 0:
+            return "StaticFX BIOS v2.0  (C) 2026"
+        if n == 1:
+            return "CPU: Quantum Core @ 4.20GHz   Cores: 16"
+        if n == 2:
+            return "Memory test: 00000K"
+        if n < 6:
+            return f"Detecting {rng.choice(DEVICES)} ... found"
+
+        roll = rng.random()
+        service = rng.choice(SERVICES)
+
+        if roll < 0.62:
+            return f"[  OK  ] Started {service}."
+        if roll < 0.78:
+            return f"[ INFO ] Mounted {rng.choice(DEVICES)} on /mnt/{rng.randrange(9)}"
+        if roll < 0.9:
+            return f"[ WARN ] {service} responded slowly ({rng.randint(120, 900)}ms)"
+        return f"[ .... ] Starting {service} ..."
+
+    def advance(self, dt: float) -> None:
+        self.t += dt
+
+        if self.emitted >= self.TOTAL_LINES:
+            self.hold += dt
+
+            if self.hold > 2.5:
+                self.on_resize()
+
+            return
+
+        self.cooldown -= dt
+
+        while self.cooldown <= 0.0 and self.emitted < self.TOTAL_LINES:
+            self.cooldown += self.rng.uniform(0.01, 0.16)
+            self.lines.append(self._next_line())
+            self.emitted += 1
+
+        keep = max(1, self.height - 2)
+        self.lines = self.lines[-keep:]
+
+        if self.memory < 65536 and self.emitted < self.TOTAL_LINES:
+            self.memory = min(65536, self.memory + int(dt * 40000))
+
+    def render(self, frame: Frame, theme: Theme) -> None:
+        text = theme.ramp(0.85)
+        ok = theme.primary
+        warn = theme.accent
+        dim = self.color_at(theme, 0.4)
+
+        for y, line in enumerate(self.lines):
+            if line.startswith("Memory test"):
+                line = f"Memory test: {self.memory:05d}K"
+
+            frame.text(0, y, line, text)
+
+            if line.startswith("[ "):
+                tag = line[:8]
+                frame.text(0, y, tag, warn if ("WARN" in tag or "...." in tag) else ok)
+            elif line.startswith("StaticFX"):
+                frame.text(0, y, line, theme.bright)
+
+        # progress bar
+        bar_row = self.height - 1
+        width = max(4, min(self.width - 8, 50))
+        fraction = clamp(self.emitted / self.TOTAL_LINES)
+        filled = int(width * fraction)
+        frame.text(0, bar_row, "[" + "#" * filled + "." * (width - filled) + "]", dim)
+        frame.text(width + 3, bar_row, f"{int(fraction * 100):3d}%", text)
+
+        if int(self.t * 2) % 2 == 0:
+            cursor_y = min(self.height - 2, len(self.lines))
+            frame.put(0, cursor_y, "_", theme.bright)
+
+
+class DecryptScramble(Effect):
+    def __init__(self, rng: random.Random, unicode: bool = False) -> None:
+        super().__init__(rng, unicode)
+        self.pool = tech_glyphs(False)
+        self.t = 0.0
+        self.target: list[str] = []
+        self.resolve: list[list[float]] = []
+        self.scramble: list[list[str]] = []
+        self.refresh = 0.0
+
+    def on_resize(self) -> None:
+        rng = self.rng
+        self.t = 0.0
+        self.target = []
+
+        for _ in range(self.height):
+            parts: list[str] = []
+            length = 0
+
+            while length < self.width:
+                word = (
+                    rng.choice(WORDS)
+                    if rng.random() < 0.6
+                    else "0x" + "".join(rng.choices(HEX, k=rng.choice((4, 8))))
+                )
+                parts.append(word)
+                length += len(word) + 1
+
+            self.target.append(" ".join(parts)[: self.width].ljust(self.width))
+
+        duration = 5.0
+        diagonal = max(1.0, self.height * 0.5 + self.width * 0.05)
+        self.resolve = [
+            [
+                (y * 0.5 + x * 0.05) / diagonal * duration + rng.uniform(0.0, 1.2)
+                for x in range(self.width)
+            ]
+            for y in range(self.height)
+        ]
+        self.scramble = [rng.choices(self.pool, k=self.width) for _ in range(self.height)]
+        self.refresh = 0.0
+
+    def advance(self, dt: float) -> None:
+        self.t += dt
+        self.refresh -= dt
+
+        if self.refresh <= 0.0:
+            self.refresh = 1.0 / 14.0
+            rng = self.rng
+
+            for row in self.scramble:
+                for x in range(len(row)):
+                    row[x] = rng.choice(self.pool)
+
+        if self.t > 5.0 + 1.2 + 2.5:
+            self.on_resize()
+
+    def render(self, frame: Frame, theme: Theme) -> None:
+        t = self.t
+        scrambled = self.color_at(theme, 0.32)
+        fresh = theme.bright
+        done = self.color_at(theme, 0.85)
+
+        for y in range(self.height):
+            times = self.resolve[y]
+            target = self.target[y]
+            noise = self.scramble[y]
+
+            for x in range(self.width):
+                age = t - times[x]
+
+                if age < 0.0:
+                    frame.put(x, y, noise[x], scrambled)
+                elif target[x] != " ":
+                    frame.put(x, y, target[x], fresh if age < 0.35 else done)
+
+
+class BarcodeScan(Effect):
+    def __init__(self, rng: random.Random, unicode: bool = False) -> None:
+        super().__init__(rng, unicode)
+        self.bars: list[bool] = []
+        self.digits = ""
+        self.t = 0.0
+
+    def on_resize(self) -> None:
+        rng = self.rng
+        self.bars = []
+        on = True
+
+        while len(self.bars) < self.width:
+            run = rng.choice((1, 1, 2, 2, 3, 4))
+            self.bars.extend([on] * run)
+            on = not on
+
+        self.bars = self.bars[: self.width]
+        self.digits = "".join(rng.choices("0123456789", k=max(1, self.width // 2)))
+
+    def advance(self, dt: float) -> None:
+        self.t += dt
+
+    def render(self, frame: Frame, theme: Theme) -> None:
+        top = max(0, int(self.height * 0.15))
+        bottom = max(top + 1, int(self.height * 0.75))
+        block = "█" if self.unicode else "#"
+        laser = (0.5 + 0.5 * math.sin(self.t * 0.9)) * (self.width - 1)
+
+        for x, on in enumerate(self.bars):
+            if not on:
+                continue
+
+            distance = abs(x - laser)
+            tone = 0.35 + 0.65 * clamp(1.0 - distance / 10.0)
+            color = self.color_at(theme, tone)
+
+            for y in range(top, bottom):
+                frame.put(x, y, block, color)
+
+        lx = int(laser)
+        for y in range(max(0, top - 2), min(self.height, bottom + 2)):
+            frame.put(lx, y, "|", theme.bright)
+
+        label_row = min(self.height - 1, bottom + 1)
+        start = max(0, (self.width - len(self.digits) * 2) // 2)
+
+        for index, digit in enumerate(self.digits):
+            frame.put(start + index * 2, label_row, digit, self.color_at(theme, 0.6))
+
+
+# (old direction, new direction) -> the box-drawing corner joining them; y grows downwards.
+CORNERS = {
+    ((1, 0), (0, 1)): "┐",
+    ((1, 0), (0, -1)): "┘",
+    ((-1, 0), (0, 1)): "┌",
+    ((-1, 0), (0, -1)): "└",
+    ((0, 1), (1, 0)): "└",
+    ((0, 1), (-1, 0)): "┘",
+    ((0, -1), (1, 0)): "┌",
+    ((0, -1), (-1, 0)): "┐",
+}
+
+
+class Circuit(Effect):
+    def __init__(self, rng: random.Random, unicode: bool = False) -> None:
+        super().__init__(rng, unicode)
+        self.chars: list[list[str]] = []
+        self.glow: list[list[float]] = []
+        self.walkers: list[list[int]] = []
+        self.timer = 0.0
+
+    def on_resize(self) -> None:
+        self.chars = [[" "] * self.width for _ in range(self.height)]
+        self.glow = [[0.0] * self.width for _ in range(self.height)]
+        self.walkers = [self._spawn() for _ in range(max(3, self.width * self.height // 260))]
+        self.timer = 0.0
+
+    def _spawn(self) -> list[int]:
+        rng = self.rng
+        dx, dy = rng.choice(((1, 0), (-1, 0), (0, 1), (0, -1)))
+        return [rng.randrange(self.width), rng.randrange(self.height), dx, dy, rng.randint(12, 70)]
+
+    def _glyph(self, direction: tuple[int, int], previous: tuple[int, int]) -> str:
+        if direction != previous:
+            return CORNERS[previous, direction] if self.unicode else "+"
+
+        if direction[1] == 0:
+            return "─" if self.unicode else "-"
+
+        return "│" if self.unicode else "|"
+
+    def advance(self, dt: float) -> None:
+        rng = self.rng
+        self.timer += dt
+
+        while self.timer >= 0.035:
+            self.timer -= 0.035
+
+            for index, walker in enumerate(self.walkers):
+                x, y, dx, dy, life = walker
+                previous = (dx, dy)
+
+                if rng.random() < 0.17:
+                    dx, dy = (dy, dx) if rng.random() < 0.5 else (-dy, -dx)
+                    self.chars[y][x] = self._glyph((dx, dy), previous)  # the bend
+
+                x += dx
+                y += dy
+                life -= 1
+
+                if not (0 <= x < self.width and 0 <= y < self.height) or life <= 0:
+                    if 0 <= x - dx < self.width and 0 <= y - dy < self.height:
+                        self.chars[y - dy][x - dx] = "o"
+                        self.glow[y - dy][x - dx] = 1.0
+
+                    self.walkers[index] = self._spawn()
+                    continue
+
+                self.chars[y][x] = self._glyph((dx, dy), (dx, dy))
+                self.glow[y][x] = 1.0
+                walker[0], walker[1], walker[2], walker[3], walker[4] = x, y, dx, dy, life
+
+        decay = 1.0 - 0.16 * dt
+
+        for y in range(self.height):
+            glow_row = self.glow[y]
+            char_row = self.chars[y]
+
+            for x in range(self.width):
+                if glow_row[x] > 0.0:
+                    glow_row[x] *= decay
+
+                    if glow_row[x] < 0.05:
+                        glow_row[x] = 0.0
+                        char_row[x] = " "
+
+    def render(self, frame: Frame, theme: Theme) -> None:
+        for y in range(self.height):
+            for x in range(self.width):
+                glow = self.glow[y][x]
+
+                if glow > 0.0:
+                    frame.put(x, y, self.chars[y][x], self.color_at(theme, 0.15 + 0.85 * glow))
+
+        for x, y, *_ in self.walkers:
+            frame.put(x, y, "@", theme.bright)

staticfx/effects/curated.py

@@ -0,0 +1,16 @@
+"""Hand-maintained lists over the generated effects.
+
+``EXCLUDED`` is written by ``tools/curate.py``: seeds whose output fails the
+quality gate (blank, frozen, a solid wall, or too slow). ``GALLERY`` is a hand-picked
+selection of the best-looking ones, shown first in the browser.
+"""
+
+EXCLUDED: frozenset[int] = frozenset({142, 177, 219, 328, 432, 446, 775, 931})
+
+# Picked by eye from the top-scoring seeds of `tools/curate.py --rank 100`.
+GALLERY: tuple[int, ...] = (
+    940, 435, 86, 409, 205, 75, 633, 874, 749, 990, 559, 671, 232, 55,
+    804, 725, 883, 445, 744, 369, 979, 643, 531, 13, 875, 764, 610, 403,
+    241, 842, 668, 736, 488, 546, 63, 879, 422, 674, 894, 602, 171, 793,
+    690, 343, 714, 304, 355,
+)  # fmt: skip

staticfx/effects/engine/__init__.py

@@ -0,0 +1,11 @@
+"""The procedural engine: recipes of layered patterns, warps and filters.
+
+Every generated effect and every effect made in the Studio is a
+:class:`Recipe` drawn by :class:`EngineEffect`.
+"""
+
+from staticfx.effects.engine.effect import EngineEffect
+from staticfx.effects.engine.generate import GENERATED_COUNT, describe, generate
+from staticfx.effects.engine.recipe import Recipe
+
+__all__ = ["GENERATED_COUNT", "EngineEffect", "Recipe", "describe", "generate"]

staticfx/effects/engine/effect.py

@@ -0,0 +1,267 @@
+"""Rendering a :class:`Recipe` to the terminal."""
+
+from __future__ import annotations
+
+import math
+import random
+import time
+
+from staticfx.core.color import BLACK, RGB, WHITE, gradient, hsv, tint
+from staticfx.core.frame import Frame
+from staticfx.core.glyphs import TECH
+from staticfx.effects.base import Effect
+from staticfx.effects.engine.filters import BLENDS, FILTERS
+from staticfx.effects.engine.layers import LAYERS
+from staticfx.effects.engine.recipe import ASCII_FALLBACK, Recipe
+from staticfx.effects.engine.warps import WARPS
+from staticfx.themes import Theme
+
+# 4x4 ordered-dither thresholds, centred on zero.
+BAYER = [
+    [(v + 0.5) / 16.0 - 0.5 for v in row]
+    for row in ((0, 8, 2, 10), (12, 4, 14, 6), (3, 11, 1, 9), (15, 7, 13, 5))
+]
+
+RAINBOW = [hsv(i / 256) for i in range(256)]
+
+# Block sizes (columns, rows) the field is sampled at. Pure-Python maths per
+# cell is the bottleneck, so big terminals sample every few cells and fill
+# blocks; the adaptive mode steps through these as frame cost changes.
+LEVELS = ((1, 1), (2, 1), (2, 2), (3, 2), (4, 2), (4, 3), (6, 3), (8, 4))
+MAX_SAMPLES = 2400
+SLOW_FRAME, FAST_FRAME = 0.045, 0.012  # seconds of render time
+
+
+class EngineEffect(Effect):
+    """Draws a recipe. The recipe is read every frame, so the Studio can edit
+    it in place and see the change immediately."""
+
+    def __init__(self, rng: random.Random, unicode: bool = False, *, recipe: Recipe) -> None:
+        super().__init__(rng, unicode)
+        self.recipe = recipe
+        self.clock = self._start_time()
+        self.level = 0
+        self.cost = 0.0
+        self.cooldown = 20
+        self.step_x = self.step_y = 1
+        self.blocks_x = self.blocks_y = 0
+        self.xs: list[float] = []
+        self.ys: list[float] = []
+        self.angles: list[float] = []
+        self.values: list[float] = []
+        self.previous: list[float] = []
+        self._duo: tuple[tuple[RGB, RGB] | None, list[RGB]] = (None, [])
+
+    def _start_time(self) -> float:
+        return (self.recipe.seed * 0.37) % 40.0
+
+    def on_resize(self) -> None:
+        self.level = 0
+        while self.level < len(LEVELS) - 1:
+            sx, sy = LEVELS[self.level]
+            if math.ceil(self.width / sx) * math.ceil(self.height / sy) <= MAX_SAMPLES:
+                break
+            self.level += 1
+        self._layout()
+
+    def on_reset(self) -> None:
+        self.clock = self._start_time()
+        self.cooldown = 20
+        super().on_reset()
+
+    def _layout(self) -> None:
+        w, h = self.width, self.height
+        self.step_x, self.step_y = LEVELS[self.level]
+        self.blocks_x = math.ceil(w / self.step_x)
+        self.blocks_y = math.ceil(h / self.step_y)
+        self.xs, self.ys, self.angles = [], [], []
+        for by in range(self.blocks_y):
+            ny = (by * self.step_y + self.step_y / 2 - h / 2) / max(1.0, h / 2)
+            for bx in range(self.blocks_x):
+                nx = (bx * self.step_x + self.step_x / 2 - w / 2) / max(1.0, float(h))
+                self.xs.append(nx)
+                self.ys.append(ny)
+                self.angles.append(math.atan2(ny, nx) / math.tau + 0.5)
+        self.values = [0.0] * len(self.xs)
+        self.previous = [0.0] * len(self.xs)
+
+    def advance(self, dt: float) -> None:
+        self.clock += dt * self.recipe.speed
+        if not self.adaptive:
+            return
+        self.cooldown -= 1
+        if self.cooldown > 0:
+            return
+        if self.cost > SLOW_FRAME and self.level < len(LEVELS) - 1:
+            self.level += 1
+            self._layout()
+            self.cooldown = 25
+        elif self.cost < FAST_FRAME and self.level > 0:
+            self.level -= 1
+            self._layout()
+            self.cooldown = 90
+
+    def charset(self) -> str:
+        chars = self.recipe.charset
+        return ASCII_FALLBACK if self.ascii_only and not chars.isascii() else chars
+
+    def _sample(self) -> None:
+        """Fill ``self.values`` with the recipe's brightness at each sample point."""
+        recipe, t = self.recipe, self.clock
+        warps = [WARPS[s.kind].build(s.params, t) for s in recipe.warps]
+        first = LAYERS[recipe.layers[0].kind].build(recipe.layers[0].params, t)
+        rest = [(BLENDS[s.blend], LAYERS[s.kind].build(s.params, t)) for s in recipe.layers[1:]]
+        filters = [FILTERS[s.kind].build(s.params, t) for s in recipe.filters]
+        xs, ys, values = self.xs, self.ys, self.values
+
+        for i in range(len(xs)):
+            x, y = xs[i], ys[i]
+            try:
+                for warp in warps:
+                    x, y = warp(x, y)
+                v = first(x, y)
+                for blend, layer in rest:
+                    v = blend(v, layer, x, y)
+                v = 0.0 if v < 0.0 else 1.0 if v > 1.0 else v
+                for f in filters:
+                    v = f(v)
+                v = 0.0 if v < 0.0 else 1.0 if v > 1.0 else v
+            except (ValueError, OverflowError, ZeroDivisionError):
+                v = 0.0  # e.g. a negative number to a fractional power
+            values[i] = v
+
+    def _post(self) -> None:
+        """Auto-gain, trails and pulsing on the sampled values."""
+        recipe, values = self.recipe, self.values
+        count = len(values)
+        peak = max(values) if values else 0.0
+
+        # Never let a recipe render dim or blank: stretch a dark field to full range,
+        # and replace a completely black one with a gentle diagonal gradient.
+        if peak < 0.6:
+            if peak > 1e-6:
+                gain = min(8.0, 0.95 / peak)
+                for i in range(count):
+                    values[i] = min(1.0, values[i] * gain)
+            else:
+                t, xs, ys = self.clock, self.xs, self.ys
+                for i in range(count):
+                    values[i] = (xs[i] * 3.1 + ys[i] * 2.3 + t * 0.3) % 1.0
+
+        if recipe.trail:
+            previous, decay = self.previous, recipe.trail
+            for i in range(count):
+                faded = previous[i] * decay
+                values[i] = max(values[i], faded)
+                previous[i] = values[i]
+
+        if recipe.pulse:
+            level = 0.55 + 0.45 * (0.5 + 0.5 * math.sin(self.clock * recipe.pulse * 6))
+            for i in range(count):
+                values[i] *= level
+
+    def _colours(self, theme: Theme) -> list[RGB]:
+        """A colour per sample point."""
+        palette, t = self.recipe.palette, self.clock
+        values = self.values
+        if palette.kind == "theme":
+            lut = theme.lut
+            return [lut[int(v * 255)] for v in values]
+        if palette.kind == "duo":
+            duo = self._duo_lut(palette.first, palette.second)
+            return [duo[int(v * 255)] for v in values]
+        out = []
+        for i, v in enumerate(values):
+            if palette.kind == "rainbow":
+                hue = v * palette.spread + t * palette.drift + palette.offset
+                k = 0.25 + 0.75 * v
+            else:  # angular
+                hue = self.angles[i] + t * 0.08 + v * 0.3
+                k = 0.2 + 0.8 * v
+            r, g, b = RAINBOW[int(hue * 255) & 255]
+            out.append(RGB(int(r * k), int(g * k), int(b * k)))
+        return out
+
+    def _duo_lut(self, first: RGB, second: RGB) -> list[RGB]:
+        if self._duo[0] != (first, second):
+            stops = [(0.0, BLACK), (0.45, first), (0.85, second), (1.0, WHITE)]
+            self._duo = ((first, second), [gradient(stops, i / 255) for i in range(256)])
+        return self._duo[1]
+
+    def render(self, frame: Frame, theme: Theme) -> None:
+        started = time.perf_counter()
+        self._sample()
+        self._post()
+        colours = self._colours(theme)
+
+        recipe, rng = self.recipe, self.rng
+        w, h = self.width, self.height
+        sx, sy = self.step_x, self.step_y
+        chars = self.charset()
+        top = len(chars) - 1
+        rnd, pool, pool_size = rng.random, TECH, len(TECH)
+        cells, values = frame.cells, self.values
+        i = 0
+
+        for by in range(self.blocks_y):
+            y0, y1 = by * sy, min(h, by * sy + sy)
+            for bx in range(self.blocks_x):
+                v, colour = values[i], colours[i]
+                i += 1
+                x0, x1 = bx * sx, min(w, bx * sx + sx)
+                if recipe.glyph_rain:
+                    if v > 0.16:
+                        threshold = 0.35 + v * 0.6
+                        for y in range(y0, y1):
+                            for cell in cells[y][x0:x1]:
+                                if rnd() < threshold:
+                                    cell.char = pool[int(rnd() * pool_size)]
+                                    cell.color = colour
+                elif recipe.dither:
+                    shifted = v * top + 0.5
+                    for y in range(y0, y1):
+                        bayer = BAYER[y & 3]
+                        row = cells[y]
+                        for x in range(x0, x1):
+                            index = min(top, int(shifted + bayer[x & 3] * 1.2))
+                            if index > 0:
+                                cell = row[x]
+                                cell.char = chars[index]
+                                cell.color = colour
+                else:
+                    index = int(v * top + 0.5)
+                    if index > 0:
+                        char = chars[index]
+                        for y in range(y0, y1):
+                            for cell in cells[y][x0:x1]:
+                                cell.char = char
+                                cell.color = colour
+
+        self._extras(frame, theme)
+        self.cost = self.cost * 0.75 + (time.perf_counter() - started) * 0.25
+
+    def _extras(self, frame: Frame, theme: Theme) -> None:
+        recipe, rng = self.recipe, self.rng
+        w, h, cells = self.width, self.height, frame.cells
+
+        if recipe.scanlines:
+            for row in cells[::2]:
+                for cell in row:
+                    if cell.char != " ":
+                        r, g, b = cell.color
+                        cell.color = RGB(r * 6 // 10, g * 6 // 10, b * 6 // 10)
+
+        if recipe.glitch and rng.random() < 0.3:
+            for _ in range(rng.randint(1, 3)):
+                row = cells[rng.randrange(h)]
+                shift = rng.randint(1, max(1, w // 6))
+                snapshot = [(c.char, c.color) for c in row]
+                for x, cell in enumerate(row):
+                    cell.char, cell.color = snapshot[(x + shift) % w]
+
+        if recipe.sparkle:
+            colour = tint(theme.bright, 0.5)
+            for _ in range(int(w * h * recipe.sparkle) + 1):
+                cell = cells[rng.randrange(h)][rng.randrange(w)]
+                cell.char = rng.choice("*+.'")
+                cell.color = colour