melonjs 19.9.0 → 20.0.0

package/build/video/webgl/buffer/retained_geometry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retained_geometry.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/buffer/retained_geometry.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;GAgBG;AACH;IACC;;;;;OAKG;IACH,gBALW,sBAAsB,cACtB,MAAM,EAAE,UACR,MAAM,6BA+DhB;IA3DA,2BAAY;IACZ,qBAA4B;IAC5B,eAAoB;IACpB,0BAAsC;IAEtC;;;OAGG;IACH,cAFU,WAAW,CAEgB;IAErC;;;OAGG;IACH,eAFU,WAAW,CAEiB;IAEtC;;;;;OAKG;IACH,WAFU,MAAM,CAEkB;IAElC;;;OAGG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,iBAFU,MAAM,CAES;IAYzB;;;OAGG;IACH,aAFU,gBAAgB,CAQxB;IAGH;;;;;;;OAOG;IACH,mBALW,YAAY,cACZ,MAAM,WACN,WAAW,GAAC,WAAW,GAAC,MAAM,EAAE,WAChC,MAAM,QAsChB;IAED;;OAEG;IACH,aAEC;IAED;;;OAGG;IACH,gBAwBC;CACD;6BA1K4B,kBAAkB"}

package/build/video/webgl/buffer/uniformblock.d.ts

@@ -0,0 +1,81 @@
+/**
+ * A uniform buffer bound to a named block in one or more shader programs.
+ *
+ * Uniform arrays are charged against `MAX_FRAGMENT_UNIFORM_VECTORS`, a
+ * driver-reported budget that is small on weak devices. A uniform buffer is
+ * charged against `MAX_UNIFORM_BLOCK_SIZE` instead — guaranteed at least
+ * 16 KB, typically 64 KB — so bulk per-frame data stops competing with
+ * everything else the shader declares.
+ *
+ * Data is staged in a `Float32Array` and uploaded with `bufferSubData`, so
+ * only the live prefix crosses the bus. Uploads are skipped entirely when the
+ * staged bytes have not changed, which preserves the property the uniform
+ * cache gives today: a scene whose lights are static costs nothing per frame.
+ *
+ * ## Context loss
+ *
+ * A block binding is program state, not buffer state, and every program is
+ * recompiled on restore — so the binding has to be re-established afterwards
+ * or the shader reads an unbound block and renders black. Callers re-bind
+ * lazily, whenever the program they last bound is no longer the current one;
+ * that covers a context restore without anyone subscribing to an event. The
+ * buffer itself needs no recovery hook — the renderer re-runs each batcher's
+ * `init()` on restore, which releases this block and builds a new one.
+ * @ignore
+ */
+export default class UniformBlock {
+    /**
+     * @param {WebGL2RenderingContext} gl - the rendering context
+     * @param {number} floats - capacity in floats
+     * @param {number} bindingPoint - the indexed binding point to occupy
+     */
+    constructor(gl: WebGL2RenderingContext, floats: number, bindingPoint: number);
+    gl: WebGL2RenderingContext;
+    /**
+     * staging buffer; callers write into this then call `upload`
+     * @type {Float32Array}
+     */
+    data: Float32Array;
+    /**
+     * mirror of what was last uploaded, so an unchanged frame can skip the
+     * `bufferSubData` entirely
+     * @type {Float32Array}
+     */
+    _uploaded: Float32Array;
+    /** nothing has been uploaded yet, so the mirror is not yet valid */
+    _everUploaded: boolean;
+    /** live length of the last upload; -1 until there has been one */
+    _uploadedLength: number;
+    /** @type {number} */
+    bindingPoint: number;
+    /** @type {WebGLBuffer|null} */
+    buffer: WebGLBuffer | null;
+    /**
+     * Point a program's named block at this buffer's binding point.
+     *
+     * Safe to call repeatedly — after a context restore the program is a new
+     * object and must be re-bound, and there is no way to ask whether it
+     * already was.
+     * @param {WebGLProgram} program - the linked program
+     * @param {string} blockName - the block's name in GLSL
+     * @returns {boolean} `false` when the program does not declare the block
+     */
+    bindTo(program: WebGLProgram, blockName: string): boolean;
+    /**
+     * Upload the first `floats` entries of {@link UniformBlock#data}.
+     *
+     * Compares against the previous upload first and does nothing when the
+     * bytes are identical. Uniform writes are already skipped when unchanged
+     * (`utils/uniforms.js`), so uploading unconditionally here would make a
+     * static scene more expensive than it was before the buffer existed.
+     * @param {number} floats - how many floats of the staging buffer are live
+     * @returns {boolean} whether anything was actually sent to the GPU
+     */
+    upload(floats: number): boolean;
+    /**
+     * Release the GL buffer. Safe to call twice, and on a lost context.
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=uniformblock.d.ts.map

package/build/video/webgl/buffer/uniformblock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uniformblock.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/buffer/uniformblock.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH;IACC;;;;OAIG;IACH,gBAJW,sBAAsB,UACtB,MAAM,gBACN,MAAM,EAkChB;IA/BA,2BAAY;IAEZ;;;OAGG;IACH,MAFU,YAAY,CAEc;IAEpC;;;;OAIG;IACH,WAFU,YAAY,CAEmB;IAEzC,oEAAoE;IACpE,uBAA0B;IAE1B,kEAAkE;IAClE,wBAAyB;IAEzB,qBAAqB;IACrB,cADW,MAAM,CACe;IAEhC,+BAA+B;IAC/B,QADW,WAAW,GAAC,IAAI,CACI;IAQhC;;;;;;;;;OASG;IACH,gBAJW,YAAY,aACZ,MAAM,GACJ,OAAO,CAanB;IAED;;;;;;;;;OASG;IACH,eAHW,MAAM,GACJ,OAAO,CAmBnB;IAoBD;;OAEG;IACH,gBAYC;;CACD"}

package/build/video/webgl/buffer/vertexstate.d.ts

@@ -0,0 +1,101 @@
+/**
+ * A WebGL Vertex State — a Vertex Array Object owning a frozen vertex
+ * buffer layout: one `vertexAttribPointer` / `enableVertexAttribArray` per
+ * attribute against a given vertex buffer, plus the ELEMENT_ARRAY_BUFFER
+ * binding when the geometry is indexed.
+ *
+ * This is the engine's `GPUVertexState` analogue, and the layout it is built
+ * from is a `GPUVertexBufferLayout[]`: a list of buffer groups, each with its
+ * own buffer, `arrayStride` and `stepMode`. Attributes in a `"vertex"` group
+ * advance once per vertex (the ordinary case); attributes in an
+ * `"instance"` group advance once per *instance*, which is what
+ * `drawElementsInstanced` reads to stamp out N copies of one geometry.
+ * The layout is immutable once built, exactly like a vertex layout baked
+ * into a render pipeline.
+ *
+ * Attribute divisors are vertex-array state, so a fresh VAO starts with every
+ * divisor at 0 and `build()` creates one each time — an instanced layout can
+ * therefore never leak its divisors into an unrelated vertex state, and the
+ * single-buffer path issues no `vertexAttribDivisor` calls at all.
+ *
+ * Every method that mutates GL binding state saves and restores the live
+ * bindings itself, so building or rebuilding one vertex state can never
+ * disturb whichever one is mid-frame. Callers never touch
+ * `bindVertexArray` directly.
+ * @ignore
+ */
+export default class WebGLVertexState {
+    /**
+     * Accepts either shape — the single-buffer one (`attributes` + `stride` +
+     * `buffer`) or a list of buffer groups (`buffers`). They are equivalent;
+     * the former is the latter with one `"vertex"` group.
+     * @param {WebGL2RenderingContext} gl - the WebGL context
+     * @param {object} descriptor - the vertex layout to realize
+     * @param {object[]} [descriptor.attributes] - attribute definitions (`name`, `size`, `type`, `normalized`, `offset`)
+     * @param {number} [descriptor.stride] - size of a single vertex in bytes (`arrayStride`)
+     * @param {WebGLBuffer} [descriptor.buffer] - the vertex buffer the attribute pointers read from
+     * @param {object[]} [descriptor.buffers] - buffer groups, each `{buffer, stride, attributes, stepMode}` where `stepMode` is `"vertex"` (default) or `"instance"`
+     * @param {Function} descriptor.resolveLocation - maps an attribute name to its shader location (`-1` when absent)
+     * @param {WebGLIndexBuffer} [descriptor.indexBuffer] - index buffer to capture, for indexed geometry
+     */
+    constructor(gl: WebGL2RenderingContext, descriptor: {
+        attributes?: object[] | undefined;
+        stride?: number | undefined;
+        buffer?: WebGLBuffer | undefined;
+        buffers?: object[] | undefined;
+        resolveLocation: Function;
+        indexBuffer?: any;
+    });
+    gl: WebGL2RenderingContext;
+    descriptor: {
+        attributes?: object[] | undefined;
+        stride?: number | undefined;
+        buffer?: WebGLBuffer | undefined;
+        buffers?: object[] | undefined;
+        resolveLocation: Function;
+        indexBuffer?: WebGLIndexBuffer;
+    };
+    /**
+     * the underlying GL vertex array object
+     * @type {WebGLVertexArrayObject}
+     */
+    handle: WebGLVertexArrayObject;
+    /**
+     * (Re)build the vertex array object from this state's descriptor,
+     * replacing any previous one. Called on construction and from every
+     * buffer-recreation path — a vertex state referencing a deleted buffer
+     * keeps it alive per the GL spec and draws stale data.
+     * @param {object} [changes] - descriptor fields to replace first (e.g. recreated `buffer` / `buffers` / `indexBuffer`)
+     */
+    build(changes?: object): void;
+    /**
+     * Capture an ELEMENT_ARRAY_BUFFER binding into this vertex state.
+     * Used when an index buffer is (re)created after the state was built —
+     * the quad batchers' static pattern buffer — since that binding is
+     * vertex-array state and would otherwise land in whichever state
+     * happens to be bound.
+     * @param {WebGLIndexBuffer} indexBuffer - the index buffer to capture
+     * @param {Function} [fill] - optional work to run with this state bound (buffer creation/upload)
+     */
+    captureIndexBuffer(indexBuffer: WebGLIndexBuffer, fill?: Function): void;
+    /**
+     * Make this vertex state current. One call restores the entire frozen
+     * layout — the WebGL analogue of `setPipeline` + `setVertexBuffer` +
+     * `setIndexBuffer`.
+     */
+    bind(): void;
+    /**
+     * Delete the underlying vertex array object, if any. Idempotent, and
+     * safe on a lost context: deleting an object belonging to a lost
+     * context would queue `INVALID_OPERATION` (deletion counts as *using*
+     * it — only the `is*` queries are exempt), so probe first.
+     */
+    release(): void;
+    /**
+     * Release the vertex array object. The vertex state must not be used
+     * after calling destroy.
+     */
+    destroy(): void;
+    #private;
+}
+//# sourceMappingURL=vertexstate.d.ts.map

package/build/video/webgl/buffer/vertexstate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vertexstate.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/buffer/vertexstate.js"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IACC;;;;;;;;;;;;OAYG;IACH,gBATW,sBAAsB,cAE9B;QAA8B,UAAU;QACZ,MAAM;QACD,MAAM;QACT,OAAO;QACR,eAAe;QACN,WAAW;KACnD,EAUA;IARA,2BAAY;IACZ;;;;;;sBAJU,gBAAgB;MAIE;IAC5B;;;OAGG;IACH,QAFU,sBAAsB,CAEd;IAyBnB;;;;;;OAMG;IACH,gBAFW,MAAM,QA4EhB;IAED;;;;;;;;OAQG;IACH,gCAHW,gBAAgB,yBAa1B;IAED;;;;OAIG;IACH,aAEC;IAED;;;;;OAKG;IACH,gBAOC;IAED;;;OAGG;IACH,gBAGC;;CACD"}

package/build/video/webgl/glshader.d.ts

@@ -1,12 +1,40 @@
 /**
- * a base GL Shader object
+ * a complete custom shader program. Historically a WebGL-only GLSL
+ * program (the class keeps its name for compatibility), since 20.0 it can
+ * carry one realization per GPU backend — a `{vertex, fragment}` GLSL
+ * pair for the WebGL renderer and/or a complete `wgsl` module for the
+ * WebGPU renderer — mirroring how {@link ShaderEffect} carries one body
+ * per shading language. The {@link GLShader#isWebGL} / {@link GLShader#isWebGPU}
+ * flags report which realizations exist; a renderer hosts the one it
+ * speaks and anything else degrades to the built-in shading (never fatal).
+ *
+ * ### The WGSL module contract (custom `Mesh` shaders)
+ *
+ * The `wgsl` source is a complete module hosted by the mesh batchers:
+ * entry points must be named **`vertex_main`** (`@vertex`) and
+ * **`fragment_main`** (`@fragment`), over the frozen mesh vertex layout —
+ * `@location(0) aVertex : vec3f`, `@location(1) aRegion : vec2f`,
+ * `@location(2) aColor : vec4f`, plus `@location(3) aNormal : vec3f` on
+ * the 48-byte `lit` layout. Bind groups (declare only what is read):
+ * group 0 `FrameUniforms {projection : mat4x4<f32>, lineWidth : f32}`,
+ * group 1 the mesh texture + sampler, group 2 the `Light3dBlock` (lit
+ * host only), group 3 `MeshUniforms {model, view : mat4x4<f32>,
+ * tint, params, emissive : vec4f}` (`params.x` = alpha cutout). The
+ * vertex stage owns the projection (`projection * view * model`) and must
+ * remap the GL-convention clip z: `(clip.z + clip.w) * 0.5`. WGSL
+ * validation is asynchronous and never throws — a failing module logs its
+ * errors once and the mesh falls back to the built-in shading.
  * @category Rendering
  */
 export default class GLShader {
     /**
-     * @param {WebGLRenderingContext} gl - the current WebGL rendering context
-     * @param {string} vertex - a string containing the GLSL source code to set
-     * @param {string} fragment - a string containing the GLSL source code to set
+     * @param {WebGLRenderingContext} [gl] - the current WebGL rendering
+     * context (`renderer.gl` — undefined on non-WebGL renderers, which
+     * simply skips the GLSL realization)
+     * @param {string|object} vertex - a string containing the GLSL vertex
+     * source, OR a sources object `{vertex, fragment, wgsl, precision,
+     * label}` carrying one realization per backend (any omittable)
+     * @param {string} [fragment] - a string containing the GLSL fragment source
      * @param {string} [precision=auto detected] - float precision ('lowp', 'mediump' or 'highp').
      * @see https://developer.mozilla.org/en-US/docs/Games/Techniques/3D_on_the_web/GLSL_Shaders
      * @example
@@ -29,13 +57,51 @@ export default class GLShader {
      *  )
      * // use the shader
      * myShader.bind();
+     * @example
+     * // a dual-backend custom mesh shader: the same object hosts on
+     * // whichever GPU renderer is active (gl is undefined on WebGPU)
+     * myMesh.shader = new me.GLShader(app.renderer.gl, {
+     *     vertex: toonVertexGLSL,
+     *     fragment: toonFragmentGLSL,
+     *     wgsl: toonModuleWGSL,
+     * });
      */
-    constructor(gl: WebGLRenderingContext, vertex: string, fragment: string, precision?: string);
+    constructor(gl?: WebGLRenderingContext, vertex: string | object, fragment?: string, precision?: string);
     /**
      * the active gl rendering context
      * @type {WebGLRenderingContext}
      */
     gl: WebGLRenderingContext;
+    /**
+     * `true` when this shader carries a WebGL realization: a
+     * `{vertex, fragment}` GLSL pair compiled against a live context.
+     * @type {boolean}
+     * @readonly
+     */
+    readonly isWebGL: boolean;
+    /**
+     * `true` when this shader carries a WebGPU realization: a complete
+     * `wgsl` module (see the class docs for the module contract).
+     * @type {boolean}
+     * @readonly
+     */
+    readonly isWebGPU: boolean;
+    /**
+     * the complete WGSL module source, when {@link GLShader#isWebGPU}
+     * @type {string|undefined}
+     */
+    wgsl: string | undefined;
+    /**
+     * optional debug label, carried onto the GPU shader module (shows
+     * up in browser GPU error messages and profilers)
+     * @type {string|undefined}
+     */
+    label: string | undefined;
+    wgslValid: boolean;
+    _wgslRegistrations: {
+        epoch: number;
+        keys: Map<any, any>;
+    };
     /**
      * `true` once {@link destroy} has been called. After this flag is
      * `true`, every method on the shader is a silent no-op — callers
@@ -68,8 +134,8 @@ export default class GLShader {
      * @readonly
      */
     readonly suspended: boolean;
-    _sourceVertex: string;
-    _sourceFragment: string;
+    _sourceVertex: string | object;
+    _sourceFragment: string | undefined;
     _precision: string | undefined;
     _uniformCache: any;
     program: WebGLProgram;
@@ -118,7 +184,15 @@ export default class GLShader {
      */
     setUniform(name: string, value: object | Float32Array): void;
     /**
-     * activate the given vertex attribute for this shader
+     * activate the given vertex attribute for this shader.
+     *
+     * Note: since 20.0 the engine no longer calls this per frame — each
+     * {@link WebGLBatcher} captures its attribute layout once into an immutable
+     * vertex-state object (VAO) at init (see `WebGLBatcher.createVertexState`).
+     * Kept public for custom callers managing their own vertex setup.
+     * Custom shaders hosted by a built-in batcher must declare that
+     * batcher's attributes first, in layout order — attribute locations
+     * are bound in declaration order and the vertex state is frozen.
      * @param {WebGLRenderingContext} gl - the current WebGL rendering context
      * @param {object[]} attributes - an array of vertex attributes
      * @param {number} stride - the size of a single vertex in bytes
@@ -142,6 +216,25 @@ export default class GLShader {
      * @returns {GLShader} a new, caller-owned shader (`shared === false`)
      */
     clone(): GLShader;
+    /**
+     * Register this shader's WGSL module as a pipeline family for one
+     * hosting mesh batcher, against that host's positional group-layout
+     * list and frozen vertex layout. Registered once per host per device
+     * generation; the module text is namespaced by the host key so the
+     * same shader yields distinct families (distinct pipeline layouts) on
+     * the unlit and lit hosts. Asynchronous WGSL validation errors flip
+     * {@link GLShader#wgslValid} and the host falls back to its built-in
+     * shading (warn-and-degrade, never fatal).
+     * @param {object} cache - the WebGPU renderer's pipeline cache
+     * @param {string} host - the hosting family's vertex-layout key
+     * @param {GPUBindGroupLayout[]} bindGroupLayouts - the host's group list
+     * @param {string} vertexLayoutKey - the host's registered vertex layout
+     * @returns {string|null} the family key to pass to the pipeline cache's
+     *   `get`, or null when the module failed validation on this device
+     *   generation (the host then uses its built-in family)
+     * @ignore
+     */
+    registerWGSL(cache: object, host: string, bindGroupLayouts: GPUBindGroupLayout[], vertexLayoutKey: string): string | null;
     /**
      * destroy this shader objects resources (program, attributes, uniforms).
      * Idempotent — calling destroy twice (or after a context-lost suspend)

package/build/video/webgl/glshader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glshader.d.ts","sourceRoot":"","sources":["../../../src/video/webgl/glshader.js"],"names":[],"mappings":"AAYA;;;GAGG;AACH;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,gBA1BW,qBAAqB,UACrB,MAAM,YACN,MAAM,cACN,MAAM,EAqFhB;IA7DA;;;OAGG;IACH,IAFU,qBAAqB,CAEnB;IAEZ;;;;;;;OAOG;IACH,oBAHU,OAAO,CAGK;IAEtB;;;;;;;;;OASG;IACH,QAHU,OAAO,CAGE;IAEnB;;;;;;;;;;OAUG;IACH,oBAHU,OAAO,CAGK;IAGtB,sBAA2B;IAC3B,wBAA+B;IAC/B,+BAA2B;IAG3B,mBAAwC;IAKvC,sBAAmB;IACnB,iBAAoB;IACpB,qBAAsB;IASxB;;;;;;OAMG;IACH,iBA0CC;IAzCA,YAGC;IACD,cAGC;IAoCF;;;;;OAKG;IACH,uBAgBC;IAED;;;;;OAKG;IACH,2BAMC;IAED;;OAEG;IACH,aAKC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,KAAK,CAYjB;IAED;;;;;;OAMG;IACH,iBALW,MAAM,SACN,MAAM,GAAC,YAAY,QA0C7B;IAED;;;;;OAKG;IACH,wBAJW,qBAAqB,cACrB,MAAM,EAAE,UACR,MAAM,QAmBhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,SAFa,QAAQ,CAyBpB;IAED;;;;;OAKG;IACH,gBA2BC;CACD"}
+{"version":3,"file":"glshader.d.ts","sourceRoot":"","sources":["../../../src/video/webgl/glshader.js"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,iBAtCW,qBAAqB,UAGrB,MAAM,GAAC,MAAM,aAGb,MAAM,cACN,MAAM,EAiKhB;IArHA;;;OAGG;IACH,IAFU,qBAAqB,CAEnB;IAEZ;;;;;OAKG;IACH,kBAHU,OAAO,CAIwD;IAEzE;;;;;OAKG;IACH,mBAHU,OAAO,CAGuB;IAExC;;;OAGG;IACH,MAFU,MAAM,GAAC,SAAS,CAEV;IAEhB;;;;OAIG;IACH,OAFU,MAAM,GAAC,SAAS,CAER;IAIlB,mBAAqB;IAKrB;;;MAAwD;IAWxD;;;;;;;OAOG;IACH,oBAHU,OAAO,CAGK;IAEtB;;;;;;;;;OASG;IACH,QAHU,OAAO,CAGE;IAEnB;;;;;;;;;;OAUG;IACH,oBAHU,OAAO,CAGK;IAGtB,+BAA2B;IAC3B,oCAA+B;IAC/B,+BAA2B;IAG3B,mBAAwC;IAMtC,sBAAmB;IACnB,iBAAoB;IACpB,qBAAsB;IAgBzB;;;;;;OAMG;IACH,iBA0CC;IAzCA,YAGC;IACD,cAGC;IAoCF;;;;;OAKG;IACH,uBAgBC;IAED;;;;;OAKG;IACH,2BAMC;IAED;;OAEG;IACH,aAMC;IAED;;;;OAIG;IACH,wBAHW,MAAM,GACJ,KAAK,CAcjB;IAED;;;;;;OAMG;IACH,iBALW,MAAM,SACN,MAAM,GAAC,YAAY,QA4C7B;IAED;;;;;;;;;;;;;OAaG;IACH,wBAJW,qBAAqB,cACrB,MAAM,EAAE,UACR,MAAM,QAmBhB;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,SAFa,QAAQ,CA8BpB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,oBATW,MAAM,QACN,MAAM,oBACN,kBAAkB,EAAE,mBACpB,MAAM,GACJ,MAAM,GAAC,IAAI,CAgFvB;IAED;;;;;OAKG;IACH,gBAkCC;CACD"}

package/build/video/webgl/lighting/constants.d.ts

@@ -1,13 +1,25 @@
 /**
- * Constants shared between the lit fragment shader (`multitexture-lit.js`),
- * the lit batcher (`LitQuadBatcher`), and the uniform packer (`pack.ts`).
- * Kept in a tiny standalone module so the three consumers don't depend on
- * each other transitively for a single integer.
+ * Constants shared between the lit fragment shaders
+ * (`multitexture-lit.js`, `mesh-lit.frag`), the lit batchers
+ * (`LitQuadBatcher`, `LitMeshBatcher`), the uniform packers (`pack.ts`,
+ * `pack3d.ts`) and the std140 writer (`std140.ts`). Kept in a tiny
+ * standalone module so the consumers don't depend on each other
+ * transitively for a couple of integers.
  */
 /**
- * Maximum number of `Light2d` instances the lit fragment shader supports
- * concurrently per draw call. Lights past this index are ignored. Sized
- * to keep the GLSL uniform arrays comfortably within WebGL1 limits.
+ * Maximum number of lights the lit fragment shaders support concurrently
+ * per draw call. Lights past this index are ignored.
+ *
+ * The data travels in a uniform buffer, so this is an allocation rather
+ * than a compatibility question: 32 lights cost 1056 bytes against
+ * `MAX_UNIFORM_BLOCK_SIZE`, which is at least 16 KB everywhere. Uniform
+ * _arrays_, the previous transport, are charged against the much smaller
+ * `MAX_FRAGMENT_UNIFORM_VECTORS` — shared with every other uniform the
+ * shader declares — which is what held this at 8.
+ *
+ * It is not a statement about what a device can afford to _shade_: the
+ * fragment loop still runs once per pixel per live light. Unused capacity
+ * is free — the loop bound is the live count — but filling it is not.
  */
-export declare const MAX_LIGHTS = 8;
+export declare const MAX_LIGHTS = 32;
 //# sourceMappingURL=constants.d.ts.map

package/build/video/webgl/lighting/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/constants.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,eAAO,MAAM,UAAU,IAAI,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,KAAK,CAAC"}

package/build/video/webgl/lighting/pack.d.ts

@@ -58,7 +58,7 @@ interface ColorLike {
  * the lit fragment's `lightPos - vWorldPos` math lines up with the
  * camera's view.
  *
- * Lights past `MAX_LIGHTS` (8) are silently dropped. Unused slots are
+ * Lights past `MAX_LIGHTS` are silently dropped. Unused slots are
  * zero-filled so stale data from a previous frame can't leak into the
  * shader.
  *

package/build/video/webgl/lighting/pack3d.d.ts

@@ -4,26 +4,42 @@ import type { Light3d } from "../../../lighting/light3d.ts";
  * @ignore
  */
 export interface PackedMeshLighting {
-    /** number of active directional lights, clamped to `MAX_LIGHTS`. */
+    /** number of active shaded lights, clamped to `MAX_LIGHTS`. */
     count: number;
-    /** `MAX_LIGHTS × 3` surface→light directions (already negated, normalized). */
-    directions: Float32Array;
-    /** `MAX_LIGHTS × 3` directional light colors premultiplied by intensity. */
-    colors: Float32Array;
+    /**
+     * `MAX_LIGHTS × 4` — `[x, y, z, range]` per light; `range` is `-1` for
+     * directional lights (the shader's type sentinel).
+     */
+    posRange: Float32Array;
+    /**
+     * `MAX_LIGHTS × 4` — `[dx, dy, dz, cos(outerConeAngle)]` per light;
+     * `cosOuter` is `-1` when no cone applies (directional carries the
+     * pre-negated surface→light vector, point carries no direction).
+     */
+    dirCone: Float32Array;
+    /**
+     * `MAX_LIGHTS × 4` — `[r, g, b, cos(innerConeAngle)]` per light,
+     * color premultiplied by intensity.
+     */
+    colorInner: Float32Array;
     /** the summed ambient color (RGB, 0..1+). */
     ambient: Float32Array;
 }
 /**
  * Pack an iterable of {@link Light3d} (e.g. the active `Stage`'s 3D-light set)
- * into the uniform arrays the mesh-lit shader reads:
- * - **directional** lights contribute a surface→light direction (negated travel
- *   direction, normalized) + a color premultiplied by intensity, up to
- *   `MAX_LIGHTS`. Re-normalized here so a direction mutated at runtime without
+ * into the std140-ready arrays the mesh-lit shader reads:
+ * - **directional** lights contribute a surface→light direction (negated
+ *   travel direction, normalized) + a color premultiplied by intensity.
+ *   Re-normalized here so a direction mutated at runtime without
  *   re-normalizing still shades correctly.
+ * - **point** lights contribute their world position, `range` (quadratic
+ *   falloff over the range — the Light2d model) and premultiplied color.
+ * - **spot** lights add their travel direction and the cone cosines
+ *   (`innerConeAngle` clamped just inside `outerConeAngle`, so the
+ *   smoothstep denominator never collapses).
  * - **ambient** lights are summed into a single flat ambient color.
  *
- * Other types (`"point"`) are skipped — not shaded yet. The same buffers are
- * returned each call (overwritten in place).
+ * The same buffers are returned each call (overwritten in place).
  * @param lights - iterable of lights, or `null`/`undefined` (treated as empty)
  * @returns the packed lighting (reused instance)
  * @ignore

package/build/video/webgl/lighting/pack3d.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack3d.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/pack3d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAG5D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,oEAAoE;IACpE,KAAK,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,UAAU,EAAE,YAAY,CAAC;IACzB,4EAA4E;IAC5E,MAAM,EAAE,YAAY,CAAC;IACrB,6CAA6C;IAC7C,OAAO,EAAE,YAAY,CAAC;CACtB;AAcD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAC1C,kBAAkB,CAuCpB"}
+{"version":3,"file":"pack3d.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/pack3d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,8BAA8B,CAAC;AAG5D;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,QAAQ,EAAE,YAAY,CAAC;IACvB;;;;OAIG;IACH,OAAO,EAAE,YAAY,CAAC;IACtB;;;OAGG;IACH,UAAU,EAAE,YAAY,CAAC;IACzB,6CAA6C;IAC7C,OAAO,EAAE,YAAY,CAAC;CACtB;AAgBD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,GAAG,SAAS,GAC1C,kBAAkB,CAuFpB"}

package/build/video/webgl/lighting/std140.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Header, occupying two `vec4`s before the light array begins.
+ *
+ * ```glsl
+ * int  count;     // offset 0
+ * vec3 ambient;   // offset 16 — a vec3 aligns to 16, so it cannot share
+ * ```
+ *
+ * `count` is written as a float and read back with `int(...)` in the
+ * shader. Declaring it `int` in the block would be tidier, but mixing int
+ * and float members means the staging buffer can no longer be a single
+ * `Float32Array` view, and the cast is free on every GPU that matters.
+ * @ignore
+ */
+export declare const HEADER_FLOATS: number;
+/**
+ * floats occupied by one light: two `vec4`s
+ * @ignore
+ */
+export declare const LIGHT_FLOATS: number;
+/**
+ * total floats in a light block, header included
+ * @ignore
+ */
+export declare const BLOCK_FLOATS: number;
+/**
+ * total bytes in a light block
+ * @ignore
+ */
+export declare const BLOCK_BYTES: number;
+/**
+ * Lay out 2D (`Light2d`) data.
+ *
+ * ```glsl
+ * struct Light2dData {
+ *   vec4 posRadiusIntensity;  // x, y, radius, intensity
+ *   vec4 colorHeight;         // r, g, b, lightHeight
+ * };
+ * ```
+ * @param out - staging buffer, at least `BLOCK_FLOATS` long
+ * @param packed - what {@link packLights} produced
+ * @param packed.count - number of live lights, clamped to `MAX_LIGHTS`
+ * @param packed.positions - `[x, y, radius, intensity]` per light
+ * @param packed.colors - `[r, g, b]` per light, 0..1 per channel
+ * @param packed.heights - per-light height; absent means 0
+ * @param packed.ambient - `[r, g, b]` ambient floor; absent means black
+ * @returns how many floats of `out` are live, for a partial upload
+ * @ignore
+ */
+export declare function writeLight2dBlock(out: Float32Array, packed: {
+    count: number;
+    positions: Float32Array;
+    colors: Float32Array;
+    heights?: Float32Array;
+    ambient?: ArrayLike<number>;
+}): number;
+/**
+ * floats occupied by one 3D light: three `vec4`s. The 3D block grew from
+ * two when point/spot shading landed (#1536) — a spot light needs position
+ * + range + direction + both cone cosines + color, which cannot fold into
+ * two vec4s' padding. The 2D block keeps its two-vec4 stride.
+ * @ignore
+ */
+export declare const LIGHT3D_FLOATS: number;
+/**
+ * total floats in a 3D light block, header included
+ * @ignore
+ */
+export declare const BLOCK3D_FLOATS: number;
+/**
+ * total bytes in a 3D light block
+ * @ignore
+ */
+export declare const BLOCK3D_BYTES: number;
+/**
+ * Lay out 3D (`Light3d`) data.
+ *
+ * ```glsl
+ * struct Light3dData {
+ *   vec4 posRange;    // x, y, z = world position · w = range;
+ *                     //   w < 0 marks a DIRECTIONAL light (xyz unused)
+ *   vec4 dirCone;     // x, y, z = direction · w = cos(outerConeAngle);
+ *                     //   w = -1 marks "no cone" (directional dir is the
+ *                     //   pre-negated surface→light vector; a point light
+ *                     //   carries no direction)
+ *   vec4 colorInner;  // r, g, b = color × intensity · w = cos(innerConeAngle)
+ * };
+ * ```
+ *
+ * The type is inferred from the sentinels rather than a tag slot:
+ * `posRange.w < 0` → directional; otherwise positional, with a cone
+ * applied when `dirCone.w > -1`.
+ * @param out - staging buffer, at least `BLOCK3D_FLOATS` long
+ * @param packed - what {@link packMeshLights} produced
+ * @param packed.count - number of live lights, clamped to `MAX_LIGHTS`
+ * @param packed.posRange - `[x, y, z, range]` per light (range -1 for directional)
+ * @param packed.dirCone - `[dx, dy, dz, cosOuter]` per light (cosOuter -1 for none)
+ * @param packed.colorInner - `[r, g, b, cosInner]` per light
+ * @param packed.ambient - `[r, g, b]` ambient floor; absent means black
+ * @returns how many floats of `out` are live, for a partial upload
+ * @ignore
+ */
+export declare function writeLight3dBlock(out: Float32Array, packed: {
+    count: number;
+    posRange: Float32Array;
+    dirCone: Float32Array;
+    colorInner: Float32Array;
+    ambient?: ArrayLike<number>;
+}): number;
+//# sourceMappingURL=std140.d.ts.map

package/build/video/webgl/lighting/std140.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"std140.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/lighting/std140.ts"],"names":[],"mappings":"AAsCA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,aAAa,QAAW,CAAC;AAEtC;;;GAGG;AACH,eAAO,MAAM,YAAY,QAAW,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,YAAY,QAA4C,CAAC;AAEtE;;;GAGG;AACH,eAAO,MAAM,WAAW,QAAgD,CAAC;AA0BzE;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,YAAY,CAAC;IACxB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CAC5B,GACC,MAAM,CAkCR;AAED;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,QAAW,CAAC;AAEvC;;;GAGG;AACH,eAAO,MAAM,cAAc,QAA8C,CAAC;AAE1E;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAkD,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,iBAAiB,CAChC,GAAG,EAAE,YAAY,EACjB,MAAM,EAAE;IACP,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,YAAY,CAAC;IACvB,OAAO,EAAE,YAAY,CAAC;IACtB,UAAU,EAAE,YAAY,CAAC;IACzB,OAAO,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CAC5B,GACC,MAAM,CA4BR"}

package/build/video/webgl/shaders/multitexture-lit.d.ts

@@ -7,17 +7,21 @@
  * unlit fast path inside this same shader (sample color, multiply by
  * vertex color, return) so lit and unlit sprites can share the lit batch
  * when they coexist with active lights. The cost vs the truly-unlit
- * `QuadBatcher` shader is one varying read + one comparison per fragment.
+ * `QuadBatcher` shader is one interpolated read + one comparison per
+ * fragment.
  *
  * The light's "height above the sprite plane" is encoded as a small
  * fraction of the light's radius (default `0.075`) so that lights
  * exactly at a fragment's screen position don't produce degenerate
  * flat shading.
+ *
+ * GLSL ES 3.00, because the light data arrives in a uniform block and
+ * blocks do not exist in ES 1.00 (see #1552). The paired vertex shader
+ * `quad-multi-lit.vert` is on the same version — both stages of a program
+ * must agree.
  * @param {number} maxTextures - the number of color/normal texture units to support
  * @returns {string} GLSL fragment shader source
  * @ignore
  */
 export function buildLitMultiTextureFragment(maxTextures: number): string;
-export { MAX_LIGHTS };
-import { MAX_LIGHTS } from "../lighting/constants.ts";
 //# sourceMappingURL=multitexture-lit.d.ts.map

package/build/video/webgl/shaders/multitexture-lit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"multitexture-lit.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/shaders/multitexture-lit.js"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;GAkBG;AACH,0DAJW,MAAM,GACJ,MAAM,CAiFlB;;2BAjI0B,0BAA0B"}
+{"version":3,"file":"multitexture-lit.d.ts","sourceRoot":"","sources":["../../../../src/video/webgl/shaders/multitexture-lit.js"],"names":[],"mappings":"AA6BA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,0DAJW,MAAM,GACJ,MAAM,CAsGlB"}