@aethervtt/shard-render 0.0.1 → 0.1.0

package/dist/post-nodes.d.ts

@@ -32,7 +32,8 @@ export declare const adaptExposure: import("@aethervtt/shard-core").SystemDef<{
 /** Graph node names of the post chain, in order (for describe and tests). */
 export declare const POST_NODES: readonly [readonly ['post/fog', 1], readonly ['post/taa', 2], readonly ['post/motion-blur', 4], readonly ['post/dof', 8], readonly ['post/bloom', 16], readonly ['post/exposure', 32], readonly ['post/fxaa', 64]];
 /** Adds the prepass, SSAO, and the post chain to the graph. */
-export declare function addPostNodes(world: World): void;
+/** The post chain's nodes. `baseline`: the baseline tier's exposure meter (0064), when on one. */
+export declare function addPostNodes(world: World, baseline?: typeof import('./baseline/exposure.js')): void;
 /** The post section of `render.describe`: per view, active effects in order with GPU time. */
 export declare function describePost(world: World): {
     views: Record<string, unknown>;

package/dist/post-nodes.js

@@ -6,12 +6,14 @@ import {
 } from "@aethervtt/shard-core";
 import { Time } from "@aethervtt/shard-runtime";
 import { Exposure } from "./camera.js";
+import { addRenderFeatures } from "./features.js";
 import { drawMaterials, ForwardStateResource, PASS_PREPASS, viewBindGroup } from "./forward.js";
 import { RenderPhase } from "./graph.js";
 import { Graph, Views } from "./plugin.js";
 import { AutoExposure, cocParams, hasEffect, needsPrepass, PostEffect } from "./post.js";
 import {
   beginPass,
+  depthTex,
   forwardView,
   HDR,
   idOf,
@@ -42,6 +44,7 @@ const prepassNode = {
     if (v.cam.deferred) drawMaterials(ctx, state, v.pv, v.cam, v.cam.forwardOnly, PASS_PREPASS);
   }
 };
+const FOG_KEYS = ["post/fog", "post/fog/alpha", "post/fog/interior", "post/fog/alpha/interior"];
 const SSAO_STEPS = [
   [1, 4],
   [2, 4],
@@ -70,11 +73,11 @@ function ssaoNode(phase, deferred) {
         layouts = {
           gtao: gpu.layouts.bindGroupLayout({
             label: "ssao/gtao",
-            entries: [uniform(0), tex(1, "depth"), tex(2, "unfilterable-float"), uniform(3)]
+            entries: [uniform(0), depthTex(gpu, 1), tex(2, "unfilterable-float"), uniform(3)]
           }),
           up: gpu.layouts.bindGroupLayout({
             label: "ssao/upsample",
-            entries: [uniform(0), tex(1, "depth"), uniform(3), tex(4, "unfilterable-float")]
+            entries: [uniform(0), depthTex(gpu, 1), uniform(3), tex(4, "unfilterable-float")]
           })
         };
       }
@@ -170,16 +173,18 @@ function fogNode() {
         layoutGen = gpu.generation;
         layout = gpu.layouts.bindGroupLayout({
           label: "fog",
-          entries: [tex(0, "unfilterable-float"), tex(1, "depth"), uniform(2)]
+          entries: [tex(0, "unfilterable-float"), depthTex(gpu, 1), uniform(2)]
         });
       }
+      const alpha = v.cam.alphaOutput;
       const pipeline = cache.render(
         ctx,
-        "post/fog",
+        FOG_KEYS[(alpha ? 1 : 0) + (state.interiorMode !== 0 ? 2 : 0)],
         "shard::post::fog",
         "fs",
         [state.layouts.view, layout],
-        HDR
+        HDR,
+        { TRANSPARENT: alpha }
       );
       if (!pipeline) return;
       const f = v.cam.post.fog;
@@ -233,7 +238,7 @@ function taaNode() {
           entries: [
             uniform(0),
             tex(1, "unfilterable-float"),
-            tex(2, "depth"),
+            depthTex(gpu, 2),
             tex(3, "unfilterable-float"),
             tex(4),
             sampler(5),
@@ -242,13 +247,15 @@ function taaNode() {
         });
         histories.clear();
       }
+      const alpha = cameraOf(ctx.view)?.alphaOutput === true;
       const pipeline = cache.render(
         ctx,
-        "post/taa",
+        alpha ? "post/taa/alpha" : "post/taa",
         "shard::post::taa",
         "fs",
         [layout],
-        [{ format: "rgba16float" }, { format: "rgba16float" }]
+        [{ format: "rgba16float" }, { format: "rgba16float" }],
+        { TRANSPARENT: alpha }
       );
       if (!pipeline) return;
       const input = ctx.texture("taa-in");
@@ -330,7 +337,7 @@ function motionBlurNode() {
           entries: [
             uniform(0),
             tex(1),
-            tex(2, "depth"),
+            depthTex(gpu, 2),
             tex(3, "unfilterable-float"),
             uniform(4),
             sampler(5)
@@ -396,7 +403,7 @@ function dofNode() {
         layoutGen = gpu.generation;
         layout = gpu.layouts.bindGroupLayout({
           label: "dof",
-          entries: [uniform(0), tex(1), tex(2, "depth"), uniform(3), tex(4), sampler(5)]
+          entries: [uniform(0), tex(1), depthTex(gpu, 2), uniform(3), tex(4), sampler(5)]
         });
       }
       const prepare = cache.render(ctx, "dof/prepare", "shard::post::dof", "prepare", [layout], HDR);
@@ -586,12 +593,22 @@ function histogramEv(bins) {
   }
   return weight > 0 ? sum / weight : void 0;
 }
-function autoExposureNode() {
+function landReading(meters, entity, index, ev) {
+  const m = meters.get(entity);
+  if (m && ev !== void 0 && index > m.reading) {
+    m.metered = ev;
+    m.reading = index;
+    m.readings++;
+  }
+}
+function autoExposureNode(baseline) {
   const cache = new PostCache();
   let layout;
   let layoutGen = -1;
   const perView = /* @__PURE__ */ new Map();
+  const meterViews = /* @__PURE__ */ new Map();
   const zero = new Uint32Array(256);
+  const bins = new Uint32Array(256);
   return {
     kind: "raw",
     phase: RenderPhase.Post + 50,
@@ -602,6 +619,63 @@ function autoExposureNode() {
       const v = forwardView(ctx);
       if (!v) return;
       const gpu = ctx.gpu;
+      if (baseline) {
+        const layout2 = baseline.meterLayout(gpu);
+        const pipeline2 = cache.render(
+          ctx,
+          "post/exposure-meter",
+          "shard::post::baseline::meter",
+          "main",
+          [layout2],
+          [{ format: "rg16float" }]
+        );
+        if (!pipeline2) return;
+        let m = meterViews.get(ctx.view.name);
+        if (!m || m.generation !== gpu.generation) {
+          m = baseline.meterView(gpu, ctx.view.name, METER_READBACKS);
+          meterViews.set(ctx.view.name, m);
+        }
+        const input2 = ctx.texture("post-hdr");
+        const key = `${idOf(input2)}/${v.pv.uniform.version}`;
+        if (!m.group || m.groupKey !== key) {
+          m.groupKey = key;
+          m.group = gpu.device.createBindGroup({
+            label: `${ctx.view.name}/exposure`,
+            layout: layout2,
+            entries: [
+              { binding: 0, resource: { buffer: v.pv.uniform.buffer } },
+              { binding: 1, resource: input2.createView() },
+              { binding: 2, resource: { buffer: m.params } }
+            ]
+          });
+        }
+        scratch[0] = METER_MIN_EV;
+        scratch[1] = METER_BINS_PER_EV;
+        scratch[2] = v.cam.post.exposure.metering;
+        scratch[3] = 0;
+        const k2 = baseline.renderMeter(ctx, m, pipeline2, m.group, scratch.subarray(0, 4));
+        if (k2 === void 0) return;
+        const meters2 = ctx.world.resource(ExposureMeters);
+        const entity2 = v.cam.entity;
+        const meter2 = meters2.get(entity2);
+        const index2 = meter2 ? ++meter2.submitted : 0;
+        const readback2 = m.readbacks[k2];
+        const busy2 = m.busy;
+        ctx.afterSubmit(() => {
+          readback2.mapAsync(GPUMapMode.READ).then(
+            () => {
+              baseline.binMeter(readback2.getMappedRange(), METER_MIN_EV, METER_BINS_PER_EV, bins);
+              readback2.unmap();
+              busy2[k2] = false;
+              landReading(meters2, entity2, index2, histogramEv(bins));
+            },
+            () => {
+              busy2[k2] = false;
+            }
+          );
+        });
+        return;
+      }
       const C = GPUShaderStage.COMPUTE;
       if (!layout || layoutGen !== gpu.generation) {
         layoutGen = gpu.generation;
@@ -687,12 +761,7 @@ function autoExposureNode() {
             const ev = histogramEv(new Uint32Array(readback.getMappedRange().slice(0)));
             readback.unmap();
             busy[k] = false;
-            const m = meters.get(entity);
-            if (m && ev !== void 0 && index > m.reading) {
-              m.metered = ev;
-              m.reading = index;
-              m.readings++;
-            }
+            landReading(meters, entity, index, ev);
           },
           () => {
             busy[k] = false;
@@ -753,7 +822,7 @@ const POST_NODES = [
   ["post/fxaa", PostEffect.Fxaa]
 ];
 const halfSize = { divide: 2 };
-function addPostNodes(world) {
+function addPostNodes(world, baseline) {
   const graph = world.resource(Graph);
   world.initResource(ExposureMeters);
   graph.declare({ name: "prepass-normal", format: "rgba16float" });
@@ -774,6 +843,29 @@ function addPostNodes(world) {
       return cam ? bloomLevels(cam) : 1;
     }
   });
+  addRenderFeatures(world, {
+    name: "render/post",
+    description: "The prepass, SSAO, fog, TAA, motion blur, depth of field and bloom.",
+    nodes: [
+      "prepass",
+      "ssao",
+      "ssao-deferred",
+      "post/fog",
+      "post/taa",
+      "post/motion-blur",
+      "post/dof",
+      "post/bloom"
+    ],
+    baseline: { strategy: "The same fragment passes" }
+  });
+  addRenderFeatures(world, {
+    name: "render/auto-exposure",
+    description: "Automatic exposure from a luminance histogram.",
+    nodes: ["post/exposure"],
+    baseline: {
+      strategy: "A 64\xD736 meter image read back and binned into the same histogram on the CPU"
+    }
+  });
   graph.addNode("prepass", prepassNode);
   graph.addNode("ssao", ssaoNode(RenderPhase.Prepass + 50, false));
   graph.addNode("ssao-deferred", ssaoNode(RenderPhase.Opaque + 20, true));
@@ -782,7 +874,7 @@ function addPostNodes(world) {
   graph.addNode("post/motion-blur", motionBlurNode());
   graph.addNode("post/dof", dofNode());
   graph.addNode("post/bloom", bloomNode());
-  graph.addNode("post/exposure", autoExposureNode());
+  graph.addNode("post/exposure", autoExposureNode(baseline));
 }
 const DESCRIBED = [
   ["ssao", "ssao", PostEffect.Ssao],

package/dist/post-plugin.js

@@ -1,7 +1,7 @@
 import { PostUpdate } from "@aethervtt/shard-core";
 import { definePlugin } from "@aethervtt/shard-runtime";
 import { applyPhysicalCameras } from "./camera.js";
-import { RenderDescribers, Shaders } from "./plugin.js";
+import { Gpu, RenderDescribers, Shaders } from "./plugin.js";
 import { PostEffect, PostFeatures } from "./post.js";
 import { adaptExposure, addPostNodes, describePost, ExposureMeters } from "./post-nodes.js";
 import { POST_SHADERS } from "./post-shaders.js";
@@ -15,10 +15,12 @@ const postPlugin = definePlugin({
     app.world.initResource(PostFeatures).effects |= POST_EFFECTS;
     app.addSystems(PostUpdate, adaptExposure.after(applyPhysicalCameras));
   },
-  ready(app) {
+  async ready(app) {
+    const baseline = app.world.resource(Gpu).tier === "baseline" ? await import("./baseline/exposure.js") : void 0;
     registerShaders(app.world.resource(Shaders), POST_SHADERS);
+    if (baseline) registerShaders(app.world.resource(Shaders), baseline.BASELINE_EXPOSURE_SHADERS);
     app.world.initResource(RenderDescribers).set("post", (world) => describePost(world));
-    addPostNodes(app.world);
+    addPostNodes(app.world, baseline);
   }
 });
 export {

package/dist/post-shaders.js

@@ -69,6 +69,7 @@ fn prepass_output(in: PrepassVertex, n: vec3f) -> PrepassOutput {
 import shard::prepass::common::{ PrepassVertex, PrepassOutput, prepass_vertex, prepass_output, surface_of };
 import shard::pbr::material::pbr_input;
 import shard::pbr::standard::material;
+@if(CUTAWAY) import shard::cutaway::cutaway_clip;
 
 @vertex fn vs(
   @builtin(instance_index) instance_index: u32,
@@ -84,12 +85,20 @@ import shard::pbr::standard::material;
 
 /** Depth, the shaded normal (normal maps included), and velocity. */
 @fragment fn fs(in: PrepassVertex) -> PrepassOutput {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
   let p = pbr_input(surface_of(in));
   @if(MASK) if (p.alpha < material.alphaCutoff) { discard; }
   return prepass_output(in, p.normal);
+}
+
+/** Baseline (0064): depth alone, for what reads depth when the scene is multisampled. */
+@if(BASELINE) @fragment fn fs_depth(in: PrepassVertex) {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
+  @if(MASK) if (pbr_input(surface_of(in)).alpha < material.alphaCutoff) { discard; }
 }`,
   "shard::prepass::plain": `
 import shard::prepass::common::{ PrepassVertex, PrepassOutput, prepass_vertex, prepass_output };
+@if(CUTAWAY) import shard::cutaway::cutaway_clip;
 
 @vertex fn vs(
   @builtin(instance_index) instance_index: u32,
@@ -105,7 +114,13 @@ import shard::prepass::common::{ PrepassVertex, PrepassOutput, prepass_vertex, p
 
 /** Materials with their own shading: the geometric normal. */
 @fragment fn fs(in: PrepassVertex) -> PrepassOutput {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
   return prepass_output(in, normalize(in.world_normal));
+}
+
+/** Baseline (0064): depth alone. */
+@if(BASELINE) @fragment fn fs_depth(in: PrepassVertex) {
+  @if(CUTAWAY) cutaway_clip(in.world_position, in.clip.xy, in.flags);
 }`,
   "shard::post::fog": `
 import shard::view::view;
@@ -159,7 +174,10 @@ fn optical_depth(y0: f32, dir_y: f32, t0: f32, t1: f32) -> f32 {
     sun = light.color * view.sunTransmittance[0].rgb * mix(1.0 / (4.0 * PI), hg, fog.sun);
   }
   let inscatter = fog.color.rgb * (sky + sun) * view.exposure;
-  return vec4f(c.rgb * transmittance + inscatter * (1.0 - transmittance), c.a);
+  let color = c.rgb * transmittance + inscatter * (1.0 - transmittance);
+  @if(!TRANSPARENT) return vec4f(color, c.a);
+  // Premultiplied (0052): the fog is a layer of its own opacity over what's behind it.
+  @if(TRANSPARENT) return vec4f(color, c.a * transmittance + (1.0 - transmittance));
 }`,
   "shard::post::bloom": `
 import shard::color::luminance;
@@ -461,12 +479,19 @@ fn sample_history(uv: vec2f) -> vec3f {
   var hi = vec3f(-1e20);
   var nearest = 0.0;
   var nearest_px = px;
+  @if(TRANSPARENT) var alpha_lo = 1.0;
+  @if(TRANSPARENT) var alpha_hi = 0.0;
   for (var y = -1; y <= 1; y++) {
     for (var x = -1; x <= 1; x++) {
       let q = clamp(px + vec2i(x, y), vec2i(0), size - 1);
-      let c = rgb_to_ycocg(compress(textureLoad(input, q, 0).rgb));
+      let texel = textureLoad(input, q, 0);
+      let c = rgb_to_ycocg(compress(texel.rgb));
       lo = min(lo, c);
       hi = max(hi, c);
+      @if(TRANSPARENT) {
+        alpha_lo = min(alpha_lo, texel.a);
+        alpha_hi = max(alpha_hi, texel.a);
+      }
       let d = textureLoad(depth_texture, q, 0);
       if (d > nearest) { nearest = d; nearest_px = q; }
     }
@@ -487,8 +512,17 @@ fn sample_history(uv: vec2f) -> vec3f {
   let blended = mix(ycocg_to_rgb(h), current, alpha);
   let color = expand(max(blended, vec3f(0.0)));
   var out: TaaOutput;
-  out.color = vec4f(color, 1.0);
-  out.history = vec4f(color, 1.0);
+  @if(!TRANSPARENT) {
+    out.color = vec4f(color, 1.0);
+    out.history = vec4f(color, 1.0);
+  }
+  @if(TRANSPARENT) {
+    // Coverage resolves like color: history clamped to the neighborhood, blended at the same rate.
+    let past = clamp(textureSampleLevel(history, linear_sampler, prev_uv, 0.0).a, alpha_lo, alpha_hi);
+    let coverage = mix(past, textureLoad(input, px, 0).a, alpha);
+    out.color = vec4f(color, coverage);
+    out.history = vec4f(color, coverage);
+  }
   return out;
 }`,
   "shard::post::ssao": `
@@ -614,6 +648,13 @@ fn at(uv: vec2f, o: vec2f, texel: vec2f) -> vec3f {
   return textureSampleLevel(input, input_sampler, uv + o * texel, 0.0).rgb;
 }
 
+/** The output at uv: opaque views write alpha 1; premultiplied ones carry it, rgb <= alpha (0052). */
+fn result(uv: vec2f) -> vec4f {
+  let c = textureSampleLevel(input, input_sampler, uv, 0.0);
+  @if(!TRANSPARENT) return vec4f(c.rgb, 1.0);
+  @if(TRANSPARENT) return vec4f(c.rgb, max(c.a, max(c.r, max(c.g, c.b))));
+}
+
 /** FXAA 3.11 (Lottes), quality preset 12: local contrast, edge direction, end search, blend. */
 @fragment fn fs(@builtin(position) frag: vec4f) -> @location(0) vec4f {
   let size = vec2f(textureDimensions(input));
@@ -628,7 +669,10 @@ fn at(uv: vec2f, o: vec2f, texel: vec2f) -> vec3f {
   let lo = min(m, min(min(n, s), min(e, w)));
   let hi = max(m, max(max(n, s), max(e, w)));
   let range = hi - lo;
-  if (range < max(0.0312, hi * 0.125)) { return vec4f(center, 1.0); }
+  if (range < max(0.0312, hi * 0.125)) {
+    @if(!TRANSPARENT) return vec4f(center, 1.0);
+    @if(TRANSPARENT) return result(uv);
+  }
   let nw = luma(at(uv, vec2f(-1.0, -1.0), texel));
   let ne = luma(at(uv, vec2f(1.0, -1.0), texel));
   let sw = luma(at(uv, vec2f(-1.0, 1.0), texel));
@@ -689,7 +733,8 @@ fn at(uv: vec2f, o: vec2f, texel: vec2f) -> vec3f {
   let blend = max(edge_blend, sub_blend);
   var final_uv = uv;
   if (horizontal) { final_uv.y += blend * step_len; } else { final_uv.x += blend * step_len; }
-  return vec4f(textureSampleLevel(input, input_sampler, final_uv, 0.0).rgb, 1.0);
+  @if(!TRANSPARENT) return vec4f(textureSampleLevel(input, input_sampler, final_uv, 0.0).rgb, 1.0);
+  @if(TRANSPARENT) return result(final_uv);
 }`
 };
 export {

package/dist/projection.d.ts

@@ -0,0 +1,24 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+/**
+ * Projects a world point to CSS pixels on `camera`'s target (origin top-left). Returns false when
+ * the point is behind the camera (`out` is left unchanged), or the camera hasn't rendered yet.
+ */
+export declare function worldToScreen(world: World, camera: Entity, point: ArrayLike<number>, out: {
+    [index: number]: number;
+}): boolean;
+/**
+ * The world ray under CSS pixel (x, y) of `camera`'s target: its origin on the near plane and its
+ * unit direction. Orthographic rays are parallel, perspective ones start at the near plane.
+ */
+export declare function screenToRay(world: World, camera: Entity, x: number, y: number, outOrigin: {
+    [index: number]: number;
+}, outDir: {
+    [index: number]: number;
+}): void;
+/**
+ * Where the ray under CSS pixel (x, y) meets the horizontal plane `y = planeY` (a floor, a ground
+ * band). Returns false when it doesn't (parallel, or behind the camera).
+ */
+export declare function screenToPlane(world: World, camera: Entity, x: number, y: number, planeY: number, out: {
+    [index: number]: number;
+}): boolean;

package/dist/projection.js

@@ -0,0 +1,87 @@
+import { mat4 } from "@aethervtt/shard-core";
+import { Cameras } from "./view.js";
+const scratchInv = mat4.create();
+const scratchKey = mat4.create();
+let invValid = false;
+function inverse(viewProj) {
+  let same = invValid;
+  for (let i = 0; same && i < 16; i++) if (scratchKey[i] !== viewProj[i]) same = false;
+  if (!same) {
+    mat4.copy(scratchKey, viewProj);
+    invValid = mat4.invert(scratchInv, viewProj) !== null;
+  }
+  return scratchInv;
+}
+function worldToScreen(world, camera, point, out) {
+  const cam = world.tryResource(Cameras)?.get(camera);
+  if (!cam) return false;
+  const m = cam.viewProjNoJitter;
+  const x = point[0];
+  const y = point[1];
+  const z = point[2];
+  const cx = m[0] * x + m[4] * y + m[8] * z + m[12];
+  const cy = m[1] * x + m[5] * y + m[9] * z + m[13];
+  const cw = m[3] * x + m[7] * y + m[11] * z + m[15];
+  if (cw <= 1e-9) return false;
+  const width = cam.displayWidth / cam.pixelRatio;
+  const height = cam.displayHeight / cam.pixelRatio;
+  out[0] = (cx / cw * 0.5 + 0.5) * width;
+  out[1] = (0.5 - cy / cw * 0.5) * height;
+  return true;
+}
+function screenToRay(world, camera, x, y, outOrigin, outDir) {
+  const cam = world.tryResource(Cameras)?.get(camera);
+  if (!cam) {
+    outOrigin[0] = outOrigin[1] = outOrigin[2] = 0;
+    outDir[0] = outDir[1] = 0;
+    outDir[2] = -1;
+    return;
+  }
+  const inv = inverse(cam.viewProjNoJitter);
+  const nx = x / (cam.displayWidth / cam.pixelRatio) * 2 - 1;
+  const ny = 1 - y / (cam.displayHeight / cam.pixelRatio) * 2;
+  let px = 0;
+  let py = 0;
+  let pz = 0;
+  for (let k = 0; k < 2; k++) {
+    const d = k === 0 ? 1 : 0.5;
+    const wx = inv[0] * nx + inv[4] * ny + inv[8] * d + inv[12];
+    const wy = inv[1] * nx + inv[5] * ny + inv[9] * d + inv[13];
+    const wz = inv[2] * nx + inv[6] * ny + inv[10] * d + inv[14];
+    const ww = inv[3] * nx + inv[7] * ny + inv[11] * d + inv[15];
+    if (k === 0) {
+      px = wx / ww;
+      py = wy / ww;
+      pz = wz / ww;
+    } else {
+      const dx = wx / ww - px;
+      const dy = wy / ww - py;
+      const dz = wz / ww - pz;
+      const len = Math.sqrt(dx * dx + dy * dy + dz * dz) || 1;
+      outDir[0] = dx / len;
+      outDir[1] = dy / len;
+      outDir[2] = dz / len;
+    }
+  }
+  outOrigin[0] = px;
+  outOrigin[1] = py;
+  outOrigin[2] = pz;
+}
+const rayOrigin = new Float64Array(3);
+const rayDir = new Float64Array(3);
+function screenToPlane(world, camera, x, y, planeY, out) {
+  screenToRay(world, camera, x, y, rayOrigin, rayDir);
+  const dy = rayDir[1];
+  if (Math.abs(dy) < 1e-9) return false;
+  const t = (planeY - rayOrigin[1]) / dy;
+  if (t < 0) return false;
+  out[0] = rayOrigin[0] + rayDir[0] * t;
+  out[1] = planeY;
+  out[2] = rayOrigin[2] + rayDir[2] * t;
+  return true;
+}
+export {
+  screenToPlane,
+  screenToRay,
+  worldToScreen
+};

package/dist/readback.d.ts

@@ -1,4 +1,5 @@
 /** Readback helpers: bytes per texel and conversion of any readable format to floats. */
 export declare const BYTES_PER_TEXEL: Partial<Record<GPUTextureFormat, number>>;
+export declare function halfToFloat(h: number): number;
 /** Unpacks a readback row of any supported format into 4 floats per pixel. */
 export declare function toFloats(src: ArrayBuffer, format: GPUTextureFormat, count: number, out: Float32Array, o: number): void;

package/dist/readback.js

@@ -91,5 +91,6 @@ function small(v, mantissaBits) {
 }
 export {
   BYTES_PER_TEXEL,
+  halfToFloat,
   toFloats
 };

package/dist/render-scale.js

@@ -2,6 +2,7 @@ import { defineResource } from "@aethervtt/shard-core";
 import { DisplayRate } from "@aethervtt/shard-runtime";
 import { Views } from "./plugin.js";
 const RenderScale = defineResource("render/RenderScale", {
+  hostWritable: true,
   description: "Render resolution of window cameras (0051): the scene renders at scale \xD7 the window size and is upscaled, UI stays native. auto moves the scale between min and max to hold the frame budget: targetMs, or one display refresh (DisplayRate) when it is 0.",
   init: () => ({
     mode: "auto",

package/dist/screen-effects.d.ts

@@ -0,0 +1,97 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+/** Effects `ScreenEffects` holds at once. */
+export declare const MAX_SCREEN_EFFECTS = 8;
+/** Keys an effect's params may have. */
+export declare const MAX_SCREEN_EFFECT_PARAMS = 8;
+export type ScreenEffectParams = Record<string, number | string | boolean>;
+/** An effect another app's view should draw at a screen point (0065). */
+export interface ScreenEffect {
+    /** What to draw: `fire`, or a kind the consuming app registered. */
+    kind: string;
+    /** Center, in the target's CSS pixels. */
+    screen: [number, number];
+    /** In CSS pixels. */
+    radius: 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); one effect per (source, kind). */
+    source: Entity;
+    params: ScreenEffectParams;
+}
+export declare const ScreenEffects: import("@aethervtt/shard-core").ResourceDef<{
+    effects: ScreenEffect[];
+}>;
+/** What an app draws for one kind of screen effect. */
+export interface ScreenEffectHandler {
+    /** An effect of this kind appeared (a new source): spawn what draws it. */
+    start(world: World, effect: ScreenEffect): Entity[] | undefined;
+    /** Each frame it stays live (refreshed), with the frame's seconds. */
+    update?(world: World, effect: ScreenEffect, entities: readonly Entity[], dt: number): void;
+    /** It expired or was cleared. Default: despawn what `start` returned. */
+    end?(world: World, effect: ScreenEffect, entities: readonly Entity[]): void;
+}
+interface LiveEffect {
+    source: Entity;
+    kind: string;
+    handler: ScreenEffectHandler;
+    entities: Entity[];
+    /** The effect as last seen, for `end`. */
+    last: ScreenEffect;
+    seen: boolean;
+}
+/** This app's handlers, the effects they're drawing, and the unhandled kinds already reported. */
+export declare const ScreenEffectHandlers: import("@aethervtt/shard-core").ResourceDef<{
+    kinds: Map<string, ScreenEffectHandler>;
+    live: LiveEffect[];
+    reported: Set<string>;
+}>;
+/**
+ * Publishes or refreshes `source`'s effect of this kind. Returns false when `MAX_SCREEN_EFFECTS`
+ * others are live. Throws `render/invalid-screen-effect` for an effect without a kind, a negative
+ * radius, or more than 8 params.
+ */
+export declare function publishScreenEffect(world: World, effect: ScreenEffect): boolean;
+/** Drops `source`'s effects, or every effect. Publishers call it on dismissal and teardown. */
+export declare function clearScreenEffects(world: World, source?: Entity): void;
+/**
+ * Copies `from`'s effects into `to` (another app on the device, 0052), for the host to call each
+ * frame, as `forwardLensFields`: copies, each app counting its own down; `offset` is where `to`'s
+ * target sits in `from`'s CSS pixels, subtracted from each center.
+ */
+export declare function forwardScreenEffects(from: World, to: World, offset?: readonly [number, number]): void;
+/**
+ * Registers what this app draws for a kind of screen effect: `start` when one appears, `update`
+ * while it's refreshed, `end` when it expires (default: despawn what `start` returned).
+ */
+export declare function onScreenEffect(world: World, kind: string, handler: ScreenEffectHandler): void;
+/** The frame demand live effects hold, so they expire on time and the app idles after (0052). */
+export declare const SCREEN_EFFECTS_DEMAND = "render/screen-effects";
+export declare const expireScreenEffects: import("@aethervtt/shard-core").SystemDef<undefined>;
+/**
+ * Starts, updates and ends this app's handlers as effects appear, stay and go. An effect of a kind
+ * nobody registered is dropped and logged once per kind (`render/unhandled-screen-effect`).
+ * Allocates only when an effect starts.
+ */
+export declare const runScreenEffects: import("@aethervtt/shard-core").SystemDef<undefined>;
+/** For render.describe: live effects, and which kinds this app draws. */
+export declare function describeScreenEffects(world: World): {
+    effects: {
+        /** What to draw: `fire`, or a kind the consuming app registered. */
+        kind: string;
+        /** In CSS pixels. */
+        radius: 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); one effect per (source, kind). */
+        source: Entity;
+        params: ScreenEffectParams;
+        screen: number[];
+    }[];
+    kinds: string[];
+    drawing: {
+        kind: string;
+        source: number;
+        entities: number;
+    }[];
+};
+export {};