@aethervtt/shard-scatter 0.0.0-stage → 0.2.0

package/dist/methods.d.ts

@@ -0,0 +1,10 @@
+import { type World } from '@aethervtt/shard-core';
+import type { AppMethod } from '@aethervtt/shard-runtime';
+import { type SurfaceScatter } from './runtime.js';
+/** A scattered surface (a planet or a ScatterSurface entity), by id or scene path; the only one when omitted. */
+export declare function resolveSurface(world: World, ref: unknown): SurfaceScatter;
+/** Placements of prop rules within `radius` of a surface-frame point, nearest first. */
+export declare function samplePlacements(ss: SurfaceScatter, x: number, y: number, z: number, radius: number, frame: number, removed?: {
+    props: string[];
+}): Record<string, unknown>[];
+export declare const scatterMethods: AppMethod[];

package/dist/methods.js

@@ -0,0 +1,341 @@
+import {
+  defineSchema,
+  findComponent,
+  ShardError,
+  t
+} from "@aethervtt/shard-core";
+import { GlobalTransform, worldPosition64 } from "@aethervtt/shard-transform";
+import { isRemoved, Removed, removedKey, ScatterBudget } from "./components.js";
+import { FOLIAGE } from "./rules.js";
+import { chunkState, finalPlacements, Scatter } from "./runtime.js";
+import {
+  P_CELL,
+  P_ITEM,
+  P_SCALE,
+  P_VARIANT,
+  P_X,
+  PLACEMENT_STRIDE
+} from "./surface.js";
+function scenePath(world, entity) {
+  const member = findComponent("scene/SceneMember");
+  if (!member || !world.isAlive(entity)) return null;
+  const v = world.tryGet(entity, member);
+  return v?.path || null;
+}
+function resolveSurface(world, ref) {
+  const surfaces = world.tryResource(Scatter)?.surfaces;
+  if (!surfaces || surfaces.size === 0) {
+    throw new ShardError("scatter/no-surface", "Nothing in the world scatters", {
+      hint: "Give a Planet (or a Biome) a scatter set, or add scatter/ScatterSurface to a mesh entity; and add the scatter plugin."
+    });
+  }
+  if (ref === void 0 || ref === null || ref === "") {
+    if (surfaces.size > 1) {
+      throw new ShardError("scatter/which-surface", `${surfaces.size} surfaces scatter; name one`, {
+        hint: "Pass surface: an entity id or a scene path (scatter.describe lists them)."
+      });
+    }
+    return [...surfaces.values()][0];
+  }
+  for (const ss of surfaces.values()) {
+    if (ss.surface.entity === ref) return ss;
+    const path = scenePath(world, ss.surface.entity);
+    if (typeof ref === "string" && path && (path === ref || path.endsWith(`/${ref}`))) return ss;
+  }
+  throw new ShardError(
+    "scatter/not-a-surface",
+    `No scattered surface matches ${JSON.stringify(ref)}`,
+    {
+      hint: "scatter.describe lists every surface with its entity and scene path."
+    }
+  );
+}
+const round = (v, digits = 3) => {
+  const k = 10 ** digits;
+  return Math.round(v * k) / k;
+};
+function describeSurface(world, ss) {
+  const surface = ss.surface;
+  const rules = surface.rules.map((rule) => {
+    const s = ss.stats[rule.index];
+    const out = {
+      name: rule.name,
+      id: rule.id,
+      kind: rule.kind === FOLIAGE ? "foliage" : "prop",
+      biome: rule.biome,
+      range: rule.range,
+      cellsPerChunk: surface.cells[rule.index]
+    };
+    if (rule.kind === FOLIAGE) {
+      const f = ss.foliage.get(rule.index);
+      let drawn = 0;
+      let shadows = 0;
+      if (f) {
+        for (const view of f.layer.views.keys()) {
+          const v = f.layer.visible(view);
+          drawn += v.drawn;
+          shadows += v.shadows;
+        }
+      }
+      out.foliage = f ? {
+        chunks: f.layer.chunkCount,
+        capacity: f.layer.capacity,
+        visible: drawn,
+        shadowCasters: shadows,
+        meshes: f.layer.options.meshes.length
+      } : {
+        chunks: 0,
+        capacity: 0,
+        visible: 0,
+        shadowCasters: 0,
+        meshes: 0,
+        note: "No renderer: foliage is GPU-only."
+      };
+    } else {
+      out.chunksInRange = s?.chunks ?? 0;
+      out.placed = s?.placed ?? 0;
+      out.spawned = s?.spawned ?? 0;
+      out.candidates = s?.candidates ?? 0;
+    }
+    return out;
+  });
+  return {
+    entity: surface.entity,
+    path: scenePath(world, surface.entity),
+    kind: surface.kind,
+    ready: ss.ready,
+    waiting: ss.waiting,
+    problem: ss.problem ? { code: ss.problem.code, message: ss.problem.message, path: ss.problem.path } : null,
+    rules,
+    chunksCached: ss.chunks.size,
+    spawnedLastFrame: ss.spawnedLast,
+    despawnedLastFrame: ss.despawnedLast,
+    msLastFrame: round(ss.ms)
+  };
+}
+const surfaceField = t.json({
+  description: "The surface: a planet or ScatterSurface entity id or scene path (default: the only one)."
+});
+const probe = new Float64Array(3);
+function samplePlacements(ss, x, y, z, radius, frame, removed) {
+  const surface = ss.surface;
+  const out = [];
+  for (const rule of surface.rules) {
+    if (rule.kind === FOLIAGE) continue;
+    const seen = /* @__PURE__ */ new Map();
+    surface.upAt(x, y, z, probe);
+    const steps = 4;
+    for (let j = -steps; j <= steps; j++) {
+      for (let i = -steps; i <= steps; i++) {
+        const s = radius / steps;
+        const ux = probe[0];
+        const uy = probe[1];
+        const uz = probe[2];
+        const ax = Math.abs(uy) < 0.9 ? 0 : 1;
+        const ay = Math.abs(uy) < 0.9 ? 1 : 0;
+        let e1x = ay * uz;
+        let e1y = -ax * uz;
+        let e1z = ax * uy - ay * ux;
+        const l = Math.sqrt(e1x * e1x + e1y * e1y + e1z * e1z) || 1;
+        e1x /= l;
+        e1y /= l;
+        e1z /= l;
+        const e2x = uy * e1z - uz * e1y;
+        const e2y = uz * e1x - ux * e1z;
+        const e2z = ux * e1y - uy * e1x;
+        const c = surface.chunkAt(
+          rule,
+          x + (e1x * i + e2x * j) * s,
+          y + (e1y * i + e2y * j) * s,
+          z + (e1z * i + e2z * j) * s
+        );
+        seen.set(c.key, c);
+      }
+    }
+    for (const chunk of seen.values()) {
+      const id = `${rule.index}|${chunk.key}`;
+      let c = ss.chunks.get(id);
+      if (!c) {
+        c = chunkState(id, chunk, frame);
+        ss.chunks.set(id, c);
+      }
+      const p = finalPlacements(ss, c, frame);
+      for (let k = 0; k < p.count; k++) {
+        const o = k * PLACEMENT_STRIDE;
+        const px = chunk.center[0] + p.data[o + P_X];
+        const py = chunk.center[1] + p.data[o + P_X + 1];
+        const pz = chunk.center[2] + p.data[o + P_X + 2];
+        const d = Math.hypot(px - x, py - y, pz - z);
+        if (d > radius) continue;
+        const item = rule.items[p.data[o + P_ITEM]];
+        const index = p.data[o + P_CELL];
+        out.push({
+          d,
+          v: {
+            rule: rule.name,
+            set: rule.id.slice(0, rule.id.lastIndexOf(":")),
+            item: item.generator || item.prefab?.path || "",
+            variant: p.data[o + P_VARIANT],
+            position: [round(px), round(py), round(pz)],
+            distance: round(d),
+            scale: round(p.data[o + P_SCALE]),
+            chunk: chunk.key,
+            index,
+            removed: removed ? isRemoved(removed, removedKey(rule.id, chunk.key, index)) : false
+          }
+        });
+      }
+    }
+  }
+  out.sort((a, b) => a.d - b.d);
+  return out.map((o) => o.v);
+}
+function pointOf(world, ss, p) {
+  if (Array.isArray(p.position)) return p.position.slice(0, 3);
+  if (p.entity !== void 0 && p.entity !== null) {
+    let e;
+    if (typeof p.entity === "number") e = p.entity;
+    else {
+      const member = findComponent("scene/SceneMember");
+      for (const table of world.allTables()) {
+        if (!member || !table.has(member)) continue;
+        for (let row = 0; row < table.count; row++) {
+          const ent = table.entities[row];
+          const path = world.get(ent, member).path;
+          if (path === p.entity || path?.endsWith(`/${p.entity}`)) e = ent;
+        }
+      }
+    }
+    if (e === void 0 || !world.isAlive(e)) {
+      throw new ShardError("scatter/bad-point", `No entity ${JSON.stringify(p.entity)}`, {
+        hint: "Pass an entity id or a scene path."
+      });
+    }
+    if (ss.surface.kind === "planet" || ss.surface.kind === "heightfield") {
+      return Array.from(worldPosition64(world, e, new Float64Array(3), ss.surface.entity));
+    }
+    const g = world.get(e, GlobalTransform).matrix;
+    const s = world.get(ss.surface.entity, GlobalTransform).matrix;
+    const w = [g[3], g[7], g[11]];
+    const inv = invertAffine(s);
+    const scale = ss.surface.scale;
+    return [0, 1, 2].map(
+      (r) => (inv[r * 4] * w[0] + inv[r * 4 + 1] * w[1] + inv[r * 4 + 2] * w[2] + inv[r * 4 + 3]) * scale
+    );
+  }
+  if (Array.isArray(p.latlon) && ss.surface.kind === "planet") {
+    const [lat, lon] = p.latlon;
+    const a = lat * Math.PI / 180;
+    const b = lon * Math.PI / 180;
+    const r = ss.surface.rt.settings.radius;
+    return [Math.cos(a) * Math.sin(b) * r, Math.sin(a) * r, Math.cos(a) * Math.cos(b) * r];
+  }
+  throw new ShardError("scatter/bad-point", "Say where: position, entity, or latlon (planets)", {
+    hint: 'e.g. { "entity": "landing-pad", "radius": 10 }.'
+  });
+}
+function invertAffine(m) {
+  const a = m[0];
+  const b = m[1];
+  const c = m[2];
+  const d = m[4];
+  const e = m[5];
+  const f = m[6];
+  const g = m[8];
+  const h = m[9];
+  const i = m[10];
+  const det = a * (e * i - f * h) - b * (d * i - f * g) + c * (d * h - e * g) || 1;
+  const r = [
+    (e * i - f * h) / det,
+    (c * h - b * i) / det,
+    (b * f - c * e) / det,
+    (f * g - d * i) / det,
+    (a * i - c * g) / det,
+    (c * d - a * f) / det,
+    (d * h - e * g) / det,
+    (b * g - a * h) / det,
+    (a * e - b * d) / det
+  ];
+  const tx = m[3];
+  const ty = m[7];
+  const tz = m[11];
+  return [
+    r[0],
+    r[1],
+    r[2],
+    -(r[0] * tx + r[1] * ty + r[2] * tz),
+    r[3],
+    r[4],
+    r[5],
+    -(r[3] * tx + r[4] * ty + r[5] * tz),
+    r[6],
+    r[7],
+    r[8],
+    -(r[6] * tx + r[7] * ty + r[8] * tz)
+  ];
+}
+const scatterMethods = [
+  {
+    name: "scatter.describe",
+    description: "Scatter as data: per surface (a planet, or a ScatterSurface mesh), whether it is ready (or what it waits for, or its problem), and per rule its kind and range; props: chunks in range, placements, spawned entities, lattice candidates; foliage: GPU chunks, instance capacity, and instances visible and casting shadows (last read back). Also props spawned and despawned last frame and the main-thread milliseconds it took.",
+    params: defineSchema("scatter/DescribeParams", { surface: surfaceField }),
+    handler: ({ world }, p) => {
+      const surfaces = world.tryResource(Scatter)?.surfaces;
+      if (!surfaces) return { surfaces: [] };
+      const removed = world.tryResource(Removed)?.props.length ?? 0;
+      const budget = world.tryResource(ScatterBudget);
+      const list = p.surface !== void 0 && p.surface !== null && p.surface !== "" ? [resolveSurface(world, p.surface)] : [...surfaces.values()];
+      return { surfaces: list.map((ss) => describeSurface(world, ss)), removed, budget };
+    }
+  },
+  {
+    name: "scatter.sample",
+    description: 'Prop placements near a point, from the CPU placement (headless-safe, whether or not they are spawned): rule, set, item, variant, position (surface frame), distance, scale, chunk and index, and whether the game removed it. Ask "what is within 10 m of the landing pad" and move the pad. Foliage is GPU-only and not listed.',
+    params: defineSchema("scatter/SampleParams", {
+      surface: surfaceField,
+      position: t.json({
+        description: "A point in the surface\u2019s frame: [x, y, z] (planet frame, or the mesh\u2019s local metres)."
+      }),
+      entity: t.json({
+        description: "Or an entity (id or scene path) whose position is the point."
+      }),
+      latlon: t.json({ description: "Or, on a planet, [lat, lon] in degrees." }),
+      radius: t.f32({ default: 10, min: 0.1, max: 500, unit: "m" })
+    }),
+    handler: ({ world }, p) => {
+      const ss = resolveSurface(world, p.surface);
+      if (ss.problem) throw ss.problem;
+      if (!ss.ready || !ss.surface.ready) {
+        throw new ShardError(
+          "scatter/not-ready",
+          `The surface is waiting for ${ss.waiting ?? "its sets"}`,
+          {
+            hint: "Sets and item meshes load asynchronously; step a frame and ask again."
+          }
+        );
+      }
+      const [x, y, z] = pointOf(world, ss, p);
+      const frame = world.resource(Scatter).frame;
+      const placements = samplePlacements(
+        ss,
+        x,
+        y,
+        z,
+        p.radius,
+        frame,
+        world.tryResource(Removed)
+      );
+      return {
+        point: [round(x), round(y), round(z)],
+        radius: p.radius,
+        count: placements.length,
+        placements
+      };
+    }
+  }
+];
+export {
+  resolveSurface,
+  samplePlacements,
+  scatterMethods
+};

package/dist/overlays.d.ts

@@ -0,0 +1,4 @@
+/** Spawned props as dots (a short upright tick per item), colored by rule. */
+export declare const scatterOverlay: import("@aethervtt/shard-render").OverlayDef;
+/** Foliage chunks' borders on the ground (green when placed on the GPU, amber while building). */
+export declare const foliageChunksOverlay: import("@aethervtt/shard-render").OverlayDef;

package/dist/overlays.js

@@ -0,0 +1,84 @@
+import { hash32 } from "@aethervtt/shard-core";
+import { defineOverlay } from "@aethervtt/shard-render";
+import { Scatter } from "./runtime.js";
+import { P_SCALE, P_X, PLACEMENT_STRIDE } from "./surface.js";
+const rows = new Float32Array(12);
+const a = new Float32Array(3);
+const b = new Float32Array(3);
+const colors = /* @__PURE__ */ new Map();
+function ruleColor(id) {
+  let c = colors.get(id);
+  if (c) return c;
+  let h = 0;
+  for (let i = 0; i < id.length; i++) h = hash32(h, id.charCodeAt(i));
+  const hue = h % 360 / 60;
+  const x = 1 - Math.abs(hue % 2 - 1);
+  const rgb = hue < 1 ? [1, x, 0] : hue < 2 ? [x, 1, 0] : hue < 3 ? [0, 1, x] : hue < 4 ? [0, x, 1] : hue < 5 ? [x, 0, 1] : [1, 0, x];
+  c = [...rgb, 1];
+  colors.set(id, c);
+  return c;
+}
+function toWorld(x, y, z, out) {
+  out[0] = rows[0] * x + rows[1] * y + rows[2] * z + rows[3];
+  out[1] = rows[4] * x + rows[5] * y + rows[6] * z + rows[7];
+  out[2] = rows[8] * x + rows[9] * y + rows[10] * z + rows[11];
+  return out;
+}
+const scatterOverlay = defineOverlay({
+  name: "scatter",
+  description: "Scatter placements: a tick at every spawned prop, colored by rule (each rule keeps its color), to see density, spacing and masks at a glance.",
+  draw: (world, g) => {
+    const state = world.tryResource(Scatter);
+    if (!state) return;
+    for (const ss of state.surfaces.values()) {
+      for (const c of ss.chunks.values()) {
+        if (c.root < 0 || !c.placements) continue;
+        const rule = ss.surface.rules[c.chunk.rule];
+        const color = ruleColor(rule.id);
+        ss.surface.chunkTransform(world, c.chunk, rows);
+        const p = c.placements;
+        ss.surface.upAt(c.chunk.center[0], c.chunk.center[1], c.chunk.center[2], up);
+        for (let i = 0; i < p.count; i++) {
+          const o = i * PLACEMENT_STRIDE;
+          const x = p.data[o + P_X];
+          const y = p.data[o + P_X + 1];
+          const z = p.data[o + P_X + 2];
+          const s = 0.6 * p.data[o + P_SCALE];
+          toWorld(x, y, z, a);
+          toWorld(x + up[0] * s, y + up[1] * s, z + up[2] * s, b);
+          g.line(a, b, color);
+        }
+      }
+    }
+  }
+});
+const up = new Float64Array(3);
+const LIVE = [0.3, 1, 0.5, 1];
+const WAITING = [1, 0.75, 0.2, 1];
+const foliageChunksOverlay = defineOverlay({
+  name: "foliage-chunks",
+  description: "GPU foliage chunks: each one\u2019s border on the ground, green once placed on the GPU and amber while its ground patch is still being built.",
+  draw: (world, g) => {
+    const state = world.tryResource(Scatter);
+    if (!state) return;
+    for (const ss of state.surfaces.values()) {
+      for (const f of ss.foliage.values()) {
+        for (const c of f.chunks.values()) {
+          if (!c.corners) continue;
+          ss.surface.chunkTransform(world, c.chunk, rows);
+          const color = c.slot >= 0 ? LIVE : WAITING;
+          for (let k = 0; k < 4; k++) {
+            const n = (k + 1) % 4;
+            toWorld(c.corners[k * 3], c.corners[k * 3 + 1], c.corners[k * 3 + 2], a);
+            toWorld(c.corners[n * 3], c.corners[n * 3 + 1], c.corners[n * 3 + 2], b);
+            g.line(a, b, color);
+          }
+        }
+      }
+    }
+  }
+});
+export {
+  foliageChunksOverlay,
+  scatterOverlay
+};

package/dist/planet.d.ts

@@ -0,0 +1,74 @@
+import type { Entity, Query, World } from '@aethervtt/shard-core';
+import { type NoiseGraph } from '@aethervtt/shard-noise';
+import type { Workers } from '@aethervtt/shard-platform';
+import { type PlanetRuntime } from '@aethervtt/shard-terrain';
+import { type CompiledRule } from './rules.js';
+import { type ChunkPlacements, type FoliagePatch, type PatchJob, type PlacementJob, type Surface, type SurfaceChunk } from './surface.js';
+/** Metres along a face edge per node at `depth` (a quarter circle over 2^depth nodes). */
+export declare const nodeMetres: (radius: number, depth: number) => number;
+/**
+ * The quadtree depth a rule places at: props aim for about 256 items a chunk (64–1 024); foliage
+ * uses the collider depth (about 1 m between the chunk's 33 vertices, the ground it's drawn on),
+ * deeper if a chunk would hold more than one dispatch can place.
+ */
+export declare function ruleDepth(rule: CompiledRule, radius: number, colliderDepth: number): number;
+/** Lattice cells per chunk side for a rule at a depth: cells the rule's size, aligned to chunks. */
+export declare function cellsPerChunk(rule: CompiledRule, radius: number, depth: number): number;
+/** A planet's scatter surface: its rules on the cube-sphere quadtree, sampled from its graphs. */
+export declare class PlanetSurface implements Surface {
+    readonly kind = "planet";
+    readonly entity: Entity;
+    rules: CompiledRule[];
+    version: number;
+    /** Per rule: chunk depth and cells per chunk side. */
+    depths: number[];
+    cells: number[];
+    /** Graph values of each rule's noise mask, by rule index (undefined: no mask). */
+    masks: (NoiseGraph | undefined)[];
+    readonly rt: PlanetRuntime;
+    private readonly cameras;
+    constructor(rt: PlanetRuntime, cameras: Query);
+    get ready(): boolean;
+    /** Rebuilds per-rule depths after the rules or the planet changed. */
+    configure(rules: CompiledRule[], masks: (NoiseGraph | undefined)[], version: number): void;
+    viewers(world: World, out: {
+        points: Float64Array;
+        cameras: number;
+        anchors: number;
+    }): void;
+    chunksNear(rule: CompiledRule, viewers: Float64Array, first: number, count: number, range: number, visit: (chunk: SurfaceChunk, distance: number) => void): void;
+    /** A chunk of `rule` (its center and extent filled in). */
+    chunk(rule: CompiledRule, face: number, depth: number, x: number, y: number): SurfaceChunk;
+    chunkAt(rule: CompiledRule, x: number, y: number, z: number): SurfaceChunk;
+    upAt(x: number, y: number, z: number, out: Float64Array): Float64Array;
+    placeChunkRoot(world: World, root: Entity, chunk: SurfaceChunk): void;
+    startPlacement(chunk: SurfaceChunk, due: number, workers: Workers | undefined): PlacementJob;
+    finishPlacement(job: PlacementJob): ChunkPlacements;
+    /**
+     * A chunk's lattice: cells per side, and the chance and jitter of each cell from the chunk's real
+     * size (its edges measured across the middle; cells aren't square on a cube-sphere).
+     */
+    lattice(rule: CompiledRule, chunk: SurfaceChunk): {
+        k: number;
+        accept: number;
+        jitter: number;
+    };
+    /** The chunk's lattice cells that pass the acceptance roll, as directions and sample points. */
+    private candidates;
+    startPatch(chunk: SurfaceChunk, workers: Workers | undefined): PatchJob;
+    /**
+     * The chunk's ground as terrain builds it (the collider chunk's own vertices at the collider
+     * depth, so grass stands on the drawn ground), with the rule's density at each vertex: its
+     * height, slope and noise masks, and its biome.
+     */
+    finishPatch(job: PatchJob): FoliagePatch;
+    chunkTransform(_world: World, chunk: SurfaceChunk, out: Float32Array): void;
+    private sampleInline;
+    /** Samples into placements: masks, biome, then each item's transform from its cell's hashes. */
+    private assemble;
+}
+/**
+ * The rotation taking +Y to `up`, after a yaw about +Y, as a quaternion (xyzw) into `out`. Trig
+ * through `sinCos`, so the bits match on every host.
+ */
+export declare function writeRotation(ux: number, uy: number, uz: number, yaw: number, out: Float32Array, o: number): void;