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.

fix(video): first WeChat PC live run — ship the .esv the runtime can actually read (V3)

esengine1560b6d17ccc
diff --git a/desktop/electron/exportWeChat.ts b/desktop/electron/exportWeChat.ts
index 454287acc..08e123bb2 100644
--- a/desktop/electron/exportWeChat.ts
+++ b/desktop/electron/exportWeChat.ts
@@ -306,10 +306,12 @@ export async function exportWeChat(opts: {
const cook = await cookAssets(opts.root, { entryScenes: scenes.map((s) => s.path), outDir: absOut, contentAddressed: opts.contentAddressed, compressTextures: opts.compressTextures, compressAudio: opts.compressAudio, atlasTextures: opts.atlasTextures, transcodeVideo: true });
warnings.push(...cook.warnings);
- // 1a. Restage for WeChat's code-package suffix whitelist (it has no `ktx2`
- // or `esscene`; the packer drops such files and fs reads are denied
+ // 1a. Restage for WeChat's code-package suffix whitelist (it has no `ktx2`,
+ // `esv` or `esscene`; the packer drops such files and fs reads are denied
// regardless of packOptions):
// *.ktx2 → *.ktx2.bin (whitelisted; isKtx2Path accepts both)
+ // *.esv → *.esv.bin (the wasm video backend strips the
+ // .bin when deriving the .m4a audio sibling)
// assets/…/<x>.esscene → scenes/<name>.json, @uuid: refs stripped to the
// bare uuids the WeChat resolver keys by; the
// manifest entry follows, so scene refs resolve
@@ -321,7 +323,7 @@ export async function exportWeChat(opts: {
try {
const flat = JSON.parse(await readFile(flatManifestPath, 'utf8')) as CookManifest;
for (const e of flat.entries) {
- if (e.path.toLowerCase().endsWith('.ktx2')) {
+ if (/\.(ktx2|esv)$/.test(e.path.toLowerCase())) {
await rename(path.join(absOut, e.path), path.join(absOut, `${e.path}.bin`));
e.path = `${e.path}.bin`;
continue;
diff --git a/desktop/electron/videoCook.ts b/desktop/electron/videoCook.ts
index 9da5fd615..4554f37b0 100644
--- a/desktop/electron/videoCook.ts
+++ b/desktop/electron/videoCook.ts
@@ -10,19 +10,23 @@
* lazily and only when a cook actually ships video.
*/
import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
import { mkdtemp, readFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import path from 'node:path';
/** Resolve the ffmpeg binary: env override first, then the bundled static
* build. Inside a packaged app the binary must run from the unpacked twin of
- * the asar (executables cannot spawn from an archive). Null if unavailable. */
+ * the asar (executables cannot spawn from an archive). Null if unavailable —
+ * including when the resolved path dangles (e.g. ffmpeg-static was bundled,
+ * which rebases its __dirname-derived path onto the bundle dir). */
export async function resolveFfmpeg(): Promise<string | null> {
if (process.env.ESTELLA_FFMPEG) return process.env.ESTELLA_FFMPEG;
try {
const mod = await import('ffmpeg-static');
const p = (mod.default ?? mod) as unknown as string | null;
- return p ? p.replace(`app.asar${path.sep}`, `app.asar.unpacked${path.sep}`) : null;
+ const real = p ? p.replace(`app.asar${path.sep}`, `app.asar.unpacked${path.sep}`) : null;
+ return real && existsSync(real) ? real : null;
} catch {
return null;
}
@@ -113,6 +117,10 @@ export async function transcodeVideoForWasm(
warnings.push(`audio track extract failed: ${lastLine(audioRes.stderr)}`);
}
return { esv, audio, warnings };
+ } catch (err) {
+ // spawn-level failure (ENOENT, EPERM) — report, don't abort the cook loop.
+ warnings.push(`ffmpeg failed to run: ${err instanceof Error ? err.message : String(err)}`);
+ return { esv: null, audio: null, warnings };
} finally {
await rm(tmp, { recursive: true, force: true });
}
diff --git a/desktop/vite.config.ts b/desktop/vite.config.ts
index ec3c5d8b0..d338b4dfb 100644
--- a/desktop/vite.config.ts
+++ b/desktop/vite.config.ts
@@ -87,10 +87,11 @@ export default defineConfig({
// exportGame run it). Keep it external → required from node_modules at
// runtime where its binary resolution works. (Vite 8 = Rolldown, so the
// option is `rolldownOptions`, not `rollupOptions`.)
- // esbuild + the vendored Basis KTX2 encoder both resolve sibling binaries
- // at runtime (native exe / wasm via import.meta.url), so bundling them
- // breaks that — keep them external, loaded from disk by the cook.
- vite: { build: { rolldownOptions: { external: ['esbuild', /[\\/]build-tools[\\/]basis[\\/]/] } } },
+ // esbuild + the vendored Basis KTX2 encoder + ffmpeg-static all resolve
+ // sibling binaries at runtime (native exe / wasm via import.meta.url /
+ // module __dirname), so bundling them breaks that — keep them external,
+ // loaded from disk by the cook.
+ vite: { build: { rolldownOptions: { external: ['esbuild', 'ffmpeg-static', /[\\/]build-tools[\\/]basis[\\/]/] } } },
},
preload: {
input: 'electron/preload.ts',
diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.ts
index 085ec992b..29c52f81c 100644
--- a/sdk/src/runtimeLoader.ts
+++ b/sdk/src/runtimeLoader.ts
@@ -25,6 +25,7 @@ import { SceneManager, type SceneConfig } from './sceneManager';
import { DEFAULT_GRAVITY, DEFAULT_FIXED_TIMESTEP } from './defaults';
import { SpriteAnimation } from './animation/SpriteAnimator';
import { Audio } from './audio/Audio';
+import { VideoPlayer } from './video/VideoAPI';
import { Localization, matchLocale } from './i18n/Localization';
import { LocalizationPlugin } from './i18n/LocalizationPlugin';
import { platformLanguage } from './platform';
@@ -238,6 +239,12 @@ export async function loadRuntimeScene(options: LoadRuntimeSceneOptions): Promis
// SAME resolver the preload keyed the caches with) and persists across scene
// loads. Spine stays a two-phase load+apply below (skipSpine).
const sceneAssets = ensureRuntimeAssets(app, module, source);
+ // Video source refs resolve through the SAME channel as every other asset
+ // (the editor's play realm wires this too) — a cooked build maps the
+ // authored logical ref (clip.mp4 / @uuid) to its staged .esv.
+ if (source.resolveRef && app.hasResource(VideoPlayer)) {
+ app.getResource(VideoPlayer).setRefResolver(source.resolveRef);
+ }
mergeSceneTextureImportSettings(sceneAssets, sceneData, source.resolveRef ?? ((r) => r));
const assetResult = await sceneAssets.preloadSceneAssets(sceneData, undefined, { skipSpine: true });
sceneAssets.resolveSceneAssetPaths(sceneData, assetResult);
diff --git a/sdk/src/video/WasmVideoBackend.ts b/sdk/src/video/WasmVideoBackend.ts
index af936777a..73a920f2b 100644
--- a/sdk/src/video/WasmVideoBackend.ts
+++ b/sdk/src/video/WasmVideoBackend.ts
@@ -61,7 +61,11 @@ const CLOCK_BACK_JUMP = 0.25;
// Bus the audio track routes through (created on demand under master).
const VIDEO_AUDIO_BUS = 'video';
// Video extensions whose cooked `.m4a` audio-track sibling is worth probing.
-const AUDIO_SIBLING_RE = /\.(esv|mpg|mpeg)$/i;
+// `.esv.bin` is the WeChat-export restaging of `.esv` (code-package suffix
+// whitelist); the sibling keeps the cook's `.esv.m4a` name, so derivation
+// strips the `.bin` first.
+const AUDIO_SIBLING_RE = /\.(esv|mpg|mpeg)(\.bin)?$/i;
+const audioSiblingUrl = (url: string): string => `${url.replace(/\.bin$/i, '')}.m4a`;
class WasmVideoStreamHandle implements VideoStreamHandle {
readonly id = nextId_++;
@@ -134,7 +138,7 @@ class WasmVideoStreamHandle implements VideoStreamHandle {
}
this.audioApi_ = deps.audio();
- if (this.audioApi_ && AUDIO_SIBLING_RE.test(url)) this.audioUrl_ = `${url}.m4a`;
+ if (this.audioApi_ && AUDIO_SIBLING_RE.test(url)) this.audioUrl_ = audioSiblingUrl(url);
if (this.playing_) void this.startAudio_(startAt);
} catch (err) {
if (this.disposed_) return;
@@ -163,6 +167,15 @@ class WasmVideoStreamHandle implements VideoStreamHandle {
const url = this.audioUrl_;
if (!api || !url) return;
const gen = ++this.audioGen_;
+ // A silent video has no cooked sibling — check local paths first so the
+ // expected miss stays silent (the audio backend logs a load failure as
+ // an error). Remote URLs can't be probed cheaply; playTrack's null
+ // return covers them.
+ if (!/^https?:\/\//.test(url) && !(await getPlatform().fileExists(url))) {
+ if (gen === this.audioGen_) this.audioUrl_ = null;
+ return;
+ }
+ if (this.disposed_ || gen !== this.audioGen_) return;
const handle = await api.playTrack(url, {
bus: VIDEO_AUDIO_BUS,
volume: this.muted_ ? 0 : this.volume_,
diff --git a/sdk/tests/wasm-video-backend.test.ts b/sdk/tests/wasm-video-backend.test.ts
index b0ba63b9e..77e1a13b0 100644
--- a/sdk/tests/wasm-video-backend.test.ts
+++ b/sdk/tests/wasm-video-backend.test.ts
@@ -356,6 +356,33 @@ describe('WasmVideoBackend audio-track clock', () => {
handle.stop();
});
+ it('derives the sibling through the WeChat .bin restaging (clip.esv.bin → clip.esv.m4a)', async () => {
+ const { mod } = mockVideoModule();
+ const { api, playTrack } = mockAudio();
+ const backend = new WasmVideoBackend({ sideModules: () => hostFor(mod), audio: () => api });
+ const handle = backend.createStream('assets/video/clip.esv.bin', {});
+ await flush();
+ expect(playTrack).toHaveBeenCalledWith('assets/video/clip.esv.m4a', expect.anything());
+ handle.stop();
+ });
+
+ it('a silent video (no sibling file) never reaches the audio backend', async () => {
+ const { mod } = mockVideoModule();
+ const { api, playTrack } = mockAudio();
+ setPlatform({ ...mockPlatform(new ArrayBuffer(64)), fileExists: async () => false });
+ const backend = new WasmVideoBackend({ sideModules: () => hostFor(mod), audio: () => api });
+ const handle = backend.createStream('clip.esv', {});
+ await flush();
+ expect(playTrack).not.toHaveBeenCalled();
+ // engine clock still drives the video
+ nowMs = 16;
+ handle.pump(engineModule);
+ nowMs = 32;
+ handle.pump(engineModule);
+ expect(handle.isPlaying).toBe(true);
+ handle.stop();
+ });
+
it('never probes a sibling for non-esv sources', async () => {
const { mod } = mockVideoModule();
const { api, playTrack } = mockAudio();