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
feat(cocos): sys, view/screen, macro, Layers, game, the global input with KeyCode and keyboard/mouse/touch events, and resources/assetManager/Bundle over a manifest the importer writes for resources and bundle folders
yhh8e799fdd3795
diff --git a/pipeline/src/import/cocos/assets.ts b/pipeline/src/import/cocos/assets.tsindex 38c6e0c16..826894706 100644--- a/pipeline/src/import/cocos/assets.ts+++ b/pipeline/src/import/cocos/assets.ts@@ -28,6 +28,15 @@ export interface CocosAssetIndex {root: string;/** Every asset and every sub-asset, by uuid. A sub-asset resolves to its parent file. */byUuid: Map<string, CocosAssetEntry>;+ /** Folders whose contents scripts load by path at run time: asset bundles, and the `resources` folders. */+ bundles: CocosBundleRoot[];+}++export interface CocosBundleRoot {+ /** The name a script loads it by: `resources`, or the bundle's own name. */+ name: string;+ /** The folder, relative to the project's `assets`. */+ rel: string;}const SKIP = new Set(['node_modules', '.git']);@@ -52,6 +61,7 @@ const asObj = (v: unknown): Record<string, unknown> => (typeof v === 'object' &&export function buildCocosAssetIndex(root: string): CocosAssetIndex {const byUuid = new Map<string, CocosAssetEntry>();+ const bundles: CocosBundleRoot[] = [];for (const metaFile of walk(root)) {let meta: Record<string, unknown>;try {@@ -60,7 +70,15 @@ export function buildCocosAssetIndex(root: string): CocosAssetIndex {continue;}const uuid = meta.uuid;- if (typeof uuid !== 'string' || meta.importer === 'directory') continue;+ if (meta.importer === 'directory') {+ const folder = metaFile.slice(0, -'.meta'.length);+ const rel = path.relative(root, folder).split(path.sep).join('/');+ const userData = asObj(meta.userData);+ if (userData.isBundle === true) bundles.push({ name: typeof userData.bundleName === 'string' && userData.bundleName ? userData.bundleName : path.basename(folder), rel });+ else if (path.basename(folder) === 'resources') bundles.push({ name: 'resources', rel });+ continue;+ }+ if (typeof uuid !== 'string') continue;const file = metaFile.slice(0, -'.meta'.length);const entry: CocosAssetEntry = {uuid,@@ -78,5 +96,5 @@ export function buildCocosAssetIndex(root: string): CocosAssetIndex {}byUuid.set(uuid, entry);}- return { root, byUuid };+ return { root, byUuid, bundles };}diff --git a/pipeline/src/import/cocos/importProject.ts b/pipeline/src/import/cocos/importProject.tsindex f214463e8..759e2bc3a 100644--- a/pipeline/src/import/cocos/importProject.ts+++ b/pipeline/src/import/cocos/importProject.ts@@ -206,6 +206,36 @@ export function importCocosProject(opts: CocosImportOptions): ImportReportData {const byRel = new Map<string, CocosAssetEntry>();for (const e of index.byUuid.values()) byRel.set(e.rel, e);+ // Assets scripts load by path at run time (`resources.load('ui/icon')`) are named by no scene, so nothing above would bring them+ // across. They are copied, and listed by bundle in a manifest the runtime layer resolves those paths through.+ const manifest: Record<string, Record<string, { path: string; kind: string }>> = {};+ if (index.bundles.length > 0) {+ const files = new Set(index.byUuid.values());+ for (const bundle of index.bundles) {+ const entries = (manifest[bundle.name] ??= {});+ for (const entry of files) {+ if (!entry.rel.startsWith(`${bundle.rel}/`) || !wanted(entry.rel)) continue;+ const key = entry.rel.slice(bundle.rel.length + 1).replace(/\.[^./]+$/, '');+ const ext = /\.([^./]+)$/.exec(entry.rel)?.[1]?.toLowerCase() ?? '';+ if (ext === 'prefab') {+ const ref = ctx.prefabRef(entry.uuid);+ if (ref) entries[key] = { path: ref, kind: 'prefab' };+ } else if (ext === 'json') {+ entries[key] = { path: ctx.assetRef(entry), kind: 'json' };+ } else if (['txt', 'text', 'xml', 'csv', 'atlas'].includes(ext)) {+ entries[key] = { path: ctx.assetRef(entry), kind: 'text' };+ } else if (['png', 'jpg', 'jpeg', 'webp'].includes(ext)) {+ entries[key] = { path: ctx.assetRef(entry), kind: 'texture' };+ } else if (['mp3', 'wav', 'ogg', 'm4a'].includes(ext)) {+ entries[key] = { path: ctx.assetRef(entry), kind: 'audio' };+ } else if (ext !== 'meta' && ext !== 'ts' && ext !== 'js' && ext !== 'scene') {+ entries[key] = { path: '', kind: ext || 'other' };+ }+ }+ }+ write(outRef('resources.json'), manifest);+ }+for (let i = 0; i < pending.length; i++) {const r = pending[i]!;const e = byRel.get(r);diff --git a/pipeline/tests/cocos-import-layer.test.ts b/pipeline/tests/cocos-import-layer.test.tsindex af6457793..c8a3fa03f 100644--- a/pipeline/tests/cocos-import-layer.test.ts+++ b/pipeline/tests/cocos-import-layer.test.ts@@ -66,6 +66,16 @@ describe('importing for the compatibility layer', () => {put('scripts/Hud.ts.meta', meta(HUD, 'typescript'));put('scripts/Other.ts', "@ccclass\n@menu('x')\n// a comment between\n@executionOrder(-1)\nexport default class Other extends Component {}\n");put('scripts/Other.ts.meta', meta(OTHER, 'typescript'));+ put('resources.meta', { ver: '1.2.0', importer: 'directory', uuid: 'eeeeeeee-eeee-4eee-8eee-eeeeeeeeeeee', userData: { isBundle: true, bundleName: 'resources' } });+ put('resources/cfg/rules.json', '{"a":1}');+ put('resources/cfg/rules.json.meta', meta('f1f1f1f1-f1f1-4f1f-8f1f-f1f1f1f1f1f1', 'json'));+ put('resources/ui/icon.png', 'not a png');+ put('resources/ui/icon.png.meta', meta('f2f2f2f2-f2f2-4f2f-8f2f-f2f2f2f2f2f2', 'image'));+ put('resources/prefab/thing.prefab', [{ __type__: 'cc.Prefab', _name: 'thing', data: { __id__: 1 } }, { ...node('Thing', 0, [], []), _prefab: { __id__: 2 } }, { __type__: 'cc.PrefabInfo', root: { __id__: 1 }, asset: { __id__: 0 }, fileId: 'thingRoot', instance: null }]);+ put('resources/prefab/thing.prefab.meta', meta('f3f3f3f3-f3f3-4f3f-8f3f-f3f3f3f3f3f3', 'prefab'));+ put('hero.meta', { ver: '1.2.0', importer: 'directory', uuid: 'f4f4f4f4-f4f4-4f4f-8f4f-f4f4f4f4f4f4', userData: { isBundle: true, bundleName: 'hero' } });+ put('hero/skin.json', '{}');+ put('hero/skin.json.meta', meta('f5f5f5f5-f5f5-4f5f-8f5f-f5f5f5f5f5f5', 'json'));put('art/plain.json', '{}');put('art/plain.json.meta', meta(PLAIN, 'json'));report = importCocosProject({ source: path.join(root, 'creator'), out: path.join(root, 'out') });@@ -123,6 +133,15 @@ describe('importing for the compatibility layer', () => {expect(path.resolve(root, 'out', 'src', line.slice("import '".length, -2) + '.ts')).toBe(path.join(root, 'creator', 'assets', 'scripts', 'Hud.ts'));});+ it('lists what scripts load by path in a manifest, by bundle, and copies those files', () => {+ const manifest = JSON.parse(readFileSync(path.join(root, 'out', 'assets', 'cocos', 'resources.json'), 'utf8'));+ expect(manifest.resources['cfg/rules']).toEqual({ path: 'assets/cocos/resources/cfg/rules.json', kind: 'json' });+ expect(manifest.resources['ui/icon']).toEqual({ path: 'assets/cocos/resources/ui/icon.png', kind: 'texture' });+ expect(manifest.resources['prefab/thing']).toEqual({ path: 'assets/cocos/resources/prefab/thing.esprefab', kind: 'prefab' });+ expect(manifest.hero['skin']).toEqual({ path: 'assets/cocos/hero/skin.json', kind: 'json' });+ expect(readFileSync(path.join(root, 'out', 'assets', 'cocos', 'resources', 'cfg', 'rules.json'), 'utf8')).toBe('{"a":1}');+ });+it('counts the components it maps', () => {for (const type of ['cc.Widget', 'cc.Layout', 'cc.Button', 'cc.UITransform']) expect(report.components[type]!.unmapped).toBe(0);});diff --git a/sdk/src/cocos/assetManager.ts b/sdk/src/cocos/assetManager.tsnew file mode 100644index 000000000..c73823416--- /dev/null+++ b/sdk/src/cocos/assetManager.ts@@ -0,0 +1,274 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/assetManager.ts+ * @brief `resources.load`, `assetManager.loadBundle` / `loadRemote` / `loadAny`, and `Bundle`.+ *+ * In Cocos a path under a `resources` folder (or a bundle) names an asset by its location, resolved at run time. The engine has no+ * such folder convention, so the importer writes a *manifest* — `assets/cocos/resources.json`, bundle name → path inside the+ * bundle → the project file and its kind — and this layer resolves a Cocos path through it.+ *+ * Kinds that load: **prefab** (prepared, so a following `instantiate` works), **json** and **text**. Textures, sprite frames,+ * audio and the rest come back with an error that says so, since a loaded asset of those kinds must be bound to the engine's+ * resource tables and that binding is not made here yet; a script gets a failure it can handle rather than an empty object.+ *+ * The cache objects (`assetManager.assets`, `.bundles`, `.cacheManager`) have the shape scripts iterate; what is in them is what+ * this layer has loaded.+ */+import { platformFetch } from '../platform';+import { log } from '../util/logger';+import { Asset, JsonAsset, Prefab, TextAsset } from './assets';+import { getCurrentWorld } from './node';+import { assetsFor, loadPrefab } from './prefabs';++export interface ResourceEntry {+ /** The project-relative path of the file. */+ path: string;+ /** What kind of asset it is: `prefab`, `json`, `text`, or another the layer cannot load. */+ kind: string;+}+export type ResourceManifest = Record<string, Record<string, ResourceEntry>>;++type Callback<T> = (err: Error | null, data: T) => void;+type AssetCtor = new (...args: any[]) => Asset;++/** A Map with the extra reads Cocos's `Cache` has. */+export class Cache<T> {+ private readonly map_ = new Map<string, T>();+ get count(): number { return this.map_.size; }+ get(key: string): T | undefined { return this.map_.get(key); }+ has(key: string): boolean { return this.map_.has(key); }+ add(key: string, value: T): T { this.map_.set(key, value); return value; }+ remove(key: string): T | undefined { const v = this.map_.get(key); this.map_.delete(key); return v; }+ clear(): void { this.map_.clear(); }+ entries(): IterableIterator<[string, T]> { return this.map_.entries(); }+ forEach(fn: (value: T, key: string) => void): void { this.map_.forEach(fn); }+ find(predicate: (value: T, key: string) => boolean): T | null {+ for (const [k, v] of this.map_) if (predicate(v, k)) return v;+ return null;+ }+ destroy(): void { this.map_.clear(); }+}++let manifest: ResourceManifest | null = null;+let manifestLoad: Promise<ResourceManifest> | null = null;+const MANIFEST_PATH = 'assets/cocos/resources.json';++/** Provide the manifest directly (a host that has it, or a test). */+export function setResourceManifest(m: ResourceManifest): void { manifest = m; manifestLoad = null; }++async function theManifest(): Promise<ResourceManifest> {+ if (manifest) return manifest;+ manifestLoad ??= (async () => {+ const assets = assetsFor(getCurrentWorld());+ if (!assets) throw new Error('the engine\'s asset loader is not running');+ const loaded = await assets.loadJson<ResourceManifest>(MANIFEST_PATH);+ manifest = loaded.data;+ return manifest;+ })();+ try {+ return await manifestLoad;+ } catch (err) {+ manifestLoad = null;+ throw new Error(`cocos compat: cannot read the resource manifest ${MANIFEST_PATH}: ${String((err as Error).message ?? err)}`);+ }+}++const stripExt = (p: string): string => p.replace(/\.[^./]+$/, '');++/** `(path, type?, onProgress?, onComplete?)` in every order Cocos accepts. */+function parseLoadArgs<T>(args: unknown[]): { type: AssetCtor | null; onProgress: ((a: number, b: number, item: unknown) => void) | null; onComplete: Callback<T> | null } {+ let type: AssetCtor | null = null;+ const fns: Function[] = [];+ for (const a of args) {+ if (typeof a !== 'function') continue;+ if ((a as { prototype?: unknown }).prototype instanceof Asset || a === Asset) type = a as AssetCtor;+ else fns.push(a);+ }+ return { type, onProgress: fns.length > 1 ? (fns[0] as never) : null, onComplete: (fns.length > 1 ? fns[1] : fns[0] ?? null) as Callback<T> | null };+}++const loaded = new Cache<Asset>();++async function loadEntry(entry: ResourceEntry, type: AssetCtor | null): Promise<Asset> {+ const assets = assetsFor(getCurrentWorld());+ switch (entry.kind) {+ case 'prefab': {+ if (type && type !== Prefab && !(Prefab.prototype instanceof type)) break;+ return loadPrefab(entry.path);+ }+ case 'json': {+ if (!assets) throw new Error('the engine\'s asset loader is not running');+ const a = new JsonAsset(entry.path);+ a.json = (await assets.loadJson(entry.path)).data;+ return a;+ }+ case 'text': {+ const response = await platformFetch(entry.path);+ if (!response.ok) throw new Error(`could not read ${entry.path}: ${response.status}`);+ const a = new TextAsset(entry.path);+ a.text = await response.text();+ return a;+ }+ default:+ }+ throw new Error(`cocos compat: loading "${entry.path}" (${entry.kind}${type ? `, as ${type.name}` : ''}) is not supported by the compatibility layer yet; prefabs, JSON and text are`);+}++export class Bundle {+ readonly base = '';+ constructor(readonly name: string, private readonly entries_: () => Promise<Record<string, ResourceEntry>>) {}++ private async entry_(path: string): Promise<ResourceEntry> {+ const entries = await this.entries_();+ const found = entries[stripExt(path)] ?? entries[path];+ if (!found) throw new Error(`cocos compat: bundle "${this.name}" has no asset "${path}"`);+ return found;+ }++ load(...args: unknown[]): void {+ const paths = args[0];+ const { type, onProgress, onComplete } = parseLoadArgs<Asset | Asset[]>(args.slice(1));+ const list = Array.isArray(paths) ? paths as string[] : [paths as string];+ (async () => {+ const out: Asset[] = [];+ for (let i = 0; i < list.length; i++) {+ const entry = await this.entry_(list[i]!);+ const key = `${this.name}/${entry.path}`;+ let asset = loaded.get(key);+ if (!asset) loaded.add(key, (asset = await loadEntry(entry, type)));+ out.push(asset);+ onProgress?.(i + 1, list.length, entry);+ }+ return Array.isArray(paths) ? out : out[0]!;+ })().then(+ (r) => onComplete?.(null, r),+ (e: Error) => { if (onComplete) onComplete(e, null as never); else log.warn('cocos', e.message); },+ );+ }++ loadDir(...args: unknown[]): void {+ const dir = String(args[0]).replace(/\/$/, '');+ const { type, onProgress, onComplete } = parseLoadArgs<Asset[]>(args.slice(1));+ (async () => {+ const entries = await this.entries_();+ const keys = Object.keys(entries).filter((k) => dir === '' || k === dir || k.startsWith(`${dir}/`));+ const out: Asset[] = [];+ for (let i = 0; i < keys.length; i++) {+ const entry = entries[keys[i]!]!;+ try {+ const key = `${this.name}/${entry.path}`;+ let asset = loaded.get(key);+ if (!asset) loaded.add(key, (asset = await loadEntry(entry, type)));+ out.push(asset);+ } catch (err) {+ // an entry of a kind that does not load, or of another type than asked for, is skipped like a type mismatch+ if (type) continue;+ throw err;+ }+ onProgress?.(i + 1, keys.length, entry);+ }+ return out;+ })().then(+ (r) => onComplete?.(null, r),+ (e: Error) => { if (onComplete) onComplete(e, null as never); else log.warn('cocos', e.message); },+ );+ }++ /** Preparing is loading, here. */+ preload(...args: unknown[]): void { this.load(...args); }+ preloadDir(...args: unknown[]): void { this.loadDir(...args); }++ /** The asset at @p path if it has been loaded. */+ get<T extends Asset>(path: string, _type?: AssetCtor): T | null {+ for (const [key, asset] of loaded.entries()) {+ if (key.startsWith(`${this.name}/`) && stripExt(key.slice(this.name.length + 1)).endsWith(stripExt(path))) return asset as T;+ }+ return null;+ }+ getInfoWithPath(path: string): { path: string; kind: string } | null {+ const m = manifest?.[this.name]?.[stripExt(path)];+ return m ? { path: m.path, kind: m.kind } : null;+ }+ getDirWithPath(dir: string): Array<{ path: string; kind: string }> {+ const entries = manifest?.[this.name] ?? {};+ return Object.entries(entries).filter(([k]) => k === dir || k.startsWith(`${dir.replace(/\/$/, '')}/`)).map(([path, e]) => ({ path, kind: e.kind }));+ }+ release(path: string): void { const a = this.get(path); if (a) loaded.remove(`${this.name}/${(a as Asset).path}`); }+ releaseAll(): void { for (const [k] of [...loaded.entries()]) if (k.startsWith(`${this.name}/`)) loaded.remove(k); }+}++const bundleOf = (name: string): Bundle => new Bundle(name, async () => (await theManifest())[name] ?? {});++const bundles = new Cache<Bundle>();+const resources = bundleOf('resources');+bundles.add('resources', resources);++class AssetManager {+ readonly assets = loaded;+ readonly bundles = bundles;+ readonly resources = resources;+ readonly presets: Record<string, { priority: number; maxConcurrency: number }> = {+ default: { priority: 0, maxConcurrency: 6 }, preload: { priority: -1, maxConcurrency: 2 }, scene: { priority: 1, maxConcurrency: 6 }, bundle: { priority: 2, maxConcurrency: 6 }, remote: { priority: 0, maxConcurrency: 6 },+ };+ readonly cacheManager = {+ cacheDir: '', cachedFiles: new Cache<unknown>(), tempFiles: new Cache<unknown>(), cacheInterval: 500, cacheEnabled: false,+ clearCache(): void { this.cachedFiles.clear(); },+ clearLRU(): void { /* no persistent cache */ },+ removeCache(url: string): void { this.cachedFiles.remove(url); },+ getCache(url: string): unknown { return this.cachedFiles.get(url); },+ getTemp(url: string): unknown { return this.tempFiles.get(url); },+ };++ getBundle(name: string): Bundle | null { return bundles.get(name) ?? null; }+ removeBundle(bundle: Bundle): void { bundles.remove(bundle.name); }++ /** A bundle by name; the manifest says what is in it. */+ loadBundle(nameOrUrl: string, ...rest: unknown[]): void {+ const onComplete = rest.find((a) => typeof a === 'function') as Callback<Bundle> | undefined;+ const name = nameOrUrl.replace(/\/+$/, '').split('/').pop() ?? nameOrUrl;+ theManifest().then((m) => {+ if (!m[name]) throw new Error(`cocos compat: no bundle "${name}" in the resource manifest`);+ const bundle = bundles.get(name) ?? bundles.add(name, bundleOf(name));+ onComplete?.(null, bundle);+ }).catch((e: Error) => { if (onComplete) onComplete(e, null as never); else log.warn('cocos', e.message); });+ }++ /** A file by URL. JSON and text are read; an image or binary is not made into an asset here. */+ loadRemote(url: string, ...rest: unknown[]): void {+ const onComplete = rest.find((a) => typeof a === 'function') as Callback<Asset> | undefined;+ const ext = (rest.find((a) => typeof a === 'object' && a !== null) as { ext?: string } | undefined)?.ext ?? (/\.([a-z0-9]+)(?:\?|$)/i.exec(url)?.[1] ?? '');+ (async () => {+ if (!/^\.?(json|txt|text|atlas|xml|csv)$/i.test(ext)) {+ throw new Error(`cocos compat: loadRemote of "${ext || 'this kind of'}" files is not supported by the compatibility layer yet; JSON and text are`);+ }+ const response = await platformFetch(url);+ if (!response.ok) throw new Error(`could not read ${url}: ${response.status}`);+ if (/json/i.test(ext)) { const a = new JsonAsset(url); a.json = await response.json(); return a; }+ const a = new TextAsset(url); a.text = await response.text(); return a;+ })().then((a) => { loaded.add(url, a); onComplete?.(null, a); }, (e: Error) => { if (onComplete) onComplete(e, null as never); else log.warn('cocos', e.message); });+ }++ /** Requests in the shapes a script writes: `{ url }` remote, `{ path, bundle?, type? }` a bundle's asset. A uuid is not resolvable here. */+ loadAny(requests: unknown, ...rest: unknown[]): void {+ const onComplete = rest.find((a) => typeof a === 'function') as Callback<unknown> | undefined;+ const one = (r: any): Promise<Asset> => new Promise((resolve, reject) => {+ const done: Callback<Asset> = (e, a) => (e ? reject(e) : resolve(a));+ if (r && typeof r === 'object' && typeof r.url === 'string') this.loadRemote(r.url, r, done);+ else if (r && typeof r === 'object' && typeof r.path === 'string') (bundles.get(r.bundle ?? 'resources') ?? resources).load(r.path, r.type ?? null, done);+ else reject(new Error('cocos compat: loadAny by uuid is not supported; use a bundle path or a url'));+ });+ const list = Array.isArray(requests) ? requests : [requests];+ Promise.all(list.map(one)).then(+ (r) => onComplete?.(null, Array.isArray(requests) ? r : r[0]),+ (e: Error) => { if (onComplete) onComplete(e, null); else log.warn('cocos', e.message); },+ );+ }++ releaseAsset(asset: Asset): void { for (const [k, v] of [...loaded.entries()]) if (v === asset) loaded.remove(k); }+ releaseAll(): void { loaded.clear(); }+}++export { AssetManager };+export const assetManager = new AssetManager();+export { resources };diff --git a/sdk/src/cocos/assets.ts b/sdk/src/cocos/assets.tsindex d5282b878..283b6f4a6 100644--- a/sdk/src/cocos/assets.ts+++ b/sdk/src/cocos/assets.ts@@ -29,8 +29,8 @@ export class Prefab extends Asset {}export class AudioClip extends Asset {}export class Material extends Asset {}-export class JsonAsset extends Asset {}-export class TextAsset extends Asset {}+export class JsonAsset extends Asset { json: unknown = null; }+export class TextAsset extends Asset { text = ''; }export class BitmapFont extends Asset {}export class Font extends Asset {}export class AnimationClip extends Asset {}diff --git a/sdk/src/cocos/builtinScripts.ts b/sdk/src/cocos/builtinScripts.tsindex da30433b4..be8079433 100644--- a/sdk/src/cocos/builtinScripts.ts+++ b/sdk/src/cocos/builtinScripts.ts@@ -15,6 +15,7 @@ import { declareUiPass } from './ui/pass';import { uiTransformDef } from './ui/uiTransform';import { declareTweenSystem } from './tween';import { declarePrefabSystem } from './prefabs';+import { declareGameSystem } from './game';import { resetClassRegistry } from './registry';const declared = new WeakSet<object>();@@ -31,6 +32,7 @@ export function declareBuiltinScripts(): void {declareUiPass();declareTweenSystem();declarePrefabSystem();+ declareGameSystem();}/** Test seam: forget the registry and declare again into the (possibly new) current context. */diff --git a/sdk/src/cocos/emitter.ts b/sdk/src/cocos/emitter.tsnew file mode 100644index 000000000..f62441577--- /dev/null+++ b/sdk/src/cocos/emitter.ts@@ -0,0 +1,54 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/emitter.ts+ * @brief The `on` / `once` / `off` / `emit` that `game`, `input`, `view` and `screen` share.+ *+ * Cocos's `EventTarget`: a listener is a callback with an optional `this`, `off` removes by callback and/or target, and one+ * listener throwing does not keep the rest from hearing the event.+ */+import { log } from '../util/logger';++type Listener = { callback: (...args: any[]) => void; target?: unknown };++export class Emitter {+ private readonly listeners_ = new Map<string, Listener[]>();++ on(type: string, callback: (...args: any[]) => void, target?: unknown): typeof callback {+ const list = this.listeners_.get(type);+ if (list) list.push({ callback, target }); else this.listeners_.set(type, [{ callback, target }]);+ return callback;+ }++ once(type: string, callback: (...args: any[]) => void, target?: unknown): typeof callback {+ const wrapper = (...args: any[]): void => { this.off(type, wrapper, target); callback.apply(target, args); };+ return this.on(type, wrapper, target);+ }++ /** With a callback: that listener (of that target, if given). With only a target: all of its listeners. With neither: the type's. */+ off(type: string, callback?: (...args: any[]) => void, target?: unknown): void {+ const list = this.listeners_.get(type);+ if (!list) return;+ this.listeners_.set(type, list.filter((l) => {+ if (callback && l.callback !== callback) return true;+ if (target !== undefined && l.target !== target) return true;+ return false;+ }));+ }++ targetOff(target: unknown): void {+ for (const [type, list] of this.listeners_) this.listeners_.set(type, list.filter((l) => l.target !== target));+ }++ hasEventListener(type: string): boolean { return (this.listeners_.get(type)?.length ?? 0) > 0; }++ emit(type: string, ...args: any[]): void {+ for (const l of [...(this.listeners_.get(type) ?? [])]) {+ try {+ l.callback.apply(l.target, args);+ } catch (err) {+ log.error('cocos', `a ${type} listener threw`, err);+ }+ }+ }+}diff --git a/sdk/src/cocos/game.ts b/sdk/src/cocos/game.tsnew file mode 100644index 000000000..ed26ec0b8--- /dev/null+++ b/sdk/src/cocos/game.ts@@ -0,0 +1,131 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/game.ts+ * @brief `game` / `Game`: the running application — its frame clock and its show / hide / low-memory events.+ *+ * The clock is fed by the frame loop (`Cocos:Game`, below). The lifecycle events are the platform's, and are bound the first time a+ * script listens for one: a mini-game host and a browser tab both report being shown and hidden, and a script that never asks+ * costs the platform nothing. `restart` and `end` ask the host, since the application is not this layer's to restart.+ */+import { Schedule, defineSystem, addSystemToSchedule } from '../ecs/system';+import { Res, Time } from '../ecs/resource';+import { isPlatformInitialized, platformNow, platformOnAppHide, platformOnAppShow, platformOnMemoryWarning } from '../platform';+import { Emitter } from './emitter';+import { Node } from './node';++const EVENTS = Object.freeze({+ EVENT_HIDE: 'game_on_hide',+ EVENT_SHOW: 'game_on_show',+ EVENT_LOW_MEMORY: 'game_on_low_memory',+ EVENT_GAME_INITED: 'game_inited',+ EVENT_ENGINE_INITED: 'engine_inited',+ EVENT_PRE_BASE_INIT: 'pre_base_init',+ EVENT_POST_BASE_INIT: 'post_base_init',+ EVENT_PRE_SUBSYSTEM_INIT: 'pre_subsystem_init',+ EVENT_POST_SUBSYSTEM_INIT: 'post_subsystem_init',+ EVENT_PRE_PROJECT_INIT: 'pre_project_init',+ EVENT_POST_PROJECT_INIT: 'post_project_init',+ EVENT_RENDERER_INITED: 'renderer_inited',+ EVENT_RESTART: 'game_on_restart',+});++const RendererType = Object.freeze({ UNKNOWN: 0, CANVAS: 1, WEBGL: 2, OPENGL: 3, HEADLESS: 4, WEBGPU: 5 });++export class Game extends Emitter {+ static readonly EVENT_HIDE = EVENTS.EVENT_HIDE;+ static readonly EVENT_SHOW = EVENTS.EVENT_SHOW;+ static readonly EVENT_LOW_MEMORY = EVENTS.EVENT_LOW_MEMORY;+ static readonly EVENT_GAME_INITED = EVENTS.EVENT_GAME_INITED;+ static readonly EVENT_ENGINE_INITED = EVENTS.EVENT_ENGINE_INITED;+ static readonly EVENT_PRE_BASE_INIT = EVENTS.EVENT_PRE_BASE_INIT;+ static readonly EVENT_POST_BASE_INIT = EVENTS.EVENT_POST_BASE_INIT;+ static readonly EVENT_PRE_SUBSYSTEM_INIT = EVENTS.EVENT_PRE_SUBSYSTEM_INIT;+ static readonly EVENT_POST_SUBSYSTEM_INIT = EVENTS.EVENT_POST_SUBSYSTEM_INIT;+ static readonly EVENT_PRE_PROJECT_INIT = EVENTS.EVENT_PRE_PROJECT_INIT;+ static readonly EVENT_POST_PROJECT_INIT = EVENTS.EVENT_POST_PROJECT_INIT;+ static readonly EVENT_RENDERER_INITED = EVENTS.EVENT_RENDERER_INITED;+ static readonly EVENT_RESTART = EVENTS.EVENT_RESTART;+ static readonly RendererType = RendererType;++ readonly RendererType = RendererType;++ frameRate = 60;+ /** Seconds since the previous frame. */+ deltaTime = 0;+ /** Seconds the application has run. */+ totalTime = 0;+ /** The time the current frame began, in milliseconds. */+ frameStartTime = 0;+ renderType = RendererType.WEBGL;+ config: Record<string, unknown> = {};++ private paused_ = false;+ private inited_ = true;+ private bound_ = false;+ private readonly persist_ = new Set<Node>();++ get isInited(): boolean { return this.inited_; }+ get isPaused(): boolean { return this.paused_; }++ /** The page's canvas, when there is a page. */+ get canvas(): HTMLCanvasElement | null {+ if (typeof document === 'undefined') return null;+ return (document.getElementById('GameCanvas') ?? document.querySelector('canvas')) as HTMLCanvasElement | null;+ }+ get container(): HTMLElement | null { return this.canvas?.parentElement ?? null; }++ pause(): void { this.paused_ = true; }+ resume(): void { this.paused_ = false; }+ step(): void { /* a frame is the engine's to run */ }++ restart(): Promise<void> {+ this.emit(EVENTS.EVENT_RESTART);+ if (typeof location !== 'undefined' && typeof location.reload === 'function') location.reload();+ return Promise.resolve();+ }+ end(): void {+ if (typeof window !== 'undefined' && typeof window.close === 'function') window.close();+ }++ addPersistRootNode(node: Node): void { this.persist_.add(node); }+ removePersistRootNode(node: Node): void { this.persist_.delete(node); }+ isPersistRootNode(node: Node): boolean { return this.persist_.has(node); }++ /** The platform's show / hide / low-memory notices are bound when a script first asks to hear one. */+ override on(type: string, callback: (...args: any[]) => void, target?: unknown): typeof callback {+ this.bind_();+ return super.on(type, callback, target);+ }++ private bind_(): void {+ if (this.bound_ || !isPlatformInitialized()) return;+ this.bound_ = true;+ try {+ platformOnAppShow(() => this.emit(EVENTS.EVENT_SHOW));+ platformOnAppHide(() => this.emit(EVENTS.EVENT_HIDE));+ platformOnMemoryWarning(() => this.emit(EVENTS.EVENT_LOW_MEMORY));+ } catch {+ // a platform without these notices: the events simply never fire+ }+ }++ /** @internal Called by the frame loop. */+ _tick(delta: number, elapsed: number): void {+ this.deltaTime = delta;+ this.totalTime = elapsed;+ this.frameStartTime = isPlatformInitialized() ? platformNow() : (typeof performance !== 'undefined' ? performance.now() : Date.now());+ }+}++export const game = new Game();++/** Register the system that feeds the game clock. */+export function declareGameSystem(): void {+ const system = defineSystem(+ [Res(Time)],+ (time) => { game._tick(time.delta, time.elapsed); },+ { name: 'Cocos:Game', touches: { opaque: true } },+ );+ addSystemToSchedule(Schedule.First, system);+}diff --git a/sdk/src/cocos/index.ts b/sdk/src/cocos/index.tsindex 71a18ad00..2dabd4d2f 100644--- a/sdk/src/cocos/index.ts+++ b/sdk/src/cocos/index.ts@@ -29,6 +29,14 @@ export { UITransform, Label, LabelOutline, LabelShadow, Sprite, UIOpacity, Buttoexport { Touch, EventTouch, pumpTouches } from './input';export { tween, Tween, tweenUtil, easing, updateTweens } from './tween';export { instantiate, loadPrefab, providePrefab } from './prefabs';+export { sys } from './sys';+export { macro } from './macro';+export { Layers } from './layers';+export { view, View, ResolutionPolicy, screen } from './view';+export { game, Game } from './game';+export { input, Input, KeyCode, EventKeyboard, EventMouse } from './inputApi';+export { Emitter as EventTarget } from './emitter';+export { assetManager, AssetManager, Bundle, Cache, resources, setResourceManifest, type ResourceManifest, type ResourceEntry } from './assetManager';export { declareBuiltinScripts, redeclareBuiltinScripts } from './builtinScripts';/** `cc/env` is the same module here: its flags are named exports beside the rest. */export * from './env';diff --git a/sdk/src/cocos/input.ts b/sdk/src/cocos/input.tsindex ed30782b9..b2e46b110 100644--- a/sdk/src/cocos/input.ts+++ b/sdk/src/cocos/input.ts@@ -27,6 +27,7 @@ import { Vec2 } from './math';import { Node, touchListeningEntities } from './node';import { UITransform } from './ui/uiTransform';import { log } from '../util/logger';+import { EventKeyboard, EventMouse, input as globalInput, keyCodeOf, Input as InputApi } from './inputApi';/** One finger (or the mouse button) as a script sees it. */export class Touch {@@ -174,28 +175,63 @@ export function pumpTouches(world: World, input: InputState, camera: UICameraDatgesture = { touch, target: hitNode(world, new Vec2(at.x, at.y)) };book.set(p.id, gesture);live.push(touch);+ globalInput.emit(Node.EventType.TOUCH_START, new EventTouch(Node.EventType.TOUCH_START, touch, live));if (gesture.target) dispatch(new EventTouch(Node.EventType.TOUCH_START, touch, live), gesture.target);}if (!gesture) continue;if (p.down && (at.x !== gesture.touch.getLocationX() || at.y !== gesture.touch.getLocationY())) {gesture.touch._move(at.x, at.y);+ globalInput.emit(Node.EventType.TOUCH_MOVE, new EventTouch(Node.EventType.TOUCH_MOVE, gesture.touch, live));if (gesture.target) dispatch(new EventTouch(Node.EventType.TOUCH_MOVE, gesture.touch, live), gesture.target);}if (p.released) {gesture.touch._move(at.x, at.y);const type = p.cancelled ? Node.EventType.TOUCH_CANCEL : Node.EventType.TOUCH_END;+ globalInput.emit(type, new EventTouch(type, gesture.touch, live));if (gesture.target) dispatch(new EventTouch(type, gesture.touch, live), gesture.target);book.delete(p.id);}}}+// ---------------------------------------------------------------------------------------------------------------------+// Keyboard and mouse, to the global `input`.+// ---------------------------------------------------------------------------------------------------------------------++/** Where each input state's mouse was last frame, so a move is a change and the first frame is not one. */+const lastMouseOf = new WeakMap<InputState, { x: number; y: number }>();++/** Turn this frame's key, button and wheel state into events on the global `input`. Touches are `pumpTouches`'s. */+export function pumpKeysAndMouse(input: InputState, camera: UICameraData): void {+ for (const code of input.keysPressed) globalInput.emit(InputApi.EventType.KEY_DOWN, new EventKeyboard(keyCodeOf(code), InputApi.EventType.KEY_DOWN));+ for (const code of input.keysDown) {+ if (!input.keysPressed.has(code)) globalInput.emit(InputApi.EventType.KEY_PRESSING, new EventKeyboard(keyCodeOf(code), InputApi.EventType.KEY_PRESSING));+ }+ for (const code of input.keysReleased) globalInput.emit(InputApi.EventType.KEY_UP, new EventKeyboard(keyCodeOf(code), InputApi.EventType.KEY_UP));++ const dpr = platformDevicePixelRatio();+ const at = camera.valid ? screenToUiWorld(camera, input.mouseX * dpr, camera.screenH - input.mouseY * dpr) : { x: 0, y: 0 };+ const lastMouse = lastMouseOf.get(input);+ const previous = lastMouse ?? at;+ const moved = lastMouse !== undefined && (at.x !== lastMouse.x || at.y !== lastMouse.y);+ const prev = new Vec2(previous.x, previous.y);+ const event = (type: string): EventMouse => new EventMouse(type, at.x, at.y, prev);+ for (const b of input.mouseButtonsPressed) globalInput.emit(InputApi.EventType.MOUSE_DOWN, event(InputApi.EventType.MOUSE_DOWN)._button(b));+ if (moved) globalInput.emit(InputApi.EventType.MOUSE_MOVE, event(InputApi.EventType.MOUSE_MOVE));+ for (const b of input.mouseButtonsReleased) globalInput.emit(InputApi.EventType.MOUSE_UP, event(InputApi.EventType.MOUSE_UP)._button(b));+ if (input.scrollDeltaX !== 0 || input.scrollDeltaY !== 0) {+ // Cocos reports a wheel turned away from the player as positive; a DOM delta is the other way.+ globalInput.emit(InputApi.EventType.MOUSE_WHEEL, event(InputApi.EventType.MOUSE_WHEEL)._scroll(-input.scrollDeltaX, -input.scrollDeltaY));+ }+ lastMouseOf.set(input, { x: at.x, y: at.y });+}+/** Register the touch system with the engine's frame loop. Idempotent per context is the caller's business: see `declareBuiltinScripts`. */export function declareInputSystem(): void {const system = defineSystem([Res(Input), Res(UICameraInfo), GetWorld()],- (input, camera, world) => { pumpTouches(world, input, camera); },+ (input, camera, world) => { pumpTouches(world, input, camera); pumpKeysAndMouse(input, camera); },{ name: 'Cocos:Input', touches: { opaque: true } },);addSystemToSchedule(Schedule.PreUpdate, system);diff --git a/sdk/src/cocos/inputApi.ts b/sdk/src/cocos/inputApi.tsnew file mode 100644index 000000000..4c05e331d--- /dev/null+++ b/sdk/src/cocos/inputApi.ts@@ -0,0 +1,119 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/inputApi.ts+ * @brief The global `input`: `input.on(Input.EventType.KEY_DOWN, ...)`, the event classes it delivers, and `KeyCode`.+ *+ * Unlike a touch listener on a node, a listener on `input` hears every event whether or not anything is under the pointer. The+ * frame's pointer, key and wheel state is turned into these events by the input system (input.ts); this file is the vocabulary:+ * the event names, `KeyCode` with the numbers Cocos uses, and the objects a handler receives.+ *+ * `KeyCode` has one entry per physical key, and the engine names keys by their DOM `code` (`'KeyA'`, `'ArrowUp'`), so the table+ * below is the pairing of the two; a key the table lacks is delivered as `KeyCode.NONE`.+ */+import { Emitter } from './emitter';+import { Vec2 } from './math';++const KEYS: Array<[name: string, value: number, code: string]> = [];+const key = (name: string, value: number, code: string): void => { KEYS.push([name, value, code]); };++for (let i = 0; i < 26; i++) { const c = String.fromCharCode(65 + i); key(`KEY_${c}`, 65 + i, `Key${c}`); }+for (let i = 0; i < 10; i++) { key(`DIGIT_${i}`, 48 + i, `Digit${i}`); key(`NUM_${i}`, 96 + i, `Numpad${i}`); }+for (let i = 1; i <= 12; i++) key(`F${i}`, 111 + i, `F${i}`);+key('ARROW_LEFT', 37, 'ArrowLeft'); key('ARROW_UP', 38, 'ArrowUp'); key('ARROW_RIGHT', 39, 'ArrowRight'); key('ARROW_DOWN', 40, 'ArrowDown');+key('SPACE', 32, 'Space'); key('ENTER', 13, 'Enter'); key('ESCAPE', 27, 'Escape'); key('TAB', 9, 'Tab'); key('BACKSPACE', 8, 'Backspace');+key('DELETE', 46, 'Delete'); key('INSERT', 45, 'Insert'); key('HOME', 36, 'Home'); key('END', 35, 'End');+key('PAGE_UP', 33, 'PageUp'); key('PAGE_DOWN', 34, 'PageDown'); key('CAPS_LOCK', 20, 'CapsLock');+key('SHIFT_LEFT', 1016, 'ShiftLeft'); key('SHIFT_RIGHT', 2016, 'ShiftRight');+key('CTRL_LEFT', 1017, 'ControlLeft'); key('CTRL_RIGHT', 2017, 'ControlRight');+key('ALT_LEFT', 1018, 'AltLeft'); key('ALT_RIGHT', 2018, 'AltRight');+key('SEMICOLON', 186, 'Semicolon'); key('EQUAL', 187, 'Equal'); key('COMMA', 188, 'Comma'); key('DASH', 189, 'Minus');+key('PERIOD', 190, 'Period'); key('SLASH', 191, 'Slash'); key('BACKQUOTE', 192, 'Backquote'); key('BRACKET_LEFT', 219, 'BracketLeft');+key('BACKSLASH', 220, 'Backslash'); key('BRACKET_RIGHT', 221, 'BracketRight'); key('QUOTE', 222, 'Quote');+key('NUM_ADD', 107, 'NumpadAdd'); key('NUM_SUBTRACT', 109, 'NumpadSubtract'); key('NUM_MULTIPLY', 106, 'NumpadMultiply');+key('NUM_DIVIDE', 111, 'NumpadDivide'); key('NUM_DECIMAL', 110, 'NumpadDecimal'); key('NUM_LOCK', 144, 'NumLock');++export const KeyCode: Readonly<Record<string, number>> = Object.freeze({+ NONE: 0,+ ...Object.fromEntries(KEYS.map(([name, value]) => [name, value])),+});++const CODE_TO_KEYCODE = new Map(KEYS.map(([, value, code]) => [code, value]));++/** The Cocos key code of a DOM key `code`; `KeyCode.NONE` for a key the table lacks. */+export function keyCodeOf(domCode: string): number { return CODE_TO_KEYCODE.get(domCode) ?? 0; }++const EventType = Object.freeze({+ TOUCH_START: 'touch-start',+ TOUCH_MOVE: 'touch-move',+ TOUCH_END: 'touch-end',+ TOUCH_CANCEL: 'touch-cancel',+ MOUSE_DOWN: 'mouse-down',+ MOUSE_MOVE: 'mouse-move',+ MOUSE_UP: 'mouse-up',+ MOUSE_WHEEL: 'mouse-wheel',+ KEY_DOWN: 'keydown',+ KEY_PRESSING: 'key-pressing',+ KEY_UP: 'keyup',+ DEVICEMOTION: 'devicemotion',+ GAMEPAD_INPUT: 'gamepad-input',+ GAMEPAD_CHANGE: 'gamepad-change',+ HANDLE_INPUT: 'handle-input',+ HMD_INPUT: 'hmd-input',+});++export class EventKeyboard {+ stopped = false;+ constructor(public readonly keyCode: number, public readonly type: string) {}+ get isPressed(): boolean { return this.type !== EventType.KEY_UP; }+ stopPropagation(): void { this.stopped = true; }+ stopPropagationImmediate(): void { this.stopped = true; }+}++export class EventMouse {+ static readonly BUTTON_LEFT = 0;+ static readonly BUTTON_MIDDLE = 1;+ static readonly BUTTON_RIGHT = 2;+ stopped = false;+ private readonly location_: Vec2;+ private prev_: Vec2;+ private scrollX_ = 0;+ private scrollY_ = 0;+ private button_ = 0;++ constructor(public readonly type: string, x = 0, y = 0, prev?: Vec2) {+ this.location_ = new Vec2(x, y);+ this.prev_ = prev ?? new Vec2(x, y);+ }++ /** @internal */ _button(b: number): this { this.button_ = b; return this; }+ /** @internal */ _scroll(x: number, y: number): this { this.scrollX_ = x; this.scrollY_ = y; return this; }++ getButton(): number { return this.button_; }+ getLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.location_.x, this.location_.y); }+ getLocationX(): number { return this.location_.x; }+ getLocationY(): number { return this.location_.y; }+ getUILocation(out: Vec2 = new Vec2()): Vec2 { return this.getLocation(out); }+ getUILocationX(): number { return this.location_.x; }+ getUILocationY(): number { return this.location_.y; }+ getPreviousLocation(out: Vec2 = new Vec2()): Vec2 { return out.set(this.prev_.x, this.prev_.y); }+ getDelta(out: Vec2 = new Vec2()): Vec2 { return out.set(this.location_.x - this.prev_.x, this.location_.y - this.prev_.y); }+ getDeltaX(): number { return this.location_.x - this.prev_.x; }+ getDeltaY(): number { return this.location_.y - this.prev_.y; }+ getScrollX(): number { return this.scrollX_; }+ getScrollY(): number { return this.scrollY_; }+ stopPropagation(): void { this.stopped = true; }+ stopPropagationImmediate(): void { this.stopped = true; }+}++class InputTarget extends Emitter {+ static readonly EventType = EventType;+ readonly EventType = EventType;+ /** Whether the device sends orientation / motion; there is no sensor feed behind it. */+ setAccelerometerEnabled(_enabled: boolean): void { /* no sensor source */ }+ setAccelerometerInterval(_interval: number): void { /* no sensor source */ }+}++/** The `Input` class scripts name for its `EventType`, and the instance `input`. */+export const Input = InputTarget;+export const input = new InputTarget();diff --git a/sdk/src/cocos/layers.ts b/sdk/src/cocos/layers.tsnew file mode 100644index 000000000..72f386526--- /dev/null+++ b/sdk/src/cocos/layers.ts@@ -0,0 +1,53 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/layers.ts+ * @brief `Layers`: the layer bitmask names (`Layers.Enum.UI_2D`), with Cocos's numbers.+ *+ * A node's `layer` is carried as the number a script set; the engine does not cull by it. The numbers matter because scripts+ * compare and combine them (`node.layer & Layers.Enum.UI_2D`).+ */+const Enum = {+ NONE: 0,+ IGNORE_RAYCAST: 1 << 20,+ GIZMOS: 1 << 21,+ EDITOR: 1 << 22,+ UI_3D: 1 << 23,+ SCENE_GIZMO: 1 << 24,+ UI_2D: 1 << 25,+ PROFILER: 1 << 28,+ DEFAULT: 1 << 30,+ ALL: 0xffffffff,+} as Record<string, number>;++const names = new Map<string, number>(Object.entries(Enum));+const bits = new Map<number, string>(Object.entries(Enum).map(([k, v]) => [v, k]));++export const Layers = {+ Enum,+ BitMask: Enum,+ /** The mask of a layer's name, or undefined when there is none. */+ nameToLayer(name: string): number | undefined { return names.get(name); },+ layerToName(layer: number): string | undefined { return bits.get(layer); },+ /** Name a user layer (bit 0..19). */+ addLayer(name: string, bitNum: number): void {+ if (bitNum < 0 || bitNum > 19 || names.has(name)) return;+ const value = 1 << bitNum;+ Enum[name] = value;+ names.set(name, value);+ bits.set(value, name);+ },+ deleteLayer(bitNum: number): void {+ const value = 1 << bitNum;+ const name = bits.get(value);+ if (name === undefined) return;+ delete Enum[name];+ names.delete(name);+ bits.delete(value);+ },+ /** A mask with the given layer names set. */+ makeMaskInclude(includes: number[]): number { return includes.reduce((a, b) => a | b, 0); },+ /** A mask with everything but the given layers set. */+ makeMaskExclude(excludes: number[]): number { return ~excludes.reduce((a, b) => a | b, 0); },+ check(layer: number, mask: number): boolean { return (layer & mask) !== 0; },+};diff --git a/sdk/src/cocos/macro.ts b/sdk/src/cocos/macro.tsnew file mode 100644index 000000000..4b32de344--- /dev/null+++ b/sdk/src/cocos/macro.ts@@ -0,0 +1,49 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/macro.ts+ * @brief `macro`: the constants and engine switches a Cocos script reads.+ *+ * The values are Cocos's. The ones that are switches in Cocos (`ENABLE_MULTI_TOUCH`, the antialiasing flags) are plain properties+ * here, so reading and writing them works; whether they change anything is the engine's own configuration, not this object's.+ */+export const macro = {+ /** `repeat` count that means forever. */+ REPEAT_FOREVER: Number.MAX_VALUE - 1,+ INVALID_INDEX: -1,+ NODE_TAG_INVALID: -1,+ PI: Math.PI,+ PI2: Math.PI * 2,+ FLT_MAX: Number.MAX_VALUE,+ FLT_MIN: Number.MIN_VALUE,+ RAD: Math.PI / 180,+ DEG: 180 / Math.PI,+ UINT_MAX: 0xffffffff,++ ENABLE_MULTI_TOUCH: true,+ ENABLE_TILEDMAP_CULLING: true,+ ENABLE_TRANSPARENT_CANVAS: false,+ ENABLE_WEBGL_ANTIALIAS: true,+ ENABLE_ANTIALIAS_FXAA: false,+ ENABLE_BLOOM: false,+ ENABLE_WEBGL_HIGHP_STRUCT_VALUES: false,+ ENABLE_CULLING: false,+ CLEANUP_IMAGE_CACHE: false,+ SHOW_MESH_WIREFRAME: false,+ SHOW_MESH_NORMAL: false,+ ALLOW_IMAGE_BITMAP: true,+ DOWNLOAD_MAX_CONCURRENT: 64,+ BATCHER2D_MEM_INCREMENT: 144,+ CUSTOM_PIPELINE_NAME: '',+ SUPPORT_TEXTURE_FORMATS: ['.astc', '.pkm', '.pvr', '.webp', '.jpg', '.jpeg', '.bmp', '.png'],++ ORIENTATION_PORTRAIT: 1,+ ORIENTATION_LANDSCAPE: 2,+ ORIENTATION_AUTO: 3,++ TextAlignment: Object.freeze({ LEFT: 0, CENTER: 1, RIGHT: 2 }),+ VerticalTextAlignment: Object.freeze({ TOP: 0, CENTER: 1, BOTTOM: 2 }),++ /** Cocos reads these from a settings file; scripts rarely set them, and a script that does gets what it set back. */+ FIX_ARTIFACTS_BY_STRECHING_TEXEL_TMX: true,+};diff --git a/sdk/src/cocos/prefabs.ts b/sdk/src/cocos/prefabs.tsindex 392bf5f94..823b1c1d1 100644--- a/sdk/src/cocos/prefabs.ts+++ b/sdk/src/cocos/prefabs.ts@@ -31,6 +31,9 @@ const assetsOf = new WeakMap<World, AssetsClass>();const wanted = new Set<string>();const inFlight = new Set<string>();+/** The engine's asset loader for a world, once the frame loop has seen it. */+export function assetsFor(world: World | null): AssetsClass | undefined { return world ? assetsOf.get(world) : undefined; }+/** Start preparing the prefab at @p path, once the engine's asset loader is there to do it. */export function requestPrepare(path: string): void {if (path && !preparedPrefabs.has(path) && !inFlight.has(path)) wanted.add(path);diff --git a/sdk/src/cocos/sys.ts b/sdk/src/cocos/sys.tsnew file mode 100644index 000000000..078f3bde6--- /dev/null+++ b/sdk/src/cocos/sys.ts@@ -0,0 +1,122 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/sys.ts+ * @brief `sys`: what the machine and platform are.+ *+ * Scripts branch on `sys.platform` and `sys.os` to choose paths, payment flows and sdk calls, so the answers have to be the+ * platform the engine is actually running on: the mini-game hosts report themselves, a browser is told apart by its user agent,+ * and `localStorage` is the platform's storage (a mini-game has no `window.localStorage`).+ *+ * Constants keep Cocos's names and its string values for `OS` and `Language`; the `Platform` numbers are this layer's own, since+ * scripts compare them to the enum's members and never to a literal.+ */+import { getPlatformType, platformGetStorageItem, platformNow, platformRemoveStorageItem, platformSetStorageItem } from '../platform';+import { Rect } from './math';++const OS = Object.freeze({+ UNKNOWN: 'Unknown', IOS: 'iOS', ANDROID: 'Android', WINDOWS: 'Windows', LINUX: 'Linux', OSX: 'OS X', OHOS: 'OHOS', OPENHARMONY: 'OpenHarmony',+});++const Platform = Object.freeze({+ UNKNOWN: 0, EDITOR_PAGE: 1, EDITOR_CORE: 2, MOBILE_BROWSER: 3, DESKTOP_BROWSER: 4, WIN32: 5, MACOS: 6, IOS: 7, ANDROID: 8, OHOS: 9,+ OPENHARMONY: 10, WECHAT_GAME: 11, WECHAT_MINI_PROGRAM: 12, BAIDU_MINI_GAME: 13, XIAOMI_QUICK_GAME: 14, ALIPAY_MINI_GAME: 15,+ BYTEDANCE_MINI_GAME: 16, OPPO_MINI_GAME: 17, VIVO_MINI_GAME: 18, HUAWEI_QUICK_GAME: 19, COCOSPLAY: 20, LINKSURE_MINI_GAME: 21,+ QTT_MINI_GAME: 22, XR_VR_MIRROR: 23, XR_AR_MIRROR: 24, XR_HMD: 25,+});++const Language = Object.freeze({+ ENGLISH: 'en', CHINESE: 'zh', FRENCH: 'fr', ITALIAN: 'it', GERMAN: 'de', SPANISH: 'es', DUTCH: 'du', RUSSIAN: 'ru', KOREAN: 'ko',+ JAPANESE: 'ja', HUNGARIAN: 'hu', PORTUGUESE: 'pt', ARABIC: 'ar', NORWEGIAN: 'no', POLISH: 'pl', TURKISH: 'tr', UKRAINIAN: 'uk',+ ROMANIAN: 'ro', BULGARIAN: 'bg', UNKNOWN: 'unknown',+});++const BrowserType = Object.freeze({+ WECHAT: 'wechat', ANDROID: 'androidbrowser', IE: 'ie', EDGE: 'edge', QQ: 'qqbrowser', MOBILE_QQ: 'mqqbrowser', UC: 'ucbrowser',+ UCBS: 'ucbs', BAIDU_APP: 'baiduboxapp', BAIDU: 'baidubrowser', MAXTHON: 'maxthon', OPERA: 'opera', OUPENG: 'oupeng', MIUI: 'miuibrowser',+ FIREFOX: 'firefox', SAFARI: 'safari', CHROME: 'chrome', LIEBAO: 'liebao', QZONE: 'qzone', SOUGOU: 'sogou', HUAWEI: 'huawei', UNKNOWN: 'unknown',+});++const userAgent = (): string => (typeof navigator !== 'undefined' && navigator.userAgent ? navigator.userAgent : '');++function detectOS(): string {+ const ua = userAgent();+ if (/iPhone|iPad|iPod/i.test(ua)) return OS.IOS;+ if (/Android/i.test(ua)) return OS.ANDROID;+ if (/OpenHarmony/i.test(ua)) return OS.OPENHARMONY;+ if (/HarmonyOS|OHOS/i.test(ua)) return OS.OHOS;+ if (/Windows/i.test(ua)) return OS.WINDOWS;+ if (/Mac OS X|Macintosh/i.test(ua)) return OS.OSX;+ if (/Linux|X11/i.test(ua)) return OS.LINUX;+ return OS.UNKNOWN;+}++const MINI_GAME: Record<string, number> = {+ wechat: Platform.WECHAT_GAME, douyin: Platform.BYTEDANCE_MINI_GAME, kuaishou: Platform.BYTEDANCE_MINI_GAME, alipay: Platform.ALIPAY_MINI_GAME,+ huawei: Platform.HUAWEI_QUICK_GAME, bilibili: Platform.UNKNOWN, quickgame: Platform.XIAOMI_QUICK_GAME,+};++function detectPlatform(os: string): number {+ const name = getPlatformType();+ if (name && name in MINI_GAME) return MINI_GAME[name]!;+ if (name === 'native') {+ return os === OS.IOS ? Platform.IOS : os === OS.ANDROID ? Platform.ANDROID : os === OS.WINDOWS ? Platform.WIN32+ : os === OS.OSX ? Platform.MACOS : os === OS.OHOS ? Platform.OHOS : Platform.UNKNOWN;+ }+ if (name === 'web') return os === OS.IOS || os === OS.ANDROID ? Platform.MOBILE_BROWSER : Platform.DESKTOP_BROWSER;+ return Platform.UNKNOWN;+}++/** Storage that falls back to memory where the platform has none, as Cocos's does outside a browser. */+const memory = new Map<string, string>();+const localStorage = {+ getItem(key: string): string | null {+ try { const v = platformGetStorageItem(key); if (v !== null) return v; } catch { /* fall through to memory */ }+ return memory.get(key) ?? null;+ },+ setItem(key: string, value: string): void {+ memory.set(key, String(value));+ try { platformSetStorageItem(key, String(value)); } catch { /* memory holds it */ }+ },+ removeItem(key: string): void {+ memory.delete(key);+ try { platformRemoveStorageItem(key); } catch { /* nothing to remove */ }+ },+ clear(): void { for (const key of [...memory.keys()]) localStorage.removeItem(key); },+};++const os = detectOS();+const platform = detectPlatform(os);+const isMobilePlatform = platform === Platform.MOBILE_BROWSER || platform === Platform.IOS || platform === Platform.ANDROID+ || platform === Platform.OHOS || platform === Platform.OPENHARMONY || (platform >= Platform.WECHAT_GAME && platform <= Platform.QTT_MINI_GAME);++export const sys = {+ OS, Platform, Language, BrowserType,+ os,+ platform,+ language: typeof navigator !== 'undefined' && navigator.language ? navigator.language.toLowerCase() : 'en',+ languageCode: typeof navigator !== 'undefined' && navigator.language ? navigator.language.toLowerCase() : 'en',+ isNative: getPlatformType() === 'native',+ isBrowser: getPlatformType() === 'web',+ isMobile: isMobilePlatform,+ isXR: false,+ isLittleEndian: new Uint8Array(new Uint16Array([1]).buffer)[0] === 1,+ browserType: BrowserType.UNKNOWN as string,+ browserVersion: '',+ osVersion: '',+ osMainVersion: 0,+ isOnline: typeof navigator === 'undefined' || navigator.onLine !== false,+ capabilities: { canvas: true, opengl: true, webp: true, imageBitmap: typeof createImageBitmap !== 'undefined', touches: platform !== Platform.DESKTOP_BROWSER, mouse: platform === Platform.DESKTOP_BROWSER, keyboard: platform === Platform.DESKTOP_BROWSER, accelerometer: false },+ localStorage,+ /** The `width`/`height` of the area free of notches and system bars, in canvas units. */+ getSafeAreaRect(): Rect { return new Rect(0, 0, 0, 0); },+ now(): number { return platformNow(); },+ openURL(url: string): void {+ if (typeof window !== 'undefined' && typeof window.open === 'function') window.open(url);+ },+ dumpRoot(): void { /* the root is the engine's; nothing to dump */ },+ garbageCollect(): void { /* the host's */ },+ restartVM(): void { /* the host's */ },+ getNetworkType(): number { return 0; },+ getBatteryLevel(): number { return 1; },+};diff --git a/sdk/src/cocos/ui/pass.ts b/sdk/src/cocos/ui/pass.tsindex 7430c3d45..c27346a4c 100644--- a/sdk/src/cocos/ui/pass.ts+++ b/sdk/src/cocos/ui/pass.ts@@ -9,16 +9,24 @@* then widgets once more for the ones that follow a size the layouts just set (those set to align every frame).*/import { Schedule, defineSystem, addSystemToSchedule, GetWorld } from '../../ecs/system';+import { Res } from '../../ecs/resource';+import { UICameraInfo } from '../../ui/core/ui-camera-info';import { setCurrentWorld } from '../node';import { alignAllWidgets, declareWidget } from './widget';import { layoutAll, declareLayout } from './layout';+import { setVisibleSize, setWindowPixels } from './screen';export function declareUiPass(): void {declareWidget();declareLayout();const system = defineSystem(- [GetWorld()],- (world) => {+ [Res(UICameraInfo), GetWorld()],+ (camera, world) => {+ // What the UI camera shows is the visible area scripts and widgets measure against; the surface is the window.+ if (camera?.valid) {+ setVisibleSize(camera.worldRight - camera.worldLeft, camera.worldTop - camera.worldBottom);+ setWindowPixels(camera.screenW, camera.screenH);+ }const previous = setCurrentWorld(world);try {alignAllWidgets(world);diff --git a/sdk/src/cocos/ui/screen.ts b/sdk/src/cocos/ui/screen.tsindex a3e420f3b..7a45944f8 100644--- a/sdk/src/cocos/ui/screen.ts+++ b/sdk/src/cocos/ui/screen.ts@@ -2,17 +2,20 @@// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/*** @file cocos/ui/screen.ts- * @brief The rectangle a root UI node aligns to: Cocos's "visible rect".+ * @brief The rectangle a root UI node aligns to (Cocos's "visible rect"), and the window it sits in.** A widget on a node whose parent has no rectangle of its own (the canvas, or anything straight under the scene) aligns to the* visible area of the screen. In an imported scene the engine's world and Cocos's are one space, with the visible area running from- * the origin to its size, so the rectangle is just a width and a height. The host sets it from the real viewport; until it does, it- * is the size of a typical design resolution so a scene still lays out.+ * the origin to its size, so the rectangle is just a width and a height. The frame loop sets it from the UI camera every frame+ * (see pass.ts); until it does, it is the size of a typical design resolution so a scene still lays out.*/let width = 960;let height = 640;let generation = 0;+let windowW = 960;+let windowH = 640;+const listeners: Array<(kind: 'visible' | 'window') => void> = [];/** The visible area's size, in the canvas units scripts see. */export function getVisibleSize(): { width: number; height: number } { return { width, height }; }@@ -23,7 +26,24 @@ export function setVisibleSize(w: number, h: number): void {width = w;height = h;generation++;+ for (const l of [...listeners]) l('visible');}/** Bumps whenever the visible size changes. */export function visibleSizeGeneration(): number { return generation; }++/** The window (the drawing surface) in physical pixels. */+export function getWindowPixels(): { width: number; height: number } { return { width: windowW, height: windowH }; }++export function setWindowPixels(w: number, h: number): void {+ if (w === windowW && h === windowH) return;+ windowW = w;+ windowH = h;+ for (const l of [...listeners]) l('window');+}++/** Hear about a change to either size. Returns the way to stop hearing. */+export function onScreenChange(listener: (kind: 'visible' | 'window') => void): () => void {+ listeners.push(listener);+ return () => { const i = listeners.indexOf(listener); if (i >= 0) listeners.splice(i, 1); };+}diff --git a/sdk/src/cocos/view.ts b/sdk/src/cocos/view.tsnew file mode 100644index 000000000..b61e3a7fd--- /dev/null+++ b/sdk/src/cocos/view.ts@@ -0,0 +1,98 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file cocos/view.ts+ * @brief `view` / `View` and `screen`: the size of what the player sees and of the window it is in.+ *+ * Both are read-mostly. The visible size is whatever the UI camera shows (the frame loop feeds it in; see ui/screen.ts), which in+ * an imported scene is the canvas the script sees. The design resolution is what the project asked for; a script that never set+ * one gets the visible size. Fitting design to window is the engine's screen layout, so the policy setters record the choice and+ * leave the fitting to it.+ *+ * `screen.windowSize` is in physical pixels, as in Cocos, and `view.getFrameSize()` is the same in CSS pixels.+ */+import { platformDevicePixelRatio } from '../platform';+import { Emitter } from './emitter';+import { Rect, Size, Vec2 } from './math';+import { getVisibleSize, getWindowPixels, onScreenChange } from './ui/screen';++const ResolutionPolicy = Object.freeze({ EXACT_FIT: 0, NO_BORDER: 1, SHOW_ALL: 2, FIXED_HEIGHT: 3, FIXED_WIDTH: 4, UNKNOWN: 5 });++const dpr = (): number => platformDevicePixelRatio() || 1;++export class View extends Emitter {+ static readonly instance: View = new View();+ static readonly ResolutionPolicy = ResolutionPolicy;++ private design_: Size | null = null;+ private policy_: number = ResolutionPolicy.UNKNOWN;+ private autoFullScreen_ = false;+ private orientation_ = 3;++ constructor() {+ super();+ // The two sizes change in one place; the events Cocos scripts listen for are named here.+ onScreenChange((kind) => {+ if (kind === 'visible') this.emit('canvas-resize');+ else this.emit('canvas-resize');+ });+ }++ /** The area the player sees, in canvas units. */+ getVisibleSize(): Size { const v = getVisibleSize(); return new Size(v.width, v.height); }+ getVisibleSizeInPixel(): Size { const v = getVisibleSize(); const s = this.getScaleX(); return new Size(v.width * s, v.height * s); }+ getVisibleOrigin(): Vec2 { return new Vec2(0, 0); }+ getVisibleOriginInPixel(): Vec2 { return new Vec2(0, 0); }+ getViewportRect(): Rect { const w = getWindowPixels(); return new Rect(0, 0, w.width, w.height); }++ getDesignResolutionSize(): Size { return this.design_ ? this.design_.clone() : this.getVisibleSize(); }+ setDesignResolutionSize(width: number, height: number, policy: number = this.policy_): void {+ this.design_ = new Size(width, height);+ this.policy_ = policy;+ this.emit('design-resolution-changed');+ }+ getResolutionPolicy(): number { return this.policy_; }+ setResolutionPolicy(policy: number): void { this.policy_ = policy; }++ /** The window in CSS pixels. */+ getFrameSize(): Size { const w = getWindowPixels(); return new Size(w.width / dpr(), w.height / dpr()); }+ setFrameSize(_w: number, _h: number): void { /* the host's window */ }+ getCanvasSize(): Size { const w = getWindowPixels(); return new Size(w.width, w.height); }+ setCanvasSize(_w: number, _h: number): void { /* the host's canvas */ }++ /** Window pixels per canvas unit. */+ getScaleX(): number { const v = getVisibleSize(); return v.width > 0 ? getWindowPixels().width / v.width : 1; }+ getScaleY(): number { const v = getVisibleSize(); return v.height > 0 ? getWindowPixels().height / v.height : 1; }+ getDevicePixelRatio(): number { return dpr(); }++ isAutoFullScreenEnabled(): boolean { return this.autoFullScreen_; }+ enableAutoFullScreen(enabled: boolean): void { this.autoFullScreen_ = enabled; }+ isAntiAliasEnabled(): boolean { return true; }+ enableAntiAlias(_enabled: boolean): void { /* a configuration of the engine */ }+ resizeWithBrowserSize(_enabled: boolean): void { /* the host decides */ }+ adjustViewportMeta(_enabled: boolean): void { /* the page's */ }+ setOrientation(orientation: number): void { this.orientation_ = orientation; }+ get orientation(): number { return this.orientation_; }+}++export const view = View.instance;++class Screen extends Emitter {+ /** The window in physical pixels. */+ get windowSize(): Size { const w = getWindowPixels(); return new Size(w.width, w.height); }+ get devicePixelRatio(): number { return dpr(); }+ get supportsFullScreen(): boolean { return false; }+ isFullScreen(): boolean { return false; }+ requestFullScreen(): Promise<void> { return Promise.resolve(); }+ exitFullScreen(): Promise<void> { return Promise.resolve(); }+ autoFullScreen(): Promise<void> { return Promise.resolve(); }+ get resolution(): Size { return this.windowSize; }++ constructor() {+ super();+ onScreenChange((kind) => { if (kind === 'window') this.emit('window-resize', this.windowSize.width, this.windowSize.height); });+ }+}++export const screen = new Screen();+export { ResolutionPolicy };diff --git a/sdk/tests/cocos/globals-wasm.test.ts b/sdk/tests/cocos/globals-wasm.test.tsnew file mode 100644index 000000000..75494613b--- /dev/null+++ b/sdk/tests/cocos/globals-wasm.test.ts@@ -0,0 +1,136 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The global `input`, the game clock, and the visible size, fed by the real frame loop.+ *+ * A listener on `input` hears every touch, key and mouse event whether or not anything is under the pointer; keys arrive as Cocos+ * key codes; the wheel is reported with Cocos's sign; the game clock advances with the engine's; and the visible size scripts read+ * is what the UI camera shows.+ */+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';+import type { ESEngineModule } from '../../src/wasm';+import { App, flushPendingRegistrations } from '../../src/app/app';+import { ensureBuiltinComponentsRegistered } from '../../src/ecs/component';+import { AppContext, setDefaultContext } from '../../src/ecs/context';+import { InputState } from '../../src/input/input';+import { UICameraInfo } from '../../src/ui/core/ui-camera-info';+import { resetClassRegistry } from '../../src/cocos/registry';+import { declareBuiltinScripts } from '../../src/cocos/builtinScripts';+import { pumpKeysAndMouse, pumpTouches } from '../../src/cocos/input';+import {+ EventKeyboard, EventMouse, EventTouch, Input, KeyCode, game, input, screen, setCurrentWorld, view,+} from '../../src/cocos';+import { HAS_WASM, loadWasmModule } from '../helpers/loadWasm';++vi.mock('../../src/ui/util/ui-pick', () => ({ screenToUiWorld: (_cam: unknown, glX: number, glY: number) => ({ x: glX, y: glY }) }));++const camera = { valid: true, screenH: 800 } as never;++describe.skipIf(!HAS_WASM)('input, game and view from the frame loop', () => {+ let module: ESEngineModule;+ let registry: InstanceType<ESEngineModule['Registry']> | undefined;+ let app: App | undefined;++ beforeAll(async () => { ensureBuiltinComponentsRegistered(); module = await loadWasmModule(); });+ afterEach(() => {+ input.targetOff(undefined);+ for (const t of Object.values(Input.EventType)) input.off(t);+ setCurrentWorld(null);+ app?.world.disconnectCpp();+ registry?.delete();+ app = undefined;+ registry = undefined;+ });++ function boot(): void {+ setDefaultContext(new AppContext());+ ensureBuiltinComponentsRegistered();+ resetClassRegistry();+ declareBuiltinScripts();+ registry = new module.Registry();+ app = App.new();+ app.connectCpp(registry as never, module);+ flushPendingRegistrations(app);+ setCurrentWorld(app.world);+ }++ it('tells a listener on input about every touch, wherever it lands', () => {+ boot();+ const state = new InputState();+ const log: string[] = [];+ for (const t of [Input.EventType.TOUCH_START, Input.EventType.TOUCH_MOVE, Input.EventType.TOUCH_END]) {+ input.on(t, (e: EventTouch) => log.push(`${t}@${Math.round(e.getUILocationX())},${Math.round(e.getUILocationY())}`));+ }+ const at = (x: number, y: number) => ({ id: 1, x, y: 800 - y });+ state.touches.set(1, at(300, 200)); state.touchesStarted.set(1, at(300, 200));+ pumpTouches(app!.world, state, camera);+ state.touchesStarted.clear();+ state.touches.set(1, at(320, 200));+ pumpTouches(app!.world, state, camera);+ state.touches.delete(1); state.touchesEnded.set(1, at(320, 200));+ pumpTouches(app!.world, state, camera);+ expect(log).toEqual(['touch-start@300,200', 'touch-move@320,200', 'touch-end@320,200']);+ });++ it('turns key state into KEY_DOWN, KEY_PRESSING and KEY_UP with Cocos key codes', () => {+ boot();+ const state = new InputState();+ const log: string[] = [];+ for (const t of [Input.EventType.KEY_DOWN, Input.EventType.KEY_PRESSING, Input.EventType.KEY_UP]) {+ input.on(t, (e: EventKeyboard) => log.push(`${t}:${e.keyCode}:${e.isPressed}`));+ }+ state.noteKeyDown('KeyA');+ pumpKeysAndMouse(state, camera);+ state.keysPressed.clear();+ pumpKeysAndMouse(state, camera); // held+ state.noteKeyUp('KeyA');+ pumpKeysAndMouse(state, camera);+ expect(log).toEqual([+ `keydown:${KeyCode.KEY_A}:true`,+ `key-pressing:${KeyCode.KEY_A}:true`,+ `keyup:${KeyCode.KEY_A}:false`,+ ]);+ });++ it('turns the mouse into MOUSE_DOWN / MOVE / UP / WHEEL, with the wheel signed as Cocos signs it', () => {+ boot();+ const state = new InputState();+ const log: string[] = [];+ input.on(Input.EventType.MOUSE_DOWN, (e: EventMouse) => log.push(`down:${e.getButton()}@${e.getUILocationX()},${e.getUILocationY()}`));+ input.on(Input.EventType.MOUSE_MOVE, (e: EventMouse) => log.push(`move:${e.getDeltaX()}`));+ input.on(Input.EventType.MOUSE_UP, (e: EventMouse) => log.push(`up:${e.getButton()}`));+ input.on(Input.EventType.MOUSE_WHEEL, (e: EventMouse) => log.push(`wheel:${e.getScrollY()}`));+ state.mouseX = 100; state.mouseY = 700;+ pumpKeysAndMouse(state, camera); // the first frame only learns where the mouse is+ state.noteMouseDown(0);+ pumpKeysAndMouse(state, camera);+ state.mouseButtonsPressed.clear();+ state.mouseX = 130;+ pumpKeysAndMouse(state, camera);+ state.noteMouseUp(0);+ state.scrollDeltaY = 120; // the DOM's "down"+ pumpKeysAndMouse(state, camera);+ expect(log).toEqual(['down:0@100,100', 'move:30', 'up:0', 'wheel:-120']);+ });++ it('advances the game clock with the engine\'s, and lets a script read it', async () => {+ boot();+ await app!.tick(1 / 60);+ const before = game.totalTime;+ await app!.tick(1 / 60);+ await app!.tick(1 / 60);+ expect(game.deltaTime).toBeCloseTo(1 / 60, 4);+ expect(game.totalTime).toBeGreaterThan(before);+ expect(game.frameStartTime).toBeGreaterThan(0);+ });++ it('takes the visible size and the window from what the UI camera shows', async () => {+ boot();+ app!.insertResource(UICameraInfo, {+ valid: true, worldLeft: -640, worldRight: 640, worldBottom: -360, worldTop: 360, screenW: 2560, screenH: 1440,+ } as never);+ await app!.tick(1 / 60);+ expect([view.getVisibleSize().width, view.getVisibleSize().height]).toEqual([1280, 720]);+ expect([screen.windowSize.width, screen.windowSize.height]).toEqual([2560, 1440]);+ });+});diff --git a/sdk/tests/cocos/globals.test.ts b/sdk/tests/cocos/globals.test.tsnew file mode 100644index 000000000..f07fde668--- /dev/null+++ b/sdk/tests/cocos/globals.test.ts@@ -0,0 +1,197 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file The globals a Cocos script reads at startup: `sys`, `macro`, `Layers`, `view`, `screen`, `game`, `KeyCode`, and+ * `resources` / `assetManager`. No engine: what is checked is the values scripts compare against and the shapes they iterate.+ */+import { beforeEach, describe, expect, it } from 'vitest';+import {+ Game, KeyCode, Layers, Prefab, Size, View, assetManager, game, macro, resources, screen, setResourceManifest, setVisibleSize, sys, view,+ providePrefab,+} from '../../src/cocos';+import { keyCodeOf } from '../../src/cocos/inputApi';+import { setWindowPixels } from '../../src/cocos/ui/screen';++describe('sys', () => {+ it('answers in the names scripts compare against', () => {+ expect(Object.values(sys.OS)).toContain(sys.os);+ expect(Object.values(sys.Platform)).toContain(sys.platform);+ expect(sys.OS.IOS).toBe('iOS');+ expect(sys.OS.ANDROID).toBe('Android');+ expect(sys.Platform.WECHAT_GAME).not.toBe(sys.Platform.IOS);+ expect(typeof sys.isNative).toBe('boolean');+ expect(typeof sys.isBrowser).toBe('boolean');+ });++ it('keeps values in localStorage, as strings, and forgets what was removed', () => {+ sys.localStorage.setItem('k', 42 as never);+ expect(sys.localStorage.getItem('k')).toBe('42');+ sys.localStorage.removeItem('k');+ expect(sys.localStorage.getItem('k')).toBeNull();+ sys.localStorage.setItem('a', '1');+ sys.localStorage.clear();+ expect(sys.localStorage.getItem('a')).toBeNull();+ });+});++describe('macro and Layers', () => {+ it('has the constants scripts use', () => {+ expect(macro.REPEAT_FOREVER).toBe(Number.MAX_VALUE - 1);+ expect(macro.TextAlignment.CENTER).toBe(1);+ expect(macro.INVALID_INDEX).toBe(-1);+ });++ it('has Cocos\'s layer numbers, and names layers both ways', () => {+ expect(Layers.Enum.UI_2D).toBe(1 << 25);+ expect(Layers.Enum.DEFAULT).toBe(1 << 30);+ expect(Layers.nameToLayer('UI_2D')).toBe(1 << 25);+ expect(Layers.layerToName(1 << 25)).toBe('UI_2D');+ Layers.addLayer('Boss', 3);+ expect(Layers.nameToLayer('Boss')).toBe(8);+ expect(Layers.check(8 | 1, Layers.makeMaskInclude([8]))).toBe(true);+ expect(Layers.check(1, Layers.makeMaskExclude([1]))).toBe(false);+ Layers.deleteLayer(3);+ expect(Layers.nameToLayer('Boss')).toBeUndefined();+ });+});++describe('view and screen', () => {+ beforeEach(() => { setVisibleSize(960, 640); setWindowPixels(1920, 1280); });++ it('is one View', () => {+ expect(View.instance).toBe(view);+ });++ it('reports the visible size, and the design size as the visible size until one is set', () => {+ expect([view.getVisibleSize().width, view.getVisibleSize().height]).toEqual([960, 640]);+ expect(view.getDesignResolutionSize()).toEqual(new Size(960, 640));+ view.setDesignResolutionSize(750, 1334, View.ResolutionPolicy.FIXED_WIDTH);+ expect(view.getDesignResolutionSize()).toEqual(new Size(750, 1334));+ expect(view.getResolutionPolicy()).toBe(View.ResolutionPolicy.FIXED_WIDTH);+ });++ it('tells a listener when the canvas resizes, once per change', () => {+ let n = 0;+ const cb = (): void => { n++; };+ view.on('canvas-resize', cb);+ setVisibleSize(960, 640); // unchanged+ setVisibleSize(1280, 720);+ view.off('canvas-resize', cb);+ setVisibleSize(1000, 700);+ expect(n).toBe(1);+ });++ it('gives the window in physical pixels, and the frame in CSS pixels', () => {+ expect([screen.windowSize.width, screen.windowSize.height]).toEqual([1920, 1280]);+ expect(view.getFrameSize().width).toBe(1920 / screen.devicePixelRatio);+ expect(view.getScaleX()).toBe(2);+ let seen: number[] = [];+ screen.on('window-resize', (w: number, h: number) => { seen = [w, h]; });+ setWindowPixels(800, 600);+ expect(seen).toEqual([800, 600]);+ });+});++describe('game', () => {+ it('has the event names scripts register for', () => {+ expect(Game.EVENT_HIDE).toBe('game_on_hide');+ expect(Game.EVENT_SHOW).toBe('game_on_show');+ expect(game.isInited).toBe(true);+ });++ it('emits and removes listeners like any event target', () => {+ const seen: unknown[] = [];+ const cb = (x: unknown): void => { seen.push(x); };+ game.on('custom', cb);+ game.emit('custom', 1);+ game.off('custom', cb);+ game.emit('custom', 2);+ expect(seen).toEqual([1]);+ });++ it('keeps persistent roots', () => {+ const node = {} as never;+ game.addPersistRootNode(node);+ expect(game.isPersistRootNode(node)).toBe(true);+ game.removePersistRootNode(node);+ expect(game.isPersistRootNode(node)).toBe(false);+ });+});++describe('KeyCode', () => {+ it('has the numbers of Cocos and finds them from the engine\'s key names', () => {+ expect(KeyCode.KEY_A).toBe(65);+ expect(KeyCode.SPACE).toBe(32);+ expect(KeyCode.ARROW_UP).toBe(38);+ expect(keyCodeOf('KeyW')).toBe(KeyCode.KEY_W);+ expect(keyCodeOf('ArrowLeft')).toBe(KeyCode.ARROW_LEFT);+ expect(keyCodeOf('Digit5')).toBe(KeyCode.DIGIT_5);+ expect(keyCodeOf('MediaPlay')).toBe(KeyCode.NONE);+ });++ it('gives every key its own number', () => {+ const values = Object.values(KeyCode);+ expect(new Set(values).size).toBe(values.length);+ });+});++describe('resources and assetManager', () => {+ const prepared = { ref: 'bullet.esprefab', scene: { version: 4, name: 'bullet', entities: [] } as never, rootId: 0, missing: [], release() {} };+ beforeEach(() => {+ setResourceManifest({+ resources: { 'prefab/bullet': { path: 'bullet.esprefab', kind: 'prefab' }, 'icon/gold': { path: 'gold.png', kind: 'texture' } },+ hero: { 'skin/red': { path: 'red.esprefab', kind: 'prefab' } },+ });+ providePrefab('bullet.esprefab', prepared);+ providePrefab('red.esprefab', prepared);+ });++ const load = <T>(fn: (cb: (e: Error | null, r: T) => void) => void): Promise<{ err: Error | null; result: T }> =>+ new Promise((resolve) => fn((err, result) => resolve({ err, result })));++ it('loads a prefab by its resources path, in any argument order', async () => {+ const a = await load<Prefab>((cb) => resources.load('prefab/bullet', Prefab, cb));+ expect(a.err).toBeNull();+ expect(a.result).toBeInstanceOf(Prefab);+ expect(a.result.path).toBe('bullet.esprefab');+ const b = await load<Prefab>((cb) => resources.load('prefab/bullet', (() => {}) as never, cb));+ expect(b.err).toBeNull();+ const c = await load<Prefab>((cb) => resources.load('prefab/bullet.prefab', cb)); // an extension is ignored+ expect(c.err).toBeNull();+ });++ it('loads a list of paths into a list, and a directory into everything under it that loads', async () => {+ const many = await load<Prefab[]>((cb) => resources.load(['prefab/bullet'], Prefab, cb));+ expect(Array.isArray(many.result)).toBe(true);+ const dir = await load<Prefab[]>((cb) => resources.loadDir('prefab', Prefab, cb));+ expect(dir.result.map((p) => p.path)).toEqual(['bullet.esprefab']);+ });++ it('says what is missing or not supported, instead of answering an empty asset', async () => {+ const missing = await load<unknown>((cb) => resources.load('nope', cb));+ expect(missing.err?.message).toMatch(/no asset "nope"/);+ const texture = await load<unknown>((cb) => resources.load('icon/gold', cb));+ expect(texture.err?.message).toMatch(/not supported/);+ });++ it('has bundles by name, from the manifest', async () => {+ const bundle = await load<{ name: string; load: Function }>((cb) => assetManager.loadBundle('hero', cb));+ expect(bundle.err).toBeNull();+ expect(bundle.result.name).toBe('hero');+ expect(assetManager.getBundle('hero')).toBe(bundle.result);+ const prefab = await load<Prefab>((cb) => (bundle.result as never as { load: Function }).load('skin/red', Prefab, cb));+ expect(prefab.result.path).toBe('red.esprefab');+ const unknown = await load<unknown>((cb) => assetManager.loadBundle('ghost', cb));+ expect(unknown.err?.message).toMatch(/no bundle "ghost"/);+ });++ it('has the caches scripts iterate', async () => {+ await load<Prefab>((cb) => resources.load('prefab/bullet', Prefab, cb));+ expect(assetManager.assets.count).toBeGreaterThan(0);+ let seen = 0;+ assetManager.assets.forEach(() => seen++);+ expect(seen).toBe(assetManager.assets.count);+ expect(assetManager.bundles.find((b) => b.name === 'resources')).toBe(resources);+ expect(assetManager.cacheManager.cachedFiles.count).toBe(0);+ });+});