JavaScript API веб-загрузчика

Точные методы Engine страницы, настройки и границы асинхронной готовности.

Это класс Engine страницы из generated loader .js, не Reckfell.Engine C# SDK. Он управляет загрузчиком, а не произвольным состоянием игры. Loader, WASM, pack и export config должны соответствовать одной сборке. Текущий C# exporter 1.0.0 не реализует Web; наличие API в исходниках не подтверждает успешный C# browser export.

Статические методы

Метод	Контракт и ограничение
Engine.load(basePath,size=0)	Promise скачанного engine response. Добавляет .wasm к base path без расширения. До unload использует общий promise первой загрузки; второй путь не создаёт независимую загрузку. size — подсказка progress, не проверочный hash.
Engine.unload()	Очищает cached load promise. Не завершает работающий экземпляр, не отменяет main и не доказывает освобождение всей browser/GPU memory.
Engine.isWebGLAvailable(majorVersion=1)	Проверяет browser context capability. Игровому пути нужен WebGL2; одной проверки с default недостаточно.
Engine.isFetchAvailable()	Проверяет доступность fetch/response stack, не успешность конкретного URL.
Engine.isSecureContext()	Сообщает secure-context capability, не разрешение каждого API.
Engine.isCrossOriginIsolated()	Сообщает isolation state; существенно для многопоточного экспорта.
Engine.isSharedArrayBufferAvailable()	Проверяет доступность SharedArrayBuffer, не worker pool или запуск.
Engine.isAudioWorkletAvailable()	Проверяет audio capability, не autoplay permission и не реальный звук.
Engine.getMissingFeatures({threads:true})	Возвращает описания недостающих функций. Передайте реальный threads flag экспорта; текущий default true. Проверяет WebGL2, fetch, secure context; для threads добавляет isolation/SharedArrayBuffer.

Методы экземпляра

Метод	Контракт и ограничение
new Engine(config)	Создаёт loader configuration. Не инстанцирует WASM, не загружает pack и не создаёт кадр.
init(basePath)	При необходимости загружает/инициализирует module и FS. Без cached load нужен base path. Resolved FS error value сейчас игнорируется; некоторые nested rejections не передаются наружу. Сохранность данных не подтверждает.
preloadFile(file,path)	Promise данных, поставленных в очередь до старта. file — URL или byte buffer/view; для buffer задайте path. Виртуальный destination отличается от URL загрузки.
start(overrides)	Применяет overrides, при необходимости инициализирует, копирует queued files и вызывает main(args). Pack автоматически не загружает. Нужен доступный canvas.
startGame(overrides)	Добавляет --main-pack, инициализирует executable, загружает mainPack/default .pck, затем запускает. Promise не означает first-frame/game readiness или завершение service worker. Один вызов на запуск страницы.
copyToFS(path,buffer)	Синхронно копирует в virtual FS инициализированного module; до init бросает ошибку. Не browser download и не квитанция persistence.
requestQuit()	Передаёт cooperative quit request живому module. Без него ничего не делает; не восстанавливает зависший/аварийный движок. Отдельно наблюдайте onExit.
addDebuggerSession(port)	Передаёт debugger MessagePort живому editor runtime; не общий networking channel.
installServiceWorker()	Возвращает registration promise при настройке/поддержке, иначе завершается без регистрации. Запуск игры его не ждёт. Не подтверждает активацию waiting worker.

forceQuit не экспортируется текущим loader. pid и onTerminatePID из старого справочника не разбираются как config options. Не вызывайте/не настраивайте их как поддерживаемые функции.

Публичная конфигурация

Параметр	Default / значение
executable	Пустая строка в raw config; exporter задаёт engine base name без расширения.
mainPack	null; startGame использует executable + .pck по умолчанию.
canvas	null; fallback — первый найденный canvas. При embedding передавайте реальный HTMLCanvasElement явно.
canvasResizePolicy	2: адаптация к окну; 0: размером управляет страница; 1: размер проекта.
focusCanvas	true; старт запрашивает focus canvas. Не browser permission для звука/fullscreen/XR.
locale	null; при отсутствии берёт browser locale и нормализует формат для движка. Не DOM i18n.
args	Пустой массив. startGame добавляет свою пару --main-pack. Избегайте повторного старта/pack arguments.
unloadAfterInit	true; после init очищает общий скачанный response. Не завершение runtime.
experimentalVK	false; experimental virtual keyboard support, не Vulkan.
serviceWorker	Пустая строка; optional registration URL.
onProgress(current,total)	null; callback скачанных байтов. total=0 — достоверный итог неизвестен; не процент загрузки сцены.
onPrint(...values)	По умолчанию console log; вывод runtime.
onPrintError(...values)	По умолчанию console error, не console warn. Не универсальная гарантия доставки startup failure.
onExit(code)	null; уведомление штатного выхода после cleanup загрузчика. Не гарантируется при crash/hang.
debugPort	null; MessagePort редактора/debugger.
onExecute(path,args)	null; интеграция page с execution requests движка, используется web-editor shell. Не разрешает запуск OS processes.

Advanced fields persistentPaths, reckfellextensionLibs, fileSizes, emscriptenPoolSize и reckfellPoolSize разбираются текущим config. Согласуйте generated library paths/sizes с вариантом экспорта. persistentPaths по умолчанию ['/userfs']; это не доступ к host filesystem. Значения thread pool не добавляют threads в немногопоточную сборку. Shell metadata ensureCrossOriginIsolationHeaders не обещает нужные headers от произвольного host.

Ограничения lifecycle и проверка

Текущий closure хранит общие loadPromise/initPromise и preloader state. Concurrent instances не приняты как проверенные: mock-тест воспроизвёл общий promise двух init, при котором module получил лишь один instance. Повторный startGame также снова добавляет arguments. Один startup owner; после брошенной попытки перезагрузите страницу до retry.

См. полный пример shell: feature detection, явный canvas, ошибки и pending-start watchdog. 20 проверок выполнили реальные Engine/config bodies с mock module/preloader/DOM и точный shell script. WASM, deployment, реальный browser rendering/storage, PWA, debugger, crash recovery и C# Web export не проверены. Source, Runtime и SDK не менялись.