A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
/**
* @file android-compat-report.mjs — one APK, every Android version, in one table.
*
* The compatibility matrix runs the SAME binary on one emulator per platform
* version and files a metrics JSON and a screenshot from each. This turns that
* pile into the thing a reviewer actually reads: a row per version, and the
* frames side by side underneath.
*
* The frames are here to be LOOKED AT. Nothing in this file judges a pixel —
* a scene that is legitimately dark and a renderer that died both produce a
* dark PNG, and no threshold tells them apart. What is gated is what can be
* decided without a human: did it install, did the host reach `ready`, did the
* boot record name an error.
*
* node tools/android-compat-report.mjs --dir build/compat --shots-base <url> --out comment.md
*
* `--shots-base` is the URL the screenshots were published under; without it the
* table still renders and the image section says where the artifact is instead.
*/
import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
import path from 'node:path';
function parseArgs(argv) {
const opts = { dir: 'build/compat', out: 'compat-comment.md' };
for (let i = 0; i < argv.length; i++) {
const key = argv[i].replace(/^--/, '').replace(/-([a-z])/g, (_, c) => c.toUpperCase());
opts[key] = argv[++i];
}
return opts;
}
const opts = parseArgs(process.argv.slice(2));
/** Every metrics JSON under `--dir`, at any depth: one artifact per matrix job. */
function collect(dir) {
const found = [];
const walk = (d) => {
for (const e of readdirSync(d, { withFileTypes: true })) {
const p = path.join(d, e.name);
if (e.isDirectory()) walk(p);
else if (e.name.endsWith('.json')) {
try {
found.push(JSON.parse(readFileSync(p, 'utf8')));
} catch {
// A truncated file is a job that died mid-write. Worth saying so
// rather than crashing the report that would have explained it.
found.push({ label: path.basename(p, '.json'), ok: false, why: 'its metrics file is not readable' });
}
}
}
};
if (existsSync(dir)) walk(dir);
return found;
}
const runs = collect(opts.dir);
// No metrics at all means the matrix never ran — the APK build failed, or every
// job died before it could file anything. Still write a comment: failing here
// instead would lose the only place that says so, and leave a red check whose
// cause is in a different job's log.
if (!runs.length) {
mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true });
writeFileSync(opts.out, ['<!-- android-compat -->', '## Android 兼容性', '',
'没有任何版本产出数据 — 说明矩阵没跑起来(APK 构建失败,或每个 job 都在写结果前就死了)。',
'原因在 `apk` / `compat` job 的日志里,不在这里。', ''].join('\n'));
console.error(`no metrics files under ${opts.dir} — wrote a comment saying so`);
process.exit(0);
}
// A version whose job never filed anything must still get a row. The first real
// run lost API 29 to a job timeout and the table simply said "7 versions" — an
// absent row reads as "that version does not exist", which is the one conclusion
// a compatibility matrix must never imply by accident.
if (opts.expect) {
const seen = new Set(runs.map((r) => r.api));
const wanted = String(opts.expect).replace(/[[\]\s]/g, '').split(',').map(Number).filter(Boolean);
for (const api of wanted) {
if (seen.has(api)) continue;
runs.push({
api, release: null, label: `api${api}`, ok: false, missing: true,
why: '没测到 — 这个 job 没跑完(模拟器没启动起来,或 job 超时)',
});
}
}
// API level ascending, so the table reads oldest-first — the direction a
// compatibility floor is read in.
runs.sort((a, b) => (a.api ?? 0) - (b.api ?? 0) || String(a.label).localeCompare(String(b.label)));
const mb = (kb) => (kb === null || kb === undefined ? '—' : `${Math.round(kb / 1024)} MB`);
const ms = (n) => (n === null || n === undefined ? '—' : `${n} ms`);
const pct = (c) => (c?.percent === null || c?.percent === undefined ? '—' : `${c.percent}%`);
const frames = (f) => (!f ? '—' : `${f.medianMs} / ${f.p95Ms} ms`);
// The label is `api<NN>-<example>`; the app column only appears when more than
// one was run, because a column with one repeated value is noise.
const appOf = (r) => String(r.label ?? '').replace(/^api\d+-?/, '') || '—';
// Placeholders for versions that filed nothing carry no app name, and counting
// their '—' as one would flip a single-app run into per-app mode.
const apps = [...new Set(runs.filter((r) => !r.missing).map(appOf))];
const perApp = apps.length > 1;
// `am start -W`'s TotalTime and logcat's "Displayed" are the SAME measurement —
// launch to the activity being fully drawn — and the first run proved it, agreeing
// to the millisecond on all six versions that produced data. Both are still
// collected into the JSON as a cross-check, but showing them as two columns
// claimed two independent clocks where there is one.
const rows = runs.map((r) => {
const s = r.startup ?? {};
return `| ${r.release ?? '?'} | ${r.api ?? '?'} ${perApp ? `| ${appOf(r)} ` : ''}`
+ `| ${ms(s.readyMs)} | ${ms(s.totalMs)} `
+ `| ${mb(r.memory?.totalPssKb)} | ${mb(r.memory?.graphicsKb)} | ${pct(r.cpu)} | ${frames(r.frames)} `
+ `| ${r.ok ? '✓' : `✗ ${r.why || 'failed'}`} |`;
});
const out = [];
out.push('<!-- android-compat -->');
out.push('## Android 兼容性');
out.push('');
const versions = new Set(runs.map((r) => r.api));
const named = apps.filter((a) => a !== '—');
out.push(`${perApp ? `${named.length} 个包` : '同一个包'}${named.length ? `(${named.join('、')})` : ''},`
+ `在 ${versions.size} 个 Android 版本上各跑一台模拟器,每个版本装的是同一个构建产物。`);
out.push('');
// Which template was wrapped changes what a red row means: against the released
// one it is the binary users installed, against a branch build it is a proposed
// fix. Stated because the table is read without the workflow next to it.
if (opts.templateSource === 'release') {
out.push('运行时模板取自**最新 release** —— 也就是用户实际装到手机上的那个二进制。');
} else if (opts.templateSource === 'head') {
out.push('运行时模板**从这个分支构建** —— 测的是这里改的代码,不是已发布的版本。');
}
out.push('');
out.push(`| Android | API ${perApp ? '| app ' : ''}| ready | 启动到首帧 | PSS | Graphics | CPU | 帧间隔 中位/p95 | 结果 |`);
out.push(`|---|---|${perApp ? '---|' : ''}---|---|---|---|---|---|---|`);
out.push(...rows);
out.push('');
// "ran and broke" and "never ran" are different findings and must not share a
// count. The first is a result about Android; the second is a result about this
// pipeline, and reporting them together lets an untested version pass for a
// tested one.
const broken = runs.filter((r) => !r.ok && !r.missing);
const untested = runs.filter((r) => r.missing);
if (broken.length) {
out.push(`**${new Set(broken.map((r) => r.api)).size}/${versions.size} 个 Android 版本装上了但没跑起来。**`);
out.push('');
for (const r of broken) {
out.push(`- **Android ${r.release ?? '?'} (API ${r.api ?? '?'})**`
+ `${perApp ? ` — ${appOf(r)}` : ''} — ${r.why || 'failed'}`);
for (const e of (r.errors ?? []).slice(0, 3)) out.push(` - \`${e.trim()}\``);
}
out.push('');
}
if (untested.length) {
out.push(`**${untested.length} 个版本没有数据 —— 这是关于这条流水线的结论,不是关于 Android 的。**`);
out.push('这些版本既没被证明可用,也没被证明有问题。');
out.push('');
for (const r of untested) out.push(`- **API ${r.api}** — ${r.why}`);
out.push('');
}
out.push('### 截图 — 需要人工看');
out.push('');
out.push('这里没有任何像素判据。上面的表只回答了「装上了、起来了、没报错」;');
out.push('画面对不对只有人能判断。');
out.push('');
if (opts.shotsBase) {
// Two per row: a phone screenshot in a PR comment column is still tall enough
// to see, and eight in a single row would each be a thumbnail nobody can read.
for (let i = 0; i < runs.length; i += 2) {
const pair = runs.slice(i, i + 2);
out.push(`| ${pair.map((r) => `Android ${r.release ?? '?'} (API ${r.api ?? '?'})`
+ (perApp ? ` — ${appOf(r)}` : '')).join(' | ')} |`);
out.push(`|${pair.map(() => '---').join('|')}|`);
out.push(`| ${pair.map((r) => (r.shot
? `<img src="${opts.shotsBase}/${r.shot}" width="260">`
: '_(没有截图)_')).join(' | ')} |`);
out.push('');
}
} else {
out.push('_截图没有发布到可引用的地址,在这次 run 的 artifact 里。_');
out.push('');
}
// The renderer is stated once, because it changes what the numbers mean rather
// than being one of them: a hosted runner has no GPU, so Dawn is on the
// emulator's SwiftShader and every frame time above is a CPU rasteriser's.
// Comparing versions against each other is still valid; reading any of it as
// device performance is not.
const renderers = [...new Set(runs.map((r) => r.renderer).filter(Boolean))];
if (renderers.length) {
out.push('### 这些数字的边界');
out.push('');
out.push(`渲染器:${renderers.map((r) => `\`${r}\``).join(', ')}`);
out.push('');
if (renderers.some((r) => /swiftshader|llvmpipe|software/i.test(r))) {
out.push('**是软件渲染。** runner 没有 GPU,Dawn 跑在模拟器自带的 SwiftShader 上,');
out.push('所以上面的帧间隔是 CPU 光栅化的耗时,GPU 占用和功耗在这里根本不存在。');
out.push('跨版本互相比较仍然有意义,把任何一个数当成真机性能则没有。');
out.push('');
// Now that the row parses, it parses as zero — and a bare 0 invites the
// reading "the renderer allocates nothing", which is not what it means.
if (runs.some((r) => r.memory && r.memory.graphicsKb === 0)) {
out.push('`Graphics` 是 0 也是同一个原因:那一列统计的是 gralloc/GPU 归属的内存,');
out.push('软件渲染下不存在这种分配,Dawn 的缓冲全落在 PSS 的其他分类里。');
out.push('这一列只有在真机上才有意义。');
out.push('');
}
}
}
const noted = runs.filter((r) => (r.notes ?? []).length);
if (noted.length) {
out.push('<details><summary>没测到的项,以及原因</summary>');
out.push('');
for (const r of noted) {
out.push(`- **API ${r.api ?? '?'}** — ${r.notes.join('; ')}`);
}
out.push('');
out.push('</details>');
out.push('');
}
mkdirSync(path.dirname(path.resolve(opts.out)), { recursive: true });
writeFileSync(opts.out, `${out.join('\n')}\n`);
console.log(`${versions.size} version(s): ${broken.length} broken, ${untested.length} untested → ${opts.out}`);
// The verdict comes from the DATA, and only after the comment is on disk.
//
// It used to come from whether the matrix jobs went green, which put it in two
// places that could disagree: a version whose emulator never booted failed its
// job and looked identical to one whose app crashed. The jobs measure; this
// decides. Writing first means a red check always has the table that explains it.
if (broken.length || untested.length) process.exit(2);