Web loader JavaScript API
Exact page Engine methods, configuration and asynchronous-readiness limits.
Web loader JavaScript API
This is the page-side Engine class from the generated loader .js, not Reckfell.Engine in the C# SDK. It controls loader startup, not arbitrary gameplay state. Match the loader, WASM, pack and export config from the same build. Current C# exporter 1.0.0 does not implement Web; API availability in source is not a successful C# browser export.
Static methods
| Method | Contract and limitation |
|---|---|
| Engine.load(basePath,size=0) | Promise for the downloaded engine response. Appends .wasm to an extensionless base path. Uses the shared first-load promise until unload; a second path is not an independent load. size is an optional progress hint, not a validation hash. |
| Engine.unload() | Clears the cached load promise. Does not quit a running instance, undo main or prove all browser/GPU memory freed. |
| Engine.isWebGLAvailable(majorVersion=1) | Browser context capability check. The game path needs WebGL2; passing the default check alone is insufficient. |
| Engine.isFetchAvailable() | Checks availability of the fetch/response stack, not success of a particular URL. |
| Engine.isSecureContext() | Reports the current secure-context capability, not permission for every API. |
| Engine.isCrossOriginIsolated() | Reports isolation state; relevant to threaded exports. |
| Engine.isSharedArrayBufferAvailable() | Checks SharedArrayBuffer availability; does not test the worker pool or startup. |
| Engine.isAudioWorkletAvailable() | Checks the relevant audio capability, not autoplay permission or actual sound. |
| Engine.getMissingFeatures({threads:true}) | Returns missing-feature descriptions. Include the export's actual threads flag; the current default is true. Checks WebGL2, fetch and secure context, adding isolation/SharedArrayBuffer for threads. |
Instance methods
| Method | Contract and limitation |
|---|---|
| new Engine(config) | Creates loader configuration. It does not instantiate WASM, load a pack or create a rendered frame. |
| init(basePath) | Loads/initializes a module and FS when necessary. Needs a base path if no cached load exists. A resolved FS error value is currently ignored; some nested rejections are not forwarded. No save-durability proof. |
| preloadFile(file,path) | Promise for queued data before start. file is a URL or byte buffer/view; specify path for a buffer. The virtual destination is distinct from the download URL. |
| start(overrides) | Applies overrides, initializes if required, copies queued files then calls main(args). Does not automatically load a pack. A canvas must be available. |
| startGame(overrides) | Adds --main-pack, initializes executable and preloads mainPack/default .pck, then starts. Promise resolution is not first-frame/game readiness or service-worker completion. Call once per page startup. |
| copyToFS(path,buffer) | Synchronous copy into an initialized module's virtual FS; throws before init. Not a browser download or persistence receipt. |
| requestQuit() | Forwards a cooperative quit request to a live module. No-op without one; cannot recover a hung/crashed engine. Observe onExit separately. |
| addDebuggerSession(port) | Forwards an editor debugger MessagePort to a live editor runtime; not a general networking channel. |
| installServiceWorker() | Returns registration promise when configured/supported, otherwise resolves without registration. Starting the game does not await it. It is not proof that a waiting worker has activated. |
forceQuit is not exported by the current loader. pid and onTerminatePID from the old imported reference are not parsed config options. Do not call or configure them as supported features.
Public configuration
| Option | Default / meaning |
|---|---|
| executable | Empty string in raw config; exporter sets the extensionless engine base name. |
| mainPack | null; startGame defaults to executable + .pck. |
| canvas | null; fallback is the first canvas found. Pass the actual HTMLCanvasElement explicitly when embedding. |
| canvasResizePolicy | 2: adaptive window size; 0: page-owned sizing; 1: project sizing. |
| focusCanvas | true; startup requests canvas focus. Not browser permission for sound/fullscreen/XR. |
| locale | null; uses browser locale when absent and normalizes its format for the engine. Not DOM i18n. |
| args | Empty array. startGame prepends its own --main-pack pair. Avoid duplicate startup/pack arguments. |
| unloadAfterInit | true; clears the shared downloaded response after init. Not runtime shutdown. |
| experimentalVK | false; experimental virtual keyboard support, not Vulkan. |
| serviceWorker | Empty string; optional registration URL. |
| onProgress(current,total) | null; byte-download callback. total=0 means no reliable total; not scene-loading percentage. |
| onPrint(...values) | Console log by default. Runtime output callback. |
| onPrintError(...values) | Console error by default, not console warn. No universal startup-failure guarantee. |
| onExit(code) | null; notified on orderly exit after loader cleanup. Not guaranteed on crash/hang. |
| debugPort | null; editor/debugger MessagePort. |
| onExecute(path,args) | null; page integration for engine execution requests, used by the web-editor shell. Does not grant OS process execution. |
Advanced fields persistentPaths, reckfellextensionLibs, fileSizes, emscriptenPoolSize and reckfellPoolSize are parsed by current config. Keep export-generated library paths/sizes consistent with the variant. persistentPaths defaults to ['/userfs']; it does not grant host filesystem access. Thread-pool values do not add thread support to a nonthreaded build. The shell's ensureCrossOriginIsolationHeaders metadata is not a promise that an arbitrary host sets the required headers.
Lifecycle limits and verification
The current closure holds shared loadPromise/initPromise and preloader state. Concurrent instances are not accepted by this review: a mock test reproduced both init calls sharing a promise while only one instance received the module. Repeated startGame also prepends arguments again. Use one startup owner and reload before retrying after an abandoned attempt.
See the complete shell example for feature detection, explicit canvas, error messages and a pending-start watchdog. Twenty checks executed actual Engine/config bodies with a mock module/preloader/DOM and the exact shell script. WASM, deployment, real browser rendering/storage, PWA, debugger, crash recovery and C# Web export remain unverified. Engine Source, Runtime and SDK were unchanged.