@aethervtt/shard-render 0.0.1

package/dist/overlays.js

@@ -0,0 +1,344 @@
+import {
+  defineResource,
+  defineSystem,
+  findComponent
+} from "@aethervtt/shard-core";
+import { GlobalTransform, GridFramesResource } from "@aethervtt/shard-transform";
+import { ForwardStateResource } from "./forward.js";
+import { Gizmos } from "./gizmos.js";
+import {
+  INSTANCE_FLOATS,
+  InstanceFlags,
+  InstanceSlot,
+  Instances
+} from "./instances.js";
+import { DirectionalLight, Lights } from "./lights.js";
+import { defineOverlay, OVERLAYS, registeredOverlays } from "./overlay-registry.js";
+const extraOverlays = registeredOverlays();
+import { Views } from "./plugin.js";
+import { Cameras, cameraOf } from "./view.js";
+import {
+  allOverlays,
+  defineOverlay as defineOverlay2,
+  OVERLAYS as OVERLAYS2,
+  overlayNames
+} from "./overlay-registry.js";
+function isOverlayOn(o, name) {
+  return OVERLAYS.includes(name) ? o[name] : o.extra[name] === true;
+}
+let memberDef;
+function scenePath(world, entity) {
+  if (!memberDef) memberDef = findComponent("scene/SceneMember") ?? null;
+  if (!memberDef) return void 0;
+  const v = world.tryGet(entity, memberDef);
+  return v?.path || void 0;
+}
+const DebugOverlays = defineResource("render/DebugOverlays", {
+  description: "Built-in debug drawings, each drawn through Gizmos: bounds, light volumes, camera frustums, shadow cascades, normals, transform axes, and entity labels.",
+  init: () => ({
+    bounds: false,
+    lights: false,
+    cameras: false,
+    cascades: false,
+    normals: false,
+    axes: false,
+    labels: false,
+    extra: {},
+    filter: { components: [], path: "" },
+    name: scenePath
+  })
+});
+function setOverlays(world, on, filter) {
+  const o = world.resource(DebugOverlays);
+  for (const name of OVERLAYS) if (on[name] !== void 0) o[name] = on[name];
+  for (const name of extraOverlays.keys()) if (on[name] !== void 0) o.extra[name] = on[name];
+  if (filter) {
+    if (filter.components) o.filter.components = filter.components;
+    if (filter.path !== void 0) o.filter.path = filter.path;
+  }
+  return o;
+}
+const BOUNDS = [0.2, 0.9, 1, 1];
+const LIGHT = [1, 0.85, 0.3, 1];
+const CAMERA = [0.9, 0.9, 0.9, 1];
+const CASCADE = [
+  [1, 0.3, 0.3, 1],
+  [0.3, 1, 0.3, 1],
+  [0.3, 0.5, 1, 1],
+  [1, 1, 0.3, 1]
+];
+const NORMAL = [0.4, 0.6, 1, 1];
+const AXES = [
+  [1, 0.2, 0.2, 1],
+  [0.2, 1, 0.2, 1],
+  [0.3, 0.5, 1, 1]
+];
+const LABEL = [1, 1, 1, 1];
+const AXES_WIDTH = { width: 2 };
+const NORMALS_PER_MESH = 1500;
+const a = new Float32Array(3);
+const b = new Float32Array(3);
+function passes(world, o, entity, defs) {
+  for (const def of defs) if (!world.has(entity, def)) return false;
+  if (o.filter.path) {
+    const name = o.name(world, entity);
+    if (!name?.startsWith(o.filter.path)) return false;
+  }
+  return true;
+}
+function slotMesh(store, slot) {
+  const batch = store.batchOf[slot];
+  if (batch >= 0) return store.batches[batch].mesh;
+  if (batch <= -2) {
+    const set = store.lodSets[-2 - batch];
+    return store.batches[set.batches[0]]?.mesh;
+  }
+  return void 0;
+}
+function drawInstances(world, o, g, defs) {
+  const store = world.tryResource(Instances);
+  if (!store) return;
+  const f = store.f32;
+  const u = store.u32;
+  for (let slot = 0; slot < store.high; slot++) {
+    if ((store.flags[slot] & InstanceFlags.Visible) === 0) continue;
+    const mesh = slotMesh(store, slot);
+    if (!mesh) continue;
+    const entity = u[slot * INSTANCE_FLOATS + 15];
+    if (!passes(world, o, entity, defs)) continue;
+    const off = slot * INSTANCE_FLOATS;
+    const bb = mesh.bounds;
+    if (o.bounds) g.bounds(bb, f, off, BOUNDS);
+    if (o.labels) {
+      const cx = (bb[0] + bb[3]) / 2;
+      const cy = (bb[1] + bb[4]) / 2;
+      const cz = (bb[2] + bb[5]) / 2;
+      const hy = (Math.abs(f[off + 4]) * (bb[3] - bb[0]) + Math.abs(f[off + 5]) * (bb[4] - bb[1]) + Math.abs(f[off + 6]) * (bb[5] - bb[2])) / 2;
+      a[0] = f[off] * cx + f[off + 1] * cy + f[off + 2] * cz + f[off + 3];
+      a[1] = f[off + 4] * cx + f[off + 5] * cy + f[off + 6] * cz + f[off + 7] + hy;
+      a[2] = f[off + 8] * cx + f[off + 9] * cy + f[off + 10] * cz + f[off + 11];
+      g.label(a, o.name(world, entity) ?? `#${entity}`, LABEL);
+    }
+    if (o.normals && mesh.normals && mesh.normals.length === mesh.positions.length) {
+      const n = mesh.positions.length / 3;
+      const step = Math.max(1, Math.ceil(n / NORMALS_PER_MESH));
+      const p = mesh.positions;
+      const nn = mesh.normals;
+      const len = Math.max(bb[3] - bb[0], bb[4] - bb[1], bb[5] - bb[2]) * 0.08;
+      for (let v = 0; v < n; v += step) {
+        const x = p[v * 3];
+        const y = p[v * 3 + 1];
+        const z = p[v * 3 + 2];
+        for (let r = 0; r < 3; r++) {
+          const ro = off + r * 4;
+          a[r] = f[ro] * x + f[ro + 1] * y + f[ro + 2] * z + f[ro + 3];
+          b[r] = f[ro] * nn[v * 3] + f[ro + 1] * nn[v * 3 + 1] + f[ro + 2] * nn[v * 3 + 2];
+        }
+        const bl = Math.sqrt(b[0] * b[0] + b[1] * b[1] + b[2] * b[2]) || 1;
+        for (let r = 0; r < 3; r++) b[r] = a[r] + b[r] / bl * len;
+        g.line(a, b, NORMAL);
+      }
+    }
+  }
+}
+function drawLights(world, o, g, defs) {
+  const lights = world.tryResource(Lights);
+  if (lights) {
+    for (const r of lights.records) {
+      if (!r.alive || !passes(world, o, r.entity, defs)) continue;
+      a[0] = r.x;
+      a[1] = r.y;
+      a[2] = r.z;
+      if (r.kind === 0) {
+        g.sphere(a, r.range, LIGHT);
+        continue;
+      }
+      const rim = Math.tan(r.outerAngle * Math.PI / 180) * r.range;
+      const ex = r.x + r.dx * r.range;
+      const ey = r.y + r.dy * r.range;
+      const ez = r.z + r.dz * r.range;
+      const hx = Math.abs(r.dy) < 0.9 ? 0 : 1;
+      const hy = Math.abs(r.dy) < 0.9 ? 1 : 0;
+      let ux = hy * r.dz;
+      let uy = -hx * r.dz;
+      let uz = hx * r.dy - hy * r.dx;
+      const ul = Math.sqrt(ux * ux + uy * uy + uz * uz) || 1;
+      ux /= ul;
+      uy /= ul;
+      uz /= ul;
+      const vx = r.dy * uz - r.dz * uy;
+      const vy = r.dz * ux - r.dx * uz;
+      const vz = r.dx * uy - r.dy * ux;
+      const SEG = 24;
+      for (let i = 0; i < SEG; i++) {
+        const t0 = i / SEG * Math.PI * 2;
+        const t1 = (i + 1) / SEG * Math.PI * 2;
+        const c0 = Math.cos(t0) * rim;
+        const s0 = Math.sin(t0) * rim;
+        const c1 = Math.cos(t1) * rim;
+        const s1 = Math.sin(t1) * rim;
+        b[0] = ex + ux * c0 + vx * s0;
+        b[1] = ey + uy * c0 + vy * s0;
+        b[2] = ez + uz * c0 + vz * s0;
+        if (i % 6 === 0) g.line(a, b, LIGHT);
+        a[0] = ex + ux * c1 + vx * s1;
+        a[1] = ey + uy * c1 + vy * s1;
+        a[2] = ez + uz * c1 + vz * s1;
+        g.line(b, a, LIGHT);
+        a[0] = r.x;
+        a[1] = r.y;
+        a[2] = r.z;
+      }
+    }
+  }
+  for (const table of world.query({ with: [DirectionalLight, GlobalTransform] }).tables) {
+    const m = table.column(GlobalTransform, "matrix");
+    for (let i = 0; i < table.count; i++) {
+      if (!passes(world, o, table.entities[i], defs)) continue;
+      const off = i * 12;
+      a[0] = m[off + 3];
+      a[1] = m[off + 7];
+      a[2] = m[off + 11];
+      b[0] = a[0] - m[off + 2] * 2;
+      b[1] = a[1] - m[off + 6] * 2;
+      b[2] = a[2] - m[off + 10] * 2;
+      g.arrow(a, b, LIGHT);
+    }
+  }
+}
+function primaryCamera(world) {
+  let best;
+  let order = Number.POSITIVE_INFINITY;
+  for (const view of world.resource(Views).list) {
+    const cam = cameraOf(view);
+    if (cam && view.order < order) {
+      order = view.order;
+      best = cam.entity;
+    }
+  }
+  return best;
+}
+const drawOverlays = defineSystem({
+  name: "render/debug-overlays",
+  run: (_, world) => {
+    const o = world.resource(DebugOverlays);
+    const g = world.resource(Gizmos);
+    g.overlay.clear();
+    let extra = false;
+    for (const name in o.extra) if (o.extra[name] && extraOverlays.has(name)) extra = true;
+    if (!(o.bounds || o.lights || o.cameras || o.cascades || o.normals || o.axes || o.labels || extra))
+      return;
+    g.beginOverlays();
+    try {
+      draw(world, o, g);
+    } finally {
+      g.endOverlays();
+    }
+  }
+});
+function draw(world, o, g) {
+  {
+    const defs = [];
+    for (const name of o.filter.components) {
+      const def = findComponent(name);
+      if (def) defs.push(def);
+    }
+    if (o.bounds || o.labels || o.normals) drawInstances(world, o, g, defs);
+    for (const [name, def] of extraOverlays) {
+      if (o.extra[name]) def.draw(world, g, (entity) => passes(world, o, entity, defs));
+    }
+    if (o.lights) drawLights(world, o, g, defs);
+    const primary = primaryCamera(world);
+    if (o.cameras) {
+      for (const [entity, cam] of world.resource(Cameras)) {
+        if (entity === primary || !passes(world, o, entity, defs)) continue;
+        g.frustum(cam.viewProjNoJitter, CAMERA);
+      }
+    }
+    if (o.cascades && primary !== void 0) {
+      const pv = world.tryResource(ForwardStateResource)?.views.get(`camera:${primary}`);
+      if (pv) {
+        for (let i = 0; i < pv.cascades.count; i++) {
+          g.frustum(pv.cascades.views[i].viewProj, CASCADE[i % CASCADE.length]);
+        }
+      }
+    }
+    if (o.axes || o.labels) {
+      for (const table of world.query({ with: [GlobalTransform] }).tables) {
+        const m = table.column(GlobalTransform, "matrix");
+        const meshed = table.has(InstanceSlot);
+        for (let i = 0; i < table.count; i++) {
+          const entity = table.entities[i];
+          if (!passes(world, o, entity, defs)) continue;
+          const off = i * 12;
+          a[0] = m[off + 3];
+          a[1] = m[off + 7];
+          a[2] = m[off + 11];
+          if (o.axes) {
+            for (let k = 0; k < 3; k++) {
+              b[0] = a[0] + m[off + k];
+              b[1] = a[1] + m[off + 4 + k];
+              b[2] = a[2] + m[off + 8 + k];
+              g.line(a, b, AXES[k], AXES_WIDTH);
+            }
+          }
+          if (o.labels && !meshed) {
+            const name = o.name(world, entity);
+            if (name) g.label(a, name, LABEL);
+          }
+        }
+      }
+    }
+  }
+}
+const GRID_CELL = [0.3, 1, 0.5, 1];
+const NEIGHBOR = [0.3, 0.6, 1, 0.45];
+const ga = new Float32Array(3);
+const gb = new Float32Array(3);
+const GRID_LINE = { width: 1.5 };
+const CELL_LINE = { width: 2.5 };
+const gridsOverlay = defineOverlay({
+  name: "grids",
+  description: "Large worlds: the floating origin's cell (bright) and its neighbors' edges, in the origin grid.",
+  draw: (world, g) => {
+    const frames = world.tryResource(GridFramesResource);
+    if (!frames?.active || frames.originSlot === 0) return;
+    const cs = frames.cellSize[frames.originSlot];
+    if (!(cs > 0)) return;
+    const h = cs / 2;
+    for (let axis = 0; axis < 3; axis++) {
+      const u = (axis + 1) % 3;
+      const v = (axis + 2) % 3;
+      for (let i = 0; i < 4; i++) {
+        for (let j = 0; j < 4; j++) {
+          const pu = (i - 1.5) * cs;
+          const pv = (j - 1.5) * cs;
+          ga[axis] = -3 * h;
+          gb[axis] = 3 * h;
+          ga[u] = gb[u] = pu;
+          ga[v] = gb[v] = pv;
+          g.line(ga, gb, NEIGHBOR, GRID_LINE);
+        }
+      }
+      for (let k = 0; k < 4; k++) {
+        ga[axis] = -h;
+        gb[axis] = h;
+        ga[u] = gb[u] = k & 1 ? h : -h;
+        ga[v] = gb[v] = k & 2 ? h : -h;
+        g.line(ga, gb, GRID_CELL, CELL_LINE);
+      }
+    }
+  }
+});
+export {
+  DebugOverlays,
+  OVERLAYS2 as OVERLAYS,
+  allOverlays,
+  defineOverlay2 as defineOverlay,
+  drawOverlays,
+  gridsOverlay,
+  isOverlayOn,
+  overlayNames,
+  setOverlays,
+  slotMesh
+};

package/dist/paths.d.ts

@@ -0,0 +1,20 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+/**
+ * An entity's name: the last segment of its scene path (`scene/SceneMember`) or instance path
+ * (`scene/InstancePart`). Undefined for entities made in code without either. Cold path: allocates.
+ */
+export declare function entityName(world: World, entity: Entity): string | undefined;
+/**
+ * Every descendant of `root` by path relative to it (`Armature/Hips/Spine`), plus `''` for the root
+ * itself. Entities without a name (and their subtrees) are left out. Cold path: allocates.
+ */
+export declare function descendantPaths(world: World, root: Entity): Map<string, Entity>;
+/**
+ * Resolves paths relative to a model root, looking for that root among `entity` and its
+ * ancestors: the nearest one under which `probe` (a path every root has, like a skin's first joint)
+ * exists. Returns the root and its paths, or undefined. Cold path: allocates.
+ */
+export declare function findModelRoot(world: World, entity: Entity, probe: string): {
+    root: Entity;
+    paths: Map<string, Entity>;
+} | undefined;

package/dist/paths.js

@@ -0,0 +1,46 @@
+import {
+  ChildOf,
+  Children,
+  findComponent
+} from "@aethervtt/shard-core";
+let memberDef;
+let partDef;
+function entityName(world, entity) {
+  if (!memberDef) memberDef = findComponent("scene/SceneMember") ?? null;
+  if (!partDef) partDef = findComponent("scene/InstancePart") ?? null;
+  const path = memberDef && world.tryGet(entity, memberDef)?.path || partDef && world.tryGet(entity, partDef)?.path;
+  if (!path) return void 0;
+  const slash = path.lastIndexOf("/");
+  return slash === -1 ? path : path.slice(slash + 1);
+}
+function descendantPaths(world, root) {
+  const out = /* @__PURE__ */ new Map([["", root]]);
+  const visit = (entity, prefix, depth) => {
+    if (depth > 64 || !world.has(entity, Children)) return;
+    for (const child of world.get(entity, Children).entities) {
+      if (child === null || !world.isAlive(child)) continue;
+      const name = entityName(world, child);
+      if (name === void 0) continue;
+      const path = prefix ? `${prefix}/${name}` : name;
+      if (!out.has(path)) out.set(path, child);
+      visit(child, path, depth + 1);
+    }
+  };
+  visit(root, "", 0);
+  return out;
+}
+function findModelRoot(world, entity, probe) {
+  let current = entity;
+  for (let depth = 0; current !== null && depth < 32; depth++) {
+    const paths = descendantPaths(world, current);
+    if (paths.has(probe)) return { root: current, paths };
+    current = world.has(current, ChildOf) ? world.get(current, ChildOf).parent : null;
+    if (current !== null && !world.isAlive(current)) return void 0;
+  }
+  return void 0;
+}
+export {
+  descendantPaths,
+  entityName,
+  findModelRoot
+};

package/dist/picking-plugin.d.ts

@@ -0,0 +1,2 @@
+/** Picking (spec 0027): what's under a pixel (`pick`), and CPU raycasts against meshes. */
+export declare const pickingPlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/picking-plugin.js

@@ -0,0 +1,20 @@
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { PICK_SHADERS } from "./debug-shaders.js";
+import { addPickNodes, BvhResource, Picking } from "./picking.js";
+import { Shaders } from "./plugin.js";
+import { registerShaders } from "./shaders.js";
+const pickingPlugin = definePlugin({
+  name: "render/picking",
+  dependencies: ["render/forward"],
+  provides: [BvhResource, Picking],
+  build(app) {
+    app.world.initResource(Picking);
+  },
+  ready(app) {
+    registerShaders(app.world.resource(Shaders), PICK_SHADERS);
+    addPickNodes(app.world);
+  }
+});
+export {
+  pickingPlugin
+};

package/dist/picking.d.ts

@@ -0,0 +1,94 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { Mesh } from '@aethervtt/shard-mesh';
+import type { NodeContext, NodeDescriptor, RenderView } from './graph.js';
+import { type CameraData } from './view.js';
+export interface PickHit {
+    entity: Entity;
+    /** Scene path, when the entity came from a scene. */
+    path: string | undefined;
+    /** World position of the surface under the pixel. */
+    position: [number, number, number];
+    /** World normal of that surface, facing the camera. */
+    normal: [number, number, number];
+    /** Meters from the camera (from the ray origin, for raycasts). */
+    distance: number;
+}
+interface PickRequest {
+    x: number;
+    y: number;
+    resolve: (hit: PickHit | undefined) => void;
+    reject: (error: unknown) => void;
+}
+/**
+ * Something that draws pickable things into the picking pass besides meshes (sprites). It gets
+ * the pass with the picking targets bound (PICK_TARGETS: r32uint entity id, rgba32float normal
+ * and depth) and a depth32float attachment (reversed Z, compare greater).
+ */
+export type PickDrawer = (ctx: NodeContext, cam: CameraData) => void;
+/**
+ * Something drawn over the scene that takes pointer input at a pixel (UI): a pick there hits it,
+ * not the world, and resolves to undefined. Gets the view name and the pixel.
+ */
+export type PickBlocker = (world: World, view: string, x: number, y: number) => boolean;
+export interface PickingState {
+    /** Requests per view name, served by the next frame that renders the view. */
+    pending: Map<string, PickRequest[]>;
+    drawers: Map<string, PickDrawer>;
+    blockers: Map<string, PickBlocker>;
+    /** Views whose pick pass skipped a draw (a pipeline still compiling): their picks wait a frame. */
+    incomplete: Set<string>;
+}
+export declare const Picking: import("@aethervtt/shard-core").ResourceDef<PickingState>;
+/** The camera view `pick` and `render.capture` use by default: the first to render. */
+export declare function primaryView(world: World): RenderView | undefined;
+/**
+ * What's under pixel (x, y) of a camera's view (pixels from the top left): the entity, its scene
+ * path, and the world position and normal of the surface. Resolves after the next frame renders
+ * the view; undefined when nothing's there. Meshes (instanced and LOD too) and world-space sprites
+ * are pickable; gizmos and screen-space sprites and text aren't. A pixel covered by UI that takes
+ * the pointer (a PickBlocker) resolves to undefined: clicks on a HUD don't reach the world.
+ */
+export declare function pick(world: World, camera: Entity | undefined, x: number, y: number): Promise<PickHit | undefined>;
+/** The picking pass: meshes, then the extra drawers, into the pick targets of views with requests. */
+export declare function pickNode(world: World): NodeDescriptor;
+/** Copies the requested pixels out of the pick targets and resolves the requests once mapped. */
+export declare function pickReadbackNode(world: World): NodeDescriptor;
+/** Adds the picking targets and nodes to the graph. */
+export declare function addPickNodes(world: World): void;
+export interface RaycastOptions {
+    /** Ignore hits farther than this (m). Default: no limit. */
+    maxDistance?: number;
+    /** Every hit along the ray, nearest first (default: only the nearest). */
+    all?: boolean;
+    /** Test bounds only, never triangles. */
+    boundsOnly?: boolean;
+}
+interface Item {
+    entity: Entity;
+    mesh: Mesh;
+    /** World matrix rows (12) and their inverse (12). */
+    m: Float32Array;
+    inv: Float32Array;
+    box: Float32Array;
+}
+/** A bounding volume hierarchy over the world bounds of mesh entities, rebuilt when they change. */
+interface Bvh {
+    items: Item[];
+    /** Node boxes (6 floats each) and, per node, [left, right, 0] (inner) or [first item, 0, count]. */
+    boxes: Float32Array;
+    nodes: Int32Array;
+    order: Int32Array;
+    count: number;
+    tick: number;
+    tables: number;
+}
+export declare const BvhResource: import("@aethervtt/shard-core").ResourceDef<{
+    bvh: Bvh | undefined;
+}>;
+/**
+ * Casts a ray against mesh entities on the CPU: their bounds (through a BVH), then their triangles.
+ * Works without a GPU. Direction needn't be normalized. Hits come back nearest first; normals face
+ * the ray. Physics (M6) adds collider hits behind this same function.
+ */
+export declare function raycast(world: World, origin: ArrayLike<number>, direction: ArrayLike<number>, options?: RaycastOptions): PickHit[];
+export {};