@dopaminefx/effect-lightning 0.1.0

package/dist/lightning-shader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lightning-shader.js","sourceRoot":"","sources":["../src/lightning-shader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EACL,cAAc,EACd,WAAW,EACX,QAAQ,EACR,SAAS,EACT,WAAW,EACX,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,uEAAuE;AACvE,0EAA0E;AAC1E,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEvF,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,CAAC;AAE3D;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,SAAS,GAAG,cAAc,CAAC;AAEtD,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;;;;EAI7C,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,UAAU,CAAC;;;;;;;;;;;;;;;;;;;;;;;uBAuB1B,WAAW;0BACR,SAAS;;oBAEf,SAAS;oBACT,SAAS;oBACT,SAAS;cACf,cAAc;EAC1B,cAAc;EACd,SAAS;EACT,QAAQ;EACR,iBAAiB;EACjB,WAAW;EACX,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAoIX,CAAC"}

package/dist/lightning.dope.json

@@ -0,0 +1,495 @@
+{
+    "fmt": "dopamine-effect",
+    "v": "1.0.0",
+    "id": "dopamine.boost.lightning",
+    "meta": {
+        "name": "Lightning",
+        "description": "A high-energy power-up / boost strike: a branching, fbm-perturbed electric arc cracks into the action point with a hard white flash, secondary forks, and a brief flicker afterglow. Electric OKLCH blues/violets to a hot white core.",
+        "tags": [
+            "boost",
+            "power-up",
+            "electric",
+            "lightning",
+            "anchored"
+        ]
+    },
+    "controls": {
+        "mood": {
+            "type": "enum",
+            "label": "Mood",
+            "default": "electric",
+            "options": [
+                "serene",
+                "celebratory",
+                "electric"
+            ],
+            "ui": "segmented"
+        },
+        "intensity": {
+            "type": "scalar",
+            "label": "Intensity",
+            "default": 0.85,
+            "min": 0,
+            "max": 1,
+            "step": 0.01,
+            "ui": "slider",
+            "help": "Bolt thickness, branch count, flash brightness."
+        },
+        "whimsy": {
+            "type": "scalar",
+            "label": "Whimsy",
+            "default": 0.5,
+            "min": 0,
+            "max": 1,
+            "step": 0.01,
+            "ui": "slider",
+            "help": "Photoreal plasma glow (0) to flat cel comic-book bolt + harder strobe (1)."
+        },
+        "seed": {
+            "type": "int",
+            "label": "Seed",
+            "default": null,
+            "nullable": true,
+            "help": "Null = unique bolt + palette per fire; pin to reproduce."
+        },
+        "origin": {
+            "type": "point",
+            "label": "Origin",
+            "default": "center"
+        },
+        "target": {
+            "type": "selector",
+            "label": "Target",
+            "default": "document.body"
+        }
+    },
+    "baselines": {
+        "serene": {
+            "durationMs": 1400,
+            "lightness": 0.82,
+            "chroma": 0.12,
+            "hueCenter": 245,
+            "hueRange": 60,
+            "thickness": 0.012,
+            "jagged": 0.55,
+            "branches": 0,
+            "flashBright": 0.5,
+            "flicker": 0.3,
+            "overshoot": 0.7
+        },
+        "celebratory": {
+            "durationMs": 1100,
+            "lightness": 0.8,
+            "chroma": 0.18,
+            "hueCenter": 228,
+            "hueRange": 110,
+            "thickness": 0.016,
+            "jagged": 0.85,
+            "branches": 3,
+            "flashBright": 0.8,
+            "flicker": 0.65,
+            "overshoot": 1.05
+        },
+        "electric": {
+            "durationMs": 850,
+            "lightness": 0.8,
+            "chroma": 0.24,
+            "hueCenter": 268,
+            "hueRange": 90,
+            "thickness": 0.02,
+            "jagged": 1.15,
+            "branches": 6,
+            "flashBright": 1.1,
+            "flicker": 1,
+            "overshoot": 1.5
+        }
+    },
+    "palette": {
+        "model": "oklch",
+        "space": "linear-srgb",
+        "generator": "golden-angle",
+        "goldenAngleDeg": 137.50776405003785,
+        "stops": 3,
+        "hueSpread": 0.4,
+        "lightness": {
+            "baseline": "lightness",
+            "perStop": [
+                0.08,
+                0,
+                -0.06
+            ]
+        },
+        "chroma": {
+            "from": {
+                "mul": [
+                    {
+                        "baseline": "chroma"
+                    },
+                    {
+                        "lerp": [
+                            "intensity",
+                            0.7,
+                            1.4
+                        ]
+                    }
+                ]
+            },
+            "perStop": [
+                -0.02,
+                0.02,
+                0.01
+            ]
+        },
+        "seed": {
+            "deterministic": true,
+            "source": "controls.seed",
+            "prng": "mulberry32"
+        },
+        "perMood": {
+            "serene": {
+                "hueCenter": 245,
+                "hueRange": 60,
+                "lightness": 0.82,
+                "chroma": 0.12
+            },
+            "celebratory": {
+                "hueCenter": 228,
+                "hueRange": 110,
+                "lightness": 0.8,
+                "chroma": 0.18
+            },
+            "electric": {
+                "hueCenter": 268,
+                "hueRange": 90,
+                "lightness": 0.8,
+                "chroma": 0.24
+            }
+        }
+    },
+    "tempo": {
+        "durationMs": {
+            "from": {
+                "round": {
+                    "mul": [
+                        {
+                            "baseline": "durationMs"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                1.15,
+                                0.9
+                            ]
+                        }
+                    ]
+                }
+            }
+        },
+        "frame": {
+            "note": "The per-frame logic, datafied (was lightning-tempo): amp = the impact envelope; strike = strikeProgress(animMs), the ease-out-quint crack-in over the 130 ms STRIKE_MS window (the same clock the CPU bolt precompute keys off — see x-build.logic); flash = flashStrobe(life, flicker), an instantaneous near-white primary that decays fast (exp(-t/0.035)) plus 6 discrete afterglow re-pulses (sin^8 spikes) whose peaks decay across the tail, scaled by flicker.",
+            "amp": {
+                "envelope": [
+                    {
+                        "input": "life"
+                    },
+                    {
+                        "param": "overshoot"
+                    }
+                ]
+            },
+            "extras": {
+                "strike": {
+                    "sub": [
+                        1,
+                        {
+                            "pow": [
+                                {
+                                    "sub": [
+                                        1,
+                                        {
+                                            "clamp01": {
+                                                "div": [
+                                                    {
+                                                        "input": "animMs"
+                                                    },
+                                                    130
+                                                ]
+                                            }
+                                        }
+                                    ]
+                                },
+                                5
+                            ]
+                        }
+                    ]
+                },
+                "flash": {
+                    "add": [
+                        {
+                            "exp": {
+                                "div": [
+                                    {
+                                        "mul": [
+                                            -1,
+                                            {
+                                                "clamp01": {
+                                                    "input": "life"
+                                                }
+                                            }
+                                        ]
+                                    },
+                                    0.035
+                                ]
+                            }
+                        },
+                        {
+                            "mul": [
+                                {
+                                    "pow": [
+                                        {
+                                            "max": [
+                                                0,
+                                                {
+                                                    "sin": {
+                                                        "mul": [
+                                                            {
+                                                                "clamp01": {
+                                                                    "input": "life"
+                                                                }
+                                                            },
+                                                            6,
+                                                            3.141592653589793,
+                                                            2
+                                                        ]
+                                                    }
+                                                }
+                                            ]
+                                        },
+                                        8
+                                    ]
+                                },
+                                {
+                                    "mul": [
+                                        {
+                                            "pow": [
+                                                {
+                                                    "sub": [
+                                                        1,
+                                                        {
+                                                            "clamp01": {
+                                                                "input": "life"
+                                                            }
+                                                        }
+                                                    ]
+                                                },
+                                                2.2
+                                            ]
+                                        },
+                                        0.28,
+                                        {
+                                            "param": "flicker"
+                                        }
+                                    ]
+                                }
+                            ]
+                        }
+                    ]
+                }
+            }
+        },
+        "reducedMotion": {
+            "peakMs": 130,
+            "holdMs": 300
+        }
+    },
+    "render": {
+        "params": {
+            "exposure": {
+                "type": "float",
+                "from": {
+                    "lerp": [
+                        "intensity",
+                        0.9,
+                        1.6
+                    ]
+                }
+            },
+            "thickness": {
+                "type": "float",
+                "from": {
+                    "mul": [
+                        {
+                            "baseline": "thickness"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                0.7,
+                                1.35
+                            ]
+                        }
+                    ]
+                }
+            },
+            "jagged": {
+                "type": "float",
+                "from": {
+                    "mul": [
+                        {
+                            "baseline": "jagged"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                0.8,
+                                1.2
+                            ]
+                        }
+                    ]
+                }
+            },
+            "branches": {
+                "type": "int",
+                "clampMax": "MAX_FORKS",
+                "from": {
+                    "round": {
+                        "mul": [
+                            {
+                                "baseline": "branches"
+                            },
+                            {
+                                "lerp": [
+                                    "intensity",
+                                    0.5,
+                                    1.25
+                                ]
+                            }
+                        ]
+                    }
+                }
+            },
+            "flashBright": {
+                "type": "float",
+                "from": {
+                    "mul": [
+                        {
+                            "baseline": "flashBright"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                0.6,
+                                1.4
+                            ]
+                        }
+                    ]
+                }
+            },
+            "flicker": {
+                "type": "float",
+                "clamp01": true,
+                "from": {
+                    "baseline": "flicker"
+                }
+            },
+            "overshoot": {
+                "type": "float",
+                "from": {
+                    "mul": [
+                        {
+                            "baseline": "overshoot"
+                        },
+                        {
+                            "lerp": [
+                                "intensity",
+                                0.7,
+                                1.25
+                            ]
+                        }
+                    ]
+                }
+            },
+            "style": {
+                "type": "float",
+                "from": {
+                    "control": "whimsy"
+                }
+            }
+        },
+        "shadowHeightFrac": {
+            "add": [
+                {
+                    "mul": [
+                        {
+                            "param": "thickness"
+                        },
+                        14
+                    ]
+                },
+                0.4
+            ]
+        },
+        "consts": {
+            "MAX_FORKS": 7
+        },
+        "config": {
+            "usesOrigin": true
+        },
+        "backends": {
+            "webgl2": {
+                "stage": "fullscreen-triangle",
+                "blend": "screen",
+                "shader": {
+                    "program": "lightning"
+                }
+            }
+        },
+        "fallbackOrder": [
+            "webgl2"
+        ]
+    },
+    "binding": {
+        "note": "CROSS-PLATFORM uniform-binding contract. Which render.params are NOT shader uniforms, the seed-keyed scatter field, the per-frame/host extras, the texture samplers, and the per-frame ARRAYS — one source of truth for the web u<Name> list, the Swift struct + packer, and the MSL struct. SHIPS in the portable .dope (the runtime derives its uniform bindings from it); the toolchain consumes it too for the Metal struct codegen. Only `x-build`, `slug` and `kind` stay toolchain-only. lightning's CPU-precomputed bolt polyline rides the frameArrays seam declared in `arrays` (uVerts/uBoltMeta), not the uniform struct.",
+        "excludeParams": [
+            "style",
+            "overshoot",
+            "flicker",
+            "durationMs",
+            "jagged",
+            "branches"
+        ],
+        "scatterKey": "boltSeed",
+        "scatterWeb": "uSeed",
+        "extras": [
+            {
+                "name": "strike",
+                "type": "float",
+                "web": "uStrike",
+                "note": "tempo.frame.extras.strike — the 130 ms ease-out-quint crack-in"
+            },
+            {
+                "name": "flash",
+                "type": "float",
+                "web": "uFlash",
+                "note": "tempo.frame.extras.flash — the strobe (primary flash + flicker afterglow)"
+            }
+        ],
+        "samplers": [],
+        "arrays": [
+            {
+                "name": "verts",
+                "web": "uVerts",
+                "size": 2,
+                "buffer": 1,
+                "note": "CPU-precomputed bolt polyline (x-build.logic): vertex i of bolt b at [b*VERTS_PER_BOLT + i], device px, gl y-up. Web/GL bind by NAME as the uniform vec2 array; Metal binds it as `constant float2 *uVerts` at fragment buffer 1."
+            },
+            {
+                "name": "meta",
+                "web": "uBoltMeta",
+                "size": 4,
+                "buffer": 2,
+                "note": "Per-bolt (segCount, radFrac, fadeMul, isMain); `constant float4 *uBoltMeta` at fragment buffer 2 on Metal."
+            }
+        ]
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@dopaminefx/effect-lightning",
+  "version": "0.1.0",
+  "description": "Lightning — a high-energy lightning-strike power-up effect for Dopamine.",
+  "keywords": [
+    "dopamine-effect"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": [
+    "./src/index.ts",
+    "./dist/index.js"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "dependencies": {
+    "@dopaminefx/core": "^0.1.0"
+  },
+  "license": "MIT",
+  "author": "10in30",
+  "homepage": "https://github.com/10in30/dopamine#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/10in30/dopamine.git",
+    "directory": "effects/lightning/web"
+  },
+  "bugs": {
+    "url": "https://github.com/10in30/dopamine/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+/**
+ * Lightning — Dopamine's high-energy "power-up / boost" STRIKE, as an
+ * `EffectFactory`. A jagged, fbm-perturbed branching electric arc cracks into the
+ * action point (uOrigin) with a hard white STROBE FLASH, a few secondary forks,
+ * and a brief flicker afterglow that decays. Electric OKLCH blues/violets to a
+ * hot white core. Casts a hard, sharp shadow (the shadow pass).
+ *
+ * FULLY DATA-DRIVEN: everything that isn't the GLSL or the bolt precompute
+ * lives in lightning.dope.json — the mood→params mapping + palette (the
+ * loader), the per-frame logic (`tempo.frame`: the impact-envelope amp, the
+ * 130 ms strike crack-in and the flash/strobe — what lightning-tempo.ts used to
+ * be), `render.shadowHeightFrac`, `render.consts` (MAX_FORKS),
+ * `render.config`, `tempo.reducedMotion` and the uniform `binding` contract
+ * (whose `arrays` section declares the uVerts/uBoltMeta frame arrays).
+ * `registerDopeEffect` interprets that data through the generic pass runner.
+ *
+ * The one genuinely code-shaped piece is the CPU bolt precompute — the
+ * fragment-independent polyline computed once per frame (lightning-logic.ts,
+ * the single source the Swift/Kotlin renderers are TRANSPILED from) — which
+ * rides the `hooks.frameArrays` seam here, exactly as the generated native
+ * factories wire the generated renderer into their runners' frameArrays seams.
+ *
+ * mood = register: serene = a soft single cool arc; celebratory = a lively
+ * branched bolt; electric = a violent multi-fork strike + bright strobe.
+ * intensity = bolt thickness + branch count + flash brightness.
+ * whimsy (= style) = photoreal plasma glow (0) to flat cel comic bolt + harder
+ * animate-on-twos strobe (1).
+ */
+
+import { LIGHTNING_FRAGMENT_SRC, LIGHTNING_VERTEX_SRC } from "./lightning-shader.js";
+import { computeLightningArrays } from "./lightning-logic.js";
+import {
+  parseDope,
+  registerDopeEffect,
+  type EffectFactory,
+  type PassParams,
+} from "@dopaminefx/core";
+import doc from "./lightning.dope.json";
+
+const DOPE = parseDope(doc as object);
+
+export interface LightningParams extends PassParams {
+  exposure: number;
+  thickness: number;
+  jagged: number;
+  branches: number;
+  flashBright: number;
+  flicker: number;
+  overshoot: number;
+  boltSeed: number;
+  style: number; // = whimsy (drives the on-twos cel jitter)
+}
+
+// The whole factory (resolve / uniforms / bindings / frame / shadow / reduced
+// motion / program registration) is data: lightning.dope.json interpreted by
+// the core backbone. The jagged bolt polyline (the part that used to cost
+// ~220 fbm/pixel) is PRECOMPUTED on the CPU once per frame and fed to the
+// shader through the binding.arrays contract (uVerts/uBoltMeta) — the
+// `frameArrays` hook below is the code-shaped precompute call.
+export const lightning = registerDopeEffect(
+  DOPE,
+  { vertex: LIGHTNING_VERTEX_SRC, fragment: LIGHTNING_FRAGMENT_SRC },
+  {
+    hooks: {
+      frameArrays: ({ animMs, life }, params, geom) => {
+        const p = params as LightningParams;
+        const { verts, meta } = computeLightningArrays(
+          p.style, p.thickness, p.jagged, p.branches, p.boltSeed,
+          geom.width, geom.height, geom.origin.x, geom.origin.y, animMs, life,
+        );
+        return [
+          { name: "uVerts", size: 2, data: verts },
+          { name: "uBoltMeta", size: 4, data: meta },
+        ];
+      },
+    },
+  },
+) as EffectFactory<PassParams> as EffectFactory<LightningParams>;
+
+export default lightning;