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.

fix(assets): two files cannot be the same asset

yhhf3dcc22900fc
diff --git a/desktop/electron/assetDb.ts b/desktop/electron/assetDb.ts
index 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.mjs
new file mode 100644
index 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.ts
index 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.ts
index 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.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/dragonbones.mdx
rename to docs/astro/src/content/docs/animation/dragonbones.mdx
diff --git a/docs/astro/src/content/docs/guides/animation.mdx b/docs/astro/src/content/docs/animation/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/animation.mdx
rename to docs/astro/src/content/docs/animation/overview.mdx
diff --git a/docs/astro/src/content/docs/guides/spine.mdx b/docs/astro/src/content/docs/animation/spine.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/spine.mdx
rename to docs/astro/src/content/docs/animation/spine.mdx
diff --git a/docs/astro/src/content/docs/guides/timeline.mdx b/docs/astro/src/content/docs/animation/timeline.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/timeline.mdx
rename to docs/astro/src/content/docs/animation/timeline.mdx
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/audio.mdx
rename to docs/astro/src/content/docs/assets/audio.mdx
diff --git a/docs/astro/src/content/docs/guides/localization.mdx b/docs/astro/src/content/docs/assets/localization.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/localization.mdx
rename to docs/astro/src/content/docs/assets/localization.mdx
diff --git a/docs/astro/src/content/docs/guides/assets.mdx b/docs/astro/src/content/docs/assets/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/assets.mdx
rename to docs/astro/src/content/docs/assets/overview.mdx
diff --git a/docs/astro/src/content/docs/guides/editor.mdx b/docs/astro/src/content/docs/editor/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/editor.mdx
rename to docs/astro/src/content/docs/editor/overview.mdx
diff --git a/docs/astro/src/content/docs/guides/agent.mdx b/docs/astro/src/content/docs/extending/built-in-agent.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/agent.mdx
rename to docs/astro/src/content/docs/extending/built-in-agent.mdx
diff --git a/docs/astro/src/content/docs/guides/editor-plugins.mdx b/docs/astro/src/content/docs/extending/editor-plugins.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/editor-plugins.mdx
rename to docs/astro/src/content/docs/extending/editor-plugins.mdx
diff --git a/docs/astro/src/content/docs/guides/mcp.mdx b/docs/astro/src/content/docs/extending/mcp.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/mcp.mdx
rename to docs/astro/src/content/docs/extending/mcp.mdx
diff --git a/docs/astro/src/content/docs/guides/ai.mdx b/docs/astro/src/content/docs/gameplay/ai.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ai.mdx
rename to docs/astro/src/content/docs/gameplay/ai.mdx
diff --git a/docs/astro/src/content/docs/guides/markers.mdx b/docs/astro/src/content/docs/gameplay/markers.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/markers.mdx
rename to docs/astro/src/content/docs/gameplay/markers.mdx
diff --git a/docs/astro/src/content/docs/guides/physics.mdx b/docs/astro/src/content/docs/gameplay/physics.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/physics.mdx
rename to docs/astro/src/content/docs/gameplay/physics.mdx
diff --git a/docs/astro/src/content/docs/guides/camera.mdx b/docs/astro/src/content/docs/graphics/camera.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/camera.mdx
rename to docs/astro/src/content/docs/graphics/camera.mdx
diff --git a/docs/astro/src/content/docs/guides/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/drawing.mdx
rename to docs/astro/src/content/docs/graphics/drawing.mdx
diff --git a/docs/astro/src/content/docs/guides/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/lighting.mdx
rename to docs/astro/src/content/docs/graphics/lighting.mdx
diff --git a/docs/astro/src/content/docs/guides/material.mdx b/docs/astro/src/content/docs/graphics/materials.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/material.mdx
rename to docs/astro/src/content/docs/graphics/materials.mdx
diff --git a/docs/astro/src/content/docs/guides/postprocess.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/postprocess.mdx
rename to docs/astro/src/content/docs/graphics/post-processing.mdx
diff --git a/docs/astro/src/content/docs/guides/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/sprites.mdx
rename to docs/astro/src/content/docs/graphics/sprites.mdx
diff --git a/docs/astro/src/content/docs/guides/video.mdx b/docs/astro/src/content/docs/graphics/video.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/video.mdx
rename to docs/astro/src/content/docs/graphics/video.mdx
diff --git a/docs/astro/src/content/docs/guides/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/profiling.mdx
rename to docs/astro/src/content/docs/performance/profiling.mdx
diff --git a/docs/astro/src/content/docs/guides/services.mdx b/docs/astro/src/content/docs/publishing/ads-sharing.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/services.mdx
rename to docs/astro/src/content/docs/publishing/ads-sharing.mdx
diff --git a/docs/astro/src/content/docs/guides/mobile.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/mobile.mdx
rename to docs/astro/src/content/docs/publishing/android-ios.mdx
diff --git a/docs/astro/src/content/docs/guides/hot-update.mdx b/docs/astro/src/content/docs/publishing/hot-update.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/hot-update.mdx
rename to docs/astro/src/content/docs/publishing/hot-update.mdx
diff --git a/docs/astro/src/content/docs/guides/minigame-platforms.mdx b/docs/astro/src/content/docs/publishing/minigame-platforms.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/minigame-platforms.mdx
rename to docs/astro/src/content/docs/publishing/minigame-platforms.mdx
diff --git a/docs/astro/src/content/docs/guides/build-export.mdx b/docs/astro/src/content/docs/publishing/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/build-export.mdx
rename to docs/astro/src/content/docs/publishing/overview.mdx
diff --git a/docs/astro/src/content/docs/guides/wechat.mdx b/docs/astro/src/content/docs/publishing/wechat.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/wechat.mdx
rename to docs/astro/src/content/docs/publishing/wechat.mdx
diff --git a/docs/astro/src/content/docs/guides/events.mdx b/docs/astro/src/content/docs/scripting/events.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/events.mdx
rename to docs/astro/src/content/docs/scripting/events.mdx
diff --git a/docs/astro/src/content/docs/guides/input.mdx b/docs/astro/src/content/docs/scripting/input.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/input.mdx
rename to docs/astro/src/content/docs/scripting/input.mdx
diff --git a/docs/astro/src/content/docs/guides/math.mdx b/docs/astro/src/content/docs/scripting/math.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/math.mdx
rename to docs/astro/src/content/docs/scripting/math.mdx
diff --git a/docs/astro/src/content/docs/guides/networking.mdx b/docs/astro/src/content/docs/scripting/networking.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/networking.mdx
rename to docs/astro/src/content/docs/scripting/networking.mdx
diff --git a/docs/astro/src/content/docs/guides/scripting.mdx b/docs/astro/src/content/docs/scripting/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/scripting.mdx
rename to docs/astro/src/content/docs/scripting/overview.mdx
diff --git a/docs/astro/src/content/docs/guides/save.mdx b/docs/astro/src/content/docs/scripting/save.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/save.mdx
rename to docs/astro/src/content/docs/scripting/save.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-controllers.mdx b/docs/astro/src/content/docs/ui/controllers.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-controllers.mdx
rename to docs/astro/src/content/docs/ui/controllers.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-binding.mdx b/docs/astro/src/content/docs/ui/data-binding.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-binding.mdx
rename to docs/astro/src/content/docs/ui/data-binding.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-interaction.mdx b/docs/astro/src/content/docs/ui/interaction.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-interaction.mdx
rename to docs/astro/src/content/docs/ui/interaction.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-layout.mdx b/docs/astro/src/content/docs/ui/layout.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-layout.mdx
rename to docs/astro/src/content/docs/ui/layout.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-lists.mdx b/docs/astro/src/content/docs/ui/lists.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-lists.mdx
rename to docs/astro/src/content/docs/ui/lists.mdx
diff --git a/docs/astro/src/content/docs/guides/ui.mdx b/docs/astro/src/content/docs/ui/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui.mdx
rename to docs/astro/src/content/docs/ui/overview.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-text.mdx b/docs/astro/src/content/docs/ui/text.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-text.mdx
rename to docs/astro/src/content/docs/ui/text.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-theme.mdx b/docs/astro/src/content/docs/ui/theming.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-theme.mdx
rename to docs/astro/src/content/docs/ui/theming.mdx
diff --git a/docs/astro/src/content/docs/guides/ui-components.mdx b/docs/astro/src/content/docs/ui/widgets.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/ui-components.mdx
rename to docs/astro/src/content/docs/ui/widgets.mdx
diff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/world/particles.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/particle.mdx
rename to docs/astro/src/content/docs/world/particles.mdx
diff --git a/docs/astro/src/content/docs/guides/prefab.mdx b/docs/astro/src/content/docs/world/prefabs.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/prefab.mdx
rename to docs/astro/src/content/docs/world/prefabs.mdx
diff --git a/docs/astro/src/content/docs/guides/scene.mdx b/docs/astro/src/content/docs/world/scenes.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/scene.mdx
rename to docs/astro/src/content/docs/world/scenes.mdx
diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/world/tilemaps.mdx
similarity index 100%
rename from docs/astro/src/content/docs/guides/tilemap.mdx
rename to docs/astro/src/content/docs/world/tilemaps.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/dragonbones.mdx b/docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/dragonbones.mdx
rename to docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/animation.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/animation.mdx
rename to docs/astro/src/content/docs/zh-cn/animation/overview.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/spine.mdx b/docs/astro/src/content/docs/zh-cn/animation/spine.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/spine.mdx
rename to docs/astro/src/content/docs/zh-cn/animation/spine.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/timeline.mdx b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/timeline.mdx
rename to docs/astro/src/content/docs/zh-cn/animation/timeline.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/audio.mdx b/docs/astro/src/content/docs/zh-cn/assets/audio.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/audio.mdx
rename to docs/astro/src/content/docs/zh-cn/assets/audio.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/localization.mdx b/docs/astro/src/content/docs/zh-cn/assets/localization.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/localization.mdx
rename to docs/astro/src/content/docs/zh-cn/assets/localization.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/assets.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/assets.mdx
rename to docs/astro/src/content/docs/zh-cn/assets/overview.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/editor.mdx b/docs/astro/src/content/docs/zh-cn/editor/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/editor.mdx
rename to docs/astro/src/content/docs/zh-cn/editor/overview.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/agent.mdx b/docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/agent.mdx
rename to docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/editor-plugins.mdx b/docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/editor-plugins.mdx
rename to docs/astro/src/content/docs/zh-cn/extending/editor-plugins.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mcp.mdx b/docs/astro/src/content/docs/zh-cn/extending/mcp.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/mcp.mdx
rename to docs/astro/src/content/docs/zh-cn/extending/mcp.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ai.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ai.mdx
rename to docs/astro/src/content/docs/zh-cn/gameplay/ai.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/markers.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/markers.mdx
rename to docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/physics.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/physics.mdx
rename to docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/camera.mdx b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/camera.mdx
rename to docs/astro/src/content/docs/zh-cn/graphics/camera.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/drawing.mdx
rename to docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/lighting.mdx
rename to docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/material.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/material.mdx
rename to docs/astro/src/content/docs/zh-cn/graphics/materials.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/postprocess.mdx
rename to docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/sprites.mdx
rename to docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/video.mdx b/docs/astro/src/content/docs/zh-cn/graphics/video.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/video.mdx
rename to docs/astro/src/content/docs/zh-cn/graphics/video.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/profiling.mdx
rename to docs/astro/src/content/docs/zh-cn/performance/profiling.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/services.mdx b/docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/services.mdx
rename to docs/astro/src/content/docs/zh-cn/publishing/ads-sharing.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/mobile.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/mobile.mdx
rename to docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/hot-update.mdx
rename to docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/minigame-platforms.mdx b/docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/minigame-platforms.mdx
rename to docs/astro/src/content/docs/zh-cn/publishing/minigame-platforms.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/build-export.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/build-export.mdx
rename to docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/wechat.mdx b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/wechat.mdx
rename to docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/events.mdx b/docs/astro/src/content/docs/zh-cn/scripting/events.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/events.mdx
rename to docs/astro/src/content/docs/zh-cn/scripting/events.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/input.mdx b/docs/astro/src/content/docs/zh-cn/scripting/input.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/input.mdx
rename to docs/astro/src/content/docs/zh-cn/scripting/input.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/math.mdx b/docs/astro/src/content/docs/zh-cn/scripting/math.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/math.mdx
rename to docs/astro/src/content/docs/zh-cn/scripting/math.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/networking.mdx
rename to docs/astro/src/content/docs/zh-cn/scripting/networking.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/scripting.mdx b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/scripting.mdx
rename to docs/astro/src/content/docs/zh-cn/scripting/overview.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/save.mdx b/docs/astro/src/content/docs/zh-cn/scripting/save.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/save.mdx
rename to docs/astro/src/content/docs/zh-cn/scripting/save.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-controllers.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/controllers.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-binding.mdx b/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-binding.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-interaction.mdx b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-interaction.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/interaction.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-layout.mdx b/docs/astro/src/content/docs/zh-cn/ui/layout.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-layout.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/layout.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-lists.mdx b/docs/astro/src/content/docs/zh-cn/ui/lists.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-lists.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/lists.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui.mdx b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/overview.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx b/docs/astro/src/content/docs/zh-cn/ui/text.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-text.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/text.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-theme.mdx b/docs/astro/src/content/docs/zh-cn/ui/theming.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-theme.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/theming.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/ui-components.mdx
rename to docs/astro/src/content/docs/zh-cn/ui/widgets.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/particle.mdx
rename to docs/astro/src/content/docs/zh-cn/world/particles.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/prefab.mdx b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/prefab.mdx
rename to docs/astro/src/content/docs/zh-cn/world/prefabs.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/scene.mdx b/docs/astro/src/content/docs/zh-cn/world/scenes.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/scene.mdx
rename to docs/astro/src/content/docs/zh-cn/world/scenes.mdx
diff --git a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx
similarity index 100%
rename from docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx
rename to docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx