@aethervtt/shard-scatter 0.0.0-stage → 0.2.1

package/dist/set.d.ts

@@ -0,0 +1,45 @@
+/** Collider shapes a prop rule can give its items (fixed bodies; none by default). */
+export declare const PROP_COLLIDERS: readonly ['none', 'convex', 'trimesh', 'ball', 'cuboid'];
+export type PropCollider = (typeof PROP_COLLIDERS)[number];
+/**
+ * Rules that place props and foliage on a surface (spec 0045): a planet everywhere
+ * (`Planet.scatter`), a planet's biome where it dominates (`Biome.scatter`), or a mesh
+ * (`scatter/ScatterSurface`). Rule order is priority: `avoid` names earlier rules.
+ */
+export declare const ScatterSet: import("@aethervtt/shard-assets").DataType<{
+    readonly rules: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+        name: import("@aethervtt/shard-core").FieldType<string, "object">;
+        kind: import("@aethervtt/shard-core").FieldType<"foliage" | "prop", "u8">;
+        items: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+            prefab: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Prefab"> | null, "object">;
+            generator: import("@aethervtt/shard-core").FieldType<string, "object">;
+            params: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").JsonValue, "object">;
+            variants: import("@aethervtt/shard-core").FieldType<number, "u8">;
+            material: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"Material"> | null, "object">;
+            weight: import("@aethervtt/shard-core").FieldType<number, "f32">;
+            radius: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        }>[], "object">;
+        density: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        spacing: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        masks: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+            slope: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+            height: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+            noise: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").InferFields<{
+                graph: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").AssetRef<"NoiseGraph"> | null, "object">;
+                above: import("@aethervtt/shard-core").FieldType<number, "f32">;
+            }>, "object">;
+        }>, "object">;
+        align: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        scale: import("@aethervtt/shard-core").FieldType<import("@aethervtt/shard-core").Vec2, "f32">;
+        sink: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        collider: import("@aethervtt/shard-core").FieldType<"ball" | "convex" | "cuboid" | "none" | "trimesh", "u8">;
+        range: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        avoid: import("@aethervtt/shard-core").FieldType<string[], "object">;
+        wind: import("@aethervtt/shard-core").FieldType<number, "f32">;
+        shadowRange: import("@aethervtt/shard-core").FieldType<number, "f32">;
+    }>[], "object">;
+    readonly seed: import("@aethervtt/shard-core").FieldType<number, "u32">;
+}, "scatter/ScatterSet">;
+export type ScatterSetValue = ReturnType<typeof ScatterSet.defaults>;
+export type ScatterRuleValue = ScatterSetValue['rules'][number];
+export type ScatterItemValue = ScatterRuleValue['items'][number];

package/dist/set.js

@@ -0,0 +1,131 @@
+import { defineDataType } from "@aethervtt/shard-assets";
+import { t } from "@aethervtt/shard-core";
+const PROP_COLLIDERS = ["none", "convex", "trimesh", "ball", "cuboid"];
+const item = t.struct({
+  prefab: t.handle("Prefab", {
+    description: "A prefab to place (its root gets the placement transform). Or use generator."
+  }),
+  generator: t.string({
+    description: 'A mesh generator by name: "shard/Rock", "shard/Tree", "shard/Bush", "shard/GrassClump", "shard/Crystal", or a project\u2019s ("star-explorer/Rock").'
+  }),
+  params: t.json({ description: "The generator\u2019s params (missing ones take its defaults)." }),
+  variants: t.u8({
+    default: 1,
+    min: 1,
+    max: 32,
+    description: "Distinct meshes generated (seeds are the rule\u2019s child seeds 0 \u2026 n\u22121); each placement picks one. 4\u20138 read as unique once scaled and rotated."
+  }),
+  material: t.handle("Material", {
+    description: "The generator item\u2019s material (default: scatter/Vegetation tinted for the generator)."
+  }),
+  weight: t.f32({
+    default: 1,
+    min: 0,
+    description: "Relative chance among the rule\u2019s items."
+  }),
+  radius: t.f32({
+    min: 0,
+    unit: "m",
+    description: "Footprint radius for `avoid` and `sink` before scale (0: from the mesh\u2019s bounds; prefabs: half the rule\u2019s spacing)."
+  })
+});
+const range = (what, unit, typical) => t.vec2({
+  unit,
+  description: `[min, max] ${what}. Equal ends (the default): anywhere. ${typical}`
+});
+const rule = t.struct({
+  name: t.string({
+    required: true,
+    description: "Unique in the set: `avoid` lists, saves, and scatter.describe use it."
+  }),
+  kind: t.enum(["prop", "foliage"], {
+    description: "prop: entities (colliders, saves, gameplay), a few thousand near the player. foliage: GPU instances only (grass, flowers), millions, no entities."
+  }),
+  items: t.list(item, { description: "What it places, picked by weight." }),
+  density: t.f32({
+    default: 0.01,
+    min: 0,
+    unit: "1/m\xB2",
+    description: "Items per square metre where the masks pass. Typical: boulders 0.002\u20130.01, trees 0.005\u20130.05, bushes 0.02\u20130.1, grass 4\u201310, flowers 0.5\u20132."
+  }),
+  spacing: t.f32({
+    min: 0,
+    unit: "m",
+    description: "Least distance between two items of this rule (0: none). Typical: about an item\u2019s diameter (trees 3\u20136, boulders 4\u20138)."
+  }),
+  masks: t.struct(
+    {
+      slope: range("slope", "deg", "Grass 0\u201325, trees 0\u201330, boulders 0\u201335, cliff rocks 35\u201390."),
+      height: range(
+        "height",
+        "m",
+        "Metres above the planet radius (a mesh surface: its local y). Beaches \u22122\u20134, treeline below 1 200."
+      ),
+      noise: t.struct(
+        {
+          graph: t.handle("NoiseGraph", {
+            description: "A noise graph (*.noise.json) sampled where items would go."
+          }),
+          above: t.f32({
+            description: "Items only where the graph\u2019s value is above this (\u22121 to 1). 0.2 makes patches."
+          })
+        },
+        { description: "Patches: items only where a noise graph is above a threshold." }
+      )
+    },
+    { description: "Where items may go, on top of the biome the set belongs to." }
+  ),
+  align: t.f32({
+    min: 0,
+    max: 1,
+    description: "Up axis from world up (0, radial on a planet) to the surface normal (1). Trees 0, rocks 0.6\u20131, grass 0.3."
+  }),
+  scale: t.vec2({
+    default: [1, 1],
+    min: 0,
+    description: "Uniform scale range [min, max] per item. Typical [0.7, 1.4]."
+  }),
+  sink: t.f32({
+    min: 0,
+    max: 1,
+    description: "Pushes items into the ground by this fraction of their height. Rocks 0.1\u20130.3."
+  }),
+  collider: t.enum(PROP_COLLIDERS, {
+    description: "Props: a fixed collider from the item\u2019s coarsest mesh (convex, trimesh) or its bounds (ball, cuboid). Foliage ignores it."
+  }),
+  range: t.f32({
+    default: 200,
+    min: 1,
+    unit: "m",
+    description: "Distance from the camera (or a TerrainAnchor, for props) at which items exist. Grass 40\u201380, bushes 100\u2013200, trees 300\u2013800, boulders 300\u2013600."
+  }),
+  avoid: t.list(t.string, {
+    description: 'Earlier rules whose items keep this one out of their footprint (by the placed item\u2019s radius): ["boulders"] keeps grass off rocks.'
+  }),
+  wind: t.f32({
+    default: 1,
+    min: 0,
+    description: "Foliage: how much the wind sways it (0 rigid, 1 grass)."
+  }),
+  shadowRange: t.f32({
+    default: 30,
+    min: 0,
+    unit: "m",
+    description: "Foliage: casts shadows within this distance of the camera (0: never)."
+  })
+});
+const ScatterSet = defineDataType(
+  "scatter/ScatterSet",
+  {
+    rules: t.list(rule, { description: "Placement rules, highest priority first." }),
+    seed: t.u32({ description: "Mixed into every rule\u2019s seed: the same rules, new places." })
+  },
+  {
+    extension: "scatter",
+    description: "Scatter rules: props (entities) and foliage (GPU instances) placed by density, spacing, masks, alignment, and random transforms, the same on every visit and machine."
+  }
+);
+export {
+  PROP_COLLIDERS,
+  ScatterSet
+};

package/dist/surface.d.ts

@@ -0,0 +1,124 @@
+import type { Entity, World } from '@aethervtt/shard-core';
+import type { NoiseGraph } from '@aethervtt/shard-noise';
+import type { Workers } from '@aethervtt/shard-platform';
+import type { CompiledRule } from './rules.js';
+/**
+ * Floats per placement in a chunk's placements: item, variant, position (xyz, relative to the
+ * chunk's center, in the surface's frame, before sink), rotation (xyzw), scale, cell index (the
+ * placement's stable id in the chunk), footprint radius (scaled, for `avoid`; 0 until the item's
+ * bounds are known), and the shade variation in [0, 1].
+ */
+export declare const PLACEMENT_STRIDE = 13;
+export declare const P_ITEM = 0;
+export declare const P_VARIANT = 1;
+export declare const P_X = 2;
+export declare const P_QX = 5;
+export declare const P_SCALE = 9;
+export declare const P_CELL = 10;
+export declare const P_RADIUS = 11;
+export declare const P_SHADE = 12;
+/** A chunk of one rule's lattice: a quadtree node on a planet, a square on a mesh. */
+export interface SurfaceChunk {
+    /** The chunk's address as text: `face/depth/x/y` on a planet, `x/z` on a mesh. */
+    key: string;
+    rule: number;
+    face: number;
+    depth: number;
+    x: number;
+    y: number;
+    /** Center at zero height, in the surface's frame. */
+    center: Float64Array;
+    /** Half the chunk's diagonal (m): a chunk is in range when its center is within range + this. */
+    extent: number;
+}
+/** A chunk's placements, cached per (surface version, rule, chunk). */
+export interface ChunkPlacements {
+    chunk: SurfaceChunk;
+    count: number;
+    data: Float32Array;
+    /** Candidates tested (lattice cells), for scatter.describe. */
+    candidates: number;
+}
+/** Placement in progress: sampling on the pool, assembled on the main thread when due. */
+export interface PlacementJob {
+    chunk: SurfaceChunk;
+    /** Frame it must be finished by (placed inline then if the pool hasn't answered). */
+    due: number;
+    /** The pool's samples arrived. */
+    ready: boolean;
+    cancelled: boolean;
+    /** Surface-specific state (candidates, samples). */
+    state: unknown;
+}
+/**
+ * What placement needs from a surface: its frame, its chunk grid per rule, and its heights, normals
+ * and masks at candidate points. Planets (0043), meshes (`ScatterSurface`) and heightfield terrains
+ * (0071, `Terrain.scatter`) implement it.
+ */
+export interface Surface {
+    readonly entity: Entity;
+    readonly kind: 'planet' | 'mesh' | 'heightfield';
+    /** Bumps when anything placements depend on changes (rules, seed, heights). */
+    readonly version: number;
+    readonly rules: readonly CompiledRule[];
+    /** Lattice cells per chunk side, per rule. */
+    readonly cells: readonly number[];
+    /** Each rule's noise mask graph, loaded (undefined: no mask). */
+    readonly masks: readonly (NoiseGraph | undefined)[];
+    /** Takes new rules (and their loaded masks); bumps `version`. */
+    configure(rules: CompiledRule[], masks: (NoiseGraph | undefined)[], version: number): void;
+    /** Whether the surface can place (its graphs and sets are loaded). */
+    readonly ready: boolean;
+    /** Viewer positions in the surface's frame: cameras, then (for props) anchors. Returns the count of each. */
+    viewers(world: World, out: {
+        points: Float64Array;
+        cameras: number;
+        anchors: number;
+    }): void;
+    /** Visits every chunk of `rule` whose center is within `range` (+ its extent) of a viewer. */
+    chunksNear(rule: CompiledRule, viewers: Float64Array, first: number, count: number, range: number, visit: (chunk: SurfaceChunk, distance: number) => void): void;
+    /** The chunk of `rule` containing a surface-frame point (avoid lookups, scatter.sample). */
+    chunkAt(rule: CompiledRule, x: number, y: number, z: number): SurfaceChunk;
+    /** Starts placing a chunk: candidates now, samples on the pool when `workers` has threads. */
+    startPlacement(chunk: SurfaceChunk, due: number, workers: Workers | undefined): PlacementJob;
+    /**
+     * Finishes a job (sampling inline if the pool hasn't answered) into placements, without
+     * `avoid` (the runtime applies that once the avoided chunks are placed).
+     */
+    finishPlacement(job: PlacementJob): ChunkPlacements;
+    /** Parents a chunk's root entity: a child of the surface at the chunk's center. */
+    placeChunkRoot(world: World, root: Entity, chunk: SurfaceChunk): void;
+    /** The surface's up (unit) at a surface-frame point: radial on a planet, +Y on a mesh. */
+    upAt(x: number, y: number, z: number, out: Float64Array): Float64Array;
+    /**
+     * Starts building a foliage chunk's ground patch: its grid of positions, normals and the rule's
+     * density per vertex (masks, biome), on the pool where there is one.
+     */
+    startPatch(chunk: SurfaceChunk, workers: Workers | undefined): PatchJob;
+    /** The patch (built inline if the pool hasn't answered). */
+    finishPatch(job: PatchJob): FoliagePatch;
+    /**
+     * The chunk's frame (surface axes, metres, origin at its center) in origin-relative world space:
+     * an affine's three rows (12 floats) into `out`. Changes with the floating origin.
+     */
+    chunkTransform(world: World, chunk: SurfaceChunk, out: Float32Array): void;
+}
+/** A foliage chunk's ground: what the GPU places instances on (render's FoliageChunk). */
+export interface FoliagePatch {
+    grid: number;
+    positions: Float32Array;
+    normals: Float32Array;
+    density: Float32Array;
+    cell0: [number, number];
+    domain: number;
+    accept: number;
+    jitter: number;
+    radial: [number, number, number] | undefined;
+}
+/** A patch being built. */
+export interface PatchJob {
+    chunk: SurfaceChunk;
+    ready: boolean;
+    cancelled: boolean;
+    state: unknown;
+}

package/dist/surface.js

@@ -0,0 +1,20 @@
+const PLACEMENT_STRIDE = 13;
+const P_ITEM = 0;
+const P_VARIANT = 1;
+const P_X = 2;
+const P_QX = 5;
+const P_SCALE = 9;
+const P_CELL = 10;
+const P_RADIUS = 11;
+const P_SHADE = 12;
+export {
+  PLACEMENT_STRIDE,
+  P_CELL,
+  P_ITEM,
+  P_QX,
+  P_RADIUS,
+  P_SCALE,
+  P_SHADE,
+  P_VARIANT,
+  P_X
+};

package/dist/testing.d.ts

@@ -0,0 +1,236 @@
+import type { AssetRef, World } from '@aethervtt/shard-core';
+import type { GpuContext } from '@aethervtt/shard-gpu';
+import type { Platform } from '@aethervtt/shard-platform';
+import type { Plugin } from '@aethervtt/shard-runtime';
+import { type PlanetApp } from '@aethervtt/shard-terrain/testing';
+/** Radius of the test planet (m): small, so tests are quick, with relief and three biomes. */
+export declare const TEST_RADIUS = 20000;
+export declare const TEST_HEIGHT: {
+    output: string;
+    nodes: {
+        hills: {
+            fbm: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+        ridges: {
+            ridged: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+        h: {
+            add: (string | {
+                multiply: (string | number)[];
+            })[];
+        };
+    };
+};
+export declare const TEST_CLIMATE: {
+    output: string;
+    nodes: {
+        temperature: {
+            add: (number | {
+                fbm: {
+                    octaves: number;
+                    frequency: number;
+                    seed: number;
+                };
+            })[];
+        };
+        moisture: {
+            fbm: {
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+    };
+};
+/** Grassland: grass, bushes, the odd boulder. */
+export declare const GRASSLAND_SET: {
+    rules: ({
+        name: string;
+        items: {
+            generator: string;
+            params: {
+                radius: number;
+                detail: number;
+            };
+            variants: number;
+        }[];
+        density: number;
+        spacing: number;
+        align: number;
+        scale: number[];
+        sink: number;
+        collider: string;
+        range: number;
+        kind?: undefined;
+        masks?: undefined;
+        avoid?: undefined;
+    } | {
+        sink?: undefined;
+        collider?: undefined;
+        name: string;
+        items: {
+            generator: string;
+            variants: number;
+        }[];
+        density: number;
+        spacing: number;
+        masks: {
+            slope: number[];
+        };
+        scale: number[];
+        avoid: string[];
+        range: number;
+        kind?: undefined;
+        align?: undefined;
+    } | {
+        sink?: undefined;
+        collider?: undefined;
+        spacing?: undefined;
+        name: string;
+        kind: string;
+        items: {
+            generator: string;
+            variants: number;
+        }[];
+        density: number;
+        masks: {
+            slope: number[];
+        };
+        align: number;
+        scale: number[];
+        avoid: string[];
+        range: number;
+    })[];
+};
+/** Forest: trees, undergrowth, sparse grass. */
+export declare const FOREST_SET: {
+    rules: ({
+        kind?: undefined;
+        avoid?: undefined;
+        name: string;
+        items: {
+            generator: string;
+            variants: number;
+        }[];
+        density: number;
+        spacing: number;
+        masks: {
+            slope: number[];
+        };
+        scale: number[];
+        sink: number;
+        collider: string;
+        range: number;
+    } | {
+        sink?: undefined;
+        collider?: undefined;
+        kind?: undefined;
+        masks?: undefined;
+        scale?: undefined;
+        name: string;
+        items: {
+            generator: string;
+            params: {
+                radius: number;
+            };
+            variants: number;
+        }[];
+        density: number;
+        spacing: number;
+        avoid: string[];
+        range: number;
+    } | {
+        sink?: undefined;
+        collider?: undefined;
+        spacing?: undefined;
+        masks?: undefined;
+        scale?: undefined;
+        name: string;
+        kind: string;
+        items: {
+            generator: string;
+            params: {
+                height: number;
+            };
+            variants: number;
+        }[];
+        density: number;
+        avoid: string[];
+        range: number;
+    })[];
+};
+/** Rock: boulders and crystals on the slopes. */
+export declare const ROCK_SET: {
+    rules: ({
+        avoid?: undefined;
+        name: string;
+        items: {
+            generator: string;
+            params: {
+                radius: number;
+                roughness: number;
+            };
+            variants: number;
+        }[];
+        density: number;
+        spacing: number;
+        align: number;
+        scale: number[];
+        sink: number;
+        collider: string;
+        range: number;
+    } | {
+        sink?: undefined;
+        collider?: undefined;
+        scale?: undefined;
+        name: string;
+        items: {
+            generator: string;
+            variants: number;
+        }[];
+        density: number;
+        spacing: number;
+        align: number;
+        avoid: string[];
+        range: number;
+    })[];
+};
+export interface ScatterPlanet extends PlanetApp {
+    sets: AssetRef[];
+}
+/**
+ * The three-biome test planet with scatter (and procgen, which makes the items' meshes). With a
+ * GPU it renders (and draws foliage); without one, props alone are placed and spawned.
+ */
+export declare function scatterPlanet(gpu: GpuContext | undefined, platform: Platform, options?: {
+    width?: number;
+    height?: number;
+    extra?: Plugin[];
+    workers?: boolean;
+    /** MSAA samples (the playground's #scatter page draws with 4). Default 1. */
+    msaa?: 1 | 4;
+    /** A fixed render scale, upscaled after (the page's window view). */
+    renderScale?: number;
+    /** A set for the whole planet (Planet.scatter), on top of the biomes'. */
+    planetSet?: unknown;
+}): Promise<ScatterPlanet>;
+/** Steps until every surface's scatter is ready and nothing is placing (or the frames run out). */
+export declare function settleScatter(p: PlanetApp, maxFrames?: number): Promise<number>;
+/**
+ * FNV-1a over every spawned prop: its rule, chunk, index and local transform (f32 bits), sorted.
+ * The same planet and viewers give the same number on every host.
+ */
+export declare function placementChecksum(world: World): {
+    checksum: string;
+    props: number;
+};