From 34de1e5edfc05fffb8f0bbeb8c02763c3b18a3bf Mon Sep 17 00:00:00 2001 From: yhh <359807859@qq.com> Date: Wed, 3 Dec 2025 22:44:04 +0800 Subject: [PATCH] =?UTF-8?q?feat(docs):=20=E6=B7=BB=E5=8A=A0=E4=B8=AD?= =?UTF-8?q?=E8=8B=B1=E6=96=87=E5=9B=BD=E9=99=85=E5=8C=96=E6=94=AF=E6=8C=81?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 11 + README_CN.md | 11 + docs/.vitepress/config.mjs | 399 +++++++++-------- docs/.vitepress/i18n/en.json | 85 ++++ docs/.vitepress/i18n/index.ts | 21 + docs/.vitepress/i18n/zh.json | 85 ++++ .../theme/components/ParticleHeroEn.vue | 422 ++++++++++++++++++ docs/.vitepress/theme/custom.css | 10 + docs/.vitepress/theme/index.js | 2 + docs/en/guide/getting-started.md | 412 +++++++++++++++++ docs/en/guide/index.md | 43 ++ docs/en/index.md | 317 +++++++++++++ docs/index.md | 16 +- 13 files changed, 1638 insertions(+), 196 deletions(-) create mode 100644 docs/.vitepress/i18n/en.json create mode 100644 docs/.vitepress/i18n/index.ts create mode 100644 docs/.vitepress/i18n/zh.json create mode 100644 docs/.vitepress/theme/components/ParticleHeroEn.vue create mode 100644 docs/en/guide/getting-started.md create mode 100644 docs/en/guide/index.md create mode 100644 docs/en/index.md diff --git a/README.md b/README.md index 5879a2e1..3511b879 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,17 @@ player.addComponent(new Position()); player.addComponent(new Velocity()); Core.setScene(scene); + +// Game loop +let lastTime = 0; +function gameLoop(currentTime: number) { + const deltaTime = (currentTime - lastTime) / 1000; + lastTime = currentTime; + + Core.update(deltaTime); + requestAnimationFrame(gameLoop); +} +requestAnimationFrame(gameLoop); ``` ## Modules diff --git a/README_CN.md b/README_CN.md index 28b060d7..6a7eb366 100644 --- a/README_CN.md +++ b/README_CN.md @@ -81,6 +81,17 @@ player.addComponent(new Position()); player.addComponent(new Velocity()); Core.setScene(scene); + +// 游戏循环 +let lastTime = 0; +function gameLoop(currentTime: number) { + const deltaTime = (currentTime - lastTime) / 1000; + lastTime = currentTime; + + Core.update(deltaTime); + requestAnimationFrame(gameLoop); +} +requestAnimationFrame(gameLoop); ``` ## 模块 diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs index c77d4135..c244de4a 100644 --- a/docs/.vitepress/config.mjs +++ b/docs/.vitepress/config.mjs @@ -9,6 +9,184 @@ const corePackageJson = JSON.parse( readFileSync(join(__dirname, '../../packages/core/package.json'), 'utf-8') ) +// Import i18n messages +import en from './i18n/en.json' with { type: 'json' } +import zh from './i18n/zh.json' with { type: 'json' } + +// 创建侧边栏配置 | Create sidebar config +// prefix: 路径前缀，如 '' 或 '/en' | Path prefix like '' or '/en' +function createSidebar(t, prefix = '') { + return { + [`${prefix}/guide/`]: [ + { + text: t.sidebar.gettingStarted, + items: [ + { text: t.sidebar.quickStart, link: `${prefix}/guide/getting-started` }, + { text: t.sidebar.guideOverview, link: `${prefix}/guide/` } + ] + }, + { + text: t.sidebar.coreConcepts, + collapsed: false, + items: [ + { text: t.sidebar.entity, link: `${prefix}/guide/entity` }, + { text: t.sidebar.hierarchy, link: `${prefix}/guide/hierarchy` }, + { text: t.sidebar.component, link: `${prefix}/guide/component` }, + { text: t.sidebar.entityQuery, link: `${prefix}/guide/entity-query` }, + { + text: t.sidebar.system, + link: `${prefix}/guide/system`, + items: [ + { text: t.sidebar.workerSystem, link: `${prefix}/guide/worker-system` } + ] + }, + { + text: t.sidebar.scene, + link: `${prefix}/guide/scene`, + items: [ + { text: t.sidebar.sceneManager, link: `${prefix}/guide/scene-manager` }, + { text: t.sidebar.worldManager, link: `${prefix}/guide/world-manager` } + ] + }, + { + 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` }, + { text: t.sidebar.logging, link: `${prefix}/guide/logging` } + ] + }, + { + text: t.sidebar.advancedFeatures, + collapsed: false, + items: [ + { text: t.sidebar.serviceContainer, link: `${prefix}/guide/service-container` }, + { text: t.sidebar.pluginSystem, link: `${prefix}/guide/plugin-system` } + ] + }, + { + text: t.sidebar.platformAdapters, + link: `${prefix}/guide/platform-adapter`, + collapsed: false, + items: [ + { text: t.sidebar.browserAdapter, link: `${prefix}/guide/platform-adapter/browser` }, + { text: t.sidebar.wechatAdapter, link: `${prefix}/guide/platform-adapter/wechat-minigame` }, + { text: t.sidebar.nodejsAdapter, link: `${prefix}/guide/platform-adapter/nodejs` } + ] + } + ], + [`${prefix}/examples/`]: [ + { + text: t.sidebar.examples, + items: [ + { text: t.sidebar.examplesOverview, link: `${prefix}/examples/` }, + { text: t.nav.workerDemo, link: `${prefix}/examples/worker-system-demo` } + ] + } + ], + [`${prefix}/api/`]: [ + { + text: t.sidebar.apiReference, + items: [ + { text: t.sidebar.overview, link: `${prefix}/api/README` }, + { + text: t.sidebar.coreClasses, + collapsed: false, + items: [ + { text: 'Core', link: `${prefix}/api/classes/Core` }, + { text: 'Scene', link: `${prefix}/api/classes/Scene` }, + { text: 'World', link: `${prefix}/api/classes/World` }, + { text: 'Entity', link: `${prefix}/api/classes/Entity` }, + { text: 'Component', link: `${prefix}/api/classes/Component` }, + { text: 'EntitySystem', link: `${prefix}/api/classes/EntitySystem` } + ] + }, + { + text: t.sidebar.systemClasses, + collapsed: true, + items: [ + { text: 'PassiveSystem', link: `${prefix}/api/classes/PassiveSystem` }, + { text: 'ProcessingSystem', link: `${prefix}/api/classes/ProcessingSystem` }, + { text: 'IntervalSystem', link: `${prefix}/api/classes/IntervalSystem` } + ] + }, + { + text: t.sidebar.utilities, + collapsed: true, + items: [ + { text: 'Matcher', link: `${prefix}/api/classes/Matcher` }, + { text: 'Time', link: `${prefix}/api/classes/Time` }, + { text: 'PerformanceMonitor', link: `${prefix}/api/classes/PerformanceMonitor` }, + { text: 'DebugManager', link: `${prefix}/api/classes/DebugManager` } + ] + }, + { + text: t.sidebar.interfaces, + collapsed: true, + items: [ + { text: 'IScene', link: `${prefix}/api/interfaces/IScene` }, + { text: 'IComponent', link: `${prefix}/api/interfaces/IComponent` }, + { text: 'ISystemBase', link: `${prefix}/api/interfaces/ISystemBase` }, + { text: 'ICoreConfig', link: `${prefix}/api/interfaces/ICoreConfig` } + ] + }, + { + text: t.sidebar.decorators, + collapsed: true, + items: [ + { text: '@ECSComponent', link: `${prefix}/api/functions/ECSComponent` }, + { text: '@ECSSystem', link: `${prefix}/api/functions/ECSSystem` } + ] + }, + { + text: t.sidebar.enums, + collapsed: true, + items: [ + { text: 'ECSEventType', link: `${prefix}/api/enumerations/ECSEventType` }, + { text: 'LogLevel', link: `${prefix}/api/enumerations/LogLevel` } + ] + } + ] + } + ] + } +} + +// 创建导航配置 | Create nav config +// prefix: 路径前缀，如 '' 或 '/en' | Path prefix like '' or '/en' +function createNav(t, prefix = '') { + return [ + { 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.api, link: `${prefix}/api/README` }, + { + text: t.nav.examples, + items: [ + { text: t.nav.workerDemo, link: `${prefix}/examples/worker-system-demo` }, + { text: t.nav.lawnMowerDemo, link: 'https://github.com/esengine/lawn-mower-demo' } + ] + }, + { + text: `v${corePackageJson.version}`, + link: 'https://github.com/esengine/ecs-framework/releases' + } + ] +} + export default defineConfig({ vite: { plugins: [ @@ -29,180 +207,49 @@ export default defineConfig({ } }, title: 'ESEngine', - description: '高性能 TypeScript ECS 框架 - 为游戏开发而生', - lang: 'zh-CN', - appearance: 'force-dark', + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + description: '高性能 TypeScript ECS 框架 - 为游戏开发而生', + themeConfig: { + nav: createNav(zh, ''), + sidebar: createSidebar(zh, ''), + editLink: { + pattern: 'https://github.com/esengine/ecs-framework/edit/master/docs/:path', + text: zh.common.editOnGithub + }, + outline: { + level: [2, 3], + label: zh.common.onThisPage + } + } + }, + en: { + label: 'English', + lang: 'en', + link: '/en/', + description: 'High-performance TypeScript ECS Framework for Game Development', + themeConfig: { + nav: createNav(en, '/en'), + sidebar: createSidebar(en, '/en'), + editLink: { + pattern: 'https://github.com/esengine/ecs-framework/edit/master/docs/:path', + text: en.common.editOnGithub + }, + outline: { + level: [2, 3], + label: en.common.onThisPage + } + } + } + }, + themeConfig: { siteTitle: 'ESEngine', - nav: [ - { text: '首页', link: '/' }, - { text: '快速开始', link: '/guide/getting-started' }, - { text: '指南', link: '/guide/' }, - { text: 'API', link: '/api/README' }, - { - text: '示例', - items: [ - { text: 'Worker系统演示', link: '/examples/worker-system-demo' }, - { text: '割草机演示', link: 'https://github.com/esengine/lawn-mower-demo' } - ] - }, - { - text: `v${corePackageJson.version}`, - link: 'https://github.com/esengine/ecs-framework/releases' - } - ], - - sidebar: { - '/guide/': [ - { - text: '开始使用', - items: [ - { text: '快速开始', link: '/guide/getting-started' }, - { text: '指南概览', link: '/guide/' } - ] - }, - { - text: '核心概念', - collapsed: false, - items: [ - { text: '实体类 (Entity)', link: '/guide/entity' }, - { text: '层级系统 (Hierarchy)', link: '/guide/hierarchy' }, - { text: '组件系统 (Component)', link: '/guide/component' }, - { text: '实体查询系统', link: '/guide/entity-query' }, - { - text: '系统架构 (System)', - link: '/guide/system', - items: [ - { text: 'Worker系统 (多线程)', link: '/guide/worker-system' } - ] - }, - { - text: '场景管理 (Scene)', - link: '/guide/scene', - items: [ - { text: 'SceneManager', link: '/guide/scene-manager' }, - { text: 'WorldManager', link: '/guide/world-manager' } - ] - }, - { - text: '行为树系统 (Behavior Tree)', - link: '/guide/behavior-tree/', - items: [ - { text: '快速开始', link: '/guide/behavior-tree/getting-started' }, - { text: '核心概念', link: '/guide/behavior-tree/core-concepts' }, - { text: '编辑器指南', link: '/guide/behavior-tree/editor-guide' }, - { text: '编辑器工作流', link: '/guide/behavior-tree/editor-workflow' }, - { text: '自定义动作组件', link: '/guide/behavior-tree/custom-actions' }, - { text: 'Cocos Creator集成', link: '/guide/behavior-tree/cocos-integration' }, - { text: 'Laya引擎集成', link: '/guide/behavior-tree/laya-integration' }, - { text: '高级用法', link: '/guide/behavior-tree/advanced-usage' }, - { text: '最佳实践', link: '/guide/behavior-tree/best-practices' } - ] - }, - { text: '序列化系统 (Serialization)', link: '/guide/serialization' }, - { text: '事件系统 (Event)', link: '/guide/event-system' }, - { text: '时间和定时器 (Time)', link: '/guide/time-and-timers' }, - { text: '日志系统 (Logger)', link: '/guide/logging' } - ] - }, - { - text: '高级特性', - collapsed: false, - items: [ - { text: '服务容器 (Service Container)', link: '/guide/service-container' }, - { text: '插件系统 (Plugin System)', link: '/guide/plugin-system' } - ] - }, - { - text: '平台适配器', - link: '/guide/platform-adapter', - collapsed: false, - items: [ - { text: '浏览器适配器', link: '/guide/platform-adapter/browser' }, - { text: '微信小游戏适配器', link: '/guide/platform-adapter/wechat-minigame' }, - { text: 'Node.js适配器', link: '/guide/platform-adapter/nodejs' } - ] - } - ], - '/examples/': [ - { - text: '示例', - items: [ - { text: '示例概览', link: '/examples/' }, - { text: 'Worker系统演示', link: '/examples/worker-system-demo' } - ] - } - ], - '/api/': [ - { - text: 'API 参考', - items: [ - { text: '概述', link: '/api/README' }, - { - text: '核心类', - collapsed: false, - items: [ - { text: 'Core', link: '/api/classes/Core' }, - { text: 'Scene', link: '/api/classes/Scene' }, - { text: 'World', link: '/api/classes/World' }, - { text: 'Entity', link: '/api/classes/Entity' }, - { text: 'Component', link: '/api/classes/Component' }, - { text: 'EntitySystem', link: '/api/classes/EntitySystem' } - ] - }, - { - text: '系统类', - collapsed: true, - items: [ - { text: 'PassiveSystem', link: '/api/classes/PassiveSystem' }, - { text: 'ProcessingSystem', link: '/api/classes/ProcessingSystem' }, - { text: 'IntervalSystem', link: '/api/classes/IntervalSystem' } - ] - }, - { - text: '工具类', - collapsed: true, - items: [ - { text: 'Matcher', link: '/api/classes/Matcher' }, - { text: 'Time', link: '/api/classes/Time' }, - { text: 'PerformanceMonitor', link: '/api/classes/PerformanceMonitor' }, - { text: 'DebugManager', link: '/api/classes/DebugManager' } - ] - }, - { - text: '接口', - collapsed: true, - items: [ - { text: 'IScene', link: '/api/interfaces/IScene' }, - { text: 'IComponent', link: '/api/interfaces/IComponent' }, - { text: 'ISystemBase', link: '/api/interfaces/ISystemBase' }, - { text: 'ICoreConfig', link: '/api/interfaces/ICoreConfig' } - ] - }, - { - text: '装饰器', - collapsed: true, - items: [ - { text: '@ECSComponent', link: '/api/functions/ECSComponent' }, - { text: '@ECSSystem', link: '/api/functions/ECSSystem' } - ] - }, - { - text: '枚举', - collapsed: true, - items: [ - { text: 'ECSEventType', link: '/api/enumerations/ECSEventType' }, - { text: 'LogLevel', link: '/api/enumerations/LogLevel' } - ] - } - ] - } - ] - }, - socialLinks: [ { icon: 'github', link: 'https://github.com/esengine/ecs-framework' } ], @@ -212,18 +259,8 @@ export default defineConfig({ copyright: 'Copyright © 2025 ECS Framework' }, - editLink: { - pattern: 'https://github.com/esengine/ecs-framework/edit/master/docs/:path', - text: '在 GitHub 上编辑此页' - }, - search: { provider: 'local' - }, - - outline: { - level: [2, 3], - label: '在这个页面上' } }, @@ -232,8 +269,6 @@ export default defineConfig({ ['link', { rel: 'icon', href: '/favicon.ico' }] ], - // 使用自定义域名 esengine.cn 时，base 设置为 '/' - // 如果部署到 GitHub Pages 子路径，改为 '/ecs-framework/' base: '/', cleanUrls: true, @@ -244,4 +279,4 @@ export default defineConfig({ dark: 'github-dark' } } -}) \ No newline at end of file +}) diff --git a/docs/.vitepress/i18n/en.json b/docs/.vitepress/i18n/en.json new file mode 100644 index 00000000..7f65a1d5 --- /dev/null +++ b/docs/.vitepress/i18n/en.json @@ -0,0 +1,85 @@ +{ + "nav": { + "home": "Home", + "quickStart": "Quick Start", + "guide": "Guide", + "api": "API", + "examples": "Examples", + "workerDemo": "Worker System Demo", + "lawnMowerDemo": "Lawn Mower Demo" + }, + "sidebar": { + "gettingStarted": "Getting Started", + "quickStart": "Quick Start", + "guideOverview": "Guide Overview", + "coreConcepts": "Core Concepts", + "entity": "Entity", + "hierarchy": "Hierarchy", + "component": "Component", + "entityQuery": "Entity Query", + "system": "System", + "workerSystem": "Worker System (Multithreading)", + "scene": "Scene", + "sceneManager": "SceneManager", + "worldManager": "WorldManager", + "behaviorTree": "Behavior Tree", + "btGettingStarted": "Getting Started", + "btCoreConcepts": "Core Concepts", + "btEditorGuide": "Editor Guide", + "btEditorWorkflow": "Editor Workflow", + "btCustomActions": "Custom Actions", + "btCocosIntegration": "Cocos Creator Integration", + "btLayaIntegration": "Laya Engine Integration", + "btAdvancedUsage": "Advanced Usage", + "btBestPractices": "Best Practices", + "serialization": "Serialization", + "eventSystem": "Event System", + "timeAndTimers": "Time and Timers", + "logging": "Logging", + "advancedFeatures": "Advanced Features", + "serviceContainer": "Service Container", + "pluginSystem": "Plugin System", + "platformAdapters": "Platform Adapters", + "browserAdapter": "Browser Adapter", + "wechatAdapter": "WeChat Mini Game Adapter", + "nodejsAdapter": "Node.js Adapter", + "examples": "Examples", + "examplesOverview": "Examples Overview", + "apiReference": "API Reference", + "overview": "Overview", + "coreClasses": "Core Classes", + "systemClasses": "System Classes", + "utilities": "Utilities", + "interfaces": "Interfaces", + "decorators": "Decorators", + "enums": "Enums" + }, + "home": { + "title": "ESEngine - High-performance TypeScript ECS Framework", + "quickLinks": "Quick Links", + "viewDocs": "View Docs", + "getStarted": "Get Started", + "getStartedDesc": "From installation to your first ECS app, learn the core concepts in 5 minutes.", + "aiSystem": "AI System", + "behaviorTreeEditor": "Visual Behavior Tree Editor", + "behaviorTreeDesc": "Built-in AI behavior tree system with visual editing and real-time debugging.", + "coreFeatures": "Core Features", + "ecsArchitecture": "High-performance ECS Architecture", + "ecsArchitectureDesc": "Data-driven entity component system for large-scale entity processing with cache-friendly memory layout.", + "typeSupport": "Full Type Support", + "typeSupportDesc": "100% TypeScript with complete type definitions and compile-time checking for the best development experience.", + "visualBehaviorTree": "Visual Behavior Tree", + "visualBehaviorTreeDesc": "Built-in AI behavior tree system with visual editor, custom nodes, and real-time debugging.", + "multiPlatform": "Multi-Platform Support", + "multiPlatformDesc": "Support for browsers, Node.js, WeChat Mini Games, and seamless integration with major game engines.", + "modularDesign": "Modular Design", + "modularDesignDesc": "Core features packaged independently, import only what you need. Support for custom plugin extensions.", + "devTools": "Developer Tools", + "devToolsDesc": "Built-in performance monitoring, debugging tools, serialization system, and complete development toolchain.", + "learnMore": "Learn more →" + }, + "common": { + "editOnGithub": "Edit this page on GitHub", + "onThisPage": "On this page" + } +} diff --git a/docs/.vitepress/i18n/index.ts b/docs/.vitepress/i18n/index.ts new file mode 100644 index 00000000..0d7e49cc --- /dev/null +++ b/docs/.vitepress/i18n/index.ts @@ -0,0 +1,21 @@ +import en from './en.json' +import zh from './zh.json' + +export const messages = { en, zh } + +export type Locale = 'en' | 'zh' + +export function getLocaleMessages(locale: Locale) { + return messages[locale] || messages.en +} + +// Helper to get nested key value +export function t(messages: typeof en, key: string): string { + const keys = key.split('.') + let result: any = messages + for (const k of keys) { + result = result?.[k] + if (result === undefined) return key + } + return result +} diff --git a/docs/.vitepress/i18n/zh.json b/docs/.vitepress/i18n/zh.json new file mode 100644 index 00000000..b1d67886 --- /dev/null +++ b/docs/.vitepress/i18n/zh.json @@ -0,0 +1,85 @@ +{ + "nav": { + "home": "首页", + "quickStart": "快速开始", + "guide": "指南", + "api": "API", + "examples": "示例", + "workerDemo": "Worker系统演示", + "lawnMowerDemo": "割草机演示" + }, + "sidebar": { + "gettingStarted": "开始使用", + "quickStart": "快速开始", + "guideOverview": "指南概览", + "coreConcepts": "核心概念", + "entity": "实体类 (Entity)", + "hierarchy": "层级系统 (Hierarchy)", + "component": "组件系统 (Component)", + "entityQuery": "实体查询系统", + "system": "系统架构 (System)", + "workerSystem": "Worker系统 (多线程)", + "scene": "场景管理 (Scene)", + "sceneManager": "SceneManager", + "worldManager": "WorldManager", + "behaviorTree": "行为树系统 (Behavior Tree)", + "btGettingStarted": "快速开始", + "btCoreConcepts": "核心概念", + "btEditorGuide": "编辑器指南", + "btEditorWorkflow": "编辑器工作流", + "btCustomActions": "自定义动作组件", + "btCocosIntegration": "Cocos Creator集成", + "btLayaIntegration": "Laya引擎集成", + "btAdvancedUsage": "高级用法", + "btBestPractices": "最佳实践", + "serialization": "序列化系统 (Serialization)", + "eventSystem": "事件系统 (Event)", + "timeAndTimers": "时间和定时器 (Time)", + "logging": "日志系统 (Logger)", + "advancedFeatures": "高级特性", + "serviceContainer": "服务容器 (Service Container)", + "pluginSystem": "插件系统 (Plugin System)", + "platformAdapters": "平台适配器", + "browserAdapter": "浏览器适配器", + "wechatAdapter": "微信小游戏适配器", + "nodejsAdapter": "Node.js适配器", + "examples": "示例", + "examplesOverview": "示例概览", + "apiReference": "API 参考", + "overview": "概述", + "coreClasses": "核心类", + "systemClasses": "系统类", + "utilities": "工具类", + "interfaces": "接口", + "decorators": "装饰器", + "enums": "枚举" + }, + "home": { + "title": "ESEngine - 高性能 TypeScript ECS 框架", + "quickLinks": "快速入口", + "viewDocs": "查看文档", + "getStarted": "快速开始", + "getStartedDesc": "从安装到创建第一个 ECS 应用，快速了解核心概念。", + "aiSystem": "AI 系统", + "behaviorTreeEditor": "行为树可视化编辑器", + "behaviorTreeDesc": "内置 AI 行为树系统，支持可视化编辑和实时调试。", + "coreFeatures": "核心特性", + "ecsArchitecture": "高性能 ECS 架构", + "ecsArchitectureDesc": "基于数据驱动的实体组件系统，支持大规模实体处理，缓存友好的内存布局。", + "typeSupport": "完整类型支持", + "typeSupportDesc": "100% TypeScript 编写，完整的类型定义和编译时检查，提供最佳的开发体验。", + "visualBehaviorTree": "可视化行为树", + "visualBehaviorTreeDesc": "内置 AI 行为树系统，提供可视化编辑器，支持自定义节点和实时调试。", + "multiPlatform": "多平台支持", + "multiPlatformDesc": "支持浏览器、Node.js、微信小游戏等多平台，可与主流游戏引擎无缝集成。", + "modularDesign": "模块化设计", + "modularDesignDesc": "核心功能独立打包，按需引入。支持自定义插件扩展，灵活适配不同项目。", + "devTools": "开发者工具", + "devToolsDesc": "内置性能监控、调试工具、序列化系统等，提供完整的开发工具链。", + "learnMore": "了解更多 →" + }, + "common": { + "editOnGithub": "在 GitHub 上编辑此页", + "onThisPage": "在这个页面上" + } +} diff --git a/docs/.vitepress/theme/components/ParticleHeroEn.vue b/docs/.vitepress/theme/components/ParticleHeroEn.vue new file mode 100644 index 00000000..c4fd384e --- /dev/null +++ b/docs/.vitepress/theme/components/ParticleHeroEn.vue @@ -0,0 +1,422 @@ + + + + + diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css index f9629a79..7416f861 100644 --- a/docs/.vitepress/theme/custom.css +++ b/docs/.vitepress/theme/custom.css @@ -183,12 +183,22 @@ html:not(.dark) { .VPContent { background: var(--es-bg-card) !important; + padding-top: 0 !important; } .VPContent.has-sidebar { background: var(--es-bg-card) !important; } +/* 首页布局修复 | Home page layout fix */ +.VPPage { + padding-top: 0 !important; +} + +.Layout > .VPContent { + padding-top: var(--vp-nav-height) !important; +} + .VPDoc { background: transparent !important; } diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js index b8c7a8f7..07d42c8a 100644 --- a/docs/.vitepress/theme/index.js +++ b/docs/.vitepress/theme/index.js @@ -1,5 +1,6 @@ import DefaultTheme from 'vitepress/theme' import ParticleHero from './components/ParticleHero.vue' +import ParticleHeroEn from './components/ParticleHeroEn.vue' import FeatureCard from './components/FeatureCard.vue' import './custom.css' @@ -7,6 +8,7 @@ export default { extends: DefaultTheme, enhanceApp({ app }) { app.component('ParticleHero', ParticleHero) + app.component('ParticleHeroEn', ParticleHeroEn) app.component('FeatureCard', FeatureCard) } } diff --git a/docs/en/guide/getting-started.md b/docs/en/guide/getting-started.md new file mode 100644 index 00000000..f5dc2f72 --- /dev/null +++ b/docs/en/guide/getting-started.md @@ -0,0 +1,412 @@ +# Quick Start + +This guide will help you get started with ECS Framework, from installation to creating your first ECS application. + +## Installation + +### NPM Installation + +```bash +# Using npm +npm install @esengine/ecs-framework +``` + +## Initialize Core + +### Basic Initialization + +The core of ECS Framework is the `Core` class, a singleton that manages the entire framework lifecycle. + +```typescript +import { Core } from '@esengine/ecs-framework' + +// Method 1: Using config object (recommended) +const core = Core.create({ + debug: true, // Enable debug mode for detailed logs and performance monitoring + debugConfig: { // Optional: Advanced debug configuration + enabled: false, // Whether to enable WebSocket debug server + websocketUrl: 'ws://localhost:8080', + debugFrameRate: 30, // Debug data send frame rate + channels: { + entities: true, + systems: true, + performance: true, + components: true, + scenes: true + } + } +}); + +// Method 2: Simplified creation (backward compatible) +const core = Core.create(true); // Equivalent to { debug: true } + +// Method 3: Production environment configuration +const core = Core.create({ + debug: false // Disable debug in production +}); +``` + +### Core Configuration Details + +```typescript +interface ICoreConfig { + /** Enable debug mode - affects log level and performance monitoring */ + debug?: boolean; + + /** Advanced debug configuration - for dev tools integration */ + debugConfig?: { + enabled: boolean; // Enable debug server + websocketUrl: string; // WebSocket server URL + autoReconnect?: boolean; // Auto reconnect + debugFrameRate?: 60 | 30 | 15; // Debug data send frame rate + channels: { // Data channel configuration + entities: boolean; // Entity data + systems: boolean; // System data + performance: boolean; // Performance data + components: boolean; // Component data + scenes: boolean; // Scene data + }; + }; +} +``` + +### Core Instance Management + +Core uses singleton pattern, accessible via static property after creation: + +```typescript +// Create instance +const core = Core.create(true); + +// Get created instance +const instance = Core.Instance; // Returns current instance, null if not created +``` + +### Game Loop Integration + +**Important**: Before creating entities and systems, you need to understand how to integrate ECS Framework into your game engine. + +`Core.update(deltaTime)` is the framework heartbeat, must be called every frame. It handles: +- Updating the built-in Time class +- Updating all global managers (timers, object pools, etc.) +- Updating all entity systems in all scenes +- Processing entity creation and destruction +- Collecting performance data (in debug mode) + +See engine integration examples: [Game Engine Integration](#game-engine-integration) + +## Create Your First ECS Application + +### 1. Define Components + +Components are pure data containers that store entity state: + +```typescript +import { Component, ECSComponent } from '@esengine/ecs-framework' + +// Position component +@ECSComponent('Position') +class Position extends Component { + x: number = 0 + y: number = 0 + + constructor(x: number = 0, y: number = 0) { + super() + this.x = x + this.y = y + } +} + +// Velocity component +@ECSComponent('Velocity') +class Velocity extends Component { + dx: number = 0 + dy: number = 0 + + constructor(dx: number = 0, dy: number = 0) { + super() + this.dx = dx + this.dy = dy + } +} + +// Sprite component +@ECSComponent('Sprite') +class Sprite extends Component { + texture: string = '' + width: number = 32 + height: number = 32 + + constructor(texture: string, width: number = 32, height: number = 32) { + super() + this.texture = texture + this.width = width + this.height = height + } +} +``` + +### 2. Create Entity Systems + +Systems contain game logic and process entities with specific components. ECS Framework provides Matcher-based entity filtering: + +```typescript +import { EntitySystem, Matcher, Time, ECSSystem } from '@esengine/ecs-framework' + +// Movement system - handles position and velocity +@ECSSystem('MovementSystem') +class MovementSystem extends EntitySystem { + + constructor() { + // Use Matcher to define target entities: must have both Position and Velocity + super(Matcher.empty().all(Position, Velocity)) + } + + protected process(entities: readonly Entity[]): void { + // process method receives all matching entities + for (const entity of entities) { + const position = entity.getComponent(Position)! + const velocity = entity.getComponent(Velocity)! + + // Update position (using framework's Time class) + position.x += velocity.dx * Time.deltaTime + position.y += velocity.dy * Time.deltaTime + + // Boundary check example + if (position.x < 0) position.x = 0 + if (position.y < 0) position.y = 0 + } + } +} + +// Render system - handles visible objects +@ECSSystem('RenderSystem') +class RenderSystem extends EntitySystem { + + constructor() { + // Must have Position and Sprite, optional Velocity (for direction) + super(Matcher.empty().all(Position, Sprite).any(Velocity)) + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const position = entity.getComponent(Position)! + const sprite = entity.getComponent(Sprite)! + const velocity = entity.getComponent(Velocity) // May be null + + // Flip sprite based on velocity direction (optional logic) + let flipX = false + if (velocity && velocity.dx < 0) { + flipX = true + } + + // Render logic (pseudocode here) + this.drawSprite(sprite.texture, position.x, position.y, sprite.width, sprite.height, flipX) + } + } + + private drawSprite(texture: string, x: number, y: number, width: number, height: number, flipX: boolean = false) { + // Actual render implementation depends on your game engine + const direction = flipX ? '<-' : '->' + console.log(`Render ${texture} at (${x.toFixed(1)}, ${y.toFixed(1)}) direction: ${direction}`) + } +} +``` + + +### 3. Create Scene + +Recommended to extend Scene class for custom scenes: + +```typescript +import { Scene } from '@esengine/ecs-framework' + +// Recommended: Extend Scene for custom scene +class GameScene extends Scene { + + initialize(): void { + // Scene initialization logic + this.name = "MainScene"; + + // Add systems to scene + this.addSystem(new MovementSystem()); + this.addSystem(new RenderSystem()); + } + + onStart(): void { + // Logic when scene starts running + console.log("Game scene started"); + } + + unload(): void { + // Cleanup logic when scene unloads + console.log("Game scene unloaded"); + } +} + +// Create and set scene +const gameScene = new GameScene(); +Core.setScene(gameScene); +``` + +### 4. Create Entities + +```typescript +// Create player entity +const player = gameScene.createEntity("Player"); +player.addComponent(new Position(100, 100)); +player.addComponent(new Velocity(50, 30)); // Move 50px/sec (x), 30px/sec (y) +player.addComponent(new Sprite("player.png", 64, 64)); +``` + +## Scene Management + +Core has built-in scene management, very simple to use: + +```typescript +import { Core, Scene } from '@esengine/ecs-framework'; + +// Initialize Core +Core.create({ debug: true }); + +// Create and set scene +class GameScene extends Scene { + initialize(): void { + this.name = "GamePlay"; + this.addSystem(new MovementSystem()); + this.addSystem(new RenderSystem()); + } +} + +const gameScene = new GameScene(); +Core.setScene(gameScene); + +// Game loop (auto-updates scene) +function gameLoop(deltaTime: number) { + Core.update(deltaTime); // Auto-updates global services and scene +} + +// Switch scenes +Core.loadScene(new MenuScene()); // Delayed switch (next frame) +Core.setScene(new GameScene()); // Immediate switch + +// Access current scene +const currentScene = Core.scene; + +// Using fluent API +const player = Core.ecsAPI?.createEntity('Player') + .addComponent(Position, 100, 100) + .addComponent(Velocity, 50, 0); +``` + +### Advanced: Using WorldManager for Multi-World + +Only for complex server-side applications (MMO game servers, game room systems, etc.): + +```typescript +import { Core, WorldManager } from '@esengine/ecs-framework'; + +// Initialize Core +Core.create({ debug: true }); + +// Get WorldManager from service container (Core auto-creates and registers it) +const worldManager = Core.services.resolve(WorldManager); + +// Create multiple independent game worlds +const room1 = worldManager.createWorld('room_001'); +const room2 = worldManager.createWorld('room_002'); + +// Create scenes in each world +const gameScene1 = room1.createScene('game', new GameScene()); +const gameScene2 = room2.createScene('game', new GameScene()); + +// Activate scenes +room1.setSceneActive('game', true); +room2.setSceneActive('game', true); + +// Game loop (need to manually update worlds) +function gameLoop(deltaTime: number) { + Core.update(deltaTime); // Update global services + worldManager.updateAll(); // Manually update all worlds +} +``` + +## Game Engine Integration + +### Laya Engine Integration + +```typescript +import { Stage } from "laya/display/Stage"; +import { Laya } from "Laya"; +import { Core } from '@esengine/ecs-framework'; + +// Initialize Laya +Laya.init(800, 600).then(() => { + // Initialize ECS + Core.create(true); + Core.setScene(new GameScene()); + + // Start game loop + Laya.timer.frameLoop(1, this, () => { + const deltaTime = Laya.timer.delta / 1000; + Core.update(deltaTime); // Auto-updates global services and scene + }); +}); +``` + +### Cocos Creator Integration + +```typescript +import { Component, _decorator } from 'cc'; +import { Core } from '@esengine/ecs-framework'; + +const { ccclass } = _decorator; + +@ccclass('ECSGameManager') +export class ECSGameManager extends Component { + onLoad() { + // Initialize ECS + Core.create(true); + Core.setScene(new GameScene()); + } + + update(deltaTime: number) { + // Auto-updates global services and scene + Core.update(deltaTime); + } + + onDestroy() { + // Cleanup resources + Core.destroy(); + } +} +``` + + +## Next Steps + +You've successfully created your first ECS application! Next you can: + +- Check the complete [API Documentation](/en/api/README) +- Explore more [practical examples](/en/examples/) + +## FAQ + +### Why isn't my system executing? + +Ensure: +1. System is added to scene: `this.addSystem(system)` (in Scene's initialize method) +2. Scene is set: `Core.setScene(scene)` +3. Game loop is calling: `Core.update(deltaTime)` + +### How to debug ECS applications? + +Enable debug mode: + +```typescript +Core.create({ debug: true }) + +// Get debug data +const debugData = Core.getDebugData() +console.log(debugData) +``` diff --git a/docs/en/guide/index.md b/docs/en/guide/index.md new file mode 100644 index 00000000..3a8e9c37 --- /dev/null +++ b/docs/en/guide/index.md @@ -0,0 +1,43 @@ +# Guide + +Welcome to the ECS Framework Guide. This guide covers the core concepts and usage of the framework. + +## Core Concepts + +### [Entity](./entity.md) +Learn the basics of ECS architecture - how to use entities, lifecycle management, and best practices. + +### [Component](./component.md) +Learn how to create and use components for modular game feature design. + +### [System](./system.md) +Master system development to implement game logic processing. + +### [Entity Query & Matcher](./entity-query.md) +Learn to use Matcher for entity filtering and queries with `all`, `any`, `none`, `nothing` conditions. + +### [Scene](./scene.md) +Understand scene lifecycle, system management, and entity container features. + +### [Event System](./event-system.md) +Master the type-safe event system for component communication and system coordination. + +### [Serialization](./serialization.md) +Master serialization for scenes, entities, and components. Supports full and incremental serialization for game saves, network sync, and more. + +### [Time and Timers](./time-and-timers.md) +Learn time management and timer systems for precise game logic timing control. + +### [Logging](./logging.md) +Master the leveled logging system for debugging, monitoring, and error tracking. + +### [Platform Adapter](./platform-adapter.md) +Learn how to implement and register platform adapters for browsers, mini-games, Node.js, and more. + +## Advanced Features + +### [Service Container](./service-container.md) +Master dependency injection and service management for loosely-coupled architecture. + +### [Plugin System](./plugin-system.md) +Learn how to develop and use plugins to extend framework functionality. diff --git a/docs/en/index.md b/docs/en/index.md new file mode 100644 index 00000000..e8888f9e --- /dev/null +++ b/docs/en/index.md @@ -0,0 +1,317 @@ +--- +layout: page +title: ESEngine - High-performance TypeScript ECS Framework +--- + + + +
+
+
+

Quick Links

+ View Docs +
+
+ +
+
+ +
+ Quick Start +
+
+

Get Started in 5 Minutes

+

From installation to your first ECS app, learn the core concepts quickly.

+
+ + +
+
+ +
+ AI System +
+
+

Visual Behavior Tree Editor

+

Built-in AI behavior tree system with visual editing and real-time debugging.

+
+ +
+
+
+ +
+
+

Core Features

+
+
+
+ +
+

High-performance ECS Architecture

+

Data-driven entity component system for large-scale entity processing with cache-friendly memory layout.

+ Learn more +
+
+
+ +
+

Full Type Support

+

100% TypeScript with complete type definitions and compile-time checking for the best development experience.

+ Learn more +
+
+
+ +
+

Visual Behavior Tree

+

Built-in AI behavior tree system with visual editor, custom nodes, and real-time debugging.

+ Learn more +
+
+
+ +
+

Multi-Platform Support

+

Support for browsers, Node.js, WeChat Mini Games, and seamless integration with major game engines.

+ Learn more +
+
+
+ +
+

Modular Design

+

Core features packaged independently, import only what you need. Support for custom plugin extensions.

+ Learn more +
+
+
+ +
+

Developer Tools

+

Built-in performance monitoring, debugging tools, serialization system, and complete development toolchain.

+ Learn more +
+
+
+
+ + diff --git a/docs/index.md b/docs/index.md index fc34c6d2..32a35e56 100644 --- a/docs/index.md +++ b/docs/index.md @@ -96,20 +96,8 @@ title: ESEngine - 高性能 TypeScript ECS 框架 -