# packages/core/src/features/textures/lib/lightning.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/features/textures/lib/lightning.ts#L230). [Back to reference](/reference/types/electric-textures/)
1 import { ElectricMemory, type ElectricConnection } from "./wasm/electric.js";
2 import { lazyKernel } from "./wasm/memory.js";
3 import { bytes } from "./wasm/lightning-bytes.js";
4 const wasmModule = /* @__PURE__ */ lazyKernel(bytes);
5 import { defineTexture } from "@pibbl/core";
6 import { validateSeed } from "./palette.js";
7 import {
8   electricOptions,
9   point,
10   range,
11   type ElectricControl,
12   type ElectricOptions,
13   type ElectricPoint,
14 } from "./electric-shared.js";
15 
16 /**
17  * Electrical appearance, electrode positions, topology frequency, and base-connection controls.
18  *
19  * @see {@link ElectricOptions}
20  * @see {@link ElectricPoint}
21  * @see {@link lightning}
22  * @see {@link LightningMessage}
23  */
24 export interface LightningOptions extends ElectricOptions {
25   /** Position of the positive electrode. See {@link ElectricPoint}. */
26   readonly positive?: ElectricPoint;
27   /** Position of the negative electrode. See {@link ElectricPoint}. */
28   readonly negative?: ElectricPoint;
29   /** Boundary edge used as the electrical connection's origin. See {@link LightningOptions}. */
30   readonly edge?: "top" | "right" | "bottom" | "left";
31   /** Enables the configured base connection; manual connections remain independent. */
32   readonly active?: boolean;
33   /** Topology refreshes per second, 1..30. Connections survive several refreshes. */
34   readonly frequency?: number;
35   /** Whether to draw the electrode contact core. See {@link LightningOptions}. */
36   readonly contactCore?: boolean;
37 }
38 /**
39  * Control, connection management, and live configuration commands for a lightning texture.
40  *
41  * @see {@link ElectricControl}
42  * @see {@link ElectricPoint}
43  * @see {@link LightningOptions}
44  */
45 export type LightningMessage =
46   | ElectricControl
47   | {
48       /** The literal "connect" identifying this variant. See {@link LightningMessage}. */
49       readonly type: "connect";
50       /** Stable identifier of this resource or connection. See {@link LightningMessage}. */
51       readonly id: string;
52       /** Position of the positive electrode. See {@link ElectricPoint}. */
53       readonly positive: ElectricPoint;
54       /** Position of the negative electrode. See {@link ElectricPoint}. */
55       readonly negative: ElectricPoint;
56     }
57   | {
58       /** The literal "disconnect" identifying this variant. See {@link LightningMessage}. */
59       readonly type: "disconnect";
60       /** Stable identifier of this resource or connection. See {@link LightningMessage}. */
61       readonly id: string;
62     }
63   | {
64       /** The literal "configure" identifying this variant. See {@link LightningMessage}. */
65       readonly type: "configure";
66       /** Position of the positive electrode. See {@link ElectricPoint}. */
67       readonly positive?: ElectricPoint;
68       /** Position of the negative electrode. See {@link ElectricPoint}. */
69       readonly negative?: ElectricPoint;
70       /** Boundary edge used as the electrical connection's origin. See {@link LightningOptions}. */
71       readonly edge?: LightningOptions["edge"];
72       /** Current active operation or its presentation configuration. See {@link LightningMessage}. */
73       readonly active?: boolean;
74       /** Amount of secondary electrical branching. See {@link LightningMessage}. */
75       readonly branching?: number;
76       /** Intensity of the electrical halo around the core. See {@link LightningMessage}. */
77       readonly glow?: number;
78       /** Rate at which the pattern or motion repeats. See {@link LightningMessage}. */
79       readonly frequency?: number;
80     };
81 function options(o: LightningOptions) {
82   if (
83     o.edge !== undefined &&
84     !["top", "right", "bottom", "left"].includes(o.edge)
85   )
86     throw new TypeError("Unknown lightning edge.");
87   return {
88     ...electricOptions(o),
89     positive: point(o.positive ?? { x: 0.2, y: 0.5 }),
90     negative: point(o.negative ?? { x: 0.8, y: 0.5 }),
91     edge: o.edge,
92     active: o.active ?? true,
93     frequency: range(o.frequency ?? 15, 1, 30, "Frequency"),
94     contactCore: o.contactCore ?? false,
95   };
96 }
97 type Connection = ElectricConnection;
98 interface State {
99   kernel: ElectricMemory;
100   config: ReturnType<typeof options>;
101   inputKey: string;
102   time: number;
103   paused: boolean;
104   connections: Map<string, Connection>;
105 }
106 function salt(id: string) {
107   let n = 0;
108   for (let i = 0; i < id.length; i++)
109     n = (Math.imul(n, 31) + id.charCodeAt(i)) | 0;
110   return n;
111 }
112 const recipe = /* @__PURE__ */ defineTexture<
113   LightningOptions,
114   State,
115   LightningMessage
116 >({
117   defaultPlacement: { mode: "stretch" },
118   create(context, input) {
119     if (input.active !== false) context.requestFrame();
120     const config = options(input);
121     return {
122       kernel: new ElectricMemory(wasmModule()),
123       config,
124       inputKey: JSON.stringify(input),
125       time: 0,
126       paused: false,
127       connections: new Map(),
128     };
129   },
130   update(s, input, context) {
131     const key = JSON.stringify(input);
132     if (key === s.inputKey) return;
133     const next = options(input);
134     if (next.seed !== s.config.seed) {
135       s.time = 0;
136       s.connections.clear();
137       s.kernel.clearConnections();
138     }
139     s.config = next;
140     s.inputKey = key;
141     context.invalidate();
142     if (!s.paused && (next.active || s.connections.size))
143       context.requestFrame();
144   },
145   receive(s, m, context) {
146     switch (m.type) {
147       case "pause":
148         s.paused = m.paused;
149         break;
150       case "reset":
151         s.config.seed =
152           m.seed === undefined ? s.config.seed : validateSeed(m.seed);
153         s.time = 0;
154         s.connections.clear();
155         s.kernel.clearConnections();
156         break;
157       case "configure":
158         s.config = options({ ...s.config, ...m });
159         break;
160       case "connect": {
161         if (typeof m.id !== "string" || m.id.length > 128)
162           throw new RangeError(
163             "Connection id must be a string of at most 128 characters.",
164           );
165         const positive = point(m.positive),
166           negative = point(m.negative),
167           old = s.connections.get(m.id);
168         if (old) {
169           old.positive = positive;
170           old.negative = negative;
171           old.active = true;
172           old.strength = 1;
173         } else if (s.connections.size < 24)
174           s.connections.set(
175             m.id,
176             Object.assign(s.kernel.connection(), {
177               positive,
178               negative,
179               strength: 1,
180               active: true,
181               salt: salt(m.id),
182             }),
183           );
184         break;
185       }
186       case "disconnect": {
187         const old = s.connections.get(m.id);
188         if (old) old.active = false;
189         break;
190       }
191       default:
192         throw new TypeError("Unknown lightning message.");
193     }
194     context.invalidate();
195     if (!s.paused && (s.config.active || s.connections.size))
196       context.requestFrame();
197   },
198   advance(s, frame, context) {
199     if (s.paused) return;
200     const dt = Math.min(50, frame.delta) / 1000;
201     s.time += dt;
202     s.kernel.advanceLightning(dt);
203     for (const [id, c] of s.connections) {
204       if (c.strength < 0.005) {
205         c.release();
206         s.connections.delete(id);
207       }
208     }
209     context.invalidate();
210     if (s.config.active || s.connections.size) context.requestFrame();
211   },
212   rasterize(s, context) {
213     s.kernel.lightning(s.config, s.time, s.connections.values());
214     s.kernel.draw(context, s.config.glow);
215   },
216   dispose(s) {
217     s.connections.clear();
218     s.kernel.dispose();
219   },
220 });
221 /**
222  * Persistent branching arcs between artistic positive/negative points.
223  *
224  * @param config - Lightning geometry, timing, and appearance settings. See
225  * {@link LightningOptions} .
226  * @returns A lightning texture recipe for useTexture.
227  *
228  * @see {@link LightningOptions}
229  */
230 export function lightning(config: LightningOptions = {}) {
231   return recipe(config);
232 }
233
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.