@woosh/meep-engine 3.18.0 → 3.19.0

package/src/shade/playground/particle_ecs/bonfire_world.d.ts

@@ -0,0 +1,86 @@
+/**
+ * @typedef {object} BonfireWorld
+ * @property {number} flame entity
+ * @property {number} smoke entity
+ * @property {number} embers entity
+ * @property {number} soot entity
+ * @property {import("../../../engine/graphics/ecs/particles/ParticleEffect.js").ParticleEffect[]} effects
+ *   the four components, in flame / smoke / embers / soot order
+ * @property {Light} firelight the point light at the fire, for {@link animate_bonfire} to flicker
+ * @property {number[]} entities everything built, for teardown
+ */
+/**
+ * Build the whole set.
+ *
+ * Async because the meshlet builder runs on a WASM instance that instantiates asynchronously at
+ * import; building geometry before it is ready reads an instance that is not there yet.
+ *
+ * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+ * @param {object} [options]
+ * @param {import("./bonfire_sprites.js").BonfireSprites} [options.sprites] image URLs for the four
+ *        effects; omitted, they draw as untextured quads, which is what the headless tests use
+ * @returns {Promise<BonfireWorld>}
+ */
+export function build_bonfire_world(dataset: import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset, { sprites }?: {
+    sprites?: import("./bonfire_sprites.js").BonfireSprites;
+}): Promise<BonfireWorld>;
+/**
+ * Flicker the firelight.
+ *
+ * Three sine waves with no common period, so it never repeats audibly — the classic cheap fire
+ * flicker, and it is here rather than in the effects because it is the *light* that flickers: the
+ * particles already flicker on their own, and a light that held still while they did would read as
+ * a lamp with a fire drawn in front of it.
+ *
+ * @param {BonfireWorld} world
+ * @param {number} time seconds since start
+ */
+export function animate_bonfire(world: BonfireWorld, time: number): void;
+/**
+ * The scene the page shows, built as entities.
+ *
+ * **Every visible thing here is a `Transform64` and one more component**, which is the whole point
+ * of the page: the ground and the logs are `ShadedGeometry`, the moon and the firelight are `Light`,
+ * and the flame, smoke, embers and soot are `ParticleEffect`. Four systems observe those pairs and
+ * put rows in one `Scene`. Nothing in this file touches the scene graph, and nothing about placing
+ * a fire is different from placing a rock.
+ *
+ * That is what the rework bought. Before it, the particle system observed the scene's emitter nodes
+ * directly, so an effect was the one thing in a level that could not be spawned, moved, parented or
+ * destroyed by the machinery everything else uses.
+ */
+/** Where the fire is. Everything else in the set is arranged around it. */
+export const FIRE_POSITION: Vector3;
+export type BonfireWorld = {
+    /**
+     * entity
+     */
+    flame: number;
+    /**
+     * entity
+     */
+    smoke: number;
+    /**
+     * entity
+     */
+    embers: number;
+    /**
+     * entity
+     */
+    soot: number;
+    /**
+     *   the four components, in flame / smoke / embers / soot order
+     */
+    effects: import("../../../engine/graphics/ecs/particles/ParticleEffect.js").ParticleEffect[];
+    /**
+     * the point light at the fire, for {@link animate_bonfire } to flicker
+     */
+    firelight: Light;
+    /**
+     * everything built, for teardown
+     */
+    entities: number[];
+};
+import Vector3 from "../../../core/geom/Vector3.js";
+import { Light } from "../../../engine/graphics/ecs/light/Light.js";
+//# sourceMappingURL=bonfire_world.d.ts.map

package/src/shade/playground/particle_ecs/bonfire_world.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bonfire_world.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_ecs/bonfire_world.js"],"names":[],"mappings":"AA8CA;;;;;;;;;;GAUG;AAEH;;;;;;;;;;;GAWG;AACH,6CANW,OAAO,+CAA+C,EAAE,sBAAsB;IAEtB,OAAO,GAA/D,OAAO,sBAAsB,EAAE,cAAc;IAE3C,QAAQ,YAAY,CAAC,CAuIjC;AAED;;;;;;;;;;GAUG;AACH,uCAHW,YAAY,QACZ,MAAM,QAShB;AA3MD;;;;;;;;;;;;GAYG;AAEH,2EAA2E;AAC3E,oCAAkD;;;;;WAapC,MAAM;;;;WACN,MAAM;;;;YACN,MAAM;;;;UACN,MAAM;;;;aACN,OAAO,0DAA0D,EAAE,cAAc,EAAE;;;;eAEnF,KAAK;;;;cACL,MAAM,EAAE;;oBArDF,+BAA+B;sBAG7B,6CAA6C"}

package/src/shade/playground/particle_ecs/bonfire_world.js

@@ -0,0 +1,303 @@
+import { Color } from "../../../core/color/Color.js";
+import Quaternion from "../../../core/geom/Quaternion.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { Entity } from "../../../engine/ecs/Entity.js";
+import { Transform64 } from "../../../engine/ecs/transform/Transform64.js";
+import { Light } from "../../../engine/graphics/ecs/light/Light.js";
+import { LightType } from "../../../engine/graphics/ecs/light/LightType.js";
+import { ShadedGeometry } from "../../../engine/graphics/ecs/mesh-v2/ShadedGeometry.js";
+import { MeshletGeometry } from "../../renderer/geometry/MeshletGeometry.js";
+import { MeshoptClusterizer } from "../../renderer/geometry/meshlet/build/meshoptimizer/meshopt_clusterizer.js";
+import { meshlet_geometry_build_from_geometry } from "../../renderer/geometry/meshlet_geometry_build_from_geometry.js";
+import { make_box_geometry } from "../../renderer/geometry/primitives/make_box_geometry.js";
+import { make_cylinder_geometry } from "../../renderer/geometry/primitives/make_cylinder_geometry.js";
+import { make_plane_geometry } from "../../renderer/geometry/primitives/make_plane_geometry.js";
+import { ShadeDrawSide } from "../../renderer/material/ShadeDrawSide.js";
+import { StandardShadeMaterial } from "../../renderer/material/StandardShadeMaterial.js";
+import { TransparencyMode } from "../../renderer/material/TransparencyMode.js";
+import { bonfire_effects } from "./bonfire_effects.js";
+import { MOON_DIRECTION } from "./moonlit_environment.js";
+
+/**
+ * The scene the page shows, built as entities.
+ *
+ * **Every visible thing here is a `Transform64` and one more component**, which is the whole point
+ * of the page: the ground and the logs are `ShadedGeometry`, the moon and the firelight are `Light`,
+ * and the flame, smoke, embers and soot are `ParticleEffect`. Four systems observe those pairs and
+ * put rows in one `Scene`. Nothing in this file touches the scene graph, and nothing about placing
+ * a fire is different from placing a rock.
+ *
+ * That is what the rework bought. Before it, the particle system observed the scene's emitter nodes
+ * directly, so an effect was the one thing in a level that could not be spawned, moved, parented or
+ * destroyed by the machinery everything else uses.
+ */
+
+/** Where the fire is. Everything else in the set is arranged around it. */
+export const FIRE_POSITION = new Vector3(0, 0, 0);
+
+/** Radius of the ring of stones, in metres. */
+const PIT_RADIUS = 0.85;
+
+/**
+ * Baseline intensity of the firelight, before the flicker.
+ * @type {number}
+ */
+const FIRELIGHT_INTENSITY = 3.5;
+
+/**
+ * @typedef {object} BonfireWorld
+ * @property {number} flame entity
+ * @property {number} smoke entity
+ * @property {number} embers entity
+ * @property {number} soot entity
+ * @property {import("../../../engine/graphics/ecs/particles/ParticleEffect.js").ParticleEffect[]} effects
+ *   the four components, in flame / smoke / embers / soot order
+ * @property {Light} firelight the point light at the fire, for {@link animate_bonfire} to flicker
+ * @property {number[]} entities everything built, for teardown
+ */
+
+/**
+ * Build the whole set.
+ *
+ * Async because the meshlet builder runs on a WASM instance that instantiates asynchronously at
+ * import; building geometry before it is ready reads an instance that is not there yet.
+ *
+ * @param {import("../../../engine/ecs/EntityComponentDataset.js").EntityComponentDataset} dataset
+ * @param {object} [options]
+ * @param {import("./bonfire_sprites.js").BonfireSprites} [options.sprites] image URLs for the four
+ *        effects; omitted, they draw as untextured quads, which is what the headless tests use
+ * @returns {Promise<BonfireWorld>}
+ */
+export async function build_bonfire_world(dataset, { sprites = {} } = {}) {
+    await MeshoptClusterizer.ready;
+
+    /** @type {number[]} */
+    const entities = [];
+
+    /**
+     * @param {Entity} builder
+     * @returns {number}
+     */
+    const build = builder => {
+        builder.build(dataset);
+        entities.push(builder.id);
+
+        return builder.id;
+    };
+
+    // --- the ground, the pit and the fuel ------------------------------------------------------
+
+    const ground_material = material(new Color(0.12, 0.113, 0.10, 1), { roughness: 0.95 });
+    const stone_material = material(new Color(0.14, 0.14, 0.15, 1), { roughness: 0.8 });
+    const log_material = material(new Color(0.17, 0.10, 0.065, 1), { roughness: 0.85 });
+
+    build(new Entity()
+        .add(placed(new Vector3(0, 0, 0), Quaternion.fromAxisAngle(Vector3.right, -Math.PI / 2)))
+        .add(shaded(meshlets(make_plane_geometry(200, 200, 1, 1)), ground_material)));
+
+    const stone = meshlets(make_box_geometry(0.34, 0.26, 0.28));
+
+    for (let i = 0; i < 11; i++) {
+        const angle = (i / 11) * Math.PI * 2;
+        const wobble = 0.9 + ((i * 37) % 7) / 24;
+
+        build(new Entity()
+            .add(placed(
+                new Vector3(
+                    FIRE_POSITION.x + Math.cos(angle) * PIT_RADIUS * wobble,
+                    0.1,
+                    FIRE_POSITION.z + Math.sin(angle) * PIT_RADIUS * wobble
+                ),
+                Quaternion.fromAxisAngle(Vector3.up, angle + wobble)
+            ))
+            .add(shaded(stone, stone_material)));
+    }
+
+    // Logs leaning into a teepee, which is where the flame's pinch comes from visually: the fire is
+    // widest at the fuel and narrows above it.
+    const log = meshlets(make_cylinder_geometry(0.075, 0.1, 1.5, 8, 1));
+
+    for (let i = 0; i < 5; i++) {
+        const angle = (i / 5) * Math.PI * 2 + 0.4;
+        const lean = 0.42;
+
+        build(new Entity()
+            .add(placed(
+                new Vector3(
+                    FIRE_POSITION.x + Math.cos(angle) * 0.34,
+                    0.62,
+                    FIRE_POSITION.z + Math.sin(angle) * 0.34
+                ),
+                // rotate +Y toward the outward lean: the axis is up x outward
+                Quaternion.fromAxisAngle(
+                    new Vector3(Math.sin(angle), 0, -Math.cos(angle)),
+                    lean
+                )
+            ))
+            .add(shaded(log, log_material)));
+    }
+
+    // two spent logs lying across the pit
+    for (const [offset, angle] of [[new Vector3(0.1, 0.09, -0.55), 0.7], [new Vector3(-0.35, 0.09, 0.4), 2.3]]) {
+        build(new Entity()
+            .add(placed(
+                new Vector3(FIRE_POSITION.x + offset.x, offset.y, FIRE_POSITION.z + offset.z),
+                Quaternion.fromAxisAngle(new Vector3(Math.sin(angle), 0, -Math.cos(angle)), Math.PI / 2)
+            ))
+            .add(shaded(log, log_material)));
+    }
+
+    // --- the lights ----------------------------------------------------------------------------
+
+    const moon = new Light();
+
+    moon.type.set(LightType.DIRECTION);
+    moon.color.setRGB(0.62, 0.72, 1.0);
+    moon.intensity.set(1.1);
+    // an angular radius, for a directional source: the moon's is about half a degree, and a source
+    // with some size is what softens the terminator and the shadow's edge
+    moon.radius.set(0.0087);
+    moon.castShadow.set(true);
+
+    build(new Entity()
+        .add(placed(new Vector3(0, 12, 0), look_along(MOON_DIRECTION.clone().negate())))
+        .add(moon));
+
+    // The fire's own light, and the thing that makes the set look lit by the fire rather than lit
+    // near it: a warm point source inside the flame, flickered by {@link animate_bonfire}.
+    const firelight = new Light();
+
+    firelight.type.set(LightType.POINT);
+    firelight.color.setRGB(1.0, 0.52, 0.19);
+    firelight.intensity.set(FIRELIGHT_INTENSITY);
+    firelight.distance.set(18);
+    // the flame is roughly a third of a metre across, and a source with size is what keeps the
+    // stones from each carrying one mirror-sharp highlight
+    firelight.radius.set(0.35);
+
+    build(new Entity()
+        .add(placed(new Vector3(FIRE_POSITION.x, 0.55, FIRE_POSITION.z)))
+        .add(firelight));
+
+    // --- the fire ------------------------------------------------------------------------------
+
+    const effects = bonfire_effects(sprites);
+
+    /**
+     * @param {import("../../../engine/graphics/ecs/particles/ParticleEffect.js").ParticleEffect} effect
+     * @param {number} height
+     * @returns {number}
+     */
+    const emitter = (effect, height) => build(new Entity()
+        .add(placed(new Vector3(FIRE_POSITION.x, FIRE_POSITION.y + height, FIRE_POSITION.z)))
+        .add(effect));
+
+    return {
+        flame: emitter(effects.flame, 0.16),
+        smoke: emitter(effects.smoke, 0.16),
+        embers: emitter(effects.embers, 0.16),
+        soot: emitter(effects.soot, 0.16),
+        effects: [effects.flame, effects.smoke, effects.embers, effects.soot],
+        firelight,
+        entities,
+    };
+}
+
+/**
+ * Flicker the firelight.
+ *
+ * Three sine waves with no common period, so it never repeats audibly — the classic cheap fire
+ * flicker, and it is here rather than in the effects because it is the *light* that flickers: the
+ * particles already flicker on their own, and a light that held still while they did would read as
+ * a lamp with a fire drawn in front of it.
+ *
+ * @param {BonfireWorld} world
+ * @param {number} time seconds since start
+ */
+export function animate_bonfire(world, time) {
+    const wobble =
+        Math.sin(time * 8.7) * 0.13
+        + Math.sin(time * 3.1 + 1.7) * 0.09
+        + Math.sin(time * 17.3 + 0.4) * 0.05;
+
+    world.firelight.intensity.set(FIRELIGHT_INTENSITY * (1 + wobble));
+}
+
+// -------------------------------------------------------------------------------------------
+// Helpers
+// -------------------------------------------------------------------------------------------
+
+/**
+ * @param {Vector3} position
+ * @param {Quaternion} [rotation]
+ * @returns {Transform64}
+ */
+function placed(position, rotation = new Quaternion()) {
+    const transform = new Transform64();
+
+    transform.setTranslation(position.x, position.y, position.z);
+    transform.setRotation(rotation.x, rotation.y, rotation.z, rotation.w);
+    transform.updateMatrix();
+
+    return transform;
+}
+
+/**
+ * A rotation that points local **forward** along `direction`, which is how a `DirectionalLight`
+ * takes its direction — it has no direction field, only a transform.
+ *
+ * @param {Vector3} direction unit
+ * @returns {Quaternion}
+ */
+function look_along(direction) {
+    const q = new Quaternion();
+
+    q.fromUnitVectors(Vector3.forward, direction);
+    q.normalize();
+
+    return q;
+}
+
+/**
+ * @param {MeshletGeometry} geometry
+ * @param {StandardShadeMaterial} material_instance
+ * @returns {ShadedGeometry}
+ */
+function shaded(geometry, material_instance) {
+    const component = new ShadedGeometry();
+
+    component.geometry = geometry;
+    component.material = material_instance;
+
+    return component;
+}
+
+/**
+ * @param {object} geometry
+ * @returns {MeshletGeometry}
+ */
+function meshlets(geometry) {
+    const built = new MeshletGeometry();
+
+    meshlet_geometry_build_from_geometry(geometry, built);
+
+    return built;
+}
+
+/**
+ * @param {Color} diffuse
+ * @param {object} [options]
+ * @param {number} [options.roughness]
+ * @returns {StandardShadeMaterial}
+ */
+function material(diffuse, { roughness = 0.8 } = {}) {
+    const result = new StandardShadeMaterial();
+
+    result.diffuse_color.copy(diffuse);
+    result.roughness_factor = roughness;
+    result.metallic_factor = 0;
+    result.transparency_mode = TransparencyMode.Opaque;
+    result.draw_side = ShadeDrawSide.Double;
+
+    return result;
+}