@aethervtt/shard-scatter 0.0.0-stage → 0.2.0

package/dist/rules.js

@@ -0,0 +1,170 @@
+import { hash32, hashSeed, ShardError } from "@aethervtt/shard-core";
+const PROP = 0;
+const FOLIAGE = 1;
+const MAX_PROPS_PER_CHUNK = 1024;
+const MAX_FOLIAGE_PER_CHUNK = 16384;
+const MIN_JITTER = 0.4;
+function compileRules(sources, surfaceSeed) {
+  const out = [];
+  for (const source of sources) {
+    const byName = /* @__PURE__ */ new Map();
+    for (const [r, rule] of source.set.rules.entries()) {
+      const path = `${source.path}#/rules/${r}`;
+      if (byName.has(rule.name)) {
+        throw new ShardError("scatter/duplicate-rule", `Two rules are named "${rule.name}"`, {
+          path,
+          hint: "Rule names are unique within a set: saves and `avoid` refer to them."
+        });
+      }
+      const avoid = [];
+      for (const name of rule.avoid) {
+        const target = byName.get(name);
+        if (target === void 0) {
+          throw new ShardError(
+            "scatter/unknown-rule",
+            `Rule "${rule.name}" avoids "${name}", which isn't an earlier rule of its set`,
+            {
+              path: `${path}/avoid`,
+              hint: `Earlier rules: ${[...byName.keys()].join(", ") || "none"}. Rule order is priority, so the avoided rule goes first.`
+            }
+          );
+        }
+        avoid.push(target);
+      }
+      const items = rule.items.filter((i) => i.weight > 0);
+      if (items.length === 0) {
+        throw new ShardError("scatter/no-items", `Rule "${rule.name}" has nothing to place`, {
+          path: `${path}/items`,
+          hint: 'Add an item: { "generator": "shard/Rock" } or { "prefab": { "path": "\u2026" } }.'
+        });
+      }
+      for (const [i, item] of items.entries()) {
+        if (!item.prefab && !item.generator) {
+          throw new ShardError(
+            "scatter/item-not-mesh",
+            `Item ${i} of rule "${rule.name}" has neither a prefab nor a generator`,
+            { path: `${path}/items/${i}`, hint: 'Set "generator" (a mesh generator) or "prefab".' }
+          );
+        }
+        if (rule.kind === "foliage" && !item.generator) {
+          throw new ShardError(
+            "scatter/item-not-mesh",
+            `Foliage rule "${rule.name}" places a prefab; foliage draws meshes only`,
+            {
+              path: `${path}/items/${i}`,
+              hint: 'Use a mesh generator item ("shard/GrassClump"), or make the rule kind "prop".'
+            }
+          );
+        }
+      }
+      const kind = rule.kind === "foliage" ? FOLIAGE : PROP;
+      const cell = cellSize(rule.density, rule.spacing);
+      if (rule.density > 0 && rule.density * cell * cell > 1 + 1e-9) {
+        const most = (1 - MIN_JITTER) ** 2 / (rule.spacing * rule.spacing);
+        throw new ShardError(
+          "scatter/density-too-high",
+          `Rule "${rule.name}" asks for ${rule.density}/m\xB2 with ${rule.spacing} m spacing; at most ${most.toPrecision(3)}/m\xB2 fit`,
+          {
+            path: `${path}/density`,
+            hint: "Lower the density or the spacing: items keep `spacing` apart on a jittered lattice."
+          }
+        );
+      }
+      let sum = 0;
+      for (const item of items) sum += item.weight;
+      const weights = new Float64Array(items.length);
+      let acc = 0;
+      for (const [i, item] of items.entries()) {
+        acc += item.weight / sum;
+        weights[i] = i === items.length - 1 ? 1 : acc;
+      }
+      const id = `${source.path}${source.biome >= 0 ? `@${source.biome}` : ""}:${rule.name}`;
+      out.push({
+        index: out.length,
+        name: rule.name,
+        id,
+        kind,
+        biome: source.biome,
+        seed: hashSeed(surfaceSeed ^ source.set.seed, id),
+        density: rule.density,
+        spacing: rule.spacing,
+        cell,
+        slopeLo: rule.masks.slope[0],
+        slopeHi: rule.masks.slope[1],
+        heightLo: rule.masks.height[0],
+        heightHi: rule.masks.height[1],
+        noise: rule.masks.noise.graph,
+        noiseAbove: rule.masks.noise.above,
+        align: rule.align,
+        scaleMin: Math.min(rule.scale[0], rule.scale[1]),
+        scaleMax: Math.max(rule.scale[0], rule.scale[1]),
+        sink: rule.sink,
+        collider: rule.collider,
+        range: rule.range,
+        wind: rule.wind,
+        shadowRange: rule.shadowRange,
+        avoid: avoid.map((a) => out.length - byName.size + a),
+        items: items.map((i) => ({
+          prefab: i.prefab,
+          generator: i.generator,
+          params: i.params && typeof i.params === "object" && !Array.isArray(i.params) ? i.params : {},
+          variants: Math.max(1, i.variants),
+          material: i.material,
+          radius: i.radius
+        })),
+        weights
+      });
+      byName.set(rule.name, r);
+    }
+  }
+  return out;
+}
+function cellSize(density, spacing) {
+  const byDensity = density > 0 ? 1 / Math.sqrt(2 * density) : Number.POSITIVE_INFINITY;
+  const bySpacing = spacing > 0 ? spacing / (1 - MIN_JITTER) : 0;
+  return Math.max(byDensity, bySpacing);
+}
+function jitterFor(cell, spacing) {
+  if (!(spacing > 0)) return 1;
+  return Math.max(0, Math.min(1, 1 - spacing / cell));
+}
+const STREAM_ACCEPT = 0;
+const STREAM_X = 1;
+const STREAM_Y = 2;
+const STREAM_ITEM = 3;
+const STREAM_VARIANT = 4;
+const STREAM_YAW = 5;
+const STREAM_SCALE = 6;
+const STREAM_SHADE = 7;
+const INV32 = 1 / 4294967296;
+function cellRandom(seed, gi, gj, domain, stream) {
+  return hash32(seed, gi, gj, domain, stream) * INV32;
+}
+function pickItem(rule, u) {
+  const w = rule.weights;
+  for (let i = 0; i < w.length - 1; i++) if (u < w[i]) return i;
+  return w.length - 1;
+}
+function inRange(x, lo, hi) {
+  return !(lo < hi) || x >= lo && x <= hi;
+}
+export {
+  FOLIAGE,
+  MAX_FOLIAGE_PER_CHUNK,
+  MAX_PROPS_PER_CHUNK,
+  PROP,
+  STREAM_ACCEPT,
+  STREAM_ITEM,
+  STREAM_SCALE,
+  STREAM_SHADE,
+  STREAM_VARIANT,
+  STREAM_X,
+  STREAM_Y,
+  STREAM_YAW,
+  cellRandom,
+  cellSize,
+  compileRules,
+  inRange,
+  jitterFor,
+  pickItem
+};

package/dist/runtime.d.ts

@@ -0,0 +1,138 @@
+import { type AssetRef, type Entity, ShardError, type World } from '@aethervtt/shard-core';
+import type { Workers } from '@aethervtt/shard-platform';
+import { type GenRequest } from '@aethervtt/shard-procgen';
+import { type PlanetRuntime } from '@aethervtt/shard-terrain';
+import { type ScatterBudgetValue } from './components.js';
+import type { FoliageRule } from './foliage.js';
+import { type CompiledRule, type SetSource } from './rules.js';
+import { type ChunkPlacements, type PlacementJob, type Surface, type SurfaceChunk } from './surface.js';
+/** Frames between wanting a chunk's placements and having them, pool or not (deterministic). */
+export declare const PLACEMENT_DELAY = 2;
+/** One mesh an item places: a generator variant (with LODs) or a prefab. */
+export interface ItemVariant {
+    request: GenRequest | undefined;
+    mesh: AssetRef<'Mesh'> | null;
+    lods: AssetRef<'Mesh'>[];
+    prefab: AssetRef<'Prefab'> | null;
+    material: AssetRef<'Material'> | null;
+    /** Bounds height and lowest point (m, before scale). */
+    height: number;
+    minY: number;
+    /** Footprint radius before scale (m). */
+    radius: number;
+    /** Half extents and center of the bounds (cuboid colliders). */
+    half: [number, number, number];
+    mid: [number, number, number];
+    ready: boolean;
+    /** The components every prop of this variant spawns with (made on first spawn). */
+    parts?: unknown[];
+}
+/** One rule's chunk: its placements, its job while placing, and its entity while spawned. */
+export interface ChunkState {
+    id: string;
+    chunk: SurfaceChunk;
+    /** Placements before `avoid`. */
+    raw: ChunkPlacements | undefined;
+    /** Placements with `avoid` applied: what spawns. */
+    placements: ChunkPlacements | undefined;
+    job: PlacementJob | undefined;
+    root: Entity;
+    /** Frame a viewer last had it within range (spawn) and within KEEP × range (keep). */
+    wanted: number;
+    kept: number;
+    distance: number;
+    /** Frame last touched (cache order). */
+    used: number;
+    spawned: number;
+    /** The next placement to spawn: a chunk spawns over several frames within the budget. */
+    next: number;
+    /** The avoided rules' chunks around it (placed before it spawns). */
+    deps?: ChunkState[];
+    /** Frame another chunk last needed its placements (for `avoid`). */
+    needed?: number;
+}
+/** A chunk's state before anything is placed or spawned. */
+export declare function chunkState(id: string, chunk: SurfaceChunk, frame: number, distance?: number): ChunkState;
+export interface RuleStats {
+    chunks: number;
+    placed: number;
+    spawned: number;
+    candidates: number;
+}
+/** A surface's scatter state: compiled rules, item meshes, chunks, jobs. */
+export declare class SurfaceScatter {
+    readonly surface: Surface;
+    /** What the compiled rules came from (sets as JSON, seeds, planet contents). */
+    key: string;
+    /** The surface's content version last refreshed against. */
+    content: string;
+    problem: ShardError | null;
+    waiting: string | null;
+    /** [rule][item][variant] */
+    variants: ItemVariant[][][];
+    readonly chunks: Map<string, ChunkState>;
+    /** Chunks spawned or waiting to, by id. */
+    ready: boolean;
+    readonly stats: RuleStats[];
+    /** Foliage rules' GPU layers (with a renderer), by rule index, and the rules' version they're for. */
+    readonly foliage: Map<number, FoliageRule>;
+    foliageVersion: number;
+    /** Props spawned and despawned last frame, main-thread ms of the scatter system. */
+    spawnedLast: number;
+    despawnedLast: number;
+    ms: number;
+    /** Main-thread ms spawning and despawning props last frame. */
+    spawnMs: number;
+    constructor(surface: Surface);
+}
+/** Every surface's scatter state and the frame counter. */
+export declare class ScatterState {
+    readonly surfaces: Map<number, SurfaceScatter>;
+    frame: number;
+    workers: Workers | undefined;
+    /** Set when an asset (re)loaded: surfaces re-resolve their sets. */
+    dirty: boolean;
+    /** True while scatter despawns its own chunks (so props aren't recorded as removed). */
+    despawning: boolean;
+    /** Default vegetation materials, per generator name. */
+    readonly materials: Map<string, AssetRef<"Material">>;
+    /** Props despawned outside scatter since the last frame (checked, then recorded as removed). */
+    readonly pendingRemovals: {
+        rule: string;
+        chunk: string;
+        index: number;
+        root: Entity;
+    }[];
+}
+export declare const Scatter: import("@aethervtt/shard-core").ResourceDef<ScatterState>;
+/** A loaded asset, undefined for no handle, or null while it loads (the load starts here). */
+export declare function resolveAsset<T>(world: World, ref: AssetRef | null | undefined, get: (guid: string) => T | undefined): T | undefined | null;
+/** The sets a planet scatters: its own, then each biome's (where that biome dominates). */
+export declare function planetSources(world: World, rt: PlanetRuntime): {
+    sources: SetSource[];
+    waiting: string | null;
+};
+/** Whether a planet scatters anything (its own set, or any biome's). */
+export declare function planetScatters(world: World, rt: PlanetRuntime): boolean;
+/**
+ * Brings a surface's compiled rules and item meshes up to date. Cheap when nothing changed (a key
+ * compare). Returns whether it can place.
+ */
+export declare function refreshSurface(world: World, ss: SurfaceScatter, sources: SetSource[], seed: number, contentKey: string): boolean;
+/** The engine's look for a generator's items (scatter/Vegetation), made once per world. */
+export declare function defaultMaterial(world: World, generator: string): AssetRef<'Material'> | null;
+/** Despawns every chunk and forgets placements (rules or the surface changed). */
+export declare function clearChunks(world: World, ss: SurfaceScatter): void;
+/**
+ * One frame of a surface's props (spec 0045): which chunks viewers want, placement (on the pool,
+ * finished inline when due), `avoid`, then spawning nearest first within the budget and despawning
+ * what's out of range. Deterministic: the same viewers give the same entities on every host.
+ */
+export declare function updateProps(world: World, ss: SurfaceScatter, frame: number, budget: ScatterBudgetValue, workers: Workers | undefined): void;
+/**
+ * A chunk's placements with `avoid` applied: anything within an avoided item's footprint is
+ * dropped. The avoided rules' chunks around it are placed first (inline if they aren't yet).
+ */
+export declare function finalPlacements(ss: SurfaceScatter, c: ChunkState, frame: number): ChunkPlacements;
+/** The avoided rule's chunks that could hold an item reaching into `chunk`. */
+export declare function neighborChunks(ss: SurfaceScatter, avoided: CompiledRule, chunk: SurfaceChunk, frame: number): ChunkState[];