Skip to content

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.

feat(editor): Play loads a project's own native modules

yhh3a8973fc0667
diff --git a/desktop/electron/buildPlayRealm.ts b/desktop/electron/buildPlayRealm.ts
index 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/promi
import { 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.ts
index 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.ts
index 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's
diff --git a/desktop/src/playHost.ts b/desktop/src/playHost.ts
index 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.ts
new file mode 100644
index 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([]);
+ });
+});