@aethervtt/shard-render 0.0.1 → 0.2.0

package/dist/vfx-draw.js

@@ -0,0 +1,291 @@
+import { assetServer } from "@aethervtt/shard-assets";
+import { GpuBuffer } from "@aethervtt/shard-gpu";
+import { Textures } from "@aethervtt/shard-texture";
+import { GpuAssetsResource } from "./gpu-assets.js";
+import { RenderPhase } from "./graph.js";
+import { InstanceSlot } from "./instances.js";
+import { Shaders, Views } from "./plugin.js";
+import { bindingDimension } from "./tier.js";
+import { cameraOf } from "./view.js";
+const VFX_SHADERS = {
+  "shard::vfx::ribbon": `
+struct View { vp: mat4x4f, eye: vec4f, forward: vec4f, params: vec4f, tint: vec4f }
+@group(0) @binding(0) var<uniform> view: View;
+@group(0) @binding(1) var image: texture_2d<f32>;
+@group(0) @binding(2) var image_sampler: sampler;
+struct Input {
+ @location(0) position: vec3f,
+ @location(1) tangent: vec3f,
+ @location(2) uv: vec2f,
+ @location(3) color: vec4f,
+ @location(4) width_side: vec2f,
+}
+struct Output { @builtin(position) position: vec4f, @location(0) uv: vec2f, @location(1) color: vec4f }
+@vertex fn vs(in: Input) -> Output {
+ var out: Output;
+ var pos = in.position;
+ if (in.width_side.x > 0.0) {
+   var toward = view.eye.xyz - pos;
+   if (view.eye.w > 0.5) { toward = -view.forward.xyz; }
+   var side = cross(in.tangent, toward);
+   if (dot(side, side) < 1e-12) { side = cross(in.tangent, vec3f(0.0, 1.0, 0.0)); }
+   if (dot(side, side) < 1e-12) { side = vec3f(1.0, 0.0, 0.0); }
+   pos += normalize(side) * in.width_side.x * in.width_side.y;
+ }
+ out.position = view.vp * vec4f(pos, 1.0);
+ out.uv = in.uv;
+ out.color = in.color * view.tint;
+ return out;
+}
+@fragment fn fs(in: Output) -> @location(0) vec4f {
+ let c = textureSample(image, image_sampler, in.uv) * in.color;
+ let alpha = c.a * view.params.x;
+ if (alpha <= 0.00001) { discard; }
+ return vec4f(c.rgb * alpha, alpha);
+}`
+};
+const OVER = {
+  color: { srcFactor: "one", dstFactor: "one-minus-src-alpha" },
+  alpha: { srcFactor: "one", dstFactor: "one-minus-src-alpha" }
+};
+const ADD = {
+  color: { srcFactor: "one", dstFactor: "one" },
+  alpha: { srcFactor: "zero", dstFactor: "one" }
+};
+const BUFFERS = [
+  {
+    arrayStride: 56,
+    attributes: [
+      { shaderLocation: 0, offset: 0, format: "float32x3" },
+      { shaderLocation: 1, offset: 12, format: "float32x3" },
+      { shaderLocation: 2, offset: 24, format: "float32x2" },
+      { shaderLocation: 3, offset: 32, format: "float32x4" },
+      { shaderLocation: 4, offset: 48, format: "float32x2" }
+    ]
+  }
+];
+class VfxRenderer {
+  draws = [];
+  generation = -1;
+  layout;
+  pipelines = [void 0, void 0];
+  white;
+  whiteView;
+  sampler;
+  decal;
+  records;
+  constructor(records, decal) {
+    this.records = records;
+    this.decal = decal;
+  }
+  dispose() {
+    for (let i = 0; i < this.draws.length; i++) {
+      this.draws[i].vertices.destroy();
+      this.draws[i].uniform.destroy();
+    }
+    this.draws.length = 0;
+    this.white?.destroy();
+    this.white = void 0;
+    this.whiteView = void 0;
+  }
+  prune(world) {
+    const views = world.resource(Views).list;
+    for (let i = this.draws.length - 1; i >= 0; i--) {
+      const d = this.draws[i];
+      let view = false;
+      for (let j = 0; j < views.length; j++)
+        if (views[j].name === d.view) {
+          view = true;
+          break;
+        }
+      if (!view || !d.source.count || !this.records.includes(d.source)) {
+        d.vertices.destroy();
+        d.uniform.destroy();
+        this.draws.splice(i, 1);
+      }
+    }
+  }
+  init(gpu) {
+    if (this.generation === gpu.generation) return;
+    this.dispose();
+    this.generation = gpu.generation;
+    this.pipelines[0] = void 0;
+    this.pipelines[1] = void 0;
+    this.layout = gpu.layouts.bindGroupLayout({
+      label: "vfx",
+      entries: [
+        {
+          binding: 0,
+          visibility: GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT,
+          buffer: { type: "uniform" }
+        },
+        { binding: 1, visibility: GPUShaderStage.FRAGMENT, texture: { sampleType: "float" } },
+        { binding: 2, visibility: GPUShaderStage.FRAGMENT, sampler: { type: "filtering" } }
+      ]
+    });
+    this.white = gpu.device.createTexture({
+      label: "vfx/white",
+      size: [1, 1],
+      format: "rgba8unorm",
+      usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
+      ...bindingDimension(gpu, "2d")
+    });
+    gpu.device.queue.writeTexture(
+      { texture: this.white },
+      new Uint8Array([255, 255, 255, 255]),
+      { bytesPerRow: 4 },
+      [1, 1]
+    );
+    this.whiteView = this.white.createView();
+    this.sampler = gpu.device.createSampler({
+      magFilter: "linear",
+      minFilter: "linear",
+      addressModeU: this.decal ? "clamp-to-edge" : "repeat",
+      addressModeV: "clamp-to-edge"
+    });
+  }
+  node() {
+    return {
+      kind: "render",
+      phase: RenderPhase.Resolve + (this.decal ? 5 : 15),
+      reads: ["depth"],
+      writes: ["hdr"],
+      color: [{ resource: "hdr" }],
+      depth: { resource: "depth", readOnly: true },
+      enabled: (view) => {
+        const cam = cameraOf(view);
+        if (!cam) return false;
+        for (let i = 0; i < this.records.length; i++) {
+          const r = this.records[i];
+          if (r.count && r.visible && r.opacity > 0 && r.layers & cam.layers) return true;
+        }
+        return false;
+      },
+      run: (ctx) => this.draw(ctx)
+    };
+  }
+  draw(ctx) {
+    const gpu = ctx.gpu, cam = cameraOf(ctx.view), pass = ctx.renderPass;
+    this.init(gpu);
+    const textures = ctx.world.resource(Textures), assets = ctx.world.resource(GpuAssetsResource);
+    for (let i = 0; i < this.records.length; i++) {
+      const r = this.records[i];
+      if (!r.count || !r.visible || r.opacity <= 0 || !(r.layers & cam.layers)) continue;
+      const index = r.additive ? 1 : 0;
+      let pipeline = this.pipelines[index];
+      if (!pipeline) {
+        const module = ctx.world.resource(Shaders).module(gpu, { root: "shard::vfx::ribbon" });
+        if (!module) {
+          gpu.pipelines.skipped++;
+          continue;
+        }
+        pipeline = gpu.pipelines.render({
+          label: index ? "vfx/additive" : "vfx/alpha",
+          layout: gpu.layouts.pipelineLayout({ bindGroupLayouts: [this.layout] }),
+          vertex: { module, entryPoint: "vs", buffers: BUFFERS },
+          fragment: {
+            module,
+            entryPoint: "fs",
+            targets: [{ format: "rgba16float", blend: index ? ADD : OVER }]
+          },
+          primitive: { topology: "triangle-list", cullMode: "none" },
+          depthStencil: {
+            format: "depth32float",
+            depthWriteEnabled: false,
+            depthCompare: "greater-equal",
+            // Resolved MSAA depth comes from a subsample, not the fragment center.
+            // Positive reversed-Z slope bias keeps coplanar decals visible on every adapter.
+            depthBias: this.decal ? 1 : 0,
+            depthBiasSlopeScale: this.decal ? 1 : 0
+          }
+        });
+        if (!pipeline) {
+          gpu.pipelines.skipped++;
+          continue;
+        }
+        this.pipelines[index] = pipeline;
+      }
+      let d;
+      for (let j = 0; j < this.draws.length; j++)
+        if (this.draws[j].source === r && this.draws[j].view === ctx.view.name) {
+          d = this.draws[j];
+          break;
+        }
+      if (!d) {
+        d = {
+          source: r,
+          view: ctx.view.name,
+          vertices: new GpuBuffer(gpu, {
+            label: "vfx/vertices",
+            usage: GPUBufferUsage.VERTEX,
+            size: r.vertices.byteLength
+          }),
+          uniform: new GpuBuffer(gpu, {
+            label: "vfx/view",
+            usage: GPUBufferUsage.UNIFORM,
+            size: 128
+          }),
+          data: new Float32Array(32),
+          group: void 0,
+          texture: void 0,
+          version: -1,
+          generation: gpu.generation
+        };
+        this.draws.push(d);
+      }
+      if (d.version !== r.version) {
+        d.vertices.write(r.vertices, 0, 0, r.count * 14);
+        d.version = r.version;
+      }
+      const texture = r.texture ? textures.get(r.texture) : void 0, gt = texture ? assets.texture(texture) : void 0;
+      r.textureState = !r.texture ? "none" : gt ? "ready" : assetServer(ctx.world).entry(r.texture) ? "loading" : "missing";
+      const image = gt ? texture.usage === "color" ? gt.srgb : gt.linear : this.whiteView;
+      if (!d.group || d.texture !== image) {
+        d.texture = image;
+        d.group = gpu.device.createBindGroup({
+          label: "vfx/draw",
+          layout: this.layout,
+          entries: [
+            { binding: 0, resource: { buffer: d.uniform.buffer } },
+            { binding: 1, resource: image },
+            { binding: 2, resource: this.sampler }
+          ]
+        });
+      }
+      d.data.set(cam.viewProj);
+      d.data.set(cam.position, 16);
+      d.data[19] = cam.orthographic ? 1 : 0;
+      d.data.set(cam.forward, 20);
+      d.data[24] = r.opacity;
+      if (this.decal) {
+        const colors = r.columns.color;
+        for (let k = 0; k < 4; k++) d.data[28 + k] = colors[r.row * 4 + k];
+      } else {
+        d.data[28] = 1;
+        d.data[29] = 1;
+        d.data[30] = 1;
+        d.data[31] = 1;
+      }
+      d.uniform.write(d.data);
+      pass.setPipeline(pipeline);
+      pass.setBindGroup(0, d.group);
+      pass.setVertexBuffer(0, d.vertices.buffer);
+      if (this.decal) {
+        const ranges = r.ranges;
+        for (let j = 0; j < ranges.length; j++) {
+          const range = ranges[j];
+          if (!(range.layers & cam.layers)) continue;
+          if (cam.hidden && ctx.world.has(range.entity, InstanceSlot)) {
+            const table = ctx.world.entityTableUnchecked(range.entity), row = ctx.world.entityRowUnchecked(range.entity), slot = table.column(InstanceSlot, "slot")[row] - 1;
+            if (slot >= 0 && (cam.hidden.bits[slot >> 5] ?? 0) & 1 << (slot & 31)) continue;
+          }
+          pass.draw(range.count, 1, range.start);
+        }
+      } else pass.draw(r.count);
+    }
+  }
+}
+export {
+  VFX_SHADERS,
+  VfxRenderer
+};

package/dist/vfx-state.d.ts

@@ -0,0 +1,42 @@
+import type { AssetRef, ComponentDef, Entity, Table, TypedArray, World } from '@aethervtt/shard-core';
+export declare const VFX_STRIDE = 14;
+export interface VfxRecord {
+    entity: Entity;
+    def: ComponentDef;
+    kind: 'trail' | 'beam' | 'decal';
+    table: Table;
+    row: number;
+    columns: Record<string, TypedArray | unknown[]>;
+    matrix: Float64Array;
+    vertices: Float32Array;
+    count: number;
+    version: number;
+    age: number;
+    wasPlaying: boolean;
+    error: string | null;
+    seen: number;
+    opacity: number;
+    texture: AssetRef<'Texture'> | null;
+    layers: number;
+    additive: boolean;
+    textureState: string;
+    visible: boolean;
+}
+export declare function createRecord(world: World, entity: Entity, def: ComponentDef, kind: VfxRecord['kind'], vertices: number): VfxRecord;
+export declare function refreshRecord(world: World, r: VfxRecord): void;
+export declare function number(r: VfxRecord, field: string): number;
+export declare function matrixChanged(world: World, entity: Entity, out: Float64Array): boolean;
+export declare function point(out: Float64Array, at: number, m: ArrayLike<number>, x: number, y: number, z: number): void;
+export declare function recordDescription(r: VfxRecord): {
+    entity: number;
+    kind: "beam" | "decal" | "trail";
+    vertices: number;
+    age: number;
+    opacity: number;
+    error: string | null;
+    visible: boolean;
+    cpuBytes: number;
+    texture: string;
+    playing: boolean;
+    paused: boolean;
+};

package/dist/vfx-state.js

@@ -0,0 +1,81 @@
+import { GlobalTransform } from "@aethervtt/shard-transform";
+import { ComputedVisibility } from "./visibility.js";
+const VFX_STRIDE = 14;
+function createRecord(world, entity, def, kind, vertices) {
+  const table = world.entityTable(entity);
+  return {
+    entity,
+    def,
+    kind,
+    table,
+    row: world.entityRow(entity),
+    columns: table.storage(def).byName,
+    matrix: new Float64Array(12),
+    vertices: new Float32Array(vertices * VFX_STRIDE),
+    count: 0,
+    version: 0,
+    age: 0,
+    wasPlaying: false,
+    error: null,
+    seen: 0,
+    opacity: 1,
+    texture: null,
+    layers: 1,
+    additive: false,
+    textureState: "none",
+    visible: true
+  };
+}
+function refreshRecord(world, r) {
+  r.table = world.entityTableUnchecked(r.entity);
+  r.row = world.entityRowUnchecked(r.entity);
+  r.columns = r.table.storage(r.def).byName;
+  r.texture = r.columns.texture[r.row];
+  r.opacity = number(r, "opacity");
+  r.layers = number(r, "layers");
+  r.additive = number(r, "blend") === 1;
+  r.visible = !r.table.has(ComputedVisibility) || r.table.column(ComputedVisibility, "visible")[r.row] !== 0;
+}
+function number(r, field) {
+  return r.columns[field][r.row];
+}
+function matrixChanged(world, entity, out) {
+  const t = world.entityTableUnchecked(entity), row = world.entityRowUnchecked(entity);
+  const m = t.column(GlobalTransform, "matrix");
+  let changed = false;
+  for (let i = 0; i < 12; i++) {
+    const v = m[row * 12 + i];
+    if (out[i] !== v) changed = true;
+    out[i] = v;
+  }
+  return changed;
+}
+function point(out, at, m, x, y, z) {
+  out[at] = m[0] * x + m[1] * y + m[2] * z + m[3];
+  out[at + 1] = m[4] * x + m[5] * y + m[6] * z + m[7];
+  out[at + 2] = m[8] * x + m[9] * y + m[10] * z + m[11];
+}
+function recordDescription(r) {
+  return {
+    entity: r.entity,
+    kind: r.kind,
+    vertices: r.count,
+    age: r.age,
+    opacity: r.opacity,
+    error: r.error,
+    visible: r.visible,
+    cpuBytes: r.vertices.byteLength,
+    texture: r.textureState,
+    playing: !!number(r, "playing"),
+    paused: !!number(r, "paused")
+  };
+}
+export {
+  VFX_STRIDE,
+  createRecord,
+  matrixChanged,
+  number,
+  point,
+  recordDescription,
+  refreshRecord
+};

package/dist/vfx.d.ts

@@ -0,0 +1,69 @@
+import { type World } from '@aethervtt/shard-core';
+export declare const Trail: import("@aethervtt/shard-core").ComponentDef<{
+    readonly playing: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly paused: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly opacity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+    readonly blend: import("@aethervtt/shard-core").FieldType<"additive" | "alpha", "u8">;
+    readonly layers: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly width: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly endColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly widthCurve: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        at: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        value: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    }>[], "object">;
+    readonly repeat: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly scroll: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly offset: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly lifetime: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly capacity: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly minDistance: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly breakDistance: import("@aethervtt/shard-core").FieldType<number, "f32">;
+}>;
+export declare const Beam: import("@aethervtt/shard-core").ComponentDef<{
+    readonly playing: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly paused: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly opacity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+    readonly blend: import("@aethervtt/shard-core").FieldType<"additive" | "alpha", "u8">;
+    readonly layers: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly width: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly endColor: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly widthCurve: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        at: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        value: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    }>[], "object">;
+    readonly repeat: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly scroll: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly start: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly end: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly target: import("@aethervtt/shard-core").FieldType<number | null, "f64">;
+    readonly points: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3[], "object">;
+    readonly segments: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly noise: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+}>;
+export declare const Decal: import("@aethervtt/shard-core").ComponentDef<{
+    readonly playing: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly paused: import("@aethervtt/shard-core").FieldType<boolean, "u8">;
+    readonly opacity: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly color: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Color, "f32">;
+    readonly texture: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Texture"> | null, "object">;
+    readonly blend: import("@aethervtt/shard-core").FieldType<"additive" | "alpha", "u8">;
+    readonly layers: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly size: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec3, "f32">;
+    readonly receiverMask: import("@aethervtt/shard-core").FieldType<number, "u16">;
+    readonly maxAngle: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly offset: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly lifetime: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly fadeOut: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    readonly maxVertices: import("@aethervtt/shard-core").FieldType<number, "u32">;
+}>;
+export declare const DecalReceiver: import("@aethervtt/shard-core").ComponentDef<{
+    readonly mask: import("@aethervtt/shard-core").FieldType<number, "u16">;
+}>;
+export declare const RibbonsPath: import("@aethervtt/shard-core").ResourceDef<boolean>;
+export declare const DecalsPath: import("@aethervtt/shard-core").ResourceDef<boolean>;
+export declare function observeVfxWithoutPlugin(world: World): void;

package/dist/vfx.js

@@ -0,0 +1,103 @@
+import { defineComponent, defineResource, onAdd, t } from "@aethervtt/shard-core";
+import { Transform } from "@aethervtt/shard-transform";
+import { warnFeatureMissing } from "./features.js";
+const presentation = {
+  playing: t.bool({ default: true }),
+  paused: t.bool(),
+  opacity: t.f32({ default: 1, min: 0, max: 1 }),
+  color: t.color({ default: [1, 1, 1, 1] }),
+  texture: t.handle("Texture"),
+  blend: t.enum(["alpha", "additive"]),
+  layers: t.u16({ default: 1 })
+};
+const ribbon = {
+  ...presentation,
+  width: t.f32({ default: 0.1, min: 0, max: 1e3 }),
+  endColor: t.color({ default: [1, 1, 1, 0] }),
+  widthCurve: t.list(
+    t.struct({ at: t.f32({ min: 0, max: 1 }), value: t.f32({ min: 0, max: 16 }) })
+  ),
+  repeat: t.f32({ default: 1, min: 1e-4, max: 1e4 }),
+  scroll: t.f32({ min: -1e4, max: 1e4 })
+};
+const Trail = defineComponent(
+  "render/Trail",
+  {
+    ...ribbon,
+    offset: t.vec3(),
+    lifetime: t.f32({ default: 0.5, min: 1e-3, max: 3600 }),
+    capacity: t.u16({ default: 64, min: 2, max: 256 }),
+    minDistance: t.f32({ default: 0.01, min: 1e-5, max: 1e3 }),
+    breakDistance: t.f32({ default: 10, min: 1e-3, max: 1e6 })
+  },
+  {
+    requires: [Transform],
+    description: "World-space ribbon history of this entity/bone; stops emitting when playing is false and drains by lifetime (0082)."
+  }
+);
+const Beam = defineComponent(
+  "render/Beam",
+  {
+    ...ribbon,
+    start: t.vec3(),
+    end: t.vec3({ default: [0, 0, -1] }),
+    target: t.entity(),
+    points: t.list(t.vec3()),
+    segments: t.u16({ default: 16, min: 1, max: 255 }),
+    noise: t.f32({ min: 0, max: 1e3 }),
+    seed: t.u32()
+  },
+  {
+    requires: [Transform],
+    description: "Camera-facing beam between transformed endpoints, or along local points; deterministic seeded displacement (0082)."
+  }
+);
+const Decal = defineComponent(
+  "render/Decal",
+  {
+    ...presentation,
+    size: t.vec3({ default: [1, 1, 1] }),
+    receiverMask: t.u16({ default: 1 }),
+    maxAngle: t.f32({ default: 80, min: 0, max: 89.9 }),
+    offset: t.f32({ default: 2e-3, min: 0, max: 1 }),
+    lifetime: t.f32({ min: 0, max: 86400 }),
+    fadeOut: t.f32({ default: 1, min: 0, max: 86400 }),
+    maxVertices: t.u32({ default: 12288, min: 3, max: 65535 })
+  },
+  {
+    requires: [Transform],
+    description: "Box projection onto DecalReceiver rigid meshes: local XY is UV, projection along -Z. Zero lifetime persists (0083)."
+  }
+);
+const DecalReceiver = defineComponent(
+  "render/DecalReceiver",
+  {
+    mask: t.u16({ default: 1 })
+  },
+  { description: "Eligible rigid Mesh3d surface for matching decal receiver masks (0083)." }
+);
+const RibbonsPath = defineResource("render/RibbonsPath", { init: () => true });
+const DecalsPath = defineResource("render/DecalsPath", { init: () => true });
+function observeVfxWithoutPlugin(world) {
+  world.observe(onAdd(Trail), ({ world: w }) => {
+    if (!w.hasResource(RibbonsPath))
+      warnFeatureMissing(w, "Trail", "ribbonsPlugin", "it draws no ribbon");
+  });
+  world.observe(onAdd(Beam), ({ world: w }) => {
+    if (!w.hasResource(RibbonsPath))
+      warnFeatureMissing(w, "Beam", "ribbonsPlugin", "it draws no ribbon");
+  });
+  world.observe(onAdd(Decal), ({ world: w }) => {
+    if (!w.hasResource(DecalsPath))
+      warnFeatureMissing(w, "Decal", "decalsPlugin", "it draws no decal");
+  });
+}
+export {
+  Beam,
+  Decal,
+  DecalReceiver,
+  DecalsPath,
+  RibbonsPath,
+  Trail,
+  observeVfxWithoutPlugin
+};

package/dist/view-visibility-plugin.d.ts

@@ -0,0 +1,61 @@
+import { type Entity, type World } from '@aethervtt/shard-core';
+import type { GpuBuffer } from '@aethervtt/shard-gpu';
+import { type HiddenSet } from './view-visibility.js';
+/**
+ * Every camera's hidden set, one range of words each. The GPU culler reads them from a region of
+ * its LOD state buffer; only words that changed upload there.
+ */
+export declare class HiddenSets {
+    /** Words per set: one bit per instance slot of the store's capacity. */
+    words: number;
+    data: Uint32Array<ArrayBuffer>;
+    readonly sets: Map<number, HiddenSet>;
+    /** Free set indices, reused before growing. */
+    private readonly free;
+    private count;
+    private dirty;
+    private dirtyLo;
+    private dirtyHi;
+    /** Every word uploads next time (a new layout, buffer, region or device). */
+    private all;
+    /** Where the last upload went: a buffer version (it bumps when replaced) and byte offset. */
+    private target;
+    private targetVersion;
+    private targetOffset;
+    /** Bytes uploaded by the last `upload`. */
+    uploadedBytes: number;
+    /** Resolves since start (tests: a still frame resolves nothing). */
+    resolves: number;
+    /** The set of `camera`, made on first use. */
+    setOf(camera: Entity): HiddenSet;
+    /** Frees a set: its words clear (and upload, so a reused index starts empty). */
+    drop(set: HiddenSet): void;
+    /** Makes room for `capacity` slots per set; a new width re-lays every set and uploads all. */
+    ensureSlots(capacity: number): void;
+    private layout;
+    private write;
+    /**
+     * Writes a set's new bits (from `next`, `words` long), marking only words that differ. Returns
+     * whether any did.
+     */
+    assign(set: HiddenSet, next: Uint32Array): boolean;
+    /**
+     * Uploads changed words in runs to `buffer` at `byteOffset`; everything when that's not where
+     * the last upload went, or the buffer was replaced (grown, or a new device).
+     */
+    upload(buffer: GpuBuffer, byteOffset: number): number;
+}
+/**
+ * Resolves each camera's ViewVisibility into its hidden set, after the instance slots are current.
+ * Lists resolve again only when they change, a slot is allocated or freed, or a ChildOf changes.
+ */
+export declare const resolveViewVisibility: import("@aethervtt/shard-core").SystemDef<{
+    q: import("@aethervtt/shard-core").Query;
+    hierarchy: import("@aethervtt/shard-core").Query;
+    epoch: number;
+    frame: number;
+}>;
+/** render.describe's viewVisibility section: per camera, what it hides and the slots it resolves to. */
+export declare function describeViewVisibility(world: World): Record<string, unknown>;
+/** Per-view hiding (0070): cameras' ViewVisibility lists, resolved for their culls. */
+export declare const viewVisibilityPlugin: import("@aethervtt/shard-runtime").Plugin;