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: the sidebar is a table of contents, not a listing of every page
yhhe29c583a0e15
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlindex a08d8a40b..5c28d1746 100644--- a/.github/workflows/docs.yml+++ b/.github/workflows/docs.yml@@ -58,6 +58,13 @@ jobs:working-directory: docs/astrorun: npm run build+ # After the build, because it resolves links against the pages that were+ # actually emitted — a guide pointing at a renamed page, or an old URL+ # whose redirect entry went missing, fails here instead of deploying a 404.+ - name: Verify internal doc links resolve+ working-directory: docs/astro+ run: npm run verify:links+- name: Merge Documentationrun: |mkdir -p docs/dist/docs/apidiff --git a/README.md b/README.mdindex 0e3cf9a04..c0984d7b8 100644--- a/README.md+++ b/README.md@@ -98,8 +98,8 @@ Full documentation: [estellaengine.com/docs](https://estellaengine.com/docs)- [ECS Architecture](https://estellaengine.com/docs/core-concepts/ecs/)- [Components](https://estellaengine.com/docs/core-concepts/components/)- [Systems](https://estellaengine.com/docs/core-concepts/systems/)-- [Building & Exporting](https://estellaengine.com/docs/guides/build-export/)-- [Android & iOS](https://estellaengine.com/docs/guides/mobile/)+- [Building & Exporting](https://estellaengine.com/docs/publishing/overview/)+- [Android & iOS](https://estellaengine.com/docs/publishing/android-ios/)## Contributingdiff --git a/docs/SITE.md b/docs/SITE.mdindex 122974ad7..1a367dd05 100644--- a/docs/SITE.md+++ b/docs/SITE.md@@ -85,7 +85,14 @@ This will:### Adding a New Guide-1. Create a new `.mdx` file in `astro/src/content/docs/guides/`+1. Create a new `.mdx` file under the section it belongs to —+ `astro/src/content/docs/<section>/`, where `<section>` is one of+ `getting-started`, `editor`, `core-concepts`, `scripting`, `graphics`,+ `animation`, `gameplay`, `ui`, `world`, `assets`, `publishing`,+ `performance` or `extending`. A page's directory IS its sidebar group and+ its URL: keep them the same, and keep every page exactly one level deep+ (`<section>/<page>.mdx`) so the relative `../../../../assets/` image paths+ resolve.2. Add frontmatter:```mdx---@@ -95,7 +102,10 @@ This will:Your content here...```-3. Add to sidebar in `astro/astro.config.mjs`+3. Add to the matching sidebar group in `astro/astro.config.mjs`, and write the+ Simplified Chinese page at `astro/src/content/docs/zh-cn/<section>/<page>.mdx`+4. If you rename or move a page, add its old path to `redirects` in+ `astro/astro.config.mjs` — published URLs must keep working4. Keep code samples accurate: every symbol a guide imports from the main `esengine`barrel must be a real SDK export. `npm run verify:imports` (from `docs/astro/`)checks this against the exports declared in `sdk/src` and runs in CI before thediff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjsindex 5e39f7095..bf1bcab76 100644--- a/docs/astro/astro.config.mjs+++ b/docs/astro/astro.config.mjs@@ -3,12 +3,78 @@ import { defineConfig } from 'astro/config';import starlight from '@astrojs/starlight';import starlightTypeDoc, { typeDocSidebarGroup } from 'starlight-typedoc';+const SITE = 'https://estellaengine.com';++// Pages that used to live in one flat `guides/` folder, and now live in the+// section the sidebar shows them under — a page's directory is its URL. Every+// old address stays reachable: Astro emits a redirect page for each entry, in+// both locales. Never delete a line from here; moving a page again means adding+// one, so a URL published once keeps resolving.+const MOVED_GUIDES = {+ 'guides/editor': 'editor/overview',+ 'guides/scripting': 'scripting/overview',+ 'guides/input': 'scripting/input',+ 'guides/events': 'scripting/events',+ 'guides/save': 'scripting/save',+ 'guides/networking': 'scripting/networking',+ 'guides/math': 'scripting/math',+ 'guides/sprites': 'graphics/sprites',+ 'guides/camera': 'graphics/camera',+ 'guides/material': 'graphics/materials',+ 'guides/lighting': 'graphics/lighting',+ 'guides/postprocess': 'graphics/post-processing',+ 'guides/drawing': 'graphics/drawing',+ 'guides/video': 'graphics/video',+ 'guides/animation': 'animation/overview',+ 'guides/timeline': 'animation/timeline',+ 'guides/spine': 'animation/spine',+ 'guides/dragonbones': 'animation/dragonbones',+ 'guides/physics': 'gameplay/physics',+ 'guides/markers': 'gameplay/markers',+ 'guides/ai': 'gameplay/ai',+ 'guides/ui': 'ui/overview',+ 'guides/ui-layout': 'ui/layout',+ 'guides/ui-text': 'ui/text',+ 'guides/ui-components': 'ui/widgets',+ 'guides/ui-lists': 'ui/lists',+ 'guides/ui-interaction': 'ui/interaction',+ 'guides/ui-theme': 'ui/theming',+ 'guides/ui-binding': 'ui/data-binding',+ 'guides/ui-controllers': 'ui/controllers',+ 'guides/scene': 'world/scenes',+ 'guides/prefab': 'world/prefabs',+ 'guides/tilemap': 'world/tilemaps',+ 'guides/particle': 'world/particles',+ 'guides/assets': 'assets/overview',+ 'guides/audio': 'assets/audio',+ 'guides/localization': 'assets/localization',+ 'guides/build-export': 'publishing/overview',+ 'guides/mobile': 'publishing/android-ios',+ 'guides/wechat': 'publishing/wechat',+ 'guides/minigame-platforms': 'publishing/minigame-platforms',+ 'guides/hot-update': 'publishing/hot-update',+ 'guides/services': 'publishing/ads-sharing',+ 'guides/profiling': 'performance/profiling',+ 'guides/editor-plugins': 'extending/editor-plugins',+ 'guides/agent': 'extending/built-in-agent',+ 'guides/mcp': 'extending/mcp',+};+// The site is deployed under estellaengine.com/docs (docs.yml merges this build// into docs/dist/docs/), so everything is served from the /docs base path.export default defineConfig({- site: 'https://estellaengine.com',+ site: SITE,base: '/docs',outDir: './dist',+ // Astro prepends `base` to a redirect's SOURCE but not to its destination, so+ // the destination carries /docs itself — without it every old URL lands on a+ // 404 at the site root.+ redirects: Object.fromEntries(+ Object.entries(MOVED_GUIDES).flatMap(([from, to]) => [+ [`/${from}`, `/docs/${to}/`],+ [`/zh-cn/${from}`, `/docs/zh-cn/${to}/`],+ ]),+ ),integrations: [starlight({title: 'Estella',@@ -52,20 +118,32 @@ export default defineConfig({editLink: {baseUrl: 'https://github.com/esengine/estella/edit/master/docs/astro/',},+ // The sidebar is the table of contents of a manual, not a list of files:+ // grouped by the task a reader came to do, every group collapsed but the+ // first, so the rail shows ~17 rows instead of every page at once.+ // Starlight still auto-expands whichever group holds the current page.sidebar: [{- label: 'Getting Started',+ label: 'Get Started',translations: { 'zh-CN': '快速开始' },items: [{ label: 'Introduction', translations: { 'zh-CN': '简介' }, slug: 'getting-started/introduction' },{ label: 'Installation', translations: { 'zh-CN': '安装' }, slug: 'getting-started/installation' },{ label: 'Quick Start', translations: { 'zh-CN': '快速上手' }, slug: 'getting-started/quick-start' },- { label: 'The Editor', translations: { 'zh-CN': '编辑器' }, slug: 'guides/editor' },+ ],+ },+ {+ label: 'Editor',+ translations: { 'zh-CN': '编辑器' },+ collapsed: true,+ items: [+ { label: 'The Editor', translations: { 'zh-CN': '编辑器' }, slug: 'editor/overview' },],},{label: 'Core Concepts',translations: { 'zh-CN': '核心概念' },+ collapsed: true,items: [{ label: 'ECS Architecture', translations: { 'zh-CN': 'ECS 架构' }, slug: 'core-concepts/ecs' },{ label: 'Components', translations: { 'zh-CN': '组件' }, slug: 'core-concepts/components' },@@ -77,87 +155,133 @@ export default defineConfig({],},{- label: 'Gameplay',- translations: { 'zh-CN': '玩法' },+ label: 'Scripting',+ translations: { 'zh-CN': '脚本' },+ collapsed: true,items: [- { label: 'Scripting', translations: { 'zh-CN': '脚本' }, slug: 'guides/scripting' },- { label: 'Event Binding', translations: { 'zh-CN': '事件绑定' }, slug: 'guides/events' },- { label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'guides/input' },- { label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'guides/camera' },- { label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },- { label: 'Markers & Trigger Areas', translations: { 'zh-CN': '标记与触发区' }, slug: 'guides/markers' },- { label: 'Gameplay AI', translations: { 'zh-CN': '游戏 AI' }, slug: 'guides/ai' },- { label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'guides/animation' },- { label: 'Timeline', translations: { 'zh-CN': '时间轴' }, slug: 'guides/timeline' },- { label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'guides/spine' },- { label: 'DragonBones Animation', translations: { 'zh-CN': 'DragonBones 动画' }, slug: 'guides/dragonbones' },+ { label: 'Scripting', translations: { 'zh-CN': '脚本' }, slug: 'scripting/overview' },+ { label: 'Input', translations: { 'zh-CN': '输入' }, slug: 'scripting/input' },+ { label: 'Event Binding', translations: { 'zh-CN': '事件绑定' }, slug: 'scripting/events' },+ { label: 'Saving & Loading', translations: { 'zh-CN': '存档与读档' }, slug: 'scripting/save' },+ { label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'scripting/networking' },+ { label: 'Math Helpers', translations: { 'zh-CN': '数学辅助' }, slug: 'scripting/math' },],},{label: 'Graphics',translations: { 'zh-CN': '图形' },+ collapsed: true,+ items: [+ { label: 'Sprites & Rendering', translations: { 'zh-CN': '精灵与渲染' }, slug: 'graphics/sprites' },+ { label: 'Camera', translations: { 'zh-CN': '相机' }, slug: 'graphics/camera' },+ { label: 'Materials & Shaders', translations: { 'zh-CN': '材质与着色器' }, slug: 'graphics/materials' },+ { label: '2D Lighting & Shadows', translations: { 'zh-CN': '2D 光照与阴影' }, slug: 'graphics/lighting' },+ { label: 'Post-processing', translations: { 'zh-CN': '后处理' }, slug: 'graphics/post-processing' },+ { label: 'Custom Drawing', translations: { 'zh-CN': '自定义绘制' }, slug: 'graphics/drawing' },+ { label: 'Video', translations: { 'zh-CN': '视频' }, slug: 'graphics/video' },+ ],+ },+ {+ label: 'Animation',+ translations: { 'zh-CN': '动画' },+ collapsed: true,+ items: [+ { label: 'Animation', translations: { 'zh-CN': '动画' }, slug: 'animation/overview' },+ { label: 'Timeline', translations: { 'zh-CN': '时间轴' }, slug: 'animation/timeline' },+ { label: 'Spine Animation', translations: { 'zh-CN': 'Spine 动画' }, slug: 'animation/spine' },+ { label: 'DragonBones Animation', translations: { 'zh-CN': 'DragonBones 动画' }, slug: 'animation/dragonbones' },+ ],+ },+ {+ label: 'Gameplay',+ translations: { 'zh-CN': '玩法' },+ collapsed: true,items: [- { label: 'Sprites & Rendering', translations: { 'zh-CN': '精灵与渲染' }, slug: 'guides/sprites' },- { label: 'Video', translations: { 'zh-CN': '视频' }, slug: 'guides/video' },- { label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },- { label: 'Particles', translations: { 'zh-CN': '粒子' }, slug: 'guides/particle' },- { label: 'Post-processing', translations: { 'zh-CN': '后处理' }, slug: 'guides/postprocess' },- { label: 'Materials & Shaders', translations: { 'zh-CN': '材质与着色器' }, slug: 'guides/material' },- { label: '2D Lighting & Shadows', translations: { 'zh-CN': '2D 光照与阴影' }, slug: 'guides/lighting' },- { label: 'Custom Drawing', translations: { 'zh-CN': '自定义绘制' }, slug: 'guides/drawing' },+ { label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'gameplay/physics' },+ { label: 'Markers & Trigger Areas', translations: { 'zh-CN': '标记与触发区' }, slug: 'gameplay/markers' },+ { label: 'Gameplay AI', translations: { 'zh-CN': '游戏 AI' }, slug: 'gameplay/ai' },],},{label: 'UI',translations: { 'zh-CN': 'UI' },+ collapsed: true,+ items: [+ { label: 'Overview', translations: { 'zh-CN': '总览' }, slug: 'ui/overview' },+ { label: 'Layout', translations: { 'zh-CN': '布局' }, slug: 'ui/layout' },+ { label: 'Text', translations: { 'zh-CN': '文本' }, slug: 'ui/text' },+ { label: 'Widgets', translations: { 'zh-CN': '控件' }, slug: 'ui/widgets' },+ { label: 'Lists & Scrolling', translations: { 'zh-CN': '列表与滚动' }, slug: 'ui/lists' },+ { label: 'Interaction', translations: { 'zh-CN': '交互' }, slug: 'ui/interaction' },+ { label: 'Theming', translations: { 'zh-CN': '主题' }, slug: 'ui/theming' },+ { label: 'Data Binding', translations: { 'zh-CN': '数据绑定' }, slug: 'ui/data-binding' },+ { label: 'Controllers', translations: { 'zh-CN': '控制器' }, slug: 'ui/controllers' },+ ],+ },+ {+ label: 'World Building',+ translations: { 'zh-CN': '世界搭建' },+ collapsed: true,+ items: [+ { label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'world/scenes' },+ { label: 'Prefabs', translations: { 'zh-CN': '预制体' }, slug: 'world/prefabs' },+ { label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'world/tilemaps' },+ { label: 'Particles', translations: { 'zh-CN': '粒子' }, slug: 'world/particles' },+ ],+ },+ {+ label: 'Assets',+ translations: { 'zh-CN': '资源' },+ collapsed: true,+ items: [+ { label: 'Assets', translations: { 'zh-CN': '资源' }, slug: 'assets/overview' },+ { label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'assets/audio' },+ { label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'assets/localization' },+ ],+ },+ {+ label: 'Publishing',+ translations: { 'zh-CN': '发布' },+ collapsed: true,items: [- { label: 'Overview', translations: { 'zh-CN': '总览' }, slug: 'guides/ui' },- { label: 'Layout', translations: { 'zh-CN': '布局' }, slug: 'guides/ui-layout' },- { label: 'Text', translations: { 'zh-CN': '文本' }, slug: 'guides/ui-text' },- { label: 'Widgets', translations: { 'zh-CN': '控件' }, slug: 'guides/ui-components' },- { label: 'Lists & Scrolling', translations: { 'zh-CN': '列表与滚动' }, slug: 'guides/ui-lists' },- { label: 'Interaction', translations: { 'zh-CN': '交互' }, slug: 'guides/ui-interaction' },- { label: 'Theming', translations: { 'zh-CN': '主题' }, slug: 'guides/ui-theme' },- { label: 'Data Binding', translations: { 'zh-CN': '数据绑定' }, slug: 'guides/ui-binding' },- { label: 'Controllers', translations: { 'zh-CN': '控制器' }, slug: 'guides/ui-controllers' },+ { label: 'Building & Exporting', translations: { 'zh-CN': '构建与导出' }, slug: 'publishing/overview' },+ { label: 'Android & iOS', translations: { 'zh-CN': 'Android 与 iOS' }, slug: 'publishing/android-ios' },+ { label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'publishing/wechat' },+ { label: 'Mini-Game Platforms', translations: { 'zh-CN': '小游戏平台' }, slug: 'publishing/minigame-platforms' },+ { label: 'Hot Update', translations: { 'zh-CN': '热更新' }, slug: 'publishing/hot-update' },+ { label: 'Ads & Sharing', translations: { 'zh-CN': '广告与分享' }, slug: 'publishing/ads-sharing' },],},{- label: 'Content & Flow',- translations: { 'zh-CN': '内容与流程' },+ label: 'Performance',+ translations: { 'zh-CN': '性能与调试' },+ collapsed: true,items: [- { label: 'Assets', translations: { 'zh-CN': '资源' }, slug: 'guides/assets' },- { label: 'Prefabs', translations: { 'zh-CN': '预制体' }, slug: 'guides/prefab' },- { label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },- { label: 'Scenes', translations: { 'zh-CN': '场景' }, slug: 'guides/scene' },- { label: 'Saving & Loading', translations: { 'zh-CN': '存档与读档' }, slug: 'guides/save' },- { label: 'Localization', translations: { 'zh-CN': '本地化' }, slug: 'guides/localization' },- { label: 'Ads & Sharing', translations: { 'zh-CN': '广告与分享' }, slug: 'guides/services' },- { label: 'Building & Exporting', translations: { 'zh-CN': '构建与导出' }, slug: 'guides/build-export' },- { label: 'Android & iOS', translations: { 'zh-CN': 'Android 与 iOS' }, slug: 'guides/mobile' },- { label: 'Hot Update', translations: { 'zh-CN': '热更新' }, slug: 'guides/hot-update' },- { label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },- { label: 'Mini-Game Platforms', translations: { 'zh-CN': '小游戏平台' }, slug: 'guides/minigame-platforms' },- { label: 'Networking', translations: { 'zh-CN': '联网' }, slug: 'guides/networking' },- { label: 'Editor Plugins', translations: { 'zh-CN': '编辑器插件' }, slug: 'guides/editor-plugins' },- { label: 'The Built-in Agent', translations: { 'zh-CN': '内置 Agent' }, slug: 'guides/agent' },- { label: 'AI Agents (MCP)', translations: { 'zh-CN': 'AI 代理 (MCP)' }, slug: 'guides/mcp' },+ { label: 'Profiling & Diagnostics', translations: { 'zh-CN': '性能剖析与诊断' }, slug: 'performance/profiling' },],},{- label: 'Utilities',- translations: { 'zh-CN': '工具' },+ label: 'Extending the Editor',+ translations: { 'zh-CN': '扩展编辑器' },+ collapsed: true,items: [- { label: 'Math Helpers', translations: { 'zh-CN': '数学辅助' }, slug: 'guides/math' },- { label: 'Profiling & Diagnostics', translations: { 'zh-CN': '性能剖析与诊断' }, slug: 'guides/profiling' },+ { label: 'Editor Plugins', translations: { 'zh-CN': '编辑器插件' }, slug: 'extending/editor-plugins' },+ { label: 'The Built-in Agent', translations: { 'zh-CN': '内置 Agent' }, slug: 'extending/built-in-agent' },+ { label: 'AI Agents (MCP)', translations: { 'zh-CN': 'AI 代理 (MCP)' }, slug: 'extending/mcp' },],},{label: 'Reference',translations: { 'zh-CN': '参考' },+ collapsed: true,items: [typeDocSidebarGroup,- { label: 'C++ API (Doxygen)', link: '/docs/api/html/', attrs: { target: '_blank' } },+ // Doxygen output is merged in beside the Astro build, not routed by+ // it, and it isn't translated. A root-relative link would get BOTH+ // the /docs base and the active locale prepended (which is how this+ // one used to render as the dead /docs/zh-cn/docs/api/html/), so it+ // has to be absolute to escape them.+ { label: 'C++ API (Doxygen)', link: `${SITE}/docs/api/html/`, attrs: { target: '_blank' } },{ label: 'Architecture', link: 'https://github.com/esengine/estella/blob/master/docs/ARCHITECTURE.md' },],},diff --git a/docs/astro/package.json b/docs/astro/package.jsonindex 2d1eec035..6b15c14a5 100644--- a/docs/astro/package.json+++ b/docs/astro/package.json@@ -8,7 +8,8 @@"build": "astro build","preview": "astro preview","check": "astro check",- "verify:imports": "node scripts/verify-doc-imports.mjs"+ "verify:imports": "node scripts/verify-doc-imports.mjs",+ "verify:links": "node scripts/verify-doc-links.mjs"},"dependencies": {"@astrojs/starlight": "^0.41.1",diff --git a/docs/astro/scripts/verify-doc-links.mjs b/docs/astro/scripts/verify-doc-links.mjsnew file mode 100644index 000000000..9fdb1833b--- /dev/null+++ b/docs/astro/scripts/verify-doc-links.mjs@@ -0,0 +1,83 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file verify-doc-links.mjs+ * @brief Guard against dead internal documentation links.+ *+ * Walks the built site and resolves every in-site `/docs/...` link against the+ * files the build actually emitted. A guide that links to a page someone+ * renamed — or an old URL whose `redirects` entry was dropped — fails here+ * instead of shipping a 404. Run after `astro build`, from `docs/astro/`:+ *+ * node scripts/verify-doc-links.mjs+ *+ * Redirect pages count as real destinations: an old address stays valid as long+ * as the build still emits its redirect stub.+ */+import { readFileSync, readdirSync, existsSync, statSync } from 'node:fs';+import { fileURLToPath } from 'node:url';+import { dirname, join, relative, sep } from 'node:path';++const here = dirname(fileURLToPath(import.meta.url));+const DIST = join(here, '..', 'dist');+const BASE = '/docs';++/** Every .html file the build emitted. */+function htmlFiles(dir) {+ const out = [];+ for (const e of readdirSync(dir, { withFileTypes: true })) {+ const p = join(dir, e.name);+ if (e.isDirectory()) out.push(...htmlFiles(p));+ else if (e.name.endsWith('.html')) out.push(p);+ }+ return out;+}++/** Does this in-site path resolve to something the build emitted? */+function resolves(urlPath) {+ const rel = urlPath.slice(BASE.length).replace(/^\/+/, '').replace(/\/+$/, '');+ const asDir = join(DIST, ...rel.split('/'), 'index.html');+ const asFile = join(DIST, ...rel.split('/'));+ if (existsSync(asDir)) return true;+ if (existsSync(asFile) && statSync(asFile).isFile()) return true;+ // The Doxygen C++ API is merged in by the site build script, not by Astro.+ if (rel.startsWith('api/')) return true;+ return false;+}++function main() {+ if (!existsSync(DIST)) {+ console.error(`no build to check at ${DIST} — run \`npm run build\` first`);+ process.exit(1);+ }+ const pages = htmlFiles(DIST);+ const dead = new Map(); // target -> pages that link to it+ let checked = 0;+ for (const page of pages) {+ // The generated TypeScript API is TypeDoc's own link graph, not ours — in+ // every locale it gets mirrored into (hence a segment test, not a prefix).+ if (relative(DIST, page).split(sep).includes('api-ts')) continue;+ const html = readFileSync(page, 'utf8');+ for (const m of html.matchAll(/href="(\/docs\/[^"#?]*)/g)) {+ const target = m[1];+ checked++;+ if (resolves(target)) continue;+ if (!dead.has(target)) dead.set(target, new Set());+ dead.get(target).add(relative(DIST, page).replaceAll(sep, '/'));+ }+ }+ console.log(`checked ${checked} internal links across ${pages.length} pages`);+ if (dead.size === 0) {+ console.log('all internal links resolve');+ return;+ }+ console.error(`\n${dead.size} dead link target(s):`);+ for (const [target, from] of dead) {+ console.error(` ${target}`);+ for (const f of [...from].slice(0, 5)) console.error(` linked from ${f}`);+ if (from.size > 5) console.error(` …and ${from.size - 5} more`);+ }+ process.exit(1);+}++main();diff --git a/docs/astro/src/content/docs/animation/dragonbones.mdx b/docs/astro/src/content/docs/animation/dragonbones.mdxindex c63b162d5..50e74388e 100644--- a/docs/astro/src/content/docs/animation/dragonbones.mdx+++ b/docs/astro/src/content/docs/animation/dragonbones.mdx@@ -195,7 +195,7 @@ to remember and no way to ship a game whose armatures have no runtime.## See also-- [Spine Animation](/docs/guides/spine/) — the other skeletal runtime, and how it differs.-- [Animation](/docs/guides/animation/) — sprite flipbooks and the Animator state machine.-- [Assets](/docs/guides/assets/) — how skeleton and atlas assets are imported and referenced.-- [Build & Export](/docs/guides/build-export/) — what a package contains per target.+- [Spine Animation](/docs/animation/spine/) — the other skeletal runtime, and how it differs.+- [Animation](/docs/animation/overview/) — sprite flipbooks and the Animator state machine.+- [Assets](/docs/assets/overview/) — how skeleton and atlas assets are imported and referenced.+- [Build & Export](/docs/publishing/overview/) — what a package contains per target.diff --git a/docs/astro/src/content/docs/animation/overview.mdx b/docs/astro/src/content/docs/animation/overview.mdxindex a4f98c182..048127f08 100644--- a/docs/astro/src/content/docs/animation/overview.mdx+++ b/docs/astro/src/content/docs/animation/overview.mdx@@ -187,7 +187,7 @@ const registerRun = defineSystem([Res(Assets), Res(SpriteAnimation)], async (ass### Driving clips from a state machine — no code-The [FSM/BT built-ins](/docs/guides/ai/) drive flipbooks as data. An action's+The [FSM/BT built-ins](/docs/gameplay/ai/) drive flipbooks as data. An action'soptional **argument** carries the clip, so idle/run/attack switching is pure`.esfsm` on the existing state-machine canvas:@@ -359,7 +359,7 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `resetTrigger(entity, name)` | Clear a trigger before it's consumed. || `getFloat(entity, name)` / `getBool(entity, name)` | Read a parameter back. |-The controller can drive both sprite **and** [Spine](/docs/guides/spine/)+The controller can drive both sprite **and** [Spine](/docs/animation/spine/)animations, so one state machine handles a whole character.Parameters come in three types (`AnimatorParamType`): `'float'`, `'bool'`, and@@ -413,7 +413,7 @@ selects — handy for tooling or tests.For skeletal characters, a state can instead carry a `spine` motion(`AnimatorSpineMotion`, `{ animation, loop? }`): on entry the controller sets-that [Spine](/docs/guides/spine/) animation (`loop` defaults `true`) and leaves+that [Spine](/docs/animation/spine/) animation (`loop` defaults `true`) and leavestrack playback and mixing to the Spine runtime — it never touches`SpriteAnimator`. States are exclusive: exactly one of `clip`, `blend`, `spine`,or `stateMachine`.@@ -499,6 +499,6 @@ evaluateAnimatorPath(player, 'locomotion/idle', { speed: 3 }, new Set());## See also-- [Spine Animation](/docs/guides/spine/) — skeletal animation, also driveable by the state machine.-- [Timeline](/docs/guides/timeline/) — keyframed cutscenes and sequenced events.-- [Camera](/docs/guides/camera/) — tween `CameraOrthoSize` for smooth zooms.+- [Spine Animation](/docs/animation/spine/) — skeletal animation, also driveable by the state machine.+- [Timeline](/docs/animation/timeline/) — keyframed cutscenes and sequenced events.+- [Camera](/docs/graphics/camera/) — tween `CameraOrthoSize` for smooth zooms.diff --git a/docs/astro/src/content/docs/animation/spine.mdx b/docs/astro/src/content/docs/animation/spine.mdxindex c26f9162c..0c6215593 100644--- a/docs/astro/src/content/docs/animation/spine.mdx+++ b/docs/astro/src/content/docs/animation/spine.mdx@@ -137,7 +137,7 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {over a locomotion track 0).- **Share skeleton + atlas** across entities — they ref-count a single loadedskeleton.-- **Drive whole characters from the [Animator](/docs/guides/animation/) state+- **Drive whole characters from the [Animator](/docs/animation/overview/) statemachine**, which can target Spine as well as sprites.<Aside type="note">@@ -155,6 +155,6 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {## See also-- [Animation](/docs/guides/animation/) — the Animator state machine can drive Spine.-- [Assets](/docs/guides/assets/) — loading skeleton + atlas assets.-- [DragonBones Animation](/docs/guides/dragonbones/) — the other skeletal runtime, MIT licensed.+- [Animation](/docs/animation/overview/) — the Animator state machine can drive Spine.+- [Assets](/docs/assets/overview/) — loading skeleton + atlas assets.+- [DragonBones Animation](/docs/animation/dragonbones/) — the other skeletal runtime, MIT licensed.diff --git a/docs/astro/src/content/docs/animation/timeline.mdx b/docs/astro/src/content/docs/animation/timeline.mdxindex a542b483b..5bfc4ad9a 100644--- a/docs/astro/src/content/docs/animation/timeline.mdx+++ b/docs/astro/src/content/docs/animation/timeline.mdx@@ -39,7 +39,7 @@ const attach = defineSystem([Commands()], (cmds) => {The component flags **are** the playback control: the engine reconciles them intoits internal clock every frame, so anything that flips `playing` — your code, the-inspector, an [AI action](/docs/guides/ai/#built-in-names) — drives the+inspector, an [AI action](/docs/gameplay/ai/#built-in-names) — drives theclip through the same channel.## Control playback@@ -77,7 +77,7 @@ These methods write through to the `TimelinePlayer` flags — `timeline.play(e)`For a **code-free cutscene**, pair the component with a state machine: thebuilt-in `timeline.play` action and `timeline.finished` condition make an FSMstate that plays a clip on enter and transitions out when it completes. See- [AI — built-in names](/docs/guides/ai/#built-in-names).+ [AI — built-in names](/docs/gameplay/ai/#built-in-names).</Aside>## Track types@@ -235,7 +235,7 @@ events) fire edge-detected during playback, not on a sample.- **`wrapMode: 'once'`** for cutscenes, `'loop'` for ambient/idle sequences.- **Scrub with `setTime`** to preview or sync a cutscene to gameplay state.- **Use a timeline (not tweens)** when many properties/entities animate in lockstep;- reach for [tweens](/docs/guides/animation/) for one-off single-property juice.+ reach for [tweens](/docs/animation/overview/) for one-off single-property juice.<Aside type="note">Timeline playback is gameplay — it advances in play mode and the standalone@@ -244,5 +244,5 @@ events) fire edge-detected during playback, not on a sample.## See also-- [Animation](/docs/guides/animation/) — tweens and the animator state machine.-- [Spine Animation](/docs/guides/spine/) — timelines can drive Spine clips.+- [Animation](/docs/animation/overview/) — tweens and the animator state machine.+- [Spine Animation](/docs/animation/spine/) — timelines can drive Spine clips.diff --git a/docs/astro/src/content/docs/assets/audio.mdx b/docs/astro/src/content/docs/assets/audio.mdxindex 045e5948e..f4ee1c0ce 100644--- a/docs/astro/src/content/docs/assets/audio.mdx+++ b/docs/astro/src/content/docs/assets/audio.mdx@@ -319,5 +319,5 @@ const pan = calculatePanning(600, 0, 0, 0, 1000); // 0.6 — to the right## See also-- [Assets](/docs/guides/assets/) — loading and bundling audio clips.-- [Scenes](/docs/guides/scene/) — `AudioSource` state persists with the scene.+- [Assets](/docs/assets/overview/) — loading and bundling audio clips.+- [Scenes](/docs/world/scenes/) — `AudioSource` state persists with the scene.diff --git a/docs/astro/src/content/docs/assets/localization.mdx b/docs/astro/src/content/docs/assets/localization.mdxindex d0d0aa2a2..fef9ff96c 100644--- a/docs/astro/src/content/docs/assets/localization.mdx+++ b/docs/astro/src/content/docs/assets/localization.mdx@@ -134,5 +134,5 @@ system that owns it instead.## See also-- [UI](/docs/guides/ui/) — the `Text` component the binding rides on.-- [Assets](/docs/guides/assets/) — how assets ship and load.+- [UI](/docs/ui/overview/) — the `Text` component the binding rides on.+- [Assets](/docs/assets/overview/) — how assets ship and load.diff --git a/docs/astro/src/content/docs/assets/overview.mdx b/docs/astro/src/content/docs/assets/overview.mdxindex cb2f1a0b8..8f57d0437 100644--- a/docs/astro/src/content/docs/assets/overview.mdx+++ b/docs/astro/src/content/docs/assets/overview.mdx@@ -74,7 +74,7 @@ guarantee and not a schema's.Loading it as an asset rather than fetching the path yourself is not ceremony. A dataasset has a uuid, so moving the file does not break what points at it; it is parsed onceand reference-counted; it can live in a lazy [group](#addressable-groups-lazy-loading) or-come from a CDN; and [hot update](/docs/guides/hot-update/) can replace it in a shipped+come from a CDN; and [hot update](/docs/publishing/hot-update/) can replace it in a shippedgame. A hand-rolled `fetch` of a project path gets none of that — and it *works in theeditor*, which serves the whole project, while the build ships only assets.@@ -122,7 +122,7 @@ nobody holds drops to the evictable warm cache. Bouncing back into the area isthen absorbed by the warm caches instead of the network.`loadByLabel(...)` loads assets tagged with a label instead of a folder group.-This grouping is what maps onto [WeChat subpackages](/docs/guides/wechat/) for+This grouping is what maps onto [WeChat subpackages](/docs/publishing/wechat/) foron-demand download.When the set of assets you want to warm isn't a group or label — say, the next@@ -226,7 +226,7 @@ entities normally.The texture budget defaults to **64 MB** (`RuntimeConfig.textureCacheBudget`,also settable as `textureCacheBudget` in the build config); decoded audio hasits own **32 MB** mirror (`audioCacheBudget` — see the-[audio guide](/docs/guides/audio/)).+[audio guide](/docs/assets/audio/)).## Texture memory & budgets@@ -266,9 +266,9 @@ does this when a texture is truly freed, so you only need it if you destroy andrecreate textures around the asset system's back.For watching these numbers frame-over-frame in the editor and at runtime, see-[Profiling](/docs/guides/profiling/). Per-texture **sampling/filtering**+[Profiling](/docs/performance/profiling/). Per-texture **sampling/filtering**parameters (pixel-art nearest vs. smooth linear) are covered in the-[Sprites guide](/docs/guides/sprites/).+[Sprites guide](/docs/graphics/sprites/).## Best practices@@ -293,6 +293,6 @@ parameters (pixel-art nearest vs. smooth linear) are covered in the## See also-- [WeChat MiniGame](/docs/guides/wechat/) — how addressable groups map to subpackages.-- [Scenes](/docs/guides/scene/) — scenes reference assets and are cooked as entry points.-- [Materials & Shaders](/docs/guides/material/) — `loadMaterial` and shader handles.+- [WeChat MiniGame](/docs/publishing/wechat/) — how addressable groups map to subpackages.+- [Scenes](/docs/world/scenes/) — scenes reference assets and are cooked as entry points.+- [Materials & Shaders](/docs/graphics/materials/) — `loadMaterial` and shader handles.diff --git a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdxindex 3efe207b1..78c156942 100644--- a/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/core-concepts/app-lifecycle.mdx@@ -337,8 +337,8 @@ from it when needed.layer — `PhysicsPlugin`, `PhysicsEvents`, `Physics`, `loadPhysicsModule`,`SpinePlugin`, `SpineEvents`, `Spine` — so hosts can register the pluginswithout a subpath import. The full APIs live on the `esengine/physics` and- `esengine/spine` subpaths. See [Physics](/docs/guides/physics/) and- [Spine](/docs/guides/spine/).+ `esengine/spine` subpaths. See [Physics](/docs/gameplay/physics/) and+ [Spine](/docs/animation/spine/).</Aside>## Hot reload@@ -362,7 +362,7 @@ component identity, so re-imported systems' queries reach the live storage.Consequently, renaming a component or behavior is a structural change (fullreload + state loss for that data), and per-entity `start` hooks run againafter a reload — write them as idempotent setup (see-[Scripting](/docs/guides/scripting/)).+[Scripting](/docs/scripting/overview/)).## Best practices@@ -388,7 +388,7 @@ after a reload — write them as idempotent setup (see- [Plugins & Resources](/docs/core-concepts/plugins-resources/) — reachingsubsystem APIs with `Res(...)`.- [Systems](/docs/core-concepts/systems/) — schedules and system parameters.-- [Building & Exporting](/docs/guides/build-export/) — how side-module+- [Building & Exporting](/docs/publishing/overview/) — how side-moduleartifacts ship per target.-- [Physics](/docs/guides/physics/) and [Spine](/docs/guides/spine/) — the two+- [Physics](/docs/gameplay/physics/) and [Spine](/docs/animation/spine/) — the twosubpath APIs behind side modules.diff --git a/docs/astro/src/content/docs/core-concepts/components.mdx b/docs/astro/src/content/docs/core-concepts/components.mdxindex d20453879..d7f7f65ea 100644--- a/docs/astro/src/content/docs/core-concepts/components.mdx+++ b/docs/astro/src/content/docs/core-concepts/components.mdx@@ -68,10 +68,10 @@ Useful `fields` options: `min` / `max` / `step`, `slider`, `unit`, `enum`(dropdown storing the option's int), `flags` (bitmask multi-select), `tooltip`.Other component-level metadata: `assetFields` (marks a field as an assetreference, so Details renders a picker and the cook ships the dependency),-`animatableFields` (which fields the [Sequencer](/docs/guides/timeline/) can+`animatableFields` (which fields the [Sequencer](/docs/animation/timeline/) cankey — defaults to all numeric fields), `transient` (never saved into the scene —for per-frame runtime state), and `replicatedFields` (synced by-[networking](/docs/guides/networking/)'s state replication).+[networking](/docs/scripting/networking/)'s state replication).## Built-in components@@ -79,9 +79,9 @@ The SDK ships ~30 engine components you query alongside your own — `Transform``Sprite`, `ShapeRenderer`, `Camera`, `Light2D`, `ParticleEmitter`,`SpineAnimation`, `TilemapLayer`, the UI set, the physics colliders, and more.Each is documented in its subsystem guide:-[Sprites & Rendering](/docs/guides/sprites/), [Camera](/docs/guides/camera/),-[2D Lighting](/docs/guides/lighting/), [Physics](/docs/guides/physics/),-[Tilemaps](/docs/guides/tilemap/), [UI](/docs/guides/ui/).+[Sprites & Rendering](/docs/graphics/sprites/), [Camera](/docs/graphics/camera/),+[2D Lighting](/docs/graphics/lighting/), [Physics](/docs/gameplay/physics/),+[Tilemaps](/docs/world/tilemaps/), [UI](/docs/ui/overview/).## Reading and writingdiff --git a/docs/astro/src/content/docs/core-concepts/ecs.mdx b/docs/astro/src/content/docs/core-concepts/ecs.mdxindex 156eb52bd..d0f164edd 100644--- a/docs/astro/src/content/docs/core-concepts/ecs.mdx+++ b/docs/astro/src/content/docs/core-concepts/ecs.mdx@@ -30,10 +30,10 @@ You compose a game from three SDK primitives:- [`defineSystem`](/docs/core-concepts/systems/) — declare a system and what itqueries.- [`App` / plugins](/docs/core-concepts/plugins-resources/) — assemble systems,- resources, and subsystems ([physics](/docs/guides/physics/),- [spine](/docs/guides/spine/), [tilemap](/docs/guides/tilemap/),- [UI](/docs/guides/ui/), [audio](/docs/guides/audio/),- [scene](/docs/guides/scene/)) into a running game.+ resources, and subsystems ([physics](/docs/gameplay/physics/),+ [spine](/docs/animation/spine/), [tilemap](/docs/world/tilemaps/),+ [UI](/docs/ui/overview/), [audio](/docs/assets/audio/),+ [scene](/docs/world/scenes/)) into a running game.```typescriptimport { App } from 'esengine';diff --git a/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdxindex 767213df6..4018e711c 100644--- a/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx+++ b/docs/astro/src/content/docs/core-concepts/plugins-resources.mdx@@ -24,25 +24,25 @@ Every subsystem's imperative API is reached the same way:| Subsystem | Resource | Guide ||---|---|---|-| Input | `Res(Input)` | [Input](/docs/guides/input/) |-| Audio | `Res(Audio)` | [Audio](/docs/guides/audio/) |-| Assets | `Res(Assets)` | [Assets](/docs/guides/assets/) |-| Tilemaps | `Res(Tilemaps)` | [Tilemaps](/docs/guides/tilemap/) |-| Particles | `Res(Particle)` | [Particles](/docs/guides/particle/) |-| Post-processing | `Res(PostProcess)` | [Post-processing](/docs/guides/postprocess/) |-| Scenes | `Res(SceneManager)` | [Scenes](/docs/guides/scene/) |-| Tweens | `Res(Tween)` | [Animation](/docs/guides/animation/) |-| Frame animation | `Res(SpriteAnimation)` | [Animation](/docs/guides/animation/) |-| Animator | `Res(AnimatorController)` | [Animation](/docs/guides/animation/) |-| Timers | `Res(TimerRes)` | [Scripting](/docs/guides/scripting/) |-| Timeline | `Res(Timeline)` | [Timeline](/docs/guides/timeline/) |-| Prefabs | `Res(Prefabs)` | [Prefabs](/docs/guides/prefab/) |-| Navigation / AI | `Res(Nav)` | [Gameplay AI](/docs/guides/ai/) |-| Localization | `Res(Localization)` | [Localization](/docs/guides/localization/) |-| Camera view | `Res(CameraView)` | [Camera](/docs/guides/camera/) |-| UI events | `Res(UIEvents)` | [UI](/docs/guides/ui/) |-| Physics | `Res(Physics)` — from `esengine/physics` | [Physics](/docs/guides/physics/) |-| Spine | `Res(Spine)` — from `esengine/spine` | [Spine](/docs/guides/spine/) |+| Input | `Res(Input)` | [Input](/docs/scripting/input/) |+| Audio | `Res(Audio)` | [Audio](/docs/assets/audio/) |+| Assets | `Res(Assets)` | [Assets](/docs/assets/overview/) |+| Tilemaps | `Res(Tilemaps)` | [Tilemaps](/docs/world/tilemaps/) |+| Particles | `Res(Particle)` | [Particles](/docs/world/particles/) |+| Post-processing | `Res(PostProcess)` | [Post-processing](/docs/graphics/post-processing/) |+| Scenes | `Res(SceneManager)` | [Scenes](/docs/world/scenes/) |+| Tweens | `Res(Tween)` | [Animation](/docs/animation/overview/) |+| Frame animation | `Res(SpriteAnimation)` | [Animation](/docs/animation/overview/) |+| Animator | `Res(AnimatorController)` | [Animation](/docs/animation/overview/) |+| Timers | `Res(TimerRes)` | [Scripting](/docs/scripting/overview/) |+| Timeline | `Res(Timeline)` | [Timeline](/docs/animation/timeline/) |+| Prefabs | `Res(Prefabs)` | [Prefabs](/docs/world/prefabs/) |+| Navigation / AI | `Res(Nav)` | [Gameplay AI](/docs/gameplay/ai/) |+| Localization | `Res(Localization)` | [Localization](/docs/assets/localization/) |+| Camera view | `Res(CameraView)` | [Camera](/docs/graphics/camera/) |+| UI events | `Res(UIEvents)` | [UI](/docs/ui/overview/) |+| Physics | `Res(Physics)` — from `esengine/physics` | [Physics](/docs/gameplay/physics/) |+| Spine | `Res(Spine)` — from `esengine/spine` | [Spine](/docs/animation/spine/) |Physics and Spine are **optional side-modules** loaded on demand, so their APIslive on subpaths to keep the base bundle small; everything else is in the maindiff --git a/docs/astro/src/content/docs/core-concepts/screen.mdx b/docs/astro/src/content/docs/core-concepts/screen.mdxindex b6122f066..79c6c2d65 100644--- a/docs/astro/src/content/docs/core-concepts/screen.mdx+++ b/docs/astro/src/content/docs/core-concepts/screen.mdx@@ -22,7 +22,7 @@ Estella's 2D units model is deliberately simple:half the design height — so at the design aspect the camera shows exactly onedesign box (1920×1080 world units).- The world is **Y-up**; screen coordinates are **Y-down** (converted for you by- [`CameraView`](/docs/guides/camera/)).+ [`CameraView`](/docs/graphics/camera/)).- `Canvas.pixelsPerUnit` (default `100`) is the **physics scale** — world pixelsper Box2D meter — **not** a display scale. Rendering never divides by it.@@ -337,7 +337,7 @@ applyBuildRuntimeConfig(app, {## See also-- [Camera](/docs/guides/camera/) — orthoSize, follow, blending, split-screen.-- [UI](/docs/guides/ui/) — the flexbox layout that consumes the design-pixel box.-- [Physics](/docs/guides/physics/) — where `pixelsPerUnit` actually matters.-- [Editor](/docs/guides/editor/) — the Display settings page and device preview.+- [Camera](/docs/graphics/camera/) — orthoSize, follow, blending, split-screen.+- [UI](/docs/ui/overview/) — the flexbox layout that consumes the design-pixel box.+- [Physics](/docs/gameplay/physics/) — where `pixelsPerUnit` actually matters.+- [Editor](/docs/editor/overview/) — the Display settings page and device preview.diff --git a/docs/astro/src/content/docs/core-concepts/transforms.mdx b/docs/astro/src/content/docs/core-concepts/transforms.mdxindex 6dda154d8..77971569a 100644--- a/docs/astro/src/content/docs/core-concepts/transforms.mdx+++ b/docs/astro/src/content/docs/core-concepts/transforms.mdx@@ -44,9 +44,9 @@ const drift = defineSystem([Query(Mut(Transform))], (q) => {````position.x/y/z`, `rotation.z`, and `scale.x/y/z` are animatable (the-[Sequencer](/docs/guides/timeline/) and [tweens](/docs/guides/animation/#tweens)+[Sequencer](/docs/animation/timeline/) and [tweens](/docs/animation/overview/#tweens)can key them), and `position` / `rotation` / `scale` are replicated by-[networking](/docs/guides/networking/)'s state replication.+[networking](/docs/scripting/networking/)'s state replication.<Aside type="note">`LocalTransform` and `WorldTransform` are exported as **aliases of the same@@ -67,14 +67,14 @@ can key them), and `position` / `rotation` / `scale` are replicated bythe angle toward a target directly).- **`position.z` is draw-order, not perspective**: 2D rendering orders coarselyby each renderer's sorting `layer`; within a layer, use `z` for fine ordering- (or a [y-sorted layer](/docs/guides/sprites/#draw-order--sorting-layers) for+ (or a [y-sorted layer](/docs/graphics/sprites/#draw-order--sorting-layers) fortop-down depth). It does not foreshorten or scale sprites.- **Screen space is Y-down**: pointer coordinates (`Input.mouseX/mouseY`, UI hittesting) are pixels from the **top-left** of the canvas, Y increasingdownward.Convert between the two with the `CameraView` resource (see-[Camera](/docs/guides/camera/#screen--world-coordinates) for the full API):+[Camera](/docs/graphics/camera/#screen--world-coordinates) for the full API):```typescriptimport { defineSystem, Res, CameraView, Input } from 'esengine';@@ -190,11 +190,11 @@ const aim = defineSystem([Query(Mut(Transform)).with(Turret), Res(CameraView)],To animate a rotation, `TweenTarget.RotationZ` drives the Z angle **in radians**(the engine rebuilds the quaternion each step), and the Sequencer keys-`rotation.z` the same way — see [Animation](/docs/guides/animation/#tweens).+`rotation.z` the same way — see [Animation](/docs/animation/overview/#tweens).<Aside type="tip">For aiming math without touching rotation at all, `v2.fromAngle(angle, len)`- and `v2.rotate(v, angle)` from the [math helpers](/docs/guides/math/) produce+ and `v2.rotate(v, angle)` from the [math helpers](/docs/scripting/math/) producedirection vectors directly.</Aside>@@ -302,7 +302,7 @@ world space).## See also- [Components](/docs/core-concepts/components/) — how components declare and store data.-- [Camera](/docs/guides/camera/) — orthoSize, follow, and screen ↔ world conversion.-- [Sprites & Rendering](/docs/guides/sprites/) — sorting layers, y-sort, and draw order.-- [Physics](/docs/guides/physics/) — the meter-based side of the unit system.-- [Math Helpers](/docs/guides/math/) — vector and rotation math on the canonical types.+- [Camera](/docs/graphics/camera/) — orthoSize, follow, and screen ↔ world conversion.+- [Sprites & Rendering](/docs/graphics/sprites/) — sorting layers, y-sort, and draw order.+- [Physics](/docs/gameplay/physics/) — the meter-based side of the unit system.+- [Math Helpers](/docs/scripting/math/) — vector and rotation math on the canonical types.diff --git a/docs/astro/src/content/docs/editor/overview.mdx b/docs/astro/src/content/docs/editor/overview.mdxindex 6e562020e..5432003e8 100644--- a/docs/astro/src/content/docs/editor/overview.mdx+++ b/docs/astro/src/content/docs/editor/overview.mdx@@ -28,7 +28,7 @@ A project is a folder on disk. The pieces the editor cares about:| `.esengine/workspace.json` | Editor-local state (last-opened scene, panel layout). Gitignored. || `assets/scenes/*.esscene` | Your scenes. || `assets/…` | Textures, materials, tilesets, and other assets, each with a `.meta` sidecar. |-| `src/components.ts` | The **declaration entry** — the editor evaluates this module and everything it imports to learn your components. Declare them anywhere; re-export them from here. See [Scripting](/docs/guides/scripting/#where-declarations-live). |+| `src/components.ts` | The **declaration entry** — the editor evaluates this module and everything it imports to learn your components. Declare them anywhere; re-export them from here. See [Scripting](/docs/scripting/overview/#where-declarations-live). || `src/main.ts` | The **startup entry** — where you register systems. This is what runs the game; the editor never evaluates it. |Assets are referenced portably by UUID (`@uuid:…`) rather than by path, so moving or@@ -238,10 +238,10 @@ widget** — most of them for UI nodes:**Stretch** toggles — with **padding** edited as a four-edge `sides` control;- an inline **Controllers** strip that pulls per-node state authoring into the inspector:pick a state page and *gear* a field to bind it, all without leaving the panel (see- [UI controllers](/docs/guides/ui-controllers/));+ [UI controllers](/docs/ui/controllers/));- for a **material**, a **Shader** picker to swap the bound shader — a built-in template ora project `.esshader` — see- [Materials & Shaders](/docs/guides/material/#choosing--sharing-shaders-in-the-editor).+ [Materials & Shaders](/docs/graphics/materials/#choosing--sharing-shaders-in-the-editor).@@ -276,7 +276,7 @@ assets in place:never bundled and its component never reaches Add Component, so the dialog also addsthe one line in your project's script entry that pulls it in — which entry dependingon whether you're making a component or a system. See-[Scripting](/docs/guides/scripting/#the-new-script-dialog).+[Scripting](/docs/scripting/overview/#the-new-script-dialog).**Import** by dragging files in from Finder / Explorer, or via Import…. Each asset getsa `.meta` sidecar the first time it's seen. Per-asset context actions include Rename,@@ -325,13 +325,13 @@ automatic reload if the GPU render process is lost.Double-click an asset in the Content Browser to open its editor in a document tab.- **Sequencer** — a timeline / curve editor for keyframe animation. See- [Timeline](/docs/guides/timeline/).+ [Timeline](/docs/animation/timeline/).- **Tilemap painter** — tools for **brush, erase, rectangle, line, bucket, select,eyedropper**, and **terrain (autotile)**, plus stamp **flip-H / flip-V / rotate-90°**(`H` / `V` / `R` while a paint tool is active) and a **random-scatter mode** (`D`). Thepalette selects with the arrow keys (`Shift` grows a multi-tile stamp), and maps canbe **orthogonal, isometric, staggered, or hexagonal**. See- [Tilemaps](/docs/guides/tilemap/).+ [Tilemaps](/docs/world/tilemaps/).- **Tileset editor** — author per-tile **collision** (box, circle, polygon, slopepresets; one-way / sensor / material modifiers) with **direct-manipulation** shapeeditors on a magnified tile: drag a circle's **centre or radius**, **click-add / drag /@@ -342,9 +342,9 @@ Double-click an asset in the Content Browser to open its editor in a document taframe thumbnails to **reorder**, or set the whole loop to **one uniform duration**, witha live preview.- **State Machine** (`.esfsm`) and **Behavior Tree** (`.esbt`) editors — visual graphs- for AI. See [Gameplay AI](/docs/guides/ai/).+ for AI. See [Gameplay AI](/docs/gameplay/ai/).- **Material Graph** (`.esmatgraph`) — a node editor that compiles to a shader. See- [Materials & Shaders](/docs/guides/material/).+ [Materials & Shaders](/docs/graphics/materials/).The State Machine and Behavior Tree editors share a common node canvas: **middle-drag**to pan, **wheel** to zoom toward the cursor, drag an output handle onto another node to@@ -365,10 +365,10 @@ Open settings with **Ctrl / ⌘ + ,** or the Activity Bar's gear. Settings are g(how the main camera scales the design resolution without a UI Canvas; `None` = off).- **UI** — the project's widget **theme** (dark / light) and per-role **ThemeColors** overrides, applied identically in the editor, Play, and every export.- See [UI widgets — theming](/docs/guides/ui-components/#theming).+ See [UI widgets — theming](/docs/ui/widgets/#theming).- **Physics** — enable, gravity, sixteen collision-layer names and a 16×16 collisionmatrix, plus solver tuning (fixed timestep, sub-steps, contact Hz/damping/push- speed, sleeping, continuous collision). See [Physics](/docs/guides/physics/).+ speed, sleeping, continuous collision). See [Physics](/docs/gameplay/physics/).- **Rendering** — up to thirty-two named sorting layers that populate the inspector'slayer dropdown, and which of them y-sort. The names are suggestions, not a limit:a render `layer` still accepts a number outside them.@@ -379,7 +379,7 @@ Open settings with **Ctrl / ⌘ + ,** or the Activity Bar's gear. Settings are gThe editor ships in **English** and **简体中文** and follows your system language onfirst launch. Switch it under **Settings → Appearance → Language** — the changeapplies after a reload (the editor prompts for one). The editor's UI strings run on-the same [localization engine](/docs/guides/localization/) your game uses at runtime.+the same [localization engine](/docs/assets/localization/) your game uses at runtime.## Keyboard shortcuts@@ -425,7 +425,7 @@ focus is always shown with a visible focus ring.## See also-- [Scenes](/docs/guides/scene/) — what a `.esscene` holds and how it loads.-- [Scripting](/docs/guides/scripting/) — project components appear in the inspector automatically.-- [Prefabs](/docs/guides/prefab/) — reusable entity templates with per-instance overrides.-- [Building & Exporting](/docs/guides/build-export/) — ship the project to web, WeChat, or a playable ad.+- [Scenes](/docs/world/scenes/) — what a `.esscene` holds and how it loads.+- [Scripting](/docs/scripting/overview/) — project components appear in the inspector automatically.+- [Prefabs](/docs/world/prefabs/) — reusable entity templates with per-instance overrides.+- [Building & Exporting](/docs/publishing/overview/) — ship the project to web, WeChat, or a playable ad.diff --git a/docs/astro/src/content/docs/extending/built-in-agent.mdx b/docs/astro/src/content/docs/extending/built-in-agent.mdxindex 09b97f1ae..19441135f 100644--- a/docs/astro/src/content/docs/extending/built-in-agent.mdx+++ b/docs/astro/src/content/docs/extending/built-in-agent.mdx@@ -8,7 +8,7 @@ import { Aside, Steps } from '@astrojs/starlight/components';The editor ships with an agent of its own. You type a sentence; it reads the scene,calls the same tools the editor's UI calls, and shows you every one of them as itgoes. Nothing about it is a separate copy of the editor: it drives the exact tool-catalog an [external MCP client](/docs/guides/mcp/) drives, so what it can do and+catalog an [external MCP client](/docs/extending/mcp/) drives, so what it can do andwhat the editor can do are one list.<Aside type="tip">@@ -127,9 +127,9 @@ screen: they show what it actually looked at.## See also-- [AI Agents (MCP)](/docs/guides/mcp/) — the same tool catalog, driven from Claude+- [AI Agents (MCP)](/docs/extending/mcp/) — the same tool catalog, driven from ClaudeCode, Cursor, or your own agent instead of from inside the editor.-- [Event Binding](/docs/guides/events/) — what the agent reaches for when you ask+- [Event Binding](/docs/scripting/events/) — what the agent reaches for when you askfor behaviour without code.-- [Prefabs](/docs/guides/prefab/) — in Prefab Mode the agent edits the prefab, not+- [Prefabs](/docs/world/prefabs/) — in Prefab Mode the agent edits the prefab, notthe scene. Check the document it is working on before asking for a big change.diff --git a/docs/astro/src/content/docs/extending/mcp.mdx b/docs/astro/src/content/docs/extending/mcp.mdxindex e7204036b..9c6b96a95 100644--- a/docs/astro/src/content/docs/extending/mcp.mdx+++ b/docs/astro/src/content/docs/extending/mcp.mdx@@ -161,7 +161,7 @@ hundreds of KB of JSON, which does not belong in a chat message. Write it with### Wiring a buttonA scene can give a button behaviour without any game code — an-[Event Binding](/docs/guides/events/) row says *when this event fires, run that+[Event Binding](/docs/scripting/events/) row says *when this event fires, run thatnamed action*. `set_event_bindings` replaces an entity's rows in **one undo step**(an empty list unwires it), and `get_event_bindings` reads them back:@@ -199,5 +199,5 @@ boots the dev editor, and two e2e suites (`editor:mcp:e2e`,## See also-- [The Editor](/docs/guides/editor/) — the visual editor this automation surface drives.-- [Scripting](/docs/guides/scripting/) — the same scene / component model, from game code.+- [The Editor](/docs/editor/overview/) — the visual editor this automation surface drives.+- [Scripting](/docs/scripting/overview/) — the same scene / component model, from game code.diff --git a/docs/astro/src/content/docs/gameplay/ai.mdx b/docs/astro/src/content/docs/gameplay/ai.mdxindex e62cdeb8f..c3a979340 100644--- a/docs/astro/src/content/docs/gameplay/ai.mdx+++ b/docs/astro/src/content/docs/gameplay/ai.mdx@@ -59,7 +59,7 @@ registerAction('chase', (ctx) => {```Every action and condition receives an **`AiContext`** for the agent it runs on. It-is the same programming model as a [`defineBehavior`](/docs/guides/scripting/) update+is the same programming model as a [`defineBehavior`](/docs/scripting/overview/) update— entity, world, and commands access — plus a per-agent `blackboard`:| Member | Type | Description |@@ -104,7 +104,7 @@ the agent entity (the same channel your code and the editor use):| Name | Kind | Effect ||---|---|---|-| `timeline.play` | action | Raise the agent's [`TimelinePlayer`](/docs/guides/timeline/) play flag. On a finished clip this replays it from the top. |+| `timeline.play` | action | Raise the agent's [`TimelinePlayer`](/docs/animation/timeline/) play flag. On a finished clip this replays it from the top. || `timeline.pause` | action | Lower the play flag (resume with `timeline.play`). || `timeline.finished` | condition | True once the clip has completed (a `once` clip that ran to its end) and is not playing. || `spriteAnim.play` | action | Play the agent's sprite flipbook; the **argument** switches to that clip. |@@ -585,8 +585,8 @@ code is the shared leaves above plus the one-time grid.## See also-- [Scripting](/docs/guides/scripting/) — behaviors are declarative systems; leaves are plain functions.-- [Animation](/docs/guides/animation/) — drive sprite clips from a state machine.-- [Scenes](/docs/guides/scene/) — `.esfsm` / `.esbt` assets load and serialize with the scene.-- [Event Binding](/docs/guides/events/) — a click or a trigger can `fsm.fire` into a state+- [Scripting](/docs/scripting/overview/) — behaviors are declarative systems; leaves are plain functions.+- [Animation](/docs/animation/overview/) — drive sprite clips from a state machine.+- [Scenes](/docs/world/scenes/) — `.esfsm` / `.esbt` assets load and serialize with the scene.+- [Event Binding](/docs/scripting/events/) — a click or a trigger can `fsm.fire` into a statemachine; actions and conditions come from this same registry.diff --git a/docs/astro/src/content/docs/gameplay/markers.mdx b/docs/astro/src/content/docs/gameplay/markers.mdxindex 19414e534..60fddb1a9 100644--- a/docs/astro/src/content/docs/gameplay/markers.mdx+++ b/docs/astro/src/content/docs/gameplay/markers.mdx@@ -18,7 +18,7 @@ entities you select, edit in the Inspector, serialize with the scene, and read wA Marker is just the `Marker` component (a `type` string and a free-form`properties` map) on an entity that also has a `Transform`. On its own it's apoint — the game asks "where do I spawn the player?" by querying markers of a given-`type`. Add a static [`RigidBody`](/docs/guides/physics/) and a sensor collider and+`type`. Add a static [`RigidBody`](/docs/gameplay/physics/) and a sensor collider andthe same entity becomes a trigger zone; the **Trigger Area** preset wires all ofthat up for you.@@ -27,7 +27,7 @@ Because a Marker is pure ECS, there is nothing special to load or parse:- It **serializes** with the scene like any component.- It shows in the **Inspector**, including a key→value editor for its properties.- It's **`Query`-able** — one code path reads markers you placed by hand *and*- markers imported from a [Tiled](/docs/guides/tilemap/) `.tmj` object layer.+ markers imported from a [Tiled](/docs/world/tilemaps/) `.tmj` object layer.The `type` vocabulary is entirely yours: `spawn`, `waypoint`, `door`, `chest`,`checkpoint` — the game defines what the strings mean.@@ -35,7 +35,7 @@ The `type` vocabulary is entirely yours: `spawn`, `waypoint`, `door`, `chest`,## Setup`Marker` lives in the main `esengine` barrel — no plugin needed to place or query-one. A **Trigger Area** carries a sensor collider, so it needs [physics](/docs/guides/physics/):+one. A **Trigger Area** carries a sensor collider, so it needs [physics](/docs/gameplay/physics/):in the editor and web runtime the physics module loads automatically when a sceneuses physics components; in a custom app, add the plugin yourself:@@ -51,7 +51,7 @@ app.addPlugin(new PhysicsPlugin('physics.js'));Physics → Trigger Area** drops a sensor region (Transform + static RigidBody + sensorBoxCollider + Marker). A Marker shows a **pin gizmo** in the viewport; a Trigger Areaalso draws its collider outline, which you shape with the same-[collider gizmo](/docs/guides/physics/) as any other body.+[collider gizmo](/docs/gameplay/physics/) as any other body.In the Inspector, set the marker's **Type** and add any number of custom**properties** (a key→value map — `targetScene: "level2"`, `team: "red"`, and so on).@@ -127,14 +127,14 @@ const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, mar```Keep sensors cheap in a busy world by putting triggers and the bodies that should-notice them on dedicated [collision layers](/docs/guides/physics/#collision-filtering),+notice them on dedicated [collision layers](/docs/gameplay/physics/#collision-filtering),so each sensor's mask narrows what it considers. See-[Collision & sensor events](/docs/guides/physics/#collision--sensor-events) for the+[Collision & sensor events](/docs/gameplay/physics/#collision--sensor-events) for thefull event surface.## Imported from Tiled-When a [`Tilemap`](/docs/guides/tilemap/) loads a `.tmj` map, its **object layers**+When a [`Tilemap`](/docs/world/tilemaps/) loads a `.tmj` map, its **object layers**converge onto the same entities you author by hand — no separate structure to walk:| Tiled object | Becomes |@@ -159,15 +159,15 @@ if you need a shape's exact vertices.- **Reuse one marker vocabulary** across hand-authored scenes and imported Tiled maps— the query code doesn't care where the marker came from.- **Trigger Areas are sensors** — for anything you want to *block* (a wall, a ledge),- paint a [collision layer](/docs/guides/tilemap/#collision-obstacle-layers) or use a+ paint a [collision layer](/docs/world/tilemaps/#collision-obstacle-layers) or use anon-sensor collider instead.## See also-- [Tilemaps](/docs/guides/tilemap/) — collision (obstacle) layers and Tiled object+- [Tilemaps](/docs/world/tilemaps/) — collision (obstacle) layers and Tiled objectlayers that feed the same Markers.-- [Physics](/docs/guides/physics/) — sensors, collision filtering, and the+- [Physics](/docs/gameplay/physics/) — sensors, collision filtering, and the`PhysicsEvents` resource behind Trigger Areas.-- [Scenes](/docs/guides/scene/) — Markers and Trigger Areas serialize with the scene.-- [Event Binding](/docs/guides/events/) — run an action when something enters a Trigger+- [Scenes](/docs/world/scenes/) — Markers and Trigger Areas serialize with the scene.+- [Event Binding](/docs/scripting/events/) — run an action when something enters a TriggerArea, authored on the area itself with no code.diff --git a/docs/astro/src/content/docs/gameplay/physics.mdx b/docs/astro/src/content/docs/gameplay/physics.mdxindex 7a706ed38..efbe2600a 100644--- a/docs/astro/src/content/docs/gameplay/physics.mdx+++ b/docs/astro/src/content/docs/gameplay/physics.mdx@@ -368,7 +368,7 @@ the character, a **Kinematic** `RigidBody`. The mover excludes the character's obody automatically, so its `maskBits` need not avoid its own collision layer. Drive`velocity` from a fixed-timestep system so motion is frame-rate independent; read the`isOnFloor` edge for jumps (delivered correctly to `FixedUpdate` — see-[Input](/docs/guides/input/#fixed-timestep-physics)).+[Input](/docs/scripting/input/#fixed-timestep-physics)).| Property | Type | Default | Description ||---|---|---|---|@@ -394,7 +394,7 @@ stairs and slopes.</Aside>The physics plugin installs a **`PhysicsDebugDraw`** resource — an in-game overlaythat strokes collider outlines, velocity vectors, and contact points through the-[`Draw`](/docs/guides/drawing/) API. It ships disabled; flip `enabled` from any+[`Draw`](/docs/graphics/drawing/) API. It ships disabled; flip `enabled` from anysystem to see exactly what the solver sees:```typescript@@ -439,5 +439,5 @@ collider/joint gizmos under the Physics Show Flag (see## See also-- [Scenes](/docs/guides/scene/) — physics components serialize with the scene.-- [Math Helpers](/docs/guides/math/) — vector math for velocities and directions.+- [Scenes](/docs/world/scenes/) — physics components serialize with the scene.+- [Math Helpers](/docs/scripting/math/) — vector math for velocities and directions.diff --git a/docs/astro/src/content/docs/getting-started/introduction.mdx b/docs/astro/src/content/docs/getting-started/introduction.mdxindex 776c0b276..37805ab7c 100644--- a/docs/astro/src/content/docs/getting-started/introduction.mdx+++ b/docs/astro/src/content/docs/getting-started/introduction.mdx@@ -30,7 +30,7 @@ desktop, WeChat MiniGames, playable ads, and native Android / iOS apps**.|-------|--------------|| **TypeScript SDK** (`esengine`) | The authored surface: `App`, `World`, systems, components, queries, plugins. || **WasmBridge** | The single boundary between the SDK and the engine, with a generated, hash-checked memory layout. |-| **C++ / WebAssembly** | The engine core: ECS storage, the renderer (`GfxDevice`), resources, particles, tilemaps, text. On [mobile](/docs/guides/mobile/) the same core is compiled to arm64 instead. |+| **C++ / WebAssembly** | The engine core: ECS storage, the renderer (`GfxDevice`), resources, particles, tilemaps, text. On [mobile](/docs/publishing/android-ios/) the same core is compiled to arm64 instead. |For the full architecture, see[`ARCHITECTURE.md`](https://github.com/esengine/estella/blob/master/docs/ARCHITECTURE.md).diff --git a/docs/astro/src/content/docs/graphics/camera.mdx b/docs/astro/src/content/docs/graphics/camera.mdxindex 989cfa6f2..98f0a8c68 100644--- a/docs/astro/src/content/docs/graphics/camera.mdx+++ b/docs/astro/src/content/docs/graphics/camera.mdx@@ -66,7 +66,7 @@ the camera by moving its entity's `Transform`.## Zoom & projection`orthoSize` is the zoom control — halve it to double the on-screen scale. Because-it's `animatable`, the smoothest way to zoom is a [tween](/docs/guides/animation/):+it's `animatable`, the smoothest way to zoom is a [tween](/docs/animation/overview/):```typescriptimport { defineSystem, Res, Tween, TweenTarget } from 'esengine';@@ -308,6 +308,6 @@ split-screen, left and right halves:- [Screen & Design Resolution](/docs/core-concepts/screen/) — the design-resolutionfit, scale modes, `ScreenScaling`, and `pixelPerfect` in depth.-- [Animation](/docs/guides/animation/) — tween `orthoSize` for smooth zooms.-- [Input](/docs/guides/input/) — `screenToWorld` with the mouse for picking.-- [UI](/docs/guides/ui/) — UI renders in screen space, independent of the camera.+- [Animation](/docs/animation/overview/) — tween `orthoSize` for smooth zooms.+- [Input](/docs/scripting/input/) — `screenToWorld` with the mouse for picking.+- [UI](/docs/ui/overview/) — UI renders in screen space, independent of the camera.diff --git a/docs/astro/src/content/docs/graphics/drawing.mdx b/docs/astro/src/content/docs/graphics/drawing.mdxindex 9ab611885..be29df980 100644--- a/docs/astro/src/content/docs/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/graphics/drawing.mdx@@ -5,7 +5,7 @@ description: Draw beyond components — immediate-mode primitives with Draw, vecimport { Aside } from '@astrojs/starlight/components';-Most visuals are components — [sprites](/docs/guides/sprites/), tilemaps,+Most visuals are components — [sprites](/docs/graphics/sprites/), tilemaps,particles. When you need something they can't express — debug overlays, proceduralshapes, custom geometry — the engine exposes its drawing layer directly.@@ -15,7 +15,7 @@ shapes, custom geometry — the engine exposes its drawing layer directly.|---|---|---|| `Draw` | **Immediate**, global — commands batch and clear every frame. | Debug overlays, gizmos, anything redrawn from scratch each frame. || `Graphics` | **Retained** path recorder — build once, replay through `Draw` with `flush()`. | Vector shapes with paths/béziers/arcs you don't want to re-tessellate per frame. |-| `ShapeRenderer` / `Mesh2D` | **Components** — entities with sorting layers, materials, editor gizmos. | Shapes/meshes that are part of the scene (see [Sprites](/docs/guides/sprites/)). |+| `ShapeRenderer` / `Mesh2D` | **Components** — entities with sorting layers, materials, editor gizmos. | Shapes/meshes that are part of the scene (see [Sprites](/docs/graphics/sprites/)). |Rule of thumb: if the visual belongs to the *scene* (sorted, saved, inspectable),make it a component; if it belongs to a *frame* (debug, HUD-ish overlays,@@ -118,7 +118,7 @@ field alone are not change-detected.Where `Mesh2D` is the *component* path, `Geometry` is the *immediate* one: ituploads an indexed vertex buffer and hands back a **handle** you draw yourself —-paired with a [material](/docs/guides/material/) via+paired with a [material](/docs/graphics/materials/) via`Draw.drawMeshWithMaterial(geometry, material, transform?)` (or a raw shader via`Draw.drawMesh(geometry, shader, transform)`).@@ -162,7 +162,7 @@ layout, so they pair directly with fragment-only `.esshader` materials.## Offscreen targets: `RenderTexture`For minimaps, portraits, mirrors — and as the backing of-[cache-as-bitmap](/docs/guides/sprites/) — `RenderTexture` allocates an offscreen+[cache-as-bitmap](/docs/graphics/sprites/) — `RenderTexture` allocates an offscreenrender target. Wrap draw commands in `begin`/`end` to render into it; theresulting `texture` is an ordinary texture handle usable anywhere (a`Sprite.texture`, `Draw.texture`, a material texture param):@@ -203,6 +203,6 @@ whatever you draw between `begin`/`end`, under a view-projection matrix you buil## See also-- [Sprites & Rendering](/docs/guides/sprites/) — the component path for images and shapes.-- [Materials & Shaders](/docs/guides/material/) — custom shaders for any renderable.-- [Camera](/docs/guides/camera/) — where the view-projection your callbacks draw under comes from.+- [Sprites & Rendering](/docs/graphics/sprites/) — the component path for images and shapes.+- [Materials & Shaders](/docs/graphics/materials/) — custom shaders for any renderable.+- [Camera](/docs/graphics/camera/) — where the view-projection your callbacks draw under comes from.diff --git a/docs/astro/src/content/docs/graphics/lighting.mdx b/docs/astro/src/content/docs/graphics/lighting.mdxindex ef9b0a14e..bf734fbd5 100644--- a/docs/astro/src/content/docs/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/graphics/lighting.mdx@@ -117,7 +117,7 @@ void main() {In the editor, **New Material (Lit)** in the Content Browser creates exactly this —a ready lit material with a tint and an optional normal map. From code, compile and-assign it as in [Materials & Shaders](/docs/guides/material/):+assign it as in [Materials & Shaders](/docs/graphics/materials/):```typescriptimport { Material, defineSystem, Query, Mut, Sprite } from 'esengine';@@ -130,7 +130,7 @@ const applyLit = defineSystem([Query(Mut(Sprite))], (q) => {```You can also build a lit material visually — set the **Material Graph**'s domain to-`Lit2D` — see the [material graph](/docs/guides/material/) section.+`Lit2D` — see the [material graph](/docs/graphics/materials/) section.<Aside type="tip">Every renderer that takes a `material` — `Sprite`, `SpineAnimation`,@@ -144,7 +144,7 @@ The `N` you pass to `applyLighting2D` is the surface normal. Passing a constant`vec3(0, 0, 1)` gives flat, evenly-lit surfaces. For per-pixel relief, sample a**normal map** in the shader and use that as `N` instead — the same base color thencatches highlights and shadow from each light's direction. Add the normal texture as a-`#pragma param … texture` on your lit material (see [Materials & Shaders](/docs/guides/material/)).+`#pragma param … texture` on your lit material (see [Materials & Shaders](/docs/graphics/materials/)).## Casting shadows@@ -186,7 +186,7 @@ your sprites; the difference shows wherever colors mix.Linear mode is also the door to **HDR**: where float render targets are available(WebGPU always; WebGL2 with `EXT_color_buffer_float`), the post-process chain runs inhalf-float, so a light with `intensity` above 1 pushes real over-range energy into-[bloom and tonemap](/docs/guides/postprocess/) — bright lights glow.+[bloom and tonemap](/docs/graphics/post-processing/) — bright lights glow.Enable it in **Project Settings → Rendering → Color space → Linear**. Shaders compileagainst the mode, so it is fixed at engine boot — the editor prompts for a reload. The@@ -206,15 +206,15 @@ const app = createWebApp(module, { colorSpace: 'linear' });- **Add a light** via **Create… → Light**, or add a `Light2D` component to an existingentity in the Details panel.- Lights are drawn as **gizmos** in edit mode — an icon plus the reach circle and the- direction / cone — so you can aim and size them by eye. See [The Editor](/docs/guides/editor/).+ direction / cone — so you can aim and size them by eye. See [The Editor](/docs/editor/overview/).- Tune `color` (a color picker), `intensity`, `radius`, and the spot angles live inDetails; the results update in the viewport immediately.- All of a light's visual fields (`color`, `intensity`, `radius`, the angles, and the- shadow settings) are **animatable** — key them in the [Sequencer](/docs/guides/timeline/)+ shadow settings) are **animatable** — key them in the [Sequencer](/docs/animation/timeline/)for flickering torches, day/night cycles, or a pulsing beacon.## See also-- [Materials & Shaders](/docs/guides/material/) — lit materials and custom shading.-- [Post-processing](/docs/guides/postprocess/) — bloom and color grading over the lit scene.-- [Sprites & Rendering](/docs/guides/sprites/) — normal maps that give 2D sprites depth under light.+- [Materials & Shaders](/docs/graphics/materials/) — lit materials and custom shading.+- [Post-processing](/docs/graphics/post-processing/) — bloom and color grading over the lit scene.+- [Sprites & Rendering](/docs/graphics/sprites/) — normal maps that give 2D sprites depth under light.diff --git a/docs/astro/src/content/docs/graphics/materials.mdx b/docs/astro/src/content/docs/graphics/materials.mdxindex 22b09a020..c89ec506e 100644--- a/docs/astro/src/content/docs/graphics/materials.mdx+++ b/docs/astro/src/content/docs/graphics/materials.mdx@@ -295,7 +295,7 @@ Materials aren't limited to component renderers: the **`Geometry`** API(`Geometry.create` with a `GeometryOptions` vertex layout, plus `createQuad` /`createCircle` / `createPolygon` helpers) builds handle-based meshes you drawimmediately with `Draw.drawMeshWithMaterial(geometry, material)` — the full-reference lives in [Custom Drawing](/docs/guides/drawing/).+reference lives in [Custom Drawing](/docs/graphics/drawing/).## Best practices@@ -318,6 +318,6 @@ reference lives in [Custom Drawing](/docs/guides/drawing/).## See also-- [Post-processing](/docs/guides/postprocess/) — full-screen effects (a separate pipeline).-- [Assets](/docs/guides/assets/) — `loadMaterial` and shader handles.-- [Particles](/docs/guides/particle/) — assign a custom `material` to an emitter.+- [Post-processing](/docs/graphics/post-processing/) — full-screen effects (a separate pipeline).+- [Assets](/docs/assets/overview/) — `loadMaterial` and shader handles.+- [Particles](/docs/world/particles/) — assign a custom `material` to an emitter.diff --git a/docs/astro/src/content/docs/graphics/post-processing.mdx b/docs/astro/src/content/docs/graphics/post-processing.mdxindex 27e289c34..1d1c23118 100644--- a/docs/astro/src/content/docs/graphics/post-processing.mdx+++ b/docs/astro/src/content/docs/graphics/post-processing.mdx@@ -37,7 +37,7 @@ you add them — `grayscale` (full desaturation), `vignette`, `bloom`, `outline`## HDR (linear color space)When the project renders in the **linear color space** (see-[Lighting](/docs/guides/lighting/)), the effect chain runs in **half-float HDR**+[Lighting](/docs/graphics/lighting/)), the effect chain runs in **half-float HDR**wherever float render targets are available — always on WebGPU, and on WebGL2 withthe near-universal `EXT_color_buffer_float`. Light accumulation past `1.0` (a`Light2D` with `intensity` above 1) then *survives* into the chain instead of@@ -138,5 +138,5 @@ stack.addPass('lutGrade', getEffectDef('lutGrade')!.factory())## See also-- [Materials & Shaders](/docs/guides/material/) — per-object shaders (a separate path).-- [Camera](/docs/guides/camera/) — bind a stack per camera.+- [Materials & Shaders](/docs/graphics/materials/) — per-object shaders (a separate path).+- [Camera](/docs/graphics/camera/) — bind a stack per camera.diff --git a/docs/astro/src/content/docs/graphics/sprites.mdx b/docs/astro/src/content/docs/graphics/sprites.mdxindex aa3d77e3b..271602225 100644--- a/docs/astro/src/content/docs/graphics/sprites.mdx+++ b/docs/astro/src/content/docs/graphics/sprites.mdx@@ -7,13 +7,13 @@ import { Aside } from '@astrojs/starlight/components';The **`Sprite`** is the workhorse 2D renderer: an entity with a `Sprite` componentdraws a textured quad in the world. For solid primitives without a texture there's-**`ShapeRenderer`**. Everything is drawn through a [Camera](/docs/guides/camera/), and+**`ShapeRenderer`**. Everything is drawn through a [Camera](/docs/graphics/camera/), anddraw order is controlled by **sorting layers**.## Your first spriteA sprite needs a `Transform` (where it is) and a `Sprite` (what it draws). Load a-texture through the [`Assets`](/docs/guides/assets/) resource and put its handle on the+texture through the [`Assets`](/docs/assets/overview/) resource and put its handle on thesprite:```typescript@@ -41,7 +41,7 @@ Content Browser onto an entity, or set the Sprite's texture field in Details.| `pivot` | `{0.5,0.5}` | Anchor point (0–1) the sprite rotates and scales about. || `layer` | `0` | Sorting layer — controls draw order (see below). || `flipX` / `flipY` | `false` | Mirror horizontally / vertically. |-| `material` | `0` | A custom [material](/docs/guides/material/) handle (`0` = the default sprite shader). |+| `material` | `0` | A custom [material](/docs/graphics/materials/) handle (`0` = the default sprite shader). || `lit` | `false` | Receive 2D lights with a flat normal — the one-flag path to lit sprites (a custom `material` overrides it). || `uvOffset` / `uvScale` | `{0,0}` / `{1,1}` | Sub-rectangle of the texture to show (for atlases / scrolling). || `tileSize` / `tileSpacing` | `{0,0}` | Repeat the texture across the sprite (`0` = no tiling). |@@ -59,7 +59,7 @@ sprite.color = { r: 1, g: 1, b: 1, a: 0.5 }; // 50% transparent````color` (and `size`) are **animatable** — key them in the-[Sequencer](/docs/guides/timeline/) for flashes and fades.+[Sequencer](/docs/animation/timeline/) for flashes and fades.## Size & pivot@@ -84,7 +84,7 @@ screen — which is why `pivot: {0, 0}` is the **bottom-left** corner, not the t<Aside type="note">`Canvas.pixelsPerUnit` (default `100`) does **not** scale sprites — it's the**physics meter scale**: how many design pixels make one Box2D meter (see- [Physics](/docs/guides/physics/)). A sprite's displayed size is `size` ×+ [Physics](/docs/gameplay/physics/)). A sprite's displayed size is `size` ×`Transform` scale, nothing else. The full units-and-spaces picture is in[Transforms](/docs/core-concepts/transforms/).</Aside>@@ -181,7 +181,7 @@ so a sprite at z = -400 is grabbable where it is drawn.a separate texture.- **Atlases**: show one cell of a packed sheet by setting `uvOffset` and `uvScale` tothe cell's normalized rectangle. (For frame-by-frame animation, drive these from the- [Animator](/docs/guides/animation/) instead of by hand.)+ [Animator](/docs/animation/overview/) instead of by hand.)- **Scrolling**: animate `uvOffset` over time to scroll a texture (water, conveyorbelts), and set `tileSize` to repeat it across a large sprite.@@ -226,7 +226,7 @@ texture): **Repeat** tiles it, **Clamp to edge** stretches the border pixel, andcrisp, but a camera at a fractional position still lands sprites between screenpixels and shimmers as it moves. Pair it with the camera's `pixelPerfect` flag,which snaps the (orthographic) camera to the pixel grid — see- [Camera](/docs/guides/camera/).+ [Camera](/docs/graphics/camera/).</Aside>## Parallax backgrounds@@ -239,12 +239,12 @@ background.## Custom materials & lightingAssign `sprite.material` to draw the sprite with your own shader — a tint, a-dissolve, a distortion — see [Materials & Shaders](/docs/guides/material/).+dissolve, a distortion — see [Materials & Shaders](/docs/graphics/materials/).To make a sprite respond to `Light2D` lights, the simplest path is to set`sprite.lit = true` — no custom material needed (it's lit with a flat normal). Fornormal maps or a fully custom look, use a **Lit-2D material** instead. Either way,-see [2D Lighting & Shadows](/docs/guides/lighting/).+see [2D Lighting & Shadows](/docs/graphics/lighting/).### Sprite filters (outline, glow, drop shadow)@@ -330,13 +330,13 @@ numbers, name tags, retro UI. Point `font` at a **BMFont** asset (`.fnt` text or| `layer` / `parallax` | `0` / `{1,1}` | Same sorting layer / parallax semantics as `Sprite`. |For screen-space UI text (layout, wrapping, SDF sharpness), use the UI `Text`-widget instead — see [UI](/docs/guides/ui/).+widget instead — see [UI](/docs/ui/overview/).## Hit-testing sprites"Did the click land on this sprite?" is two steps: convert the screen point toworld space, then test it against the sprite's rectangle. The `CameraView`-resource does the first (see [Camera](/docs/guides/camera/)); for the second the+resource does the first (see [Camera](/docs/graphics/camera/)); for the second theSDK exports pivot-aware point tests:| Function | Tests |@@ -381,7 +381,7 @@ const hit = pointInHitArea(p.x - t.worldPosition.x, p.y - t.worldPosition.y, hulmatrix and a viewport rectangle) for code that manages its own camera math — the`CameraView` resource is the same function with the active camera filled in. Forinteractive **UI**, don't hand-roll any of this: `Interactable` + `UIEvents` do-picking for you (see [UI](/docs/guides/ui/)).+picking for you (see [UI](/docs/ui/overview/)).## Cache as bitmap@@ -423,7 +423,7 @@ Draw.texture(pos, { x: 512, y: 256 }, cache.textureId);````cache.textureId` is an ordinary texture handle — it also works as a-`Sprite.texture`. Under the hood this is a [RenderTexture](/docs/guides/drawing/)+`Sprite.texture`. Under the hood this is a [RenderTexture](/docs/graphics/drawing/)without a depth buffer.## In the editor@@ -431,10 +431,10 @@ without a depth buffer.- **Create → Sprite** adds a sprite entity, or **drag an image** from the ContentBrowser into the viewport to spawn one already textured.- Every field above is editable in **Details**; sprites, cameras, and lights show as- gizmos in the viewport. See [The Editor](/docs/guides/editor/).+ gizmos in the viewport. See [The Editor](/docs/editor/overview/).## See also-- [Animation](/docs/guides/animation/) — sprite-sheet flipbooks and tweened properties.-- [Custom Drawing](/docs/guides/drawing/) — meshes and immediate-mode shapes beyond sprites.-- [2D Lighting & Shadows](/docs/guides/lighting/) — normal maps and per-sprite lighting.+- [Animation](/docs/animation/overview/) — sprite-sheet flipbooks and tweened properties.+- [Custom Drawing](/docs/graphics/drawing/) — meshes and immediate-mode shapes beyond sprites.+- [2D Lighting & Shadows](/docs/graphics/lighting/) — normal maps and per-sprite lighting.diff --git a/docs/astro/src/content/docs/graphics/video.mdx b/docs/astro/src/content/docs/graphics/video.mdxindex 3e372e9b2..736bd1427 100644--- a/docs/astro/src/content/docs/graphics/video.mdx+++ b/docs/astro/src/content/docs/graphics/video.mdx@@ -162,6 +162,6 @@ same component, the same handle sharing — only the decoder differs:## See also-- [Sprites & Rendering](/docs/guides/sprites/) — the texture a Video writes to and its `uvOffset` / `uvScale`.-- [Assets](/docs/guides/assets/) — loading and bundling video clips.-- [WeChat MiniGame](/docs/guides/wechat/) — the wasm decode path and export.+- [Sprites & Rendering](/docs/graphics/sprites/) — the texture a Video writes to and its `uvOffset` / `uvScale`.+- [Assets](/docs/assets/overview/) — loading and bundling video clips.+- [WeChat MiniGame](/docs/publishing/wechat/) — the wasm decode path and export.diff --git a/docs/astro/src/content/docs/index.mdx b/docs/astro/src/content/docs/index.mdxindex b31c7730d..4b6397e90 100644--- a/docs/astro/src/content/docs/index.mdx+++ b/docs/astro/src/content/docs/index.mdx@@ -49,9 +49,9 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';<CardGrid><LinkCard title="Quick Start" href="/docs/getting-started/quick-start/" description="Build your first scene and run it." />- <LinkCard title="The Editor" href="/docs/guides/editor/" description="A tour of the visual editor and its panels." />- <LinkCard title="Sprites & Rendering" href="/docs/guides/sprites/" description="Draw images — tint, size, sort, and layer them." />- <LinkCard title="Physics" href="/docs/guides/physics/" description="Rigid bodies, colliders, joints, and spatial queries." />- <LinkCard title="Gameplay AI" href="/docs/guides/ai/" description="Navigation, perception, state machines, behavior trees." />- <LinkCard title="Building & Exporting" href="/docs/guides/build-export/" description="Ship to web, desktop, WeChat, playable ads, Android and iOS." />+ <LinkCard title="The Editor" href="/docs/editor/overview/" description="A tour of the visual editor and its panels." />+ <LinkCard title="Sprites & Rendering" href="/docs/graphics/sprites/" description="Draw images — tint, size, sort, and layer them." />+ <LinkCard title="Physics" href="/docs/gameplay/physics/" description="Rigid bodies, colliders, joints, and spatial queries." />+ <LinkCard title="Gameplay AI" href="/docs/gameplay/ai/" description="Navigation, perception, state machines, behavior trees." />+ <LinkCard title="Building & Exporting" href="/docs/publishing/overview/" description="Ship to web, desktop, WeChat, playable ads, Android and iOS." /></CardGrid>diff --git a/docs/astro/src/content/docs/performance/profiling.mdx b/docs/astro/src/content/docs/performance/profiling.mdxindex 40b0069f9..424a101f5 100644--- a/docs/astro/src/content/docs/performance/profiling.mdx+++ b/docs/astro/src/content/docs/performance/profiling.mdx@@ -425,7 +425,7 @@ bisect where in the frame an error appears.## GPU resource budgets & residencyReleased textures stay resident in a byte-budgeted warm cache (the full model-is in the [assets guide](/docs/guides/assets/#lifetime--reference-counting)).+is in the [assets guide](/docs/assets/overview/#lifetime--reference-counting)).The diagnostics side of it:```typescript@@ -505,7 +505,7 @@ is the equivalent.## See also-- [Assets](/docs/guides/assets/) — the texture warm cache and budget the resource stats observe.+- [Assets](/docs/assets/overview/) — the texture warm cache and budget the resource stats observe.- [App & Lifecycle](/docs/core-concepts/app-lifecycle/) — plugins, schedules, and the subsystem registry.- [Systems](/docs/core-concepts/systems/) — schedules and system names (the keys in `systemTimings`).-- [Editor](/docs/guides/editor/) — the desktop editor, including its Profiler panel.+- [Editor](/docs/editor/overview/) — the desktop editor, including its Profiler panel.diff --git a/docs/astro/src/content/docs/publishing/android-ios.mdx b/docs/astro/src/content/docs/publishing/android-ios.mdxindex 37f2cc72e..a43a57c2a 100644--- a/docs/astro/src/content/docs/publishing/android-ios.mdx+++ b/docs/astro/src/content/docs/publishing/android-ios.mdx@@ -243,13 +243,13 @@ delivery:```Off by default, deliberately — reachability is what keeps a build from shipping-everything. See [Assets](/docs/guides/assets/#shipping-what-only-code-names).+everything. See [Assets](/docs/assets/overview/#shipping-what-only-code-names).### Tune textures for the platform where memory is tightestPer-asset **Import Settings** have a tab per platform, mobile targets included —so a texture can be compressed harder for a phone than for the web without-touching the source PNG. See [Assets](/docs/guides/assets/).+touching the source PNG. See [Assets](/docs/assets/overview/).### Your game script is interpreted@@ -349,7 +349,7 @@ adb logcat --pid=$(adb shell pidof <your.package.id>)## See also-- [Building & Exporting](/docs/guides/build-export/) — every target, the cook options, and the Package dialog.-- [Assets](/docs/guides/assets/) — reachability culling, delivery groups, and import settings.+- [Building & Exporting](/docs/publishing/overview/) — every target, the cook options, and the Package dialog.+- [Assets](/docs/assets/overview/) — reachability culling, delivery groups, and import settings.- [Screen & Design Resolution](/docs/core-concepts/screen/) — designing for a phone's aspect.- [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md) — the host's architecture and the full build recipe.diff --git a/docs/astro/src/content/docs/publishing/hot-update.mdx b/docs/astro/src/content/docs/publishing/hot-update.mdxindex f3189293e..0a40e7204 100644--- a/docs/astro/src/content/docs/publishing/hot-update.mdx+++ b/docs/astro/src/content/docs/publishing/hot-update.mdx@@ -51,13 +51,13 @@ to one of three modes:| Mode | Bundle | Badge | Ships… | Use for || --- | --- | --- | --- | --- || **Local** | eager | — | inside the package, loaded at boot | the game's core assets |-| **Subpackage** | lazy | `PKG` (purple) | inside the package, loaded on demand | large optional content, [WeChat subpackages](/docs/guides/wechat/) |+| **Subpackage** | lazy | `PKG` (purple) | inside the package, loaded on demand | large optional content, [WeChat subpackages](/docs/publishing/wechat/) || **Remote** | remote | `CDN` (blue) | from a CDN, **hot-updatable** | anything you want to change after shipping |Only **Remote** groups are hot-updated — they're the assets fetched from your CDNagainst a per-environment root. Local and Subpackage assets are baked into thebuild. (Subpackages are on-demand *within* the package; see-[Assets → Addressable groups](/docs/guides/assets/#addressable-groups-lazy-loading).)+[Assets → Addressable groups](/docs/assets/overview/#addressable-groups-lazy-loading).)### Mark a folder for CDN delivery@@ -71,7 +71,7 @@ In the **Content Browser**, right-click any folder and pick **Delivery → RemotThe same submenu carries **Always include in builds** — an independent toggle thatkeeps the folder in a build even when nothing in it is reachable from a scene. See-[Assets](/docs/guides/assets/#shipping-what-only-code-names).+[Assets](/docs/assets/overview/#shipping-what-only-code-names).A folder assigned to a Subpackage or Remote group carries a corner **badge** soyou can see the delivery layout at a glance — `CDN` (blue) for remote, `PKG`@@ -123,7 +123,7 @@ never disagree about where an asset ships):| `groups` | `Record<name, {folder, mode}>` | Folder → delivery assignments. || `groups.<name>.folder` | `string` | Project-relative folder; every asset under it (recursively) joins the group. The **longest** matching prefix wins when folders nest. || `groups.<name>.mode` | `'local' \| 'subpackage' \| 'remote'` | Delivery mode. |-| `groups.<name>.alwaysInclude` | `boolean` | Ship the group even when nothing in the build *reaches* it — for assets only your code names (a url, a path, rich-text markup). Off by default. See [Assets](/docs/guides/assets/#shipping-what-only-code-names). |+| `groups.<name>.alwaysInclude` | `boolean` | Ship the group even when nothing in the build *reaches* it — for assets only your code names (a url, a path, rich-text markup). Off by default. See [Assets](/docs/assets/overview/#shipping-what-only-code-names). || `activeProfile` | `string` | Which profile the build uses (key into `profiles`). || `profiles.<name>.remoteRoot` | `string` | CDN root that this profile's remote-group assets are served from. Empty ⇒ same-origin. |@@ -275,7 +275,7 @@ assets.releaseGroup('world2');`loadGroup` warms the cache through the same typed loaders as everything else, and`releaseGroup` reference-counts the release — an asset another scene still holds-survives. See [Assets → Addressable groups](/docs/guides/assets/#addressable-groups-lazy-loading)+survives. See [Assets → Addressable groups](/docs/assets/overview/#addressable-groups-lazy-loading)for the group model in full.## Integrity, atomicity & rollback@@ -342,6 +342,6 @@ disk-cache primitives differ per platform, and the runtime picks the right one.## See also-- [Assets](/docs/guides/assets/) — references, the manifest, typed loaders, and the group model.-- [Building & Exporting](/docs/guides/build-export/) — where the CDN root and `asset-manifest.json` come from.-- [WeChat MiniGame](/docs/guides/wechat/) — how subpackages map to the delivery groups here.+- [Assets](/docs/assets/overview/) — references, the manifest, typed loaders, and the group model.+- [Building & Exporting](/docs/publishing/overview/) — where the CDN root and `asset-manifest.json` come from.+- [WeChat MiniGame](/docs/publishing/wechat/) — how subpackages map to the delivery groups here.diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdxindex 380392882..387c48f3f 100644--- a/docs/astro/src/content/docs/publishing/overview.mdx+++ b/docs/astro/src/content/docs/publishing/overview.mdx@@ -38,7 +38,7 @@ time.## Scenes in buildEvery scene in the project's scenes folder ships with the export and becomes a-`SceneManager.switchTo` target — see [Scenes](/docs/guides/scene/) for how a game+`SceneManager.switchTo` target — see [Scenes](/docs/world/scenes/) for how a gamescript switches between them. The dialog's **Scenes in build** list controls theset:@@ -69,10 +69,10 @@ and opens it in your browser.|---|---|---|---|| **Web** | A static, self-contained web build. | `dist-web/` | **Preview over http**, or upload the folder to any static host. || **Desktop** | An Electron app source tree. | `dist-desktop/` | `cd dist-desktop && npm install && npm start` — or `npm run dist` for a native `.dmg` / `.exe` / AppImage installer. |-| **WeChat** | A WeChat MiniGame package. | `dist-wechat/` | Open the folder in WeChat DevTools and set your AppID. See [WeChat MiniGame](/docs/guides/wechat/). |+| **WeChat** | A WeChat MiniGame package. | `dist-wechat/` | Open the folder in WeChat DevTools and set your AppID. See [WeChat MiniGame](/docs/publishing/wechat/). || **Playable** | One self-contained `index.html` with everything inlined — no external requests, as ad networks require. | `dist-playable/` | **Preview over http** (its real surface is an ad-network iframe). Pick the [ad network](#playable-ad-networks) so the CTA and the size check match where it ships. |-| **Android** | Content for a **native** arm64 app (Vulkan) — a real APK, not a WebView. | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` wraps it in a signed APK. See [Android & iOS](/docs/guides/mobile/). |-| **iOS** | Content for a **native** arm64 app (Metal), plus the Xcode project when the engine is built for iOS here. | `dist-ios/` | Open the generated Xcode project, pick a signing team, Run. See [Android & iOS](/docs/guides/mobile/). |+| **Android** | Content for a **native** arm64 app (Vulkan) — a real APK, not a WebView. | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` wraps it in a signed APK. See [Android & iOS](/docs/publishing/android-ios/). |+| **iOS** | Content for a **native** arm64 app (Metal), plus the Xcode project when the engine is built for iOS here. | `dist-ios/` | Open the generated Xcode project, pick a signing team, Run. See [Android & iOS](/docs/publishing/android-ios/). |The mobile targets export app **content**, not a runnable payload: the engine, theSDK and the game runtime live in the app binary. That is also why they need a@@ -159,7 +159,7 @@ WeChat export **fails fast** — naming the exact build command — rather thanproducing a package that breaks at runtime. WeChat also needs a matching sidemodule for each engine feature the game uses (`physics-wechat`, `spine-wechat`,`basis-wechat` for compressed textures) — see-[WeChat MiniGame](/docs/guides/wechat/).+[WeChat MiniGame](/docs/publishing/wechat/).The dialog distinguishes **two kinds** of missing prerequisite, because they don'tblock the same amount:@@ -175,7 +175,7 @@ block the same amount:Android and iOS are the one pair of targets the editor download does not carryend to end: the native host is built once from an engine source checkout (Dawn +QuickJS), plus the Android SDK/NDK or macOS with Xcode. See- [Android & iOS](/docs/guides/mobile/).+ [Android & iOS](/docs/publishing/android-ios/).</Aside>## Content a target cannot render@@ -248,7 +248,7 @@ smaller downloads and less VRAM.**Content addressing** is on by default for Web/Desktop (each file named by a hashof its bytes — immutable URLs, automatic dedupe). **Advanced** holds the CDN root-for [hot update](/docs/guides/hot-update/), source maps, and whether to open the+for [hot update](/docs/publishing/hot-update/), source maps, and whether to open theoutput folder when the build finishes.<Aside type="caution" title="Assets only your code names are culled">@@ -257,7 +257,7 @@ output folder when the build finishes.spawned by path — is culled, and the editor never notices because it serves theproject straight off disk. Mark that folder **Delivery → Always include inbuilds** in the Content Browser. See- [Assets](/docs/guides/assets/#shipping-what-only-code-names).+ [Assets](/docs/assets/overview/#shipping-what-only-code-names).</Aside>## Packaging settings@@ -292,7 +292,7 @@ asks for that), and the orientation is only *declared* to the platform where oneit, e.g. Google's `ad.orientation` meta tag. Design for both aspects, or letterboxwith [a camera fit](#) so the framing survives either one.-See [The Editor](/docs/guides/editor/) for the settings UI.+See [The Editor](/docs/editor/overview/) for the settings UI.## Package size@@ -305,7 +305,7 @@ Three figures, because where the bytes sit matters more than how many there are:the engine runtime, your scripts, and the assets in `local` groups.- **On demand** — subpackages, fetched when the game asks for that group.- **CDN (not packaged)** — assets in `remote` groups. Real bytes, but they live on- your CDN and cost the package nothing. See [Hot Update](/docs/guides/hot-update/).+ your CDN and cost the package nothing. See [Hot Update](/docs/publishing/hot-update/).That split is read from the same manifest the runtime loads, so what the report saysand what the game does cannot disagree. Moving a level behind a subpackage genuinely@@ -371,13 +371,13 @@ node build-tools/cli.js native --target ios # …the native mobile host<Aside type="note">Most game developers never run the build CLI beyond the one-time WeChatruntime build — day-to-day work happens in the editor and the SDK. The- exception is [mobile](/docs/guides/mobile/), where the CLI is also what+ exception is [mobile](/docs/publishing/android-ios/), where the CLI is also whatassembles the app around an export.</Aside>## See also-- [Android & iOS](/docs/guides/mobile/) — the native app: prerequisites, assembling it, and what only bites on a device.-- [WeChat MiniGame](/docs/guides/wechat/) — subpackage layout and platform-specific quirks.-- [Assets](/docs/guides/assets/) — how the cook step bundles and content-addresses assets.-- [Profiling & Diagnostics](/docs/guides/profiling/) — check frame time and draw calls before you ship.+- [Android & iOS](/docs/publishing/android-ios/) — the native app: prerequisites, assembling it, and what only bites on a device.+- [WeChat MiniGame](/docs/publishing/wechat/) — subpackage layout and platform-specific quirks.+- [Assets](/docs/assets/overview/) — how the cook step bundles and content-addresses assets.+- [Profiling & Diagnostics](/docs/performance/profiling/) — check frame time and draw calls before you ship.diff --git a/docs/astro/src/content/docs/publishing/wechat.mdx b/docs/astro/src/content/docs/publishing/wechat.mdxindex aa5565a2f..0f6f07977 100644--- a/docs/astro/src/content/docs/publishing/wechat.mdx+++ b/docs/astro/src/content/docs/publishing/wechat.mdx@@ -55,7 +55,7 @@ The output directory contains `game.js` (the entry, which bootsas `scenes/<name>.json`, and a `wasm/` folder holding the engine plus exactlythe side modules your scenes need. Every scene in the build is a`SceneManager.switchTo` target — non-startup scenes load on their first switch-(see [Scenes](/docs/guides/scene/)).+(see [Scenes](/docs/world/scenes/)).<Aside type="caution">Don't hand-edit `game.js` or move files under `wasm/` — the boot sequence@@ -95,7 +95,7 @@ levels download on demand rather than bloating the initial package:## Best practices- **Stay under the 4 MB main-package limit** by moving on-demand content into- `subpackages/<name>/` — see [Assets](/docs/guides/assets/). The export sets+ `subpackages/<name>/` — see [Assets](/docs/assets/overview/). The export sets`bigPackageSizeSupport`, so an oversized package still *previews* inDevTools — but upload enforces the cap.- **Compress textures** — see above; the single biggest package-size win.@@ -106,7 +106,7 @@ levels download on demand rather than bloating the initial package:## See also-- [Assets](/docs/guides/assets/) — addressable groups and cooking map onto subpackages.-- [Building & Exporting](/docs/guides/build-export/) — the Package Project dialog.-- [Video](/docs/guides/video/) — the MPEG-1 wasm decode path shipped for WeChat.-- [Networking](/docs/guides/networking/) — sockets use `wx.connectSocket` here.+- [Assets](/docs/assets/overview/) — addressable groups and cooking map onto subpackages.+- [Building & Exporting](/docs/publishing/overview/) — the Package Project dialog.+- [Video](/docs/graphics/video/) — the MPEG-1 wasm decode path shipped for WeChat.+- [Networking](/docs/scripting/networking/) — sockets use `wx.connectSocket` here.diff --git a/docs/astro/src/content/docs/scripting/events.mdx b/docs/astro/src/content/docs/scripting/events.mdxindex 57d6eb984..032b3e4e1 100644--- a/docs/astro/src/content/docs/scripting/events.mdx+++ b/docs/astro/src/content/docs/scripting/events.mdx@@ -16,7 +16,7 @@ click ─▶ ui.setPage(badge, on) on "Card"Wires are deliberately **not** a visual programming language. A row has no branches and noexpressions; when something genuinely needs logic, the row names an action that hands off to-[a state machine](/docs/guides/ai/) — the editor Estella already has for graphs.+[a state machine](/docs/gameplay/ai/) — the editor Estella already has for graphs.## A wire in the inspector@@ -40,7 +40,7 @@ Select any entity that can emit — a UI node, an `Interactable`, a collider —## The dataA wire is the `EventBinding` component, so it serializes into scenes and travels with-[prefabs](/docs/guides/prefab/) like any other component — no new asset type:+[prefabs](/docs/world/prefabs/) like any other component — no new asset type:```typescriptimport { EventBinding, UIEventType } from 'esengine';@@ -90,12 +90,12 @@ These ship with the engine:| Action | What it does ||---|---|-| `ui.setPage` | Switch a [UI controller](/docs/guides/ui-controllers/) to a page. |+| `ui.setPage` | Switch a [UI controller](/docs/ui/controllers/) to a page. || `ui.setVisible` | Show/hide a UI subtree (`UINode.display`). || `property.set` | Write any component field, addressed as `Component.dot.path`. || `fsm.fire` | Fire a trigger on the target's state machine. || `blackboard.set` | Set a blackboard value. |-| `timeline.play` · `timeline.pause` | Drive a [timeline](/docs/guides/timeline/) on the target. |+| `timeline.play` · `timeline.pause` | Drive a [timeline](/docs/animation/timeline/) on the target. || `spriteAnim.play` · `spriteAnim.restart` · `spriteAnim.stop` | Drive a sprite flipbook. |### Your own actions@@ -148,8 +148,8 @@ shown ─▶ fsm.fire(enter) on "MissionPanel" → Hidden ──enter──The watching costs nothing until something listens for one of the two, and nothing again on aframe where no UI moved.-[Physics](/docs/guides/physics/) contacts reach the same channel (`PhysicsEventType`), so a-[trigger area](/docs/guides/markers/) is wired exactly like a button — both participants get+[Physics](/docs/gameplay/physics/) contacts reach the same channel (`PhysicsEventType`), so a+[trigger area](/docs/gameplay/markers/) is wired exactly like a button — both participants getthe event, each told about the other:`collision_enter` · `collision_exit` · `collision_hit` · `trigger_enter` · `trigger_exit`@@ -166,7 +166,7 @@ app.getResource(EntityEvents).emit(chest, 'looted', { gold: 12 });A row runs one action; it has no "if" and no sequence. That is a deliberate ceiling, and`fsm.fire` is the way through it — the click fires a trigger, and the entity's-[state machine](/docs/guides/ai/) decides what it means:+[state machine](/docs/gameplay/ai/) decides what it means:```click ─▶ fsm.fire(start) on "Hint" → Idle ──start──▶ Runningdiff --git a/docs/astro/src/content/docs/scripting/input.mdx b/docs/astro/src/content/docs/scripting/input.mdxindex f6c7abe39..a67f62f24 100644--- a/docs/astro/src/content/docs/scripting/input.mdx+++ b/docs/astro/src/content/docs/scripting/input.mdx@@ -300,5 +300,5 @@ Each `*Down` reads held state; `*Pressed` / `*Released` are the this-frame edges## See also-- [Camera](/docs/guides/camera/) — `screenToWorld` for arbitrary screen points.-- [UI](/docs/guides/ui/) — UI consumes pointer input above the game world.+- [Camera](/docs/graphics/camera/) — `screenToWorld` for arbitrary screen points.+- [UI](/docs/ui/overview/) — UI consumes pointer input above the game world.diff --git a/docs/astro/src/content/docs/scripting/math.mdx b/docs/astro/src/content/docs/scripting/math.mdxindex 59c5ade0e..32e0a39b6 100644--- a/docs/astro/src/content/docs/scripting/math.mdx+++ b/docs/astro/src/content/docs/scripting/math.mdx@@ -117,5 +117,5 @@ For direction *vectors* instead of rotations, stay in `v2`: `fromAngle` /- [Transforms, Units & Coordinates](/docs/core-concepts/transforms/) — what thenumbers mean: world units = design pixels, physics meters, Y-up, and rotatingentities with quaternions.-- [Physics](/docs/guides/physics/) — the meter-based unit surface these helpers+- [Physics](/docs/gameplay/physics/) — the meter-based unit surface these helpersfeed into.diff --git a/docs/astro/src/content/docs/scripting/networking.mdx b/docs/astro/src/content/docs/scripting/networking.mdxindex f0600284a..6eafd7044 100644--- a/docs/astro/src/content/docs/scripting/networking.mdx+++ b/docs/astro/src/content/docs/scripting/networking.mdx@@ -213,5 +213,5 @@ never re-sends snap back. Owned entities bypass snapshot interpolation.## See also-- [WeChat MiniGame](/docs/guides/wechat/) — sockets use `wx.connectSocket` there.-- [Saving & Loading](/docs/guides/save/) — persist state locally between sessions.+- [WeChat MiniGame](/docs/publishing/wechat/) — sockets use `wx.connectSocket` there.+- [Saving & Loading](/docs/scripting/save/) — persist state locally between sessions.diff --git a/docs/astro/src/content/docs/scripting/overview.mdx b/docs/astro/src/content/docs/scripting/overview.mdxindex 2b639f14e..afab0d825 100644--- a/docs/astro/src/content/docs/scripting/overview.mdx+++ b/docs/astro/src/content/docs/scripting/overview.mdx@@ -212,7 +212,7 @@ the world around it:| `ctx.self` | `S` | This behavior's own `state`. **Mutate it freely — changes persist.** || `ctx.entity` | `Entity` | The entity this instance is attached to. || `ctx.time` | `TimeData` | Frame timing: `delta`, `elapsed`, `frameCount`, `fixedDelta`. |-| `ctx.input` | `InputState` | Keyboard / mouse / touch / gamepad (see [Input](/docs/guides/input/)). |+| `ctx.input` | `InputState` | Keyboard / mouse / touch / gamepad (see [Input](/docs/scripting/input/)). || `ctx.commands` | `Commands` | Deferred spawn / despawn / insert — safe to call mid-update. || `ctx.world` | `World` | Full world access for cross-entity reads and writes. || `ctx.get(Comp)` | `ComponentData` | Read another component on **this** entity. |@@ -341,7 +341,7 @@ one `defineSystem`. Reach for `defineBehavior` when your logic is naturallycoordinating across entities.The hook signature — `entity`, `world`, `commands`, plus `self` — is also the same-programming model used by the [Gameplay AI](/docs/guides/ai/) layer's actions and+programming model used by the [Gameplay AI](/docs/gameplay/ai/) layer's actions andbehavior-tree leaves, so moving logic between a behavior and an AI action isstraightforward.@@ -365,4 +365,4 @@ documented in [App Setup & Lifecycle](/docs/core-concepts/app-lifecycle/#hot-rel- [Systems](/docs/core-concepts/systems/) — the full query vocabulary, filters, and schedules.- [ECS Architecture](/docs/core-concepts/ecs/) — entities, components, and how systems iterate them.-- [Input](/docs/guides/input/) — read keyboard, pointer, and gestures from a system.+- [Input](/docs/scripting/input/) — read keyboard, pointer, and gestures from a system.diff --git a/docs/astro/src/content/docs/scripting/save.mdx b/docs/astro/src/content/docs/scripting/save.mdxindex 292a3b268..982d4583b 100644--- a/docs/astro/src/content/docs/scripting/save.mdx+++ b/docs/astro/src/content/docs/scripting/save.mdx@@ -124,5 +124,5 @@ it — your players keep their progress and there is nothing to write.## See also-- [Scenes](/docs/guides/scene/) — loading and switching the scenes a save points at.-- [Assets](/docs/guides/assets/) — why bulk data belongs in assets, not in a save slot.+- [Scenes](/docs/world/scenes/) — loading and switching the scenes a save points at.+- [Assets](/docs/assets/overview/) — why bulk data belongs in assets, not in a save slot.diff --git a/docs/astro/src/content/docs/ui/controllers.mdx b/docs/astro/src/content/docs/ui/controllers.mdxindex cce73f487..1ee136cdc 100644--- a/docs/astro/src/content/docs/ui/controllers.mdx+++ b/docs/astro/src/content/docs/ui/controllers.mdx@@ -11,9 +11,9 @@ value *per page*, so when the controller switches page, every geared element refcolor, position, visibility, text, or any reflected field, snapping or tweening.One controller drives many elements, and the whole thing is plain ECS data (two-components, `UIController` and `UIGear`) that travels with a [prefab](/docs/guides/prefab/)+components, `UIController` and `UIGear`) that travels with a [prefab](/docs/world/prefabs/)and serializes into a scene. It is the shared, multi-page generalization of the-per-widget state a [button](/docs/guides/ui-components/#button) uses — one mechanism for+per-widget state a [button](/docs/ui/widgets/#button) uses — one mechanism fortabs, radio groups, button states, and show/hide panels.## Controllers@@ -70,7 +70,7 @@ world.insert(card, UIGear, {````gearBinding(controller, component, property, pages, tween?)` addresses a field the same-way a [Timeline](/docs/guides/timeline/) property track does — a component name plus a+way a [Timeline](/docs/animation/timeline/) property track does — a component name plus adot-path `property` (`"color"`, `"color.a"`, `"scale.x"`). `pages` is a **sparse** mapkeyed by page name: a page with no entry leaves the field untouched.@@ -134,7 +134,7 @@ root's controllers stay switchable while you work on a geared leaf:to rename, drag to reorder, and the hover × deletes — renames cascade into everygear binding that resolves to the controller, and deleting a page clears itsrecorded values.-- Click a controller to make it **active**. In the [Details](/docs/guides/editor/) panel,+- Click a controller to make it **active**. In the [Details](/docs/editor/overview/) panel,every field then shows a small **gear dot** — click it to bind that field to the activecontroller (seeding the current page with the field's value). Click a bound dot to openits settings: the page-change **transition** (duration + easing, 0 = snap) and unbind.@@ -153,7 +153,7 @@ else, and instance with it.Two bridges switch pages from *data* or *logic*, each reusing an existing system.**From a signal** — `bindControllerPage` drives a controller's page from a-[reactive signal](/docs/guides/ui/), the declarative path to a data-driven tab bar:+[reactive signal](/docs/ui/overview/), the declarative path to a data-driven tab bar:```typescriptimport { signal, bindControllerPage } from 'esengine';@@ -164,7 +164,7 @@ bindControllerPage(world, root, 'tab', activeTab); // the controller follows thactiveTab.set('shop'); // page switches, every geared element reflows```-**From a button, with no code** — an [event wire](/docs/guides/events/) on the button+**From a button, with no code** — an [event wire](/docs/scripting/events/) on the buttonruns `ui.setPage` when it is clicked, targeting the entity that owns the controller:```json@@ -172,7 +172,7 @@ runs `ui.setPage` when it is clicked, targeting the entity that owns the control```**From a state machine** — the `ui.setPage` action lets a data-driven-[FSM / behavior tree](/docs/guides/ai/) (`.esfsm` / `.esbt`) switch a page with no code.+[FSM / behavior tree](/docs/gameplay/ai/) (`.esfsm` / `.esbt`) switch a page with no code.Its argument is `"controller:page"`:```json@@ -197,8 +197,8 @@ controller state → gear presentation.## See also-- [UI](/docs/guides/ui/) — the flexbox component model gears drive.-- [UI Components](/docs/guides/ui-components/) — the widget factories.-- [Timeline](/docs/guides/timeline/) — keyframed transitions; gears use the same field addressing.-- [Gameplay AI](/docs/guides/ai/) — the `.esfsm` / `.esbt` that can call `ui.setPage`.-- [Event Binding](/docs/guides/events/) — wire a click straight to `ui.setPage`, no code.+- [UI](/docs/ui/overview/) — the flexbox component model gears drive.+- [UI Components](/docs/ui/widgets/) — the widget factories.+- [Timeline](/docs/animation/timeline/) — keyframed transitions; gears use the same field addressing.+- [Gameplay AI](/docs/gameplay/ai/) — the `.esfsm` / `.esbt` that can call `ui.setPage`.+- [Event Binding](/docs/scripting/events/) — wire a click straight to `ui.setPage`, no code.diff --git a/docs/astro/src/content/docs/ui/data-binding.mdx b/docs/astro/src/content/docs/ui/data-binding.mdxindex d97e30c1a..3e760d4cc 100644--- a/docs/astro/src/content/docs/ui/data-binding.mdx+++ b/docs/astro/src/content/docs/ui/data-binding.mdx@@ -158,7 +158,7 @@ fires `change` identically.## Binding controller pages`bindControllerPage(world, entity, controller, source)` drives a-[UI controller's](/docs/guides/ui-controllers/) current page from a+[UI controller's](/docs/ui/controllers/) current page from a`ReadonlySignal<string>` — the declarative path to a data-driven tab bar. Setthe signal, the page switches, every geared element reflows:@@ -175,7 +175,7 @@ returned. Unknown controllers/pages are ignored rather than throwing.## Binding and lists-A [ListView](/docs/guides/ui-lists/) is *already* data-driven — it renders+A [ListView](/docs/ui/lists/) is *already* data-driven — it rendersfrom a `DataSource` (e.g. `ArrayDataSource`) with fine-grainedinsert/remove/update notifications, which virtualization needs and a singlevalue signal can't express. So: **collections go in a `DataSource`, scalar UI@@ -190,9 +190,9 @@ Three ways to get game state onto the screen — pick by the shape of the state:| State shape | Use | Why ||---|---|---|| A **value** — score, health, a name, a slider position | `signal` + `bind` / `bindWidgetValue` | Push on change, no polling; two-way for value widgets. |-| A **named state** out of a finite set — tab, open/closed, button state | [Controller + gears](/docs/guides/ui-controllers/) | Many elements reflow from one page switch; editor-authorable; tweens. Bridge from data with `bindControllerPage`. |-| A **collection** — inventory rows, leaderboard | `DataSource` + [ListView](/docs/guides/ui-lists/) | Fine-grained change notifications drive virtualization. |-| A **per-frame** value derived from simulation — cooldown sweep, follow-the-player markers | A plain [system](/docs/guides/scripting/) writing components | The value changes every frame anyway; a query is the natural reader. |+| A **named state** out of a finite set — tab, open/closed, button state | [Controller + gears](/docs/ui/controllers/) | Many elements reflow from one page switch; editor-authorable; tweens. Bridge from data with `bindControllerPage`. |+| A **collection** — inventory rows, leaderboard | `DataSource` + [ListView](/docs/ui/lists/) | Fine-grained change notifications drive virtualization. |+| A **per-frame** value derived from simulation — cooldown sweep, follow-the-player markers | A plain [system](/docs/scripting/overview/) writing components | The value changes every frame anyway; a query is the natural reader. |Rule of thumb: if you're about to write a system that only copies a variableinto a component when it changes, that's a `bind`. If you're about to hand-set@@ -214,8 +214,8 @@ colors on five entities whenever a mode changes, that's a controller.## See also-- [UI](/docs/guides/ui/) — the component model bindings write into.-- [UI Components](/docs/guides/ui-components/) — the value widgets (`createSlider`, `createToggle`, `createDropdown`).-- [UI Controllers](/docs/guides/ui-controllers/) — named page state + gears; `bindControllerPage` bridges signals into it.-- [UI Lists](/docs/guides/ui-lists/) — `DataSource`-driven virtualized lists.-- [Theming](/docs/guides/ui-theme/) — design tokens and live re-theming.+- [UI](/docs/ui/overview/) — the component model bindings write into.+- [UI Components](/docs/ui/widgets/) — the value widgets (`createSlider`, `createToggle`, `createDropdown`).+- [UI Controllers](/docs/ui/controllers/) — named page state + gears; `bindControllerPage` bridges signals into it.+- [UI Lists](/docs/ui/lists/) — `DataSource`-driven virtualized lists.+- [Theming](/docs/ui/theming/) — design tokens and live re-theming.diff --git a/docs/astro/src/content/docs/ui/interaction.mdx b/docs/astro/src/content/docs/ui/interaction.mdxindex 45bcf943f..f037752ff 100644--- a/docs/astro/src/content/docs/ui/interaction.mdx+++ b/docs/astro/src/content/docs/ui/interaction.mdx@@ -109,7 +109,7 @@ activates). Options: `disabled` (start with `Interactable.enabled = false`),`focusable` (default `true`), `tabIndex` (default `0` = document order). Itdeliberately does *not* insert `UIInteraction` — that stays transient. Forhover/press **visuals**, bind fields to the built-in interaction controller-pages — see [UI Controllers](/docs/guides/ui-controllers/).+pages — see [UI Controllers](/docs/ui/controllers/).## Drag & drop@@ -197,7 +197,7 @@ const focusDebug = defineSystem([Res(FocusManager)], (focus) => {<Aside type="note">Gamepad navigation is not built into the focus system — the ring is driven by`Tab` / `Enter` / `Space` / `Escape` and the arrow keys. For gamepad menus,- drive selection yourself from an [input map](/docs/guides/input/) and call+ drive selection yourself from an [input map](/docs/scripting/input/) and callwidget state directly.</Aside>@@ -274,8 +274,8 @@ a system must claim *raw* events before the `Input` resource sees them at all## See also-- [UI](/docs/guides/ui/) — the component model overview.-- [UI Components](/docs/guides/ui-components/) — widget factories with events pre-wired.-- [UI Controllers](/docs/guides/ui-controllers/) — hover/press **visual** states driven by the interaction controller.-- [UI Binding](/docs/guides/ui-binding/) — two-way widget-value binding over `change` events.-- [Input](/docs/guides/input/) — the `Input` resource, input maps, and gestures below the UI layer.+- [UI](/docs/ui/overview/) — the component model overview.+- [UI Components](/docs/ui/widgets/) — widget factories with events pre-wired.+- [UI Controllers](/docs/ui/controllers/) — hover/press **visual** states driven by the interaction controller.+- [UI Binding](/docs/ui/data-binding/) — two-way widget-value binding over `change` events.+- [Input](/docs/scripting/input/) — the `Input` resource, input maps, and gestures below the UI layer.diff --git a/docs/astro/src/content/docs/ui/layout.mdx b/docs/astro/src/content/docs/ui/layout.mdxindex fb830d203..f1ca99735 100644--- a/docs/astro/src/content/docs/ui/layout.mdx+++ b/docs/astro/src/content/docs/ui/layout.mdx@@ -9,7 +9,7 @@ UI geometry is a CSS box model solved by a single-pass flexbox engine (Yoga) inthe C++ core, every frame, against the camera's UI box. This page is the deepreference: units, the `Dimension` type, every `UINode` and `FlexContainer`field, absolute positioning, anchor presets, and recipes. For the component-model overview start at [UI](/docs/guides/ui/).+model overview start at [UI](/docs/ui/overview/).## Units: design pixels@@ -21,7 +21,7 @@ every device; the canvas scale mode decides how that design box fits the realscreen (letterbox, expand, match). The editor's free-zoom view lays UI outagainst the same fixed design box, so zooming the viewport never reflows yourinterface. See [Screen & Resolution](/docs/core-concepts/screen/) and-[Camera](/docs/guides/camera/).+[Camera](/docs/graphics/camera/).## Dimensions: `px`, `percent`, `auto`@@ -280,7 +280,7 @@ const scrim = spawnUIEntity({Two equivalent tools: give the **parent** a centering `FlexContainer`(`justifyContent: Center, alignItems: Center` — the quickstart pattern in-[UI](/docs/guides/ui/)), or make the panel itself `Absolute` with all-`auto`+[UI](/docs/ui/overview/)), or make the panel itself `Absolute` with all-`auto`insets **and** margins (the [Center anchor](#centering-with-auto) — no parentcontainer needed).@@ -377,8 +377,8 @@ world.insert(e, UIVisual, buildUIVisual({ color: { r: 0.2, g: 0.2, b: 0.25, a: 1## See also-- [UI](/docs/guides/ui/) — the component model overview and quickstart.-- [UI Text](/docs/guides/ui-text/) — how `Text` measures and aligns inside the box.-- [UI Interaction](/docs/guides/ui-interaction/) — hit-testing the laid-out boxes.-- [UI Components](/docs/guides/ui-components/) — widgets built on these primitives (incl. mobile safe areas).-- [Camera](/docs/guides/camera/) — cameras, canvas scale modes, and the UI box.+- [UI](/docs/ui/overview/) — the component model overview and quickstart.+- [UI Text](/docs/ui/text/) — how `Text` measures and aligns inside the box.+- [UI Interaction](/docs/ui/interaction/) — hit-testing the laid-out boxes.+- [UI Components](/docs/ui/widgets/) — widgets built on these primitives (incl. mobile safe areas).+- [Camera](/docs/graphics/camera/) — cameras, canvas scale modes, and the UI box.diff --git a/docs/astro/src/content/docs/ui/lists.mdx b/docs/astro/src/content/docs/ui/lists.mdxindex 3b3c2a107..843259d1d 100644--- a/docs/astro/src/content/docs/ui/lists.mdx+++ b/docs/astro/src/content/docs/ui/lists.mdx@@ -6,7 +6,7 @@ description: Virtualized data-driven lists and grids with createListView — datimport { Aside } from '@astrojs/starlight/components';Long, scrollable content in Estella is built from two factories on top of the-[UI](/docs/guides/ui/) component model:+[UI](/docs/ui/overview/) component model:- **`createListView`** — a **virtualized**, data-driven list or grid. Only theitems near the viewport are ever mounted, so a 10 000-row inventory,@@ -499,9 +499,9 @@ bubble's wrapped height is measured before anything is placed.## See also-- [UI](/docs/guides/ui/) — the component model these factories are built on.-- [UI Components](/docs/guides/ui-components/) — the other widget factories (Button, Dialog, Text input, …).-- [UI Layout](/docs/guides/ui-layout/) — `UINode` boxes, flexbox, and dimensions.-- [UI Binding](/docs/guides/ui-binding/) — signals and two-way widget binding.-- [UI Interaction](/docs/guides/ui-interaction/) — pointer events, focus, drag & drop.-- [UI Theme](/docs/guides/ui-theme/) — the token roles the scrollbar and defaults draw from.+- [UI](/docs/ui/overview/) — the component model these factories are built on.+- [UI Components](/docs/ui/widgets/) — the other widget factories (Button, Dialog, Text input, …).+- [UI Layout](/docs/ui/layout/) — `UINode` boxes, flexbox, and dimensions.+- [UI Binding](/docs/ui/data-binding/) — signals and two-way widget binding.+- [UI Interaction](/docs/ui/interaction/) — pointer events, focus, drag & drop.+- [UI Theme](/docs/ui/theming/) — the token roles the scrollbar and defaults draw from.diff --git a/docs/astro/src/content/docs/ui/overview.mdx b/docs/astro/src/content/docs/ui/overview.mdxindex 0cac360f7..9e9ec060c 100644--- a/docs/astro/src/content/docs/ui/overview.mdx+++ b/docs/astro/src/content/docs/ui/overview.mdx@@ -17,14 +17,14 @@ detailed UI guides. Deep reference for each area lives in its own chapter.| Component | Role | Guide ||---|---|---|-| `UINode` | The layout box; holds the per-item flex fields (size, grow/shrink, margin, inset). | [UI Layout](/docs/guides/ui-layout/) |-| `FlexContainer` | Lays a node's children out with flexbox (direction, justify, align, gap, padding). | [UI Layout](/docs/guides/ui-layout/) |-| `Text` | Text via a dynamic glyph atlas (content, font, color, align, stroke, shadow, rich text). | [UI Text](/docs/guides/ui-text/) |+| `UINode` | The layout box; holds the per-item flex fields (size, grow/shrink, margin, inset). | [UI Layout](/docs/ui/layout/) |+| `FlexContainer` | Lays a node's children out with flexbox (direction, justify, align, gap, padding). | [UI Layout](/docs/ui/layout/) |+| `Text` | Text via a dynamic glyph atlas (content, font, color, align, stroke, shadow, rich text). | [UI Text](/docs/ui/text/) || `UIVisual` | The fill — solid color, texture, 9-slice, tiled, or filled. | below || `UIMask` | Clips its children. | below || `UIScroll` | Makes a clipped node a scroll viewport: the wheel and drags move its content. | below |-| `Interactable` | Marks a node hit-testable so it can be hovered/clicked. | [UI Interaction](/docs/guides/ui-interaction/) |-| `UIInteraction` | Engine-written per-frame pointer state (read-only for your logic). | [UI Interaction](/docs/guides/ui-interaction/) |+| `Interactable` | Marks a node hit-testable so it can be hovered/clicked. | [UI Interaction](/docs/ui/interaction/) |+| `UIInteraction` | Engine-written per-frame pointer state (read-only for your logic). | [UI Interaction](/docs/ui/interaction/) |## Quickstart: a pause menu@@ -75,10 +75,10 @@ addStartupSystem(buildPauseMenu);`spawnUIEntity({ world, parent?, node?, visual?, text? })` returns the entity; pass`parent` to nest. Sizes use the dimension helpers `px`, `percent`, `auto` — all-in **design pixels** (see [UI Layout](/docs/guides/ui-layout/#units-design-pixels)).+in **design pixels** (see [UI Layout](/docs/ui/layout/#units-design-pixels)).The other widget factories work the same way: `createToggle`, `createSlider`,`createProgress`, `createDialog`, `createDropdown` — see-[UI Components](/docs/guides/ui-components/).+[UI Components](/docs/ui/widgets/).## How the pieces fit@@ -86,21 +86,21 @@ Each layer builds on the one before it:1. **Layout** — `UINode` boxes, solved by the flexbox engine; `FlexContainer`arranges children, `Absolute` insets place overlays.- → [UI Layout](/docs/guides/ui-layout/)+ → [UI Layout](/docs/ui/layout/)2. **Visuals & text** — `UIVisual` fills the box, `UIMask` clips, `Text` draws- crisp glyphs. → [UI Text](/docs/guides/ui-text/)+ crisp glyphs. → [UI Text](/docs/ui/text/)3. **Interaction** — `Interactable` makes a box hit-testable; the engine writespointer state into `UIInteraction` and emits bubbling `UIEvents`; drag & drop- and keyboard focus sit on top. → [UI Interaction](/docs/guides/ui-interaction/)+ and keyboard focus sit on top. → [UI Interaction](/docs/ui/interaction/)4. **Widgets** — factories (`createButton`, `createSlider`, …) compose the threelayers into ready-made controls; `createListView` adds virtualized lists.- → [UI Components](/docs/guides/ui-components/), [UI Lists](/docs/guides/ui-lists/)+ → [UI Components](/docs/ui/widgets/), [UI Lists](/docs/ui/lists/)5. **Controllers** — a named "page" state per UI root with per-page fieldbindings (tabs, button states, show/hide) — no code.- → [UI Controllers](/docs/guides/ui-controllers/)+ → [UI Controllers](/docs/ui/controllers/)6. **Theme & binding** — design tokens skin every widget (live-switchable), andreactive signals keep UI in sync with game state.- → [UI Theme](/docs/guides/ui-theme/), [UI Binding](/docs/guides/ui-binding/)+ → [UI Theme](/docs/ui/theming/), [UI Binding](/docs/ui/data-binding/)### `UIVisual` and `UIMask`@@ -130,7 +130,7 @@ reaches. Corners keep their exact pixels at any size, so one 100×112 texture setooltip and a full-width banner. The border belongs to the **image**, not to the entityusing it, so it is a texture import setting — set it once and every `NineSlice` thatreferences the texture is sliced the same way. See-[dragging the border](/docs/guides/editor/#the-content-browser) in the asset inspector.+[dragging the border](/docs/editor/overview/#the-content-browser) in the asset inspector.#### What a mask is for@@ -229,7 +229,7 @@ Both author the **same components** — there is no separate editor format:- **Editor** — *Create… → UI* drops widget prefabs (Button, Toggle, Slider,Dialog, …); nest by dragging, edit every field in Details, place with theper-axis anchor picker, and preview against the project's design resolution- and device presets. See [The Editor](/docs/guides/editor/).+ and device presets. See [The Editor](/docs/editor/overview/).- **Code** — `spawnUIEntity` + the widget factories, from a startup system asabove. Anything the editor writes, code can write too.@@ -237,14 +237,14 @@ Both author the **same components** — there is no separate editor format:| You want to… | Open ||---|---|-| Size and place boxes — `px`/`percent`/`auto`, flexbox, absolute insets, anchors | [UI Layout](/docs/guides/ui-layout/) |-| Draw text — fonts, SDF/bitmap crispness, wrapping, rich text | [UI Text](/docs/guides/ui-text/) |-| React to pointer & keyboard — clicks, `UIEvents`, drag & drop, focus | [UI Interaction](/docs/guides/ui-interaction/) |-| Use ready-made controls — button, toggle, slider, dialog, dropdown, input | [UI Components](/docs/guides/ui-components/) |-| Show scrolling data — virtualized lists and grids | [UI Lists](/docs/guides/ui-lists/) |-| Skin everything — design tokens, project theme, live switching | [UI Theme](/docs/guides/ui-theme/) |-| Keep UI in sync with game state — signals, `bind`, two-way widget binding | [UI Binding](/docs/guides/ui-binding/) |-| Share state across elements — tabs, radio groups, page-driven visuals | [UI Controllers](/docs/guides/ui-controllers/) |+| Size and place boxes — `px`/`percent`/`auto`, flexbox, absolute insets, anchors | [UI Layout](/docs/ui/layout/) |+| Draw text — fonts, SDF/bitmap crispness, wrapping, rich text | [UI Text](/docs/ui/text/) |+| React to pointer & keyboard — clicks, `UIEvents`, drag & drop, focus | [UI Interaction](/docs/ui/interaction/) |+| Use ready-made controls — button, toggle, slider, dialog, dropdown, input | [UI Components](/docs/ui/widgets/) |+| Show scrolling data — virtualized lists and grids | [UI Lists](/docs/ui/lists/) |+| Skin everything — design tokens, project theme, live switching | [UI Theme](/docs/ui/theming/) |+| Keep UI in sync with game state — signals, `bind`, two-way widget binding | [UI Binding](/docs/ui/data-binding/) |+| Share state across elements — tabs, radio groups, page-driven visuals | [UI Controllers](/docs/ui/controllers/) |## Best practices@@ -259,7 +259,7 @@ Both author the **same components** — there is no separate editor format:## See also-- [Input](/docs/guides/input/) — raw keyboard/mouse/touch below the UI layer.-- [Localization](/docs/guides/localization/) — bind `Text.content` to translated keys.-- [Animation](/docs/guides/animation/) — tween UI color/position for juice.-- [The Editor](/docs/guides/editor/) — visual authoring, prefabs, anchor picker.+- [Input](/docs/scripting/input/) — raw keyboard/mouse/touch below the UI layer.+- [Localization](/docs/assets/localization/) — bind `Text.content` to translated keys.+- [Animation](/docs/animation/overview/) — tween UI color/position for juice.+- [The Editor](/docs/editor/overview/) — visual authoring, prefabs, anchor picker.diff --git a/docs/astro/src/content/docs/ui/text.mdx b/docs/astro/src/content/docs/ui/text.mdxindex c2ba17587..670c931d0 100644--- a/docs/astro/src/content/docs/ui/text.mdx+++ b/docs/astro/src/content/docs/ui/text.mdx@@ -80,7 +80,7 @@ Defaults below are the component defaults (what the inspector shows).| `align` | `TextAlign` | `Left` | Horizontal alignment: `Left` / `Center` / `Right`. || `verticalAlign` | `TextVerticalAlign` | `Top` | Vertical alignment: `Top` / `Middle` / `Bottom`. || `wordWrap` | boolean | `true` | Wrap lines at the box width (needs a `UINode` box). |-| `overflow` | `TextOverflow` | `Visible` | `Visible` / `Clip` / `Ellipsis`. Currently the renderer always draws `Visible`; clip overflow with a [`UIMask`](/docs/guides/ui/) on the box. |+| `overflow` | `TextOverflow` | `Visible` | `Visible` / `Clip` / `Ellipsis`. Currently the renderer always draws `Visible`; clip overflow with a [`UIMask`](/docs/ui/overview/) on the box. || `lineHeight` | number | `1.2` | Line spacing as a **ratio of `fontSize`** (baseline-to-baseline = `lineHeight × fontSize`). || `bold` / `italic` | boolean | `false` | Base font style (rich-text `<b>`/`<i>` layer on top). || `strokeColor` | Color | `{0,0,0,1}` | Outline color. |@@ -274,7 +274,7 @@ exists (install `localizationPlugin`), a per-frame system resolves the keythrough the catalogs and writes the result into `content` — so `setLocale`re-flows every bound label on the next frame. A missing key resolves to the keyitself (visible and greppable), and with no Localization resource the authored-`content` stands. See [Localization](/docs/guides/localization/).+`content` stands. See [Localization](/docs/assets/localization/).## Best practices@@ -293,9 +293,9 @@ itself (visible and greppable), and with no Localization resource the authored## See also-- [UI](/docs/guides/ui/) — the component model overview.-- [UI Layout](/docs/guides/ui-layout/) — the `UINode` box that text aligns and wraps within.-- [UI Components](/docs/guides/ui-components/) — `createTextInput` for editable text.-- [UI Theme](/docs/guides/ui-theme/) — themed text color roles and type scale.-- [UI Binding](/docs/guides/ui-binding/) — drive `content` from reactive signals.-- [Localization](/docs/guides/localization/) — catalogs, locales, and `i18nKey` resolution.+- [UI](/docs/ui/overview/) — the component model overview.+- [UI Layout](/docs/ui/layout/) — the `UINode` box that text aligns and wraps within.+- [UI Components](/docs/ui/widgets/) — `createTextInput` for editable text.+- [UI Theme](/docs/ui/theming/) — themed text color roles and type scale.+- [UI Binding](/docs/ui/data-binding/) — drive `content` from reactive signals.+- [Localization](/docs/assets/localization/) — catalogs, locales, and `i18nKey` resolution.diff --git a/docs/astro/src/content/docs/ui/theming.mdx b/docs/astro/src/content/docs/ui/theming.mdxindex 59c3b1f8a..8b4117a5f 100644--- a/docs/astro/src/content/docs/ui/theming.mdx+++ b/docs/astro/src/content/docs/ui/theming.mdx@@ -228,7 +228,7 @@ widget with `$interaction` color gears, tag the page→role map instead:## See also-- [UI](/docs/guides/ui/) — the component model the tokens color.-- [UI Components](/docs/guides/ui-components/) — the widget factories that consume tokens.-- [UI Controllers](/docs/guides/ui-controllers/) — the `$interaction` gears that theme state colors ride on.-- [Data Binding](/docs/guides/ui-binding/) — reactive values into component fields.+- [UI](/docs/ui/overview/) — the component model the tokens color.+- [UI Components](/docs/ui/widgets/) — the widget factories that consume tokens.+- [UI Controllers](/docs/ui/controllers/) — the `$interaction` gears that theme state colors ride on.+- [Data Binding](/docs/ui/data-binding/) — reactive values into component fields.diff --git a/docs/astro/src/content/docs/ui/widgets.mdx b/docs/astro/src/content/docs/ui/widgets.mdxindex 3b62308d3..349b4f0d8 100644--- a/docs/astro/src/content/docs/ui/widgets.mdx+++ b/docs/astro/src/content/docs/ui/widgets.mdx@@ -5,17 +5,17 @@ description: The built-in widget factories — Button, Toggle, Slider, Progress,import { Aside } from '@astrojs/starlight/components';-The widget factories build common controls out of the [UI](/docs/guides/ui/) component+The widget factories build common controls out of the [UI](/docs/ui/overview/) componentmodel (`UINode` + `Interactable` + a `$interaction`-[controller with gears](/docs/guides/ui-controllers/)), so you don't wire+[controller with gears](/docs/ui/controllers/)), so you don't wireeach one by hand. Each factory takes an options object and returns a **handle** —always with `entity` and `dispose()`, plus imperative methods to read and drive it.Interactive widgets need the world and the UI event queue — `world` from `GetWorld()`-and `events` from `Res(UIEvents)`, exactly as in the [UI guide](/docs/guides/ui/). They-all accept `parent?`, a `node?` ([`UINode`](/docs/guides/ui-layout/) layout — **default:+and `events` from `Res(UIEvents)`, exactly as in the [UI guide](/docs/ui/overview/). They+all accept `parent?`, a `node?` ([`UINode`](/docs/ui/layout/) layout — **default:fill the parent**), and visual overrides; visual defaults come from the active-[theme](/docs/guides/ui-theme/)'s roles and re-resolve on a live theme swap.+[theme](/docs/ui/theming/)'s roles and re-resolve on a live theme swap.Interactive widgets are **keyboard-reachable by default**: they carry a `Focusable`,so Tab reaches them, Enter/Space clicks them, and arrow keys drive sliders — opt outwith `focusable: false`.@@ -28,7 +28,7 @@ with `focusable: false`.<Aside type="note">For **shared** state across many elements — tabs, radio groups, show/hide panels, orcustom button states driven from data — reach for- [UI Controllers](/docs/guides/ui-controllers/): a named "page" state plus declarative+ [UI Controllers](/docs/ui/controllers/): a named "page" state plus declarativeper-page field bindings, authorable in the editor.</Aside>@@ -190,7 +190,7 @@ const ring = createProgress({ world, parent, radial: true, value: 0.75 });**Handle:** `getValue()`, `setValue(v)`, `dispose()`, plus `entity` / `fillEntity`.<Aside type="note">- **One fill primitive.** A progress bar is a single [`UIVisual`](/docs/guides/ui/) in+ **One fill primitive.** A progress bar is a single [`UIVisual`](/docs/ui/overview/) in**`Filled`** mode — the same primitive the slider's fill is built on, mirroring Unity's"health bar = Filled Image". `setValue()` writes `fillAmount`, so the fill is arender-time crop with **no per-frame layout pass**, and a sprite fill *reveals* along@@ -341,7 +341,7 @@ authored in a scene needs to stop looking generic:| Field | Default | Description ||---|---|---|-| `font` | `0` | A font asset **this project ships** (`.ttf` / `.otf`), the same slot [`Text.font`](/docs/guides/ui-text/#custom-fonts) uses. Set, it wins over `fontFamily` — so a field on a panel drawn in the game's typeface is drawn in it too, rather than in Arial. |+| `font` | `0` | A font asset **this project ships** (`.ttf` / `.otf`), the same slot [`Text.font`](/docs/ui/text/#custom-fonts) uses. Set, it wins over `fontFamily` — so a field on a panel drawn in the game's typeface is drawn in it too, rather than in Arial. || `textAlign` | `Left` | Where the value sits in the field: `Left` / `Center` / `Right`. A single line holds the alignment **while the value fits**; past that the field scrolls to follow the caret, exactly as a left-aligned one always has. Multiline aligns per line. || `renderMode` | `Auto` | Glyph pipeline for the field text — mirrors `Text.renderMode`. |@@ -394,20 +394,20 @@ newlines).Virtualized data-driven lists and grids (`createListView`), free-form scrollablepanels (`createScrollView`), data sources, layout providers, auto-height rows, andthe kinetic-scroll / scrollbar machinery have their own chapter:-**[Lists & Scrolling](/docs/guides/ui-lists/)**.+**[Lists & Scrolling](/docs/ui/lists/)**.## Data bindingWidget values are plain component fields (`UISlider.value`, `UIToggle.isOn`, …), sothe signal layer binds to them directly — and `bindWidgetValue` makes it two-way.-See **[UI Binding](/docs/guides/ui-binding/)**.+See **[UI Binding](/docs/ui/data-binding/)**.## Drag & dropAdd `Draggable` to any interactable UI entity and pointer drags move it, with`drag_start` / `drag_move` / `drag_end` events and a live `DragState` component.Axis locks and range clamps included. See-**[UI Interaction](/docs/guides/ui-interaction/)**.+**[UI Interaction](/docs/ui/interaction/)**.## Keyboard focus@@ -415,7 +415,7 @@ Entities with a `Focusable` participate in keyboard focus: Tab / Shift+Tab cycleby `tabIndex`, Enter/Space activate, sliders take the arrow keys, and a focusedcontrol shows its `focused` interaction page. Widget factories add `Focusable`automatically (`focusable: false` opts out); the `FocusManager` resource gives-programmatic control. Details in **[UI Interaction](/docs/guides/ui-interaction/)**.+programmatic control. Details in **[UI Interaction](/docs/ui/interaction/)**.## Safe area (mobile notches)@@ -428,7 +428,7 @@ with per-edge opt-outs. See **[Screen & Resolution](/docs/core-concepts/screen/)Widget colors come from a shared token set with roles like `surface`, `control`,`primary`, and `track`; `switchTheme(world, tokens)` live-restyles everything onscreen, and a project declares its palette once in **Project Settings → UI**.-See **[UI Theme](/docs/guides/ui-theme/)**.+See **[UI Theme](/docs/ui/theming/)**.## Editor prefabs@@ -442,7 +442,7 @@ under the pointer (a dashed outline previews the would-be parent while youdrag), and an empty-canvas drop lands at the root as before. The anchor pickeredits **per axis** and keeps the widget exactly where it was — changing thehorizontal anchor never disturbs the vertical layout, and vice versa. See-[The Editor](/docs/guides/editor/).+[The Editor](/docs/editor/overview/).## Best practices@@ -461,9 +461,9 @@ horizontal anchor never disturbs the vertical layout, and vice versa. See## See also-- [UI](/docs/guides/ui/) — the component model: `UINode`, `Text`, `UIVisual`, interaction.-- [Lists & Scrolling](/docs/guides/ui-lists/) — `createListView`, `createScrollView`, virtualization.-- [UI Controllers](/docs/guides/ui-controllers/) — shared "page" state + declarative per-page field bindings.-- [UI Binding](/docs/guides/ui-binding/) — signals and two-way widget binding.-- [UI Interaction](/docs/guides/ui-interaction/) — focus, drag & drop, pointer events.-- [UI Theme](/docs/guides/ui-theme/) — tokens, roles, live theme swaps, the project theme.+- [UI](/docs/ui/overview/) — the component model: `UINode`, `Text`, `UIVisual`, interaction.+- [Lists & Scrolling](/docs/ui/lists/) — `createListView`, `createScrollView`, virtualization.+- [UI Controllers](/docs/ui/controllers/) — shared "page" state + declarative per-page field bindings.+- [UI Binding](/docs/ui/data-binding/) — signals and two-way widget binding.+- [UI Interaction](/docs/ui/interaction/) — focus, drag & drop, pointer events.+- [UI Theme](/docs/ui/theming/) — tokens, roles, live theme swaps, the project theme.diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex d6816c27a..4908592b5 100644--- a/docs/astro/src/content/docs/world/particles.mdx+++ b/docs/astro/src/content/docs/world/particles.mdx@@ -515,6 +515,6 @@ const control = defineSystem([Res(Particle)], (particles) => {## See also-- [Materials & Shaders](/docs/guides/material/) — custom particle materials.-- [Post-processing](/docs/guides/postprocess/) — bloom over additive particles.-- [Assets](/docs/guides/assets/) — loading particle textures and atlases.+- [Materials & Shaders](/docs/graphics/materials/) — custom particle materials.+- [Post-processing](/docs/graphics/post-processing/) — bloom over additive particles.+- [Assets](/docs/assets/overview/) — loading particle textures and atlases.diff --git a/docs/astro/src/content/docs/world/prefabs.mdx b/docs/astro/src/content/docs/world/prefabs.mdxindex 793bd9507..6170e37f3 100644--- a/docs/astro/src/content/docs/world/prefabs.mdx+++ b/docs/astro/src/content/docs/world/prefabs.mdx@@ -172,5 +172,5 @@ Besides `'property'`, `type` can be `'name'`, `'visibility'`, `'component_added'## See also-- [Scenes](/docs/guides/scene/) — scenes are where prefab instances live.-- [Assets](/docs/guides/assets/) — prefabs are assets, loaded on first instantiate.+- [Scenes](/docs/world/scenes/) — scenes are where prefab instances live.+- [Assets](/docs/assets/overview/) — prefabs are assets, loaded on first instantiate.diff --git a/docs/astro/src/content/docs/world/scenes.mdx b/docs/astro/src/content/docs/world/scenes.mdxindex 5fc99ceec..f81037365 100644--- a/docs/astro/src/content/docs/world/scenes.mdx+++ b/docs/astro/src/content/docs/world/scenes.mdx@@ -135,7 +135,7 @@ Two things do **not** come along with it:</Aside>For state rather than live entities — score, inventory, quest flags — reach for-[saves](/docs/guides/save/) instead. Persistence is for objects that must keep+[saves](/docs/scripting/save/) instead. Persistence is for objects that must keeprunning across the cut; a save is for data that merely has to be there on theother side.@@ -195,7 +195,7 @@ on their first switch, so extra scenes don't slow the initial load.Scenes you untick in the Package dialog's **Scenes in build** list are left out ofthe export (they stay editable and playable in the editor), and Playable-ad buildsship the startup scene only. See-[Building & Exporting](/docs/guides/build-export/).+[Building & Exporting](/docs/publishing/overview/).## `SceneManager` reference@@ -219,7 +219,7 @@ ship the startup scene only. SeeThe scene file format is a public surface: `SceneData` is plain JSON, and theprimitives the editor and runtime use to read and write it are exported for gamecode. You reach for them to save a **snapshot of the live world** (a checkpoint-richer than the [save-game API](/docs/guides/save/)), to load player-generated+richer than the [save-game API](/docs/scripting/save/)), to load player-generatedor downloaded scenes, or to ship components whose state doesn't fit their plainfields.@@ -315,7 +315,7 @@ the owning plugin (see `tilemapPlugin`) does it at startup.no `SceneOwner`, so no scene will ever clean it up. `ctx.adopt(entity)` hands one tothe current scene; `setPersistent` is the deliberate opposite.- **Carry objects across a switch with [persistence](#persistent-entities), carry- state with [saves](/docs/guides/save/)** — an entity that must keep running versus+ state with [saves](/docs/scripting/save/)** — an entity that must keep running versusdata that just has to be there afterwards.<Aside type="note">@@ -327,6 +327,6 @@ the owning plugin (see `tilemapPlugin`) does it at startup.## See also-- [Prefabs](/docs/guides/prefab/) — spawn reusable entity trees within a scene.-- [Saving & Loading](/docs/guides/save/) — persist state across scene switches.-- [Assets](/docs/guides/assets/) — scenes are cook entry points.+- [Prefabs](/docs/world/prefabs/) — spawn reusable entity trees within a scene.+- [Saving & Loading](/docs/scripting/save/) — persist state across scene switches.+- [Assets](/docs/assets/overview/) — scenes are cook entry points.diff --git a/docs/astro/src/content/docs/world/tilemaps.mdx b/docs/astro/src/content/docs/world/tilemaps.mdxindex 0614ab673..96069f27d 100644--- a/docs/astro/src/content/docs/world/tilemaps.mdx+++ b/docs/astro/src/content/docs/world/tilemaps.mdx@@ -326,7 +326,7 @@ The brushes:| **Ramp ◢ / ◣** | Triangle | 45° slopes rising to the right / left. || **Half** (bottom / top / left / right) | Half box | Ledges, low walls, thin floors. || **One-way ↑** | Solid-top box | Jump-through platforms — solid from above, pass-through from below. Flip to reorient it (a ceiling, a wall). |-| **Trigger** | Sensor box | A non-solid region that fires overlap events — see [Markers & Trigger Areas](/docs/guides/markers/). |+| **Trigger** | Sensor box | A non-solid region that fires overlap events — see [Markers & Trigger Areas](/docs/gameplay/markers/). |Paint them like tiles; the **collision overlay** draws exactly what Play will spawn.Each collision layer can also carry its own **physics material** (friction / bounce /@@ -347,7 +347,7 @@ cells came from the built-in palette.Tiled **object layers** (spawn points, triggers, region shapes) load with the map. Themodern way to read them is `Query(Marker)`: on load, point objects converge into-[**Marker**](/docs/guides/markers/) entities and shape objects into **Trigger Area**+[**Marker**](/docs/gameplay/markers/) entities and shape objects into **Trigger Area**regions — the very same entities you author by hand — so one query reads objectswhether they came from Tiled or the Estella editor.@@ -422,8 +422,8 @@ specially), and `tileCollisionAtWorld(...)` addresses in world pixels.## See also-- [Markers & Trigger Areas](/docs/guides/markers/) — place gameplay points and trigger+- [Markers & Trigger Areas](/docs/gameplay/markers/) — place gameplay points and triggerzones over your level as real, queryable entities.-- [Physics](/docs/guides/physics/) — tile colliders participate in the physics world.-- [Assets](/docs/guides/assets/) — loading `.tmj` maps and `.estileset` tilesets.-- [Scenes](/docs/guides/scene/) — tilemap layers serialize with the scene.+- [Physics](/docs/gameplay/physics/) — tile colliders participate in the physics world.+- [Assets](/docs/assets/overview/) — loading `.tmj` maps and `.estileset` tilesets.+- [Scenes](/docs/world/scenes/) — tilemap layers serialize with the scene.diff --git a/docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdx b/docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdxindex 35afbffd3..e459e47dc 100644--- a/docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/dragonbones.mdx@@ -169,7 +169,7 @@ DragonBones 运行时是**按需付费**的。项目里没有骨架,就不会去## 参见-- [Spine 动画](/docs/zh-cn/guides/spine/) —— 另一个骨骼运行时,以及两者的差别。-- [动画](/docs/zh-cn/guides/animation/) —— 精灵帧动画与 Animator 状态机。-- [资源](/docs/zh-cn/guides/assets/) —— 骨骼与图集资源怎么导入和引用。-- [构建与导出](/docs/zh-cn/guides/build-export/) —— 每个目标的包里有什么。+- [Spine 动画](/docs/zh-cn/animation/spine/) —— 另一个骨骼运行时,以及两者的差别。+- [动画](/docs/zh-cn/animation/overview/) —— 精灵帧动画与 Animator 状态机。+- [资源](/docs/zh-cn/assets/overview/) —— 骨骼与图集资源怎么导入和引用。+- [构建与导出](/docs/zh-cn/publishing/overview/) —— 每个目标的包里有什么。diff --git a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx b/docs/astro/src/content/docs/zh-cn/animation/overview.mdxindex 155b6b459..715b0716f 100644--- a/docs/astro/src/content/docs/zh-cn/animation/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/overview.mdx@@ -173,7 +173,7 @@ const registerRun = defineSystem([Res(Assets), Res(SpriteAnimation)], async (ass### 用状态机驱动剪辑——零代码-[FSM/BT 内置](/docs/zh-cn/guides/ai/)以数据驱动翻页动画。动作的可选**参数**+[FSM/BT 内置](/docs/zh-cn/gameplay/ai/)以数据驱动翻页动画。动作的可选**参数**携带剪辑,所以 idle/run/attack 切换是纯 `.esfsm` 数据,画在现有状态机画布上:| 名称 | 类型 | 说明 |@@ -335,7 +335,7 @@ const drive = defineSystem([Query(Animator), Res(AnimatorController)], (q, anim)| `resetTrigger(entity, name)` | 在被消费前清除一个 trigger。 || `getFloat(entity, name)` / `getBool(entity, name)` | 读回一个参数。 |-控制器可以同时驱动精灵**和** [Spine](/docs/zh-cn/guides/spine/) 动画,所以一套状态机就能+控制器可以同时驱动精灵**和** [Spine](/docs/zh-cn/animation/spine/) 动画,所以一套状态机就能管一整个角色。参数有三种类型(`AnimatorParamType`):`'float'`、`'bool'`、`'trigger'`。条件用@@ -384,7 +384,7 @@ const setup = defineSystem([Res(AnimatorController)], (anim) => {纯函数 `selectBlendClip(blend, value)` 返回某个值会选中的档位——方便做工具或测试。骨骼角色的状态可以改为携带 `spine` 运动(`AnimatorSpineMotion`,-`{ animation, loop? }`):进入时控制器设置该 [Spine](/docs/zh-cn/guides/spine/)+`{ animation, loop? }`):进入时控制器设置该 [Spine](/docs/zh-cn/animation/spine/)动画(`loop` 默认 `true`),轨道播放与混合交给 Spine 运行时——完全不碰`SpriteAnimator`。状态互斥:`clip`、`blend`、`spine`、`stateMachine` 四者取一。@@ -464,6 +464,6 @@ evaluateAnimatorPath(player, 'locomotion/idle', { speed: 3 }, new Set());## 参见-- [Spine 动画](/docs/zh-cn/guides/spine/) —— 骨骼动画,也能被状态机驱动。-- [时间轴](/docs/zh-cn/guides/timeline/) —— 关键帧过场与序列化事件。-- [相机](/docs/zh-cn/guides/camera/) —— 补间 `CameraOrthoSize` 做平滑缩放。+- [Spine 动画](/docs/zh-cn/animation/spine/) —— 骨骼动画,也能被状态机驱动。+- [时间轴](/docs/zh-cn/animation/timeline/) —— 关键帧过场与序列化事件。+- [相机](/docs/zh-cn/graphics/camera/) —— 补间 `CameraOrthoSize` 做平滑缩放。diff --git a/docs/astro/src/content/docs/zh-cn/animation/spine.mdx b/docs/astro/src/content/docs/zh-cn/animation/spine.mdxindex 23646bc5b..7cc9fd290 100644--- a/docs/astro/src/content/docs/zh-cn/animation/spine.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/spine.mdx@@ -126,7 +126,7 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {- **设一个默认混合**(`setDefaultMix`)让转移交叉淡入而非硬切;热点路径用 `setMixDuration` 覆盖。- **用轨道 + `setTrackAlpha` 分层**(例如在轨道 1 放一个瞄准/叠加,混合在轨道 0 的移动之上)。- **跨实体共享骨骼 + 图集**——它们引用计数同一份已加载骨骼。-- **用 [Animator](/docs/zh-cn/guides/animation/) 状态机驱动整个角色**,它既能驱动 Spine 也能驱动精灵。+- **用 [Animator](/docs/zh-cn/animation/overview/) 状态机驱动整个角色**,它既能驱动 Spine 也能驱动精灵。<Aside type="note">Estella 支持 Spine **2.1 / 3.8 / 4.1 / 4.2 / 4.3**——每个骨骼版本按需加载自己的@@ -141,6 +141,6 @@ const onSpine = defineSystem([Res(SpineEvents)], (spineEvents) => {## 参见-- [动画](/docs/zh-cn/guides/animation/) —— Animator 状态机可以驱动 Spine。-- [资源](/docs/zh-cn/guides/assets/) —— 加载骨骼 + 图集资源。-- [DragonBones 动画](/docs/zh-cn/guides/dragonbones/) —— 另一个骨骼运行时,MIT 许可。+- [动画](/docs/zh-cn/animation/overview/) —— Animator 状态机可以驱动 Spine。+- [资源](/docs/zh-cn/assets/overview/) —— 加载骨骼 + 图集资源。+- [DragonBones 动画](/docs/zh-cn/animation/dragonbones/) —— 另一个骨骼运行时,MIT 许可。diff --git a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdxindex 5f327fb65..6d6bb1637 100644--- a/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx+++ b/docs/astro/src/content/docs/zh-cn/animation/timeline.mdx@@ -36,7 +36,7 @@ const attach = defineSystem([Commands()], (cmds) => {| `finished` | boolean | `false` | `'once'` 片段播完时闩为 true;下次播放时清除。运行时只读。 |组件旗标**就是**播放控制本身:引擎每帧把它们调和进内部时钟,所以任何翻动-`playing` 的一方——你的代码、检视器、[AI 动作](/docs/zh-cn/guides/ai/#内建名字)——+`playing` 的一方——你的代码、检视器、[AI 动作](/docs/zh-cn/gameplay/ai/#内建名字)——都经同一条通道驱动片段。## 控制播放@@ -73,7 +73,7 @@ const control = defineSystem([Query(TimelinePlayer), Res(Timeline)], (q, timelin<Aside type="tip">想做**零代码过场**,把组件和状态机配对:内建的 `timeline.play` 动作 +`timeline.finished` 条件就是一个"进入即播放、播完即转出"的 FSM 状态。见- [AI——内建名字](/docs/zh-cn/guides/ai/#内建名字)。+ [AI——内建名字](/docs/zh-cn/gameplay/ai/#内建名字)。</Aside>## 轨道类型@@ -216,7 +216,7 @@ API 里。映射与行为:- 过场用 **`wrapMode: 'once'`**,环境/待机序列用 `'loop'`。- **用 `setTime` scrub** 来预览,或把过场与玩法状态同步。- 当很多属性/实体需要同步动画时**用时间轴(而非补间)**;一次性的单属性手感用- [补间](/docs/zh-cn/guides/animation/)。+ [补间](/docs/zh-cn/animation/overview/)。<Aside type="note">时间轴播放属于玩法——它在播放模式和独立运行时里推进,在编辑器编辑模式下冻结。@@ -224,5 +224,5 @@ API 里。映射与行为:## 参见-- [动画](/docs/zh-cn/guides/animation/) —— 补间与动画状态机。-- [Spine 动画](/docs/zh-cn/guides/spine/) —— 时间轴可以驱动 Spine 片段。+- [动画](/docs/zh-cn/animation/overview/) —— 补间与动画状态机。+- [Spine 动画](/docs/zh-cn/animation/spine/) —— 时间轴可以驱动 Spine 片段。diff --git a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx b/docs/astro/src/content/docs/zh-cn/assets/audio.mdxindex e4fa7980a..4b99e0395 100644--- a/docs/astro/src/content/docs/zh-cn/assets/audio.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/audio.mdx@@ -296,5 +296,5 @@ const pan = calculatePanning(600, 0, 0, 0, 1000); // 0.6 — to the right## 参见-- [资源](/docs/zh-cn/guides/assets/) —— 加载与打包音频片段。-- [场景](/docs/zh-cn/guides/scene/) —— `AudioSource` 状态随场景持久化。+- [资源](/docs/zh-cn/assets/overview/) —— 加载与打包音频片段。+- [场景](/docs/zh-cn/world/scenes/) —— `AudioSource` 状态随场景持久化。diff --git a/docs/astro/src/content/docs/zh-cn/assets/localization.mdx b/docs/astro/src/content/docs/zh-cn/assets/localization.mdxindex 2f444a377..887d6efa3 100644--- a/docs/astro/src/content/docs/zh-cn/assets/localization.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/localization.mdx@@ -119,5 +119,5 @@ i18n.t('apples', { count: 3 }); // "3 apples"## 参见-- [UI](/docs/zh-cn/guides/ui/) —— 绑定所依托的 `Text` 组件。-- [资源](/docs/zh-cn/guides/assets/) —— 资产如何发布与加载。+- [UI](/docs/zh-cn/ui/overview/) —— 绑定所依托的 `Text` 组件。+- [资源](/docs/zh-cn/assets/overview/) —— 资产如何发布与加载。diff --git a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx b/docs/astro/src/content/docs/zh-cn/assets/overview.mdxindex 6cbef3dd3..cc664c268 100644--- a/docs/astro/src/content/docs/zh-cn/assets/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/assets/overview.mdx@@ -70,7 +70,7 @@ const { data } = await assets.loadJson<LevelTable>('assets/data/levels.json');把它当资源加载、而不是自己去 fetch 那个路径,不是走形式。数据资源有 uuid,所以移动文件不会让指向它的东西失效;它只解析一次并被引用计数;它可以放进惰性[分组](#寻址组懒加载)或者从 CDN 来;-[热更新](/docs/zh-cn/guides/hot-update/)能在已发行的游戏里替换它。手写的 `fetch` 一样都拿不到——+[热更新](/docs/zh-cn/publishing/hot-update/)能在已发行的游戏里替换它。手写的 `fetch` 一样都拿不到——而且它**在编辑器里是通的**(编辑器伺服整个项目),而构建只装资源。数据资源无论有没有人引用都会进包——见[只有代码点名的资产](#只有代码点名的资产),@@ -109,7 +109,7 @@ assets.releaseGroup('level2');折返该区域时由热缓存吸收,而不是重走网络。`loadByLabel(...)` 按 label 标签加载资源,而不是按文件夹分组。正是这种分组映射到-[微信分包](/docs/zh-cn/guides/wechat/),实现按需下载。+[微信分包](/docs/zh-cn/publishing/wechat/),实现按需下载。当你想预热的资源集合不是一个组或标签时——比如玩家还在当前区域,就先加载下一区域的纹理——`preload` 接受显式的引用列表,自动推断每个资源的类型(清单优先,其次文件扩展名),@@ -194,7 +194,7 @@ const { failed } = await assets.preload(纹理预算默认 **64 MB**(`RuntimeConfig.textureCacheBudget`,也可在构建配置里用`textureCacheBudget` 设置);解码音频有自己的 **32 MB** 镜像(`audioCacheBudget`,-见[音频指南](/docs/zh-cn/guides/audio/))。+见[音频指南](/docs/zh-cn/assets/audio/))。## 纹理内存与预算@@ -227,9 +227,9 @@ const freed = trimTextureCache(); // 立即丢弃所有可逐出纹理`{ width, height }`(首次查询后缓存在 TS 侧),`evictTextureDimensions(handle)` 丢弃那条缓存——资源系统在纹理真正释放时会这么做,所以只有绕过资源系统自己销毁重建纹理时才需要它。-想逐帧观察这些数字(编辑器内和运行时),见[性能分析](/docs/zh-cn/guides/profiling/)。+想逐帧观察这些数字(编辑器内和运行时),见[性能分析](/docs/zh-cn/performance/profiling/)。逐纹理的**采样/过滤**参数(像素风 nearest 还是平滑 linear)见-[精灵指南](/docs/zh-cn/guides/sprites/)。+[精灵指南](/docs/zh-cn/graphics/sprites/)。## 最佳实践@@ -249,6 +249,6 @@ const freed = trimTextureCache(); // 立即丢弃所有可逐出纹理## 参见-- [微信小游戏](/docs/zh-cn/guides/wechat/) —— 可寻址分组如何映射到子包。-- [场景](/docs/zh-cn/guides/scene/) —— 场景引用资源,并作为入口点被 cook。-- [材质与着色器](/docs/zh-cn/guides/material/) —— `loadMaterial` 与着色器句柄。+- [微信小游戏](/docs/zh-cn/publishing/wechat/) —— 可寻址分组如何映射到子包。+- [场景](/docs/zh-cn/world/scenes/) —— 场景引用资源,并作为入口点被 cook。+- [材质与着色器](/docs/zh-cn/graphics/materials/) —— `loadMaterial` 与着色器句柄。diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdxindex bf34e7533..3cac6e274 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/app-lifecycle.mdx@@ -307,8 +307,8 @@ host 用 `acquire(id)` 应答,返回已实例化模块的 promise(按 id 缓存,主 `esengine` barrel 恰好镜像了物理/Spine 的**接线**层——`PhysicsPlugin`、`PhysicsEvents`、`Physics`、`loadPhysicsModule`、`SpinePlugin`、`SpineEvents`、`Spine`——宿主无需子路径导入即可注册这些插件。完整 API 在- `esengine/physics` 与 `esengine/spine` 子路径上。见[物理](/docs/zh-cn/guides/physics/)- 与 [Spine](/docs/zh-cn/guides/spine/)。+ `esengine/physics` 与 `esengine/spine` 子路径上。见[物理](/docs/zh-cn/gameplay/physics/)+ 与 [Spine](/docs/zh-cn/animation/spine/)。</Aside>## 热重载@@ -326,7 +326,7 @@ import 你的 bundle,返回一个 `ProbedRegistrations`:`defineComponent('Health', …)` 解析到*同一个*组件身份,因此重新导入的系统的查询能命中存活的存储。相应地,给组件或 behavior 改名是结构性变更(整体重载 +该数据的状态丢失),且重载后每实体的 `start` 钩子会再次运行——请把它写成幂等-的初始化(见[脚本](/docs/zh-cn/guides/scripting/))。+的初始化(见[脚本](/docs/zh-cn/scripting/overview/))。## 最佳实践@@ -347,6 +347,6 @@ import 你的 bundle,返回一个 `ProbedRegistrations`:- [插件与资源](/docs/zh-cn/core-concepts/plugins-resources/)——用 `Res(...)`触达子系统 API。- [系统](/docs/zh-cn/core-concepts/systems/)——调度与系统参数。-- [构建与导出](/docs/zh-cn/guides/build-export/)——侧模块产物在各目标如何发布。-- [物理](/docs/zh-cn/guides/physics/)与 [Spine](/docs/zh-cn/guides/spine/)——+- [构建与导出](/docs/zh-cn/publishing/overview/)——侧模块产物在各目标如何发布。+- [物理](/docs/zh-cn/gameplay/physics/)与 [Spine](/docs/zh-cn/animation/spine/)——侧模块背后的两个子路径 API。diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdxindex f5522135d..ba1f1f9ff 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/components.mdx@@ -64,18 +64,18 @@ const Turret = defineComponent('Turret', {常用的 `fields` 选项:`min` / `max` / `step`、`slider`、`unit`、`enum`(下拉,存储选项的整数值)、`flags`(位掩码多选)、`tooltip`。其他组件级元数据:`assetFields`(把字段标记为资产引用,Details 渲染选择器、cook 会带上依赖)、-`animatableFields`([Sequencer](/docs/zh-cn/guides/timeline/) 可打关键帧的字段+`animatableFields`([Sequencer](/docs/zh-cn/animation/timeline/) 可打关键帧的字段——默认为全部数字字段)、`transient`(永不存进场景——用于逐帧运行时状态),以及-`replicatedFields`(由[联网](/docs/zh-cn/guides/networking/)的状态复制同步)。+`replicatedFields`(由[联网](/docs/zh-cn/scripting/networking/)的状态复制同步)。## 内置组件SDK 自带约 30 个引擎组件,与你自己的组件一起查询——`Transform`、`Sprite`、`ShapeRenderer`、`Camera`、`Light2D`、`ParticleEmitter`、`SpineAnimation`、`TilemapLayer`、UI 组件族、物理碰撞体等等。各自在对应的子系统指南里有完整文档:-[精灵与渲染](/docs/zh-cn/guides/sprites/)、[相机](/docs/zh-cn/guides/camera/)、-[2D 光照](/docs/zh-cn/guides/lighting/)、[物理](/docs/zh-cn/guides/physics/)、-[瓦片地图](/docs/zh-cn/guides/tilemap/)、[UI](/docs/zh-cn/guides/ui/)。+[精灵与渲染](/docs/zh-cn/graphics/sprites/)、[相机](/docs/zh-cn/graphics/camera/)、+[2D 光照](/docs/zh-cn/graphics/lighting/)、[物理](/docs/zh-cn/gameplay/physics/)、+[瓦片地图](/docs/zh-cn/world/tilemaps/)、[UI](/docs/zh-cn/ui/overview/)。## 读取与写入diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdxindex 4259e37a7..4984f996a 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/ecs.mdx@@ -26,9 +26,9 @@ C++/WebAssembly 内核中,SDK 通过一份生成并经哈希校验的内存布- [`defineComponent`](/docs/zh-cn/core-concepts/components/) —— 声明一个组件类型。- [`defineSystem`](/docs/zh-cn/core-concepts/systems/) —— 声明一个系统及其查询。- [`App` / 插件](/docs/zh-cn/core-concepts/plugins-resources/) —— 把系统、资源与- 各子系统([物理](/docs/zh-cn/guides/physics/)、[Spine](/docs/zh-cn/guides/spine/)、- [瓦片地图](/docs/zh-cn/guides/tilemap/)、[UI](/docs/zh-cn/guides/ui/)、- [音频](/docs/zh-cn/guides/audio/)、[场景](/docs/zh-cn/guides/scene/))组装成一个+ 各子系统([物理](/docs/zh-cn/gameplay/physics/)、[Spine](/docs/zh-cn/animation/spine/)、+ [瓦片地图](/docs/zh-cn/world/tilemaps/)、[UI](/docs/zh-cn/ui/overview/)、+ [音频](/docs/zh-cn/assets/audio/)、[场景](/docs/zh-cn/world/scenes/))组装成一个运行中的游戏。```typescriptdiff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdxindex 16df8b1c5..78aa8515b 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/plugins-resources.mdx@@ -22,25 +22,25 @@ defineSystem([Res(Audio)], (audio) => {| 子系统 | 资源 | 指南 ||---|---|---|-| 输入 | `Res(Input)` | [输入](/docs/zh-cn/guides/input/) |-| 音频 | `Res(Audio)` | [音频](/docs/zh-cn/guides/audio/) |-| 资源 | `Res(Assets)` | [资源](/docs/zh-cn/guides/assets/) |-| 瓦片地图 | `Res(Tilemaps)` | [瓦片地图](/docs/zh-cn/guides/tilemap/) |-| 粒子 | `Res(Particle)` | [粒子](/docs/zh-cn/guides/particle/) |-| 后处理 | `Res(PostProcess)` | [后处理](/docs/zh-cn/guides/postprocess/) |-| 场景 | `Res(SceneManager)` | [场景](/docs/zh-cn/guides/scene/) |-| 补间 | `Res(Tween)` | [动画](/docs/zh-cn/guides/animation/) |-| 帧动画 | `Res(SpriteAnimation)` | [动画](/docs/zh-cn/guides/animation/) |-| 动画机 | `Res(AnimatorController)` | [动画](/docs/zh-cn/guides/animation/) |-| 计时器 | `Res(TimerRes)` | [脚本](/docs/zh-cn/guides/scripting/) |-| 时间轴 | `Res(Timeline)` | [时间轴](/docs/zh-cn/guides/timeline/) |-| 预制体 | `Res(Prefabs)` | [预制体](/docs/zh-cn/guides/prefab/) |-| 导航 / AI | `Res(Nav)` | [游戏 AI](/docs/zh-cn/guides/ai/) |-| 本地化 | `Res(Localization)` | [本地化](/docs/zh-cn/guides/localization/) |-| 相机视图 | `Res(CameraView)` | [相机](/docs/zh-cn/guides/camera/) |-| UI 事件 | `Res(UIEvents)` | [UI](/docs/zh-cn/guides/ui/) |-| 物理 | `Res(Physics)` —— 来自 `esengine/physics` | [物理](/docs/zh-cn/guides/physics/) |-| Spine | `Res(Spine)` —— 来自 `esengine/spine` | [Spine](/docs/zh-cn/guides/spine/) |+| 输入 | `Res(Input)` | [输入](/docs/zh-cn/scripting/input/) |+| 音频 | `Res(Audio)` | [音频](/docs/zh-cn/assets/audio/) |+| 资源 | `Res(Assets)` | [资源](/docs/zh-cn/assets/overview/) |+| 瓦片地图 | `Res(Tilemaps)` | [瓦片地图](/docs/zh-cn/world/tilemaps/) |+| 粒子 | `Res(Particle)` | [粒子](/docs/zh-cn/world/particles/) |+| 后处理 | `Res(PostProcess)` | [后处理](/docs/zh-cn/graphics/post-processing/) |+| 场景 | `Res(SceneManager)` | [场景](/docs/zh-cn/world/scenes/) |+| 补间 | `Res(Tween)` | [动画](/docs/zh-cn/animation/overview/) |+| 帧动画 | `Res(SpriteAnimation)` | [动画](/docs/zh-cn/animation/overview/) |+| 动画机 | `Res(AnimatorController)` | [动画](/docs/zh-cn/animation/overview/) |+| 计时器 | `Res(TimerRes)` | [脚本](/docs/zh-cn/scripting/overview/) |+| 时间轴 | `Res(Timeline)` | [时间轴](/docs/zh-cn/animation/timeline/) |+| 预制体 | `Res(Prefabs)` | [预制体](/docs/zh-cn/world/prefabs/) |+| 导航 / AI | `Res(Nav)` | [游戏 AI](/docs/zh-cn/gameplay/ai/) |+| 本地化 | `Res(Localization)` | [本地化](/docs/zh-cn/assets/localization/) |+| 相机视图 | `Res(CameraView)` | [相机](/docs/zh-cn/graphics/camera/) |+| UI 事件 | `Res(UIEvents)` | [UI](/docs/zh-cn/ui/overview/) |+| 物理 | `Res(Physics)` —— 来自 `esengine/physics` | [物理](/docs/zh-cn/gameplay/physics/) |+| Spine | `Res(Spine)` —— 来自 `esengine/spine` | [Spine](/docs/zh-cn/animation/spine/) |物理和 Spine 是**可选 side-module**,按需加载,因此它们的 API 放在子路径上以保持基础包精简;其余都在主 `esengine` 包里。上表的基础子系统都随标准 App 附带——无需接线。diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdxindex 88f0bf0f2..a76612e0b 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/screen.mdx@@ -19,7 +19,7 @@ Estella 的 2D 单位模型刻意保持简单:- 默认场景相机的 `orthoSize` 是 `designResolution.y / 2` = **540**——设计高度的一半——所以在设计宽高比下,相机恰好显示一个设计盒(1920×1080 世界单位)。- 世界是 **Y 向上**;屏幕坐标是 **Y 向下**(由- [`CameraView`](/docs/zh-cn/guides/camera/) 为你转换)。+ [`CameraView`](/docs/zh-cn/graphics/camera/) 为你转换)。- `Canvas.pixelsPerUnit`(默认 `100`)是**物理缩放**——每 Box2D 米的世界像素数——**不是**显示缩放。渲染从不除以它。@@ -301,7 +301,7 @@ applyBuildRuntimeConfig(app, {## 参见-- [相机](/docs/zh-cn/guides/camera/) —— orthoSize、跟随、混合、分屏。-- [UI](/docs/zh-cn/guides/ui/) —— 消费设计像素盒的 flexbox 布局。-- [物理](/docs/zh-cn/guides/physics/) —— `pixelsPerUnit` 真正起作用的地方。-- [编辑器](/docs/zh-cn/guides/editor/) —— 显示设置页与设备预览。+- [相机](/docs/zh-cn/graphics/camera/) —— orthoSize、跟随、混合、分屏。+- [UI](/docs/zh-cn/ui/overview/) —— 消费设计像素盒的 flexbox 布局。+- [物理](/docs/zh-cn/gameplay/physics/) —— `pixelsPerUnit` 真正起作用的地方。+- [编辑器](/docs/zh-cn/editor/overview/) —— 显示设置页与设备预览。diff --git a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdxindex b4d52b720..40fe214f6 100644--- a/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx+++ b/docs/astro/src/content/docs/zh-cn/core-concepts/transforms.mdx@@ -38,9 +38,9 @@ const drift = defineSystem([Query(Mut(Transform))], (q) => {});```-`position.x/y/z`、`rotation.z`、`scale.x/y/z` 是可动画字段([Sequencer](/docs/zh-cn/guides/timeline/)-和[补间](/docs/zh-cn/guides/animation/#补间tween)可以打关键帧),而 `position` /-`rotation` / `scale` 会被[网络](/docs/zh-cn/guides/networking/)的状态复制同步。+`position.x/y/z`、`rotation.z`、`scale.x/y/z` 是可动画字段([Sequencer](/docs/zh-cn/animation/timeline/)+和[补间](/docs/zh-cn/animation/overview/#补间tween)可以打关键帧),而 `position` /+`rotation` / `scale` 会被[网络](/docs/zh-cn/scripting/networking/)的状态复制同步。<Aside type="note">`LocalTransform` 和 `WorldTransform` 是**同一个组件的别名导出**——@@ -59,13 +59,13 @@ const drift = defineSystem([Query(Mut(Transform))], (q) => {(`Math.atan2(dy, dx)` 可直接得到指向目标的角度)。- **`position.z` 是绘制顺序,不是透视**:2D 渲染先按各渲染器的排序层 `layer` 粗排;同一层内用 `z` 做精细排序(俯视角深度请用- [y 排序层](/docs/zh-cn/guides/sprites/#绘制顺序与排序层))。它不会使精灵产生+ [y 排序层](/docs/zh-cn/graphics/sprites/#绘制顺序与排序层))。它不会使精灵产生透视缩放。- **屏幕空间 Y 轴向下**:指针坐标(`Input.mouseX/mouseY`、UI 命中测试)是从画布**左上角**起算的像素,Y 向下增大。用 `CameraView` 资源在两个空间之间转换(完整 API 见-[相机](/docs/zh-cn/guides/camera/#屏幕--世界坐标)):+[相机](/docs/zh-cn/graphics/camera/#屏幕--世界坐标)):```typescriptimport { defineSystem, Res, CameraView, Input } from 'esengine';@@ -175,10 +175,10 @@ const aim = defineSystem([Query(Mut(Transform)).with(Turret), Res(CameraView)],想动画化旋转,`TweenTarget.RotationZ` 以**弧度**驱动 Z 角度(引擎每步重建四元数),Sequencer 给 `rotation.z` 打关键帧也是同样的语义——见-[动画](/docs/zh-cn/guides/animation/#补间tween)。+[动画](/docs/zh-cn/animation/overview/#补间tween)。<Aside type="tip">- 如果只需要瞄准数学而完全不碰旋转,[数学辅助](/docs/zh-cn/guides/math/)里的+ 如果只需要瞄准数学而完全不碰旋转,[数学辅助](/docs/zh-cn/scripting/math/)里的`v2.fromAngle(angle, len)` 和 `v2.rotate(v, angle)` 可以直接产出方向向量。</Aside>@@ -273,7 +273,7 @@ world = parentWorld × T(position) × R(rotation) × S(scale)## 另请参阅- [组件](/docs/zh-cn/core-concepts/components/)——组件如何声明与存储数据。-- [相机](/docs/zh-cn/guides/camera/)——orthoSize、跟随与屏幕 ↔ 世界转换。-- [精灵与渲染](/docs/zh-cn/guides/sprites/)——排序层、y 排序与绘制顺序。-- [物理](/docs/zh-cn/guides/physics/)——单位制中以米为单位的那一侧。-- [数学辅助](/docs/zh-cn/guides/math/)——在规范类型上做向量与旋转数学。+- [相机](/docs/zh-cn/graphics/camera/)——orthoSize、跟随与屏幕 ↔ 世界转换。+- [精灵与渲染](/docs/zh-cn/graphics/sprites/)——排序层、y 排序与绘制顺序。+- [物理](/docs/zh-cn/gameplay/physics/)——单位制中以米为单位的那一侧。+- [数学辅助](/docs/zh-cn/scripting/math/)——在规范类型上做向量与旋转数学。diff --git a/docs/astro/src/content/docs/zh-cn/editor/overview.mdx b/docs/astro/src/content/docs/zh-cn/editor/overview.mdxindex 1651d122f..5f565dc7b 100644--- a/docs/astro/src/content/docs/zh-cn/editor/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/editor/overview.mdx@@ -26,7 +26,7 @@ Estella 编辑器是一个桌面应用(Electron + React),带 UE5 风格的**可| `.esengine/workspace.json` | 编辑器本地状态(上次打开的场景、面板布局)。被 gitignore。 || `assets/scenes/*.esscene` | 你的场景。 || `assets/…` | 纹理、材质、瓦片集等资产,每个带一个 `.meta` 边车文件。 |-| `src/components.ts` | **声明入口**——编辑器会求值这个模块以及它 import 到的一切,以此认识你的组件。组件定义在哪都行,从这里 re-export 出来即可。见[脚本](/zh-cn/docs/guides/scripting/#声明放在哪里)。 |+| `src/components.ts` | **声明入口**——编辑器会求值这个模块以及它 import 到的一切,以此认识你的组件。组件定义在哪都行,从这里 re-export 出来即可。见[脚本](/zh-cn/docs/scripting/overview/#声明放在哪里)。 || `src/main.ts` | **启动入口**——注册系统的地方。跑游戏的是它;编辑器从不求值它。 |资产按 UUID(`@uuid:…`)可移植地引用,而不是按路径,所以移动或重命名文件不会断掉引用。@@ -196,9 +196,9 @@ Details 是选中项的检视器。它列出实体上的每个组件及其字段一点即设主轴与交叉轴对齐的 **3×3 对齐网格**、主轴**分布**(紧凑 / 两端 / 环绕 / 均匀),以及**换行 / 填满**开关——**内边距**用一个四边 `sides` 控件编辑;- 一个内联 **Controllers(控制器)条**,把逐节点的状态创作拉进检视器:选一个状态页、给字段- *挂齿轮*绑定,全程不用离开面板(见 [UI 控制器](/docs/zh-cn/guides/ui-controllers/));+ *挂齿轮*绑定,全程不用离开面板(见 [UI 控制器](/docs/zh-cn/ui/controllers/));- 对**材质**,一个 **Shader** 选择器,用于切换绑定的着色器——内置模板或项目里的 `.esshader`——见- [材质与着色器](/docs/zh-cn/guides/material/#在编辑器里选取与共享着色器)。+ [材质与着色器](/docs/zh-cn/graphics/materials/#在编辑器里选取与共享着色器)。@@ -228,7 +228,7 @@ Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即**新建脚本…** 是唯一一个不止写一个文件的:没人 import 的模块永远不会被打包,它的组件也永远进不了 Add Component,所以对话框还会在项目的脚本入口里加上够到它的那一行——加到哪个入口,取决于你建的是组件还是系统。见-[脚本编写](/docs/zh-cn/guides/scripting/#新建脚本对话框)。+[脚本编写](/docs/zh-cn/scripting/overview/#新建脚本对话框)。**导入**可从访达/资源管理器把文件拖进来,或用"导入…"。每个资产首次出现时会得到一个 `.meta`边车。按资产的上下文动作包括重命名、复制、复制路径、复制引用、**查找引用**、在文件管理器中@@ -263,11 +263,11 @@ Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即在内容浏览器里双击一个资产,即可在文档标签里打开它的编辑器。-- **Sequencer** — 关键帧动画的时间轴/曲线编辑器。见 [时间轴](/docs/zh-cn/guides/timeline/)。+- **Sequencer** — 关键帧动画的时间轴/曲线编辑器。见 [时间轴](/docs/zh-cn/animation/timeline/)。- **瓦片地图画笔** — **画笔、擦除、矩形、直线、油漆桶、选区、吸管**和**地形(autotile)**等工具,外加图章 **水平翻转 / 垂直翻转 / 旋转 90°**(画笔工具激活时按 `H` / `V` / `R`)和一个**随机散布模式**(`D`)。调色板用方向键选择(`Shift` 扩成多瓦片图章),地图可以是- **正交、等距、交错或六边形**。见 [瓦片地图](/docs/zh-cn/guides/tilemap/)。+ **正交、等距、交错或六边形**。见 [瓦片地图](/docs/zh-cn/world/tilemaps/)。- **瓦片集编辑器** — 创作每瓦片的**碰撞**(盒 / 圆 / 多边形、斜坡预设;单向 / 传感器 / 材质修饰),并可在放大的瓦片上**直接操纵**编辑形状:拖圆的**圆心或半径**、给多边形**点击加点 /拖动 / 点击删点**编辑**顶点**、给**单向**平台挑选实心的一侧(上 / 下 / 左 / 右)——调整大小会@@ -275,9 +275,9 @@ Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即**角 Wang**)、逐瓦片**概率**权重与属性,以及**动画瓦片**——拖动帧缩略图**重排**,或把整段循环设成**一个统一时长**,带实时预览。- **状态机**(`.esfsm`)和**行为树**(`.esbt`)编辑器 — AI 的可视化图。见- [游戏 AI](/docs/zh-cn/guides/ai/)。+ [游戏 AI](/docs/zh-cn/gameplay/ai/)。- **材质图**(`.esmatgraph`) — 编译成着色器的节点编辑器。见- [材质与着色器](/docs/zh-cn/guides/material/)。+ [材质与着色器](/docs/zh-cn/graphics/materials/)。状态机和行为树编辑器共享一块公共节点画布:**中键拖动**平移,**滚轮**朝光标缩放,把一个输出手柄拖到另一个节点上连线,点击选中节点或边,**Delete** 删除,右键画布在光标处添加节点。@@ -293,9 +293,9 @@ Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即(所有导出目标都遵循它;留空则从设计分辨率的宽高比推导),以及**相机适配**(主相机如何在无 UICanvas 的情况下按设计分辨率缩放;`无`=关闭)。- **UI** — 项目的控件**主题**(深色 / 浅色)与逐角色的**主题颜色**覆盖,在编辑器、Play- 和所有导出里一致生效。见 [UI 控件——主题](/docs/zh-cn/guides/ui-components/#主题)。+ 和所有导出里一致生效。见 [UI 控件——主题](/docs/zh-cn/ui/widgets/#主题)。- **物理** — 启用、重力、十六个碰撞层名字和一个 16×16 碰撞矩阵,以及解算器调参(固定时间步、- 子步、接触 Hz/阻尼/推出速度、允许睡眠、连续碰撞)。见 [物理](/docs/zh-cn/guides/physics/)。+ 子步、接触 Hz/阻尼/推出速度、允许睡眠、连续碰撞)。见 [物理](/docs/zh-cn/gameplay/physics/)。- **渲染** — 最多三十二个命名排序层,填充检视器里的层下拉,以及其中哪些参与 Y 轴排序。名字只是建议,不是上限:渲染组件的 `layer` 照样接受名单以外的数字。- **打包** — 每目标元数据:微信 AppID、桌面应用 id / 产品名。@@ -304,7 +304,7 @@ Details 同时是**资产检视器**:在内容浏览器里选中一个资产,即编辑器内置 **English** 和 **简体中文**,首次启动跟随系统语言。在 **设置 → 外观 → 语言** 切换——更改在重新加载后生效(编辑器会弹出提示)。编辑器界面文案跑在与游戏运行时相同的-[本地化引擎](/docs/zh-cn/guides/localization/)上。+[本地化引擎](/docs/zh-cn/assets/localization/)上。## 键盘快捷键@@ -345,7 +345,7 @@ Home/End、`→` / `←` 进出子菜单),Outliner 输入名字即跳转,内容## 参见-- [场景](/docs/zh-cn/guides/scene/) —— 一个 `.esscene` 里有什么、如何加载。-- [脚本](/docs/zh-cn/guides/scripting/) —— 项目组件会自动出现在检视器里。-- [预制体](/docs/zh-cn/guides/prefab/) —— 带逐实例覆盖的可复用实体模板。-- [构建与导出](/docs/zh-cn/guides/build-export/) —— 把项目发布到 Web、微信或可玩广告。+- [场景](/docs/zh-cn/world/scenes/) —— 一个 `.esscene` 里有什么、如何加载。+- [脚本](/docs/zh-cn/scripting/overview/) —— 项目组件会自动出现在检视器里。+- [预制体](/docs/zh-cn/world/prefabs/) —— 带逐实例覆盖的可复用实体模板。+- [构建与导出](/docs/zh-cn/publishing/overview/) —— 把项目发布到 Web、微信或可玩广告。diff --git a/docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdx b/docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdxindex ae4810333..382686fe3 100644--- a/docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdx+++ b/docs/astro/src/content/docs/zh-cn/extending/built-in-agent.mdx@@ -7,7 +7,7 @@ import { Aside, Steps } from '@astrojs/starlight/components';编辑器自带一个 Agent。你打一句话,它读场景、调用编辑器 UI 调用的同一批工具,并把每一次调用都摊在你眼前。它不是编辑器的另一份复制品:它驱动的工具目录,-和[外部 MCP 客户端](/docs/zh-cn/guides/mcp/)驱动的是同一份——它能做什么,+和[外部 MCP 客户端](/docs/zh-cn/extending/mcp/)驱动的是同一份——它能做什么,和编辑器能做什么,是一张清单。<Aside type="tip">@@ -114,8 +114,8 @@ import { Aside, Steps } from '@astrojs/starlight/components';## 参见-- [AI 代理 (MCP)](/docs/zh-cn/guides/mcp/) —— 同一份工具目录,+- [AI 代理 (MCP)](/docs/zh-cn/extending/mcp/) —— 同一份工具目录,只不过是从 Claude Code、Cursor 或你自己的代理去驱动,而不是从编辑器内部。-- [事件绑定](/docs/zh-cn/guides/events/) —— 你要求"不写代码的行为"时,Agent 会去用的东西。-- [预制体](/docs/zh-cn/guides/prefab/) —— 在预制体模式下,Agent 编辑的是预制体而不是场景。+- [事件绑定](/docs/zh-cn/scripting/events/) —— 你要求"不写代码的行为"时,Agent 会去用的东西。+- [预制体](/docs/zh-cn/world/prefabs/) —— 在预制体模式下,Agent 编辑的是预制体而不是场景。要它做大改动之前,先确认它正在编辑的是哪个文档。diff --git a/docs/astro/src/content/docs/zh-cn/extending/mcp.mdx b/docs/astro/src/content/docs/zh-cn/extending/mcp.mdxindex ab16169c7..04f0565d8 100644--- a/docs/astro/src/content/docs/zh-cn/extending/mcp.mdx+++ b/docs/astro/src/content/docs/zh-cn/extending/mcp.mdx@@ -148,7 +148,7 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \### 给按钮接线-场景不写一行游戏代码也能给按钮行为——一行[事件绑定](/docs/zh-cn/guides/events/)+场景不写一行游戏代码也能给按钮行为——一行[事件绑定](/docs/zh-cn/scripting/events/)说的是*当这个事件发生,就跑那个具名动作*。`set_event_bindings` 在**一个撤销步骤**里整体替换某实体的绑定行(传空列表即拆线),`get_event_bindings` 读回来:@@ -184,5 +184,5 @@ claude mcp add estella --env ESTELLA_MCP_ALLOW_WRITES=1 -- \## 参见-- [编辑器](/docs/zh-cn/guides/editor/) —— 这个自动化面驱动的可视化编辑器。-- [脚本](/docs/zh-cn/guides/scripting/) —— 同一套场景 / 组件模型,从游戏代码这边看。+- [编辑器](/docs/zh-cn/editor/overview/) —— 这个自动化面驱动的可视化编辑器。+- [脚本](/docs/zh-cn/scripting/overview/) —— 同一套场景 / 组件模型,从游戏代码这边看。diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/ai.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/ai.mdxindex 29e28f3d6..e7e6846e4 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/ai.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/ai.mdx@@ -51,7 +51,7 @@ registerAction('chase', (ctx) => {```每个动作和条件都会收到它所运行实体的 **`AiContext`**。它和一个-[`defineBehavior`](/docs/zh-cn/guides/scripting/) 的 update 是同一套编程模型——实体、世界、+[`defineBehavior`](/docs/zh-cn/scripting/overview/) 的 update 是同一套编程模型——实体、世界、命令的访问——外加一个每个 agent 独有的 `blackboard`(黑板):| 成员 | 类型 | 说明 |@@ -92,7 +92,7 @@ export enum Status { Success = 'success', Failure = 'failure', Running = 'runnin| 名字 | 类别 | 效果 ||---|---|---|-| `timeline.play` | 动作 | 拉起该实体 [`TimelinePlayer`](/docs/zh-cn/guides/timeline/) 的播放旗标。对已播完的片段,从头重播。 |+| `timeline.play` | 动作 | 拉起该实体 [`TimelinePlayer`](/docs/zh-cn/animation/timeline/) 的播放旗标。对已播完的片段,从头重播。 || `timeline.pause` | 动作 | 放下播放旗标(用 `timeline.play` 恢复)。 || `timeline.finished` | 条件 | 片段已完成(`once` 片段播到末尾)且未在播放时为真。 || `spriteAnim.play` | 动作 | 播放代理实体的精灵翻页动画;**参数**可切换到指定剪辑。 |@@ -541,7 +541,7 @@ export const setupNavGrid = defineSystem([Res(Nav)], (nav) => {## 参见-- [脚本](/docs/zh-cn/guides/scripting/) —— 行为是声明式系统;叶子就是普通函数。-- [动画](/docs/zh-cn/guides/animation/) —— 用状态机驱动精灵动画。-- [场景](/docs/zh-cn/guides/scene/) —— `.esfsm` / `.esbt` 资产随场景加载与序列化。-- [事件绑定](/docs/zh-cn/guides/events/) —— 点击或触发可以 `fsm.fire` 进状态机;动作与条件出自同一个注册表。+- [脚本](/docs/zh-cn/scripting/overview/) —— 行为是声明式系统;叶子就是普通函数。+- [动画](/docs/zh-cn/animation/overview/) —— 用状态机驱动精灵动画。+- [场景](/docs/zh-cn/world/scenes/) —— `.esfsm` / `.esbt` 资产随场景加载与序列化。+- [事件绑定](/docs/zh-cn/scripting/events/) —— 点击或触发可以 `fsm.fire` 进状态机;动作与条件出自同一个注册表。diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdxindex 0d058b40e..4fd3861f9 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/markers.mdx@@ -15,7 +15,7 @@ import { Aside } from '@astrojs/starlight/components';Marker 就是 `Marker` 组件(一个 `type` 字符串加一个自由形式的 `properties` 映射),挂在一个同时带 `Transform` 的实体上。单独存在时它是一个点——游戏通过查询某个 `type` 的标记来问“该在-哪里生成玩家?”。给同一个实体加上一个静态 [`RigidBody`](/docs/zh-cn/guides/physics/) 和一个+哪里生成玩家?”。给同一个实体加上一个静态 [`RigidBody`](/docs/zh-cn/gameplay/physics/) 和一个传感器碰撞体,它就变成一块触发区;**Trigger Area** 预设会替你把这些一次接好。因为 Marker 是纯 ECS,没有任何特殊的东西要加载或解析:@@ -23,7 +23,7 @@ Marker 就是 `Marker` 组件(一个 `type` 字符串加一个自由形式的 `p- 它和任何组件一样**随场景序列化**。- 它出现在 **Inspector** 里,包括一个键→值属性编辑器。- 它**可 `Query`**——同一条代码路径既读你手工放置的标记,*也*读从- [Tiled](/docs/zh-cn/guides/tilemap/) `.tmj` 对象层导入的标记。+ [Tiled](/docs/zh-cn/world/tilemaps/) `.tmj` 对象层导入的标记。`type` 的词汇完全由你定义:`spawn`、`waypoint`、`door`、`chest`、`checkpoint`——字符串的含义由游戏说了算。@@ -31,7 +31,7 @@ Marker 就是 `Marker` 组件(一个 `type` 字符串加一个自由形式的 `p## 安装`Marker` 在主 `esengine` barrel 里——放置或查询它无需任何插件。**Trigger Area** 带一个传感器-碰撞体,因此需要[物理](/docs/zh-cn/guides/physics/):在编辑器和 Web 运行时,当场景用到物理+碰撞体,因此需要[物理](/docs/zh-cn/gameplay/physics/):在编辑器和 Web 运行时,当场景用到物理组件时物理模块会自动加载;在自定义 app 里,请自己加上插件:```typescript@@ -45,7 +45,7 @@ app.addPlugin(new PhysicsPlugin('physics.js'));**Create → Common → Marker** 在场景原点放一个命名点;**Create → Physics → Trigger Area**放一块传感区域(Transform + 静态 RigidBody + 传感器 BoxCollider + Marker)。Marker 在视口里显示一个**图钉 gizmo**;Trigger Area 还会画出它的碰撞体轮廓,你用与任何其他刚体相同的-[碰撞体 gizmo](/docs/zh-cn/guides/physics/) 来塑形。+[碰撞体 gizmo](/docs/zh-cn/gameplay/physics/) 来塑形。在 Inspector 里设置标记的 **Type**,并添加任意多个自定义 **properties**(一个键→值映射——`targetScene: "level2"`、`team: "red"` 等等)。二者都能存/读并进入构建。@@ -116,12 +116,12 @@ const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, mar```在繁忙的世界里让传感器保持廉价:把触发区和应当感知它们的刚体放到专门的-[碰撞层](/docs/zh-cn/guides/physics/#碰撞过滤)上,让每个传感器的掩码收窄它要考虑的范围。完整-事件面见 [碰撞与传感事件](/docs/zh-cn/guides/physics/#碰撞与传感事件)。+[碰撞层](/docs/zh-cn/gameplay/physics/#碰撞过滤)上,让每个传感器的掩码收窄它要考虑的范围。完整+事件面见 [碰撞与传感事件](/docs/zh-cn/gameplay/physics/#碰撞与传感事件)。## 从 Tiled 导入-当 [`Tilemap`](/docs/zh-cn/guides/tilemap/) 加载一张 `.tmj` 地图时,它的**对象层**汇聚到你+当 [`Tilemap`](/docs/zh-cn/world/tilemaps/) 加载一张 `.tmj` 地图时,它的**对象层**汇聚到你手工创建的同一批实体上——没有单独的结构要遍历:| Tiled 对象 | 变成 |@@ -141,11 +141,11 @@ const onTrigger = defineSystem([Res(PhysicsEvents), Query(Marker)], (events, mar- **能查一次就查一次。** 出生点、路点图、巡逻路线通常在场景开始时读一次;缓存结果,别每帧重查。- **复用同一套标记词汇**,横跨手工创建的场景与导入的 Tiled 地图——查询代码不关心标记从哪来。- **Trigger Area 是传感器**——要*挡住*的东西(墙、台沿),请画一块- [碰撞层](/docs/zh-cn/guides/tilemap/#碰撞障碍层)或用非传感器碰撞体。+ [碰撞层](/docs/zh-cn/world/tilemaps/#碰撞障碍层)或用非传感器碰撞体。## 参见-- [瓦片地图](/docs/zh-cn/guides/tilemap/) —— 碰撞(障碍)层与喂给同一批 Marker 的 Tiled 对象层。-- [物理](/docs/zh-cn/guides/physics/) —— 传感器、碰撞过滤,以及 Trigger Area 背后的 `PhysicsEvents` 资源。-- [场景](/docs/zh-cn/guides/scene/) —— Marker 与 Trigger Area 随场景序列化。-- [事件绑定](/docs/zh-cn/guides/events/) —— 有东西进入 Trigger Area 时执行一个动作,直接挂在触发区上,不写代码。+- [瓦片地图](/docs/zh-cn/world/tilemaps/) —— 碰撞(障碍)层与喂给同一批 Marker 的 Tiled 对象层。+- [物理](/docs/zh-cn/gameplay/physics/) —— 传感器、碰撞过滤,以及 Trigger Area 背后的 `PhysicsEvents` 资源。+- [场景](/docs/zh-cn/world/scenes/) —— Marker 与 Trigger Area 随场景序列化。+- [事件绑定](/docs/zh-cn/scripting/events/) —— 有东西进入 Trigger Area 时执行一个动作,直接挂在触发区上,不写代码。diff --git a/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdxindex c77409abd..5e8002670 100644--- a/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx+++ b/docs/astro/src/content/docs/zh-cn/gameplay/physics.mdx@@ -342,7 +342,7 @@ const drive = defineSystem([Query(Mut(CharacterController))], (q) => {给实体加一个碰撞体(mover 形状由它推导——盒子会内接成沿长轴的胶囊);若希望别的刚体能撞到角色,再加一个**运动学(Kinematic)** `RigidBody`。mover 会自动排除角色自身的刚体,所以它的 `maskBits`不必刻意避开自身的碰撞层。用固定步长的系统驱动 `velocity` 让运动与帧率无关;跳跃读 `isOnFloor`-边沿(会正确投递到 `FixedUpdate`——见 [输入](/docs/zh-cn/guides/input/#固定步长物理))。+边沿(会正确投递到 `FixedUpdate`——见 [输入](/docs/zh-cn/scripting/input/#固定步长物理))。| 属性 | 类型 | 默认 | 说明 ||---|---|---|---|@@ -365,7 +365,7 @@ const drive = defineSystem([Query(Mut(CharacterController))], (q) => {## 调试绘制物理插件会安装一个 **`PhysicsDebugDraw`** 资源——一个游戏内叠加层,通过-[`Draw`](/docs/zh-cn/guides/drawing/) API 描出碰撞体轮廓、速度向量和接触点。+[`Draw`](/docs/zh-cn/graphics/drawing/) API 描出碰撞体轮廓、速度向量和接触点。它默认关闭;在任何系统里翻转 `enabled`,就能看见求解器眼中的世界:```typescript@@ -404,5 +404,5 @@ gizmo(见[关节——在编辑器里](#在编辑器里));两者互相独立。<## 参见-- [场景](/docs/zh-cn/guides/scene/) —— 物理组件随场景序列化。-- [数学辅助](/docs/zh-cn/guides/math/) —— 速度与方向的向量运算。+- [场景](/docs/zh-cn/world/scenes/) —— 物理组件随场景序列化。+- [数学辅助](/docs/zh-cn/scripting/math/) —— 速度与方向的向量运算。diff --git a/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdxindex 7f331fa97..7a6c71b0c 100644--- a/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx+++ b/docs/astro/src/content/docs/zh-cn/getting-started/introduction.mdx@@ -25,7 +25,7 @@ Estella 是一个 **2D 游戏引擎**:上层是 TypeScript SDK,底层由高|----|------|| **TypeScript SDK**(`esengine`) | 你编写的界面:`App`、`World`、系统、组件、查询、插件。 || **WasmBridge** | SDK 与引擎之间的唯一边界,内存布局由生成器产出并经哈希校验。 |-| **C++ / WebAssembly** | 引擎内核:ECS 存储、渲染器(`GfxDevice`)、资源、粒子、瓦片地图、文本。在[移动端](/docs/zh-cn/guides/mobile/),同一份内核改为编译到 arm64。 |+| **C++ / WebAssembly** | 引擎内核:ECS 存储、渲染器(`GfxDevice`)、资源、粒子、瓦片地图、文本。在[移动端](/docs/zh-cn/publishing/android-ios/),同一份内核改为编译到 arm64。 |完整架构见[`ARCHITECTURE.md`](https://github.com/esengine/estella/blob/master/docs/ARCHITECTURE.md)。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdxindex 90eeb6585..197526856 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/camera.mdx@@ -61,7 +61,7 @@ SDK 默认值为 2D 调好(正交、活动、`orthoSize` 540)。移动相机就## 缩放与投影`orthoSize` 是缩放控制——减半即让屏上尺寸翻倍。因为它是 `animatable` 的,最平滑的缩放方式-是用一个 [tween](/docs/zh-cn/guides/animation/):+是用一个 [tween](/docs/zh-cn/animation/overview/):```typescriptimport { defineSystem, Res, Tween, TweenTarget } from 'esengine';@@ -283,6 +283,6 @@ updateCameraAspectRatio(app.world, canvas.width / canvas.height);- [屏幕与设计分辨率](/docs/zh-cn/core-concepts/screen/) —— 设计分辨率适配、缩放模式、`ScreenScaling` 与 `pixelPerfect` 的深入讲解。-- [动画](/docs/zh-cn/guides/animation/) —— 用 tween 缩放 `orthoSize`。-- [输入](/docs/zh-cn/guides/input/) —— 用鼠标配 `screenToWorld` 做拾取。-- [UI](/docs/zh-cn/guides/ui/) —— UI 在屏幕空间渲染,与相机无关。+- [动画](/docs/zh-cn/animation/overview/) —— 用 tween 缩放 `orthoSize`。+- [输入](/docs/zh-cn/scripting/input/) —— 用鼠标配 `screenToWorld` 做拾取。+- [UI](/docs/zh-cn/ui/overview/) —— UI 在屏幕空间渲染,与相机无关。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdxindex c3c468125..fe69450ca 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/drawing.mdx@@ -5,7 +5,7 @@ description: 超出组件的绘制——用 Draw 画即时模式图元、用 Graimport { Aside } from '@astrojs/starlight/components';-大多数视觉是组件——[精灵](/docs/zh-cn/guides/sprites/)、瓦片地图、粒子。当它们+大多数视觉是组件——[精灵](/docs/zh-cn/graphics/sprites/)、瓦片地图、粒子。当它们表达不了你要的东西——调试覆盖层、程序化形状、自定义几何——引擎把绘制层直接暴露给你。@@ -15,7 +15,7 @@ import { Aside } from '@astrojs/starlight/components';|---|---|---|| `Draw` | **即时模式**,全局——命令自动合批、每帧清空。 | 调试覆盖层、gizmo、任何每帧从头重画的东西。 || `Graphics` | **保留式**路径记录器——构建一次,`flush()` 时经 `Draw` 回放。 | 带路径/贝塞尔/圆弧的矢量形状,不想每帧重新细分。 |-| `ShapeRenderer` / `Mesh2D` | **组件**——带排序层、材质、编辑器 gizmo 的实体。 | 属于场景的形状/网格(见[精灵](/docs/zh-cn/guides/sprites/))。 |+| `ShapeRenderer` / `Mesh2D` | **组件**——带排序层、材质、编辑器 gizmo 的实体。 | 属于场景的形状/网格(见[精灵](/docs/zh-cn/graphics/sprites/))。 |经验法则:视觉属于*场景*(参与排序、保存、可检视)就做成组件;属于*某一帧*(调试、类 HUD 覆盖、程序化效果)就在回调里画。@@ -108,7 +108,7 @@ cmds.spawn()## 自定义几何:`Geometry` API`Mesh2D` 是*组件*路径,`Geometry` 则是*即时*路径:它上传一个索引顶点缓冲,交回-一个**句柄**由你自己绘制——配上[材质](/docs/zh-cn/guides/material/)用+一个**句柄**由你自己绘制——配上[材质](/docs/zh-cn/graphics/materials/)用`Draw.drawMeshWithMaterial(geometry, material, transform?)`(或配原始着色器用`Draw.drawMesh(geometry, shader, transform)`)。@@ -151,7 +151,7 @@ registerDrawCallback('custom-mesh', () => {## 离屏目标:`RenderTexture`-小地图、头像、镜面——以及[位图缓存](/docs/zh-cn/guides/sprites/)的底层——+小地图、头像、镜面——以及[位图缓存](/docs/zh-cn/graphics/sprites/)的底层——`RenderTexture` 分配一个离屏渲染目标。把绘制命令包在 `begin`/`end` 之间即渲染进去;得到的 `texture` 是普通纹理句柄,哪里都能用(`Sprite.texture`、`Draw.texture`、材质纹理参数):@@ -192,6 +192,6 @@ sprite.texture = rt.texture;## 参见-- [精灵与渲染](/docs/zh-cn/guides/sprites/) —— 图像与形状的组件路径。-- [材质与着色器](/docs/zh-cn/guides/material/) —— 给任何渲染体上自定义着色器。-- [相机](/docs/zh-cn/guides/camera/) —— 回调所用 view-projection 的来源。+- [精灵与渲染](/docs/zh-cn/graphics/sprites/) —— 图像与形状的组件路径。+- [材质与着色器](/docs/zh-cn/graphics/materials/) —— 给任何渲染体上自定义着色器。+- [相机](/docs/zh-cn/graphics/camera/) —— 回调所用 view-projection 的来源。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdxindex c8a83cb60..21076eb3d 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/lighting.mdx@@ -114,7 +114,7 @@ void main() {在编辑器里,内容浏览器的 **New Material (Lit)** 创建的正是这样一个现成的受光材质,自带色调参数和可选法线贴图。代码侧的编译与赋材质方式与-[材质与着色器](/docs/zh-cn/guides/material/)里完全一致:+[材质与着色器](/docs/zh-cn/graphics/materials/)里完全一致:```typescriptimport { Material, defineSystem, Query, Mut, Sprite } from 'esengine';@@ -127,7 +127,7 @@ const applyLit = defineSystem([Query(Mut(Sprite))], (q) => {```你也能可视化地做一个受光材质——把 **材质图** 的域设为 `Lit2D`——见-[材质图](/docs/zh-cn/guides/material/)一节。+[材质图](/docs/zh-cn/graphics/materials/)一节。<Aside type="tip">每个接受 `material` 的渲染器——`Sprite`、`SpineAnimation`、`ParticleEmitter`、`Mesh2D`@@ -140,7 +140,7 @@ const applyLit = defineSystem([Query(Mut(Sprite))], (q) => {你传给 `applyLighting2D` 的 `N` 是表面法线。传一个常量 `vec3(0, 0, 1)` 得到平坦、均匀受光的表面。要有逐像素的凹凸感,就在着色器里采样一张**法线贴图**并用它作 `N`——同一张基础色便会随每盏灯的方向产生高光和阴影。把法线纹理作为一个 `#pragma param … texture` 加到你的受光材质上-(见[材质与着色器](/docs/zh-cn/guides/material/))。+(见[材质与着色器](/docs/zh-cn/graphics/materials/))。## 投射阴影@@ -177,7 +177,7 @@ cmds.spawn()线性模式也是 **HDR** 的入口:只要浮点渲染目标可用(WebGPU 恒可用;WebGL2 有`EXT_color_buffer_float`),后处理链就跑在半浮点上——`intensity` 大于 1 的灯把真正的超范围-能量推进 [bloom 与 tonemap](/docs/zh-cn/guides/postprocess/),亮光会发辉光。+能量推进 [bloom 与 tonemap](/docs/zh-cn/graphics/post-processing/),亮光会发辉光。在 **项目设置 → 渲染 → 色彩空间 → 线性** 启用。着色器按该模式编译,所以它在引擎启动时定死——编辑器会提示重新加载。设置随项目清单走:视口、运行预览和所有导出——web、桌面、微信、playable——@@ -195,13 +195,13 @@ const app = createWebApp(module, { colorSpace: 'linear' });- 通过 **创建… → 光** 添加光源,或在 Details 面板里给已有实体加一个 `Light2D` 组件。- 光源在编辑模式下画成 **gizmo**——图标加上其范围圈和朝向/锥——所以你能凭眼睛瞄准和调尺寸。见- [编辑器](/docs/zh-cn/guides/editor/)。+ [编辑器](/docs/zh-cn/editor/overview/)。- 在 Details 里实时调 `color`(取色器)、`intensity`、`radius` 和聚光角度;结果在视口里即时更新。- 一盏灯的全部视觉字段(`color`、`intensity`、`radius`、各角度、阴影设置)都**可动画**——在- [Sequencer](/docs/zh-cn/guides/timeline/)里给它们打关键帧,做闪烁的火把、昼夜循环或脉动的信标。+ [Sequencer](/docs/zh-cn/animation/timeline/)里给它们打关键帧,做闪烁的火把、昼夜循环或脉动的信标。## 参见-- [材质与着色器](/docs/zh-cn/guides/material/) —— 受光材质与自定义着色。-- [后处理](/docs/zh-cn/guides/postprocess/) —— 在受光场景上叠加辉光与调色。-- [精灵与渲染](/docs/zh-cn/guides/sprites/) —— 让 2D 精灵在光下有立体感的法线贴图。+- [材质与着色器](/docs/zh-cn/graphics/materials/) —— 受光材质与自定义着色。+- [后处理](/docs/zh-cn/graphics/post-processing/) —— 在受光场景上叠加辉光与调色。+- [精灵与渲染](/docs/zh-cn/graphics/sprites/) —— 让 2D 精灵在光下有立体感的法线贴图。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdxindex ac6189596..26a414168 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/materials.mdx@@ -274,7 +274,7 @@ Material.setUniform(mat, 'u_tint', [1, 0, 0, 1]); // 图参数就是普通参材质不局限于组件渲染器:**`Geometry`** API(`Geometry.create` 加`GeometryOptions` 顶点布局,还有 `createQuad` / `createCircle` / `createPolygon`辅助函数)构建句柄式网格,用 `Draw.drawMeshWithMaterial(geometry, material)`-即时绘制——完整参考见[自定义绘制](/docs/zh-cn/guides/drawing/)。+即时绘制——完整参考见[自定义绘制](/docs/zh-cn/graphics/drawing/)。## 最佳实践@@ -292,6 +292,6 @@ Material.setUniform(mat, 'u_tint', [1, 0, 0, 1]); // 图参数就是普通参## 参见-- [后处理](/docs/zh-cn/guides/postprocess/) —— 全屏效果(独立的管线)。-- [资源](/docs/zh-cn/guides/assets/) —— `loadMaterial` 与着色器句柄。-- [粒子](/docs/zh-cn/guides/particle/) —— 给发射器指定自定义 `material`。+- [后处理](/docs/zh-cn/graphics/post-processing/) —— 全屏效果(独立的管线)。+- [资源](/docs/zh-cn/assets/overview/) —— `loadMaterial` 与着色器句柄。+- [粒子](/docs/zh-cn/world/particles/) —— 给发射器指定自定义 `material`。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdxindex 3211f3b92..e4c2b0ce7 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/post-processing.mdx@@ -33,7 +33,7 @@ Estella 通过 ping-pong 帧缓冲运行全屏后处理。加一个 `PostProcess## HDR(线性色彩空间)-当项目以**线性色彩空间**渲染时(见[光照](/docs/zh-cn/guides/lighting/)),只要浮点渲染目标+当项目以**线性色彩空间**渲染时(见[光照](/docs/zh-cn/graphics/lighting/)),只要浮点渲染目标可用——WebGPU 恒可用,WebGL2 上是几乎无处不在的 `EXT_color_buffer_float`——效果链就跑在**半浮点 HDR** 上。超过 `1.0` 的光照累积(`intensity` 大于 1 的 `Light2D`)会*存活*进效果链,而不是在 8 位存储处被压平:@@ -123,5 +123,5 @@ stack.addPass('lutGrade', getEffectDef('lutGrade')!.factory())## 参见-- [材质与着色器](/docs/zh-cn/guides/material/) —— 逐物体着色器(独立的路径)。-- [相机](/docs/zh-cn/guides/camera/) —— 为每个相机绑定一个栈。+- [材质与着色器](/docs/zh-cn/graphics/materials/) —— 逐物体着色器(独立的路径)。+- [相机](/docs/zh-cn/graphics/camera/) —— 为每个相机绑定一个栈。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdxindex f9a6cfa41..fbdb9edf6 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/sprites.mdx@@ -6,12 +6,12 @@ description: 用 Sprite 组件绘制 2D 图像——纹理、着色与透明、import { Aside } from '@astrojs/starlight/components';**`Sprite`** 是 2D 渲染的主力:一个带 `Sprite` 组件的实体在世界里绘制一个带纹理的四边形。要绘制-不带纹理的实心图元,有 **`ShapeRenderer`**。一切都经由 [相机](/docs/zh-cn/guides/camera/) 绘制,+不带纹理的实心图元,有 **`ShapeRenderer`**。一切都经由 [相机](/docs/zh-cn/graphics/camera/) 绘制,而绘制顺序由**排序层**控制。## 你的第一个精灵-一个精灵需要 `Transform`(在哪)和 `Sprite`(画什么)。通过 [`Assets`](/docs/zh-cn/guides/assets/)+一个精灵需要 `Transform`(在哪)和 `Sprite`(画什么)。通过 [`Assets`](/docs/zh-cn/assets/overview/)资源加载一张纹理,把它的句柄放到精灵上:```typescript@@ -38,7 +38,7 @@ const spawnPlayer = defineSystem([Commands(), Res(Assets)], async (cmds, assets)| `pivot` | `{0.5,0.5}` | 精灵旋转/缩放所绕的轴心点(0–1)。 || `layer` | `0` | 排序层——控制绘制顺序(见下)。 || `flipX` / `flipY` | `false` | 水平 / 垂直镜像。 |-| `material` | `0` | 自定义[材质](/docs/zh-cn/guides/material/)句柄(`0` = 默认精灵着色器)。 |+| `material` | `0` | 自定义[材质](/docs/zh-cn/graphics/materials/)句柄(`0` = 默认精灵着色器)。 || `lit` | `false` | 用平面法线接收 2D 光照——让精灵变"受光"的一键路径(自定义 `material` 会覆盖它)。 || `uvOffset` / `uvScale` | `{0,0}` / `{1,1}` | 要显示的纹理子矩形(用于图集 / 滚动)。 || `tileSize` / `tileSpacing` | `{0,0}` | 把纹理在精灵上平铺重复(`0` = 不平铺)。 |@@ -54,7 +54,7 @@ sprite.color = { r: 1, g: 0.4, b: 0.4, a: 1 }; // 泛红sprite.color = { r: 1, g: 1, b: 1, a: 0.5 }; // 50% 透明```-`color`(和 `size`)都**可动画**——在 [Sequencer](/docs/zh-cn/guides/timeline/) 里给它们打关键帧+`color`(和 `size`)都**可动画**——在 [Sequencer](/docs/zh-cn/animation/timeline/) 里给它们打关键帧做闪烁和淡入淡出。## 尺寸与轴心@@ -75,7 +75,7 @@ sprite.color = { r: 1, g: 1, b: 1, a: 0.5 }; // 50% 透明<Aside type="note">`Canvas.pixelsPerUnit`(默认 `100`)**不会**缩放精灵——它是**物理米尺度**:- 多少设计像素等于一个 Box2D 米(见[物理](/docs/zh-cn/guides/physics/))。精灵的+ 多少设计像素等于一个 Box2D 米(见[物理](/docs/zh-cn/gameplay/physics/))。精灵的显示尺寸只由 `size` × `Transform` 缩放决定,别无其他。完整的单位与坐标空间图景见[变换](/docs/zh-cn/core-concepts/transforms/)。</Aside>@@ -155,7 +155,7 @@ world.applyEntityOrder([other, another, card]);- 用 `flipX` / `flipY` **翻转**精灵——例如让角色朝左或朝右,而不用另一张纹理。- **图集**:把 `uvOffset` 和 `uvScale` 设为某个单元格的归一化矩形,显示打包图集里的一格。(逐帧动画- 请用 [Animator](/docs/zh-cn/guides/animation/) 驱动这些,而非手动。)+ 请用 [Animator](/docs/zh-cn/animation/overview/) 驱动这些,而非手动。)- **滚动**:随时间改 `uvOffset` 来滚动纹理(水面、传送带),并设 `tileSize` 把它在大精灵上重复平铺。## 纹理过滤与环绕@@ -197,7 +197,7 @@ setTextureParams(tex.handle, TextureFilter.Nearest, TextureFilter.Nearest,对像素画来说 `TextureFilter.Nearest` 只解决一半问题:它让**纹素**锐利,但相机停在小数位置时精灵仍会落在屏幕像素之间,移动时闪烁。把它和相机的`pixelPerfect` 标志配合使用——它把(正交)相机吸附到像素网格——见- [相机](/docs/zh-cn/guides/camera/)。+ [相机](/docs/zh-cn/graphics/camera/)。</Aside>## 视差背景@@ -208,11 +208,11 @@ setTextureParams(tex.handle, TextureFilter.Nearest, TextureFilter.Nearest,## 自定义材质与光照给 `sprite.material` 赋值,用你自己的着色器绘制精灵——染色、溶解、扭曲——见-[材质与着色器](/docs/zh-cn/guides/material/)。+[材质与着色器](/docs/zh-cn/graphics/materials/)。要让精灵响应 `Light2D` 光源,最简单的路径是设 `sprite.lit = true`——无需自定义材质(用平面法线受光)。需要法线贴图或完全自定义的观感时,改用 **Lit-2D 材质**。两种方式都见-[2D 光照与阴影](/docs/zh-cn/guides/lighting/)。+[2D 光照与阴影](/docs/zh-cn/graphics/lighting/)。### 精灵滤镜(描边、发光、投影)@@ -294,12 +294,12 @@ UI。把 `font` 指向一个 **BMFont** 资产(`.fnt` 文本或 `.bmfont` JSON),| `layer` / `parallax` | `0` / `{1,1}` | 与 `Sprite` 相同的排序层 / 视差语义。 |屏幕空间的 UI 文字(布局、换行、SDF 锐度)请用 UI 的 `Text` 控件——见-[UI](/docs/zh-cn/guides/ui/)。+[UI](/docs/zh-cn/ui/overview/)。## 精灵点击检测"这次点击落在这个精灵上了吗?"分两步:把屏幕点转到世界空间,再对精灵的矩形做测试。-第一步由 `CameraView` 资源完成(见[相机](/docs/zh-cn/guides/camera/));第二步 SDK+第一步由 `CameraView` 资源完成(见[相机](/docs/zh-cn/graphics/camera/));第二步 SDK导出了感知轴心的点测试:| 函数 | 测试 |@@ -342,7 +342,7 @@ const hit = pointInHitArea(p.x - t.worldPosition.x, p.y - t.worldPosition.y, hul`screenToWorld` 也有独立导出(接收逆 view-projection 矩阵和视口矩形),供自己管理相机数学的代码使用——`CameraView` 资源就是同一个函数、替你填好了当前相机。至于交互式 **UI**,别手写这些:`Interactable` + `UIEvents` 会替你做拾取(见-[UI](/docs/zh-cn/guides/ui/))。+[UI](/docs/zh-cn/ui/overview/))。## 位图缓存(Cache as bitmap)@@ -380,16 +380,16 @@ Draw.texture(pos, { x: 512, y: 256 }, cache.textureId);````cache.textureId` 是普通的纹理句柄——也可以直接当 `Sprite.texture` 用。底层就是一个-不带深度缓冲的 [RenderTexture](/docs/zh-cn/guides/drawing/)。+不带深度缓冲的 [RenderTexture](/docs/zh-cn/graphics/drawing/)。## 在编辑器里- **创建 → 精灵** 添加一个精灵实体,或从内容浏览器**把图拖**进视口,生成一个已带纹理的精灵。- 上面每个字段都能在 **Details** 里编辑;精灵、相机、光源在视口里显示为 gizmo。见- [编辑器](/docs/zh-cn/guides/editor/)。+ [编辑器](/docs/zh-cn/editor/overview/)。## 参见-- [动画](/docs/zh-cn/guides/animation/) —— 精灵表帧动画与属性补间。-- [自定义绘制](/docs/zh-cn/guides/drawing/) —— 精灵之外的网格与即时模式图形。-- [2D 光照与阴影](/docs/zh-cn/guides/lighting/) —— 法线贴图与逐精灵光照。+- [动画](/docs/zh-cn/animation/overview/) —— 精灵表帧动画与属性补间。+- [自定义绘制](/docs/zh-cn/graphics/drawing/) —— 精灵之外的网格与即时模式图形。+- [2D 光照与阴影](/docs/zh-cn/graphics/lighting/) —— 法线贴图与逐精灵光照。diff --git a/docs/astro/src/content/docs/zh-cn/graphics/video.mdx b/docs/astro/src/content/docs/zh-cn/graphics/video.mdxindex 6fa3e258c..7480cbb61 100644--- a/docs/astro/src/content/docs/zh-cn/graphics/video.mdx+++ b/docs/astro/src/content/docs/zh-cn/graphics/video.mdx@@ -146,6 +146,6 @@ const playIntro = defineSystem([Res(VideoPlayer)], (video) => {## 参见-- [精灵与渲染](/docs/zh-cn/guides/sprites/) —— Video 写入的纹理及其 `uvOffset` / `uvScale`。-- [资源](/docs/zh-cn/guides/assets/) —— 加载与打包视频片段。-- [微信小游戏](/docs/zh-cn/guides/wechat/) —— wasm 解码路径与导出。+- [精灵与渲染](/docs/zh-cn/graphics/sprites/) —— Video 写入的纹理及其 `uvOffset` / `uvScale`。+- [资源](/docs/zh-cn/assets/overview/) —— 加载与打包视频片段。+- [微信小游戏](/docs/zh-cn/publishing/wechat/) —— wasm 解码路径与导出。diff --git a/docs/astro/src/content/docs/zh-cn/index.mdx b/docs/astro/src/content/docs/zh-cn/index.mdxindex b66aafd8d..e623ff5ef 100644--- a/docs/astro/src/content/docs/zh-cn/index.mdx+++ b/docs/astro/src/content/docs/zh-cn/index.mdx@@ -45,9 +45,9 @@ import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';<CardGrid><LinkCard title="快速上手" href="/docs/zh-cn/getting-started/quick-start/" description="搭建你的第一个场景并运行。" />- <LinkCard title="编辑器" href="/docs/zh-cn/guides/editor/" description="可视化编辑器及其各面板导览。" />- <LinkCard title="精灵与渲染" href="/docs/zh-cn/guides/sprites/" description="绘制图像——着色、尺寸、排序与分层。" />- <LinkCard title="物理" href="/docs/zh-cn/guides/physics/" description="刚体、碰撞体、关节与空间查询。" />- <LinkCard title="游戏 AI" href="/docs/zh-cn/guides/ai/" description="导航、感知、状态机、行为树。" />- <LinkCard title="构建与导出" href="/docs/zh-cn/guides/build-export/" description="发布到 Web、桌面、微信、Playable 广告、Android 与 iOS。" />+ <LinkCard title="编辑器" href="/docs/zh-cn/editor/overview/" description="可视化编辑器及其各面板导览。" />+ <LinkCard title="精灵与渲染" href="/docs/zh-cn/graphics/sprites/" description="绘制图像——着色、尺寸、排序与分层。" />+ <LinkCard title="物理" href="/docs/zh-cn/gameplay/physics/" description="刚体、碰撞体、关节与空间查询。" />+ <LinkCard title="游戏 AI" href="/docs/zh-cn/gameplay/ai/" description="导航、感知、状态机、行为树。" />+ <LinkCard title="构建与导出" href="/docs/zh-cn/publishing/overview/" description="发布到 Web、桌面、微信、Playable 广告、Android 与 iOS。" /></CardGrid>diff --git a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdxindex 3f9861185..8ef7e5c68 100644--- a/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx+++ b/docs/astro/src/content/docs/zh-cn/performance/profiling.mdx@@ -382,7 +382,7 @@ GLDebug.disable();## GPU 资源预算与驻留已释放的贴图会驻留在一个按字节预算的温缓存里(完整模型见-[资源指南](/docs/zh-cn/guides/assets/#生命周期与引用计数))。这里是它的诊断面:+[资源指南](/docs/zh-cn/assets/overview/#生命周期与引用计数))。这里是它的诊断面:```typescriptimport { getResourceStats, setTextureBudget, trimTextureCache } from 'esengine';@@ -451,7 +451,7 @@ FPS。对游戏内构建,上面的 `statsPlugin` 就是对应物。## 另请参阅-- [资源](/docs/zh-cn/guides/assets/) — 资源统计所观察的贴图温缓存与预算。+- [资源](/docs/zh-cn/assets/overview/) — 资源统计所观察的贴图温缓存与预算。- [App 与生命周期](/docs/zh-cn/core-concepts/app-lifecycle/) — 插件、调度与子系统注册表。- [系统](/docs/zh-cn/core-concepts/systems/) — 调度与系统名(`systemTimings` 的键)。-- [编辑器](/docs/zh-cn/guides/editor/) — 桌面编辑器,含其 Profiler 面板。+- [编辑器](/docs/zh-cn/editor/overview/) — 桌面编辑器,含其 Profiler 面板。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdxindex 68ab13834..846039cdf 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/android-ios.mdx@@ -207,12 +207,12 @@ Android 的下限是 29,因为引擎的字体路径调用 `AFontMatcher_create`,```默认关闭,这是刻意的——正是可达性分析拦住了"什么都往包里塞"。-见[资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。+见[资源](/docs/zh-cn/assets/overview/#只有代码点名的资产)。### 为内存最紧张的平台单独调纹理逐资产的**导入设置**每个平台一个页签,移动目标也在其中——所以一张纹理可以为手机压得比-网页端更狠,而不用动源 PNG。见[资源](/docs/zh-cn/guides/assets/)。+网页端更狠,而不用动源 PNG。见[资源](/docs/zh-cn/assets/overview/)。### 你的游戏脚本是解释执行的@@ -301,7 +301,7 @@ adb logcat --pid=$(adb shell pidof <你的包名>)## 另见-- [构建与导出](/docs/zh-cn/guides/build-export/) —— 所有目标、cook 选项与打包对话框。-- [资源](/docs/zh-cn/guides/assets/) —— 可达性剔除、交付分组与导入设置。+- [构建与导出](/docs/zh-cn/publishing/overview/) —— 所有目标、cook 选项与打包对话框。+- [资源](/docs/zh-cn/assets/overview/) —— 可达性剔除、交付分组与导入设置。- [屏幕与设计分辨率](/docs/zh-cn/core-concepts/screen/) —— 为手机的宽高比做设计。- [`native/README.md`](https://github.com/esengine/estella/blob/master/native/README.md) —— 宿主架构与完整构建配方。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdxindex 353af65b9..492ad3dbb 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/hot-update.mdx@@ -38,10 +38,10 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回| 模式 | Bundle | 徽标 | 交付方式 | 适用于 || --- | --- | --- | --- | --- || **本地** | eager | — | 打进包内,启动时加载 | 游戏的核心资产 |-| **分包** | lazy | `分包`(紫) | 打进包内,按需加载 | 大体量可选内容、[微信分包](/docs/zh-cn/guides/wechat/) |+| **分包** | lazy | `分包`(紫) | 打进包内,按需加载 | 大体量可选内容、[微信分包](/docs/zh-cn/publishing/wechat/) || **远端** | remote | `CDN`(蓝) | 从 CDN 提供,**可热更新** | 任何你想在发布后改动的内容 |-只有**远端**组会被热更新——它们是按环境根地址从你的 CDN 拉取的资产。本地与分包资产都被烘进构建里。(分包是包*内*的按需加载,见 [资源 → 寻址组](/docs/zh-cn/guides/assets/#寻址组懒加载)。)+只有**远端**组会被热更新——它们是按环境根地址从你的 CDN 拉取的资产。本地与分包资产都被烘进构建里。(分包是包*内*的按需加载,见 [资源 → 寻址组](/docs/zh-cn/assets/overview/#寻址组懒加载)。)### 把文件夹标为 CDN 交付@@ -52,7 +52,7 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回*内容浏览器 → 右键文件夹 → **交付方式** → **本地 / 分包 / 远端(CDN / 热更)**。选择会写入 `.esengine/asset-groups.json`。*同一个子菜单里还有**总是打进构建**——一个独立开关,即使文件夹里没有任何东西能从场景可达,-也让它留在构建里。见[资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。+也让它留在构建里。见[资源](/docs/zh-cn/assets/overview/#只有代码点名的资产)。被指派到分包或远端组的文件夹会带一个角标**徽标**,让你一眼看清交付布局——`CDN`(蓝)表示远端,`分包`(紫)表示分包。@@ -94,7 +94,7 @@ Estella 的热更新是**内容寻址**、**原子**(要么全成、要么回| `groups` | `Record<name, {folder, mode}>` | 文件夹 → 交付方式的指派。 || `groups.<name>.folder` | `string` | 项目相对文件夹;其下(递归)每个资产都归入该组。文件夹嵌套时,**最长**匹配前缀胜出。 || `groups.<name>.mode` | `'local' \| 'subpackage' \| 'remote'` | 交付模式。 |-| `groups.<name>.alwaysInclude` | `boolean` | 即使构建里没有任何东西*可达*到它,也照样发布这个组——用于只有你的代码点名的资产(url、路径、富文本标记)。默认关闭。见[资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。 |+| `groups.<name>.alwaysInclude` | `boolean` | 即使构建里没有任何东西*可达*到它,也照样发布这个组——用于只有你的代码点名的资产(url、路径、富文本标记)。默认关闭。见[资源](/docs/zh-cn/assets/overview/#只有代码点名的资产)。 || `activeProfile` | `string` | 构建使用哪个 profile(`profiles` 的键)。 || `profiles.<name>.remoteRoot` | `string` | 该 profile 的远端组资产的 CDN 根地址。留空 ⇒ 同源。 |@@ -224,7 +224,7 @@ const bundle = await assets.loadGroup('world2', (loaded, total) => {assets.releaseGroup('world2');```-`loadGroup` 通过与其它一切相同的类型化加载器暖起缓存,`releaseGroup` 按引用计数释放——被另一个场景仍持有的资产会存活。完整的组模型见 [资源 → 寻址组](/docs/zh-cn/guides/assets/#寻址组懒加载)。+`loadGroup` 通过与其它一切相同的类型化加载器暖起缓存,`releaseGroup` 按引用计数释放——被另一个场景仍持有的资产会存活。完整的组模型见 [资源 → 寻址组](/docs/zh-cn/assets/overview/#寻址组懒加载)。## 完整性、原子性与回滚@@ -269,6 +269,6 @@ assets.releaseGroup('world2');## 参见-- [资源](/docs/zh-cn/guides/assets/)——引用、清单、类型化加载器与组模型。-- [构建与导出](/docs/zh-cn/guides/build-export/)——CDN 根地址与 `asset-manifest.json` 从哪里来。-- [微信小游戏](/docs/zh-cn/guides/wechat/)——分包如何映射到这里的交付组。+- [资源](/docs/zh-cn/assets/overview/)——引用、清单、类型化加载器与组模型。+- [构建与导出](/docs/zh-cn/publishing/overview/)——CDN 根地址与 `asset-manifest.json` 从哪里来。+- [微信小游戏](/docs/zh-cn/publishing/wechat/)——分包如何映射到这里的交付组。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdxindex cef22cfd4..3028ca618 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx@@ -34,7 +34,7 @@ import { Aside, Steps } from '@astrojs/starlight/components';## 构建场景项目场景目录下的每个场景都随导出发布,并成为 `SceneManager.switchTo` 的目标——游戏脚本-如何切换见[场景](/docs/zh-cn/guides/scene/)。对话框的**构建场景**列表控制这个集合:+如何切换见[场景](/docs/zh-cn/world/scenes/)。对话框的**构建场景**列表控制这个集合:- **启动场景**置顶并带播放徽标。它总是发布——点其他场景的播放按钮可把启动权移过去,或在内容浏览器里右键任意场景选**设为启动场景(Set as Startup Scene)**。@@ -59,10 +59,10 @@ import { Aside, Steps } from '@astrojs/starlight/components';|---|---|---|---|| **Web** | 一个静态、自包含的 Web 构建。 | `dist-web/` | **Preview over http**,或把文件夹上传到任意静态托管。 || **桌面** | 一棵 Electron 应用源码树。 | `dist-desktop/` | `cd dist-desktop && npm install && npm start`——或 `npm run dist` 出原生 `.dmg` / `.exe` / AppImage 安装包。 |-| **微信** | 一个微信小游戏包。 | `dist-wechat/` | 在微信开发者工具里打开该文件夹并设置你的 AppID。见 [微信小游戏](/docs/zh-cn/guides/wechat/)。 |+| **微信** | 一个微信小游戏包。 | `dist-wechat/` | 在微信开发者工具里打开该文件夹并设置你的 AppID。见 [微信小游戏](/docs/zh-cn/publishing/wechat/)。 || **Playable** | 一个自包含的 `index.html`,一切内联——无外部请求(广告平台的要求)。 | `dist-playable/` | **Preview over http**(它的真实宿主是广告平台的 iframe)。先选好[广告平台](#试玩广告平台),CTA 与体积检查才对得上投放目标。 |-| **Android** | **原生** arm64 应用(Vulkan)的内容——真 APK,不是 WebView。 | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` 把它包成已签名的 APK。见 [Android 与 iOS](/docs/zh-cn/guides/mobile/)。 |-| **iOS** | **原生** arm64 应用(Metal)的内容;若本机已为 iOS 构建过引擎,还会附带 Xcode 工程。 | `dist-ios/` | 打开生成的 Xcode 工程,选签名 Team,Run。见 [Android 与 iOS](/docs/zh-cn/guides/mobile/)。 |+| **Android** | **原生** arm64 应用(Vulkan)的内容——真 APK,不是 WebView。 | `dist-android/` | `node build-tools/cli.js native --package --content dist-android` 把它包成已签名的 APK。见 [Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。 |+| **iOS** | **原生** arm64 应用(Metal)的内容;若本机已为 iOS 构建过引擎,还会附带 Xcode 工程。 | `dist-ios/` | 打开生成的 Xcode 工程,选签名 Team,Run。见 [Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。 |移动目标导出的是应用**内容**而非可直接运行的载荷:引擎、SDK 和游戏运行时都住在应用二进制里。这也是它们需要另外四个目标不需要的工具链的原因——见下文的[前置条件](#运行时前置条件)。@@ -137,7 +137,7 @@ node build-tools/cli.js build -t wechat当某个目标的运行时缺失时,打包项目对话框会提醒你,而微信导出会**直接失败**并给出确切的构建命令——而不是产出一个运行时才崩的包。微信还需要为游戏用到的每个引擎特性构建对应的侧模块(`physics-wechat`、`spine-wechat`,压缩纹理用 `basis-wechat`)——见-[微信小游戏](/docs/zh-cn/guides/wechat/)。+[微信小游戏](/docs/zh-cn/publishing/wechat/)。对话框区分**两类**缺失的前置条件,因为它们挡住的程度并不一样:@@ -149,7 +149,7 @@ node build-tools/cli.js build -t wechat<Aside type="caution" title="移动端需要引擎源码检出">Android 和 iOS 是唯一一对编辑器下载包没有端到端自带的目标:原生宿主需要先从引擎源码检出构建一次(Dawn + QuickJS),再加上 Android SDK/NDK,或装有 Xcode 的 macOS。见- [Android 与 iOS](/docs/zh-cn/guides/mobile/)。+ [Android 与 iOS](/docs/zh-cn/publishing/android-ios/)。</Aside>## 目标渲染不了的内容@@ -205,14 +205,14 @@ KTX2 纹理由运行时转码为设备支持的最佳格式(ASTC → ETC2 → S3mip 链——下载更小、显存更省。**内容寻址** 对 Web/桌面默认开启(每个文件按字节哈希命名——URL 不可变、自动去重)。-**高级**里放着[热更新](/docs/zh-cn/guides/hot-update/)的 CDN 根地址、source map,+**高级**里放着[热更新](/docs/zh-cn/publishing/hot-update/)的 CDN 根地址、source map,以及构建结束后是否打开输出目录。<Aside type="caution" title="只有代码点名的资产会被剔除">cook 发布的是它能从构建场景**可达**的东西。只在代码里点名的东西——富文本标记里的纹理、按 url 播放的音频、按路径 spawn 的预制体——会被剔除,而编辑器直接从磁盘伺服项目,根本不会察觉。请在内容浏览器里把那个文件夹标记为 **交付方式 → 总是打进构建**。见- [资源](/docs/zh-cn/guides/assets/#只有代码点名的资产)。+ [资源](/docs/zh-cn/assets/overview/#只有代码点名的资产)。</Aside>## 打包设置@@ -231,7 +231,7 @@ mip 链——下载更小、显存更省。**试玩包是有意的例外**:它从不锁定页面方向。在广告 SDK 里,容器尺寸由 SDK 决定,因此"请旋转设备"这类遮罩可能把游戏永久挡住——玩家转了手机却毫无变化,因为那条 media query 一直在读容器而不是设备。试玩包保持自适应(各平台都要求如此),方向只在平台需要时**声明**出去,例如 Google 的 `ad.orientation` meta 标签。请为两种比例都设计,或用[相机适配](#)做 letterbox,让构图在任一比例下都成立。-设置界面见 [编辑器](/docs/zh-cn/guides/editor/)。+设置界面见 [编辑器](/docs/zh-cn/editor/overview/)。## 包体体积@@ -241,7 +241,7 @@ mip 链——下载更小、显存更省。- **首包** —— 玩家在能玩之前必须下载的部分:宿主页面、引擎运行时、你的脚本,以及 `local` 组里的资产。- **按需分包** —— 分包,在游戏请求那个组时才拉取。-- **CDN(不进包)** —— `remote` 组里的资产。它们是真实存在的字节,但住在你的 CDN 上,对包体零成本。见[热更新](/docs/zh-cn/guides/hot-update/)。+- **CDN(不进包)** —— `remote` 组里的资产。它们是真实存在的字节,但住在你的 CDN 上,对包体零成本。见[热更新](/docs/zh-cn/publishing/hot-update/)。这个划分读自运行时加载的同一份清单,所以报告说的和游戏做的不可能对不上。把一个关卡挪进分包是真的把它移出了主包,报告在你操作后立刻反映出来。@@ -289,13 +289,13 @@ node build-tools/cli.js native --target ios # …原生移动宿主<Aside type="note">大多数游戏开发者除了那一次性的微信运行时构建外,从不需要动构建 CLI——日常工作都在- 编辑器和 SDK 里。例外是[移动端](/docs/zh-cn/guides/mobile/):在那里,围绕导出组装应用+ 编辑器和 SDK 里。例外是[移动端](/docs/zh-cn/publishing/android-ios/):在那里,围绕导出组装应用也由这个 CLI 完成。</Aside>## 参见-- [Android 与 iOS](/docs/zh-cn/guides/mobile/) —— 原生应用:前置条件、如何组装,以及只在真机上才咬人的那些事。-- [微信小游戏](/docs/zh-cn/guides/wechat/) —— 分包布局与平台差异。-- [资源](/docs/zh-cn/guides/assets/) —— cook 步骤如何打包与内容寻址资产。-- [性能剖析与诊断](/docs/zh-cn/guides/profiling/) —— 发布前检查帧时间与 draw call。+- [Android 与 iOS](/docs/zh-cn/publishing/android-ios/) —— 原生应用:前置条件、如何组装,以及只在真机上才咬人的那些事。+- [微信小游戏](/docs/zh-cn/publishing/wechat/) —— 分包布局与平台差异。+- [资源](/docs/zh-cn/assets/overview/) —— cook 步骤如何打包与内容寻址资产。+- [性能剖析与诊断](/docs/zh-cn/performance/profiling/) —— 发布前检查帧时间与 draw call。diff --git a/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdxindex acb746569..4729b23c7 100644--- a/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx+++ b/docs/astro/src/content/docs/zh-cn/publishing/wechat.mdx@@ -47,7 +47,7 @@ node build-tools/cli.js build -t videodec-wechat # 视频(MPEG-1 wasm 解码`game.json` / `project.config.json`(微信配置)、`asset-manifest.json`、以`scenes/<名字>.json` 存放的场景,以及 `wasm/` 目录 —— 引擎加上场景实际需要的侧模块。构建里的每个场景都是 `SceneManager.switchTo` 的切换目标——非启动场景在-首次切换时才加载(见[场景](/docs/zh-cn/guides/scene/))。+首次切换时才加载(见[场景](/docs/zh-cn/world/scenes/))。<Aside type="caution">不要手改 `game.js` 或移动 `wasm/` 下的文件——引导序列按暂存时的确切文件名@@ -84,7 +84,7 @@ node build-tools/cli.js build -t videodec-wechat # 视频(MPEG-1 wasm 解码## 最佳实践- **保持在 4 MB 主包限制以内**:把按需内容移到 `subpackages/<name>/`——见- [资源](/docs/zh-cn/guides/assets/)。导出会设置 `bigPackageSizeSupport`,超限的包+ [资源](/docs/zh-cn/assets/overview/)。导出会设置 `bigPackageSizeSupport`,超限的包在开发者工具里仍可*预览*——但上传照样卡限制。- **压缩纹理** —— 见上文;这是包体最大的一笔节省。- **在微信开发者工具里测试**,而不只是浏览器——文件系统、存储与套接字后端都与 Web 不同。@@ -92,7 +92,7 @@ node build-tools/cli.js build -t videodec-wechat # 视频(MPEG-1 wasm 解码## 参见-- [资源](/docs/zh-cn/guides/assets/) —— 可寻址分组与 cook 映射到分包。-- [构建与导出](/docs/zh-cn/guides/build-export/) —— Package Project 对话框。-- [视频](/docs/zh-cn/guides/video/) —— 为微信随包发布的 MPEG-1 wasm 解码路径。-- [联网](/docs/zh-cn/guides/networking/) —— 那里套接字用 `wx.connectSocket`。+- [资源](/docs/zh-cn/assets/overview/) —— 可寻址分组与 cook 映射到分包。+- [构建与导出](/docs/zh-cn/publishing/overview/) —— Package Project 对话框。+- [视频](/docs/zh-cn/graphics/video/) —— 为微信随包发布的 MPEG-1 wasm 解码路径。+- [联网](/docs/zh-cn/scripting/networking/) —— 那里套接字用 `wx.connectSocket`。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx b/docs/astro/src/content/docs/zh-cn/scripting/events.mdxindex 3ca97bc1f..635bbe2ad 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/events.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/events.mdx@@ -15,7 +15,7 @@ click ─▶ ui.setPage(badge, on) 目标「Card」```连线**刻意不是**可视化编程语言。一行里没有分支、没有表达式;真的需要逻辑时,这行会指向一个-把控制权交给[状态机](/docs/zh-cn/guides/ai/)的动作——Estella 已经有图编辑器了。+把控制权交给[状态机](/docs/zh-cn/gameplay/ai/)的动作——Estella 已经有图编辑器了。## 检视器里的一根线@@ -38,7 +38,7 @@ click ─▶ ui.setPage(badge, on) 目标「Card」## 数据本身-一根线就是 `EventBinding` 组件,因此它会序列化进场景、随[预制体](/docs/zh-cn/guides/prefab/)+一根线就是 `EventBinding` 组件,因此它会序列化进场景、随[预制体](/docs/zh-cn/world/prefabs/)一起走,和任何组件一样——不新增资产类型:```typescript@@ -86,12 +86,12 @@ world.insert(button, EventBinding, {| 动作 | 作用 ||---|---|-| `ui.setPage` | 把 [UI 控制器](/docs/zh-cn/guides/ui-controllers/)切到某一页。 |+| `ui.setPage` | 把 [UI 控制器](/docs/zh-cn/ui/controllers/)切到某一页。 || `ui.setVisible` | 显示/隐藏一棵 UI 子树(`UINode.display`)。 || `property.set` | 写任意组件字段,按 `Component.dot.path` 寻址。 || `fsm.fire` | 向目标的状态机发一个触发器。 || `blackboard.set` | 设置一个黑板变量。 |-| `timeline.play` · `timeline.pause` | 驱动目标上的[时间轴](/docs/zh-cn/guides/timeline/)。 |+| `timeline.play` · `timeline.pause` | 驱动目标上的[时间轴](/docs/zh-cn/animation/timeline/)。 || `spriteAnim.play` · `spriteAnim.restart` · `spriteAnim.stop` | 驱动精灵序列帧。 |### 你自己的动作@@ -140,8 +140,8 @@ shown ─▶ fsm.fire(enter) 挂在 "MissionPanel" → Hidden ──enter在没有人监听这两个事件之前,这份「盯着」不花任何代价;有人监听、但这一帧 UI 没动过时,同样不花。-[物理](/docs/zh-cn/guides/physics/)接触也走同一条通道(`PhysicsEventType`),所以-[触发区](/docs/zh-cn/guides/markers/)的接线方式和按钮一模一样——双方都会收到事件,各自拿到对方:+[物理](/docs/zh-cn/gameplay/physics/)接触也走同一条通道(`PhysicsEventType`),所以+[触发区](/docs/zh-cn/gameplay/markers/)的接线方式和按钮一模一样——双方都会收到事件,各自拿到对方:`collision_enter` · `collision_exit` · `collision_hit` · `trigger_enter` · `trigger_exit`@@ -156,7 +156,7 @@ app.getResource(EntityEvents).emit(chest, 'looted', { gold: 12 });## 当一根线需要逻辑时一行只跑一个动作,没有"如果",也没有先后序列。这是**刻意**设的天花板,而 `fsm.fire` 就是-突破口——点击发出一个触发器,实体的[状态机](/docs/zh-cn/guides/ai/)来决定它意味着什么:+突破口——点击发出一个触发器,实体的[状态机](/docs/zh-cn/gameplay/ai/)来决定它意味着什么:```click ─▶ fsm.fire(start) 目标「Hint」 → Idle ──start──▶ Runningdiff --git a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx b/docs/astro/src/content/docs/zh-cn/scripting/input.mdxindex 40d4fde59..683af93fc 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/input.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/input.mdx@@ -281,5 +281,5 @@ key-up 边沿,处理器看到的它仍是按住的,与 DOM `event.shiftKey` 的## 参见-- [相机](/docs/zh-cn/guides/camera/) —— 对任意屏幕点用 `screenToWorld`。-- [UI](/docs/zh-cn/guides/ui/) —— UI 在游戏世界之上消费指针输入。+- [相机](/docs/zh-cn/graphics/camera/) —— 对任意屏幕点用 `screenToWorld`。+- [UI](/docs/zh-cn/ui/overview/) —— UI 在游戏世界之上消费指针输入。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx b/docs/astro/src/content/docs/zh-cn/scripting/math.mdxindex 0bb397409..78599e456 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/math.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/math.mdx@@ -113,4 +113,4 @@ const delta = normalizeAngle(targetAngle - facing);- [变换、单位与坐标系](/docs/zh-cn/core-concepts/transforms/)——这些数字的含义:世界单位 = 设计像素、物理米制、Y 轴向上,以及用四元数旋转实体。-- [物理](/docs/zh-cn/guides/physics/)——这些辅助函数最终喂给的米制单位面。+- [物理](/docs/zh-cn/gameplay/physics/)——这些辅助函数最终喂给的米制单位面。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdxindex 86c776e6a..435d6e590 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/networking.mdx@@ -194,5 +194,5 @@ clientNet.client.sendInput({ move: { x: 1, y: 0 } }); // pawn 立刻动## 参见-- [微信小游戏](/docs/zh-cn/guides/wechat/) —— 那里套接字用 `wx.connectSocket`。-- [存档与读档](/docs/zh-cn/guides/save/) —— 在会话之间本地持久化状态。+- [微信小游戏](/docs/zh-cn/publishing/wechat/) —— 那里套接字用 `wx.connectSocket`。+- [存档与读档](/docs/zh-cn/scripting/save/) —— 在会话之间本地持久化状态。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdxindex 6b9f8dc6f..b2bba4047 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/overview.mdx@@ -187,7 +187,7 @@ export const Enemy = defineBehavior('Enemy', {| `ctx.self` | `S` | 该行为自己的 `state`。**随意改——修改会持久化。** || `ctx.entity` | `Entity` | 该实例所挂的实体。 || `ctx.time` | `TimeData` | 帧计时:`delta`、`elapsed`、`frameCount`、`fixedDelta`。 |-| `ctx.input` | `InputState` | 键盘 / 鼠标 / 触摸 / 手柄(见 [输入](/docs/zh-cn/guides/input/))。 |+| `ctx.input` | `InputState` | 键盘 / 鼠标 / 触摸 / 手柄(见 [输入](/docs/zh-cn/scripting/input/))。 || `ctx.commands` | `Commands` | 延迟的 spawn / despawn / insert——update 中调用安全。 || `ctx.world` | `World` | 完整世界访问,用于跨实体读写。 || `ctx.get(Comp)` | `ComponentData` | 读取**本**实体上的另一个组件。 |@@ -305,7 +305,7 @@ world.spawn()天然是*每实体*的(巡逻、抛射物、拾取物)时,用 `defineBehavior`;当你要一次处理整个查询、或在实体间协调时,用一个普通[系统](/docs/zh-cn/core-concepts/systems/)。-钩子签名——`entity`、`world`、`commands`,外加 `self`——也和[游戏 AI](/docs/zh-cn/guides/ai/) 层+钩子签名——`entity`、`world`、`commands`,外加 `self`——也和[游戏 AI](/docs/zh-cn/gameplay/ai/) 层的动作与行为树叶子是同一套编程模型,所以在 behavior 和 AI 动作之间搬逻辑很顺手。## 热重载@@ -326,4 +326,4 @@ world.spawn()- [系统](/docs/zh-cn/core-concepts/systems/) —— 完整的查询词汇、过滤器与调度。- [ECS 架构](/docs/zh-cn/core-concepts/ecs/) —— 实体、组件,以及系统如何遍历它们。-- [输入](/docs/zh-cn/guides/input/) —— 在系统里读取键盘、指针与手势。+- [输入](/docs/zh-cn/scripting/input/) —— 在系统里读取键盘、指针与手势。diff --git a/docs/astro/src/content/docs/zh-cn/scripting/save.mdx b/docs/astro/src/content/docs/zh-cn/scripting/save.mdxindex 450ae3797..b449cab3b 100644--- a/docs/astro/src/content/docs/zh-cn/scripting/save.mdx+++ b/docs/astro/src/content/docs/zh-cn/scripting/save.mdx@@ -114,5 +114,5 @@ Estella 0.41 之前的构建把同一个文件放在缓存目录里。如果你## 参见-- [场景](/docs/zh-cn/guides/scene/) —— 加载与切换存档所指向的场景。-- [资源](/docs/zh-cn/guides/assets/) —— 为什么大块数据应放资源而非存档槽。+- [场景](/docs/zh-cn/world/scenes/) —— 加载与切换存档所指向的场景。+- [资源](/docs/zh-cn/assets/overview/) —— 为什么大块数据应放资源而非存档槽。diff --git a/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdxindex 24dcad8fe..646344667 100644--- a/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/controllers.mdx@@ -11,8 +11,8 @@ import { Aside } from '@astrojs/starlight/components';或任何可反射的字段,可瞬切也可补间。一个控制器驱动多个元素,而整套东西就是普通的 ECS 数据(两个组件 `UIController` 和-`UIGear`),会随 [预制体](/docs/zh-cn/guides/prefab/) 一起走、序列化进场景。它是-[按钮](/docs/zh-cn/guides/ui-components/#button) 那种"单控件状态"的共享化、多页化推广——+`UIGear`),会随 [预制体](/docs/zh-cn/world/prefabs/) 一起走、序列化进场景。它是+[按钮](/docs/zh-cn/ui/widgets/#button) 那种"单控件状态"的共享化、多页化推广——页签、单选组、按钮状态、面板显隐,统一用一套机制。## 控制器@@ -67,7 +67,7 @@ world.insert(card, UIGear, {````gearBinding(controller, component, property, pages, tween?)` 寻址字段的方式和-[时间轴](/docs/zh-cn/guides/timeline/) 属性轨道一致——组件名 + 点路径 `property`+[时间轴](/docs/zh-cn/animation/timeline/) 属性轨道一致——组件名 + 点路径 `property`(`"color"`、`"color.a"`、`"scale.x"`)。`pages` 是按页名索引的 **稀疏** 映射:某页没有条目就不动这个字段。@@ -125,7 +125,7 @@ world.insert(btn, UIGear, {- **添加控制器**(指针按钮预设一键添加带四页的 `$interaction`),页以 **chip** 管理:单击预览、双击重命名、拖拽排序、悬停 × 删除——重命名会级联进所有解析到该控制器的绑定,删页会清掉该页已录的值。-- 点击某个控制器使其 **活动**。在 [细节](/docs/zh-cn/guides/editor/) 面板里,每个字段旁便出现一个小的+- 点击某个控制器使其 **活动**。在 [细节](/docs/zh-cn/editor/overview/) 面板里,每个字段旁便出现一个小的**gear 点**——点它把该字段绑定到活动控制器(以当前页 + 字段当前值作种子)。再点已绑定的点,打开设置:切页 **过渡**(时长 + 缓动,0 = 瞬切)与解绑。- 打开 **录制**:此时每次编辑都写入控制器的 **当前页**——还没绑定的字段会当场自动@@ -140,7 +140,7 @@ world.insert(btn, UIGear, {两座桥从 *数据* 或 *逻辑* 切页,各自复用一套已有系统。-**从信号** —— `bindControllerPage` 用一个 [响应式信号](/docs/zh-cn/guides/ui/) 驱动控制器的页,+**从信号** —— `bindControllerPage` 用一个 [响应式信号](/docs/zh-cn/ui/overview/) 驱动控制器的页,这是数据驱动页签的声明式路径:```typescript@@ -152,7 +152,7 @@ bindControllerPage(world, root, 'tab', activeTab); // 控制器跟随信号activeTab.set('shop'); // 翻页,所有被绑定的元素重排```-**从按钮,且不写代码** —— 在按钮上挂一根[事件连线](/docs/zh-cn/guides/events/),点击时执行+**从按钮,且不写代码** —— 在按钮上挂一根[事件连线](/docs/zh-cn/scripting/events/),点击时执行`ui.setPage`,目标指向持有该控制器的实体:```json@@ -160,7 +160,7 @@ activeTab.set('shop'); // 翻页,所有被绑定的元素重排```**从状态机** —— `ui.setPage` 动作让数据驱动的-[FSM / 行为树](/docs/zh-cn/guides/ai/)(`.esfsm` / `.esbt`)无需写码就切页。参数是 `"controller:page"`:+[FSM / 行为树](/docs/zh-cn/gameplay/ai/)(`.esfsm` / `.esbt`)无需写码就切页。参数是 `"controller:page"`:```json{ "onEnter": { "name": "ui.setPage", "arg": "hud:alert" } }@@ -178,8 +178,8 @@ activeTab.set('shop'); // 翻页,所有被绑定的元素重排## 参见-- [UI](/docs/zh-cn/guides/ui/) —— 绑定所驱动的 flexbox 组件模型。-- [UI 控件](/docs/zh-cn/guides/ui-components/) —— 控件工厂。-- [时间轴](/docs/zh-cn/guides/timeline/) —— 关键帧过渡;绑定用的是同一套字段寻址。-- [游戏 AI](/docs/zh-cn/guides/ai/) —— 能调用 `ui.setPage` 的 `.esfsm` / `.esbt`。-- [事件绑定](/docs/zh-cn/guides/events/) —— 把点击直接接到 `ui.setPage`,不写代码。+- [UI](/docs/zh-cn/ui/overview/) —— 绑定所驱动的 flexbox 组件模型。+- [UI 控件](/docs/zh-cn/ui/widgets/) —— 控件工厂。+- [时间轴](/docs/zh-cn/animation/timeline/) —— 关键帧过渡;绑定用的是同一套字段寻址。+- [游戏 AI](/docs/zh-cn/gameplay/ai/) —— 能调用 `ui.setPage` 的 `.esfsm` / `.esbt`。+- [事件绑定](/docs/zh-cn/scripting/events/) —— 把点击直接接到 `ui.setPage`,不写代码。diff --git a/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx b/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdxindex 3a3dca862..3de773891 100644--- a/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/data-binding.mdx@@ -146,7 +146,7 @@ addStartupSystem(buildVolumeRow);## 绑定控制器页`bindControllerPage(world, entity, controller, source)` 用一个-`ReadonlySignal<string>` 驱动 [UI 控制器](/docs/zh-cn/guides/ui-controllers/)+`ReadonlySignal<string>` 驱动 [UI 控制器](/docs/zh-cn/ui/controllers/)的当前页——数据驱动页签栏的声明式路径。设置信号,页切换,所有 geared 元素随之重排:@@ -163,7 +163,7 @@ activeTab.set('shop');## 绑定与列表-[ListView](/docs/zh-cn/guides/ui-lists/) 本身*已经*是数据驱动的——它渲染自+[ListView](/docs/zh-cn/ui/lists/) 本身*已经*是数据驱动的——它渲染自`DataSource`(例如 `ArrayDataSource`),带细粒度的插入/删除/更新通知,这是虚拟化所必需、而单个值信号表达不了的。所以:**集合放进 `DataSource`,标量 UI状态放进信号**,两者组合使用——条目模板的 `bind` 回调可以读信号,而一个信号@@ -176,9 +176,9 @@ activeTab.set('shop');| 状态形状 | 用 | 原因 ||---|---|---|| 一个**值**——分数、血量、名字、滑杆位置 | `signal` + `bind` / `bindWidgetValue` | 变化时推送,无轮询;值控件可双向。 |-| 有限集合中的一个**命名状态**——页签、开/关、按钮状态 | [控制器 + gear](/docs/zh-cn/guides/ui-controllers/) | 一次翻页带动多元素重排;可在编辑器创作;支持补间。用 `bindControllerPage` 从数据接入。 |-| 一个**集合**——背包行、排行榜 | `DataSource` + [ListView](/docs/zh-cn/guides/ui-lists/) | 细粒度变更通知驱动虚拟化。 |-| 由模拟派生的**逐帧**值——冷却扫过、跟随玩家的标记 | 普通[系统](/docs/zh-cn/guides/scripting/)写组件 | 值本来每帧都变;query 是天然的读者。 |+| 有限集合中的一个**命名状态**——页签、开/关、按钮状态 | [控制器 + gear](/docs/zh-cn/ui/controllers/) | 一次翻页带动多元素重排;可在编辑器创作;支持补间。用 `bindControllerPage` 从数据接入。 |+| 一个**集合**——背包行、排行榜 | `DataSource` + [ListView](/docs/zh-cn/ui/lists/) | 细粒度变更通知驱动虚拟化。 |+| 由模拟派生的**逐帧**值——冷却扫过、跟随玩家的标记 | 普通[系统](/docs/zh-cn/scripting/overview/)写组件 | 值本来每帧都变;query 是天然的读者。 |经验法则:如果你正要写一个只在变量变化时把它拷进组件的系统,那就是一条`bind`。如果你正要在模式切换时手动给五个实体设颜色,那就是一个控制器。@@ -196,8 +196,8 @@ activeTab.set('shop');## 参见-- [UI](/docs/zh-cn/guides/ui/) —— 绑定所写入的组件模型。-- [UI 控件](/docs/zh-cn/guides/ui-components/) —— 值控件(`createSlider`、`createToggle`、`createDropdown`)。-- [UI 控制器](/docs/zh-cn/guides/ui-controllers/) —— 命名的页状态 + gear;`bindControllerPage` 把信号接进去。-- [UI 列表](/docs/zh-cn/guides/ui-lists/) —— `DataSource` 驱动的虚拟化列表。-- [主题](/docs/zh-cn/guides/ui-theme/) —— 设计令牌与实时换肤。+- [UI](/docs/zh-cn/ui/overview/) —— 绑定所写入的组件模型。+- [UI 控件](/docs/zh-cn/ui/widgets/) —— 值控件(`createSlider`、`createToggle`、`createDropdown`)。+- [UI 控制器](/docs/zh-cn/ui/controllers/) —— 命名的页状态 + gear;`bindControllerPage` 把信号接进去。+- [UI 列表](/docs/zh-cn/ui/lists/) —— `DataSource` 驱动的虚拟化列表。+- [主题](/docs/zh-cn/ui/theming/) —— 设计令牌与实时换肤。diff --git a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdxindex 8d4b03b5a..2c383d5d6 100644--- a/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/interaction.mdx@@ -101,7 +101,7 @@ makeWidgetInteractable(world, myWidgetRoot, { tabIndex: 2 });`Interactable.enabled = false` 起步)、`focusable`(默认 `true`)、`tabIndex`(默认 `0` = 文档顺序)。它刻意*不*插入 `UIInteraction`——那是 transient 状态。悬停/按下的**视觉**状态请把字段绑到内置交互控制器的页——见-[UI 控制器](/docs/zh-cn/guides/ui-controllers/)。+[UI 控制器](/docs/zh-cn/ui/controllers/)。## 拖放@@ -183,7 +183,7 @@ const focusDebug = defineSystem([Res(FocusManager)], (focus) => {<Aside type="note">手柄导航未内置于焦点系统——焦点环由 `Tab` / `Enter` / `Space` / `Escape` 和- 方向键驱动。手柄菜单请用[输入映射](/docs/zh-cn/guides/input/)自行驱动选择,+ 方向键驱动。手柄菜单请用[输入映射](/docs/zh-cn/scripting/input/)自行驱动选择,直接调用控件状态。</Aside>@@ -252,8 +252,8 @@ const tooltip = defineSystem([GetWorld(), Res(UICameraInfo)], (world, camera) =>## 另请参阅-- [UI](/docs/zh-cn/guides/ui/) —— 组件模型总览。-- [UI 组件](/docs/zh-cn/guides/ui-components/) —— 事件已接好线的控件工厂。-- [UI 控制器](/docs/zh-cn/guides/ui-controllers/) —— 由交互控制器驱动的悬停/按下**视觉**状态。-- [UI 数据绑定](/docs/zh-cn/guides/ui-binding/) —— 基于 `change` 事件的控件值双向绑定。-- [输入](/docs/zh-cn/guides/input/) —— UI 层之下的 `Input` 资源、输入映射与手势。+- [UI](/docs/zh-cn/ui/overview/) —— 组件模型总览。+- [UI 组件](/docs/zh-cn/ui/widgets/) —— 事件已接好线的控件工厂。+- [UI 控制器](/docs/zh-cn/ui/controllers/) —— 由交互控制器驱动的悬停/按下**视觉**状态。+- [UI 数据绑定](/docs/zh-cn/ui/data-binding/) —— 基于 `change` 事件的控件值双向绑定。+- [输入](/docs/zh-cn/scripting/input/) —— UI 层之下的 `Input` 资源、输入映射与手势。diff --git a/docs/astro/src/content/docs/zh-cn/ui/layout.mdx b/docs/astro/src/content/docs/zh-cn/ui/layout.mdxindex 21d5fb6d5..d9b7b6cd7 100644--- a/docs/astro/src/content/docs/zh-cn/ui/layout.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/layout.mdx@@ -7,7 +7,7 @@ import { Aside } from '@astrojs/starlight/components';UI 几何是一套 CSS 盒模型,由 C++ 内核中的单趟 flexbox 引擎(Yoga)每帧针对相机的 UI框求解。本页是深入参考:单位、`Dimension` 类型、`UINode` 与 `FlexContainer` 的全部字段、-绝对定位、锚点预设和配方。组件模型总览请从 [UI](/docs/zh-cn/guides/ui/) 开始。+绝对定位、锚点预设和配方。组件模型总览请从 [UI](/docs/zh-cn/ui/overview/) 开始。## 单位:设计像素@@ -16,7 +16,7 @@ UI 布局里的每个 `px` 都是**设计像素**——项目设计分辨率(Pro**1 世界单位 = 1 设计像素**,一个 `px(320)` 的面板在任何设备上都是 320 设计像素宽;画布缩放模式决定这个设计框如何适配真实屏幕(letterbox、expand、match)。编辑器的自由缩放视图针对同一个固定设计框排布 UI,所以缩放视口永远不会让界面重排。见-[屏幕与分辨率](/docs/zh-cn/core-concepts/screen/)和[相机](/docs/zh-cn/guides/camera/)。+[屏幕与分辨率](/docs/zh-cn/core-concepts/screen/)和[相机](/docs/zh-cn/graphics/camera/)。## 维度:`px`、`percent`、`auto`@@ -256,7 +256,7 @@ const scrim = spawnUIEntity({### 居中一个面板两种等价工具:给**父项**一个居中的 `FlexContainer`(`justifyContent: Center,-alignItems: Center`——[UI](/docs/zh-cn/guides/ui/) 快速上手的模式),或把面板本身设为+alignItems: Center`——[UI](/docs/zh-cn/ui/overview/) 快速上手的模式),或把面板本身设为`Absolute` 且内偏移**和**外边距全 `auto`([Center 锚点](#用-auto-居中)——不需要父容器)。### HUD 角标@@ -344,8 +344,8 @@ world.insert(e, UIVisual, buildUIVisual({ color: { r: 0.2, g: 0.2, b: 0.25, a: 1## 另请参阅-- [UI](/docs/zh-cn/guides/ui/)——组件模型总览与快速上手。-- [UI 文本](/docs/zh-cn/guides/ui-text/)——`Text` 如何在盒内测量与对齐。-- [UI 交互](/docs/zh-cn/guides/ui-interaction/)——对排布好的盒子做命中测试。-- [UI 组件](/docs/zh-cn/guides/ui-components/)——建立在这些原语上的控件(含移动端安全区)。-- [相机](/docs/zh-cn/guides/camera/)——相机、画布缩放模式与 UI 框。+- [UI](/docs/zh-cn/ui/overview/)——组件模型总览与快速上手。+- [UI 文本](/docs/zh-cn/ui/text/)——`Text` 如何在盒内测量与对齐。+- [UI 交互](/docs/zh-cn/ui/interaction/)——对排布好的盒子做命中测试。+- [UI 组件](/docs/zh-cn/ui/widgets/)——建立在这些原语上的控件(含移动端安全区)。+- [相机](/docs/zh-cn/graphics/camera/)——相机、画布缩放模式与 UI 框。diff --git a/docs/astro/src/content/docs/zh-cn/ui/lists.mdx b/docs/astro/src/content/docs/zh-cn/ui/lists.mdxindex 21729144e..794063351 100644--- a/docs/astro/src/content/docs/zh-cn/ui/lists.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/lists.mdx@@ -5,7 +5,7 @@ description: 用 createListView 构建虚拟化的数据驱动列表与网格—import { Aside } from '@astrojs/starlight/components';-在 Estella 里,长的可滚动内容由 [UI](/docs/zh-cn/guides/ui/) 组件模型之上的两个工厂构建:+在 Estella 里,长的可滚动内容由 [UI](/docs/zh-cn/ui/overview/) 组件模型之上的两个工厂构建:- **`createListView`** —— **虚拟化**的数据驱动列表或网格。任何时刻只挂载视口附近的条目,所以 10 000 行的背包、排行榜或聊天记录和 10 行的一样便宜。@@ -443,9 +443,9 @@ addStartupSystem(buildChat);## 另请参阅-- [UI](/docs/zh-cn/guides/ui/) —— 这些工厂所依托的组件模型。-- [UI 控件](/docs/zh-cn/guides/ui-components/) —— 其余控件工厂(Button、Dialog、文本输入……)。-- [UI 布局](/docs/zh-cn/guides/ui-layout/) —— `UINode` 盒模型、flexbox 与尺寸。-- [UI 数据绑定](/docs/zh-cn/guides/ui-binding/) —— 信号与控件双向绑定。-- [UI 交互](/docs/zh-cn/guides/ui-interaction/) —— 指针事件、焦点、拖放。-- [UI 主题](/docs/zh-cn/guides/ui-theme/) —— 滚动条与默认色所取用的 token 角色。+- [UI](/docs/zh-cn/ui/overview/) —— 这些工厂所依托的组件模型。+- [UI 控件](/docs/zh-cn/ui/widgets/) —— 其余控件工厂(Button、Dialog、文本输入……)。+- [UI 布局](/docs/zh-cn/ui/layout/) —— `UINode` 盒模型、flexbox 与尺寸。+- [UI 数据绑定](/docs/zh-cn/ui/data-binding/) —— 信号与控件双向绑定。+- [UI 交互](/docs/zh-cn/ui/interaction/) —— 指针事件、焦点、拖放。+- [UI 主题](/docs/zh-cn/ui/theming/) —— 滚动条与默认色所取用的 token 角色。diff --git a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx b/docs/astro/src/content/docs/zh-cn/ui/overview.mdxindex 2a0983cfa..470021dcd 100644--- a/docs/astro/src/content/docs/zh-cn/ui/overview.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/overview.mdx@@ -15,14 +15,14 @@ flexbox,用 `px` / `percent` / `auto` 加 `Absolute` 内偏移(inset)来定尺| 组件 | 职责 | 指南 ||---|---|---|-| `UINode` | 布局盒;持有逐项的 flex 字段(尺寸、grow/shrink、margin、inset)。 | [UI 布局](/docs/zh-cn/guides/ui-layout/) |-| `FlexContainer` | 用 flexbox 排布一个节点的子项(方向、justify、align、gap、padding)。 | [UI 布局](/docs/zh-cn/guides/ui-layout/) |-| `Text` | 经动态字形图集渲染文本(内容、字体、颜色、对齐、描边、阴影、富文本)。 | [UI 文本](/docs/zh-cn/guides/ui-text/) |+| `UINode` | 布局盒;持有逐项的 flex 字段(尺寸、grow/shrink、margin、inset)。 | [UI 布局](/docs/zh-cn/ui/layout/) |+| `FlexContainer` | 用 flexbox 排布一个节点的子项(方向、justify、align、gap、padding)。 | [UI 布局](/docs/zh-cn/ui/layout/) |+| `Text` | 经动态字形图集渲染文本(内容、字体、颜色、对齐、描边、阴影、富文本)。 | [UI 文本](/docs/zh-cn/ui/text/) || `UIVisual` | 填充——纯色、纹理、九宫格、平铺或填充。 | 见下文 || `UIMask` | 裁剪它的子项。 | 见下文 || `UIScroll` | 让被裁剪的节点成为滚动视口:滚轮与拖拽移动它的内容。 | 见下文 |-| `Interactable` | 标记节点可命中,从而能被悬停/点击。 | [UI 交互](/docs/zh-cn/guides/ui-interaction/) |-| `UIInteraction` | 引擎每帧写入的指针状态(对你的逻辑只读)。 | [UI 交互](/docs/zh-cn/guides/ui-interaction/) |+| `Interactable` | 标记节点可命中,从而能被悬停/点击。 | [UI 交互](/docs/zh-cn/ui/interaction/) |+| `UIInteraction` | 引擎每帧写入的指针状态(对你的逻辑只读)。 | [UI 交互](/docs/zh-cn/ui/interaction/) |## 快速上手:暂停菜单@@ -72,29 +72,29 @@ addStartupSystem(buildPauseMenu);`spawnUIEntity({ world, parent?, node?, visual?, text? })` 返回实体;传 `parent` 来嵌套。尺寸用维度助手 `px`、`percent`、`auto`——单位都是**设计像素**(见-[UI 布局](/docs/zh-cn/guides/ui-layout/#单位设计像素))。其余控件工厂用法相同:+[UI 布局](/docs/zh-cn/ui/layout/#单位设计像素))。其余控件工厂用法相同:`createToggle`、`createSlider`、`createProgress`、`createDialog`、`createDropdown`——见-[UI 组件](/docs/zh-cn/guides/ui-components/)。+[UI 组件](/docs/zh-cn/ui/widgets/)。## 各部分如何协作每一层都建立在前一层之上:1. **布局**——`UINode` 盒子由 flexbox 引擎求解;`FlexContainer` 排布子项,- `Absolute` 内偏移放置悬浮层。→ [UI 布局](/docs/zh-cn/guides/ui-layout/)+ `Absolute` 内偏移放置悬浮层。→ [UI 布局](/docs/zh-cn/ui/layout/)2. **视觉与文本**——`UIVisual` 填充盒子,`UIMask` 裁剪,`Text` 绘制锐利字形。- → [UI 文本](/docs/zh-cn/guides/ui-text/)+ → [UI 文本](/docs/zh-cn/ui/text/)3. **交互**——`Interactable` 让盒子可命中;引擎把指针状态写入 `UIInteraction`并发出冒泡的 `UIEvents`;拖放和键盘焦点建立在其上。- → [UI 交互](/docs/zh-cn/guides/ui-interaction/)+ → [UI 交互](/docs/zh-cn/ui/interaction/)4. **控件**——工厂(`createButton`、`createSlider`……)把前三层组合成现成的控件;`createListView` 提供虚拟化列表。- → [UI 组件](/docs/zh-cn/guides/ui-components/)、[UI 列表](/docs/zh-cn/guides/ui-lists/)+ → [UI 组件](/docs/zh-cn/ui/widgets/)、[UI 列表](/docs/zh-cn/ui/lists/)5. **控制器**——每个 UI 根一份命名"页面"状态加逐页字段绑定(标签页、按钮状态、- 显示/隐藏)——零代码。→ [UI 控制器](/docs/zh-cn/guides/ui-controllers/)+ 显示/隐藏)——零代码。→ [UI 控制器](/docs/zh-cn/ui/controllers/)6. **主题与绑定**——设计 token 给所有控件换肤(可实时切换),响应式 signal 让 UI与游戏状态保持同步。- → [UI 主题](/docs/zh-cn/guides/ui-theme/)、[UI 绑定](/docs/zh-cn/guides/ui-binding/)+ → [UI 主题](/docs/zh-cn/ui/theming/)、[UI 绑定](/docs/zh-cn/ui/data-binding/)### `UIVisual` 与 `UIMask`@@ -121,7 +121,7 @@ addStartupSystem(buildPauseMenu);`sliceBorder` 就是那四个数字:从每条边往内多远是"不该拉伸"的区带。四角在任何尺寸下都保留自己的精确像素,于是同一张 100×112 的纹理既能做小提示框,也能做通栏横幅。这个边框属于**图像**本身,而不属于用到它的实体,所以它是纹理的导入设置——设一次,引用该纹理的每个 `NineSlice` 都按同样-方式切片。参见资产检视器中的[拖拽边框](/zh-cn/docs/guides/editor/#内容浏览器)。+方式切片。参见资产检视器中的[拖拽边框](/zh-cn/docs/editor/overview/#内容浏览器)。#### 遮罩是用来做什么的@@ -210,7 +210,7 @@ world.insert(viewport, UIScroll, { vertical: true }); // content 缺省取第- **编辑器**——*Create… → UI* 放入控件预制件(Button、Toggle、Slider、Dialog……);拖拽嵌套,在 Details 里编辑每个字段,用逐轴锚点选择器摆放,并按项目的设计分辨率- 和设备预设预览。见[编辑器](/docs/zh-cn/guides/editor/)。+ 和设备预设预览。见[编辑器](/docs/zh-cn/editor/overview/)。- **代码**——`spawnUIEntity` + 控件工厂,如上例在启动系统里构建。编辑器能写的,代码都能写。@@ -218,14 +218,14 @@ world.insert(viewport, UIScroll, { vertical: true }); // content 缺省取第| 你想…… | 打开 ||---|---|-| 定尺寸摆盒子——`px`/`percent`/`auto`、flexbox、绝对内偏移、锚点 | [UI 布局](/docs/zh-cn/guides/ui-layout/) |-| 绘制文本——字体、SDF/位图锐利度、换行、富文本 | [UI 文本](/docs/zh-cn/guides/ui-text/) |-| 响应指针与键盘——点击、`UIEvents`、拖放、焦点 | [UI 交互](/docs/zh-cn/guides/ui-interaction/) |-| 使用现成控件——按钮、开关、滑条、对话框、下拉、输入框 | [UI 组件](/docs/zh-cn/guides/ui-components/) |-| 展示滚动数据——虚拟化列表与网格 | [UI 列表](/docs/zh-cn/guides/ui-lists/) |-| 全局换肤——设计 token、项目主题、实时切换 | [UI 主题](/docs/zh-cn/guides/ui-theme/) |-| 让 UI 与游戏状态同步——signal、`bind`、控件双向绑定 | [UI 绑定](/docs/zh-cn/guides/ui-binding/) |-| 跨元素共享状态——标签页、单选组、页面驱动的视觉 | [UI 控制器](/docs/zh-cn/guides/ui-controllers/) |+| 定尺寸摆盒子——`px`/`percent`/`auto`、flexbox、绝对内偏移、锚点 | [UI 布局](/docs/zh-cn/ui/layout/) |+| 绘制文本——字体、SDF/位图锐利度、换行、富文本 | [UI 文本](/docs/zh-cn/ui/text/) |+| 响应指针与键盘——点击、`UIEvents`、拖放、焦点 | [UI 交互](/docs/zh-cn/ui/interaction/) |+| 使用现成控件——按钮、开关、滑条、对话框、下拉、输入框 | [UI 组件](/docs/zh-cn/ui/widgets/) |+| 展示滚动数据——虚拟化列表与网格 | [UI 列表](/docs/zh-cn/ui/lists/) |+| 全局换肤——设计 token、项目主题、实时切换 | [UI 主题](/docs/zh-cn/ui/theming/) |+| 让 UI 与游戏状态同步——signal、`bind`、控件双向绑定 | [UI 绑定](/docs/zh-cn/ui/data-binding/) |+| 跨元素共享状态——标签页、单选组、页面驱动的视觉 | [UI 控制器](/docs/zh-cn/ui/controllers/) |## 最佳实践@@ -239,7 +239,7 @@ world.insert(viewport, UIScroll, { vertical: true }); // content 缺省取第## 另请参阅-- [输入](/docs/zh-cn/guides/input/)——UI 层之下的原始键盘/鼠标/触摸。-- [本地化](/docs/zh-cn/guides/localization/)——把 `Text.content` 绑定到翻译键。-- [动画](/docs/zh-cn/guides/animation/)——补间 UI 颜色/位置增加动感。-- [编辑器](/docs/zh-cn/guides/editor/)——可视化编排、预制件、锚点选择器。+- [输入](/docs/zh-cn/scripting/input/)——UI 层之下的原始键盘/鼠标/触摸。+- [本地化](/docs/zh-cn/assets/localization/)——把 `Text.content` 绑定到翻译键。+- [动画](/docs/zh-cn/animation/overview/)——补间 UI 颜色/位置增加动感。+- [编辑器](/docs/zh-cn/editor/overview/)——可视化编排、预制件、锚点选择器。diff --git a/docs/astro/src/content/docs/zh-cn/ui/text.mdx b/docs/astro/src/content/docs/zh-cn/ui/text.mdxindex 35b091479..e2d64b4a9 100644--- a/docs/astro/src/content/docs/zh-cn/ui/text.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/text.mdx@@ -74,7 +74,7 @@ const pulseBanner = defineSystem([Query(Mut(Transform), Text), Res(Time)], (q, t| `align` | `TextAlign` | `Left` | 水平对齐:`Left` / `Center` / `Right`。 || `verticalAlign` | `TextVerticalAlign` | `Top` | 垂直对齐:`Top` / `Middle` / `Bottom`。 || `wordWrap` | boolean | `true` | 按盒宽换行(需要 `UINode` 盒)。 |-| `overflow` | `TextOverflow` | `Visible` | `Visible` / `Clip` / `Ellipsis`。当前渲染器始终按 `Visible` 绘制;要裁剪溢出,给盒加 [`UIMask`](/docs/zh-cn/guides/ui/)。 |+| `overflow` | `TextOverflow` | `Visible` | `Visible` / `Clip` / `Ellipsis`。当前渲染器始终按 `Visible` 绘制;要裁剪溢出,给盒加 [`UIMask`](/docs/zh-cn/ui/overview/)。 || `lineHeight` | number | `1.2` | 行距,为 **`fontSize` 的比率**(基线间距 = `lineHeight × fontSize`)。 || `bold` / `italic` | boolean | `false` | 基础字体样式(富文本 `<b>`/`<i>` 在其上叠加)。 || `strokeColor` | Color | `{0,0,0,1}` | 描边颜色。 |@@ -237,7 +237,7 @@ addStartupSystem(buildBubble);不要手写 `content`,改设 `i18nKey`:存在 Localization 资源时(安装`localizationPlugin`),每帧有系统把键经目录解析并写入 `content`——因此`setLocale` 下一帧就重排所有绑定的标签。缺失的键解析为键本身(可见、可 grep);-没有 Localization 资源时按原作 `content` 显示。见[本地化](/docs/zh-cn/guides/localization/)。+没有 Localization 资源时按原作 `content` 显示。见[本地化](/docs/zh-cn/assets/localization/)。## 最佳实践@@ -255,9 +255,9 @@ addStartupSystem(buildBubble);## 另请参阅-- [UI](/docs/zh-cn/guides/ui/) —— 组件模型总览。-- [UI 布局](/docs/zh-cn/guides/ui-layout/) —— 文本对齐与换行所依的 `UINode` 盒。-- [UI 组件](/docs/zh-cn/guides/ui-components/) —— 可编辑文本的 `createTextInput`。-- [UI 主题](/docs/zh-cn/guides/ui-theme/) —— 主题化的文本颜色角色与字号阶梯。-- [UI 数据绑定](/docs/zh-cn/guides/ui-binding/) —— 用响应式 signal 驱动 `content`。-- [本地化](/docs/zh-cn/guides/localization/) —— 目录、语言与 `i18nKey` 解析。+- [UI](/docs/zh-cn/ui/overview/) —— 组件模型总览。+- [UI 布局](/docs/zh-cn/ui/layout/) —— 文本对齐与换行所依的 `UINode` 盒。+- [UI 组件](/docs/zh-cn/ui/widgets/) —— 可编辑文本的 `createTextInput`。+- [UI 主题](/docs/zh-cn/ui/theming/) —— 主题化的文本颜色角色与字号阶梯。+- [UI 数据绑定](/docs/zh-cn/ui/data-binding/) —— 用响应式 signal 驱动 `content`。+- [本地化](/docs/zh-cn/assets/localization/) —— 目录、语言与 `i18nKey` 解析。diff --git a/docs/astro/src/content/docs/zh-cn/ui/theming.mdx b/docs/astro/src/content/docs/zh-cn/ui/theming.mdxindex 28ec4ee4d..10040c9b5 100644--- a/docs/astro/src/content/docs/zh-cn/ui/theming.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/theming.mdx@@ -214,7 +214,7 @@ function createBadge(world: World, parent: Entity, label: string): Entity {## 参见-- [UI](/docs/zh-cn/guides/ui/) —— 令牌所着色的组件模型。-- [UI 控件](/docs/zh-cn/guides/ui-components/) —— 消费令牌的控件工厂。-- [UI 控制器](/docs/zh-cn/guides/ui-controllers/) —— 主题状态色所依附的 `$interaction` gear。-- [数据绑定](/docs/zh-cn/guides/ui-binding/) —— 把响应式值写进组件字段。+- [UI](/docs/zh-cn/ui/overview/) —— 令牌所着色的组件模型。+- [UI 控件](/docs/zh-cn/ui/widgets/) —— 消费令牌的控件工厂。+- [UI 控制器](/docs/zh-cn/ui/controllers/) —— 主题状态色所依附的 `$interaction` gear。+- [数据绑定](/docs/zh-cn/ui/data-binding/) —— 把响应式值写进组件字段。diff --git a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdxindex ed3d60630..65f2a60cd 100644--- a/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx+++ b/docs/astro/src/content/docs/zh-cn/ui/widgets.mdx@@ -5,15 +5,15 @@ description: 内置控件工厂——Button、Toggle、Slider、Progress、Dropdimport { Aside } from '@astrojs/starlight/components';-控件工厂用 [UI](/docs/zh-cn/guides/ui/) 组件模型(`UINode` + `Interactable` +-`$interaction` [控制器与属性绑定](/docs/zh-cn/guides/ui-controllers/))构建常见控件,+控件工厂用 [UI](/docs/zh-cn/ui/overview/) 组件模型(`UINode` + `Interactable` ++`$interaction` [控制器与属性绑定](/docs/zh-cn/ui/controllers/))构建常见控件,免得你逐个手动接线。每个工厂接收一个选项对象,返回一个**句柄(handle)**——总是带 `entity` 和 `dispose()`,外加读取和驱动它的命令式方法。交互式控件需要 world 和 UI 事件队列——`world` 来自 `GetWorld()`,`events` 来自-`Res(UIEvents)`,和 [UI 指南](/docs/zh-cn/guides/ui/)里一样。它们都接受 `parent?`、-一个 `node?`([`UINode`](/docs/zh-cn/guides/ui-layout/) 布局——**默认:填满父级**)-和视觉覆盖;视觉默认值取自当前[主题](/docs/zh-cn/guides/ui-theme/)的角色,+`Res(UIEvents)`,和 [UI 指南](/docs/zh-cn/ui/overview/)里一样。它们都接受 `parent?`、+一个 `node?`([`UINode`](/docs/zh-cn/ui/layout/) 布局——**默认:填满父级**)+和视觉覆盖;视觉默认值取自当前[主题](/docs/zh-cn/ui/theming/)的角色,主题热切换时会重新解析。交互式控件**默认键盘可达**:它们自带 `Focusable`,Tab 能到达、Enter/Space 能点击、方向键能驱动滑块——用 `focusable: false` 退出。@@ -24,7 +24,7 @@ Tab 能到达、Enter/Space 能点击、方向键能驱动滑块——用 `focus<Aside type="note">需要跨多个元素的 **共享** 状态——页签、单选组、显隐面板、或从数据驱动的自定义按钮状态——- 请用 [UI 控制器](/docs/zh-cn/guides/ui-controllers/):一个具名的"页"状态,加上声明式的每页字段+ 请用 [UI 控制器](/docs/zh-cn/ui/controllers/):一个具名的"页"状态,加上声明式的每页字段绑定,可在编辑器里授权。</Aside>@@ -181,7 +181,7 @@ const ring = createProgress({ world, parent, radial: true, value: 0.75 });<Aside type="note">**同一个填充原语。** 进度条就是一个 **`Filled`** 模式的- [`UIVisual`](/docs/zh-cn/guides/ui/)——滑块的填充也构建于同一原语,对应 Unity 的+ [`UIVisual`](/docs/zh-cn/ui/overview/)——滑块的填充也构建于同一原语,对应 Unity 的"血条 = Filled Image"。`setValue()` 写 `fillAmount`,所以填充是渲染期裁剪,**没有逐帧布局**,精灵填充沿轴*揭示*而不是拉伸。`direction` 经共享的 `FILL_AXIS`表解析为 `Filled` 的裁剪轴与锚边,因此进度条、滑块以及任何基于 Filled 的控件填充方式@@ -325,7 +325,7 @@ events.on(field, 'submit', () => save(world.get(field, TextInput).value)); // E| 字段 | 默认 | 说明 ||---|---|---|-| `font` | `0` | **本项目自带**的字体资源(`.ttf` / `.otf`),与 [`Text.font`](/docs/zh-cn/guides/ui-text/#自定义字体) 是同一个槽位。设了它就压过 `fontFamily`——于是画在游戏自有字体面板上的输入框也用那套字,而不是 Arial。 |+| `font` | `0` | **本项目自带**的字体资源(`.ttf` / `.otf`),与 [`Text.font`](/docs/zh-cn/ui/text/#自定义字体) 是同一个槽位。设了它就压过 `fontFamily`——于是画在游戏自有字体面板上的输入框也用那套字,而不是 Arial。 || `textAlign` | `Left` | 值在框内的位置:`Left` / `Center` / `Right`。单行**在放得下时**保持该对齐;放不下之后改为跟随光标横向滚动,与一向左对齐时的行为一致。多行按行对齐。 || `renderMode` | `Auto` | 框内文本的字形管线——与 `Text.renderMode` 对应。 |@@ -356,25 +356,25 @@ world.insert(field, TextInput, { placeholder: 'Name', font: gameFont, textAlign:虚拟化的数据驱动列表与网格(`createListView`)、自由滚动面板(`createScrollView`)、数据源、布局提供者、自动行高以及惯性滚动 / 滚动条机制,单独成章:-**[列表与滚动](/docs/zh-cn/guides/ui-lists/)**。+**[列表与滚动](/docs/zh-cn/ui/lists/)**。## 数据绑定控件值就是普通组件字段(`UISlider.value`、`UIToggle.isOn`……),信号层可直接绑定——-`bindWidgetValue` 更把它做成双向。见 **[UI 数据绑定](/docs/zh-cn/guides/ui-binding/)**。+`bindWidgetValue` 更把它做成双向。见 **[UI 数据绑定](/docs/zh-cn/ui/data-binding/)**。## 拖放给任意可交互 UI 实体加 `Draggable`,指针拖拽即可移动它,附带`drag_start` / `drag_move` / `drag_end` 事件和实时的 `DragState` 组件。-轴锁定与范围约束齐备。见 **[UI 交互](/docs/zh-cn/guides/ui-interaction/)**。+轴锁定与范围约束齐备。见 **[UI 交互](/docs/zh-cn/ui/interaction/)**。## 键盘焦点带 `Focusable` 的实体参与键盘焦点:Tab / Shift+Tab 按 `tabIndex` 轮换,Enter/Space 激活,滑块接管方向键,聚焦的控件显示其 `focused` 交互页。控件工厂自动加 `Focusable`(`focusable: false` 退出);`FocusManager` 资源提供-程序化控制。详见 **[UI 交互](/docs/zh-cn/guides/ui-interaction/)**。+程序化控制。详见 **[UI 交互](/docs/zh-cn/ui/interaction/)**。## 安全区(移动端刘海)@@ -386,7 +386,7 @@ Enter/Space 激活,滑块接管方向键,聚焦的控件显示其 `focused` 交控件颜色来自共享的 token 集,角色如 `surface`、`control`、`primary`、`track`;`switchTheme(world, tokens)` 实时重刷屏上一切,项目在 **Project Settings → UI**-一次声明调色板。见 **[UI 主题](/docs/zh-cn/guides/ui-theme/)**。+一次声明调色板。见 **[UI 主题](/docs/zh-cn/ui/theming/)**。## 编辑器预制体@@ -396,7 +396,7 @@ Slider、Dialog、TextInput 等丢进场景,再在 Details 里编辑。活在组从调色板拖放会**嵌套**:落点会认指针下的布局容器为父级(拖拽时虚线框预览将要成为的父级),空画布落点则照旧落在根上。锚点选择器**按轴**编辑并保持控件原位——-改水平锚点绝不扰动垂直布局,反之亦然。见[编辑器](/docs/zh-cn/guides/editor/)。+改水平锚点绝不扰动垂直布局,反之亦然。见[编辑器](/docs/zh-cn/editor/overview/)。## 最佳实践@@ -413,9 +413,9 @@ Slider、Dialog、TextInput 等丢进场景,再在 Details 里编辑。活在组## 另请参阅-- [UI](/docs/zh-cn/guides/ui/) —— 组件模型:`UINode`、`Text`、`UIVisual` 与交互。-- [列表与滚动](/docs/zh-cn/guides/ui-lists/) —— `createListView`、`createScrollView` 与虚拟化。-- [UI 控制器](/docs/zh-cn/guides/ui-controllers/) —— 共享"页"状态 + 声明式每页字段绑定。-- [UI 数据绑定](/docs/zh-cn/guides/ui-binding/) —— 信号与控件双向绑定。-- [UI 交互](/docs/zh-cn/guides/ui-interaction/) —— 焦点、拖放、指针事件。-- [UI 主题](/docs/zh-cn/guides/ui-theme/) —— token、角色、主题热切换与项目主题。+- [UI](/docs/zh-cn/ui/overview/) —— 组件模型:`UINode`、`Text`、`UIVisual` 与交互。+- [列表与滚动](/docs/zh-cn/ui/lists/) —— `createListView`、`createScrollView` 与虚拟化。+- [UI 控制器](/docs/zh-cn/ui/controllers/) —— 共享"页"状态 + 声明式每页字段绑定。+- [UI 数据绑定](/docs/zh-cn/ui/data-binding/) —— 信号与控件双向绑定。+- [UI 交互](/docs/zh-cn/ui/interaction/) —— 焦点、拖放、指针事件。+- [UI 主题](/docs/zh-cn/ui/theming/) —— token、角色、主题热切换与项目主题。diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxindex df6ba6bea..97b99d7d5 100644--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx@@ -475,6 +475,6 @@ const control = defineSystem([Res(Particle)], (particles) => {## 参见-- [材质与着色器](/docs/zh-cn/guides/material/) —— 自定义粒子材质。-- [后处理](/docs/zh-cn/guides/postprocess/) —— 在 additive 粒子上叠加泛光。-- [资源](/docs/zh-cn/guides/assets/) —— 加载粒子贴图与图集。+- [材质与着色器](/docs/zh-cn/graphics/materials/) —— 自定义粒子材质。+- [后处理](/docs/zh-cn/graphics/post-processing/) —— 在 additive 粒子上叠加泛光。+- [资源](/docs/zh-cn/assets/overview/) —— 加载粒子贴图与图集。diff --git a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdxindex 7d0468c7a..abbdda75f 100644--- a/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/prefabs.mdx@@ -149,5 +149,5 @@ const { root } = await prefabs.instantiate('assets/prefabs/enemy.esprefab', {## 参见-- [场景](/docs/zh-cn/guides/scene/) —— 预制体实例存在于场景中。-- [资源](/docs/zh-cn/guides/assets/) —— 预制体是资源,首次 instantiate 时加载。+- [场景](/docs/zh-cn/world/scenes/) —— 预制体实例存在于场景中。+- [资源](/docs/zh-cn/assets/overview/) —— 预制体是资源,首次 instantiate 时加载。diff --git a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx b/docs/astro/src/content/docs/zh-cn/world/scenes.mdxindex 2baa13afa..9a18654ab 100644--- a/docs/astro/src/content/docs/zh-cn/world/scenes.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/scenes.mdx@@ -113,7 +113,7 @@ const keepPlayer = defineSystem([Res(SceneManager)], (scenes) => {之外,所以在编辑器里摆放的实体要在运行时用代码标记为持久化。</Aside>-如果要跨场景的是**状态**而不是活实体——分数、背包、任务标记——请用[存档](/docs/zh-cn/guides/save/)。+如果要跨场景的是**状态**而不是活实体——分数、背包、任务标记——请用[存档](/docs/zh-cn/scripting/save/)。持久化是给那些必须跨过切换继续运行的对象;存档是给那些只需要在对面还在的数据。## 场景流送(开放世界)@@ -164,7 +164,7 @@ const setupStreaming = defineSystem([Res(SceneStreaming)], (streaming) => {不会拖慢首屏。在打包对话框的**构建场景**列表里取消勾选的场景不会进入导出(在编辑器里仍可正常编辑和-运行),Playable 广告构建只带启动场景。见[构建与导出](/docs/zh-cn/guides/build-export/)。+运行),Playable 广告构建只带启动场景。见[构建与导出](/docs/zh-cn/publishing/overview/)。## `SceneManager` 参考@@ -186,7 +186,7 @@ const setupStreaming = defineSystem([Res(SceneStreaming)], (streaming) => {## 序列化与迁移场景文件格式是公开表面:`SceneData` 是纯 JSON,编辑器和运行时读写它所用的原语都导出给-游戏代码。你会在这些时刻用到它们:保存**活世界的快照**(比[存档 API](/docs/zh-cn/guides/save/)+游戏代码。你会在这些时刻用到它们:保存**活世界的快照**(比[存档 API](/docs/zh-cn/scripting/save/)更完整的检查点)、加载玩家生成或下载的场景,或发布状态放不进普通字段的组件。`serializeScene(world, name?)` 遍历活世界,产出能经加载器往返的 `SceneData`——层级折叠进@@ -269,7 +269,7 @@ registerSceneComponentCodec('MyVoxelChunk', {独立更新。- **对你生成的每个实体确立归属**——在场景上下文之外创建的实体不带 `SceneOwner`,于是没有任何场景会清理它。`ctx.adopt(entity)` 把它交给当前场景;`setPersistent` 是刻意的反面。-- **跨切换带对象用[持久化](#持久化实体),跨切换带状态用[存档](/docs/zh-cn/guides/save/)**+- **跨切换带对象用[持久化](#持久化实体),跨切换带状态用[存档](/docs/zh-cn/scripting/save/)**——一边是必须继续运行的实体,一边是切过去后还在就行的数据。<Aside type="note">@@ -280,6 +280,6 @@ registerSceneComponentCodec('MyVoxelChunk', {## 参见-- [预制体](/docs/zh-cn/guides/prefab/) —— 在场景内生成可复用的实体树。-- [存档与读档](/docs/zh-cn/guides/save/) —— 跨场景切换持久化状态。-- [资源](/docs/zh-cn/guides/assets/) —— 场景是 cook 入口点。+- [预制体](/docs/zh-cn/world/prefabs/) —— 在场景内生成可复用的实体树。+- [存档与读档](/docs/zh-cn/scripting/save/) —— 跨场景切换持久化状态。+- [资源](/docs/zh-cn/assets/overview/) —— 场景是 cook 入口点。diff --git a/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdxindex 530427e11..bd58ccc51 100644--- a/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/tilemaps.mdx@@ -284,7 +284,7 @@ Tiled 地图享受同等待遇:在 **Tiled 瓦片碰撞编辑器** 里画的形| **Ramp ◢ / ◣(斜坡)** | 三角 | 向右 / 向左升的 45° 斜坡。 || **Half(半砖:下 / 上 / 左 / 右)** | 半格盒 | 台沿、矮墙、薄地板。 || **One-way ↑(单向)** | 顶部实心盒 | 可跳穿平台——上方实心、下方可穿过。翻转即可改朝向(天花板、墙)。 |-| **Trigger(触发器)** | 传感器盒 | 非实心区域,触发重叠事件——见 [标记与触发区](/docs/zh-cn/guides/markers/)。 |+| **Trigger(触发器)** | 传感器盒 | 非实心区域,触发重叠事件——见 [标记与触发区](/docs/zh-cn/gameplay/markers/)。 |像画瓦片一样画它们;**碰撞叠加层**画出的正是播放时会生成的东西。每个碰撞层还能携带自己的**物理材质**(摩擦力 / 弹性 / 密度),作用于它生成的每个格子——在 Inspector 里设置。@@ -300,7 +300,7 @@ Tiled 地图享受同等待遇:在 **Tiled 瓦片碰撞编辑器** 里画的形## 对象层Tiled 的**对象层**(出生点、触发器、区域形状)随地图一起加载。现代的读法是-`Query(Marker)`:加载时点对象汇聚成 [**Marker**](/docs/zh-cn/guides/markers/) 实体、形状对象汇聚成+`Query(Marker)`:加载时点对象汇聚成 [**Marker**](/docs/zh-cn/gameplay/markers/) 实体、形状对象汇聚成**Trigger Area** 区域——正是你手工创建的那些实体——于是一条查询就能读到对象,无论它来自Tiled 还是 Estella 编辑器。@@ -365,7 +365,7 @@ origin / 每单位像素 / 播放模式生命周期。## 参见-- [标记与触发区](/docs/zh-cn/guides/markers/) —— 把玩法点位和触发区作为可查询的真实体铺在关卡上。-- [物理](/docs/zh-cn/guides/physics/) —— 瓦片碰撞体参与物理世界。-- [资源](/docs/zh-cn/guides/assets/) —— 加载 `.tmj` 地图与 `.estileset` 图集。-- [场景](/docs/zh-cn/guides/scene/) —— 瓦片图层随场景序列化。+- [标记与触发区](/docs/zh-cn/gameplay/markers/) —— 把玩法点位和触发区作为可查询的真实体铺在关卡上。+- [物理](/docs/zh-cn/gameplay/physics/) —— 瓦片碰撞体参与物理世界。+- [资源](/docs/zh-cn/assets/overview/) —— 加载 `.tmj` 地图与 `.estileset` 图集。+- [场景](/docs/zh-cn/world/scenes/) —— 瓦片图层随场景序列化。diff --git a/examples/lighting-2d/README.md b/examples/lighting-2d/README.mdindex a3d767832..980fc8fb1 100644--- a/examples/lighting-2d/README.md+++ b/examples/lighting-2d/README.md@@ -32,7 +32,7 @@ unlit wall is nearly black — so a light does not just brighten the room, itthey read as emissive dots. Kill every light and the whole room goes black;only the markers keep glowing. When a surface needs more than the flag (atint, a normal map), give it a `Lit2D`- material instead — see the [lighting guide](../../docs/astro/src/content/docs/guides/lighting.mdx).+ material instead — see the [lighting guide](../../docs/astro/src/content/docs/graphics/lighting.mdx).- **Shadow casters are lit like anything else**: an occluder box never shadowsits own interior, so the pillars and obstacles take light on the side facingit while still throwing a shadow cone behind them.