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: round out the Assets guide (VRAM budget, best practices, links)

yhhcdfcf5cbb4d3
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index 137b620b8..8b0dd9ce2 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -103,8 +103,36 @@ 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.
+Cap resident texture memory with `setTextureBudget` — the LRU evicts oldest
+unreferenced textures once resident VRAM crosses it:
+
+```typescript
+import { setTextureBudget } from 'esengine';
+
+setTextureBudget(256 * 1024 * 1024); // 256 MB texture budget
+```
+
+## Best practices
+
+- **Reference by path in code, let the editor write `@uuid:`** — never hand-author
+ UUID refs.
+- **Preload with `loadGroup` / `loadByLabel`** at level boundaries so play doesn't
+ stall mid-scene.
+- **Put on-demand content under `subpackages/<name>/`** so it becomes a lazy group
+ (and a WeChat subpackage) instead of bloating the main bundle.
+- **Let cooking cull + compress** — reachable-only staging and PNG→KTX2 keep the
+ shipped bundle small; don't ship raw PNGs you can cook.
+- **Set a texture budget** on memory-constrained targets and trust reference
+ counting for the rest.
+
<Aside type="note">
Content hashing runs on the **staged** bytes (after PNG→KTX2 encoding), so the
manifest hash identifies the shipped artifact. Assets under `subpackages/` are
always included even if unreachable — only their group assignment differs.
</Aside>
+
+## See also
+
+- [WeChat MiniGame](/docs/guides/wechat/) — how addressable groups map to subpackages.
+- [Scenes](/docs/guides/scene/) — scenes reference assets and are cooked as entry points.
+- [Materials & Shaders](/docs/guides/material/) — `loadMaterial` and shader handles.
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 667bc917d..4b320f2d1 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -92,7 +92,30 @@ const bundle = await assets.loadGroup('level2', (loaded, total) => {
一个按字节预算的 LRU 会在常驻显存超过预算时逐出最旧的未引用纹理。你一般不用手动管理——
正常引用和销毁实体即可。
+用 `setTextureBudget` 限制常驻纹理内存——常驻显存越过它后,LRU 会逐出最旧的未引用纹理:
+
+```typescript
+import { setTextureBudget } from 'esengine';
+
+setTextureBudget(256 * 1024 * 1024); // 256 MB texture budget
+```
+
+## 最佳实践
+
+- **代码里按路径引用,让编辑器写 `@uuid:`**——绝不手写 UUID 引用。
+- **在关卡边界用 `loadGroup` / `loadByLabel` 预加载**,别让游戏在场景中途卡顿。
+- **把按需内容放到 `subpackages/<name>/` 下**,它就成为一个 lazy 组(以及微信子包),而不是
+ 撑大主包。
+- **让 cook 去剔除 + 压缩**——只暂存可达资源、PNG→KTX2 让发布包更小;别发能被 cook 的裸 PNG。
+- **在内存受限的目标上设纹理预算**,其余交给引用计数。
+
<Aside type="note">
内容哈希基于**暂存后**的字节(PNG→KTX2 编码之后)计算,因此清单里的哈希标识的是最终
发布的产物。`subpackages/` 下的资源即使触达不到也总会被包含——只是分组归属不同。
</Aside>
+
+## 参见
+
+- [微信小游戏](/docs/zh-cn/guides/wechat/) —— 可寻址分组如何映射到子包。
+- [场景](/docs/zh-cn/guides/scene/) —— 场景引用资源,并作为入口点被 cook。
+- [材质与着色器](/docs/zh-cn/guides/material/) —— `loadMaterial` 与着色器句柄。