@aethervtt/shard-scatter 0.0.0-stage → 0.2.0

package/dist/plugin.js

@@ -0,0 +1,265 @@
+import { AssetServerResource, assetServer } from "@aethervtt/shard-assets";
+import {
+  ChildOf,
+  defineSystem,
+  onRemove,
+  PostUpdate
+} from "@aethervtt/shard-core";
+import {
+  computeVisibility,
+  Mesh3d,
+  Meshes,
+  registerShaders,
+  Shaders
+} from "@aethervtt/shard-render";
+import { definePlugin } from "@aethervtt/shard-runtime";
+import {
+  Planet,
+  Terrain,
+  TerrainWorld,
+  updateHeightfields,
+  updatePlanets
+} from "@aethervtt/shard-terrain";
+import { GlobalTransform, TransformSystems } from "@aethervtt/shard-transform";
+import * as componentsModule from "./components.js";
+import {
+  addRemoved,
+  Prop,
+  propIdentity,
+  Removed,
+  removedKey,
+  ScatterBudget,
+  ScatterSurface
+} from "./components.js";
+import * as foliageModule from "./foliage.js";
+import { applyWind, clearFoliage, updateFoliage, Wind } from "./foliage.js";
+import { HeightfieldSurface } from "./heightfield-surface.js";
+import * as materialModule from "./material.js";
+import { SCATTER_SHADERS } from "./material.js";
+import { MeshSurface } from "./mesh-surface.js";
+import { scatterMethods } from "./methods.js";
+import * as overlaysModule from "./overlays.js";
+import { PlanetSurface } from "./planet.js";
+import * as previewModule from "./preview.js";
+import {
+  clearChunks,
+  planetScatters,
+  planetSources,
+  refreshSurface,
+  resolveAsset,
+  Scatter,
+  SurfaceScatter,
+  updateProps
+} from "./runtime.js";
+import * as setModule from "./set.js";
+import { ScatterSet } from "./set.js";
+import { cameraQuery } from "./viewers.js";
+const watching = /* @__PURE__ */ new WeakSet();
+function watchAssets(world) {
+  if (watching.has(world) || !world.tryResource(AssetServerResource)) return;
+  watching.add(world);
+  assetServer(world).onEvent((event) => {
+    if (event.kind === "loaded" || event.kind === "modified" || event.kind === "failed")
+      world.resource(Scatter).dirty = true;
+  });
+}
+const updateScatter = defineSystem({
+  name: "scatter/props",
+  description: "Places scatter props (rocks, trees, \u2026) in chunks around cameras and TerrainAnchors, spawning them nearest first within ScatterBudget and despawning those out of range.",
+  setup: (world) => ({
+    cameras: cameraQuery(world),
+    meshes: world.query({ with: [ScatterSurface, Mesh3d, GlobalTransform] })
+  }),
+  run: (s, world) => {
+    const state = world.resource(Scatter);
+    watchAssets(world);
+    state.frame++;
+    const frame = state.frame;
+    const budget = world.resource(ScatterBudget);
+    const dirty = state.dirty;
+    state.dirty = false;
+    recordRemovals(world);
+    const terrain = world.tryResource(TerrainWorld);
+    if (terrain) {
+      for (const rt of terrain.planets.values()) {
+        if (!world.isAlive(rt.entity) || !rt.ready) continue;
+        let ss = state.surfaces.get(rt.entity);
+        if (!ss) {
+          if (!planetScatters(world, rt)) continue;
+          ss = new SurfaceScatter(new PlanetSurface(rt, s.cameras));
+          state.surfaces.set(rt.entity, ss);
+        }
+        const start = performance.now();
+        const content = `${rt.version}:${rt.biomeVersion}`;
+        if (dirty || ss.content !== content || !ss.ready) {
+          ss.content = content;
+          const { sources, waiting } = planetSources(world, rt);
+          if (waiting) {
+            ss.waiting = waiting;
+            continue;
+          }
+          if (!refreshSurface(world, ss, sources, rt.settings.seed, content)) continue;
+        }
+        updateProps(world, ss, frame, budget, state.workers);
+        updateFoliage(world, ss, frame, state.workers);
+        ss.ms = performance.now() - start;
+      }
+    }
+    if (terrain) {
+      const sets = world.initResource(ScatterSet.store);
+      for (const rt of terrain.heightfields.values()) {
+        if (!world.isAlive(rt.entity) || !rt.ready || !world.has(rt.entity, Terrain)) continue;
+        const own = world.get(rt.entity, Terrain).scatter;
+        let ss = state.surfaces.get(rt.entity);
+        if (!own && !ss) continue;
+        if (!ss) {
+          ss = new SurfaceScatter(new HeightfieldSurface(world, rt, s.cameras));
+          state.surfaces.set(rt.entity, ss);
+        }
+        const start = performance.now();
+        const content = `${rt.version}:${rt.asset?.hash}`;
+        if (dirty || ss.content !== content || !ss.ready) {
+          const set = resolveAsset(world, own, (g) => sets.get({ guid: g }));
+          if (!set) {
+            ss.waiting = `scatter set ${own?.path ?? own?.guid ?? "(none)"}`;
+            continue;
+          }
+          ;
+          ss.surface.setTerrain();
+          ss.content = content;
+          const sources = [{ path: own?.path ?? own?.guid ?? "", set, biome: -1 }];
+          if (!refreshSurface(world, ss, sources, rt.asset.source.seed, content)) continue;
+        }
+        updateProps(world, ss, frame, budget, state.workers);
+        updateFoliage(world, ss, frame, state.workers);
+        ss.ms = performance.now() - start;
+      }
+    }
+    for (const table of s.meshes.tables) {
+      const sets = world.initResource(ScatterSet.store);
+      const meshes = world.initResource(Meshes);
+      for (let row = 0; row < table.count; row++) {
+        const entity = table.entities[row];
+        let ss = state.surfaces.get(entity);
+        if (!ss) {
+          ss = new SurfaceScatter(new MeshSurface(world, entity, s.cameras));
+          state.surfaces.set(entity, ss);
+        }
+        const start = performance.now();
+        const surface = ss.surface;
+        const value = world.get(entity, ScatterSurface);
+        const meshRef = world.get(entity, Mesh3d).mesh;
+        const mesh = resolveAsset(world, meshRef, (g) => meshes.get({ guid: g }));
+        if (!mesh || mesh.gpu) {
+          ss.waiting = `mesh ${meshRef?.path ?? meshRef?.guid ?? "(none)"}`;
+          continue;
+        }
+        const set = resolveAsset(world, value.set, (g) => sets.get({ guid: g }));
+        if (!set) {
+          ss.waiting = `scatter set ${value.set?.path ?? value.set?.guid ?? "(none)"}`;
+          continue;
+        }
+        const changed = surface.setMesh(
+          mesh,
+          uniformScale(world.get(entity, GlobalTransform).matrix)
+        );
+        const content = `${mesh.version}:${surface.scale}`;
+        if (dirty || changed || ss.content !== content || !ss.ready) {
+          ss.content = content;
+          const sources = [{ path: value.set?.path ?? value.set?.guid ?? "", set, biome: -1 }];
+          if (!refreshSurface(world, ss, sources, value.seed, content)) continue;
+        }
+        updateProps(world, ss, frame, budget, state.workers);
+        updateFoliage(world, ss, frame, state.workers);
+        ss.ms = performance.now() - start;
+      }
+    }
+    applyWind(world, windMaterials(state));
+  }
+});
+const used = /* @__PURE__ */ new Set();
+function windMaterials(state) {
+  used.clear();
+  for (const ref of state.materials.values()) used.add(ref);
+  for (const ss of state.surfaces.values())
+    for (const items of ss.variants)
+      for (const vs of items) for (const v of vs) used.add(v.material);
+  return used;
+}
+function uniformScale(m) {
+  const sx = Math.sqrt(m[0] * m[0] + m[4] * m[4] + m[8] * m[8]);
+  const sy = Math.sqrt(m[1] * m[1] + m[5] * m[5] + m[9] * m[9]);
+  const sz = Math.sqrt(m[2] * m[2] + m[6] * m[6] + m[10] * m[10]);
+  return (sx + sy + sz) / 3 || 1;
+}
+function recordRemovals(world) {
+  const state = world.resource(Scatter);
+  if (state.pendingRemovals.length === 0) return;
+  const removed = world.initResource(Removed);
+  for (const p of state.pendingRemovals) {
+    if (!world.isAlive(p.root)) continue;
+    addRemoved(removed, removedKey(p.rule, p.chunk, p.index));
+  }
+  state.pendingRemovals.length = 0;
+}
+function scatterPlugin(options = {}) {
+  return definePlugin({
+    name: "scatter",
+    // Registers the scatter and foliage-chunks overlays.
+    provides: [
+      componentsModule,
+      foliageModule,
+      materialModule,
+      overlaysModule,
+      previewModule,
+      setModule,
+      Scatter
+    ],
+    dependencies: ["core/transform"],
+    build(app) {
+      const world = app.world;
+      const state = world.initResource(Scatter);
+      state.workers = options.workers;
+      world.initResource(ScatterBudget);
+      world.initResource(Removed);
+      world.initResource(Wind);
+      world.observe(onRemove(Prop), ({ entity, world: world2 }) => {
+        const st = world2.resource(Scatter);
+        if (st.despawning) return;
+        const id = propIdentity(world2, entity);
+        const root = world2.tryGet(entity, ChildOf)?.parent;
+        if (!id || root === void 0 || root === null) return;
+        st.pendingRemovals.push({ ...id, root });
+      });
+      world.observe(onRemove(ScatterSurface), ({ entity, world: world2 }) => {
+        const st = world2.resource(Scatter);
+        const ss = st.surfaces.get(entity);
+        if (!ss) return;
+        clearChunks(world2, ss);
+        clearFoliage(world2, ss);
+        st.surfaces.delete(entity);
+      });
+      world.observe(onRemove(Planet), ({ entity, world: world2 }) => {
+        const st = world2.resource(Scatter);
+        const ss = st.surfaces.get(entity);
+        if (!ss) return;
+        clearChunks(world2, ss);
+        clearFoliage(world2, ss);
+        st.surfaces.delete(entity);
+      });
+      app.addSystems(
+        PostUpdate,
+        updateScatter.after(updatePlanets).after(updateHeightfields).after(TransformSystems).before(computeVisibility)
+      );
+      app.addMethod(...scatterMethods);
+    },
+    ready(app) {
+      const shaders = app.world.tryResource(Shaders);
+      if (shaders) registerShaders(shaders, SCATTER_SHADERS);
+    }
+  });
+}
+export {
+  scatterPlugin,
+  updateScatter
+};

package/dist/preview-render.d.ts

@@ -0,0 +1,10 @@
+import { type PreviewImage } from '@aethervtt/shard-assets';
+import { type World } from '@aethervtt/shard-core';
+/** Side of the previewed patch (m). */
+export declare const PREVIEW_SIZE = 64;
+/**
+ * A ScatterSet on a flat 64 m patch, in a private world sharing the game's GPU, assets and
+ * generator outputs: from above (left half) and at eye level (right half), or one of them with
+ * `options.view` ('top' | 'eye').
+ */
+export declare function renderScatterPreview(world: World, path: string, width: number, height: number, options?: Readonly<Record<string, unknown>>): Promise<PreviewImage>;

package/dist/preview-render.js

@@ -0,0 +1,155 @@
+import { AssetServerResource, assetServer } from "@aethervtt/shard-assets";
+import { findResource } from "@aethervtt/shard-core";
+import { plane } from "@aethervtt/shard-mesh";
+import { NoiseGraphs } from "@aethervtt/shard-noise";
+import {
+  AmbientLight,
+  Camera3d,
+  captureView,
+  DirectionalLight,
+  Exposure,
+  FoliageLayers,
+  forwardPlugin,
+  Gpu,
+  MaterialAsset,
+  Materials,
+  Mesh3d,
+  Meshes,
+  MeshMaterial,
+  OffscreenTarget,
+  RenderTargets,
+  renderPlugin,
+  Shaders,
+  Tonemapping
+} from "@aethervtt/shard-render";
+import { App } from "@aethervtt/shard-runtime";
+import { ScenePlugin } from "@aethervtt/shard-scene";
+import { Textures } from "@aethervtt/shard-texture";
+import { lookAt, Transform, TransformPlugin } from "@aethervtt/shard-transform";
+import { ScatterSurface } from "./components.js";
+import { scatterPlugin } from "./plugin.js";
+import { Scatter } from "./runtime.js";
+import { ScatterSet } from "./set.js";
+const PREVIEW_SIZE = 64;
+async function renderScatterPreview(world, path, width, height, options = {}) {
+  const gpu = world.resource(Gpu);
+  const server = assetServer(world);
+  await server.load(path);
+  const entry = server.entry(path);
+  const view = options.view === "top" || options.view === "eye" ? options.view : "both";
+  const app = new App();
+  app.world.insertResource(AssetServerResource, server);
+  for (const def of [Meshes, Materials, Textures, NoiseGraphs, ScatterSet.store])
+    app.world.insertResource(def, world.initResource(def));
+  for (const name of ["procgen/Runtime", "procgen/Generators", "procgen/Data"]) {
+    const def = findResource(name);
+    if (def && world.hasResource(def)) app.world.insertResource(def, world.resource(def));
+  }
+  app.addPlugin(
+    TransformPlugin,
+    renderPlugin({ gpu, windowView: false, shaders: world.resource(Shaders) }),
+    forwardPlugin({ msaa: 1 }),
+    ScenePlugin,
+    scatterPlugin()
+  );
+  const views = view === "both" ? ["top", "eye"] : [view];
+  const cellW = view === "both" ? Math.max(1, Math.floor(width / 2)) : width;
+  const targets = [];
+  try {
+    await app.init();
+    const w = app.world;
+    const ground = w.resource(Materials).add(new MaterialAsset({ baseColor: [0.36, 0.3, 0.22, 1], roughness: 1 }));
+    w.spawn(
+      [Mesh3d, { mesh: w.resource(Meshes).add(plane({ size: 1, subdivisions: 2 })) }],
+      [MeshMaterial, { material: ground }],
+      [
+        ScatterSurface,
+        {
+          set: {
+            type: "scatter/ScatterSet",
+            guid: entry.guid,
+            path: entry.path
+          },
+          seed: 1
+        }
+      ],
+      [Transform, { scale: [PREVIEW_SIZE, PREVIEW_SIZE, PREVIEW_SIZE] }]
+    );
+    Object.assign(w.resource(AmbientLight), { brightness: 4e3 });
+    w.spawn(
+      [DirectionalLight, { illuminance: 6e4, shadows: true }],
+      [Transform, { rotation: lookAt([-3, 8, 4], [0, 0, 0]) }]
+    );
+    const cameras = [];
+    for (const v of views) {
+      const target = new OffscreenTarget(gpu, {
+        label: `scatter-preview-${v}`,
+        width: cellW,
+        height
+      });
+      targets.push(target);
+      const ref = w.resource(RenderTargets).add(target, `scatter-preview-${v}`);
+      const eye = v === "top" ? [0, 40, 1e-3] : [-PREVIEW_SIZE * 0.42, 1.7, PREVIEW_SIZE * 0.42];
+      const at = v === "top" ? [0, 0, 0] : [0, 0.8, 0];
+      const camera = w.spawn(
+        [
+          Camera3d,
+          v === "top" ? {
+            target: ref,
+            projection: "orthographic",
+            orthoHeight: PREVIEW_SIZE,
+            far: 200,
+            clearColor: [0.5, 0.65, 0.85, 1]
+          } : { target: ref, fovY: 55, clearColor: [0.5, 0.65, 0.85, 1] }
+        ],
+        [Exposure, { ev100: 13.5 }],
+        [Tonemapping, { dither: false }],
+        [Transform, { translation: eye, rotation: lookAt(eye, at) }]
+      );
+      cameras.push(`camera:${camera}`);
+    }
+    for (let i = 0; i < 600; i++) {
+      app.update(1 / 60);
+      await w.resource(Shaders).whenIdle();
+      await gpu.pipelines.whenIdle();
+      await new Promise((r) => setTimeout(r, 1));
+      const state = w.resource(Scatter);
+      let busy = state.surfaces.size === 0;
+      for (const ss of state.surfaces.values()) {
+        if (ss.problem) throw ss.problem;
+        if (!ss.ready) busy = true;
+        for (const c of ss.chunks.values()) if (c.job) busy = true;
+        for (const f of ss.foliage.values())
+          for (const c of f.chunks.values()) if (c.slot < 0) busy = true;
+      }
+      const layers = w.resource(FoliageLayers).layers;
+      for (const l of layers) if (l.pending.length > 0) busy = true;
+      if (!busy && i > 3 && gpu.pipelines.pending === 0 && gpu.pipelines.skipped === 0) break;
+    }
+    for (let i = 0; i < 3; i++) app.update(1 / 60);
+    const shots = cameras.map((c) => captureView(w, c));
+    app.update(1 / 60);
+    const images = await Promise.all(shots);
+    if (images.length === 1) {
+      const image = images[0];
+      return { width: image.width, height: image.height, data: image.data };
+    }
+    const out = new Uint8Array(cellW * 2 * height * 4);
+    for (const [k, image] of images.entries()) {
+      for (let y = 0; y < height; y++) {
+        out.set(
+          image.data.subarray(y * cellW * 4, (y + 1) * cellW * 4),
+          (y * cellW * 2 + k * cellW) * 4
+        );
+      }
+    }
+    return { width: cellW * 2, height, data: out };
+  } finally {
+    await app.dispose();
+    for (const t of targets) t.destroy();
+  }
+}
+export {
+  PREVIEW_SIZE,
+  renderScatterPreview
+};

package/dist/preview.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A ScatterSet on a 64 m test patch (spec 0045), from above and at eye level (`options.view`:
+ * 'top', 'eye', or both side by side). `asset.preview` and `procgen.preview` use it.
+ */
+export declare const scatterSetPreview: import("@aethervtt/shard-assets").AssetPreview;

package/dist/preview.js

@@ -0,0 +1,11 @@
+import { defineAssetPreview } from "@aethervtt/shard-assets";
+const scatterSetPreview = defineAssetPreview(
+  "scatter/ScatterSet",
+  async (world, path, width, height, options) => {
+    const { renderScatterPreview } = await import("./preview-render.js");
+    return renderScatterPreview(world, path, width, height, options);
+  }
+);
+export {
+  scatterSetPreview
+};

package/dist/rules.d.ts

@@ -0,0 +1,97 @@
+import { type AssetRef, type JsonValue } from '@aethervtt/shard-core';
+import type { PropCollider, ScatterSetValue } from './set.js';
+/** Rule kinds as numbers. */
+export declare const PROP = 0;
+export declare const FOLIAGE = 1;
+/** Most items a prop chunk may hold: placement picks a chunk size to hold 64–1 024. */
+export declare const MAX_PROPS_PER_CHUNK = 1024;
+/** Most items a foliage chunk may hold (one GPU placement dispatch). */
+export declare const MAX_FOLIAGE_PER_CHUNK = 16384;
+export interface CompiledItem {
+    prefab: AssetRef | null;
+    /** Generator name, or '' for a prefab item. */
+    generator: string;
+    params: Record<string, JsonValue>;
+    variants: number;
+    material: AssetRef | null;
+    /** Footprint radius before scale, 0: from the mesh bounds. */
+    radius: number;
+}
+/** A rule as numbers, ready to place: its lattice, masks, and items. */
+export interface CompiledRule {
+    /** Index in the surface's compiled list (priority order). */
+    index: number;
+    name: string;
+    /** Stable across runs: the set's path, the biome it belongs to, and the rule's name. */
+    id: string;
+    kind: number;
+    /** The biome it applies in (−1: everywhere). */
+    biome: number;
+    seed: number;
+    density: number;
+    spacing: number;
+    /** Lattice cell size (m): at most one candidate per cell. */
+    cell: number;
+    slopeLo: number;
+    slopeHi: number;
+    heightLo: number;
+    heightHi: number;
+    noise: AssetRef | null;
+    noiseAbove: number;
+    align: number;
+    scaleMin: number;
+    scaleMax: number;
+    sink: number;
+    collider: PropCollider;
+    range: number;
+    wind: number;
+    shadowRange: number;
+    /** Indices of earlier rules whose footprints this one avoids. */
+    avoid: number[];
+    items: CompiledItem[];
+    /** Running sum of item weights, normalized to end at 1. */
+    weights: Float64Array;
+}
+/** A set with where its rules apply: everywhere, or a biome (by index in the BiomeSet). */
+export interface SetSource {
+    /** The set's asset path (rule ids, saves). */
+    path: string;
+    set: ScatterSetValue;
+    biome: number;
+}
+/**
+ * Turns sets into one priority-ordered rule list for a surface: a surface's own set first, then
+ * each biome's in biome order. Throws `scatter/unknown-rule` (an `avoid` naming no earlier rule),
+ * `scatter/density-too-high` (a density the spacing can't fit), and `scatter/no-items`.
+ */
+export declare function compileRules(sources: readonly SetSource[], surfaceSeed: number): CompiledRule[];
+/**
+ * The lattice cell for a density and spacing: about two cells per expected item (so acceptance is
+ * a coin flip, which hides the lattice), but never so small that jitter can't keep `spacing`.
+ */
+export declare function cellSize(density: number, spacing: number): number;
+/**
+ * Jitter as a fraction of a cell, for cells `cell` metres across: as much as `spacing` allows.
+ * Items sit in the middle `jitter` of their cell, so two in neighboring cells are at least
+ * `cell × (1 − jitter)` = `spacing` apart.
+ */
+export declare function jitterFor(cell: number, spacing: number): number;
+/** Streams of a cell's hash (the w lane of hash32), so each decision is independent. */
+export declare const STREAM_ACCEPT = 0;
+export declare const STREAM_X = 1;
+export declare const STREAM_Y = 2;
+export declare const STREAM_ITEM = 3;
+export declare const STREAM_VARIANT = 4;
+export declare const STREAM_YAW = 5;
+export declare const STREAM_SCALE = 6;
+export declare const STREAM_SHADE = 7;
+/**
+ * A cell's random number in [0, 1) for a stream: a hash of the rule's seed, the cell's global
+ * lattice coordinates, and its domain (a cube face, or 0 on a mesh). The foliage compute shader
+ * computes the same numbers.
+ */
+export declare function cellRandom(seed: number, gi: number, gj: number, domain: number, stream: number): number;
+/** The item a cell picks by weight. */
+export declare function pickItem(rule: CompiledRule, u: number): number;
+/** Whether `x` is within [lo, hi], or the range is open (lo ≥ hi). */
+export declare function inRange(x: number, lo: number, hi: number): boolean;