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.

9.5 KB
Raw Blame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
 * @file  The start screen the exported page carries.
 *
 * It has to be on screen before `game.js` is even fetched, so everything it
 * needs is IN the page — a logo that arrives over the network arrives in the
 * same window the engine does, with nothing left to cover.
 */
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import { exportGame } from '../src/export/exportGame';
import { runtimeConfigOf } from '../src/project/runtimeConfig';
import type { ProjectPackaging } from '../src/project/format';
import { writeFakeSdkDist } from './fixtures/fakeSdkDist';
import { OFFICIAL_PACKAGES } from './officialPackagesDir';

let root: string;
const TEX = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
const SCN = 'bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb';
const meta = (uuid: string, type: string) => JSON.stringify({ uuid, version: '2.0', type, importer: {} });
/** A one-pixel PNG, so the inlined bytes are a real image rather than a string. */
const PNG = Buffer.from(
  'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==',
  'base64',
);

beforeAll(() => {
  root = mkdtempSync(path.join(tmpdir(), 'estella-export-splash-'));
  mkdirSync(path.join(root, 'assets'), { recursive: true });
  writeFileSync(path.join(root, 'assets', 'hero.png'), PNG);
  writeFileSync(path.join(root, 'assets', 'hero.png.meta'), meta(TEX, 'texture'));
  writeFileSync(path.join(root, 'assets', 'logo.png'), PNG);
  mkdirSync(path.join(root, 'scenes'), { recursive: true });
  writeFileSync(
    path.join(root, 'scenes', 'main.esscene'),
    JSON.stringify({ version: '1.0', name: 'Main', entities: [{ id: 0, components: [{ type: 'Sprite', data: { texture: `@uuid:${TEX}` } }] }] }),
  );
  writeFileSync(path.join(root, 'scenes', 'main.esscene.meta'), meta(SCN, 'scene'));
  writeFakeSdkDist(path.join(root, '_sdk'), {
    'index.js': 'export function initWebRuntime(){return Promise.resolve();}\n',
  });
  mkdirSync(path.join(root, '_wasm'), { recursive: true });
  writeFileSync(path.join(root, '_wasm', 'esengine.js'), 'const M=()=>{};\nexport default M;\n');
  writeFileSync(path.join(root, '_wasm', 'esengine.wasm'), 'wasmbytes');
}, 60_000);

afterAll(() => rmSync(root, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 }));

/** Export for web and hand back the page plus whatever the build said about it. */
async function page(splash?: ProjectPackaging['splash'], webChannel?: 'poki' | 'crazygames' | 'youtube', leaderboardEncryptionKey?: string): Promise<{ html: string; config: Record<string, unknown>; warnings: string[]; splashBytes?: number }> {
  const outDir = path.join(root, `dist-${Math.random().toString(36).slice(2)}`);
  const res = await exportGame({
    root,
    entryScene: 'scenes/main.esscene',
    hostsDir: path.resolve(__dirname, '../src/runtime'), packagesDir: OFFICIAL_PACKAGES,
    sdkDistDir: path.join(root, '_sdk'),
    wasmDir: path.join(root, '_wasm'),
    outDir,
    title: 'My Game',
    platform: 'web', webChannel, leaderboardEncryptionKey,
    runtime: runtimeConfigOf({ designResolution: { width: 800, height: 600 } }),
    splash,
  });
  expect(res.ok, res.errors.join('\n')).toBe(true);
  return { html: readFileSync(path.join(outDir, 'index.html'), 'utf8'), config: JSON.parse(readFileSync(path.join(outDir, 'game.config.json'), 'utf8')), warnings: res.warnings, splashBytes: res.size?.splashBytes };
}

describe('the exported page’s start screen', () => {
  it('has its own line in the size report, logo included', async () => {
    const plain = await page();
    const withLogo = await page({ logo: 'assets/logo.png' });
    expect(plain.splashBytes).toBeGreaterThan(0);
    expect(plain.html.length).toBeGreaterThan(plain.splashBytes!);
    expect(withLogo.splashBytes! - plain.splashBytes!).toBeGreaterThanOrEqual(Math.floor(PNG.length * 4 / 3));
  }, 180_000);

  it('is there with nothing configured, showing the game’s name', async () => {
    const { html } = await page();
    expect(html).toContain('id="es-splash"');
    expect(html).toContain('My Game');
    expect(html).not.toContain('class="es-splash-logo"');
  }, 180_000);

  it('carries the logo IN the page, not as a request that races the engine', async () => {
    const { html, warnings } = await page({ logo: 'assets/logo.png' });
    // Nothing REFUSED it. What it costs the page is said separately, below.
    expect(warnings.join('\n')).not.toMatch(/does not exist|not an image/);
    expect(html).toContain('class="es-splash-logo"');
    expect(html).toContain(`src="data:image/png;base64,${PNG.toString('base64')}"`);
    // The path itself must not survive into the page: a start screen that
    // fetches its own logo is the failure this inlining exists to prevent.
    expect(html).not.toContain('assets/logo.png');
  }, 180_000);

  // Inlined, the logo is page bytes: a size report files it under the html and a
  // start screen can take a share of a main-package limit with nothing saying so.
  it('says what the logo costs the page, since the page hides it', async () => {
    const { warnings } = await page({ logo: 'assets/logo.png' });
    const said = warnings.find((w) => w.includes('assets/logo.png'));
    expect(said, 'the inlined logo cost nothing was told about').toBeDefined();
    expect(said).toContain(`${PNG.length} bytes`);
    // …and the base64 tax, which is the part a file listing cannot show.
    expect(said).toMatch(/\b\d+ in the page/);
  }, 180_000);

  it('says so and ships anyway when the logo is not there', async () => {
    const { html, warnings } = await page({ logo: 'assets/missing.png' });
    expect(warnings.join('\n')).toContain('assets/missing.png');
    // Still a start screen, still the game's name — a bad path must not leave
    // the player watching a blank page.
    expect(html).toContain('id="es-splash"');
    expect(html).toContain('My Game');
  }, 180_000);

  it('refuses a file the page could not decode, rather than a broken first screen', async () => {
    const { html, warnings } = await page({ logo: 'assets/hero.tga' });
    expect(warnings.join('\n')).toContain('assets/hero.tga');
    expect(html).not.toContain('class="es-splash-logo"');
  }, 180_000);

  it('holds for as long as the project asked, and paints the colour it asked for', async () => {
    const { html } = await page({ background: '#102030', minMs: 800 });
    expect(html).toContain('data-min-ms="800"');
    expect(html).toContain('#102030');
  }, 180_000);
});


describe('Poki host page', () => {
  it('loads YouTube SDK before game code and carries its fixed channel marker', async () => {
    const { html, config, warnings } = await page(undefined, 'youtube');
    const script = '<script src="https://www.youtube.com/game_api/v1"></script>';
    expect(html.indexOf(script)).toBeGreaterThan(html.indexOf('<head>'));
    expect(html.indexOf(script)).toBeLessThan(html.indexOf('</head>'));
    expect(html.indexOf(script)).toBeLessThan(html.indexOf('src="./game.js"'));
    expect(html).toContain('data-web-channel="youtube"'); expect(config.webChannel).toBe('youtube');
    expect(html).not.toContain('crazygames-sdk'); expect(html).not.toContain('poki-sdk');
    expect(warnings.some(warning => warning.includes('static bundle checks do not measure'))).toBe(true);
  });
  it('packages the client leaderboard key only for CrazyGames', async () => {
    const key = Buffer.alloc(32, 7).toString('base64');
    expect((await page(undefined, 'crazygames', key)).config.leaderboardEncryptionKey).toBe(key);
    expect((await page(undefined, 'poki', key)).config.leaderboardEncryptionKey).toBeUndefined();
    expect((await page(undefined, undefined, key)).config.leaderboardEncryptionKey).toBeUndefined();
  });
  it('loads CrazyGames v3 before the game without injecting Poki', async () => {
    const { html } = await page(undefined, 'crazygames');
    const script = '<script src="https://sdk.crazygames.com/crazygames-sdk-v3.js"></script>';
    expect(html.indexOf(script)).toBeGreaterThan(html.indexOf('<head>'));
    expect(html.indexOf(script)).toBeLessThan(html.indexOf('</head>'));
    expect(html.indexOf(script)).toBeLessThan(html.indexOf('src="./game.js"'));
    expect(html).toContain('data-web-channel="crazygames"');
    expect(html).toContain('frame-src https:');
    expect(html).not.toContain('poki-sdk');
  });
  it('loads the official SDK in the head before the game, with its channel policy', async () => {
    const { html } = await page(undefined, 'poki');
    const script = '<script src="https://game-cdn.poki.com/scripts/v2/poki-sdk.js"></script>';
    expect(html.indexOf(script)).toBeGreaterThan(html.indexOf('<head>'));
    expect(html.indexOf(script)).toBeLessThan(html.indexOf('</head>'));
    expect(html.indexOf(script)).toBeLessThan(html.indexOf('src="./game.js"'));
    expect(html).toContain('data-web-channel="poki"');
    expect(html).toContain('frame-src https:');
    expect(html).toContain("script-src 'self' 'unsafe-eval' blob: https:");
  });
  it('keeps standalone exports free of SDK injection and broad HTTPS policy', async () => {
    const { html } = await page();
    expect(html).toContain('data-web-channel="standalone"');
    expect(html).not.toContain('poki-sdk');
    expect(html).not.toContain('crazygames-sdk');
    expect(html).not.toContain('frame-src https:');
    expect(html).toContain("default-src 'self';");
  });
});