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: lead the Assets guide with path-based loading, not @uuid

yhh2d406a3a3627
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index 26e8928f3..137b620b8 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -11,12 +11,20 @@ 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.
-## Asset references
+## Referencing assets
-Assets are referenced by UUID in the canonical form `@uuid:<uuid>`. The editor
-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.
+In code, reference an asset by its **project-relative path** — readable, and what
+you'll normally write:
+
+```typescript
+const tex = await assets.loadTexture('textures/player.png');
+```
+
+The editor, by contrast, serializes references into scenes and prefabs as a
+**stable UUID** (`@uuid:<uuid>`) so a reference survives the file being renamed or
+moved. Both forms are accepted by every loader and resolve to the same path — you
+don't hand-write `@uuid:` refs, the editor does. `resolveRef(ref)` returns the
+resolved path for either.
## Loading by type
@@ -27,7 +35,7 @@ id you put on a component. For example, load a texture and show it on a `Sprite`
import { defineSystem, Query, Mut, Res, Sprite, Assets } from 'esengine';
const loadArt = defineSystem([Query(Mut(Sprite)), Res(Assets)], async (q, assets) => {
- const tex = await assets.loadTexture('@uuid:a1b2c3…'); // { handle, width, height }
+ const tex = await assets.loadTexture('textures/player.png'); // { handle, width, height }
for (const [entity, sprite] of q) {
sprite.texture = tex.handle;
}
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 85e379b50..667bc917d 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -9,10 +9,17 @@ import { Aside } from '@astrojs/starlight/components';
(cook)游戏能触达的部分,运行时通过**清单(manifest)**解析引用,按类型的**加载器**
把引用变成可用句柄,**引用计数**再释放不再用的资源。本篇逐一讲清。
-## 资源引用
+## 引用资源
-资源以规范形式 `@uuid:<uuid>` 按 UUID 引用。编辑器会管理它们——你几乎不用手写。运行时
-引用会通过清单解析为真实文件路径;需要时 `assets.resolveRef(ref)` 会给你那个路径。
+在代码里,按资源的**项目相对路径**引用它——可读,也是你平常会写的:
+
+```typescript
+const tex = await assets.loadTexture('textures/player.png');
+```
+
+而编辑器会把引用序列化进场景/预制体时写成**稳定 UUID**(`@uuid:<uuid>`),这样文件被
+改名或移动后引用仍然有效,并自动解析——**`@uuid:` 不是给你手写的,是编辑器写的**。两种
+形式所有加载器都认、解析到同一路径。`resolveRef(ref)` 会返回两者解析后的路径。
## 按类型加载
@@ -23,7 +30,7 @@ import { Aside } from '@astrojs/starlight/components';
import { defineSystem, Query, Mut, Res, Sprite, Assets } from 'esengine';
const loadArt = defineSystem([Query(Mut(Sprite)), Res(Assets)], async (q, assets) => {
- const tex = await assets.loadTexture('@uuid:a1b2c3…'); // { handle, width, height }
+ const tex = await assets.loadTexture('textures/player.png'); // { handle, width, height }
for (const [entity, sprite] of q) {
sprite.texture = tex.handle;
}