@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/scenario.js

@@ -0,0 +1,125 @@
+import { spanCovers, spanName } from "@aethervtt/shard-core";
+import {
+  budget,
+  passTiming,
+  scenarioSlices,
+  timingMode
+} from "@aethervtt/shard-core/test-env";
+import { capturePerf } from "@aethervtt/shard-runtime";
+import { ablatePasses } from "./ablation.js";
+import { Graph } from "./plugin.js";
+function p95Of(values) {
+  const sorted = Array.from(values).sort((a, b) => a - b);
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * 0.95))];
+}
+async function measureScenario(world, name, options) {
+  const keys = scenarioSlices(name);
+  let i = 0;
+  const { summary, capture } = await capturePerf(world, {
+    frames: options.frames,
+    write: false,
+    trace: false,
+    keep: true,
+    step: async () => {
+      await options.step(Math.min(i, options.frames - 1));
+      i++;
+    }
+  });
+  if (!capture) throw new Error("capturePerf kept no capture");
+  const seen = /* @__PURE__ */ new Set();
+  for (let e = 0; e < capture.eventCount; e++) seen.add(capture.events.ids[e]);
+  const spans = [...seen].map(spanName).sort();
+  const gpuFrame = capture.spanTime("gpu:frame");
+  const timedFrames = [];
+  for (let f = 0; f < gpuFrame.length; f++) if (gpuFrame[f] > 0) timedFrames.push(f);
+  const gpuTimed = timedFrames.length > 0;
+  const slices = [];
+  for (const track of ["gpu", "cpu"]) {
+    for (const key of keys[track]) {
+      const perFrame = capture.spanTime(key);
+      const values = track === "gpu" ? timedFrames.map((f) => perFrame[f]) : perFrame;
+      slices.push({
+        key,
+        track,
+        covers: spans.filter((s) => spanCovers(key, s)),
+        perFrame,
+        p95: p95Of(values),
+        measuredBy: "capture"
+      });
+    }
+  }
+  if ((options.ablation?.force || passTiming() === "ablation") && gpuTimed) {
+    const graph = world.resource(Graph);
+    const nodes = graph.nodeNames();
+    const groups = {};
+    for (const s of slices) {
+      if (s.track !== "gpu") continue;
+      const covered = nodes.filter((n) => spanCovers(s.key, `gpu:${n}`));
+      if (covered.length > 0) groups[s.key] = covered;
+    }
+    const passes = Object.keys(groups);
+    if (passes.length > 0) {
+      const result = await ablatePasses(
+        world,
+        {
+          passes,
+          groups,
+          frames: options.ablation?.frames ?? 60,
+          rounds: options.ablation?.rounds ?? 3
+        },
+        () => options.step(options.frames - 1)
+      );
+      for (const cost of result.passes) {
+        const s = slices.find((x) => x.track === "gpu" && x.key === cost.pass);
+        s.p95 = Math.max(0, cost.ms);
+        s.measuredBy = "ablation";
+        s.noise = (Math.max(...cost.rounds) - Math.min(...cost.rounds)) / 2;
+      }
+    }
+  }
+  return {
+    name,
+    summary,
+    capture,
+    spans,
+    frame: {
+      cpu: capture.frames.cpu,
+      gpu: gpuFrame,
+      cpuP95: p95Of(capture.frames.cpu),
+      gpuP95: p95Of(timedFrames.map((f) => gpuFrame[f]))
+    },
+    gpuTimed,
+    slices
+  };
+}
+function expectScenario(run, expect) {
+  expect(run.summary.frames.count).toBe(run.capture.frameCount);
+  expect(run.capture.frameCount).toBeGreaterThan(0);
+  for (const s of run.slices) {
+    if (s.track === "gpu" && !run.gpuTimed) continue;
+    expect(s.covers, `${run.name}: slice "${s.key}" covers no span that ran`).not.toEqual([]);
+  }
+  if (timingMode !== "bench") return;
+  const soft = expect.soft;
+  soft(run.frame.cpuP95, `${run.name}: CPU frame p95`).toBeLessThan(
+    budget(`${run.name}`, { track: "cpu" })
+  );
+  if (run.gpuTimed) {
+    soft(run.frame.gpuP95, `${run.name}: GPU frame p95`).toBeLessThan(
+      budget(`${run.name}`, { track: "gpu" })
+    );
+  }
+  for (const s of run.slices) {
+    if (s.track === "gpu" && !run.gpuTimed) continue;
+    const measured = s.noise === void 0 ? s.p95 : Math.max(0, s.p95 - s.noise);
+    const how = s.noise === void 0 ? s.measuredBy : `ablation, ${s.p95.toFixed(3)} \xB1 ${s.noise.toFixed(3)} ms`;
+    soft(measured, `${run.name}: ${s.track} slice ${s.key} p95 (${how})`).toBeLessThan(
+      budget(`${run.name}`, { slice: s.key, track: s.track })
+    );
+  }
+}
+export {
+  expectScenario,
+  measureScenario
+};

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 {};

package/dist/screen-effects.js

@@ -0,0 +1,192 @@
+import {
+  defineResource,
+  defineSystem,
+  ShardError
+} from "@aethervtt/shard-core";
+import { FrameDemand, LogResource, Time } from "@aethervtt/shard-runtime";
+const MAX_SCREEN_EFFECTS = 8;
+const MAX_SCREEN_EFFECT_PARAMS = 8;
+const ScreenEffects = defineResource("render/ScreenEffects", {
+  hostWritable: true,
+  description: "Typed effects published at a screen point (at most 8): kind, center and radius in CSS pixels, ms to live, source entity, params. The app whose view they are in draws them through handlers registered with onScreenEffect.",
+  init: () => ({ effects: [] })
+});
+const ScreenEffectHandlers = defineResource("render/ScreenEffectHandlers", {
+  description: "Handlers by kind (onScreenEffect) and the screen effects they are drawing.",
+  init: () => ({ kinds: /* @__PURE__ */ new Map(), live: [], reported: /* @__PURE__ */ new Set() })
+});
+function invalid(message, path) {
+  return new ShardError("render/invalid-screen-effect", message, {
+    path,
+    hint: "A screen effect has a kind, a radius of at least 0, and at most 8 params."
+  });
+}
+function publishScreenEffect(world, effect) {
+  if (!effect.kind) throw invalid("A screen effect needs a kind", "kind");
+  if (!(effect.radius >= 0)) throw invalid(`Radius ${effect.radius} is below 0`, "radius");
+  const keys = Object.keys(effect.params);
+  if (keys.length > MAX_SCREEN_EFFECT_PARAMS) {
+    throw invalid(`${keys.length} params; at most ${MAX_SCREEN_EFFECT_PARAMS}`, "params");
+  }
+  const effects = world.initResource(ScreenEffects).effects;
+  let i = 0;
+  while (i < effects.length && (effects[i].source !== effect.source || effects[i].kind !== effect.kind))
+    i++;
+  if (i === MAX_SCREEN_EFFECTS) return false;
+  const e = effects[i];
+  if (e) {
+    e.screen[0] = effect.screen[0];
+    e.screen[1] = effect.screen[1];
+    e.radius = effect.radius;
+    e.ttlMs = effect.ttlMs;
+    e.params = effect.params;
+  } else effects.push({ ...effect, screen: [effect.screen[0], effect.screen[1]] });
+  world.touchResource(ScreenEffects);
+  return true;
+}
+function clearScreenEffects(world, source) {
+  const value = world.tryResource(ScreenEffects);
+  if (!value || value.effects.length === 0) return;
+  if (source === void 0) value.effects.length = 0;
+  else value.effects = value.effects.filter((e) => e.source !== source);
+  world.touchResource(ScreenEffects);
+}
+const NO_OFFSET = [0, 0];
+function forwardScreenEffects(from, to, offset = NO_OFFSET) {
+  const source = from.tryResource(ScreenEffects)?.effects ?? [];
+  const out = to.initResource(ScreenEffects).effects;
+  const n = Math.min(source.length, MAX_SCREEN_EFFECTS);
+  for (let i = 0; i < n; i++) {
+    const s = source[i];
+    const d = out[i];
+    if (d) {
+      d.kind = s.kind;
+      d.radius = s.radius;
+      d.ttlMs = s.ttlMs;
+      d.source = s.source;
+      d.params = s.params;
+    } else out.push({ ...s, screen: [0, 0] });
+    const e = out[i];
+    e.screen[0] = s.screen[0] - offset[0];
+    e.screen[1] = s.screen[1] - offset[1];
+  }
+  if (out.length === 0 && n === 0) return;
+  out.length = n;
+  to.touchResource(ScreenEffects);
+}
+function onScreenEffect(world, kind, handler) {
+  world.initResource(ScreenEffectHandlers).kinds.set(kind, handler);
+}
+const SCREEN_EFFECTS_DEMAND = "render/screen-effects";
+const expireScreenEffects = defineSystem({
+  name: "render/expire-screen-effects",
+  description: "Counts ScreenEffects down by the frame time and drops expired ones; holds frames while any live.",
+  run: (_, world) => {
+    const effects = world.tryResource(ScreenEffects)?.effects;
+    let n = 0;
+    if (effects && effects.length > 0) {
+      const ms = world.resource(Time).delta * 1e3;
+      for (let i = 0; i < effects.length; i++) {
+        const e = effects[i];
+        e.ttlMs -= ms;
+        if (e.ttlMs > 0 && n < MAX_SCREEN_EFFECTS) effects[n++] = e;
+      }
+      effects.length = n;
+    }
+    const live = world.tryResource(ScreenEffectHandlers)?.live.length ?? 0;
+    world.tryResource(FrameDemand)?.set(SCREEN_EFFECTS_DEMAND, n > 0 || live > 0);
+  }
+});
+function despawnAll(world, entities) {
+  for (const e of entities) if (world.isAlive(e)) world.despawn(e);
+}
+const runScreenEffects = defineSystem({
+  name: "render/screen-effects",
+  description: "Runs the handlers registered with onScreenEffect for live ScreenEffects.",
+  run: (_, world) => {
+    const handlers = world.tryResource(ScreenEffectHandlers);
+    const effects = world.tryResource(ScreenEffects)?.effects;
+    if (!handlers || handlers.live.length === 0 && (!effects || effects.length === 0)) return;
+    const live = handlers.live;
+    for (let i = 0; i < live.length; i++) live[i].seen = false;
+    const dt = world.resource(Time).delta;
+    if (effects) {
+      for (let i = 0; i < effects.length; i++) {
+        const e = effects[i];
+        let found;
+        for (let j = 0; j < live.length; j++) {
+          const l = live[j];
+          if (l.source === e.source && l.kind === e.kind) {
+            found = l;
+            break;
+          }
+        }
+        if (found) {
+          found.seen = true;
+          found.last = e;
+          found.handler.update?.(world, e, found.entities, dt);
+          continue;
+        }
+        const handler = handlers.kinds.get(e.kind);
+        if (!handler) {
+          if (!handlers.reported.has(e.kind)) {
+            handlers.reported.add(e.kind);
+            world.tryResource(LogResource)?.log("warn", `No handler draws "${e.kind}" effects`, {
+              code: "render/unhandled-screen-effect",
+              hint: "Register one in this app with onScreenEffect(world, kind, handler)."
+            });
+          }
+          continue;
+        }
+        live.push({
+          source: e.source,
+          kind: e.kind,
+          handler,
+          entities: handler.start(world, e) ?? [],
+          last: e,
+          seen: true
+        });
+      }
+    }
+    let kept = 0;
+    for (let i = 0; i < live.length; i++) {
+      const l = live[i];
+      if (l.seen) {
+        live[kept++] = l;
+        continue;
+      }
+      if (l.handler.end) l.handler.end(world, l.last, l.entities);
+      else despawnAll(world, l.entities);
+    }
+    live.length = kept;
+  }
+});
+function describeScreenEffects(world) {
+  const handlers = world.tryResource(ScreenEffectHandlers);
+  return {
+    effects: (world.tryResource(ScreenEffects)?.effects ?? []).map((e) => ({
+      ...e,
+      screen: [...e.screen]
+    })),
+    kinds: handlers ? [...handlers.kinds.keys()].sort() : [],
+    drawing: (handlers?.live ?? []).map((l) => ({
+      kind: l.kind,
+      source: l.source,
+      entities: l.entities.length
+    }))
+  };
+}
+export {
+  MAX_SCREEN_EFFECTS,
+  MAX_SCREEN_EFFECT_PARAMS,
+  SCREEN_EFFECTS_DEMAND,
+  ScreenEffectHandlers,
+  ScreenEffects,
+  clearScreenEffects,
+  describeScreenEffects,
+  expireScreenEffects,
+  forwardScreenEffects,
+  onScreenEffect,
+  publishScreenEffect,
+  runScreenEffects
+};

package/dist/shaders.d.ts

@@ -25,6 +25,12 @@ export declare const ViewUniform: import("@aethervtt/shard-core").ComponentDef<{
      * that sun, applied to its light (spec 0044). All ones without an atmosphere.
      */
     readonly sunTransmittance: import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]> | undefined) => import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32">);
+    /**
+     * Screen scale (0057): render pixels per CSS pixel (x); world units per render pixel at one
+     * unit of view depth, or everywhere when orthographic (y); 1 when orthographic (z). A CSS-pixel
+     * width w at view depth d is w · x · y · d world units (w · x · y orthographic).
+     */
+    readonly pixelScale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<import("@aethervtt/shard-core").Vec4> | undefined) => import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">);
 }>;
 export declare const viewLayout: import("@aethervtt/shard-shader").WgslLayout<{
     readonly viewProj: import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]> | undefined) => import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32">);
@@ -51,6 +57,12 @@ export declare const viewLayout: import("@aethervtt/shard-shader").WgslLayout<{
      * that sun, applied to its light (spec 0044). All ones without an atmosphere.
      */
     readonly sunTransmittance: import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number]> | undefined) => import("@aethervtt/shard-core").FieldType<[number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number], "f32">);
+    /**
+     * Screen scale (0057): render pixels per CSS pixel (x); world units per render pixel at one
+     * unit of view depth, or everywhere when orthographic (y); 1 when orthographic (z). A CSS-pixel
+     * width w at view depth d is w · x · y · d world units (w · x · y orthographic).
+     */
+    readonly pixelScale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32"> & ((options?: import("@aethervtt/shard-core").FieldOptions<import("@aethervtt/shard-core").Vec4> | undefined) => import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec4, "f32">);
 }>;
 export declare const materialLayout: import("@aethervtt/shard-shader").WgslLayout<{
     baseColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
@@ -59,6 +71,7 @@ export declare const materialLayout: import("@aethervtt/shard-shader").WgslLayou
     emissive: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
     emissiveLuminance: import("@aethervtt/shard-core").FieldType<number, "f32">;
     doubleSided: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    deferUntilReady: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
     alphaMode: import("@aethervtt/shard-core").FieldType<"additive" | "alpha" | "mask" | "opaque" | "premultiplied", "u8">;
     alphaCutoff: import("@aethervtt/shard-core").FieldType<number, "f32">;
     normalScale: import("@aethervtt/shard-core").FieldType<number, "f32">;