From 76691cc19891aafef38763e108c0faa792174849 Mon Sep 17 00:00:00 2001 From: YHH <359807859@qq.com> Date: Fri, 26 Dec 2025 19:15:08 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E7=BB=93=E6=9E=84=EF=BC=8C=E6=B7=BB=E5=8A=A0=E7=8B=AC=E7=AB=8B?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E5=8C=BA=E5=9F=9F=20(#349)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: 重构文档结构，添加独立模块区域 - 新增 /modules/ 目录用于功能模块文档 - 移动 behavior-tree 从 /guide/ 到 /modules/ - 添加模块总览页面 - 更新导航栏添加"模块"入口 - 更新侧边栏：模块区域独立侧边栏 - 更新 i18n 配置支持新模块 * style(docs): 提高文字对比度 --- docs/.vitepress/config.mjs | 74 +++++++++++++++---- docs/.vitepress/i18n/en.json | 22 +++++- docs/.vitepress/i18n/zh.json | 22 +++++- docs/.vitepress/theme/custom.css | 27 +++---- docs/en/modules/index.md | 54 ++++++++++++++ .../behavior-tree/advanced-usage.md | 0 .../behavior-tree/asset-management.md | 0 .../behavior-tree/best-practices.md | 0 .../behavior-tree/cocos-integration.md | 0 .../behavior-tree/core-concepts.md | 0 .../behavior-tree/custom-actions.md | 0 .../behavior-tree/editor-guide.md | 0 .../behavior-tree/editor-workflow.md | 0 .../behavior-tree/getting-started.md | 0 .../{guide => modules}/behavior-tree/index.md | 0 .../behavior-tree/laya-integration.md | 0 .../behavior-tree/nodejs-usage.md | 0 docs/modules/index.md | 54 ++++++++++++++ 18 files changed, 223 insertions(+), 30 deletions(-) create mode 100644 docs/en/modules/index.md rename docs/{guide => modules}/behavior-tree/advanced-usage.md (100%) rename docs/{guide => modules}/behavior-tree/asset-management.md (100%) rename docs/{guide => modules}/behavior-tree/best-practices.md (100%) rename docs/{guide => modules}/behavior-tree/cocos-integration.md (100%) rename docs/{guide => modules}/behavior-tree/core-concepts.md (100%) rename docs/{guide => modules}/behavior-tree/custom-actions.md (100%) rename docs/{guide => modules}/behavior-tree/editor-guide.md (100%) rename docs/{guide => modules}/behavior-tree/editor-workflow.md (100%) rename docs/{guide => modules}/behavior-tree/getting-started.md (100%) rename docs/{guide => modules}/behavior-tree/index.md (100%) rename docs/{guide => modules}/behavior-tree/laya-integration.md (100%) rename docs/{guide => modules}/behavior-tree/nodejs-usage.md (100%) create mode 100644 docs/modules/index.md diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index 42332060..7f8f68c3 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -49,21 +49,6 @@ function createSidebar(t, prefix = '') { { text: t.sidebar.persistentEntity, link: `${prefix}/guide/persistent-entity` } ] }, - { - text: t.sidebar.behaviorTree, - link: `${prefix}/guide/behavior-tree/`, - items: [ - { text: t.sidebar.btGettingStarted, link: `${prefix}/guide/behavior-tree/getting-started` }, - { text: t.sidebar.btCoreConcepts, link: `${prefix}/guide/behavior-tree/core-concepts` }, - { text: t.sidebar.btEditorGuide, link: `${prefix}/guide/behavior-tree/editor-guide` }, - { text: t.sidebar.btEditorWorkflow, link: `${prefix}/guide/behavior-tree/editor-workflow` }, - { text: t.sidebar.btCustomActions, link: `${prefix}/guide/behavior-tree/custom-actions` }, - { text: t.sidebar.btCocosIntegration, link: `${prefix}/guide/behavior-tree/cocos-integration` }, - { text: t.sidebar.btLayaIntegration, link: `${prefix}/guide/behavior-tree/laya-integration` }, - { text: t.sidebar.btAdvancedUsage, link: `${prefix}/guide/behavior-tree/advanced-usage` }, - { text: t.sidebar.btBestPractices, link: `${prefix}/guide/behavior-tree/best-practices` } - ] - }, { text: t.sidebar.serialization, link: `${prefix}/guide/serialization` }, { text: t.sidebar.eventSystem, link: `${prefix}/guide/event-system` }, { text: t.sidebar.timeAndTimers, link: `${prefix}/guide/time-and-timers` }, @@ -89,6 +74,64 @@ function createSidebar(t, prefix = '') { ] } ], + // 模块总览侧边栏 | Modules overview sidebar + [`${prefix}/modules/`]: [ + { + text: t.sidebar.modulesOverview, + link: `${prefix}/modules/`, + items: [ + { + text: t.sidebar.aiModules, + collapsed: false, + items: [ + { text: t.sidebar.behaviorTree, link: `${prefix}/modules/behavior-tree/` }, + { text: t.sidebar.fsm, link: `${prefix}/modules/fsm/` } + ] + }, + { + text: t.sidebar.gameplayModules, + collapsed: false, + items: [ + { text: t.sidebar.timer, link: `${prefix}/modules/timer/` }, + { text: t.sidebar.spatial, link: `${prefix}/modules/spatial/` }, + { text: t.sidebar.pathfinding, link: `${prefix}/modules/pathfinding/` } + ] + }, + { + text: t.sidebar.toolModules, + collapsed: false, + items: [ + { text: t.sidebar.blueprint, link: `${prefix}/modules/blueprint/` }, + { text: t.sidebar.procgen, link: `${prefix}/modules/procgen/` } + ] + }, + { + text: t.sidebar.networkModules, + collapsed: false, + items: [ + { text: t.sidebar.network, link: `${prefix}/modules/network/` } + ] + } + ] + } + ], + // 行为树模块侧边栏 | Behavior tree module sidebar + [`${prefix}/modules/behavior-tree/`]: [ + { + text: t.sidebar.behaviorTree, + items: [ + { text: t.sidebar.btGettingStarted, link: `${prefix}/modules/behavior-tree/getting-started` }, + { text: t.sidebar.btCoreConcepts, link: `${prefix}/modules/behavior-tree/core-concepts` }, + { text: t.sidebar.btEditorGuide, link: `${prefix}/modules/behavior-tree/editor-guide` }, + { text: t.sidebar.btEditorWorkflow, link: `${prefix}/modules/behavior-tree/editor-workflow` }, + { text: t.sidebar.btCustomActions, link: `${prefix}/modules/behavior-tree/custom-actions` }, + { text: t.sidebar.btCocosIntegration, link: `${prefix}/modules/behavior-tree/cocos-integration` }, + { text: t.sidebar.btLayaIntegration, link: `${prefix}/modules/behavior-tree/laya-integration` }, + { text: t.sidebar.btAdvancedUsage, link: `${prefix}/modules/behavior-tree/advanced-usage` }, + { text: t.sidebar.btBestPractices, link: `${prefix}/modules/behavior-tree/best-practices` } + ] + } + ], [`${prefix}/examples/`]: [ { text: t.sidebar.examples, @@ -173,6 +216,7 @@ function createNav(t, prefix = '') { { text: t.nav.home, link: `${prefix}/` }, { text: t.nav.quickStart, link: `${prefix}/guide/getting-started` }, { text: t.nav.guide, link: `${prefix}/guide/` }, + { text: t.nav.modules, link: `${prefix}/modules/` }, { text: t.nav.api, link: `${prefix}/api/README` }, { text: t.nav.examples, diff --git a/docs/.vitepress/i18n/en.json b/docs/.vitepress/i18n/en.json index 64be9e0c..a71a337c 100644 --- a/docs/.vitepress/i18n/en.json +++ b/docs/.vitepress/i18n/en.json @@ -3,6 +3,7 @@ "home": "Home", "quickStart": "Quick Start", "guide": "Guide", + "modules": "Modules", "api": "API", "examples": "Examples", "workerDemo": "Worker System Demo", @@ -54,7 +55,26 @@ "utilities": "Utilities", "interfaces": "Interfaces", "decorators": "Decorators", - "enums": "Enums" + "enums": "Enums", + "modulesOverview": "Modules Overview", + "aiModules": "AI Modules", + "gameplayModules": "Gameplay", + "toolModules": "Tools", + "networkModules": "Network", + "fsm": "State Machine (FSM)", + "fsmOverview": "Overview", + "timer": "Timer System", + "timerOverview": "Overview", + "spatial": "Spatial Index", + "spatialOverview": "Overview", + "pathfinding": "Pathfinding", + "pathfindingOverview": "Overview", + "blueprint": "Visual Scripting", + "blueprintOverview": "Overview", + "procgen": "Procedural Generation", + "procgenOverview": "Overview", + "network": "Network Sync", + "networkOverview": "Overview" }, "home": { "title": "ESEngine - High-performance TypeScript ECS Framework", diff --git a/docs/.vitepress/i18n/zh.json b/docs/.vitepress/i18n/zh.json index 4bd3e189..2d936680 100644 --- a/docs/.vitepress/i18n/zh.json +++ b/docs/.vitepress/i18n/zh.json @@ -3,6 +3,7 @@ "home": "首页", "quickStart": "快速开始", "guide": "指南", + "modules": "模块", "api": "API", "examples": "示例", "workerDemo": "Worker系统演示", @@ -54,7 +55,26 @@ "utilities": "工具类", "interfaces": "接口", "decorators": "装饰器", - "enums": "枚举" + "enums": "枚举", + "modulesOverview": "模块总览", + "aiModules": "AI 模块", + "gameplayModules": "游戏逻辑", + "toolModules": "工具模块", + "networkModules": "网络模块", + "fsm": "状态机 (FSM)", + "fsmOverview": "概述", + "timer": "定时器系统", + "timerOverview": "概述", + "spatial": "空间索引", + "spatialOverview": "概述", + "pathfinding": "寻路系统", + "pathfindingOverview": "概述", + "blueprint": "可视化脚本", + "blueprintOverview": "概述", + "procgen": "程序化生成", + "procgenOverview": "概述", + "network": "网络同步", + "networkOverview": "概述" }, "home": { "title": "ESEngine - 高性能 TypeScript ECS 框架", diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css index 7416f861..13e23f0d 100644 --- a/docs/.vitepress/theme/custom.css +++ b/docs/.vitepress/theme/custom.css @@ -2,23 +2,24 @@ color-scheme: dark; --vp-nav-height: 64px; - --es-bg-base: #1e1e1e; - --es-bg-elevated: #252526; - --es-bg-overlay: #2d2d2d; - --es-bg-input: #3c3c3c; - --es-bg-inset: #181818; + --es-bg-base: #1a1a1a; + --es-bg-elevated: #222222; + --es-bg-overlay: #2a2a2a; + --es-bg-input: #333333; + --es-bg-inset: #151515; --es-bg-hover: #2a2d2e; --es-bg-active: #37373d; - --es-bg-sidebar: #262626; - --es-bg-card: #2a2a2a; - --es-bg-header: #2d2d2d; + --es-bg-sidebar: #1e1e1e; + --es-bg-card: #242424; + --es-bg-header: #1e1e1e; - --es-text-primary: #cccccc; - --es-text-secondary: #9d9d9d; - --es-text-tertiary: #6a6a6a; + /* 提高文字对比度 | Improve text contrast */ + --es-text-primary: #e0e0e0; + --es-text-secondary: #b0b0b0; + --es-text-tertiary: #888888; --es-text-inverse: #ffffff; - --es-text-muted: #aaaaaa; - --es-text-dim: #6a6a6a; + --es-text-muted: #c0c0c0; + --es-text-dim: #888888; --es-font-xs: 11px; --es-font-sm: 12px; diff --git a/docs/en/modules/index.md b/docs/en/modules/index.md new file mode 100644 index 00000000..08d7cb72 --- /dev/null +++ b/docs/en/modules/index.md @@ -0,0 +1,54 @@ +# Modules + +ESEngine provides a rich set of modules that can be imported as needed. + +## Module List + +### AI Modules + +| Module | Package | Description | +|--------|---------|-------------| +| [Behavior Tree](/en/modules/behavior-tree/) | `@esengine/behavior-tree` | AI behavior tree with visual editor | +| [State Machine](/en/modules/fsm/) | `@esengine/fsm` | Finite state machine for character/AI states | + +### Gameplay + +| Module | Package | Description | +|--------|---------|-------------| +| [Timer](/en/modules/timer/) | `@esengine/timer` | Timer and cooldown system | +| [Spatial](/en/modules/spatial/) | `@esengine/spatial` | Spatial queries, AOI management | +| [Pathfinding](/en/modules/pathfinding/) | `@esengine/pathfinding` | A* pathfinding, NavMesh navigation | + +### Tools + +| Module | Package | Description | +|--------|---------|-------------| +| [Blueprint](/en/modules/blueprint/) | `@esengine/blueprint` | Visual scripting system | +| [Procgen](/en/modules/procgen/) | `@esengine/procgen` | Noise functions, random utilities | + +### Network + +| Module | Package | Description | +|--------|---------|-------------| +| [Network](/en/modules/network/) | `@esengine/network` | Multiplayer game networking | + +## Installation + +All modules can be installed independently: + +```bash +# Install a single module +npm install @esengine/behavior-tree + +# Or use CLI to add to existing project +npx @esengine/cli add behavior-tree +``` + +## Platform Compatibility + +All modules are pure TypeScript and compatible with: + +- Cocos Creator 3.x +- Laya 3.x +- Node.js +- Browser diff --git a/docs/guide/behavior-tree/advanced-usage.md b/docs/modules/behavior-tree/advanced-usage.md similarity index 100% rename from docs/guide/behavior-tree/advanced-usage.md rename to docs/modules/behavior-tree/advanced-usage.md diff --git a/docs/guide/behavior-tree/asset-management.md b/docs/modules/behavior-tree/asset-management.md similarity index 100% rename from docs/guide/behavior-tree/asset-management.md rename to docs/modules/behavior-tree/asset-management.md diff --git a/docs/guide/behavior-tree/best-practices.md b/docs/modules/behavior-tree/best-practices.md similarity index 100% rename from docs/guide/behavior-tree/best-practices.md rename to docs/modules/behavior-tree/best-practices.md diff --git a/docs/guide/behavior-tree/cocos-integration.md b/docs/modules/behavior-tree/cocos-integration.md similarity index 100% rename from docs/guide/behavior-tree/cocos-integration.md rename to docs/modules/behavior-tree/cocos-integration.md diff --git a/docs/guide/behavior-tree/core-concepts.md b/docs/modules/behavior-tree/core-concepts.md similarity index 100% rename from docs/guide/behavior-tree/core-concepts.md rename to docs/modules/behavior-tree/core-concepts.md diff --git a/docs/guide/behavior-tree/custom-actions.md b/docs/modules/behavior-tree/custom-actions.md similarity index 100% rename from docs/guide/behavior-tree/custom-actions.md rename to docs/modules/behavior-tree/custom-actions.md diff --git a/docs/guide/behavior-tree/editor-guide.md b/docs/modules/behavior-tree/editor-guide.md similarity index 100% rename from docs/guide/behavior-tree/editor-guide.md rename to docs/modules/behavior-tree/editor-guide.md diff --git a/docs/guide/behavior-tree/editor-workflow.md b/docs/modules/behavior-tree/editor-workflow.md similarity index 100% rename from docs/guide/behavior-tree/editor-workflow.md rename to docs/modules/behavior-tree/editor-workflow.md diff --git a/docs/guide/behavior-tree/getting-started.md b/docs/modules/behavior-tree/getting-started.md similarity index 100% rename from docs/guide/behavior-tree/getting-started.md rename to docs/modules/behavior-tree/getting-started.md diff --git a/docs/guide/behavior-tree/index.md b/docs/modules/behavior-tree/index.md similarity index 100% rename from docs/guide/behavior-tree/index.md rename to docs/modules/behavior-tree/index.md diff --git a/docs/guide/behavior-tree/laya-integration.md b/docs/modules/behavior-tree/laya-integration.md similarity index 100% rename from docs/guide/behavior-tree/laya-integration.md rename to docs/modules/behavior-tree/laya-integration.md diff --git a/docs/guide/behavior-tree/nodejs-usage.md b/docs/modules/behavior-tree/nodejs-usage.md similarity index 100% rename from docs/guide/behavior-tree/nodejs-usage.md rename to docs/modules/behavior-tree/nodejs-usage.md diff --git a/docs/modules/index.md b/docs/modules/index.md new file mode 100644 index 00000000..59ca09fe --- /dev/null +++ b/docs/modules/index.md @@ -0,0 +1,54 @@ +# 功能模块 + +ESEngine 提供了丰富的功能模块，可以按需引入到你的项目中。 + +## 模块列表 + +### AI 模块 + +| 模块 | 包名 | 描述 | +|------|------|------| +| [行为树](/modules/behavior-tree/) | `@esengine/behavior-tree` | AI 行为树系统，支持可视化编辑 | +| [状态机](/modules/fsm/) | `@esengine/fsm` | 有限状态机，用于角色/AI 状态管理 | + +### 游戏逻辑 + +| 模块 | 包名 | 描述 | +|------|------|------| +| [定时器](/modules/timer/) | `@esengine/timer` | 定时器和冷却系统 | +| [空间索引](/modules/spatial/) | `@esengine/spatial` | 空间查询、AOI 兴趣区域管理 | +| [寻路系统](/modules/pathfinding/) | `@esengine/pathfinding` | A* 寻路、NavMesh 导航网格 | + +### 工具模块 + +| 模块 | 包名 | 描述 | +|------|------|------| +| [可视化脚本](/modules/blueprint/) | `@esengine/blueprint` | 蓝图可视化脚本系统 | +| [程序化生成](/modules/procgen/) | `@esengine/procgen` | 噪声函数、随机工具 | + +### 网络模块 + +| 模块 | 包名 | 描述 | +|------|------|------| +| [网络同步](/modules/network/) | `@esengine/network` | 多人游戏网络同步 | + +## 安装 + +所有模块都可以独立安装： + +```bash +# 安装单个模块 +npm install @esengine/behavior-tree + +# 或使用 CLI 添加到现有项目 +npx @esengine/cli add behavior-tree +``` + +## 平台兼容性 + +所有功能模块都是纯 TypeScript 实现，兼容： + +- Cocos Creator 3.x +- Laya 3.x +- Node.js +- 浏览器