@woosh/meep-engine 3.18.0 → 3.20.0

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

@@ -0,0 +1,566 @@
+import ConcurrentExecutor from "../../../core/process/executor/ConcurrentExecutor.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+import { DEG_TO_RAD } from "../../../core/math/DEG_TO_RAD.js";
+import { AssetManager } from "../../../engine/asset/AssetManager.js";
+import { GameAssetType } from "../../../engine/asset/GameAssetType.js";
+import { ImageRGBADataLoader } from "../../../engine/asset/loaders/image/ImageRGBADataLoader.js";
+import { EntityComponentDataset } from "../../../engine/ecs/EntityComponentDataset.js";
+import { EntityManager } from "../../../engine/ecs/EntityManager.js";
+import { GPUParticleEmitterSystem } from "../../../engine/graphics3/GPUParticleEmitterSystem.js";
+import { GraphicsEngine } from "../../../engine/graphics3/GraphicsEngine.js";
+import { LightSystem } from "../../../engine/graphics3/LightSystem.js";
+import { ShadedGeometrySystem } from "../../../engine/graphics3/ShadedGeometrySystem.js";
+import { OrbitalCameraController } from "../../renderer/camera/OrbitalCameraController.js";
+import { create_frame_loop } from "../../renderer/create_frame_loop.js";
+import { install_profile_hotkey } from "../profile_hotkey.js";
+import { PARTICLE_COUNTER_COUNT } from "../../renderer/particles/data/PARTICLE_COUNTERS.js";
+import { Scene } from "../../renderer/scene/Scene.js";
+import { ShadeTransparencyMode } from "../../renderer/ShadeTransparencyMode.js";
+import { animate_bonfire, build_bonfire_world } from "./bonfire_world.js";
+import { BONFIRE_EFFECT_NAMES, bonfire_sprite_urls } from "./bonfire_effects.js";
+import { install_effect_editor } from "./bonfire_editor.js";
+import { bonfire_sprites } from "./bonfire_sprites.js";
+import { moonlit_environment } from "./moonlit_environment.js";
+
+/**
+ * The page: a meep `EntityManager` with four systems on it, an entity per thing in the set, and a
+ * frame loop that ticks the one and draws the other.
+ *
+ * There is no particle code here at all. The fire is four entities, each carrying a `Transform64`
+ * and a `ParticleEffect`, and `GPUParticleEmitterSystem` is what makes them burn — the same way
+ * `ShadedGeometrySystem` makes the logs visible and `LightSystem` makes the moon shine. That
+ * symmetry is what the page exists to show, and it is the whole of the API being demonstrated:
+ *
+ * ```js
+ * new Entity()
+ *     .add(new Transform64())
+ *     .add(ParticleEffect.from({ ...effect, spawn_rate: 900 }))
+ *     .build(dataset);
+ * ```
+ *
+ * Serve the workspace with `npm run dev --workspace @woosh/meep-engine` and open
+ * `/src/shade/playground/particle_ecs/index.html`. See README.md for what to look at and for the
+ * `?debug` query flag that swaps the frame loop for manual stepping.
+ */
+
+/** Particles one press of "Stoke the fire" asks the ember emitter for. */
+const STOKE_EMBERS = 900;
+
+/** …and the flame, so the fire visibly flares rather than only throwing sparks. */
+const STOKE_FLAME = 400;
+
+/** How often the counters are copied back for the overlay. Display only — nothing sizes a pass. */
+const STATS_INTERVAL_FRAMES = 20;
+
+/** Bytes {@link capture_stats} copies: the particle counters, then the indirect draw args. */
+const STATS_BYTES = 64;
+const STATS_OFFSET_DRAW_ARGS = 48;
+
+const CAMERA = {
+    position: new Vector3(2.9, 1.35, 3.7),
+    target: new Vector3(0, 1.0, 0),
+    fov_degrees: 48,
+    near: 0.05,
+    far: 300,
+};
+
+const element = id => document.getElementById(id);
+
+const view_size = () => [Math.max(1, window.innerWidth), Math.max(1, window.innerHeight)];
+
+async function main() {
+    // ---- the world, before any device -------------------------------------------------------
+    // Entities and components are plain data, so all of this is built and correct whether or not a
+    // WebGPU adapter ever turns up. The systems below are what need one.
+
+    const graphics = new GraphicsEngine();
+    const scene = new Scene();
+
+    // Before any system starts: `GraphicsEngine.set_scene` fills an environment in for a scene that
+    // has none, and its default is a daylight sky — which would leave the fire as a pale smudge.
+    scene.lights.environment = moonlit_environment();
+
+    element("viewport").appendChild(graphics.viewport.el);
+
+    const [initial_width, initial_height] = view_size();
+
+    graphics.viewport.size.set(initial_width, initial_height);
+
+    const assets = new AssetManager({ context: {}, executor: new ConcurrentExecutor() });
+
+    await assets.registerLoader(GameAssetType.Image, new ImageRGBADataLoader());
+
+    assets.startup();
+
+    const dataset = new EntityComponentDataset();
+    const entities = new EntityManager();
+
+    const particles = new GPUParticleEmitterSystem(graphics, scene, assets);
+
+    entities.addSystem(new ShadedGeometrySystem(graphics, scene));
+    entities.addSystem(new LightSystem(graphics, scene));
+    entities.addSystem(particles);
+    entities.attachDataset(dataset);
+
+    await new Promise((resolve, reject) => entities.startup(resolve, reject));
+
+    const sprites = bonfire_sprites();
+    const world = await build_bonfire_world(dataset, { sprites });
+
+    // ---- camera and controls ------------------------------------------------------------------
+    // Wired before the device on purpose: a browser without an adapter still gets a page that can be
+    // driven, and the failure it reports is the device's rather than a cascade of undefined handlers.
+
+    const camera = graphics.camera.camera;
+
+    camera.near = CAMERA.near;
+    camera.far = CAMERA.far;
+    camera.fov = CAMERA.fov_degrees * DEG_TO_RAD;
+
+    // document.body rather than the canvas: the controller starts a keyboard device, and only a
+    // focusable element receives key events
+    const controller = new OrbitalCameraController(camera, document.body);
+
+    controller.look(CAMERA.position, CAMERA.target);
+    controller.movement_speed_scale = 2;
+
+    document.body.focus();
+
+    /*
+     Which checkbox drives which effect, by index rather than by component: a live edit in the
+     particle editor REPLACES the component on the entity, so a handler that had captured one would
+     be writing to an object that left the dataset several edits ago.
+    */
+    for (let i = 0; i < BONFIRE_EFFECT_NAMES.length; i++) {
+        const id = BONFIRE_EFFECT_NAMES[i];
+
+        element(id).addEventListener("change", () => {
+            /*
+             The whole of turning an effect off: write the component. No system call, no node, no
+             remembering what the rate was — `emitting` holds the authored `spawn_rate` and the next
+             frame's comparison finds the change. Particles already alive burn out on their own,
+             which is what putting a fire out looks like.
+            */
+            world.effects[i].emitting = element(id).checked;
+        });
+    }
+
+    element("stoke").addEventListener("click", () => {
+        /*
+         And the whole of a one-shot: ask the entity. The request is queued and handed to the GPU
+         after the next frame's membership sweep, so it works before the first frame has run and it
+         goes through the same spawn path the continuous rate does.
+        */
+        particles.burst(world.embers, STOKE_EMBERS);
+        particles.burst(world.flame, STOKE_FLAME);
+    });
+
+    // ---- the particle editor --------------------------------------------------------------------
+    // E opens it over the fire. An edit recompiles the document and swaps the component on its
+    // entity, so what is on screen is the effect being edited rather than a preview of it.
+
+    const editor = install_effect_editor({
+        dataset,
+        world,
+        sprites: bonfire_sprite_urls(sprites),
+        host: element("effect_editor"),
+        selector: element("editor_effect"),
+        status: element("editor_status"),
+        mount: element("editor_mount"),
+    });
+
+    element("editor_close").addEventListener("click", close_editor);
+
+    element("editor_download").addEventListener("click", () => {
+        const source = editor.current();
+
+        download_json(`${source.name}.json`, source.toJSON());
+    });
+
+    element("editor_import").addEventListener("click", () => element("editor_file").click());
+
+    element("editor_file").addEventListener("change", async event => {
+        const file = event.target.files?.[0];
+
+        if (file === undefined) {
+            return;
+        }
+
+        try {
+            editor.import_json(JSON.parse(await file.text()));
+        } catch (e) {
+            console.error(e);
+            element("editor_status").textContent = `could not open ${file.name}: ${e.message}`;
+            element("editor_status").className = "failed";
+        }
+
+        // cleared, so opening the same file twice in a row fires again
+        event.target.value = "";
+    });
+
+    /**
+      * Leave the editor and hand the keyboard back to the scene.
+      *
+      * The focus matters: the camera controller listens on `body`, so coming back with the caret
+      * still in a spawn-rate field would leave WASD typing numbers into it.
+      */
+    function close_editor() {
+        if (!editor.is_open()) {
+            return;
+        }
+
+        editor.toggle();
+        document.body.focus();
+    }
+
+    /*
+     Bound in the CAPTURE phase, which is the difference between a way out and a trap: the editor is
+     a tree of views that stop propagation on the keys they own, and a listener on `window` in the
+     bubble phase is the last thing an event reaches — if it reaches it at all.
+    */
+    window.addEventListener("keydown", event => {
+        if (event.ctrlKey || event.metaKey || event.altKey || event.repeat) {
+            return;
+        }
+
+        const escape = event.key === "Escape" || event.code === "Escape";
+        const toggle = event.key.toLowerCase() === "e" || event.code === "KeyE";
+
+        if (!escape && !toggle) {
+            return;
+        }
+
+        /*
+         Escape leaves, from anywhere, including from inside a field. It types nothing, so there is
+         nothing for it to conflict with — and using the editor means clicking into its fields, after
+         which a rule that says "not while something is focused" means there is no key that gets you
+         out at all. That is the bug this replaces: E opened the editor and then never closed it.
+        */
+        if (escape) {
+            if (!editor.is_open()) {
+                return;
+            }
+
+            event.preventDefault();
+            close_editor();
+
+            return;
+        }
+
+        // E is a letter, so it belongs to whatever is being typed into — a text field, or a <select>,
+        // where letters jump to the option that starts with one. Escape is the way out of those.
+        const focused = event.target;
+
+        if (
+            focused instanceof HTMLInputElement
+            || focused instanceof HTMLTextAreaElement
+            || focused instanceof HTMLSelectElement
+            || (focused instanceof HTMLElement && focused.isContentEditable)
+        ) {
+            return;
+        }
+
+        event.preventDefault();
+
+        if (editor.is_open()) {
+            close_editor();
+        } else {
+            editor.toggle();
+        }
+    }, true);
+
+    /*
+     `particle_editor` rather than `editor`: an element with an id is already a global of that name,
+     so `globalThis.editor` reads as the <section> until this line runs and as the handle afterwards.
+     One name, one meaning.
+    */
+    Object.assign(globalThis, {
+        graphics, scene, dataset, entities, particles, world, camera, controller,
+        particle_editor: editor,
+    });
+
+    /**
+     * Where the camera is and what it orbits, as plain numbers: enough to put another instance of
+     * this page in exactly the same view.
+     *
+     * @returns {{position: number[], target: number[], fov_degrees: number}}
+     */
+    globalThis.camera_state = () => {
+        const p = camera.transform;
+        const t = controller.target;
+        const round = v => Math.round(v * 1000) / 1000;
+
+        return {
+            position: [round(p.translation_x), round(p.translation_y), round(p.translation_z)],
+            target: [round(t.x), round(t.y), round(t.z)],
+            fov_degrees: round(camera.fov / DEG_TO_RAD),
+        };
+    };
+
+    /**
+     * Put the camera where a {@link camera_state} says.
+     *
+     * @param {{position: number[], target: number[], fov_degrees?: number}|string} state
+     */
+    globalThis.apply_camera = state => {
+        const parsed = typeof state === "string" ? JSON.parse(state) : state;
+
+        if (parsed.fov_degrees !== undefined) {
+            camera.fov = parsed.fov_degrees * DEG_TO_RAD;
+        }
+
+        controller.look(
+            new Vector3(parsed.position[0], parsed.position[1], parsed.position[2]),
+            new Vector3(parsed.target[0], parsed.target[1], parsed.target[2])
+        );
+    };
+
+    // ---- the device, last ---------------------------------------------------------------------
+
+    graphics.on.contextFailed.add(failure => show_message(
+        "There will be no rendering.\n\n" + failure.message
+        + "\n\nThe page needs WebGPU with subgroups and immediate data, over http://localhost — "
+        + "a secure context, and not file://."
+    ));
+
+    try {
+        await graphics.start();
+    } catch (e) {
+        console.error(e);
+
+        return;
+    }
+
+    const renderer = graphics.renderer;
+
+    globalThis.renderer = renderer;
+
+    // The particles are drawn inside the AVBOIT transparency pipeline as a side channel of the
+    // transparent meshes. MBOIT is the legacy path and has no particle channel.
+    renderer.transparency_mode = ShadeTransparencyMode.AVBOIT;
+
+    // Eye adaptation drifts for seconds after any change, which makes a fire impossible to judge —
+    // it is the brightest thing in a dark frame, so the adaptation chases it as it flickers.
+    renderer.feature_automatic_exposure_enabled = false;
+    renderer.exposure_compensation = 0;
+
+    const device = renderer.graphics.device;
+
+    /** @type {(() => void)|null} */
+    let stop_loop = null;
+
+    device.lost?.then(info => {
+        stop_loop?.();
+        show_message("The GPU device was lost.\n\n" + (info?.message ?? ""));
+    });
+
+    // ---- profiling ------------------------------------------------------------------------------
+    // T records a GPU capture and T again saves it. Worth having on this page in particular: four
+    // distinct VM programs means the simulate pass runs four coherence buckets, and what that costs
+    // relative to the emit, the bounds and the three AVBOIT passes is not a thing anybody can guess.
+
+    install_profile_hotkey({
+        renderer,
+        name: "particle_ecs",
+        status: element("profile_status"),
+        settings: () => [
+            `${particles.emitters.length} emitters`,
+            BONFIRE_EFFECT_NAMES.filter((_, i) => world.effects[i].emitting).join("+") || "none emitting",
+            `${globalThis.__stats?.alive ?? "?"} alive`,
+        ],
+    });
+
+    // ---- frame loop -----------------------------------------------------------------------------
+
+    const stats_buffer = device.createBuffer({
+        label: "bonfire/stats",
+        size: STATS_BYTES,
+        usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ,
+    });
+
+    let stats_pending = false;
+    let frame_index = 0;
+    let time = 0;
+    let fps = 0;
+
+    /**
+     * @param {number} dt seconds
+     */
+    function frame(dt) {
+        time += dt;
+        fps = dt > 0 ? fps * 0.9 + 0.1 / dt : fps;
+
+        const [width, height] = view_size();
+
+        if (width !== graphics.viewport.size.x || height !== graphics.viewport.size.y) {
+            graphics.viewport.size.set(width, height);
+        }
+
+        animate_bonfire(world, time);
+        controller.update();
+
+        // The simulation tick: every system's `update`, in the order the manager resolved. The
+        // particle system's is where the four components are compared against their emitters.
+        entities.update(dt);
+
+        /*
+         Nothing is drawn while the editor is up. It covers the window, so a frame underneath it is
+         a whole scene — the transparency pipeline, the particle passes, the resolve — composited
+         behind an opaque panel and then thrown away. Measured at 1075x1216, the trickle this
+         replaces ran 9.8 of them a second, each costing 3.5 ms of CPU to encode and about 21 ms
+         from submission to completion — so a fifth of every second went to pixels nobody could
+         see. The machine goes to the graph editor instead, which is the thing you are looking at.
+
+         An edit still reaches the GPU, it just waits for the way back: GPUParticleEmitterSystem
+         publishes the emitter table from `prepare` at FrameStart rather than from the tick above,
+         and that is idempotent by design, because a frame must not depend on a simulation tick
+         having preceded it. So the first frame after Escape carries every edit made while the
+         editor was open.
+
+         What this gives up is that the fire no longer advances behind the editor — the simulation
+         is GPU work, so you come back to the instant you left rather than a few seconds on. An edit
+         kills and restarts the effect anyway, which is where that would otherwise have shown.
+        */
+        if (!editor.is_open()) {
+            graphics.render(dt);
+        }
+
+        frame_index++;
+
+        /*
+         The counters only move on a drawn frame and the panel showing them is behind the editor, so
+         while it is open this would be a copy and a map round trip for numbers nobody can see that
+         have not changed since the last one.
+        */
+        if (!editor.is_open() && !stats_pending && frame_index % STATS_INTERVAL_FRAMES === 0) {
+            capture_stats();
+        }
+    }
+
+    /** Read the counters back to display them. Submitted on its own, after the frame's own work. */
+    function capture_stats() {
+        const system = renderer.particles(renderer.scenes.obtain(scene));
+        const buffers = system.buffers;
+        const encoder = device.createCommandEncoder({ label: "bonfire/stats" });
+
+        encoder.copyBufferToBuffer(buffers.counters, 0, stats_buffer, 0, PARTICLE_COUNTER_COUNT * 4);
+        encoder.copyBufferToBuffer(buffers.draw_args, 0, stats_buffer, STATS_OFFSET_DRAW_ARGS, 4 * 4);
+
+        device.queue.submit([encoder.finish()]);
+
+        stats_pending = true;
+
+        stats_buffer.mapAsync(GPUMapMode.READ).then(() => {
+            const words = new Uint32Array(stats_buffer.getMappedRange().slice(0));
+
+            stats_buffer.unmap();
+            stats_pending = false;
+
+            globalThis.__stats = {
+                frame: frame_index,
+                fps,
+                alive: words[0],
+                dead: words[1],
+                draw: words[STATS_OFFSET_DRAW_ARGS / 4 + 1],
+                emitters: particles.emitters.length,
+            };
+
+            write_hud(globalThis.__stats);
+        }).catch(() => {
+            stats_pending = false;
+        });
+    }
+
+    /**
+     * One frame, with the loop stopped on the first failure.
+     *
+     * A lost device makes `render` throw, and the frame loop re-arms itself before it calls back —
+     * so without this the page would throw once per frame for ever, with the first and most
+     * informative failure scrolled far out of reach.
+     *
+     * @param {number} dt
+     */
+    function guarded_frame(dt) {
+        try {
+            frame(dt);
+        } catch (e) {
+            stop_loop?.();
+            console.error(e);
+            show_message("The frame failed and the loop has stopped.\n\n" + e.message);
+        }
+    }
+
+    if (new URLSearchParams(location.search).has("debug")) {
+        // Drive frames by hand when the tab is hidden (rAF suspended) — headless verification.
+        // Nothing is scheduled: a stray rAF frame interleaved with __step would make the count the
+        // caller asked for and the count that ran two different numbers.
+        globalThis.__step = (n = 1, dt = 1 / 60) => {
+            for (let i = 0; i < n; i++) {
+                guarded_frame(dt);
+            }
+
+            return frame_index;
+        };
+
+        return;
+    }
+
+    stop_loop = create_frame_loop(dt => guarded_frame(Math.min(dt, 0.05)));
+}
+
+/**
+ * @param {{fps: number, alive: number, dead: number, draw: number, emitters: number}} stats
+ */
+function write_hud({ fps, alive, dead, draw, emitters }) {
+    const put = (id, value) => {
+        const node = element(id);
+
+        if (node !== null) {
+            node.textContent = value;
+        }
+    };
+
+    put("stat-fps", fps.toFixed(0));
+    put("stat-alive", alive.toLocaleString());
+    put("stat-dead", dead.toLocaleString());
+    put("stat-draw", draw.toLocaleString());
+    put("stat-emitters", String(emitters));
+}
+
+/**
+ * Hand the browser a file. The editor's Download button is the only thing here that produces one,
+ * and it is the whole of the round trip: what comes out is what `effects/` holds.
+ *
+ * @param {string} filename
+ * @param {object} json
+ */
+function download_json(filename, json) {
+    const url = URL.createObjectURL(
+        new Blob([JSON.stringify(json, null, 2)], { type: "application/json" })
+    );
+
+    const anchor = document.createElement("a");
+
+    anchor.href = url;
+    anchor.download = filename;
+
+    document.body.appendChild(anchor);
+    anchor.click();
+    anchor.remove();
+
+    // Revoking in the same task cancels the download in some browsers — the click only schedules it.
+    setTimeout(() => URL.revokeObjectURL(url), 60000);
+}
+
+function show_message(text) {
+    const node = element("message");
+
+    if (node !== null) {
+        node.textContent = text;
+    }
+}
+
+main().catch(e => {
+    console.error(e);
+    show_message("The bonfire playground failed to start — see the console.\n\n" + e.message);
+});

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

@@ -0,0 +1,16 @@
+/**
+ * The environment map. Assign it to `scene.lights.environment`.
+ *
+ * @returns {ShadeTexture}
+ */
+export function moonlit_environment(): ShadeTexture;
+/**
+ * Where the moon is. Unit, +Y up — the direction light arrives *from*, so the shadows fall the
+ * other way.
+ *
+ * @type {Vector3}
+ */
+export const MOON_DIRECTION: Vector3;
+import { ShadeTexture } from "../../renderer/texture/ShadeTexture.js";
+import Vector3 from "../../../core/geom/Vector3.js";
+//# sourceMappingURL=moonlit_environment.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"moonlit_environment.d.ts","sourceRoot":"","sources":["../../../../../src/shade/playground/particle_ecs/moonlit_environment.js"],"names":[],"mappings":"AAyGA;;;;GAIG;AACH,uCAFa,YAAY,CAmCxB;AA9GD;;;;;GAKG;AACH,6BAFU,OAAO,CAEyD;6BAjC7C,wCAAwC;oBANjD,+BAA+B"}