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.

15.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
//
// The native PlatformAdapter driven headlessly by a mock NativeBridge — proves the
// host-bridge contract holds (fs / fetch / wasm / image-pixels / storage / input /
// identity) with no device, plus fills the platform-layer test gap that the
// DOM-free surface refactor uncovered (mini-game family identity + defaults,
// mini-game canvas/image with the `as unknown` casts removed, node canvas/image
// fail loud).
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
import {
    NativePlatformAdapter,
    installNativePlatform,
    type NativeBridge,
    type NativeInputListener,
} from '../src/platform/native';
import { getPlatformType, isNative, platformLanguage } from '../src/platform';
import type { InputEventCallbacks } from '../src/platform/types';
import { InputState, inputEventCallbacks } from '../src/input/input';

function makeBridge() {
    const store = new Map<string, string>();
    const cacheStore = new Map<string, ArrayBuffer>();
    const files = new Map<string, ArrayBuffer>([
        ['data/config.json', new TextEncoder().encode('{"a":1}').buffer as ArrayBuffer],
    ]);
    const listeners: NativeInputListener[] = [];
    const bridge: NativeBridge = {
        readFile: async (p) => {
            const b = files.get(p);
            if (!b) throw new Error('ENOENT ' + p);
            return b;
        },
        fileExists: async (p) => files.has(p),
        fetch: async () => ({ ok: true, status: 200, statusText: 'OK', text: '{"ok":true}' }),
        loadImagePixels: async () => ({ width: 2, height: 2, pixels: new Uint8Array(16).fill(255) }),
        getStorageItem: (k) => store.get(k) ?? null,
        setStorageItem: (k, v) => { store.set(k, v); },
        removeStorageItem: (k) => { store.delete(k); },
        storageKeys: () => [...store.keys()],
        readCacheFile: async (k) => cacheStore.get(k) ?? null,
        writeCacheFile: async (k, b) => { cacheStore.set(k, b); },
        registerInput: (l) => {
            listeners.push(l);
            return () => {
                const i = listeners.indexOf(l);
                if (i >= 0) listeners.splice(i, 1);
            };
        },
        devicePixelRatio: () => 3,
        now: () => 12345,
        language: () => 'zh_CN',
    };
    return { bridge, store, cacheStore, files, listeners };
}

function makeInputCallbacks(): InputEventCallbacks {
    return {
        onKeyDown: vi.fn(),
        onKeyUp: vi.fn(),
        onPointerMove: vi.fn(),
        onPointerDown: vi.fn(),
        onPointerUp: vi.fn(),
        onWheel: vi.fn(),
        onTouchStart: vi.fn(),
        onTouchMove: vi.fn(),
        onTouchEnd: vi.fn(),
        onTouchCancel: vi.fn(),
    };
}

describe('NativePlatformAdapter (mock bridge)', () => {
    let env: ReturnType<typeof makeBridge>;
    let adapter: NativePlatformAdapter;

    beforeEach(() => {
        env = makeBridge();
        adapter = installNativePlatform(env.bridge);
    });

    it('installs as a first-class native platform identity', () => {
        expect(adapter.name).toBe('native');
        expect(getPlatformType()).toBe('native');
        expect(isNative()).toBe(true);
    });

    it('reads packaged files as bytes and text', async () => {
        expect(await adapter.fileExists('data/config.json')).toBe(true);
        expect(await adapter.fileExists('nope')).toBe(false);
        expect(new TextDecoder().decode(await adapter.readFile('data/config.json'))).toBe('{"a":1}');
        expect(await adapter.readTextFile('data/config.json')).toBe('{"a":1}');
        await expect(adapter.readFile('nope')).rejects.toThrow();
    });

    it('wraps the bridge fetch into a PlatformResponse', async () => {
        const res = await adapter.fetch('https://cdn/x.json');
        expect(res.ok).toBe(true);
        expect(res.status).toBe(200);
        expect(await res.text()).toBe('{"ok":true}');
        expect(await res.json()).toEqual({ ok: true });
    });

    it('decodes image pixels through the bridge (Path 2)', async () => {
        const img = await adapter.loadImagePixels('art/hero.png');
        expect(img.width).toBe(2);
        expect(img.height).toBe(2);
        expect(img.pixels.length).toBe(16);
        expect(img.pixels[0]).toBe(255);
    });

    it('instantiates wasm via the host JS engine WebAssembly (no bridge call)', async () => {
        // Minimal valid module: magic + version header.
        const bytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]).buffer;
        const result = await adapter.instantiateWasm(bytes, {});
        expect(result.instance).toBeDefined();
        expect(result.module).toBeDefined();
    });

    it('round-trips storage and clears by prefix', () => {
        adapter.setStorageItem('esengine:a', '1');
        adapter.setStorageItem('esengine:b', '2');
        adapter.setStorageItem('other:c', '3');
        expect(adapter.getStorageItem('esengine:a')).toBe('1');
        adapter.removeStorageItem('esengine:a');
        expect(adapter.getStorageItem('esengine:a')).toBeNull();

        adapter.clearStorage('esengine:');
        expect(adapter.getStorageItem('esengine:b')).toBeNull();
        expect(adapter.getStorageItem('other:c')).toBe('3'); // untouched
    });

    it('reports clock, DPR and normalized language', () => {
        expect(adapter.now()).toBe(12345);
        expect(adapter.devicePixelRatio()).toBe(3);
        // base.platformLanguage() normalizes the bridge's underscore tag.
        expect(platformLanguage()).toBe('zh-CN');
    });

    it('without a host clock, times sub-millisecond spans instead of reading them as 0', () => {
        const { now: _, ...clockless } = env.bridge;
        const bare = installNativePlatform(clockless);
        vi.spyOn(performance, 'now').mockReturnValueOnce(100.25).mockReturnValueOnce(100.5);
        expect(bare.now() - bare.now()).toBe(-0.25);
    });

    it('dispatches pushed native input, synthesizing the primary pointer', () => {
        const cb = makeInputCallbacks();
        adapter.bindInputEvents(cb);
        expect(env.listeners.length).toBe(1);
        const sink = env.listeners[0];

        sink.onTouchStart(1, 10, 20);
        expect(cb.onTouchStart).toHaveBeenCalledWith(1, 10, 20);
        expect(cb.onPointerDown).toHaveBeenCalledWith(0, 10, 20);

        sink.onTouchMove(1, 30, 40);
        expect(cb.onPointerMove).toHaveBeenCalledWith(30, 40);

        sink.onTouchEnd(1);
        expect(cb.onPointerUp).toHaveBeenCalledWith(0);

        sink.onKeyDown?.('KeyA');
        expect(cb.onKeyDown).toHaveBeenCalledWith('KeyA');

        adapter.unbindInputEvents();
        expect(env.listeners.length).toBe(0);
    });
    it('hiding the native host cancels input and resets the primary finger', () => {
        let hide = () => {};
        const offHide = vi.fn();
        env.bridge.onHide = callback => { hide = callback; return offHide; };
        const input = new InputState(); adapter.bindInputEvents(inputEventCallbacks(input));
        const sink = env.listeners[0];
        sink.onKeyDown('KeyA'); sink.onPointerDown(2, 0, 0); sink.onTouchStart(1, 10, 20);
        hide();
        expect(input.keysDown.size).toBe(0); expect(input.touches.size).toBe(0);
        expect(input.mouseButtons.size).toBe(0);
        input.beginFixedStep(); expect(input.isMouseButtonPressed(0)).toBe(false); input.endFixedStep();
        sink.onTouchStart(2, 30, 40); sink.onTouchEnd(1);
        expect(input.isMouseButtonDown(0)).toBe(true);
        expect(input.getMousePosition()).toEqual({ x: 30, y: 40 });
        adapter.unbindInputEvents();
        expect(input.touches.size).toBe(0); expect(input.mouseButtons.size).toBe(0);
        expect(offHide).toHaveBeenCalledOnce();
    });
    it('rebinding native input clears the previous input state', () => {
        const first = new InputState(); adapter.bindInputEvents(inputEventCallbacks(first));
        env.listeners[0].onKeyDown('KeyA'); env.listeners[0].onTouchStart(1, 10, 20);
        const next = new InputState(); adapter.bindInputEvents(inputEventCallbacks(next));
        expect(first.keysDown.size).toBe(0); expect(first.touches.size).toBe(0);
        expect(first.isMouseButtonDown(0)).toBe(false);
        env.listeners[0].onTouchStart(2, 30, 40);
        expect(next.isMouseButtonDown(0)).toBe(true); adapter.unbindInputEvents();
    });

    it('fails loud on the offscreen DOM surfaces (native uses loadImagePixels)', () => {
        expect(() => adapter.createCanvas(1, 1)).toThrow(/native/);
        expect(() => adapter.createImage()).toThrow(/native/);
    });

    it('round-trips the offline content cache through the bridge', async () => {
        expect(await adapter.readCacheFile('https://cdn/a.png')).toBeNull();
        await adapter.writeCacheFile('https://cdn/a.png', new Uint8Array([1, 2, 3]).buffer);
        const got = await adapter.readCacheFile('https://cdn/a.png');
        expect(new Uint8Array(got!)).toEqual(new Uint8Array([1, 2, 3]));
    });

    it('degrades to no-cache when the bridge omits cache methods', async () => {
        const bare = makeBridge().bridge as Partial<NativeBridge>;
        delete bare.readCacheFile;
        delete bare.writeCacheFile;
        const a = new NativePlatformAdapter(bare as NativeBridge);
        expect(await a.readCacheFile('x')).toBeNull();
        await expect(a.writeCacheFile('x', new ArrayBuffer(1))).resolves.toBeUndefined();
    });
});

describe('mini-game family identity', () => {
    // The point of the family: a vendor the SDK has never heard of gets every
    // mini-game code path without being enumerated anywhere in the engine.
    it('an unknown vendor is a mini-game, and is not WeChat', async () => {
        const { MiniGamePlatformAdapter } = await import('../src/platform/minigame/adapter');
        const { setPlatform, isMiniGame, isWeChat, isWeb, getPlatformType } = await import('../src/platform');
        const profile = { id: 'myvendor', hostLabel: 'MyVendor', global: {} };
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        setPlatform(new MiniGamePlatformAdapter(profile as any));

        expect(isMiniGame()).toBe(true);
        expect(isWeChat()).toBe(false);
        expect(isWeb()).toBe(false);
        expect(getPlatformType()).toBe('myvendor');
    });

    it('WeChat answers the family check too', async () => {
        const { MiniGamePlatformAdapter } = await import('../src/platform/minigame/adapter');
        const { setPlatform, isMiniGame, isWeChat } = await import('../src/platform');
        const profile = { id: 'wechat', hostLabel: 'WeChat', global: {} };
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        setPlatform(new MiniGamePlatformAdapter(profile as any));

        expect(isMiniGame()).toBe(true);
        expect(isWeChat()).toBe(true);
    });
});

describe('mini-game family defaults', () => {
    // A profile that overrides nothing still gets audio, sockets and video —
    // they come off the normalized global, so they are not per-vendor work.
    it('a profile with no overrides still has audio, socket and video backends', async () => {
        const { MiniGamePlatformAdapter } = await import('../src/platform/minigame/adapter');
        const { MiniGameAudioBackend } = await import('../src/audio/MiniGameAudioBackend');
        const { MiniGameSocket } = await import('../src/net/MiniGameSocket');
        const g = {
            createInnerAudioContext: () => ({}),
            connectSocket: () => ({}),
        };
        const profile = { id: 'myvendor', hostLabel: 'MyVendor', global: g };
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        const a = new MiniGamePlatformAdapter(profile as any);

        expect(a.createAudioBackend()).toBeInstanceOf(MiniGameAudioBackend);
        expect(a.createAudioBackend().name).toBe('MyVendor');
        expect(a.createSocket({ url: 'wss://example.test' })).toBeInstanceOf(MiniGameSocket);
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        expect(a.createVideoBackend({} as any)).toBeTruthy();
    });

    it('falls back to standard WebAssembly when the profile omits instantiateWasm', async () => {
        const { MiniGamePlatformAdapter } = await import('../src/platform/minigame/adapter');
        // A minimal valid wasm module (the 8-byte header — magic + version).
        const wasm = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
        const profile = { id: 'myvendor', hostLabel: 'MyVendor', global: {} };
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        const a = new MiniGamePlatformAdapter(profile as any);

        const res = await a.instantiateWasm(wasm.buffer as ArrayBuffer, {});
        expect(res.instance).toBeInstanceOf(WebAssembly.Instance);
    });
});

describe('MiniGamePlatformAdapter surfaces (casts removed)', () => {
    it('returns a sized canvas and image from the host global', async () => {
        const { MiniGamePlatformAdapter } = await import('../src/platform/minigame/adapter');
        const g = {
            createCanvas: () => ({ width: 0, height: 0, getContext: () => null }),
            createImage: () => ({ width: 5, height: 7, src: '', onload: null, onerror: null }),
        };
        const profile = {
            id: 'wechat',
            hostLabel: 'WeChat',
            global: g,
            instantiateWasm: vi.fn(),
            createAudioBackend: vi.fn(),
            createVideoBackend: vi.fn(),
            createSocket: vi.fn(),
        };
        // eslint-disable-next-line @typescript-eslint/no-explicit-any
        const a = new MiniGamePlatformAdapter(profile as any);
        expect(a.name).toBe('wechat');
        const c = a.createCanvas(10, 20);
        expect(c.width).toBe(10);
        expect(c.height).toBe(20);
        const img = a.createImage();
        expect(img.width).toBe(5);
        expect(img.height).toBe(7);
    });
});

describe('node adapter surfaces (fail loud, no render host)', () => {
    it('throws for canvas/image and rejects image decode', async () => {
        const { nodeAdapter } = await import('../src/platform/node');
        expect(() => nodeAdapter.createCanvas(1, 1)).toThrow();
        expect(() => nodeAdapter.createImage()).toThrow();
        await expect(nodeAdapter.loadImagePixels('x.png')).rejects.toThrow();
    });
});

describe('esengine/native entry', () => {
    // These two transform the WHOLE native entry graph (core + webAppFactory +
    // every re-export) on first import — several seconds cold, and slower still
    // under the full suite's parallel load. Give them room past the 5s default so
    // they measure re-export wiring, not machine contention.
    it('re-exports the native surface + the core SDK', async () => {
        const native = await import('../src/index.native');
        expect(typeof native.installNativePlatform).toBe('function');
        expect(typeof native.NativePlatformAdapter).toBe('function');
        // Core + webAppFactory are re-exported so a shell imports everything from here.
        expect(typeof native.createWebApp).toBe('function');
        expect(typeof native.createHeadlessApp).toBe('function');
        expect(typeof native.App).toBe('function');
    }, 30000);

    it('installNativePlatform from the entry activates the native platform', async () => {
        const native = await import('../src/index.native');
        native.installNativePlatform(makeBridge().bridge);
        const { getPlatformType, isNative } = await import('../src/platform');
        expect(getPlatformType()).toBe('native');
        expect(isNative()).toBe(true);
    }, 30000);
});