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
docs: package size and shipped-game error reporting, in both languages
yhhea4f2c9f4310
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/guides/build-export.mdxindex 5c3783108..380392882 100644--- a/docs/astro/src/content/docs/guides/build-export.mdx+++ b/docs/astro/src/content/docs/guides/build-export.mdx@@ -294,6 +294,66 @@ with [a camera fit](#) so the framing survives either one.See [The Editor](/docs/guides/editor/) for the settings UI.+## Package size++A finished export is weighed, and the result appears under the build log: what the+package costs a player, what it's made of, and which files are the largest.++Three figures, because where the bytes sit matters more than how many there are:++- **Initial** — what a player downloads before the game is playable: the host page,+ the engine runtime, your scripts, and the assets in `local` groups.+- **On demand** — subpackages, fetched when the game asks for that group.+- **CDN (not packaged)** — assets in `remote` groups. Real bytes, but they live on+ your CDN and cost the package nothing. See [Hot Update](/docs/guides/hot-update/).++That split is read from the same manifest the runtime loads, so what the report says+and what the game does cannot disagree. Moving a level behind a subpackage genuinely+removes it from the main package, and the report shows it the moment you do.++### Limits++Where a platform publishes a limit, the build is judged against it and the meter says+which one and where the number came from — quoted, so you can check it against that+platform's current docs rather than trusting us:++| Target | Limit |+| --- | --- |+| WeChat MiniGame | 4MB main package, and 20MB across all subpackages |+| Playable ad | whatever the chosen network accepts — Meta 2MB for a single `index.html`, Google 5MB for a ZIP, etc. |+| Web / Desktop / Android / iOS | none published; set your own below |++A build over a limit is reported, not blocked — it built and it runs, and whether+that's release-blocking is your call (see [the gate](#gating-a-build-on-size) below).+Past 90% of a limit the meter turns amber, because the pass after that is the one+that breaks it.++### Your own budget++**Package Project → Advanced → Size budget** sets a ceiling in MB for the selected+target, saved per platform in `packaging.sizeBudget`. Two reasons to use it: you ship+well under WeChat's 4MB and want to hear about it before it creeps up, or you target a+host whose cap the editor doesn't know.++It **replaces the target's primary limit** — WeChat's 4MB main-package figure becomes+yours — and is attributed to your project rather than quoted as a platform rule. It's+not a waiver: WeChat's 20MB total still applies. Clear the field to go back to the+platform's own limit.++### Gating a build on size++The headless exporter carries the same report on its result and can fail on it:++```bash+node desktop/scripts/export-project.mjs ./my-game \+ --platform wechat --json report.json --enforce-budget+```++With `--enforce-budget`, a package over any limit in force exits non-zero and names+the limit on stderr. Without it, the same facts are reported and the build passes.+The report is `result.size` in the JSON — the same verdicts the dialog draws, so CI+and the editor never disagree about whether a build fits.+## The build CLI (advanced)The editor packages your **game**. The `build-tools/cli.js` command builds thediff --git a/docs/astro/src/content/docs/guides/profiling.mdx b/docs/astro/src/content/docs/guides/profiling.mdxindex e34ead849..40b0069f9 100644--- a/docs/astro/src/content/docs/guides/profiling.mdx+++ b/docs/astro/src/content/docs/guides/profiling.mdx@@ -200,6 +200,131 @@ getLogger().addHandler(crumbs);| `message` | string | The message. || `data` | unknown | Optional payload (object, `Error`, …). |+## Error reporting from a shipped game++Everything above assumes you're watching. After a build ships you aren't: the console+that would show the error is on a player's phone. The **`Diagnostics`** resource+collects what went wrong and hands it to a destination you choose.++**The engine never picks that destination.** There is no default endpoint, no bundled+vendor, and nothing opens a socket on its own. Stack traces carry file paths and+messages carry whatever was interpolated into them, so where that goes is your+decision, not ours. With no sink installed the plugin still does its whole job+locally — events aggregate and you can read them — and nothing leaves the device.++The plugin is installed by default, so this is available without any setup:++```typescript+import { Diagnostics, type DiagnosticEvent } from 'esengine';++const diagnostics = app.getResource(Diagnostics);++diagnostics.setSink((events: readonly DiagnosticEvent[]) => {+ // Batched, distinct problems with counts — not one call per occurrence.+ void fetch('https://your-service.example/errors', {+ method: 'POST',+ body: JSON.stringify({ build: '1.4.2', events }),+ });+});+```++Your sink must not throw (one that does is caught and dropped) and should not block —+awaiting a network round-trip inside it trades a bug report for a stutter. Batch it+and send it yourself.++### What it collects++| Kind | Where it comes from |+|---|---|+| `engine` | Everything the engine logs as an error — a system that threw during a schedule, an asset that would not load, a subsystem that refused to start. |+| `unhandled` | Reached the host with nobody catching it: `window.onerror` / `unhandledrejection`, `wx.onError` / `wx.onUnhandledRejection`. Usually game code outside a system — a callback, a promise, a timer. |+| `context-lost` | The GPU took the rendering context away. The frames after it draw nothing, and no error is thrown — this is the only way to find out it happened. |+| `memory` | The OS says memory is running out: the warning that arrives *before* the process is killed, which is the crash that never gets a report of its own. |+| `game` | Whatever you called `report` about. |++The engine half needs no platform support — it listens to the same log broadcast the+section above describes, which is why installing a `Diagnostics` sink takes nothing+away from `app.onError`, `app.onSystemError` or your own `LogHandler`. They all keep+working. The other kinds need the host to have a signal for them:++| | web | WeChat / mini-game | native (Android / iOS) |+|---|---|---|---|+| `unhandled` | yes | yes | if the shell wires it |+| `memory` | — | yes | if the shell wires it |+| `context-lost` | yes | **no** — a mini-game canvas is not a DOM element and no vendor API reports it | if the shell wires it |++Warnings are not collected by default; pass `captureLevel: LogLevel.Warn` to the+plugin when chasing a specific complaint.++### Distinct problems, not occurrences++A system that throws does it *every frame* — sixty identical reports a second, from+every player at once. Sent one by one that isn't telemetry, it's an outage your game+caused. So the unit is the **distinct problem with a count**:++```typescript+diagnostics.setSink((events) => {+ for (const e of events) {+ console.log(`${e.kind} ${e.source ?? ''}: ${e.message} ×${e.count}`);+ // engine physics: the world could not step ×1842+ }+});+```++Two occurrences are the same problem when their kind, source, message and **throw+site** match. The whole stack would split one bug across its callers; the message+alone would merge two unrelated bugs into one. Numbers in messages are normalized, so+`Entity 41 has no Transform` files one problem rather than one per entity.++| `DiagnosticEvent` field | Type | Description |+|---|---|---|+| `kind` | `DiagnosticKind` | One of the five above. |+| `id` | string | Stable identity across repeats. |+| `message` | string | The message, as reported. |+| `source` | string? | Log category, or the system's name. |+| `stack` | string? | Present when something with a stack was thrown. |+| `count` | number | Occurrences since it was first seen. |+| `firstAt` / `lastAt` | number | Epoch ms, first and most recent. |+| `context` | object? | Whatever the reporter attached; the newest wins. |++### Reporting from your own game++```typescript+diagnostics.report({+ kind: 'game',+ message: 'Cloud save rejected the payload',+ context: { slot: 3, bytes: 41_233 },+});++try { risky(); } catch (err) {+ diagnostics.reportError('game', err, 'shop');+}+```++Keep player-identifying data out of `context` for the same reason the engine picks no+endpoint — it ends up wherever your sink sends it.++### Tuning++```typescript+import { DiagnosticsPlugin } from 'esengine';++app.addPlugin(new DiagnosticsPlugin({+ maxDistinct: 64, // distinct problems tracked at once+ flushIntervalSec: 10, // seconds between handing a batch to the sink+}));+```++At `maxDistinct` new problems are dropped while known ones keep counting, and+`diagnostics.dropped` says how many — a non-zero value means the batch is incomplete,+and a sink should say so rather than let it read as the whole picture. The earliest+distinct problems are the ones kept: when a game comes apart it comes apart in+cascade, and the first failure is what explains the next fifty.++Flushing runs on the engine clock, not a timer, so a backgrounded tab or a suspended+mini-game doesn't report from a game that isn't running. `flush()` sends immediately —+useful right before a level transition — and shutdown flushes once on its own.+## Frame capture — every draw call, explainedWhen "why is this 40 draw calls?" needs an answer, capture a frame. Arm thediff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdxindex 70c28ceae..cef22cfd4 100644--- a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx@@ -233,6 +233,47 @@ mip 链——下载更小、显存更省。设置界面见 [编辑器](/docs/zh-cn/guides/editor/)。+## 包体体积++导出完成后包体会被称重,结果显示在构建日志下方:玩家要为它付出多少、它由什么组成、哪些文件最大。++三个数字,因为字节**待在哪里**比总共多少更重要:++- **首包** —— 玩家在能玩之前必须下载的部分:宿主页面、引擎运行时、你的脚本,以及 `local` 组里的资产。+- **按需分包** —— 分包,在游戏请求那个组时才拉取。+- **CDN(不进包)** —— `remote` 组里的资产。它们是真实存在的字节,但住在你的 CDN 上,对包体零成本。见[热更新](/docs/zh-cn/guides/hot-update/)。++这个划分读自运行时加载的同一份清单,所以报告说的和游戏做的不可能对不上。把一个关卡挪进分包是真的把它移出了主包,报告在你操作后立刻反映出来。++### 上限++凡是平台公布了上限的目标,构建都会被对照判定,并且会说明是哪一条、数字从哪来——原文引用,好让你去核对该平台当前的文档,而不是相信我们:++| 目标 | 上限 |+| --- | --- |+| 微信小游戏 | 主包 4MB,所有分包合计 20MB |+| 试玩广告 | 取决于所选平台 —— Meta 单个 `index.html` 2MB、Google ZIP 5MB 等 |+| 网页 / 桌面 / Android / iOS | 无公开上限;可用下面的方式自定 |++超出上限只报告、不阻断——它构建成功也能跑,是否卡发布由你决定(见下面的[用体积卡构建](#用体积卡构建))。超过上限的 90% 后进度条转为琥珀色,因为再来一轮美术就该破线了。++### 自定预算++**打包项目 → 高级 → 体积预算** 为当前所选目标设置一个 MB 上限,按平台保存在 `packaging.sizeBudget` 里。两种用途:你的包远低于微信 4MB,想在它悄悄涨上去之前就收到提醒;或者你的目标平台上限编辑器并不知道。++它**替换该目标的主上限** —— 微信那条 4MB 主包数字会换成你的 —— 并且归因为"本项目自定的体积预算",而不是伪装成一条平台规则。它不是豁免:微信的 20MB 总量依然生效。清空该字段即恢复平台自身的上限。++### 用体积卡构建++无头导出器的结果里带着同一份报告,并且可以据此失败:++```bash+node desktop/scripts/export-project.mjs ./my-game \+ --platform wechat --json report.json --enforce-budget+```++加上 `--enforce-budget`,任何一条上限被突破都会以非零码退出,并在 stderr 上点名是哪一条;不加则同样报告事实但构建通过。报告就是 JSON 里的 `result.size`——与对话框绘制的是同一批判定,所以 CI 和编辑器永远不会对"这个包放不放得下"给出两种答案。+## 构建 CLI(进阶)编辑器打包你的**游戏**。而 `build-tools/cli.js` 命令构建的是**引擎和 SDK 本身**——你只在要产出上面diff --git a/docs/astro/src/content/docs/zh-cn/guides/profiling.mdx b/docs/astro/src/content/docs/zh-cn/guides/profiling.mdxindex bf7de1ba9..3f9861185 100644--- a/docs/astro/src/content/docs/zh-cn/guides/profiling.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/profiling.mdx@@ -185,6 +185,107 @@ getLogger().addHandler(crumbs);| `message` | string | 消息文本。 || `data` | unknown | 可选负载(对象、`Error`……)。 |+## 已发布游戏的错误上报++上面所有内容都假设你在看着。而游戏发布之后你并不在:那个会打印错误的控制台在玩家手机上。**`Diagnostics`** 资源负责收集出了什么问题,并交给一个**由你指定**的去处。++**引擎绝不替你选择这个去处。** 没有默认端点、没有内置服务商,也不会自己开任何连接。堆栈里带着文件路径,消息里带着被拼接进去的一切,所以这些数据去哪儿是你的决定,不是我们的。没有安装 sink 时插件照常完整工作——事件照样聚合、你随时可读——只是什么都不会离开设备。++该插件**默认已安装**,无需任何配置即可使用:++```typescript+import { Diagnostics, type DiagnosticEvent } from 'esengine';++const diagnostics = app.getResource(Diagnostics);++diagnostics.setSink((events: readonly DiagnosticEvent[]) => {+ // 收到的是带计数的「不同问题」,不是每次发生调用一次。+ void fetch('https://your-service.example/errors', {+ method: 'POST',+ body: JSON.stringify({ build: '1.4.2', events }),+ });+});+```++你的 sink 不能抛异常(抛了会被吞掉),也不该阻塞——在里面 await 一次网络往返,等于拿一份错误报告换了一次卡顿。请自己攒批再发。++### 它收集什么++| 类别 | 来自哪里 |+|---|---|+| `engine` | 引擎作为错误记录的一切 —— 某个 system 在调度中抛异常、某个资产加载不了、某个子系统拒绝启动。 |+| `unhandled` | 没人接住、直接到达宿主的错误:`window.onerror` / `unhandledrejection`、`wx.onError` / `wx.onUnhandledRejection`。通常是 system 之外的游戏代码——回调、promise、定时器。 |+| `context-lost` | GPU 收回了渲染上下文。之后的帧什么也画不出来,而且不会抛任何错误——这是唯一能知道它发生过的途径。 |+| `memory` | 系统提示内存不足:它在进程被杀掉**之前**到达,而那次崩溃本身是永远发不出报告的。 |+| `game` | 你自己调用 `report` 上报的内容。 |++engine 这一半不需要任何平台支持——它监听的正是上一节所说的那条日志广播。所以安装 `Diagnostics` 的 sink 不会从 `app.onError`、`app.onSystemError` 或你自己的 `LogHandler` 那里拿走任何东西,它们照常工作。其余类别则取决于宿主有没有对应信号:++| | 网页 | 微信 / 小游戏 | 原生(Android / iOS) |+|---|---|---|---|+| `unhandled` | 有 | 有 | 需要壳层接入 |+| `memory` | — | 有 | 需要壳层接入 |+| `context-lost` | 有 | **没有** —— 小游戏的 canvas 不是 DOM 元素,也没有厂商 API 报告它 | 需要壳层接入 |++警告默认不收集;排查具体问题时给插件传 `captureLevel: LogLevel.Warn`。++### 是「不同的问题」,不是「每次发生」++一个抛异常的 system 会**每帧**都抛——每秒六十条一模一样的报告,而且是所有玩家同时。逐条发出去那不叫遥测,那是你的游戏自己造出来的事故。所以单位是**带计数的不同问题**:++```typescript+diagnostics.setSink((events) => {+ for (const e of events) {+ console.log(`${e.kind} ${e.source ?? ''}: ${e.message} ×${e.count}`);+ // engine physics: the world could not step ×1842+ }+});+```++当类别、来源、消息和**抛出位置**都相同时,两次发生算同一个问题。用完整堆栈会把一个 bug 按调用者拆成十个;只用消息又会把两个不相干的 bug 并成一个。消息里的数字会被归一化,所以 `Entity 41 has no Transform` 只记一个问题,而不是每个实体一条。++| `DiagnosticEvent` 字段 | 类型 | 说明 |+|---|---|---|+| `kind` | `DiagnosticKind` | 上面五种之一。 |+| `id` | string | 跨重复出现的稳定身份。 |+| `message` | string | 上报时的消息。 |+| `source` | string? | 日志分类,或 system 的名字。 |+| `stack` | string? | 抛出物带堆栈时存在。 |+| `count` | number | 自首次出现以来的发生次数。 |+| `firstAt` / `lastAt` | number | epoch 毫秒,首次与最近一次。 |+| `context` | object? | 上报方附带的数据;以最新的为准。 |++### 上报你自己游戏的问题++```typescript+diagnostics.report({+ kind: 'game',+ message: 'Cloud save rejected the payload',+ context: { slot: 3, bytes: 41_233 },+});++try { risky(); } catch (err) {+ diagnostics.reportError('game', err, 'shop');+}+```++不要把能识别玩家身份的数据放进 `context`,理由和引擎不替你选端点是同一个:它最终会去到你的 sink 送达的任何地方。++### 调节++```typescript+import { DiagnosticsPlugin } from 'esengine';++app.addPlugin(new DiagnosticsPlugin({+ maxDistinct: 64, // 同时跟踪多少个不同问题+ flushIntervalSec: 10, // 每隔多少秒把一批交给 sink+}));+```++达到 `maxDistinct` 后,新问题会被丢弃而已知问题继续计数,`diagnostics.dropped` 告诉你丢了多少——它非零就意味着这批数据并不完整,sink 应当如实说明,而不是让它读起来像全貌。被保留的是**最早**出现的那些:游戏垮掉时是连锁垮的,第一个失败往往解释了后面五十个。++flush 走引擎时钟而非定时器,因此后台标签页或被挂起的小游戏不会从一个根本没在运行的游戏里往外发。`flush()` 可立即发送(比如切关之前),关闭时也会自动发一次。+## 帧捕获 — 每个 draw call 都有解释当"这帧为什么是 40 个 draw call?"需要答案时,捕获一帧。先武装捕获,让一帧渲染