A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(editor): Play loads a project's own native modules
yhh3a8973fc0667
diff --git a/desktop/electron/buildPlayRealm.ts b/desktop/electron/buildPlayRealm.tsindex f22b05b8d..f013d4d95 100644--- a/desktop/electron/buildPlayRealm.ts+++ b/desktop/electron/buildPlayRealm.ts@@ -25,6 +25,7 @@ import { cp, mkdir, rm, writeFile, readFile, stat, readdir } from 'node:fs/promiimport { existsSync } from 'node:fs';import { createHash } from 'node:crypto';import path from 'node:path';+import { loadProjectModules, sideModuleDeclarations, stageProjectModules } from './projectModules';const PLAY_DIR = '.esengine/play';@@ -81,6 +82,18 @@ export interface PlayRealmResult {/** Project-relative path to the host page → `estella://project/<hostPath>`. */hostPath: string;errors: string[];+ /** Non-fatal: a project module with no web build, say. Play still runs. */+ warnings: string[];+ /**+ * The project's own native modules, staged into the realm's `wasm/` and ready+ * to be declared to it — the same shape `game.config.json` carries in an+ * export, because it is the same fact told to a different realm.+ *+ * Play has to load these or the loop is broken: a developer would have to+ * package the game to find out whether their module works, which is exactly+ * the feedback delay the editor exists to remove.+ */+ sideModules: Array<{ id: string; file: string; globalName?: string }>;}/** Signature over a dir's top-level entries (name+size+mtime) — catches an@@ -128,6 +141,8 @@ export async function buildPlayRealm(opts: {ok: false,hostPath: '',errors: [`play host bundle not found: ${opts.playHostArtifact} (built by vite build — see realm-hosts in vite.config.ts)`],+ warnings: [],+ sideModules: [],};}const hostStamp = path.join(out, '.host-stamp');@@ -144,6 +159,15 @@ export async function buildPlayRealm(opts: {// 2. SDK + wasm copies (gated on a full dir signature, so an added file re-syncs).await syncDir(opts.sdkDistDir, path.join(out, 'sdk'), path.join(out, '.sdk-stamp'));await syncDir(opts.wasmDir, path.join(out, 'wasm'), path.join(out, '.wasm-stamp'));+ // …and the project's own modules on top. AFTER the sync, which deletes its+ // destination before copying — and unconditionally, because it is a handful of+ // files and re-staging them is how an edited module reaches the next Play.+ // The realm is a web one (fetch transport), so it takes the `web` build.+ const projectModules = await loadProjectModules(opts.root, 'web');+ // Not an error: a module with no web build leaves Play without it, and the+ // rest of the game still runs. It is said out loud instead — the alternative+ // is a plugin that quietly does nothing.+ const warnings = await stageProjectModules(projectModules, path.join(out, 'wasm'), 'web');// 3. Host page (rewrite only on change — keeps mtimes stable).const htmlPath = path.join(out, 'play.html');@@ -151,5 +175,11 @@ export async function buildPlayRealm(opts: {await writeFile(htmlPath, PLAY_HTML);}- return { ok: errors.length === 0, hostPath: `${PLAY_DIR}/play.html`, errors };+ return {+ ok: errors.length === 0,+ hostPath: `${PLAY_DIR}/play.html`,+ errors,+ warnings,+ sideModules: sideModuleDeclarations(projectModules, 'web'),+ };}diff --git a/desktop/src/engine/PlayRealm.ts b/desktop/src/engine/PlayRealm.tsindex aa813024c..edd428bf0 100644--- a/desktop/src/engine/PlayRealm.ts+++ b/desktop/src/engine/PlayRealm.ts@@ -61,6 +61,11 @@ export class PlayRealmInstance {private iframe: HTMLIFrameElement | null = null;private payload: PlayPayload | null = null;private netPorts: MessagePort[] | null = null;+ // The project's own native modules, learned when the realm was staged. Held+ // across a warm re-Play because staging is what discovers them: a module added+ // while a realm is warm reaches the game on the next COLD Play, the same rule+ // every other file in the realm's wasm/ follows.+ private sideModules: PlayPayload['sideModules'];private epoch = 0;// The realm's wasm + GL are alive in the (persistent) iframe from a prior Play,// so a re-Play hands over the new scene instead of cold-booting a fresh iframe@@ -173,6 +178,10 @@ export class PlayRealmInstance {this.set({ error: realm.errors[0] ?? t('proj.playPrepareFailed') });return;}+ this.sideModules = realm.sideModules?.length ? realm.sideModules : undefined;+ // A module that could not be staged does not stop Play — but silence here+ // is a plugin that mysteriously does nothing, so it reaches the log.+ for (const w of realm.warnings ?? []) console.warn('[play]', w);frame.src = `estella://project/${realm.hostPath}?n=${++this.epoch}`;} catch (err) {this.set({ error: err instanceof Error ? err.message : String(err) });@@ -184,7 +193,12 @@ export class PlayRealmInstance {private postInit(): void {if (!this.payload) return;const ports = this.netPorts ?? undefined;- this.post({ type: 'estella:play:init', ...this.payload, netPorts: ports }, ports);+ this.post({+ type: 'estella:play:init',+ ...this.payload,+ ...(this.sideModules ? { sideModules: this.sideModules } : {}),+ netPorts: ports,+ }, ports);}/** Stop the game. Single-player keeps the engine WARM (hide + pause, no reboot)@@ -241,6 +255,10 @@ export class PlayRealmInstance {if (this.id !== 0 || this.warm || this.store.getState().playing) return;const realm = await window.estella.project.preparePlayRealm().catch(() => null);if (!realm?.ok || this.warm || this.store.getState().playing) return;+ // Prewarm stages the realm too, so it is where the project's modules are+ // first learned — and on the path that follows, `start()` finds the realm+ // already warm and returns before it would have asked.+ this.sideModules = realm.sideModules?.length ? realm.sideModules : undefined;const frame = this.ensureIframe();// Must be in the DOM to load; the viewport attaches it as the persistent play// host. Not attached yet ⇒ skip — a later prewarm tick warms it.diff --git a/desktop/src/engine/playProtocol.ts b/desktop/src/engine/playProtocol.tsindex a9e7e2541..01dca47c3 100644--- a/desktop/src/engine/playProtocol.ts+++ b/desktop/src/engine/playProtocol.ts@@ -81,6 +81,15 @@ export interface PlayPayload {screenFit?: { designWidth: number; designHeight: number; scaleMode: number; matchWidthOrHeight: number };/** Multiplayer preview role; absent = a plain single-player session. */net?: PlayNetConfig;+ /**+ * The project's own native modules (`.esengine/modules/<id>/`), staged into+ * the realm by `buildPlayRealm` and declared here so `acquire(id)` resolves —+ * the Play-side twin of what `game.config.json` carries in a shipped build.+ *+ * Without it a developer could only find out whether their module works by+ * packaging the game, which is the feedback delay the editor exists to remove.+ */+ sideModules?: Array<{ id: string; file: string; globalName?: string }>;}/** A live inspect snapshot: a shallow entity tree (Outliner) + the selected entity'sdiff --git a/desktop/src/playHost.ts b/desktop/src/playHost.tsindex 8884c6574..3c6563ec2 100644--- a/desktop/src/playHost.ts+++ b/desktop/src/playHost.ts@@ -14,7 +14,7 @@* Everything is same-origin estella:// (host, sdk, bundle, wasm, assets),* sidestepping the custom-scheme cross-fetch ban.*/-import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport, Assets, Ads, createMockAdProvider, Leaderboard, createLocalLeaderboard } from 'esengine';+import { createWebApp, setEditorMode, setPlayMode, initPlayRealmRuntime, getComponent, clearUserComponents, getUserComponentFingerprint, probeRegistrations, Net, MessagePortTransport, Assets, Ads, createMockAdProvider, Leaderboard, createLocalLeaderboard, registerPackagedSideModules } from 'esengine';import type { App, ESEngineModule, SceneData } from 'esengine';import { PLAY_PROTOCOL_VERSION } from './engine/playProtocol';import type { PlayOutbound, PlayInbound } from './engine/playProtocol';@@ -365,6 +365,11 @@ async function warm(): Promise<void> {async function boot(msg: InitMessage): Promise<void> {lastInit = msg;+ // The project's own native modules, staged into this realm's wasm/ alongside+ // the engine's. Registered before the App exists so a plugin acquiring during+ // build finds them — the Play-side equivalent of what the packaged game host+ // does with game.config.json.+ registerPackagedSideModules({ sideModules: msg.sideModules });// Warm re-Play: wasm + GL are already alive from a prior Play, so rebuild the// World on them — no second instantiate, no bundle re-parse. (A multiplayer// realm can't hot-rebuild — its net ports were consumed — so it cold-boots.)diff --git a/desktop/tests/play-realm-modules.test.ts b/desktop/tests/play-realm-modules.test.tsnew file mode 100644index 000000000..a8a90f3c0--- /dev/null+++ b/desktop/tests/play-realm-modules.test.ts@@ -0,0 +1,105 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The play realm carries a project's own native modules.+ *+ * Without this a developer can only find out whether their module works by+ * packaging the game — the feedback delay the editor exists to remove. The+ * realm is staged from the same `.esengine/modules/` the export reads, so what+ * Play loads and what ships are the same files.+ *+ * The ordering here is load-bearing and was wrong once: `syncDir` DELETES its+ * destination before copying, so project modules have to be staged after it,+ * and unconditionally — a stamp-skipped sync must not leave the previous run's+ * modules as the only copy.+ */+import { describe, it, expect, beforeEach, afterEach } from 'vitest';+import { mkdtemp, rm, writeFile, mkdir, readdir } from 'node:fs/promises';+import { tmpdir } from 'node:os';+import path from 'node:path';+import { buildPlayRealm } from '../electron/buildPlayRealm';++let root: string;+let stage: string;++/** The three inputs buildPlayRealm copies from. */+async function fixture(): Promise<{ playHostArtifact: string; sdkDistDir: string; wasmDir: string }> {+ const hostFile = path.join(stage, 'playHost.js');+ await writeFile(hostFile, '// play host bundle');+ const sdkDistDir = path.join(stage, 'sdk');+ await mkdir(sdkDistDir, { recursive: true });+ await writeFile(path.join(sdkDistDir, 'index.js'), '// sdk');+ const wasmDir = path.join(stage, 'wasm');+ await mkdir(wasmDir, { recursive: true });+ await writeFile(path.join(wasmDir, 'esengine.js'), '// engine glue');+ await writeFile(path.join(wasmDir, 'esengine.wasm'), 'enginebytes');+ return { playHostArtifact: hostFile, sdkDistDir, wasmDir };+}++async function writeModule(id: string, platformDir: string): Promise<void> {+ const dir = path.join(root, '.esengine', 'modules', id, platformDir);+ await mkdir(dir, { recursive: true });+ await writeFile(path.join(root, '.esengine', 'modules', id, 'module.json'),+ JSON.stringify({ file: id, globalName: `${id}Module` }));+ await writeFile(path.join(dir, `${id}.js`), `var ${id}Module = () => Promise.resolve({});`);+ await writeFile(path.join(dir, `${id}.wasm`), 'modulebytes');+}++beforeEach(async () => {+ root = await mkdtemp(path.join(tmpdir(), 'es-play-'));+ stage = await mkdtemp(path.join(tmpdir(), 'es-play-src-'));+});+afterEach(async () => {+ await rm(root, { recursive: true, force: true });+ await rm(stage, { recursive: true, force: true });+});++describe('buildPlayRealm — project modules', () => {+ it('stages them beside the engine runtime and declares them to the realm', async () => {+ await writeModule('rive', 'web');+ const res = await buildPlayRealm({ root, ...await fixture() });+ expect(res.ok).toBe(true);+ const staged = (await readdir(path.join(root, '.esengine', 'play', 'wasm'))).sort();+ expect(staged).toEqual(['esengine.js', 'esengine.wasm', 'rive.js', 'rive.wasm']);+ expect(res.sideModules).toEqual([{ id: 'rive', file: 'rive', globalName: 'riveModule' }]);+ });++ it('survives the wasm sync that deletes its own destination', async () => {+ await writeModule('rive', 'web');+ const inputs = await fixture();+ await buildPlayRealm({ root, ...inputs });+ // Second build with the engine runtime CHANGED, so syncDir re-copies (and+ // therefore wipes wasm/ first). The project module must still be there.+ await writeFile(path.join(inputs.wasmDir, 'esengine.wasm'), 'enginebytes-v2');+ const res = await buildPlayRealm({ root, ...inputs });+ expect(res.ok).toBe(true);+ expect(await readdir(path.join(root, '.esengine', 'play', 'wasm')))+ .toContain('rive.js');+ });++ it('re-stages an edited module even when the engine runtime did not change', async () => {+ await writeModule('rive', 'web');+ const inputs = await fixture();+ await buildPlayRealm({ root, ...inputs });+ await writeFile(path.join(root, '.esengine', 'modules', 'rive', 'web', 'rive.js'), '// rebuilt');+ await buildPlayRealm({ root, ...inputs });+ const { readFile } = await import('node:fs/promises');+ expect(await readFile(path.join(root, '.esengine', 'play', 'wasm', 'rive.js'), 'utf8'))+ .toBe('// rebuilt');+ });++ it('does not stop Play over a module with no web build, but says so', async () => {+ await writeModule('rive', 'wechat'); // mini-game build only+ const res = await buildPlayRealm({ root, ...await fixture() });+ expect(res.ok).toBe(true);+ expect(res.sideModules).toEqual([]);+ expect(res.warnings.join('\n')).toContain('"rive"');+ });++ it('says nothing at all for a project that declares no modules', async () => {+ const res = await buildPlayRealm({ root, ...await fixture() });+ expect(res.ok).toBe(true);+ expect(res.sideModules).toEqual([]);+ expect(res.warnings).toEqual([]);+ });+});