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: 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.mdxindex 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.mdxindex 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.mdxindex 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 assetsIn 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 ormoved. 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:```typescriptconst { 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.mdxindex 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.mdxindex 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 rchildren 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 foreditor-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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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');```typescriptconst { 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.mdxindex 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.mdxindex 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.mdxindex 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.mdxindex 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.tsindex 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;