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: an asset ref is rooted at the project, not at the assets folder

yhh564f1b701c6a
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/guides/ai.mdx
index 5e06c9f66..e62cdeb8f 100644
--- a/docs/astro/src/content/docs/guides/ai.mdx
+++ b/docs/astro/src/content/docs/guides/ai.mdx
@@ -274,7 +274,7 @@ cmds.spawn()
.insert(NavAgent, {})
.insert(Perceiver, { range: 240 })
.insert(Perception, {})
- .insert(StateMachineAgent, { fsm: 'ai/enemy.esfsm' }); // an editor-authored asset
+ .insert(StateMachineAgent, { fsm: 'assets/ai/enemy.esfsm' }); // an editor-authored asset
```
| `StateMachineAgent` field | Description |
@@ -337,7 +337,7 @@ import { BehaviorTreeAgent } from 'esengine';
cmds.spawn()
.insert(NavAgent, {})
.insert(Perception, {})
- .insert(BehaviorTreeAgent, { bt: 'ai/enemy.esbt' }); // an editor-authored asset
+ .insert(BehaviorTreeAgent, { bt: 'assets/ai/enemy.esbt' }); // an editor-authored asset
```
| `BehaviorTreeAgent` field | Description |
diff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/guides/animation.mdx
index e84d35ab6..a4f98c182 100644
--- a/docs/astro/src/content/docs/guides/animation.mdx
+++ b/docs/astro/src/content/docs/guides/animation.mdx
@@ -80,7 +80,7 @@ import { defineSystem, Res, SpriteAnimation } from 'esengine';
const listen = defineSystem([Res(SpriteAnimation)], (anim) => {
anim.onEvent(playerEntity, (e) => {
- if (e.name === 'footstep') audio.playSFX('sfx/step.wav');
+ if (e.name === 'footstep') audio.playSFX('assets/sfx/step.wav');
});
});
```
@@ -163,14 +163,14 @@ import {
} from 'esengine';
const registerRun = defineSystem([Res(Assets), Res(SpriteAnimation)], async (assets, sprites) => {
- const tex = await assets.loadTexture('textures/run-sheet.png');
+ const tex = await assets.loadTexture('assets/textures/run-sheet.png');
// A 32×32 grid over the sheet; frames reference grid cells (row-major).
- const data = createAnimClip('textures/run-sheet.png', 32, 32, tex.width, tex.height);
+ const data = createAnimClip('assets/textures/run-sheet.png', 32, 32, tex.width, tex.height);
data.fps = 10;
for (let cell = 0; cell < 6; cell++) data.frames.push({ cell });
- const handles = new Map([['textures/run-sheet.png', tex.handle]]);
+ const handles = new Map([['assets/textures/run-sheet.png', tex.handle]]);
sprites.registerClip(parseAnimClipData('run', data, handles));
// Any SpriteAnimator can now set clip = 'run'.
});
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/guides/assets.mdx
index a288ca9e6..cb2f1a0b8 100644
--- a/docs/astro/src/content/docs/guides/assets.mdx
+++ b/docs/astro/src/content/docs/guides/assets.mdx
@@ -14,12 +14,17 @@ used. This guide covers each piece.
## Referencing assets
In code, reference an asset by its **project-relative path** — readable, and what
-you'll normally write:
+you'll normally write. The path is relative to the **project root**, not to the
+assets folder, so it starts with `assets/` — the spelling the Content Browser
+shows and the one the cook's manifest keys on:
```typescript
-const tex = await assets.loadTexture('textures/player.png');
+const tex = await assets.loadTexture('assets/textures/player.png');
```
+A ref that drops the root (`'textures/player.png'`) resolves against the project
+root all the same, finds nothing there, and fails the load with a 404.
+
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
@@ -35,7 +40,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('textures/player.png'); // { handle, width, height }
+ const tex = await assets.loadTexture('assets/textures/player.png'); // { handle, width, height }
for (const [entity, sprite] of q) {
sprite.texture = tex.handle;
}
@@ -60,7 +65,7 @@ A `.json` that is not a Spine skeleton or a DragonBones pair is a **data asset**
game's own tables, tuning and dialogue. It loads like anything else:
```typescript
-const { data } = await assets.loadJson<LevelTable>('data/levels.json');
+const { data } = await assets.loadJson<LevelTable>('assets/data/levels.json');
```
`T` is what you expect the file to hold; nothing validates it, so this is `JSON.parse`'s
@@ -127,7 +132,7 @@ and loads through the same typed channels with bounded concurrency:
```typescript
const { failed } = await assets.preload(
- ['textures/boss.png', 'audio/boss-theme.mp3', 'maps/arena.estilemap'],
+ ['assets/textures/boss.png', 'assets/audio/boss-theme.mp3', 'assets/maps/arena.estilemap'],
(loaded, total) => console.log(`${loaded}/${total}`),
);
```
diff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/guides/particle.mdx
index 482fd28a0..d6816c27a 100644
--- a/docs/astro/src/content/docs/guides/particle.mdx
+++ b/docs/astro/src/content/docs/guides/particle.mdx
@@ -270,7 +270,7 @@ over each particle's life:
```typescript
.insert(ParticleEmitter, {
- texture: 'effects/explosion.png',
+ texture: 'assets/effects/explosion.png',
spriteColumns: 4, spriteRows: 4, spriteFPS: 24, spriteLoop: false,
});
```
diff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/guides/prefab.mdx
index 9d236d334..793bd9507 100644
--- a/docs/astro/src/content/docs/guides/prefab.mdx
+++ b/docs/astro/src/content/docs/guides/prefab.mdx
@@ -104,7 +104,7 @@ tree — `root` is the new root entity:
import { defineSystem, Res, Prefabs } from 'esengine';
const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {
- const { root } = await prefabs.instantiate('prefabs/enemy.esprefab');
+ const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab');
// `root` is the new entity — move it, tag it, give it a Transform position…
});
```
@@ -115,7 +115,7 @@ Nest the instance under another entity, and use the returned `entities` map to r
children by their prefab-local id:
```typescript
-const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab', {
+const { root, entities } = await prefabs.instantiate('assets/prefabs/turret.esprefab', {
parent: mountPointEntity,
});
// root → the instance root
@@ -130,7 +130,7 @@ targets a prefab entity by its **string** `prefabEntityId` (a UUID for
editor-authored prefabs) and names the component + property:
```typescript
-const { root } = await prefabs.instantiate('prefabs/enemy.esprefab', {
+const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {
overrides: [
{ prefabEntityId: '0', type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
],
diff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/guides/sprites.mdx
index 1d1489ae5..aea2c0d47 100644
--- a/docs/astro/src/content/docs/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/guides/sprites.mdx
@@ -20,7 +20,7 @@ sprite:
import { defineSystem, Commands, Res, Query, Mut, Transform, Sprite, Assets } from 'esengine';
const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets) => {
- const tex = await assets.loadTexture('textures/player.png'); // { handle, width, height }
+ const tex = await assets.loadTexture('assets/textures/player.png'); // { handle, width, height }
cmds.spawn()
.insert(Transform, { position: { x: 0, y: 0, z: 0 } })
.insert(Sprite, { texture: tex.handle, size: { x: tex.width, y: tex.height } });
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/guides/timeline.mdx
index adda6e10b..a542b483b 100644
--- a/docs/astro/src/content/docs/guides/timeline.mdx
+++ b/docs/astro/src/content/docs/guides/timeline.mdx
@@ -21,7 +21,7 @@ import { defineSystem, Commands, TimelinePlayer } from 'esengine';
const attach = defineSystem([Commands()], (cmds) => {
cmds.spawn().insert(TimelinePlayer, {
- timeline: 'timelines/intro.estimeline',
+ timeline: 'assets/timelines/intro.estimeline',
playing: true,
speed: 1.0,
wrapMode: 'once',
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
index 486732c14..29e28f3d6 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/ai.mdx
@@ -251,7 +251,7 @@ cmds.spawn()
.insert(NavAgent, {})
.insert(Perceiver, { range: 240 })
.insert(Perception, {})
- .insert(StateMachineAgent, { fsm: 'ai/enemy.esfsm' }); // 一个编辑器编排的资产
+ .insert(StateMachineAgent, { fsm: 'assets/ai/enemy.esfsm' }); // 一个编辑器编排的资产
```
| `StateMachineAgent` 字段 | 说明 |
@@ -311,7 +311,7 @@ import { BehaviorTreeAgent } from 'esengine';
cmds.spawn()
.insert(NavAgent, {})
.insert(Perception, {})
- .insert(BehaviorTreeAgent, { bt: 'ai/enemy.esbt' }); // 一个编辑器编排的资产
+ .insert(BehaviorTreeAgent, { bt: 'assets/ai/enemy.esbt' }); // 一个编辑器编排的资产
```
| `BehaviorTreeAgent` 字段 | 说明 |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
index 8d6253e59..155b6b459 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/animation.mdx
@@ -76,7 +76,7 @@ import { defineSystem, Res, SpriteAnimation } from 'esengine';
const listen = defineSystem([Res(SpriteAnimation)], (anim) => {
anim.onEvent(playerEntity, (e) => {
- if (e.name === 'footstep') audio.playSFX('sfx/step.wav');
+ if (e.name === 'footstep') audio.playSFX('assets/sfx/step.wav');
});
});
```
@@ -149,14 +149,14 @@ import {
} from 'esengine';
const registerRun = defineSystem([Res(Assets), Res(SpriteAnimation)], async (assets, sprites) => {
- const tex = await assets.loadTexture('textures/run-sheet.png');
+ const tex = await assets.loadTexture('assets/textures/run-sheet.png');
// A 32×32 grid over the sheet; frames reference grid cells (row-major).
- const data = createAnimClip('textures/run-sheet.png', 32, 32, tex.width, tex.height);
+ const data = createAnimClip('assets/textures/run-sheet.png', 32, 32, tex.width, tex.height);
data.fps = 10;
for (let cell = 0; cell < 6; cell++) data.frames.push({ cell });
- const handles = new Map([['textures/run-sheet.png', tex.handle]]);
+ const handles = new Map([['assets/textures/run-sheet.png', tex.handle]]);
sprites.registerClip(parseAnimClipData('run', data, handles));
// Any SpriteAnimator can now set clip = 'run'.
});
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 d242ee99b..6cbef3dd3 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/assets.mdx
@@ -11,12 +11,17 @@ import { Aside } from '@astrojs/starlight/components';
## 引用资源
-在代码里,按资源的**项目相对路径**引用它——可读,也是你平常会写的:
+在代码里,按资源的**项目相对路径**引用它——可读,也是你平常会写的。这个路径相对的是
+**项目根目录**,不是 assets 文件夹,所以它以 `assets/` 开头——和内容浏览器里显示的那个
+写法一致,也是烘焙产出的清单所用的键:
```typescript
-const tex = await assets.loadTexture('textures/player.png');
+const tex = await assets.loadTexture('assets/textures/player.png');
```
+少写这层根的引用(`'textures/player.png'`)照样按项目根解析,在那里什么也找不到,
+加载就以 404 失败。
+
而编辑器会把引用序列化进场景/预制体时写成**稳定 UUID**(`@uuid:<uuid>`),这样文件被
改名或移动后引用仍然有效,并自动解析——**`@uuid:` 不是给你手写的,是编辑器写的**。两种
形式所有加载器都认、解析到同一路径。`resolveRef(ref)` 会返回两者解析后的路径。
@@ -30,7 +35,7 @@ const tex = await assets.loadTexture('textures/player.png');
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('textures/player.png'); // { handle, width, height }
+ const tex = await assets.loadTexture('assets/textures/player.png'); // { handle, width, height }
for (const [entity, sprite] of q) {
sprite.texture = tex.handle;
}
@@ -58,7 +63,7 @@ const loadArt = defineSystem([Query(Mut(Sprite)), Res(Assets)], async (q, assets
游戏自己的数值表、配置、对白。和别的资源一样加载:
```typescript
-const { data } = await assets.loadJson<LevelTable>('data/levels.json');
+const { data } = await assets.loadJson<LevelTable>('assets/data/levels.json');
```
`T` 是你声称这个文件长什么样;没有任何东西校验它,所以这是 `JSON.parse` 的保证,不是 schema 的。
@@ -112,7 +117,7 @@ assets.releaseGroup('level2');
```typescript
const { failed } = await assets.preload(
- ['textures/boss.png', 'audio/boss-theme.mp3', 'maps/arena.estilemap'],
+ ['assets/textures/boss.png', 'assets/audio/boss-theme.mp3', 'assets/maps/arena.estilemap'],
(loaded, total) => console.log(`${loaded}/${total}`),
);
```
diff --git a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
index b9fadebb7..df6ba6bea 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
@@ -257,7 +257,7 @@ const recolor = defineSystem([Res(Particle)], (particles) => {
```typescript
.insert(ParticleEmitter, {
- texture: 'effects/explosion.png',
+ texture: 'assets/effects/explosion.png',
spriteColumns: 4, spriteRows: 4, spriteFPS: 24, spriteLoop: false,
});
```
diff --git a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
index f58954a36..7d0468c7a 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
@@ -86,7 +86,7 @@ Prefab Mode 暂不支持:就地编辑**嵌套**预制体,或基不是扁平的
import { defineSystem, Res, Prefabs } from 'esengine';
const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {
- const { root } = await prefabs.instantiate('prefabs/enemy.esprefab');
+ const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab');
// `root` is the new entity — move it, tag it, give it a Transform position…
});
```
@@ -96,7 +96,7 @@ const spawnEnemy = defineSystem([Res(Prefabs)], async (prefabs) => {
把实例嵌套到另一个实体下,并用返回的 `entities` map 按预制体局部 id 访问子项:
```typescript
-const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab', {
+const { root, entities } = await prefabs.instantiate('assets/prefabs/turret.esprefab', {
parent: mountPointEntity,
});
// root → the instance root
@@ -110,7 +110,7 @@ const { root, entities } = await prefabs.instantiate('prefabs/turret.esprefab',
组件 + 属性:
```typescript
-const { root } = await prefabs.instantiate('prefabs/enemy.esprefab', {
+const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {
overrides: [
{ prefabEntityId: '0', type: 'property', componentType: 'Health', propertyName: 'value', value: 250 },
],
diff --git a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
index f171fdaaa..cf9e3fe8e 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
@@ -18,7 +18,7 @@ import { Aside } from '@astrojs/starlight/components';
import { defineSystem, Commands, Res, Query, Mut, Transform, Sprite, Assets } from 'esengine';
const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets) => {
- const tex = await assets.loadTexture('textures/player.png'); // { handle, width, height }
+ const tex = await assets.loadTexture('assets/textures/player.png'); // { handle, width, height }
cmds.spawn()
.insert(Transform, { position: { x: 0, y: 0, z: 0 } })
.insert(Sprite, { texture: tex.handle, size: { x: tex.width, y: tex.height } });
diff --git a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
index 6dd4ec52d..5f327fb65 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
@@ -19,7 +19,7 @@ import { defineSystem, Commands, TimelinePlayer } from 'esengine';
const attach = defineSystem([Commands()], (cmds) => {
cmds.spawn().insert(TimelinePlayer, {
- timeline: 'timelines/intro.estimeline',
+ timeline: 'assets/timelines/intro.estimeline',
playing: true,
speed: 1.0,
wrapMode: 'once',
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 6b26825f7..7ef6f8d04 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -184,6 +184,22 @@ export interface SceneAssetResult {
export type AssetRefResolver = (ref: string) => string | null;
+/**
+ * The asset server: one typed loader per asset type, over one ref vocabulary.
+ *
+ * Every `ref` a loader takes is one of two spellings, and both land on the same
+ * file:
+ *
+ * - a **project-root-relative path** — `'assets/textures/player.png'`. Relative
+ * to the project root, NOT to the assets folder, so it carries the `assets/`
+ * segment: it is the path the Content Browser shows, the key the cook's
+ * manifest is built on, and what the backend appends to its base url. A ref
+ * that drops the root resolves just the same and 404s, because nothing lives
+ * at the project root.
+ * - an **`@uuid:` ref** — what the editor serializes into scenes and prefabs so
+ * renaming or moving the file breaks nothing. Not hand-written; the realm's
+ * resolver turns it back into the path above before any fetch.
+ */
export class Assets {
readonly backend: Backend;
readonly catalog: Catalog;