npm - @woosh/meep-engine - Versions diffs - 3.1.0 → 3.3.0 - Mend

@woosh/meep-engine 3.1.0 → 3.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1869) hide show

package/src/engine/Engine.js CHANGED Viewed

@@ -1,726 +1,726 @@
-/**
- *
- */
-import { assert } from "../core/assert.js";
-import Vector1 from "../core/geom/Vector1.js";
-import { Localization } from "../core/localization/Localization.js";
-import { ModuleRegistry } from "../core/model/ModuleRegistry.js";
-import ObservedBoolean from "../core/model/ObservedBoolean.js";
-import ConcurrentExecutor from '../core/process/executor/ConcurrentExecutor.js';
-import EmptyView from "../view/elements/EmptyView.js";
-import { ViewStack } from "../view/elements/navigation/ViewStack.js";
-import { WebGLContextFailureView } from "../view/graphics/WebGLContextFailureView.js";
-import { AssetManager } from './asset/AssetManager.js';
-import { AssetPreloader } from "./asset/preloader/AssetPreloader.js";
-import { MetricCollection } from "./development/performance/MetricCollection.js";
-import { MetricStatistics } from "./development/performance/MetricStatistics.js";
-import { PeriodicConsolePrinter } from "./development/performance/monitor/PeriodicConsolePrinter.js";
-import { EntityManager } from "./ecs/EntityManager.js";
-import { BinarySerializationRegistry } from "./ecs/storage/binary/BinarySerializationRegistry.js";
-import { GraphicsEngine3 } from './graphics3/GraphicsEngine3.js';
-import { GamepadDevice } from "./input/devices/GamepadDevice.js";
-import KeyboardDevice from "./input/devices/KeyboardDevice.js";
-import { PointerDevice } from "./input/devices/PointerDevice.js";
-import { StaticKnowledgeDatabase, StaticKnowledgeState } from "./knowledge/database/StaticKnowledgeDatabase.js";
-import { logger } from "./logging/GlobalLogger.js";
-import { OptionGroup } from "./options/OptionGroup.js";
-import { EnginePluginManager } from "./plugin/EnginePluginManager.js";
-import SceneManager from "./scene/SceneManager.js";
-import Ticker from "./simulation/Ticker.js";
-import SoundEngine from './sound/SoundEngine.js';
-import GUIEngine from './ui/GUIEngine.js';
-class EngineSettings {
-    graphics_control_viewport_size = new ObservedBoolean(true);
-    simulation_speed = new Vector1(1);
-    input_mouse_sensitivity = new Vector1(5);
-}
-const METRIC_ID_FRAME = 'frame_delay';
-const METRIC_ID_RENDER = 'render_time';
-const METRIC_ID_SIMULATION = 'simulation_time';
-/**
- * How long a context loss is tolerated before the simulation is paused as well, in seconds. Most losses
- * are resolved in well under a second, and stopping the world for those would be more disruptive than
- * letting it run; a longer outage is worth pausing for, as the player cannot see what is happening.
- * @type {number}
- */
-const CONTEXT_LOSS_SIMULATION_PAUSE_DELAY = 2;
-class Engine {
-    #last_frame_timestamp = 0;
-    /**
-     * Handle of the pending render-loop frame, `-1` when the loop is not running
-     * @type {number}
-     */
-    #animation_frame_handle = -1;
-    /**
-     * Handle of the pending "pause the simulation, this outage is taking a while" timer, `-1` when none
-     * @type {number}
-     */
-    #context_loss_pause_timer = -1;
-    /**
-     * Whether the simulation was paused because of a context loss, and therefore should be resumed once
-     * the context comes back
-     * @type {boolean}
-     */
-    #paused_by_context_loss = false;
-    /**
-     * Absent when the engine is constructed with `enableGraphics: false`.
-     * @type {GraphicsEngine3|null}
-     */
-    graphics = null;
-    /**
-     * Absent when the engine is constructed with `enableAudio: false`.
-     * @type {SoundEngine|null}
-     */
-    sound = null;
-    viewStack = new ViewStack();
-    /**
-     *
-     * Static database
-     * Can contain tables of structured data that the application often works with.
-     * Engine startup will load all tables ensuring that data is ready once startup finishes
-     * Use sparingly, this is not suitable for very large amounts of data as all the data will be in memory and deserialization will stall engine startup
-     * Example: inventory item table, monster table
-     * @readonly
-     * @type {StaticKnowledgeDatabase}
-     */
-    staticKnowledge = new StaticKnowledgeDatabase();
-    /**
-     * @readonly
-     * @type {EnginePluginManager}
-     */
-    plugins = new EnginePluginManager();
-    /**
-     * Main simulation ticker
-     * @readonly
-     * @type {Ticker}
-     */
-    ticker = new Ticker();
-    /**
-     * Default executor, enables time-sharing concurrency
-     * @readonly
-     * @type {ConcurrentExecutor}
-     */
-    executor = new ConcurrentExecutor(1, 10);
-    /**
-     *
-     * @param {EnginePlatform} platform
-     * @param {EntityManager} [entityManager]
-     * @param {boolean} [enableGraphics]
-     * @param {boolean} [enableAudio]
-     * @param {boolean} [debug]
-     * @constructor
-     */
-    constructor(platform, {
-        entityManager,
-        enableGraphics = true,
-        enableAudio = true,
-        debug = true
-    } = {}) {
-        assert.defined(platform, 'platform');
-        /**
-         *
-         * @type {EnginePlatform}
-         */
-        this.platform = platform;
-        this.staticKnowledge.validation_enabled = debug;
-        /**
-         *
-         * @type {MetricCollection}
-         */
-        this.performance = new MetricCollection();
-        this.__using_external_entity_manager = entityManager !== undefined;
-        //setup entity component system
-        if (this.__using_external_entity_manager) {
-            // external entity manager provided
-            this.entityManager = entityManager;
-        } else {
-            this.entityManager = new EntityManager();
-        }
-        /**
-         *
-         * @type {AssetManager<Engine>}
-         */
-        this.assetManager = new AssetManager({
-            context: this,
-            executor: this.executor
-        });
-        this.__performacne_monitor = new PeriodicConsolePrinter(15, () => {
-            const metrics = this.performance;
-            const stats = new MetricStatistics();
-            // RENDER
-            const m_render = metrics.get(METRIC_ID_RENDER);
-            m_render.computeStats(stats);
-            const v_render = (stats.mean * 1000).toFixed(2);
-            // SIMULATION
-            const m_sim = metrics.get(METRIC_ID_SIMULATION);
-            m_sim.computeStats(stats);
-            const v_sim = (stats.mean * 1000).toFixed(2);
-            // FPS
-            const m_frame = metrics.get(METRIC_ID_FRAME);
-            m_frame.computeStats(stats);
-            const v_fps = (1 / stats.mean).toFixed(2);
-            // clear stats
-            m_render.clear();
-            m_sim.clear();
-            m_frame.clear();
-            return `FPS: ${v_fps}, RENDER: ${v_render}ms, SIMULATION: ${v_sim}ms`;
-        });
-        if (!this.__using_external_entity_manager) {
-            // subscribe simulator to common ticker
-            this.ticker.onTick.add(timeDelta => {
-                const t0 = performance.now();
-                this.entityManager.simulate(timeDelta);
-                const t1 = performance.now();
-                const duration = (t1 - t0) / 1000;
-                // record frame time
-                this.performance.get(METRIC_ID_SIMULATION).record(duration);
-            });
-        }
-        // initialize performance metrics
-        this.performance.create({
-            name: METRIC_ID_RENDER
-        });
-        this.performance.create({
-            name: METRIC_ID_SIMULATION
-        });
-        this.performance.create({
-            name: METRIC_ID_FRAME
-        });
-        /**
-         *
-         * @type {OptionGroup}
-         */
-        this.options = new OptionGroup("options");
-        /**
-         *
-         * @type {ModuleRegistry}
-         */
-        this.moduleRegistry = new ModuleRegistry();
-        /**
-         * @readonly
-         * @type {BinarySerializationRegistry}
-         */
-        this.binarySerializationRegistry = new BinarySerializationRegistry();
-        this.settings = new EngineSettings();
-        /**
-         * @deprecated use plugins instead
-         */
-        this.services = {};
-        /**
-         *
-         * @type {Storage}
-         */
-        this.storage = this.platform.getStorage();
-        this.localization = new Localization();
-        this.localization.setAssetManager(this.assetManager);
-        if (enableGraphics !== false) {
-            /**
-             * @type {GraphicsEngine3}
-             */
-            const graphicsEngine = new GraphicsEngine3();
-            this.graphics = graphicsEngine;
-            // The renderer is not started here. Acquiring a WebGPU device is asynchronous and a
-            // constructor is the wrong place to fail from, so `start()` does it — which is also
-            // what makes the device restartable (E1).
-            graphicsEngine.on.contextLost.add(this.#handle_context_lost, this);
-            graphicsEngine.on.contextRestored.add(this.#handle_context_restored, this);
-            graphicsEngine.on.contextFailed.add(this.#handle_context_failed, this);
-        } else {
-            logger.info('enableGraphics option is not set, no graphics engine will be created');
-        }
-        if (enableAudio !== false) {
-            //sound engine
-            const soundEngine = new SoundEngine();
-            soundEngine.volume = 1;
-            /**
-             *
-             * @type {SoundEngine}
-             */
-            this.sound = soundEngine;
-        } else {
-            logger.info('enableAudio option is not set, no audio engine will be created');
-        }
-        /**
-         * Graphical User Interface engine
-         * @type {GUIEngine}
-         */
-        this.gui = new GUIEngine();
-        /**
-         * @readonly
-         * @type {SceneManager}
-         */
-        this.sceneManager = new SceneManager(this.entityManager, this.ticker.clock);
-        this.initializeViews();
-        this.devices = {
-            pointer: new PointerDevice(this.viewStack.el),
-            keyboard: new KeyboardDevice(this.viewStack.el),
-            gamepad: new GamepadDevice()
-        };
-        this.devices.pointer.start();
-        this.devices.keyboard.start();
-        this.devices.gamepad.start();
-        //process settings
-        this.initializeSettings();
-        logger.info("engine initialized");
-        /**
-         * Toggles GraphicsEngine rendering on and off
-         * @type {boolean}
-         */
-        this.renderingEnabled = true;
-        this.plugins.initialize(this);
-    }
-    #clear_context_loss_pause_timer() {
-        if (this.#context_loss_pause_timer !== -1) {
-            clearTimeout(this.#context_loss_pause_timer);
-            this.#context_loss_pause_timer = -1;
-        }
-    }
-    /**
-     * Pauses the simulation, if it is running. {@link Ticker#pause} freezes the clock, so no simulation
-     * time accrues while we wait and the first step after resuming is a normal-sized one.
-     *
-     * A ticker that is already paused is left alone - somebody else owns that pause and it is not ours to
-     * undo when the context comes back.
-     */
-    #pause_simulation_for_context_loss() {
-        this.#context_loss_pause_timer = -1;
-        if (this.#paused_by_context_loss) {
-            return;
-        }
-        const ticker = this.ticker;
-        if (!ticker.is_active || ticker.is_paused) {
-            return;
-        }
-        this.#paused_by_context_loss = true;
-        logger.warn('Graphics context outage is taking a while, pausing simulation');
-        ticker.pause();
-    }
-    #handle_context_lost() {
-        logger.warn('Graphics context lost, waiting for recovery');
-        this.#clear_context_loss_pause_timer();
-        this.#context_loss_pause_timer = setTimeout(
-            () => this.#pause_simulation_for_context_loss(),
-            CONTEXT_LOSS_SIMULATION_PAUSE_DELAY * 1000
-        );
-    }
-    #handle_context_restored() {
-        this.#clear_context_loss_pause_timer();
-        if (this.#paused_by_context_loss) {
-            this.#paused_by_context_loss = false;
-            if (this.ticker.is_active) {
-                this.ticker.resume();
-            }
-        }
-        logger.info('Graphics context restored, rendering resumed');
-    }
-    /**
-     * @param {ShadeDeviceFailure} reason carries a message written to be shown to a person
-     */
-    #handle_context_failed(reason) {
-        logger.error(`Graphics context recovery abandoned (${reason}), no further rendering is possible`);
-        this.#clear_context_loss_pause_timer();
-        // nothing can be drawn any more, so let the simulation stop rather than burn cycles invisibly.
-        // Application state is left intact, which keeps a save-on-failure handler viable.
-        this.#pause_simulation_for_context_loss();
-        this.viewStack.addChild(new WebGLContextFailureView());
-    }
-    #initialize_audio() {
-        const sound = this.sound;
-        if (sound === null) {
-            // no sound engine
-            return;
-        }
-        // hook up context resumption to input
-        if (this.devices.pointer !== undefined) {
-            this.devices.pointer.on.down.addOne(sound.resumeContext, sound);
-            this.devices.keyboard.on.down.addOne(sound.resumeContext, sound);
-        }
-    }
-    initializeViews() {
-        const gameView = new EmptyView();
-        gameView.addClass('game-view');
-        gameView.css({
-            left: 0,
-            top: 0,
-            position: "absolute",
-            pointerEvents: "none"
-        });
-        this.gameView = gameView;
-        this.viewStack.push(gameView, 'game-view');
-        if (this.graphics !== null) {
-            const viewport = this.graphics.viewport;
-            viewport.css({
-                pointerEvents: "auto"
-            });
-            gameView.addChild(viewport);
-            //bind size of renderer viewport to game view
-            viewport.bindSignal(gameView.size.onChanged, viewport.size.set.bind(viewport.size));
-            gameView.on.linked.add(function () {
-                viewport.size.copy(gameView.size);
-            });
-        }
-    }
-    initializeSettings() {
-        logger.info('Initializing engine settings...');
-        const engine = this;
-        function setViewportToWindowSize() {
-            // get parent element
-            let parentElement = engine.viewStack.el.parentElement;
-            while (parentElement !== null && parentElement.innerWidth === undefined) {
-                // traverse up until we find an element with defined dimensions
-                parentElement = parentElement.parentElement;
-            }
-            if (parentElement === null || parentElement === undefined) {
-                // no parent element, default to window
-                parentElement = window;
-            }
-            engine.viewStack.size.set(parentElement.innerWidth, parentElement.innerHeight);
-        }
-        this.settings.graphics_control_viewport_size.process(function (value) {
-            if (value) {
-                setViewportToWindowSize();
-                window.addEventListener("resize", setViewportToWindowSize, false);
-            } else {
-                window.removeEventListener("resize", setViewportToWindowSize);
-            }
-        });
-        logger.info('Engine settings initilized.');
-    }
-    benchmark() {
-        const duration = 2000;
-        let count = 0;
-        const t0 = Date.now();
-        let t1;
-        while (true) {
-            this.entityManager.simulate(0.0000000001);
-            t1 = Date.now();
-            if (t1 - t0 > duration) {
-                break;
-            }
-            count++;
-        }
-        //normalize
-        const elapsed = (t1 - t0) / 1000;
-        const rate = (count / elapsed);
-        return rate;
-    }
-    /**
-     * Returns preloader object
-     * @param {String} listURL
-     */
-    loadAssetList(listURL) {
-        const preloader = new AssetPreloader();
-        const assetManager = this.assetManager;
-        assetManager.get({
-            path: listURL, type: "json", callback: function (asset) {
-                preloader.addAll(asset.create());
-                preloader.load(assetManager);
-            }
-        });
-        return preloader;
-    }
-    render() {
-        assert.isInstanceOf(this, Engine, 'this', 'Engine');
-        const graphics = this.graphics;
-        if (graphics === null) {
-            // headless
-            return;
-        }
-        if (graphics.autoDraw) {
-            // request redraw
-            graphics.needDraw = true;
-        }
-        if (this.renderingEnabled && graphics.needDraw) {
-            const metrics = this.performance;
-            const t0 = performance.now();
-            graphics.render();
-            const t1 = performance.now();
-            const frame_time = (t1 - t0) / 1000;
-            // record frame time
-            metrics.get(METRIC_ID_RENDER).record(frame_time);
-        }
-    }
-    /**
-     * Startup
-     * @returns {Promise}
-     */
-    async start() {
-        // First, and awaited: systems read `graphics.viewport` and size themselves off it during
-        // their own startup, so the device has to exist before the entity manager runs.
-        if (this.graphics !== null) {
-            await this.graphics.start();
-        }
-        this.assetManager.startup();
-        this.#initialize_audio();
-        const promiseEntityManager = () => {
-            return new Promise((resolve, reject) => {
-                //initialize entity manager
-                this.entityManager.startup(resolve, reject);
-            });
-        }
-        this.__performacne_monitor.start();
-        const sound = this.sound;
-        const soundStarted = sound === null
-            ? Promise.resolve()
-            : sound.start();
-        const knowledge = this.staticKnowledge;
-        // static knowledge is engine-lifetime content and a stop does not drop it, so a restart keeps
-        // what the first start loaded. `load` accepts the Initial state only; callers that want the
-        // tables re-read call `reset` first.
-        const knowledgeLoaded = knowledge.state === StaticKnowledgeState.Initial
-            ? knowledge.load(this.assetManager, this.executor)
-            : Promise.resolve();
-        return Promise.all([
-            soundStarted.then(promiseEntityManager),
-            knowledgeLoaded,
-            this.gui.startup(this),
-            this.plugins.startup()
-        ]).then(async () => {
-            this.#last_frame_timestamp = performance.now();
-            /**
-             * Starting the engine
-             */
-            this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
-            //start simulation
-            this.ticker.start({ maxTimeout: 200 });
-            //self.uiController.init(self);
-            //load options
-            await this.options.attachToStorage('lazykitty.komrade.options', this.storage);
-            logger.info('engine started');
-        }, function (e) {
-            logger.error(`Engine Failed to start: ${e}`);
-            // the caller awaits start() to know whether the engine came up;
-            // swallowing this reported success after a failed startup
-            throw e;
-        });
-    }
-    /**
-     * Fired every animation frame via {@link requestAnimationFrame}
-     */
-    #animation_frame = () => {
-        const t0 = this.#last_frame_timestamp;
-        const t1 = performance.now();
-        this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
-        this.render();
-        const frame_delay = (t1 - t0) / 1000;
-        // swap variables
-        this.#last_frame_timestamp = t1;
-        // record metric
-        this.performance.get(METRIC_ID_FRAME).record(frame_delay);
-    }
-    /**
-     * Shutdown the engine, disposing all relevant resources
-     */
-    async stop() {
-        this.__performacne_monitor.stop();
-        // stop the ticker. pause() throws when the loop is not currently
-        // running, which would abort the whole teardown below
-        this.ticker.stop();
-        // and the render loop, which re-requests itself every frame and would
-        // otherwise keep calling render() on a torn-down engine forever
-        cancelAnimationFrame(this.#animation_frame_handle);
-        this.#animation_frame_handle = -1;
-        // shutdown entity manager
-        if (!this.__using_external_entity_manager) {
-            await new Promise((resolve, reject) => this.entityManager.shutdown(resolve, reject));
-        }
-        // shutdown plugins
-        await this.plugins.shutdown();
-        // stop gui
-        await this.gui.shutdown();
-        // TODO shutdown executor
-        await this.assetManager.shutdown();
-        // last, so that everything above still has a live context to release its GPU resources through
-        const graphics = this.graphics;
-        if (graphics !== null) {
-            graphics.stop();
-        }
-    }
-    exit() {
-        window.close();
-    }
-    /**
-     * @returns {Promise}
-     */
-    requestExit() {
-        return this.gui.confirmTextDialog({
-            title: this.localization.getString('system_confirm_exit_to_system.title'),
-            text: this.localization.getString('system_confirm_exit_to_system.text')
-        }).then(() => {
-            this.exit();
-        });
-    }
-}
-/**
- * @readonly
- * @type {boolean}
- */
-Engine.prototype.isEngine = true;
-export default Engine;
+/**
+ *
+ */
+import { assert } from "../core/assert.js";
+import Vector1 from "../core/geom/Vector1.js";
+import { Localization } from "../core/localization/Localization.js";
+import { ModuleRegistry } from "../core/model/ModuleRegistry.js";
+import ObservedBoolean from "../core/model/ObservedBoolean.js";
+import ConcurrentExecutor from '../core/process/executor/ConcurrentExecutor.js';
+import EmptyView from "../view/elements/EmptyView.js";
+import { ViewStack } from "../view/elements/navigation/ViewStack.js";
+import { WebGLContextFailureView } from "../view/graphics/WebGLContextFailureView.js";
+import { AssetManager } from './asset/AssetManager.js';
+import { AssetPreloader } from "./asset/preloader/AssetPreloader.js";
+import { MetricCollection } from "./development/performance/MetricCollection.js";
+import { MetricStatistics } from "./development/performance/MetricStatistics.js";
+import { PeriodicConsolePrinter } from "./development/performance/monitor/PeriodicConsolePrinter.js";
+import { EntityManager } from "./ecs/EntityManager.js";
+import { BinarySerializationRegistry } from "./ecs/storage/binary/BinarySerializationRegistry.js";
+import { GraphicsEngine3 } from './graphics3/GraphicsEngine3.js';
+import { GamepadDevice } from "./input/devices/GamepadDevice.js";
+import KeyboardDevice from "./input/devices/KeyboardDevice.js";
+import { PointerDevice } from "./input/devices/PointerDevice.js";
+import { StaticKnowledgeDatabase, StaticKnowledgeState } from "./knowledge/database/StaticKnowledgeDatabase.js";
+import { logger } from "./logging/GlobalLogger.js";
+import { OptionGroup } from "./options/OptionGroup.js";
+import { EnginePluginManager } from "./plugin/EnginePluginManager.js";
+import SceneManager from "./scene/SceneManager.js";
+import Ticker from "./simulation/Ticker.js";
+import SoundEngine from './sound/SoundEngine.js';
+import GUIEngine from './ui/GUIEngine.js';
+class EngineSettings {
+    graphics_control_viewport_size = new ObservedBoolean(true);
+    simulation_speed = new Vector1(1);
+    input_mouse_sensitivity = new Vector1(5);
+}
+const METRIC_ID_FRAME = 'frame_delay';
+const METRIC_ID_RENDER = 'render_time';
+const METRIC_ID_SIMULATION = 'simulation_time';
+/**
+ * How long a context loss is tolerated before the simulation is paused as well, in seconds. Most losses
+ * are resolved in well under a second, and stopping the world for those would be more disruptive than
+ * letting it run; a longer outage is worth pausing for, as the player cannot see what is happening.
+ * @type {number}
+ */
+const CONTEXT_LOSS_SIMULATION_PAUSE_DELAY = 2;
+class Engine {
+    #last_frame_timestamp = 0;
+    /**
+     * Handle of the pending render-loop frame, `-1` when the loop is not running
+     * @type {number}
+     */
+    #animation_frame_handle = -1;
+    /**
+     * Handle of the pending "pause the simulation, this outage is taking a while" timer, `-1` when none
+     * @type {number}
+     */
+    #context_loss_pause_timer = -1;
+    /**
+     * Whether the simulation was paused because of a context loss, and therefore should be resumed once
+     * the context comes back
+     * @type {boolean}
+     */
+    #paused_by_context_loss = false;
+    /**
+     * Absent when the engine is constructed with `enableGraphics: false`.
+     * @type {GraphicsEngine3|null}
+     */
+    graphics = null;
+    /**
+     * Absent when the engine is constructed with `enableAudio: false`.
+     * @type {SoundEngine|null}
+     */
+    sound = null;
+    viewStack = new ViewStack();
+    /**
+     *
+     * Static database
+     * Can contain tables of structured data that the application often works with.
+     * Engine startup will load all tables ensuring that data is ready once startup finishes
+     * Use sparingly, this is not suitable for very large amounts of data as all the data will be in memory and deserialization will stall engine startup
+     * Example: inventory item table, monster table
+     * @readonly
+     * @type {StaticKnowledgeDatabase}
+     */
+    staticKnowledge = new StaticKnowledgeDatabase();
+    /**
+     * @readonly
+     * @type {EnginePluginManager}
+     */
+    plugins = new EnginePluginManager();
+    /**
+     * Main simulation ticker
+     * @readonly
+     * @type {Ticker}
+     */
+    ticker = new Ticker();
+    /**
+     * Default executor, enables time-sharing concurrency
+     * @readonly
+     * @type {ConcurrentExecutor}
+     */
+    executor = new ConcurrentExecutor(1, 10);
+    /**
+     *
+     * @param {EnginePlatform} platform
+     * @param {EntityManager} [entityManager]
+     * @param {boolean} [enableGraphics]
+     * @param {boolean} [enableAudio]
+     * @param {boolean} [debug]
+     * @constructor
+     */
+    constructor(platform, {
+        entityManager,
+        enableGraphics = true,
+        enableAudio = true,
+        debug = true
+    } = {}) {
+        assert.defined(platform, 'platform');
+        /**
+         *
+         * @type {EnginePlatform}
+         */
+        this.platform = platform;
+        this.staticKnowledge.validation_enabled = debug;
+        /**
+         *
+         * @type {MetricCollection}
+         */
+        this.performance = new MetricCollection();
+        this.__using_external_entity_manager = entityManager !== undefined;
+        //setup entity component system
+        if (this.__using_external_entity_manager) {
+            // external entity manager provided
+            this.entityManager = entityManager;
+        } else {
+            this.entityManager = new EntityManager();
+        }
+        /**
+         *
+         * @type {AssetManager<Engine>}
+         */
+        this.assetManager = new AssetManager({
+            context: this,
+            executor: this.executor
+        });
+        this.__performacne_monitor = new PeriodicConsolePrinter(15, () => {
+            const metrics = this.performance;
+            const stats = new MetricStatistics();
+            // RENDER
+            const m_render = metrics.get(METRIC_ID_RENDER);
+            m_render.computeStats(stats);
+            const v_render = (stats.mean * 1000).toFixed(2);
+            // SIMULATION
+            const m_sim = metrics.get(METRIC_ID_SIMULATION);
+            m_sim.computeStats(stats);
+            const v_sim = (stats.mean * 1000).toFixed(2);
+            // FPS
+            const m_frame = metrics.get(METRIC_ID_FRAME);
+            m_frame.computeStats(stats);
+            const v_fps = (1 / stats.mean).toFixed(2);
+            // clear stats
+            m_render.clear();
+            m_sim.clear();
+            m_frame.clear();
+            return `FPS: ${v_fps}, RENDER: ${v_render}ms, SIMULATION: ${v_sim}ms`;
+        });
+        if (!this.__using_external_entity_manager) {
+            // subscribe simulator to common ticker
+            this.ticker.onTick.add(timeDelta => {
+                const t0 = performance.now();
+                this.entityManager.update(timeDelta);
+                const t1 = performance.now();
+                const duration = (t1 - t0) / 1000;
+                // record frame time
+                this.performance.get(METRIC_ID_SIMULATION).record(duration);
+            });
+        }
+        // initialize performance metrics
+        this.performance.create({
+            name: METRIC_ID_RENDER
+        });
+        this.performance.create({
+            name: METRIC_ID_SIMULATION
+        });
+        this.performance.create({
+            name: METRIC_ID_FRAME
+        });
+        /**
+         *
+         * @type {OptionGroup}
+         */
+        this.options = new OptionGroup("options");
+        /**
+         *
+         * @type {ModuleRegistry}
+         */
+        this.moduleRegistry = new ModuleRegistry();
+        /**
+         * @readonly
+         * @type {BinarySerializationRegistry}
+         */
+        this.binarySerializationRegistry = new BinarySerializationRegistry();
+        this.settings = new EngineSettings();
+        /**
+         * @deprecated use plugins instead
+         */
+        this.services = {};
+        /**
+         *
+         * @type {Storage}
+         */
+        this.storage = this.platform.getStorage();
+        this.localization = new Localization();
+        this.localization.setAssetManager(this.assetManager);
+        if (enableGraphics !== false) {
+            /**
+             * @type {GraphicsEngine3}
+             */
+            const graphicsEngine = new GraphicsEngine3();
+            this.graphics = graphicsEngine;
+            // The renderer is not started here. Acquiring a WebGPU device is asynchronous and a
+            // constructor is the wrong place to fail from, so `start()` does it — which is also
+            // what makes the device restartable (E1).
+            graphicsEngine.on.contextLost.add(this.#handle_context_lost, this);
+            graphicsEngine.on.contextRestored.add(this.#handle_context_restored, this);
+            graphicsEngine.on.contextFailed.add(this.#handle_context_failed, this);
+        } else {
+            logger.info('enableGraphics option is not set, no graphics engine will be created');
+        }
+        if (enableAudio !== false) {
+            //sound engine
+            const soundEngine = new SoundEngine();
+            soundEngine.volume = 1;
+            /**
+             *
+             * @type {SoundEngine}
+             */
+            this.sound = soundEngine;
+        } else {
+            logger.info('enableAudio option is not set, no audio engine will be created');
+        }
+        /**
+         * Graphical User Interface engine
+         * @type {GUIEngine}
+         */
+        this.gui = new GUIEngine();
+        /**
+         * @readonly
+         * @type {SceneManager}
+         */
+        this.sceneManager = new SceneManager(this.entityManager, this.ticker.clock);
+        this.initializeViews();
+        this.devices = {
+            pointer: new PointerDevice(this.viewStack.el),
+            keyboard: new KeyboardDevice(this.viewStack.el),
+            gamepad: new GamepadDevice()
+        };
+        this.devices.pointer.start();
+        this.devices.keyboard.start();
+        this.devices.gamepad.start();
+        //process settings
+        this.initializeSettings();
+        logger.info("engine initialized");
+        /**
+         * Toggles GraphicsEngine rendering on and off
+         * @type {boolean}
+         */
+        this.renderingEnabled = true;
+        this.plugins.initialize(this);
+    }
+    #clear_context_loss_pause_timer() {
+        if (this.#context_loss_pause_timer !== -1) {
+            clearTimeout(this.#context_loss_pause_timer);
+            this.#context_loss_pause_timer = -1;
+        }
+    }
+    /**
+     * Pauses the simulation, if it is running. {@link Ticker#pause} freezes the clock, so no simulation
+     * time accrues while we wait and the first step after resuming is a normal-sized one.
+     *
+     * A ticker that is already paused is left alone - somebody else owns that pause and it is not ours to
+     * undo when the context comes back.
+     */
+    #pause_simulation_for_context_loss() {
+        this.#context_loss_pause_timer = -1;
+        if (this.#paused_by_context_loss) {
+            return;
+        }
+        const ticker = this.ticker;
+        if (!ticker.is_active || ticker.is_paused) {
+            return;
+        }
+        this.#paused_by_context_loss = true;
+        logger.warn('Graphics context outage is taking a while, pausing simulation');
+        ticker.pause();
+    }
+    #handle_context_lost() {
+        logger.warn('Graphics context lost, waiting for recovery');
+        this.#clear_context_loss_pause_timer();
+        this.#context_loss_pause_timer = setTimeout(
+            () => this.#pause_simulation_for_context_loss(),
+            CONTEXT_LOSS_SIMULATION_PAUSE_DELAY * 1000
+        );
+    }
+    #handle_context_restored() {
+        this.#clear_context_loss_pause_timer();
+        if (this.#paused_by_context_loss) {
+            this.#paused_by_context_loss = false;
+            if (this.ticker.is_active) {
+                this.ticker.resume();
+            }
+        }
+        logger.info('Graphics context restored, rendering resumed');
+    }
+    /**
+     * @param {ShadeDeviceFailure} reason carries a message written to be shown to a person
+     */
+    #handle_context_failed(reason) {
+        logger.error(`Graphics context recovery abandoned (${reason}), no further rendering is possible`);
+        this.#clear_context_loss_pause_timer();
+        // nothing can be drawn any more, so let the simulation stop rather than burn cycles invisibly.
+        // Application state is left intact, which keeps a save-on-failure handler viable.
+        this.#pause_simulation_for_context_loss();
+        this.viewStack.addChild(new WebGLContextFailureView());
+    }
+    #initialize_audio() {
+        const sound = this.sound;
+        if (sound === null) {
+            // no sound engine
+            return;
+        }
+        // hook up context resumption to input
+        if (this.devices.pointer !== undefined) {
+            this.devices.pointer.on.down.addOne(sound.resumeContext, sound);
+            this.devices.keyboard.on.down.addOne(sound.resumeContext, sound);
+        }
+    }
+    initializeViews() {
+        const gameView = new EmptyView();
+        gameView.addClass('game-view');
+        gameView.css({
+            left: 0,
+            top: 0,
+            position: "absolute",
+            pointerEvents: "none"
+        });
+        this.gameView = gameView;
+        this.viewStack.push(gameView, 'game-view');
+        if (this.graphics !== null) {
+            const viewport = this.graphics.viewport;
+            viewport.css({
+                pointerEvents: "auto"
+            });
+            gameView.addChild(viewport);
+            //bind size of renderer viewport to game view
+            viewport.bindSignal(gameView.size.onChanged, viewport.size.set.bind(viewport.size));
+            gameView.on.linked.add(function () {
+                viewport.size.copy(gameView.size);
+            });
+        }
+    }
+    initializeSettings() {
+        logger.info('Initializing engine settings...');
+        const engine = this;
+        function setViewportToWindowSize() {
+            // get parent element
+            let parentElement = engine.viewStack.el.parentElement;
+            while (parentElement !== null && parentElement.innerWidth === undefined) {
+                // traverse up until we find an element with defined dimensions
+                parentElement = parentElement.parentElement;
+            }
+            if (parentElement === null || parentElement === undefined) {
+                // no parent element, default to window
+                parentElement = window;
+            }
+            engine.viewStack.size.set(parentElement.innerWidth, parentElement.innerHeight);
+        }
+        this.settings.graphics_control_viewport_size.process(function (value) {
+            if (value) {
+                setViewportToWindowSize();
+                window.addEventListener("resize", setViewportToWindowSize, false);
+            } else {
+                window.removeEventListener("resize", setViewportToWindowSize);
+            }
+        });
+        logger.info('Engine settings initilized.');
+    }
+    benchmark() {
+        const duration = 2000;
+        let count = 0;
+        const t0 = Date.now();
+        let t1;
+        while (true) {
+            this.entityManager.update(0.0000000001);
+            t1 = Date.now();
+            if (t1 - t0 > duration) {
+                break;
+            }
+            count++;
+        }
+        //normalize
+        const elapsed = (t1 - t0) / 1000;
+        const rate = (count / elapsed);
+        return rate;
+    }
+    /**
+     * Returns preloader object
+     * @param {String} listURL
+     */
+    loadAssetList(listURL) {
+        const preloader = new AssetPreloader();
+        const assetManager = this.assetManager;
+        assetManager.get({
+            path: listURL, type: "json", callback: function (asset) {
+                preloader.addAll(asset.create());
+                preloader.load(assetManager);
+            }
+        });
+        return preloader;
+    }
+    render() {
+        assert.isInstanceOf(this, Engine, 'this', 'Engine');
+        const graphics = this.graphics;
+        if (graphics === null) {
+            // headless
+            return;
+        }
+        if (graphics.autoDraw) {
+            // request redraw
+            graphics.needDraw = true;
+        }
+        if (this.renderingEnabled && graphics.needDraw) {
+            const metrics = this.performance;
+            const t0 = performance.now();
+            graphics.render();
+            const t1 = performance.now();
+            const frame_time = (t1 - t0) / 1000;
+            // record frame time
+            metrics.get(METRIC_ID_RENDER).record(frame_time);
+        }
+    }
+    /**
+     * Startup
+     * @returns {Promise}
+     */
+    async start() {
+        // First, and awaited: systems read `graphics.viewport` and size themselves off it during
+        // their own startup, so the device has to exist before the entity manager runs.
+        if (this.graphics !== null) {
+            await this.graphics.start();
+        }
+        this.assetManager.startup();
+        this.#initialize_audio();
+        const promiseEntityManager = () => {
+            return new Promise((resolve, reject) => {
+                //initialize entity manager
+                this.entityManager.startup(resolve, reject);
+            });
+        }
+        this.__performacne_monitor.start();
+        const sound = this.sound;
+        const soundStarted = sound === null
+            ? Promise.resolve()
+            : sound.start();
+        const knowledge = this.staticKnowledge;
+        // static knowledge is engine-lifetime content and a stop does not drop it, so a restart keeps
+        // what the first start loaded. `load` accepts the Initial state only; callers that want the
+        // tables re-read call `reset` first.
+        const knowledgeLoaded = knowledge.state === StaticKnowledgeState.Initial
+            ? knowledge.load(this.assetManager, this.executor)
+            : Promise.resolve();
+        return Promise.all([
+            soundStarted.then(promiseEntityManager),
+            knowledgeLoaded,
+            this.gui.startup(this),
+            this.plugins.startup()
+        ]).then(async () => {
+            this.#last_frame_timestamp = performance.now();
+            /**
+             * Starting the engine
+             */
+            this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
+            //start simulation
+            this.ticker.start({ maxTimeout: 200 });
+            //self.uiController.init(self);
+            //load options
+            await this.options.attachToStorage('lazykitty.komrade.options', this.storage);
+            logger.info('engine started');
+        }, function (e) {
+            logger.error(`Engine Failed to start: ${e}`);
+            // the caller awaits start() to know whether the engine came up;
+            // swallowing this reported success after a failed startup
+            throw e;
+        });
+    }
+    /**
+     * Fired every animation frame via {@link requestAnimationFrame}
+     */
+    #animation_frame = () => {
+        const t0 = this.#last_frame_timestamp;
+        const t1 = performance.now();
+        this.#animation_frame_handle = requestAnimationFrame(this.#animation_frame);
+        this.render();
+        const frame_delay = (t1 - t0) / 1000;
+        // swap variables
+        this.#last_frame_timestamp = t1;
+        // record metric
+        this.performance.get(METRIC_ID_FRAME).record(frame_delay);
+    }
+    /**
+     * Shutdown the engine, disposing all relevant resources
+     */
+    async stop() {
+        this.__performacne_monitor.stop();
+        // stop the ticker. pause() throws when the loop is not currently
+        // running, which would abort the whole teardown below
+        this.ticker.stop();
+        // and the render loop, which re-requests itself every frame and would
+        // otherwise keep calling render() on a torn-down engine forever
+        cancelAnimationFrame(this.#animation_frame_handle);
+        this.#animation_frame_handle = -1;
+        // shutdown entity manager
+        if (!this.__using_external_entity_manager) {
+            await new Promise((resolve, reject) => this.entityManager.shutdown(resolve, reject));
+        }
+        // shutdown plugins
+        await this.plugins.shutdown();
+        // stop gui
+        await this.gui.shutdown();
+        // TODO shutdown executor
+        await this.assetManager.shutdown();
+        // last, so that everything above still has a live context to release its GPU resources through
+        const graphics = this.graphics;
+        if (graphics !== null) {
+            graphics.stop();
+        }
+    }
+    exit() {
+        window.close();
+    }
+    /**
+     * @returns {Promise}
+     */
+    requestExit() {
+        return this.gui.confirmTextDialog({
+            title: this.localization.getString('system_confirm_exit_to_system.title'),
+            text: this.localization.getString('system_confirm_exit_to_system.text')
+        }).then(() => {
+            this.exit();
+        });
+    }
+}
+/**
+ * @readonly
+ * @type {boolean}
+ */
+Engine.prototype.isEngine = true;
+export default Engine;