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: 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.mdxindex 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 areference into a usable handle, and **reference counting** frees what's no longerused. 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.mdxindex 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;}