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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file splash.ts — the exported page's start screen, and the one list of boot
* stages it and the runtime both read.
*
* The page carries the markup because it has to be on screen before `game.js`
* is even fetched, and the runtime moves the bar because `boot()` is the only
* thing that knows which stage it reached. Those are two readers of one list, so
* the list lives here rather than being spelled once in each.
*
* The stage list is the SDK's: a mini-game shows the same progress through a
* host API rather than an overlay, and two copies would disagree about how far
* along one boot is.
*/
import { BOOT_STAGES, BOOT_TOTAL, type BootStage } from '../../../sdk/src/runtime/bootStages';
export { BOOT_STAGES, type BootStage };
/**
* The page's ground, and what the start screen fades out over. One colour for
* both, or the fade flashes through to white between them — which is why the
* page and this file cannot each name their own.
*/
export const PAGE_BACKGROUND = '#0e121b';
/** Ids the page and the runtime agree on; `es-` so a game's own markup cannot collide. */
const ROOT = 'es-splash';
const BAR = 'es-splash-bar';
const LABEL = 'es-splash-label';
/** What the project said the start screen should look like. */
export interface SplashLook {
/** The logo as a data: URI — inlined by the export, since an image fetched
* after the engine has nothing left to cover. */
logo?: string;
/** Shortest time on screen, in ms. */
minMs?: number;
/** CSS colour behind it; the page's own when the project said nothing. */
background?: string;
}
/**
* The start screen's CSS. `background` matches the page so the fade lands on the
* same colour the canvas clears to, rather than flashing through to white.
*/
export function splashCss(background: string): string {
return (
`#${ROOT} .es-splash-logo{max-width:min(220px,46vw);max-height:30vh;object-fit:contain;}`
+ `#${ROOT}{position:fixed;inset:0;z-index:20;display:flex;flex-direction:column;`
+ `align-items:center;justify-content:center;gap:18px;background:${background};`
+ "color:#c7d0e0;font:500 14px/1.5 system-ui,-apple-system,'Segoe UI',sans-serif;"
+ 'transition:opacity .35s ease;padding:24px;text-align:center;}'
+ `#${ROOT}.es-splash-gone{opacity:0;pointer-events:none;}`
+ `#${ROOT} .es-splash-title{font-size:19px;font-weight:650;letter-spacing:.01em;}`
+ `#${ROOT} .es-splash-track{width:min(260px,62vw);height:3px;border-radius:2px;`
+ 'background:rgba(199,208,224,.18);overflow:hidden;}'
+ `#${ROOT} #${BAR}{height:100%;width:0;border-radius:2px;background:#c7d0e0;`
+ 'transition:width .25s ease;}'
+ `#${ROOT} #${LABEL}{font-size:12px;opacity:.72;min-height:1.5em;}`
// A stretch with no measure of its own (shaders compiling, a world being made): a light runs along the track, so a bar
// that has stopped moving does not read as a page that has stopped.
+ `#${ROOT} .es-splash-track{position:relative;}`
+ `#${ROOT}.es-splash-busy .es-splash-track::after{content:'';position:absolute;top:0;bottom:0;left:-30%;width:30%;`
+ 'background:linear-gradient(90deg,transparent,rgba(255,255,255,.75),transparent);animation:es-splash-run 1.1s linear infinite;}'
+ '@keyframes es-splash-run{to{left:100%;}}'
+ `@media (prefers-reduced-motion:reduce){#${ROOT}.es-splash-busy .es-splash-track::after{animation-duration:3s;}}`
// A start screen that outlives its own boot is worse than none: if the
// runtime never arrives to fade it, this hides it rather than covering the
// game forever.
+ `@media (prefers-reduced-motion:reduce){#${ROOT}{transition:none;}}`
);
}
/** The start screen's markup — no script of its own, so the page adds no CSP hash.
* `minMs` rides on a data attribute for the same reason. */
export function splashHtml(title: string, look: SplashLook = {}): string {
const safe = title.replace(/[&<>]/g, (c) => ({ '&': '&', '<': '<', '>': '>' }[c] as string));
const hold = look.minMs ? ` data-min-ms="${Math.round(look.minMs)}"` : '';
// A game with a logo shows the logo; the title is then the alt text rather
// than a second heading saying the same thing.
const mark = look.logo
? `<img class="es-splash-logo" src="${look.logo}" alt="${safe}">`
: `<div class="es-splash-title">${safe}</div>`;
return `<div id="${ROOT}" role="status" aria-live="polite"${hold}>`
+ mark
+ `<div class="es-splash-track"><div id="${BAR}"></div></div>`
+ `<div id="${LABEL}">${BOOT_STAGES[0].says}…</div>`
+ '</div>';
}
/** What {@link attachSplash} hands the boot sequence. */
export interface Splash {
/** Mark a stage finished and advance the bar by that stage's weight. */
reach(stage: BootStage): void;
/** How far through a stage that has NOT finished — `0..1` of its own weight.
* `engine` alone is 40 of the 100, so a bar that only moves on completion
* stands still for most of a cold start. */
within(stage: BootStage, fraction: number): void;
/** The boot is in a stretch nothing measures: the track shows it is alive, and the label says `says` if given. */
busy(says?: string): void;
/** Fade out and remove. Safe to call twice. */
done(): void;
}
/**
* The events a page outside the bundle listens for — a portal SDK's own loading
* screen. DOM events, not a global: a listener must be added BEFORE the bundle
* runs, and the page carries no script of ours to define one on. `progress` is
* 0..1 and never goes backwards; `partial` marks a stage still running.
*/
export const BOOT_PROGRESS_EVENT = 'esengine:bootprogress';
export const FIRST_FRAME_EVENT = 'esengine:firstframe';
/**
* Drive the page's start screen and announce the boot.
*
* Always returns: a page with no start screen (a playable exported before it had
* one) still has a portal around it that wants the events. A boot must never be a
* thing the start screen can fail.
*
* `weights` replaces a stage's share of the bar for a host whose boot is shaped differently: the list's own are a web page's,
* most of whose start is fetching the engine, and a page with everything inlined spends that time elsewhere.
*/
export function attachSplash(doc: Document = document, weights: Partial<Record<BootStage, number>> = {}): Splash {
const weightOf = (stage: BootStage): number => weights[stage] ?? BOOT_STAGES.find((s) => s.id === stage)?.weight ?? 0;
const total = BOOT_STAGES.reduce((n, s) => n + weightOf(s.id), 0) || BOOT_TOTAL;
const root = doc.getElementById(ROOT);
const bar = root && doc.getElementById(BAR);
const label = root && doc.getElementById(LABEL);
const showUntil = Date.now() + Number(root?.getAttribute('data-min-ms') ?? 0);
let done = 0;
/** What the bar is showing, so a partial step never pulls it back. */
let shown = 0;
let finished = false;
const seen = new Set<BootStage>();
const announce = (type: string, detail: unknown): void => {
const view = doc.defaultView;
if (view) view.dispatchEvent(new view.CustomEvent(type, { detail }));
};
const fade = (): void => {
if (!root?.isConnected) return;
root.classList.add('es-splash-gone');
setTimeout(() => root.remove(), 400);
};
/** Never backwards. Answers whether the bar actually moved a whole percent,
* which is the only movement worth telling a portal's own screen about. */
const show = (progress: number): boolean => {
if (progress <= shown) return false;
const was = Math.round(shown * 100);
shown = progress;
const now = Math.round(progress * 100);
if (bar) bar.style.width = `${now}%`;
return now > was;
};
return {
within(stage, fraction) {
if (seen.has(stage)) return;
const partial = Math.max(0, Math.min(1, fraction)) * weightOf(stage);
const progress = Math.min(1, (done + partial) / total);
// `partial` marks a stage still running, so a listener can tell "40% of
// the way through fetching the engine" from "the engine is up".
if (show(progress)) announce(BOOT_PROGRESS_EVENT, { stage, progress, partial: true });
},
reach(stage) {
// Idempotent by stage, not additive: a retried leg must not push the bar
// past what it has actually finished.
if (seen.has(stage)) return;
seen.add(stage);
done += weightOf(stage);
const progress = Math.min(1, done / total);
show(progress);
const at = BOOT_STAGES.findIndex((s) => s.id === stage);
const next = BOOT_STAGES[at + 1];
if (label && next) label.textContent = `${next.says}…`;
announce(BOOT_PROGRESS_EVENT, { stage, progress });
},
busy(says) {
if (finished || !root) return;
root.classList.add('es-splash-busy');
if (label && says && label.textContent !== `${says}…`) label.textContent = `${says}…`;
},
done() {
if (finished) return;
finished = true;
show(1);
announce(FIRST_FRAME_EVENT, {});
// A boot that finished in 120ms would otherwise flash a bar that appears
// and vanishes, which reads as a glitch rather than as loading.
const wait = showUntil - Date.now();
if (wait > 0) setTimeout(fade, wait);
else fade();
},
};
}