@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/layers.js

@@ -0,0 +1,49 @@
+import { defineComponent, t } from "@aethervtt/shard-core";
+import { Transform } from "@aethervtt/shard-transform";
+const RenderLayers = defineComponent(
+  "render/RenderLayers",
+  {
+    mask: t.u16({
+      default: 1,
+      description: "Layer bits, 16 layers (1 is layer 1). A camera draws it if any bit is also in its layers."
+    })
+  },
+  {
+    description: "Per-view visuals: a token keeps its Transform on a root, and each child visual (a flat disc, a standee) carries the layer of the camera that shows it."
+  }
+);
+const GROUND_BANDS = {
+  tiles: 10,
+  grid: 20,
+  drawings: 30,
+  "tokens-flat": 40,
+  fog: 50,
+  overlay: 60
+};
+const OVERLAY_BAND = GROUND_BANDS.overlay;
+const GroundLayer = defineComponent(
+  "render/GroundLayer",
+  {
+    band: t.i16({
+      default: GROUND_BANDS.drawings,
+      presets: GROUND_BANDS,
+      description: "Stacking band: tiles 10, grid 20, drawings 30, tokens-flat 40, fog 50, overlay 60. Higher draws over lower. Bands from 60 up draw after transparent objects and projected fog."
+    }),
+    order: t.i32({ description: "Order within the band: higher draws over lower." }),
+    level: t.i8({
+      min: -16,
+      max: 15,
+      description: "Structure level index (0067): ground layers sort by level first, so a lower level never draws over an upper one. 0 is the ground level."
+    })
+  },
+  {
+    description: "Draws a mesh in the ground phase: coplanar layers in a fixed order, hidden by walls and props, never z-fighting.",
+    requires: [Transform]
+  }
+);
+export {
+  GROUND_BANDS,
+  GroundLayer,
+  OVERLAY_BAND,
+  RenderLayers
+};

package/dist/lens-plugin.d.ts

@@ -0,0 +1,43 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+/** The largest lens target, in pixels: the bound of Aether's ADR-0098. */
+export declare const MAX_LENS_PIXELS = 2097152;
+export declare const LENS_SHADERS: Record<string, string>;
+/** A Lens view's fields this frame, in its target's pixels, and the texture they bend from. */
+export interface LensView {
+    /** The view's name last frame. */
+    view: string;
+    /** Fields that intersect the view. */
+    count: number;
+    /** The pass's uniforms: region (4), count (4), then center x, y, radius, strength per field. */
+    params: Float32Array;
+    /** The source of each field. */
+    sources: Float64Array;
+    /** Target pixels per CSS pixel. */
+    pixelRatio: number;
+    /** Cut down to MAX_LENS_PIXELS: the fields' bounds were larger. */
+    clipped: boolean;
+    /** The copy of the region, while a field intersects the view. */
+    texture: GPUTexture | undefined;
+    generation: number;
+    /** post/lens ran for the view last frame. */
+    ran: boolean;
+    seen: number;
+}
+export declare const LensViews: import("@aethervtt/shard-core").ResourceDef<Map<number, LensView>>;
+export declare const extractLens: import("@aethervtt/shard-core").SystemDef<undefined>;
+/** render.describe's lens section: live fields, and per Lens view what it bent and at what size. */
+export declare function describeLens(world: World): {
+    fields: {
+        screen: [number, number];
+        radius: number;
+        strength: number;
+        ttlMs: number;
+        source: Entity;
+    }[];
+    views: Record<string, unknown>;
+};
+/**
+ * Screen-space lens fields (spec 0063): cameras with Lens bend their own pixels inside the live
+ * LensFields, in a post pass that isn't in the graph while no field is.
+ */
+export declare const lensPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/lens-plugin.js

@@ -0,0 +1,304 @@
+import { defineResource, defineSystem, Last } from "@aethervtt/shard-core";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { addRenderFeatures } from "./features.js";
+import { RenderPhase } from "./graph.js";
+import { Lens, LensFields, LensPath, MAX_LENS_FIELDS } from "./lens.js";
+import { Graph, RenderDescribers, RenderSet, Shaders, Views } from "./plugin.js";
+import { beginPass, idOf, PostCache, tex, uniform } from "./post-common.js";
+import { registerShaders } from "./shaders.js";
+import { cameraOf, extractCameras } from "./view.js";
+const MAX_LENS_PIXELS = 2097152;
+const LENS_SHADERS = {
+  "shard::post::lens": `
+struct Lens {
+  /** The copied region of the target: origin (xy) and size (zw), in pixels. */
+  region: vec4f,
+  /** x: how many fields. */
+  count: vec4f,
+  /** Center (xy) and radius (z) in target pixels, strength (w). */
+  fields: array<vec4f, 4>,
+}
+
+@group(0) @binding(0) var region_copy: texture_2d<f32>;
+@group(0) @binding(1) var<uniform> lens: Lens;
+
+fn texel(p: vec2f) -> vec4f {
+  let last = vec2i(lens.region.zw) - 1;
+  return textureLoad(region_copy, clamp(vec2i(p), vec2i(0), last), 0);
+}
+
+/** Bilinear between the copy's texel centers, clamped to its edge; exact on a center. */
+fn sample_copy(p: vec2f) -> vec4f {
+  let q = p - lens.region.xy - 0.5;
+  let base = floor(q);
+  let t = q - base;
+  let top = mix(texel(base), texel(base + vec2f(1.0, 0.0)), t.x);
+  let bottom = mix(texel(base + vec2f(0.0, 1.0)), texel(base + vec2f(1.0, 1.0)), t.x);
+  return mix(top, bottom, t.y);
+}
+
+/** Inside a field, the view's own pixels at displaced coordinates; outside every field, nothing. */
+@fragment fn fs(@builtin(position) frag: vec4f) -> @location(0) vec4f {
+  var offset = vec2f(0.0);
+  var inside = false;
+  let n = u32(lens.count.x);
+  for (var i = 0u; i < n; i++) {
+    let f = lens.fields[i];
+    let d = frag.xy - f.xy;
+    let u = length(d) / f.z;
+    if (u < 1.0) {
+      inside = true;
+      // Distance u samples from u (1 - s (1 - u)\xB2): unchanged at the rim, never outside it.
+      let k = 1.0 - u;
+      offset -= d * (f.w * k * k);
+    }
+  }
+  if (!inside) { discard; }
+  return sample_copy(frag.xy + offset);
+}`
+};
+const LensViews = defineResource("render/LensViews", {
+  description: "Lens cameras' fields in target pixels and their lens targets, by camera entity.",
+  init: () => /* @__PURE__ */ new Map()
+});
+const clamp1 = (s) => Number.isNaN(s) ? 0 : Math.min(1, Math.max(-1, s));
+let frame = 0;
+function releaseUnseen(state, entity, map) {
+  if (state.seen === frame) return;
+  state.texture?.destroy();
+  map.delete(entity);
+}
+const extractLens = defineSystem({
+  name: "render/extract-lens",
+  description: "Maps live LensFields into each Lens view's pixels, and sizes or releases its lens target.",
+  run: (_, world) => {
+    frame++;
+    const views = world.resource(Views).list;
+    const fields = world.resource(LensFields).fields;
+    const states = world.resource(LensViews);
+    for (let v = 0; v < views.length; v++) {
+      const view = views[v];
+      const cam = cameraOf(view);
+      if (!cam || cam.pixelPerfect || !world.has(cam.entity, Lens)) continue;
+      let s = states.get(cam.entity);
+      if (!s) {
+        s = {
+          view: view.name,
+          count: 0,
+          params: new Float32Array(8 + 4 * MAX_LENS_FIELDS),
+          sources: new Float64Array(MAX_LENS_FIELDS),
+          pixelRatio: 1,
+          clipped: false,
+          texture: void 0,
+          generation: -1,
+          ran: false,
+          seen: 0
+        };
+        states.set(cam.entity, s);
+      }
+      s.seen = frame;
+      s.view = view.name;
+      s.ran = false;
+      s.clipped = false;
+      const width = cam.displayWidth;
+      const height = cam.displayHeight;
+      const ratio = cam.pixelRatio;
+      s.pixelRatio = ratio;
+      const p = s.params;
+      let count = 0;
+      let x0 = width;
+      let y0 = height;
+      let x1 = 0;
+      let y1 = 0;
+      for (let i = 0; i < fields.length && count < MAX_LENS_FIELDS; i++) {
+        const f = fields[i];
+        const cx = f.screen[0] * ratio;
+        const cy = f.screen[1] * ratio;
+        const r = f.radius * ratio;
+        if (!(r > 0) || !Number.isFinite(r + cx + cy)) continue;
+        const fx0 = Math.max(0, Math.floor(cx - r));
+        const fy0 = Math.max(0, Math.floor(cy - r));
+        const fx1 = Math.min(width, Math.ceil(cx + r));
+        const fy1 = Math.min(height, Math.ceil(cy + r));
+        if (fx0 >= fx1 || fy0 >= fy1) continue;
+        const o = 8 + count * 4;
+        p[o] = cx;
+        p[o + 1] = cy;
+        p[o + 2] = r;
+        p[o + 3] = clamp1(f.strength);
+        s.sources[count] = f.source;
+        count++;
+        if (fx0 < x0) x0 = fx0;
+        if (fy0 < y0) y0 = fy0;
+        if (fx1 > x1) x1 = fx1;
+        if (fy1 > y1) y1 = fy1;
+      }
+      s.count = count;
+      p[4] = count;
+      if (count === 0) {
+        s.texture?.destroy();
+        s.texture = void 0;
+        continue;
+      }
+      let w = x1 - x0;
+      let h = y1 - y0;
+      if (w * h > MAX_LENS_PIXELS) {
+        const k = Math.sqrt(MAX_LENS_PIXELS / (w * h));
+        const cw = Math.max(1, Math.floor(w * k));
+        const ch = Math.max(1, Math.floor(h * k));
+        x0 = Math.min(width - cw, Math.max(0, Math.round(x0 + (w - cw) / 2)));
+        y0 = Math.min(height - ch, Math.max(0, Math.round(y0 + (h - ch) / 2)));
+        w = cw;
+        h = ch;
+        s.clipped = true;
+      }
+      p[0] = x0;
+      p[1] = y0;
+      p[2] = w;
+      p[3] = h;
+    }
+    states.forEach(releaseUnseen);
+  }
+});
+function lensTexture(gpu, s, format) {
+  const w = s.params[2];
+  const h = s.params[3];
+  let t = s.texture;
+  if (t && s.generation === gpu.generation && t.format === format) {
+    if (t.width >= w && t.height >= h) return t;
+  } else t = void 0;
+  let tw = Math.max(w, t?.width ?? 0);
+  let th = Math.max(h, t?.height ?? 0);
+  if (tw * th > MAX_LENS_PIXELS) {
+    tw = w;
+    th = h;
+  }
+  s.texture?.destroy();
+  s.generation = gpu.generation;
+  s.texture = gpu.device.createTexture({
+    label: `${s.view}/lens`,
+    size: [tw, th],
+    format,
+    usage: GPUTextureUsage.COPY_DST | GPUTextureUsage.TEXTURE_BINDING
+  });
+  return s.texture;
+}
+function lensNode(states) {
+  const cache = new PostCache();
+  let layout;
+  let layoutGen = -1;
+  return {
+    kind: "raw",
+    // After the display stage wrote the target (tonemap, FXAA, upscale), before overlays.
+    phase: RenderPhase.Display + 20,
+    enabled: (view) => {
+      const cam = cameraOf(view);
+      return cam !== void 0 && (states.get(cam.entity)?.count ?? 0) > 0;
+    },
+    writes: ["view-target"],
+    run: (ctx) => {
+      const gpu = ctx.gpu;
+      const s = states.get(cameraOf(ctx.view).entity);
+      if (!layout || layoutGen !== gpu.generation) {
+        layoutGen = gpu.generation;
+        layout = gpu.layouts.bindGroupLayout({
+          label: "lens",
+          entries: [tex(0, "unfilterable-float"), uniform(1)]
+        });
+      }
+      const target = ctx.texture("view-target");
+      const format = target.format;
+      const pipeline = cache.render(
+        ctx,
+        `lens/${format}`,
+        "shard::post::lens",
+        "fs",
+        [layout],
+        [{ format }]
+      );
+      if (!pipeline) return;
+      const copy = lensTexture(gpu, s, format);
+      const p = s.params;
+      const x = p[0];
+      const y = p[1];
+      const w = p[2];
+      const h = p[3];
+      ctx.encoder.copyTextureToTexture(
+        { texture: target, origin: { x, y } },
+        { texture: copy },
+        { width: w, height: h }
+      );
+      const params = cache.buffer(gpu, `${ctx.view.name}/lens`, p.byteLength);
+      params.write(p);
+      const group = cache.group(
+        gpu,
+        `${ctx.view.name}/lens`,
+        `${idOf(copy)}/${params.version}`,
+        layout,
+        () => [
+          { binding: 0, resource: copy.createView() },
+          { binding: 1, resource: { buffer: params.buffer } }
+        ]
+      );
+      const pass = beginPass(ctx, "post/lens", target.createView(), true);
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, group);
+      pass.setScissorRect(x, y, w, h);
+      pass.draw(3);
+      pass.end();
+      s.ran = true;
+    }
+  };
+}
+function describeLens(world) {
+  const views = {};
+  world.resource(LensViews).forEach((s) => {
+    const fields = [];
+    for (let i = 0; i < s.count; i++) {
+      const o = 8 + i * 4;
+      fields.push({
+        source: s.sources[i],
+        screen: [s.params[o] / s.pixelRatio, s.params[o + 1] / s.pixelRatio],
+        radius: s.params[o + 2] / s.pixelRatio,
+        strength: s.params[o + 3]
+      });
+    }
+    views[s.view] = {
+      fields,
+      ran: s.ran,
+      region: s.count > 0 ? [...s.params.subarray(0, 4)] : null,
+      target: s.texture ? [s.texture.width, s.texture.height] : null,
+      clipped: s.clipped
+    };
+  });
+  return { fields: world.resource(LensFields).fields.map((f) => ({ ...f })), views };
+}
+const lensPlugin = definePlugin({
+  name: "render/lens",
+  dependencies: ["render/forward"],
+  provides: [LensViews],
+  build(app) {
+    app.insertResource(LensPath, { installed: true });
+    app.world.initResource(LensViews);
+    app.addSystems(Last, extractLens.inSet(RenderSet.Extract).after(extractCameras));
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), LENS_SHADERS);
+    app.world.initResource(RenderDescribers).set("lens", describeLens);
+    addRenderFeatures(app.world, {
+      name: "render/lens",
+      description: "Screen-space lens fields (bounded displacement).",
+      nodes: ["post/lens"],
+      baseline: { strategy: "The same fragment passes" }
+    });
+    app.world.resource(Graph).addNode("post/lens", lensNode(app.world.resource(LensViews)));
+  }
+});
+export {
+  LENS_SHADERS,
+  LensViews,
+  MAX_LENS_PIXELS,
+  describeLens,
+  extractLens,
+  lensPlugin
+};

package/dist/lens.d.ts

@@ -0,0 +1,41 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+/** Fields `LensFields` holds at once. */
+export declare const MAX_LENS_FIELDS = 4;
+/** A screen-space field that bends what's behind it (0063). */
+export interface LensField {
+    /** Center, in the target's CSS pixels. */
+    screen: [number, number];
+    /** In CSS pixels. */
+    radius: number;
+    /** -1..1: above 0 magnifies the middle, below 0 pulls the surroundings in. 0 bends nothing. */
+    strength: number;
+    /** Ms it has left: counts down each frame, and refreshing sets it again. At 0 it drops. */
+    ttlMs: number;
+    /** What published it (a die), so it can clear its own. */
+    source: Entity;
+}
+export declare const LensFields: import("@aethervtt/shard-core").ResourceDef<{
+    fields: LensField[];
+}>;
+export declare const Lens: import("@aethervtt/shard-core").ComponentDef<{}>;
+/** Present when lensPlugin is installed; without it Lens cameras render unbent. */
+export declare const LensPath: import("@aethervtt/shard-core").ResourceDef<{
+    installed: true;
+}>;
+/**
+ * Publishes or refreshes `source`'s field: a field with the same source is replaced. Returns false
+ * when `MAX_LENS_FIELDS` other sources hold fields already.
+ */
+export declare function publishLensField(world: World, field: LensField): boolean;
+/** Drops `source`'s fields, or every field. Publishers call it on dismissal and teardown. */
+export declare function clearLensFields(world: World, source?: Entity): void;
+/**
+ * Copies `from`'s fields into `to` (another app on the device, 0052), for the host to call each
+ * frame they're live. Copies, not shares: each app counts its fields down on its own. `offset` is
+ * where `to`'s target sits in `from`'s CSS pixels (a table canvas below a page-wide dice canvas's
+ * top bar, say); it's subtracted from each field's center.
+ */
+export declare function forwardLensFields(from: World, to: World, offset?: readonly [number, number]): void;
+/** The frame demand live fields hold, so they expire on time and the app idles after (0052). */
+export declare const LENS_DEMAND = "render/lens-fields";
+export declare const expireLensFields: import("@aethervtt/shard-core").SystemDef<undefined>;

package/dist/lens.js

@@ -0,0 +1,99 @@
+import {
+  defineComponent,
+  defineResource,
+  defineSystem
+} from "@aethervtt/shard-core";
+import { FrameDemand, Time } from "@aethervtt/shard-runtime";
+import { Camera3d } from "./camera.js";
+const MAX_LENS_FIELDS = 4;
+const LensFields = defineResource("render/LensFields", {
+  hostWritable: true,
+  description: "Screen-space fields effects publish (at most 4): center and radius in CSS pixels, strength, ms to live, source entity. Views with Lens bend their own pixels inside them (lensPlugin).",
+  init: () => ({ fields: [] })
+});
+const Lens = defineComponent(
+  "render/Lens",
+  {},
+  {
+    description: "Tag: this camera's view bends its own pixels inside the live LensFields, after the display stage. Pixels outside every field are left exactly as rendered.",
+    requires: [Camera3d]
+  }
+);
+const LensPath = defineResource("render/LensPath", {
+  description: "Present when lens fields (lensPlugin) are installed."
+});
+function publishLensField(world, field) {
+  const fields = world.initResource(LensFields).fields;
+  let i = 0;
+  while (i < fields.length && fields[i].source !== field.source) i++;
+  if (i === MAX_LENS_FIELDS) return false;
+  const f = fields[i];
+  if (f) {
+    f.screen[0] = field.screen[0];
+    f.screen[1] = field.screen[1];
+    f.radius = field.radius;
+    f.strength = field.strength;
+    f.ttlMs = field.ttlMs;
+  } else fields.push({ ...field, screen: [field.screen[0], field.screen[1]] });
+  world.touchResource(LensFields);
+  return true;
+}
+function clearLensFields(world, source) {
+  const value = world.tryResource(LensFields);
+  if (!value || value.fields.length === 0) return;
+  if (source === void 0) value.fields.length = 0;
+  else value.fields = value.fields.filter((f) => f.source !== source);
+  world.touchResource(LensFields);
+}
+const NO_OFFSET = [0, 0];
+function forwardLensFields(from, to, offset = NO_OFFSET) {
+  const source = from.tryResource(LensFields)?.fields ?? [];
+  const out = to.initResource(LensFields).fields;
+  const n = Math.min(source.length, MAX_LENS_FIELDS);
+  for (let i = 0; i < n; i++) {
+    const s = source[i];
+    const d = out[i];
+    if (d) {
+      d.radius = s.radius;
+      d.strength = s.strength;
+      d.ttlMs = s.ttlMs;
+      d.source = s.source;
+    } else out.push({ ...s, screen: [0, 0] });
+    const f = out[i];
+    f.screen[0] = s.screen[0] - offset[0];
+    f.screen[1] = s.screen[1] - offset[1];
+  }
+  if (out.length === 0 && n === 0) return;
+  out.length = n;
+  to.touchResource(LensFields);
+}
+const LENS_DEMAND = "render/lens-fields";
+const expireLensFields = defineSystem({
+  name: "render/expire-lens-fields",
+  description: "Counts LensFields down by the frame time and drops expired ones; holds frames while any live.",
+  run: (_, world) => {
+    const fields = world.tryResource(LensFields)?.fields;
+    let n = 0;
+    if (fields && fields.length > 0) {
+      const ms = world.resource(Time).delta * 1e3;
+      for (let i = 0; i < fields.length; i++) {
+        const f = fields[i];
+        f.ttlMs -= ms;
+        if (f.ttlMs > 0 && n < MAX_LENS_FIELDS) fields[n++] = f;
+      }
+      fields.length = n;
+    }
+    world.tryResource(FrameDemand)?.set(LENS_DEMAND, n > 0);
+  }
+});
+export {
+  LENS_DEMAND,
+  Lens,
+  LensFields,
+  LensPath,
+  MAX_LENS_FIELDS,
+  clearLensFields,
+  expireLensFields,
+  forwardLensFields,
+  publishLensField
+};

package/dist/lights.d.ts

@@ -1,5 +1,6 @@
-import { type Entity, type World } from '@aethervtt/shard-core';
+import { type ComponentDef, type Entity, type World } from '@aethervtt/shard-core';
 import { GpuBuffer, type GpuContext } from '@aethervtt/shard-gpu';
+import { DataStore } from './data-store.js';
 /** Luminous power presets in lumens, for point and spot lights. */
 export declare const LuminousPowerPresets: {
     readonly candle: 12;
@@ -10,18 +11,20 @@ export declare const LuminousPowerPresets: {
 export type LuminousPowerPreset = keyof typeof LuminousPowerPresets;
 /** Lumens for a preset name or a number. */
 export declare const lumens: (value: LuminousPowerPreset | number) => number;
+export declare const SHADOW_UPDATES: readonly ['always', 'on-change'];
 export declare const CascadeSettings: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
     count: import("@aethervtt/shard-core").FieldType<number, "u8">;
     maxDistance: import("@aethervtt/shard-core").FieldType<number, "f32">;
     splitLambda: import("@aethervtt/shard-core").FieldType<number, "f32">;
 }>, "object">;
-export declare const DirectionalLight: import("@aethervtt/shard-core").ComponentDef<{
+export declare const DirectionalLight: ComponentDef<{
     readonly shadows: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
     readonly shadowBias: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly shadowNormalBias: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly shadowSoftness: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
     readonly illuminance: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly shadowUpdate: import("@aethervtt/shard-core").FieldType<"always" | "on-change", "u8">;
     readonly cascades: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
         count: import("@aethervtt/shard-core").FieldType<number, "u8">;
         maxDistance: import("@aethervtt/shard-core").FieldType<number, "f32">;
@@ -29,7 +32,8 @@ export declare const DirectionalLight: import("@aethervtt/shard-core").Component
     }>, "object">;
     readonly angularDiameter: import("@aethervtt/shard-core").FieldType<number, "f32">;
 }>;
-export declare const PointLight: import("@aethervtt/shard-core").ComponentDef<{
+export declare const FALLOFFS: readonly ['physical', 'tabletop'];
+export declare const PointLight: ComponentDef<{
     readonly shadows: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
     readonly shadowBias: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly shadowNormalBias: import("@aethervtt/shard-core").FieldType<number, "f32">;
@@ -38,8 +42,17 @@ export declare const PointLight: import("@aethervtt/shard-core").ComponentDef<{
     readonly intensity: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly range: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly blockedByWalls: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly shadowUpdate: import("@aethervtt/shard-core").FieldType<"always" | "on-change", "u8">;
+    readonly falloff: import("@aethervtt/shard-core").FieldType<"physical" | "tabletop", "u8">;
+    readonly bright: import("@aethervtt/shard-core").FieldType<number, "f32">;
 }>;
-export declare const SpotLight: import("@aethervtt/shard-core").ComponentDef<{
+/**
+ * Tabletop falloff (0057): 1 inside `bright`, linear to 0 at `range`. Mirrors `light_falloff`
+ * in `shard::pbr::lights`.
+ */
+export declare function tabletopFalloff(distance: number, bright: number, range: number): number;
+export declare const SpotLight: ComponentDef<{
     readonly shadows: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
     readonly shadowBias: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly shadowNormalBias: import("@aethervtt/shard-core").FieldType<number, "f32">;
@@ -48,6 +61,8 @@ export declare const SpotLight: import("@aethervtt/shard-core").ComponentDef<{
     readonly intensity: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly range: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly blockedByWalls: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly shadowUpdate: import("@aethervtt/shard-core").FieldType<"always" | "on-change", "u8">;
     readonly innerAngle: import("@aethervtt/shard-core").FieldType<number, "f32">;
     readonly outerAngle: import("@aethervtt/shard-core").FieldType<number, "f32">;
 }>;
@@ -68,6 +83,11 @@ export interface LightingSettingsValue {
     shadowMapSize: number;
     maxShadowedPoints: number;
     maxShadowedSpots: number;
+    /**
+     * Baseline tier (0064): the point and spot lights a view shades, the nearest first; at most 128.
+     * Past it the farthest go unshaded, and `render/light-budget` says how many.
+     */
+    baselineMaxLights: number;
 }
 export declare const LightingSettings: import("@aethervtt/shard-core").ResourceDef<LightingSettingsValue>;
 /** Floats per light record in the light buffer. */
@@ -100,7 +120,21 @@ export interface LightRecord {
     outerAngle: number;
     radius: number;
     alive: boolean;
+    /** `shadowUpdate: 'on-change'`: the light's shadow maps are cached. */
+    cachedShadow: boolean;
+    /** Its wall-blocking row (0069), or -1: see `setLightRow`. */
+    row: number;
 }
+/**
+ * Where a light's wall-blocking row (0069) rides in its record, as row + 1 (0: none): a word its
+ * kind never reads. A point light's spot scale (read only for spots) and a spot's tabletop bright
+ * radius (spots always fall off physically). The Light struct is unchanged, so shaders without
+ * `BLOCKED_LIGHTS` link the same code.
+ */
+export declare const LIGHT_ROW_WORD: {
+    readonly point: 12;
+    readonly spot: 19;
+};
 /**
  * Point and spot lights in a storage buffer (`array<Light>`). Each light owns a slot; only lights
  * whose data changed this frame are uploaded (coalesced runs), and the counters say how many.
@@ -118,9 +152,13 @@ export declare class LightStore {
     uploadedBytes: number;
     readonly buffer: GpuBuffer;
     /** Directional lights: count + up to 4 × (direction, shadow cascade flag, color × lux, disk radius). */
-    readonly directional: GpuBuffer;
+    /** Directional lights: `@data(uniform)`, a uniform block on baseline. */
+    readonly directional: DataStore;
     readonly directionalData: Float32Array<ArrayBuffer>;
     readonly directionalU32: Uint32Array<ArrayBuffer>;
+    /** What the directional buffer holds, so an unchanged frame writes nothing (0055). */
+    private readonly directionalSent;
+    private directionalStale;
     /** The first directional light with shadows: entity, and its settings. */
     shadowSun: {
         entity: Entity;
@@ -131,6 +169,8 @@ export declare class LightStore {
         bias: number;
         normalBias: number;
         softness: number;
+        /** `shadowUpdate: 'on-change'`: cascades are cached. */
+        cached: boolean;
     } | null;
     directionalCount: number;
     private generation;
@@ -156,5 +196,10 @@ export declare const extractLights: import("@aethervtt/shard-core").SystemDef<{
 }>;
 /** Frees a light's slot when its component goes away (including despawn). */
 export declare function observeLightRemovals(world: World): void;
+/**
+ * Gives a light its wall-blocking row (0069), or none with -1 (marks it dirty if it changed).
+ * Structure's interiorLightingPlugin calls it after extraction.
+ */
+export declare function setLightRow(store: LightStore, r: LightRecord, row: number): void;
 /** Sets a light's shadow index (marks it dirty if it changed). */
 export declare function setShadowIndex(store: LightStore, r: LightRecord, index: number): void;