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
fix(assets): two files cannot be the same asset
yhhf3dcc22900fc
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.tsindex aa63556b0..10386b175 100644--- a/desktop/electron/assetDb.ts+++ b/desktop/electron/assetDb.ts@@ -18,6 +18,7 @@*/import { readFile, writeFile, mkdir, readdir, stat } from 'node:fs/promises';import { existsSync } from 'node:fs';+import { randomUUID } from 'node:crypto';import path from 'node:path';import { readTextInRoot } from './projectFs';import { META_EXT, isContentDir, isContentFile, isNonContentPath } from './contentPolicy';@@ -63,12 +64,70 @@ export interface ScanAssetsResult {warnings: string[];/** Orphan content files the scan adopted (minted a `.meta` for) this pass. */adopted: string[];+ /** Files whose `.meta` carried a uuid another file already had, re-minted this+ * pass (see {@link resolveDuplicateUuids}). */+ reminted: string[];/** Per-sub-phase wall time (ms) — surfaced in the renderer boot profile so the* cost of this O(files) scan is visible and attributable (adopt vs meta-walk* vs dependency graph vs write-back). */timingMs?: { adopt: number; walk: number; deps: number; write: number; total: number; files: number };}+/**+ * Give every file its own identity back when two `.meta`s claim the same uuid.+ *+ * A uuid IS the asset's identity: every stored reference is written against it, and+ * the registry is a uuid→path map. Two files sharing one means the map keeps a+ * single winner — so one of the files is not in the registry at all, and every ref+ * to that uuid resolves to the other. Nothing about that is visible: the Content+ * Browser lists files from disk and previews the path it selected, so the picture on+ * screen is right, while the sprite in the scene shows a DIFFERENT image. That is+ * how it gets reported — "what I dropped is not what I see" — and the last place+ * anyone looks is the sidecar.+ *+ * Duplicates arrive in bulk: a folder copied in with its sidecars, a script that+ * stamped one uuid into every meta it wrote, a file duplicated outside the editor.+ *+ * The first file in path order keeps the uuid (deterministic, so a re-scan does not+ * shuffle identities); the rest are re-minted on disk. Re-minting is safe precisely+ * BECAUSE the uuid was ambiguous: no reference to it could have been resolving+ * reliably, and a ref that now fails to resolve says so in diagnostics instead of+ * quietly drawing the wrong thing.+ */+async function resolveDuplicateUuids(+ root: string,+ entries: AssetEntry[],+ warnings: string[],+): Promise<string[]> {+ const owner = new Map<string, string>();+ const reminted: string[] = [];+ for (const entry of entries) {+ const first = owner.get(entry.uuid);+ if (first === undefined) {+ owner.set(entry.uuid, entry.path);+ continue;+ }+ const fresh = randomUUID();+ try {+ const metaPath = path.join(root, `${entry.path}${META_EXT}`);+ const meta = JSON.parse(await readTextInRoot(metaPath)) as Record<string, unknown>;+ meta.uuid = fresh;+ await writeFile(metaPath, `${JSON.stringify(meta, null, 2)}\n`, 'utf8');+ } catch (err) {+ warnings.push(+ `${entry.path}: shares its uuid with ${first} and could not be re-minted `+ + `(${err instanceof Error ? err.message : String(err)}) — it is not addressable`,+ );+ continue;+ }+ warnings.push(`${entry.path}: shared its uuid with ${first}; re-minted as ${fresh}`);+ entry.uuid = fresh;+ owner.set(fresh, entry.path);+ reminted.push(entry.path);+ }+ return reminted;+}+/** Recursively yield every `<file>.meta` path (project-relative, forward-slashed). */async function* walkMeta(root: string, rel = ''): AsyncGenerator<string> {const abs = rel ? path.join(root, rel) : root;@@ -382,6 +441,9 @@ export async function scanAssetDatabase(}entries.sort((a, b) => a.path.localeCompare(b.path));+ // Sorted FIRST: which file keeps a shared uuid has to be the same answer on every+ // machine and every re-scan, and path order is the only stable one here.+ const reminted = await resolveDuplicateUuids(root, entries, warnings);t.walk = performance.now() - tWalk;const tDeps = performance.now();@@ -405,7 +467,7 @@ export async function scanAssetDatabase(`adopt ${timingMs.adopt} / walk ${timingMs.walk} / deps ${timingMs.deps} / write ${timingMs.write}`,);- return { ok: true, outputPath, index, warnings, adopted, timingMs };+ return { ok: true, outputPath, index, warnings, adopted, reminted, timingMs };}/** Above this many changed paths a full rescan is cheaper/safer than per-path@@ -464,7 +526,7 @@ export async function updateAssetIndex(contentPaths.add(content);}if (contentPaths.size === 0) {- return { ok: true, outputPath: null, index: prev, warnings: [], adopted: [], fullRescan: false };+ return { ok: true, outputPath: null, index: prev, warnings: [], adopted: [], reminted: [], fullRescan: false };}const byPath = new Map(prev.entries.map((e) => [e.path, e] as const));@@ -505,6 +567,12 @@ export async function updateAssetIndex(}const entries = [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));+ // Here too, and here MOST: a folder of assets dropped in with their sidecars+ // arrives through the watcher, which is exactly where duplicate uuids come from.+ // Before deps, which are keyed by uuid.+ const warnings: string[] = [];+ const reminted = await resolveDuplicateUuids(root, entries, warnings);+ if (reminted.length > 0) setChanged = true;// Deps: when the entry SET changed, path + bare-uuid resolution is global, so// recompute the whole graph from the new entries (still bounded to ref-carrying@@ -512,7 +580,6 @@ export async function updateAssetIndex(// changed, other assets' edges can't have moved: patch just the touched// ref-assets over the previous graph.let deps: Record<string, string[]>;- const warnings: string[] = [];if (setChanged) {const r = await computeDeps(root, entries);deps = r.deps;@@ -528,5 +595,5 @@ export async function updateAssetIndex(const index: AssetIndex = { version: '1.0', entries, deps };const outputPath = opts?.write !== false ? await writeIndexIfChanged(root, index) : null;- return { ok: true, outputPath, index, warnings, adopted, fullRescan: false };+ return { ok: true, outputPath, index, warnings, adopted, reminted, fullRescan: false };}diff --git a/desktop/scripts/editor-checks/duplicate-uuid.mjs b/desktop/scripts/editor-checks/duplicate-uuid.mjsnew file mode 100644index 000000000..8d7a96697--- /dev/null+++ b/desktop/scripts/editor-checks/duplicate-uuid.mjs@@ -0,0 +1,85 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file duplicate-uuid — two files cannot be the same asset.+ *+ * A `.meta`'s uuid is the identity every stored reference is written against, and+ * nothing checked that two of them were not the same. Assets that arrive in bulk+ * are exactly where that happens: a folder copied in with its sidecars, a script+ * that stamped one uuid into every meta it wrote, a duplicated file.+ *+ * The failure is silent and looks like a rendering bug. `pathToUuid` is per-path so+ * a drag reads the right uuid; `uuidToPath` keeps one winner, so resolving it hands+ * back some OTHER file. The Content Browser preview reads the path it selected and+ * is right; the sprite in the scene reads the ref and is a different picture — which+ * is exactly how it was reported: "what I dropped is not what I see".+ */+import path from 'node:path';+import { cp, writeFile } from 'node:fs/promises';+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';++const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');+const SHARED_UUID = '11111111-2222-3333-4444-555555555555';++const SCENE = JSON.stringify({+ version: '1.0', name: 'Main',+ entities: [{+ id: 0, name: 'Camera', parent: null, children: [], visible: true,+ components: [+ { type: 'Transform', data: { position: { x: 0, y: 0, z: 10 } } },+ { type: 'Camera', data: { projectionType: 1, orthoSize: 300, isActive: true, priority: 0 } },+ ],+ }],+}, null, 1);++const meta = (uuid) => JSON.stringify({ uuid, version: '1.0', type: 'texture', importer: {} }, null, 2);++export const name = 'duplicate-uuid';+export const describes = 'two assets that carry the same uuid are caught, not silently merged';++export async function run(ed) {+ const root = await makeProject({ 'assets/scenes/main.esscene': SCENE });+ await cp(path.join(EXAMPLE, 'project.esproject'), path.join(root, 'project.esproject'));+ await cp(path.join(EXAMPLE, 'src'), path.join(root, 'src'), { recursive: true });+ // Two DIFFERENT pictures, stamped with one identity.+ await cp(path.join(EXAMPLE, 'assets', 'textures', 'star.png'), path.join(root, 'assets', 'dupA.png'));+ await cp(path.join(EXAMPLE, 'assets', 'textures', 'arrow.png'), path.join(root, 'assets', 'dupB.png'));+ await writeFile(path.join(root, 'assets', 'dupA.png.meta'), meta(SHARED_UUID));+ await writeFile(path.join(root, 'assets', 'dupB.png.meta'), meta(SHARED_UUID));+ const check = checker();++ await ed.open(root, 'assets/scenes/main.esscene');++ const listed = await ed.json('list_assets', { match: 'dup' }, 60000);+ const rows = listed?.assets ?? [];+ check(rows.length === 2, `expected both files in the registry, got ${JSON.stringify(rows)}`);+ const refs = new Set(rows.map((a) => a.ref));+ check(+ refs.size === rows.length,+ `${rows.length} files share ${refs.size} ref(s): ${rows.map((a) => `${a.path}=${a.ref}`).join(', ')} `+ + '— a ref that names two files resolves to whichever the scan saw last',+ );++ // And end to end: a sprite pointed at ONE of them must show that one.+ await ed.call('apply_scene_ops', {+ ops: [{+ op: 'create', ref: 'sprite', name: 'Dropped', components: ['Transform', 'Sprite'],+ fields: { 'Sprite.texture': 'assets/dupA.png' },+ }],+ label: 'drop dupA',+ }, 60000);+ const tree = await ed.json('get_scene_tree', {});+ const dropped = tree.find((e) => e.name === 'Dropped');+ if (!check(!!dropped, 'the sprite was not created')) return check.failures;++ const inspector = await ed.json('get_inspector', { entity: dropped.id }, 60000);+ const sprite = inspector.find((c) => c.name === 'Sprite');+ const texture = sprite?.fields?.find((f) => f.key === 'texture');+ const named = JSON.stringify(texture ?? null);+ check(+ !named.includes('dupB'),+ `the sprite was pointed at dupA and the editor reports ${named} — it resolved to the other file`,+ );++ return check.failures;+}diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 7cc63db20..a058a8578 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -776,6 +776,17 @@ class ProjectStoreImpl {scan.adopted,);}+ // Said out loud, because until now the symptom was a picture: a uuid two files+ // claimed resolved to one of them, so a sprite showed something other than the+ // asset it was pointed at, and nothing anywhere mentioned the sidecar.+ if ((scan.reminted?.length ?? 0) > 0) {+ console.warn(+ `[assets] ${scan.reminted.length} file(s) carried a uuid another file already had — re-minted so each `+ + 'is addressable. A reference written against the shared uuid resolved to whichever file the scan saw '+ + 'last; re-check anything that pointed at these.',+ scan.reminted,+ );+ }return scan.index.entries;} catch (err) {console.warn('[project] asset scan failed', err);diff --git a/desktop/tests/asset-db.test.ts b/desktop/tests/asset-db.test.tsindex d87c6bda7..76c26988c 100644--- a/desktop/tests/asset-db.test.ts+++ b/desktop/tests/asset-db.test.ts@@ -179,3 +179,41 @@ describe('scanAssetDatabase — orphan adoption', () => {rmSync(ts); rmSync(pkg);});});++describe('two files that claim the same uuid', () => {+ // A uuid IS the asset's identity: the registry is a uuid→path map, so a shared one+ // keeps a single winner. The other file is then in no registry at all, and every+ // reference to that uuid resolves to whichever the scan saw last — which reaches a+ // user as "the sprite I dropped shows a different picture than the preview".+ it('gives each file its own identity back, on disk, and says so', async () => {+ const shared = '44444444-4444-4444-8444-444444444444';+ writeAsset('assets/bulk/a.png', 'texture', shared, 'A');+ writeAsset('assets/bulk/b.png', 'texture', shared, 'B');+ writeAsset('assets/bulk/c.png', 'texture', shared, 'C');++ const res = await scanAssetDatabase(root, { write: false });+ const bulk = res.index.entries.filter((e) => e.path.startsWith('assets/bulk/'));+ expect(bulk.map((e) => e.path)).toEqual(['assets/bulk/a.png', 'assets/bulk/b.png', 'assets/bulk/c.png']);+ expect(new Set(bulk.map((e) => e.uuid)).size).toBe(3);++ // The FIRST in path order keeps it, so a re-scan does not shuffle identities and+ // whatever already referenced it still resolves.+ expect(bulk[0].uuid).toBe(shared);+ expect(res.reminted.sort()).toEqual(['assets/bulk/b.png', 'assets/bulk/c.png']);+ expect(res.warnings.some((w) => /shared its uuid/.test(w))).toBe(true);++ // Written through, not just fixed in memory — the next scan must agree.+ const uuidOf = (p: string) => JSON.parse(readFileSync(path.join(root, `${p}.meta`), 'utf8')).uuid;+ expect(uuidOf('assets/bulk/b.png')).not.toBe(shared);+ expect(uuidOf('assets/bulk/c.png')).not.toBe(uuidOf('assets/bulk/b.png'));++ const again = await scanAssetDatabase(root, { write: false });+ expect(again.reminted).toEqual([]);+ expect(new Set(again.index.entries.filter((e) => e.path.startsWith('assets/bulk/')).map((e) => e.uuid)).size).toBe(3);++ for (const f of ['a.png', 'b.png', 'c.png']) {+ rmSync(path.join(root, `assets/bulk/${f}`));+ rmSync(path.join(root, `assets/bulk/${f}.meta`));+ }+ });+});diff --git a/docs/astro/src/content/docs/guides/dragonbones.mdx b/docs/astro/src/content/docs/animation/dragonbones.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/dragonbones.mdxrename to docs/astro/src/content/docs/animation/dragonbones.mdxdiff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/animation/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/animation.mdxrename to docs/astro/src/content/docs/animation/overview.mdxdiff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/animation/spine.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/spine.mdxrename to docs/astro/src/content/docs/animation/spine.mdxdiff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/animation/timeline.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/timeline.mdxrename to docs/astro/src/content/docs/animation/timeline.mdxdiff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/audio.mdxrename to docs/astro/src/content/docs/assets/audio.mdxdiff --git a/docs/astro/src/content/docs/guides/localization.mdx b/docs/astro/src/content/docs/assets/localization.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/localization.mdxrename to docs/astro/src/content/docs/assets/localization.mdxdiff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/assets/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/assets.mdxrename to docs/astro/src/content/docs/assets/overview.mdxdiff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/editor/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/editor.mdxrename to docs/astro/src/content/docs/editor/overview.mdxdiff --git a/docs/astro/src/content/docs/guides/agent.mdx b/docs/astro/src/content/docs/extending/built-in-agent.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/agent.mdxrename to docs/astro/src/content/docs/extending/built-in-agent.mdxdiff --git a/docs/astro/src/content/docs/guides/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/editor-plugins.mdxrename to docs/astro/src/content/docs/extending/editor-plugins.mdxdiff --git a/docs/astro/src/content/docs/guides/mcp.mdx b/docs/astro/src/content/docs/extending/mcp.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/mcp.mdxrename to docs/astro/src/content/docs/extending/mcp.mdxdiff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/gameplay/ai.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ai.mdxrename to docs/astro/src/content/docs/gameplay/ai.mdxdiff --git a/docs/astro/src/content/docs/guides/markers.mdx b/docs/astro/src/content/docs/gameplay/markers.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/markers.mdxrename to docs/astro/src/content/docs/gameplay/markers.mdxdiff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/gameplay/physics.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/physics.mdxrename to docs/astro/src/content/docs/gameplay/physics.mdxdiff --git a/docs/astro/src/content/docs/guides/camera.mdx b/docs/astro/src/content/docs/graphics/camera.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/camera.mdxrename to docs/astro/src/content/docs/graphics/camera.mdxdiff --git a/docs/astro/src/content/docs/guides/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/drawing.mdxrename to docs/astro/src/content/docs/graphics/drawing.mdxdiff --git a/docs/astro/src/content/docs/guides/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/lighting.mdxrename to docs/astro/src/content/docs/graphics/lighting.mdxdiff --git a/docs/astro/src/content/docs/guides/material.mdx b/docs/astro/src/content/docs/graphics/materials.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/material.mdxrename to docs/astro/src/content/docs/graphics/materials.mdxdiff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/postprocess.mdxrename to docs/astro/src/content/docs/graphics/post-processing.mdxdiff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/sprites.mdxrename to docs/astro/src/content/docs/graphics/sprites.mdxdiff --git a/docs/astro/src/content/docs/guides/video.mdx b/docs/astro/src/content/docs/graphics/video.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/video.mdxrename to docs/astro/src/content/docs/graphics/video.mdxdiff --git a/docs/astro/src/content/docs/guides/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/profiling.mdxrename to docs/astro/src/content/docs/performance/profiling.mdxdiff --git a/docs/astro/src/content/docs/guides/services.mdx b/docs/astro/src/content/docs/publishing/ads-sharing.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/services.mdxrename to docs/astro/src/content/docs/publishing/ads-sharing.mdxdiff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/mobile.mdxrename to docs/astro/src/content/docs/publishing/android-ios.mdxdiff --git a/docs/astro/src/content/docs/guides/hot-update.mdx b/docs/astro/src/content/docs/publishing/hot-update.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/hot-update.mdxrename to docs/astro/src/content/docs/publishing/hot-update.mdxdiff --git a/docs/astro/src/content/docs/guides/minigame-platforms.mdx b/docs/astro/src/content/docs/publishing/minigame-platforms.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/minigame-platforms.mdxrename to docs/astro/src/content/docs/publishing/minigame-platforms.mdxdiff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/publishing/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/build-export.mdxrename to docs/astro/src/content/docs/publishing/overview.mdxdiff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/publishing/wechat.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/wechat.mdxrename to docs/astro/src/content/docs/publishing/wechat.mdxdiff --git a/docs/astro/src/content/docs/guides/events.mdx b/docs/astro/src/content/docs/scripting/events.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/events.mdxrename to docs/astro/src/content/docs/scripting/events.mdxdiff --git a/docs/astro/src/content/docs/guides/input.mdx b/docs/astro/src/content/docs/scripting/input.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/input.mdxrename to docs/astro/src/content/docs/scripting/input.mdxdiff --git a/docs/astro/src/content/docs/guides/math.mdx b/docs/astro/src/content/docs/scripting/math.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/math.mdxrename to docs/astro/src/content/docs/scripting/math.mdxdiff --git a/docs/astro/src/content/docs/guides/networking.mdx b/docs/astro/src/content/docs/scripting/networking.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/networking.mdxrename to docs/astro/src/content/docs/scripting/networking.mdxdiff --git a/docs/astro/src/content/docs/guides/scripting.mdx b/docs/astro/src/content/docs/scripting/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/scripting.mdxrename to docs/astro/src/content/docs/scripting/overview.mdxdiff --git a/docs/astro/src/content/docs/guides/save.mdx b/docs/astro/src/content/docs/scripting/save.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/save.mdxrename to docs/astro/src/content/docs/scripting/save.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-controllers.mdx b/docs/astro/src/content/docs/ui/controllers.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-controllers.mdxrename to docs/astro/src/content/docs/ui/controllers.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-binding.mdx b/docs/astro/src/content/docs/ui/data-binding.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-binding.mdxrename to docs/astro/src/content/docs/ui/data-binding.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-interaction.mdx b/docs/astro/src/content/docs/ui/interaction.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-interaction.mdxrename to docs/astro/src/content/docs/ui/interaction.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-layout.mdx b/docs/astro/src/content/docs/ui/layout.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-layout.mdxrename to docs/astro/src/content/docs/ui/layout.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-lists.mdx b/docs/astro/src/content/docs/ui/lists.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-lists.mdxrename to docs/astro/src/content/docs/ui/lists.mdxdiff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/ui/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui.mdxrename to docs/astro/src/content/docs/ui/overview.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/ui/text.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-text.mdxrename to docs/astro/src/content/docs/ui/text.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-theme.mdx b/docs/astro/src/content/docs/ui/theming.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-theme.mdxrename to docs/astro/src/content/docs/ui/theming.mdxdiff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/ui/widgets.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/ui-components.mdxrename to docs/astro/src/content/docs/ui/widgets.mdxdiff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/world/particles.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/particle.mdxrename to docs/astro/src/content/docs/world/particles.mdxdiff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/world/prefabs.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/prefab.mdxrename to docs/astro/src/content/docs/world/prefabs.mdxdiff --git a/docs/astro/src/content/docs/guides/scene.mdx b/docs/astro/src/content/docs/world/scenes.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/scene.mdxrename to docs/astro/src/content/docs/world/scenes.mdxdiff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/world/tilemaps.mdxsimilarity index 100%rename from docs/astro/src/content/docs/guides/tilemap.mdxrename to docs/astro/src/content/docs/world/tilemaps.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/dragonbones.mdx b/docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/dragonbones.mdxrename to docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/animation.mdxrename to docs/astro/src/content/docs/zh-cn/animation/overview.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/animation/spine.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/spine.mdxrename to docs/astro/src/content/docs/zh-cn/animation/spine.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/timeline.mdxrename to docs/astro/src/content/docs/zh-cn/animation/timeline.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx b/docs/astro/src/content/docs/zh-cn/assets/audio.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/audio.mdxrename to docs/astro/src/content/docs/zh-cn/assets/audio.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx b/docs/astro/src/content/docs/zh-cn/assets/localization.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/localization.mdxrename to docs/astro/src/content/docs/zh-cn/assets/localization.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/assets.mdxrename to docs/astro/src/content/docs/zh-cn/assets/overview.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/editor/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/editor.mdxrename to docs/astro/src/content/docs/zh-cn/editor/overview.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/agent.mdx b/docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/agent.mdxrename to docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/editor-plugins.mdxrename to docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx b/docs/astro/src/content/docs/zh-cn/extending/mcp.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/mcp.mdxrename to docs/astro/src/content/docs/zh-cn/extending/mcp.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ai.mdxrename to docs/astro/src/content/docs/zh-cn/gameplay/ai.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/markers.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/markers.mdxrename to docs/astro/src/content/docs/zh-cn/gameplay/markers.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/physics.mdxrename to docs/astro/src/content/docs/zh-cn/gameplay/physics.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/camera.mdx b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/camera.mdxrename to docs/astro/src/content/docs/zh-cn/graphics/camera.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/drawing.mdxrename to docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/lighting.mdxrename to docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/material.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/material.mdxrename to docs/astro/src/content/docs/zh-cn/graphics/materials.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/postprocess.mdxrename to docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/sprites.mdxrename to docs/astro/src/content/docs/zh-cn/graphics/sprites.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/video.mdx b/docs/astro/src/content/docs/zh-cn/graphics/video.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/video.mdxrename to docs/astro/src/content/docs/zh-cn/graphics/video.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/profiling.mdxrename to docs/astro/src/content/docs/zh-cn/performance/profiling.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/services.mdx b/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/services.mdxrename to docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/mobile.mdxrename to docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/hot-update.mdxrename to docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/minigame-platforms.mdx b/docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/minigame-platforms.mdxrename to docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/build-export.mdxrename to docs/astro/src/content/docs/zh-cn/publishing/overview.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/wechat.mdxrename to docs/astro/src/content/docs/zh-cn/publishing/wechat.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/events.mdx b/docs/astro/src/content/docs/zh-cn/scripting/events.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/events.mdxrename to docs/astro/src/content/docs/zh-cn/scripting/events.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/input.mdx b/docs/astro/src/content/docs/zh-cn/scripting/input.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/input.mdxrename to docs/astro/src/content/docs/zh-cn/scripting/input.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/math.mdx b/docs/astro/src/content/docs/zh-cn/scripting/math.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/math.mdxrename to docs/astro/src/content/docs/zh-cn/scripting/math.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/networking.mdxrename to docs/astro/src/content/docs/zh-cn/scripting/networking.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/scripting.mdxrename to docs/astro/src/content/docs/zh-cn/scripting/overview.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/save.mdx b/docs/astro/src/content/docs/zh-cn/scripting/save.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/save.mdxrename to docs/astro/src/content/docs/zh-cn/scripting/save.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdxrename to docs/astro/src/content/docs/zh-cn/ui/controllers.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-binding.mdx b/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-binding.mdxrename to docs/astro/src/content/docs/zh-cn/ui/data-binding.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-interaction.mdx b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-interaction.mdxrename to docs/astro/src/content/docs/zh-cn/ui/interaction.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-layout.mdx b/docs/astro/src/content/docs/zh-cn/ui/layout.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-layout.mdxrename to docs/astro/src/content/docs/zh-cn/ui/layout.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-lists.mdx b/docs/astro/src/content/docs/zh-cn/ui/lists.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-lists.mdxrename to docs/astro/src/content/docs/zh-cn/ui/lists.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/ui/overview.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui.mdxrename to docs/astro/src/content/docs/zh-cn/ui/overview.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx b/docs/astro/src/content/docs/zh-cn/ui/text.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-text.mdxrename to docs/astro/src/content/docs/zh-cn/ui/text.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-theme.mdx b/docs/astro/src/content/docs/zh-cn/ui/theming.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-theme.mdxrename to docs/astro/src/content/docs/zh-cn/ui/theming.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/ui-components.mdxrename to docs/astro/src/content/docs/zh-cn/ui/widgets.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/particle.mdxrename to docs/astro/src/content/docs/zh-cn/world/particles.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/prefab.mdxrename to docs/astro/src/content/docs/zh-cn/world/prefabs.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/scene.mdx b/docs/astro/src/content/docs/zh-cn/world/scenes.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/scene.mdxrename to docs/astro/src/content/docs/zh-cn/world/scenes.mdxdiff --git a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdxsimilarity index 100%rename from docs/astro/src/content/docs/zh-cn/guides/tilemap.mdxrename to docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx