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(runtime): a mini-game host that asks to hear the first frame is told

esengine70e7b314859a
diff --git a/sdk/src/runtime/miniGameRuntime.ts b/sdk/src/runtime/miniGameRuntime.ts
index edbb71046..cd7354b81 100644
--- a/sdk/src/runtime/miniGameRuntime.ts
+++ b/sdk/src/runtime/miniGameRuntime.ts
@@ -32,6 +32,8 @@ import type { Physics2DPluginConfig } from '../physics/PhysicsTypes';
import type { SceneData } from '../scene/scene';
import type { AotManifest } from '../ecs/aot/AotSystems';
import { log } from '../util/logger';
+import { Schedule, defineSystem } from '../ecs/system';
+import type { App } from '../app/app';
// =============================================================================
// Emscripten WASM Instantiation
@@ -271,5 +273,21 @@ export async function initMiniGameRuntime(config: MiniGameRuntimeConfig): Promis
progress.reach('ready');
// Before run(), which may hand control to the engine's loop and not return.
progress.finish();
+ reportFirstFrame(app, adapter.host as { launchSuccess?: () => void });
app.run();
}
+
+/**
+ * Tell the host the first screen has rendered, where it asks to be told:
+ * Bilibili reviews a game by it (「需要在游戏首页成功渲染时调用」`bl.launchSuccess`).
+ * At the end of the first frame, once; a host without the call is skipped.
+ */
+export function reportFirstFrame(app: Pick<App, 'addSystemToSchedule'>, host: { launchSuccess?: () => void }): void {
+ if (typeof host.launchSuccess !== 'function') return;
+ let told = false;
+ app.addSystemToSchedule(Schedule.Last, defineSystem([], () => {
+ if (told) return;
+ told = true;
+ try { host.launchSuccess!(); } catch (e) { log.warn('runtime', `launchSuccess threw: ${String(e)}`); }
+ }, { name: 'ReportFirstFrame' }));
+}
diff --git a/sdk/tests/minigame-first-frame.test.ts b/sdk/tests/minigame-first-frame.test.ts
new file mode 100644
index 000000000..50e2315c6
--- /dev/null
+++ b/sdk/tests/minigame-first-frame.test.ts
@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file A host that reviews a game by its first rendered frame hears about it
+ * once, after that frame — Bilibili's `bl.launchSuccess`.
+ */
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { App } from '../src/app/app';
+import { AppContext, setDefaultContext } from '../src/ecs/context';
+import { reportFirstFrame } from '../src/runtime/miniGameRuntime';
+
+beforeEach(() => setDefaultContext(new AppContext()));
+
+describe('reportFirstFrame', () => {
+ it('tells the host after the first frame, and only then', async () => {
+ const app = App.new();
+ const launchSuccess = vi.fn();
+ reportFirstFrame(app, { launchSuccess });
+ expect(launchSuccess).not.toHaveBeenCalled();
+ await app.tick(1 / 60);
+ await app.tick(1 / 60);
+ expect(launchSuccess).toHaveBeenCalledTimes(1);
+ });
+
+ it('adds nothing for a host without the call', () => {
+ const app = { addSystemToSchedule: vi.fn() };
+ reportFirstFrame(app as never, {});
+ expect(app.addSystemToSchedule).not.toHaveBeenCalled();
+ });
+
+ it('does not let a throwing host take the frame down', async () => {
+ const app = App.new();
+ reportFirstFrame(app, { launchSuccess: () => { throw new Error('host broke'); } });
+ await expect(app.tick(1 / 60)).resolves.not.toThrow();
+ });
+});