@aethervtt/shard-sprite 0.0.1

package/dist/lighting-shaders.js

@@ -0,0 +1,267 @@
+const LIGHT2D_SHADERS = {
+  "shard::sprite::light2d::types": `
+const TILE_PIXELS: u32 = 16u;
+/** Per tile: a count, then up to 64 light indices. */
+const TILE_STRIDE: u32 = 65u;
+const TILE_MAX: u32 = 64u;
+/** Angles per shadow row. */
+const SHADOW_RES: u32 = 1024u;
+/** Coarse bins per row (min and max over 32 angles each). */
+const COARSE_RES: u32 = 32u;
+const COARSE_SPAN: f32 = 32.0;
+const TAU: f32 = 6.283185307179586;
+const PI: f32 = 3.141592653589793;
+
+struct Light2d {
+  pos: vec2f,
+  height: f32,
+  radius: f32,
+  /** Color \xD7 intensity. */
+  color: vec3f,
+  falloff: f32,
+  /** Spot direction (unit), cos of the inner and outer half-angles; points: cos_outer < -1. */
+  dir: vec2f,
+  cos_inner: f32,
+  cos_outer: f32,
+  /** Shadow row, or -1. */
+  row: i32,
+  softness: f32,
+  layers: u32,
+  /** 1 / radius\xB2. */
+  inv_r2: f32,
+}
+
+struct Lighting2dView {
+  /** Ambient \xD7 intensity (rgb), 0. */
+  ambient: vec4f,
+  /** Lights, tiles across, tiles down, shadowed lights. */
+  counts: vec4u,
+  /** Occluder segments, 0, 0, 0. */
+  extra: vec4u,
+}
+
+struct Segment2d {
+  a: vec2f,
+  b: vec2f,
+  /** How far light reaches into the occluder (added to the stored distance). */
+  penetration: f32,
+  layers: u32,
+  _pad0: u32,
+  _pad1: u32,
+}`,
+  "shard::sprite::light2d": `
+import shard::sprite::light2d::types::{ Light2d, Lighting2dView, TILE_PIXELS, TILE_STRIDE, TILE_MAX, SHADOW_RES, COARSE_RES, COARSE_SPAN, TAU, PI };
+
+@group(3) @binding(0) var<uniform> light_view: Lighting2dView;
+@group(3) @binding(1) var<storage, read> lights: array<Light2d>;
+@group(3) @binding(2) var<storage, read> light_tiles: array<u32>;
+@group(3) @binding(3) var<storage, read> shadow_map: array<u32>;
+/** Per row, per 32 angles: the nearest and farthest occluder distance. */
+@group(3) @binding(4) var<storage, read> shadow_coarse: array<vec2f>;
+
+/** Min and max over the coarse bin holding continuous bin coordinate x. */
+fn coarse_at(row: u32, x: f32) -> vec2f {
+  let n = i32(COARSE_RES);
+  let c = i32(floor(x / COARSE_SPAN));
+  return shadow_coarse[row * COARSE_RES + u32(((c % n) + n) % n)];
+}
+
+/** Nearest occluder distance (plus penetration) in angle bin k of a shadow row. */
+fn occluder_at(row: u32, k: i32) -> f32 {
+  let n = i32(SHADOW_RES);
+  let w = ((k % n) + n) % n;
+  return bitcast<f32>(shadow_map[row + u32(w)]);
+}
+
+/** A filtered depth test at continuous bin coordinate x: blends the two nearest bins' results. */
+fn lit_at(row: u32, x: f32, d: f32) -> f32 {
+  let k = floor(x - 0.5);
+  let a = select(0.0, 1.0, d <= occluder_at(row, i32(k)));
+  let b = select(0.0, 1.0, d <= occluder_at(row, i32(k) + 1));
+  return mix(a, b, x - 0.5 - k);
+}
+
+/**
+ * How lit a fragment d from the light is (0..1). Hard shadows take one tap. Soft ones search
+ * for blockers across the widest penumbra softness allows, then filter across a kernel whose width
+ * grows with softness \xD7 (d \u2212 blocker) / blocker, so penumbras widen away from the occluder.
+ */
+fn shadow2d(l: Light2d, d: f32, to_frag: vec2f) -> f32 {
+  let step = TAU / f32(SHADOW_RES);
+  let fb = (atan2(to_frag.y, to_frag.x) + PI) / step;
+  let row = u32(l.row) * SHADOW_RES;
+  if (l.softness <= 0.0) {
+    return select(0.0, 1.0, d <= occluder_at(row, i32(floor(fb))));
+  }
+  // Blocker search: 8 taps across the widest penumbra softness allows at this distance. The
+  // search window spans at most three coarse bins; their min and max settle "fully lit" and "in
+  // the umbra" without the taps, with the same answer the taps would give.
+  let search = min(l.softness / max(d, 1e-3) / step, 32.0);
+  let a = coarse_at(u32(l.row), fb - search);
+  let b = coarse_at(u32(l.row), fb);
+  let c = coarse_at(u32(l.row), fb + search);
+  if (d <= min(a.x, min(b.x, c.x))) { return 1.0; }
+  if (d > max(a.y, max(b.y, c.y))) { return 0.0; }
+  var blockers = 0.0;
+  var sum = 0.0;
+  for (var i = 0; i < 8; i++) {
+    let o = occluder_at(row, i32(floor(fb + (f32(i) / 7.0 * 2.0 - 1.0) * search)));
+    if (o < d) {
+      sum += o;
+      blockers += 1.0;
+    }
+  }
+  if (blockers == 0.0) { return 1.0; }
+  // Every tap blocked: in the umbra.
+  if (blockers == 8.0) { return 0.0; }
+  let blocker = sum / blockers;
+  let width = min(l.softness * (d - blocker) / max(blocker, 1e-3) / d / step, 32.0);
+  var lit = 0.0;
+  for (var i = 0; i < 24; i++) {
+    lit += lit_at(row, fb + (f32(i) / 23.0 * 2.0 - 1.0) * width, d);
+  }
+  return lit / 24.0;
+}
+
+/**
+ * Light reaching a fragment: ambient plus every light of its screen tile that reaches it, with
+ * smooth falloff, the spot cone, N\xB7L from the normal and the light's height (normal-mapped
+ * sprites only; others get plain radial falloff), and shadows.
+ */
+fn light2d(frag: vec2f, world: vec2f, n: vec3f, has_normal: bool, bit: u32) -> vec3f {
+  var sum = light_view.ambient.rgb;
+  let tiles_x = light_view.counts.y;
+  let tiles_y = light_view.counts.z;
+  let tx = min(u32(max(frag.x, 0.0)) / TILE_PIXELS, tiles_x - 1u);
+  let ty = min(u32(max(frag.y, 0.0)) / TILE_PIXELS, tiles_y - 1u);
+  let base = (ty * tiles_x + tx) * TILE_STRIDE;
+  let count = min(light_tiles[base], TILE_MAX);
+  for (var k = 0u; k < count; k++) {
+    let l = lights[light_tiles[base + 1u + k]];
+    if ((l.layers & bit) == 0u) { continue; }
+    let delta = l.pos - world;
+    let q = 1.0 - dot(delta, delta) * l.inv_r2;
+    if (q <= 0.0) { continue; }
+    let d = length(delta);
+    var att = pow(q, l.falloff);
+    if (l.cos_outer > -1.5 && d > 1e-4) {
+      att *= smoothstep(l.cos_outer, l.cos_inner, dot(-delta / d, l.dir));
+    }
+    if (has_normal) {
+      att *= max(0.0, dot(n, normalize(vec3f(delta, l.height))));
+    }
+    if (l.row >= 0 && att > 0.0) {
+      att *= shadow2d(l, d, -delta);
+    }
+    sum += l.color * att;
+  }
+  return sum;
+}`,
+  "shard::sprite::light2d::compute": `
+import shard::sprite::light2d::types::{ Light2d, Lighting2dView, Segment2d, TILE_PIXELS, TILE_STRIDE, TILE_MAX, SHADOW_RES, COARSE_RES, TAU, PI };
+
+@group(0) @binding(0) var<uniform> light_view: Lighting2dView;
+@group(0) @binding(1) var<storage, read> lights: array<Light2d>;
+/** Per light: its circle in pixels (center xy, radius), 0. */
+@group(0) @binding(2) var<storage, read> circles: array<vec4f>;
+@group(0) @binding(3) var<storage, read_write> light_tiles: array<u32>;
+@group(0) @binding(4) var<storage, read_write> shadow_map: array<atomic<u32>>;
+@group(0) @binding(5) var<storage, read> segments: array<Segment2d>;
+/** The light index of each shadow row. */
+@group(0) @binding(6) var<storage, read> shadowed: array<u32>;
+@group(0) @binding(7) var<storage, read_write> shadow_coarse: array<vec2f>;
+
+/** One thread per 16\xD716-pixel tile: the lights whose circle reaches it, up to 64. */
+@compute @workgroup_size(64) fn bin(@builtin(global_invocation_id) id: vec3u) {
+  let tiles_x = light_view.counts.y;
+  let tiles = tiles_x * light_view.counts.z;
+  let t = id.x;
+  if (t >= tiles) { return; }
+  let lo = vec2f(f32((t % tiles_x) * TILE_PIXELS), f32((t / tiles_x) * TILE_PIXELS));
+  let hi = lo + vec2f(f32(TILE_PIXELS));
+  let base = t * TILE_STRIDE;
+  var n = 0u;
+  for (var i = 0u; i < light_view.counts.x; i++) {
+    let c = circles[i];
+    let q = clamp(c.xy, lo, hi) - c.xy;
+    if (dot(q, q) > c.z * c.z) { continue; }
+    if (n < TILE_MAX) {
+      light_tiles[base + 1u + n] = i;
+    }
+    n++;
+  }
+  // The full count (possibly over the cap) for stats; shading clamps to 64.
+  light_tiles[base] = n;
+}
+
+/** Every shadow texel starts at "nothing in the way". */
+@compute @workgroup_size(64) fn clear(@builtin(global_invocation_id) id: vec3u) {
+  if (id.x >= light_view.counts.w * SHADOW_RES) { return; }
+  atomicStore(&shadow_map[id.x], 0x7f7fffffu);
+}
+
+/**
+ * One thread per (segment, shadowed light): for each angle bin the segment covers as seen from
+ * the light, the distance along that bin's ray to the segment, kept with atomicMin on the
+ * distance's bits (positive floats sort like their bits). Bins holding an endpoint count too, with
+ * the ray clamped into the segment, so segments thinner than a bin still cast.
+ */
+@compute @workgroup_size(64) fn shadows(@builtin(global_invocation_id) id: vec3u) {
+  if (id.x >= light_view.extra.x || id.y >= light_view.counts.w) { return; }
+  let s = segments[id.x];
+  let l = lights[shadowed[id.y]];
+  if ((s.layers & l.layers) == 0u) { return; }
+  let a = s.a - l.pos;
+  let b = s.b - l.pos;
+  let e = b - a;
+  // Skip segments outside the light's circle.
+  let len2 = dot(e, e);
+  let t0 = select(0.0, clamp(-dot(a, e) / len2, 0.0, 1.0), len2 > 0.0);
+  let near = a + e * t0;
+  if (dot(near, near) >= l.radius * l.radius) { return; }
+  let side = a.x * b.y - a.y * b.x;
+  // A segment through the light (or edge-on to it) casts nothing useful.
+  if (abs(side) < 1e-9) { return; }
+  var start = atan2(a.y, a.x);
+  var span = atan2(b.y, b.x) - start;
+  if (span > PI) { span -= TAU; }
+  if (span < -PI) { span += TAU; }
+  if (span < 0.0) {
+    start += span;
+    span = -span;
+  }
+  let step = TAU / f32(SHADOW_RES);
+  let first = i32(floor((start + PI) / step));
+  let last = min(i32(floor((start + span + PI) / step)), first + i32(SHADOW_RES) - 1);
+  let row = id.y * SHADOW_RES;
+  let n = i32(SHADOW_RES);
+  for (var k = first; k <= last; k++) {
+    let theta = clamp(-PI + (f32(k) + 0.5) * step, start, start + span);
+    let dir = vec2f(cos(theta), sin(theta));
+    let den = dir.x * e.y - dir.y * e.x;
+    if (abs(den) < 1e-12) { continue; }
+    let t = (a.x * e.y - a.y * e.x) / den;
+    if (t <= 0.0) { continue; }
+    let w = ((k % n) + n) % n;
+    atomicMin(&shadow_map[row + u32(w)], bitcast<u32>(t + s.penetration));
+  }
+}
+
+/** One thread per (row, coarse bin): the min and max of its 32 angles. */
+@compute @workgroup_size(64) fn coarse(@builtin(global_invocation_id) id: vec3u) {
+  if (id.x >= light_view.counts.w * COARSE_RES) { return; }
+  let row = id.x / COARSE_RES;
+  let first = row * SHADOW_RES + (id.x % COARSE_RES) * (SHADOW_RES / COARSE_RES);
+  var lo = 3.4028234e38;
+  var hi = 0.0;
+  for (var k = 0u; k < SHADOW_RES / COARSE_RES; k++) {
+    let v = bitcast<f32>(atomicLoad(&shadow_map[first + k]));
+    lo = min(lo, v);
+    hi = max(hi, v);
+  }
+  shadow_coarse[id.x] = vec2f(lo, hi);
+}`
+};
+export {
+  LIGHT2D_SHADERS
+};

package/dist/lighting.d.ts

@@ -0,0 +1,44 @@
+export declare const PointLight2d: import("@aethervtt/shard-core").ComponentDef<{
+    color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    intensity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    falloff: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    height: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    shadows: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    softness: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    layers: import("@aethervtt/shard-core").FieldType<number, "u32">;
+}>;
+export declare const SpotLight2d: import("@aethervtt/shard-core").ComponentDef<{
+    readonly color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly intensity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly falloff: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly height: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly shadows: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly softness: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly layers: import("@aethervtt/shard-core").FieldType<number, "u32">;
+    readonly innerAngle: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly outerAngle: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const Lighting2d: import("@aethervtt/shard-core").ComponentDef<{
+    readonly ambient: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly ambientIntensity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly maxLights: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly maxShadowed: import("@aethervtt/shard-core").FieldType<number, "u16">;
+}>;
+export declare const SpriteLighting: import("@aethervtt/shard-core").ComponentDef<{
+    readonly normal: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+    readonly emissive: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly normalStrength: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const OCCLUDER_SHAPES: readonly ['box', 'circle', 'polygon', 'sprite', 'collider'];
+export type OccluderShape = (typeof OCCLUDER_SHAPES)[number];
+export declare const LightOccluder2d: import("@aethervtt/shard-core").ComponentDef<{
+    readonly shape: import("@aethervtt/shard-core").FieldType<"box" | "circle" | "collider" | "polygon" | "sprite", "u8">;
+    readonly size: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+    readonly points: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2[], "object">;
+    readonly lightPenetration: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly layers: import("@aethervtt/shard-core").FieldType<number, "u32">;
+}>;
+/** The light-layer bit of a sprite layer: bands of 64 layers from −1024. */
+export declare function layerBit(layer: number): number;

package/dist/lighting.js

@@ -0,0 +1,149 @@
+import { defineComponent, t } from "@aethervtt/shard-core";
+import { Visibility } from "@aethervtt/shard-render";
+import { Transform } from "@aethervtt/shard-transform";
+const lightFields = {
+  color: t.color({ default: [1, 1, 1, 1], description: "Light color (linear)." }),
+  intensity: t.f32({
+    default: 1,
+    min: 0,
+    description: "Sprite units: 1 shows a sprite it fully lights at its texture color. Above 1 overbrightens (and blooms)."
+  }),
+  radius: t.f32({
+    default: 5,
+    min: 0,
+    unit: "m",
+    description: "World units: the light reaches zero here."
+  }),
+  falloff: t.f32({
+    default: 2,
+    min: 0,
+    description: "Exponent of the smooth window (1 \u2212 (d/radius)\xB2)^falloff: higher is tighter."
+  }),
+  height: t.f32({
+    default: 1,
+    min: 0,
+    unit: "m",
+    description: "Height above the sprite plane, for normal maps: low grazes the surface, high lights it flat."
+  }),
+  shadows: t.bool({ description: "Cast shadows from LightOccluder2d shapes and occluding tiles." }),
+  softness: t.f32({
+    default: 0.1,
+    min: 0,
+    unit: "m",
+    description: "Emitter size in world units: penumbras widen with distance from the occluder. 0: hard shadows."
+  }),
+  layers: t.u32({
+    default: 4294967295,
+    description: "Which sprite layers it lights: bit k covers layers k\xD764 \u2212 1024 to k\xD764 \u2212 961. All bits: every layer."
+  })
+};
+const PointLight2d = defineComponent("sprite/PointLight2d", lightFields, {
+  description: "A 2D light at the entity: lights sprites and tiles under a Lighting2d camera, with optional shadows.",
+  requires: [Transform, Visibility]
+});
+const SpotLight2d = defineComponent(
+  "sprite/SpotLight2d",
+  {
+    ...lightFields,
+    innerAngle: t.f32({
+      default: 30,
+      min: 0,
+      max: 180,
+      unit: "deg",
+      description: "Half-angle of full brightness, from the entity\u2019s +X."
+    }),
+    outerAngle: t.f32({
+      default: 45,
+      min: 0,
+      max: 180,
+      unit: "deg",
+      description: "Half-angle where the cone fades to zero."
+    })
+  },
+  {
+    description: "A 2D cone light pointing along the entity\u2019s +X (rotate the entity to aim it), like a flashlight.",
+    requires: [Transform, Visibility]
+  }
+);
+const Lighting2d = defineComponent(
+  "sprite/Lighting2d",
+  {
+    ambient: t.color({
+      default: [0.08, 0.08, 0.1, 1],
+      description: "Light every lit sprite gets without any light (linear)."
+    }),
+    ambientIntensity: t.f32({ default: 1, min: 0, description: "Multiplies ambient." }),
+    maxLights: t.u16({ default: 256, min: 1, max: 1024, description: "Visible lights per view." }),
+    maxShadowed: t.u16({
+      default: 64,
+      max: 64,
+      description: "Shadowed lights per view: the ones nearest the view center win."
+    })
+  },
+  {
+    description: "On a camera: lights the 2D world it sees with PointLight2d and SpotLight2d. Without it, sprites draw unlit."
+  }
+);
+const SpriteLighting = defineComponent(
+  "sprite/SpriteLighting",
+  {
+    normal: t.handle("Texture", {
+      description: "Normal map for a plain texture sprite (atlas sprites use TextureAtlas.normals). Tangent space, +Y up."
+    }),
+    emissive: t.f32({
+      min: 0,
+      description: "Glow: \xD7 the sprite color, added after lighting (eyes, screens, embers)."
+    }),
+    normalStrength: t.f32({
+      default: 1,
+      min: 0,
+      description: "Scales the normal map\u2019s tilt: 0 lights it flat."
+    })
+  },
+  { description: "Per-sprite lighting options: a normal map, emissive glow, normal strength." }
+);
+const OCCLUDER_SHAPES = ["box", "circle", "polygon", "sprite", "collider"];
+const LightOccluder2d = defineComponent(
+  "sprite/LightOccluder2d",
+  {
+    shape: t.enum(OCCLUDER_SHAPES, {
+      description: "box: size. circle: size[0] is the radius. polygon: points. sprite: the sprite's alpha outline (atlas with outlines: true), else its rectangle. collider: the entity's physics/Collider (cuboid, ball, capsule, convex)."
+    }),
+    size: t.vec2({
+      default: [1, 1],
+      min: 0,
+      unit: "m",
+      description: "box: full size. circle: size[0] is the radius."
+    }),
+    points: t.list(t.vec2, {
+      description: "polygon: local-space points, closed (the last joins the first)."
+    }),
+    lightPenetration: t.f32({
+      default: 0.05,
+      min: 0,
+      unit: "m",
+      description: "How far light reaches into the occluder, so its own face toward the light stays lit."
+    }),
+    layers: t.u32({
+      default: 4294967295,
+      description: "Which lights it blocks, matching PointLight2d.layers."
+    })
+  },
+  {
+    description: "Blocks 2D light: shadowed lights (shadows: true) cast shadows from its shape.",
+    requires: [Transform]
+  }
+);
+function layerBit(layer) {
+  const band = Math.min(31, Math.max(0, layer + 1024 >> 6));
+  return 1 << band >>> 0;
+}
+export {
+  LightOccluder2d,
+  Lighting2d,
+  OCCLUDER_SHAPES,
+  PointLight2d,
+  SpotLight2d,
+  SpriteLighting,
+  layerBit
+};

package/dist/lights2d.d.ts

@@ -0,0 +1,203 @@
+import { type Entity, type Query, type World } from '@aethervtt/shard-core';
+import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import { type NodeDescriptor } from '@aethervtt/shard-render';
+import { type TileLayer } from './tilemap.js';
+/** Floats per light record (see `Light2d` in lighting-shaders.ts). */
+export declare const LIGHT2D_FLOATS = 16;
+/** Floats per occluder segment record (`Segment2d`). */
+export declare const SEGMENT_FLOATS = 8;
+export declare const TILE_PIXELS = 16;
+export declare const TILE_MAX = 64;
+/** u32s per tile in the tile buffer: a count, then TILE_MAX light indices. */
+export declare const TILE_STRIDE: number;
+/** Angles per shadow row. */
+export declare const SHADOW_RES = 1024;
+/** Coarse bins per shadow row (min and max of 32 angles each). */
+export declare const COARSE_RES = 32;
+export declare const MAX_SHADOWED = 64;
+/**
+ * A light's circle in pixels (y down), written to `out` at `o` (x, y, radius, 0). Returns whether it
+ * reaches the view. Works for any camera: the radius is the larger of the projected x and y offsets.
+ */
+export declare function lightCircle(viewProj: ArrayLike<number>, width: number, height: number, x: number, y: number, z: number, r: number, out: Float32Array, o: number): boolean;
+/** Bins light circles into 16×16-pixel tiles, like the GPU: a full count and up to 64 indices. */
+export declare function binLightsCpu(circles: Float32Array, count: number, tilesX: number, tilesY: number): {
+    counts: Uint32Array;
+    indices: Uint32Array;
+};
+/**
+ * One light's shadow row on the CPU, like the GPU kernel: per angle bin, the nearest segment
+ * distance plus its penetration. `segments` holds SEGMENT_FLOATS per segment.
+ */
+export declare function shadowRowCpu(lx: number, ly: number, radius: number, layers: number, segments: Float32Array, count: number, out: Float32Array): Float32Array;
+/** How lit a point is by a shadow row: the fragment shader's `shadow2d`, on the CPU. */
+export declare function shadowFactorCpu(row: Float32Array, softness: number, d: number, toX: number, toY: number): number;
+/** One occluder entity's segments, cached in world space until it changes. */
+interface OccluderRecord {
+    entity: Entity;
+    local: number[];
+    world: Float32Array;
+    /** minX, minY, maxX, maxY. */
+    bounds: Float32Array;
+    penetration: number;
+    layers: number;
+    seen: number;
+}
+/** One occluding tile layer: boundary edges per chunk, rebuilt only for edited chunks. */
+interface TileOccluder {
+    entity: Entity;
+    layerIndex: number;
+    layer: TileLayer;
+    chunkSize: number;
+    chunksX: number;
+    chunksY: number;
+    editBase: number;
+    cursor: number;
+    local: number[][];
+    world: Float32Array[];
+    bounds: Float32Array;
+    affine: Float32Array;
+    tileSize: [number, number];
+    /** Light reaches three quarters of a tile into walls, so their faces toward it stay lit. */
+    penetration: number;
+    seen: number;
+}
+/** Occluders in world space, shared by every lit view. */
+export declare class OccluderStore {
+    readonly records: OccluderRecord[];
+    readonly index: Map<number, number>;
+    readonly tiles: Map<string, TileOccluder>;
+    /** Bumps whenever any occluder's world segments change. */
+    version: number;
+    /** Tile chunks whose edges were rebuilt in the last update. */
+    chunkRebuilds: number;
+    frame: number;
+    /** Errors already logged, per entity and code. */
+    readonly logged: Set<string>;
+    /** Segments across all occluders (entities and tile chunks). */
+    get segmentCount(): number;
+}
+/** Brings occluder entities and occluding tile layers up to date. */
+/** The queries the lighting system reads, built once in its setup. */
+interface LightQueries {
+    cameras: Query;
+    points: Query;
+    spots: Query;
+    occluders: Query;
+    tilemaps: Query;
+}
+/** One lit view: its lights, shadow rows, occluder segments, and GPU buffers. */
+export declare class LightView2d {
+    readonly name: string;
+    camera: Entity;
+    lights: Float32Array<ArrayBuffer>;
+    lightBits: Uint32Array<ArrayBuffer>;
+    circles: Float32Array<ArrayBuffer>;
+    entities: Float64Array<ArrayBuffer>;
+    count: number;
+    /** Light index per shadow row. */
+    readonly shadowed: Uint32Array<ArrayBuffer>;
+    shadowedCount: number;
+    segments: Float32Array<ArrayBuffer>;
+    segmentBits: Uint32Array<ArrayBuffer>;
+    segmentCount: number;
+    tilesX: number;
+    tilesY: number;
+    readonly uniformData: Float32Array<ArrayBuffer>;
+    readonly uniformBits: Uint32Array<ArrayBuffer>;
+    /** Stats for describe. */
+    visible: number;
+    culled: number;
+    dropped: number;
+    demoted: number;
+    uploadedBytes: number;
+    frame: number;
+    private segmentKey;
+    gpu: ViewGpu | undefined;
+    constructor(name: string);
+    ensureLights(n: number): void;
+    ensureSegments(n: number): void;
+    /** Uploads what changed. Segments go up only when the selection or an occluder changed. */
+    upload(gpu: GpuContext, segmentKey: number): void;
+}
+interface ViewGpu {
+    generation: number;
+    uniform: GpuBuffer;
+    lights: GpuBuffer;
+    circles: GpuBuffer;
+    tiles: GpuBuffer;
+    shadowMap: GpuBuffer;
+    shadowCoarse: GpuBuffer;
+    segments: GpuBuffer;
+    shadowed: GpuBuffer;
+    computeGroup?: {
+        key: string;
+        group: GPUBindGroup;
+    };
+    renderGroup?: {
+        key: string;
+        group: GPUBindGroup;
+    };
+}
+/** 2D lighting state: lit views and the occluders they share. */
+export declare class Lights2dStore {
+    readonly views: Map<string, LightView2d>;
+    readonly occluders: OccluderStore;
+    /** Budget warnings already logged, per view and code. */
+    readonly warned: Set<string>;
+}
+export declare const Lights2d: import("@aethervtt/shard-core").ResourceDef<Lights2dStore>;
+/**
+ * Per lit camera (Lighting2d): extracts visible lights (circle vs view), picks shadow rows,
+ * selects the occluder segments that reach them, and uploads. Does nothing without a lit camera.
+ */
+export declare const prepareLights2d: import("@aethervtt/shard-core").SystemDef<LightQueries>;
+/** The bind group layout lit sprite and tilemap pipelines take at group 3. */
+export declare function lights2dLayout(gpu: GpuContext): GPUBindGroupLayout;
+/** A lit view's light state, or undefined when the view isn't lit. */
+export declare function litView(world: World, view: string): LightView2d | undefined;
+/** The group-3 bind group of a lit view's sprite and tilemap draws. */
+export declare function lights2dGroup(gpu: GpuContext, view: LightView2d): GPUBindGroup;
+/**
+ * Bins lights into screen tiles, fills the shadow rows, and reduces them to coarse min/max bins,
+ * in one compute pass per lit view.
+ */
+export declare function lights2dNode(world: World): NodeDescriptor;
+/** One lit view in `render.describe` → `sprites.lighting.views`. */
+export interface LightViewStats {
+    /** Lights uploaded (at most maxLights). */
+    lights: number;
+    /** Lights that reached the view, before the maxLights budget. */
+    visible: number;
+    /** Lights outside the view. */
+    culled: number;
+    /** Lights over maxLights. */
+    dropped: number;
+    shadowed: number;
+    /** Shadowed lights over maxShadowed, drawn without shadows. */
+    demoted: number;
+    /** Occluder segments uploaded for the shadowed lights. */
+    segments: number;
+    tiles: number;
+    /** Tiles whose lights hit the 64-light cap. */
+    tilesAtCap: number;
+    maxLightsPerTile: number;
+    uploadedBytes: number;
+    /** GPU time (timestamp queries), when the device has them. */
+    gpuMs: {
+        binAndShadows: number | undefined;
+        sprites: number | undefined;
+    };
+    /** The lit lights, in upload order. */
+    entities: number[];
+}
+/** `render.describe` → `sprites.lighting`: per lit view, what's lit, culled, and over budget. */
+export declare function describeLights2d(world: World): {
+    occluders: number;
+    tileLayers: number;
+    segments: number;
+    chunkRebuilds: number;
+    views: Record<string, LightViewStats>;
+} | undefined;
+export declare const lights2dOverlay: import("@aethervtt/shard-render").OverlayDef;
+export {};