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.

11.0 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  A development build's channel opens before its engine does: what it
 *        printed meanwhile reaches the editor, and a question asked meanwhile is
 *        answered once the game starts rather than refused.
 */
import { describe, it, expect, vi } from 'vitest';
import { setPlatform } from '../src/platform/base';
import type { PlatformAdapter, PlatformSocket, PlatformSocketEvents } from '../src/platform/types';
import { startDebugChannel, attachDebugChannel, fitWithin } from '../src/runtime/debugChannel';
import type { App } from '../src/app/app';

function fakeSocket() {
    const handlers: { [K in keyof PlatformSocketEvents]?: Array<(...a: PlatformSocketEvents[K]) => void> } = {};
    const sent: unknown[] = [];
    const socket: PlatformSocket = {
        delivery: 'reliable-ordered',
        readyState: 'connecting',
        on(event, fn) { (handlers[event] ??= [] as never).push(fn as never); return () => {}; },
        connect() {},
        send(data) { sent.push(typeof data === 'string' ? JSON.parse(data) : data); },
        close() {},
    };
    const emit = <K extends keyof PlatformSocketEvents>(event: K, ...args: PlatformSocketEvents[K]): void => {
        for (const fn of handlers[event] ?? []) (fn as (...a: PlatformSocketEvents[K]) => void)(...args);
    };
    return { socket, sent, open: () => { socket.readyState = 'open'; emit('open'); }, receive: (m: unknown) => emit('message', JSON.stringify(m)) };
}

const flush = () => new Promise((r) => setTimeout(r, 0));

describe('the debug channel', () => {
    it('forwards what was printed before the editor listened, then answers a question asked before the game started', async () => {
        const s = fakeSocket();
        setPlatform({
            name: 'web', now: () => performance.now(), createSocket: () => s.socket, deviceName: () => 'Chrome · Android',
        } as unknown as PlatformAdapter);
        startDebugChannel({ url: 'ws://editor:1/?token=t', project: 'Demo' });
        console.log('booting the engine');

        s.open();
        const logged = s.sent.filter((m) => (m as { t: string }).t === 'logs')
            .flatMap((m) => (m as { entries: Array<{ line: string }> }).entries.map((e) => e.line));
        expect(logged).toContain('booting the engine');
        expect(s.sent[0]).toMatchObject({ t: 'hello', title: 'Chrome · Android', project: 'Demo', revision: null });

        s.receive({ t: 'query', reqId: 7, kind: 'control', paused: true });
        await flush();
        expect(s.sent.some((m) => (m as { reqId?: number }).reqId === 7)).toBe(false);

        let paused = false;
        const app = {
            hasResource: () => false,
            onFrameEnd: () => () => {},
            setTargetFrameRate: () => {},
            setPaused: (p: boolean) => { paused = p; },
            isPaused: () => paused,
            getTargetFrameRate: () => 0,
        } as unknown as App;
        attachDebugChannel(app);
        await flush();
        expect(s.sent.find((m) => (m as { reqId?: number }).reqId === 7)).toEqual({ t: 'reply', reqId: 7, data: { paused: true, fps: 0 } });
    });
});

describe('a build whose renderer cannot capture', () => {
    it('says so, rather than answering with nothing', async () => {
        vi.resetModules();
        const base = await import('../src/platform/base');
        const channel = await import('../src/runtime/debugChannel');
        const s = fakeSocket();
        base.setPlatform({ name: 'native', now: () => performance.now(), createSocket: () => s.socket } as unknown as PlatformAdapter);
        channel.startDebugChannel({ url: 'ws://editor:1/?token=t', project: 'Demo' });
        s.open();
        channel.attachDebugChannel({ hasResource: () => false, onFrameEnd: () => () => {}, wasmModule: null } as unknown as App);
        s.receive({ t: 'query', reqId: 12, kind: 'frameCapture' });
        await flush();
        expect(s.sent.find((m) => (m as { reqId?: number }).reqId === 12)).toMatchObject({ error: expect.stringMatching(/no frame capture/) });
    });
});

describe('a device asked about its content', () => {
    it('answers with the revision it runs and what update is staged', async () => {
        vi.resetModules();
        const base = await import('../src/platform/base');
        const channel = await import('../src/runtime/debugChannel');
        const { Assets } = await import('../src/asset/AssetPlugin');
        const s = fakeSocket();
        base.setPlatform({ name: 'web', now: () => performance.now(), createSocket: () => s.socket } as unknown as PlatformAdapter);
        channel.startDebugChannel({ url: 'ws://editor:1/?token=t', project: 'Demo' });
        s.open();
        const status = { revision: 'bfdfdde', persistedRevision: null, staged: { revision: '2c4bd22', assets: 1, bytes: 208 }, applying: false };
        channel.attachDebugChannel({
            hasResource: (r: unknown) => r === Assets,
            getResource: () => ({ updateStatus: () => status, getManifest: () => null }),
            onFrameEnd: () => () => {},
        } as unknown as App);
        s.receive({ t: 'query', reqId: 11, kind: 'updateStatus' });
        await flush();
        expect(s.sent.find((m) => (m as { reqId?: number }).reqId === 11)).toEqual({ t: 'reply', reqId: 11, data: status });
    });
});

describe('a device asked about its disk cache', () => {
    it('routes scans, previews, explicit cleanup and version retention through its Assets service', async () => {
        vi.resetModules();
        const base = await import('../src/platform/base');
        const channel = await import('../src/runtime/debugChannel');
        const { Assets } = await import('../src/asset/AssetPlugin');
        const s = fakeSocket();
        base.setPlatform({ name: 'wechat', now: () => performance.now(), createSocket: () => s.socket } as unknown as PlatformAdapter);
        channel.startDebugChannel({ url: 'ws://editor:1/?token=t', project: 'Demo' });
        s.open();
        const disk = vi.fn(async () => ({ capability: 'managed', usedBytes: 16 }));
        const clean = vi.fn(async () => ({ releaseBytes: 8 }));
        const retain = vi.fn(async () => ({ capability: 'managed', usedBytes: 16 }));
        channel.attachDebugChannel({ hasResource: (r: unknown) => r === Assets,
            getResource: () => ({ getManifest: () => null, diskCacheReport: disk, cleanDiskCache: clean, retainDiskCacheVersion: retain }),
            onFrameEnd: () => () => {},
        } as unknown as App);
        s.receive({ t: 'query', reqId: 31, kind: 'diskCache', rescan: true });
        s.receive({ t: 'query', reqId: 32, kind: 'cleanDiskCache', budgetBytes: 8 });
        s.receive({ t: 'query', reqId: 33, kind: 'cleanDiskCache', budgetBytes: 8, execute: true });
        s.receive({ t: 'query', reqId: 34, kind: 'retainDiskCacheVersion', revision: 'v1', retain: false });
        await flush();
        expect(disk).toHaveBeenCalledWith(true);
        expect(clean.mock.calls).toEqual([[8, false], [8, true]]);
        expect(retain).toHaveBeenCalledWith('v1', false);
        expect(s.sent.find((m) => (m as { reqId?: number }).reqId === 33)).toEqual({ t: 'reply', reqId: 33, data: { releaseBytes: 8 } });
    });
});

describe('what the channel costs a device', () => {
    it('comes with the step of the device clock, so a 0 below it reads as unmeasured', async () => {
        vi.resetModules();
        const base = await import('../src/platform/base');
        const channel = await import('../src/runtime/debugChannel');
        const s = fakeSocket();
        // A browser that is not cross-origin isolated: performance.now() steps by 0.1 ms.
        const coarse = () => Math.floor(performance.now() * 10) / 10;
        base.setPlatform({ name: 'web', now: coarse, createSocket: () => s.socket } as unknown as PlatformAdapter);
        channel.startDebugChannel({ url: 'ws://editor:1/?token=t', project: 'Demo' });
        s.open();
        channel.attachDebugChannel({
            hasResource: () => false,
            enableStats: () => {},
            onFrameEnd: () => () => {},
            getPhaseTimings: () => [],
            getFrameCosts: () => null,
            getFrameTiming: () => null,
            wasmModule: null,
            world: { getAllEntities: () => [], getEntitiesWithComponents: () => [] },
        } as unknown as App);
        s.receive({ t: 'query', reqId: 21, kind: 'stats' });
        await flush();
        const reply = s.sent.find((m) => (m as { reqId?: number }).reqId === 21) as { data: { clockMs: number } };
        expect(reply.data.clockMs).toBeCloseTo(0.1, 5);
    });
});

describe('a device in the background', () => {
    it('refuses a capture at once instead of waiting for a frame it will not draw', async () => {
        // The channel is one per process; this device needs its own.
        vi.resetModules();
        const base = await import('../src/platform/base');
        const channel = await import('../src/runtime/debugChannel');
        const { Lifecycle } = await import('../src/ecs/lifecycle');
        const s = fakeSocket();
        base.setPlatform({ name: 'web', now: () => performance.now(), createSocket: () => s.socket } as unknown as PlatformAdapter);
        channel.startDebugChannel({ url: 'ws://editor:1/?token=t', project: 'Demo' });
        s.open();
        channel.attachDebugChannel({
            hasResource: (r: unknown) => r === Lifecycle,
            getResource: () => ({ visible: false }),
            onFrameEnd: () => () => {},
        } as unknown as App);
        s.receive({ t: 'query', reqId: 9, kind: 'frameCapture' });
        await flush();
        expect(s.sent.find((m) => (m as { reqId?: number }).reqId === 9)).toMatchObject({ error: expect.stringMatching(/background/) });
    });
});

describe('a replay sent from a device', () => {
    // A mini-game socket moved a 2340x1080 replay in 55 s; the editor asks for what it shows.
    const image = (w: number, h: number) => {
        const pixels = new Uint8ClampedArray(w * h * 4);
        for (let i = 0; i < w * h; i++) pixels.set([i % 256, (i >> 8) % 256, 7, 255], i * 4);
        return { width: w, height: h, pixels, matchesCapture: true };
    };

    it('is scaled so its longer side fits, and says how big the whole one is', () => {
        const out = fitWithin(image(2340, 1080), 800);
        expect([out.width, out.height, out.fullWidth, out.fullHeight]).toEqual([800, 369, 2340, 1080]);
        expect(out.pixels.byteLength).toBe(800 * 369 * 4);
        // Nearest sampling: output column x reads source column floor(x / scale).
        const col = Math.floor(799 / (800 / 2340));
        const src = Array.from(image(2340, 1080).pixels.subarray(col * 4, (col + 1) * 4));
        expect(Array.from(out.pixels.subarray((800 - 1) * 4, 800 * 4))).toEqual(src);
    });

    it('is sent as it is when it already fits, or when no limit is asked', () => {
        const small = image(640, 360);
        expect(fitWithin(small, 800).pixels).toBe(small.pixels);
        expect(fitWithin(image(2340, 1080)).width).toBe(2340);
    });
});