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.

docs: deepen the Assets guide to a comprehensive treatment

yhh4868b96c487c
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index 2c202ffd8..26e8928f3 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -1,42 +1,70 @@
---
title: Assets
-description: How assets are referenced, cooked, and loaded at runtime.
+description: References, typed loaders, the manifest, addressable groups, and lifetime.
---
import { Aside } from '@astrojs/starlight/components';
Every asset in a project has a stable UUID. Scenes and prefabs reference assets
-by UUID; at build time the engine **cooks** only the assets your game actually
-reaches, and the runtime loads them through a manifest.
+by UUID; at build time the engine **cooks** only what your game reaches, the
+runtime resolves references through a **manifest**, typed **loaders** turn a
+reference into a usable handle, and **reference counting** frees what's no longer
+used. This guide covers each piece.
-## Referencing assets
+## Asset references
Assets are referenced by UUID in the canonical form `@uuid:<uuid>`. The editor
-manages these — you rarely type them by hand.
+manages these — you rarely type them by hand. At runtime a reference is resolved
+to a real file path through the manifest; `assets.resolveRef(ref)` gives you that
+path if you need it.
-## Cooking
+## Loading by type
-Cooking walks the dependency graph from your entry scene(s), **culls anything
-unreachable**, stages the reachable files, and writes `assets.manifest.json`
-(the map the runtime consumes). Optionally it compresses textures: PNGs are
-encoded to GPU-ready **KTX2** (Basis Universal), which the runtime transcodes to
-the best format the device supports (ASTC → ETC2 → S3TC, falling back to RGBA8).
-
-## Loading at runtime
+The `Assets` resource has a typed loader per asset type. Each returns a handle or
+id you put on a component. For example, load a texture and show it on a `Sprite`:
```typescript
-import { defineSystem, Res, Assets } from 'esengine';
+import { defineSystem, Query, Mut, Res, Sprite, Assets } from 'esengine';
-defineSystem([Res(Assets)], async (assets) => {
- // load(type, ref): the asset type plus its @uuid reference
- const texture = await assets.load('texture', '@uuid:a1234567-...');
+const loadArt = defineSystem([Query(Mut(Sprite)), Res(Assets)], async (q, assets) => {
+ const tex = await assets.loadTexture('@uuid:a1b2c3…'); // { handle, width, height }
+ for (const [entity, sprite] of q) {
+ sprite.texture = tex.handle;
+ }
});
```
-## Addressable groups (subpackages)
+| Loader | Returns |
+|---|---|
+| `loadTexture(ref)` | `{ handle, width, height }` |
+| `loadAudio(ref)` | `{ bufferId }` |
+| `loadFont(ref)` | `{ handle }` |
+| `loadMaterial(ref)` | `{ handle, shaderHandle }` |
+| `loadSpine(skeletonRef, atlasRef?)` | `{ skeletonHandle }` |
+| `loadTilemap(ref)` / `loadTileset(ref)` | `{ sourceId }` / `{ tilesetId }` |
+| `loadTimeline(ref)` | `{ timelineId }` |
+| `loadPrefab(ref)` | `{ data }` |
+
+There's also a generic `load<T>(type, ref)` when you're driving the type
+dynamically, and `register(loader)` to add a loader for a custom asset type.
+
+## The manifest
+
+The runtime resolves `@uuid` references to file paths through a manifest:
+
+```typescript
+assets.setManifest(manifest); // usually the runtime does this for you
+```
+
+The manifest is produced by the cook (below). `getManifest()` returns the active
+one. Refs that aren't in the manifest fall back to a direct path lookup.
+
+## Addressable groups (lazy loading)
-Assets under a `subpackages/<name>/…` folder belong to a lazy group `<name>`;
-everything else is the eagerly-loaded `main` group. Load a group on demand:
+Assets under a `subpackages/<name>/…` folder form a lazy group `<name>`;
+everything else is the eagerly-loaded `main` group. Load a group on demand — with
+progress — and it downloads before its assets load (on WeChat this triggers
+`wx.loadSubpackage`; on the web it's a no-op download):
```typescript
const bundle = await assets.loadGroup('level2', (loaded, total) => {
@@ -44,12 +72,31 @@ const bundle = await assets.loadGroup('level2', (loaded, total) => {
});
```
+`loadByLabel(...)` loads assets tagged with a label instead of a folder group.
This grouping is what maps onto [WeChat subpackages](/docs/guides/wechat/) for
on-demand download.
+## Cooking, compression & content addressing
+
+At build time the **cook** walks the dependency graph from your entry scene(s),
+**culls anything unreachable**, stages the reachable files, and writes the
+manifest. Along the way it can:
+
+- **Compress textures** — PNGs are encoded to GPU-ready **KTX2** (Basis
+ Universal), which the runtime transcodes to the best format the device supports
+ (ASTC → ETC2 → S3TC, falling back to RGBA8).
+- **Content-address** — name each shipped file by a hash of its bytes, so URLs
+ are immutable and identical files dedupe to a single copy.
+
+## Lifetime & reference counting
+
+Loaded GPU resources are **reference-counted**. When an entity that uses an asset
+is despawned, its references are released; a byte-budgeted LRU then evicts the
+oldest unreferenced textures when resident VRAM exceeds the budget. You generally
+don't manage this by hand — reference and despawn entities normally.
+
<Aside type="note">
Content hashing runs on the **staged** bytes (after PNG→KTX2 encoding), so the
- manifest hash identifies the shipped artifact and identical files dedupe to one
- copy. Assets under `subpackages/` are always included even if unreachable —
- only their group assignment differs.
+ manifest hash identifies the shipped artifact. Assets under `subpackages/` are
+ always included even if unreachable — only their group assignment differs.
</Aside>
diff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
index 94e6b32f8..85e379b50 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -1,39 +1,65 @@
---
title: 资源
-description: 资源如何被引用、烘焙,以及在运行时加载。
+description: 引用、按类型加载器、清单、寻址组,以及生命周期。
---
import { Aside } from '@astrojs/starlight/components';
-项目里每个资源都有一个稳定的 UUID。场景与预制体按 UUID 引用资源;构建时引擎只**烘焙**
-(cook)你的游戏真正能触达的资源,运行时再通过清单加载它们。
+项目里每个资源都有稳定的 UUID。场景与预制体按 UUID 引用资源;构建时引擎只**烘焙**
+(cook)游戏能触达的部分,运行时通过**清单(manifest)**解析引用,按类型的**加载器**
+把引用变成可用句柄,**引用计数**再释放不再用的资源。本篇逐一讲清。
-## 引用资源
+## 资源引用
-资源以规范形式 `@uuid:<uuid>` 按 UUID 引用。编辑器会管理这些——你几乎不用手写。
+资源以规范形式 `@uuid:<uuid>` 按 UUID 引用。编辑器会管理它们——你几乎不用手写。运行时
+引用会通过清单解析为真实文件路径;需要时 `assets.resolveRef(ref)` 会给你那个路径。
-## 烘焙(cook)
+## 按类型加载
-烘焙从入口场景出发遍历依赖图,**剔除一切触达不到的资源**,暂存可达文件,并写出
-`assets.manifest.json`(运行时消费的映射)。它还可选地压缩纹理:PNG 被编码为 GPU 就绪
-的 **KTX2**(Basis Universal),运行时再转码为设备支持的最佳格式(ASTC → ETC2 → S3TC,
-最后回退到 RGBA8)。
-
-## 运行时加载
+`Assets` 资源为每种资源类型提供一个按类型的加载器。每个返回一个句柄或 id,你把它设到
+组件上。例如加载一张贴图并显示在 `Sprite` 上:
```typescript
-import { defineSystem, Res, Assets } from 'esengine';
+import { defineSystem, Query, Mut, Res, Sprite, Assets } from 'esengine';
-defineSystem([Res(Assets)], async (assets) => {
- // load(type, ref):资源类型 + 它的 @uuid 引用
- const texture = await assets.load('texture', '@uuid:a1234567-...');
+const loadArt = defineSystem([Query(Mut(Sprite)), Res(Assets)], async (q, assets) => {
+ const tex = await assets.loadTexture('@uuid:a1b2c3…'); // { handle, width, height }
+ for (const [entity, sprite] of q) {
+ sprite.texture = tex.handle;
+ }
});
```
-## 可寻址分组(分包)
+| 加载器 | 返回 |
+|---|---|
+| `loadTexture(ref)` | `{ handle, width, height }` |
+| `loadAudio(ref)` | `{ bufferId }` |
+| `loadFont(ref)` | `{ handle }` |
+| `loadMaterial(ref)` | `{ handle, shaderHandle }` |
+| `loadSpine(skeletonRef, atlasRef?)` | `{ skeletonHandle }` |
+| `loadTilemap(ref)` / `loadTileset(ref)` | `{ sourceId }` / `{ tilesetId }` |
+| `loadTimeline(ref)` | `{ timelineId }` |
+| `loadPrefab(ref)` | `{ data }` |
+
+还有一个通用的 `load<T>(type, ref)`,当类型是动态决定时用;以及 `register(loader)`
+为自定义资源类型添加加载器。
+
+## 清单(manifest)
+
+运行时通过清单把 `@uuid` 引用解析为文件路径:
+
+```typescript
+assets.setManifest(manifest); // 通常运行时会替你设好
+```
+
+清单由烘焙(见下)产出。`getManifest()` 返回当前清单。不在清单里的引用会回退到直接
+路径查找。
+
+## 寻址组(懒加载)
-位于 `subpackages/<name>/…` 文件夹下的资源属于惰性分组 `<name>`;其余属于会被急切加载的
-`main` 分组。按需加载某个分组:
+位于 `subpackages/<name>/…` 文件夹下的资源组成惰性分组 `<name>`;其余属于会被急切加载的
+`main` 分组。按需加载某个分组——带进度——它会先下载再加载其中的资源(在微信上会触发
+`wx.loadSubpackage`;在 Web 上下载是空操作):
```typescript
const bundle = await assets.loadGroup('level2', (loaded, total) => {
@@ -41,10 +67,25 @@ const bundle = await assets.loadGroup('level2', (loaded, total) => {
});
```
-正是这种分组映射到[微信分包](/docs/zh-cn/guides/wechat/),实现按需下载。
+`loadByLabel(...)` 按 label 标签加载资源,而不是按文件夹分组。正是这种分组映射到
+[微信分包](/docs/zh-cn/guides/wechat/),实现按需下载。
+
+## 烘焙、压缩与内容寻址
+
+构建时,**烘焙**从入口场景出发遍历依赖图,**剔除一切触达不到的资源**,暂存可达文件,
+并写出清单。过程中它还能:
+
+- **压缩纹理** —— PNG 被编码为 GPU 就绪的 **KTX2**(Basis Universal),运行时再转码为
+ 设备支持的最佳格式(ASTC → ETC2 → S3TC,最后回退 RGBA8)。
+- **内容寻址** —— 每个发布文件按字节哈希命名,于是 URL 不可变,相同文件去重成一份。
+
+## 生命周期与引用计数
+
+加载的 GPU 资源是**引用计数**的。当使用某资源的实体被销毁(despawn)时,它的引用被释放;
+一个按字节预算的 LRU 会在常驻显存超过预算时逐出最旧的未引用纹理。你一般不用手动管理——
+正常引用和销毁实体即可。
<Aside type="note">
- 内容哈希基于**暂存后**的字节(PNG→KTX2 编码之后)计算,因此清单里的哈希标识的是最终
- 发布的产物,相同文件会去重成一份。`subpackages/` 下的资源即使触达不到也总会被包含——
- 只是分组归属不同而已。
+ 内容哈希基于**暂存后**的字节(PNG→KTX2 编码之后)计算,因此清单里的哈希标识的是最终
+ 发布的产物。`subpackages/` 下的资源即使触达不到也总会被包含——只是分组归属不同。
</Aside>