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 The official runtime packages (`estella-plugin-*`) resolve to the copy
* the editor ships, for every bundle a project's scripts go into.
*
* They are not on any registry: the editor carries `plugins/` beside itself, so
* `import … from 'estella-plugin-minigame-services'` has to be answered here or
* nowhere. A copy the project installed into its own node_modules still wins —
* that is a choice someone made, and the built-in one is only the default.
*/
import { existsSync, readdirSync, readFileSync } from 'node:fs';
import path from 'node:path';
import type { Plugin } from 'esbuild';
import { BUNDLER_RESOLVES } from './bundlerResolve';
const OFFICIAL = /^(estella-plugin-[^/]+)(\/.+)?$/;
export interface OfficialPackage {
/** The package's directory under the shipped `plugins/`. */
readonly dir: string;
/** Export subpath ('.', './open-data') → absolute entry file. Empty for an
* editor-only plugin, which a game has nothing to import from. */
readonly exports: ReadonlyMap<string, string>;
}
/** Package name → package. */
export type OfficialPackages = ReadonlyMap<string, OfficialPackage>;
const cache = new Map<string, OfficialPackages>();
export function readOfficialPackages(packagesDir: string): OfficialPackages {
const hit = cache.get(packagesDir);
if (hit) return hit;
const out = new Map<string, OfficialPackage>();
const entries = existsSync(packagesDir) ? readdirSync(packagesDir, { withFileTypes: true }) : [];
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const dir = path.join(packagesDir, entry.name);
const manifest = path.join(dir, 'package.json');
if (!existsSync(manifest)) continue;
const pkg = JSON.parse(readFileSync(manifest, 'utf8')) as {
name?: string; main?: string; exports?: string | Record<string, string>;
};
if (!pkg.name || !OFFICIAL.test(pkg.name)) continue;
const exportsMap = typeof pkg.exports === 'string' ? { '.': pkg.exports }
: pkg.exports ?? (pkg.main ? { '.': pkg.main } : {});
const subpaths = new Map<string, string>();
for (const [sub, rel] of Object.entries(exportsMap)) subpaths.set(sub, path.join(dir, rel));
out.set(pkg.name, { dir, exports: subpaths });
}
cache.set(packagesDir, out);
return out;
}
/** esbuild plugin: `estella-plugin-*` from the project's node_modules if it has
* one, otherwise from `packagesDir`. */
export function officialPackagesPlugin(packagesDir: string): Plugin {
return {
name: 'estella-official-packages',
setup(build) {
build.onResolve({ filter: OFFICIAL }, async (args) => {
if (args.pluginData === BUNDLER_RESOLVES) return undefined;
const own = await build.resolve(args.path, {
kind: args.kind, importer: args.importer, resolveDir: args.resolveDir, pluginData: BUNDLER_RESOLVES,
});
if (own.errors.length === 0) return { path: own.path, external: own.external, sideEffects: own.sideEffects };
const [, name, rest] = OFFICIAL.exec(args.path)!;
const packages = readOfficialPackages(packagesDir);
const subpaths = packages.get(name)?.exports;
if (!subpaths) {
return { errors: [{ text: `"${name}" is not one of the packages the editor ships (${[...packages.keys()].join(', ') || 'none found'}), and the project has not installed it` }] };
}
const entry = subpaths.get(rest ? `.${rest}` : '.');
if (!entry) {
return { errors: [{ text: `"${name}" exports no "${rest ? `.${rest}` : '.'}" — it exports ${[...subpaths.keys()].join(', ')}` }] };
}
return { path: entry };
});
},
};
}