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.

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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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, Butto
export { 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.ts
index 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: UICameraDat
gesture = { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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);
+ });
+});