@woosh/meep-engine 3.14.2 → 3.14.4

package/src/engine/Engine.js

@@ -1,726 +1,733 @@
-/**
- *
- */
-
-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 { GraphicsContextFailureView } from "../view/graphics/GraphicsContextFailureView.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 { GraphicsEngine } from './graphics3/GraphicsEngine.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 {GraphicsEngine|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 {GraphicsEngine}
-             */
-            const graphicsEngine = new GraphicsEngine();
-
-            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 GraphicsContextFailureView());
-    }
-
-    #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;
+/**
+ *
+ */
+
+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 { GraphicsContextFailureView } from "../view/graphics/GraphicsContextFailureView.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 { GraphicsEngine } from './graphics3/GraphicsEngine.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 {GraphicsEngine|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 {GraphicsEngine}
+             */
+            const graphicsEngine = new GraphicsEngine();
+
+            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 GraphicsContextFailureView());
+    }
+
+    #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;
+
+        // the input devices the constructor started. The gamepad one polls on its own animation
+        // frame loop, so left alone it outlives the engine the same way the render loop would;
+        // the other two hold listeners on a view stack that is about to go away
+        this.devices.pointer.stop();
+        this.devices.keyboard.stop();
+        this.devices.gamepad.stop();
+
+        // 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;