@woosh/meep-engine 3.64.1 → 3.67.0

package/src/engine/graphics/ecs/grass/GrassSpecies.d.ts

@@ -0,0 +1,143 @@
+/**
+ * What grows on ground: one kind of grass, as content. Shared by every {@link GroundCover} that names it.
+ *
+ * Everything here is physical, in SI units, and describes the plant, not how well it is drawn: drawing
+ * fewer, wider blades of the same species at a distance is the renderer's business.
+ *
+ * After changing a field in place, dispatch {@link onChanged}.
+ */
+export class GrassSpecies {
+    /**
+     * @param {object} [options]
+     * @param {number} [options.blade_length]
+     * @param {number} [options.blade_width]
+     * @param {number} [options.density]
+     * @returns {GrassSpecies}
+     */
+    static from({ blade_length, blade_width, density }?: {
+        blade_length?: number;
+        blade_width?: number;
+        density?: number;
+    }): GrassSpecies;
+    /**
+     * Length of a blade from root to tip, metres.
+     * @type {number}
+     */
+    blade_length: number;
+    /**
+     * Width of a blade at its root, metres.
+     * @type {number}
+     */
+    blade_width: number;
+    /**
+     * Blades in a square metre of fully covered ground.
+     * @type {number}
+     */
+    density: number;
+    /**
+     * A blade's colour at its root and at its tip, linear RGB.
+     * @type {number[]}
+     */
+    color_root: number[];
+    /** @type {number[]} */
+    color_tip: number[];
+    /**
+     * How far a blade's colour strays from its species', as a share of it: a blade's own, the same every frame.
+     * @type {number}
+     */
+    tint: number;
+    /**
+     * Roughness of a blade's surface.
+     * @type {number}
+     */
+    roughness: number;
+    /**
+     * How much of {@link blade_length} a blade can lack, 0 to 1: blades are that share shorter at most.
+     * @type {number}
+     */
+    length_variation: number;
+    /**
+     * The most a blade leans from upright at its root, in still air, radians.
+     * @type {number}
+     */
+    lean: number;
+    /**
+     * The most a blade's tip turns further than its root leans, in still air, radians.
+     * @type {number}
+     */
+    curl: number;
+    /**
+     * How far a blade's normal turns towards its edges, 0 for a flat blade: the tangent of the angle at an edge.
+     * @type {number}
+     */
+    roundness: number;
+    /**
+     * Young's modulus of the blade in bending, Pa.
+     * @type {number}
+     */
+    elastic_modulus: number;
+    /**
+     * Depth of the blade's section in bending, metres: the thickness of a flat strip as stiff as the
+     * blade. A folded or keeled blade, or one that stands in its sheath, is deeper than its leaf is thick.
+     * @type {number}
+     */
+    blade_depth: number;
+    /**
+     * How unsteady the wind a blade feels is, beyond what the scene's wind resolves: the size of its
+     * swings as a share of its speed. A blade sways with it at its own frequency. 0 for none.
+     * @type {number}
+     */
+    turbulence: number;
+    /**
+     * How long a blade that was pressed down takes to stand back up, seconds: what is left of its lean
+     * falls by a factor of `e` in this time. Must be positive.
+     * @type {number}
+     */
+    recovery_time: number;
+    /**
+     * Dispatched by whoever edits the species in place.
+     * @type {Signal}
+     */
+    onChanged: Signal;
+    toJSON(): {
+        blade_length: number;
+        blade_width: number;
+        density: number;
+        color_root: number[];
+        color_tip: number[];
+        tint: number;
+        roughness: number;
+        length_variation: number;
+        lean: number;
+        curl: number;
+        roundness: number;
+        elastic_modulus: number;
+        blade_depth: number;
+        turbulence: number;
+        recovery_time: number;
+    };
+    fromJSON({ blade_length, blade_width, density, color_root, color_tip, tint, roughness, length_variation, lean, curl, roundness, elastic_modulus, blade_depth, turbulence, recovery_time, }: {
+        blade_length?: number;
+        blade_width?: number;
+        density?: number;
+        color_root?: number[];
+        color_tip?: number[];
+        tint?: number;
+        roughness?: number;
+        length_variation?: number;
+        lean?: number;
+        curl?: number;
+        roundness?: number;
+        elastic_modulus?: number;
+        blade_depth?: number;
+        turbulence?: number;
+        recovery_time?: number;
+    }): void;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isGrassSpecies: boolean;
+}
+import Signal from "../../../../core/events/signal/Signal.js";
+//# sourceMappingURL=GrassSpecies.d.ts.map

package/src/engine/graphics/ecs/grass/GrassSpecies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrassSpecies.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/grass/GrassSpecies.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH;IAiGI;;;;;;OAMG;IACH;QAL4B,YAAY,GAA7B,MAAM;QACW,WAAW,GAA5B,MAAM;QACW,OAAO,GAAxB,MAAM;QACJ,YAAY,CAcxB;IAnHD;;;OAGG;IACH,cAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,aAFU,MAAM,CAEI;IAEpB;;;OAGG;IACH,SAFU,MAAM,CAEF;IAEd;;;OAGG;IACH,YAFU,MAAM,EAAE,CAEc;IAEhC,uBAAuB;IACvB,WADW,MAAM,EAAE,CACY;IAE/B;;;OAGG;IACH,MAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,kBAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,MAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,MAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,iBAFU,MAAM,CAEM;IAEtB;;;;OAIG;IACH,aAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,YAFU,MAAM,CAEE;IAElB;;;;OAIG;IACH,eAFU,MAAM,CAEE;IAElB;;;OAGG;IACH,WAFU,MAAM,CAES;IAuBzB;;;;;;;;;;;;;;;;MAkBC;IAED;;;;;;;;;;;;;;;;aAgCC;IAGL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;CANpC;mBArLkB,0CAA0C"}

package/src/engine/graphics/ecs/grass/GrassSpecies.js

@@ -0,0 +1,189 @@
+import { assert } from "../../../../core/assert.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+
+/**
+ * What grows on ground: one kind of grass, as content. Shared by every {@link GroundCover} that names it.
+ *
+ * Everything here is physical, in SI units, and describes the plant, not how well it is drawn: drawing
+ * fewer, wider blades of the same species at a distance is the renderer's business.
+ *
+ * After changing a field in place, dispatch {@link onChanged}.
+ */
+export class GrassSpecies {
+    /**
+     * Length of a blade from root to tip, metres.
+     * @type {number}
+     */
+    blade_length = 0.4;
+
+    /**
+     * Width of a blade at its root, metres.
+     * @type {number}
+     */
+    blade_width = 0.015;
+
+    /**
+     * Blades in a square metre of fully covered ground.
+     * @type {number}
+     */
+    density = 300;
+
+    /**
+     * A blade's colour at its root and at its tip, linear RGB.
+     * @type {number[]}
+     */
+    color_root = [0.04, 0.10, 0.02];
+
+    /** @type {number[]} */
+    color_tip = [0.20, 0.36, 0.08];
+
+    /**
+     * How far a blade's colour strays from its species', as a share of it: a blade's own, the same every frame.
+     * @type {number}
+     */
+    tint = 0.15;
+
+    /**
+     * Roughness of a blade's surface.
+     * @type {number}
+     */
+    roughness = 0.6;
+
+    /**
+     * How much of {@link blade_length} a blade can lack, 0 to 1: blades are that share shorter at most.
+     * @type {number}
+     */
+    length_variation = 0.35;
+
+    /**
+     * The most a blade leans from upright at its root, in still air, radians.
+     * @type {number}
+     */
+    lean = 0.35;
+
+    /**
+     * The most a blade's tip turns further than its root leans, in still air, radians.
+     * @type {number}
+     */
+    curl = 0.9;
+
+    /**
+     * How far a blade's normal turns towards its edges, 0 for a flat blade: the tangent of the angle at an edge.
+     * @type {number}
+     */
+    roundness = 0.5;
+
+    /**
+     * Young's modulus of the blade in bending, Pa.
+     * @type {number}
+     */
+    elastic_modulus = 5e8;
+
+    /**
+     * Depth of the blade's section in bending, metres: the thickness of a flat strip as stiff as the
+     * blade. A folded or keeled blade, or one that stands in its sheath, is deeper than its leaf is thick.
+     * @type {number}
+     */
+    blade_depth = 1e-3;
+
+    /**
+     * How unsteady the wind a blade feels is, beyond what the scene's wind resolves: the size of its
+     * swings as a share of its speed. A blade sways with it at its own frequency. 0 for none.
+     * @type {number}
+     */
+    turbulence = 0.28;
+
+    /**
+     * How long a blade that was pressed down takes to stand back up, seconds: what is left of its lean
+     * falls by a factor of `e` in this time. Must be positive.
+     * @type {number}
+     */
+    recovery_time = 2;
+
+    /**
+     * Dispatched by whoever edits the species in place.
+     * @type {Signal}
+     */
+    onChanged = new Signal();
+
+    /**
+     * @param {object} [options]
+     * @param {number} [options.blade_length]
+     * @param {number} [options.blade_width]
+     * @param {number} [options.density]
+     * @returns {GrassSpecies}
+     */
+    static from({ blade_length = 0.4, blade_width = 0.015, density = 300 } = {}) {
+        assert.greaterThan(blade_length, 0, 'blade_length');
+        assert.greaterThan(blade_width, 0, 'blade_width');
+        assert.greaterThan(density, 0, 'density');
+
+        const r = new GrassSpecies();
+
+        r.blade_length = blade_length;
+        r.blade_width = blade_width;
+        r.density = density;
+
+        return r;
+    }
+
+    toJSON() {
+        return {
+            blade_length: this.blade_length,
+            blade_width: this.blade_width,
+            density: this.density,
+            color_root: this.color_root.slice(),
+            color_tip: this.color_tip.slice(),
+            tint: this.tint,
+            roughness: this.roughness,
+            length_variation: this.length_variation,
+            lean: this.lean,
+            curl: this.curl,
+            roundness: this.roundness,
+            elastic_modulus: this.elastic_modulus,
+            blade_depth: this.blade_depth,
+            turbulence: this.turbulence,
+            recovery_time: this.recovery_time,
+        };
+    }
+
+    fromJSON({
+                 blade_length = 0.4,
+                 blade_width = 0.015,
+                 density = 300,
+                 color_root = [0.04, 0.10, 0.02],
+                 color_tip = [0.20, 0.36, 0.08],
+                 tint = 0.15,
+                 roughness = 0.6,
+                 length_variation = 0.35,
+                 lean = 0.35,
+                 curl = 0.9,
+                 roundness = 0.5,
+                 elastic_modulus = 5e8,
+                 blade_depth = 1e-3,
+                 turbulence = 0.28,
+                 recovery_time = 2,
+             }) {
+        this.blade_length = blade_length;
+        this.blade_width = blade_width;
+        this.density = density;
+        this.color_root = color_root.slice();
+        this.color_tip = color_tip.slice();
+        this.tint = tint;
+        this.roughness = roughness;
+        this.length_variation = length_variation;
+        this.lean = lean;
+        this.curl = curl;
+        this.roundness = roundness;
+        this.elastic_modulus = elastic_modulus;
+        this.blade_depth = blade_depth;
+        this.turbulence = turbulence;
+        this.recovery_time = recovery_time;
+    }
+}
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+GrassSpecies.prototype.isGrassSpecies = true;

package/src/engine/graphics/ecs/grass/GrassSurface.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Makes its entity a grass surface: a group of mesh instances whose ground is sampled as one.
+ *
+ * The surface's frame is where the entity's `Transform64` is and how it is turned; the transform's scale
+ * is no part of it. The ground is sampled on a lattice in that frame, along the frame's up axis, so a
+ * surface that moves as one carries its grass with it.
+ *
+ * The members are the mesh entities whose {@link GroundCover} names this entity. A mesh entity that
+ * carries both components and names itself is a surface of one instance.
+ *
+ * The component holds nothing: which meshes belong is said by each of them.
+ */
+export class GrassSurface {
+    toJSON(): {};
+    fromJSON(json: any): void;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isGrassSurface: boolean;
+}
+export namespace GrassSurface {
+    let typeName: string;
+}
+//# sourceMappingURL=GrassSurface.d.ts.map

package/src/engine/graphics/ecs/grass/GrassSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GrassSurface.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/grass/GrassSurface.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH;IACI,aAEC;IAED,0BACC;IASL;;;OAGG;IACH,yBAFU,OAAO,CAEoB;CAZpC;;kBAIS,MAAM"}

package/src/engine/graphics/ecs/grass/GrassSurface.js

@@ -0,0 +1,32 @@
+/**
+ * Makes its entity a grass surface: a group of mesh instances whose ground is sampled as one.
+ *
+ * The surface's frame is where the entity's `Transform64` is and how it is turned; the transform's scale
+ * is no part of it. The ground is sampled on a lattice in that frame, along the frame's up axis, so a
+ * surface that moves as one carries its grass with it.
+ *
+ * The members are the mesh entities whose {@link GroundCover} names this entity. A mesh entity that
+ * carries both components and names itself is a surface of one instance.
+ *
+ * The component holds nothing: which meshes belong is said by each of them.
+ */
+export class GrassSurface {
+    toJSON() {
+        return {};
+    }
+
+    fromJSON(json) {
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+GrassSurface.typeName = "GrassSurface";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+GrassSurface.prototype.isGrassSurface = true;

package/src/engine/graphics/ecs/grass/GroundCover.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Makes its mesh entity ground of a grass surface, and says what grows on it.
+ *
+ * The entity carries a `ShadedGeometry` and a `Transform64`. Its faces become ground of the surface
+ * {@link surface} names: columns of that surface's lattice find them, and they hide the ground of other
+ * members under them.
+ *
+ * **Membership is its own relation.** It says which surface a mesh is sampled with, and nothing about
+ * where the mesh is (`TransformAttachment`) or how long it lives (`ParentEntity`); the three are free to
+ * name different entities, and a meadow of loose meshes needs no transform parent to be one surface.
+ *
+ * **A member with no species only hides ground**: a boulder, a path, the floor of a building. Nothing
+ * grows on it, and nothing grows through it.
+ *
+ * How densely the species grows across the mesh is painted in the red of the geometry's vertex colour, 1
+ * where there is none; {@link density} scales that.
+ *
+ * After changing {@link species} or {@link density} in place, dispatch {@link onChanged}.
+ */
+export class GroundCover {
+    /**
+     * @param {object} options
+     * @param {number} options.surface the surface's entity
+     * @param {GrassSpecies|null} [options.species]
+     * @param {number} [options.density]
+     * @returns {GroundCover}
+     */
+    static from({ surface, species, density }: {
+        surface: number;
+        species?: GrassSpecies | null;
+        density?: number;
+    }): GroundCover;
+    /**
+     * The entity whose {@link GrassSurface} this mesh is ground of.
+     * Must not be mutated (changed) while the component is attached to a dataset: remove the component and
+     * add it back to move a mesh to another surface.
+     *
+     * @type {number}
+     */
+    surface: number;
+    /**
+     * What grows on the mesh, or null for a member that only hides ground.
+     *
+     * @type {GrassSpecies|null}
+     */
+    species: GrassSpecies | null;
+    /**
+     * Scale on the mesh's painted density, 0 to 1.
+     *
+     * @type {number}
+     */
+    density: number;
+    /**
+     * Dispatched by whoever edits the component in place.
+     * @type {Signal}
+     */
+    onChanged: Signal;
+    /**
+     * @readonly
+     * @type {boolean}
+     */
+    readonly isGroundCover: boolean;
+}
+export namespace GroundCover {
+    let typeName: string;
+}
+import Signal from "../../../../core/events/signal/Signal.js";
+//# sourceMappingURL=GroundCover.d.ts.map

package/src/engine/graphics/ecs/grass/GroundCover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroundCover.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/graphics/ecs/grass/GroundCover.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IA8BI;;;;;;OAMG;IACH;QAL2B,OAAO,EAAvB,MAAM;QACsB,OAAO,GAAnC,eAAa,IAAI;QACA,OAAO,GAAxB,MAAM;QACJ,WAAW,CAcvB;IAhDD;;;;;;OAMG;IACH,SAFU,MAAM,CAEH;IAEb;;;;OAIG;IACH,SAFU,eAAa,IAAI,CAEZ;IAEf;;;;OAIG;IACH,SAFU,MAAM,CAEJ;IAEZ;;;OAGG;IACH,WAFU,MAAM,CAES;IA8B7B;;;OAGG;IACH,wBAFU,OAAO,CAEkB;CAZlC;;kBAIS,MAAM;;mBA3EG,0CAA0C"}

package/src/engine/graphics/ecs/grass/GroundCover.js

@@ -0,0 +1,85 @@
+import { assert } from "../../../../core/assert.js";
+import Signal from "../../../../core/events/signal/Signal.js";
+
+/**
+ * Makes its mesh entity ground of a grass surface, and says what grows on it.
+ *
+ * The entity carries a `ShadedGeometry` and a `Transform64`. Its faces become ground of the surface
+ * {@link surface} names: columns of that surface's lattice find them, and they hide the ground of other
+ * members under them.
+ *
+ * **Membership is its own relation.** It says which surface a mesh is sampled with, and nothing about
+ * where the mesh is (`TransformAttachment`) or how long it lives (`ParentEntity`); the three are free to
+ * name different entities, and a meadow of loose meshes needs no transform parent to be one surface.
+ *
+ * **A member with no species only hides ground**: a boulder, a path, the floor of a building. Nothing
+ * grows on it, and nothing grows through it.
+ *
+ * How densely the species grows across the mesh is painted in the red of the geometry's vertex colour, 1
+ * where there is none; {@link density} scales that.
+ *
+ * After changing {@link species} or {@link density} in place, dispatch {@link onChanged}.
+ */
+export class GroundCover {
+    /**
+     * The entity whose {@link GrassSurface} this mesh is ground of.
+     * Must not be mutated (changed) while the component is attached to a dataset: remove the component and
+     * add it back to move a mesh to another surface.
+     *
+     * @type {number}
+     */
+    surface = -1;
+
+    /**
+     * What grows on the mesh, or null for a member that only hides ground.
+     *
+     * @type {GrassSpecies|null}
+     */
+    species = null;
+
+    /**
+     * Scale on the mesh's painted density, 0 to 1.
+     *
+     * @type {number}
+     */
+    density = 1;
+
+    /**
+     * Dispatched by whoever edits the component in place.
+     * @type {Signal}
+     */
+    onChanged = new Signal();
+
+    /**
+     * @param {object} options
+     * @param {number} options.surface the surface's entity
+     * @param {GrassSpecies|null} [options.species]
+     * @param {number} [options.density]
+     * @returns {GroundCover}
+     */
+    static from({ surface, species = null, density = 1 }) {
+        assert.isNonNegativeInteger(surface, 'surface');
+        assert.greaterThanOrEqual(density, 0, 'density');
+        assert.lessThanOrEqual(density, 1, 'density');
+
+        const r = new GroundCover();
+
+        r.surface = surface;
+        r.species = species;
+        r.density = density;
+
+        return r;
+    }
+}
+
+/**
+ * @readonly
+ * @type {string}
+ */
+GroundCover.typeName = "GroundCover";
+
+/**
+ * @readonly
+ * @type {boolean}
+ */
+GroundCover.prototype.isGroundCover = true;