From 89cdfe396be1864bf37926deff4423aba65a430c Mon Sep 17 00:00:00 2001 From: YHH <359807859@qq.com> Date: Sat, 27 Dec 2025 12:54:53 +0800 Subject: [PATCH] docs: migrate documentation from VitePress to Starlight (#361) - Replace VitePress with Astro Starlight for documentation - Reorganize document structure with better hierarchy - Split large documents into sub-modules for better readability - Add new sections: component, entity-query, serialization, system - Support both Chinese (default) and English documentation - Add responsive design and improved navigation --- docs/.gitignore | 21 + docs/.vitepress/config.mjs | 329 ----- docs/.vitepress/i18n/en.json | 107 -- docs/.vitepress/i18n/index.ts | 21 - docs/.vitepress/i18n/zh.json | 107 -- .../theme/components/FeatureCard.vue | 93 -- .../theme/components/ParticleHero.vue | 422 ------ .../theme/components/ParticleHeroEn.vue | 422 ------ docs/.vitepress/theme/custom.css | 595 --------- docs/.vitepress/theme/index.js | 14 - docs/README.md | 49 + docs/architecture/material-system-refactor.md | 663 ---------- docs/astro.config.mjs | 178 +++ docs/changelog.md | 293 ----- docs/en/changelog.md | 291 ----- docs/en/guide/system.md | 1161 ----------------- docs/en/index.md | 317 ----- docs/guide/component.md | 725 ---------- docs/guide/editor-plugin-system.md | 0 docs/guide/entity-query.md | 750 ----------- docs/guide/persistent-entity.md | 360 ----- docs/guide/scene-manager.md | 681 ---------- docs/guide/serialization.md | 923 ------------- docs/guide/service-container.md | 828 ------------ docs/guide/system.md | 1161 ----------------- docs/guide/world-manager.md | 761 ----------- docs/index.md | 317 ----- docs/package.json | 21 + docs/public/favicon.svg | 1 + docs/src/assets/houston.webp | Bin 0 -> 98506 bytes docs/src/assets/logo.svg | 45 + docs/src/components/Head.astro | 20 + docs/src/components/ThemeSelect.astro | 3 + docs/src/content.config.ts | 7 + docs/src/content/docs/api/index.md | 64 + docs/src/content/docs/en/examples/index.md | 20 + .../docs/en/guide/component/best-practices.md | 312 +++++ .../docs/en/guide/component/entity-ref.md | 228 ++++ .../content/docs/en/guide/component/index.md | 226 ++++ .../docs/en/guide/component/lifecycle.md | 182 +++ .../en/guide/entity-query/best-practices.md | 225 ++++ .../en/guide/entity-query/compiled-query.md | 133 ++ .../docs/en/guide/entity-query/index.md | 244 ++++ .../docs/en/guide/entity-query/matcher-api.md | 118 ++ .../{ => src/content/docs}/en/guide/entity.md | 12 +- .../src/content/docs/en/guide/event-system.md | 260 ++++ .../content/docs}/en/guide/getting-started.md | 4 +- docs/src/content/docs/en/guide/hierarchy.md | 202 +++ docs/{ => src/content/docs}/en/guide/index.md | 4 +- docs/src/content/docs/en/guide/logging.md | 225 ++++ .../docs}/en/guide/persistent-entity.md | 4 + .../content/docs/en/guide/platform-adapter.md | 291 +++++ .../docs/en/guide/platform-adapter/browser.md | 372 ++++++ .../docs/en/guide/platform-adapter/nodejs.md | 560 ++++++++ .../guide/platform-adapter/wechat-minigame.md | 485 +++++++ .../content/docs/en/guide/plugin-system.md | 645 +++++++++ .../content/docs}/en/guide/scene-manager.md | 4 + docs/{ => src/content/docs}/en/guide/scene.md | 4 + .../docs/en/guide/serialization/decorators.md | 165 +++ .../en/guide/serialization/incremental.md | 228 ++++ .../docs/en/guide/serialization/index.md | 170 +++ .../docs/en/guide/serialization/migration.md | 151 +++ .../docs/en/guide/serialization/use-cases.md | 306 +++++ .../en/guide/service-container/advanced.md | 208 +++ .../service-container/built-in-services.md | 97 ++ .../service-container/dependency-injection.md | 190 +++ .../docs/en/guide/service-container/index.md | 123 ++ .../plugin-service-registry.md | 182 +++ .../docs/en/guide/system/best-practices.md | 368 ++++++ .../docs/en/guide/system/change-detection.md | 252 ++++ .../docs/en/guide/system/command-buffer.md | 172 +++ .../src/content/docs/en/guide/system/index.md | 170 +++ .../content/docs/en/guide/system/lifecycle.md | 249 ++++ .../docs/en/guide/system/scheduling.md | 182 +++ .../src/content/docs/en/guide/system/types.md | 200 +++ .../content/docs}/en/guide/time-and-timers.md | 4 +- .../content/docs}/en/guide/worker-system.md | 4 +- docs/src/content/docs/en/index.mdx | 67 + .../docs}/en/modules/blueprint/index.md | 4 +- .../content/docs}/en/modules/fsm/index.md | 4 +- .../content/docs}/en/modules/index.md | 4 +- .../content/docs}/en/modules/network/index.md | 4 +- .../docs}/en/modules/pathfinding/index.md | 4 +- .../content/docs}/en/modules/procgen/index.md | 4 +- .../content/docs}/en/modules/spatial/index.md | 4 +- .../content/docs}/en/modules/timer/index.md | 4 +- docs/{ => src/content/docs}/examples/index.md | 4 +- .../docs}/examples/worker-system-demo.md | 4 +- .../docs/guide/component/best-practices.md | 312 +++++ .../docs/guide/component/entity-ref.md | 228 ++++ .../src/content/docs/guide/component/index.md | 226 ++++ .../content/docs/guide/component/lifecycle.md | 182 +++ .../docs/guide/entity-query/best-practices.md | 225 ++++ .../docs/guide/entity-query/compiled-query.md | 133 ++ .../content/docs/guide/entity-query/index.md | 244 ++++ .../docs/guide/entity-query/matcher-api.md | 118 ++ docs/{ => src/content/docs}/guide/entity.md | 12 +- .../content/docs}/guide/event-system.md | 4 +- .../content/docs}/guide/getting-started.md | 5 +- .../{ => src/content/docs}/guide/hierarchy.md | 10 +- docs/{ => src/content/docs}/guide/index.md | 29 +- docs/{ => src/content/docs}/guide/logging.md | 4 +- .../content/docs}/guide/platform-adapter.md | 10 +- .../docs}/guide/platform-adapter/browser.md | 4 +- .../docs}/guide/platform-adapter/nodejs.md | 4 +- .../guide/platform-adapter/wechat-minigame.md | 4 +- .../content/docs}/guide/plugin-system.md | 10 +- docs/{ => src/content/docs}/guide/scene.md | 14 +- .../docs/guide/serialization/decorators.md | 165 +++ .../docs/guide/serialization/incremental.md | 228 ++++ .../content/docs/guide/serialization/index.md | 170 +++ .../docs/guide/serialization/migration.md | 151 +++ .../docs/guide/serialization/use-cases.md | 306 +++++ .../docs/guide/service-container/advanced.md | 208 +++ .../service-container/built-in-services.md | 97 ++ .../service-container/dependency-injection.md | 190 +++ .../docs/guide/service-container/index.md | 123 ++ .../plugin-service-registry.md | 182 +++ .../docs/guide/system/best-practices.md | 368 ++++++ .../docs/guide/system/change-detection.md | 252 ++++ .../docs/guide/system/command-buffer.md | 172 +++ docs/src/content/docs/guide/system/index.md | 170 +++ .../content/docs/guide/system/lifecycle.md | 249 ++++ .../content/docs/guide/system/scheduling.md | 182 +++ docs/src/content/docs/guide/system/types.md | 200 +++ .../content/docs}/guide/time-and-timers.md | 4 +- .../content/docs}/guide/worker-system.md | 4 +- docs/src/content/docs/index.mdx | 67 + .../modules/behavior-tree/advanced-usage.md | 14 +- .../modules/behavior-tree/asset-management.md | 10 +- .../modules/behavior-tree/best-practices.md | 12 +- .../behavior-tree/cocos-integration.md | 14 +- .../modules/behavior-tree/core-concepts.md | 14 +- .../modules/behavior-tree/custom-actions.md | 10 +- .../modules/behavior-tree/editor-guide.md | 8 +- .../modules/behavior-tree/editor-workflow.md | 12 +- .../modules/behavior-tree/getting-started.md | 16 +- .../docs}/modules/behavior-tree/index.md | 42 +- .../modules/behavior-tree/laya-integration.md | 10 +- .../modules/behavior-tree/nodejs-usage.md | 10 +- .../content/docs}/modules/blueprint/index.md | 4 +- .../content/docs}/modules/fsm/index.md | 4 +- docs/{ => src/content/docs}/modules/index.md | 5 +- .../content/docs}/modules/network/index.md | 12 +- .../docs}/modules/pathfinding/index.md | 4 +- .../content/docs}/modules/procgen/index.md | 4 +- .../content/docs}/modules/spatial/index.md | 4 +- .../content/docs}/modules/timer/index.md | 4 +- docs/src/styles/custom.css | 238 ++++ docs/src/styles/global.css | 1 + docs/tsconfig.json | 13 + 151 files changed, 14280 insertions(+), 11489 deletions(-) create mode 100644 docs/.gitignore delete mode 100644 docs/.vitepress/config.mjs delete mode 100644 docs/.vitepress/i18n/en.json delete mode 100644 docs/.vitepress/i18n/index.ts delete mode 100644 docs/.vitepress/i18n/zh.json delete mode 100644 docs/.vitepress/theme/components/FeatureCard.vue delete mode 100644 docs/.vitepress/theme/components/ParticleHero.vue delete mode 100644 docs/.vitepress/theme/components/ParticleHeroEn.vue delete mode 100644 docs/.vitepress/theme/custom.css delete mode 100644 docs/.vitepress/theme/index.js create mode 100644 docs/README.md delete mode 100644 docs/architecture/material-system-refactor.md create mode 100644 docs/astro.config.mjs delete mode 100644 docs/changelog.md delete mode 100644 docs/en/changelog.md delete mode 100644 docs/en/guide/system.md delete mode 100644 docs/en/index.md delete mode 100644 docs/guide/component.md delete mode 100644 docs/guide/editor-plugin-system.md delete mode 100644 docs/guide/entity-query.md delete mode 100644 docs/guide/persistent-entity.md delete mode 100644 docs/guide/scene-manager.md delete mode 100644 docs/guide/serialization.md delete mode 100644 docs/guide/service-container.md delete mode 100644 docs/guide/system.md delete mode 100644 docs/guide/world-manager.md delete mode 100644 docs/index.md create mode 100644 docs/package.json create mode 100644 docs/public/favicon.svg create mode 100644 docs/src/assets/houston.webp create mode 100644 docs/src/assets/logo.svg create mode 100644 docs/src/components/Head.astro create mode 100644 docs/src/components/ThemeSelect.astro create mode 100644 docs/src/content.config.ts create mode 100644 docs/src/content/docs/api/index.md create mode 100644 docs/src/content/docs/en/examples/index.md create mode 100644 docs/src/content/docs/en/guide/component/best-practices.md create mode 100644 docs/src/content/docs/en/guide/component/entity-ref.md create mode 100644 docs/src/content/docs/en/guide/component/index.md create mode 100644 docs/src/content/docs/en/guide/component/lifecycle.md create mode 100644 docs/src/content/docs/en/guide/entity-query/best-practices.md create mode 100644 docs/src/content/docs/en/guide/entity-query/compiled-query.md create mode 100644 docs/src/content/docs/en/guide/entity-query/index.md create mode 100644 docs/src/content/docs/en/guide/entity-query/matcher-api.md rename docs/{ => src/content/docs}/en/guide/entity.md (97%) create mode 100644 docs/src/content/docs/en/guide/event-system.md rename docs/{ => src/content/docs}/en/guide/getting-started.md (99%) create mode 100644 docs/src/content/docs/en/guide/hierarchy.md rename docs/{ => src/content/docs}/en/guide/index.md (98%) create mode 100644 docs/src/content/docs/en/guide/logging.md rename docs/{ => src/content/docs}/en/guide/persistent-entity.md (99%) create mode 100644 docs/src/content/docs/en/guide/platform-adapter.md create mode 100644 docs/src/content/docs/en/guide/platform-adapter/browser.md create mode 100644 docs/src/content/docs/en/guide/platform-adapter/nodejs.md create mode 100644 docs/src/content/docs/en/guide/platform-adapter/wechat-minigame.md create mode 100644 docs/src/content/docs/en/guide/plugin-system.md rename docs/{ => src/content/docs}/en/guide/scene-manager.md (99%) rename docs/{ => src/content/docs}/en/guide/scene.md (99%) create mode 100644 docs/src/content/docs/en/guide/serialization/decorators.md create mode 100644 docs/src/content/docs/en/guide/serialization/incremental.md create mode 100644 docs/src/content/docs/en/guide/serialization/index.md create mode 100644 docs/src/content/docs/en/guide/serialization/migration.md create mode 100644 docs/src/content/docs/en/guide/serialization/use-cases.md create mode 100644 docs/src/content/docs/en/guide/service-container/advanced.md create mode 100644 docs/src/content/docs/en/guide/service-container/built-in-services.md create mode 100644 docs/src/content/docs/en/guide/service-container/dependency-injection.md create mode 100644 docs/src/content/docs/en/guide/service-container/index.md create mode 100644 docs/src/content/docs/en/guide/service-container/plugin-service-registry.md create mode 100644 docs/src/content/docs/en/guide/system/best-practices.md create mode 100644 docs/src/content/docs/en/guide/system/change-detection.md create mode 100644 docs/src/content/docs/en/guide/system/command-buffer.md create mode 100644 docs/src/content/docs/en/guide/system/index.md create mode 100644 docs/src/content/docs/en/guide/system/lifecycle.md create mode 100644 docs/src/content/docs/en/guide/system/scheduling.md create mode 100644 docs/src/content/docs/en/guide/system/types.md rename docs/{ => src/content/docs}/en/guide/time-and-timers.md (99%) rename docs/{ => src/content/docs}/en/guide/worker-system.md (99%) create mode 100644 docs/src/content/docs/en/index.mdx rename docs/{ => src/content/docs}/en/modules/blueprint/index.md (99%) rename docs/{ => src/content/docs}/en/modules/fsm/index.md (99%) rename docs/{ => src/content/docs}/en/modules/index.md (98%) rename docs/{ => src/content/docs}/en/modules/network/index.md (99%) rename docs/{ => src/content/docs}/en/modules/pathfinding/index.md (99%) rename docs/{ => src/content/docs}/en/modules/procgen/index.md (99%) rename docs/{ => src/content/docs}/en/modules/spatial/index.md (99%) rename docs/{ => src/content/docs}/en/modules/timer/index.md (99%) rename docs/{ => src/content/docs}/examples/index.md (96%) rename docs/{ => src/content/docs}/examples/worker-system-demo.md (94%) create mode 100644 docs/src/content/docs/guide/component/best-practices.md create mode 100644 docs/src/content/docs/guide/component/entity-ref.md create mode 100644 docs/src/content/docs/guide/component/index.md create mode 100644 docs/src/content/docs/guide/component/lifecycle.md create mode 100644 docs/src/content/docs/guide/entity-query/best-practices.md create mode 100644 docs/src/content/docs/guide/entity-query/compiled-query.md create mode 100644 docs/src/content/docs/guide/entity-query/index.md create mode 100644 docs/src/content/docs/guide/entity-query/matcher-api.md rename docs/{ => src/content/docs}/guide/entity.md (97%) rename docs/{ => src/content/docs}/guide/event-system.md (99%) rename docs/{ => src/content/docs}/guide/getting-started.md (99%) rename docs/{ => src/content/docs}/guide/hierarchy.md (98%) rename docs/{ => src/content/docs}/guide/index.md (64%) rename docs/{ => src/content/docs}/guide/logging.md (99%) rename docs/{ => src/content/docs}/guide/platform-adapter.md (98%) rename docs/{ => src/content/docs}/guide/platform-adapter/browser.md (99%) rename docs/{ => src/content/docs}/guide/platform-adapter/nodejs.md (99%) rename docs/{ => src/content/docs}/guide/platform-adapter/wechat-minigame.md (99%) rename docs/{ => src/content/docs}/guide/plugin-system.md (98%) rename docs/{ => src/content/docs}/guide/scene.md (97%) create mode 100644 docs/src/content/docs/guide/serialization/decorators.md create mode 100644 docs/src/content/docs/guide/serialization/incremental.md create mode 100644 docs/src/content/docs/guide/serialization/index.md create mode 100644 docs/src/content/docs/guide/serialization/migration.md create mode 100644 docs/src/content/docs/guide/serialization/use-cases.md create mode 100644 docs/src/content/docs/guide/service-container/advanced.md create mode 100644 docs/src/content/docs/guide/service-container/built-in-services.md create mode 100644 docs/src/content/docs/guide/service-container/dependency-injection.md create mode 100644 docs/src/content/docs/guide/service-container/index.md create mode 100644 docs/src/content/docs/guide/service-container/plugin-service-registry.md create mode 100644 docs/src/content/docs/guide/system/best-practices.md create mode 100644 docs/src/content/docs/guide/system/change-detection.md create mode 100644 docs/src/content/docs/guide/system/command-buffer.md create mode 100644 docs/src/content/docs/guide/system/index.md create mode 100644 docs/src/content/docs/guide/system/lifecycle.md create mode 100644 docs/src/content/docs/guide/system/scheduling.md create mode 100644 docs/src/content/docs/guide/system/types.md rename docs/{ => src/content/docs}/guide/time-and-timers.md (99%) rename docs/{ => src/content/docs}/guide/worker-system.md (99%) create mode 100644 docs/src/content/docs/index.mdx rename docs/{ => src/content/docs}/modules/behavior-tree/advanced-usage.md (96%) rename docs/{ => src/content/docs}/modules/behavior-tree/asset-management.md (97%) rename docs/{ => src/content/docs}/modules/behavior-tree/best-practices.md (98%) rename docs/{ => src/content/docs}/modules/behavior-tree/cocos-integration.md (97%) rename docs/{ => src/content/docs}/modules/behavior-tree/core-concepts.md (97%) rename docs/{ => src/content/docs}/modules/behavior-tree/custom-actions.md (98%) rename docs/{ => src/content/docs}/modules/behavior-tree/editor-guide.md (93%) rename docs/{ => src/content/docs}/modules/behavior-tree/editor-workflow.md (95%) rename docs/{ => src/content/docs}/modules/behavior-tree/getting-started.md (95%) rename docs/{ => src/content/docs}/modules/behavior-tree/index.md (73%) rename docs/{ => src/content/docs}/modules/behavior-tree/laya-integration.md (97%) rename docs/{ => src/content/docs}/modules/behavior-tree/nodejs-usage.md (98%) rename docs/{ => src/content/docs}/modules/blueprint/index.md (99%) rename docs/{ => src/content/docs}/modules/fsm/index.md (99%) rename docs/{ => src/content/docs}/modules/index.md (95%) rename docs/{ => src/content/docs}/modules/network/index.md (98%) rename docs/{ => src/content/docs}/modules/pathfinding/index.md (99%) rename docs/{ => src/content/docs}/modules/procgen/index.md (99%) rename docs/{ => src/content/docs}/modules/spatial/index.md (99%) rename docs/{ => src/content/docs}/modules/timer/index.md (99%) create mode 100644 docs/src/styles/custom.css create mode 100644 docs/src/styles/global.css create mode 100644 docs/tsconfig.json diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..6240da8b --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,21 @@ +# build output +dist/ +# generated types +.astro/ + +# dependencies +node_modules/ + +# logs +npm-debug.log* +yarn-debug.log* +yarn-error.log* +pnpm-debug.log* + + +# environment variables +.env +.env.production + +# macOS-specific files +.DS_Store diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs deleted file mode 100644 index 7f8f68c3..00000000 --- a/docs/.vitepress/config.mjs +++ /dev/null @@ -1,329 +0,0 @@ -import { defineConfig } from 'vitepress' -import Icons from 'unplugin-icons/vite' -import { readFileSync } from 'fs' -import { join, dirname } from 'path' -import { fileURLToPath } from 'url' - -const __dirname = dirname(fileURLToPath(import.meta.url)) -const corePackageJson = JSON.parse( - readFileSync(join(__dirname, '../../packages/framework/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.persistentEntity, link: `${prefix}/guide/persistent-entity` } - ] - }, - { 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` } - ] - } - ], - // 模块总览侧边栏 | 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, - 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.modules, link: `${prefix}/modules/` }, - { 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: t.nav.changelog, link: `${prefix}/changelog` }, - { - text: `v${corePackageJson.version}`, - link: 'https://github.com/esengine/esengine/releases' - } - ] -} - -export default defineConfig({ - vite: { - plugins: [ - Icons({ - compiler: 'vue3', - autoInstall: true - }) - ], - server: { - fs: { - allow: ['..'] - }, - middlewareMode: false, - headers: { - 'Cross-Origin-Embedder-Policy': 'require-corp', - 'Cross-Origin-Opener-Policy': 'same-origin' - } - } - }, - title: 'ESEngine', - 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/esengine/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/esengine/edit/master/docs/:path', - text: en.common.editOnGithub - }, - outline: { - level: [2, 3], - label: en.common.onThisPage - } - } - } - }, - - themeConfig: { - siteTitle: 'ESEngine', - - socialLinks: [ - { icon: 'github', link: 'https://github.com/esengine/esengine' } - ], - - footer: { - message: 'Released under the MIT License.', - copyright: 'Copyright © 2025 ECS Framework' - }, - - search: { - provider: 'local' - } - }, - - head: [ - ['meta', { name: 'theme-color', content: '#646cff' }], - ['link', { rel: 'icon', href: '/favicon.ico' }] - ], - - base: '/', - cleanUrls: true, - ignoreDeadLinks: true, - - markdown: { - lineNumbers: true, - theme: { - light: 'github-light', - dark: 'github-dark' - } - } -}) diff --git a/docs/.vitepress/i18n/en.json b/docs/.vitepress/i18n/en.json deleted file mode 100644 index a71a337c..00000000 --- a/docs/.vitepress/i18n/en.json +++ /dev/null @@ -1,107 +0,0 @@ -{ - "nav": { - "home": "Home", - "quickStart": "Quick Start", - "guide": "Guide", - "modules": "Modules", - "api": "API", - "examples": "Examples", - "workerDemo": "Worker System Demo", - "lawnMowerDemo": "Lawn Mower Demo", - "changelog": "Changelog" - }, - "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", - "persistentEntity": "Persistent Entity", - "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", - "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", - "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 deleted file mode 100644 index 0d7e49cc..00000000 --- a/docs/.vitepress/i18n/index.ts +++ /dev/null @@ -1,21 +0,0 @@ -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 deleted file mode 100644 index 2d936680..00000000 --- a/docs/.vitepress/i18n/zh.json +++ /dev/null @@ -1,107 +0,0 @@ -{ - "nav": { - "home": "首页", - "quickStart": "快速开始", - "guide": "指南", - "modules": "模块", - "api": "API", - "examples": "示例", - "workerDemo": "Worker系统演示", - "lawnMowerDemo": "割草机演示", - "changelog": "更新日志" - }, - "sidebar": { - "gettingStarted": "开始使用", - "quickStart": "快速开始", - "guideOverview": "指南概览", - "coreConcepts": "核心概念", - "entity": "实体类 (Entity)", - "hierarchy": "层级系统 (Hierarchy)", - "component": "组件系统 (Component)", - "entityQuery": "实体查询系统", - "system": "系统架构 (System)", - "workerSystem": "Worker系统 (多线程)", - "scene": "场景管理 (Scene)", - "sceneManager": "SceneManager", - "worldManager": "WorldManager", - "persistentEntity": "持久化实体 (Persistent Entity)", - "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": "枚举", - "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 框架", - "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/FeatureCard.vue b/docs/.vitepress/theme/components/FeatureCard.vue deleted file mode 100644 index 2770f2df..00000000 --- a/docs/.vitepress/theme/components/FeatureCard.vue +++ /dev/null @@ -1,93 +0,0 @@ - - - - - diff --git a/docs/.vitepress/theme/components/ParticleHero.vue b/docs/.vitepress/theme/components/ParticleHero.vue deleted file mode 100644 index 8e90ffae..00000000 --- a/docs/.vitepress/theme/components/ParticleHero.vue +++ /dev/null @@ -1,422 +0,0 @@ - - - - - diff --git a/docs/.vitepress/theme/components/ParticleHeroEn.vue b/docs/.vitepress/theme/components/ParticleHeroEn.vue deleted file mode 100644 index 7fe698a6..00000000 --- a/docs/.vitepress/theme/components/ParticleHeroEn.vue +++ /dev/null @@ -1,422 +0,0 @@ - - - - - diff --git a/docs/.vitepress/theme/custom.css b/docs/.vitepress/theme/custom.css deleted file mode 100644 index 13e23f0d..00000000 --- a/docs/.vitepress/theme/custom.css +++ /dev/null @@ -1,595 +0,0 @@ -:root { - color-scheme: dark; - --vp-nav-height: 64px; - - --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: #1e1e1e; - --es-bg-card: #242424; - --es-bg-header: #1e1e1e; - - /* 提高文字对比度 | Improve text contrast */ - --es-text-primary: #e0e0e0; - --es-text-secondary: #b0b0b0; - --es-text-tertiary: #888888; - --es-text-inverse: #ffffff; - --es-text-muted: #c0c0c0; - --es-text-dim: #888888; - - --es-font-xs: 11px; - --es-font-sm: 12px; - --es-font-base: 13px; - --es-font-md: 14px; - --es-font-lg: 16px; - - --es-border-default: #3a3a3a; - --es-border-subtle: #1a1a1a; - --es-border-strong: #4a4a4a; - - --es-primary: #3b82f6; - --es-primary-hover: #2563eb; - --es-success: #4ade80; - --es-warning: #f59e0b; - --es-error: #ef4444; - --es-info: #3b82f6; - - --es-selected: #3d5a80; - --es-selected-hover: #4a6a90; -} - -body { - background: var(--es-bg-base) !important; -} - -html, -html.dark { - --vp-c-bg: var(--es-bg-base); - --vp-c-bg-soft: var(--es-bg-elevated); - --vp-c-bg-mute: var(--es-bg-overlay); - --vp-c-bg-alt: var(--es-bg-sidebar); - --vp-c-text-1: var(--es-text-primary); - --vp-c-text-2: var(--es-text-tertiary); - --vp-c-text-3: var(--es-text-muted); - --vp-c-divider: var(--es-border-default); - --vp-c-divider-light: var(--es-border-subtle); -} - -html:not(.dark) { - --vp-c-bg: var(--es-bg-base) !important; - --vp-c-bg-soft: var(--es-bg-elevated) !important; - --vp-c-bg-mute: var(--es-bg-overlay) !important; - --vp-c-bg-alt: var(--es-bg-sidebar) !important; - --vp-c-text-1: var(--es-text-primary) !important; - --vp-c-text-2: var(--es-text-tertiary) !important; - --vp-c-text-3: var(--es-text-muted) !important; -} - -.VPNav { - background: var(--es-bg-header) !important; - border-bottom: 1px solid var(--es-border-subtle) !important; -} - -.VPNav .VPNavBar { - background: var(--es-bg-header) !important; -} - -.VPNav .VPNavBar .wrapper { - background: var(--es-bg-header) !important; -} - -.VPNav .VPNavBar::before, -.VPNav .VPNavBar::after { - display: none !important; -} - -.VPNavBar { - background: var(--es-bg-header) !important; -} - -.VPNavBar::before { - display: none !important; -} - -.VPNavBarTitle .title { - color: var(--es-text-primary); - font-weight: 500; - font-size: var(--es-font-base); -} - -.VPNavBarMenuLink { - color: var(--es-text-secondary) !important; - font-size: var(--es-font-sm) !important; - font-weight: 400 !important; -} - -.VPNavBarMenuLink:hover { - color: var(--es-text-primary) !important; -} - -.VPNavBarMenuLink.active { - color: var(--es-text-primary) !important; -} - -.VPNavBarSearch .DocSearch-Button { - background: var(--es-bg-input) !important; - border: 1px solid var(--es-border-default) !important; - border-radius: 2px; - height: 26px; -} - -.VPSidebar { - background: var(--es-bg-sidebar) !important; - border-right: 1px solid var(--es-border-subtle) !important; -} - -.VPSidebarItem.level-0 > .item { - padding: 8px 0 4px 0; -} - -.VPSidebarItem.level-0 > .item > .text { - font-weight: 600; - font-size: var(--es-font-xs); - color: var(--es-text-secondary); - text-transform: uppercase; - letter-spacing: 0.05em; -} - -.VPSidebarItem .link { - padding: 4px 8px; - margin: 1px 0; - border-radius: 2px; - color: var(--es-text-primary); - font-size: var(--es-font-sm); - transition: all 0.1s ease; - border-left: 2px solid transparent; -} - -.VPSidebarItem .link:hover { - background: rgba(255, 255, 255, 0.03); - color: var(--es-text-inverse); -} - -.VPSidebarItem.is-active > .item > .link { - background: var(--es-selected); - color: var(--es-text-inverse); - border-left: 2px solid var(--es-primary); -} - -.VPSidebarItem.is-active > .item > .link:hover { - background: var(--es-selected-hover); -} - -.VPSidebarItem.level-1 .link { - padding-left: 20px; - font-size: var(--es-font-sm); -} - -.VPSidebarItem.level-2 .link { - padding-left: 32px; - font-size: var(--es-font-sm); -} - -.VPSidebarItem .caret { - color: var(--es-text-secondary); -} - -.VPSidebarItem .caret:hover { - color: var(--es-text-primary); -} - -.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; -} - -.VPNavBar .content { - background: var(--es-bg-header) !important; -} - -.VPNavBar .content-body { - background: var(--es-bg-header) !important; -} - -.VPNavBar .divider { - display: none; -} - -.VPLocalNav { - background: var(--es-bg-header) !important; - border-bottom: 1px solid var(--es-border-subtle) !important; -} - -.VPNavScreenMenu { - background: var(--es-bg-base) !important; -} - -.VPNavScreen { - background: var(--es-bg-base) !important; -} - -.curtain { - display: none !important; -} - -.VPNav .curtain, -.VPNavBar .curtain { - display: none !important; -} - -[class*="curtain"] { - display: none !important; -} - -.VPNav > div::before, -.VPNav > div::after { - display: none !important; -} - -.vp-doc { - color: var(--es-text-primary); -} - -.vp-doc h1 { - font-size: var(--es-font-lg); - font-weight: 600; - color: var(--es-text-inverse); - border-bottom: none; - padding-bottom: 0; - margin-bottom: 16px; - line-height: 1.3; -} - -.vp-doc h2 { - font-size: var(--es-font-md); - font-weight: 600; - color: var(--es-text-inverse); - border-bottom: none; - padding-bottom: 0; - margin-top: 32px; - margin-bottom: 12px; - padding: 6px 12px; - background: var(--es-bg-header); - border-left: 3px solid var(--es-primary); -} - -.vp-doc h3 { - font-size: var(--es-font-base); - font-weight: 600; - color: var(--es-text-primary); - margin-top: 20px; - margin-bottom: 8px; -} - -.vp-doc p { - color: var(--es-text-primary); - line-height: 1.7; - font-size: var(--es-font-base); - margin: 12px 0; -} - -.vp-doc ul, -.vp-doc ol { - padding-left: 20px; - margin: 12px 0; -} - -.vp-doc li { - line-height: 1.7; - margin: 4px 0; - color: var(--es-text-primary); - font-size: var(--es-font-base); -} - -.vp-doc li::marker { - color: var(--es-text-secondary); -} - -.vp-doc strong { - color: var(--es-text-primary); - font-weight: 600; -} - -.vp-doc a { - color: var(--es-primary); - text-decoration: none; -} - -.vp-doc a:hover { - text-decoration: underline; -} - -.VPDocAside { - padding-left: 16px; - border-left: 1px solid var(--es-border-subtle); -} - -.VPDocAsideOutline { - padding: 0; - border: none !important; -} - -.VPDocAsideOutline .content { - border: none !important; - padding-left: 0 !important; -} - -.VPDocAsideOutline .outline-title { - font-size: var(--es-font-xs); - font-weight: 600; - text-transform: uppercase; - letter-spacing: 0.05em; - color: var(--es-text-secondary); - padding-bottom: 8px; -} - -.VPDocAsideOutline .outline-link { - color: var(--es-text-secondary); - font-size: var(--es-font-xs); - padding: 4px 0; - line-height: 1.4; - display: block; -} - -.VPDocAsideOutline .outline-link:hover { - color: var(--es-text-primary); -} - -.VPDocAsideOutline .outline-link.active { - color: var(--es-primary); -} - -.VPDocAsideOutline .outline-marker { - display: none; -} - -div[class*='language-'] { - background: var(--es-bg-inset) !important; - border: 1px solid var(--es-border-default); - border-radius: 2px; - margin: 12px 0; -} - -.vp-code-group .tabs { - background: var(--es-bg-header); - border-bottom: 1px solid var(--es-border-subtle); -} - -.vp-doc :not(pre) > code { - background: var(--es-bg-input); - color: var(--es-primary); - padding: 2px 6px; - border-radius: 2px; - font-size: var(--es-font-xs); -} - -.vp-doc table { - display: table; - width: 100%; - background: transparent; - border: none; - border-collapse: collapse; - margin: 16px 0; - font-size: var(--es-font-sm); -} - -.vp-doc tr { - border-bottom: 1px solid var(--es-border-subtle); - background: transparent; -} - -.vp-doc tr:last-child { - border-bottom: none; -} - -.vp-doc tr:hover { - background: rgba(255, 255, 255, 0.02); -} - -.vp-doc th { - background: var(--es-bg-header); - font-weight: 600; - font-size: var(--es-font-xs); - color: var(--es-text-secondary); - text-align: left; - padding: 8px 12px; - border-bottom: 1px solid var(--es-border-subtle); - text-transform: uppercase; - letter-spacing: 0.05em; -} - -.vp-doc td { - font-size: var(--es-font-sm); - color: var(--es-text-primary); - padding: 8px 12px; - vertical-align: top; - line-height: 1.5; -} - -.vp-doc td:first-child { - font-weight: 500; - color: var(--es-text-primary); - min-width: 100px; -} - -.vp-doc .warning, -.vp-doc .custom-block.warning { - background: rgba(245, 158, 11, 0.08); - border: none; - border-left: 3px solid var(--es-warning); - border-radius: 0 2px 2px 0; - padding: 10px 12px; - margin: 16px 0; -} - -.vp-doc .warning .custom-block-title, -.vp-doc .custom-block.warning .custom-block-title { - color: var(--es-warning); - font-weight: 600; - font-size: var(--es-font-xs); - margin-bottom: 4px; -} - -.vp-doc .warning p { - color: var(--es-text-primary); - margin: 0; - font-size: var(--es-font-xs); -} - -.vp-doc .tip, -.vp-doc .custom-block.tip { - background: rgba(59, 130, 246, 0.08); - border: none; - border-left: 3px solid var(--es-primary); - border-radius: 0 2px 2px 0; - padding: 10px 12px; - margin: 16px 0; -} - -.vp-doc .tip .custom-block-title, -.vp-doc .custom-block.tip .custom-block-title { - color: var(--es-primary); - font-weight: 600; - font-size: var(--es-font-xs); - margin-bottom: 4px; -} - -.vp-doc .tip p { - color: var(--es-text-primary); - margin: 0; - font-size: var(--es-font-xs); -} - -.vp-doc .info, -.vp-doc .custom-block.info { - background: rgba(74, 222, 128, 0.08); - border: none; - border-left: 3px solid var(--es-success); - border-radius: 0 2px 2px 0; - padding: 10px 12px; - margin: 16px 0; -} - -.vp-doc .info .custom-block-title, -.vp-doc .custom-block.info .custom-block-title { - color: var(--es-success); - font-weight: 600; - font-size: var(--es-font-xs); - margin-bottom: 4px; -} - -.vp-doc .danger, -.vp-doc .custom-block.danger { - background: rgba(239, 68, 68, 0.08); - border: none; - border-left: 3px solid var(--es-error); - border-radius: 0 2px 2px 0; - padding: 10px 12px; - margin: 16px 0; -} - -.vp-doc .danger .custom-block-title, -.vp-doc .custom-block.danger .custom-block-title { - color: var(--es-error); - font-weight: 600; - font-size: var(--es-font-xs); - margin-bottom: 4px; -} - -.vp-doc .card { - background: var(--es-bg-sidebar); - border: 1px solid var(--es-border-subtle); - border-radius: 4px; - padding: 12px; - margin: 16px 0; -} - -.vp-doc .card-title { - font-size: var(--es-font-sm); - font-weight: 600; - color: var(--es-text-primary); - margin-bottom: 6px; -} - -.vp-doc .card-description { - font-size: var(--es-font-xs); - color: var(--es-text-muted); - line-height: 1.5; -} - -.vp-doc .tag { - display: inline-block; - padding: 2px 8px; - background: transparent; - border: 1px solid var(--es-border-default); - border-radius: 2px; - color: var(--es-text-secondary); - font-size: var(--es-font-xs); - margin-right: 4px; - margin-bottom: 4px; -} - -.VPFooter { - background: var(--es-bg-sidebar) !important; - border-top: 1px solid var(--es-border-subtle) !important; -} - -::-webkit-scrollbar { - width: 8px; - height: 8px; -} - -::-webkit-scrollbar-track { - background: var(--es-bg-card); -} - -::-webkit-scrollbar-thumb { - background: var(--es-border-strong); - border-radius: 4px; - border: 2px solid var(--es-bg-card); -} - -::-webkit-scrollbar-thumb:hover { - background: #5a5a5a; -} - -::-webkit-scrollbar-corner { - background: transparent; -} - -.home-container { - max-width: 1000px; - margin: 0 auto; - padding: 0 16px; -} - -.home-section { - padding: 32px 0; -} - -@media (max-width: 960px) { - .VPDoc .content { - padding: 16px !important; - } -} diff --git a/docs/.vitepress/theme/index.js b/docs/.vitepress/theme/index.js deleted file mode 100644 index 07d42c8a..00000000 --- a/docs/.vitepress/theme/index.js +++ /dev/null @@ -1,14 +0,0 @@ -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' - -export default { - extends: DefaultTheme, - enhanceApp({ app }) { - app.component('ParticleHero', ParticleHero) - app.component('ParticleHeroEn', ParticleHeroEn) - app.component('FeatureCard', FeatureCard) - } -} diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..1b7f5c3d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,49 @@ +# Starlight Starter Kit: Basics + +[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build) + +``` +npm create astro@latest -- --template starlight +``` + +> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun! + +## 🚀 Project Structure + +Inside of your Astro + Starlight project, you'll see the following folders and files: + +``` +. +├── public/ +├── src/ +│ ├── assets/ +│ ├── content/ +│ │ └── docs/ +│ └── content.config.ts +├── astro.config.mjs +├── package.json +└── tsconfig.json +``` + +Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name. + +Images can be added to `src/assets/` and embedded in Markdown with a relative link. + +Static assets, like favicons, can be placed in the `public/` directory. + +## 🧞 Commands + +All commands are run from the root of the project, from a terminal: + +| Command | Action | +| :------------------------ | :----------------------------------------------- | +| `npm install` | Installs dependencies | +| `npm run dev` | Starts local dev server at `localhost:4321` | +| `npm run build` | Build your production site to `./dist/` | +| `npm run preview` | Preview your build locally, before deploying | +| `npm run astro ...` | Run CLI commands like `astro add`, `astro check` | +| `npm run astro -- --help` | Get help using the Astro CLI | + +## 👀 Want to learn more? + +Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat). diff --git a/docs/architecture/material-system-refactor.md b/docs/architecture/material-system-refactor.md deleted file mode 100644 index b43a8383..00000000 --- a/docs/architecture/material-system-refactor.md +++ /dev/null @@ -1,663 +0,0 @@ -# ESEngine 材质系统统一架构重构方案 - -## 问题概述 - -当前 UI 和 Scene (Sprite) 两套渲染系统存在大量代码重复： - -| 重复项 | Sprite | UI | 重复度 | -|--------|--------|----|----| -| 材质属性覆盖接口 | `MaterialPropertyOverride` | `UIMaterialPropertyOverride` | 100% | -| 材质方法 (12个) | `SpriteComponent` | `UIRenderComponent` | 100% | -| ShinyEffect 组件 | `ShinyEffectComponent` | `UIShinyEffectComponent` | 99% | -| ShinyEffect 系统 | `ShinyEffectSystem` | `UIShinyEffectSystem` | 98% | - -**根本原因**：缺乏统一的材质覆盖接口抽象层。 - ---- - -## 一、统一材质覆盖接口 - -### 1.1 定义通用接口 - -在 `@esengine/material-system` 包中定义统一接口： - -```typescript -// packages/material-system/src/interfaces/IMaterialOverridable.ts - -/** - * Material property override definition. - * 材质属性覆盖定义。 - */ -export interface MaterialPropertyOverride { - type: 'float' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'int'; - value: number | number[]; -} - -export type MaterialOverrides = Record; - -/** - * Interface for components that support material property overrides. - * 支持材质属性覆盖的组件接口。 - */ -export interface IMaterialOverridable { - /** Material GUID for asset reference | 材质资产引用的 GUID */ - materialGuid: string; - - /** Current material overrides | 当前材质覆盖 */ - readonly materialOverrides: MaterialOverrides; - - /** Get current material ID | 获取当前材质 ID */ - getMaterialId(): number; - - /** Set material ID | 设置材质 ID */ - setMaterialId(id: number): void; - - // Uniform setters - setOverrideFloat(name: string, value: number): this; - setOverrideVec2(name: string, x: number, y: number): this; - setOverrideVec3(name: string, x: number, y: number, z: number): this; - setOverrideVec4(name: string, x: number, y: number, z: number, w: number): this; - setOverrideColor(name: string, r: number, g: number, b: number, a?: number): this; - setOverrideInt(name: string, value: number): this; - - // Uniform getters - getOverride(name: string): MaterialPropertyOverride | undefined; - removeOverride(name: string): this; - clearOverrides(): this; - hasOverrides(): boolean; -} -``` - -### 1.2 创建 Mixin 实现 - -使用 Mixin 模式避免代码重复： - -```typescript -// packages/material-system/src/mixins/MaterialOverridableMixin.ts - -import type { MaterialPropertyOverride, MaterialOverrides } from '../interfaces/IMaterialOverridable'; - -/** - * Mixin that provides material override functionality. - * 提供材质覆盖功能的 Mixin。 - */ -export function MaterialOverridableMixin {}>(Base: TBase) { - return class extends Base { - materialGuid: string = ''; - private _materialId: number = 0; - private _materialOverrides: MaterialOverrides = {}; - - get materialOverrides(): MaterialOverrides { - return this._materialOverrides; - } - - getMaterialId(): number { - return this._materialId; - } - - setMaterialId(id: number): void { - this._materialId = id; - } - - setOverrideFloat(name: string, value: number): this { - this._materialOverrides[name] = { type: 'float', value }; - return this; - } - - setOverrideVec2(name: string, x: number, y: number): this { - this._materialOverrides[name] = { type: 'vec2', value: [x, y] }; - return this; - } - - setOverrideVec3(name: string, x: number, y: number, z: number): this { - this._materialOverrides[name] = { type: 'vec3', value: [x, y, z] }; - return this; - } - - setOverrideVec4(name: string, x: number, y: number, z: number, w: number): this { - this._materialOverrides[name] = { type: 'vec4', value: [x, y, z, w] }; - return this; - } - - setOverrideColor(name: string, r: number, g: number, b: number, a: number = 1.0): this { - this._materialOverrides[name] = { type: 'color', value: [r, g, b, a] }; - return this; - } - - setOverrideInt(name: string, value: number): this { - this._materialOverrides[name] = { type: 'int', value: Math.floor(value) }; - return this; - } - - getOverride(name: string): MaterialPropertyOverride | undefined { - return this._materialOverrides[name]; - } - - removeOverride(name: string): this { - delete this._materialOverrides[name]; - return this; - } - - clearOverrides(): this { - this._materialOverrides = {}; - return this; - } - - hasOverrides(): boolean { - return Object.keys(this._materialOverrides).length > 0; - } - }; -} -``` - ---- - -## 二、Shader Property 元数据系统 - -### 2.1 定义属性元数据接口 - -```typescript -// packages/material-system/src/interfaces/IShaderProperty.ts - -/** - * Shader property UI metadata. - * 着色器属性 UI 元数据。 - */ -export interface ShaderPropertyMeta { - /** Property type | 属性类型 */ - type: 'float' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'int' | 'texture'; - - /** Display label (supports i18n key) | 显示标签（支持 i18n 键） */ - label: string; - - /** Property group for organization | 属性分组 */ - group?: string; - - /** Default value | 默认值 */ - default?: number | number[] | string; - - // Numeric constraints - min?: number; - max?: number; - step?: number; - - /** UI hints | UI 提示 */ - hint?: 'range' | 'angle' | 'hdr' | 'normal'; - - /** Tooltip description | 工具提示描述 */ - tooltip?: string; - - /** Whether to hide in inspector | 是否在检查器中隐藏 */ - hidden?: boolean; -} - -/** - * Extended shader definition with property metadata. - * 带属性元数据的扩展着色器定义。 - */ -export interface ShaderAssetDefinition { - /** Shader name | 着色器名称 */ - name: string; - - /** Display name for UI | UI 显示名称 */ - displayName?: string; - - /** Shader description | 着色器描述 */ - description?: string; - - /** Vertex shader source (inline or path) | 顶点着色器源（内联或路径）*/ - vertexSource: string; - - /** Fragment shader source (inline or path) | 片段着色器源（内联或路径）*/ - fragmentSource: string; - - /** Property metadata for inspector | 检查器属性元数据 */ - properties?: Record; - - /** Render queue / order | 渲染队列/顺序 */ - renderQueue?: number; - - /** Preset blend mode | 预设混合模式 */ - blendMode?: 'alpha' | 'additive' | 'multiply' | 'opaque'; -} -``` - -### 2.2 .shader 资产文件格式 - -```json -{ - "$schema": "esengine://schemas/shader.json", - "version": 1, - "name": "Shiny", - "displayName": "闪光效果 | Shiny Effect", - "description": "扫光高亮动画着色器 | Sweeping highlight animation shader", - - "vertexSource": "./shaders/sprite.vert", - "fragmentSource": "./shaders/shiny.frag", - - "blendMode": "alpha", - "renderQueue": 2000, - - "properties": { - "u_shinyProgress": { - "type": "float", - "label": "进度 | Progress", - "group": "Animation", - "default": 0, - "min": 0, - "max": 1, - "step": 0.01, - "hidden": true - }, - "u_shinyWidth": { - "type": "float", - "label": "宽度 | Width", - "group": "Effect", - "default": 0.25, - "min": 0, - "max": 1, - "step": 0.01, - "tooltip": "闪光带宽度 | Width of the shiny band" - }, - "u_shinyRotation": { - "type": "float", - "label": "角度 | Rotation", - "group": "Effect", - "default": 2.25, - "min": 0, - "max": 6.28, - "step": 0.01, - "hint": "angle" - }, - "u_shinySoftness": { - "type": "float", - "label": "柔和度 | Softness", - "group": "Effect", - "default": 1.0, - "min": 0, - "max": 1, - "step": 0.01 - }, - "u_shinyBrightness": { - "type": "float", - "label": "亮度 | Brightness", - "group": "Effect", - "default": 1.0, - "min": 0, - "max": 2, - "step": 0.01 - }, - "u_shinyGloss": { - "type": "float", - "label": "光泽度 | Gloss", - "group": "Effect", - "default": 1.0, - "min": 0, - "max": 1, - "step": 0.01, - "tooltip": "0=白色高光, 1=带颜色 | 0=white shine, 1=color-tinted" - } - } -} -``` - ---- - -## 三、统一效果组件/系统架构 - -### 3.1 抽取通用 ShinyEffect 基类 - -```typescript -// packages/material-system/src/effects/BaseShinyEffect.ts - -import { Component, Property, Serializable, Serialize } from '@esengine/ecs-framework'; - -/** - * Base shiny effect configuration (shared between UI and Sprite). - * 基础闪光效果配置（UI 和 Sprite 共享）。 - */ -export abstract class BaseShinyEffect extends Component { - // ============= Effect Parameters ============= - @Serialize() - @Property({ type: 'number', label: 'Width', min: 0, max: 1, step: 0.01 }) - public width: number = 0.25; - - @Serialize() - @Property({ type: 'number', label: 'Rotation', min: 0, max: 360, step: 1 }) - public rotation: number = 129; - - @Serialize() - @Property({ type: 'number', label: 'Softness', min: 0, max: 1, step: 0.01 }) - public softness: number = 1.0; - - @Serialize() - @Property({ type: 'number', label: 'Brightness', min: 0, max: 2, step: 0.01 }) - public brightness: number = 1.0; - - @Serialize() - @Property({ type: 'number', label: 'Gloss', min: 0, max: 2, step: 0.01 }) - public gloss: number = 1.0; - - // ============= Animation Settings ============= - @Serialize() - @Property({ type: 'boolean', label: 'Play' }) - public play: boolean = true; - - @Serialize() - @Property({ type: 'boolean', label: 'Loop' }) - public loop: boolean = true; - - @Serialize() - @Property({ type: 'number', label: 'Duration', min: 0.1, step: 0.1 }) - public duration: number = 2.0; - - @Serialize() - @Property({ type: 'number', label: 'Loop Delay', min: 0, step: 0.1 }) - public loopDelay: number = 2.0; - - @Serialize() - @Property({ type: 'number', label: 'Initial Delay', min: 0, step: 0.1 }) - public initialDelay: number = 0; - - // ============= Runtime State ============= - public progress: number = 0; - public elapsedTime: number = 0; - public inDelay: boolean = false; - public delayRemaining: number = 0; - public initialDelayProcessed: boolean = false; - - reset(): void { - this.progress = 0; - this.elapsedTime = 0; - this.inDelay = false; - this.delayRemaining = 0; - this.initialDelayProcessed = false; - } - - start(): void { - this.reset(); - this.play = true; - } - - stop(): void { - this.play = false; - } - - getRotationRadians(): number { - return this.rotation * Math.PI / 180; - } -} -``` - -### 3.2 通用动画更新逻辑 - -```typescript -// packages/material-system/src/effects/ShinyEffectAnimator.ts - -import type { BaseShinyEffect } from './BaseShinyEffect'; -import type { IMaterialOverridable } from '../interfaces/IMaterialOverridable'; -import { BuiltInShaders } from '../types'; - -/** - * Shared animator logic for shiny effect. - * 闪光效果共享的动画逻辑。 - */ -export class ShinyEffectAnimator { - /** - * Update animation state. - * 更新动画状态。 - */ - static updateAnimation(shiny: BaseShinyEffect, deltaTime: number): void { - if (!shiny.initialDelayProcessed && shiny.initialDelay > 0) { - shiny.delayRemaining = shiny.initialDelay; - shiny.inDelay = true; - shiny.initialDelayProcessed = true; - } - - if (shiny.inDelay) { - shiny.delayRemaining -= deltaTime; - if (shiny.delayRemaining <= 0) { - shiny.inDelay = false; - shiny.elapsedTime = 0; - } - return; - } - - shiny.elapsedTime += deltaTime; - shiny.progress = Math.min(shiny.elapsedTime / shiny.duration, 1.0); - - if (shiny.progress >= 1.0) { - if (shiny.loop) { - shiny.inDelay = true; - shiny.delayRemaining = shiny.loopDelay; - shiny.progress = 0; - shiny.elapsedTime = 0; - } else { - shiny.play = false; - shiny.progress = 1.0; - } - } - } - - /** - * Apply material overrides. - * 应用材质覆盖。 - */ - static applyMaterialOverrides(shiny: BaseShinyEffect, target: IMaterialOverridable): void { - if (target.getMaterialId() === 0) { - target.setMaterialId(BuiltInShaders.Shiny); - } - - target.setOverrideFloat('u_shinyProgress', shiny.progress); - target.setOverrideFloat('u_shinyWidth', shiny.width); - target.setOverrideFloat('u_shinyRotation', shiny.getRotationRadians()); - target.setOverrideFloat('u_shinySoftness', shiny.softness); - target.setOverrideFloat('u_shinyBrightness', shiny.brightness); - target.setOverrideFloat('u_shinyGloss', shiny.gloss); - } -} -``` - ---- - -## 四、Material Inspector 设计 - -### 4.1 组件架构 - -``` -MaterialPropertiesEditor (容器组件) -├── ShaderSelector (着色器选择器) -├── PropertyGroup (属性分组) -│ ├── FloatProperty (浮点属性) -│ ├── VectorProperty (向量属性) -│ ├── ColorProperty (颜色属性) -│ └── TextureProperty (纹理属性) -└── OverrideIndicator (覆盖指示器) -``` - -### 4.2 核心组件 - -```typescript -// packages/editor-app/src/components/inspectors/material/MaterialPropertiesEditor.tsx - -interface MaterialPropertiesEditorProps { - /** Target component implementing IMaterialOverridable */ - target: IMaterialOverridable; - /** Current shader definition with property metadata */ - shaderDef?: ShaderAssetDefinition; - /** Callback when property changes */ - onChange?: (name: string, value: MaterialPropertyOverride) => void; -} - -export const MaterialPropertiesEditor: React.FC = ({ - target, - shaderDef, - onChange -}) => { - // Group properties by their group field - const groupedProps = useMemo(() => { - if (!shaderDef?.properties) return {}; - - const groups: Record> = {}; - for (const [name, meta] of Object.entries(shaderDef.properties)) { - if (meta.hidden) continue; - const group = meta.group || 'Default'; - if (!groups[group]) groups[group] = []; - groups[group].push([name, meta]); - } - return groups; - }, [shaderDef]); - - return ( -
- target.setMaterialId(id)} - /> - - {Object.entries(groupedProps).map(([group, props]) => ( - - {props.map(([name, meta]) => ( - { - applyOverride(target, name, meta.type, value); - onChange?.(name, target.getOverride(name)!); - }} - /> - ))} - - ))} -
- ); -}; -``` - ---- - -## 五、实施计划 - -### Phase 1: 接口层 (1-2 天) - -1. **创建 IMaterialOverridable 接口** (`packages/material-system/src/interfaces/`) -2. **创建 MaterialOverridableMixin** (`packages/material-system/src/mixins/`) -3. **导出新接口** (`packages/material-system/src/index.ts`) - -### Phase 2: 重构现有组件 (2-3 天) - -1. **修改 SpriteComponent**：实现 `IMaterialOverridable`，使用 Mixin -2. **修改 UIRenderComponent**：实现 `IMaterialOverridable`，使用 Mixin -3. **删除重复代码**：移除各组件中的重复材质方法 - -### Phase 3: 统一效果系统 (2-3 天) - -1. **创建 BaseShinyEffect** (`packages/material-system/src/effects/`) -2. **创建 ShinyEffectAnimator** (`packages/material-system/src/effects/`) -3. **重构 ShinyEffectComponent**：继承 BaseShinyEffect -4. **重构 UIShinyEffectComponent**：继承 BaseShinyEffect -5. **重构系统**：使用 ShinyEffectAnimator - -### Phase 4: Shader Property 系统 (2-3 天) - -1. **定义 ShaderPropertyMeta 接口** -2. **扩展 ShaderDefinition** 添加 properties 字段 -3. **创建 ShaderLoader** 支持 .shader 文件 -4. **注册内置着色器属性元数据** - -### Phase 5: Material Inspector (3-4 天) - -1. **创建 MaterialPropertiesEditor 组件** -2. **创建 PropertyField 组件** (Float, Vector, Color, Texture) -3. **集成到现有 Inspector 系统** -4. **支持实时预览** - ---- - -## 六、文件修改清单 - -| 优先级 | 包 | 文件 | 操作 | -|--------|-----|------|------| -| P0 | material-system | `src/interfaces/IMaterialOverridable.ts` | 新建 | -| P0 | material-system | `src/mixins/MaterialOverridableMixin.ts` | 新建 | -| P0 | material-system | `src/interfaces/IShaderProperty.ts` | 新建 | -| P1 | material-system | `src/effects/BaseShinyEffect.ts` | 新建 | -| P1 | material-system | `src/effects/ShinyEffectAnimator.ts` | 新建 | -| P1 | sprite | `src/SpriteComponent.ts` | 重构 | -| P1 | ui | `src/components/UIRenderComponent.ts` | 重构 | -| P2 | sprite | `src/ShinyEffectComponent.ts` | 重构 | -| P2 | ui | `src/components/UIShinyEffectComponent.ts` | 重构 | -| P2 | sprite | `src/systems/ShinyEffectSystem.ts` | 重构 | -| P2 | ui | `src/systems/render/UIShinyEffectSystem.ts` | 重构 | -| P3 | material-system | `src/loaders/ShaderLoader.ts` | 扩展 | -| P3 | editor-app | `src/components/inspectors/material/*` | 新建 | - ---- - -## 七、Transform 组件统一（可选） - -### 7.1 现状分析 - -| 特性 | TransformComponent | UITransformComponent | -|------|-------------------|---------------------| -| **坐标系** | 绝对坐标 (position.x/y/z) | 相对锚点坐标 (x/y + anchor) | -| **尺寸** | ❌ 无 | ✅ width/height + 约束 | -| **锚点系统** | ❌ 无 | ✅ anchorMin/Max | -| **3D 支持** | ✅ IVector3 | ❌ 纯 2D | -| **可见性** | ❌ 无 | ✅ visible, alpha | - -### 7.2 结论 - -**不建议完全合并**，但可提取公共基类： - -```typescript -// packages/engine-core/src/interfaces/ITransformBase.ts - -export interface ITransformBase { - /** 旋转角度（度） | Rotation in degrees */ - rotation: number; - - /** X 缩放 | Scale X */ - scaleX: number; - - /** Y 缩放 | Scale Y */ - scaleY: number; - - /** 本地到世界矩阵 | Local to world matrix */ - readonly localToWorldMatrix: Matrix2D; - - /** 是否需要更新 | Dirty flag */ - isDirty: boolean; - - /** 世界坐标 X | World position X */ - readonly worldX: number; - - /** 世界坐标 Y | World position Y */ - readonly worldY: number; - - /** 世界旋转 | World rotation */ - readonly worldRotation: number; - - /** 世界缩放 X | World scale X */ - readonly worldScaleX: number; - - /** 世界缩放 Y | World scale Y */ - readonly worldScaleY: number; -} -``` - -### 7.3 收益 - -- 渲染系统可以统一处理 `ITransformBase` -- 减少 SpriteRenderSystem 和 UIRenderSystem 的重复 -- Gizmo 系统可以共享变换操作逻辑 - ---- - -## 八、向后兼容性 - -1. **接口兼容**：现有组件的 API 保持不变 -2. **序列化兼容**：不改变现有序列化格式 -3. **渐进迁移**：可分阶段进行，不影响现有功能 diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs new file mode 100644 index 00000000..1a011f8b --- /dev/null +++ b/docs/astro.config.mjs @@ -0,0 +1,178 @@ +// @ts-check +import { defineConfig } from 'astro/config'; +import starlight from '@astrojs/starlight'; +import vue from '@astrojs/vue'; +import tailwindcss from '@tailwindcss/vite'; + +export default defineConfig({ + integrations: [ + starlight({ + title: 'ESEngine', + logo: { + src: './src/assets/logo.svg', + replacesTitle: false, + }, + social: [ + { icon: 'github', label: 'GitHub', href: 'https://github.com/esengine/esengine' } + ], + defaultLocale: 'root', + locales: { + root: { + label: '简体中文', + lang: 'zh-CN', + }, + en: { + label: 'English', + lang: 'en', + }, + }, + sidebar: [ + { + label: '快速开始', + translations: { en: 'Getting Started' }, + items: [ + { label: '快速入门', slug: 'guide/getting-started', translations: { en: 'Quick Start' } }, + { label: '指南概览', slug: 'guide', translations: { en: 'Guide Overview' } }, + ], + }, + { + label: '核心概念', + translations: { en: 'Core Concepts' }, + items: [ + { label: '实体', slug: 'guide/entity', translations: { en: 'Entity' } }, + { label: '层级结构', slug: 'guide/hierarchy', translations: { en: 'Hierarchy' } }, + { + label: '组件', + translations: { en: 'Component' }, + items: [ + { label: '概述', slug: 'guide/component', translations: { en: 'Overview' } }, + { label: '生命周期', slug: 'guide/component/lifecycle', translations: { en: 'Lifecycle' } }, + { label: 'EntityRef 装饰器', slug: 'guide/component/entity-ref', translations: { en: 'EntityRef' } }, + { label: '最佳实践', slug: 'guide/component/best-practices', translations: { en: 'Best Practices' } }, + ], + }, + { + label: '实体查询', + translations: { en: 'Entity Query' }, + items: [ + { label: '概述', slug: 'guide/entity-query', translations: { en: 'Overview' } }, + { label: 'Matcher API', slug: 'guide/entity-query/matcher-api', translations: { en: 'Matcher API' } }, + { label: '编译查询', slug: 'guide/entity-query/compiled-query', translations: { en: 'Compiled Query' } }, + { label: '最佳实践', slug: 'guide/entity-query/best-practices', translations: { en: 'Best Practices' } }, + ], + }, + { + label: '系统', + translations: { en: 'System' }, + items: [ + { label: '概述', slug: 'guide/system', translations: { en: 'Overview' } }, + { label: '系统类型', slug: 'guide/system/types', translations: { en: 'System Types' } }, + { label: '生命周期', slug: 'guide/system/lifecycle', translations: { en: 'Lifecycle' } }, + { label: '命令缓冲区', slug: 'guide/system/command-buffer', translations: { en: 'Command Buffer' } }, + { label: '系统调度', slug: 'guide/system/scheduling', translations: { en: 'Scheduling' } }, + { label: '变更检测', slug: 'guide/system/change-detection', translations: { en: 'Change Detection' } }, + { label: '最佳实践', slug: 'guide/system/best-practices', translations: { en: 'Best Practices' } }, + ], + }, + { label: '场景', slug: 'guide/scene', translations: { en: 'Scene' } }, + { + label: '序列化', + translations: { en: 'Serialization' }, + items: [ + { label: '概述', slug: 'guide/serialization', translations: { en: 'Overview' } }, + { label: '装饰器与继承', slug: 'guide/serialization/decorators', translations: { en: 'Decorators & Inheritance' } }, + { label: '增量序列化', slug: 'guide/serialization/incremental', translations: { en: 'Incremental' } }, + { label: '版本迁移', slug: 'guide/serialization/migration', translations: { en: 'Migration' } }, + { label: '使用场景', slug: 'guide/serialization/use-cases', translations: { en: 'Use Cases' } }, + ], + }, + { label: '事件系统', slug: 'guide/event-system', translations: { en: 'Event System' } }, + { label: '时间与定时器', slug: 'guide/time-and-timers', translations: { en: 'Time & Timers' } }, + { label: '日志系统', slug: 'guide/logging', translations: { en: 'Logging' } }, + ], + }, + { + label: '高级功能', + translations: { en: 'Advanced Features' }, + items: [ + { + label: '服务容器', + translations: { en: 'Service Container' }, + items: [ + { label: '概述', slug: 'guide/service-container', translations: { en: 'Overview' } }, + { label: '内置服务', slug: 'guide/service-container/built-in-services', translations: { en: 'Built-in Services' } }, + { label: '依赖注入', slug: 'guide/service-container/dependency-injection', translations: { en: 'Dependency Injection' } }, + { label: 'PluginServiceRegistry', slug: 'guide/service-container/plugin-service-registry', translations: { en: 'PluginServiceRegistry' } }, + { label: '高级用法', slug: 'guide/service-container/advanced', translations: { en: 'Advanced' } }, + ], + }, + { label: '插件系统', slug: 'guide/plugin-system', translations: { en: 'Plugin System' } }, + { label: 'Worker 系统', slug: 'guide/worker-system', translations: { en: 'Worker System' } }, + ], + }, + { + label: '平台适配器', + translations: { en: 'Platform Adapters' }, + items: [ + { label: '概览', slug: 'guide/platform-adapter', translations: { en: 'Overview' } }, + { label: '浏览器', slug: 'guide/platform-adapter/browser', translations: { en: 'Browser' } }, + { label: '微信小游戏', slug: 'guide/platform-adapter/wechat-minigame', translations: { en: 'WeChat Mini Game' } }, + { label: 'Node.js', slug: 'guide/platform-adapter/nodejs', translations: { en: 'Node.js' } }, + ], + }, + { + label: '模块', + translations: { en: 'Modules' }, + items: [ + { label: '模块总览', slug: 'modules', translations: { en: 'Modules Overview' } }, + { label: '行为树', slug: 'modules/behavior-tree', translations: { en: 'Behavior Tree' } }, + { label: '状态机', slug: 'modules/fsm', translations: { en: 'FSM' } }, + { label: '定时器', slug: 'modules/timer', translations: { en: 'Timer' } }, + { label: '空间索引', slug: 'modules/spatial', translations: { en: 'Spatial' } }, + { label: '寻路', slug: 'modules/pathfinding', translations: { en: 'Pathfinding' } }, + { label: '蓝图', slug: 'modules/blueprint', translations: { en: 'Blueprint' } }, + { label: '程序生成', slug: 'modules/procgen', translations: { en: 'Procgen' } }, + { label: '网络', slug: 'modules/network', translations: { en: 'Network' } }, + ], + }, + { + label: '示例', + translations: { en: 'Examples' }, + items: [ + { label: '示例总览', slug: 'examples', translations: { en: 'Examples Overview' } }, + { label: 'Worker 系统演示', slug: 'examples/worker-system-demo', translations: { en: 'Worker System Demo' } }, + ], + }, + { + label: 'API 参考', + translations: { en: 'API Reference' }, + autogenerate: { directory: 'api' }, + }, + { + label: '更新日志', + translations: { en: 'Changelog' }, + items: [ + { label: '@esengine/ecs-framework', link: 'https://github.com/esengine/esengine/blob/master/packages/framework/core/CHANGELOG.md', attrs: { target: '_blank' } }, + { label: '@esengine/behavior-tree', link: 'https://github.com/esengine/esengine/blob/master/packages/framework/behavior-tree/CHANGELOG.md', attrs: { target: '_blank' } }, + { label: '@esengine/fsm', link: 'https://github.com/esengine/esengine/blob/master/packages/framework/fsm/CHANGELOG.md', attrs: { target: '_blank' } }, + { label: '@esengine/timer', link: 'https://github.com/esengine/esengine/blob/master/packages/framework/timer/CHANGELOG.md', attrs: { target: '_blank' } }, + { label: '@esengine/network', link: 'https://github.com/esengine/esengine/blob/master/packages/framework/network/CHANGELOG.md', attrs: { target: '_blank' } }, + { label: '@esengine/cli', link: 'https://github.com/esengine/esengine/blob/master/packages/tools/cli/CHANGELOG.md', attrs: { target: '_blank' } }, + ], + }, + ], + customCss: ['./src/styles/custom.css'], + head: [ + { tag: 'meta', attrs: { name: 'theme-color', content: '#646cff' } }, + ], + components: { + Head: './src/components/Head.astro', + ThemeSelect: './src/components/ThemeSelect.astro', + }, + }), + vue(), + ], + vite: { + plugins: [tailwindcss()], + }, +}); \ No newline at end of file diff --git a/docs/changelog.md b/docs/changelog.md deleted file mode 100644 index eb1ae4fd..00000000 --- a/docs/changelog.md +++ /dev/null @@ -1,293 +0,0 @@ -# Changelog - -本文档记录 `@esengine/ecs-framework` 核心库的版本更新历史。 - ---- - -## v2.4.2 (2025-12-25) - -### Features - -- **IncrementalSerializer 实体过滤**: 增量序列化支持 `entityFilter` 选项 (#335) - - 创建快照时可按条件过滤实体 - - 支持按标签、组件类型等自定义过滤逻辑 - - 适用于只同步部分实体的场景（如只同步玩家） - -```typescript -// 只快照玩家实体 -const snapshot = IncrementalSerializer.createSnapshot(scene, { - entityFilter: (entity) => entity.tag === PLAYER_TAG -}); - -// 只快照有特定组件的实体 -const snapshot = IncrementalSerializer.createSnapshot(scene, { - entityFilter: (entity) => entity.hasComponent(PlayerMarker) -}); -``` - -### Refactor - -- 优化 `PlatformWorkerPool` 代码规范，提取为独立模块 (#335) -- 优化 `WorkerEntitySystem` 实现，改进代码结构 (#334) -- 代码规范化与依赖清理 (#317) -- 代码结构优化，添加 `GlobalTypes.ts` 统一类型定义 (#316) - ---- - -## v2.4.1 (2025-12-23) - -### Bug Fixes - -- 修复 `IntervalSystem` 时间累加 bug，间隔计时更加准确 -- 修复 Cocos Creator 兼容性问题，类型导出更完整 - -### Documentation - -- 新增 `Core.paused` 属性文档说明 - ---- - -## v2.4.0 (2025-12-15) - -### Features - -- **EntityHandle 实体句柄**: 轻量级实体引用抽象 (#304) - - 28位索引 + 20位代数（generation）设计，高效复用已销毁实体槽位 - - `EntityHandleManager` 管理句柄生命周期和有效性验证 - - 支持句柄转换为实体引用，检测悬空引用 - -- **SystemScheduler 系统调度器**: 声明式系统调度 (#304) - - 新增 `@Stage(name)` 装饰器指定系统执行阶段 - - 新增 `@Before(SystemClass)` / `@After(SystemClass)` 装饰器声明系统依赖 - - 新增 `@InSet(setName)` 装饰器将系统归入逻辑分组 - - 基于拓扑排序自动解析执行顺序，检测循环依赖 - -- **EpochManager 变更检测**: 帧级变更追踪机制 (#304) - - 跟踪组件添加/修改时间戳（epoch） - - 支持查询"自上次检查以来变化的组件" - - 适用于脏检测、增量更新等优化场景 - -- **CompiledQuery 编译查询**: 预编译类型安全查询 (#304) - - 编译时生成优化的查询逻辑，减少运行时开销 - - 完整的 TypeScript 类型推断支持 - - 支持 `With`、`Without`、`Changed` 等查询条件组合 - -- **PluginServiceRegistry**: 类型安全的插件服务注册表 (#300) - - 通过 `Core.pluginServices` 访问 - - 支持 `ServiceToken` 模式获取服务 - -- **组件自动注册**: `@ECSComponent` 装饰器增强 (#302) - - 装饰器现在自动注册到 `ComponentRegistry` - - 解决 `Decorators ↔ ComponentRegistry` 循环依赖 - - 新建 `ComponentTypeUtils.ts` 作为底层无依赖模块 - -### API Changes - -- `EntitySystem` 添加 `getBefore()` / `getAfter()` / `getSets()` getter 方法 -- `Entity` 添加 `markDirty()` 辅助方法用于手动触发变更检测 -- `IScene` 添加 `epochManager` 属性 -- `CommandBuffer.pendingCount` 修正为返回实际操作数（而非实体数） - -### Documentation - -- 更新系统调度文档，添加声明式依赖配置章节 -- 更新实体查询文档，添加编译查询使用说明 - ---- - -## v2.3.2 (2025-12-08) - -### Features - -- **微信小游戏 Worker 支持**: 添加对微信小游戏平台 Worker 的完整支持 (#297) - - 新增 `workerScriptPath` 配置项，支持预编译 Worker 脚本路径 - - 修复微信小游戏 Worker 消息格式差异（`res` 直接是数据，无需 `.data`） - - 适用于微信小游戏等不支持动态脚本的平台 - -### New Package - -- **@esengine/worker-generator** `v1.0.2`: CLI 工具，从 `WorkerEntitySystem` 子类自动生成 Worker 文件 - - 自动扫描并提取 `workerProcess` 方法体 - - 支持 `--wechat` 模式，使用 TypeScript 编译器转换为 ES5 语法 - - 读取代码中的 `workerScriptPath` 配置，生成到指定路径 - - 生成 `worker-mapping.json` 映射文件 - -### Documentation - -- 更新 Worker 系统文档，添加微信小游戏支持章节 -- 新增英文版 Worker 系统文档 (`docs/en/guide/worker-system.md`) - ---- - -## v2.3.1 (2025-12-07) - -### Bug Fixes - -- **类型导出修复**: 修复 v2.3.0 中的类型导出问题 - - 解决 `ServiceToken` 跨包类型兼容性问题 - - 修复 `editor-app` 和 `behavior-tree-editor` 中的类型引用 - ---- - -## v2.3.0 (2025-12-06) ⚠️ DEPRECATED - -> **警告**: 此版本存在类型导出问题，请升级到 v2.3.1 或更高版本。 -> -> **Warning**: This version has type export issues. Please upgrade to v2.3.1 or later. - -### Features - -- **持久化实体**: 添加实体跨场景迁移支持 (#285) - - 新增 `EEntityLifecyclePolicy` 枚举（`SceneLocal`/`Persistent`） - - Entity 添加 `setPersistent()`、`setSceneLocal()`、`isPersistent` API - - Scene 添加 `findPersistentEntities()`、`extractPersistentEntities()`、`receiveMigratedEntities()` - - `SceneManager.setScene()` 自动处理持久化实体迁移 - - 适用场景：全局管理器、玩家角色、跨场景状态保持 - -- **CommandBuffer 延迟命令系统**: 在帧末统一执行实体操作 (#281) - - 支持延迟添加/移除组件、销毁实体、设置实体激活状态 - - 每个系统拥有独立的 `commands` 属性 - - 避免在迭代过程中修改实体列表，防止迭代问题 - - Scene 在 `lateUpdate` 后自动刷新所有命令缓冲区 - -### Performance - -- **ReactiveQuery 快照优化**: 优化实体查询迭代性能 (#281) - - 添加快照机制，避免每帧拷贝数组 - - 只在实体列表变化时创建新快照 - - 静态场景下多个系统共享同一快照 - ---- - -## v2.2.21 (2025-12-05) - -### Bug Fixes - -- **迭代安全修复**: 修复 `process`/`lateProcess` 迭代时组件变化导致跳过实体的问题 (#272) - - 在系统处理过程中添加/移除组件不再导致实体被意外跳过 - -### Performance - -- **HierarchySystem 性能优化**: 优化层级系统避免每帧遍历所有实体 (#279) - - 使用脏实体集合代替每帧遍历所有实体 - - 静态场景下 `process()` 从 O(n) 优化为 O(1) - - 1000 实体静态场景: 81.79μs → 0.07μs (快 1168 倍) - - 10000 实体静态场景: 939.43μs → 0.56μs (快 1677 倍) - - 服务端模拟 (100房间 x 100实体): 2.7ms → 1.4ms 每 tick - ---- - -## v2.2.20 (2025-12-04) - -### Bug Fixes - -- **系统 onAdded 回调修复**: 修复系统 `onAdded` 回调受注册顺序影响的问题 (#270) - - 系统初始化时会对已存在的匹配实体触发 `onAdded` 回调 - - 新增 `matchesEntity(entity)` 方法，用于检查实体是否匹配系统的查询条件 - - Scene 新增 `notifySystemsEntityAdded/Removed` 方法，确保所有系统都能收到实体变更通知 - ---- - -## v2.2.19 (2025-12-03) - -### Features - -- **系统稳定排序**: 添加系统稳定排序支持 (#257) - - 新增 `addOrder` 属性，用于 `updateOrder` 相同时的稳定排序 - - 确保相同优先级的系统按添加顺序执行 - -- **模块配置**: 添加 `module.json` 配置文件 (#256) - - 定义模块 ID、名称、版本等元信息 - - 支持模块依赖声明和导出配置 - ---- - -## v2.2.18 (2025-11-30) - -### Features - -- **高级性能分析器**: 实现全新的性能分析 SDK (#248) - - `ProfilerSDK`: 统一的性能分析接口 - - 手动采样标记 (`beginSample`/`endSample`) - - 自动作用域测量 (`measure`/`measureAsync`) - - 调用层级追踪和调用图生成 - - 计数器和仪表支持 - - `AdvancedProfilerCollector`: 高级性能数据收集器 - - 帧时间统计和历史记录 - - 内存快照和 GC 检测 - - 长任务检测 (Long Task API) - - 性能报告生成 - - `DebugManager`: 调试管理器 - - 统一的调试工具入口 - - 性能分析器集成 - -- **属性装饰器增强**: 扩展 `@serialize` 装饰器功能 (#247) - - 支持更多序列化选项配置 - -### Improvements - -- **EntitySystem 测试覆盖**: 添加完整的系统测试用例 (#240) - - 覆盖实体查询、缓存、生命周期等场景 - -- **Matcher 增强**: 优化匹配器功能 (#240) - - 改进匹配逻辑和性能 - ---- - -## v2.2.17 (2025-11-28) - -### Features - -- **ComponentRegistry 增强**: 添加组件注册表新功能 (#244) - - 支持通过名称注册和查询组件类型 - - 添加组件掩码缓存优化性能 - -- **序列化装饰器改进**: 增强 `@serialize` 装饰器 (#244) - - 支持更灵活的序列化配置 - - 改进嵌套对象序列化 - -- **EntitySystem 生命周期**: 新增系统生命周期方法 (#244) - - `onSceneStart()`: 场景开始时调用 - - `onSceneStop()`: 场景停止时调用 - ---- - -## v2.2.16 (2025-11-27) - -### Features - -- **组件生命周期**: 添加组件生命周期回调支持 (#237) - - `onDeserialized()`: 组件从场景文件加载或快照恢复后调用，用于恢复运行时数据 - -- **ServiceContainer 增强**: 改进服务容器功能 (#237) - - 支持 `Symbol.for()` 模式的服务标识 - - 新增 `@InjectProperty` 属性注入装饰器 - - 改进服务解析和生命周期管理 - -- **SceneSerializer 增强**: 场景序列化器新功能 (#237) - - 支持更多组件类型的序列化 - - 改进反序列化错误处理 - -- **属性装饰器扩展**: 扩展 `@serialize` 装饰器 (#238) - - 支持 `@range`、`@slider` 等编辑器提示 - - 支持 `@dropdown`、`@color` 等 UI 类型 - - 支持 `@asset` 资源引用类型 - -### Improvements - -- **Matcher 测试**: 添加 Matcher 匹配器测试用例 (#240) -- **EntitySystem 测试**: 添加实体系统完整测试覆盖 (#240) - ---- - -## 版本说明 - -- **主版本号**: 重大不兼容更新 -- **次版本号**: 新功能添加（向后兼容） -- **修订版本号**: Bug 修复和小改进 - -## 相关链接 - -- [GitHub Releases](https://github.com/esengine/esengine/releases) -- [NPM Package](https://www.npmjs.com/package/@esengine/ecs-framework) -- [文档首页](./index.md) diff --git a/docs/en/changelog.md b/docs/en/changelog.md deleted file mode 100644 index 56d5079f..00000000 --- a/docs/en/changelog.md +++ /dev/null @@ -1,291 +0,0 @@ -# Changelog - -This document records the version update history of the `@esengine/ecs-framework` core library. - ---- - -## v2.4.2 (2025-12-25) - -### Features - -- **IncrementalSerializer Entity Filter**: Incremental serialization supports `entityFilter` option (#335) - - Filter entities by condition when creating snapshots - - Support custom filter logic by tag, component type, etc. - - Suitable for scenarios that only sync partial entities (e.g., only sync players) - -```typescript -// Only snapshot player entities -const snapshot = IncrementalSerializer.createSnapshot(scene, { - entityFilter: (entity) => entity.tag === PLAYER_TAG -}); - -// Only snapshot entities with specific component -const snapshot = IncrementalSerializer.createSnapshot(scene, { - entityFilter: (entity) => entity.hasComponent(PlayerMarker) -}); -``` - -### Refactor - -- Optimize `PlatformWorkerPool` code style, extract as standalone module (#335) -- Optimize `WorkerEntitySystem` implementation, improve code structure (#334) -- Code standardization and dependency cleanup (#317) -- Code structure optimization, add `GlobalTypes.ts` for unified type definitions (#316) - ---- - -## v2.4.1 (2025-12-23) - -### Bug Fixes - -- Fix `IntervalSystem` time accumulation bug, interval timing is now more accurate -- Fix Cocos Creator compatibility issue, more complete type exports - -### Documentation - -- Add `Core.paused` property documentation - ---- - -## v2.4.0 (2025-12-15) - -### Features - -- **EntityHandle**: Lightweight entity reference abstraction (#304) - - 28-bit index + 20-bit generation design for efficient reuse of destroyed entity slots - - `EntityHandleManager` manages handle lifecycle and validity verification - - Support handle-to-entity conversion with dangling reference detection - -- **SystemScheduler**: Declarative system scheduling (#304) - - New `@Stage(name)` decorator to specify system execution stage - - New `@Before(SystemClass)` / `@After(SystemClass)` decorators to declare dependencies - - New `@InSet(setName)` decorator to group systems logically - - Automatic execution order resolution via topological sort with cycle detection - -- **EpochManager**: Frame-level change detection mechanism (#304) - - Track component add/modify timestamps (epochs) - - Support querying "components changed since last check" - - Suitable for dirty checking, incremental updates, and other optimization scenarios - -- **CompiledQuery**: Pre-compiled type-safe queries (#304) - - Compile-time generated optimized query logic, reducing runtime overhead - - Full TypeScript type inference support - - Support `With`, `Without`, `Changed` and other query condition combinations - -- **PluginServiceRegistry**: Type-safe plugin service registry (#300) - - Accessible via `Core.pluginServices` - - Support `ServiceToken` pattern for service retrieval - -- **Component Auto-Registration**: `@ECSComponent` decorator enhancement (#302) - - Decorator now automatically registers to `ComponentRegistry` - - Resolved `Decorators ↔ ComponentRegistry` circular dependency - - New `ComponentTypeUtils.ts` as low-level dependency-free module - -### API Changes - -- `EntitySystem` adds `getBefore()` / `getAfter()` / `getSets()` getter methods -- `Entity` adds `markDirty()` helper method for manual change detection triggering -- `IScene` adds `epochManager` property -- `CommandBuffer.pendingCount` corrected to return actual operation count (not entity count) - -### Documentation - -- Updated system scheduling documentation with declarative dependency configuration -- Updated entity query documentation with compiled query usage - ---- - -## v2.3.2 (2025-12-08) - -### Features - -- **WeChat Mini Game Worker Support**: Add complete Worker support for WeChat Mini Game platform (#297) - - New `workerScriptPath` config option for pre-compiled Worker script path - - Fix WeChat Mini Game Worker message format difference (`res` is data directly, no `.data` wrapper) - - Applicable to WeChat Mini Game and other platforms that don't support dynamic scripts - -### New Package - -- **@esengine/worker-generator** `v1.0.2`: CLI tool to auto-generate Worker files from `WorkerEntitySystem` subclasses - - Automatically scan and extract `workerProcess` method body - - Support `--wechat` mode, use TypeScript compiler to convert to ES5 syntax - - Read `workerScriptPath` config from code, generate to specified path - - Generate `worker-mapping.json` mapping file - -### Documentation - -- Updated Worker system documentation with WeChat Mini Game support section -- Added English Worker system documentation (`docs/en/guide/worker-system.md`) - ---- - -## v2.3.1 (2025-12-07) - -### Bug Fixes - -- **Type export fix**: Fix type export issues in v2.3.0 - - Resolve `ServiceToken` cross-package type compatibility issues - - Fix type references in `editor-app` and `behavior-tree-editor` - ---- - -## v2.3.0 (2025-12-06) ⚠️ DEPRECATED - -> **Warning**: This version has type export issues. Please upgrade to v2.3.1 or later. - -### Features - -- **Persistent Entity**: Add entity cross-scene migration support (#285) - - New `EEntityLifecyclePolicy` enum (`SceneLocal`/`Persistent`) - - Entity adds `setPersistent()`, `setSceneLocal()`, `isPersistent` API - - Scene adds `findPersistentEntities()`, `extractPersistentEntities()`, `receiveMigratedEntities()` - - `SceneManager.setScene()` automatically handles persistent entity migration - - Use cases: global managers, player characters, cross-scene state persistence - -- **CommandBuffer Deferred Command System**: Execute entity operations uniformly at end of frame (#281) - - Support deferred add/remove components, destroy entities, set entity active state - - Each system has its own `commands` property - - Avoid modifying entity list during iteration, preventing iteration issues - - Scene automatically flushes all command buffers after `lateUpdate` - -### Performance - -- **ReactiveQuery Snapshot Optimization**: Optimize entity query iteration performance (#281) - - Add snapshot mechanism to avoid copying arrays every frame - - Only create new snapshots when entity list changes - - Multiple systems share the same snapshot in static scenes - ---- - -## v2.2.21 (2025-12-05) - -### Bug Fixes - -- **Iteration safety fix**: Fix issue where component changes during `process`/`lateProcess` iteration caused entities to be skipped (#272) - - Adding/removing components during system processing no longer causes entities to be unexpectedly skipped - -### Performance - -- **HierarchySystem optimization**: Optimize hierarchy system to avoid iterating all entities every frame (#279) - - Use dirty entity set instead of iterating all entities - - Static scene `process()` optimized from O(n) to O(1) - - 1000 entities static scene: 81.79μs → 0.07μs (1168x faster) - - 10000 entities static scene: 939.43μs → 0.56μs (1677x faster) - - Server simulation (100 rooms x 100 entities): 2.7ms → 1.4ms per tick - ---- - -## v2.2.20 (2025-12-04) - -### Bug Fixes - -- **System onAdded callback fix**: Fix issue where system `onAdded` callback was affected by registration order (#270) - - System initialization now triggers `onAdded` callback for existing matching entities - - Added `matchesEntity(entity)` method to check if an entity matches the system's query condition - - Scene added `notifySystemsEntityAdded/Removed` methods to ensure all systems receive entity change notifications - ---- - -## v2.2.19 (2025-12-03) - -### Features - -- **System stable sorting**: Add stable sorting support for systems (#257) - - Added `addOrder` property for stable sorting when `updateOrder` is the same - - Ensures systems with same priority execute in add order - -- **Module configuration**: Add `module.json` configuration file (#256) - - Define module ID, name, version and other metadata - - Support module dependency declaration and export configuration - ---- - -## v2.2.18 (2025-11-30) - -### Features - -- **Advanced Performance Profiler**: Implement new performance analysis SDK (#248) - - `ProfilerSDK`: Unified performance analysis interface - - Manual sampling markers (`beginSample`/`endSample`) - - Automatic scope measurement (`measure`/`measureAsync`) - - Call hierarchy tracking and call graph generation - - Counter and gauge support - - `AdvancedProfilerCollector`: Advanced performance data collector - - Frame time statistics and history - - Memory snapshots and GC detection - - Long task detection (Long Task API) - - Performance report generation - - `DebugManager`: Debug manager - - Unified debug tool entry point - - Profiler integration - -- **Property decorator enhancement**: Extend `@serialize` decorator functionality (#247) - - Support more serialization option configurations - -### Improvements - -- **EntitySystem test coverage**: Add complete system test cases (#240) - - Cover entity query, cache, lifecycle scenarios - -- **Matcher enhancement**: Optimize matcher functionality (#240) - - Improved matching logic and performance - ---- - -## v2.2.17 (2025-11-28) - -### Features - -- **ComponentRegistry enhancement**: Add new component registry features (#244) - - Support registering and querying component types by name - - Add component mask caching for performance optimization - -- **Serialization decorator improvements**: Enhance `@serialize` decorator (#244) - - Support more flexible serialization configuration - - Improved nested object serialization - -- **EntitySystem lifecycle**: Add new system lifecycle methods (#244) - - `onSceneStart()`: Called when scene starts - - `onSceneStop()`: Called when scene stops - ---- - -## v2.2.16 (2025-11-27) - -### Features - -- **Component lifecycle**: Add component lifecycle callback support (#237) - - `onDeserialized()`: Called after component is loaded from scene file or snapshot restore, used to restore runtime data - -- **ServiceContainer enhancement**: Improve service container functionality (#237) - - Support `Symbol.for()` pattern for service identifiers - - Added `@InjectProperty` property injection decorator - - Improved service resolution and lifecycle management - -- **SceneSerializer enhancement**: New scene serializer features (#237) - - Support serialization of more component types - - Improved deserialization error handling - -- **Property decorator extension**: Extend `@serialize` decorator (#238) - - Support `@range`, `@slider` and other editor hints - - Support `@dropdown`, `@color` and other UI types - - Support `@asset` resource reference type - -### Improvements - -- **Matcher tests**: Add Matcher test cases (#240) -- **EntitySystem tests**: Add complete entity system test coverage (#240) - ---- - -## Version Notes - -- **Major version**: Breaking changes -- **Minor version**: New features (backward compatible) -- **Patch version**: Bug fixes and improvements - -## Related Links - -- [GitHub Releases](https://github.com/esengine/esengine/releases) -- [NPM Package](https://www.npmjs.com/package/@esengine/ecs-framework) -- [Documentation Home](./index.md) diff --git a/docs/en/guide/system.md b/docs/en/guide/system.md deleted file mode 100644 index dba78ce4..00000000 --- a/docs/en/guide/system.md +++ /dev/null @@ -1,1161 +0,0 @@ -# System Architecture - -In ECS architecture, Systems are where business logic is processed. Systems are responsible for performing operations on entities that have specific component combinations, serving as the logic processing units of ECS architecture. - -## Basic Concepts - -Systems are concrete classes that inherit from the `EntitySystem` abstract base class, used for: -- Defining entity processing logic (such as movement, collision detection, rendering, etc.) -- Filtering entities based on component combinations -- Providing lifecycle management and performance monitoring -- Managing entity add/remove events - -## System Types - -The framework provides several different system base classes: - -### EntitySystem - Base System - -The most basic system class, all other systems inherit from it: - -```typescript -import { EntitySystem, ECSSystem, Matcher } from '@esengine/ecs-framework'; - -@ECSSystem('Movement') -class MovementSystem extends EntitySystem { - constructor() { - // Use Matcher to define entity conditions to process - super(Matcher.all(Position, Velocity)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const position = entity.getComponent(Position); - const velocity = entity.getComponent(Velocity); - - if (position && velocity) { - position.x += velocity.dx * Time.deltaTime; - position.y += velocity.dy * Time.deltaTime; - } - } - } -} -``` - -### ProcessingSystem - Processing System - -Suitable for systems that don't need to process entities individually: - -```typescript -@ECSSystem('Physics') -class PhysicsSystem extends ProcessingSystem { - constructor() { - super(); // No Matcher needed - } - - public processSystem(): void { - // Execute physics world step - this.physicsWorld.step(Time.deltaTime); - } -} -``` - -### PassiveSystem - Passive System - -Passive systems don't actively process, mainly used for listening to entity add and remove events: - -```typescript -@ECSSystem('EntityTracker') -class EntityTrackerSystem extends PassiveSystem { - constructor() { - super(Matcher.all(Health)); - } - - protected onAdded(entity: Entity): void { - console.log(`Health entity added: ${entity.name}`); - } - - protected onRemoved(entity: Entity): void { - console.log(`Health entity removed: ${entity.name}`); - } -} -``` - -### IntervalSystem - Interval System - -Systems that execute at fixed time intervals: - -```typescript -@ECSSystem('AutoSave') -class AutoSaveSystem extends IntervalSystem { - constructor() { - // Execute every 5 seconds - super(5.0, Matcher.all(SaveData)); - } - - protected process(entities: readonly Entity[]): void { - console.log('Executing auto save...'); - // Save game data - this.saveGameData(entities); - } - - private saveGameData(entities: readonly Entity[]): void { - // Save logic - } -} -``` - -### WorkerEntitySystem - Multi-threaded System - -A Web Worker-based multi-threaded processing system, suitable for compute-intensive tasks, capable of fully utilizing multi-core CPU performance. - -Worker systems provide true parallel computing capabilities, support SharedArrayBuffer optimization, and have automatic fallback support. Particularly suitable for physics simulation, particle systems, AI computation, and similar scenarios. - -**For detailed content, please refer to: [Worker System](/guide/worker-system)** - -## Entity Matcher - -Matcher is used to define which entities a system needs to process. It provides flexible condition combinations: - -### Basic Match Conditions - -```typescript -// Must have both Position and Velocity components -const matcher1 = Matcher.all(Position, Velocity); - -// Must have at least one of Health or Shield components -const matcher2 = Matcher.any(Health, Shield); - -// Must not have Dead component -const matcher3 = Matcher.none(Dead); -``` - -### Compound Match Conditions - -```typescript -// Complex combination conditions -const complexMatcher = Matcher.all(Position, Velocity) - .any(Player, Enemy) - .none(Dead, Disabled); - -@ECSSystem('Combat') -class CombatSystem extends EntitySystem { - constructor() { - super(complexMatcher); - } -} -``` - -### Special Match Conditions - -```typescript -// Match by tag -const tagMatcher = Matcher.byTag(1); // Match entities with tag 1 - -// Match by name -const nameMatcher = Matcher.byName("Player"); // Match entities named "Player" - -// Single component match -const componentMatcher = Matcher.byComponent(Health); // Match entities with Health component - -// Match no entities -const nothingMatcher = Matcher.nothing(); // For systems that only need lifecycle callbacks -``` - -### Empty Matcher vs Nothing Matcher - -```typescript -// empty() - Empty condition, matches all entities -const emptyMatcher = Matcher.empty(); - -// nothing() - Matches no entities, for systems that only need lifecycle methods -const nothingMatcher = Matcher.nothing(); - -// Use case: Systems that only need onBegin/onEnd lifecycle -@ECSSystem('FrameTimer') -class FrameTimerSystem extends EntitySystem { - constructor() { - super(Matcher.nothing()); // Process no entities - } - - protected onBegin(): void { - // Execute at the start of each frame, e.g., record frame start time - console.log('Frame started'); - } - - protected process(entities: readonly Entity[]): void { - // Never called because there are no matching entities - } - - protected onEnd(): void { - // Execute at the end of each frame - console.log('Frame ended'); - } -} -``` - -> **Tip**: For more details on Matcher and entity queries, please refer to the [Entity Query System](/guide/entity-query) documentation. - -## System Lifecycle - -Systems provide complete lifecycle callbacks: - -```typescript -@ECSSystem('Example') -class ExampleSystem extends EntitySystem { - protected onInitialize(): void { - console.log('System initialized'); - // Called when system is added to scene, for initializing resources - } - - protected onBegin(): void { - // Called before each frame's processing begins - } - - protected process(entities: readonly Entity[]): void { - // Main processing logic - for (const entity of entities) { - // Process each entity - // Safe to add/remove components here without affecting current iteration - } - } - - protected lateProcess(entities: readonly Entity[]): void { - // Post-processing after main process - // Safe to add/remove components here without affecting current iteration - } - - protected onEnd(): void { - // Called after each frame's processing ends - } - - protected onDestroy(): void { - console.log('System destroyed'); - // Called when system is removed from scene, for cleaning up resources - } -} -``` - -## Entity Event Listening - -Systems can listen for entity add and remove events: - -```typescript -@ECSSystem('EnemyManager') -class EnemyManagerSystem extends EntitySystem { - private enemyCount = 0; - - constructor() { - super(Matcher.all(Enemy, Health)); - } - - protected onAdded(entity: Entity): void { - this.enemyCount++; - console.log(`Enemy joined battle, current enemy count: ${this.enemyCount}`); - - // Can set initial state for new enemies here - const health = entity.getComponent(Health); - if (health) { - health.current = health.max; - } - } - - protected onRemoved(entity: Entity): void { - this.enemyCount--; - console.log(`Enemy removed, remaining enemies: ${this.enemyCount}`); - - // Check if all enemies are defeated - if (this.enemyCount === 0) { - this.scene?.eventSystem.emitSync('all_enemies_defeated'); - } - } -} -``` - -### Important: Timing of onAdded/onRemoved Calls - -> **Note**: `onAdded` and `onRemoved` callbacks are called **synchronously**, executing immediately **before** `addComponent`/`removeComponent` returns. - -This means: - -```typescript -// Wrong: Chain assignment executes after onAdded -const comp = entity.addComponent(new ClickComponent()); -comp.element = this._element; // At this point onAdded has already executed! - -// Correct: Pass initial values through constructor -const comp = entity.addComponent(new ClickComponent(this._element)); - -// Or use the createComponent method -const comp = entity.createComponent(ClickComponent, this._element); -``` - -**Why this design?** - -The event-driven design ensures that `onAdded`/`onRemoved` callbacks are not affected by system registration order. When a component is added, all systems listening for that component receive notification immediately, rather than waiting until the next frame. - -**Best Practices:** - -1. Component initial values should be passed through the **constructor** -2. Don't rely on setting properties after `addComponent` returns -3. If you need to access component properties in `onAdded`, ensure those properties are set at construction time - -### Safely Modifying Components in process/lateProcess - -When iterating entities in `process` or `lateProcess`, you can safely add or remove components without affecting the current iteration: - -```typescript -@ECSSystem('Damage') -class DamageSystem extends EntitySystem { - constructor() { - super(Matcher.all(Health, DamageReceiver)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - const damage = entity.getComponent(DamageReceiver); - - if (health && damage) { - health.current -= damage.amount; - - // Safe: removing component won't affect current iteration - entity.removeComponent(damage); - - if (health.current <= 0) { - // Safe: adding component won't affect current iteration - entity.addComponent(new Dead()); - } - } - } - } -} -``` - -The framework creates a snapshot of the entity list before each `process`/`lateProcess` call, ensuring that component changes during iteration won't cause entities to be skipped or processed multiple times. - -## Command Buffer (CommandBuffer) - -> **v2.3.0+** - -CommandBuffer provides a mechanism for deferred execution of entity operations. When you need to destroy entities or perform other operations that might affect iteration during processing, CommandBuffer allows you to defer these operations to the end of the frame. - -### Basic Usage - -Every EntitySystem has a built-in `commands` property: - -```typescript -@ECSSystem('Damage') -class DamageSystem extends EntitySystem { - constructor() { - super(Matcher.all(Health, DamageReceiver)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - const damage = entity.getComponent(DamageReceiver); - - if (health && damage) { - health.current -= damage.amount; - - // Use command buffer to defer component removal - this.commands.removeComponent(entity, DamageReceiver); - - if (health.current <= 0) { - // Defer adding death marker - this.commands.addComponent(entity, new Dead()); - // Defer entity destruction - this.commands.destroyEntity(entity); - } - } - } - } -} -``` - -### Supported Commands - -| Method | Description | -|--------|-------------| -| `addComponent(entity, component)` | Defer adding component | -| `removeComponent(entity, ComponentType)` | Defer removing component | -| `destroyEntity(entity)` | Defer destroying entity | -| `setEntityActive(entity, active)` | Defer setting entity active state | - -### Execution Timing - -Commands in the buffer are automatically executed after the `lateUpdate` phase of each frame. Execution order matches the order commands were queued. - -``` -Scene Update Flow: -1. onBegin() -2. process() -3. lateProcess() -4. onEnd() -5. flushCommandBuffers() <-- Commands execute here -``` - -### Use Cases - -CommandBuffer is suitable for: - -1. **Destroying entities during iteration**: Avoid modifying collection being traversed -2. **Batch deferred operations**: Merge multiple operations to execute at end of frame -3. **Cross-system coordination**: One system marks, another system responds - -```typescript -// Example: Enemy death system -@ECSSystem('EnemyDeath') -class EnemyDeathSystem extends EntitySystem { - constructor() { - super(Matcher.all(Enemy, Health)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - if (health && health.current <= 0) { - // Play death animation, spawn loot, etc. - this.spawnLoot(entity); - - // Defer destruction, doesn't affect current iteration - this.commands.destroyEntity(entity); - } - } - } - - private spawnLoot(entity: Entity): void { - // Loot spawning logic - } -} -``` - -### Notes - -- Commands skip already destroyed entities (safety check) -- Single command failure doesn't affect other commands -- Commands execute in queue order -- Command queue clears after each `flush()` - -## System Properties and Methods - -### Important Properties - -```typescript -@ECSSystem('Example') -class ExampleSystem extends EntitySystem { - showSystemInfo(): void { - console.log(`System name: ${this.systemName}`); // System name - console.log(`Update order: ${this.updateOrder}`); // Update order - console.log(`Is enabled: ${this.enabled}`); // Enabled state - console.log(`Entity count: ${this.entities.length}`); // Number of matched entities - console.log(`Scene: ${this.scene?.name}`); // Parent scene - } -} -``` - -### Entity Access - -```typescript -protected process(entities: readonly Entity[]): void { - // Method 1: Use entity list from parameter - for (const entity of entities) { - // Process entity - } - - // Method 2: Use this.entities property (same as parameter) - for (const entity of this.entities) { - // Process entity - } -} -``` - -### Controlling System Execution - -```typescript -@ECSSystem('Conditional') -class ConditionalSystem extends EntitySystem { - private shouldProcess = true; - - protected onCheckProcessing(): boolean { - // Return false to skip this processing - return this.shouldProcess && this.entities.length > 0; - } - - public pause(): void { - this.shouldProcess = false; - } - - public resume(): void { - this.shouldProcess = true; - } -} -``` - -## Event System Integration - -Systems can conveniently listen for and send events: - -```typescript -@ECSSystem('GameLogic') -class GameLogicSystem extends EntitySystem { - protected onInitialize(): void { - // Add event listeners (automatically cleaned up when system is destroyed) - this.addEventListener('player_died', this.onPlayerDied.bind(this)); - this.addEventListener('level_complete', this.onLevelComplete.bind(this)); - } - - private onPlayerDied(data: any): void { - console.log('Player died, restarting game'); - // Handle player death logic - } - - private onLevelComplete(data: any): void { - console.log('Level complete, loading next level'); - // Handle level completion logic - } - - protected process(entities: readonly Entity[]): void { - // Send events during processing - for (const entity of entities) { - const health = entity.getComponent(Health); - if (health && health.current <= 0) { - this.scene?.eventSystem.emitSync('entity_died', { entity }); - } - } - } -} -``` - -## Performance Monitoring - -Systems have built-in performance monitoring: - -```typescript -@ECSSystem('Performance') -class PerformanceSystem extends EntitySystem { - protected onEnd(): void { - // Get performance data - const perfData = this.getPerformanceData(); - if (perfData) { - console.log(`Execution time: ${perfData.executionTime.toFixed(2)}ms`); - } - - // Get performance statistics - const stats = this.getPerformanceStats(); - if (stats) { - console.log(`Average execution time: ${stats.averageTime.toFixed(2)}ms`); - } - } - - public resetPerformance(): void { - this.resetPerformanceData(); - } -} -``` - -## System Management - -### Adding Systems to Scene - -The framework provides two ways to add systems: pass an instance or pass a type (automatic dependency injection). - -```typescript -// Add systems in scene subclass -class GameScene extends Scene { - protected initialize(): void { - // Method 1: Pass instance - this.addSystem(new MovementSystem()); - this.addSystem(new RenderSystem()); - - // Method 2: Pass type (automatic dependency injection) - this.addEntityProcessor(PhysicsSystem); - - // Set system update order - const movementSystem = this.getSystem(MovementSystem); - if (movementSystem) { - movementSystem.updateOrder = 1; - } - } -} -``` - -### System Dependency Injection - -Systems implement the `IService` interface and support obtaining other services or systems through dependency injection: - -```typescript -import { ECSSystem, Injectable, Inject } from '@esengine/ecs-framework'; - -@Injectable() -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - constructor( - @Inject(CollisionService) private collision: CollisionService - ) { - super(Matcher.all(Transform, RigidBody)); - } - - protected process(entities: readonly Entity[]): void { - // Use injected service - this.collision.detectCollisions(entities); - } - - // Implement IService interface dispose method - public dispose(): void { - // Clean up resources - } -} - -// Just pass the type when using, framework will auto-inject dependencies -class GameScene extends Scene { - protected initialize(): void { - // Automatic dependency injection - this.addEntityProcessor(PhysicsSystem); - } -} -``` - -Notes: -- Use `@Injectable()` decorator to mark systems that need dependency injection -- Use `@Inject()` decorator in constructor parameters to declare dependencies -- Systems must implement the `dispose()` method (IService interface requirement) -- Use `addEntityProcessor(Type)` instead of `addSystem(new Type())` to enable dependency injection - -### System Update Order - -System execution order is determined by the `updateOrder` property. Lower values execute first: - -```typescript -@ECSSystem('Input') -class InputSystem extends EntitySystem { - constructor() { - super(Matcher.all(InputComponent)); - this.updateOrder = -100; // Input system executes first - } -} - -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - constructor() { - super(Matcher.all(RigidBody)); - this.updateOrder = 0; // Default order - } -} - -@ECSSystem('Render') -class RenderSystem extends EntitySystem { - constructor() { - super(Matcher.all(Sprite, Transform)); - this.updateOrder = 100; // Render system executes last - } -} -``` - -#### Stable Sorting: addOrder - -When multiple systems have the same `updateOrder`, the framework uses `addOrder` (add order) as a secondary sorting criterion to ensure stable and predictable results: - -```typescript -// Both systems have default updateOrder of 0 -@ECSSystem('SystemA') -class SystemA extends EntitySystem { /* ... */ } - -@ECSSystem('SystemB') -class SystemB extends EntitySystem { /* ... */ } - -// Add order determines execution order -scene.addSystem(new SystemA()); // addOrder = 0, executes first -scene.addSystem(new SystemB()); // addOrder = 1, executes second -``` - -> **Note**: `addOrder` is automatically set by the framework when calling `addSystem`, no manual management needed. This ensures systems with the same `updateOrder` execute in their addition order, avoiding random behavior from unstable sorting. - -## Declarative System Scheduling - -> **v2.4.0+** - -In addition to manually controlling execution order with `updateOrder`, the framework provides a declarative system scheduling mechanism that lets you define execution order through dependencies. - -### Scheduling Decorators - -```typescript -import { EntitySystem, ECSSystem, Stage, Before, After, InSet } from '@esengine/ecs-framework'; - -// Use decorators to declare system scheduling -@ECSSystem('Movement') -@Stage('update') // Execute in update stage -@After('InputSystem') // Execute after InputSystem -@Before('RenderSystem') // Execute before RenderSystem -class MovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - } - - protected process(entities: readonly Entity[]): void { - // Movement logic - } -} - -// Use system sets for grouping -@ECSSystem('Physics') -@Stage('update') -@InSet('CoreSystems') // Belongs to CoreSystems set -class PhysicsSystem extends EntitySystem { - // ... -} - -@ECSSystem('Collision') -@Stage('update') -@After('set:CoreSystems') // Execute after all systems in CoreSystems set -class CollisionSystem extends EntitySystem { - // ... -} -``` - -### System Execution Stages - -The framework defines the following system execution stages, executed in order: - -| Stage | Description | Typical Usage | -|-------|-------------|---------------| -| `startup` | Startup stage | One-time initialization | -| `preUpdate` | Pre-update stage | Input handling, state preparation | -| `update` | Main update stage (default) | Core game logic | -| `postUpdate` | Post-update stage | Physics, collision detection | -| `cleanup` | Cleanup stage | Resource cleanup, state reset | - -### Fluent API Configuration - -If you prefer not to use decorators, you can configure scheduling at runtime using the Fluent API: - -```typescript -@ECSSystem('Movement') -class MovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - - // Configure scheduling using Fluent API - this.stage('update') - .after('InputSystem') - .before('RenderSystem') - .inSet('CoreSystems'); - } -} -``` - -### Cycle Dependency Detection - -The framework automatically detects cyclic dependencies and throws clear errors: - -```typescript -// This will cause a cycle dependency error -@ECSSystem('SystemA') -@Before('SystemB') -class SystemA extends EntitySystem { } - -@ECSSystem('SystemB') -@Before('SystemA') // Error: A -> B -> A forms a cycle -class SystemB extends EntitySystem { } - -// Error message: Cyclic dependency detected: SystemA -> SystemB -> SystemA -``` - -## Frame-Level Change Detection - -> **v2.4.0+** - -The framework provides epoch-based frame-level change detection, allowing systems to process only entities that have changed, significantly improving performance. - -### Core Concepts - -- **Epoch**: Global frame counter, incremented each frame -- **lastWriteEpoch**: The epoch when a component was last modified -- **Change Detection**: Determine if component changed after a specific point by comparing epochs - -### Marking Components as Modified - -After modifying component data, you need to mark the component as changed. There are two approaches: - -**Approach 1: Via Entity Helper Method (Recommended)** - -```typescript -// Mark component dirty via entity.markDirty() after modification -const pos = entity.getComponent(Position)!; -pos.x = 100; -pos.y = 200; -entity.markDirty(pos); - -// Can mark multiple components at once -const vel = entity.getComponent(Velocity)!; -vel.vx = 10; -entity.markDirty(pos, vel); -``` - -**Approach 2: Encapsulate in Component** - -```typescript -class VelocityComponent extends Component { - private _vx: number = 0; - private _vy: number = 0; - - // Provide modification method that accepts epoch parameter - public setVelocity(vx: number, vy: number, epoch: number): void { - this._vx = vx; - this._vy = vy; - this.markDirty(epoch); - } - - public get vx(): number { return this._vx; } - public get vy(): number { return this._vy; } -} - -// Usage in system -const vel = entity.getComponent(VelocityComponent)!; -vel.setVelocity(10, 20, this.currentEpoch); -``` - -### Using Change Detection in Systems - -EntitySystem provides several change detection helper methods: - -```typescript -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - } - - protected process(entities: readonly Entity[]): void { - // Method 1: Use forEachChanged to process only changed entities - // Automatically saves epoch checkpoint - this.forEachChanged(entities, [Velocity], (entity) => { - const pos = this.requireComponent(entity, Position); - const vel = this.requireComponent(entity, Velocity); - - // Only update position when Velocity changes - pos.x += vel.vx * Time.deltaTime; - pos.y += vel.vy * Time.deltaTime; - }); - } -} - -@ECSSystem('Transform') -class TransformSystem extends EntitySystem { - constructor() { - super(Matcher.all(Transform, RigidBody)); - } - - protected process(entities: readonly Entity[]): void { - // Method 2: Use filterChanged to get list of changed entities - const changedEntities = this.filterChanged(entities, [RigidBody]); - - for (const entity of changedEntities) { - // Process entities with changed physics state - this.updatePhysics(entity); - } - - // Manually save epoch checkpoint - this.saveEpoch(); - } - - protected updatePhysics(entity: Entity): void { - // Physics update logic - } -} -``` - -### Change Detection API Reference - -| Method | Description | -|--------|-------------| -| `forEachChanged(entities, [Types], callback)` | Iterate entities with changed specified components, auto-saves checkpoint | -| `filterChanged(entities, [Types])` | Return array of entities with changed specified components | -| `hasChanged(entity, [Types])` | Check if single entity's specified components have changed | -| `saveEpoch()` | Manually save current epoch as checkpoint | -| `lastProcessEpoch` | Get last saved epoch checkpoint | -| `currentEpoch` | Get current scene epoch | - -### Use Cases - -Change detection is particularly suitable for: - -1. **Dirty flag optimization**: Only update rendering when data changes -2. **Physics sync**: Only sync entities with changed position/velocity -3. **Network sync**: Only send changed component data -4. **Cache invalidation**: Only recalculate when dependent data changes - -```typescript -@ECSSystem('NetworkSync') -class NetworkSyncSystem extends EntitySystem { - constructor() { - super(Matcher.all(NetworkComponent, Transform)); - } - - protected process(entities: readonly Entity[]): void { - // Only sync changed entities, greatly reducing network traffic - this.forEachChanged(entities, [Transform], (entity) => { - const transform = this.requireComponent(entity, Transform); - const network = this.requireComponent(entity, NetworkComponent); - - this.sendTransformUpdate(network.id, transform); - }); - } - - private sendTransformUpdate(id: string, transform: Transform): void { - // Send network update - } -} -``` - -## Complex System Examples - -### Collision Detection System - -```typescript -@ECSSystem('Collision') -class CollisionSystem extends EntitySystem { - constructor() { - super(Matcher.all(Transform, Collider)); - } - - protected process(entities: readonly Entity[]): void { - // Simple n² collision detection - for (let i = 0; i < entities.length; i++) { - for (let j = i + 1; j < entities.length; j++) { - this.checkCollision(entities[i], entities[j]); - } - } - } - - private checkCollision(entityA: Entity, entityB: Entity): void { - const transformA = entityA.getComponent(Transform); - const transformB = entityB.getComponent(Transform); - const colliderA = entityA.getComponent(Collider); - const colliderB = entityB.getComponent(Collider); - - if (this.isColliding(transformA, colliderA, transformB, colliderB)) { - // Send collision event - this.scene?.eventSystem.emitSync('collision', { - entityA, - entityB - }); - } - } - - private isColliding(transformA: Transform, colliderA: Collider, - transformB: Transform, colliderB: Collider): boolean { - // Collision detection logic - return false; // Simplified example - } -} -``` - -### State Machine System - -```typescript -@ECSSystem('StateMachine') -class StateMachineSystem extends EntitySystem { - constructor() { - super(Matcher.all(StateMachine)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const stateMachine = entity.getComponent(StateMachine); - if (stateMachine) { - stateMachine.updateTimer(Time.deltaTime); - this.updateState(entity, stateMachine); - } - } - } - - private updateState(entity: Entity, stateMachine: StateMachine): void { - switch (stateMachine.currentState) { - case EntityState.Idle: - this.handleIdleState(entity, stateMachine); - break; - case EntityState.Moving: - this.handleMovingState(entity, stateMachine); - break; - case EntityState.Attacking: - this.handleAttackingState(entity, stateMachine); - break; - } - } - - private handleIdleState(entity: Entity, stateMachine: StateMachine): void { - // Idle state logic - } - - private handleMovingState(entity: Entity, stateMachine: StateMachine): void { - // Moving state logic - } - - private handleAttackingState(entity: Entity, stateMachine: StateMachine): void { - // Attacking state logic - } -} -``` - -## Best Practices - -### 1. Single Responsibility for Systems - -```typescript -// Good system design - single responsibility -@ECSSystem('Movement') -class MovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - } -} - -@ECSSystem('Rendering') -class RenderingSystem extends EntitySystem { - constructor() { - super(Matcher.all(Sprite, Transform)); - } -} - -// Avoid - too many responsibilities -@ECSSystem('GameSystem') -class GameSystem extends EntitySystem { - // One system handling movement, rendering, sound effects, and more -} -``` - -### 2. Use @ECSSystem Decorator - -`@ECSSystem` is a required decorator for system classes, providing type identification and metadata management. - -#### Why It's Required - -| Feature | Description | -|---------|-------------| -| **Type Identification** | Provides stable system names that remain correct after code obfuscation | -| **Debug Support** | Shows readable system names in performance monitoring, logs, and debug tools | -| **System Management** | Find and manage systems by name | -| **Serialization Support** | Records system configuration during scene serialization | - -#### Basic Syntax - -```typescript -@ECSSystem(systemName: string) -``` - -- `systemName`: The system's name, recommend using descriptive names - -#### Usage Example - -```typescript -// Correct usage -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - // System implementation -} - -// Recommended: Use descriptive names -@ECSSystem('PlayerMovement') -class PlayerMovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Player, Position, Velocity)); - } -} - -// Wrong - no decorator -class BadSystem extends EntitySystem { - // Systems defined this way may have issues in production: - // 1. Class name changes after code minification, can't identify correctly - // 2. Performance monitoring and debug tools show incorrect names -} -``` - -#### System Name Usage - -```typescript -@ECSSystem('Combat') -class CombatSystem extends EntitySystem { - protected onInitialize(): void { - // Access system name using systemName property - console.log(`System ${this.systemName} initialized`); // Output: System Combat initialized - } -} - -// Find system by name -const combat = scene.getSystemByName('Combat'); - -// Performance monitoring displays system name -const perfData = combatSystem.getPerformanceData(); -console.log(`${combatSystem.systemName} execution time: ${perfData?.executionTime}ms`); -``` - -### 3. Proper Update Order - -```typescript -// Set system update order by logical sequence -@ECSSystem('Input') -class InputSystem extends EntitySystem { - constructor() { - super(); - this.updateOrder = -100; // Process input first - } -} - -@ECSSystem('Logic') -class GameLogicSystem extends EntitySystem { - constructor() { - super(); - this.updateOrder = 0; // Process game logic - } -} - -@ECSSystem('Render') -class RenderSystem extends EntitySystem { - constructor() { - super(); - this.updateOrder = 100; // Render last - } -} -``` - -### 4. Avoid Direct References Between Systems - -```typescript -// Avoid: Direct system references -@ECSSystem('Bad') -class BadSystem extends EntitySystem { - private otherSystem: SomeOtherSystem; // Avoid direct references to other systems -} - -// Recommended: Communicate through event system -@ECSSystem('Good') -class GoodSystem extends EntitySystem { - protected process(entities: readonly Entity[]): void { - // Communicate with other systems through event system - this.scene?.eventSystem.emitSync('data_updated', { entities }); - } -} -``` - -### 5. Clean Up Resources Promptly - -```typescript -@ECSSystem('Resource') -class ResourceSystem extends EntitySystem { - private resources: Map = new Map(); - - protected onDestroy(): void { - // Clean up resources - for (const [key, resource] of this.resources) { - if (resource.dispose) { - resource.dispose(); - } - } - this.resources.clear(); - } -} -``` - -Systems are the logic processing core of ECS architecture. Properly designing and using systems makes your game code more modular, efficient, and maintainable. diff --git a/docs/en/index.md b/docs/en/index.md deleted file mode 100644 index e8888f9e..00000000 --- a/docs/en/index.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -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/guide/component.md b/docs/guide/component.md deleted file mode 100644 index dd42209b..00000000 --- a/docs/guide/component.md +++ /dev/null @@ -1,725 +0,0 @@ -# 组件系统 - -在 ECS 架构中，组件（Component）是数据和行为的载体。组件定义了实体具有的属性和功能，是 ECS 架构的核心构建块。 - -## 基本概念 - -组件是继承自 `Component` 抽象基类的具体类，用于： -- 存储实体的数据（如位置、速度、健康值等） -- 定义与数据相关的行为方法 -- 提供生命周期回调钩子 -- 支持序列化和调试 - -## 创建组件 - -### 基础组件定义 - -```typescript -import { Component, ECSComponent } from '@esengine/ecs-framework'; - -@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; - } -} - -@ECSComponent('Health') -class Health extends Component { - current: number; - max: number; - - constructor(max: number = 100) { - super(); - this.max = max; - this.current = max; - } - - // 组件可以包含行为方法 - takeDamage(damage: number): void { - this.current = Math.max(0, this.current - damage); - } - - heal(amount: number): void { - this.current = Math.min(this.max, this.current + amount); - } - - isDead(): boolean { - return this.current <= 0; - } -} -``` - -### @ECSComponent 装饰器 - -`@ECSComponent` 是组件类必须使用的装饰器，它为组件提供了类型标识和元数据管理。 - -#### 为什么必须使用 - -| 功能 | 说明 | -|------|------| -| **类型识别** | 提供稳定的类型名称，代码混淆后仍能正确识别 | -| **序列化支持** | 序列化/反序列化时使用该名称作为类型标识 | -| **组件注册** | 自动注册到 ComponentRegistry，分配唯一的位掩码 | -| **调试支持** | 在调试工具和日志中显示可读的组件名称 | - -#### 基本语法 - -```typescript -@ECSComponent(typeName: string) -``` - -- `typeName`: 组件的类型名称，建议使用与类名相同或相近的名称 - -#### 使用示例 - -```typescript -// ✅ 正确的用法 -@ECSComponent('Velocity') -class Velocity extends Component { - dx: number = 0; - dy: number = 0; -} - -// ✅ 推荐：类型名与类名保持一致 -@ECSComponent('PlayerController') -class PlayerController extends Component { - speed: number = 5; -} - -// ❌ 错误的用法 - 没有装饰器 -class BadComponent extends Component { - // 这样定义的组件可能在生产环境出现问题： - // 1. 代码压缩后类名变化，无法正确序列化 - // 2. 组件未注册到框架，查询和匹配可能失效 -} -``` - -#### 与 @Serializable 配合使用 - -当组件需要支持序列化时，`@ECSComponent` 和 `@Serializable` 需要一起使用： - -```typescript -import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework'; - -@ECSComponent('Player') -@Serializable({ version: 1 }) -class PlayerComponent extends Component { - @Serialize() - name: string = ''; - - @Serialize() - level: number = 1; - - // 不使用 @Serialize() 的字段不会被序列化 - private _cachedData: any = null; -} -``` - -> **注意**：`@ECSComponent` 的 `typeName` 和 `@Serializable` 的 `typeId` 可以不同。如果 `@Serializable` 没有指定 `typeId`，则默认使用 `@ECSComponent` 的 `typeName`。 - -#### 组件类型名的唯一性 - -每个组件的类型名应该是唯一的： - -```typescript -// ❌ 错误：两个组件使用相同的类型名 -@ECSComponent('Health') -class HealthComponent extends Component { } - -@ECSComponent('Health') // 冲突！ -class EnemyHealthComponent extends Component { } - -// ✅ 正确：使用不同的类型名 -@ECSComponent('PlayerHealth') -class PlayerHealthComponent extends Component { } - -@ECSComponent('EnemyHealth') -class EnemyHealthComponent extends Component { } -``` - -## 组件生命周期 - -组件提供了生命周期钩子，可以重写来执行特定的逻辑： - -```typescript -@ECSComponent('ExampleComponent') -class ExampleComponent extends Component { - private resource: SomeResource | null = null; - - /** - * 组件被添加到实体时调用 - * 用于初始化资源、建立引用等 - */ - onAddedToEntity(): void { - console.log(`组件 ${this.constructor.name} 已添加，实体ID: ${this.entityId}`); - this.resource = new SomeResource(); - } - - /** - * 组件从实体移除时调用 - * 用于清理资源、断开引用等 - */ - onRemovedFromEntity(): void { - console.log(`组件 ${this.constructor.name} 已移除`); - if (this.resource) { - this.resource.cleanup(); - this.resource = null; - } - } -} -``` - -## 组件与实体的关系 - -组件存储了所属实体的ID (`entityId`)，而不是直接引用实体对象。这是ECS数据导向设计的体现，避免了循环引用。 - -在实际使用中，**应该在 System 中处理实体和组件的交互**，而不是在组件内部： - -```typescript -@ECSComponent('Health') -class Health extends Component { - current: number; - max: number; - - constructor(max: number = 100) { - super(); - this.max = max; - this.current = max; - } - - isDead(): boolean { - return this.current <= 0; - } -} - -@ECSComponent('Damage') -class Damage extends Component { - value: number; - - constructor(value: number) { - super(); - this.value = value; - } -} - -// 推荐：在 System 中处理逻辑 -class DamageSystem extends EntitySystem { - constructor() { - super(new Matcher().all(Health, Damage)); - } - - process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health)!; - const damage = entity.getComponent(Damage)!; - - health.current -= damage.value; - - if (health.isDead()) { - entity.destroy(); - } - - // 应用伤害后移除 Damage 组件 - entity.removeComponent(damage); - } - } -} -``` - -## 组件属性 - -每个组件都有一些内置属性： - -```typescript -@ECSComponent('ExampleComponent') -class ExampleComponent extends Component { - someData: string = "example"; - - onAddedToEntity(): void { - console.log(`组件ID: ${this.id}`); // 唯一的组件ID - console.log(`所属实体ID: ${this.entityId}`); // 所属实体的ID - } -} -``` - -如果需要访问实体对象，应该在 System 中进行： - -```typescript -class ExampleSystem extends EntitySystem { - constructor() { - super(new Matcher().all(ExampleComponent)); - } - - process(entities: readonly Entity[]): void { - for (const entity of entities) { - const comp = entity.getComponent(ExampleComponent)!; - console.log(`实体名称: ${entity.name}`); - console.log(`组件数据: ${comp.someData}`); - } - } -} -``` - - -## 复杂组件示例 - -### 状态机组件 - -```typescript -enum EntityState { - Idle, - Moving, - Attacking, - Dead -} - -@ECSComponent('StateMachine') -class StateMachine extends Component { - private _currentState: EntityState = EntityState.Idle; - private _previousState: EntityState = EntityState.Idle; - private _stateTimer: number = 0; - - get currentState(): EntityState { - return this._currentState; - } - - get previousState(): EntityState { - return this._previousState; - } - - get stateTimer(): number { - return this._stateTimer; - } - - changeState(newState: EntityState): void { - if (this._currentState !== newState) { - this._previousState = this._currentState; - this._currentState = newState; - this._stateTimer = 0; - } - } - - updateTimer(deltaTime: number): void { - this._stateTimer += deltaTime; - } - - isInState(state: EntityState): boolean { - return this._currentState === state; - } -} -``` - -### 配置数据组件 - -```typescript -interface WeaponData { - damage: number; - range: number; - fireRate: number; - ammo: number; -} - -@ECSComponent('WeaponConfig') -class WeaponConfig extends Component { - data: WeaponData; - - constructor(weaponData: WeaponData) { - super(); - this.data = { ...weaponData }; // 深拷贝避免共享引用 - } - - // 提供便捷的访问方法 - getDamage(): number { - return this.data.damage; - } - - canFire(): boolean { - return this.data.ammo > 0; - } - - consumeAmmo(): boolean { - if (this.data.ammo > 0) { - this.data.ammo--; - return true; - } - return false; - } -} -``` - -## 最佳实践 - -### 1. 保持组件简单 - -```typescript -// 好的组件设计 - 单一职责 -@ECSComponent('Position') -class Position extends Component { - x: number = 0; - y: number = 0; -} - -@ECSComponent('Velocity') -class Velocity extends Component { - dx: number = 0; - dy: number = 0; -} - -// 避免的组件设计 - 职责过多 -@ECSComponent('GameObject') -class GameObject extends Component { - x: number; - y: number; - dx: number; - dy: number; - health: number; - damage: number; - sprite: string; - // 太多不相关的属性 -} -``` - -### 2. 使用构造函数初始化 - -```typescript -@ECSComponent('Transform') -class Transform extends Component { - x: number; - y: number; - rotation: number; - scale: number; - - constructor(x = 0, y = 0, rotation = 0, scale = 1) { - super(); - this.x = x; - this.y = y; - this.rotation = rotation; - this.scale = scale; - } -} -``` - -### 3. 明确的类型定义 - -```typescript -interface InventoryItem { - id: string; - name: string; - quantity: number; - type: 'weapon' | 'consumable' | 'misc'; -} - -@ECSComponent('Inventory') -class Inventory extends Component { - items: InventoryItem[] = []; - maxSlots: number; - - constructor(maxSlots: number = 20) { - super(); - this.maxSlots = maxSlots; - } - - addItem(item: InventoryItem): boolean { - if (this.items.length < this.maxSlots) { - this.items.push(item); - return true; - } - return false; - } - - removeItem(itemId: string): InventoryItem | null { - const index = this.items.findIndex(item => item.id === itemId); - if (index !== -1) { - return this.items.splice(index, 1)[0]; - } - return null; - } -} -``` - -### 4. 引用其他实体 - -当组件需要关联其他实体时（如父子关系、跟随目标等），**推荐方式是存储实体ID**，然后在 System 中查找： - -```typescript -@ECSComponent('Follower') -class Follower extends Component { - targetId: number; - followDistance: number = 50; - - constructor(targetId: number) { - super(); - this.targetId = targetId; - } -} - -// 在 System 中查找目标实体并处理逻辑 -class FollowerSystem extends EntitySystem { - constructor() { - super(new Matcher().all(Follower, Position)); - } - - process(entities: readonly Entity[]): void { - for (const entity of entities) { - const follower = entity.getComponent(Follower)!; - const position = entity.getComponent(Position)!; - - // 通过场景查找目标实体 - const target = entity.scene?.findEntityById(follower.targetId); - if (target) { - const targetPos = target.getComponent(Position); - if (targetPos) { - // 跟随逻辑 - const dx = targetPos.x - position.x; - const dy = targetPos.y - position.y; - const distance = Math.sqrt(dx * dx + dy * dy); - - if (distance > follower.followDistance) { - // 移动靠近目标 - } - } - } - } - } -} -``` - -这种方式的优势： -- 组件保持简单，只存储基本数据类型 -- 符合数据导向设计 -- 在 System 中统一处理查找和逻辑 -- 易于理解和维护 - -**避免在组件中直接存储实体引用**： - -```typescript -// 错误示范：直接存储实体引用 -@ECSComponent('BadFollower') -class BadFollower extends Component { - target: Entity; // 实体销毁后仍持有引用，可能导致内存泄漏 -} -``` - -## 高级特性 - -### EntityRef 装饰器 - 自动引用追踪 - -框架提供了 `@EntityRef` 装饰器用于**特殊场景**下安全地存储实体引用。这是一个高级特性,一般情况下推荐使用存储ID的方式。 - -#### 什么时候需要 EntityRef？ - -在以下场景中,`@EntityRef` 可以简化代码: - -1. **父子关系**: 需要在组件中直接访问父实体或子实体 -2. **复杂关联**: 实体之间有多个引用关系 -3. **频繁访问**: 需要在多处访问引用的实体,使用ID查找会有性能开销 - -#### 核心特性 - -`@EntityRef` 装饰器通过 **ReferenceTracker** 自动追踪引用关系: - -- 当被引用的实体销毁时,所有指向它的 `@EntityRef` 属性自动设为 `null` -- 防止跨场景引用(会输出警告并拒绝设置) -- 防止引用已销毁的实体(会输出警告并设为 `null`) -- 使用 WeakRef 避免内存泄漏(自动GC支持) -- 组件移除时自动清理引用注册 - -#### 基本用法 - -```typescript -import { Component, ECSComponent, EntityRef, Entity } from '@esengine/ecs-framework'; - -@ECSComponent('Parent') -class ParentComponent extends Component { - @EntityRef() - parent: Entity | null = null; -} - -// 使用示例 -const scene = new Scene(); -const parent = scene.createEntity('Parent'); -const child = scene.createEntity('Child'); - -const comp = child.addComponent(new ParentComponent()); -comp.parent = parent; - -console.log(comp.parent); // Entity { name: 'Parent' } - -// 当 parent 被销毁时，comp.parent 自动变为 null -parent.destroy(); -console.log(comp.parent); // null -``` - -#### 多个引用属性 - -一个组件可以有多个 `@EntityRef` 属性: - -```typescript -@ECSComponent('Combat') -class CombatComponent extends Component { - @EntityRef() - target: Entity | null = null; - - @EntityRef() - ally: Entity | null = null; - - @EntityRef() - lastAttacker: Entity | null = null; -} - -// 使用示例 -const player = scene.createEntity('Player'); -const enemy = scene.createEntity('Enemy'); -const npc = scene.createEntity('NPC'); - -const combat = player.addComponent(new CombatComponent()); -combat.target = enemy; -combat.ally = npc; - -// enemy 销毁后，只有 target 变为 null，ally 仍然有效 -enemy.destroy(); -console.log(combat.target); // null -console.log(combat.ally); // Entity { name: 'NPC' } -``` - -#### 安全检查 - -`@EntityRef` 提供了多重安全检查: - -```typescript -const scene1 = new Scene(); -const scene2 = new Scene(); - -const entity1 = scene1.createEntity('Entity1'); -const entity2 = scene2.createEntity('Entity2'); - -const comp = entity1.addComponent(new ParentComponent()); - -// 跨场景引用会失败 -comp.parent = entity2; // 输出错误日志，comp.parent 为 null -console.log(comp.parent); // null - -// 引用已销毁的实体会失败 -const entity3 = scene1.createEntity('Entity3'); -entity3.destroy(); -comp.parent = entity3; // 输出警告日志，comp.parent 为 null -console.log(comp.parent); // null -``` - -#### 实现原理 - -`@EntityRef` 使用以下机制实现自动引用追踪: - -1. **ReferenceTracker**: Scene 持有一个引用追踪器,记录所有实体引用关系 -2. **WeakRef**: 使用弱引用存储组件,避免循环引用导致内存泄漏 -3. **属性拦截**: 通过 `Object.defineProperty` 拦截 getter/setter -4. **自动清理**: 实体销毁时,ReferenceTracker 遍历所有引用并设为 null - -```typescript -// 简化的实现原理 -class ReferenceTracker { - // entityId -> 引用该实体的所有组件记录 - private _references: Map, propertyKey: string }>>; - - // 实体销毁时调用 - clearReferencesTo(entityId: number): void { - const records = this._references.get(entityId); - if (records) { - for (const record of records) { - const component = record.component.deref(); - if (component) { - // 将组件的引用属性设为 null - (component as any)[record.propertyKey] = null; - } - } - this._references.delete(entityId); - } - } -} -``` - -#### 性能考虑 - -`@EntityRef` 会带来一些性能开销: - -- **写入开销**: 每次设置引用时需要更新 ReferenceTracker -- **内存开销**: ReferenceTracker 需要维护引用映射表 -- **销毁开销**: 实体销毁时需要遍历所有引用并清理 - -对于大多数场景,这些开销是可以接受的。但如果有**大量实体和频繁的引用变更**,存储ID可能更高效。 - -#### 最佳实践 - -```typescript -// 推荐：适合使用 @EntityRef 的场景 - 父子关系 -@ECSComponent('Transform') -class Transform extends Component { - @EntityRef() - parent: Entity | null = null; - - position: { x: number, y: number } = { x: 0, y: 0 }; - - // 可以直接访问父实体的组件 - getWorldPosition(): { x: number, y: number } { - if (!this.parent) { - return { ...this.position }; - } - - const parentTransform = this.parent.getComponent(Transform); - if (parentTransform) { - const parentPos = parentTransform.getWorldPosition(); - return { - x: parentPos.x + this.position.x, - y: parentPos.y + this.position.y - }; - } - - return { ...this.position }; - } -} - -// 不推荐：不适合使用 @EntityRef 的场景 - 大量动态目标 -@ECSComponent('AITarget') -class AITarget extends Component { - @EntityRef() - target: Entity | null = null; // 如果目标频繁变化，用ID更好 - - updateCooldown: number = 0; -} - -// 推荐：这种场景用ID更好 -@ECSComponent('AITarget') -class AITargetBetter extends Component { - targetId: number | null = null; // 存储ID - updateCooldown: number = 0; -} -``` - -#### 调试支持 - -ReferenceTracker 提供了调试接口: - -```typescript -// 查看某个实体被哪些组件引用 -const references = scene.referenceTracker.getReferencesTo(entity.id); -console.log(`实体 ${entity.name} 被 ${references.length} 个组件引用`); - -// 获取完整的调试信息 -const debugInfo = scene.referenceTracker.getDebugInfo(); -console.log(debugInfo); -``` - -#### 总结 - -- **推荐做法**: 大部分情况使用存储ID + System查找的方式 -- **EntityRef 适用场景**: 父子关系、复杂关联、组件内需要直接访问引用实体的场景 -- **核心优势**: 自动清理、防止悬空引用、代码更简洁 -- **注意事项**: 有性能开销,不适合大量动态引用的场景 - -组件是 ECS 架构的数据载体，正确设计组件能让你的游戏代码更模块化、可维护和高性能。 \ No newline at end of file diff --git a/docs/guide/editor-plugin-system.md b/docs/guide/editor-plugin-system.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/guide/entity-query.md b/docs/guide/entity-query.md deleted file mode 100644 index 978846b2..00000000 --- a/docs/guide/entity-query.md +++ /dev/null @@ -1,750 +0,0 @@ -# 实体查询系统 - -实体查询是 ECS 架构的核心功能之一。本指南将介绍如何使用 Matcher 和 QuerySystem 来查询和筛选实体。 - -## 核心概念 - -### Matcher - 查询条件描述符 - -Matcher 是一个链式 API,用于描述实体查询条件。它本身不执行查询,而是作为条件传递给 EntitySystem 或 QuerySystem。 - -### QuerySystem - 查询执行引擎 - -QuerySystem 负责实际执行查询,内部使用响应式查询机制自动优化性能。 - -## 在 EntitySystem 中使用 Matcher - -这是最常见的使用方式。EntitySystem 通过 Matcher 自动筛选和处理符合条件的实体。 - -### 基础用法 - -```typescript -import { EntitySystem, Matcher, Entity, Component } from '@esengine/ecs-framework'; - -class PositionComponent extends Component { - public x: number = 0; - public y: number = 0; -} - -class VelocityComponent extends Component { - public vx: number = 0; - public vy: number = 0; -} - -class MovementSystem extends EntitySystem { - constructor() { - // 方式1: 使用 Matcher.empty().all() - super(Matcher.empty().all(PositionComponent, VelocityComponent)); - - // 方式2: 直接使用 Matcher.all() (等价) - // super(Matcher.all(PositionComponent, VelocityComponent)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const pos = entity.getComponent(PositionComponent)!; - const vel = entity.getComponent(VelocityComponent)!; - - pos.x += vel.vx; - pos.y += vel.vy; - } - } -} - -// 添加到场景 -scene.addEntityProcessor(new MovementSystem()); -``` - -### Matcher 链式 API - -#### all() - 必须包含所有组件 - -```typescript -class HealthSystem extends EntitySystem { - constructor() { - // 实体必须同时拥有 Health 和 Position 组件 - super(Matcher.empty().all(HealthComponent, PositionComponent)); - } - - protected process(entities: readonly Entity[]): void { - // 只处理同时拥有两个组件的实体 - } -} -``` - -#### any() - 至少包含一个组件 - -```typescript -class DamageableSystem extends EntitySystem { - constructor() { - // 实体至少拥有 Health 或 Shield 其中之一 - super(Matcher.any(HealthComponent, ShieldComponent)); - } - - protected process(entities: readonly Entity[]): void { - // 处理拥有生命值或护盾的实体 - } -} -``` - -#### none() - 不能包含指定组件 - -```typescript -class AliveEntitySystem extends EntitySystem { - constructor() { - // 实体不能拥有 DeadTag 组件 - super(Matcher.all(HealthComponent).none(DeadTag)); - } - - protected process(entities: readonly Entity[]): void { - // 只处理活着的实体 - } -} -``` - -#### 组合条件 - -```typescript -class CombatSystem extends EntitySystem { - constructor() { - super( - Matcher.empty() - .all(PositionComponent, HealthComponent) // 必须有位置和生命 - .any(WeaponComponent, MagicComponent) // 至少有武器或魔法 - .none(DeadTag, FrozenTag) // 不能是死亡或冰冻状态 - ); - } - - protected process(entities: readonly Entity[]): void { - // 处理可以战斗的活着的实体 - } -} -``` - -#### nothing() - 不匹配任何实体 - -用于创建只需要生命周期方法（`onBegin`、`onEnd`）但不需要处理实体的系统。 - -```typescript -class FrameTimerSystem extends EntitySystem { - constructor() { - // 不匹配任何实体 - super(Matcher.nothing()); - } - - protected onBegin(): void { - // 每帧开始时执行 - Performance.markFrameStart(); - } - - protected process(entities: readonly Entity[]): void { - // 永远不会被调用，因为没有匹配的实体 - } - - protected onEnd(): void { - // 每帧结束时执行 - Performance.markFrameEnd(); - } -} -``` - -#### empty() vs nothing() 的区别 - -| 方法 | 行为 | 使用场景 | -|------|------|----------| -| `Matcher.empty()` | 匹配**所有**实体 | 需要处理场景中所有实体 | -| `Matcher.nothing()` | 不匹配**任何**实体 | 只需要生命周期回调，不处理实体 | - -```typescript -// empty() - 返回场景中的所有实体 -class AllEntitiesSystem extends EntitySystem { - constructor() { - super(Matcher.empty()); - } - - protected process(entities: readonly Entity[]): void { - // entities 包含场景中的所有实体 - console.log(`场景中共有 ${entities.length} 个实体`); - } -} - -// nothing() - 不返回任何实体 -class NoEntitiesSystem extends EntitySystem { - constructor() { - super(Matcher.nothing()); - } - - protected process(entities: readonly Entity[]): void { - // entities 永远是空数组，此方法不会被调用 - } -} -``` - -### 按标签查询 - -```typescript -class PlayerSystem extends EntitySystem { - constructor() { - // 查询特定标签的实体 - super(Matcher.empty().withTag(Tags.PLAYER)); - } - - protected process(entities: readonly Entity[]): void { - // 只处理玩家实体 - } -} -``` - -### 按名称查询 - -```typescript -class BossSystem extends EntitySystem { - constructor() { - // 查询特定名称的实体 - super(Matcher.empty().withName('Boss')); - } - - protected process(entities: readonly Entity[]): void { - // 只处理名为 'Boss' 的实体 - } -} -``` - -## 直接使用 QuerySystem - -如果不需要创建系统,可以直接使用 Scene 的 querySystem 进行查询。 - -### 基础查询方法 - -```typescript -// 获取场景的查询系统 -const querySystem = scene.querySystem; - -// 查询拥有所有指定组件的实体 -const result1 = querySystem.queryAll(PositionComponent, VelocityComponent); -console.log(`找到 ${result1.count} 个移动实体`); -console.log(`查询耗时: ${result1.executionTime.toFixed(2)}ms`); - -// 查询拥有任意指定组件的实体 -const result2 = querySystem.queryAny(WeaponComponent, MagicComponent); -console.log(`找到 ${result2.count} 个战斗单位`); - -// 查询不包含指定组件的实体 -const result3 = querySystem.queryNone(DeadTag); -console.log(`找到 ${result3.count} 个活着的实体`); -``` - -### 按标签查询 - -```typescript -const playerResult = querySystem.queryByTag(Tags.PLAYER); -for (const player of playerResult.entities) { - console.log('玩家:', player.name); -} -``` - -### 按名称查询 - -```typescript -const bossResult = querySystem.queryByName('Boss'); -if (bossResult.count > 0) { - const boss = bossResult.entities[0]; - console.log('找到Boss:', boss); -} -``` - -### 按单个组件查询 - -```typescript -const healthResult = querySystem.queryByComponent(HealthComponent); -console.log(`有 ${healthResult.count} 个实体拥有生命值`); -``` - -## 性能优化 - -### 自动缓存 - -QuerySystem 内部使用响应式查询自动缓存结果,相同的查询条件会直接使用缓存: - -```typescript -// 第一次查询,执行实际查询 -const result1 = querySystem.queryAll(PositionComponent); -console.log('fromCache:', result1.fromCache); // false - -// 第二次相同查询,使用缓存 -const result2 = querySystem.queryAll(PositionComponent); -console.log('fromCache:', result2.fromCache); // true -``` - -### 实体变化自动更新 - -当实体添加/移除组件时,查询缓存会自动更新: - -```typescript -// 查询拥有武器的实体 -const before = querySystem.queryAll(WeaponComponent); -console.log('之前:', before.count); // 假设为 5 - -// 给实体添加武器 -const enemy = scene.createEntity('Enemy'); -enemy.addComponent(new WeaponComponent()); - -// 再次查询,自动包含新实体 -const after = querySystem.queryAll(WeaponComponent); -console.log('之后:', after.count); // 现在是 6 -``` - -### 查询性能统计 - -```typescript -const stats = querySystem.getStats(); -console.log('总查询次数:', stats.queryStats.totalQueries); -console.log('缓存命中率:', stats.queryStats.cacheHitRate); -console.log('缓存大小:', stats.cacheStats.size); -``` - -## 实际应用场景 - -### 场景1: 物理系统 - -```typescript -class PhysicsSystem extends EntitySystem { - constructor() { - super(Matcher.empty().all(TransformComponent, RigidbodyComponent)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const transform = entity.getComponent(TransformComponent)!; - const rigidbody = entity.getComponent(RigidbodyComponent)!; - - // 应用重力 - rigidbody.velocity.y -= 9.8 * Time.deltaTime; - - // 更新位置 - transform.position.x += rigidbody.velocity.x * Time.deltaTime; - transform.position.y += rigidbody.velocity.y * Time.deltaTime; - } - } -} -``` - -### 场景2: 渲染系统 - -```typescript -class RenderSystem extends EntitySystem { - constructor() { - super( - Matcher.empty() - .all(TransformComponent, SpriteComponent) - .none(InvisibleTag) // 排除不可见实体 - ); - } - - protected process(entities: readonly Entity[]): void { - // 按 z-order 排序 - const sorted = entities.slice().sort((a, b) => { - const zA = a.getComponent(TransformComponent)!.z; - const zB = b.getComponent(TransformComponent)!.z; - return zA - zB; - }); - - // 渲染实体 - for (const entity of sorted) { - const transform = entity.getComponent(TransformComponent)!; - const sprite = entity.getComponent(SpriteComponent)!; - - renderer.drawSprite(sprite.texture, transform.position); - } - } -} -``` - -### 场景3: 碰撞检测 - -```typescript -class CollisionSystem extends EntitySystem { - constructor() { - super(Matcher.empty().all(TransformComponent, ColliderComponent)); - } - - protected process(entities: readonly Entity[]): void { - // 简单的 O(n²) 碰撞检测 - for (let i = 0; i < entities.length; i++) { - for (let j = i + 1; j < entities.length; j++) { - this.checkCollision(entities[i], entities[j]); - } - } - } - - private checkCollision(a: Entity, b: Entity): void { - const transA = a.getComponent(TransformComponent)!; - const transB = b.getComponent(TransformComponent)!; - const colliderA = a.getComponent(ColliderComponent)!; - const colliderB = b.getComponent(ColliderComponent)!; - - if (this.isOverlapping(transA, colliderA, transB, colliderB)) { - // 触发碰撞事件 - scene.eventSystem.emit('collision', { entityA: a, entityB: b }); - } - } - - private isOverlapping(...args: any[]): boolean { - // 碰撞检测逻辑 - return false; - } -} -``` - -### 场景4: 一次性查询 - -```typescript -// 在系统外部执行一次性查询 -class GameManager { - private scene: Scene; - - public countEnemies(): number { - const result = this.scene.querySystem.queryByTag(Tags.ENEMY); - return result.count; - } - - public findNearestEnemy(playerPos: Vector2): Entity | null { - const enemies = this.scene.querySystem.queryByTag(Tags.ENEMY); - - let nearest: Entity | null = null; - let minDistance = Infinity; - - for (const enemy of enemies.entities) { - const transform = enemy.getComponent(TransformComponent); - if (!transform) continue; - - const distance = Vector2.distance(playerPos, transform.position); - if (distance < minDistance) { - minDistance = distance; - nearest = enemy; - } - } - - return nearest; - } -} -``` - -## 编译查询 (CompiledQuery) - -> **v2.4.0+** - -CompiledQuery 是一个轻量级的查询工具，提供类型安全的组件访问和变更检测支持。适合临时查询、工具开发和简单的迭代场景。 - -### 基本用法 - -```typescript -// 创建编译查询 -const query = scene.querySystem.compile(Position, Velocity); - -// 类型安全的遍历 - 组件参数自动推断类型 -query.forEach((entity, pos, vel) => { - pos.x += vel.vx * deltaTime; - pos.y += vel.vy * deltaTime; -}); - -// 获取实体数量 -console.log(`匹配实体数: ${query.count}`); - -// 获取第一个匹配的实体 -const first = query.first(); -if (first) { - const [entity, pos, vel] = first; - console.log(`第一个实体: ${entity.name}`); -} -``` - -### 变更检测 - -CompiledQuery 支持基于 epoch 的变更检测： - -```typescript -class RenderSystem extends EntitySystem { - private _query: CompiledQuery<[typeof Transform, typeof Sprite]>; - private _lastEpoch = 0; - - protected onInitialize(): void { - this._query = this.scene!.querySystem.compile(Transform, Sprite); - } - - protected process(entities: readonly Entity[]): void { - // 只处理 Transform 或 Sprite 发生变化的实体 - this._query.forEachChanged(this._lastEpoch, (entity, transform, sprite) => { - this.updateRenderData(entity, transform, sprite); - }); - - // 保存当前 epoch 作为下次检查的起点 - this._lastEpoch = this.scene!.epochManager.current; - } - - private updateRenderData(entity: Entity, transform: Transform, sprite: Sprite): void { - // 更新渲染数据 - } -} -``` - -### 函数式 API - -CompiledQuery 提供了丰富的函数式 API： - -```typescript -const query = scene.querySystem.compile(Position, Health); - -// map - 转换实体数据 -const positions = query.map((entity, pos, health) => ({ - x: pos.x, - y: pos.y, - healthPercent: health.current / health.max -})); - -// filter - 过滤实体 -const lowHealthEntities = query.filter((entity, pos, health) => { - return health.current < health.max * 0.2; -}); - -// find - 查找第一个匹配的实体 -const target = query.find((entity, pos, health) => { - return health.current > 0 && pos.x > 100; -}); - -// toArray - 转换为数组 -const allData = query.toArray(); -for (const [entity, pos, health] of allData) { - console.log(`${entity.name}: ${pos.x}, ${pos.y}`); -} - -// any/empty - 检查是否有匹配 -if (query.any()) { - console.log('有匹配的实体'); -} -if (query.empty()) { - console.log('没有匹配的实体'); -} -``` - -### CompiledQuery vs EntitySystem - -| 特性 | CompiledQuery | EntitySystem | -|------|---------------|--------------| -| **用途** | 轻量级查询工具 | 完整的系统逻辑 | -| **生命周期** | 无 | 完整 (onInitialize, onDestroy 等) | -| **调度集成** | 无 | 支持 @Stage, @Before, @After | -| **变更检测** | forEachChanged | forEachChanged | -| **事件监听** | 无 | addEventListener | -| **命令缓冲** | 无 | this.commands | -| **类型安全组件** | forEach 参数自动推断 | 需要手动 getComponent | -| **适用场景** | 临时查询、工具、原型 | 核心游戏逻辑 | - -**选择建议**： - -- 使用 **EntitySystem** 处理核心游戏逻辑（移动、战斗、AI 等） -- 使用 **CompiledQuery** 进行一次性查询、工具开发或简单迭代 - -### CompiledQuery API 参考 - -| 方法 | 说明 | -|------|------| -| `forEach(callback)` | 遍历所有匹配实体，类型安全的组件参数 | -| `forEachChanged(sinceEpoch, callback)` | 只遍历变更的实体 | -| `first()` | 获取第一个匹配的实体和组件 | -| `toArray()` | 转换为 [entity, ...components] 数组 | -| `map(callback)` | 映射转换 | -| `filter(predicate)` | 过滤实体 | -| `find(predicate)` | 查找第一个满足条件的实体 | -| `any()` | 是否有任何匹配 | -| `empty()` | 是否没有匹配 | -| `count` | 匹配的实体数量 | -| `entities` | 匹配的实体列表（只读） | - -## 最佳实践 - -### 1. 优先使用 EntitySystem - -```typescript -// 推荐: 使用 EntitySystem -class GoodSystem extends EntitySystem { - constructor() { - super(Matcher.empty().all(HealthComponent)); - } - - protected process(entities: readonly Entity[]): void { - // 自动获得符合条件的实体,每帧自动更新 - } -} - -// 不推荐: 在 update 中手动查询 -class BadSystem extends EntitySystem { - constructor() { - super(Matcher.empty()); - } - - protected process(entities: readonly Entity[]): void { - // 每帧手动查询,浪费性能 - const result = this.scene!.querySystem.queryAll(HealthComponent); - for (const entity of result.entities) { - // ... - } - } -} -``` - -### 2. 合理使用 none() 排除条件 - -```typescript -// 排除已死亡的敌人 -class EnemyAISystem extends EntitySystem { - constructor() { - super( - Matcher.empty() - .all(EnemyTag, AIComponent) - .none(DeadTag) // 不处理死亡的敌人 - ); - } -} -``` - -### 3. 使用标签优化查询 - -```typescript -// 不好: 查询所有实体再过滤 -const allEntities = scene.querySystem.getAllEntities(); -const players = allEntities.filter(e => e.hasComponent(PlayerTag)); - -// 好: 直接按标签查询 -const players = scene.querySystem.queryByTag(Tags.PLAYER).entities; -``` - -### 4. 避免过于复杂的查询条件 - -```typescript -// 不推荐: 过于复杂 -super( - Matcher.empty() - .all(A, B, C, D) - .any(E, F, G) - .none(H, I, J) -); - -// 推荐: 拆分成多个简单系统 -class SystemAB extends EntitySystem { - constructor() { - super(Matcher.empty().all(A, B)); - } -} - -class SystemCD extends EntitySystem { - constructor() { - super(Matcher.empty().all(C, D)); - } -} -``` - -## 注意事项 - -### 1. 查询结果是只读的 - -```typescript -const result = querySystem.queryAll(PositionComponent); - -// 不要修改返回的数组 -result.entities.push(someEntity); // 错误! - -// 如果需要修改,先复制 -const mutableArray = [...result.entities]; -mutableArray.push(someEntity); // 正确 -``` - -### 2. 组件添加/移除后的查询时机 - -```typescript -// 创建实体并添加组件 -const entity = scene.createEntity('Player'); -entity.addComponent(new PositionComponent()); - -// 立即查询可能获取到新实体 -const result = scene.querySystem.queryAll(PositionComponent); -// result.entities 包含新创建的实体 -``` - -### 3. Matcher 是不可变的 - -```typescript -const matcher = Matcher.empty().all(PositionComponent); - -// 链式调用返回新的 Matcher 实例 -const matcher2 = matcher.any(VelocityComponent); - -// matcher 本身不变 -console.log(matcher === matcher2); // false -``` - -## Matcher API 快速参考 - -### 静态创建方法 - -| 方法 | 说明 | 示例 | -|------|------|------| -| `Matcher.all(...types)` | 必须包含所有指定组件 | `Matcher.all(Position, Velocity)` | -| `Matcher.any(...types)` | 至少包含一个指定组件 | `Matcher.any(Health, Shield)` | -| `Matcher.none(...types)` | 不能包含任何指定组件 | `Matcher.none(Dead)` | -| `Matcher.byTag(tag)` | 按标签查询 | `Matcher.byTag(1)` | -| `Matcher.byName(name)` | 按名称查询 | `Matcher.byName("Player")` | -| `Matcher.byComponent(type)` | 按单个组件查询 | `Matcher.byComponent(Health)` | -| `Matcher.empty()` | 创建空匹配器（匹配所有实体） | `Matcher.empty()` | -| `Matcher.nothing()` | 不匹配任何实体 | `Matcher.nothing()` | -| `Matcher.complex()` | 创建复杂查询构建器 | `Matcher.complex()` | - -### 链式方法 - -| 方法 | 说明 | 示例 | -|------|------|------| -| `.all(...types)` | 添加必须包含的组件 | `.all(Position)` | -| `.any(...types)` | 添加可选组件（至少一个） | `.any(Weapon, Magic)` | -| `.none(...types)` | 添加排除的组件 | `.none(Dead)` | -| `.exclude(...types)` | `.none()` 的别名 | `.exclude(Disabled)` | -| `.one(...types)` | `.any()` 的别名 | `.one(Player, Enemy)` | -| `.withTag(tag)` | 添加标签条件 | `.withTag(1)` | -| `.withName(name)` | 添加名称条件 | `.withName("Boss")` | -| `.withComponent(type)` | 添加单组件条件 | `.withComponent(Health)` | - -### 实用方法 - -| 方法 | 说明 | -|------|------| -| `.getCondition()` | 获取查询条件（只读） | -| `.isEmpty()` | 检查是否为空条件 | -| `.isNothing()` | 检查是否为 nothing 匹配器 | -| `.clone()` | 克隆匹配器 | -| `.reset()` | 重置所有条件 | -| `.toString()` | 获取字符串表示 | - -### 常用组合示例 - -```typescript -// 基础移动系统 -Matcher.all(Position, Velocity) - -// 可攻击的活着的实体 -Matcher.all(Position, Health) - .any(Weapon, Magic) - .none(Dead, Disabled) - -// 所有带标签的敌人 -Matcher.byTag(Tags.ENEMY) - .all(AIComponent) - -// 只需要生命周期的系统 -Matcher.nothing() -``` - -## 相关 API - -- [Matcher](../api/classes/Matcher.md) - 查询条件描述符 API 参考 -- [QuerySystem](../api/classes/QuerySystem.md) - 查询系统 API 参考 -- [EntitySystem](../api/classes/EntitySystem.md) - 实体系统 API 参考 -- [Entity](../api/classes/Entity.md) - 实体 API 参考 diff --git a/docs/guide/persistent-entity.md b/docs/guide/persistent-entity.md deleted file mode 100644 index 0ff5412f..00000000 --- a/docs/guide/persistent-entity.md +++ /dev/null @@ -1,360 +0,0 @@ -# 持久化实体 - -> **版本**: v2.3.0+ - -持久化实体（Persistent Entity）是一种可以在场景切换时自动迁移到新场景的特殊实体。适用于需要跨场景保持状态的游戏对象，如玩家、游戏管理器、音频管理器等。 - -## 基本概念 - -在 ECS 框架中，实体有两种生命周期策略： - -| 策略 | 说明 | 默认 | -|-----|------|------| -| `SceneLocal` | 场景本地实体，场景切换时销毁 | ✓ | -| `Persistent` | 持久化实体，场景切换时自动迁移 | | - -## 快速开始 - -### 创建持久化实体 - -```typescript -import { Scene } from '@esengine/ecs-framework'; - -class GameScene extends Scene { - protected initialize(): void { - // 创建持久化玩家实体 - const player = this.createEntity('Player').setPersistent(); - player.addComponent(new Position(100, 200)); - player.addComponent(new PlayerData('Hero', 500)); - - // 创建普通敌人实体（场景切换时销毁） - const enemy = this.createEntity('Enemy'); - enemy.addComponent(new Position(300, 200)); - enemy.addComponent(new EnemyAI()); - } -} -``` - -### 场景切换时的行为 - -```typescript -import { Core, Scene } from '@esengine/ecs-framework'; - -// 初始场景 -class Level1Scene extends Scene { - protected initialize(): void { - // 玩家 - 持久化，会迁移到下一个场景 - const player = this.createEntity('Player').setPersistent(); - player.addComponent(new Position(0, 0)); - player.addComponent(new Health(100)); - - // 敌人 - 场景本地，切换时销毁 - const enemy = this.createEntity('Enemy'); - enemy.addComponent(new Position(100, 100)); - } -} - -// 目标场景 -class Level2Scene extends Scene { - protected initialize(): void { - // 新的敌人 - const enemy = this.createEntity('Boss'); - enemy.addComponent(new Position(200, 200)); - } - - public onStart(): void { - // 玩家已自动迁移到此场景 - const player = this.findEntity('Player'); - console.log(player !== null); // true - - // 位置和血量数据完整保留 - const position = player?.getComponent(Position); - const health = player?.getComponent(Health); - console.log(position?.x, position?.y); // 0, 0 - console.log(health?.value); // 100 - } -} - -// 切换场景 -Core.create({ debug: true }); -Core.setScene(new Level1Scene()); - -// 稍后切换到 Level2 -Core.loadScene(new Level2Scene()); -// Player 实体自动迁移，Enemy 实体被销毁 -``` - -## API 参考 - -### Entity 方法 - -#### setPersistent() - -将实体标记为持久化，场景切换时不会被销毁。 - -```typescript -public setPersistent(): this -``` - -**返回**: 返回实体本身，支持链式调用 - -**示例**: -```typescript -const player = scene.createEntity('Player') - .setPersistent(); - -player.addComponent(new Position(100, 200)); -``` - -#### setSceneLocal() - -将实体恢复为场景本地策略（默认）。 - -```typescript -public setSceneLocal(): this -``` - -**返回**: 返回实体本身，支持链式调用 - -**示例**: -```typescript -// 动态取消持久化 -player.setSceneLocal(); -``` - -#### isPersistent - -检查实体是否为持久化实体。 - -```typescript -public get isPersistent(): boolean -``` - -**示例**: -```typescript -if (entity.isPersistent) { - console.log('这是持久化实体'); -} -``` - -#### lifecyclePolicy - -获取实体的生命周期策略。 - -```typescript -public get lifecyclePolicy(): EEntityLifecyclePolicy -``` - -**示例**: -```typescript -import { EEntityLifecyclePolicy } from '@esengine/ecs-framework'; - -if (entity.lifecyclePolicy === EEntityLifecyclePolicy.Persistent) { - console.log('持久化实体'); -} -``` - -### Scene 方法 - -#### findPersistentEntities() - -查找场景中所有持久化实体。 - -```typescript -public findPersistentEntities(): Entity[] -``` - -**返回**: 持久化实体数组 - -**示例**: -```typescript -const persistentEntities = scene.findPersistentEntities(); -console.log(`场景中有 ${persistentEntities.length} 个持久化实体`); -``` - -#### extractPersistentEntities() - -提取并从场景中移除所有持久化实体（通常由框架内部调用）。 - -```typescript -public extractPersistentEntities(): Entity[] -``` - -**返回**: 被提取的持久化实体数组 - -#### receiveMigratedEntities() - -接收迁移过来的实体（通常由框架内部调用）。 - -```typescript -public receiveMigratedEntities(entities: Entity[]): void -``` - -**参数**: -- `entities` - 要接收的实体数组 - -## 使用场景 - -### 1. 玩家实体跨关卡 - -```typescript -class PlayerSetupScene extends Scene { - protected initialize(): void { - // 玩家在所有关卡中保持状态 - const player = this.createEntity('Player').setPersistent(); - player.addComponent(new Transform(0, 0)); - player.addComponent(new Health(100)); - player.addComponent(new Inventory()); - player.addComponent(new PlayerStats()); - } -} - -class Level1 extends Scene { /* ... */ } -class Level2 extends Scene { /* ... */ } -class Level3 extends Scene { /* ... */ } - -// 玩家实体会自动在所有关卡间迁移 -Core.setScene(new PlayerSetupScene()); -// ... 游戏进行 -Core.loadScene(new Level1()); -// ... 关卡完成 -Core.loadScene(new Level2()); -// 玩家数据（血量、物品栏、属性）完整保留 -``` - -### 2. 全局管理器 - -```typescript -class BootstrapScene extends Scene { - protected initialize(): void { - // 音频管理器 - 跨场景保持 - const audioManager = this.createEntity('AudioManager').setPersistent(); - audioManager.addComponent(new AudioController()); - - // 成就管理器 - 跨场景保持 - const achievementManager = this.createEntity('AchievementManager').setPersistent(); - achievementManager.addComponent(new AchievementTracker()); - - // 游戏设置 - 跨场景保持 - const settings = this.createEntity('GameSettings').setPersistent(); - settings.addComponent(new SettingsData()); - } -} -``` - -### 3. 动态切换持久化状态 - -```typescript -class GameScene extends Scene { - protected initialize(): void { - // 初始创建为普通实体 - const companion = this.createEntity('Companion'); - companion.addComponent(new Transform(0, 0)); - companion.addComponent(new CompanionAI()); - - // 监听招募事件 - this.eventSystem.on('companion:recruited', () => { - // 招募后变为持久化实体 - companion.setPersistent(); - console.log('同伴已加入队伍，将跟随玩家跨场景'); - }); - - // 监听解散事件 - this.eventSystem.on('companion:dismissed', () => { - // 解散后恢复为场景本地实体 - companion.setSceneLocal(); - console.log('同伴已离队，不再跨场景'); - }); - } -} -``` - -## 最佳实践 - -### 1. 明确标识持久化实体 - -```typescript -// 推荐：在创建时立即标记 -const player = this.createEntity('Player').setPersistent(); - -// 不推荐：创建后再标记（容易遗漏） -const player = this.createEntity('Player'); -// ... 很多代码 ... -player.setPersistent(); // 容易忘记 -``` - -### 2. 合理使用持久化 - -```typescript -// ✓ 适合持久化的实体 -const player = this.createEntity('Player').setPersistent(); // 玩家 -const gameManager = this.createEntity('GameManager').setPersistent(); // 全局管理器 -const audioManager = this.createEntity('AudioManager').setPersistent(); // 音频系统 - -// ✗ 不应持久化的实体 -const bullet = this.createEntity('Bullet'); // 临时对象 -const enemy = this.createEntity('Enemy'); // 关卡特定敌人 -const particle = this.createEntity('Particle'); // 特效粒子 -``` - -### 3. 检查迁移后的实体 - -```typescript -class NewScene extends Scene { - public onStart(): void { - // 检查预期的持久化实体是否存在 - const player = this.findEntity('Player'); - if (!player) { - console.error('玩家实体未正确迁移！'); - // 处理错误情况 - } - } -} -``` - -### 4. 避免循环引用 - -```typescript -// ✗ 避免：持久化实体引用场景本地实体 -class BadScene extends Scene { - protected initialize(): void { - const player = this.createEntity('Player').setPersistent(); - const enemy = this.createEntity('Enemy'); - - // 危险：player 持久化但 enemy 不是 - // 场景切换后 enemy 被销毁，引用失效 - player.addComponent(new TargetComponent(enemy)); - } -} - -// ✓ 推荐：使用 ID 引用或事件系统 -class GoodScene extends Scene { - protected initialize(): void { - const player = this.createEntity('Player').setPersistent(); - const enemy = this.createEntity('Enemy'); - - // 存储 ID 而非直接引用 - player.addComponent(new TargetComponent(enemy.id)); - - // 或使用事件系统通信 - } -} -``` - -## 注意事项 - -1. **已销毁的实体不会迁移**：如果实体在场景切换前被销毁，即使标记为持久化也不会迁移。 - -2. **组件数据完整保留**：迁移时所有组件及其状态都会保留。 - -3. **场景引用会更新**：迁移后实体的 `scene` 属性会指向新场景。 - -4. **查询系统会更新**：迁移的实体会自动注册到新场景的查询系统中。 - -5. **延迟切换同样生效**：使用 `Core.loadScene()` 延迟切换时，持久化实体同样会迁移。 - -## 相关文档 - -- [场景管理](./scene.md) - 了解场景的基本使用 -- [SceneManager](./scene-manager.md) - 了解场景切换 -- [WorldManager](./world-manager.md) - 了解多世界管理 diff --git a/docs/guide/scene-manager.md b/docs/guide/scene-manager.md deleted file mode 100644 index a50b9af1..00000000 --- a/docs/guide/scene-manager.md +++ /dev/null @@ -1,681 +0,0 @@ -# SceneManager - -SceneManager 是 ECS Framework 提供的轻量级场景管理器，适用于 95% 的游戏应用。它提供简单直观的 API，支持场景切换和延迟加载。 - -## 适用场景 - -SceneManager 适合以下场景： -- 单人游戏 -- 简单多人游戏 -- 移动游戏 -- 需要场景切换的游戏（菜单、游戏、暂停等） -- 不需要多 World 隔离的项目 - -## 特点 - -- 轻量级，零额外开销 -- 简单直观的 API -- 支持延迟场景切换（避免在当前帧中途切换） -- 自动管理 ECS 流式 API -- 自动处理场景生命周期 -- 集成在 Core 中，自动更新 -- 支持[持久化实体](./persistent-entity.md)跨场景迁移（v2.3.0+） - -## 基本使用 - -### 推荐方式：使用 Core 的静态方法 - -这是最简单和推荐的方式，适合大多数应用： - -```typescript -import { Core, Scene } from '@esengine/ecs-framework'; - -// 1. 初始化 Core -Core.create({ debug: true }); - -// 2. 创建并设置场景 -class GameScene extends Scene { - protected initialize(): void { - this.name = "GameScene"; - - // 添加系统 - this.addSystem(new MovementSystem()); - this.addSystem(new RenderSystem()); - - // 创建初始实体 - const player = this.createEntity("Player"); - player.addComponent(new Transform(400, 300)); - player.addComponent(new Health(100)); - } - - public onStart(): void { - console.log("游戏场景已启动"); - } -} - -// 3. 设置场景 -Core.setScene(new GameScene()); - -// 4. 游戏循环（Core.update 会自动更新场景） -function gameLoop(deltaTime: number) { - Core.update(deltaTime); // 自动更新所有服务和场景 -} - -// Laya 引擎集成 -Laya.timer.frameLoop(1, this, () => { - const deltaTime = Laya.timer.delta / 1000; - Core.update(deltaTime); -}); - -// Cocos Creator 集成 -update(deltaTime: number) { - Core.update(deltaTime); -} -``` - -### 高级方式：直接使用 SceneManager - -如果需要更多控制，可以直接使用 SceneManager： - -```typescript -import { Core, SceneManager, Scene } from '@esengine/ecs-framework'; - -// 初始化 Core -Core.create({ debug: true }); - -// 获取 SceneManager（Core 已自动创建并注册） -const sceneManager = Core.services.resolve(SceneManager); - -// 设置场景 -const gameScene = new GameScene(); -sceneManager.setScene(gameScene); - -// 游戏循环（仍然使用 Core.update） -function gameLoop(deltaTime: number) { - Core.update(deltaTime); // Core会自动调用sceneManager.update() -} -``` - -**重要**：无论使用哪种方式，游戏循环中都应该只调用 `Core.update()`，它会自动更新 SceneManager 和场景。不需要手动调用 `sceneManager.update()`。 - -## 场景切换 - -### 立即切换 - -使用 `Core.setScene()` 或 `sceneManager.setScene()` 立即切换场景： - -```typescript -// 方式1：使用 Core（推荐） -Core.setScene(new MenuScene()); - -// 方式2：使用 SceneManager -const sceneManager = Core.services.resolve(SceneManager); -sceneManager.setScene(new MenuScene()); -``` - -### 延迟切换 - -使用 `Core.loadScene()` 或 `sceneManager.loadScene()` 延迟切换场景，场景会在下一帧切换： - -```typescript -// 方式1：使用 Core（推荐） -Core.loadScene(new GameOverScene()); - -// 方式2：使用 SceneManager -const sceneManager = Core.services.resolve(SceneManager); -sceneManager.loadScene(new GameOverScene()); -``` - -在 System 中切换场景时，应该使用延迟切换： - -```typescript -class GameOverSystem extends EntitySystem { - process(entities: readonly Entity[]): void { - const player = entities.find(e => e.name === 'Player'); - const health = player?.getComponent(Health); - - if (health && health.value <= 0) { - // 延迟切换到游戏结束场景（下一帧生效） - Core.loadScene(new GameOverScene()); - // 当前帧继续执行，不会中断当前系统的处理 - } - } -} -``` - -### 完整的场景切换示例 - -```typescript -import { Core, Scene } from '@esengine/ecs-framework'; - -// 初始化 -Core.create({ debug: true }); - -// 菜单场景 -class MenuScene extends Scene { - protected initialize(): void { - this.name = "MenuScene"; - - // 监听开始游戏事件 - this.eventSystem.on('start_game', () => { - Core.loadScene(new GameScene()); - }); - } - - public onStart(): void { - console.log("显示菜单界面"); - } - - public unload(): void { - console.log("菜单场景卸载"); - } -} - -// 游戏场景 -class GameScene extends Scene { - protected initialize(): void { - this.name = "GameScene"; - - // 创建游戏实体 - const player = this.createEntity("Player"); - player.addComponent(new Transform(400, 300)); - player.addComponent(new Health(100)); - - // 监听游戏结束事件 - this.eventSystem.on('game_over', () => { - Core.loadScene(new GameOverScene()); - }); - } - - public onStart(): void { - console.log("游戏开始"); - } - - public unload(): void { - console.log("游戏场景卸载"); - } -} - -// 游戏结束场景 -class GameOverScene extends Scene { - protected initialize(): void { - this.name = "GameOverScene"; - - // 监听返回菜单事件 - this.eventSystem.on('back_to_menu', () => { - Core.loadScene(new MenuScene()); - }); - } - - public onStart(): void { - console.log("显示游戏结束界面"); - } -} - -// 开始游戏 -Core.setScene(new MenuScene()); - -// 游戏循环 -function gameLoop(deltaTime: number) { - Core.update(deltaTime); // 自动更新场景 -} -``` - -## API 参考 - -### Core 静态方法（推荐） - -#### Core.setScene() - -立即切换场景。 - -```typescript -public static setScene(scene: T): T -``` - -**参数**： -- `scene` - 要设置的场景实例 - -**返回**： -- 返回设置的场景实例 - -**示例**： -```typescript -const gameScene = Core.setScene(new GameScene()); -console.log(gameScene.name); -``` - -#### Core.loadScene() - -延迟加载场景（下一帧切换）。 - -```typescript -public static loadScene(scene: T): void -``` - -**参数**： -- `scene` - 要加载的场景实例 - -**示例**： -```typescript -Core.loadScene(new GameOverScene()); -``` - -#### Core.scene - -获取当前活跃的场景。 - -```typescript -public static get scene(): IScene | null -``` - -**返回**： -- 当前场景实例，如果没有场景则返回 null - -**示例**： -```typescript -const currentScene = Core.scene; -if (currentScene) { - console.log(`当前场景: ${currentScene.name}`); -} -``` - -#### Core.ecsAPI - -获取 ECS 流式 API。 - -```typescript -public static get ecsAPI(): ECSFluentAPI | null -``` - -**返回**： -- ECS API 实例，如果当前没有场景则返回 null - -**示例**： -```typescript -const api = Core.ecsAPI; -if (api) { - // 查询实体 - const enemies = api.find(Enemy, Transform); - - // 发射事件 - api.emit('game:start', { level: 1 }); -} -``` - -### SceneManager 方法（高级） - -如果需要直接使用 SceneManager，可以通过服务容器获取： - -```typescript -const sceneManager = Core.services.resolve(SceneManager); -``` - -#### setScene() - -立即切换场景。 - -```typescript -public setScene(scene: T): T -``` - -#### loadScene() - -延迟加载场景。 - -```typescript -public loadScene(scene: T): void -``` - -#### currentScene - -获取当前场景。 - -```typescript -public get currentScene(): IScene | null -``` - -#### api - -获取 ECS 流式 API。 - -```typescript -public get api(): ECSFluentAPI | null -``` - -#### hasScene - -检查是否有活跃场景。 - -```typescript -public get hasScene(): boolean -``` - -#### hasPendingScene - -检查是否有待切换的场景。 - -```typescript -public get hasPendingScene(): boolean -``` - -## 使用 ECS 流式 API - -通过 `Core.ecsAPI` 可以方便地访问场景的 ECS 功能： - -```typescript -const api = Core.ecsAPI; -if (!api) { - console.error('没有活跃场景'); - return; -} - -// 查询实体 -const players = api.find(Player, Transform); -const enemies = api.find(Enemy, Health, Transform); - -// 发射事件 -api.emit('player:scored', { points: 100 }); - -// 监听事件 -api.on('enemy:died', (data) => { - console.log('敌人死亡:', data); -}); -``` - -## 最佳实践 - -### 1. 使用 Core 的静态方法 - -```typescript -// 推荐：使用 Core 的静态方法 -Core.setScene(new GameScene()); -Core.loadScene(new MenuScene()); -const currentScene = Core.scene; - -// 不推荐：除非有特殊需求，否则不需要直接使用 SceneManager -const sceneManager = Core.services.resolve(SceneManager); -sceneManager.setScene(new GameScene()); -``` - -### 2. 只调用 Core.update() - -```typescript -// 正确：只调用 Core.update() -function gameLoop(deltaTime: number) { - Core.update(deltaTime); // 自动更新所有服务和场景 -} - -// 错误：不要手动调用 sceneManager.update() -function gameLoop(deltaTime: number) { - Core.update(deltaTime); - sceneManager.update(); // 重复更新，会导致问题！ -} -``` - -### 3. 使用延迟切换避免问题 - -在 System 中切换场景时，应该使用 `loadScene()` 而不是 `setScene()`： - -```typescript -// 推荐：延迟切换 -class HealthSystem extends EntitySystem { - process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - if (health.value <= 0) { - Core.loadScene(new GameOverScene()); - // 当前帧继续处理其他实体 - } - } - } -} - -// 不推荐：立即切换可能导致问题 -class HealthSystem extends EntitySystem { - process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - if (health.value <= 0) { - Core.setScene(new GameOverScene()); - // 场景立即切换，当前帧的其他实体可能无法正常处理 - } - } - } -} -``` - -### 4. 场景职责分离 - -每个场景应该只负责一个特定的游戏状态： - -```typescript -// 好的设计 - 职责清晰 -class MenuScene extends Scene { - // 只处理菜单相关逻辑 -} - -class GameScene extends Scene { - // 只处理游戏玩法逻辑 -} - -class PauseScene extends Scene { - // 只处理暂停界面逻辑 -} - -// 避免的设计 - 职责混乱 -class MegaScene extends Scene { - // 包含菜单、游戏、暂停等所有逻辑 -} -``` - -### 5. 资源管理 - -在场景的 `unload()` 方法中清理资源： - -```typescript -class GameScene extends Scene { - private textures: Map = new Map(); - private sounds: Map = new Map(); - - protected initialize(): void { - this.loadResources(); - } - - private loadResources(): void { - this.textures.set('player', loadTexture('player.png')); - this.sounds.set('bgm', loadSound('bgm.mp3')); - } - - public unload(): void { - // 清理资源 - this.textures.clear(); - this.sounds.clear(); - console.log('场景资源已清理'); - } -} -``` - -### 6. 事件驱动的场景切换 - -使用事件系统来触发场景切换，保持代码解耦： - -```typescript -class GameScene extends Scene { - protected initialize(): void { - // 监听场景切换事件 - this.eventSystem.on('goto:menu', () => { - Core.loadScene(new MenuScene()); - }); - - this.eventSystem.on('goto:gameover', (data) => { - Core.loadScene(new GameOverScene()); - }); - } -} - -// 在 System 中触发事件 -class GameLogicSystem extends EntitySystem { - process(entities: readonly Entity[]): void { - if (levelComplete) { - this.scene.eventSystem.emitSync('goto:gameover', { - score: 1000, - level: 5 - }); - } - } -} -``` - -## 架构层次 - -SceneManager 在 ECS Framework 中的位置： - -``` -Core (全局服务) - └── SceneManager (场景管理，自动更新) - └── Scene (当前场景) - ├── EntitySystem (系统) - ├── Entity (实体) - └── Component (组件) -``` - -## 与 WorldManager 的对比 - -| 特性 | SceneManager | WorldManager | -|------|--------------|--------------| -| 适用场景 | 95% 的游戏应用 | 高级多世界隔离场景 | -| 复杂度 | 简单 | 复杂 | -| 场景数量 | 单场景（可切换） | 多 World，每个 World 多场景 | -| 性能开销 | 最小 | 较高 | -| 使用方式 | `Core.setScene()` | `worldManager.createWorld()` | - -**何时使用 SceneManager**： -- 单人游戏 -- 简单的多人游戏 -- 移动游戏 -- 场景之间需要切换但不需要同时运行 - -**何时使用 WorldManager**： -- MMO 游戏服务器（每个房间一个 World） -- 游戏大厅系统（每个游戏房间完全隔离） -- 需要运行多个完全独立的游戏实例 - -## 完整示例 - -```typescript -import { Core, Scene, EntitySystem, Entity, Matcher } from '@esengine/ecs-framework'; - -// 定义组件 -class Transform { - constructor(public x: number, public y: number) {} -} - -class Velocity { - constructor(public vx: number, public vy: number) {} -} - -class Health { - constructor(public value: number) {} -} - -// 定义系统 -class MovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Transform, Velocity)); - } - - process(entities: readonly Entity[]): void { - for (const entity of entities) { - const transform = entity.getComponent(Transform); - const velocity = entity.getComponent(Velocity); - - if (transform && velocity) { - transform.x += velocity.vx; - transform.y += velocity.vy; - } - } - } -} - -// 定义场景 -class MenuScene extends Scene { - protected initialize(): void { - this.name = "MenuScene"; - console.log("菜单场景初始化"); - } - - public onStart(): void { - console.log("菜单场景启动"); - } -} - -class GameScene extends Scene { - protected initialize(): void { - this.name = "GameScene"; - - // 添加系统 - this.addSystem(new MovementSystem()); - - // 创建玩家 - const player = this.createEntity("Player"); - player.addComponent(new Transform(400, 300)); - player.addComponent(new Velocity(0, 0)); - player.addComponent(new Health(100)); - - // 创建敌人 - for (let i = 0; i < 5; i++) { - const enemy = this.createEntity(`Enemy_${i}`); - enemy.addComponent(new Transform( - Math.random() * 800, - Math.random() * 600 - )); - enemy.addComponent(new Velocity( - Math.random() * 100 - 50, - Math.random() * 100 - 50 - )); - enemy.addComponent(new Health(50)); - } - } - - public onStart(): void { - console.log('游戏场景启动'); - } - - public unload(): void { - console.log('游戏场景卸载'); - } -} - -// 初始化 -Core.create({ debug: true }); - -// 设置初始场景 -Core.setScene(new MenuScene()); - -// 游戏循环 -let lastTime = 0; -function gameLoop(currentTime: number) { - const deltaTime = (currentTime - lastTime) / 1000; - lastTime = currentTime; - - // 只需要调用 Core.update，它会自动更新场景 - Core.update(deltaTime); - - requestAnimationFrame(gameLoop); -} - -requestAnimationFrame(gameLoop); - -// 切换到游戏场景 -setTimeout(() => { - Core.loadScene(new GameScene()); -}, 3000); -``` - -SceneManager 为大多数游戏提供了简单而强大的场景管理能力。通过 Core 的静态方法，你可以轻松地管理场景切换。 - -## 相关文档 - -- [持久化实体](./persistent-entity.md) - 了解如何让实体跨场景保持状态 -- [WorldManager](./world-manager.md) - 了解更高级的多世界隔离功能 diff --git a/docs/guide/serialization.md b/docs/guide/serialization.md deleted file mode 100644 index 4c1f4aa9..00000000 --- a/docs/guide/serialization.md +++ /dev/null @@ -1,923 +0,0 @@ -# 序列化系统 - -序列化系统提供了完整的场景、实体和组件数据持久化方案，支持全量序列化和增量序列化两种模式，适用于游戏存档、网络同步、场景编辑器、时间回溯等场景。 - -## 基本概念 - -序列化系统分为两个层次： - -- **全量序列化**：序列化完整的场景状态，包括所有实体、组件和场景数据 -- **增量序列化**：只序列化相对于基础快照的变更部分，大幅减少数据量 - -### 支持的数据格式 - -- **JSON格式**：人类可读，便于调试和编辑 -- **Binary格式**：使用MessagePack，体积更小，性能更高 - -> **📢 v2.2.2 重要变更** -> -> 从 v2.2.2 开始，二进制序列化格式返回 `Uint8Array` 而非 Node.js 的 `Buffer`，以确保浏览器兼容性： -> - `serialize({ format: 'binary' })` 返回 `string | Uint8Array`（原为 `string | Buffer`） -> - `deserialize(data)` 接收 `string | Uint8Array`（原为 `string | Buffer`） -> - `applyIncremental(data)` 接收 `IncrementalSnapshot | string | Uint8Array`（原为包含 `Buffer`） -> -> **迁移影响**： -> - ✅ **运行时兼容**：Node.js 的 `Buffer` 继承自 `Uint8Array`，现有代码可直接运行 -> - ⚠️ **类型检查**：如果你的 TypeScript 代码中显式使用了 `Buffer` 类型，需要改为 `Uint8Array` -> - ✅ **浏览器支持**：`Uint8Array` 是标准 JavaScript 类型，所有现代浏览器都支持 - -## 全量序列化 - -### 基础用法 - -#### 1. 标记可序列化组件 - -使用 `@Serializable` 和 `@Serialize` 装饰器标记需要序列化的组件和字段： - -```typescript -import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework'; - -@ECSComponent('Player') -@Serializable({ version: 1 }) -class PlayerComponent extends Component { - @Serialize() - public name: string = ''; - - @Serialize() - public level: number = 1; - - @Serialize() - public experience: number = 0; - - @Serialize() - public position: { x: number; y: number } = { x: 0, y: 0 }; - - // 不使用 @Serialize() 的字段不会被序列化 - private tempData: any = null; -} -``` - -#### 2. 序列化场景 - -```typescript -// JSON格式序列化 -const jsonData = scene.serialize({ - format: 'json', - pretty: true // 美化输出 -}); - -// 保存到本地存储 -localStorage.setItem('gameSave', jsonData); - -// Binary格式序列化（更小的体积） -const binaryData = scene.serialize({ - format: 'binary' -}); - -// 保存为文件（Node.js环境） -// 注意：binaryData 是 Uint8Array 类型，Node.js 的 fs 可以直接写入 -fs.writeFileSync('save.bin', binaryData); -``` - -#### 3. 反序列化场景 - -```typescript -// 从JSON恢复 -const saveData = localStorage.getItem('gameSave'); -if (saveData) { - scene.deserialize(saveData, { - strategy: 'replace' // 替换当前场景内容 - }); -} - -// 从Binary恢复 -const binaryData = fs.readFileSync('save.bin'); -scene.deserialize(binaryData, { - strategy: 'merge' // 合并到现有场景 -}); -``` - -### 序列化选项 - -#### SerializationOptions - -```typescript -interface SceneSerializationOptions { - // 指定要序列化的组件类型（可选） - components?: ComponentType[]; - - // 序列化格式：'json' 或 'binary' - format?: 'json' | 'binary'; - - // JSON美化输出 - pretty?: boolean; - - // 包含元数据 - includeMetadata?: boolean; -} -``` - -示例： - -```typescript -// 只序列化特定组件类型 -const saveData = scene.serialize({ - format: 'json', - components: [PlayerComponent, InventoryComponent], - pretty: true, - includeMetadata: true -}); -``` - -#### DeserializationOptions - -```typescript -interface SceneDeserializationOptions { - // 反序列化策略 - strategy?: 'merge' | 'replace'; - - // 组件类型注册表（可选，默认使用全局注册表） - componentRegistry?: Map; -} -``` - -### 高级装饰器 - -#### 字段序列化选项 - -```typescript -@ECSComponent('Advanced') -@Serializable({ version: 1 }) -class AdvancedComponent extends Component { - // 使用别名 - @Serialize({ alias: 'playerName' }) - public name: string = ''; - - // 自定义序列化器 - @Serialize({ - serializer: (value: Date) => value.toISOString(), - deserializer: (value: string) => new Date(value) - }) - public createdAt: Date = new Date(); - - // 忽略序列化 - @IgnoreSerialization() - public cachedData: any = null; -} -``` - -#### 集合类型序列化 - -```typescript -@ECSComponent('Collections') -@Serializable({ version: 1 }) -class CollectionsComponent extends Component { - // Map序列化 - @SerializeAsMap() - public inventory: Map = new Map(); - - // Set序列化 - @SerializeAsSet() - public acquiredSkills: Set = new Set(); - - constructor() { - super(); - this.inventory.set('gold', 100); - this.inventory.set('silver', 50); - this.acquiredSkills.add('attack'); - this.acquiredSkills.add('defense'); - } -} -``` - -### 组件继承与序列化 - -框架完整支持组件类的继承，子类会自动继承父类的序列化字段，同时可以添加自己的字段。 - -#### 基础继承 - -```typescript -// 基类组件 -@ECSComponent('Collider2DBase') -@Serializable({ version: 1, typeId: 'Collider2DBase' }) -abstract class Collider2DBase extends Component { - @Serialize() - public friction: number = 0.5; - - @Serialize() - public restitution: number = 0.0; - - @Serialize() - public isTrigger: boolean = false; -} - -// 子类组件 - 自动继承父类的序列化字段 -@ECSComponent('BoxCollider2D') -@Serializable({ version: 1, typeId: 'BoxCollider2D' }) -class BoxCollider2DComponent extends Collider2DBase { - @Serialize() - public width: number = 1.0; - - @Serialize() - public height: number = 1.0; -} - -// 另一个子类组件 -@ECSComponent('CircleCollider2D') -@Serializable({ version: 1, typeId: 'CircleCollider2D' }) -class CircleCollider2DComponent extends Collider2DBase { - @Serialize() - public radius: number = 0.5; -} -``` - -#### 继承规则 - -1. **字段继承**：子类自动继承父类所有被 `@Serialize()` 标记的字段 -2. **独立元数据**：每个子类维护独立的序列化元数据，修改子类不会影响父类或其他子类 -3. **typeId 区分**：使用 `typeId` 选项为每个类指定唯一标识，确保反序列化时能正确识别组件类型 - -#### 使用 typeId 的重要性 - -当使用组件继承时，**强烈建议**为每个类设置唯一的 `typeId`： - -```typescript -// ✅ 推荐：明确指定 typeId -@Serializable({ version: 1, typeId: 'BoxCollider2D' }) -class BoxCollider2DComponent extends Collider2DBase { } - -@Serializable({ version: 1, typeId: 'CircleCollider2D' }) -class CircleCollider2DComponent extends Collider2DBase { } - -// ⚠️ 不推荐：依赖类名作为 typeId -// 在代码压缩后类名可能变化，导致反序列化失败 -@Serializable({ version: 1 }) -class BoxCollider2DComponent extends Collider2DBase { } -``` - -#### 子类覆盖父类字段 - -子类可以重新声明父类的字段以修改其序列化选项： - -```typescript -@ECSComponent('SpecialCollider') -@Serializable({ version: 1, typeId: 'SpecialCollider' }) -class SpecialColliderComponent extends Collider2DBase { - // 覆盖父类字段，使用不同的别名 - @Serialize({ alias: 'fric' }) - public override friction: number = 0.8; - - @Serialize() - public specialProperty: string = ''; -} -``` - -#### 忽略继承的字段 - -使用 `@IgnoreSerialization()` 可以在子类中忽略从父类继承的字段： - -```typescript -@ECSComponent('TriggerOnly') -@Serializable({ version: 1, typeId: 'TriggerOnly' }) -class TriggerOnlyCollider extends Collider2DBase { - // 忽略父类的 friction 和 restitution 字段 - // 因为 Trigger 不需要物理材质属性 - @IgnoreSerialization() - public override friction: number = 0; - - @IgnoreSerialization() - public override restitution: number = 0; -} -``` - -### 场景自定义数据 - -除了实体和组件，还可以序列化场景级别的配置数据： - -```typescript -// 设置场景数据 -scene.sceneData.set('weather', 'rainy'); -scene.sceneData.set('difficulty', 'hard'); -scene.sceneData.set('checkpoint', { x: 100, y: 200 }); - -// 序列化时会自动包含场景数据 -const saveData = scene.serialize({ format: 'json' }); - -// 反序列化后场景数据会恢复 -scene.deserialize(saveData); -console.log(scene.sceneData.get('weather')); // 'rainy' -``` - -## 增量序列化 - -增量序列化只保存场景的变更部分，适用于网络同步、撤销/重做、时间回溯等需要频繁保存状态的场景。 - -### 基础用法 - -#### 1. 创建基础快照 - -```typescript -// 在需要开始记录变更前创建基础快照 -scene.createIncrementalSnapshot(); -``` - -#### 2. 修改场景 - -```typescript -// 添加实体 -const enemy = scene.createEntity('Enemy'); -enemy.addComponent(new PositionComponent(100, 200)); -enemy.addComponent(new HealthComponent(50)); - -// 修改组件 -const player = scene.findEntity('Player'); -const pos = player.getComponent(PositionComponent); -pos.x = 300; -pos.y = 400; - -// 删除组件 -player.removeComponentByType(BuffComponent); - -// 删除实体 -const oldEntity = scene.findEntity('ToDelete'); -oldEntity.destroy(); - -// 修改场景数据 -scene.sceneData.set('score', 1000); -``` - -#### 3. 获取增量变更 - -```typescript -// 获取相对于基础快照的所有变更 -const incremental = scene.serializeIncremental(); - -// 查看变更统计 -const stats = IncrementalSerializer.getIncrementalStats(incremental); -console.log('总变更数:', stats.totalChanges); -console.log('新增实体:', stats.addedEntities); -console.log('删除实体:', stats.removedEntities); -console.log('新增组件:', stats.addedComponents); -console.log('更新组件:', stats.updatedComponents); -``` - -#### 4. 序列化增量数据 - -```typescript -// JSON格式（默认） -const jsonData = IncrementalSerializer.serializeIncremental(incremental, { - format: 'json' -}); - -// 二进制格式（更小的体积，更高性能） -const binaryData = IncrementalSerializer.serializeIncremental(incremental, { - format: 'binary' -}); - -// 美化JSON输出（便于调试） -const prettyJson = IncrementalSerializer.serializeIncremental(incremental, { - format: 'json', - pretty: true -}); - -// 发送或保存 -socket.send(binaryData); // 网络传输使用二进制 -localStorage.setItem('changes', jsonData); // 本地存储可用JSON -``` - -#### 5. 应用增量变更 - -```typescript -// 在另一个场景应用变更 -const otherScene = new Scene(); - -// 直接应用增量对象 -otherScene.applyIncremental(incremental); - -// 从JSON字符串应用 -const jsonData = IncrementalSerializer.serializeIncremental(incremental, { format: 'json' }); -otherScene.applyIncremental(jsonData); - -// 从二进制Uint8Array应用 -const binaryData = IncrementalSerializer.serializeIncremental(incremental, { format: 'binary' }); -otherScene.applyIncremental(binaryData); -``` - -### 增量快照管理 - -#### 更新快照基准 - -在应用增量变更后，可以更新快照基准： - -```typescript -// 创建初始快照 -scene.createIncrementalSnapshot(); - -// 第一次修改 -entity.addComponent(new VelocityComponent(5, 0)); -const incremental1 = scene.serializeIncremental(); - -// 更新基准（将当前状态设为新的基准） -scene.updateIncrementalSnapshot(); - -// 第二次修改（增量将基于更新后的基准） -entity.getComponent(VelocityComponent).dx = 10; -const incremental2 = scene.serializeIncremental(); -``` - -#### 清除快照 - -```typescript -// 释放快照占用的内存 -scene.clearIncrementalSnapshot(); - -// 检查是否有快照 -if (scene.hasIncrementalSnapshot()) { - console.log('存在增量快照'); -} -``` - -### 增量序列化选项 - -```typescript -interface IncrementalSerializationOptions { - // 是否进行组件数据的深度对比 - // 默认true，设为false可提升性能但可能漏掉组件内部字段变更 - deepComponentComparison?: boolean; - - // 是否跟踪场景数据变更 - // 默认true - trackSceneData?: boolean; - - // 是否压缩快照（使用JSON序列化） - // 默认false - compressSnapshot?: boolean; - - // 序列化格式 - // 'json': JSON格式（可读性好，方便调试） - // 'binary': MessagePack二进制格式（体积小，性能高） - // 默认 'json' - format?: 'json' | 'binary'; - - // 是否美化JSON输出（仅在format='json'时有效） - // 默认false - pretty?: boolean; -} - -// 使用选项 -scene.createIncrementalSnapshot({ - deepComponentComparison: true, - trackSceneData: true -}); -``` - -### 增量数据结构 - -增量快照包含以下变更类型： - -```typescript -interface IncrementalSnapshot { - version: number; // 快照版本号 - timestamp: number; // 时间戳 - sceneName: string; // 场景名称 - baseVersion: number; // 基础版本号 - entityChanges: EntityChange[]; // 实体变更 - componentChanges: ComponentChange[]; // 组件变更 - sceneDataChanges: SceneDataChange[]; // 场景数据变更 -} - -// 变更操作类型 -enum ChangeOperation { - EntityAdded = 'entity_added', - EntityRemoved = 'entity_removed', - EntityUpdated = 'entity_updated', - ComponentAdded = 'component_added', - ComponentRemoved = 'component_removed', - ComponentUpdated = 'component_updated', - SceneDataUpdated = 'scene_data_updated' -} -``` - -## 版本迁移 - -当组件结构发生变化时，版本迁移系统可以自动升级旧版本的存档数据。 - -### 注册迁移函数 - -```typescript -import { VersionMigrationManager } from '@esengine/ecs-framework'; - -// 假设 PlayerComponent v1 有 hp 字段 -// v2 改为 health 和 maxHealth 字段 - -// 注册从版本1到版本2的迁移 -VersionMigrationManager.registerComponentMigration( - 'Player', - 1, // 从版本 - 2, // 到版本 - (data) => { - // 迁移逻辑 - const newData = { - ...data, - health: data.hp, - maxHealth: data.hp, - }; - delete newData.hp; - return newData; - } -); -``` - -### 使用迁移构建器 - -```typescript -import { MigrationBuilder } from '@esengine/ecs-framework'; - -new MigrationBuilder() - .forComponent('Player') - .fromVersionToVersion(2, 3) - .migrate((data) => { - // 从版本2迁移到版本3 - data.experience = data.exp || 0; - delete data.exp; - return data; - }); -``` - -### 场景级迁移 - -```typescript -// 注册场景级迁移 -VersionMigrationManager.registerSceneMigration( - 1, // 从版本 - 2, // 到版本 - (scene) => { - // 迁移场景结构 - scene.metadata = { - ...scene.metadata, - migratedFrom: 1 - }; - return scene; - } -); -``` - -### 检查迁移路径 - -```typescript -// 检查是否可以迁移 -const canMigrate = VersionMigrationManager.canMigrateComponent( - 'Player', - 1, // 从版本 - 3 // 到版本 -); - -if (canMigrate) { - // 可以安全迁移 - scene.deserialize(oldSaveData); -} - -// 获取迁移路径 -const path = VersionMigrationManager.getComponentMigrationPath('Player'); -console.log('可用迁移版本:', path); // [1, 2, 3] -``` - -## 使用场景 - -### 游戏存档系统 - -```typescript -class SaveSystem { - private static SAVE_KEY = 'game_save'; - - // 保存游戏 - public static saveGame(scene: Scene): void { - const saveData = scene.serialize({ - format: 'json', - pretty: false - }); - - localStorage.setItem(this.SAVE_KEY, saveData); - console.log('游戏已保存'); - } - - // 加载游戏 - public static loadGame(scene: Scene): boolean { - const saveData = localStorage.getItem(this.SAVE_KEY); - if (saveData) { - scene.deserialize(saveData, { - strategy: 'replace' - }); - console.log('游戏已加载'); - return true; - } - return false; - } - - // 检查是否有存档 - public static hasSave(): boolean { - return localStorage.getItem(this.SAVE_KEY) !== null; - } -} -``` - -### 网络同步 - -```typescript -class NetworkSync { - private baseSnapshot?: any; - private syncInterval: number = 100; // 100ms同步一次 - - constructor(private scene: Scene, private socket: WebSocket) { - this.setupSync(); - } - - private setupSync(): void { - // 创建基础快照 - this.scene.createIncrementalSnapshot(); - - // 定期发送增量 - setInterval(() => { - this.sendIncremental(); - }, this.syncInterval); - - // 接收远程增量 - this.socket.onmessage = (event) => { - this.receiveIncremental(event.data); - }; - } - - private sendIncremental(): void { - const incremental = this.scene.serializeIncremental(); - const stats = IncrementalSerializer.getIncrementalStats(incremental); - - // 只在有变更时发送 - if (stats.totalChanges > 0) { - // 使用二进制格式减少网络传输量 - const binaryData = IncrementalSerializer.serializeIncremental(incremental, { - format: 'binary' - }); - this.socket.send(binaryData); - - // 更新基准 - this.scene.updateIncrementalSnapshot(); - } - } - - private receiveIncremental(data: ArrayBuffer): void { - // 直接应用二进制数据（ArrayBuffer 转 Uint8Array） - const uint8Array = new Uint8Array(data); - this.scene.applyIncremental(uint8Array); - } -} -``` - -### 撤销/重做系统 - -```typescript -class UndoRedoSystem { - private history: IncrementalSnapshot[] = []; - private currentIndex: number = -1; - private maxHistory: number = 50; - - constructor(private scene: Scene) { - // 创建初始快照 - this.scene.createIncrementalSnapshot(); - this.saveState('Initial'); - } - - // 保存当前状态 - public saveState(label: string): void { - const incremental = this.scene.serializeIncremental(); - - // 删除当前位置之后的历史 - this.history = this.history.slice(0, this.currentIndex + 1); - - // 添加新状态 - this.history.push(incremental); - this.currentIndex++; - - // 限制历史记录数量 - if (this.history.length > this.maxHistory) { - this.history.shift(); - this.currentIndex--; - } - - // 更新快照基准 - this.scene.updateIncrementalSnapshot(); - } - - // 撤销 - public undo(): boolean { - if (this.currentIndex > 0) { - this.currentIndex--; - const incremental = this.history[this.currentIndex]; - this.scene.applyIncremental(incremental); - return true; - } - return false; - } - - // 重做 - public redo(): boolean { - if (this.currentIndex < this.history.length - 1) { - this.currentIndex++; - const incremental = this.history[this.currentIndex]; - this.scene.applyIncremental(incremental); - return true; - } - return false; - } - - public canUndo(): boolean { - return this.currentIndex > 0; - } - - public canRedo(): boolean { - return this.currentIndex < this.history.length - 1; - } -} -``` - -### 关卡编辑器 - -```typescript -class LevelEditor { - // 导出关卡 - public exportLevel(scene: Scene, filename: string): void { - const levelData = scene.serialize({ - format: 'json', - pretty: true, - includeMetadata: true - }); - - // 浏览器环境 - const blob = new Blob([levelData], { type: 'application/json' }); - const url = URL.createObjectURL(blob); - const a = document.createElement('a'); - a.href = url; - a.download = filename; - a.click(); - URL.revokeObjectURL(url); - } - - // 导入关卡 - public importLevel(scene: Scene, fileContent: string): void { - scene.deserialize(fileContent, { - strategy: 'replace' - }); - } - - // 验证关卡数据 - public validateLevel(saveData: string): boolean { - const validation = SceneSerializer.validate(saveData); - if (!validation.valid) { - console.error('关卡数据无效:', validation.errors); - return false; - } - return true; - } - - // 获取关卡信息（不完全反序列化） - public getLevelInfo(saveData: string): any { - const info = SceneSerializer.getInfo(saveData); - return info; - } -} -``` - -## 性能优化建议 - -### 1. 选择合适的格式 - -- **开发阶段**：使用JSON格式，便于调试和查看 -- **生产环境**：使用Binary格式，减少30-50%的数据大小 - -### 2. 按需序列化 - -```typescript -// 只序列化需要持久化的组件 -const saveData = scene.serialize({ - format: 'binary', - components: [PlayerComponent, InventoryComponent, QuestComponent] -}); -``` - -### 3. 增量序列化优化 - -```typescript -// 对于高频同步，关闭深度对比以提升性能 -scene.createIncrementalSnapshot({ - deepComponentComparison: false // 只检测组件的添加/删除 -}); -``` - -### 4. 批量操作 - -```typescript -// 批量修改后再序列化 -scene.entities.buffer.forEach(entity => { - // 批量修改 -}); - -// 一次性序列化所有变更 -const incremental = scene.serializeIncremental(); -``` - -## 最佳实践 - -### 1. 明确序列化字段 - -```typescript -// 明确标记需要序列化的字段 -@ECSComponent('Player') -@Serializable({ version: 1 }) -class PlayerComponent extends Component { - @Serialize() - public name: string = ''; - - @Serialize() - public level: number = 1; - - // 运行时数据不序列化 - private _cachedSprite: any = null; -} -``` - -### 2. 使用版本控制 - -```typescript -// 为组件指定版本 -@Serializable({ version: 2 }) -class PlayerComponent extends Component { - // 版本2的字段 -} - -// 注册迁移函数确保兼容性 -VersionMigrationManager.registerComponentMigration('Player', 1, 2, migrateV1ToV2); -``` - -### 3. 避免循环引用 - -```typescript -// 不要在组件中直接引用其他实体 -@ECSComponent('Follower') -@Serializable({ version: 1 }) -class FollowerComponent extends Component { - // 存储实体ID而不是实体引用 - @Serialize() - public targetId: number = 0; - - // 通过场景查找目标实体 - public getTarget(scene: Scene): Entity | null { - return scene.entities.findEntityById(this.targetId); - } -} -``` - -### 4. 压缩大数据 - -```typescript -// 对于大型数据结构，使用自定义序列化 -@ECSComponent('LargeData') -@Serializable({ version: 1 }) -class LargeDataComponent extends Component { - @Serialize({ - serializer: (data: LargeObject) => compressData(data), - deserializer: (data: CompressedData) => decompressData(data) - }) - public data: LargeObject; -} -``` - -## API参考 - -### 全量序列化API - -- [`Scene.serialize()`](/api/classes/Scene#serialize) - 序列化场景 -- [`Scene.deserialize()`](/api/classes/Scene#deserialize) - 反序列化场景 -- [`SceneSerializer`](/api/classes/SceneSerializer) - 场景序列化器 -- [`ComponentSerializer`](/api/classes/ComponentSerializer) - 组件序列化器 - -### 增量序列化API - -- [`Scene.createIncrementalSnapshot()`](/api/classes/Scene#createincrementalsnapshot) - 创建基础快照 -- [`Scene.serializeIncremental()`](/api/classes/Scene#serializeincremental) - 获取增量变更 -- [`Scene.applyIncremental()`](/api/classes/Scene#applyincremental) - 应用增量变更（支持IncrementalSnapshot对象、JSON字符串或二进制Uint8Array） -- [`Scene.updateIncrementalSnapshot()`](/api/classes/Scene#updateincrementalsnapshot) - 更新快照基准 -- [`Scene.clearIncrementalSnapshot()`](/api/classes/Scene#clearincrementalsnapshot) - 清除快照 -- [`Scene.hasIncrementalSnapshot()`](/api/classes/Scene#hasincrementalsnapshot) - 检查是否有快照 -- [`IncrementalSerializer`](/api/classes/IncrementalSerializer) - 增量序列化器 -- [`IncrementalSnapshot`](/api/interfaces/IncrementalSnapshot) - 增量快照接口 -- [`IncrementalSerializationOptions`](/api/interfaces/IncrementalSerializationOptions) - 增量序列化选项 -- [`IncrementalSerializationFormat`](/api/type-aliases/IncrementalSerializationFormat) - 序列化格式类型 - -### 版本迁移API - -- [`VersionMigrationManager`](/api/classes/VersionMigrationManager) - 版本迁移管理器 -- `VersionMigrationManager.registerComponentMigration()` - 注册组件迁移 -- `VersionMigrationManager.registerSceneMigration()` - 注册场景迁移 -- `VersionMigrationManager.canMigrateComponent()` - 检查是否可以迁移 -- `VersionMigrationManager.getComponentMigrationPath()` - 获取迁移路径 - -序列化系统是构建完整游戏的重要基础设施，合理使用可以实现强大的功能，如存档系统、网络同步、关卡编辑器等。 diff --git a/docs/guide/service-container.md b/docs/guide/service-container.md deleted file mode 100644 index e5f1086e..00000000 --- a/docs/guide/service-container.md +++ /dev/null @@ -1,828 +0,0 @@ -# 服务容器 - -服务容器（ServiceContainer）是 ECS Framework 的依赖注入容器，负责管理框架中所有服务的注册、解析和生命周期。通过服务容器，你可以实现松耦合的架构设计，提高代码的可测试性和可维护性。 - -## 概述 - -### 什么是服务容器 - -服务容器是一个轻量级的依赖注入（DI）容器，它提供了： - -- **服务注册**: 将服务类型注册到容器中 -- **服务解析**: 从容器中获取服务实例 -- **生命周期管理**: 自动管理服务实例的创建和销毁 -- **依赖注入**: 自动解析服务之间的依赖关系 - -### 核心概念 - -#### 服务（Service） - -服务是实现了 `IService` 接口的类，必须提供 `dispose()` 方法用于资源清理： - -```typescript -import { IService } from '@esengine/ecs-framework'; - -class MyService implements IService { - constructor() { - // 初始化逻辑 - } - - dispose(): void { - // 清理资源 - } -} -``` - -#### 服务标识符（ServiceIdentifier） - -服务标识符用于在容器中唯一标识一个服务，支持两种类型： - -- **类构造函数**: 直接使用服务类作为标识符，适用于具体实现类 -- **Symbol**: 使用 Symbol 作为标识符，适用于接口抽象（推荐用于插件和跨包场景） - -```typescript -// 方式1: 使用类作为标识符 -Core.services.registerSingleton(DataService); -const data = Core.services.resolve(DataService); - -// 方式2: 使用 Symbol 作为标识符（推荐用于接口） -const IFileSystem = Symbol.for('IFileSystem'); -Core.services.registerInstance(IFileSystem, new TauriFileSystem()); -const fs = Core.services.resolve(IFileSystem); -``` - -> **提示**: 使用 `Symbol.for()` 而非 `Symbol()` 可确保跨包/跨模块共享同一个标识符。详见[高级用法 - 接口与 Symbol 标识符模式](#接口与-symbol-标识符模式)。 - -#### 生命周期 - -服务容器支持两种生命周期： - -- **Singleton（单例）**: 整个应用程序生命周期内只有一个实例，所有解析请求返回同一个实例 -- **Transient（瞬时）**: 每次解析都创建新的实例 - -## 基础使用 - -### 访问服务容器 - -ECS Framework 提供了三级服务容器： - -> **版本说明**：World 服务容器功能在 v2.2.13+ 版本中可用 - -#### Core 级别服务容器 - -应用程序全局服务容器，可以通过 `Core.services` 访问： - -```typescript -import { Core } from '@esengine/ecs-framework'; - -// 初始化Core -Core.create({ debug: true }); - -// 访问全局服务容器 -const container = Core.services; -``` - -#### World 级别服务容器 - -每个 World 拥有独立的服务容器，用于管理 World 范围内的服务： - -```typescript -import { World } from '@esengine/ecs-framework'; - -// 创建 World -const world = new World({ name: 'GameWorld' }); - -// 访问 World 级别的服务容器 -const worldContainer = world.services; - -// 注册 World 级别的服务 -world.services.registerSingleton(RoomManager); -``` - -#### Scene 级别服务容器 - -每个 Scene 拥有独立的服务容器，用于管理 Scene 范围内的服务： - -```typescript -// 访问 Scene 级别的服务容器 -const sceneContainer = scene.services; - -// 注册 Scene 级别的服务 -scene.services.registerSingleton(PhysicsSystem); -``` - -#### 服务容器层级 - -``` -Core.services (应用程序全局) - └─ World.services (World 级别) - └─ Scene.services (Scene 级别) -``` - -不同级别的服务容器是独立的，服务不会自动向上或向下查找。选择合适的容器级别： - -- **Core.services**: 应用程序级别的全局服务（配置、插件管理器等） -- **World.services**: World 级别的服务（房间管理器、多人游戏状态等） -- **Scene.services**: Scene 级别的服务（ECS 系统、场景特定逻辑等） - -### 注册服务 - -#### 注册单例服务 - -单例服务在首次解析时创建，之后所有解析请求都返回同一个实例： - -```typescript -class DataService implements IService { - private data: Map = new Map(); - - getData(key: string) { - return this.data.get(key); - } - - setData(key: string, value: any) { - this.data.set(key, value); - } - - dispose(): void { - this.data.clear(); - } -} - -// 注册单例服务 -Core.services.registerSingleton(DataService); -``` - -#### 注册瞬时服务 - -瞬时服务每次解析都创建新实例，适用于无状态或短生命周期的服务： - -```typescript -class CommandService implements IService { - execute(command: string) { - console.log(`Executing: ${command}`); - } - - dispose(): void { - // 清理资源 - } -} - -// 注册瞬时服务 -Core.services.registerTransient(CommandService); -``` - -#### 注册服务实例 - -直接注册已创建的实例，自动视为单例： - -```typescript -const config = new ConfigService(); -config.load('./config.json'); - -// 注册实例 -Core.services.registerInstance(ConfigService, config); -``` - -#### 使用工厂函数注册 - -工厂函数允许你在创建服务时执行自定义逻辑： - -```typescript -Core.services.registerSingleton(LoggerService, (container) => { - const logger = new LoggerService(); - logger.setLevel('debug'); - return logger; -}); -``` - -### 解析服务 - -#### resolve 方法 - -解析服务实例，如果服务未注册会抛出异常： - -```typescript -// 解析服务 -const dataService = Core.services.resolve(DataService); -dataService.setData('player', { name: 'Alice', score: 100 }); - -// 单例服务，多次解析返回同一个实例 -const same = Core.services.resolve(DataService); -console.log(same === dataService); // true -``` - -#### tryResolve 方法 - -尝试解析服务，如果未注册返回 null 而不抛出异常： - -```typescript -const optional = Core.services.tryResolve(OptionalService); -if (optional) { - optional.doSomething(); -} -``` - -#### isRegistered 方法 - -检查服务是否已注册： - -```typescript -if (Core.services.isRegistered(DataService)) { - const service = Core.services.resolve(DataService); -} -``` - -## 内置服务 - -Core 在初始化时自动注册了以下内置服务： - -### TimerManager - -定时器管理器，负责管理所有游戏定时器： - -```typescript -const timerManager = Core.services.resolve(TimerManager); - -// 创建定时器 -timerManager.schedule(1.0, false, null, (timer) => { - console.log('1秒后执行'); -}); -``` - -### PerformanceMonitor - -性能监控器，监控游戏性能并提供优化建议： - -```typescript -const monitor = Core.services.resolve(PerformanceMonitor); - -// 启用性能监控 -monitor.enable(); - -// 获取性能数据 -const fps = monitor.getFPS(); -``` - -### SceneManager - -场景管理器，管理单场景应用的场景生命周期： - -```typescript -const sceneManager = Core.services.resolve(SceneManager); - -// 设置当前场景 -sceneManager.setScene(new GameScene()); - -// 获取当前场景 -const currentScene = sceneManager.currentScene; - -// 延迟切换场景 -sceneManager.loadScene(new MenuScene()); - -// 更新场景 -sceneManager.update(); -``` - -### WorldManager - -世界管理器，管理多个独立的 World 实例（高级用例）： - -```typescript -const worldManager = Core.services.resolve(WorldManager); - -// 创建独立的游戏世界 -const gameWorld = worldManager.createWorld('game_room_001', { - name: 'GameRoom', - maxScenes: 5 -}); - -// 在World中创建场景 -const scene = gameWorld.createScene('battle', new BattleScene()); -gameWorld.setSceneActive('battle', true); - -// 更新所有World -worldManager.updateAll(); -``` - -**适用场景**: -- SceneManager: 适用于 95% 的游戏（单人游戏、简单多人游戏） -- WorldManager: 适用于 MMO 服务器、游戏房间系统等需要完全隔离的多世界应用 - -### PoolManager - -对象池管理器，管理所有对象池： - -```typescript -const poolManager = Core.services.resolve(PoolManager); - -// 创建对象池 -const bulletPool = poolManager.createPool('bullets', () => new Bullet(), 100); -``` - -### PluginManager - -插件管理器，管理插件的安装和卸载： - -```typescript -const pluginManager = Core.services.resolve(PluginManager); - -// 获取所有已安装的插件 -const plugins = pluginManager.getAllPlugins(); -``` - -## 依赖注入 - -ECS Framework 提供了装饰器来简化依赖注入。 - -### @Injectable 装饰器 - -标记类为可注入的服务： - -```typescript -import { Injectable, IService } from '@esengine/ecs-framework'; - -@Injectable() -class GameService implements IService { - constructor() { - console.log('GameService created'); - } - - dispose(): void { - console.log('GameService disposed'); - } -} -``` - -### @InjectProperty 装饰器 - -通过属性装饰器注入依赖。注入时机是在构造函数执行后、`onInitialize()` 调用前完成： - -```typescript -import { Injectable, InjectProperty, IService } from '@esengine/ecs-framework'; - -@Injectable() -class PlayerService implements IService { - @InjectProperty(DataService) - private data!: DataService; - - @InjectProperty(GameService) - private game!: GameService; - - dispose(): void { - // 清理资源 - } -} -``` - -在 EntitySystem 中使用属性注入： - -```typescript -@Injectable() -class CombatSystem extends EntitySystem { - @InjectProperty(TimeService) - private timeService!: TimeService; - - @InjectProperty(AudioService) - private audio!: AudioService; - - constructor() { - super(Matcher.all(Health, Attack)); - } - - onInitialize(): void { - // 此时属性已注入完成，可以安全使用 - console.log('Delta time:', this.timeService.getDeltaTime()); - } - - processEntity(entity: Entity): void { - // 使用注入的服务 - this.audio.playSound('attack'); - } -} -``` - -> **注意**: 属性声明时使用 `!` 断言（如 `private data!: DataService`），表示该属性会在使用前被注入。 - -### 注册可注入服务 - -使用 `registerInjectable` 自动处理依赖注入： - -```typescript -import { registerInjectable } from '@esengine/ecs-framework'; - -// 注册服务（会自动解析 @InjectProperty 依赖） -registerInjectable(Core.services, PlayerService); - -// 解析时会自动注入属性依赖 -const player = Core.services.resolve(PlayerService); -``` - -### @Updatable 装饰器 - -标记服务为可更新的，使其在每帧自动被调用： - -```typescript -import { Injectable, Updatable, IService, IUpdatable } from '@esengine/ecs-framework'; - -@Injectable() -@Updatable() // 默认优先级为0 -class PhysicsService implements IService, IUpdatable { - update(deltaTime?: number): void { - // 每帧更新物理模拟 - } - - dispose(): void { - // 清理资源 - } -} - -// 指定更新优先级（数值越小越先执行） -@Injectable() -@Updatable(10) -class RenderService implements IService, IUpdatable { - update(deltaTime?: number): void { - // 每帧渲染 - } - - dispose(): void { - // 清理资源 - } -} -``` - -使用 `@Updatable` 装饰器的服务会被 Core 自动调用，无需手动管理： - -```typescript -// Core.update() 会自动调用所有@Updatable服务的update方法 -function gameLoop(deltaTime: number) { - Core.update(deltaTime); // 自动更新所有可更新服务 -} -``` - -## 自定义服务 - -### 创建自定义服务 - -实现 `IService` 接口并注册到容器： - -```typescript -import { IService } from '@esengine/ecs-framework'; - -class AudioService implements IService { - private sounds: Map = new Map(); - - play(soundId: string) { - const sound = this.sounds.get(soundId); - if (sound) { - sound.play(); - } - } - - load(soundId: string, url: string) { - const audio = new Audio(url); - this.sounds.set(soundId, audio); - } - - dispose(): void { - // 停止所有音效并清理 - for (const sound of this.sounds.values()) { - sound.pause(); - sound.src = ''; - } - this.sounds.clear(); - } -} - -// 注册自定义服务 -Core.services.registerSingleton(AudioService); - -// 使用服务 -const audio = Core.services.resolve(AudioService); -audio.load('jump', '/sounds/jump.mp3'); -audio.play('jump'); -``` - -### 服务间依赖 - -服务可以依赖其他服务： - -```typescript -@Injectable() -class ConfigService implements IService { - private config: any = {}; - - get(key: string) { - return this.config[key]; - } - - dispose(): void { - this.config = {}; - } -} - -@Injectable() -class NetworkService implements IService { - constructor( - @Inject(ConfigService) private config: ConfigService - ) { - // 使用配置服务 - const apiUrl = this.config.get('apiUrl'); - } - - dispose(): void { - // 清理网络连接 - } -} - -// 注册服务（按依赖顺序） -registerInjectable(Core.services, ConfigService); -registerInjectable(Core.services, NetworkService); -``` - -## 高级用法 - -### 接口与 Symbol 标识符模式 - -在大型项目或需要跨平台适配的游戏中，推荐使用"接口 + Symbol.for 标识符"模式。这种模式实现了真正的依赖倒置，让代码依赖于抽象而非具体实现。 - -#### 为什么使用 Symbol.for - -- **跨包共享**: `Symbol.for('key')` 在全局 Symbol 注册表中创建/获取 Symbol，确保不同包中使用相同的标识符 -- **接口解耦**: 消费者只依赖接口定义，不依赖具体实现类 -- **可替换实现**: 可以在运行时注入不同的实现（如测试 Mock、不同平台适配） - -#### 定义接口和标识符 - -以音频服务为例，游戏需要在不同平台（Web、微信小游戏、原生App）使用不同的音频实现： - -```typescript -// IAudioService.ts - 定义接口和标识符 -export interface IAudioService { - dispose(): void; - playSound(id: string): void; - playMusic(id: string, loop?: boolean): void; - stopMusic(): void; - setVolume(volume: number): void; - preload(id: string, url: string): Promise; -} - -// 使用 Symbol.for 确保跨包共享同一个 Symbol -export const IAudioService = Symbol.for('IAudioService'); -``` - -#### 实现接口 - -```typescript -// WebAudioService.ts - Web 平台实现 -import { IAudioService } from './IAudioService'; - -export class WebAudioService implements IAudioService { - private audioContext: AudioContext; - private sounds: Map = new Map(); - - constructor() { - this.audioContext = new AudioContext(); - } - - playSound(id: string): void { - const buffer = this.sounds.get(id); - if (buffer) { - const source = this.audioContext.createBufferSource(); - source.buffer = buffer; - source.connect(this.audioContext.destination); - source.start(); - } - } - - async preload(id: string, url: string): Promise { - const response = await fetch(url); - const arrayBuffer = await response.arrayBuffer(); - const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer); - this.sounds.set(id, audioBuffer); - } - - // ... 其他方法实现 - - dispose(): void { - this.audioContext.close(); - this.sounds.clear(); - } -} -``` - -```typescript -// WechatAudioService.ts - 微信小游戏平台实现 -export class WechatAudioService implements IAudioService { - private innerAudioContexts: Map = new Map(); - - playSound(id: string): void { - const ctx = this.innerAudioContexts.get(id); - if (ctx) { - ctx.play(); - } - } - - async preload(id: string, url: string): Promise { - const ctx = wx.createInnerAudioContext(); - ctx.src = url; - this.innerAudioContexts.set(id, ctx); - } - - // ... 其他方法实现 - - dispose(): void { - for (const ctx of this.innerAudioContexts.values()) { - ctx.destroy(); - } - this.innerAudioContexts.clear(); - } -} -``` - -#### 注册和使用 - -```typescript -import { IAudioService } from './IAudioService'; -import { WebAudioService } from './WebAudioService'; -import { WechatAudioService } from './WechatAudioService'; - -// 根据平台注册不同实现 -if (typeof wx !== 'undefined') { - Core.services.registerInstance(IAudioService, new WechatAudioService()); -} else { - Core.services.registerInstance(IAudioService, new WebAudioService()); -} - -// 业务代码中使用 - 不关心具体实现 -const audio = Core.services.resolve(IAudioService); -await audio.preload('explosion', '/sounds/explosion.mp3'); -audio.playSound('explosion'); -``` - -#### 跨模块使用 - -```typescript -// 在游戏系统中使用 -import { IAudioService } from '@mygame/core'; - -class CombatSystem extends EntitySystem { - private audio: IAudioService; - - initialize(): void { - // 获取音频服务，不需要知道具体实现 - this.audio = this.scene.services.resolve(IAudioService); - } - - onEntityDeath(entity: Entity): void { - this.audio.playSound('death'); - } -} -``` - -#### Symbol vs Symbol.for - -```typescript -// Symbol() - 每次创建唯一的 Symbol -const sym1 = Symbol('test'); -const sym2 = Symbol('test'); -console.log(sym1 === sym2); // false - 不同的 Symbol - -// Symbol.for() - 在全局注册表中共享 -const sym3 = Symbol.for('test'); -const sym4 = Symbol.for('test'); -console.log(sym3 === sym4); // true - 同一个 Symbol - -// 跨包场景 -// package-a/index.ts -export const IMyService = Symbol.for('IMyService'); - -// package-b/index.ts (不同的包) -const IMyService = Symbol.for('IMyService'); -// 与 package-a 中的是同一个 Symbol！ -``` - -### 循环依赖检测 - -服务容器会自动检测循环依赖： - -```typescript -// A 依赖 B，B 依赖 A -@Injectable() -class ServiceA implements IService { - constructor(@Inject(ServiceB) b: ServiceB) {} - dispose(): void {} -} - -@Injectable() -class ServiceB implements IService { - constructor(@Inject(ServiceA) a: ServiceA) {} - dispose(): void {} -} - -// 解析时会抛出错误: Circular dependency detected: ServiceA -> ServiceB -> ServiceA -``` - -### 获取所有服务 - -```typescript -// 获取所有已注册的服务类型 -const types = Core.services.getRegisteredServices(); - -// 获取所有已实例化的服务实例 -const instances = Core.services.getAll(); -``` - -### 服务清理 - -```typescript -// 注销单个服务 -Core.services.unregister(MyService); - -// 清空所有服务（会调用每个服务的dispose方法） -Core.services.clear(); -``` - -## 最佳实践 - -### 服务命名 - -服务类名应该以 `Service` 或 `Manager` 结尾，清晰表达其职责： - -```typescript -class PlayerService implements IService {} -class AudioManager implements IService {} -class NetworkService implements IService {} -``` - -### 资源清理 - -始终在 `dispose()` 方法中清理资源： - -```typescript -class ResourceService implements IService { - private resources: Map = new Map(); - - dispose(): void { - // 释放所有资源 - for (const resource of this.resources.values()) { - resource.release(); - } - this.resources.clear(); - } -} -``` - -### 避免过度使用 - -不要把所有类都注册为服务，服务应该是： - -- 全局单例或需要共享状态 -- 需要在多处使用 -- 生命周期需要管理 -- 需要依赖注入 - -对于简单的工具类或数据类，直接创建实例即可。 - -### 依赖方向 - -保持清晰的依赖方向，避免循环依赖： - -``` -高层服务 -> 中层服务 -> 底层服务 -GameLogic -> DataService -> ConfigService -``` - -## 常见问题 - -### 服务未注册错误 - -**问题**: `Error: Service MyService is not registered` - -**解决**: -```typescript -// 确保服务已注册 -Core.services.registerSingleton(MyService); - -// 或者使用tryResolve -const service = Core.services.tryResolve(MyService); -if (!service) { - console.log('Service not found'); -} -``` - -### 循环依赖错误 - -**问题**: `Circular dependency detected` - -**解决**: 重新设计服务依赖关系，引入中间服务或使用事件系统解耦。 - -### 何时使用单例 vs 瞬时 - -- **单例**: 管理器类、配置、缓存、状态管理 -- **瞬时**: 命令对象、请求处理器、临时任务 - -## 相关链接 - -- [插件系统](./plugin-system.md) - 使用服务容器注册插件服务 -- [快速开始](./getting-started.md) - Core 初始化和基础使用 -- [系统架构](./system.md) - 在系统中使用服务 diff --git a/docs/guide/system.md b/docs/guide/system.md deleted file mode 100644 index c44220b7..00000000 --- a/docs/guide/system.md +++ /dev/null @@ -1,1161 +0,0 @@ -# 系统架构 - -在 ECS 架构中，系统（System）是处理业务逻辑的地方。系统负责对拥有特定组件组合的实体执行操作，是 ECS 架构的逻辑处理单元。 - -## 基本概念 - -系统是继承自 `EntitySystem` 抽象基类的具体类，用于： -- 定义实体的处理逻辑（如移动、碰撞检测、渲染等） -- 根据组件组合筛选需要处理的实体 -- 提供生命周期管理和性能监控 -- 管理实体的添加、移除事件 - -## 系统类型 - -框架提供了几种不同类型的系统基类： - -### EntitySystem - 基础系统 - -最基础的系统类，所有其他系统都继承自它： - -```typescript -import { EntitySystem, ECSSystem, Matcher } from '@esengine/ecs-framework'; - -@ECSSystem('Movement') -class MovementSystem extends EntitySystem { - constructor() { - // 使用 Matcher 定义需要处理的实体条件 - super(Matcher.all(Position, Velocity)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const position = entity.getComponent(Position); - const velocity = entity.getComponent(Velocity); - - if (position && velocity) { - position.x += velocity.dx * Time.deltaTime; - position.y += velocity.dy * Time.deltaTime; - } - } - } -} -``` - -### ProcessingSystem - 处理系统 - -适用于不需要逐个处理实体的系统： - -```typescript -@ECSSystem('Physics') -class PhysicsSystem extends ProcessingSystem { - constructor() { - super(); // 不需要指定 Matcher - } - - public processSystem(): void { - // 执行物理世界步进 - this.physicsWorld.step(Time.deltaTime); - } -} -``` - -### PassiveSystem - 被动系统 - -被动系统不进行主动处理，主要用于监听实体的添加和移除事件： - -```typescript -@ECSSystem('EntityTracker') -class EntityTrackerSystem extends PassiveSystem { - constructor() { - super(Matcher.all(Health)); - } - - protected onAdded(entity: Entity): void { - console.log(`生命值实体被添加: ${entity.name}`); - } - - protected onRemoved(entity: Entity): void { - console.log(`生命值实体被移除: ${entity.name}`); - } -} -``` - -### IntervalSystem - 间隔系统 - -按固定时间间隔执行的系统： - -```typescript -@ECSSystem('AutoSave') -class AutoSaveSystem extends IntervalSystem { - constructor() { - // 每 5 秒执行一次 - super(5.0, Matcher.all(SaveData)); - } - - protected process(entities: readonly Entity[]): void { - console.log('执行自动保存...'); - // 保存游戏数据 - this.saveGameData(entities); - } - - private saveGameData(entities: readonly Entity[]): void { - // 保存逻辑 - } -} -``` - -### WorkerEntitySystem - 多线程系统 - -基于Web Worker的多线程处理系统，适用于计算密集型任务，能够充分利用多核CPU性能。 - -Worker系统提供了真正的并行计算能力，支持SharedArrayBuffer优化，并具有自动降级支持。特别适合物理模拟、粒子系统、AI计算等场景。 - -**详细内容请参考：[Worker系统](/guide/worker-system)** - -## 实体匹配器 (Matcher) - -Matcher 用于定义系统需要处理哪些实体。它提供了灵活的条件组合： - -### 基本匹配条件 - -```typescript -// 必须同时拥有 Position 和 Velocity 组件 -const matcher1 = Matcher.all(Position, Velocity); - -// 至少拥有 Health 或 Shield 组件之一 -const matcher2 = Matcher.any(Health, Shield); - -// 不能拥有 Dead 组件 -const matcher3 = Matcher.none(Dead); -``` - -### 复合匹配条件 - -```typescript -// 复杂的组合条件 -const complexMatcher = Matcher.all(Position, Velocity) - .any(Player, Enemy) - .none(Dead, Disabled); - -@ECSSystem('Combat') -class CombatSystem extends EntitySystem { - constructor() { - super(complexMatcher); - } -} -``` - -### 特殊匹配条件 - -```typescript -// 按标签匹配 -const tagMatcher = Matcher.byTag(1); // 匹配标签为 1 的实体 - -// 按名称匹配 -const nameMatcher = Matcher.byName("Player"); // 匹配名称为 "Player" 的实体 - -// 单组件匹配 -const componentMatcher = Matcher.byComponent(Health); // 匹配拥有 Health 组件的实体 - -// 不匹配任何实体 -const nothingMatcher = Matcher.nothing(); // 用于只需要生命周期回调的系统 -``` - -### 空匹配器 vs Nothing 匹配器 - -```typescript -// empty() - 空条件，匹配所有实体 -const emptyMatcher = Matcher.empty(); - -// nothing() - 不匹配任何实体，用于只需要生命周期方法的系统 -const nothingMatcher = Matcher.nothing(); - -// 使用场景：只需要 onBegin/onEnd 生命周期的系统 -@ECSSystem('FrameTimer') -class FrameTimerSystem extends EntitySystem { - constructor() { - super(Matcher.nothing()); // 不处理任何实体 - } - - protected onBegin(): void { - // 每帧开始时执行，例如：记录帧开始时间 - console.log('帧开始'); - } - - protected process(entities: readonly Entity[]): void { - // 永远不会被调用，因为没有匹配的实体 - } - - protected onEnd(): void { - // 每帧结束时执行 - console.log('帧结束'); - } -} -``` - -> 💡 **提示**：更多关于 Matcher 和实体查询的详细用法，请参考 [实体查询系统](/guide/entity-query) 文档。 - -## 系统生命周期 - -系统提供了完整的生命周期回调： - -```typescript -@ECSSystem('Example') -class ExampleSystem extends EntitySystem { - protected onInitialize(): void { - console.log('系统初始化'); - // 系统被添加到场景时调用，用于初始化资源 - } - - protected onBegin(): void { - // 每帧处理开始前调用 - } - - protected process(entities: readonly Entity[]): void { - // 主要的处理逻辑 - for (const entity of entities) { - // 处理每个实体 - // ✅ 可以安全地在这里添加/移除组件，不会影响当前迭代 - } - } - - protected lateProcess(entities: readonly Entity[]): void { - // 主处理之后的后期处理 - // ✅ 可以安全地在这里添加/移除组件，不会影响当前迭代 - } - - protected onEnd(): void { - // 每帧处理结束后调用 - } - - protected onDestroy(): void { - console.log('系统销毁'); - // 系统从场景移除时调用，用于清理资源 - } -} -``` - -## 实体事件监听 - -系统可以监听实体的添加和移除事件： - -```typescript -@ECSSystem('EnemyManager') -class EnemyManagerSystem extends EntitySystem { - private enemyCount = 0; - - constructor() { - super(Matcher.all(Enemy, Health)); - } - - protected onAdded(entity: Entity): void { - this.enemyCount++; - console.log(`敌人加入战斗，当前敌人数量: ${this.enemyCount}`); - - // 可以在这里为新敌人设置初始状态 - const health = entity.getComponent(Health); - if (health) { - health.current = health.max; - } - } - - protected onRemoved(entity: Entity): void { - this.enemyCount--; - console.log(`敌人被移除，剩余敌人数量: ${this.enemyCount}`); - - // 检查是否所有敌人都被消灭 - if (this.enemyCount === 0) { - this.scene?.eventSystem.emitSync('all_enemies_defeated'); - } - } -} -``` - -### 重要：onAdded/onRemoved 的调用时机 - -> ⚠️ **注意**：`onAdded` 和 `onRemoved` 回调是**同步调用**的，会在 `addComponent`/`removeComponent` 返回**之前**立即执行。 - -这意味着： - -```typescript -// ❌ 错误的用法：链式赋值在 onAdded 之后才执行 -const comp = entity.addComponent(new ClickComponent()); -comp.element = this._element; // 此时 onAdded 已经执行完了！ - -// ✅ 正确的用法：通过构造函数传入初始值 -const comp = entity.addComponent(new ClickComponent(this._element)); - -// ✅ 或者使用 createComponent 方法 -const comp = entity.createComponent(ClickComponent, this._element); -``` - -**为什么这样设计？** - -事件驱动设计确保 `onAdded`/`onRemoved` 回调不受系统注册顺序的影响。当组件被添加时，所有监听该组件的系统都会立即收到通知，而不是等到下一帧。 - -**最佳实践：** - -1. 组件的初始值应该通过**构造函数**传入 -2. 不要依赖 `addComponent` 返回后再设置属性 -3. 如果需要在 `onAdded` 中访问组件属性，确保这些属性在构造时已经设置 - -### 在 process/lateProcess 中安全地修改组件 - -在 `process` 或 `lateProcess` 中迭代实体时，可以安全地添加或移除组件，不会影响当前的迭代过程： - -```typescript -@ECSSystem('Damage') -class DamageSystem extends EntitySystem { - constructor() { - super(Matcher.all(Health, DamageReceiver)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - const damage = entity.getComponent(DamageReceiver); - - if (health && damage) { - health.current -= damage.amount; - - // ✅ 安全：移除组件不会影响当前迭代 - entity.removeComponent(damage); - - if (health.current <= 0) { - // ✅ 安全：添加组件也不会影响当前迭代 - entity.addComponent(new Dead()); - } - } - } - } -} -``` - -框架会在每次 `process`/`lateProcess` 调用前创建实体列表的快照，确保迭代过程中的组件变化不会导致跳过实体或重复处理。 - -## 命令缓冲区 (CommandBuffer) - -> **v2.3.0+** - -CommandBuffer 提供了一种延迟执行实体操作的机制。当你需要在迭代过程中销毁实体或进行其他可能影响迭代的操作时，使用 CommandBuffer 可以将这些操作推迟到帧末统一执行。 - -### 基本用法 - -每个 EntitySystem 都内置了 `commands` 属性： - -```typescript -@ECSSystem('Damage') -class DamageSystem extends EntitySystem { - constructor() { - super(Matcher.all(Health, DamageReceiver)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - const damage = entity.getComponent(DamageReceiver); - - if (health && damage) { - health.current -= damage.amount; - - // 使用命令缓冲区延迟移除组件 - this.commands.removeComponent(entity, DamageReceiver); - - if (health.current <= 0) { - // 延迟添加死亡标记 - this.commands.addComponent(entity, new Dead()); - // 延迟销毁实体 - this.commands.destroyEntity(entity); - } - } - } - } -} -``` - -### 支持的命令 - -| 方法 | 说明 | -|------|------| -| `addComponent(entity, component)` | 延迟添加组件 | -| `removeComponent(entity, ComponentType)` | 延迟移除组件 | -| `destroyEntity(entity)` | 延迟销毁实体 | -| `setEntityActive(entity, active)` | 延迟设置实体激活状态 | - -### 执行时机 - -命令缓冲区中的命令会在每帧的 `lateUpdate` 阶段之后自动执行。执行顺序与命令入队顺序一致。 - -``` -场景更新流程: -1. onBegin() -2. process() -3. lateProcess() -4. onEnd() -5. flushCommandBuffers() <-- 命令在这里执行 -``` - -### 使用场景 - -CommandBuffer 适用于以下场景： - -1. **在迭代中销毁实体**：避免修改正在遍历的集合 -2. **批量延迟操作**：将多个操作合并到帧末执行 -3. **跨系统协调**：一个系统标记，另一个系统响应 - -```typescript -// 示例：敌人死亡系统 -@ECSSystem('EnemyDeath') -class EnemyDeathSystem extends EntitySystem { - constructor() { - super(Matcher.all(Enemy, Health)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const health = entity.getComponent(Health); - if (health && health.current <= 0) { - // 播放死亡动画、掉落物品等 - this.spawnLoot(entity); - - // 延迟销毁，不影响当前迭代 - this.commands.destroyEntity(entity); - } - } - } - - private spawnLoot(entity: Entity): void { - // 掉落物品逻辑 - } -} -``` - -### 注意事项 - -- 命令会跳过已销毁的实体（安全检查） -- 单个命令执行失败不会影响其他命令 -- 命令按入队顺序执行 -- 每次 `flush()` 后命令队列会清空 - -## 系统属性和方法 - -### 重要属性 - -```typescript -@ECSSystem('Example') -class ExampleSystem extends EntitySystem { - showSystemInfo(): void { - console.log(`系统名称: ${this.systemName}`); // 系统名称 - console.log(`更新顺序: ${this.updateOrder}`); // 更新时序 - console.log(`是否启用: ${this.enabled}`); // 启用状态 - console.log(`实体数量: ${this.entities.length}`); // 匹配的实体数量 - console.log(`所属场景: ${this.scene?.name}`); // 所属场景 - } -} -``` - -### 实体访问 - -```typescript -protected process(entities: readonly Entity[]): void { - // 方式1：使用参数中的实体列表 - for (const entity of entities) { - // 处理实体 - } - - // 方式2：使用 this.entities 属性（与参数相同） - for (const entity of this.entities) { - // 处理实体 - } -} -``` - -### 控制系统执行 - -```typescript -@ECSSystem('Conditional') -class ConditionalSystem extends EntitySystem { - private shouldProcess = true; - - protected onCheckProcessing(): boolean { - // 返回 false 时跳过本次处理 - return this.shouldProcess && this.entities.length > 0; - } - - public pause(): void { - this.shouldProcess = false; - } - - public resume(): void { - this.shouldProcess = true; - } -} -``` - -## 事件系统集成 - -系统可以方便地监听和发送事件： - -```typescript -@ECSSystem('GameLogic') -class GameLogicSystem extends EntitySystem { - protected onInitialize(): void { - // 添加事件监听器（系统销毁时自动清理） - this.addEventListener('player_died', this.onPlayerDied.bind(this)); - this.addEventListener('level_complete', this.onLevelComplete.bind(this)); - } - - private onPlayerDied(data: any): void { - console.log('玩家死亡，重新开始游戏'); - // 处理玩家死亡逻辑 - } - - private onLevelComplete(data: any): void { - console.log('关卡完成，加载下一关'); - // 处理关卡完成逻辑 - } - - protected process(entities: readonly Entity[]): void { - // 在处理过程中发送事件 - for (const entity of entities) { - const health = entity.getComponent(Health); - if (health && health.current <= 0) { - this.scene?.eventSystem.emitSync('entity_died', { entity }); - } - } - } -} -``` - -## 性能监控 - -系统内置了性能监控功能： - -```typescript -@ECSSystem('Performance') -class PerformanceSystem extends EntitySystem { - protected onEnd(): void { - // 获取性能数据 - const perfData = this.getPerformanceData(); - if (perfData) { - console.log(`执行时间: ${perfData.executionTime.toFixed(2)}ms`); - } - - // 获取性能统计 - const stats = this.getPerformanceStats(); - if (stats) { - console.log(`平均执行时间: ${stats.averageTime.toFixed(2)}ms`); - } - } - - public resetPerformance(): void { - this.resetPerformanceData(); - } -} -``` - -## 系统管理 - -### 添加系统到场景 - -框架提供了两种方式添加系统：传入实例或传入类型（自动依赖注入）。 - -```typescript -// 在场景子类中添加系统 -class GameScene extends Scene { - protected initialize(): void { - // 方式1：传入实例 - this.addSystem(new MovementSystem()); - this.addSystem(new RenderSystem()); - - // 方式2：传入类型（自动依赖注入） - this.addEntityProcessor(PhysicsSystem); - - // 设置系统更新顺序 - const movementSystem = this.getSystem(MovementSystem); - if (movementSystem) { - movementSystem.updateOrder = 1; - } - } -} -``` - -### 系统依赖注入 - -系统实现了 `IService` 接口，支持通过依赖注入获取其他服务或系统： - -```typescript -import { ECSSystem, Injectable, Inject } from '@esengine/ecs-framework'; - -@Injectable() -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - constructor( - @Inject(CollisionService) private collision: CollisionService - ) { - super(Matcher.all(Transform, RigidBody)); - } - - protected process(entities: readonly Entity[]): void { - // 使用注入的服务 - this.collision.detectCollisions(entities); - } - - // 实现 IService 接口的 dispose 方法 - public dispose(): void { - // 清理资源 - } -} - -// 使用时传入类型即可，框架会自动注入依赖 -class GameScene extends Scene { - protected initialize(): void { - // 自动依赖注入 - this.addEntityProcessor(PhysicsSystem); - } -} -``` - -注意事项： -- 使用 `@Injectable()` 装饰器标记需要依赖注入的系统 -- 在构造函数参数中使用 `@Inject()` 装饰器声明依赖 -- 系统必须实现 `dispose()` 方法（IService 接口要求） -- 使用 `addEntityProcessor(类型)` 而不是 `addSystem(new 类型())` 来启用依赖注入 - -### 系统更新顺序 - -系统的执行顺序由 `updateOrder` 属性决定，数值越小越先执行： - -```typescript -@ECSSystem('Input') -class InputSystem extends EntitySystem { - constructor() { - super(Matcher.all(InputComponent)); - this.updateOrder = -100; // 输入系统优先执行 - } -} - -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - constructor() { - super(Matcher.all(RigidBody)); - this.updateOrder = 0; // 默认顺序 - } -} - -@ECSSystem('Render') -class RenderSystem extends EntitySystem { - constructor() { - super(Matcher.all(Sprite, Transform)); - this.updateOrder = 100; // 渲染系统最后执行 - } -} -``` - -#### 稳定排序：addOrder - -当多个系统的 `updateOrder` 相同时，框架使用 `addOrder`（添加顺序）作为第二排序条件，确保排序结果稳定可预测： - -```typescript -// 这两个系统 updateOrder 都是默认值 0 -@ECSSystem('SystemA') -class SystemA extends EntitySystem { /* ... */ } - -@ECSSystem('SystemB') -class SystemB extends EntitySystem { /* ... */ } - -// 添加顺序决定了执行顺序 -scene.addSystem(new SystemA()); // addOrder = 0，先执行 -scene.addSystem(new SystemB()); // addOrder = 1，后执行 -``` - -> **注意**：`addOrder` 由框架在 `addSystem` 时自动设置，无需手动管理。这确保了相同 `updateOrder` 的系统按照添加顺序执行，避免了排序不稳定导致的随机行为。 - -## 声明式系统调度 - -> **v2.4.0+** - -除了使用 `updateOrder` 手动控制执行顺序外，框架还提供了声明式的系统调度机制，让你可以通过依赖关系来定义系统的执行顺序。 - -### 调度装饰器 - -```typescript -import { EntitySystem, ECSSystem, Stage, Before, After, InSet } from '@esengine/ecs-framework'; - -// 使用装饰器声明系统调度 -@ECSSystem('Movement') -@Stage('update') // 在 update 阶段执行 -@After('InputSystem') // 在 InputSystem 之后执行 -@Before('RenderSystem') // 在 RenderSystem 之前执行 -class MovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - } - - protected process(entities: readonly Entity[]): void { - // 移动逻辑 - } -} - -// 使用系统集合进行分组 -@ECSSystem('Physics') -@Stage('update') -@InSet('CoreSystems') // 属于 CoreSystems 集合 -class PhysicsSystem extends EntitySystem { - // ... -} - -@ECSSystem('Collision') -@Stage('update') -@After('set:CoreSystems') // 在 CoreSystems 集合的所有系统之后执行 -class CollisionSystem extends EntitySystem { - // ... -} -``` - -### 系统执行阶段 - -框架定义了以下系统执行阶段，按顺序执行： - -| 阶段 | 说明 | 典型用途 | -|------|------|----------| -| `startup` | 启动阶段 | 一次性初始化 | -| `preUpdate` | 更新前阶段 | 输入处理、状态准备 | -| `update` | 主更新阶段（默认） | 核心游戏逻辑 | -| `postUpdate` | 更新后阶段 | 物理、碰撞检测 | -| `cleanup` | 清理阶段 | 资源清理、状态重置 | - -### Fluent API 配置 - -如果不想使用装饰器，也可以使用 Fluent API 在运行时配置调度： - -```typescript -@ECSSystem('Movement') -class MovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - - // 使用 Fluent API 配置调度 - this.stage('update') - .after('InputSystem') - .before('RenderSystem') - .inSet('CoreSystems'); - } -} -``` - -### 循环依赖检测 - -框架会自动检测循环依赖并抛出明确的错误： - -```typescript -// 这会导致循环依赖错误 -@ECSSystem('SystemA') -@Before('SystemB') -class SystemA extends EntitySystem { } - -@ECSSystem('SystemB') -@Before('SystemA') // 错误：A -> B -> A 形成循环 -class SystemB extends EntitySystem { } - -// 错误信息：Cyclic dependency detected: SystemA -> SystemB -> SystemA -``` - -## 帧级变更检测 - -> **v2.4.0+** - -框架提供了基于 epoch 的帧级变更检测机制，让系统可以只处理发生变化的实体，大幅提升性能。 - -### 核心概念 - -- **Epoch**：全局帧计数器，每帧递增 -- **lastWriteEpoch**：组件最后被修改时的 epoch -- **变更检测**：通过比较 epoch 判断组件是否在指定时间点后发生变化 - -### 标记组件为已修改 - -修改组件数据后，需要标记组件为已变更。有两种方式： - -**方式 1：通过 Entity 辅助方法（推荐）** - -```typescript -// 修改组件后通过 entity.markDirty() 标记 -const pos = entity.getComponent(Position)!; -pos.x = 100; -pos.y = 200; -entity.markDirty(pos); - -// 可以同时标记多个组件 -const vel = entity.getComponent(Velocity)!; -vel.vx = 10; -entity.markDirty(pos, vel); -``` - -**方式 2：在组件内部封装** - -```typescript -class VelocityComponent extends Component { - private _vx: number = 0; - private _vy: number = 0; - - // 提供修改方法，接收 epoch 参数 - public setVelocity(vx: number, vy: number, epoch: number): void { - this._vx = vx; - this._vy = vy; - this.markDirty(epoch); - } - - public get vx(): number { return this._vx; } - public get vy(): number { return this._vy; } -} - -// 在系统中使用 -const vel = entity.getComponent(VelocityComponent)!; -vel.setVelocity(10, 20, this.currentEpoch); -``` - -### 在系统中使用变更检测 - -EntitySystem 提供了多个变更检测辅助方法： - -```typescript -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - } - - protected process(entities: readonly Entity[]): void { - // 方式1：使用 forEachChanged 只处理变更的实体 - // 自动保存 epoch 检查点 - this.forEachChanged(entities, [Velocity], (entity) => { - const pos = this.requireComponent(entity, Position); - const vel = this.requireComponent(entity, Velocity); - - // 只有 Velocity 变化时才更新位置 - pos.x += vel.vx * Time.deltaTime; - pos.y += vel.vy * Time.deltaTime; - }); - } -} - -@ECSSystem('Transform') -class TransformSystem extends EntitySystem { - constructor() { - super(Matcher.all(Transform, RigidBody)); - } - - protected process(entities: readonly Entity[]): void { - // 方式2：使用 filterChanged 获取变更的实体列表 - const changedEntities = this.filterChanged(entities, [RigidBody]); - - for (const entity of changedEntities) { - // 处理物理状态变化的实体 - this.updatePhysics(entity); - } - - // 手动保存 epoch 检查点 - this.saveEpoch(); - } - - protected updatePhysics(entity: Entity): void { - // 物理更新逻辑 - } -} -``` - -### 变更检测 API 参考 - -| 方法 | 说明 | -|------|------| -| `forEachChanged(entities, [Types], callback)` | 遍历指定组件发生变更的实体，自动保存检查点 | -| `filterChanged(entities, [Types])` | 返回指定组件发生变更的实体数组 | -| `hasChanged(entity, [Types])` | 检查单个实体的指定组件是否发生变更 | -| `saveEpoch()` | 手动保存当前 epoch 作为检查点 | -| `lastProcessEpoch` | 获取上次保存的 epoch 检查点 | -| `currentEpoch` | 获取当前场景的 epoch | - -### 使用场景 - -变更检测特别适合以下场景： - -1. **脏标记优化**：只在数据变化时更新渲染 -2. **物理同步**：只同步位置/速度发生变化的实体 -3. **网络同步**：只发送变化的组件数据 -4. **缓存失效**：只在依赖数据变化时重新计算 - -```typescript -@ECSSystem('NetworkSync') -class NetworkSyncSystem extends EntitySystem { - constructor() { - super(Matcher.all(NetworkComponent, Transform)); - } - - protected process(entities: readonly Entity[]): void { - // 只同步变化的实体，大幅减少网络流量 - this.forEachChanged(entities, [Transform], (entity) => { - const transform = this.requireComponent(entity, Transform); - const network = this.requireComponent(entity, NetworkComponent); - - this.sendTransformUpdate(network.id, transform); - }); - } - - private sendTransformUpdate(id: string, transform: Transform): void { - // 发送网络更新 - } -} -``` - -## 复杂系统示例 - -### 碰撞检测系统 - -```typescript -@ECSSystem('Collision') -class CollisionSystem extends EntitySystem { - constructor() { - super(Matcher.all(Transform, Collider)); - } - - protected process(entities: readonly Entity[]): void { - // 简单的 n² 碰撞检测 - for (let i = 0; i < entities.length; i++) { - for (let j = i + 1; j < entities.length; j++) { - this.checkCollision(entities[i], entities[j]); - } - } - } - - private checkCollision(entityA: Entity, entityB: Entity): void { - const transformA = entityA.getComponent(Transform); - const transformB = entityB.getComponent(Transform); - const colliderA = entityA.getComponent(Collider); - const colliderB = entityB.getComponent(Collider); - - if (this.isColliding(transformA, colliderA, transformB, colliderB)) { - // 发送碰撞事件 - this.scene?.eventSystem.emitSync('collision', { - entityA, - entityB - }); - } - } - - private isColliding(transformA: Transform, colliderA: Collider, - transformB: Transform, colliderB: Collider): boolean { - // 碰撞检测逻辑 - return false; // 简化示例 - } -} -``` - -### 状态机系统 - -```typescript -@ECSSystem('StateMachine') -class StateMachineSystem extends EntitySystem { - constructor() { - super(Matcher.all(StateMachine)); - } - - protected process(entities: readonly Entity[]): void { - for (const entity of entities) { - const stateMachine = entity.getComponent(StateMachine); - if (stateMachine) { - stateMachine.updateTimer(Time.deltaTime); - this.updateState(entity, stateMachine); - } - } - } - - private updateState(entity: Entity, stateMachine: StateMachine): void { - switch (stateMachine.currentState) { - case EntityState.Idle: - this.handleIdleState(entity, stateMachine); - break; - case EntityState.Moving: - this.handleMovingState(entity, stateMachine); - break; - case EntityState.Attacking: - this.handleAttackingState(entity, stateMachine); - break; - } - } - - private handleIdleState(entity: Entity, stateMachine: StateMachine): void { - // 空闲状态逻辑 - } - - private handleMovingState(entity: Entity, stateMachine: StateMachine): void { - // 移动状态逻辑 - } - - private handleAttackingState(entity: Entity, stateMachine: StateMachine): void { - // 攻击状态逻辑 - } -} -``` - -## 最佳实践 - -### 1. 系统单一职责 - -```typescript -// ✅ 好的系统设计 - 职责单一 -@ECSSystem('Movement') -class MovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Position, Velocity)); - } -} - -@ECSSystem('Rendering') -class RenderingSystem extends EntitySystem { - constructor() { - super(Matcher.all(Sprite, Transform)); - } -} - -// ❌ 避免的系统设计 - 职责过多 -@ECSSystem('GameSystem') -class GameSystem extends EntitySystem { - // 一个系统处理移动、渲染、音效等多种逻辑 -} -``` - -### 2. 使用 @ECSSystem 装饰器 - -`@ECSSystem` 是系统类必须使用的装饰器，它为系统提供类型标识和元数据管理。 - -#### 为什么必须使用 - -| 功能 | 说明 | -|------|------| -| **类型识别** | 提供稳定的系统名称，代码混淆后仍能正确识别 | -| **调试支持** | 在性能监控、日志和调试工具中显示可读的系统名称 | -| **系统管理** | 通过名称查找和管理系统 | -| **序列化支持** | 场景序列化时可以记录系统配置 | - -#### 基本语法 - -```typescript -@ECSSystem(systemName: string) -``` - -- `systemName`: 系统的名称，建议使用描述性的名称 - -#### 使用示例 - -```typescript -// ✅ 正确的用法 -@ECSSystem('Physics') -class PhysicsSystem extends EntitySystem { - // 系统实现 -} - -// ✅ 推荐：使用描述性的名称 -@ECSSystem('PlayerMovement') -class PlayerMovementSystem extends EntitySystem { - constructor() { - super(Matcher.all(Player, Position, Velocity)); - } -} - -// ❌ 错误的用法 - 没有装饰器 -class BadSystem extends EntitySystem { - // 这样定义的系统可能在生产环境出现问题： - // 1. 代码压缩后类名变化，无法正确识别 - // 2. 性能监控和调试工具显示不正确的名称 -} -``` - -#### 系统名称的作用 - -```typescript -@ECSSystem('Combat') -class CombatSystem extends EntitySystem { - protected onInitialize(): void { - // 使用 systemName 属性访问系统名称 - console.log(`系统 ${this.systemName} 已初始化`); // 输出: 系统 Combat 已初始化 - } -} - -// 通过名称查找系统 -const combat = scene.getSystemByName('Combat'); - -// 性能监控中会显示系统名称 -const perfData = combatSystem.getPerformanceData(); -console.log(`${combatSystem.systemName} 执行时间: ${perfData?.executionTime}ms`); -``` - -### 3. 合理的更新顺序 - -```typescript -// 按逻辑顺序设置系统的更新时序 -@ECSSystem('Input') -class InputSystem extends EntitySystem { - constructor() { - super(); - this.updateOrder = -100; // 最先处理输入 - } -} - -@ECSSystem('Logic') -class GameLogicSystem extends EntitySystem { - constructor() { - super(); - this.updateOrder = 0; // 处理游戏逻辑 - } -} - -@ECSSystem('Render') -class RenderSystem extends EntitySystem { - constructor() { - super(); - this.updateOrder = 100; // 最后进行渲染 - } -} -``` - -### 4. 避免在系统间直接引用 - -```typescript -// ❌ 避免：系统间直接引用 -@ECSSystem('Bad') -class BadSystem extends EntitySystem { - private otherSystem: SomeOtherSystem; // 避免直接引用其他系统 -} - -// ✅ 推荐：通过事件系统通信 -@ECSSystem('Good') -class GoodSystem extends EntitySystem { - protected process(entities: readonly Entity[]): void { - // 通过事件系统与其他系统通信 - this.scene?.eventSystem.emitSync('data_updated', { entities }); - } -} -``` - -### 5. 及时清理资源 - -```typescript -@ECSSystem('Resource') -class ResourceSystem extends EntitySystem { - private resources: Map = new Map(); - - protected onDestroy(): void { - // 清理资源 - for (const [key, resource] of this.resources) { - if (resource.dispose) { - resource.dispose(); - } - } - this.resources.clear(); - } -} -``` - -系统是 ECS 架构的逻辑处理核心，正确设计和使用系统能让你的游戏代码更加模块化、高效和易于维护。 diff --git a/docs/guide/world-manager.md b/docs/guide/world-manager.md deleted file mode 100644 index 268f831a..00000000 --- a/docs/guide/world-manager.md +++ /dev/null @@ -1,761 +0,0 @@ -# WorldManager - -WorldManager 是 ECS Framework 提供的高级世界管理器，用于管理多个完全隔离的游戏世界（World）。每个 World 都是独立的 ECS 环境，可以包含多个场景。 - -## 适用场景 - -WorldManager 适合以下高级场景： -- MMO 游戏服务器的多房间管理 -- 游戏大厅系统（每个游戏房间完全隔离） -- 服务器端的多游戏实例 -- 需要完全隔离的多个游戏环境 -- 需要同时运行多个独立世界的应用 - -## 特点 - -- 多 World 管理，每个 World 完全独立 -- 每个 World 可以包含多个 Scene -- 支持 World 的激活/停用 -- 自动清理空 World -- World 级别的全局系统 -- 批量操作和查询 - -## 基本使用 - -### 初始化 - -WorldManager 是 Core 的内置服务，通过服务容器获取： - -```typescript -import { Core, WorldManager } from '@esengine/ecs-framework'; - -// 初始化 Core -Core.create({ debug: true }); - -// 从服务容器获取 WorldManager（Core 已自动创建并注册） -const worldManager = Core.services.resolve(WorldManager); -``` - -### 创建 World - -```typescript -// 创建游戏房间 World -const room1 = worldManager.createWorld('room_001', { - name: 'GameRoom_001', - maxScenes: 5, - debug: true -}); - -// 激活 World -worldManager.setWorldActive('room_001', true); - -// 创建更多房间 -const room2 = worldManager.createWorld('room_002', { - name: 'GameRoom_002', - maxScenes: 5 -}); - -worldManager.setWorldActive('room_002', true); -``` - -### 游戏循环 - -在游戏循环中更新所有活跃的 World： - -```typescript -function gameLoop(deltaTime: number) { - Core.update(deltaTime); // 更新全局服务 - worldManager.updateAll(); // 更新所有活跃的 World -} - -// 启动游戏循环 -let lastTime = 0; -setInterval(() => { - const currentTime = Date.now(); - const deltaTime = (currentTime - lastTime) / 1000; - lastTime = currentTime; - - gameLoop(deltaTime); -}, 16); // 60 FPS -``` - -## World 管理 - -### 创建 World - -```typescript -// 基本创建 -const world = worldManager.createWorld('worldId'); - -// 带配置创建 -const world = worldManager.createWorld('worldId', { - name: 'MyWorld', - maxScenes: 10, - autoCleanup: true, - debug: true -}); -``` - -**配置选项（IWorldConfig）**： -- `name?: string` - World 名称 -- `maxScenes?: number` - 最大场景数量限制（默认 10） -- `autoCleanup?: boolean` - 是否自动清理空场景（默认 true） -- `debug?: boolean` - 是否启用调试模式（默认 false） - -### 获取 World - -```typescript -// 通过 ID 获取 -const world = worldManager.getWorld('room_001'); -if (world) { - console.log(`World: ${world.name}`); -} - -// 获取所有 World -const allWorlds = worldManager.getAllWorlds(); -console.log(`共有 ${allWorlds.length} 个 World`); - -// 获取所有 World ID -const worldIds = worldManager.getWorldIds(); -console.log('World 列表:', worldIds); - -// 通过名称查找 -const world = worldManager.findWorldByName('GameRoom_001'); -``` - -### 激活和停用 World - -```typescript -// 激活 World（开始运行和更新） -worldManager.setWorldActive('room_001', true); - -// 停用 World（停止更新但保留数据） -worldManager.setWorldActive('room_001', false); - -// 检查 World 是否激活 -if (worldManager.isWorldActive('room_001')) { - console.log('房间正在运行'); -} - -// 获取所有活跃的 World -const activeWorlds = worldManager.getActiveWorlds(); -console.log(`当前有 ${activeWorlds.length} 个活跃 World`); -``` - -### 移除 World - -```typescript -// 移除 World（会自动停用并销毁） -const removed = worldManager.removeWorld('room_001'); -if (removed) { - console.log('World 已移除'); -} -``` - -## World 中的场景管理 - -每个 World 可以包含多个 Scene 并独立管理它们的生命周期。 - -### 创建场景 - -```typescript -const world = worldManager.getWorld('room_001'); -if (!world) return; - -// 创建场景 -const mainScene = world.createScene('main', new MainScene()); -const uiScene = world.createScene('ui', new UIScene()); -const hudScene = world.createScene('hud', new HUDScene()); - -// 激活场景 -world.setSceneActive('main', true); -world.setSceneActive('ui', true); -world.setSceneActive('hud', false); -``` - -### 查询场景 - -```typescript -// 获取特定场景 -const mainScene = world.getScene('main'); -if (mainScene) { - console.log(`场景名称: ${mainScene.name}`); -} - -// 获取所有场景 -const allScenes = world.getAllScenes(); -console.log(`World 中共有 ${allScenes.length} 个场景`); - -// 获取所有场景 ID -const sceneIds = world.getSceneIds(); -console.log('场景列表:', sceneIds); - -// 获取活跃场景数量 -const activeCount = world.getActiveSceneCount(); -console.log(`当前有 ${activeCount} 个活跃场景`); - -// 检查场景是否激活 -if (world.isSceneActive('main')) { - console.log('主场景正在运行'); -} -``` - -### 场景切换 - -World 支持多场景同时运行，也支持场景切换： - -```typescript -class GameWorld { - private world: World; - - constructor(worldManager: WorldManager) { - this.world = worldManager.createWorld('game', { - name: 'GameWorld', - maxScenes: 5 - }); - - // 创建所有场景 - this.world.createScene('menu', new MenuScene()); - this.world.createScene('game', new GameScene()); - this.world.createScene('pause', new PauseScene()); - this.world.createScene('gameover', new GameOverScene()); - - // 激活 World - worldManager.setWorldActive('game', true); - } - - public showMenu(): void { - this.deactivateAllScenes(); - this.world.setSceneActive('menu', true); - } - - public startGame(): void { - this.deactivateAllScenes(); - this.world.setSceneActive('game', true); - } - - public pauseGame(): void { - // 游戏场景继续存在但停止更新 - this.world.setSceneActive('game', false); - // 显示暂停界面 - this.world.setSceneActive('pause', true); - } - - public resumeGame(): void { - this.world.setSceneActive('pause', false); - this.world.setSceneActive('game', true); - } - - public showGameOver(): void { - this.deactivateAllScenes(); - this.world.setSceneActive('gameover', true); - } - - private deactivateAllScenes(): void { - const sceneIds = this.world.getSceneIds(); - sceneIds.forEach(id => this.world.setSceneActive(id, false)); - } -} -``` - -### 移除场景 - -```typescript -// 移除不再需要的场景 -const removed = world.removeScene('oldScene'); -if (removed) { - console.log('场景已移除'); -} - -// 场景会自动调用 end() 方法进行清理 -``` - -## 全局系统 - -World 支持全局系统，这些系统在 World 级别运行，不依赖特定 Scene。 - -### 定义全局系统 - -```typescript -import { IGlobalSystem } from '@esengine/ecs-framework'; - -// 网络系统（World 级别） -class NetworkSystem implements IGlobalSystem { - readonly name = 'NetworkSystem'; - - private connectionId: string; - - constructor(connectionId: string) { - this.connectionId = connectionId; - } - - initialize(): void { - console.log(`网络系统初始化: ${this.connectionId}`); - // 建立网络连接 - } - - update(deltaTime?: number): void { - // 处理网络消息，不依赖任何 Scene - // 接收和发送网络包 - } - - destroy(): void { - console.log(`网络系统销毁: ${this.connectionId}`); - // 关闭网络连接 - } -} - -// 物理系统（World 级别） -class PhysicsSystem implements IGlobalSystem { - readonly name = 'PhysicsSystem'; - - initialize(): void { - console.log('物理系统初始化'); - } - - update(deltaTime?: number): void { - // 物理模拟，作用于 World 中所有场景 - } - - destroy(): void { - console.log('物理系统销毁'); - } -} -``` - -### 使用全局系统 - -```typescript -const world = worldManager.getWorld('room_001'); -if (!world) return; - -// 添加全局系统 -const networkSystem = world.addGlobalSystem(new NetworkSystem('conn_001')); -const physicsSystem = world.addGlobalSystem(new PhysicsSystem()); - -// 获取全局系统 -const network = world.getGlobalSystem(NetworkSystem); -if (network) { - console.log('找到网络系统'); -} - -// 移除全局系统 -world.removeGlobalSystem(networkSystem); -``` - -## 批量操作 - -### 更新所有 World - -```typescript -// 更新所有活跃的 World（应该在游戏循环中调用） -worldManager.updateAll(); - -// 这会自动更新每个 World 的： -// 1. 全局系统 -// 2. 所有活跃场景 -``` - -### 启动和停止 - -```typescript -// 启动所有 World -worldManager.startAll(); - -// 停止所有 World -worldManager.stopAll(); - -// 检查是否正在运行 -if (worldManager.isRunning) { - console.log('WorldManager 正在运行'); -} -``` - -### 查找 World - -```typescript -// 使用条件查找 -const emptyWorlds = worldManager.findWorlds(world => { - return world.sceneCount === 0; -}); - -// 查找活跃的 World -const activeWorlds = worldManager.findWorlds(world => { - return world.isActive; -}); - -// 查找特定名称的 World -const world = worldManager.findWorldByName('GameRoom_001'); -``` - -## 统计和监控 - -### 获取统计信息 - -```typescript -const stats = worldManager.getStats(); - -console.log(`总 World 数: ${stats.totalWorlds}`); -console.log(`活跃 World 数: ${stats.activeWorlds}`); -console.log(`总场景数: ${stats.totalScenes}`); -console.log(`总实体数: ${stats.totalEntities}`); -console.log(`总系统数: ${stats.totalSystems}`); - -// 查看每个 World 的详细信息 -stats.worlds.forEach(worldInfo => { - console.log(`World: ${worldInfo.name}`); - console.log(` 场景数: ${worldInfo.sceneCount}`); - console.log(` 是否活跃: ${worldInfo.isActive}`); -}); -``` - -### 获取详细状态 - -```typescript -const status = worldManager.getDetailedStatus(); - -// 包含所有 World 的详细状态 -status.worlds.forEach(worldStatus => { - console.log(`World ID: ${worldStatus.id}`); - console.log(`状态:`, worldStatus.status); -}); -``` - -## 自动清理 - -WorldManager 支持自动清理空的 World。 - -### 配置清理 - -```typescript -// 创建带清理配置的 WorldManager -const worldManager = Core.services.resolve(WorldManager); - -// WorldManager 的配置在 Core 中设置： -// { -// maxWorlds: 50, -// autoCleanup: true, -// cleanupFrameInterval: 1800 // 间隔多少帧清理闲置 World -// } -``` - -### 手动清理 - -```typescript -// 手动触发清理 -const cleanedCount = worldManager.cleanup(); -console.log(`清理了 ${cleanedCount} 个 World`); -``` - -**清理条件**： -- World 未激活 -- 没有 Scene 或所有 Scene 都是空的 -- 创建时间超过 10 分钟 - -## API 参考 - -### WorldManager API - -| 方法 | 说明 | -|------|------| -| `createWorld(worldId, config?)` | 创建新 World | -| `removeWorld(worldId)` | 移除 World | -| `getWorld(worldId)` | 获取 World | -| `getAllWorlds()` | 获取所有 World | -| `getWorldIds()` | 获取所有 World ID | -| `setWorldActive(worldId, active)` | 设置 World 激活状态 | -| `isWorldActive(worldId)` | 检查 World 是否激活 | -| `getActiveWorlds()` | 获取所有活跃的 World | -| `updateAll()` | 更新所有活跃 World | -| `startAll()` | 启动所有 World | -| `stopAll()` | 停止所有 World | -| `findWorlds(predicate)` | 查找满足条件的 World | -| `findWorldByName(name)` | 根据名称查找 World | -| `getStats()` | 获取统计信息 | -| `getDetailedStatus()` | 获取详细状态信息 | -| `cleanup()` | 清理空 World | -| `destroy()` | 销毁 WorldManager | - -### World API - -| 方法 | 说明 | -|------|------| -| `createScene(sceneId, sceneInstance?)` | 创建并添加 Scene | -| `removeScene(sceneId)` | 移除 Scene | -| `getScene(sceneId)` | 获取 Scene | -| `getAllScenes()` | 获取所有 Scene | -| `getSceneIds()` | 获取所有 Scene ID | -| `setSceneActive(sceneId, active)` | 设置 Scene 激活状态 | -| `isSceneActive(sceneId)` | 检查 Scene 是否激活 | -| `getActiveSceneCount()` | 获取活跃 Scene 数量 | -| `addGlobalSystem(system)` | 添加全局系统 | -| `removeGlobalSystem(system)` | 移除全局系统 | -| `getGlobalSystem(type)` | 获取全局系统 | -| `start()` | 启动 World | -| `stop()` | 停止 World | -| `updateGlobalSystems()` | 更新全局系统 | -| `updateScenes()` | 更新所有激活 Scene | -| `destroy()` | 销毁 World | -| `getStatus()` | 获取 World 状态 | -| `getStats()` | 获取统计信息 | - -### 属性 - -| 属性 | 说明 | -|------|------| -| `worldCount` | World 总数 | -| `activeWorldCount` | 活跃 World 数量 | -| `isRunning` | 是否正在运行 | -| `config` | 配置信息 | - -## 完整示例 - -### MMO 游戏房间系统 - -```typescript -import { Core, WorldManager, Scene, World } from '@esengine/ecs-framework'; - -// 初始化 -Core.create({ debug: true }); -const worldManager = Core.services.resolve(WorldManager); - -// 房间管理器 -class RoomManager { - private worldManager: WorldManager; - private rooms: Map = new Map(); - - constructor(worldManager: WorldManager) { - this.worldManager = worldManager; - } - - // 创建游戏房间 - public createRoom(roomId: string, maxPlayers: number): World { - const world = this.worldManager.createWorld(roomId, { - name: `Room_${roomId}`, - maxScenes: 3, - debug: true - }); - - // 创建房间场景 - world.createScene('lobby', new LobbyScene()); - world.createScene('game', new GameScene()); - world.createScene('result', new ResultScene()); - - // 添加房间级别的系统 - world.addGlobalSystem(new NetworkSystem(roomId)); - world.addGlobalSystem(new RoomLogicSystem(maxPlayers)); - - // 激活 World 和初始场景 - this.worldManager.setWorldActive(roomId, true); - world.setSceneActive('lobby', true); - - this.rooms.set(roomId, world); - console.log(`房间 ${roomId} 已创建`); - - return world; - } - - // 玩家加入房间 - public joinRoom(roomId: string, playerId: string): boolean { - const world = this.rooms.get(roomId); - if (!world) { - console.log(`房间 ${roomId} 不存在`); - return false; - } - - // 在大厅场景中创建玩家实体 - const lobbyScene = world.getScene('lobby'); - if (lobbyScene) { - const player = lobbyScene.createEntity(`Player_${playerId}`); - // 添加玩家组件... - console.log(`玩家 ${playerId} 加入房间 ${roomId}`); - return true; - } - - return false; - } - - // 开始游戏 - public startGame(roomId: string): void { - const world = this.rooms.get(roomId); - if (!world) return; - - // 切换到游戏场景 - world.setSceneActive('lobby', false); - world.setSceneActive('game', true); - - console.log(`房间 ${roomId} 游戏开始`); - } - - // 结束游戏 - public endGame(roomId: string): void { - const world = this.rooms.get(roomId); - if (!world) return; - - // 切换到结果场景 - world.setSceneActive('game', false); - world.setSceneActive('result', true); - - console.log(`房间 ${roomId} 游戏结束`); - } - - // 关闭房间 - public closeRoom(roomId: string): void { - this.worldManager.removeWorld(roomId); - this.rooms.delete(roomId); - console.log(`房间 ${roomId} 已关闭`); - } - - // 获取房间列表 - public getRoomList(): string[] { - return Array.from(this.rooms.keys()); - } - - // 获取房间统计 - public getRoomStats(roomId: string) { - const world = this.rooms.get(roomId); - return world?.getStats(); - } -} - -// 使用房间管理器 -const roomManager = new RoomManager(worldManager); - -// 创建多个游戏房间 -roomManager.createRoom('room_001', 4); -roomManager.createRoom('room_002', 4); -roomManager.createRoom('room_003', 2); - -// 玩家加入 -roomManager.joinRoom('room_001', 'player_1'); -roomManager.joinRoom('room_001', 'player_2'); - -// 开始游戏 -roomManager.startGame('room_001'); - -// 游戏循环 -function gameLoop(deltaTime: number) { - Core.update(deltaTime); - worldManager.updateAll(); // 更新所有房间 -} - -// 定期清理空房间 -setInterval(() => { - const stats = worldManager.getStats(); - console.log(`当前房间数: ${stats.totalWorlds}`); - console.log(`活跃房间数: ${stats.activeWorlds}`); - - worldManager.cleanup(); -}, 60000); // 每分钟清理一次 -``` - -## 最佳实践 - -### 1. 合理的 World 粒度 - -```typescript -// 推荐：每个独立环境一个 World -const room1 = worldManager.createWorld('room_1'); // 游戏房间1 -const room2 = worldManager.createWorld('room_2'); // 游戏房间2 - -// 不推荐：过度使用 World -const world1 = worldManager.createWorld('ui'); // UI 不需要独立 World -const world2 = worldManager.createWorld('menu'); // 菜单不需要独立 World -``` - -### 2. 使用全局系统处理跨场景逻辑 - -```typescript -// 推荐：World 级别的系统 -class NetworkSystem implements IGlobalSystem { - update() { - // 网络处理不依赖场景 - } -} - -// 不推荐：在每个场景中重复创建 -class GameScene extends Scene { - initialize() { - this.addSystem(new NetworkSystem()); // 不应该在场景级别 - } -} -``` - -### 3. 及时清理不用的 World - -```typescript -// 推荐：玩家离开时清理房间 -function onPlayerLeave(roomId: string) { - const world = worldManager.getWorld(roomId); - if (world && world.sceneCount === 0) { - worldManager.removeWorld(roomId); - } -} - -// 或使用自动清理 -worldManager.cleanup(); -``` - -### 4. 监控资源使用 - -```typescript -// 定期检查资源使用情况 -setInterval(() => { - const stats = worldManager.getStats(); - - if (stats.totalWorlds > 100) { - console.warn('World 数量过多，考虑清理'); - worldManager.cleanup(); - } - - if (stats.totalEntities > 10000) { - console.warn('实体数量过多，检查是否有泄漏'); - } -}, 30000); -``` - -## 与 SceneManager 的对比 - -| 特性 | SceneManager | WorldManager | -|------|--------------|--------------| -| 适用场景 | 95% 的游戏应用 | 高级多世界隔离场景 | -| 复杂度 | 简单 | 复杂 | -| 场景数量 | 单场景（可切换） | 多 World，每个 World 多场景 | -| 场景隔离 | 无（场景切换） | 完全隔离（每个 World 独立） | -| 性能开销 | 最小 | 较高 | -| 全局系统 | 无 | 支持（World 级别） | -| 使用示例 | 单人游戏、移动游戏 | MMO 服务器、游戏房间系统 | - -**何时使用 WorldManager**： -- MMO 游戏服务器（每个房间一个 World） -- 游戏大厅系统（每个游戏房间完全隔离） -- 需要运行多个完全独立的游戏实例 -- 服务器端模拟多个游戏世界 - -**何时使用 SceneManager**： -- 单人游戏 -- 简单的多人游戏 -- 移动游戏 -- 场景之间需要切换但不需要同时运行 - -## 架构层次 - -WorldManager 在 ECS Framework 中的位置： - -``` -Core (全局服务) - └── WorldManager (世界管理) - ├── World 1 (游戏房间1) - │ ├── GlobalSystem (全局系统) - │ ├── Scene 1 (场景1) - │ │ ├── EntitySystem - │ │ ├── Entity - │ │ └── Component - │ └── Scene 2 (场景2) - ├── World 2 (游戏房间2) - │ ├── GlobalSystem - │ └── Scene 1 - └── World 3 (游戏房间3) -``` - -WorldManager 为需要多世界隔离的高级应用提供了强大的管理能力。如果你的应用不需要多世界隔离，建议使用更简单的 [SceneManager](./scene-manager.md)。 diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 32a35e56..00000000 --- a/docs/index.md +++ /dev/null @@ -1,317 +0,0 @@ ---- -layout: page -title: ESEngine - 高性能 TypeScript ECS 框架 ---- - - - -
-
-
-

快速入口

- 查看文档 -
-
- -
-
- -
- 快速开始 -
-
-

5 分钟上手 ESEngine

-

从安装到创建第一个 ECS 应用，快速了解核心概念。

-
- - -
-
- -
- AI 系统 -
-
-

行为树可视化编辑器

-

内置 AI 行为树系统，支持可视化编辑和实时调试。

-
- -
-
-
- -
-
-

核心特性

-
-
-
- -
-

高性能 ECS 架构

-

基于数据驱动的实体组件系统，支持大规模实体处理，缓存友好的内存布局。

- 了解更多 → -
-
-
- -
-

完整类型支持

-

100% TypeScript 编写，完整的类型定义和编译时检查，提供最佳的开发体验。

- 了解更多 → -
-
-
- -
-

可视化行为树

-

内置 AI 行为树系统，提供可视化编辑器，支持自定义节点和实时调试。

- 了解更多 → -
-
-
- -
-

多平台支持

-

支持浏览器、Node.js、微信小游戏等多平台，可与主流游戏引擎无缝集成。

- 了解更多 → -
-
-
- -
-

模块化设计

-

核心功能独立打包，按需引入。支持自定义插件扩展，灵活适配不同项目。

- 了解更多 → -
-
-
- -
-

开发者工具

-

内置性能监控、调试工具、序列化系统等，提供完整的开发工具链。

- 了解更多 → -
-
-
-
- - diff --git a/docs/package.json b/docs/package.json new file mode 100644 index 00000000..1113e479 --- /dev/null +++ b/docs/package.json @@ -0,0 +1,21 @@ +{ + "name": "docs-new", + "type": "module", + "version": "0.0.1", + "scripts": { + "dev": "astro dev", + "start": "astro dev", + "build": "astro build", + "preview": "astro preview", + "astro": "astro" + }, + "dependencies": { + "@astrojs/starlight": "^0.37.1", + "@astrojs/vue": "^5.1.3", + "@tailwindcss/vite": "^4.1.18", + "astro": "^5.6.1", + "sharp": "^0.34.2", + "tailwindcss": "^4.1.18", + "vue": "^3.5.26" + } +} diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg new file mode 100644 index 00000000..cba5ac14 --- /dev/null +++ b/docs/public/favicon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/src/assets/houston.webp b/docs/src/assets/houston.webp new file mode 100644 index 0000000000000000000000000000000000000000..930c164974ad8eb528878f15a98016249b8cf546 GIT binary patch literal 98506 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 b6~t;_wBcJ3AWgga7~Sz~izoKbpAY~5r|m$8 literal 0 HcmV?d00001 diff --git a/docs/src/assets/logo.svg b/docs/src/assets/logo.svg new file mode 100644 index 00000000..5a54f816 --- /dev/null +++ b/docs/src/assets/logo.svg @@ -0,0 +1,45 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/src/components/Head.astro b/docs/src/components/Head.astro new file mode 100644 index 00000000..10382433 --- /dev/null +++ b/docs/src/components/Head.astro @@ -0,0 +1,20 @@ +--- +import type { Props } from '@astrojs/starlight/props'; +import Default from '@astrojs/starlight/components/Head.astro'; +--- + + + + + + + + + + diff --git a/docs/src/components/ThemeSelect.astro b/docs/src/components/ThemeSelect.astro new file mode 100644 index 00000000..e7dda4fa --- /dev/null +++ b/docs/src/components/ThemeSelect.astro @@ -0,0 +1,3 @@ +--- +// Empty component to disable theme selection (dark mode only) +--- diff --git a/docs/src/content.config.ts b/docs/src/content.config.ts new file mode 100644 index 00000000..d9ee8c9d --- /dev/null +++ b/docs/src/content.config.ts @@ -0,0 +1,7 @@ +import { defineCollection } from 'astro:content'; +import { docsLoader } from '@astrojs/starlight/loaders'; +import { docsSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }), +}; diff --git a/docs/src/content/docs/api/index.md b/docs/src/content/docs/api/index.md new file mode 100644 index 00000000..1a78a369 --- /dev/null +++ b/docs/src/content/docs/api/index.md @@ -0,0 +1,64 @@ +--- +title: API 参考 +description: ESEngine 完整 API 文档 +--- + +# API 参考 + +ESEngine 提供完整的 TypeScript API 文档，涵盖所有核心类、接口和方法。 + +## 核心模块 + +### 基础类 + +| 类名 | 描述 | +|------|------| +| [Core](/api/classes/Core) | 框架核心单例，管理整个 ECS 生命周期 | +| [Scene](/api/classes/Scene) | 场景类，包含实体和系统 | +| [World](/api/classes/World) | 游戏世界，可包含多个场景 | +| [Entity](/api/classes/Entity) | 实体类，组件的容器 | +| [Component](/api/classes/Component) | 组件基类，纯数据容器 | + +### 系统类 + +| 类名 | 描述 | +|------|------| +| [EntitySystem](/api/classes/EntitySystem) | 实体系统基类 | +| [ProcessingSystem](/api/classes/ProcessingSystem) | 处理系统，逐个处理实体 | +| [IntervalSystem](/api/classes/IntervalSystem) | 间隔执行系统 | +| [PassiveSystem](/api/classes/PassiveSystem) | 被动系统，不自动执行 | + +### 工具类 + +| 类名 | 描述 | +|------|------| +| [Matcher](/api/classes/Matcher) | 实体匹配器，用于过滤实体 | +| [Time](/api/classes/Time) | 时间管理器 | +| [PerformanceMonitor](/api/classes/PerformanceMonitor) | 性能监控 | + +## 装饰器 + +| 装饰器 | 描述 | +|--------|------| +| [@ECSComponent](/api/functions/ECSComponent) | 组件装饰器，用于注册组件 | +| [@ECSSystem](/api/functions/ECSSystem) | 系统装饰器，用于注册系统 | + +## 枚举 + +| 枚举 | 描述 | +|------|------| +| [ECSEventType](/api/enumerations/ECSEventType) | ECS 事件类型 | +| [LogLevel](/api/enumerations/LogLevel) | 日志级别 | + +## 接口 + +| 接口 | 描述 | +|------|------| +| [IScene](/api/interfaces/IScene) | 场景接口 | +| [IComponent](/api/interfaces/IComponent) | 组件接口 | +| [ISystemBase](/api/interfaces/ISystemBase) | 系统基础接口 | +| [ICoreConfig](/api/interfaces/ICoreConfig) | Core 配置接口 | + +:::tip[API 文档生成] +完整 API 文档由 TypeDoc 自动生成，详见 GitHub 仓库中的 `/docs/api` 目录。 +::: diff --git a/docs/src/content/docs/en/examples/index.md b/docs/src/content/docs/en/examples/index.md new file mode 100644 index 00000000..398b6300 --- /dev/null +++ b/docs/src/content/docs/en/examples/index.md @@ -0,0 +1,20 @@ +--- +title: "Examples" +description: "ESEngine example projects and demos" +--- + +Explore example projects to learn ESEngine best practices. + +## Available Examples + +### [Worker System Demo](/en/examples/worker-system-demo/) +Demonstrates how to use Web Workers for parallel processing, offloading heavy computations from the main thread. + +## External Examples + +### [Lawn Mower Demo](https://github.com/esengine/lawn-mower-demo) +A complete game demo showcasing ESEngine features including: +- Entity-Component-System architecture +- Behavior tree AI +- Scene management +- Platform adaptation diff --git a/docs/src/content/docs/en/guide/component/best-practices.md b/docs/src/content/docs/en/guide/component/best-practices.md new file mode 100644 index 00000000..0ca9d092 --- /dev/null +++ b/docs/src/content/docs/en/guide/component/best-practices.md @@ -0,0 +1,312 @@ +--- +title: "Best Practices" +description: "Component design patterns and complex examples" +--- + +## Design Principles + +### 1. Keep Components Simple + +```typescript +// ✅ Good component design - single responsibility +@ECSComponent('Position') +class Position extends Component { + x: number = 0; + y: number = 0; +} + +@ECSComponent('Velocity') +class Velocity extends Component { + dx: number = 0; + dy: number = 0; +} + +// ❌ Avoid this design - too many responsibilities +@ECSComponent('GameObject') +class GameObject extends Component { + x: number; + y: number; + dx: number; + dy: number; + health: number; + damage: number; + sprite: string; + // Too many unrelated properties +} +``` + +### 2. Use Constructor for Initialization + +```typescript +@ECSComponent('Transform') +class Transform extends Component { + x: number; + y: number; + rotation: number; + scale: number; + + constructor(x = 0, y = 0, rotation = 0, scale = 1) { + super(); + this.x = x; + this.y = y; + this.rotation = rotation; + this.scale = scale; + } +} +``` + +### 3. Clear Type Definitions + +```typescript +interface InventoryItem { + id: string; + name: string; + quantity: number; + type: 'weapon' | 'consumable' | 'misc'; +} + +@ECSComponent('Inventory') +class Inventory extends Component { + items: InventoryItem[] = []; + maxSlots: number; + + constructor(maxSlots: number = 20) { + super(); + this.maxSlots = maxSlots; + } + + addItem(item: InventoryItem): boolean { + if (this.items.length < this.maxSlots) { + this.items.push(item); + return true; + } + return false; + } + + removeItem(itemId: string): InventoryItem | null { + const index = this.items.findIndex(item => item.id === itemId); + if (index !== -1) { + return this.items.splice(index, 1)[0]; + } + return null; + } +} +``` + +### 4. Referencing Other Entities + +When components need to reference other entities (like parent-child relationships, follow targets), **the recommended approach is to store entity IDs**, then look up in System: + +```typescript +@ECSComponent('Follower') +class Follower extends Component { + targetId: number; + followDistance: number = 50; + + constructor(targetId: number) { + super(); + this.targetId = targetId; + } +} + +// Look up target entity and handle logic in System +class FollowerSystem extends EntitySystem { + constructor() { + super(new Matcher().all(Follower, Position)); + } + + process(entities: readonly Entity[]): void { + for (const entity of entities) { + const follower = entity.getComponent(Follower)!; + const position = entity.getComponent(Position)!; + + // Look up target entity through scene + const target = entity.scene?.findEntityById(follower.targetId); + if (target) { + const targetPos = target.getComponent(Position); + if (targetPos) { + // Follow logic + const dx = targetPos.x - position.x; + const dy = targetPos.y - position.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance > follower.followDistance) { + // Move closer to target + } + } + } + } + } +} +``` + +Advantages of this approach: +- Components stay simple, only store basic data types +- Follows data-oriented design +- Unified lookup and logic handling in System +- Easy to understand and maintain + +**Avoid storing entity references directly in components**: + +```typescript +// ❌ Wrong example: Storing entity reference directly +@ECSComponent('BadFollower') +class BadFollower extends Component { + target: Entity; // Still holds reference after entity destroyed, may cause memory leak +} +``` + +## Complex Component Examples + +### State Machine Component + +```typescript +enum EntityState { + Idle, + Moving, + Attacking, + Dead +} + +@ECSComponent('StateMachine') +class StateMachine extends Component { + private _currentState: EntityState = EntityState.Idle; + private _previousState: EntityState = EntityState.Idle; + private _stateTimer: number = 0; + + get currentState(): EntityState { + return this._currentState; + } + + get previousState(): EntityState { + return this._previousState; + } + + get stateTimer(): number { + return this._stateTimer; + } + + changeState(newState: EntityState): void { + if (this._currentState !== newState) { + this._previousState = this._currentState; + this._currentState = newState; + this._stateTimer = 0; + } + } + + updateTimer(deltaTime: number): void { + this._stateTimer += deltaTime; + } + + isInState(state: EntityState): boolean { + return this._currentState === state; + } +} +``` + +### Configuration Data Component + +```typescript +interface WeaponData { + damage: number; + range: number; + fireRate: number; + ammo: number; +} + +@ECSComponent('WeaponConfig') +class WeaponConfig extends Component { + data: WeaponData; + + constructor(weaponData: WeaponData) { + super(); + this.data = { ...weaponData }; // Deep copy to avoid shared reference + } + + // Provide convenience methods + getDamage(): number { + return this.data.damage; + } + + canFire(): boolean { + return this.data.ammo > 0; + } + + consumeAmmo(): boolean { + if (this.data.ammo > 0) { + this.data.ammo--; + return true; + } + return false; + } +} +``` + +### Tag Components + +```typescript +// Tag components: No data, only for identification +@ECSComponent('Player') +class PlayerTag extends Component {} + +@ECSComponent('Enemy') +class EnemyTag extends Component {} + +@ECSComponent('Dead') +class DeadTag extends Component {} + +// Use tags for querying +class EnemySystem extends EntitySystem { + constructor() { + super(Matcher.all(EnemyTag, Health).none(DeadTag)); + } +} +``` + +### Buffer Components + +```typescript +// Event/command buffer component +@ECSComponent('DamageBuffer') +class DamageBuffer extends Component { + damages: { amount: number; source: number; timestamp: number }[] = []; + + addDamage(amount: number, sourceId: number): void { + this.damages.push({ + amount, + source: sourceId, + timestamp: Date.now() + }); + } + + clear(): void { + this.damages.length = 0; + } + + getTotalDamage(): number { + return this.damages.reduce((sum, d) => sum + d.amount, 0); + } +} +``` + +## FAQ + +### Q: How large should a component be? + +**A**: Follow single responsibility principle. If a component contains unrelated data, split into multiple components. + +### Q: Can components have methods? + +**A**: Yes, but they should be data-related helper methods (like `isDead()`), not business logic. Business logic goes in Systems. + +### Q: How to handle dependencies between components? + +**A**: Handle inter-component interactions in Systems, don't directly access other components within a component. + +### Q: When to use EntityRef? + +**A**: Only when you need frequent access to referenced entity and the reference relationship is stable (like parent-child). Storing IDs is better for most cases. + +--- + +Components are the data carriers of ECS architecture. Properly designing components makes your game code more modular, maintainable, and performant. diff --git a/docs/src/content/docs/en/guide/component/entity-ref.md b/docs/src/content/docs/en/guide/component/entity-ref.md new file mode 100644 index 00000000..edf37911 --- /dev/null +++ b/docs/src/content/docs/en/guide/component/entity-ref.md @@ -0,0 +1,228 @@ +--- +title: "EntityRef Decorator" +description: "Safe entity reference tracking mechanism" +--- + +The framework provides the `@EntityRef` decorator for **special scenarios** to safely store entity references. This is an advanced feature; storing IDs is recommended for most cases. + +## When Do You Need EntityRef? + +`@EntityRef` can simplify code in these scenarios: + +1. **Parent-Child Relationships**: Need to directly access parent or child entities in components +2. **Complex Associations**: Multiple reference relationships between entities +3. **Frequent Access**: Need to access referenced entity in multiple places, ID lookup has performance overhead + +## Core Features + +The `@EntityRef` decorator automatically tracks references through **ReferenceTracker**: + +- When the referenced entity is destroyed, all `@EntityRef` properties pointing to it are automatically set to `null` +- Prevents cross-scene references (outputs warning and refuses to set) +- Prevents references to destroyed entities (outputs warning and sets to `null`) +- Uses WeakRef to avoid memory leaks (automatic GC support) +- Automatically cleans up reference registration when component is removed + +## Basic Usage + +```typescript +import { Component, ECSComponent, EntityRef, Entity } from '@esengine/ecs-framework'; + +@ECSComponent('Parent') +class ParentComponent extends Component { + @EntityRef() + parent: Entity | null = null; +} + +// Usage example +const scene = new Scene(); +const parent = scene.createEntity('Parent'); +const child = scene.createEntity('Child'); + +const comp = child.addComponent(new ParentComponent()); +comp.parent = parent; + +console.log(comp.parent); // Entity { name: 'Parent' } + +// When parent is destroyed, comp.parent automatically becomes null +parent.destroy(); +console.log(comp.parent); // null +``` + +## Multiple Reference Properties + +A component can have multiple `@EntityRef` properties: + +```typescript +@ECSComponent('Combat') +class CombatComponent extends Component { + @EntityRef() + target: Entity | null = null; + + @EntityRef() + ally: Entity | null = null; + + @EntityRef() + lastAttacker: Entity | null = null; +} + +// Usage example +const player = scene.createEntity('Player'); +const enemy = scene.createEntity('Enemy'); +const npc = scene.createEntity('NPC'); + +const combat = player.addComponent(new CombatComponent()); +combat.target = enemy; +combat.ally = npc; + +// After enemy is destroyed, only target becomes null, ally remains valid +enemy.destroy(); +console.log(combat.target); // null +console.log(combat.ally); // Entity { name: 'NPC' } +``` + +## Safety Checks + +`@EntityRef` provides multiple safety checks: + +```typescript +const scene1 = new Scene(); +const scene2 = new Scene(); + +const entity1 = scene1.createEntity('Entity1'); +const entity2 = scene2.createEntity('Entity2'); + +const comp = entity1.addComponent(new ParentComponent()); + +// Cross-scene reference fails +comp.parent = entity2; // Outputs error log, comp.parent is null +console.log(comp.parent); // null + +// Reference to destroyed entity fails +const entity3 = scene1.createEntity('Entity3'); +entity3.destroy(); +comp.parent = entity3; // Outputs warning log, comp.parent is null +console.log(comp.parent); // null +``` + +## Implementation Principle + +`@EntityRef` uses the following mechanisms for automatic reference tracking: + +1. **ReferenceTracker**: Scene holds a reference tracker that records all entity reference relationships +2. **WeakRef**: Uses weak references to store components, avoiding memory leaks from circular references +3. **Property Interception**: Intercepts getter/setter through `Object.defineProperty` +4. **Automatic Cleanup**: When entity is destroyed, ReferenceTracker traverses all references and sets them to null + +```typescript +// Simplified implementation principle +class ReferenceTracker { + // entityId -> all component records referencing this entity + private _references: Map, propertyKey: string }>>; + + // Called when entity is destroyed + clearReferencesTo(entityId: number): void { + const records = this._references.get(entityId); + if (records) { + for (const record of records) { + const component = record.component.deref(); + if (component) { + // Set component's reference property to null + (component as any)[record.propertyKey] = null; + } + } + this._references.delete(entityId); + } + } +} +``` + +## Performance Considerations + +`@EntityRef` introduces some performance overhead: + +- **Write Overhead**: Need to update ReferenceTracker each time a reference is set +- **Memory Overhead**: ReferenceTracker needs to maintain reference mapping table +- **Destroy Overhead**: Need to traverse all references and clean up when entity is destroyed + +For most scenarios, this overhead is acceptable. But with **many entities and frequent reference changes**, storing IDs may be more efficient. + +## Debug Support + +ReferenceTracker provides debug interfaces: + +```typescript +// View which components reference an entity +const references = scene.referenceTracker.getReferencesTo(entity.id); +console.log(`Entity ${entity.name} is referenced by ${references.length} components`); + +// Get complete debug info +const debugInfo = scene.referenceTracker.getDebugInfo(); +console.log(debugInfo); +``` + +## Comparison with Storing IDs + +### Storing IDs (Recommended for Most Cases) + +```typescript +@ECSComponent('Follower') +class Follower extends Component { + targetId: number | null = null; +} + +// Look up in System +class FollowerSystem extends EntitySystem { + process(entities: readonly Entity[]): void { + for (const entity of entities) { + const follower = entity.getComponent(Follower)!; + const target = entity.scene?.findEntityById(follower.targetId); + if (target) { + // Follow logic + } + } + } +} +``` + +### Using EntityRef (For Complex Associations) + +```typescript +@ECSComponent('Transform') +class Transform extends Component { + @EntityRef() + parent: Entity | null = null; + + position: { x: number, y: number } = { x: 0, y: 0 }; + + // Can directly access parent entity's component + getWorldPosition(): { x: number, y: number } { + if (!this.parent) { + return { ...this.position }; + } + + const parentTransform = this.parent.getComponent(Transform); + if (parentTransform) { + const parentPos = parentTransform.getWorldPosition(); + return { + x: parentPos.x + this.position.x, + y: parentPos.y + this.position.y + }; + } + + return { ...this.position }; + } +} +``` + +## Summary + +| Approach | Use Case | Pros | Cons | +|----------|----------|------|------| +| Store ID | Most cases | Simple, no extra overhead | Need to lookup in System | +| @EntityRef | Parent-child, complex associations | Auto-cleanup, cleaner code | Has performance overhead | + +- **Recommended**: Use store ID + System lookup for most cases +- **EntityRef Use Cases**: Parent-child relationships, complex associations, when component needs direct access to referenced entity +- **Core Advantage**: Automatic cleanup, prevents dangling references, cleaner code +- **Considerations**: Has performance overhead, not suitable for many dynamic references diff --git a/docs/src/content/docs/en/guide/component/index.md b/docs/src/content/docs/en/guide/component/index.md new file mode 100644 index 00000000..445282fe --- /dev/null +++ b/docs/src/content/docs/en/guide/component/index.md @@ -0,0 +1,226 @@ +--- +title: "Component System" +description: "ECS component basics and creation methods" +--- + +In ECS architecture, Components are carriers of data and behavior. Components define the properties and functionality that entities possess, and are the core building blocks of ECS architecture. + +## Basic Concepts + +Components are concrete classes that inherit from the `Component` abstract base class, used for: +- Storing entity data (such as position, velocity, health, etc.) +- Defining behavior methods related to the data +- Providing lifecycle callback hooks +- Supporting serialization and debugging + +## Creating Components + +### Basic Component Definition + +```typescript +import { Component, ECSComponent } from '@esengine/ecs-framework'; + +@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; + } +} + +@ECSComponent('Health') +class Health extends Component { + current: number; + max: number; + + constructor(max: number = 100) { + super(); + this.max = max; + this.current = max; + } + + // Components can contain behavior methods + takeDamage(damage: number): void { + this.current = Math.max(0, this.current - damage); + } + + heal(amount: number): void { + this.current = Math.min(this.max, this.current + amount); + } + + isDead(): boolean { + return this.current <= 0; + } +} +``` + +## @ECSComponent Decorator + +`@ECSComponent` is a required decorator for component classes, providing type identification and metadata management. + +### Why It's Required + +| Feature | Description | +|---------|-------------| +| **Type Identification** | Provides stable type name that remains correct after code obfuscation | +| **Serialization Support** | Uses this name as type identifier during serialization/deserialization | +| **Component Registration** | Auto-registers to ComponentRegistry, assigns unique bitmask | +| **Debug Support** | Shows readable component names in debug tools and logs | + +### Basic Syntax + +```typescript +@ECSComponent(typeName: string) +``` + +- `typeName`: Component's type name, recommended to use same or similar name as class name + +### Usage Examples + +```typescript +// ✅ Correct usage +@ECSComponent('Velocity') +class Velocity extends Component { + dx: number = 0; + dy: number = 0; +} + +// ✅ Recommended: Keep type name consistent with class name +@ECSComponent('PlayerController') +class PlayerController extends Component { + speed: number = 5; +} + +// ❌ Wrong usage - no decorator +class BadComponent extends Component { + // Components defined this way may have issues in production: + // 1. Class name changes after minification, can't serialize correctly + // 2. Component not registered to framework, queries may fail +} +``` + +### Using with @Serializable + +When components need serialization support, use `@ECSComponent` and `@Serializable` together: + +```typescript +import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework'; + +@ECSComponent('Player') +@Serializable({ version: 1 }) +class PlayerComponent extends Component { + @Serialize() + name: string = ''; + + @Serialize() + level: number = 1; + + // Fields without @Serialize() won't be serialized + private _cachedData: any = null; +} +``` + +> **Note**: `@ECSComponent`'s `typeName` and `@Serializable`'s `typeId` can differ. If `@Serializable` doesn't specify `typeId`, it defaults to `@ECSComponent`'s `typeName`. + +### Type Name Uniqueness + +Each component's type name should be unique: + +```typescript +// ❌ Wrong: Two components using the same type name +@ECSComponent('Health') +class HealthComponent extends Component { } + +@ECSComponent('Health') // Conflict! +class EnemyHealthComponent extends Component { } + +// ✅ Correct: Use different type names +@ECSComponent('PlayerHealth') +class PlayerHealthComponent extends Component { } + +@ECSComponent('EnemyHealth') +class EnemyHealthComponent extends Component { } +``` + +## Component Properties + +Each component has some built-in properties: + +```typescript +@ECSComponent('ExampleComponent') +class ExampleComponent extends Component { + someData: string = "example"; + + onAddedToEntity(): void { + console.log(`Component ID: ${this.id}`); // Unique component ID + console.log(`Entity ID: ${this.entityId}`); // Owning entity's ID + } +} +``` + +## Component and Entity Relationship + +Components store the owning entity's ID (`entityId`), not a direct entity reference. This is a reflection of ECS's data-oriented design, avoiding circular references. + +In practice, **entity and component interactions should be handled in Systems**, not within components: + +```typescript +@ECSComponent('Health') +class Health extends Component { + current: number; + max: number; + + constructor(max: number = 100) { + super(); + this.max = max; + this.current = max; + } + + isDead(): boolean { + return this.current <= 0; + } +} + +@ECSComponent('Damage') +class Damage extends Component { + value: number; + + constructor(value: number) { + super(); + this.value = value; + } +} + +// Recommended: Handle logic in System +class DamageSystem extends EntitySystem { + constructor() { + super(new Matcher().all(Health, Damage)); + } + + process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health)!; + const damage = entity.getComponent(Damage)!; + + health.current -= damage.value; + + if (health.isDead()) { + entity.destroy(); + } + + // Remove Damage component after applying damage + entity.removeComponent(damage); + } + } +} +``` + +## More Topics + +- [Lifecycle](/en/guide/component/lifecycle) - Component lifecycle hooks +- [EntityRef Decorator](/en/guide/component/entity-ref) - Safe entity references +- [Best Practices](/en/guide/component/best-practices) - Component design patterns and examples diff --git a/docs/src/content/docs/en/guide/component/lifecycle.md b/docs/src/content/docs/en/guide/component/lifecycle.md new file mode 100644 index 00000000..b8a445d4 --- /dev/null +++ b/docs/src/content/docs/en/guide/component/lifecycle.md @@ -0,0 +1,182 @@ +--- +title: "Component Lifecycle" +description: "Component lifecycle hooks and events" +--- + +Components provide lifecycle hooks that can be overridden to execute specific logic. + +## Lifecycle Methods + +```typescript +@ECSComponent('ExampleComponent') +class ExampleComponent extends Component { + private resource: SomeResource | null = null; + + /** + * Called when component is added to entity + * Use for initializing resources, establishing references, etc. + */ + onAddedToEntity(): void { + console.log(`Component ${this.constructor.name} added, Entity ID: ${this.entityId}`); + this.resource = new SomeResource(); + } + + /** + * Called when component is removed from entity + * Use for cleaning up resources, breaking references, etc. + */ + onRemovedFromEntity(): void { + console.log(`Component ${this.constructor.name} removed`); + if (this.resource) { + this.resource.cleanup(); + this.resource = null; + } + } +} +``` + +## Lifecycle Order + +``` +Entity created + ↓ +addComponent() called + ↓ +onAddedToEntity() triggered + ↓ +Component in normal use... + ↓ +removeComponent() or entity.destroy() called + ↓ +onRemovedFromEntity() triggered + ↓ +Component removed/destroyed +``` + +## Practical Use Cases + +### Resource Management + +```typescript +@ECSComponent('TextureComponent') +class TextureComponent extends Component { + private _texture: Texture | null = null; + texturePath: string = ''; + + onAddedToEntity(): void { + // Load texture resource + this._texture = TextureManager.load(this.texturePath); + } + + onRemovedFromEntity(): void { + // Release texture resource + if (this._texture) { + TextureManager.release(this._texture); + this._texture = null; + } + } + + get texture(): Texture | null { + return this._texture; + } +} +``` + +### Event Listening + +```typescript +@ECSComponent('InputListener') +class InputListener extends Component { + private _boundHandler: ((e: KeyboardEvent) => void) | null = null; + + onAddedToEntity(): void { + this._boundHandler = this.handleKeyDown.bind(this); + window.addEventListener('keydown', this._boundHandler); + } + + onRemovedFromEntity(): void { + if (this._boundHandler) { + window.removeEventListener('keydown', this._boundHandler); + this._boundHandler = null; + } + } + + private handleKeyDown(e: KeyboardEvent): void { + // Handle keyboard input + } +} +``` + +### Registering with External Systems + +```typescript +@ECSComponent('PhysicsBody') +class PhysicsBody extends Component { + private _body: PhysicsWorld.Body | null = null; + + onAddedToEntity(): void { + // Create rigid body in physics world + this._body = PhysicsWorld.createBody({ + entityId: this.entityId, + type: 'dynamic' + }); + } + + onRemovedFromEntity(): void { + // Remove rigid body from physics world + if (this._body) { + PhysicsWorld.removeBody(this._body); + this._body = null; + } + } +} +``` + +## Important Notes + +### Avoid Accessing Other Components in Lifecycle + +```typescript +@ECSComponent('BadComponent') +class BadComponent extends Component { + onAddedToEntity(): void { + // ⚠️ Not recommended: Other components may not be added yet + const other = this.entity?.getComponent(OtherComponent); + if (other) { + // May be null + } + } +} +``` + +### Recommended: Use System to Handle Inter-Component Interactions + +```typescript +@ECSSystem('InitializationSystem') +class InitializationSystem extends EntitySystem { + constructor() { + super(Matcher.all(ComponentA, ComponentB)); + } + + // Use onAdded event to ensure both components exist + onAdded(entity: Entity): void { + const a = entity.getComponent(ComponentA)!; + const b = entity.getComponent(ComponentB)!; + // Safely initialize interaction + a.linkTo(b); + } + + onRemoved(entity: Entity): void { + // Cleanup + } +} +``` + +## Comparison with System Lifecycle + +| Feature | Component Lifecycle | System Lifecycle | +|---------|---------------------|------------------| +| Trigger Timing | When component added/removed | When match conditions met | +| Use Case | Resource init/cleanup | Business logic processing | +| Access Other Components | Not recommended | Safe | +| Access Scene | Limited | Full | diff --git a/docs/src/content/docs/en/guide/entity-query/best-practices.md b/docs/src/content/docs/en/guide/entity-query/best-practices.md new file mode 100644 index 00000000..9e3451a6 --- /dev/null +++ b/docs/src/content/docs/en/guide/entity-query/best-practices.md @@ -0,0 +1,225 @@ +--- +title: "Best Practices" +description: "Entity query optimization and practical applications" +--- + +## Design Principles + +### 1. Prefer EntitySystem + +```typescript +// ✅ Recommended: Use EntitySystem +class GoodSystem extends EntitySystem { + constructor() { + super(Matcher.empty().all(HealthComponent)); + } + + protected process(entities: readonly Entity[]): void { + // Automatically get matching entities, updated each frame + } +} + +// ❌ Not recommended: Manual query in update +class BadSystem extends EntitySystem { + constructor() { + super(Matcher.empty()); + } + + protected process(entities: readonly Entity[]): void { + // Manual query each frame wastes performance + const result = this.scene!.querySystem.queryAll(HealthComponent); + for (const entity of result.entities) { + // ... + } + } +} +``` + +### 2. Use none() for Exclusions + +```typescript +// Exclude dead enemies +class EnemyAISystem extends EntitySystem { + constructor() { + super( + Matcher.empty() + .all(EnemyTag, AIComponent) + .none(DeadTag) // Don't process dead enemies + ); + } +} +``` + +### 3. Use Tags for Query Optimization + +```typescript +// ❌ Bad: Query all entities then filter +const allEntities = scene.querySystem.getAllEntities(); +const players = allEntities.filter(e => e.hasComponent(PlayerTag)); + +// ✅ Good: Query directly by tag +const players = scene.querySystem.queryByTag(Tags.PLAYER).entities; +``` + +### 4. Avoid Overly Complex Query Conditions + +```typescript +// ❌ Not recommended: Too complex +super( + Matcher.empty() + .all(A, B, C, D) + .any(E, F, G) + .none(H, I, J) +); + +// ✅ Recommended: Split into multiple simple systems +class SystemAB extends EntitySystem { + constructor() { + super(Matcher.empty().all(A, B)); + } +} + +class SystemCD extends EntitySystem { + constructor() { + super(Matcher.empty().all(C, D)); + } +} +``` + +## Practical Applications + +### Scenario 1: Physics System + +```typescript +class PhysicsSystem extends EntitySystem { + constructor() { + super(Matcher.empty().all(TransformComponent, RigidbodyComponent)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const transform = entity.getComponent(TransformComponent)!; + const rigidbody = entity.getComponent(RigidbodyComponent)!; + + // Apply gravity + rigidbody.velocity.y -= 9.8 * Time.deltaTime; + + // Update position + transform.position.x += rigidbody.velocity.x * Time.deltaTime; + transform.position.y += rigidbody.velocity.y * Time.deltaTime; + } + } +} +``` + +### Scenario 2: Render System + +```typescript +class RenderSystem extends EntitySystem { + constructor() { + super( + Matcher.empty() + .all(TransformComponent, SpriteComponent) + .none(InvisibleTag) // Exclude invisible entities + ); + } + + protected process(entities: readonly Entity[]): void { + // Sort by z-order + const sorted = entities.slice().sort((a, b) => { + const zA = a.getComponent(TransformComponent)!.z; + const zB = b.getComponent(TransformComponent)!.z; + return zA - zB; + }); + + // Render entities + for (const entity of sorted) { + const transform = entity.getComponent(TransformComponent)!; + const sprite = entity.getComponent(SpriteComponent)!; + + renderer.drawSprite(sprite.texture, transform.position); + } + } +} +``` + +### Scenario 3: Collision Detection + +```typescript +class CollisionSystem extends EntitySystem { + constructor() { + super(Matcher.empty().all(TransformComponent, ColliderComponent)); + } + + protected process(entities: readonly Entity[]): void { + // Simple O(n²) collision detection + for (let i = 0; i < entities.length; i++) { + for (let j = i + 1; j < entities.length; j++) { + this.checkCollision(entities[i], entities[j]); + } + } + } + + private checkCollision(a: Entity, b: Entity): void { + const transA = a.getComponent(TransformComponent)!; + const transB = b.getComponent(TransformComponent)!; + const colliderA = a.getComponent(ColliderComponent)!; + const colliderB = b.getComponent(ColliderComponent)!; + + if (this.isOverlapping(transA, colliderA, transB, colliderB)) { + // Trigger collision event + scene.eventSystem.emit('collision', { entityA: a, entityB: b }); + } + } +} +``` + +### Scenario 4: One-Time Query + +```typescript +// Execute one-time query outside of systems +class GameManager { + private scene: Scene; + + public countEnemies(): number { + const result = this.scene.querySystem.queryByTag(Tags.ENEMY); + return result.count; + } + + public findNearestEnemy(playerPos: Vector2): Entity | null { + const enemies = this.scene.querySystem.queryByTag(Tags.ENEMY); + + let nearest: Entity | null = null; + let minDistance = Infinity; + + for (const enemy of enemies.entities) { + const transform = enemy.getComponent(TransformComponent); + if (!transform) continue; + + const distance = Vector2.distance(playerPos, transform.position); + if (distance < minDistance) { + minDistance = distance; + nearest = enemy; + } + } + + return nearest; + } +} +``` + +## Performance Statistics + +```typescript +const stats = querySystem.getStats(); +console.log('Total queries:', stats.queryStats.totalQueries); +console.log('Cache hit rate:', stats.queryStats.cacheHitRate); +console.log('Cache size:', stats.cacheStats.size); +``` + +## Related APIs + +- [Matcher](/api/classes/Matcher/) - Query condition descriptor API reference +- [QuerySystem](/api/classes/QuerySystem/) - Query system API reference +- [EntitySystem](/api/classes/EntitySystem/) - Entity system API reference +- [Entity](/api/classes/Entity/) - Entity API reference diff --git a/docs/src/content/docs/en/guide/entity-query/compiled-query.md b/docs/src/content/docs/en/guide/entity-query/compiled-query.md new file mode 100644 index 00000000..f01382c9 --- /dev/null +++ b/docs/src/content/docs/en/guide/entity-query/compiled-query.md @@ -0,0 +1,133 @@ +--- +title: "Compiled Query" +description: "CompiledQuery type-safe query tool" +--- + +> **v2.4.0+** + +CompiledQuery is a lightweight query tool providing type-safe component access and change detection support. Suitable for ad-hoc queries, tool development, and simple iteration scenarios. + +## Basic Usage + +```typescript +// Create compiled query +const query = scene.querySystem.compile(Position, Velocity); + +// Type-safe iteration - component parameters auto-infer types +query.forEach((entity, pos, vel) => { + pos.x += vel.vx * deltaTime; + pos.y += vel.vy * deltaTime; +}); + +// Get entity count +console.log(`Matched entities: ${query.count}`); + +// Get first matched entity +const first = query.first(); +if (first) { + const [entity, pos, vel] = first; + console.log(`First entity: ${entity.name}`); +} +``` + +## Change Detection + +CompiledQuery supports epoch-based change detection: + +```typescript +class RenderSystem extends EntitySystem { + private _query: CompiledQuery<[typeof Transform, typeof Sprite]>; + private _lastEpoch = 0; + + protected onInitialize(): void { + this._query = this.scene!.querySystem.compile(Transform, Sprite); + } + + protected process(entities: readonly Entity[]): void { + // Only process entities where Transform or Sprite changed + this._query.forEachChanged(this._lastEpoch, (entity, transform, sprite) => { + this.updateRenderData(entity, transform, sprite); + }); + + // Save current epoch as next check starting point + this._lastEpoch = this.scene!.epochManager.current; + } + + private updateRenderData(entity: Entity, transform: Transform, sprite: Sprite): void { + // Update render data + } +} +``` + +## Functional API + +CompiledQuery provides rich functional APIs: + +```typescript +const query = scene.querySystem.compile(Position, Health); + +// map - Transform entity data +const positions = query.map((entity, pos, health) => ({ + x: pos.x, + y: pos.y, + healthPercent: health.current / health.max +})); + +// filter - Filter entities +const lowHealthEntities = query.filter((entity, pos, health) => { + return health.current < health.max * 0.2; +}); + +// find - Find first matching entity +const target = query.find((entity, pos, health) => { + return health.current > 0 && pos.x > 100; +}); + +// toArray - Convert to array +const allData = query.toArray(); +for (const [entity, pos, health] of allData) { + console.log(`${entity.name}: ${pos.x}, ${pos.y}`); +} + +// any/empty - Check for matches +if (query.any()) { + console.log('Has matching entities'); +} +if (query.empty()) { + console.log('No matching entities'); +} +``` + +## CompiledQuery vs EntitySystem + +| Feature | CompiledQuery | EntitySystem | +|---------|---------------|--------------| +| **Purpose** | Lightweight query tool | Complete system logic | +| **Lifecycle** | None | Full (onInitialize, onDestroy, etc.) | +| **Scheduling Integration** | None | Supports @Stage, @Before, @After | +| **Change Detection** | forEachChanged | forEachChanged | +| **Event Listening** | None | addEventListener | +| **Command Buffer** | None | this.commands | +| **Type-Safe Components** | forEach params auto-infer | Need manual getComponent | +| **Use Cases** | Ad-hoc queries, tools, prototypes | Core game logic | + +**Selection Advice**: + +- Use **EntitySystem** for core game logic (movement, combat, AI, etc.) +- Use **CompiledQuery** for one-time queries, tool development, or simple iteration + +## API Reference + +| Method | Description | +|--------|-------------| +| `forEach(callback)` | Iterate all matched entities, type-safe component params | +| `forEachChanged(sinceEpoch, callback)` | Only iterate changed entities | +| `first()` | Get first matched entity and components | +| `toArray()` | Convert to [entity, ...components] array | +| `map(callback)` | Map transformation | +| `filter(predicate)` | Filter entities | +| `find(predicate)` | Find first entity meeting condition | +| `any()` | Whether any matches exist | +| `empty()` | Whether no matches exist | +| `count` | Number of matched entities | +| `entities` | Matched entity list (read-only) | diff --git a/docs/src/content/docs/en/guide/entity-query/index.md b/docs/src/content/docs/en/guide/entity-query/index.md new file mode 100644 index 00000000..3d9aa316 --- /dev/null +++ b/docs/src/content/docs/en/guide/entity-query/index.md @@ -0,0 +1,244 @@ +--- +title: "Entity Query System" +description: "ECS entity query core concepts and basic usage" +--- + +Entity querying is one of the core features of ECS architecture. This guide introduces how to use Matcher and QuerySystem to query and filter entities. + +## Core Concepts + +### Matcher - Query Condition Descriptor + +Matcher is a chainable API used to describe entity query conditions. It doesn't execute queries itself but passes conditions to EntitySystem or QuerySystem. + +### QuerySystem - Query Execution Engine + +QuerySystem is responsible for actually executing queries, using reactive query mechanisms internally for automatic performance optimization. + +## Using Matcher in EntitySystem + +This is the most common usage. EntitySystem automatically filters and processes entities matching conditions through Matcher. + +### Basic Usage + +```typescript +import { EntitySystem, Matcher, Entity, Component } from '@esengine/ecs-framework'; + +class PositionComponent extends Component { + public x: number = 0; + public y: number = 0; +} + +class VelocityComponent extends Component { + public vx: number = 0; + public vy: number = 0; +} + +class MovementSystem extends EntitySystem { + constructor() { + // Method 1: Use Matcher.empty().all() + super(Matcher.empty().all(PositionComponent, VelocityComponent)); + + // Method 2: Use Matcher.all() directly (equivalent) + // super(Matcher.all(PositionComponent, VelocityComponent)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const pos = entity.getComponent(PositionComponent)!; + const vel = entity.getComponent(VelocityComponent)!; + + pos.x += vel.vx; + pos.y += vel.vy; + } + } +} + +// Add to scene +scene.addEntityProcessor(new MovementSystem()); +``` + +### Matcher Chainable API + +#### all() - Must Include All Components + +```typescript +class HealthSystem extends EntitySystem { + constructor() { + // Entity must have both Health and Position components + super(Matcher.empty().all(HealthComponent, PositionComponent)); + } + + protected process(entities: readonly Entity[]): void { + // Only process entities with both components + } +} +``` + +#### any() - Include At Least One Component + +```typescript +class DamageableSystem extends EntitySystem { + constructor() { + // Entity must have at least Health or Shield + super(Matcher.any(HealthComponent, ShieldComponent)); + } + + protected process(entities: readonly Entity[]): void { + // Process entities with health or shield + } +} +``` + +#### none() - Must Not Include Components + +```typescript +class AliveEntitySystem extends EntitySystem { + constructor() { + // Entity must not have DeadTag component + super(Matcher.all(HealthComponent).none(DeadTag)); + } + + protected process(entities: readonly Entity[]): void { + // Only process living entities + } +} +``` + +#### Combined Conditions + +```typescript +class CombatSystem extends EntitySystem { + constructor() { + super( + Matcher.empty() + .all(PositionComponent, HealthComponent) // Must have position and health + .any(WeaponComponent, MagicComponent) // At least weapon or magic + .none(DeadTag, FrozenTag) // Not dead or frozen + ); + } + + protected process(entities: readonly Entity[]): void { + // Process living entities that can fight + } +} +``` + +#### nothing() - Match No Entities + +Used for systems that only need lifecycle methods (`onBegin`, `onEnd`) but don't process entities. + +```typescript +class FrameTimerSystem extends EntitySystem { + constructor() { + // Match no entities + super(Matcher.nothing()); + } + + protected onBegin(): void { + // Execute at frame start + Performance.markFrameStart(); + } + + protected process(entities: readonly Entity[]): void { + // Never called because no matching entities + } + + protected onEnd(): void { + // Execute at frame end + Performance.markFrameEnd(); + } +} +``` + +#### empty() vs nothing() + +| Method | Behavior | Use Case | +|--------|----------|----------| +| `Matcher.empty()` | Match **all** entities | Process all entities in scene | +| `Matcher.nothing()` | Match **no** entities | Only need lifecycle callbacks | + +## Using QuerySystem Directly + +If you don't need to create a system, you can use Scene's querySystem directly. + +### Basic Query Methods + +```typescript +// Get scene's query system +const querySystem = scene.querySystem; + +// Query entities with all specified components +const result1 = querySystem.queryAll(PositionComponent, VelocityComponent); +console.log(`Found ${result1.count} moving entities`); +console.log(`Query time: ${result1.executionTime.toFixed(2)}ms`); + +// Query entities with any specified component +const result2 = querySystem.queryAny(WeaponComponent, MagicComponent); +console.log(`Found ${result2.count} combat units`); + +// Query entities without specified components +const result3 = querySystem.queryNone(DeadTag); +console.log(`Found ${result3.count} living entities`); +``` + +### Query by Tag and Name + +```typescript +// Query by tag +const playerResult = querySystem.queryByTag(Tags.PLAYER); +for (const player of playerResult.entities) { + console.log('Player:', player.name); +} + +// Query by name +const bossResult = querySystem.queryByName('Boss'); +if (bossResult.count > 0) { + const boss = bossResult.entities[0]; + console.log('Found Boss:', boss); +} + +// Query by single component +const healthResult = querySystem.queryByComponent(HealthComponent); +console.log(`${healthResult.count} entities have health`); +``` + +## Performance Optimization + +### Automatic Caching + +QuerySystem uses reactive queries internally with automatic caching: + +```typescript +// First query, executes actual query +const result1 = querySystem.queryAll(PositionComponent); +console.log('fromCache:', result1.fromCache); // false + +// Second same query, uses cache +const result2 = querySystem.queryAll(PositionComponent); +console.log('fromCache:', result2.fromCache); // true +``` + +### Automatic Updates on Entity Changes + +Query cache updates automatically when entities add/remove components: + +```typescript +// Query entities with weapons +const before = querySystem.queryAll(WeaponComponent); +console.log('Before:', before.count); // Assume 5 + +// Add weapon to entity +const enemy = scene.createEntity('Enemy'); +enemy.addComponent(new WeaponComponent()); + +// Query again, automatically includes new entity +const after = querySystem.queryAll(WeaponComponent); +console.log('After:', after.count); // Now 6 +``` + +## More Topics + +- [Matcher API](/en/guide/entity-query/matcher-api) - Complete Matcher API reference +- [Compiled Query](/en/guide/entity-query/compiled-query) - CompiledQuery advanced usage +- [Best Practices](/en/guide/entity-query/best-practices) - Query optimization and practical applications diff --git a/docs/src/content/docs/en/guide/entity-query/matcher-api.md b/docs/src/content/docs/en/guide/entity-query/matcher-api.md new file mode 100644 index 00000000..fc4a309d --- /dev/null +++ b/docs/src/content/docs/en/guide/entity-query/matcher-api.md @@ -0,0 +1,118 @@ +--- +title: "Matcher API" +description: "Complete Matcher API reference" +--- + +## Static Creation Methods + +| Method | Description | Example | +|--------|-------------|---------| +| `Matcher.all(...types)` | Must include all specified components | `Matcher.all(Position, Velocity)` | +| `Matcher.any(...types)` | Include at least one specified component | `Matcher.any(Health, Shield)` | +| `Matcher.none(...types)` | Must not include any specified components | `Matcher.none(Dead)` | +| `Matcher.byTag(tag)` | Query by tag | `Matcher.byTag(1)` | +| `Matcher.byName(name)` | Query by name | `Matcher.byName("Player")` | +| `Matcher.byComponent(type)` | Query by single component | `Matcher.byComponent(Health)` | +| `Matcher.empty()` | Create empty matcher (matches all entities) | `Matcher.empty()` | +| `Matcher.nothing()` | Match no entities | `Matcher.nothing()` | +| `Matcher.complex()` | Create complex query builder | `Matcher.complex()` | + +## Chainable Methods + +| Method | Description | Example | +|--------|-------------|---------| +| `.all(...types)` | Add required components | `.all(Position)` | +| `.any(...types)` | Add optional components (at least one) | `.any(Weapon, Magic)` | +| `.none(...types)` | Add excluded components | `.none(Dead)` | +| `.exclude(...types)` | Alias for `.none()` | `.exclude(Disabled)` | +| `.one(...types)` | Alias for `.any()` | `.one(Player, Enemy)` | +| `.withTag(tag)` | Add tag condition | `.withTag(1)` | +| `.withName(name)` | Add name condition | `.withName("Boss")` | +| `.withComponent(type)` | Add single component condition | `.withComponent(Health)` | + +## Utility Methods + +| Method | Description | +|--------|-------------| +| `.getCondition()` | Get query condition (read-only) | +| `.isEmpty()` | Check if empty condition | +| `.isNothing()` | Check if nothing matcher | +| `.clone()` | Clone matcher | +| `.reset()` | Reset all conditions | +| `.toString()` | Get string representation | + +## Common Combination Examples + +```typescript +// Basic movement system +Matcher.all(Position, Velocity) + +// Attackable living entities +Matcher.all(Position, Health) + .any(Weapon, Magic) + .none(Dead, Disabled) + +// All tagged enemies +Matcher.byTag(Tags.ENEMY) + .all(AIComponent) + +// System only needing lifecycle +Matcher.nothing() +``` + +## Query by Tag + +```typescript +class PlayerSystem extends EntitySystem { + constructor() { + // Query entities with specific tag + super(Matcher.empty().withTag(Tags.PLAYER)); + } + + protected process(entities: readonly Entity[]): void { + // Only process player entities + } +} +``` + +## Query by Name + +```typescript +class BossSystem extends EntitySystem { + constructor() { + // Query entities with specific name + super(Matcher.empty().withName('Boss')); + } + + protected process(entities: readonly Entity[]): void { + // Only process entities named 'Boss' + } +} +``` + +## Important Notes + +### Matcher is Immutable + +```typescript +const matcher = Matcher.empty().all(PositionComponent); + +// Chain calls return new Matcher instances +const matcher2 = matcher.any(VelocityComponent); + +// Original matcher unchanged +console.log(matcher === matcher2); // false +``` + +### Query Results are Read-Only + +```typescript +const result = querySystem.queryAll(PositionComponent); + +// Don't modify returned array +result.entities.push(someEntity); // Wrong! + +// If modification needed, copy first +const mutableArray = [...result.entities]; +mutableArray.push(someEntity); // Correct +``` diff --git a/docs/en/guide/entity.md b/docs/src/content/docs/en/guide/entity.md similarity index 97% rename from docs/en/guide/entity.md rename to docs/src/content/docs/en/guide/entity.md index 884f2769..7a83f22f 100644 --- a/docs/en/guide/entity.md +++ b/docs/src/content/docs/en/guide/entity.md @@ -1,4 +1,6 @@ -# Entity +--- +title: "Entity" +--- In ECS architecture, an Entity is the basic object in the game world. An entity itself does not contain game logic or data - it's just a container that combines different components to achieve various functionalities. @@ -12,7 +14,7 @@ An entity is a lightweight object mainly used for: ::: tip About Parent-Child Hierarchy Parent-child hierarchy relationships between entities are managed through `HierarchyComponent` and `HierarchySystem`, not built-in Entity properties. This design follows ECS composition principles - only entities that need hierarchy relationships add this component. -See [Hierarchy System](./hierarchy.md) documentation. +See [Hierarchy System](./hierarchy/) documentation. ::: ## Creating Entities @@ -439,6 +441,6 @@ const emptyHandle = NULL_HANDLE; ## Next Steps -- Learn about [Hierarchy System](./hierarchy.md) to establish parent-child relationships -- Learn about [Component System](./component.md) to add functionality to entities -- Learn about [Scene Management](./scene.md) to organize and manage entities +- Learn about [Hierarchy System](./hierarchy/) to establish parent-child relationships +- Learn about [Component System](./component/) to add functionality to entities +- Learn about [Scene Management](./scene/) to organize and manage entities diff --git a/docs/src/content/docs/en/guide/event-system.md b/docs/src/content/docs/en/guide/event-system.md new file mode 100644 index 00000000..ac275c21 --- /dev/null +++ b/docs/src/content/docs/en/guide/event-system.md @@ -0,0 +1,260 @@ +--- +title: "Event System" +description: "Type-safe event system with sync/async events, priorities, and batching" +--- + +The ECS framework includes a powerful type-safe event system supporting sync/async events, priorities, batching, and more advanced features. The event system is the core mechanism for inter-component and inter-system communication. + +## Basic Concepts + +The event system implements a publish-subscribe pattern with these core concepts: +- **Event Publisher**: Object that emits events +- **Event Listener**: Object that listens for and handles specific events +- **Event Type**: String identifier to distinguish different event types +- **Event Data**: Related information carried by the event + +## Basic Usage + +### Using Event System in Scene + +Each scene has a built-in event system: + +```typescript +class GameScene extends Scene { + protected initialize(): void { + // Listen for events + this.eventSystem.on('player_died', this.onPlayerDied.bind(this)); + this.eventSystem.on('enemy_spawned', this.onEnemySpawned.bind(this)); + this.eventSystem.on('score_changed', this.onScoreChanged.bind(this)); + } + + private onPlayerDied(data: { player: Entity, cause: string }): void { + console.log(`Player died, cause: ${data.cause}`); + } + + private onEnemySpawned(data: { enemy: Entity, position: { x: number, y: number } }): void { + console.log('Enemy spawned at:', data.position); + } + + private onScoreChanged(data: { newScore: number, oldScore: number }): void { + console.log(`Score changed: ${data.oldScore} -> ${data.newScore}`); + } + + // Emit events in systems + someGameLogic(): void { + this.eventSystem.emitSync('score_changed', { + newScore: 1000, + oldScore: 800 + }); + } +} +``` + +### Using Events in Systems + +Systems can conveniently listen for and send events: + +```typescript +@ECSSystem('Combat') +class CombatSystem extends EntitySystem { + constructor() { + super(Matcher.all(Health, Combat)); + } + + protected onInitialize(): void { + // Use system's event listener method (auto-cleanup) + this.addEventListener('player_attack', this.onPlayerAttack.bind(this)); + this.addEventListener('enemy_death', this.onEnemyDeath.bind(this)); + } + + private onPlayerAttack(data: { damage: number, target: Entity }): void { + const health = data.target.getComponent(Health); + if (health) { + health.current -= data.damage; + + if (health.current <= 0) { + this.scene?.eventSystem.emitSync('enemy_death', { + enemy: data.target, + killer: 'player' + }); + } + } + } + + private onEnemyDeath(data: { enemy: Entity, killer: string }): void { + data.enemy.destroy(); + this.scene?.eventSystem.emitSync('experience_gained', { + amount: 100, + source: 'enemy_kill' + }); + } +} +``` + +## Advanced Features + +### One-Time Listeners + +```typescript +// Listen only once +this.eventSystem.once('game_start', this.onGameStart.bind(this)); + +// Or use configuration object +this.eventSystem.on('level_complete', this.onLevelComplete.bind(this), { + once: true +}); +``` + +### Priority Control + +```typescript +// Higher priority listeners execute first +this.eventSystem.on('damage_dealt', this.onDamageDealt.bind(this), { + priority: 100 // High priority +}); + +this.eventSystem.on('damage_dealt', this.updateUI.bind(this), { + priority: 0 // Default priority +}); + +this.eventSystem.on('damage_dealt', this.logDamage.bind(this), { + priority: -100 // Low priority, executes last +}); +``` + +### Async Event Handling + +```typescript +protected initialize(): void { + this.eventSystem.onAsync('save_game', this.onSaveGame.bind(this)); +} + +private async onSaveGame(data: { saveSlot: number }): Promise { + console.log(`Saving game to slot ${data.saveSlot}`); + await this.saveGameData(data.saveSlot); + console.log('Game saved'); +} + +// Emit async event +public async triggerSave(): Promise { + await this.eventSystem.emit('save_game', { saveSlot: 1 }); + console.log('All async save operations complete'); +} +``` + +### Batch Processing + +For high-frequency events, use batching to improve performance: + +```typescript +protected onInitialize(): void { + // Configure batch processing for position updates + this.scene?.eventSystem.setBatchConfig('position_updated', { + batchSize: 50, + delay: 16, + enabled: true + }); + + // Listen for batch events + this.addEventListener('position_updated:batch', this.onPositionBatch.bind(this)); +} + +private onPositionBatch(batchData: any): void { + console.log(`Batch processing ${batchData.count} position updates`); + for (const event of batchData.events) { + this.updateMinimap(event.entityId, event.position); + } +} +``` + +## Global Event Bus + +For cross-scene event communication: + +```typescript +import { GlobalEventBus } from '@esengine/ecs-framework'; + +class GameManager { + private eventBus = GlobalEventBus.getInstance(); + + constructor() { + this.eventBus.on('player_level_up', this.onPlayerLevelUp.bind(this)); + this.eventBus.on('achievement_unlocked', this.onAchievementUnlocked.bind(this)); + } + + private onPlayerLevelUp(data: { level: number }): void { + console.log(`Player leveled up to ${data.level}!`); + } +} +``` + +## Best Practices + +### 1. Event Naming Convention + +```typescript +// ✅ Good naming +this.eventSystem.emitSync('player:health_changed', data); +this.eventSystem.emitSync('enemy:spawned', data); +this.eventSystem.emitSync('ui:score_updated', data); + +// ❌ Avoid +this.eventSystem.emitSync('event1', data); +this.eventSystem.emitSync('update', data); +``` + +### 2. Type-Safe Event Data + +```typescript +interface PlayerHealthChangedEvent { + entityId: number; + oldHealth: number; + newHealth: number; + cause: 'damage' | 'healing'; +} + +class HealthSystem extends EntitySystem { + private onHealthChanged(data: PlayerHealthChangedEvent): void { + // TypeScript provides full type checking + console.log(`Health changed: ${data.oldHealth} -> ${data.newHealth}`); + } +} +``` + +### 3. Avoid Event Loops + +```typescript +// ❌ Avoid: May cause infinite loop +private onScoreChanged(data: any): void { + this.scene?.eventSystem.emitSync('score_changed', newData); // Dangerous! +} + +// ✅ Correct: Use guard flag +private isProcessingScore = false; + +private onScoreChanged(data: any): void { + if (this.isProcessingScore) return; + + this.isProcessingScore = true; + this.updateUI(data); + this.isProcessingScore = false; +} +``` + +### 4. Clean Up Event Listeners + +```typescript +class TemporaryUI { + private listenerId: string; + + constructor(scene: Scene) { + this.listenerId = scene.eventSystem.on('ui_update', this.onUpdate.bind(this)); + } + + public destroy(): void { + if (this.listenerId) { + scene.eventSystem.off('ui_update', this.listenerId); + } + } +} +``` diff --git a/docs/en/guide/getting-started.md b/docs/src/content/docs/en/guide/getting-started.md similarity index 99% rename from docs/en/guide/getting-started.md rename to docs/src/content/docs/en/guide/getting-started.md index 4c7bf840..cefaa770 100644 --- a/docs/en/guide/getting-started.md +++ b/docs/src/content/docs/en/guide/getting-started.md @@ -1,4 +1,6 @@ -# Quick Start +--- +title: "Quick Start" +--- This guide will help you get started with ECS Framework, from installation to creating your first ECS application. diff --git a/docs/src/content/docs/en/guide/hierarchy.md b/docs/src/content/docs/en/guide/hierarchy.md new file mode 100644 index 00000000..7951eab7 --- /dev/null +++ b/docs/src/content/docs/en/guide/hierarchy.md @@ -0,0 +1,202 @@ +--- +title: "Hierarchy System" +description: "Parent-child entity relationships using component-based design" +--- + +In game development, parent-child hierarchy relationships between entities are common requirements. ECS Framework manages hierarchy relationships through a component-based approach using `HierarchyComponent` and `HierarchySystem`, fully adhering to ECS composition principles. + +## Design Philosophy + +### Why Not Built-in Hierarchy in Entity? + +Traditional game object models build hierarchy into entities. ECS Framework chose a component-based approach because: + +1. **ECS Composition Principle**: Hierarchy is a "feature" that should be added through components, not inherent to all entities +2. **On-Demand Usage**: Only entities that need hierarchy add `HierarchyComponent` +3. **Data-Logic Separation**: `HierarchyComponent` stores data, `HierarchySystem` handles logic +4. **Serialization-Friendly**: Hierarchy as component data can be easily serialized/deserialized + +## Basic Concepts + +### HierarchyComponent + +Component storing hierarchy relationship data: + +```typescript +import { HierarchyComponent } from '@esengine/ecs-framework'; + +interface HierarchyComponent { + parentId: number | null; // Parent entity ID, null means root + childIds: number[]; // Child entity ID list + depth: number; // Depth in hierarchy (maintained by system) + bActiveInHierarchy: boolean; // Active in hierarchy (maintained by system) +} +``` + +### HierarchySystem + +System handling hierarchy logic, provides all hierarchy operation APIs: + +```typescript +import { HierarchySystem } from '@esengine/ecs-framework'; + +const hierarchySystem = scene.getEntityProcessor(HierarchySystem); +``` + +## Quick Start + +### Add System to Scene + +```typescript +import { Scene, HierarchySystem } from '@esengine/ecs-framework'; + +class GameScene extends Scene { + protected initialize(): void { + this.addSystem(new HierarchySystem()); + } +} +``` + +### Establish Parent-Child Relationships + +```typescript +const parent = scene.createEntity("Parent"); +const child1 = scene.createEntity("Child1"); +const child2 = scene.createEntity("Child2"); + +const hierarchySystem = scene.getEntityProcessor(HierarchySystem); + +// Set parent-child relationship (auto-adds HierarchyComponent) +hierarchySystem.setParent(child1, parent); +hierarchySystem.setParent(child2, parent); +``` + +### Query Hierarchy + +```typescript +// Get parent entity +const parentEntity = hierarchySystem.getParent(child1); + +// Get all children +const children = hierarchySystem.getChildren(parent); + +// Get child count +const count = hierarchySystem.getChildCount(parent); + +// Check if has children +const hasKids = hierarchySystem.hasChildren(parent); + +// Get depth in hierarchy +const depth = hierarchySystem.getDepth(child1); // Returns 1 +``` + +## API Reference + +### Parent-Child Operations + +```typescript +// Set parent +hierarchySystem.setParent(child, parent); + +// Move to root (no parent) +hierarchySystem.setParent(child, null); + +// Insert child at position +hierarchySystem.insertChildAt(parent, child, 0); + +// Remove child (becomes root) +hierarchySystem.removeChild(parent, child); + +// Remove all children +hierarchySystem.removeAllChildren(parent); +``` + +### Hierarchy Queries + +```typescript +// Get root of entity +const root = hierarchySystem.getRoot(deepChild); + +// Get all root entities +const roots = hierarchySystem.getRootEntities(); + +// Check ancestor/descendant relationships +const isAncestor = hierarchySystem.isAncestorOf(grandparent, child); +const isDescendant = hierarchySystem.isDescendantOf(child, grandparent); +``` + +### Hierarchy Traversal + +```typescript +// Find child by name +const child = hierarchySystem.findChild(parent, "ChildName"); + +// Recursive search +const deepChild = hierarchySystem.findChild(parent, "DeepChild", true); + +// Find children by tag +const tagged = hierarchySystem.findChildrenByTag(parent, TAG_ENEMY, true); + +// Iterate children +hierarchySystem.forEachChild(parent, (child) => { + console.log(child.name); +}, true); // true for recursive +``` + +### Hierarchy State + +```typescript +// Check if active in hierarchy (considers all ancestors) +const activeInHierarchy = hierarchySystem.isActiveInHierarchy(child); + +// Get depth (root = 0) +const depth = hierarchySystem.getDepth(entity); +``` + +## Complete Example + +```typescript +class GameScene extends Scene { + private hierarchySystem!: HierarchySystem; + + protected initialize(): void { + this.hierarchySystem = new HierarchySystem(); + this.addSystem(this.hierarchySystem); + this.createPlayerHierarchy(); + } + + private createPlayerHierarchy(): void { + const player = this.createEntity("Player"); + player.addComponent(new Transform(0, 0)); + + const body = this.createEntity("Body"); + body.addComponent(new Sprite("body.png")); + this.hierarchySystem.setParent(body, player); + + const weapon = this.createEntity("Weapon"); + weapon.addComponent(new Sprite("sword.png")); + this.hierarchySystem.setParent(weapon, body); + + console.log(`Player depth: ${this.hierarchySystem.getDepth(player)}`); // 0 + console.log(`Weapon depth: ${this.hierarchySystem.getDepth(weapon)}`); // 2 + } +} +``` + +## Best Practices + +1. **Avoid Deep Nesting**: System limits max depth to 32 levels +2. **Batch Operations**: Set up all parent-child relationships at once when building complex hierarchies +3. **On-Demand Addition**: Only add `HierarchyComponent` to entities that truly need hierarchy +4. **Cache System Reference**: Avoid getting `HierarchySystem` on every call + +```typescript +// Good practice +class MySystem extends EntitySystem { + private hierarchySystem!: HierarchySystem; + + onAddedToScene() { + this.hierarchySystem = this.scene!.getEntityProcessor(HierarchySystem)!; + } +} +``` diff --git a/docs/en/guide/index.md b/docs/src/content/docs/en/guide/index.md similarity index 98% rename from docs/en/guide/index.md rename to docs/src/content/docs/en/guide/index.md index a08d69cc..6131b3f9 100644 --- a/docs/en/guide/index.md +++ b/docs/src/content/docs/en/guide/index.md @@ -1,4 +1,6 @@ -# Guide +--- +title: "Guide" +--- Welcome to the ECS Framework Guide. This guide covers the core concepts and usage of the framework. diff --git a/docs/src/content/docs/en/guide/logging.md b/docs/src/content/docs/en/guide/logging.md new file mode 100644 index 00000000..65e26b4b --- /dev/null +++ b/docs/src/content/docs/en/guide/logging.md @@ -0,0 +1,225 @@ +--- +title: "Logging System" +description: "Multi-level logging with colors, prefixes, and flexible configuration" +--- + +The ECS framework provides a powerful hierarchical logging system supporting multiple log levels, color output, custom prefixes, and flexible configuration options. + +## Basic Concepts + +- **Log Levels**: Debug < Info < Warn < Error < Fatal < None +- **Logger**: Named log outputter, each module can have its own logger +- **Logger Manager**: Singleton managing all loggers globally +- **Color Config**: Supports console color output + +## Log Levels + +```typescript +import { LogLevel } from '@esengine/ecs-framework'; + +LogLevel.Debug // 0 - Debug information +LogLevel.Info // 1 - General information +LogLevel.Warn // 2 - Warning information +LogLevel.Error // 3 - Error information +LogLevel.Fatal // 4 - Fatal errors +LogLevel.None // 5 - No output +``` + +## Basic Usage + +### Using Default Logger + +```typescript +import { Logger } from '@esengine/ecs-framework'; + +class GameSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + Logger.debug('Processing entities:', entities.length); + Logger.info('System running normally'); + Logger.warn('Performance issue detected'); + Logger.error('Error during processing', new Error('Example')); + Logger.fatal('Fatal error, system stopping'); + } +} +``` + +### Creating Named Logger + +```typescript +import { createLogger } from '@esengine/ecs-framework'; + +class MovementSystem extends EntitySystem { + private logger = createLogger('MovementSystem'); + + protected process(entities: readonly Entity[]): void { + this.logger.info(`Processing ${entities.length} moving entities`); + + for (const entity of entities) { + const position = entity.getComponent(Position); + this.logger.debug(`Entity ${entity.id} moved to (${position.x}, ${position.y})`); + } + } +} +``` + +## Log Configuration + +### Set Global Log Level + +```typescript +import { setGlobalLogLevel, LogLevel } from '@esengine/ecs-framework'; + +// Development: show all logs +setGlobalLogLevel(LogLevel.Debug); + +// Production: show warnings and above +setGlobalLogLevel(LogLevel.Warn); + +// Disable all logs +setGlobalLogLevel(LogLevel.None); +``` + +### Custom Logger Configuration + +```typescript +import { ConsoleLogger, LogLevel } from '@esengine/ecs-framework'; + +// Development logger +const debugLogger = new ConsoleLogger({ + level: LogLevel.Debug, + enableTimestamp: true, + enableColors: true, + prefix: 'DEV' +}); + +// Production logger +const productionLogger = new ConsoleLogger({ + level: LogLevel.Error, + enableTimestamp: true, + enableColors: false, + prefix: 'PROD' +}); +``` + +## Color Configuration + +```typescript +import { Colors, setLoggerColors } from '@esengine/ecs-framework'; + +setLoggerColors({ + debug: Colors.BRIGHT_BLACK, + info: Colors.BLUE, + warn: Colors.YELLOW, + error: Colors.RED, + fatal: Colors.BRIGHT_RED +}); +``` + +## Advanced Features + +### Hierarchical Loggers + +```typescript +import { LoggerManager } from '@esengine/ecs-framework'; + +const manager = LoggerManager.getInstance(); + +// Create child loggers +const movementLogger = manager.createChildLogger('GameSystems', 'Movement'); +const renderLogger = manager.createChildLogger('GameSystems', 'Render'); + +// Child logger shows full path: [GameSystems.Movement] +movementLogger.debug('Movement system initialized'); +``` + +### Third-Party Logger Integration + +```typescript +import { setLoggerFactory } from '@esengine/ecs-framework'; + +// Integrate with Winston +setLoggerFactory((name?: string) => winston.createLogger({ /* ... */ })); + +// Integrate with Pino +setLoggerFactory((name?: string) => pino({ name })); + +// Integrate with NestJS Logger +setLoggerFactory((name?: string) => new Logger(name)); +``` + +### Custom Output + +```typescript +const fileLogger = new ConsoleLogger({ + level: LogLevel.Info, + output: (level: LogLevel, message: string) => { + this.writeToFile(LogLevel[level], message); + } +}); +``` + +## Best Practices + +### 1. Choose Appropriate Log Levels + +```typescript +// Debug - Detailed debug info +this.logger.debug('Variable values', { x: 10, y: 20 }); + +// Info - Important state changes +this.logger.info('System startup complete'); + +// Warn - Abnormal but non-fatal +this.logger.warn('Resource not found, using default'); + +// Error - Errors but program can continue +this.logger.error('Save failed, will retry', new Error('Network timeout')); + +// Fatal - Fatal errors, program cannot continue +this.logger.fatal('Out of memory, exiting'); +``` + +### 2. Structured Log Data + +```typescript +this.logger.info('User action', { + userId: 12345, + action: 'move', + position: { x: 100, y: 200 }, + timestamp: Date.now() +}); +``` + +### 3. Avoid Performance Issues + +```typescript +// ✅ Check log level before expensive computation +if (this.logger.debug) { + const expensiveData = this.calculateExpensiveDebugInfo(); + this.logger.debug('Debug info', expensiveData); +} +``` + +### 4. Environment-Based Configuration + +```typescript +class LoggingConfiguration { + public static setupLogging(): void { + const isDevelopment = process.env.NODE_ENV === 'development'; + + if (isDevelopment) { + setGlobalLogLevel(LogLevel.Debug); + setLoggerColors({ + debug: Colors.CYAN, + info: Colors.GREEN, + warn: Colors.YELLOW, + error: Colors.RED, + fatal: Colors.BRIGHT_RED + }); + } else { + setGlobalLogLevel(LogLevel.Warn); + LoggerManager.getInstance().resetColors(); + } + } +} +``` diff --git a/docs/en/guide/persistent-entity.md b/docs/src/content/docs/en/guide/persistent-entity.md similarity index 99% rename from docs/en/guide/persistent-entity.md rename to docs/src/content/docs/en/guide/persistent-entity.md index 95bd224c..4ac94bce 100644 --- a/docs/en/guide/persistent-entity.md +++ b/docs/src/content/docs/en/guide/persistent-entity.md @@ -1,3 +1,7 @@ +--- +title: "persistent-entity" +--- + # Persistent Entity > **Version**: v2.3.0+ diff --git a/docs/src/content/docs/en/guide/platform-adapter.md b/docs/src/content/docs/en/guide/platform-adapter.md new file mode 100644 index 00000000..89ee1c4a --- /dev/null +++ b/docs/src/content/docs/en/guide/platform-adapter.md @@ -0,0 +1,291 @@ +--- +title: "Platform Adapter" +--- + +## Overview + +The ECS framework provides a platform adapter interface that allows users to implement custom platform adapters for different runtime environments. + +**The core library only provides interface definitions. Platform adapter implementations should be copied from the documentation.** + +## Why No Separate Adapter Packages? + +1. **Flexibility**: Different projects may have different platform adaptation needs. Copying code allows users to freely modify as needed +2. **Reduce Dependencies**: Avoid introducing unnecessary dependency packages, keeping the core framework lean +3. **Customization**: Users can customize according to specific runtime environments and requirements + +## Supported Platforms + +### [Browser Adapter](./platform-adapter/browser/) + +Supports all modern browser environments, including Chrome, Firefox, Safari, Edge, etc. + +**Feature Support**: +- Worker (Web Worker) +- SharedArrayBuffer (requires COOP/COEP) +- Transferable Objects +- Module Worker (modern browsers) + +**Use Cases**: Web games, Web applications, PWA + +--- + +### [WeChat Mini Game Adapter](./platform-adapter/wechat-minigame/) + +Designed specifically for the WeChat Mini Game environment, handling special restrictions and APIs. + +**Feature Support**: +- Worker (max 1, requires game.json configuration) +- SharedArrayBuffer (not supported) +- Transferable Objects (not supported) +- WeChat Device Info API + +**Use Cases**: WeChat Mini Game development + +--- + +### [Node.js Adapter](./platform-adapter/nodejs/) + +Provides support for Node.js server environments, suitable for game servers and compute servers. + +**Feature Support**: +- Worker Threads +- SharedArrayBuffer +- Transferable Objects +- Complete system information + +**Use Cases**: Game servers, compute servers, CLI tools + +--- + +## Core Interfaces + +### IPlatformAdapter + +```typescript +export interface IPlatformAdapter { + readonly name: string; + readonly version?: string; + + isWorkerSupported(): boolean; + isSharedArrayBufferSupported(): boolean; + getHardwareConcurrency(): number; + createWorker(script: string, options?: WorkerCreationOptions): PlatformWorker; + createSharedArrayBuffer(length: number): SharedArrayBuffer | null; + getHighResTimestamp(): number; + getPlatformConfig(): PlatformConfig; + getPlatformConfigAsync?(): Promise; +} +``` + +### PlatformWorker Interface + +```typescript +export interface PlatformWorker { + postMessage(message: any, transfer?: Transferable[]): void; + onMessage(handler: (event: { data: any }) => void): void; + onError(handler: (error: ErrorEvent) => void): void; + terminate(): void; + readonly state: 'running' | 'terminated'; +} +``` + +## Usage + +### 1. Choose the Appropriate Platform Adapter + +Select the corresponding adapter based on your runtime environment: + +```typescript +import { PlatformManager } from '@esengine/ecs-framework'; + +// Browser environment +if (typeof window !== 'undefined') { + const { BrowserAdapter } = await import('./platform/BrowserAdapter'); + PlatformManager.getInstance().registerAdapter(new BrowserAdapter()); +} + +// WeChat Mini Game environment +else if (typeof wx !== 'undefined') { + const { WeChatMiniGameAdapter } = await import('./platform/WeChatMiniGameAdapter'); + PlatformManager.getInstance().registerAdapter(new WeChatMiniGameAdapter()); +} + +// Node.js environment +else if (typeof process !== 'undefined' && process.versions?.node) { + const { NodeAdapter } = await import('./platform/NodeAdapter'); + PlatformManager.getInstance().registerAdapter(new NodeAdapter()); +} +``` + +### 2. Check Adapter Status + +```typescript +const manager = PlatformManager.getInstance(); + +// Check if adapter is registered +if (manager.hasAdapter()) { + const adapter = manager.getAdapter(); + console.log('Current platform:', adapter.name); + console.log('Platform version:', adapter.version); + + // Check feature support + console.log('Worker support:', manager.supportsFeature('worker')); + console.log('SharedArrayBuffer support:', manager.supportsFeature('shared-array-buffer')); +} +``` + +## Creating Custom Adapters + +If existing platform adapters don't meet your needs, you can create custom adapters: + +### 1. Implement the Interface + +```typescript +import type { IPlatformAdapter, PlatformWorker, WorkerCreationOptions, PlatformConfig } from '@esengine/ecs-framework'; + +export class CustomAdapter implements IPlatformAdapter { + public readonly name = 'custom'; + public readonly version = '1.0.0'; + + public isWorkerSupported(): boolean { + // Implement your Worker support check logic + return false; + } + + public isSharedArrayBufferSupported(): boolean { + // Implement your SharedArrayBuffer support check logic + return false; + } + + public getHardwareConcurrency(): number { + // Return your platform's concurrency count + return 1; + } + + public createWorker(script: string, options?: WorkerCreationOptions): PlatformWorker { + throw new Error('Worker not supported on this platform'); + } + + public createSharedArrayBuffer(length: number): SharedArrayBuffer | null { + return null; + } + + public getHighResTimestamp(): number { + return Date.now(); + } + + public getPlatformConfig(): PlatformConfig { + return { + maxWorkerCount: 1, + supportsModuleWorker: false, + supportsTransferableObjects: false, + limitations: { + workerNotSupported: true + } + }; + } +} +``` + +### 2. Register Custom Adapter + +```typescript +import { PlatformManager } from '@esengine/ecs-framework'; +import { CustomAdapter } from './CustomAdapter'; + +const customAdapter = new CustomAdapter(); +PlatformManager.getInstance().registerAdapter(customAdapter); +``` + +## Best Practices + +### 1. Platform Detection Order + +Recommend detecting and registering platform adapters in this order: + +```typescript +async function initializePlatform() { + const manager = PlatformManager.getInstance(); + + try { + // 1. WeChat Mini Game (highest priority, most distinctive environment) + if (typeof wx !== 'undefined' && wx.getSystemInfoSync) { + const { WeChatMiniGameAdapter } = await import('./platform/WeChatMiniGameAdapter'); + manager.registerAdapter(new WeChatMiniGameAdapter()); + return; + } + + // 2. Node.js environment + if (typeof process !== 'undefined' && process.versions?.node) { + const { NodeAdapter } = await import('./platform/NodeAdapter'); + manager.registerAdapter(new NodeAdapter()); + return; + } + + // 3. Browser environment (last check, broadest coverage) + if (typeof window !== 'undefined' && typeof document !== 'undefined') { + const { BrowserAdapter } = await import('./platform/BrowserAdapter'); + manager.registerAdapter(new BrowserAdapter()); + return; + } + + // 4. Unknown environment, use default adapter + console.warn('Unrecognized platform environment, using default adapter'); + manager.registerAdapter(new CustomAdapter()); + + } catch (error) { + console.error('Platform adapter initialization failed:', error); + throw error; + } +} +``` + +### 2. Feature Degradation Handling + +```typescript +function createWorkerSystem() { + const manager = PlatformManager.getInstance(); + + if (!manager.hasAdapter()) { + throw new Error('No platform adapter registered'); + } + + const config: WorkerSystemConfig = { + enableWorker: manager.supportsFeature('worker'), + workerCount: manager.supportsFeature('worker') ? + manager.getAdapter().getHardwareConcurrency() : 1, + useSharedArrayBuffer: manager.supportsFeature('shared-array-buffer') + }; + + // If Worker not supported, automatically degrade to synchronous processing + if (!config.enableWorker) { + console.info('Current platform does not support Worker, using synchronous processing mode'); + } + + return new PhysicsSystem(config); +} +``` + +### 3. Error Handling + +```typescript +try { + await initializePlatform(); + + // Validate adapter functionality + const manager = PlatformManager.getInstance(); + const adapter = manager.getAdapter(); + + console.log(`Platform adapter initialized: ${adapter.name} v${adapter.version}`); + +} catch (error) { + console.error('Platform initialization failed:', error); + + // Provide fallback solution + const fallbackAdapter = new CustomAdapter(); + PlatformManager.getInstance().registerAdapter(fallbackAdapter); + + console.warn('Using fallback adapter to continue running'); +} +``` diff --git a/docs/src/content/docs/en/guide/platform-adapter/browser.md b/docs/src/content/docs/en/guide/platform-adapter/browser.md new file mode 100644 index 00000000..aada3f5d --- /dev/null +++ b/docs/src/content/docs/en/guide/platform-adapter/browser.md @@ -0,0 +1,372 @@ +--- +title: "Browser Adapter" +--- + +## Overview + +The browser platform adapter provides support for standard web browser environments, including modern browsers like Chrome, Firefox, Safari, Edge, etc. + +## Feature Support + +- **Worker**: Supports Web Worker and Module Worker +- **SharedArrayBuffer**: Supported (requires COOP/COEP headers) +- **Transferable Objects**: Fully supported +- **High-Resolution Time**: Uses `performance.now()` +- **Basic Info**: Browser version and basic configuration + +## Complete Implementation + +```typescript +import type { + IPlatformAdapter, + PlatformWorker, + WorkerCreationOptions, + PlatformConfig +} from '@esengine/ecs-framework'; + +/** + * Browser platform adapter + * Supports standard web browser environments + */ +export class BrowserAdapter implements IPlatformAdapter { + public readonly name = 'browser'; + public readonly version: string; + + constructor() { + this.version = this.getBrowserInfo(); + } + + /** + * Check if Worker is supported + */ + public isWorkerSupported(): boolean { + return typeof Worker !== 'undefined'; + } + + /** + * Check if SharedArrayBuffer is supported + */ + public isSharedArrayBufferSupported(): boolean { + return typeof SharedArrayBuffer !== 'undefined' && this.checkSharedArrayBufferEnabled(); + } + + /** + * Get hardware concurrency (CPU core count) + */ + public getHardwareConcurrency(): number { + return navigator.hardwareConcurrency || 4; + } + + /** + * Create Worker + */ + public createWorker(script: string, options: WorkerCreationOptions = {}): PlatformWorker { + if (!this.isWorkerSupported()) { + throw new Error('Browser does not support Worker'); + } + + try { + return new BrowserWorker(script, options); + } catch (error) { + throw new Error(`Failed to create browser Worker: ${(error as Error).message}`); + } + } + + /** + * Create SharedArrayBuffer + */ + public createSharedArrayBuffer(length: number): SharedArrayBuffer | null { + if (!this.isSharedArrayBufferSupported()) { + return null; + } + + try { + return new SharedArrayBuffer(length); + } catch (error) { + console.warn('SharedArrayBuffer creation failed:', error); + return null; + } + } + + /** + * Get high-resolution timestamp + */ + public getHighResTimestamp(): number { + return performance.now(); + } + + /** + * Get platform configuration + */ + public getPlatformConfig(): PlatformConfig { + return { + maxWorkerCount: this.getHardwareConcurrency(), + supportsModuleWorker: false, + supportsTransferableObjects: true, + maxSharedArrayBufferSize: 1024 * 1024 * 1024, // 1GB + workerScriptPrefix: '', + limitations: { + noEval: false, + requiresWorkerInit: false + } + }; + } + + /** + * Get browser information + */ + private getBrowserInfo(): string { + const userAgent = navigator.userAgent; + if (userAgent.includes('Chrome')) { + const match = userAgent.match(/Chrome\/([0-9.]+)/); + return match ? `Chrome ${match[1]}` : 'Chrome'; + } else if (userAgent.includes('Firefox')) { + const match = userAgent.match(/Firefox\/([0-9.]+)/); + if (match) return `Firefox ${match[1]}`; + } else if (userAgent.includes('Safari')) { + const match = userAgent.match(/Version\/([0-9.]+)/); + if (match) return `Safari ${match[1]}`; + } + return 'Unknown Browser'; + } + + /** + * Check if SharedArrayBuffer is actually available + */ + private checkSharedArrayBufferEnabled(): boolean { + try { + new SharedArrayBuffer(8); + return true; + } catch { + return false; + } + } +} + +/** + * Browser Worker wrapper + */ +class BrowserWorker implements PlatformWorker { + private _state: 'running' | 'terminated' = 'running'; + private worker: Worker; + + constructor(script: string, options: WorkerCreationOptions = {}) { + this.worker = this.createBrowserWorker(script, options); + } + + public get state(): 'running' | 'terminated' { + return this._state; + } + + public postMessage(message: any, transfer?: Transferable[]): void { + if (this._state === 'terminated') { + throw new Error('Worker has been terminated'); + } + + try { + if (transfer && transfer.length > 0) { + this.worker.postMessage(message, transfer); + } else { + this.worker.postMessage(message); + } + } catch (error) { + throw new Error(`Failed to send message to Worker: ${(error as Error).message}`); + } + } + + public onMessage(handler: (event: { data: any }) => void): void { + this.worker.onmessage = (event: MessageEvent) => { + handler({ data: event.data }); + }; + } + + public onError(handler: (error: ErrorEvent) => void): void { + this.worker.onerror = handler; + } + + public terminate(): void { + if (this._state === 'running') { + try { + this.worker.terminate(); + this._state = 'terminated'; + } catch (error) { + console.error('Failed to terminate Worker:', error); + } + } + } + + /** + * Create browser Worker + */ + private createBrowserWorker(script: string, options: WorkerCreationOptions): Worker { + try { + // Create Blob URL + const blob = new Blob([script], { type: 'application/javascript' }); + const url = URL.createObjectURL(blob); + + // Create Worker + const worker = new Worker(url, { + type: options.type || 'classic', + credentials: options.credentials, + name: options.name + }); + + // Clean up Blob URL (delayed to ensure Worker has loaded) + setTimeout(() => { + URL.revokeObjectURL(url); + }, 1000); + + return worker; + } catch (error) { + throw new Error(`Cannot create browser Worker: ${(error as Error).message}`); + } + } +} +``` + +## Usage + +### 1. Copy the Code + +Copy the above code to your project, e.g., `src/platform/BrowserAdapter.ts`. + +### 2. Register the Adapter + +```typescript +import { PlatformManager } from '@esengine/ecs-framework'; +import { BrowserAdapter } from './platform/BrowserAdapter'; + +// Create and register browser adapter +const browserAdapter = new BrowserAdapter(); +PlatformManager.registerAdapter(browserAdapter); + +// Framework will automatically detect and use the appropriate adapter +``` + +### 3. Use WorkerEntitySystem + +The browser adapter works with WorkerEntitySystem, and the framework automatically handles Worker script creation: + +```typescript +import { WorkerEntitySystem, Matcher } from '@esengine/ecs-framework'; + +class PhysicsSystem extends WorkerEntitySystem { + constructor() { + super(Matcher.all(Transform, Velocity), { + enableWorker: true, + workerCount: navigator.hardwareConcurrency || 4, + useSharedArrayBuffer: true, + systemConfig: { gravity: 9.8 } + }); + } + + protected getDefaultEntityDataSize(): number { + return 6; // x, y, vx, vy, mass, radius + } + + protected extractEntityData(entity: Entity): PhysicsData { + const transform = entity.getComponent(Transform); + const velocity = entity.getComponent(Velocity); + return { + x: transform.x, + y: transform.y, + vx: velocity.x, + vy: velocity.y, + mass: 1, + radius: 10 + }; + } + + // This function is automatically serialized and executed in Worker + protected workerProcess(entities, deltaTime, config) { + return entities.map(entity => { + // Apply gravity + entity.vy += config.gravity * deltaTime; + + // Update position + entity.x += entity.vx * deltaTime; + entity.y += entity.vy * deltaTime; + + return entity; + }); + } + + protected applyResult(entity: Entity, result: PhysicsData): void { + const transform = entity.getComponent(Transform); + const velocity = entity.getComponent(Velocity); + + transform.x = result.x; + transform.y = result.y; + velocity.x = result.vx; + velocity.y = result.vy; + } +} + +interface PhysicsData { + x: number; + y: number; + vx: number; + vy: number; + mass: number; + radius: number; +} +``` + +### 4. Verify Adapter Status + +```typescript +// Verify adapter is working properly +const adapter = new BrowserAdapter(); +console.log('Adapter name:', adapter.name); +console.log('Browser version:', adapter.version); +console.log('Worker support:', adapter.isWorkerSupported()); +console.log('SharedArrayBuffer support:', adapter.isSharedArrayBufferSupported()); +console.log('CPU core count:', adapter.getHardwareConcurrency()); +``` + +## Important Notes + +### SharedArrayBuffer Support + +SharedArrayBuffer requires special security configuration: + +1. **HTTPS**: Must be used in a secure context +2. **COOP/COEP Headers**: Requires correct cross-origin isolation headers + +```html + + + +``` + +Or set in server configuration: + +``` +Cross-Origin-Opener-Policy: same-origin +Cross-Origin-Embedder-Policy: require-corp +``` + +### Browser Compatibility + +- **Worker**: All modern browsers supported +- **Module Worker**: Chrome 80+, Firefox 114+ +- **SharedArrayBuffer**: Chrome 68+, Firefox 79+ (requires COOP/COEP) +- **Transferable Objects**: All modern browsers supported + +## Performance Optimization Tips + +1. **Worker Pool**: Reuse Worker instances to avoid frequent creation and destruction +2. **Data Transfer**: Use Transferable Objects to reduce data copying +3. **SharedArrayBuffer**: Use SharedArrayBuffer for large data sharing +4. **Module Worker**: Use module Workers in supported browsers for better code organization + +## Debugging Tips + +```typescript +// Check browser support +const adapter = new BrowserAdapter(); +console.log('Worker support:', adapter.isWorkerSupported()); +console.log('SharedArrayBuffer support:', adapter.isSharedArrayBufferSupported()); +console.log('Hardware concurrency:', adapter.getHardwareConcurrency()); +console.log('Platform config:', adapter.getPlatformConfig()); +``` diff --git a/docs/src/content/docs/en/guide/platform-adapter/nodejs.md b/docs/src/content/docs/en/guide/platform-adapter/nodejs.md new file mode 100644 index 00000000..476ddb8c --- /dev/null +++ b/docs/src/content/docs/en/guide/platform-adapter/nodejs.md @@ -0,0 +1,560 @@ +--- +title: "Node.js Adapter" +--- + +## Overview + +The Node.js platform adapter provides support for Node.js server environments, suitable for game servers, compute servers, or other server applications that need ECS architecture. + +## Feature Support + +- **Worker**: Supported (via `worker_threads` module) +- **SharedArrayBuffer**: Supported (Node.js 16.17.0+) +- **Transferable Objects**: Fully supported +- **High-Resolution Time**: Uses `process.hrtime.bigint()` +- **Device Info**: Complete system and process information + +## Complete Implementation + +```typescript +import { worker_threads, Worker, isMainThread, parentPort } from 'worker_threads'; +import * as os from 'os'; +import * as process from 'process'; +import * as fs from 'fs'; +import * as path from 'path'; +import type { + IPlatformAdapter, + PlatformWorker, + WorkerCreationOptions, + PlatformConfig, + NodeDeviceInfo +} from '@esengine/ecs-framework'; + +/** + * Node.js platform adapter + * Supports Node.js server environments + */ +export class NodeAdapter implements IPlatformAdapter { + public readonly name = 'nodejs'; + public readonly version: string; + + constructor() { + this.version = process.version; + } + + /** + * Check if Worker is supported + */ + public isWorkerSupported(): boolean { + try { + // Check if worker_threads module is available + return typeof worker_threads !== 'undefined' && typeof Worker !== 'undefined'; + } catch { + return false; + } + } + + /** + * Check if SharedArrayBuffer is supported + */ + public isSharedArrayBufferSupported(): boolean { + // Node.js supports SharedArrayBuffer + return typeof SharedArrayBuffer !== 'undefined'; + } + + /** + * Get hardware concurrency (CPU core count) + */ + public getHardwareConcurrency(): number { + return os.cpus().length; + } + + /** + * Create Worker + */ + public createWorker(script: string, options: WorkerCreationOptions = {}): PlatformWorker { + if (!this.isWorkerSupported()) { + throw new Error('Node.js environment does not support Worker Threads'); + } + + try { + return new NodeWorker(script, options); + } catch (error) { + throw new Error(`Failed to create Node.js Worker: ${(error as Error).message}`); + } + } + + /** + * Create SharedArrayBuffer + */ + public createSharedArrayBuffer(length: number): SharedArrayBuffer | null { + if (!this.isSharedArrayBufferSupported()) { + return null; + } + + try { + return new SharedArrayBuffer(length); + } catch (error) { + console.warn('SharedArrayBuffer creation failed:', error); + return null; + } + } + + /** + * Get high-resolution timestamp (nanoseconds) + */ + public getHighResTimestamp(): number { + // Return milliseconds, consistent with browser performance.now() + return Number(process.hrtime.bigint()) / 1000000; + } + + /** + * Get platform configuration + */ + public getPlatformConfig(): PlatformConfig { + return { + maxWorkerCount: this.getHardwareConcurrency(), + supportsModuleWorker: true, // Node.js supports ES modules + supportsTransferableObjects: true, + maxSharedArrayBufferSize: this.getMaxSharedArrayBufferSize(), + workerScriptPrefix: '', + limitations: { + noEval: false, // Node.js supports eval + requiresWorkerInit: false + }, + extensions: { + platform: 'nodejs', + nodeVersion: process.version, + v8Version: process.versions.v8, + uvVersion: process.versions.uv, + zlibVersion: process.versions.zlib, + opensslVersion: process.versions.openssl, + architecture: process.arch, + endianness: os.endianness(), + pid: process.pid, + ppid: process.ppid + } + }; + } + + /** + * Get Node.js device information + */ + public getDeviceInfo(): NodeDeviceInfo { + const cpus = os.cpus(); + const networkInterfaces = os.networkInterfaces(); + const userInfo = os.userInfo(); + + return { + // System info + platform: os.platform(), + arch: os.arch(), + type: os.type(), + release: os.release(), + version: os.version(), + hostname: os.hostname(), + + // CPU info + cpus: cpus.map(cpu => ({ + model: cpu.model, + speed: cpu.speed, + times: cpu.times + })), + + // Memory info + totalMemory: os.totalmem(), + freeMemory: os.freemem(), + usedMemory: os.totalmem() - os.freemem(), + + // Load info + loadAverage: os.loadavg(), + + // Network interfaces + networkInterfaces: Object.fromEntries( + Object.entries(networkInterfaces).map(([name, interfaces]) => [ + name, + (interfaces || []).map(iface => ({ + address: iface.address, + netmask: iface.netmask, + family: iface.family as 'IPv4' | 'IPv6', + mac: iface.mac, + internal: iface.internal, + cidr: iface.cidr, + scopeid: iface.scopeid + })) + ]) + ), + + // Process info + process: { + pid: process.pid, + ppid: process.ppid, + version: process.version, + versions: process.versions, + uptime: process.uptime() + }, + + // User info + userInfo: { + uid: userInfo.uid, + gid: userInfo.gid, + username: userInfo.username, + homedir: userInfo.homedir, + shell: userInfo.shell + } + }; + } + + /** + * Get SharedArrayBuffer maximum size limit + */ + private getMaxSharedArrayBufferSize(): number { + const totalMemory = os.totalmem(); + // Limit to 50% of total system memory + return Math.floor(totalMemory * 0.5); + } +} + +/** + * Node.js Worker wrapper + */ +class NodeWorker implements PlatformWorker { + private _state: 'running' | 'terminated' = 'running'; + private worker: Worker; + private isTemporaryFile: boolean = false; + private scriptPath: string; + + constructor(script: string, options: WorkerCreationOptions = {}) { + try { + // Determine if script is a file path or script content + if (this.isFilePath(script)) { + // Use file path directly + this.scriptPath = script; + this.isTemporaryFile = false; + } else { + // Write script content to temporary file + this.scriptPath = this.writeScriptToFile(script, options.name); + this.isTemporaryFile = true; + } + + // Create Worker + this.worker = new Worker(this.scriptPath, { + // Node.js Worker options + workerData: options.name ? { name: options.name } : undefined + }); + + } catch (error) { + throw new Error(`Failed to create Node.js Worker: ${(error as Error).message}`); + } + } + + /** + * Determine if string is a file path + */ + private isFilePath(script: string): boolean { + // Check if it looks like a file path + return (script.endsWith('.js') || script.endsWith('.mjs') || script.endsWith('.ts')) && + !script.includes('\n') && + !script.includes(';') && + script.length < 500; // File paths are typically not too long + } + + /** + * Write script content to temporary file + */ + private writeScriptToFile(script: string, name?: string): string { + const tmpDir = os.tmpdir(); + const fileName = name ? `worker-${name}-${Date.now()}.js` : `worker-${Date.now()}.js`; + const filePath = path.join(tmpDir, fileName); + + try { + fs.writeFileSync(filePath, script, 'utf8'); + return filePath; + } catch (error) { + throw new Error(`Failed to write Worker script file: ${(error as Error).message}`); + } + } + + public get state(): 'running' | 'terminated' { + return this._state; + } + + public postMessage(message: any, transfer?: Transferable[]): void { + if (this._state === 'terminated') { + throw new Error('Worker has been terminated'); + } + + try { + if (transfer && transfer.length > 0) { + // Node.js Worker supports Transferable Objects + this.worker.postMessage(message, transfer); + } else { + this.worker.postMessage(message); + } + } catch (error) { + throw new Error(`Failed to send message to Node.js Worker: ${(error as Error).message}`); + } + } + + public onMessage(handler: (event: { data: any }) => void): void { + this.worker.on('message', (data: any) => { + handler({ data }); + }); + } + + public onError(handler: (error: ErrorEvent) => void): void { + this.worker.on('error', (error: Error) => { + // Convert Error to ErrorEvent format + const errorEvent = { + message: error.message, + filename: '', + lineno: 0, + colno: 0, + error: error + } as ErrorEvent; + handler(errorEvent); + }); + } + + public terminate(): void { + if (this._state === 'running') { + try { + this.worker.terminate(); + this._state = 'terminated'; + + // Clean up temporary script file + this.cleanupScriptFile(); + } catch (error) { + console.error('Failed to terminate Node.js Worker:', error); + } + } + } + + /** + * Clean up temporary script file + */ + private cleanupScriptFile(): void { + // Only clean up temporarily created files, not user-provided file paths + if (this.scriptPath && this.isTemporaryFile) { + try { + fs.unlinkSync(this.scriptPath); + } catch (error) { + console.warn('Failed to clean up Worker script file:', error); + } + } + } +} +``` + +## Usage + +### 1. Copy the Code + +Copy the above code to your project, e.g., `src/platform/NodeAdapter.ts`. + +### 2. Register the Adapter + +```typescript +import { PlatformManager } from '@esengine/ecs-framework'; +import { NodeAdapter } from './platform/NodeAdapter'; + +// Check if in Node.js environment +if (typeof process !== 'undefined' && process.versions && process.versions.node) { + const nodeAdapter = new NodeAdapter(); + PlatformManager.getInstance().registerAdapter(nodeAdapter); +} +``` + +### 3. Use WorkerEntitySystem + +The Node.js adapter works with WorkerEntitySystem, and the framework automatically handles Worker script creation: + +```typescript +import { WorkerEntitySystem, Matcher } from '@esengine/ecs-framework'; +import * as os from 'os'; + +class PhysicsSystem extends WorkerEntitySystem { + constructor() { + super(Matcher.all(Transform, Velocity), { + enableWorker: true, + workerCount: os.cpus().length, // Use all CPU cores + useSharedArrayBuffer: true, + systemConfig: { gravity: 9.8 } + }); + } + + protected getDefaultEntityDataSize(): number { + return 6; // x, y, vx, vy, mass, radius + } + + protected extractEntityData(entity: Entity): PhysicsData { + const transform = entity.getComponent(Transform); + const velocity = entity.getComponent(Velocity); + return { + x: transform.x, + y: transform.y, + vx: velocity.x, + vy: velocity.y, + mass: 1, + radius: 10 + }; + } + + // This function is automatically serialized and executed in Worker + protected workerProcess(entities, deltaTime, config) { + return entities.map(entity => { + // Apply gravity + entity.vy += config.gravity * deltaTime; + + // Update position + entity.x += entity.vx * deltaTime; + entity.y += entity.vy * deltaTime; + + return entity; + }); + } + + protected applyResult(entity: Entity, result: PhysicsData): void { + const transform = entity.getComponent(Transform); + const velocity = entity.getComponent(Velocity); + + transform.x = result.x; + transform.y = result.y; + velocity.x = result.vx; + velocity.y = result.vy; + } +} + +interface PhysicsData { + x: number; + y: number; + vx: number; + vy: number; + mass: number; + radius: number; +} +``` + +### 4. Get System Information + +```typescript +const manager = PlatformManager.getInstance(); +if (manager.hasAdapter()) { + const adapter = manager.getAdapter(); + const deviceInfo = adapter.getDeviceInfo(); + + console.log('Node.js version:', deviceInfo.process?.version); + console.log('CPU core count:', deviceInfo.cpus?.length); + console.log('Total memory:', Math.round(deviceInfo.totalMemory! / 1024 / 1024), 'MB'); + console.log('Available memory:', Math.round(deviceInfo.freeMemory! / 1024 / 1024), 'MB'); +} +``` + +## Official Documentation Reference + +Node.js Worker Threads related official documentation: + +- [Worker Threads Official Docs](https://nodejs.org/api/worker_threads.html) +- [SharedArrayBuffer Support](https://nodejs.org/api/globals.html#class-sharedarraybuffer) +- [OS Module Docs](https://nodejs.org/api/os.html) +- [Process Module Docs](https://nodejs.org/api/process.html) + +## Important Notes + +### Worker Threads Requirements + +- **Node.js Version**: Requires Node.js 10.5.0+ (12+ recommended) +- **Module Type**: Supports both CommonJS and ES modules +- **Thread Limit**: Theoretically unlimited, but recommended not to exceed 2x CPU core count + +### Performance Optimization Tips + +#### 1. Worker Pool Management + +```typescript +class ServerPhysicsSystem extends WorkerEntitySystem { + constructor() { + const cpuCount = os.cpus().length; + super(Matcher.all(Transform, Velocity), { + enableWorker: true, + workerCount: Math.min(cpuCount * 2, 16), // Max 16 Workers + entitiesPerWorker: 1000, // 1000 entities per Worker + useSharedArrayBuffer: true, + systemConfig: { + gravity: 9.8, + timeStep: 1/60 + } + }); + } +} +``` + +#### 2. Memory Management + +```typescript +class MemoryMonitor { + public static checkMemoryUsage(): void { + const used = process.memoryUsage(); + + console.log('Memory usage:'); + console.log(` RSS: ${Math.round(used.rss / 1024 / 1024)} MB`); + console.log(` Heap Used: ${Math.round(used.heapUsed / 1024 / 1024)} MB`); + console.log(` Heap Total: ${Math.round(used.heapTotal / 1024 / 1024)} MB`); + console.log(` External: ${Math.round(used.external / 1024 / 1024)} MB`); + + // Trigger warning when memory usage is too high + if (used.heapUsed > used.heapTotal * 0.9) { + console.warn('Memory usage too high, consider optimizing or restarting'); + } + } +} + +// Check memory usage periodically +setInterval(() => { + MemoryMonitor.checkMemoryUsage(); +}, 30000); // Check every 30 seconds +``` + +#### 3. Server Environment Optimization + +```typescript +// Set process title +process.title = 'ecs-game-server'; + +// Handle uncaught exceptions +process.on('uncaughtException', (error) => { + console.error('Uncaught exception:', error); + process.exit(1); +}); + +process.on('unhandledRejection', (reason, promise) => { + console.error('Unhandled Promise rejection:', reason); +}); + +// Graceful shutdown +process.on('SIGTERM', () => { + console.log('Received SIGTERM signal, shutting down server...'); + // Clean up resources + process.exit(0); +}); +``` + +## Debugging Tips + +```typescript +// Check Node.js environment support +const adapter = new NodeAdapter(); +console.log('Node.js version:', adapter.version); +console.log('Worker support:', adapter.isWorkerSupported()); +console.log('SharedArrayBuffer support:', adapter.isSharedArrayBufferSupported()); +console.log('CPU core count:', adapter.getHardwareConcurrency()); + +// Get detailed configuration +const config = adapter.getPlatformConfig(); +console.log('Platform config:', JSON.stringify(config, null, 2)); + +// System resource monitoring +const deviceInfo = adapter.getDeviceInfo(); +console.log('System load:', deviceInfo.loadAverage); +console.log('Network interfaces:', Object.keys(deviceInfo.networkInterfaces!)); +``` diff --git a/docs/src/content/docs/en/guide/platform-adapter/wechat-minigame.md b/docs/src/content/docs/en/guide/platform-adapter/wechat-minigame.md new file mode 100644 index 00000000..39524696 --- /dev/null +++ b/docs/src/content/docs/en/guide/platform-adapter/wechat-minigame.md @@ -0,0 +1,485 @@ +--- +title: "WeChat Mini Game Adapter" +--- + +## Overview + +The WeChat Mini Game platform adapter is designed specifically for the WeChat Mini Game environment, handling special restrictions and APIs. + +## Feature Support + +| Feature | Support | Notes | +|---------|---------|-------| +| **Worker** | Supported | Requires precompiled file, configure `workerScriptPath` | +| **SharedArrayBuffer** | Not Supported | WeChat Mini Game environment doesn't support this | +| **Transferable Objects** | Not Supported | Only serializable objects supported | +| **High-Resolution Time** | Supported | Uses `wx.getPerformance()` | +| **Device Info** | Supported | Complete WeChat Mini Game device info | + +## WorkerEntitySystem Usage + +### Important: WeChat Mini Game Worker Restrictions + +WeChat Mini Game Workers have the following restrictions: +- **Worker scripts must be in the code package**, cannot be dynamically generated +- **Must be configured in `game.json`** with `workers` directory +- **Maximum of 1 Worker** can be created + +Therefore, when using `WorkerEntitySystem`, there are two approaches: +1. **Recommended: Use CLI tool** to automatically generate Worker files +2. Manually create Worker files + +### Method 1: Use CLI Tool for Auto-Generation (Recommended) + +We provide the `@esengine/worker-generator` tool that can automatically extract `workerProcess` functions from your TypeScript code and generate WeChat Mini Game compatible Worker files. + +#### Installation + +```bash +pnpm add -D @esengine/worker-generator +# or +npm install --save-dev @esengine/worker-generator +``` + +#### Usage + +```bash +# Scan src directory, generate Worker files to workers directory +npx esengine-worker-gen --src ./src --out ./workers --wechat + +# View help +npx esengine-worker-gen --help +``` + +#### Parameter Reference + +| Parameter | Description | Default | +|-----------|-------------|---------| +| `-s, --src

` | Source code directory | `./src` | +| `-o, --out ` | Output directory | `./workers` | +| `-w, --wechat` | Generate WeChat Mini Game compatible code | `false` | +| `-m, --mapping` | Generate worker-mapping.json | `true` | +| `-t, --tsconfig ` | TypeScript config file path | Auto-detect | +| `-v, --verbose` | Verbose output | `false` | + +#### Example Output + +``` +ESEngine Worker Generator + +Source directory: /project/src +Output directory: /project/workers +WeChat mode: Yes + +Scanning for WorkerEntitySystem classes... + +Found 1 WorkerEntitySystem class(es): + - PhysicsSystem (src/systems/PhysicsSystem.ts) + +Generating Worker files... + +Successfully generated 1 Worker file(s): + - PhysicsSystem -> workers/physics-system-worker.js + +Usage: +1. Copy the generated files to your project's workers/ directory +2. Configure game.json (WeChat): { "workers": "workers" } +3. In your System constructor, add: + workerScriptPath: 'workers/physics-system-worker.js' +``` + +#### Integration in Build Process + +```json +// package.json +{ + "scripts": { + "build:workers": "esengine-worker-gen --src ./src --out ./workers --wechat", + "build": "pnpm build:workers && your-build-command" + } +} +``` + +### Method 2: Manually Create Worker Files + +If you don't want to use the CLI tool, you can manually create Worker files. + +Create `workers/entity-worker.js` in your project: + +```javascript +// workers/entity-worker.js +// WeChat Mini Game WorkerEntitySystem Generic Worker Template + +let sharedFloatArray = null; + +worker.onMessage(function(e) { + const { type, id, entities, deltaTime, systemConfig, startIndex, endIndex, sharedBuffer } = e.data; + + try { + // Handle SharedArrayBuffer initialization + if (type === 'init' && sharedBuffer) { + sharedFloatArray = new Float32Array(sharedBuffer); + worker.postMessage({ type: 'init', success: true }); + return; + } + + // Handle SharedArrayBuffer data + if (type === 'shared' && sharedFloatArray) { + processSharedArrayBuffer(startIndex, endIndex, deltaTime, systemConfig); + worker.postMessage({ id, result: null }); + return; + } + + // Traditional processing method + if (entities) { + const result = workerProcess(entities, deltaTime, systemConfig); + + // Handle Promise return value + if (result && typeof result.then === 'function') { + result.then(function(finalResult) { + worker.postMessage({ id, result: finalResult }); + }).catch(function(error) { + worker.postMessage({ id, error: error.message }); + }); + } else { + worker.postMessage({ id, result: result }); + } + } + } catch (error) { + worker.postMessage({ id, error: error.message }); + } +}); + +/** + * Entity processing function - Modify this function based on your business logic + * @param {Array} entities - Entity data array + * @param {number} deltaTime - Frame interval time + * @param {Object} systemConfig - System configuration + * @returns {Array} Processed entity data + */ +function workerProcess(entities, deltaTime, systemConfig) { + // ====== Write your processing logic here ====== + // Example: Physics calculation + return entities.map(function(entity) { + // Apply gravity + entity.vy += (systemConfig.gravity || 100) * deltaTime; + + // Update position + entity.x += entity.vx * deltaTime; + entity.y += entity.vy * deltaTime; + + // Apply friction + entity.vx *= (systemConfig.friction || 0.95); + entity.vy *= (systemConfig.friction || 0.95); + + return entity; + }); +} + +/** + * SharedArrayBuffer processing function (optional) + */ +function processSharedArrayBuffer(startIndex, endIndex, deltaTime, systemConfig) { + if (!sharedFloatArray) return; + + // ====== Implement SharedArrayBuffer processing logic as needed ====== + // Note: WeChat Mini Game doesn't support SharedArrayBuffer, this function typically won't be called +} +``` + +### Step 2: Configure game.json + +Add workers configuration in `game.json`: + +```json +{ + "deviceOrientation": "portrait", + "showStatusBar": false, + "workers": "workers" +} +``` + +### Step 3: Use WorkerEntitySystem + +```typescript +import { WorkerEntitySystem, Matcher, Entity } from '@esengine/ecs-framework'; + +interface PhysicsData { + id: number; + x: number; + y: number; + vx: number; + vy: number; + mass: number; +} + +class PhysicsSystem extends WorkerEntitySystem { + constructor() { + super(Matcher.all(Transform, Velocity), { + enableWorker: true, + workerCount: 1, // WeChat Mini Game limits to 1 Worker + workerScriptPath: 'workers/entity-worker.js', // Specify precompiled Worker file + systemConfig: { + gravity: 100, + friction: 0.95 + } + }); + } + + protected getDefaultEntityDataSize(): number { + return 6; + } + + protected extractEntityData(entity: Entity): PhysicsData { + const transform = entity.getComponent(Transform); + const velocity = entity.getComponent(Velocity); + const physics = entity.getComponent(Physics); + + return { + id: entity.id, + x: transform.x, + y: transform.y, + vx: velocity.x, + vy: velocity.y, + mass: physics.mass + }; + } + + // Note: In WeChat Mini Game, this method won't be used + // Worker processing logic is in workers/entity-worker.js workerProcess function + protected workerProcess(entities: PhysicsData[], deltaTime: number, config: any): PhysicsData[] { + return entities.map(entity => { + entity.vy += config.gravity * deltaTime; + entity.x += entity.vx * deltaTime; + entity.y += entity.vy * deltaTime; + entity.vx *= config.friction; + entity.vy *= config.friction; + return entity; + }); + } + + protected applyResult(entity: Entity, result: PhysicsData): void { + const transform = entity.getComponent(Transform); + const velocity = entity.getComponent(Velocity); + + transform.x = result.x; + transform.y = result.y; + velocity.x = result.vx; + velocity.y = result.vy; + } + + // SharedArrayBuffer related methods (not supported in WeChat Mini Game, can be omitted) + protected writeEntityToBuffer(data: PhysicsData, offset: number): void {} + protected readEntityFromBuffer(offset: number): PhysicsData | null { return null; } +} +``` + +### Temporarily Disable Worker (Fallback to Sync Mode) + +If you encounter issues, you can temporarily disable Worker: + +```typescript +class PhysicsSystem extends WorkerEntitySystem { + constructor() { + super(Matcher.all(Transform, Velocity), { + enableWorker: false, // Disable Worker, use main thread synchronous processing + // ... other config + }); + } +} +``` + +## Complete Adapter Implementation + +```typescript +import type { + IPlatformAdapter, + PlatformWorker, + WorkerCreationOptions, + PlatformConfig +} from '@esengine/ecs-framework'; + +/** + * WeChat Mini Game platform adapter + */ +export class WeChatMiniGameAdapter implements IPlatformAdapter { + public readonly name = 'wechat-minigame'; + public readonly version: string; + private systemInfo: any; + + constructor() { + this.systemInfo = this.getSystemInfo(); + this.version = this.systemInfo.SDKVersion || 'unknown'; + } + + public isWorkerSupported(): boolean { + return typeof wx !== 'undefined' && typeof wx.createWorker === 'function'; + } + + public isSharedArrayBufferSupported(): boolean { + return false; + } + + public getHardwareConcurrency(): number { + return 1; // WeChat Mini Game max 1 Worker + } + + public createWorker(scriptPath: string, options: WorkerCreationOptions = {}): PlatformWorker { + if (!this.isWorkerSupported()) { + throw new Error('WeChat Mini Game environment does not support Worker'); + } + + // scriptPath must be a file path in the code package + const worker = wx.createWorker(scriptPath, { + useExperimentalWorker: true + }); + + return new WeChatWorker(worker); + } + + public createSharedArrayBuffer(length: number): SharedArrayBuffer | null { + return null; + } + + public getHighResTimestamp(): number { + if (typeof wx !== 'undefined' && wx.getPerformance) { + return wx.getPerformance().now(); + } + return Date.now(); + } + + public getPlatformConfig(): PlatformConfig { + return { + maxWorkerCount: 1, + supportsModuleWorker: false, + supportsTransferableObjects: false, + maxSharedArrayBufferSize: 0, + workerScriptPrefix: '', + limitations: { + noEval: true, // Important: Mark that dynamic scripts not supported + requiresWorkerInit: false, + memoryLimit: 512 * 1024 * 1024, + workerNotSupported: false, + workerLimitations: [ + 'Maximum of 1 Worker can be created', + 'Worker scripts must be in the code package', + 'workers path must be configured in game.json', + 'workerScriptPath configuration required' + ] + }, + extensions: { + platform: 'wechat-minigame', + sdkVersion: this.systemInfo.SDKVersion + } + }; + } + + private getSystemInfo(): any { + if (typeof wx !== 'undefined' && wx.getSystemInfoSync) { + try { + return wx.getSystemInfoSync(); + } catch (error) { + console.warn('Failed to get WeChat system info:', error); + } + } + return {}; + } +} + +/** + * WeChat Worker wrapper + */ +class WeChatWorker implements PlatformWorker { + private _state: 'running' | 'terminated' = 'running'; + private worker: any; + + constructor(worker: any) { + this.worker = worker; + } + + public get state(): 'running' | 'terminated' { + return this._state; + } + + public postMessage(message: any, transfer?: Transferable[]): void { + if (this._state === 'terminated') { + throw new Error('Worker has been terminated'); + } + this.worker.postMessage(message); + } + + public onMessage(handler: (event: { data: any }) => void): void { + this.worker.onMessage((res: any) => { + handler({ data: res }); + }); + } + + public onError(handler: (error: ErrorEvent) => void): void { + if (this.worker.onError) { + this.worker.onError(handler); + } + } + + public terminate(): void { + if (this._state === 'running') { + this.worker.terminate(); + this._state = 'terminated'; + } + } +} +``` + +## Register the Adapter + +```typescript +import { PlatformManager } from '@esengine/ecs-framework'; +import { WeChatMiniGameAdapter } from './platform/WeChatMiniGameAdapter'; + +// Register adapter at game startup +if (typeof wx !== 'undefined') { + const adapter = new WeChatMiniGameAdapter(); + PlatformManager.getInstance().registerAdapter(adapter); +} +``` + +## Official Documentation Reference + +- [wx.createWorker API](https://developers.weixin.qq.com/minigame/dev/api/worker/wx.createWorker.html) +- [Worker.postMessage API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.postMessage.html) +- [Worker.onMessage API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.onMessage.html) + +## Important Notes + +### Worker Restrictions + +| Restriction | Description | +|-------------|-------------| +| Quantity Limit | Maximum of 1 Worker can be created | +| Version Requirement | Requires base library 1.9.90 or above | +| Script Location | Must be in code package, dynamic generation not supported | +| Lifecycle | Must terminate() before creating new Worker | + +### Memory Limits + +- Typically limited to 256MB - 512MB +- Need to release unused resources promptly +- Recommend listening for memory warnings: + +```typescript +wx.onMemoryWarning(() => { + console.warn('Received memory warning, starting resource cleanup'); + // Clean up unnecessary resources +}); +``` + +## Debugging Tips + +```typescript +// Check Worker configuration +const adapter = PlatformManager.getInstance().getAdapter(); +const config = adapter.getPlatformConfig(); + +console.log('Worker support:', adapter.isWorkerSupported()); +console.log('Max Worker count:', config.maxWorkerCount); +console.log('Platform limitations:', config.limitations); +``` diff --git a/docs/src/content/docs/en/guide/plugin-system.md b/docs/src/content/docs/en/guide/plugin-system.md new file mode 100644 index 00000000..aad0eccc --- /dev/null +++ b/docs/src/content/docs/en/guide/plugin-system.md @@ -0,0 +1,645 @@ +--- +title: "Plugin System" +--- + +The plugin system allows you to extend ECS Framework functionality in a modular way. Through plugins, you can encapsulate specific features (such as network synchronization, physics engines, debugging tools, etc.) and reuse them across multiple projects. + +## Overview + +### What is a Plugin + +A plugin is a class that implements the `IPlugin` interface and can be dynamically installed into the framework at runtime. Plugins can: + +- Register custom services to the service container +- Add systems to scenes +- Register custom components +- Extend framework functionality + +### Advantages of Plugins + +- **Modular**: Encapsulate functionality as independent modules, improving code maintainability +- **Reusable**: Same plugin can be used across multiple projects +- **Decoupled**: Core framework separated from extended functionality +- **Hot-swappable**: Dynamically install and uninstall plugins at runtime + +## Quick Start + +### Creating Your First Plugin + +Create a simple debug plugin: + +```typescript +import { IPlugin, Core, ServiceContainer } from '@esengine/ecs-framework'; + +class DebugPlugin implements IPlugin { + readonly name = 'debug-plugin'; + readonly version = '1.0.0'; + + install(core: Core, services: ServiceContainer): void { + console.log('Debug plugin installed'); + + // Can register services, add systems, etc. here + } + + uninstall(): void { + console.log('Debug plugin uninstalled'); + // Clean up resources + } +} +``` + +### Installing a Plugin + +Use `Core.installPlugin()` to install a plugin: + +```typescript +import { Core } from '@esengine/ecs-framework'; + +// Initialize Core +Core.create({ debug: true }); + +// Install plugin +await Core.installPlugin(new DebugPlugin()); + +// Check if plugin is installed +if (Core.isPluginInstalled('debug-plugin')) { + console.log('Debug plugin is running'); +} +``` + +### Uninstalling a Plugin + +```typescript +// Uninstall plugin +await Core.uninstallPlugin('debug-plugin'); +``` + +### Getting Plugin Instance + +```typescript +// Get installed plugin +const plugin = Core.getPlugin('debug-plugin'); +if (plugin) { + console.log(`Plugin version: ${plugin.version}`); +} +``` + +## Plugin Development + +### IPlugin Interface + +All plugins must implement the `IPlugin` interface: + +```typescript +export interface IPlugin { + // Unique plugin name + readonly name: string; + + // Plugin version (semver recommended) + readonly version: string; + + // Dependencies on other plugins (optional) + readonly dependencies?: readonly string[]; + + // Called when plugin is installed + install(core: Core, services: ServiceContainer): void | Promise; + + // Called when plugin is uninstalled + uninstall(): void | Promise; +} +``` + +### Plugin Lifecycle + +#### install Method + +Called when the plugin is installed, used to initialize the plugin: + +```typescript +class MyPlugin implements IPlugin { + readonly name = 'my-plugin'; + readonly version = '1.0.0'; + + install(core: Core, services: ServiceContainer): void { + // 1. Register services + services.registerSingleton(MyService); + + // 2. Access current scene + const scene = core.scene; + if (scene) { + // 3. Add systems + scene.addSystem(new MySystem()); + } + + // 4. Other initialization logic + console.log('Plugin initialized'); + } + + uninstall(): void { + // Cleanup logic + } +} +``` + +#### uninstall Method + +Called when the plugin is uninstalled, used to clean up resources: + +```typescript +class MyPlugin implements IPlugin { + readonly name = 'my-plugin'; + readonly version = '1.0.0'; + private myService?: MyService; + + install(core: Core, services: ServiceContainer): void { + this.myService = new MyService(); + services.registerInstance(MyService, this.myService); + } + + uninstall(): void { + // Clean up service + if (this.myService) { + this.myService.dispose(); + this.myService = undefined; + } + + // Remove event listeners + // Release other resources + } +} +``` + +### Async Plugins + +Plugin `install` and `uninstall` methods both support async: + +```typescript +class AsyncPlugin implements IPlugin { + readonly name = 'async-plugin'; + readonly version = '1.0.0'; + + async install(core: Core, services: ServiceContainer): Promise { + // Async resource loading + const config = await fetch('/plugin-config.json').then(r => r.json()); + + // Initialize service with loaded config + const service = new MyService(config); + services.registerInstance(MyService, service); + } + + async uninstall(): Promise { + // Async cleanup + await this.saveState(); + } + + private async saveState() { + // Save plugin state + } +} + +// Usage +await Core.installPlugin(new AsyncPlugin()); +``` + +### Registering Services + +Plugins can register their own services to the service container: + +```typescript +import { IService } from '@esengine/ecs-framework'; + +class NetworkService implements IService { + connect(url: string) { + console.log(`Connecting to ${url}`); + } + + dispose(): void { + console.log('Network service disposed'); + } +} + +class NetworkPlugin implements IPlugin { + readonly name = 'network-plugin'; + readonly version = '1.0.0'; + + install(core: Core, services: ServiceContainer): void { + // Register network service + services.registerSingleton(NetworkService); + + // Resolve and use service + const network = services.resolve(NetworkService); + network.connect('ws://localhost:8080'); + } + + uninstall(): void { + // Service container automatically calls service's dispose method + } +} +``` + +### Adding Systems + +Plugins can add custom systems to scenes: + +```typescript +import { EntitySystem, Matcher } from '@esengine/ecs-framework'; + +class PhysicsSystem extends EntitySystem { + constructor() { + super(Matcher.empty().all(PhysicsBody)); + } + + protected process(entities: readonly Entity[]): void { + // Physics simulation logic + } +} + +class PhysicsPlugin implements IPlugin { + readonly name = 'physics-plugin'; + readonly version = '1.0.0'; + private physicsSystem?: PhysicsSystem; + + install(core: Core, services: ServiceContainer): void { + const scene = core.scene; + if (scene) { + this.physicsSystem = new PhysicsSystem(); + scene.addSystem(this.physicsSystem); + } + } + + uninstall(): void { + // Remove system + if (this.physicsSystem) { + const scene = Core.scene; + if (scene) { + scene.removeSystem(this.physicsSystem); + } + this.physicsSystem = undefined; + } + } +} +``` + +## Dependency Management + +### Declaring Dependencies + +Plugins can declare dependencies on other plugins: + +```typescript +class AdvancedPhysicsPlugin implements IPlugin { + readonly name = 'advanced-physics'; + readonly version = '2.0.0'; + + // Declare dependency on base physics plugin + readonly dependencies = ['physics-plugin'] as const; + + install(core: Core, services: ServiceContainer): void { + // Can safely use services provided by physics-plugin + const physicsService = services.resolve(PhysicsService); + // ... + } + + uninstall(): void { + // Cleanup + } +} +``` + +### Dependency Checking + +The framework automatically checks dependency relationships and throws errors if dependencies are unmet: + +```typescript +// Error: physics-plugin not installed +try { + await Core.installPlugin(new AdvancedPhysicsPlugin()); +} catch (error) { + console.error(error); // Plugin advanced-physics has unmet dependencies: physics-plugin +} + +// Correct: Install dependency first +await Core.installPlugin(new PhysicsPlugin()); +await Core.installPlugin(new AdvancedPhysicsPlugin()); +``` + +### Uninstall Order + +The framework checks dependency relationships, preventing uninstallation of plugins that other plugins depend on: + +```typescript +await Core.installPlugin(new PhysicsPlugin()); +await Core.installPlugin(new AdvancedPhysicsPlugin()); + +// Error: physics-plugin is required by advanced-physics +try { + await Core.uninstallPlugin('physics-plugin'); +} catch (error) { + console.error(error); // Cannot uninstall plugin physics-plugin: it is required by advanced-physics +} + +// Correct: Uninstall dependent plugin first +await Core.uninstallPlugin('advanced-physics'); +await Core.uninstallPlugin('physics-plugin'); +``` + +## Plugin Management + +### Managing via Core + +The Core class provides convenient plugin management methods: + +```typescript +// Install plugin +await Core.installPlugin(myPlugin); + +// Uninstall plugin +await Core.uninstallPlugin('plugin-name'); + +// Check if plugin is installed +if (Core.isPluginInstalled('plugin-name')) { + // ... +} + +// Get plugin instance +const plugin = Core.getPlugin('plugin-name'); +``` + +### Managing via PluginManager + +You can also use the PluginManager service directly: + +```typescript +const pluginManager = Core.services.resolve(PluginManager); + +// Get all plugins +const allPlugins = pluginManager.getAllPlugins(); +console.log(`Total plugins: ${allPlugins.length}`); + +// Get plugin metadata +const metadata = pluginManager.getMetadata('my-plugin'); +if (metadata) { + console.log(`State: ${metadata.state}`); + console.log(`Installed at: ${new Date(metadata.installedAt!)}`); +} + +// Get all plugin metadata +const allMetadata = pluginManager.getAllMetadata(); +for (const meta of allMetadata) { + console.log(`${meta.name} v${meta.version} - ${meta.state}`); +} +``` + +## Practical Plugin Examples + +### Network Sync Plugin + +```typescript +import { IPlugin, IService, Core, ServiceContainer } from '@esengine/ecs-framework'; + +class NetworkSyncService implements IService { + private ws?: WebSocket; + + connect(url: string) { + this.ws = new WebSocket(url); + this.ws.onmessage = (event) => { + const data = JSON.parse(event.data); + this.handleMessage(data); + }; + } + + private handleMessage(data: any) { + // Handle network messages + } + + dispose(): void { + if (this.ws) { + this.ws.close(); + this.ws = undefined; + } + } +} + +class NetworkSyncPlugin implements IPlugin { + readonly name = 'network-sync'; + readonly version = '1.0.0'; + + install(core: Core, services: ServiceContainer): void { + // Register network service + services.registerSingleton(NetworkSyncService); + + // Auto connect + const network = services.resolve(NetworkSyncService); + network.connect('ws://localhost:8080'); + } + + uninstall(): void { + // Service will auto dispose + } +} +``` + +### Performance Analysis Plugin + +```typescript +class PerformanceAnalysisPlugin implements IPlugin { + readonly name = 'performance-analysis'; + readonly version = '1.0.0'; + private frameCount = 0; + private totalTime = 0; + + install(core: Core, services: ServiceContainer): void { + const monitor = services.resolve(PerformanceMonitor); + monitor.enable(); + + // Periodically output performance report + const timer = services.resolve(TimerManager); + timer.schedule(5.0, true, null, () => { + this.printReport(monitor); + }); + } + + uninstall(): void { + // Cleanup + } + + private printReport(monitor: PerformanceMonitor) { + console.log('=== Performance Report ==='); + console.log(`FPS: ${monitor.getFPS()}`); + console.log(`Memory: ${monitor.getMemoryUsage()} MB`); + } +} +``` + +## Best Practices + +### Naming Convention + +- Plugin names use lowercase letters and hyphens: `my-awesome-plugin` +- Version numbers follow semantic versioning: `1.0.0` + +```typescript +class MyPlugin implements IPlugin { + readonly name = 'my-awesome-plugin'; // Good + readonly version = '1.0.0'; // Good +} +``` + +### Resource Cleanup + +Always clean up all resources created by the plugin in `uninstall`: + +```typescript +class MyPlugin implements IPlugin { + readonly name = 'my-plugin'; + readonly version = '1.0.0'; + private timerId?: number; + private listener?: () => void; + + install(core: Core, services: ServiceContainer): void { + // Add timer + this.timerId = setInterval(() => { + // ... + }, 1000); + + // Add event listener + this.listener = () => {}; + window.addEventListener('resize', this.listener); + } + + uninstall(): void { + // Clean up timer + if (this.timerId) { + clearInterval(this.timerId); + this.timerId = undefined; + } + + // Remove event listener + if (this.listener) { + window.removeEventListener('resize', this.listener); + this.listener = undefined; + } + } +} +``` + +### Error Handling + +Handle errors properly in plugins to avoid affecting the entire application: + +```typescript +class MyPlugin implements IPlugin { + readonly name = 'my-plugin'; + readonly version = '1.0.0'; + + async install(core: Core, services: ServiceContainer): Promise { + try { + // Operation that might fail + await this.loadConfig(); + } catch (error) { + console.error('Failed to load plugin config:', error); + throw error; // Re-throw to let framework know installation failed + } + } + + async uninstall(): Promise { + try { + await this.cleanup(); + } catch (error) { + console.error('Failed to cleanup plugin:', error); + // Cleanup failure shouldn't block uninstall + } + } + + private async loadConfig() { + // Load configuration + } + + private async cleanup() { + // Cleanup + } +} +``` + +### Configuration + +Allow users to configure plugin behavior: + +```typescript +interface NetworkPluginConfig { + serverUrl: string; + autoReconnect: boolean; + timeout: number; +} + +class NetworkPlugin implements IPlugin { + readonly name = 'network-plugin'; + readonly version = '1.0.0'; + + constructor(private config: NetworkPluginConfig) {} + + install(core: Core, services: ServiceContainer): void { + const network = new NetworkService(this.config); + services.registerInstance(NetworkService, network); + } + + uninstall(): void { + // Cleanup + } +} + +// Usage +const plugin = new NetworkPlugin({ + serverUrl: 'ws://localhost:8080', + autoReconnect: true, + timeout: 5000 +}); + +await Core.installPlugin(plugin); +``` + +## Common Issues + +### Plugin Installation Failed + +**Problem**: Plugin throws error during installation + +**Causes**: +- Dependencies not met +- Exception in install method +- Service registration conflict + +**Solutions**: +1. Check if dependencies are installed +2. Check error logs +3. Ensure service names don't conflict + +### Plugin Still Has Side Effects After Uninstall + +**Problem**: After uninstalling plugin, plugin functionality is still running + +**Cause**: Resources not properly cleaned up in uninstall method + +**Solution**: Ensure cleanup in uninstall: +- Timers +- Event listeners +- WebSocket connections +- System references + +### When to Use Plugins + +**Good for plugins**: +- Optional features (debug tools, performance analysis) +- Third-party integrations (network libraries, physics engines) +- Functionality modules reused across projects + +**Not suitable for plugins**: +- Core game logic +- Simple utility classes +- Project-specific features + +## Related Links + +- [Service Container](./service-container/) - Using service container in plugins +- [System Architecture](./system/) - Adding systems in plugins +- [Quick Start](./getting-started/) - Core initialization and basic usage diff --git a/docs/en/guide/scene-manager.md b/docs/src/content/docs/en/guide/scene-manager.md similarity index 99% rename from docs/en/guide/scene-manager.md rename to docs/src/content/docs/en/guide/scene-manager.md index 1e30a37e..776a2ce4 100644 --- a/docs/en/guide/scene-manager.md +++ b/docs/src/content/docs/en/guide/scene-manager.md @@ -1,3 +1,7 @@ +--- +title: "scene-manager" +--- + # SceneManager SceneManager is a lightweight scene manager provided by ECS Framework, suitable for 95% of game applications. It provides a simple and intuitive API with support for scene transitions and delayed loading. diff --git a/docs/en/guide/scene.md b/docs/src/content/docs/en/guide/scene.md similarity index 99% rename from docs/en/guide/scene.md rename to docs/src/content/docs/en/guide/scene.md index 0285db82..baa4b090 100644 --- a/docs/en/guide/scene.md +++ b/docs/src/content/docs/en/guide/scene.md @@ -1,3 +1,7 @@ +--- +title: "scene" +--- + # Scene Management In the ECS architecture, a Scene is a container for the game world, responsible for managing the lifecycle of entities, systems, and components. Scenes provide a complete ECS runtime environment. diff --git a/docs/src/content/docs/en/guide/serialization/decorators.md b/docs/src/content/docs/en/guide/serialization/decorators.md new file mode 100644 index 00000000..423526d0 --- /dev/null +++ b/docs/src/content/docs/en/guide/serialization/decorators.md @@ -0,0 +1,165 @@ +--- +title: "Decorators & Inheritance" +description: "Advanced serialization decorator usage and component inheritance" +--- + +## Advanced Decorators + +### Field Serialization Options + +```typescript +@ECSComponent('Advanced') +@Serializable({ version: 1 }) +class AdvancedComponent extends Component { + // Use alias + @Serialize({ alias: 'playerName' }) + public name: string = ''; + + // Custom serializer + @Serialize({ + serializer: (value: Date) => value.toISOString(), + deserializer: (value: string) => new Date(value) + }) + public createdAt: Date = new Date(); + + // Ignore serialization + @IgnoreSerialization() + public cachedData: any = null; +} +``` + +### Collection Type Serialization + +```typescript +@ECSComponent('Collections') +@Serializable({ version: 1 }) +class CollectionsComponent extends Component { + // Map serialization + @SerializeAsMap() + public inventory: Map = new Map(); + + // Set serialization + @SerializeAsSet() + public acquiredSkills: Set = new Set(); + + constructor() { + super(); + this.inventory.set('gold', 100); + this.inventory.set('silver', 50); + this.acquiredSkills.add('attack'); + this.acquiredSkills.add('defense'); + } +} +``` + +## Component Inheritance and Serialization + +The framework fully supports component class inheritance. Subclasses automatically inherit parent class serialization fields while adding their own. + +### Basic Inheritance + +```typescript +// Base component +@ECSComponent('Collider2DBase') +@Serializable({ version: 1, typeId: 'Collider2DBase' }) +abstract class Collider2DBase extends Component { + @Serialize() + public friction: number = 0.5; + + @Serialize() + public restitution: number = 0.0; + + @Serialize() + public isTrigger: boolean = false; +} + +// Subclass component - automatically inherits parent's serialization fields +@ECSComponent('BoxCollider2D') +@Serializable({ version: 1, typeId: 'BoxCollider2D' }) +class BoxCollider2DComponent extends Collider2DBase { + @Serialize() + public width: number = 1.0; + + @Serialize() + public height: number = 1.0; +} + +// Another subclass component +@ECSComponent('CircleCollider2D') +@Serializable({ version: 1, typeId: 'CircleCollider2D' }) +class CircleCollider2DComponent extends Collider2DBase { + @Serialize() + public radius: number = 0.5; +} +``` + +### Inheritance Rules + +1. **Field Inheritance**: Subclasses automatically inherit all `@Serialize()` marked fields from parent +2. **Independent Metadata**: Each subclass maintains independent serialization metadata; modifying subclass doesn't affect parent or other subclasses +3. **typeId Distinction**: Use `typeId` option to specify unique identifier for each class, ensuring correct component type recognition during deserialization + +### Importance of Using typeId + +When using component inheritance, it's **strongly recommended** to set a unique `typeId` for each class: + +```typescript +// ✅ Recommended: Explicitly specify typeId +@Serializable({ version: 1, typeId: 'BoxCollider2D' }) +class BoxCollider2DComponent extends Collider2DBase { } + +@Serializable({ version: 1, typeId: 'CircleCollider2D' }) +class CircleCollider2DComponent extends Collider2DBase { } + +// ⚠️ Not recommended: Relying on class name as typeId +// Class names may change after code minification, causing deserialization failure +@Serializable({ version: 1 }) +class BoxCollider2DComponent extends Collider2DBase { } +``` + +### Subclass Overriding Parent Fields + +Subclasses can redeclare parent fields to modify their serialization options: + +```typescript +@ECSComponent('SpecialCollider') +@Serializable({ version: 1, typeId: 'SpecialCollider' }) +class SpecialColliderComponent extends Collider2DBase { + // Override parent field with different alias + @Serialize({ alias: 'fric' }) + public override friction: number = 0.8; + + @Serialize() + public specialProperty: string = ''; +} +``` + +### Ignoring Inherited Fields + +Use `@IgnoreSerialization()` to ignore fields inherited from parent in subclass: + +```typescript +@ECSComponent('TriggerOnly') +@Serializable({ version: 1, typeId: 'TriggerOnly' }) +class TriggerOnlyCollider extends Collider2DBase { + // Ignore parent's friction and restitution fields + // Because Trigger doesn't need physics material properties + @IgnoreSerialization() + public override friction: number = 0; + + @IgnoreSerialization() + public override restitution: number = 0; +} +``` + +## Decorator Reference + +| Decorator | Description | +|-----------|-------------| +| `@Serializable({ version, typeId })` | Mark component as serializable | +| `@Serialize()` | Mark field as serializable | +| `@Serialize({ alias })` | Serialize field with alias | +| `@Serialize({ serializer, deserializer })` | Custom serialization logic | +| `@SerializeAsMap()` | Serialize Map type | +| `@SerializeAsSet()` | Serialize Set type | +| `@IgnoreSerialization()` | Ignore field serialization | diff --git a/docs/src/content/docs/en/guide/serialization/incremental.md b/docs/src/content/docs/en/guide/serialization/incremental.md new file mode 100644 index 00000000..6a05c71c --- /dev/null +++ b/docs/src/content/docs/en/guide/serialization/incremental.md @@ -0,0 +1,228 @@ +--- +title: "Incremental Serialization" +description: "Only serialize changes in the scene" +--- + +Incremental serialization only saves the changed parts of a scene, suitable for network synchronization, undo/redo, time rewinding, and other scenarios requiring frequent state saving. + +## Basic Usage + +### 1. Create Base Snapshot + +```typescript +// Create base snapshot before starting to record changes +scene.createIncrementalSnapshot(); +``` + +### 2. Modify Scene + +```typescript +// Add entity +const enemy = scene.createEntity('Enemy'); +enemy.addComponent(new PositionComponent(100, 200)); +enemy.addComponent(new HealthComponent(50)); + +// Modify component +const player = scene.findEntity('Player'); +const pos = player.getComponent(PositionComponent); +pos.x = 300; +pos.y = 400; + +// Remove component +player.removeComponentByType(BuffComponent); + +// Delete entity +const oldEntity = scene.findEntity('ToDelete'); +oldEntity.destroy(); + +// Modify scene data +scene.sceneData.set('score', 1000); +``` + +### 3. Get Incremental Changes + +```typescript +// Get all changes relative to base snapshot +const incremental = scene.serializeIncremental(); + +// View change statistics +const stats = IncrementalSerializer.getIncrementalStats(incremental); +console.log('Total changes:', stats.totalChanges); +console.log('Added entities:', stats.addedEntities); +console.log('Removed entities:', stats.removedEntities); +console.log('Added components:', stats.addedComponents); +console.log('Updated components:', stats.updatedComponents); +``` + +### 4. Serialize Incremental Data + +```typescript +// JSON format (default) +const jsonData = IncrementalSerializer.serializeIncremental(incremental, { + format: 'json' +}); + +// Binary format (smaller size, higher performance) +const binaryData = IncrementalSerializer.serializeIncremental(incremental, { + format: 'binary' +}); + +// Pretty print JSON output (for debugging) +const prettyJson = IncrementalSerializer.serializeIncremental(incremental, { + format: 'json', + pretty: true +}); + +// Send or save +socket.send(binaryData); // Use binary for network transmission +localStorage.setItem('changes', jsonData); // JSON for local storage +``` + +### 5. Apply Incremental Changes + +```typescript +// Apply changes to another scene +const otherScene = new Scene(); + +// Directly apply incremental object +otherScene.applyIncremental(incremental); + +// Apply from JSON string +const jsonData = IncrementalSerializer.serializeIncremental(incremental, { format: 'json' }); +otherScene.applyIncremental(jsonData); + +// Apply from binary Uint8Array +const binaryData = IncrementalSerializer.serializeIncremental(incremental, { format: 'binary' }); +otherScene.applyIncremental(binaryData); +``` + +## Incremental Snapshot Management + +### Update Snapshot Base + +After applying incremental changes, you can update the snapshot base: + +```typescript +// Create initial snapshot +scene.createIncrementalSnapshot(); + +// First modification +entity.addComponent(new VelocityComponent(5, 0)); +const incremental1 = scene.serializeIncremental(); + +// Update base (set current state as new base) +scene.updateIncrementalSnapshot(); + +// Second modification (incremental will be based on updated base) +entity.getComponent(VelocityComponent).dx = 10; +const incremental2 = scene.serializeIncremental(); +``` + +### Clear Snapshot + +```typescript +// Release memory used by snapshot +scene.clearIncrementalSnapshot(); + +// Check if snapshot exists +if (scene.hasIncrementalSnapshot()) { + console.log('Incremental snapshot exists'); +} +``` + +## Incremental Serialization Options + +```typescript +interface IncrementalSerializationOptions { + // Whether to perform deep comparison of component data + // Default true, set to false to improve performance but may miss internal field changes + deepComponentComparison?: boolean; + + // Whether to track scene data changes + // Default true + trackSceneData?: boolean; + + // Whether to compress snapshot (using JSON serialization) + // Default false + compressSnapshot?: boolean; + + // Serialization format + // 'json': JSON format (readable, convenient for debugging) + // 'binary': MessagePack binary format (smaller, higher performance) + // Default 'json' + format?: 'json' | 'binary'; + + // Whether to pretty print JSON output (only effective when format='json') + // Default false + pretty?: boolean; +} + +// Using options +scene.createIncrementalSnapshot({ + deepComponentComparison: true, + trackSceneData: true +}); +``` + +## Incremental Data Structure + +Incremental snapshots contain the following change types: + +```typescript +interface IncrementalSnapshot { + version: number; // Snapshot version number + timestamp: number; // Timestamp + sceneName: string; // Scene name + baseVersion: number; // Base version number + entityChanges: EntityChange[]; // Entity changes + componentChanges: ComponentChange[]; // Component changes + sceneDataChanges: SceneDataChange[]; // Scene data changes +} + +// Change operation types +enum ChangeOperation { + EntityAdded = 'entity_added', + EntityRemoved = 'entity_removed', + EntityUpdated = 'entity_updated', + ComponentAdded = 'component_added', + ComponentRemoved = 'component_removed', + ComponentUpdated = 'component_updated', + SceneDataUpdated = 'scene_data_updated' +} +``` + +## Performance Optimization + +### For High-Frequency Sync + +```typescript +// Disable deep comparison to improve performance +scene.createIncrementalSnapshot({ + deepComponentComparison: false // Only detect component addition/removal +}); +``` + +### Batch Operations + +```typescript +// Batch modify then serialize +scene.entities.buffer.forEach(entity => { + // Batch modifications +}); + +// Serialize all changes at once +const incremental = scene.serializeIncremental(); +``` + +## API Reference + +| Method | Description | +|--------|-------------| +| `scene.createIncrementalSnapshot(options?)` | Create base snapshot | +| `scene.serializeIncremental()` | Get incremental changes | +| `scene.applyIncremental(data)` | Apply incremental changes | +| `scene.updateIncrementalSnapshot()` | Update snapshot base | +| `scene.clearIncrementalSnapshot()` | Clear snapshot | +| `scene.hasIncrementalSnapshot()` | Check if snapshot exists | +| `IncrementalSerializer.getIncrementalStats(snapshot)` | Get change statistics | +| `IncrementalSerializer.serializeIncremental(snapshot, options)` | Serialize incremental data | diff --git a/docs/src/content/docs/en/guide/serialization/index.md b/docs/src/content/docs/en/guide/serialization/index.md new file mode 100644 index 00000000..74291177 --- /dev/null +++ b/docs/src/content/docs/en/guide/serialization/index.md @@ -0,0 +1,170 @@ +--- +title: "Serialization System" +description: "ECS serialization system overview and full serialization" +--- + +The serialization system provides a complete solution for persisting scene, entity, and component data. It supports both full serialization and incremental serialization modes, suitable for game saves, network synchronization, scene editors, time rewinding, and more. + +## Basic Concepts + +The serialization system has two layers: + +- **Full Serialization**: Serializes the complete scene state, including all entities, components, and scene data +- **Incremental Serialization**: Only serializes changes relative to a base snapshot, greatly reducing data size + +### Supported Data Formats + +- **JSON Format**: Human-readable, convenient for debugging and editing +- **Binary Format**: Uses MessagePack, smaller size and better performance + +> **v2.2.2 Important Change** +> +> Starting from v2.2.2, binary serialization returns `Uint8Array` instead of Node.js `Buffer` to ensure browser compatibility: +> - `serialize({ format: 'binary' })` returns `string | Uint8Array` (was `string | Buffer`) +> - `deserialize(data)` accepts `string | Uint8Array` (was `string | Buffer`) +> - `applyIncremental(data)` accepts `IncrementalSnapshot | string | Uint8Array` (was including `Buffer`) +> +> **Migration Impact**: +> - **Runtime Compatible**: Node.js `Buffer` inherits from `Uint8Array`, existing code works directly +> - **Type Checking**: If your TypeScript code explicitly uses `Buffer` type, change to `Uint8Array` +> - **Browser Support**: `Uint8Array` is a standard JavaScript type supported by all modern browsers + +## Full Serialization + +### Basic Usage + +#### 1. Mark Serializable Components + +Use `@Serializable` and `@Serialize` decorators to mark components and fields for serialization: + +```typescript +import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework'; + +@ECSComponent('Player') +@Serializable({ version: 1 }) +class PlayerComponent extends Component { + @Serialize() + public name: string = ''; + + @Serialize() + public level: number = 1; + + @Serialize() + public experience: number = 0; + + @Serialize() + public position: { x: number; y: number } = { x: 0, y: 0 }; + + // Fields without @Serialize() won't be serialized + private tempData: any = null; +} +``` + +#### 2. Serialize Scene + +```typescript +// JSON format serialization +const jsonData = scene.serialize({ + format: 'json', + pretty: true // Pretty print output +}); + +// Save to local storage +localStorage.setItem('gameSave', jsonData); + +// Binary format serialization (smaller size) +const binaryData = scene.serialize({ + format: 'binary' +}); + +// Save to file (Node.js environment) +// Note: binaryData is Uint8Array type, Node.js fs can write it directly +fs.writeFileSync('save.bin', binaryData); +``` + +#### 3. Deserialize Scene + +```typescript +// Restore from JSON +const saveData = localStorage.getItem('gameSave'); +if (saveData) { + scene.deserialize(saveData, { + strategy: 'replace' // Replace current scene content + }); +} + +// Restore from Binary +const binaryData = fs.readFileSync('save.bin'); +scene.deserialize(binaryData, { + strategy: 'merge' // Merge into existing scene +}); +``` + +### Serialization Options + +#### SerializationOptions + +```typescript +interface SceneSerializationOptions { + // Component types to serialize (optional) + components?: ComponentType[]; + + // Serialization format: 'json' or 'binary' + format?: 'json' | 'binary'; + + // Pretty print JSON output + pretty?: boolean; + + // Include metadata + includeMetadata?: boolean; +} +``` + +Example: + +```typescript +// Only serialize specific component types +const saveData = scene.serialize({ + format: 'json', + components: [PlayerComponent, InventoryComponent], + pretty: true, + includeMetadata: true +}); +``` + +#### DeserializationOptions + +```typescript +interface SceneDeserializationOptions { + // Deserialization strategy + strategy?: 'merge' | 'replace'; + + // Component type registry (optional, uses global registry by default) + componentRegistry?: Map; +} +``` + +### Scene Custom Data + +Besides entities and components, you can also serialize scene-level configuration data: + +```typescript +// Set scene data +scene.sceneData.set('weather', 'rainy'); +scene.sceneData.set('difficulty', 'hard'); +scene.sceneData.set('checkpoint', { x: 100, y: 200 }); + +// Scene data is automatically included when serializing +const saveData = scene.serialize({ format: 'json' }); + +// Scene data is restored after deserialization +scene.deserialize(saveData); +console.log(scene.sceneData.get('weather')); // 'rainy' +``` + +## More Topics + +- [Decorators & Inheritance](/en/guide/serialization/decorators) - Advanced decorator usage and component inheritance +- [Incremental Serialization](/en/guide/serialization/incremental) - Only serialize changes +- [Version Migration](/en/guide/serialization/migration) - Handle data structure changes +- [Use Cases](/en/guide/serialization/use-cases) - Save system, network sync, undo/redo examples diff --git a/docs/src/content/docs/en/guide/serialization/migration.md b/docs/src/content/docs/en/guide/serialization/migration.md new file mode 100644 index 00000000..47e1ca74 --- /dev/null +++ b/docs/src/content/docs/en/guide/serialization/migration.md @@ -0,0 +1,151 @@ +--- +title: "Version Migration" +description: "Handle component and scene data structure changes" +--- + +When component structure changes, the version migration system can automatically upgrade old version save data. + +## Register Migration Function + +```typescript +import { VersionMigrationManager } from '@esengine/ecs-framework'; + +// Assume PlayerComponent v1 has hp field +// v2 changes to health and maxHealth fields + +// Register migration from version 1 to version 2 +VersionMigrationManager.registerComponentMigration( + 'Player', + 1, // From version + 2, // To version + (data) => { + // Migration logic + const newData = { + ...data, + health: data.hp, + maxHealth: data.hp, + }; + delete newData.hp; + return newData; + } +); +``` + +## Using Migration Builder + +```typescript +import { MigrationBuilder } from '@esengine/ecs-framework'; + +new MigrationBuilder() + .forComponent('Player') + .fromVersionToVersion(2, 3) + .migrate((data) => { + // Migrate from version 2 to version 3 + data.experience = data.exp || 0; + delete data.exp; + return data; + }); +``` + +## Scene-Level Migration + +```typescript +// Register scene-level migration +VersionMigrationManager.registerSceneMigration( + 1, // From version + 2, // To version + (scene) => { + // Migrate scene structure + scene.metadata = { + ...scene.metadata, + migratedFrom: 1 + }; + return scene; + } +); +``` + +## Check Migration Path + +```typescript +// Check if migration is possible +const canMigrate = VersionMigrationManager.canMigrateComponent( + 'Player', + 1, // From version + 3 // To version +); + +if (canMigrate) { + // Safe to migrate + scene.deserialize(oldSaveData); +} + +// Get migration path +const path = VersionMigrationManager.getComponentMigrationPath('Player'); +console.log('Available migration versions:', path); // [1, 2, 3] +``` + +## Migration Chain Example + +When migrating across multiple versions, the system automatically chains migrations: + +```typescript +// Register v1 -> v2 +VersionMigrationManager.registerComponentMigration('Player', 1, 2, (data) => { + data.health = data.hp; + delete data.hp; + return data; +}); + +// Register v2 -> v3 +VersionMigrationManager.registerComponentMigration('Player', 2, 3, (data) => { + data.stats = { health: data.health, mana: 100 }; + delete data.health; + return data; +}); + +// When loading v1 data, it will automatically execute v1 -> v2 -> v3 +``` + +## Best Practices + +### 1. Always Maintain Backward Compatibility + +```typescript +// Document data structure changes for each version +// v1: { hp: number } +// v2: { health: number, maxHealth: number } +// v3: { stats: { health: number, mana: number } } +``` + +### 2. Test Migration Paths + +```typescript +// Test all possible migration paths +const testData = { hp: 100 }; +const migrated = VersionMigrationManager.migrateComponent('Player', testData, 1, 3); +expect(migrated.stats.health).toBe(100); +``` + +### 3. Keep Backup of Original Data + +```typescript +// Backup before migration +const backup = JSON.parse(JSON.stringify(saveData)); +try { + scene.deserialize(saveData); +} catch (e) { + // Restore on migration failure + console.error('Migration failed:', e); +} +``` + +## API Reference + +| Method | Description | +|--------|-------------| +| `registerComponentMigration(type, from, to, fn)` | Register component migration function | +| `registerSceneMigration(from, to, fn)` | Register scene migration function | +| `canMigrateComponent(type, from, to)` | Check if migration is possible | +| `getComponentMigrationPath(type)` | Get component's migration version path | +| `migrateComponent(type, data, from, to)` | Execute component data migration | diff --git a/docs/src/content/docs/en/guide/serialization/use-cases.md b/docs/src/content/docs/en/guide/serialization/use-cases.md new file mode 100644 index 00000000..ef9b8a98 --- /dev/null +++ b/docs/src/content/docs/en/guide/serialization/use-cases.md @@ -0,0 +1,306 @@ +--- +title: "Use Cases" +description: "Practical examples of the serialization system" +--- + +## Game Save System + +```typescript +class SaveSystem { + private static SAVE_KEY = 'game_save'; + + // Save game + public static saveGame(scene: Scene): void { + const saveData = scene.serialize({ + format: 'json', + pretty: false + }); + + localStorage.setItem(this.SAVE_KEY, saveData); + console.log('Game saved'); + } + + // Load game + public static loadGame(scene: Scene): boolean { + const saveData = localStorage.getItem(this.SAVE_KEY); + if (saveData) { + scene.deserialize(saveData, { + strategy: 'replace' + }); + console.log('Game loaded'); + return true; + } + return false; + } + + // Check if save exists + public static hasSave(): boolean { + return localStorage.getItem(this.SAVE_KEY) !== null; + } +} +``` + +## Network Synchronization + +```typescript +class NetworkSync { + private baseSnapshot?: any; + private syncInterval: number = 100; // Sync every 100ms + + constructor(private scene: Scene, private socket: WebSocket) { + this.setupSync(); + } + + private setupSync(): void { + // Create base snapshot + this.scene.createIncrementalSnapshot(); + + // Periodically send incremental updates + setInterval(() => { + this.sendIncremental(); + }, this.syncInterval); + + // Receive remote incremental updates + this.socket.onmessage = (event) => { + this.receiveIncremental(event.data); + }; + } + + private sendIncremental(): void { + const incremental = this.scene.serializeIncremental(); + const stats = IncrementalSerializer.getIncrementalStats(incremental); + + // Only send when there are changes + if (stats.totalChanges > 0) { + // Use binary format to reduce network transmission + const binaryData = IncrementalSerializer.serializeIncremental(incremental, { + format: 'binary' + }); + this.socket.send(binaryData); + + // Update base + this.scene.updateIncrementalSnapshot(); + } + } + + private receiveIncremental(data: ArrayBuffer): void { + // Directly apply binary data (ArrayBuffer to Uint8Array) + const uint8Array = new Uint8Array(data); + this.scene.applyIncremental(uint8Array); + } +} +``` + +## Undo/Redo System + +```typescript +class UndoRedoSystem { + private history: IncrementalSnapshot[] = []; + private currentIndex: number = -1; + private maxHistory: number = 50; + + constructor(private scene: Scene) { + // Create initial snapshot + this.scene.createIncrementalSnapshot(); + this.saveState('Initial'); + } + + // Save current state + public saveState(label: string): void { + const incremental = this.scene.serializeIncremental(); + + // Remove history after current position + this.history = this.history.slice(0, this.currentIndex + 1); + + // Add new state + this.history.push(incremental); + this.currentIndex++; + + // Limit history count + if (this.history.length > this.maxHistory) { + this.history.shift(); + this.currentIndex--; + } + + // Update snapshot base + this.scene.updateIncrementalSnapshot(); + } + + // Undo + public undo(): boolean { + if (this.currentIndex > 0) { + this.currentIndex--; + const incremental = this.history[this.currentIndex]; + this.scene.applyIncremental(incremental); + return true; + } + return false; + } + + // Redo + public redo(): boolean { + if (this.currentIndex < this.history.length - 1) { + this.currentIndex++; + const incremental = this.history[this.currentIndex]; + this.scene.applyIncremental(incremental); + return true; + } + return false; + } + + public canUndo(): boolean { + return this.currentIndex > 0; + } + + public canRedo(): boolean { + return this.currentIndex < this.history.length - 1; + } +} +``` + +## Level Editor + +```typescript +class LevelEditor { + // Export level + public exportLevel(scene: Scene, filename: string): void { + const levelData = scene.serialize({ + format: 'json', + pretty: true, + includeMetadata: true + }); + + // Browser environment + const blob = new Blob([levelData], { type: 'application/json' }); + const url = URL.createObjectURL(blob); + const a = document.createElement('a'); + a.href = url; + a.download = filename; + a.click(); + URL.revokeObjectURL(url); + } + + // Import level + public importLevel(scene: Scene, fileContent: string): void { + scene.deserialize(fileContent, { + strategy: 'replace' + }); + } + + // Validate level data + public validateLevel(saveData: string): boolean { + const validation = SceneSerializer.validate(saveData); + if (!validation.valid) { + console.error('Level data invalid:', validation.errors); + return false; + } + return true; + } + + // Get level info (without full deserialization) + public getLevelInfo(saveData: string): any { + const info = SceneSerializer.getInfo(saveData); + return info; + } +} +``` + +## Performance Tips + +### 1. Choose the Right Format + +- **Development**: Use JSON format for easy debugging and inspection +- **Production**: Use Binary format to reduce 30-50% data size + +### 2. Serialize On-Demand + +```typescript +// Only serialize components that need persistence +const saveData = scene.serialize({ + format: 'binary', + components: [PlayerComponent, InventoryComponent, QuestComponent] +}); +``` + +### 3. Optimize Incremental Serialization + +```typescript +// For high-frequency sync, disable deep comparison for better performance +scene.createIncrementalSnapshot({ + deepComponentComparison: false // Only detect component addition/removal +}); +``` + +## Best Practices + +### 1. Explicitly Mark Serialized Fields + +```typescript +// Clearly mark fields that need serialization +@ECSComponent('Player') +@Serializable({ version: 1 }) +class PlayerComponent extends Component { + @Serialize() + public name: string = ''; + + @Serialize() + public level: number = 1; + + // Runtime data not serialized + private _cachedSprite: any = null; +} +``` + +### 2. Use Version Control + +```typescript +// Specify version for components +@Serializable({ version: 2 }) +class PlayerComponent extends Component { + // Version 2 fields +} + +// Register migration function to ensure compatibility +VersionMigrationManager.registerComponentMigration('Player', 1, 2, migrateV1ToV2); +``` + +### 3. Avoid Circular References + +```typescript +// Don't directly reference other entities in components +@ECSComponent('Follower') +@Serializable({ version: 1 }) +class FollowerComponent extends Component { + // Store entity ID instead of entity reference + @Serialize() + public targetId: number = 0; + + // Find target entity through scene + public getTarget(scene: Scene): Entity | null { + return scene.entities.findEntityById(this.targetId); + } +} +``` + +### 4. Compress Large Data + +```typescript +// For large data structures, use custom serialization +@ECSComponent('LargeData') +@Serializable({ version: 1 }) +class LargeDataComponent extends Component { + @Serialize({ + serializer: (data: LargeObject) => compressData(data), + deserializer: (data: CompressedData) => decompressData(data) + }) + public data: LargeObject; +} +``` + +## Performance Comparison + +| Scenario | JSON Format | Binary Format | Savings | +|----------|-------------|---------------|---------| +| Small save (100 entities) | 50KB | 35KB | 30% | +| Medium save (1000 entities) | 500KB | 300KB | 40% | +| Large save (10000 entities) | 5MB | 2.5MB | 50% | diff --git a/docs/src/content/docs/en/guide/service-container/advanced.md b/docs/src/content/docs/en/guide/service-container/advanced.md new file mode 100644 index 00000000..e9f52bfb --- /dev/null +++ b/docs/src/content/docs/en/guide/service-container/advanced.md @@ -0,0 +1,208 @@ +--- +title: "Advanced Usage" +description: "Symbol patterns, best practices, common issues" +--- + +## Interface and Symbol Identifier Pattern + +For large projects or games requiring cross-platform adaptation, the "Interface + Symbol.for identifier" pattern is recommended. + +### Why Use Symbol.for + +- **Cross-package Sharing**: `Symbol.for('key')` creates/retrieves Symbol from global registry +- **Interface Decoupling**: Consumers only depend on interface definitions, not concrete implementations +- **Replaceable Implementations**: Can inject different implementations at runtime (test mocks, platform adapters) + +### Define Interface and Identifier + +```typescript +// IAudioService.ts +export interface IAudioService { + dispose(): void; + playSound(id: string): void; + playMusic(id: string, loop?: boolean): void; + stopMusic(): void; + setVolume(volume: number): void; + preload(id: string, url: string): Promise; +} + +// Use Symbol.for to ensure cross-package sharing +export const IAudioService = Symbol.for('IAudioService'); +``` + +### Implement Interface + +```typescript +// WebAudioService.ts - Web platform +export class WebAudioService implements IAudioService { + private audioContext: AudioContext; + + constructor() { + this.audioContext = new AudioContext(); + } + + playSound(id: string): void { + // Web Audio API implementation + } + + dispose(): void { + this.audioContext.close(); + } +} + +// WechatAudioService.ts - WeChat Mini Game platform +export class WechatAudioService implements IAudioService { + playSound(id: string): void { + // WeChat Mini Game API implementation + } + + dispose(): void { + // Cleanup + } +} +``` + +### Register and Use + +```typescript +// Register different implementations based on platform +if (typeof wx !== 'undefined') { + Core.services.registerInstance(IAudioService, new WechatAudioService()); +} else { + Core.services.registerInstance(IAudioService, new WebAudioService()); +} + +// Business code - doesn't care about concrete implementation +const audio = Core.services.resolve(IAudioService); +audio.playSound('explosion'); +``` + +### Symbol vs Symbol.for + +```typescript +// Symbol() - Creates unique Symbol each time +const sym1 = Symbol('test'); +const sym2 = Symbol('test'); +console.log(sym1 === sym2); // false + +// Symbol.for() - Shares in global registry +const sym3 = Symbol.for('test'); +const sym4 = Symbol.for('test'); +console.log(sym3 === sym4); // true +``` + +## Circular Dependency Detection + +The service container automatically detects circular dependencies: + +```typescript +// A depends on B, B depends on A +@Injectable() +class ServiceA implements IService { + @InjectProperty(ServiceB) + private b!: ServiceB; + dispose(): void {} +} + +@Injectable() +class ServiceB implements IService { + @InjectProperty(ServiceA) + private a!: ServiceA; + dispose(): void {} +} + +// Throws error on resolution +// Circular dependency detected: ServiceA -> ServiceB -> ServiceA +``` + +## Service Management + +```typescript +// Get all registered service types +const types = Core.services.getRegisteredServices(); + +// Get all instantiated service instances +const instances = Core.services.getAll(); + +// Unregister single service +Core.services.unregister(MyService); + +// Clear all services (calls dispose on each) +Core.services.clear(); +``` + +## Best Practices + +### Service Naming + +Service class names should end with `Service` or `Manager`: + +```typescript +class PlayerService implements IService {} +class AudioManager implements IService {} +class NetworkService implements IService {} +``` + +### Resource Cleanup + +Always clean up resources in the `dispose()` method: + +```typescript +class ResourceService implements IService { + private resources: Map = new Map(); + + dispose(): void { + for (const resource of this.resources.values()) { + resource.release(); + } + this.resources.clear(); + } +} +``` + +### Avoid Overuse + +Don't register every class as a service. Services should be: + +- Global singletons or need shared state +- Used in multiple places +- Need lifecycle management +- Require dependency injection + +### Dependency Direction + +Maintain clear dependency direction, avoid circular dependencies: + +``` +High-level services -> Mid-level services -> Low-level services +GameLogic -> DataService -> ConfigService +``` + +### When to Use Singleton vs Transient + +- **Singleton**: Manager classes, config, cache, state management +- **Transient**: Command objects, request handlers, temporary tasks + +## Common Issues + +### Service Not Registered Error + +**Problem**: `Error: Service MyService is not registered` + +**Solution**: +```typescript +// Ensure service is registered +Core.services.registerSingleton(MyService); + +// Or use tryResolve +const service = Core.services.tryResolve(MyService); +if (!service) { + console.log('Service not found'); +} +``` + +### Circular Dependency Error + +**Problem**: `Circular dependency detected` + +**Solution**: Redesign service dependencies, introduce intermediate services or use event system for decoupling. diff --git a/docs/src/content/docs/en/guide/service-container/built-in-services.md b/docs/src/content/docs/en/guide/service-container/built-in-services.md new file mode 100644 index 00000000..2190e3cc --- /dev/null +++ b/docs/src/content/docs/en/guide/service-container/built-in-services.md @@ -0,0 +1,97 @@ +--- +title: "Built-in Services" +description: "Services automatically registered by Core" +--- + +Core automatically registers the following built-in services during initialization: + +## TimerManager + +Timer manager responsible for managing all game timers: + +```typescript +const timerManager = Core.services.resolve(TimerManager); + +// Create a timer +timerManager.schedule(1.0, false, null, (timer) => { + console.log('Executed after 1 second'); +}); +``` + +## PerformanceMonitor + +Performance monitor for tracking game performance: + +```typescript +const monitor = Core.services.resolve(PerformanceMonitor); + +// Enable performance monitoring +monitor.enable(); + +// Get performance data +const fps = monitor.getFPS(); +``` + +## SceneManager + +Scene manager for single-scene application lifecycle: + +```typescript +const sceneManager = Core.services.resolve(SceneManager); + +// Set current scene +sceneManager.setScene(new GameScene()); + +// Get current scene +const currentScene = sceneManager.currentScene; + +// Delayed scene switch +sceneManager.loadScene(new MenuScene()); +``` + +## WorldManager + +World manager for managing multiple independent World instances (advanced use case): + +```typescript +const worldManager = Core.services.resolve(WorldManager); + +// Create independent game worlds +const gameWorld = worldManager.createWorld('game_room_001', { + name: 'GameRoom', + maxScenes: 5 +}); + +// Create scene in World +const scene = gameWorld.createScene('battle', new BattleScene()); +gameWorld.setSceneActive('battle', true); + +// Update all Worlds +worldManager.updateAll(); +``` + +**Use Cases**: +- **SceneManager**: Suitable for 95% of games (single-player, simple multiplayer) +- **WorldManager**: Suitable for MMO servers, game room systems requiring complete isolation + +## PoolManager + +Object pool manager: + +```typescript +const poolManager = Core.services.resolve(PoolManager); + +// Create object pool +const bulletPool = poolManager.createPool('bullets', () => new Bullet(), 100); +``` + +## PluginManager + +Plugin manager for installing and uninstalling plugins: + +```typescript +const pluginManager = Core.services.resolve(PluginManager); + +// Get all installed plugins +const plugins = pluginManager.getAllPlugins(); +``` diff --git a/docs/src/content/docs/en/guide/service-container/dependency-injection.md b/docs/src/content/docs/en/guide/service-container/dependency-injection.md new file mode 100644 index 00000000..7f91e4e5 --- /dev/null +++ b/docs/src/content/docs/en/guide/service-container/dependency-injection.md @@ -0,0 +1,190 @@ +--- +title: "Dependency Injection" +description: "Decorators and automatic dependency injection" +--- + +ECS Framework provides decorators to simplify dependency injection. + +## @Injectable Decorator + +Marks a class as injectable: + +```typescript +import { Injectable, IService } from '@esengine/ecs-framework'; + +@Injectable() +class GameService implements IService { + constructor() { + console.log('GameService created'); + } + + dispose(): void { + console.log('GameService disposed'); + } +} +``` + +## @InjectProperty Decorator + +Injects dependencies via property decorator. Injection occurs after constructor execution, before `onInitialize()` is called: + +```typescript +import { Injectable, InjectProperty, IService } from '@esengine/ecs-framework'; + +@Injectable() +class PlayerService implements IService { + @InjectProperty(DataService) + private data!: DataService; + + @InjectProperty(GameService) + private game!: GameService; + + dispose(): void { + // Cleanup resources + } +} +``` + +### Usage in EntitySystem + +```typescript +@Injectable() +class CombatSystem extends EntitySystem { + @InjectProperty(TimeService) + private timeService!: TimeService; + + @InjectProperty(AudioService) + private audio!: AudioService; + + constructor() { + super(Matcher.all(Health, Attack)); + } + + onInitialize(): void { + // Properties are injected at this point + console.log('Delta time:', this.timeService.getDeltaTime()); + } + + processEntity(entity: Entity): void { + this.audio.playSound('attack'); + } +} +``` + +> **Note**: Use `!` assertion when declaring properties (e.g., `private data!: DataService`) to indicate the property will be injected before use. + +## Registering Injectable Services + +Use `registerInjectable` to automatically handle dependency injection: + +```typescript +import { registerInjectable } from '@esengine/ecs-framework'; + +// Register service (automatically resolves @InjectProperty dependencies) +registerInjectable(Core.services, PlayerService); + +// Property dependencies are automatically injected on resolution +const player = Core.services.resolve(PlayerService); +``` + +## @Updatable Decorator + +Marks a service as updatable, making it automatically called each frame: + +```typescript +import { Injectable, Updatable, IService, IUpdatable } from '@esengine/ecs-framework'; + +@Injectable() +@Updatable() // Default priority is 0 +class PhysicsService implements IService, IUpdatable { + update(deltaTime?: number): void { + // Update physics simulation each frame + } + + dispose(): void {} +} + +// Specify update priority (lower values execute first) +@Injectable() +@Updatable(10) +class RenderService implements IService, IUpdatable { + update(deltaTime?: number): void { + // Render each frame + } + + dispose(): void {} +} +``` + +Services with `@Updatable` decorator are automatically called by Core: + +```typescript +function gameLoop(deltaTime: number) { + Core.update(deltaTime); // Automatically updates all updatable services +} +``` + +## Service Dependencies + +Recommended to use `@InjectProperty` for service dependencies: + +```typescript +@Injectable() +class ConfigService implements IService { + private config: any = {}; + + get(key: string) { + return this.config[key]; + } + + dispose(): void { + this.config = {}; + } +} + +@Injectable() +class NetworkService implements IService { + @InjectProperty(ConfigService) + private config!: ConfigService; + + onInitialize(): void { + // Use injected service in onInitialize + const apiUrl = this.config.get('apiUrl'); + } + + dispose(): void {} +} + +// Register services (in dependency order) +registerInjectable(Core.services, ConfigService); +registerInjectable(Core.services, NetworkService); +``` + +## @Inject Constructor Decorator + +:::caution[Compatibility Warning] +The `@Inject` constructor parameter decorator may **not be supported** in **Cocos Creator** and **LayaAir**, as these engines' build tools may have issues processing constructor parameter decorators. + +**Recommended**: Always use `@InjectProperty` property decorator, which works correctly on all platforms. +::: + +```typescript +// ⚠️ Not recommended: Constructor injection (may not work in Cocos/Laya) +@Injectable() +class NetworkService implements IService { + constructor( + @Inject(ConfigService) private config: ConfigService + ) {} +} + +// ✅ Recommended: Property injection (compatible with all platforms) +@Injectable() +class NetworkService implements IService { + @InjectProperty(ConfigService) + private config!: ConfigService; + + onInitialize(): void { + // Use injected service here + } +} +``` diff --git a/docs/src/content/docs/en/guide/service-container/index.md b/docs/src/content/docs/en/guide/service-container/index.md new file mode 100644 index 00000000..886666b5 --- /dev/null +++ b/docs/src/content/docs/en/guide/service-container/index.md @@ -0,0 +1,123 @@ +--- +title: "Service Container Overview" +description: "ECS Framework Dependency Injection Container" +--- + +The ServiceContainer is the dependency injection container of ECS Framework, responsible for managing the registration, resolution, and lifecycle of all services. + +## What is a Service Container + +The service container is a lightweight dependency injection (DI) container that provides: + +- **Service Registration**: Register service types into the container +- **Service Resolution**: Retrieve service instances from the container +- **Lifecycle Management**: Automatically manage service instance creation and destruction +- **Dependency Injection**: Automatically resolve dependencies between services + +## Core Concepts + +### Service + +A service is a class that implements the `IService` interface and must provide a `dispose()` method for resource cleanup: + +```typescript +import { IService } from '@esengine/ecs-framework'; + +class MyService implements IService { + constructor() { + // Initialization logic + } + + dispose(): void { + // Cleanup resources + } +} +``` + +### Service Identifier + +Service identifiers are used to uniquely identify a service in the container. Two types are supported: + +- **Class Constructor**: Use the service class directly as identifier +- **Symbol**: Use Symbol as identifier (recommended for interface abstractions) + +```typescript +// Method 1: Using class as identifier +Core.services.registerSingleton(DataService); +const data = Core.services.resolve(DataService); + +// Method 2: Using Symbol as identifier +const IFileSystem = Symbol.for('IFileSystem'); +Core.services.registerInstance(IFileSystem, new TauriFileSystem()); +const fs = Core.services.resolve(IFileSystem); +``` + +### Lifecycle + +- **Singleton**: Only one instance throughout the application lifecycle +- **Transient**: Creates a new instance on each resolution + +## Container Hierarchy + +ECS Framework provides three levels of service containers: + +``` +Core.services (Application global) + └─ World.services (World level) + └─ Scene.services (Scene level) +``` + +```typescript +// Core level +const container = Core.services; + +// World level +const worldContainer = world.services; + +// Scene level +const sceneContainer = scene.services; +``` + +## Basic Usage + +### Registering Services + +```typescript +// Singleton service +Core.services.registerSingleton(DataService); + +// Transient service +Core.services.registerTransient(CommandService); + +// Register instance +Core.services.registerInstance(ConfigService, config); + +// Factory function +Core.services.registerSingleton(LoggerService, (container) => { + const logger = new LoggerService(); + logger.setLevel('debug'); + return logger; +}); +``` + +### Resolving Services + +```typescript +// Resolve service (throws if not registered) +const dataService = Core.services.resolve(DataService); + +// Try resolve (returns null if not registered) +const optional = Core.services.tryResolve(OptionalService); + +// Check if registered +if (Core.services.isRegistered(DataService)) { + // ... +} +``` + +## Next Steps + +- [Built-in Services](./built-in-services/) - Framework provided services +- [Dependency Injection](./dependency-injection/) - Decorators and auto-injection +- [PluginServiceRegistry](./plugin-service-registry/) - Plugin service registry +- [Advanced Usage](./advanced/) - Symbol patterns, best practices diff --git a/docs/src/content/docs/en/guide/service-container/plugin-service-registry.md b/docs/src/content/docs/en/guide/service-container/plugin-service-registry.md new file mode 100644 index 00000000..a1694db3 --- /dev/null +++ b/docs/src/content/docs/en/guide/service-container/plugin-service-registry.md @@ -0,0 +1,182 @@ +--- +title: "PluginServiceRegistry" +description: "Type-safe plugin service registry" +--- + +`PluginServiceRegistry` is a type-safe service registry based on `ServiceToken`, designed for sharing services between plugins. + +## Design Principles + +1. **Type Safety** - Uses ServiceToken to carry type information +2. **Explicit Dependencies** - Express dependencies clearly by importing tokens +3. **Optional Dependencies** - `get` returns undefined, `require` throws +4. **Single Responsibility** - Only handles registration and lookup, not lifecycle +5. **Who Defines the Interface, Exports the Token** - Each module defines its own interfaces and tokens + +## ServiceToken + +Service tokens are used for type-safe service registration and retrieval: + +```typescript +import { createServiceToken, ServiceToken } from '@esengine/ecs-framework'; + +// Define interface +interface IAssetManager { + load(path: string): Promise; + unload(path: string): void; +} + +// Create service token +const AssetManagerToken = createServiceToken('assetManager'); +``` + +### Why Use ServiceToken + +- **Cross-package Type Safety**: TypeScript preserves generic type information across packages +- **Globally Unique**: Uses `Symbol.for()` to ensure same-named tokens reference the same Symbol +- **Explicit Dependencies**: Clearly express inter-module dependencies by importing tokens + +## Basic Usage + +### Registering Services + +```typescript +import { PluginServiceRegistry, createServiceToken } from '@esengine/ecs-framework'; + +// Create registry +const registry = new PluginServiceRegistry(); + +// Define token +interface ILogger { + log(message: string): void; +} +const LoggerToken = createServiceToken('logger'); + +// Register service +const logger: ILogger = { + log: (msg) => console.log(msg) +}; +registry.register(LoggerToken, logger); +``` + +### Getting Services + +```typescript +// Optional get (returns undefined if not exists) +const logger = registry.get(LoggerToken); +if (logger) { + logger.log('Hello'); +} + +// Required get (throws if not exists) +try { + const logger = registry.require(LoggerToken); + logger.log('Hello'); +} catch (e) { + console.error('Logger not registered'); +} +``` + +### Check and Unregister + +```typescript +// Check if registered +if (registry.has(LoggerToken)) { + // ... +} + +// Unregister service +registry.unregister(LoggerToken); + +// Clear all services +registry.clear(); +``` + +## Usage in Plugins + +### Define Module Service Tokens + +Each module should define its interfaces and tokens in `tokens.ts`: + +```typescript +// packages/asset-system/src/tokens.ts +import { createServiceToken } from '@esengine/ecs-framework'; + +export interface IAssetManager { + load(path: string): Promise; + unload(path: string): void; + getCache(path: string): any | undefined; +} + +export const AssetManagerToken = createServiceToken('assetManager'); +``` + +### Register Service in Plugin + +```typescript +// packages/asset-system/src/AssetSystemPlugin.ts +import { Core } from '@esengine/ecs-framework'; +import { AssetManagerToken, IAssetManager } from './tokens'; +import { AssetManager } from './AssetManager'; + +export function installAssetSystem() { + const assetManager = new AssetManager(); + + // Register to Core's plugin service registry + Core.pluginServices.register(AssetManagerToken, assetManager); +} +``` + +### Use in Other Plugins + +```typescript +// packages/sprite/src/SpriteSystem.ts +import { Core } from '@esengine/ecs-framework'; +import { AssetManagerToken, IAssetManager } from '@esengine/asset-system'; + +class SpriteSystem extends EntitySystem { + private assetManager!: IAssetManager; + + onInitialize(): void { + // Get from plugin service registry + this.assetManager = Core.pluginServices.require(AssetManagerToken); + } + + async loadSprite(path: string) { + const texture = await this.assetManager.load(path); + // ... + } +} +``` + +## Difference from ServiceContainer + +| Feature | ServiceContainer | PluginServiceRegistry | +|---------|------------------|----------------------| +| Purpose | General DI | Cross-plugin service sharing | +| Identifier | Class or Symbol | ServiceToken | +| Lifecycle | Singleton/Transient | None (caller managed) | +| Decorator Support | @Injectable, @InjectProperty | None | +| Type Safety | Requires generic assertion | Token carries type | + +## API Reference + +### createServiceToken + +```typescript +function createServiceToken(name: string): ServiceToken +``` + +Creates a service token. Uses `Symbol.for()` to ensure cross-package sharing. + +### PluginServiceRegistry + +| Method | Description | +|--------|-------------| +| `register(token, service)` | Register a service | +| `get(token): T \| undefined` | Get service (optional) | +| `require(token): T` | Get service (required, throws if missing) | +| `has(token): boolean` | Check if registered | +| `unregister(token): boolean` | Unregister service | +| `clear()` | Clear all services | +| `dispose()` | Dispose resources | diff --git a/docs/src/content/docs/en/guide/system/best-practices.md b/docs/src/content/docs/en/guide/system/best-practices.md new file mode 100644 index 00000000..c0fe4661 --- /dev/null +++ b/docs/src/content/docs/en/guide/system/best-practices.md @@ -0,0 +1,368 @@ +--- +title: "Best Practices" +description: "System design best practices and complex examples" +--- + +## Design Principles + +### 1. Single Responsibility for Systems + +```typescript +// ✅ Good system design - single responsibility +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + } +} + +@ECSSystem('Rendering') +class RenderingSystem extends EntitySystem { + constructor() { + super(Matcher.all(Sprite, Transform)); + } +} + +// ❌ Avoid - too many responsibilities +@ECSSystem('GameSystem') +class GameSystem extends EntitySystem { + // One system handling movement, rendering, sound effects, and more +} +``` + +### 2. Use @ECSSystem Decorator + +`@ECSSystem` is a required decorator for system classes, providing type identification and metadata management. + +| Feature | Description | +|---------|-------------| +| **Type Identification** | Provides stable system names that remain correct after code obfuscation | +| **Debug Support** | Shows readable system names in performance monitoring, logs, and debug tools | +| **System Management** | Find and manage systems by name | +| **Serialization Support** | Records system configuration during scene serialization | + +```typescript +// ✅ Correct usage +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + // System implementation +} + +// ✅ Recommended: Use descriptive names +@ECSSystem('PlayerMovement') +class PlayerMovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Player, Position, Velocity)); + } +} + +// ❌ Wrong - no decorator +class BadSystem extends EntitySystem { + // Systems defined this way may have issues in production +} +``` + +### 3. Proper Update Order + +```typescript +// Set system update order by logical sequence +@ECSSystem('Input') +class InputSystem extends EntitySystem { + constructor() { + super(); + this.updateOrder = -100; // Process input first + } +} + +@ECSSystem('Logic') +class GameLogicSystem extends EntitySystem { + constructor() { + super(); + this.updateOrder = 0; // Process game logic + } +} + +@ECSSystem('Render') +class RenderSystem extends EntitySystem { + constructor() { + super(); + this.updateOrder = 100; // Render last + } +} +``` + +### 4. Avoid Direct References Between Systems + +```typescript +// ❌ Avoid: Direct system references +@ECSSystem('Bad') +class BadSystem extends EntitySystem { + private otherSystem: SomeOtherSystem; // Avoid direct references to other systems +} + +// ✅ Recommended: Communicate through event system +@ECSSystem('Good') +class GoodSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // Communicate with other systems through event system + this.scene?.eventSystem.emitSync('data_updated', { entities }); + } +} +``` + +### 5. Clean Up Resources Promptly + +```typescript +@ECSSystem('Resource') +class ResourceSystem extends EntitySystem { + private resources: Map = new Map(); + + protected onDestroy(): void { + // Clean up resources + for (const [key, resource] of this.resources) { + if (resource.dispose) { + resource.dispose(); + } + } + this.resources.clear(); + } +} +``` + +## Complex System Examples + +### Collision Detection System + +```typescript +@ECSSystem('Collision') +class CollisionSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, Collider)); + } + + protected process(entities: readonly Entity[]): void { + // Simple n² collision detection + for (let i = 0; i < entities.length; i++) { + for (let j = i + 1; j < entities.length; j++) { + this.checkCollision(entities[i], entities[j]); + } + } + } + + private checkCollision(entityA: Entity, entityB: Entity): void { + const transformA = entityA.getComponent(Transform); + const transformB = entityB.getComponent(Transform); + const colliderA = entityA.getComponent(Collider); + const colliderB = entityB.getComponent(Collider); + + if (this.isColliding(transformA, colliderA, transformB, colliderB)) { + // Send collision event + this.scene?.eventSystem.emitSync('collision', { + entityA, + entityB + }); + } + } + + private isColliding( + transformA: Transform, colliderA: Collider, + transformB: Transform, colliderB: Collider + ): boolean { + // Collision detection logic + const dx = transformA.x - transformB.x; + const dy = transformA.y - transformB.y; + const distance = Math.sqrt(dx * dx + dy * dy); + return distance < colliderA.radius + colliderB.radius; + } +} +``` + +### State Machine System + +```typescript +enum EntityState { + Idle, + Moving, + Attacking, + Dead +} + +@ECSSystem('StateMachine') +class StateMachineSystem extends EntitySystem { + constructor() { + super(Matcher.all(StateMachine)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const stateMachine = entity.getComponent(StateMachine); + if (stateMachine) { + stateMachine.updateTimer(Time.deltaTime); + this.updateState(entity, stateMachine); + } + } + } + + private updateState(entity: Entity, stateMachine: StateMachine): void { + switch (stateMachine.currentState) { + case EntityState.Idle: + this.handleIdleState(entity, stateMachine); + break; + case EntityState.Moving: + this.handleMovingState(entity, stateMachine); + break; + case EntityState.Attacking: + this.handleAttackingState(entity, stateMachine); + break; + } + } + + private handleIdleState(entity: Entity, sm: StateMachine): void { + // Check for movement input + const input = entity.getComponent(InputComponent); + if (input && input.hasMovementInput()) { + sm.changeState(EntityState.Moving); + } + } + + private handleMovingState(entity: Entity, sm: StateMachine): void { + // Check if movement stopped + const input = entity.getComponent(InputComponent); + if (!input || !input.hasMovementInput()) { + sm.changeState(EntityState.Idle); + } + } + + private handleAttackingState(entity: Entity, sm: StateMachine): void { + // Return to idle after attack animation + if (sm.stateTimer > 0.5) { + sm.changeState(EntityState.Idle); + } + } +} +``` + +### AI Behavior System + +```typescript +@ECSSystem('AIBehavior') +class AIBehaviorSystem extends EntitySystem { + constructor() { + super(Matcher.all(AIComponent, Transform).none(Dead)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const ai = entity.getComponent(AIComponent)!; + const transform = entity.getComponent(Transform)!; + + switch (ai.state) { + case AIState.Patrol: + this.patrol(entity, ai, transform); + break; + case AIState.Chase: + this.chase(entity, ai, transform); + break; + case AIState.Attack: + this.attack(entity, ai); + break; + } + } + } + + private patrol(entity: Entity, ai: AIComponent, transform: Transform): void { + // Move to patrol point + const target = ai.patrolPoints[ai.currentPatrolIndex]; + const dx = target.x - transform.x; + const dy = target.y - transform.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance < 5) { + // Reached patrol point, move to next + ai.currentPatrolIndex = (ai.currentPatrolIndex + 1) % ai.patrolPoints.length; + } else { + // Move towards patrol point + const speed = ai.moveSpeed * Time.deltaTime; + transform.x += (dx / distance) * speed; + transform.y += (dy / distance) * speed; + } + + // Detect player + if (this.detectPlayer(entity, ai)) { + ai.state = AIState.Chase; + } + } + + private chase(entity: Entity, ai: AIComponent, transform: Transform): void { + const player = this.findPlayer(); + if (!player) { + ai.state = AIState.Patrol; + return; + } + + const playerTransform = player.getComponent(Transform)!; + const dx = playerTransform.x - transform.x; + const dy = playerTransform.y - transform.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance < ai.attackRange) { + ai.state = AIState.Attack; + } else if (distance > ai.chaseRange) { + ai.state = AIState.Patrol; + } else { + // Chase player + const speed = ai.chaseSpeed * Time.deltaTime; + transform.x += (dx / distance) * speed; + transform.y += (dy / distance) * speed; + } + } + + private attack(entity: Entity, ai: AIComponent): void { + ai.attackCooldown -= Time.deltaTime; + if (ai.attackCooldown <= 0) { + // Execute attack + this.scene?.eventSystem.emitSync('ai_attack', { attacker: entity }); + ai.attackCooldown = ai.attackInterval; + } + } + + private detectPlayer(entity: Entity, ai: AIComponent): boolean { + // Player detection logic + return false; + } + + private findPlayer(): Entity | null { + const result = this.scene?.querySystem.queryByTag(Tags.PLAYER); + return result?.entities[0] ?? null; + } +} +``` + +## FAQ + +### Q: How big should a system be? + +**A**: Follow the single responsibility principle. If a system handles multiple unrelated logic, split it into multiple systems. + +### Q: How to share data between systems? + +**A**: +1. Share data through components (recommended) +2. Communicate through event system +3. Inject shared services through service container + +### Q: When to use CommandBuffer? + +**A**: When you need to destroy entities during iteration, use CommandBuffer. Adding/removing components can be done directly. + +### Q: How to optimize processing of many entities? + +**A**: +1. Use change detection, only process changed entities +2. Use WorkerEntitySystem for parallel processing +3. Optimize Matcher conditions, reduce matched entities +4. Consider using Spatial Partitioning + +--- + +Systems are the logic processing core of ECS architecture. Properly designing and using systems makes your game code more modular, efficient, and maintainable. diff --git a/docs/src/content/docs/en/guide/system/change-detection.md b/docs/src/content/docs/en/guide/system/change-detection.md new file mode 100644 index 00000000..1f21971a --- /dev/null +++ b/docs/src/content/docs/en/guide/system/change-detection.md @@ -0,0 +1,252 @@ +--- +title: "Change Detection" +description: "Frame-level change detection to optimize system performance" +--- + +> **v2.4.0+** + +The framework provides epoch-based frame-level change detection, allowing systems to process only entities that have changed, significantly improving performance. + +## Core Concepts + +- **Epoch**: Global frame counter, incremented each frame +- **lastWriteEpoch**: The epoch when a component was last modified +- **Change Detection**: Determine if component changed after a specific point by comparing epochs + +## Marking Components as Modified + +After modifying component data, you need to mark the component as changed. There are two approaches: + +### Approach 1: Via Entity Helper Method (Recommended) + +```typescript +// Mark component dirty via entity.markDirty() after modification +const pos = entity.getComponent(Position)!; +pos.x = 100; +pos.y = 200; +entity.markDirty(pos); + +// Can mark multiple components at once +const vel = entity.getComponent(Velocity)!; +vel.vx = 10; +entity.markDirty(pos, vel); +``` + +### Approach 2: Encapsulate in Component + +```typescript +class VelocityComponent extends Component { + private _vx: number = 0; + private _vy: number = 0; + + // Provide modification method that accepts epoch parameter + public setVelocity(vx: number, vy: number, epoch: number): void { + this._vx = vx; + this._vy = vy; + this.markDirty(epoch); + } + + public get vx(): number { return this._vx; } + public get vy(): number { return this._vy; } +} + +// Usage in system +const vel = entity.getComponent(VelocityComponent)!; +vel.setVelocity(10, 20, this.currentEpoch); +``` + +## Using Change Detection in Systems + +EntitySystem provides several change detection helper methods: + +### forEachChanged - Iterate Changed Entities + +```typescript +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + // Use forEachChanged to process only changed entities + // Automatically saves epoch checkpoint + this.forEachChanged(entities, [Velocity], (entity) => { + const pos = this.requireComponent(entity, Position); + const vel = this.requireComponent(entity, Velocity); + + // Only update position when Velocity changes + pos.x += vel.vx * Time.deltaTime; + pos.y += vel.vy * Time.deltaTime; + }); + } +} +``` + +### filterChanged - Get List of Changed Entities + +```typescript +@ECSSystem('Transform') +class TransformSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, RigidBody)); + } + + protected process(entities: readonly Entity[]): void { + // Use filterChanged to get list of changed entities + const changedEntities = this.filterChanged(entities, [RigidBody]); + + for (const entity of changedEntities) { + // Process entities with changed physics state + this.updatePhysics(entity); + } + + // Manually save epoch checkpoint + this.saveEpoch(); + } + + protected updatePhysics(entity: Entity): void { + // Physics update logic + } +} +``` + +### hasChanged - Check Single Entity + +```typescript +protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + // Check if single entity's specified components have changed + if (this.hasChanged(entity, [Transform])) { + this.updateRenderData(entity); + } + } +} +``` + +## Change Detection API Reference + +| Method | Description | +|--------|-------------| +| `forEachChanged(entities, [Types], callback)` | Iterate entities with changed specified components, auto-saves checkpoint | +| `filterChanged(entities, [Types])` | Return array of entities with changed specified components | +| `hasChanged(entity, [Types])` | Check if single entity's specified components have changed | +| `saveEpoch()` | Manually save current epoch as checkpoint | +| `lastProcessEpoch` | Get last saved epoch checkpoint | +| `currentEpoch` | Get current scene epoch | + +## Use Cases + +Change detection is particularly suitable for: + +### 1. Dirty Flag Optimization + +Only update rendering when data changes: + +```typescript +@ECSSystem('RenderUpdate') +class RenderUpdateSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, Sprite)); + } + + protected process(entities: readonly Entity[]): void { + // Only update changed sprites + this.forEachChanged(entities, [Transform, Sprite], (entity) => { + const transform = this.requireComponent(entity, Transform); + const sprite = this.requireComponent(entity, Sprite); + + this.updateSpriteMatrix(sprite, transform); + }); + } +} +``` + +### 2. Network Sync + +Only send changed component data: + +```typescript +@ECSSystem('NetworkSync') +class NetworkSyncSystem extends EntitySystem { + constructor() { + super(Matcher.all(NetworkComponent, Transform)); + } + + protected process(entities: readonly Entity[]): void { + // Only sync changed entities, greatly reducing network traffic + this.forEachChanged(entities, [Transform], (entity) => { + const transform = this.requireComponent(entity, Transform); + const network = this.requireComponent(entity, NetworkComponent); + + this.sendTransformUpdate(network.id, transform); + }); + } + + private sendTransformUpdate(id: string, transform: Transform): void { + // Send network update + } +} +``` + +### 3. Physics Sync + +Only sync entities with changed position/velocity: + +```typescript +@ECSSystem('PhysicsSync') +class PhysicsSyncSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, RigidBody)); + } + + protected process(entities: readonly Entity[]): void { + // Sync changed entities from physics engine + this.forEachChanged(entities, [RigidBody], (entity) => { + const transform = entity.getComponent(Transform)!; + const rigidBody = entity.getComponent(RigidBody)!; + + // Update Transform + transform.position = rigidBody.getPosition(); + transform.rotation = rigidBody.getRotation(); + + // Mark Transform as changed + entity.markDirty(transform); + }); + } +} +``` + +### 4. Cache Invalidation + +Only recalculate when dependent data changes: + +```typescript +@ECSSystem('PathCache') +class PathCacheSystem extends EntitySystem { + constructor() { + super(Matcher.all(PathFinder, Transform)); + } + + protected process(entities: readonly Entity[]): void { + // Only recalculate path when position changes + this.forEachChanged(entities, [Transform], (entity) => { + const pathFinder = entity.getComponent(PathFinder)!; + pathFinder.invalidateCache(); + pathFinder.recalculatePath(); + }); + } +} +``` + +## Performance Comparison + +| Scenario | Without Change Detection | With Change Detection | Improvement | +|----------|--------------------------|----------------------|-------------| +| 1000 entities, 10% changed | 1000 processes | 100 processes | 10x | +| 1000 entities, 1% changed | 1000 processes | 10 processes | 100x | +| Network sync | Full send | Incremental send | 90%+ bandwidth saved | + +:::tip +Change detection works best for "many entities, few changes" scenarios. If most entities change every frame, the overhead of change detection may not be worthwhile. +::: diff --git a/docs/src/content/docs/en/guide/system/command-buffer.md b/docs/src/content/docs/en/guide/system/command-buffer.md new file mode 100644 index 00000000..583e5878 --- /dev/null +++ b/docs/src/content/docs/en/guide/system/command-buffer.md @@ -0,0 +1,172 @@ +--- +title: "Command Buffer" +description: "Use CommandBuffer for deferred entity operations" +--- + +> **v2.3.0+** + +CommandBuffer provides a mechanism for deferred execution of entity operations. When you need to destroy entities or perform other operations that might affect iteration during processing, CommandBuffer allows you to defer these operations to the end of the frame. + +## Basic Usage + +Every EntitySystem has a built-in `commands` property: + +```typescript +@ECSSystem('Damage') +class DamageSystem extends EntitySystem { + constructor() { + super(Matcher.all(Health, DamageReceiver)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health); + const damage = entity.getComponent(DamageReceiver); + + if (health && damage) { + health.current -= damage.amount; + + // Use command buffer to defer component removal + this.commands.removeComponent(entity, DamageReceiver); + + if (health.current <= 0) { + // Defer adding death marker + this.commands.addComponent(entity, new Dead()); + // Defer entity destruction + this.commands.destroyEntity(entity); + } + } + } + } +} +``` + +## Supported Commands + +| Method | Description | +|--------|-------------| +| `addComponent(entity, component)` | Defer adding component | +| `removeComponent(entity, ComponentType)` | Defer removing component | +| `destroyEntity(entity)` | Defer destroying entity | +| `setEntityActive(entity, active)` | Defer setting entity active state | + +## Execution Timing + +Commands in the buffer are automatically executed after the `lateUpdate` phase of each frame. Execution order matches the order commands were queued. + +``` +Scene Update Flow: +1. onBegin() +2. process() +3. lateProcess() +4. onEnd() +5. flushCommandBuffers() <-- Commands execute here +``` + +## Use Cases + +CommandBuffer is suitable for: + +### 1. Destroying Entities During Iteration + +Avoid modifying collection being traversed: + +```typescript +@ECSSystem('EnemyDeath') +class EnemyDeathSystem extends EntitySystem { + constructor() { + super(Matcher.all(Enemy, Health)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health); + if (health && health.current <= 0) { + // Play death animation, spawn loot, etc. + this.spawnLoot(entity); + + // Defer destruction, doesn't affect current iteration + this.commands.destroyEntity(entity); + } + } + } + + private spawnLoot(entity: Entity): void { + // Loot spawning logic + } +} +``` + +### 2. Batch Deferred Operations + +Merge multiple operations to execute at end of frame: + +```typescript +@ECSSystem('Cleanup') +class CleanupSystem extends EntitySystem { + constructor() { + super(Matcher.all(MarkedForDeletion)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + // Batch collect entities to delete + this.commands.destroyEntity(entity); + } + // All destruction operations execute at frame end + } +} +``` + +### 3. Cross-System Coordination + +One system marks, another system responds: + +```typescript +@ECSSystem('Combat') +class CombatSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + if (this.shouldDie(entity)) { + // Mark as dead + this.commands.addComponent(entity, new Dead()); + } + } + } +} + +@ECSSystem('DeathHandler') +class DeathHandlerSystem extends EntitySystem { + constructor() { + super(Matcher.all(Dead)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + // Handle death logic + this.playDeathAnimation(entity); + this.commands.destroyEntity(entity); + } + } +} +``` + +## Notes + +- Commands skip already destroyed entities (safety check) +- Single command failure doesn't affect other commands +- Commands execute in queue order +- Command queue clears after each `flush()` + +## Direct Modification vs Command Buffer + +| Operation | Direct Modification | Command Buffer | +|-----------|---------------------|----------------| +| Add component | ✅ Safe | ✅ Safe | +| Remove component | ✅ Safe | ✅ Safe | +| Destroy entity | ⚠️ May cause issues | ✅ Recommended | +| Execution timing | Immediate | End of frame | + +:::tip +While adding/removing components in `process` is safe (due to snapshot mechanism), if you need to destroy entities, using command buffer is recommended. +::: diff --git a/docs/src/content/docs/en/guide/system/index.md b/docs/src/content/docs/en/guide/system/index.md new file mode 100644 index 00000000..e8ecb4bd --- /dev/null +++ b/docs/src/content/docs/en/guide/system/index.md @@ -0,0 +1,170 @@ +--- +title: "System Architecture" +description: "ECS System Overview and Basic Concepts" +--- + +In ECS architecture, Systems are where business logic is processed. Systems are responsible for performing operations on entities that have specific component combinations, serving as the logic processing units of ECS architecture. + +## Basic Concepts + +Systems are concrete classes that inherit from the `EntitySystem` abstract base class, used for: +- Defining entity processing logic (such as movement, collision detection, rendering, etc.) +- Filtering entities based on component combinations +- Providing lifecycle management and performance monitoring +- Managing entity add/remove events + +## Quick Example + +```typescript +import { EntitySystem, ECSSystem, Matcher } from '@esengine/ecs-framework'; + +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + // Use Matcher to define entity conditions to process + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const position = entity.getComponent(Position); + const velocity = entity.getComponent(Velocity); + + if (position && velocity) { + position.x += velocity.dx * Time.deltaTime; + position.y += velocity.dy * Time.deltaTime; + } + } + } +} +``` + +## System Properties and Methods + +### Important Properties + +```typescript +@ECSSystem('Example') +class ExampleSystem extends EntitySystem { + showSystemInfo(): void { + console.log(`System name: ${this.systemName}`); // System name + console.log(`Update order: ${this.updateOrder}`); // Update order + console.log(`Is enabled: ${this.enabled}`); // Enabled state + console.log(`Entity count: ${this.entities.length}`); // Number of matched entities + console.log(`Scene: ${this.scene?.name}`); // Parent scene + } +} +``` + +### Entity Access + +```typescript +protected process(entities: readonly Entity[]): void { + // Method 1: Use entity list from parameter + for (const entity of entities) { + // Process entity + } + + // Method 2: Use this.entities property (same as parameter) + for (const entity of this.entities) { + // Process entity + } +} +``` + +### Controlling System Execution + +```typescript +@ECSSystem('Conditional') +class ConditionalSystem extends EntitySystem { + private shouldProcess = true; + + protected onCheckProcessing(): boolean { + // Return false to skip this processing + return this.shouldProcess && this.entities.length > 0; + } + + public pause(): void { + this.shouldProcess = false; + } + + public resume(): void { + this.shouldProcess = true; + } +} +``` + +## System Management + +### Adding Systems to Scene + +The framework provides two ways to add systems: pass an instance or pass a type (automatic dependency injection). + +```typescript +// Add systems in scene subclass +class GameScene extends Scene { + protected initialize(): void { + // Method 1: Pass instance + this.addSystem(new MovementSystem()); + this.addSystem(new RenderSystem()); + + // Method 2: Pass type (automatic dependency injection) + this.addEntityProcessor(PhysicsSystem); + + // Set system update order + const movementSystem = this.getSystem(MovementSystem); + if (movementSystem) { + movementSystem.updateOrder = 1; + } + } +} +``` + +### System Update Order + +System execution order is determined by the `updateOrder` property. Lower values execute first: + +```typescript +@ECSSystem('Input') +class InputSystem extends EntitySystem { + constructor() { + super(Matcher.all(InputComponent)); + this.updateOrder = -100; // Input system executes first + } +} + +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + constructor() { + super(Matcher.all(RigidBody)); + this.updateOrder = 0; // Default order + } +} + +@ECSSystem('Render') +class RenderSystem extends EntitySystem { + constructor() { + super(Matcher.all(Sprite, Transform)); + this.updateOrder = 100; // Render system executes last + } +} +``` + +#### Stable Sorting: addOrder + +When multiple systems have the same `updateOrder`, the framework uses `addOrder` (add order) as a secondary sorting criterion: + +```typescript +// Both systems have default updateOrder of 0 +scene.addSystem(new SystemA()); // addOrder = 0, executes first +scene.addSystem(new SystemB()); // addOrder = 1, executes second +``` + +## Next Steps + +- [System Types](/en/guide/system/types) - Learn about different system base classes +- [System Lifecycle](/en/guide/system/lifecycle) - Lifecycle callbacks and event listening +- [Command Buffer](/en/guide/system/command-buffer) - Deferred entity operations +- [System Scheduling](/en/guide/system/scheduling) - Declarative system scheduling +- [Change Detection](/en/guide/system/change-detection) - Frame-level change detection optimization +- [Best Practices](/en/guide/system/best-practices) - System design best practices diff --git a/docs/src/content/docs/en/guide/system/lifecycle.md b/docs/src/content/docs/en/guide/system/lifecycle.md new file mode 100644 index 00000000..c89cb88d --- /dev/null +++ b/docs/src/content/docs/en/guide/system/lifecycle.md @@ -0,0 +1,249 @@ +--- +title: "System Lifecycle" +description: "System lifecycle callbacks, event listening and dependency injection" +--- + +## Lifecycle Callbacks + +Systems provide complete lifecycle callbacks: + +```typescript +@ECSSystem('Example') +class ExampleSystem extends EntitySystem { + protected onInitialize(): void { + console.log('System initialized'); + // Called when system is added to scene, for initializing resources + } + + protected onBegin(): void { + // Called before each frame's processing begins + } + + protected process(entities: readonly Entity[]): void { + // Main processing logic + for (const entity of entities) { + // Process each entity + // ✅ Safe to add/remove components here without affecting current iteration + } + } + + protected lateProcess(entities: readonly Entity[]): void { + // Post-processing after main process + // ✅ Safe to add/remove components here without affecting current iteration + } + + protected onEnd(): void { + // Called after each frame's processing ends + } + + protected onDestroy(): void { + console.log('System destroyed'); + // Called when system is removed from scene, for cleaning up resources + } +} +``` + +## Entity Event Listening + +Systems can listen for entity add and remove events: + +```typescript +@ECSSystem('EnemyManager') +class EnemyManagerSystem extends EntitySystem { + private enemyCount = 0; + + constructor() { + super(Matcher.all(Enemy, Health)); + } + + protected onAdded(entity: Entity): void { + this.enemyCount++; + console.log(`Enemy joined battle, current enemy count: ${this.enemyCount}`); + + // Can set initial state for new enemies here + const health = entity.getComponent(Health); + if (health) { + health.current = health.max; + } + } + + protected onRemoved(entity: Entity): void { + this.enemyCount--; + console.log(`Enemy removed, remaining enemies: ${this.enemyCount}`); + + // Check if all enemies are defeated + if (this.enemyCount === 0) { + this.scene?.eventSystem.emitSync('all_enemies_defeated'); + } + } +} +``` + +### Important: Timing of onAdded/onRemoved Calls + +:::caution +`onAdded` and `onRemoved` callbacks are called **synchronously**, executing immediately **before** `addComponent`/`removeComponent` returns. +::: + +This means: + +```typescript +// ❌ Wrong: Chain assignment executes after onAdded +const comp = entity.addComponent(new ClickComponent()); +comp.element = this._element; // At this point onAdded has already executed! + +// ✅ Correct: Pass initial values through constructor +const comp = entity.addComponent(new ClickComponent(this._element)); + +// ✅ Or use the createComponent method +const comp = entity.createComponent(ClickComponent, this._element); +``` + +**Why this design?** + +The event-driven design ensures that `onAdded`/`onRemoved` callbacks are not affected by system registration order. When a component is added, all systems listening for that component receive notification immediately, rather than waiting until the next frame. + +**Best Practices:** + +1. Component initial values should be passed through the **constructor** +2. Don't rely on setting properties after `addComponent` returns +3. If you need to access component properties in `onAdded`, ensure those properties are set at construction time + +### Safely Modifying Components in process/lateProcess + +When iterating entities in `process` or `lateProcess`, you can safely add or remove components without affecting the current iteration: + +```typescript +@ECSSystem('Damage') +class DamageSystem extends EntitySystem { + constructor() { + super(Matcher.all(Health, DamageReceiver)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health); + const damage = entity.getComponent(DamageReceiver); + + if (health && damage) { + health.current -= damage.amount; + + // ✅ Safe: removing component won't affect current iteration + entity.removeComponent(damage); + + if (health.current <= 0) { + // ✅ Safe: adding component won't affect current iteration + entity.addComponent(new Dead()); + } + } + } + } +} +``` + +The framework creates a snapshot of the entity list before each `process`/`lateProcess` call, ensuring that component changes during iteration won't cause entities to be skipped or processed multiple times. + +## Event System Integration + +Systems can conveniently listen for and send events: + +```typescript +@ECSSystem('GameLogic') +class GameLogicSystem extends EntitySystem { + protected onInitialize(): void { + // Add event listeners (automatically cleaned up when system is destroyed) + this.addEventListener('player_died', this.onPlayerDied.bind(this)); + this.addEventListener('level_complete', this.onLevelComplete.bind(this)); + } + + private onPlayerDied(data: any): void { + console.log('Player died, restarting game'); + // Handle player death logic + } + + private onLevelComplete(data: any): void { + console.log('Level complete, loading next level'); + // Handle level completion logic + } + + protected process(entities: readonly Entity[]): void { + // Send events during processing + for (const entity of entities) { + const health = entity.getComponent(Health); + if (health && health.current <= 0) { + this.scene?.eventSystem.emitSync('entity_died', { entity }); + } + } + } +} +``` + +## Performance Monitoring + +Systems have built-in performance monitoring: + +```typescript +@ECSSystem('Performance') +class PerformanceSystem extends EntitySystem { + protected onEnd(): void { + // Get performance data + const perfData = this.getPerformanceData(); + if (perfData) { + console.log(`Execution time: ${perfData.executionTime.toFixed(2)}ms`); + } + + // Get performance statistics + const stats = this.getPerformanceStats(); + if (stats) { + console.log(`Average execution time: ${stats.averageTime.toFixed(2)}ms`); + } + } + + public resetPerformance(): void { + this.resetPerformanceData(); + } +} +``` + +## System Dependency Injection + +Systems implement the `IService` interface and support obtaining other services or systems through dependency injection: + +```typescript +import { ECSSystem, Injectable, InjectProperty } from '@esengine/ecs-framework'; + +@Injectable() +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + @InjectProperty(CollisionService) + private collision!: CollisionService; + + constructor() { + super(Matcher.all(Transform, RigidBody)); + } + + protected process(entities: readonly Entity[]): void { + // Use injected service + this.collision.detectCollisions(entities); + } + + // Implement IService interface dispose method + public dispose(): void { + // Clean up resources + } +} + +// Just pass the type when using, framework will auto-inject dependencies +class GameScene extends Scene { + protected initialize(): void { + // Automatic dependency injection + this.addEntityProcessor(PhysicsSystem); + } +} +``` + +Notes: +- Use `@Injectable()` decorator to mark systems that need dependency injection +- Use `@InjectProperty()` decorator to declare dependencies +- Systems must implement the `dispose()` method (IService interface requirement) +- Use `addEntityProcessor(Type)` instead of `addSystem(new Type())` to enable dependency injection diff --git a/docs/src/content/docs/en/guide/system/scheduling.md b/docs/src/content/docs/en/guide/system/scheduling.md new file mode 100644 index 00000000..e80feeb8 --- /dev/null +++ b/docs/src/content/docs/en/guide/system/scheduling.md @@ -0,0 +1,182 @@ +--- +title: "System Scheduling" +description: "Declarative system scheduling and execution stages" +--- + +> **v2.4.0+** + +In addition to manually controlling execution order with `updateOrder`, the framework provides a declarative system scheduling mechanism that lets you define execution order through dependencies. + +## Scheduling Decorators + +```typescript +import { EntitySystem, ECSSystem, Stage, Before, After, InSet } from '@esengine/ecs-framework'; + +// Use decorators to declare system scheduling +@ECSSystem('Movement') +@Stage('update') // Execute in update stage +@After('InputSystem') // Execute after InputSystem +@Before('RenderSystem') // Execute before RenderSystem +class MovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + // Movement logic + } +} + +// Use system sets for grouping +@ECSSystem('Physics') +@Stage('update') +@InSet('CoreSystems') // Belongs to CoreSystems set +class PhysicsSystem extends EntitySystem { + // ... +} + +@ECSSystem('Collision') +@Stage('update') +@After('set:CoreSystems') // Execute after all systems in CoreSystems set +class CollisionSystem extends EntitySystem { + // ... +} +``` + +## System Execution Stages + +The framework defines the following system execution stages, executed in order: + +| Stage | Description | Typical Usage | +|-------|-------------|---------------| +| `startup` | Startup stage | One-time initialization | +| `preUpdate` | Pre-update stage | Input handling, state preparation | +| `update` | Main update stage (default) | Core game logic | +| `postUpdate` | Post-update stage | Physics, collision detection | +| `cleanup` | Cleanup stage | Resource cleanup, state reset | + +### Stage Usage Example + +```typescript +@ECSSystem('Input') +@Stage('preUpdate') // Handle input in pre-update stage +class InputSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // Read input, update input components + } +} + +@ECSSystem('Movement') +@Stage('update') // Handle movement in main update stage +class MovementSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // Move entities based on input + } +} + +@ECSSystem('Physics') +@Stage('postUpdate') // Handle physics in post-update stage +class PhysicsSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // Physics simulation and collision detection + } +} + +@ECSSystem('Cleanup') +@Stage('cleanup') // Reset state in cleanup stage +class CleanupSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // Clean up temporary data + } +} +``` + +## Fluent API Configuration + +If you prefer not to use decorators, you can configure scheduling at runtime using the Fluent API: + +```typescript +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + + // Configure scheduling using Fluent API + this.stage('update') + .after('InputSystem') + .before('RenderSystem') + .inSet('CoreSystems'); + } +} +``` + +## System Sets + +System sets allow you to group related systems, then define dependencies based on the entire set: + +```typescript +// Define core systems set +@ECSSystem('Movement') +@InSet('CoreSystems') +class MovementSystem extends EntitySystem { } + +@ECSSystem('Physics') +@InSet('CoreSystems') +class PhysicsSystem extends EntitySystem { } + +@ECSSystem('AI') +@InSet('CoreSystems') +class AISystem extends EntitySystem { } + +// Execute after core systems set +@ECSSystem('Render') +@After('set:CoreSystems') +class RenderSystem extends EntitySystem { } + +// Execute before core systems set +@ECSSystem('Input') +@Before('set:CoreSystems') +class InputSystem extends EntitySystem { } +``` + +## Cycle Dependency Detection + +The framework automatically detects cyclic dependencies and throws clear errors: + +```typescript +// This will cause a cycle dependency error +@ECSSystem('SystemA') +@Before('SystemB') +class SystemA extends EntitySystem { } + +@ECSSystem('SystemB') +@Before('SystemA') // Error: A -> B -> A forms a cycle +class SystemB extends EntitySystem { } + +// Error message: Cyclic dependency detected: SystemA -> SystemB -> SystemA +``` + +## Scheduling Decorator Reference + +| Decorator | Description | Example | +|-----------|-------------|---------| +| `@Stage(name)` | Specify execution stage | `@Stage('update')` | +| `@Before(system)` | Execute before specified system | `@Before('RenderSystem')` | +| `@After(system)` | Execute after specified system | `@After('InputSystem')` | +| `@InSet(name)` | Join system set | `@InSet('CoreSystems')` | +| `@Before('set:name')` | Execute before set | `@Before('set:UI')` | +| `@After('set:name')` | Execute after set | `@After('set:Physics')` | + +## updateOrder vs Declarative Scheduling + +| Feature | updateOrder | Declarative Scheduling | +|---------|-------------|------------------------| +| Configuration | Manually set values | Declare dependencies | +| Readability | Need to remember value meanings | Directly express intent | +| Cycle detection | None | Automatic | +| Refactor-friendly | Manually adjust values | Auto-handles ordering | +| Use case | Simple projects | Complex dependencies | + +:::tip +For small projects, `updateOrder` is sufficient. When system count increases and dependencies become complex, declarative scheduling is recommended. +::: diff --git a/docs/src/content/docs/en/guide/system/types.md b/docs/src/content/docs/en/guide/system/types.md new file mode 100644 index 00000000..cdb8518c --- /dev/null +++ b/docs/src/content/docs/en/guide/system/types.md @@ -0,0 +1,200 @@ +--- +title: "System Types" +description: "EntitySystem, ProcessingSystem, PassiveSystem, IntervalSystem and other base classes" +--- + +The framework provides several different system base classes for different use cases. + +## EntitySystem - Base System + +The most basic system class, all other systems inherit from it: + +```typescript +import { EntitySystem, ECSSystem, Matcher } from '@esengine/ecs-framework'; + +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + // Use Matcher to define entity conditions to process + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const position = entity.getComponent(Position); + const velocity = entity.getComponent(Velocity); + + if (position && velocity) { + position.x += velocity.dx * Time.deltaTime; + position.y += velocity.dy * Time.deltaTime; + } + } + } +} +``` + +## ProcessingSystem - Processing System + +Suitable for systems that don't need to process entities individually: + +```typescript +@ECSSystem('Physics') +class PhysicsSystem extends ProcessingSystem { + constructor() { + super(); // No Matcher needed + } + + public processSystem(): void { + // Execute physics world step + this.physicsWorld.step(Time.deltaTime); + } +} +``` + +## PassiveSystem - Passive System + +Passive systems don't actively process, mainly used for listening to entity add and remove events: + +```typescript +@ECSSystem('EntityTracker') +class EntityTrackerSystem extends PassiveSystem { + constructor() { + super(Matcher.all(Health)); + } + + protected onAdded(entity: Entity): void { + console.log(`Health entity added: ${entity.name}`); + } + + protected onRemoved(entity: Entity): void { + console.log(`Health entity removed: ${entity.name}`); + } +} +``` + +## IntervalSystem - Interval System + +Systems that execute at fixed time intervals: + +```typescript +@ECSSystem('AutoSave') +class AutoSaveSystem extends IntervalSystem { + constructor() { + // Execute every 5 seconds + super(5.0, Matcher.all(SaveData)); + } + + protected process(entities: readonly Entity[]): void { + console.log('Executing auto save...'); + // Save game data + this.saveGameData(entities); + } + + private saveGameData(entities: readonly Entity[]): void { + // Save logic + } +} +``` + +## WorkerEntitySystem - Multi-threaded System + +A Web Worker-based multi-threaded processing system, suitable for compute-intensive tasks, capable of fully utilizing multi-core CPU performance. + +Worker systems provide true parallel computing capabilities, support SharedArrayBuffer optimization, and have automatic fallback support. Particularly suitable for physics simulation, particle systems, AI computation, and similar scenarios. + +**For detailed content, please refer to: [Worker System](/en/guide/worker-system)** + +## Entity Matcher + +Matcher is used to define which entities a system needs to process. It provides flexible condition combinations: + +### Basic Match Conditions + +```typescript +// Must have both Position and Velocity components +const matcher1 = Matcher.all(Position, Velocity); + +// Must have at least one of Health or Shield components +const matcher2 = Matcher.any(Health, Shield); + +// Must not have Dead component +const matcher3 = Matcher.none(Dead); +``` + +### Compound Match Conditions + +```typescript +// Complex combination conditions +const complexMatcher = Matcher.all(Position, Velocity) + .any(Player, Enemy) + .none(Dead, Disabled); + +@ECSSystem('Combat') +class CombatSystem extends EntitySystem { + constructor() { + super(complexMatcher); + } +} +``` + +### Special Match Conditions + +```typescript +// Match by tag +const tagMatcher = Matcher.byTag(1); // Match entities with tag 1 + +// Match by name +const nameMatcher = Matcher.byName("Player"); // Match entities named "Player" + +// Single component match +const componentMatcher = Matcher.byComponent(Health); // Match entities with Health component + +// Match no entities +const nothingMatcher = Matcher.nothing(); // For systems that only need lifecycle callbacks +``` + +### Empty Matcher vs Nothing Matcher + +```typescript +// empty() - Empty condition, matches all entities +const emptyMatcher = Matcher.empty(); + +// nothing() - Matches no entities, for systems that only need lifecycle methods +const nothingMatcher = Matcher.nothing(); + +// Use case: Systems that only need onBegin/onEnd lifecycle +@ECSSystem('FrameTimer') +class FrameTimerSystem extends EntitySystem { + constructor() { + super(Matcher.nothing()); // Process no entities + } + + protected onBegin(): void { + // Execute at the start of each frame + console.log('Frame started'); + } + + protected process(entities: readonly Entity[]): void { + // Never called because there are no matching entities + } + + protected onEnd(): void { + // Execute at the end of each frame + console.log('Frame ended'); + } +} +``` + +:::tip +For more details on Matcher and entity queries, please refer to the [Entity Query System](/en/guide/entity-query) documentation. +::: + +## System Type Selection Guide + +| System Type | Use Case | +|-------------|----------| +| `EntitySystem` | General system that processes matched entities one by one | +| `ProcessingSystem` | No entity list needed, only executes global logic | +| `PassiveSystem` | Only listens for entity add/remove events | +| `IntervalSystem` | Executes at fixed time intervals | +| `WorkerEntitySystem` | Compute-intensive tasks requiring multi-threading | diff --git a/docs/en/guide/time-and-timers.md b/docs/src/content/docs/en/guide/time-and-timers.md similarity index 99% rename from docs/en/guide/time-and-timers.md rename to docs/src/content/docs/en/guide/time-and-timers.md index de89d1f0..6114991e 100644 --- a/docs/en/guide/time-and-timers.md +++ b/docs/src/content/docs/en/guide/time-and-timers.md @@ -1,4 +1,6 @@ -# Time and Timer System +--- +title: "Time and Timer System" +--- The ECS framework provides a complete time management and timer system, including time scaling, frame time calculation, and flexible timer scheduling. diff --git a/docs/en/guide/worker-system.md b/docs/src/content/docs/en/guide/worker-system.md similarity index 99% rename from docs/en/guide/worker-system.md rename to docs/src/content/docs/en/guide/worker-system.md index 8305dfa8..95ff1527 100644 --- a/docs/en/guide/worker-system.md +++ b/docs/src/content/docs/en/guide/worker-system.md @@ -1,4 +1,6 @@ -# Worker System +--- +title: "Worker System" +--- The Worker System (WorkerEntitySystem) is a multi-threaded processing system based on Web Workers in the ECS framework. It's designed for compute-intensive tasks, fully utilizing multi-core CPU performance for true parallel computing. diff --git a/docs/src/content/docs/en/index.mdx b/docs/src/content/docs/en/index.mdx new file mode 100644 index 00000000..d0973717 --- /dev/null +++ b/docs/src/content/docs/en/index.mdx @@ -0,0 +1,67 @@ +--- +title: ESEngine +description: High-performance TypeScript ECS Framework for Game Development +template: splash +hero: + tagline: High-performance ECS game framework based on TypeScript, with multi-platform support and modular design + image: + file: ../../../assets/logo.svg + actions: + - text: Quick Start + link: /en/guide/getting-started/ + icon: right-arrow + variant: primary + - text: GitHub + link: https://github.com/esengine/esengine + icon: external +--- + +import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +## Core Features + + + + Data-driven entity component system supporting large-scale entity processing with cache-friendly memory layout. + + + 100% TypeScript with complete type definitions and compile-time checks for the best development experience. + + + Built-in AI behavior tree system with visual editor, custom nodes and real-time debugging support. + + + Supports browsers, Node.js, WeChat Mini Games, and integrates seamlessly with mainstream game engines. + + + Core features packaged independently. Import on demand with custom plugin extensions for flexible project adaptation. + + + Built-in performance monitoring, debugging tools, serialization system and complete development toolchain. + + + +## Quick Links + + + + + + + diff --git a/docs/en/modules/blueprint/index.md b/docs/src/content/docs/en/modules/blueprint/index.md similarity index 99% rename from docs/en/modules/blueprint/index.md rename to docs/src/content/docs/en/modules/blueprint/index.md index f32740b7..e0a1e6b5 100644 --- a/docs/en/modules/blueprint/index.md +++ b/docs/src/content/docs/en/modules/blueprint/index.md @@ -1,4 +1,6 @@ -# Blueprint Visual Scripting +--- +title: "Blueprint Visual Scripting" +--- `@esengine/blueprint` provides a full-featured visual scripting system supporting node-based programming, event-driven execution, and blueprint composition. diff --git a/docs/en/modules/fsm/index.md b/docs/src/content/docs/en/modules/fsm/index.md similarity index 99% rename from docs/en/modules/fsm/index.md rename to docs/src/content/docs/en/modules/fsm/index.md index 1fb09f8d..f6793896 100644 --- a/docs/en/modules/fsm/index.md +++ b/docs/src/content/docs/en/modules/fsm/index.md @@ -1,4 +1,6 @@ -# State Machine (FSM) +--- +title: "State Machine (FSM)" +--- `@esengine/fsm` provides a type-safe finite state machine implementation for characters, AI, or any scenario requiring state management. diff --git a/docs/en/modules/index.md b/docs/src/content/docs/en/modules/index.md similarity index 98% rename from docs/en/modules/index.md rename to docs/src/content/docs/en/modules/index.md index 08d7cb72..40e01106 100644 --- a/docs/en/modules/index.md +++ b/docs/src/content/docs/en/modules/index.md @@ -1,4 +1,6 @@ -# Modules +--- +title: "Modules" +--- ESEngine provides a rich set of modules that can be imported as needed. diff --git a/docs/en/modules/network/index.md b/docs/src/content/docs/en/modules/network/index.md similarity index 99% rename from docs/en/modules/network/index.md rename to docs/src/content/docs/en/modules/network/index.md index 8ef0c571..5d1df15e 100644 --- a/docs/en/modules/network/index.md +++ b/docs/src/content/docs/en/modules/network/index.md @@ -1,4 +1,6 @@ -# Network System +--- +title: "Network System" +--- `@esengine/network` provides a TSRPC-based client-server network synchronization solution for multiplayer games, including entity synchronization, input handling, and state interpolation. diff --git a/docs/en/modules/pathfinding/index.md b/docs/src/content/docs/en/modules/pathfinding/index.md similarity index 99% rename from docs/en/modules/pathfinding/index.md rename to docs/src/content/docs/en/modules/pathfinding/index.md index 21c319ad..a1422f4b 100644 --- a/docs/en/modules/pathfinding/index.md +++ b/docs/src/content/docs/en/modules/pathfinding/index.md @@ -1,4 +1,6 @@ -# Pathfinding System +--- +title: "Pathfinding System" +--- `@esengine/pathfinding` provides a complete 2D pathfinding solution including A* algorithm, grid maps, navigation meshes, and path smoothing. diff --git a/docs/en/modules/procgen/index.md b/docs/src/content/docs/en/modules/procgen/index.md similarity index 99% rename from docs/en/modules/procgen/index.md rename to docs/src/content/docs/en/modules/procgen/index.md index 6115f0f5..1b923a08 100644 --- a/docs/en/modules/procgen/index.md +++ b/docs/src/content/docs/en/modules/procgen/index.md @@ -1,4 +1,6 @@ -# Procedural Generation (Procgen) +--- +title: "Procedural Generation (Procgen)" +--- `@esengine/procgen` provides core tools for procedural content generation, including noise functions, seeded random numbers, and various random utilities. diff --git a/docs/en/modules/spatial/index.md b/docs/src/content/docs/en/modules/spatial/index.md similarity index 99% rename from docs/en/modules/spatial/index.md rename to docs/src/content/docs/en/modules/spatial/index.md index 407b7021..3df4752f 100644 --- a/docs/en/modules/spatial/index.md +++ b/docs/src/content/docs/en/modules/spatial/index.md @@ -1,4 +1,6 @@ -# Spatial Index System +--- +title: "Spatial Index System" +--- `@esengine/spatial` provides efficient spatial querying and indexing, including range queries, nearest neighbor queries, raycasting, and AOI (Area of Interest) management. diff --git a/docs/en/modules/timer/index.md b/docs/src/content/docs/en/modules/timer/index.md similarity index 99% rename from docs/en/modules/timer/index.md rename to docs/src/content/docs/en/modules/timer/index.md index 8a80ae53..a3009407 100644 --- a/docs/en/modules/timer/index.md +++ b/docs/src/content/docs/en/modules/timer/index.md @@ -1,4 +1,6 @@ -# Timer System +--- +title: "Timer System" +--- `@esengine/timer` provides a flexible timer and cooldown system for delayed execution, repeating tasks, skill cooldowns, and more. diff --git a/docs/examples/index.md b/docs/src/content/docs/examples/index.md similarity index 96% rename from docs/examples/index.md rename to docs/src/content/docs/examples/index.md index d6ebe7e3..b8cce211 100644 --- a/docs/examples/index.md +++ b/docs/src/content/docs/examples/index.md @@ -1,4 +1,6 @@ -# 示例 +--- +title: "示例" +--- 这里展示了ECS Framework的各种使用示例，通过实际的演示帮助您理解框架的功能和最佳实践。 diff --git a/docs/examples/worker-system-demo.md b/docs/src/content/docs/examples/worker-system-demo.md similarity index 94% rename from docs/examples/worker-system-demo.md rename to docs/src/content/docs/examples/worker-system-demo.md index 6e8bdc62..8451ba52 100644 --- a/docs/examples/worker-system-demo.md +++ b/docs/src/content/docs/examples/worker-system-demo.md @@ -1,4 +1,6 @@ -# Worker系统演示 +--- +title: "Worker系统演示" +--- 这是一个展示ECS框架Worker系统功能的交互式演示。 diff --git a/docs/src/content/docs/guide/component/best-practices.md b/docs/src/content/docs/guide/component/best-practices.md new file mode 100644 index 00000000..8854f0a5 --- /dev/null +++ b/docs/src/content/docs/guide/component/best-practices.md @@ -0,0 +1,312 @@ +--- +title: "最佳实践" +description: "组件设计模式和复杂示例" +--- + +## 设计原则 + +### 1. 保持组件简单 + +```typescript +// ✅ 好的组件设计 - 单一职责 +@ECSComponent('Position') +class Position extends Component { + x: number = 0; + y: number = 0; +} + +@ECSComponent('Velocity') +class Velocity extends Component { + dx: number = 0; + dy: number = 0; +} + +// ❌ 避免的组件设计 - 职责过多 +@ECSComponent('GameObject') +class GameObject extends Component { + x: number; + y: number; + dx: number; + dy: number; + health: number; + damage: number; + sprite: string; + // 太多不相关的属性 +} +``` + +### 2. 使用构造函数初始化 + +```typescript +@ECSComponent('Transform') +class Transform extends Component { + x: number; + y: number; + rotation: number; + scale: number; + + constructor(x = 0, y = 0, rotation = 0, scale = 1) { + super(); + this.x = x; + this.y = y; + this.rotation = rotation; + this.scale = scale; + } +} +``` + +### 3. 明确的类型定义 + +```typescript +interface InventoryItem { + id: string; + name: string; + quantity: number; + type: 'weapon' | 'consumable' | 'misc'; +} + +@ECSComponent('Inventory') +class Inventory extends Component { + items: InventoryItem[] = []; + maxSlots: number; + + constructor(maxSlots: number = 20) { + super(); + this.maxSlots = maxSlots; + } + + addItem(item: InventoryItem): boolean { + if (this.items.length < this.maxSlots) { + this.items.push(item); + return true; + } + return false; + } + + removeItem(itemId: string): InventoryItem | null { + const index = this.items.findIndex(item => item.id === itemId); + if (index !== -1) { + return this.items.splice(index, 1)[0]; + } + return null; + } +} +``` + +### 4. 引用其他实体 + +当组件需要关联其他实体时（如父子关系、跟随目标等），**推荐方式是存储实体ID**，然后在 System 中查找： + +```typescript +@ECSComponent('Follower') +class Follower extends Component { + targetId: number; + followDistance: number = 50; + + constructor(targetId: number) { + super(); + this.targetId = targetId; + } +} + +// 在 System 中查找目标实体并处理逻辑 +class FollowerSystem extends EntitySystem { + constructor() { + super(new Matcher().all(Follower, Position)); + } + + process(entities: readonly Entity[]): void { + for (const entity of entities) { + const follower = entity.getComponent(Follower)!; + const position = entity.getComponent(Position)!; + + // 通过场景查找目标实体 + const target = entity.scene?.findEntityById(follower.targetId); + if (target) { + const targetPos = target.getComponent(Position); + if (targetPos) { + // 跟随逻辑 + const dx = targetPos.x - position.x; + const dy = targetPos.y - position.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance > follower.followDistance) { + // 移动靠近目标 + } + } + } + } + } +} +``` + +这种方式的优势： +- 组件保持简单，只存储基本数据类型 +- 符合数据导向设计 +- 在 System 中统一处理查找和逻辑 +- 易于理解和维护 + +**避免在组件中直接存储实体引用**： + +```typescript +// ❌ 错误示范：直接存储实体引用 +@ECSComponent('BadFollower') +class BadFollower extends Component { + target: Entity; // 实体销毁后仍持有引用，可能导致内存泄漏 +} +``` + +## 复杂组件示例 + +### 状态机组件 + +```typescript +enum EntityState { + Idle, + Moving, + Attacking, + Dead +} + +@ECSComponent('StateMachine') +class StateMachine extends Component { + private _currentState: EntityState = EntityState.Idle; + private _previousState: EntityState = EntityState.Idle; + private _stateTimer: number = 0; + + get currentState(): EntityState { + return this._currentState; + } + + get previousState(): EntityState { + return this._previousState; + } + + get stateTimer(): number { + return this._stateTimer; + } + + changeState(newState: EntityState): void { + if (this._currentState !== newState) { + this._previousState = this._currentState; + this._currentState = newState; + this._stateTimer = 0; + } + } + + updateTimer(deltaTime: number): void { + this._stateTimer += deltaTime; + } + + isInState(state: EntityState): boolean { + return this._currentState === state; + } +} +``` + +### 配置数据组件 + +```typescript +interface WeaponData { + damage: number; + range: number; + fireRate: number; + ammo: number; +} + +@ECSComponent('WeaponConfig') +class WeaponConfig extends Component { + data: WeaponData; + + constructor(weaponData: WeaponData) { + super(); + this.data = { ...weaponData }; // 深拷贝避免共享引用 + } + + // 提供便捷的访问方法 + getDamage(): number { + return this.data.damage; + } + + canFire(): boolean { + return this.data.ammo > 0; + } + + consumeAmmo(): boolean { + if (this.data.ammo > 0) { + this.data.ammo--; + return true; + } + return false; + } +} +``` + +### 标签组件 + +```typescript +// 标签组件：无数据，仅用于标识 +@ECSComponent('Player') +class PlayerTag extends Component {} + +@ECSComponent('Enemy') +class EnemyTag extends Component {} + +@ECSComponent('Dead') +class DeadTag extends Component {} + +// 使用标签进行查询 +class EnemySystem extends EntitySystem { + constructor() { + super(Matcher.all(EnemyTag, Health).none(DeadTag)); + } +} +``` + +### 缓冲组件 + +```typescript +// 事件/命令缓冲组件 +@ECSComponent('DamageBuffer') +class DamageBuffer extends Component { + damages: { amount: number; source: number; timestamp: number }[] = []; + + addDamage(amount: number, sourceId: number): void { + this.damages.push({ + amount, + source: sourceId, + timestamp: Date.now() + }); + } + + clear(): void { + this.damages.length = 0; + } + + getTotalDamage(): number { + return this.damages.reduce((sum, d) => sum + d.amount, 0); + } +} +``` + +## 常见问题 + +### Q: 组件应该有多大？ + +**A**: 遵循单一职责原则。如果组件包含不相关的数据，拆分成多个组件。 + +### Q: 组件可以有方法吗？ + +**A**: 可以，但应该是数据相关的辅助方法（如 `isDead()`），而非业务逻辑。业务逻辑放在 System 中。 + +### Q: 如何处理组件间的依赖？ + +**A**: 在 System 中处理组件间交互，不要在组件内部直接访问其他组件。 + +### Q: 什么时候使用 EntityRef？ + +**A**: 仅在需要频繁访问引用实体且引用关系稳定时使用（如父子关系）。大多数情况存储 ID 更好。 + +--- + +组件是 ECS 架构的数据载体，正确设计组件能让你的游戏代码更模块化、可维护和高性能。 diff --git a/docs/src/content/docs/guide/component/entity-ref.md b/docs/src/content/docs/guide/component/entity-ref.md new file mode 100644 index 00000000..71774ce2 --- /dev/null +++ b/docs/src/content/docs/guide/component/entity-ref.md @@ -0,0 +1,228 @@ +--- +title: "EntityRef 装饰器" +description: "安全的实体引用追踪机制" +--- + +框架提供了 `@EntityRef` 装饰器用于**特殊场景**下安全地存储实体引用。这是一个高级特性，一般情况下推荐使用存储ID的方式。 + +## 什么时候需要 EntityRef？ + +在以下场景中，`@EntityRef` 可以简化代码： + +1. **父子关系**: 需要在组件中直接访问父实体或子实体 +2. **复杂关联**: 实体之间有多个引用关系 +3. **频繁访问**: 需要在多处访问引用的实体，使用ID查找会有性能开销 + +## 核心特性 + +`@EntityRef` 装饰器通过 **ReferenceTracker** 自动追踪引用关系： + +- 当被引用的实体销毁时，所有指向它的 `@EntityRef` 属性自动设为 `null` +- 防止跨场景引用（会输出警告并拒绝设置） +- 防止引用已销毁的实体（会输出警告并设为 `null`） +- 使用 WeakRef 避免内存泄漏（自动GC支持） +- 组件移除时自动清理引用注册 + +## 基本用法 + +```typescript +import { Component, ECSComponent, EntityRef, Entity } from '@esengine/ecs-framework'; + +@ECSComponent('Parent') +class ParentComponent extends Component { + @EntityRef() + parent: Entity | null = null; +} + +// 使用示例 +const scene = new Scene(); +const parent = scene.createEntity('Parent'); +const child = scene.createEntity('Child'); + +const comp = child.addComponent(new ParentComponent()); +comp.parent = parent; + +console.log(comp.parent); // Entity { name: 'Parent' } + +// 当 parent 被销毁时，comp.parent 自动变为 null +parent.destroy(); +console.log(comp.parent); // null +``` + +## 多个引用属性 + +一个组件可以有多个 `@EntityRef` 属性： + +```typescript +@ECSComponent('Combat') +class CombatComponent extends Component { + @EntityRef() + target: Entity | null = null; + + @EntityRef() + ally: Entity | null = null; + + @EntityRef() + lastAttacker: Entity | null = null; +} + +// 使用示例 +const player = scene.createEntity('Player'); +const enemy = scene.createEntity('Enemy'); +const npc = scene.createEntity('NPC'); + +const combat = player.addComponent(new CombatComponent()); +combat.target = enemy; +combat.ally = npc; + +// enemy 销毁后，只有 target 变为 null，ally 仍然有效 +enemy.destroy(); +console.log(combat.target); // null +console.log(combat.ally); // Entity { name: 'NPC' } +``` + +## 安全检查 + +`@EntityRef` 提供了多重安全检查： + +```typescript +const scene1 = new Scene(); +const scene2 = new Scene(); + +const entity1 = scene1.createEntity('Entity1'); +const entity2 = scene2.createEntity('Entity2'); + +const comp = entity1.addComponent(new ParentComponent()); + +// 跨场景引用会失败 +comp.parent = entity2; // 输出错误日志，comp.parent 为 null +console.log(comp.parent); // null + +// 引用已销毁的实体会失败 +const entity3 = scene1.createEntity('Entity3'); +entity3.destroy(); +comp.parent = entity3; // 输出警告日志，comp.parent 为 null +console.log(comp.parent); // null +``` + +## 实现原理 + +`@EntityRef` 使用以下机制实现自动引用追踪： + +1. **ReferenceTracker**: Scene 持有一个引用追踪器，记录所有实体引用关系 +2. **WeakRef**: 使用弱引用存储组件，避免循环引用导致内存泄漏 +3. **属性拦截**: 通过 `Object.defineProperty` 拦截 getter/setter +4. **自动清理**: 实体销毁时，ReferenceTracker 遍历所有引用并设为 null + +```typescript +// 简化的实现原理 +class ReferenceTracker { + // entityId -> 引用该实体的所有组件记录 + private _references: Map, propertyKey: string }>>; + + // 实体销毁时调用 + clearReferencesTo(entityId: number): void { + const records = this._references.get(entityId); + if (records) { + for (const record of records) { + const component = record.component.deref(); + if (component) { + // 将组件的引用属性设为 null + (component as any)[record.propertyKey] = null; + } + } + this._references.delete(entityId); + } + } +} +``` + +## 性能考虑 + +`@EntityRef` 会带来一些性能开销： + +- **写入开销**: 每次设置引用时需要更新 ReferenceTracker +- **内存开销**: ReferenceTracker 需要维护引用映射表 +- **销毁开销**: 实体销毁时需要遍历所有引用并清理 + +对于大多数场景，这些开销是可以接受的。但如果有**大量实体和频繁的引用变更**，存储ID可能更高效。 + +## 调试支持 + +ReferenceTracker 提供了调试接口： + +```typescript +// 查看某个实体被哪些组件引用 +const references = scene.referenceTracker.getReferencesTo(entity.id); +console.log(`实体 ${entity.name} 被 ${references.length} 个组件引用`); + +// 获取完整的调试信息 +const debugInfo = scene.referenceTracker.getDebugInfo(); +console.log(debugInfo); +``` + +## 与存储 ID 方式的对比 + +### 存储 ID（推荐大多数情况） + +```typescript +@ECSComponent('Follower') +class Follower extends Component { + targetId: number | null = null; +} + +// 在 System 中查找 +class FollowerSystem extends EntitySystem { + process(entities: readonly Entity[]): void { + for (const entity of entities) { + const follower = entity.getComponent(Follower)!; + const target = entity.scene?.findEntityById(follower.targetId); + if (target) { + // 跟随逻辑 + } + } + } +} +``` + +### 使用 EntityRef（适合复杂关联） + +```typescript +@ECSComponent('Transform') +class Transform extends Component { + @EntityRef() + parent: Entity | null = null; + + position: { x: number, y: number } = { x: 0, y: 0 }; + + // 可以直接访问父实体的组件 + getWorldPosition(): { x: number, y: number } { + if (!this.parent) { + return { ...this.position }; + } + + const parentTransform = this.parent.getComponent(Transform); + if (parentTransform) { + const parentPos = parentTransform.getWorldPosition(); + return { + x: parentPos.x + this.position.x, + y: parentPos.y + this.position.y + }; + } + + return { ...this.position }; + } +} +``` + +## 总结 + +| 方式 | 适用场景 | 优点 | 缺点 | +|------|----------|------|------| +| 存储 ID | 大多数情况 | 简单、无额外开销 | 需要在 System 中查找 | +| @EntityRef | 父子关系、复杂关联 | 自动清理、代码简洁 | 有性能开销 | + +- **推荐做法**: 大部分情况使用存储ID + System查找的方式 +- **EntityRef 适用场景**: 父子关系、复杂关联、组件内需要直接访问引用实体的场景 +- **核心优势**: 自动清理、防止悬空引用、代码更简洁 +- **注意事项**: 有性能开销，不适合大量动态引用的场景 diff --git a/docs/src/content/docs/guide/component/index.md b/docs/src/content/docs/guide/component/index.md new file mode 100644 index 00000000..11d27622 --- /dev/null +++ b/docs/src/content/docs/guide/component/index.md @@ -0,0 +1,226 @@ +--- +title: "组件系统" +description: "ECS 组件基础概念和创建方法" +--- + +在 ECS 架构中，组件（Component）是数据和行为的载体。组件定义了实体具有的属性和功能，是 ECS 架构的核心构建块。 + +## 基本概念 + +组件是继承自 `Component` 抽象基类的具体类，用于： +- 存储实体的数据（如位置、速度、健康值等） +- 定义与数据相关的行为方法 +- 提供生命周期回调钩子 +- 支持序列化和调试 + +## 创建组件 + +### 基础组件定义 + +```typescript +import { Component, ECSComponent } from '@esengine/ecs-framework'; + +@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; + } +} + +@ECSComponent('Health') +class Health extends Component { + current: number; + max: number; + + constructor(max: number = 100) { + super(); + this.max = max; + this.current = max; + } + + // 组件可以包含行为方法 + takeDamage(damage: number): void { + this.current = Math.max(0, this.current - damage); + } + + heal(amount: number): void { + this.current = Math.min(this.max, this.current + amount); + } + + isDead(): boolean { + return this.current <= 0; + } +} +``` + +## @ECSComponent 装饰器 + +`@ECSComponent` 是组件类必须使用的装饰器，它为组件提供了类型标识和元数据管理。 + +### 为什么必须使用 + +| 功能 | 说明 | +|------|------| +| **类型识别** | 提供稳定的类型名称，代码混淆后仍能正确识别 | +| **序列化支持** | 序列化/反序列化时使用该名称作为类型标识 | +| **组件注册** | 自动注册到 ComponentRegistry，分配唯一的位掩码 | +| **调试支持** | 在调试工具和日志中显示可读的组件名称 | + +### 基本语法 + +```typescript +@ECSComponent(typeName: string) +``` + +- `typeName`: 组件的类型名称，建议使用与类名相同或相近的名称 + +### 使用示例 + +```typescript +// ✅ 正确的用法 +@ECSComponent('Velocity') +class Velocity extends Component { + dx: number = 0; + dy: number = 0; +} + +// ✅ 推荐：类型名与类名保持一致 +@ECSComponent('PlayerController') +class PlayerController extends Component { + speed: number = 5; +} + +// ❌ 错误的用法 - 没有装饰器 +class BadComponent extends Component { + // 这样定义的组件可能在生产环境出现问题： + // 1. 代码压缩后类名变化，无法正确序列化 + // 2. 组件未注册到框架，查询和匹配可能失效 +} +``` + +### 与 @Serializable 配合使用 + +当组件需要支持序列化时，`@ECSComponent` 和 `@Serializable` 需要一起使用： + +```typescript +import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework'; + +@ECSComponent('Player') +@Serializable({ version: 1 }) +class PlayerComponent extends Component { + @Serialize() + name: string = ''; + + @Serialize() + level: number = 1; + + // 不使用 @Serialize() 的字段不会被序列化 + private _cachedData: any = null; +} +``` + +> **注意**：`@ECSComponent` 的 `typeName` 和 `@Serializable` 的 `typeId` 可以不同。如果 `@Serializable` 没有指定 `typeId`，则默认使用 `@ECSComponent` 的 `typeName`。 + +### 组件类型名的唯一性 + +每个组件的类型名应该是唯一的： + +```typescript +// ❌ 错误：两个组件使用相同的类型名 +@ECSComponent('Health') +class HealthComponent extends Component { } + +@ECSComponent('Health') // 冲突！ +class EnemyHealthComponent extends Component { } + +// ✅ 正确：使用不同的类型名 +@ECSComponent('PlayerHealth') +class PlayerHealthComponent extends Component { } + +@ECSComponent('EnemyHealth') +class EnemyHealthComponent extends Component { } +``` + +## 组件属性 + +每个组件都有一些内置属性： + +```typescript +@ECSComponent('ExampleComponent') +class ExampleComponent extends Component { + someData: string = "example"; + + onAddedToEntity(): void { + console.log(`组件ID: ${this.id}`); // 唯一的组件ID + console.log(`所属实体ID: ${this.entityId}`); // 所属实体的ID + } +} +``` + +## 组件与实体的关系 + +组件存储了所属实体的ID (`entityId`)，而不是直接引用实体对象。这是ECS数据导向设计的体现，避免了循环引用。 + +在实际使用中，**应该在 System 中处理实体和组件的交互**，而不是在组件内部： + +```typescript +@ECSComponent('Health') +class Health extends Component { + current: number; + max: number; + + constructor(max: number = 100) { + super(); + this.max = max; + this.current = max; + } + + isDead(): boolean { + return this.current <= 0; + } +} + +@ECSComponent('Damage') +class Damage extends Component { + value: number; + + constructor(value: number) { + super(); + this.value = value; + } +} + +// 推荐：在 System 中处理逻辑 +class DamageSystem extends EntitySystem { + constructor() { + super(new Matcher().all(Health, Damage)); + } + + process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health)!; + const damage = entity.getComponent(Damage)!; + + health.current -= damage.value; + + if (health.isDead()) { + entity.destroy(); + } + + // 应用伤害后移除 Damage 组件 + entity.removeComponent(damage); + } + } +} +``` + +## 更多主题 + +- [生命周期](/guide/component/lifecycle) - 组件生命周期钩子 +- [EntityRef 装饰器](/guide/component/entity-ref) - 安全的实体引用 +- [最佳实践](/guide/component/best-practices) - 组件设计模式和示例 diff --git a/docs/src/content/docs/guide/component/lifecycle.md b/docs/src/content/docs/guide/component/lifecycle.md new file mode 100644 index 00000000..423f8d89 --- /dev/null +++ b/docs/src/content/docs/guide/component/lifecycle.md @@ -0,0 +1,182 @@ +--- +title: "组件生命周期" +description: "组件的生命周期钩子和事件" +--- + +组件提供了生命周期钩子，可以重写来执行特定的逻辑。 + +## 生命周期方法 + +```typescript +@ECSComponent('ExampleComponent') +class ExampleComponent extends Component { + private resource: SomeResource | null = null; + + /** + * 组件被添加到实体时调用 + * 用于初始化资源、建立引用等 + */ + onAddedToEntity(): void { + console.log(`组件 ${this.constructor.name} 已添加，实体ID: ${this.entityId}`); + this.resource = new SomeResource(); + } + + /** + * 组件从实体移除时调用 + * 用于清理资源、断开引用等 + */ + onRemovedFromEntity(): void { + console.log(`组件 ${this.constructor.name} 已移除`); + if (this.resource) { + this.resource.cleanup(); + this.resource = null; + } + } +} +``` + +## 生命周期顺序 + +``` +实体创建 + ↓ +addComponent() 调用 + ↓ +onAddedToEntity() 触发 + ↓ +组件正常使用中... + ↓ +removeComponent() 或 entity.destroy() 调用 + ↓ +onRemovedFromEntity() 触发 + ↓ +组件被移除/销毁 +``` + +## 实际用例 + +### 资源管理 + +```typescript +@ECSComponent('TextureComponent') +class TextureComponent extends Component { + private _texture: Texture | null = null; + texturePath: string = ''; + + onAddedToEntity(): void { + // 加载纹理资源 + this._texture = TextureManager.load(this.texturePath); + } + + onRemovedFromEntity(): void { + // 释放纹理资源 + if (this._texture) { + TextureManager.release(this._texture); + this._texture = null; + } + } + + get texture(): Texture | null { + return this._texture; + } +} +``` + +### 事件监听 + +```typescript +@ECSComponent('InputListener') +class InputListener extends Component { + private _boundHandler: ((e: KeyboardEvent) => void) | null = null; + + onAddedToEntity(): void { + this._boundHandler = this.handleKeyDown.bind(this); + window.addEventListener('keydown', this._boundHandler); + } + + onRemovedFromEntity(): void { + if (this._boundHandler) { + window.removeEventListener('keydown', this._boundHandler); + this._boundHandler = null; + } + } + + private handleKeyDown(e: KeyboardEvent): void { + // 处理键盘输入 + } +} +``` + +### 注册到外部系统 + +```typescript +@ECSComponent('PhysicsBody') +class PhysicsBody extends Component { + private _body: PhysicsWorld.Body | null = null; + + onAddedToEntity(): void { + // 在物理世界中创建刚体 + this._body = PhysicsWorld.createBody({ + entityId: this.entityId, + type: 'dynamic' + }); + } + + onRemovedFromEntity(): void { + // 从物理世界移除刚体 + if (this._body) { + PhysicsWorld.removeBody(this._body); + this._body = null; + } + } +} +``` + +## 注意事项 + +### 避免在生命周期中访问其他组件 + +```typescript +@ECSComponent('BadComponent') +class BadComponent extends Component { + onAddedToEntity(): void { + // ⚠️ 不推荐：此时其他组件可能还未添加 + const other = this.entity?.getComponent(OtherComponent); + if (other) { + // 可能为 null + } + } +} +``` + +### 推荐：使用 System 处理组件间交互 + +```typescript +@ECSSystem('InitializationSystem') +class InitializationSystem extends EntitySystem { + constructor() { + super(Matcher.all(ComponentA, ComponentB)); + } + + // 使用 onAdded 事件，确保两个组件都存在 + onAdded(entity: Entity): void { + const a = entity.getComponent(ComponentA)!; + const b = entity.getComponent(ComponentB)!; + // 安全地初始化交互 + a.linkTo(b); + } + + onRemoved(entity: Entity): void { + // 清理 + } +} +``` + +## 与 System 生命周期的对比 + +| 特性 | 组件生命周期 | System 生命周期 | +|------|-------------|----------------| +| 触发时机 | 组件添加/移除时 | 匹配条件满足时 | +| 适用场景 | 资源初始化/清理 | 业务逻辑处理 | +| 访问其他组件 | 不推荐 | 安全 | +| 访问 Scene | 有限 | 完整 | diff --git a/docs/src/content/docs/guide/entity-query/best-practices.md b/docs/src/content/docs/guide/entity-query/best-practices.md new file mode 100644 index 00000000..c3a93014 --- /dev/null +++ b/docs/src/content/docs/guide/entity-query/best-practices.md @@ -0,0 +1,225 @@ +--- +title: "最佳实践" +description: "实体查询优化和实际应用场景" +--- + +## 设计原则 + +### 1. 优先使用 EntitySystem + +```typescript +// ✅ 推荐: 使用 EntitySystem +class GoodSystem extends EntitySystem { + constructor() { + super(Matcher.empty().all(HealthComponent)); + } + + protected process(entities: readonly Entity[]): void { + // 自动获得符合条件的实体，每帧自动更新 + } +} + +// ❌ 不推荐: 在 update 中手动查询 +class BadSystem extends EntitySystem { + constructor() { + super(Matcher.empty()); + } + + protected process(entities: readonly Entity[]): void { + // 每帧手动查询，浪费性能 + const result = this.scene!.querySystem.queryAll(HealthComponent); + for (const entity of result.entities) { + // ... + } + } +} +``` + +### 2. 合理使用 none() 排除条件 + +```typescript +// 排除已死亡的敌人 +class EnemyAISystem extends EntitySystem { + constructor() { + super( + Matcher.empty() + .all(EnemyTag, AIComponent) + .none(DeadTag) // 不处理死亡的敌人 + ); + } +} +``` + +### 3. 使用标签优化查询 + +```typescript +// ❌ 不好: 查询所有实体再过滤 +const allEntities = scene.querySystem.getAllEntities(); +const players = allEntities.filter(e => e.hasComponent(PlayerTag)); + +// ✅ 好: 直接按标签查询 +const players = scene.querySystem.queryByTag(Tags.PLAYER).entities; +``` + +### 4. 避免过于复杂的查询条件 + +```typescript +// ❌ 不推荐: 过于复杂 +super( + Matcher.empty() + .all(A, B, C, D) + .any(E, F, G) + .none(H, I, J) +); + +// ✅ 推荐: 拆分成多个简单系统 +class SystemAB extends EntitySystem { + constructor() { + super(Matcher.empty().all(A, B)); + } +} + +class SystemCD extends EntitySystem { + constructor() { + super(Matcher.empty().all(C, D)); + } +} +``` + +## 实际应用场景 + +### 场景1: 物理系统 + +```typescript +class PhysicsSystem extends EntitySystem { + constructor() { + super(Matcher.empty().all(TransformComponent, RigidbodyComponent)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const transform = entity.getComponent(TransformComponent)!; + const rigidbody = entity.getComponent(RigidbodyComponent)!; + + // 应用重力 + rigidbody.velocity.y -= 9.8 * Time.deltaTime; + + // 更新位置 + transform.position.x += rigidbody.velocity.x * Time.deltaTime; + transform.position.y += rigidbody.velocity.y * Time.deltaTime; + } + } +} +``` + +### 场景2: 渲染系统 + +```typescript +class RenderSystem extends EntitySystem { + constructor() { + super( + Matcher.empty() + .all(TransformComponent, SpriteComponent) + .none(InvisibleTag) // 排除不可见实体 + ); + } + + protected process(entities: readonly Entity[]): void { + // 按 z-order 排序 + const sorted = entities.slice().sort((a, b) => { + const zA = a.getComponent(TransformComponent)!.z; + const zB = b.getComponent(TransformComponent)!.z; + return zA - zB; + }); + + // 渲染实体 + for (const entity of sorted) { + const transform = entity.getComponent(TransformComponent)!; + const sprite = entity.getComponent(SpriteComponent)!; + + renderer.drawSprite(sprite.texture, transform.position); + } + } +} +``` + +### 场景3: 碰撞检测 + +```typescript +class CollisionSystem extends EntitySystem { + constructor() { + super(Matcher.empty().all(TransformComponent, ColliderComponent)); + } + + protected process(entities: readonly Entity[]): void { + // 简单的 O(n²) 碰撞检测 + for (let i = 0; i < entities.length; i++) { + for (let j = i + 1; j < entities.length; j++) { + this.checkCollision(entities[i], entities[j]); + } + } + } + + private checkCollision(a: Entity, b: Entity): void { + const transA = a.getComponent(TransformComponent)!; + const transB = b.getComponent(TransformComponent)!; + const colliderA = a.getComponent(ColliderComponent)!; + const colliderB = b.getComponent(ColliderComponent)!; + + if (this.isOverlapping(transA, colliderA, transB, colliderB)) { + // 触发碰撞事件 + scene.eventSystem.emit('collision', { entityA: a, entityB: b }); + } + } +} +``` + +### 场景4: 一次性查询 + +```typescript +// 在系统外部执行一次性查询 +class GameManager { + private scene: Scene; + + public countEnemies(): number { + const result = this.scene.querySystem.queryByTag(Tags.ENEMY); + return result.count; + } + + public findNearestEnemy(playerPos: Vector2): Entity | null { + const enemies = this.scene.querySystem.queryByTag(Tags.ENEMY); + + let nearest: Entity | null = null; + let minDistance = Infinity; + + for (const enemy of enemies.entities) { + const transform = enemy.getComponent(TransformComponent); + if (!transform) continue; + + const distance = Vector2.distance(playerPos, transform.position); + if (distance < minDistance) { + minDistance = distance; + nearest = enemy; + } + } + + return nearest; + } +} +``` + +## 性能统计 + +```typescript +const stats = querySystem.getStats(); +console.log('总查询次数:', stats.queryStats.totalQueries); +console.log('缓存命中率:', stats.queryStats.cacheHitRate); +console.log('缓存大小:', stats.cacheStats.size); +``` + +## 相关 API + +- [Matcher](/api/classes/Matcher/) - 查询条件描述符 API 参考 +- [QuerySystem](/api/classes/QuerySystem/) - 查询系统 API 参考 +- [EntitySystem](/api/classes/EntitySystem/) - 实体系统 API 参考 +- [Entity](/api/classes/Entity/) - 实体 API 参考 diff --git a/docs/src/content/docs/guide/entity-query/compiled-query.md b/docs/src/content/docs/guide/entity-query/compiled-query.md new file mode 100644 index 00000000..a123c35e --- /dev/null +++ b/docs/src/content/docs/guide/entity-query/compiled-query.md @@ -0,0 +1,133 @@ +--- +title: "编译查询" +description: "CompiledQuery 类型安全查询工具" +--- + +> **v2.4.0+** + +CompiledQuery 是一个轻量级的查询工具，提供类型安全的组件访问和变更检测支持。适合临时查询、工具开发和简单的迭代场景。 + +## 基本用法 + +```typescript +// 创建编译查询 +const query = scene.querySystem.compile(Position, Velocity); + +// 类型安全的遍历 - 组件参数自动推断类型 +query.forEach((entity, pos, vel) => { + pos.x += vel.vx * deltaTime; + pos.y += vel.vy * deltaTime; +}); + +// 获取实体数量 +console.log(`匹配实体数: ${query.count}`); + +// 获取第一个匹配的实体 +const first = query.first(); +if (first) { + const [entity, pos, vel] = first; + console.log(`第一个实体: ${entity.name}`); +} +``` + +## 变更检测 + +CompiledQuery 支持基于 epoch 的变更检测： + +```typescript +class RenderSystem extends EntitySystem { + private _query: CompiledQuery<[typeof Transform, typeof Sprite]>; + private _lastEpoch = 0; + + protected onInitialize(): void { + this._query = this.scene!.querySystem.compile(Transform, Sprite); + } + + protected process(entities: readonly Entity[]): void { + // 只处理 Transform 或 Sprite 发生变化的实体 + this._query.forEachChanged(this._lastEpoch, (entity, transform, sprite) => { + this.updateRenderData(entity, transform, sprite); + }); + + // 保存当前 epoch 作为下次检查的起点 + this._lastEpoch = this.scene!.epochManager.current; + } + + private updateRenderData(entity: Entity, transform: Transform, sprite: Sprite): void { + // 更新渲染数据 + } +} +``` + +## 函数式 API + +CompiledQuery 提供了丰富的函数式 API： + +```typescript +const query = scene.querySystem.compile(Position, Health); + +// map - 转换实体数据 +const positions = query.map((entity, pos, health) => ({ + x: pos.x, + y: pos.y, + healthPercent: health.current / health.max +})); + +// filter - 过滤实体 +const lowHealthEntities = query.filter((entity, pos, health) => { + return health.current < health.max * 0.2; +}); + +// find - 查找第一个匹配的实体 +const target = query.find((entity, pos, health) => { + return health.current > 0 && pos.x > 100; +}); + +// toArray - 转换为数组 +const allData = query.toArray(); +for (const [entity, pos, health] of allData) { + console.log(`${entity.name}: ${pos.x}, ${pos.y}`); +} + +// any/empty - 检查是否有匹配 +if (query.any()) { + console.log('有匹配的实体'); +} +if (query.empty()) { + console.log('没有匹配的实体'); +} +``` + +## CompiledQuery vs EntitySystem + +| 特性 | CompiledQuery | EntitySystem | +|------|---------------|--------------| +| **用途** | 轻量级查询工具 | 完整的系统逻辑 | +| **生命周期** | 无 | 完整 (onInitialize, onDestroy 等) | +| **调度集成** | 无 | 支持 @Stage, @Before, @After | +| **变更检测** | forEachChanged | forEachChanged | +| **事件监听** | 无 | addEventListener | +| **命令缓冲** | 无 | this.commands | +| **类型安全组件** | forEach 参数自动推断 | 需要手动 getComponent | +| **适用场景** | 临时查询、工具、原型 | 核心游戏逻辑 | + +**选择建议**： + +- 使用 **EntitySystem** 处理核心游戏逻辑（移动、战斗、AI 等） +- 使用 **CompiledQuery** 进行一次性查询、工具开发或简单迭代 + +## API 参考 + +| 方法 | 说明 | +|------|------| +| `forEach(callback)` | 遍历所有匹配实体，类型安全的组件参数 | +| `forEachChanged(sinceEpoch, callback)` | 只遍历变更的实体 | +| `first()` | 获取第一个匹配的实体和组件 | +| `toArray()` | 转换为 [entity, ...components] 数组 | +| `map(callback)` | 映射转换 | +| `filter(predicate)` | 过滤实体 | +| `find(predicate)` | 查找第一个满足条件的实体 | +| `any()` | 是否有任何匹配 | +| `empty()` | 是否没有匹配 | +| `count` | 匹配的实体数量 | +| `entities` | 匹配的实体列表（只读） | diff --git a/docs/src/content/docs/guide/entity-query/index.md b/docs/src/content/docs/guide/entity-query/index.md new file mode 100644 index 00000000..fa7ec9df --- /dev/null +++ b/docs/src/content/docs/guide/entity-query/index.md @@ -0,0 +1,244 @@ +--- +title: "实体查询系统" +description: "ECS 实体查询核心概念和基础用法" +--- + +实体查询是 ECS 架构的核心功能之一。本指南将介绍如何使用 Matcher 和 QuerySystem 来查询和筛选实体。 + +## 核心概念 + +### Matcher - 查询条件描述符 + +Matcher 是一个链式 API，用于描述实体查询条件。它本身不执行查询，而是作为条件传递给 EntitySystem 或 QuerySystem。 + +### QuerySystem - 查询执行引擎 + +QuerySystem 负责实际执行查询，内部使用响应式查询机制自动优化性能。 + +## 在 EntitySystem 中使用 Matcher + +这是最常见的使用方式。EntitySystem 通过 Matcher 自动筛选和处理符合条件的实体。 + +### 基础用法 + +```typescript +import { EntitySystem, Matcher, Entity, Component } from '@esengine/ecs-framework'; + +class PositionComponent extends Component { + public x: number = 0; + public y: number = 0; +} + +class VelocityComponent extends Component { + public vx: number = 0; + public vy: number = 0; +} + +class MovementSystem extends EntitySystem { + constructor() { + // 方式1: 使用 Matcher.empty().all() + super(Matcher.empty().all(PositionComponent, VelocityComponent)); + + // 方式2: 直接使用 Matcher.all() (等价) + // super(Matcher.all(PositionComponent, VelocityComponent)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const pos = entity.getComponent(PositionComponent)!; + const vel = entity.getComponent(VelocityComponent)!; + + pos.x += vel.vx; + pos.y += vel.vy; + } + } +} + +// 添加到场景 +scene.addEntityProcessor(new MovementSystem()); +``` + +### Matcher 链式 API + +#### all() - 必须包含所有组件 + +```typescript +class HealthSystem extends EntitySystem { + constructor() { + // 实体必须同时拥有 Health 和 Position 组件 + super(Matcher.empty().all(HealthComponent, PositionComponent)); + } + + protected process(entities: readonly Entity[]): void { + // 只处理同时拥有两个组件的实体 + } +} +``` + +#### any() - 至少包含一个组件 + +```typescript +class DamageableSystem extends EntitySystem { + constructor() { + // 实体至少拥有 Health 或 Shield 其中之一 + super(Matcher.any(HealthComponent, ShieldComponent)); + } + + protected process(entities: readonly Entity[]): void { + // 处理拥有生命值或护盾的实体 + } +} +``` + +#### none() - 不能包含指定组件 + +```typescript +class AliveEntitySystem extends EntitySystem { + constructor() { + // 实体不能拥有 DeadTag 组件 + super(Matcher.all(HealthComponent).none(DeadTag)); + } + + protected process(entities: readonly Entity[]): void { + // 只处理活着的实体 + } +} +``` + +#### 组合条件 + +```typescript +class CombatSystem extends EntitySystem { + constructor() { + super( + Matcher.empty() + .all(PositionComponent, HealthComponent) // 必须有位置和生命 + .any(WeaponComponent, MagicComponent) // 至少有武器或魔法 + .none(DeadTag, FrozenTag) // 不能是死亡或冰冻状态 + ); + } + + protected process(entities: readonly Entity[]): void { + // 处理可以战斗的活着的实体 + } +} +``` + +#### nothing() - 不匹配任何实体 + +用于创建只需要生命周期方法（`onBegin`、`onEnd`）但不需要处理实体的系统。 + +```typescript +class FrameTimerSystem extends EntitySystem { + constructor() { + // 不匹配任何实体 + super(Matcher.nothing()); + } + + protected onBegin(): void { + // 每帧开始时执行 + Performance.markFrameStart(); + } + + protected process(entities: readonly Entity[]): void { + // 永远不会被调用，因为没有匹配的实体 + } + + protected onEnd(): void { + // 每帧结束时执行 + Performance.markFrameEnd(); + } +} +``` + +#### empty() vs nothing() 的区别 + +| 方法 | 行为 | 使用场景 | +|------|------|----------| +| `Matcher.empty()` | 匹配**所有**实体 | 需要处理场景中所有实体 | +| `Matcher.nothing()` | 不匹配**任何**实体 | 只需要生命周期回调，不处理实体 | + +## 直接使用 QuerySystem + +如果不需要创建系统，可以直接使用 Scene 的 querySystem 进行查询。 + +### 基础查询方法 + +```typescript +// 获取场景的查询系统 +const querySystem = scene.querySystem; + +// 查询拥有所有指定组件的实体 +const result1 = querySystem.queryAll(PositionComponent, VelocityComponent); +console.log(`找到 ${result1.count} 个移动实体`); +console.log(`查询耗时: ${result1.executionTime.toFixed(2)}ms`); + +// 查询拥有任意指定组件的实体 +const result2 = querySystem.queryAny(WeaponComponent, MagicComponent); +console.log(`找到 ${result2.count} 个战斗单位`); + +// 查询不包含指定组件的实体 +const result3 = querySystem.queryNone(DeadTag); +console.log(`找到 ${result3.count} 个活着的实体`); +``` + +### 按标签和名称查询 + +```typescript +// 按标签查询 +const playerResult = querySystem.queryByTag(Tags.PLAYER); +for (const player of playerResult.entities) { + console.log('玩家:', player.name); +} + +// 按名称查询 +const bossResult = querySystem.queryByName('Boss'); +if (bossResult.count > 0) { + const boss = bossResult.entities[0]; + console.log('找到Boss:', boss); +} + +// 按单个组件查询 +const healthResult = querySystem.queryByComponent(HealthComponent); +console.log(`有 ${healthResult.count} 个实体拥有生命值`); +``` + +## 性能优化 + +### 自动缓存 + +QuerySystem 内部使用响应式查询自动缓存结果，相同的查询条件会直接使用缓存： + +```typescript +// 第一次查询，执行实际查询 +const result1 = querySystem.queryAll(PositionComponent); +console.log('fromCache:', result1.fromCache); // false + +// 第二次相同查询，使用缓存 +const result2 = querySystem.queryAll(PositionComponent); +console.log('fromCache:', result2.fromCache); // true +``` + +### 实体变化自动更新 + +当实体添加/移除组件时，查询缓存会自动更新： + +```typescript +// 查询拥有武器的实体 +const before = querySystem.queryAll(WeaponComponent); +console.log('之前:', before.count); // 假设为 5 + +// 给实体添加武器 +const enemy = scene.createEntity('Enemy'); +enemy.addComponent(new WeaponComponent()); + +// 再次查询，自动包含新实体 +const after = querySystem.queryAll(WeaponComponent); +console.log('之后:', after.count); // 现在是 6 +``` + +## 更多主题 + +- [Matcher API](/guide/entity-query/matcher-api) - 完整的 Matcher API 参考 +- [编译查询](/guide/entity-query/compiled-query) - CompiledQuery 高级用法 +- [最佳实践](/guide/entity-query/best-practices) - 查询优化和实际应用 diff --git a/docs/src/content/docs/guide/entity-query/matcher-api.md b/docs/src/content/docs/guide/entity-query/matcher-api.md new file mode 100644 index 00000000..34472558 --- /dev/null +++ b/docs/src/content/docs/guide/entity-query/matcher-api.md @@ -0,0 +1,118 @@ +--- +title: "Matcher API" +description: "Matcher 完整 API 参考" +--- + +## 静态创建方法 + +| 方法 | 说明 | 示例 | +|------|------|------| +| `Matcher.all(...types)` | 必须包含所有指定组件 | `Matcher.all(Position, Velocity)` | +| `Matcher.any(...types)` | 至少包含一个指定组件 | `Matcher.any(Health, Shield)` | +| `Matcher.none(...types)` | 不能包含任何指定组件 | `Matcher.none(Dead)` | +| `Matcher.byTag(tag)` | 按标签查询 | `Matcher.byTag(1)` | +| `Matcher.byName(name)` | 按名称查询 | `Matcher.byName("Player")` | +| `Matcher.byComponent(type)` | 按单个组件查询 | `Matcher.byComponent(Health)` | +| `Matcher.empty()` | 创建空匹配器（匹配所有实体） | `Matcher.empty()` | +| `Matcher.nothing()` | 不匹配任何实体 | `Matcher.nothing()` | +| `Matcher.complex()` | 创建复杂查询构建器 | `Matcher.complex()` | + +## 链式方法 + +| 方法 | 说明 | 示例 | +|------|------|------| +| `.all(...types)` | 添加必须包含的组件 | `.all(Position)` | +| `.any(...types)` | 添加可选组件（至少一个） | `.any(Weapon, Magic)` | +| `.none(...types)` | 添加排除的组件 | `.none(Dead)` | +| `.exclude(...types)` | `.none()` 的别名 | `.exclude(Disabled)` | +| `.one(...types)` | `.any()` 的别名 | `.one(Player, Enemy)` | +| `.withTag(tag)` | 添加标签条件 | `.withTag(1)` | +| `.withName(name)` | 添加名称条件 | `.withName("Boss")` | +| `.withComponent(type)` | 添加单组件条件 | `.withComponent(Health)` | + +## 实用方法 + +| 方法 | 说明 | +|------|------| +| `.getCondition()` | 获取查询条件（只读） | +| `.isEmpty()` | 检查是否为空条件 | +| `.isNothing()` | 检查是否为 nothing 匹配器 | +| `.clone()` | 克隆匹配器 | +| `.reset()` | 重置所有条件 | +| `.toString()` | 获取字符串表示 | + +## 常用组合示例 + +```typescript +// 基础移动系统 +Matcher.all(Position, Velocity) + +// 可攻击的活着的实体 +Matcher.all(Position, Health) + .any(Weapon, Magic) + .none(Dead, Disabled) + +// 所有带标签的敌人 +Matcher.byTag(Tags.ENEMY) + .all(AIComponent) + +// 只需要生命周期的系统 +Matcher.nothing() +``` + +## 按标签查询 + +```typescript +class PlayerSystem extends EntitySystem { + constructor() { + // 查询特定标签的实体 + super(Matcher.empty().withTag(Tags.PLAYER)); + } + + protected process(entities: readonly Entity[]): void { + // 只处理玩家实体 + } +} +``` + +## 按名称查询 + +```typescript +class BossSystem extends EntitySystem { + constructor() { + // 查询特定名称的实体 + super(Matcher.empty().withName('Boss')); + } + + protected process(entities: readonly Entity[]): void { + // 只处理名为 'Boss' 的实体 + } +} +``` + +## 注意事项 + +### Matcher 是不可变的 + +```typescript +const matcher = Matcher.empty().all(PositionComponent); + +// 链式调用返回新的 Matcher 实例 +const matcher2 = matcher.any(VelocityComponent); + +// matcher 本身不变 +console.log(matcher === matcher2); // false +``` + +### 查询结果是只读的 + +```typescript +const result = querySystem.queryAll(PositionComponent); + +// 不要修改返回的数组 +result.entities.push(someEntity); // 错误! + +// 如果需要修改，先复制 +const mutableArray = [...result.entities]; +mutableArray.push(someEntity); // 正确 +``` diff --git a/docs/guide/entity.md b/docs/src/content/docs/guide/entity.md similarity index 97% rename from docs/guide/entity.md rename to docs/src/content/docs/guide/entity.md index 56cf598f..0113d8dd 100644 --- a/docs/guide/entity.md +++ b/docs/src/content/docs/guide/entity.md @@ -1,4 +1,6 @@ -# 实体类 +--- +title: "实体类" +--- 在 ECS 架构中，实体（Entity）是游戏世界中的基本对象。实体本身不包含游戏逻辑或数据，它只是一个容器，用来组合不同的组件来实现各种功能。 @@ -12,7 +14,7 @@ ::: tip 关于父子层级关系 实体间的父子层级关系通过 `HierarchyComponent` 和 `HierarchySystem` 管理，而非 Entity 内置属性。这种设计遵循 ECS 组合原则 —— 只有需要层级关系的实体才添加此组件。 -详见 [层级系统](./hierarchy.md) 文档。 +详见 [层级系统](./hierarchy/) 文档。 ::: ## 创建实体 @@ -441,6 +443,6 @@ const emptyHandle = NULL_HANDLE; ## 下一步 -- 了解 [层级系统](./hierarchy.md) 建立实体间的父子关系 -- 了解 [组件系统](./component.md) 为实体添加功能 -- 了解 [场景管理](./scene.md) 组织和管理实体 \ No newline at end of file +- 了解 [层级系统](./hierarchy/) 建立实体间的父子关系 +- 了解 [组件系统](./component/) 为实体添加功能 +- 了解 [场景管理](./scene/) 组织和管理实体 \ No newline at end of file diff --git a/docs/guide/event-system.md b/docs/src/content/docs/guide/event-system.md similarity index 99% rename from docs/guide/event-system.md rename to docs/src/content/docs/guide/event-system.md index d5b8ca55..3e1273f9 100644 --- a/docs/guide/event-system.md +++ b/docs/src/content/docs/guide/event-system.md @@ -1,4 +1,6 @@ -# 事件系统 +--- +title: "事件系统" +--- ECS 框架内置了强大的类型安全事件系统，支持同步/异步事件、优先级、批处理等高级功能。事件系统是实现组件间通信、系统间协作的核心机制。 diff --git a/docs/guide/getting-started.md b/docs/src/content/docs/guide/getting-started.md similarity index 99% rename from docs/guide/getting-started.md rename to docs/src/content/docs/guide/getting-started.md index 438be968..0de747d5 100644 --- a/docs/guide/getting-started.md +++ b/docs/src/content/docs/guide/getting-started.md @@ -1,4 +1,7 @@ -# 快速开始 +--- +title: 快速开始 +description: 5 分钟上手 ESEngine ECS 框架 +--- 本指南将帮助你快速上手 ECS Framework，从安装到创建第一个 ECS 应用。 diff --git a/docs/guide/hierarchy.md b/docs/src/content/docs/guide/hierarchy.md similarity index 98% rename from docs/guide/hierarchy.md rename to docs/src/content/docs/guide/hierarchy.md index 79a470d3..9dbd923c 100644 --- a/docs/guide/hierarchy.md +++ b/docs/src/content/docs/guide/hierarchy.md @@ -1,4 +1,6 @@ -# 层级系统 +--- +title: "层级系统" +--- 在游戏开发中，实体间的父子层级关系是常见需求。ECS Framework 采用组件化方式管理层级关系，通过 `HierarchyComponent` 和 `HierarchySystem` 实现，完全遵循 ECS 组合原则。 @@ -432,6 +434,6 @@ const found = hierarchySystem.findChild(parent, "Child"); ## 下一步 -- 了解 [实体类](./entity.md) 的其他功能 -- 了解 [场景管理](./scene.md) 如何组织实体和系统 -- 了解 [组件系统](./component.md) 如何定义和使用组件 +- 了解 [实体类](./entity/) 的其他功能 +- 了解 [场景管理](./scene/) 如何组织实体和系统 +- 了解 [组件系统](./component/) 如何定义和使用组件 diff --git a/docs/guide/index.md b/docs/src/content/docs/guide/index.md similarity index 64% rename from docs/guide/index.md rename to docs/src/content/docs/guide/index.md index acba3782..c991b315 100644 --- a/docs/guide/index.md +++ b/docs/src/content/docs/guide/index.md @@ -1,43 +1,46 @@ -# 指南 +--- +title: 指南 +description: ESEngine ECS 框架完整指南 +--- 欢迎使用 ECS Framework 指南。这里将详细介绍框架的各个核心概念和使用方法。 ## 核心概念 -### [实体类 (Entity)](./entity.md) +### [实体类 (Entity)](./entity/) 了解 ECS 架构的基础 - 实体类的使用方法、生命周期管理和最佳实践。 -### [组件系统 (Component)](./component.md) +### [组件系统 (Component)](./component/) 学习如何创建和使用组件，实现游戏功能的模块化设计。 -### [系统架构 (System)](./system.md) +### [系统架构 (System)](./system/) 掌握系统的编写方法，实现游戏逻辑的处理。 -### [实体查询与 Matcher](./entity-query.md) +### [实体查询与 Matcher](./entity-query/) 学习使用 Matcher 进行实体筛选和查询，掌握 `all`、`any`、`none`、`nothing` 等匹配条件。 -### [场景管理 (Scene)](./scene.md) +### [场景管理 (Scene)](./scene/) 了解场景的生命周期、系统管理和实体容器功能。 -### [事件系统 (Event)](./event-system.md) +### [事件系统 (Event)](./event-system/) 掌握类型安全的事件系统，实现组件间通信和系统协作。 -### [序列化系统 (Serialization)](./serialization.md) +### [序列化系统 (Serialization)](./serialization/) 掌握场景、实体和组件的序列化方案，支持全量序列化和增量序列化，实现游戏存档、网络同步等功能。 -### [时间和定时器 (Time)](./time-and-timers.md) +### [时间和定时器 (Time)](./time-and-timers/) 学习时间管理和定时器系统，实现游戏逻辑的精确时间控制。 -### [日志系统 (Logger)](./logging.md) +### [日志系统 (Logger)](./logging/) 掌握分级日志系统，用于调试、监控和错误追踪。 -### [平台适配器 (Platform Adapter)](./platform-adapter.md) +### [平台适配器 (Platform Adapter)](./platform-adapter/) 了解如何为不同平台实现和注册平台适配器，支持浏览器、小游戏、Node.js等环境。 ## 高级特性 -### [服务容器 (Service Container)](./service-container.md) +### [服务容器 (Service Container)](./service-container/) 掌握依赖注入和服务管理，实现松耦合的架构设计。 -### [插件系统 (Plugin System)](./plugin-system.md) +### [插件系统 (Plugin System)](./plugin-system/) 学习如何开发和使用插件，扩展框架功能，实现功能模块化。 \ No newline at end of file diff --git a/docs/guide/logging.md b/docs/src/content/docs/guide/logging.md similarity index 99% rename from docs/guide/logging.md rename to docs/src/content/docs/guide/logging.md index ceaf52b1..971cfa7c 100644 --- a/docs/guide/logging.md +++ b/docs/src/content/docs/guide/logging.md @@ -1,4 +1,6 @@ -# 日志系统 +--- +title: "日志系统" +--- ECS 框架提供了功能强大的分级日志系统，支持多种日志级别、颜色输出、自定义前缀和灵活的配置选项。日志系统可以帮助开发者调试代码和监控应用运行状态。 diff --git a/docs/guide/platform-adapter.md b/docs/src/content/docs/guide/platform-adapter.md similarity index 98% rename from docs/guide/platform-adapter.md rename to docs/src/content/docs/guide/platform-adapter.md index 26703cdf..34733718 100644 --- a/docs/guide/platform-adapter.md +++ b/docs/src/content/docs/guide/platform-adapter.md @@ -1,4 +1,6 @@ -# 平台适配器 +--- +title: "平台适配器" +--- ## 概述 @@ -14,7 +16,7 @@ ECS框架提供了平台适配器接口，允许用户为不同的运行环境 ## 支持的平台 -### 🌐 [浏览器适配器](./platform-adapter/browser.md) +### 🌐 [浏览器适配器](./platform-adapter/browser/) 支持所有现代浏览器环境，包括 Chrome、Firefox、Safari、Edge 等。 @@ -28,7 +30,7 @@ ECS框架提供了平台适配器接口，允许用户为不同的运行环境 --- -### 📱 [微信小游戏适配器](./platform-adapter/wechat-minigame.md) +### 📱 [微信小游戏适配器](./platform-adapter/wechat-minigame/) 专为微信小游戏环境设计，处理微信小游戏的特殊限制和API。 @@ -42,7 +44,7 @@ ECS框架提供了平台适配器接口，允许用户为不同的运行环境 --- -### 🖥️ [Node.js适配器](./platform-adapter/nodejs.md) +### 🖥️ [Node.js适配器](./platform-adapter/nodejs/) 为 Node.js 服务器环境提供支持，适用于游戏服务器和计算服务器。 diff --git a/docs/guide/platform-adapter/browser.md b/docs/src/content/docs/guide/platform-adapter/browser.md similarity index 99% rename from docs/guide/platform-adapter/browser.md rename to docs/src/content/docs/guide/platform-adapter/browser.md index 71e79138..abf48203 100644 --- a/docs/guide/platform-adapter/browser.md +++ b/docs/src/content/docs/guide/platform-adapter/browser.md @@ -1,4 +1,6 @@ -# 浏览器适配器 +--- +title: "浏览器适配器" +--- ## 概述 diff --git a/docs/guide/platform-adapter/nodejs.md b/docs/src/content/docs/guide/platform-adapter/nodejs.md similarity index 99% rename from docs/guide/platform-adapter/nodejs.md rename to docs/src/content/docs/guide/platform-adapter/nodejs.md index 574e2369..9dfe3b7c 100644 --- a/docs/guide/platform-adapter/nodejs.md +++ b/docs/src/content/docs/guide/platform-adapter/nodejs.md @@ -1,4 +1,6 @@ -# Node.js 适配器 +--- +title: "Node.js 适配器" +--- ## 概述 diff --git a/docs/guide/platform-adapter/wechat-minigame.md b/docs/src/content/docs/guide/platform-adapter/wechat-minigame.md similarity index 99% rename from docs/guide/platform-adapter/wechat-minigame.md rename to docs/src/content/docs/guide/platform-adapter/wechat-minigame.md index e3605ae8..35862df0 100644 --- a/docs/guide/platform-adapter/wechat-minigame.md +++ b/docs/src/content/docs/guide/platform-adapter/wechat-minigame.md @@ -1,4 +1,6 @@ -# 微信小游戏适配器 +--- +title: "微信小游戏适配器" +--- ## 概述 diff --git a/docs/guide/plugin-system.md b/docs/src/content/docs/guide/plugin-system.md similarity index 98% rename from docs/guide/plugin-system.md rename to docs/src/content/docs/guide/plugin-system.md index af4803e1..e559bfc8 100644 --- a/docs/guide/plugin-system.md +++ b/docs/src/content/docs/guide/plugin-system.md @@ -1,4 +1,6 @@ -# 插件系统 +--- +title: "插件系统" +--- 插件系统允许你以模块化的方式扩展 ECS Framework 的功能。通过插件，你可以封装特定功能（如网络同步、物理引擎、调试工具等），并在多个项目中复用。 @@ -638,6 +640,6 @@ await Core.installPlugin(plugin); ## 相关链接 -- [服务容器](./service-container.md) - 在插件中使用服务容器 -- [系统架构](./system.md) - 在插件中添加系统 -- [快速开始](./getting-started.md) - Core 初始化和基础使用 +- [服务容器](./service-container/) - 在插件中使用服务容器 +- [系统架构](./system/) - 在插件中添加系统 +- [快速开始](./getting-started/) - Core 初始化和基础使用 diff --git a/docs/guide/scene.md b/docs/src/content/docs/guide/scene.md similarity index 97% rename from docs/guide/scene.md rename to docs/src/content/docs/guide/scene.md index cb108070..d2483fed 100644 --- a/docs/guide/scene.md +++ b/docs/src/content/docs/guide/scene.md @@ -1,3 +1,7 @@ +--- +title: "scene" +--- + # 场景管理 在 ECS 架构中，场景（Scene）是游戏世界的容器，负责管理实体、系统和组件的生命周期。场景提供了完整的 ECS 运行环境。 @@ -15,12 +19,12 @@ ECS Framework 提供了两种场景管理方式： -1. **[SceneManager](./scene-manager.md)** - 适用于 95% 的游戏应用 +1. **[SceneManager](./scene-manager/)** - 适用于 95% 的游戏应用 - 单人游戏、简单多人游戏、移动游戏 - 轻量级，简单直观的 API - 支持场景切换 -2. **[WorldManager](./world-manager.md)** - 适用于高级多世界隔离场景 +2. **[WorldManager](./world-manager/)** - 适用于高级多世界隔离场景 - MMO 游戏服务器、游戏房间系统 - 多 World 管理，每个 World 可包含多个场景 - 完全隔离的独立环境 @@ -655,8 +659,8 @@ world.setSceneActive('main', true); ## 下一步 -- 了解 [SceneManager](./scene-manager.md) - 适用于大多数游戏的简单场景管理 -- 了解 [WorldManager](./world-manager.md) - 适用于需要多世界隔离的高级场景 -- 了解 [持久化实体](./persistent-entity.md) - 让实体跨场景保持状态（v2.3.0+） +- 了解 [SceneManager](./scene-manager/) - 适用于大多数游戏的简单场景管理 +- 了解 [WorldManager](./world-manager/) - 适用于需要多世界隔离的高级场景 +- 了解 [持久化实体](./persistent-entity/) - 让实体跨场景保持状态（v2.3.0+） 场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。 diff --git a/docs/src/content/docs/guide/serialization/decorators.md b/docs/src/content/docs/guide/serialization/decorators.md new file mode 100644 index 00000000..84d72203 --- /dev/null +++ b/docs/src/content/docs/guide/serialization/decorators.md @@ -0,0 +1,165 @@ +--- +title: "装饰器与继承" +description: "序列化装饰器高级用法和组件继承" +--- + +## 高级装饰器 + +### 字段序列化选项 + +```typescript +@ECSComponent('Advanced') +@Serializable({ version: 1 }) +class AdvancedComponent extends Component { + // 使用别名 + @Serialize({ alias: 'playerName' }) + public name: string = ''; + + // 自定义序列化器 + @Serialize({ + serializer: (value: Date) => value.toISOString(), + deserializer: (value: string) => new Date(value) + }) + public createdAt: Date = new Date(); + + // 忽略序列化 + @IgnoreSerialization() + public cachedData: any = null; +} +``` + +### 集合类型序列化 + +```typescript +@ECSComponent('Collections') +@Serializable({ version: 1 }) +class CollectionsComponent extends Component { + // Map序列化 + @SerializeAsMap() + public inventory: Map = new Map(); + + // Set序列化 + @SerializeAsSet() + public acquiredSkills: Set = new Set(); + + constructor() { + super(); + this.inventory.set('gold', 100); + this.inventory.set('silver', 50); + this.acquiredSkills.add('attack'); + this.acquiredSkills.add('defense'); + } +} +``` + +## 组件继承与序列化 + +框架完整支持组件类的继承，子类会自动继承父类的序列化字段，同时可以添加自己的字段。 + +### 基础继承 + +```typescript +// 基类组件 +@ECSComponent('Collider2DBase') +@Serializable({ version: 1, typeId: 'Collider2DBase' }) +abstract class Collider2DBase extends Component { + @Serialize() + public friction: number = 0.5; + + @Serialize() + public restitution: number = 0.0; + + @Serialize() + public isTrigger: boolean = false; +} + +// 子类组件 - 自动继承父类的序列化字段 +@ECSComponent('BoxCollider2D') +@Serializable({ version: 1, typeId: 'BoxCollider2D' }) +class BoxCollider2DComponent extends Collider2DBase { + @Serialize() + public width: number = 1.0; + + @Serialize() + public height: number = 1.0; +} + +// 另一个子类组件 +@ECSComponent('CircleCollider2D') +@Serializable({ version: 1, typeId: 'CircleCollider2D' }) +class CircleCollider2DComponent extends Collider2DBase { + @Serialize() + public radius: number = 0.5; +} +``` + +### 继承规则 + +1. **字段继承**：子类自动继承父类所有被 `@Serialize()` 标记的字段 +2. **独立元数据**：每个子类维护独立的序列化元数据，修改子类不会影响父类或其他子类 +3. **typeId 区分**：使用 `typeId` 选项为每个类指定唯一标识，确保反序列化时能正确识别组件类型 + +### 使用 typeId 的重要性 + +当使用组件继承时，**强烈建议**为每个类设置唯一的 `typeId`： + +```typescript +// ✅ 推荐：明确指定 typeId +@Serializable({ version: 1, typeId: 'BoxCollider2D' }) +class BoxCollider2DComponent extends Collider2DBase { } + +@Serializable({ version: 1, typeId: 'CircleCollider2D' }) +class CircleCollider2DComponent extends Collider2DBase { } + +// ⚠️ 不推荐：依赖类名作为 typeId +// 在代码压缩后类名可能变化，导致反序列化失败 +@Serializable({ version: 1 }) +class BoxCollider2DComponent extends Collider2DBase { } +``` + +### 子类覆盖父类字段 + +子类可以重新声明父类的字段以修改其序列化选项： + +```typescript +@ECSComponent('SpecialCollider') +@Serializable({ version: 1, typeId: 'SpecialCollider' }) +class SpecialColliderComponent extends Collider2DBase { + // 覆盖父类字段，使用不同的别名 + @Serialize({ alias: 'fric' }) + public override friction: number = 0.8; + + @Serialize() + public specialProperty: string = ''; +} +``` + +### 忽略继承的字段 + +使用 `@IgnoreSerialization()` 可以在子类中忽略从父类继承的字段： + +```typescript +@ECSComponent('TriggerOnly') +@Serializable({ version: 1, typeId: 'TriggerOnly' }) +class TriggerOnlyCollider extends Collider2DBase { + // 忽略父类的 friction 和 restitution 字段 + // 因为 Trigger 不需要物理材质属性 + @IgnoreSerialization() + public override friction: number = 0; + + @IgnoreSerialization() + public override restitution: number = 0; +} +``` + +## 装饰器参考 + +| 装饰器 | 说明 | +|--------|------| +| `@Serializable({ version, typeId })` | 标记组件为可序列化 | +| `@Serialize()` | 标记字段为可序列化 | +| `@Serialize({ alias })` | 使用别名序列化字段 | +| `@Serialize({ serializer, deserializer })` | 自定义序列化逻辑 | +| `@SerializeAsMap()` | 序列化 Map 类型 | +| `@SerializeAsSet()` | 序列化 Set 类型 | +| `@IgnoreSerialization()` | 忽略字段序列化 | diff --git a/docs/src/content/docs/guide/serialization/incremental.md b/docs/src/content/docs/guide/serialization/incremental.md new file mode 100644 index 00000000..422b140c --- /dev/null +++ b/docs/src/content/docs/guide/serialization/incremental.md @@ -0,0 +1,228 @@ +--- +title: "增量序列化" +description: "只序列化场景的变更部分" +--- + +增量序列化只保存场景的变更部分，适用于网络同步、撤销/重做、时间回溯等需要频繁保存状态的场景。 + +## 基础用法 + +### 1. 创建基础快照 + +```typescript +// 在需要开始记录变更前创建基础快照 +scene.createIncrementalSnapshot(); +``` + +### 2. 修改场景 + +```typescript +// 添加实体 +const enemy = scene.createEntity('Enemy'); +enemy.addComponent(new PositionComponent(100, 200)); +enemy.addComponent(new HealthComponent(50)); + +// 修改组件 +const player = scene.findEntity('Player'); +const pos = player.getComponent(PositionComponent); +pos.x = 300; +pos.y = 400; + +// 删除组件 +player.removeComponentByType(BuffComponent); + +// 删除实体 +const oldEntity = scene.findEntity('ToDelete'); +oldEntity.destroy(); + +// 修改场景数据 +scene.sceneData.set('score', 1000); +``` + +### 3. 获取增量变更 + +```typescript +// 获取相对于基础快照的所有变更 +const incremental = scene.serializeIncremental(); + +// 查看变更统计 +const stats = IncrementalSerializer.getIncrementalStats(incremental); +console.log('总变更数:', stats.totalChanges); +console.log('新增实体:', stats.addedEntities); +console.log('删除实体:', stats.removedEntities); +console.log('新增组件:', stats.addedComponents); +console.log('更新组件:', stats.updatedComponents); +``` + +### 4. 序列化增量数据 + +```typescript +// JSON格式（默认） +const jsonData = IncrementalSerializer.serializeIncremental(incremental, { + format: 'json' +}); + +// 二进制格式（更小的体积，更高性能） +const binaryData = IncrementalSerializer.serializeIncremental(incremental, { + format: 'binary' +}); + +// 美化JSON输出（便于调试） +const prettyJson = IncrementalSerializer.serializeIncremental(incremental, { + format: 'json', + pretty: true +}); + +// 发送或保存 +socket.send(binaryData); // 网络传输使用二进制 +localStorage.setItem('changes', jsonData); // 本地存储可用JSON +``` + +### 5. 应用增量变更 + +```typescript +// 在另一个场景应用变更 +const otherScene = new Scene(); + +// 直接应用增量对象 +otherScene.applyIncremental(incremental); + +// 从JSON字符串应用 +const jsonData = IncrementalSerializer.serializeIncremental(incremental, { format: 'json' }); +otherScene.applyIncremental(jsonData); + +// 从二进制Uint8Array应用 +const binaryData = IncrementalSerializer.serializeIncremental(incremental, { format: 'binary' }); +otherScene.applyIncremental(binaryData); +``` + +## 增量快照管理 + +### 更新快照基准 + +在应用增量变更后，可以更新快照基准： + +```typescript +// 创建初始快照 +scene.createIncrementalSnapshot(); + +// 第一次修改 +entity.addComponent(new VelocityComponent(5, 0)); +const incremental1 = scene.serializeIncremental(); + +// 更新基准（将当前状态设为新的基准） +scene.updateIncrementalSnapshot(); + +// 第二次修改（增量将基于更新后的基准） +entity.getComponent(VelocityComponent).dx = 10; +const incremental2 = scene.serializeIncremental(); +``` + +### 清除快照 + +```typescript +// 释放快照占用的内存 +scene.clearIncrementalSnapshot(); + +// 检查是否有快照 +if (scene.hasIncrementalSnapshot()) { + console.log('存在增量快照'); +} +``` + +## 增量序列化选项 + +```typescript +interface IncrementalSerializationOptions { + // 是否进行组件数据的深度对比 + // 默认true，设为false可提升性能但可能漏掉组件内部字段变更 + deepComponentComparison?: boolean; + + // 是否跟踪场景数据变更 + // 默认true + trackSceneData?: boolean; + + // 是否压缩快照（使用JSON序列化） + // 默认false + compressSnapshot?: boolean; + + // 序列化格式 + // 'json': JSON格式（可读性好，方便调试） + // 'binary': MessagePack二进制格式（体积小，性能高） + // 默认 'json' + format?: 'json' | 'binary'; + + // 是否美化JSON输出（仅在format='json'时有效） + // 默认false + pretty?: boolean; +} + +// 使用选项 +scene.createIncrementalSnapshot({ + deepComponentComparison: true, + trackSceneData: true +}); +``` + +## 增量数据结构 + +增量快照包含以下变更类型： + +```typescript +interface IncrementalSnapshot { + version: number; // 快照版本号 + timestamp: number; // 时间戳 + sceneName: string; // 场景名称 + baseVersion: number; // 基础版本号 + entityChanges: EntityChange[]; // 实体变更 + componentChanges: ComponentChange[]; // 组件变更 + sceneDataChanges: SceneDataChange[]; // 场景数据变更 +} + +// 变更操作类型 +enum ChangeOperation { + EntityAdded = 'entity_added', + EntityRemoved = 'entity_removed', + EntityUpdated = 'entity_updated', + ComponentAdded = 'component_added', + ComponentRemoved = 'component_removed', + ComponentUpdated = 'component_updated', + SceneDataUpdated = 'scene_data_updated' +} +``` + +## 性能优化 + +### 对于高频同步 + +```typescript +// 关闭深度对比以提升性能 +scene.createIncrementalSnapshot({ + deepComponentComparison: false // 只检测组件的添加/删除 +}); +``` + +### 批量操作 + +```typescript +// 批量修改后再序列化 +scene.entities.buffer.forEach(entity => { + // 批量修改 +}); + +// 一次性序列化所有变更 +const incremental = scene.serializeIncremental(); +``` + +## API 参考 + +| 方法 | 说明 | +|------|------| +| `scene.createIncrementalSnapshot(options?)` | 创建基础快照 | +| `scene.serializeIncremental()` | 获取增量变更 | +| `scene.applyIncremental(data)` | 应用增量变更 | +| `scene.updateIncrementalSnapshot()` | 更新快照基准 | +| `scene.clearIncrementalSnapshot()` | 清除快照 | +| `scene.hasIncrementalSnapshot()` | 检查是否有快照 | +| `IncrementalSerializer.getIncrementalStats(snapshot)` | 获取变更统计 | +| `IncrementalSerializer.serializeIncremental(snapshot, options)` | 序列化增量数据 | diff --git a/docs/src/content/docs/guide/serialization/index.md b/docs/src/content/docs/guide/serialization/index.md new file mode 100644 index 00000000..f7abab8c --- /dev/null +++ b/docs/src/content/docs/guide/serialization/index.md @@ -0,0 +1,170 @@ +--- +title: "序列化系统" +description: "ECS 序列化系统概述和全量序列化" +--- + +序列化系统提供了完整的场景、实体和组件数据持久化方案，支持全量序列化和增量序列化两种模式，适用于游戏存档、网络同步、场景编辑器、时间回溯等场景。 + +## 基本概念 + +序列化系统分为两个层次： + +- **全量序列化**：序列化完整的场景状态，包括所有实体、组件和场景数据 +- **增量序列化**：只序列化相对于基础快照的变更部分，大幅减少数据量 + +### 支持的数据格式 + +- **JSON格式**：人类可读，便于调试和编辑 +- **Binary格式**：使用MessagePack，体积更小，性能更高 + +> **v2.2.2 重要变更** +> +> 从 v2.2.2 开始，二进制序列化格式返回 `Uint8Array` 而非 Node.js 的 `Buffer`，以确保浏览器兼容性： +> - `serialize({ format: 'binary' })` 返回 `string | Uint8Array`（原为 `string | Buffer`） +> - `deserialize(data)` 接收 `string | Uint8Array`（原为 `string | Buffer`） +> - `applyIncremental(data)` 接收 `IncrementalSnapshot | string | Uint8Array`（原为包含 `Buffer`） +> +> **迁移影响**： +> - **运行时兼容**：Node.js 的 `Buffer` 继承自 `Uint8Array`，现有代码可直接运行 +> - **类型检查**：如果你的 TypeScript 代码中显式使用了 `Buffer` 类型，需要改为 `Uint8Array` +> - **浏览器支持**：`Uint8Array` 是标准 JavaScript 类型，所有现代浏览器都支持 + +## 全量序列化 + +### 基础用法 + +#### 1. 标记可序列化组件 + +使用 `@Serializable` 和 `@Serialize` 装饰器标记需要序列化的组件和字段： + +```typescript +import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework'; + +@ECSComponent('Player') +@Serializable({ version: 1 }) +class PlayerComponent extends Component { + @Serialize() + public name: string = ''; + + @Serialize() + public level: number = 1; + + @Serialize() + public experience: number = 0; + + @Serialize() + public position: { x: number; y: number } = { x: 0, y: 0 }; + + // 不使用 @Serialize() 的字段不会被序列化 + private tempData: any = null; +} +``` + +#### 2. 序列化场景 + +```typescript +// JSON格式序列化 +const jsonData = scene.serialize({ + format: 'json', + pretty: true // 美化输出 +}); + +// 保存到本地存储 +localStorage.setItem('gameSave', jsonData); + +// Binary格式序列化（更小的体积） +const binaryData = scene.serialize({ + format: 'binary' +}); + +// 保存为文件（Node.js环境） +// 注意：binaryData 是 Uint8Array 类型，Node.js 的 fs 可以直接写入 +fs.writeFileSync('save.bin', binaryData); +``` + +#### 3. 反序列化场景 + +```typescript +// 从JSON恢复 +const saveData = localStorage.getItem('gameSave'); +if (saveData) { + scene.deserialize(saveData, { + strategy: 'replace' // 替换当前场景内容 + }); +} + +// 从Binary恢复 +const binaryData = fs.readFileSync('save.bin'); +scene.deserialize(binaryData, { + strategy: 'merge' // 合并到现有场景 +}); +``` + +### 序列化选项 + +#### SerializationOptions + +```typescript +interface SceneSerializationOptions { + // 指定要序列化的组件类型（可选） + components?: ComponentType[]; + + // 序列化格式：'json' 或 'binary' + format?: 'json' | 'binary'; + + // JSON美化输出 + pretty?: boolean; + + // 包含元数据 + includeMetadata?: boolean; +} +``` + +示例： + +```typescript +// 只序列化特定组件类型 +const saveData = scene.serialize({ + format: 'json', + components: [PlayerComponent, InventoryComponent], + pretty: true, + includeMetadata: true +}); +``` + +#### DeserializationOptions + +```typescript +interface SceneDeserializationOptions { + // 反序列化策略 + strategy?: 'merge' | 'replace'; + + // 组件类型注册表（可选，默认使用全局注册表） + componentRegistry?: Map; +} +``` + +### 场景自定义数据 + +除了实体和组件，还可以序列化场景级别的配置数据： + +```typescript +// 设置场景数据 +scene.sceneData.set('weather', 'rainy'); +scene.sceneData.set('difficulty', 'hard'); +scene.sceneData.set('checkpoint', { x: 100, y: 200 }); + +// 序列化时会自动包含场景数据 +const saveData = scene.serialize({ format: 'json' }); + +// 反序列化后场景数据会恢复 +scene.deserialize(saveData); +console.log(scene.sceneData.get('weather')); // 'rainy' +``` + +## 更多主题 + +- [装饰器与继承](/guide/serialization/decorators) - 高级装饰器用法和组件继承 +- [增量序列化](/guide/serialization/incremental) - 只序列化变更部分 +- [版本迁移](/guide/serialization/migration) - 处理数据结构变更 +- [使用场景](/guide/serialization/use-cases) - 存档、网络同步、撤销重做等实例 diff --git a/docs/src/content/docs/guide/serialization/migration.md b/docs/src/content/docs/guide/serialization/migration.md new file mode 100644 index 00000000..68f49134 --- /dev/null +++ b/docs/src/content/docs/guide/serialization/migration.md @@ -0,0 +1,151 @@ +--- +title: "版本迁移" +description: "处理组件和场景数据结构变更" +--- + +当组件结构发生变化时，版本迁移系统可以自动升级旧版本的存档数据。 + +## 注册迁移函数 + +```typescript +import { VersionMigrationManager } from '@esengine/ecs-framework'; + +// 假设 PlayerComponent v1 有 hp 字段 +// v2 改为 health 和 maxHealth 字段 + +// 注册从版本1到版本2的迁移 +VersionMigrationManager.registerComponentMigration( + 'Player', + 1, // 从版本 + 2, // 到版本 + (data) => { + // 迁移逻辑 + const newData = { + ...data, + health: data.hp, + maxHealth: data.hp, + }; + delete newData.hp; + return newData; + } +); +``` + +## 使用迁移构建器 + +```typescript +import { MigrationBuilder } from '@esengine/ecs-framework'; + +new MigrationBuilder() + .forComponent('Player') + .fromVersionToVersion(2, 3) + .migrate((data) => { + // 从版本2迁移到版本3 + data.experience = data.exp || 0; + delete data.exp; + return data; + }); +``` + +## 场景级迁移 + +```typescript +// 注册场景级迁移 +VersionMigrationManager.registerSceneMigration( + 1, // 从版本 + 2, // 到版本 + (scene) => { + // 迁移场景结构 + scene.metadata = { + ...scene.metadata, + migratedFrom: 1 + }; + return scene; + } +); +``` + +## 检查迁移路径 + +```typescript +// 检查是否可以迁移 +const canMigrate = VersionMigrationManager.canMigrateComponent( + 'Player', + 1, // 从版本 + 3 // 到版本 +); + +if (canMigrate) { + // 可以安全迁移 + scene.deserialize(oldSaveData); +} + +// 获取迁移路径 +const path = VersionMigrationManager.getComponentMigrationPath('Player'); +console.log('可用迁移版本:', path); // [1, 2, 3] +``` + +## 迁移链示例 + +当需要跨多个版本迁移时，系统会自动链式执行迁移： + +```typescript +// 注册 v1 -> v2 +VersionMigrationManager.registerComponentMigration('Player', 1, 2, (data) => { + data.health = data.hp; + delete data.hp; + return data; +}); + +// 注册 v2 -> v3 +VersionMigrationManager.registerComponentMigration('Player', 2, 3, (data) => { + data.stats = { health: data.health, mana: 100 }; + delete data.health; + return data; +}); + +// 当加载 v1 数据时，会自动执行 v1 -> v2 -> v3 +``` + +## 最佳实践 + +### 1. 始终保持向后兼容 + +```typescript +// 记录每个版本的数据结构变更 +// v1: { hp: number } +// v2: { health: number, maxHealth: number } +// v3: { stats: { health: number, mana: number } } +``` + +### 2. 测试迁移路径 + +```typescript +// 测试所有可能的迁移路径 +const testData = { hp: 100 }; +const migrated = VersionMigrationManager.migrateComponent('Player', testData, 1, 3); +expect(migrated.stats.health).toBe(100); +``` + +### 3. 保留原始数据备份 + +```typescript +// 在迁移前备份 +const backup = JSON.parse(JSON.stringify(saveData)); +try { + scene.deserialize(saveData); +} catch (e) { + // 迁移失败时恢复 + console.error('迁移失败:', e); +} +``` + +## API 参考 + +| 方法 | 说明 | +|------|------| +| `registerComponentMigration(type, from, to, fn)` | 注册组件迁移函数 | +| `registerSceneMigration(from, to, fn)` | 注册场景迁移函数 | +| `canMigrateComponent(type, from, to)` | 检查是否可以迁移 | +| `getComponentMigrationPath(type)` | 获取组件的迁移版本路径 | +| `migrateComponent(type, data, from, to)` | 执行组件数据迁移 | diff --git a/docs/src/content/docs/guide/serialization/use-cases.md b/docs/src/content/docs/guide/serialization/use-cases.md new file mode 100644 index 00000000..f00340c1 --- /dev/null +++ b/docs/src/content/docs/guide/serialization/use-cases.md @@ -0,0 +1,306 @@ +--- +title: "使用场景" +description: "序列化系统的实际应用示例" +--- + +## 游戏存档系统 + +```typescript +class SaveSystem { + private static SAVE_KEY = 'game_save'; + + // 保存游戏 + public static saveGame(scene: Scene): void { + const saveData = scene.serialize({ + format: 'json', + pretty: false + }); + + localStorage.setItem(this.SAVE_KEY, saveData); + console.log('游戏已保存'); + } + + // 加载游戏 + public static loadGame(scene: Scene): boolean { + const saveData = localStorage.getItem(this.SAVE_KEY); + if (saveData) { + scene.deserialize(saveData, { + strategy: 'replace' + }); + console.log('游戏已加载'); + return true; + } + return false; + } + + // 检查是否有存档 + public static hasSave(): boolean { + return localStorage.getItem(this.SAVE_KEY) !== null; + } +} +``` + +## 网络同步 + +```typescript +class NetworkSync { + private baseSnapshot?: any; + private syncInterval: number = 100; // 100ms同步一次 + + constructor(private scene: Scene, private socket: WebSocket) { + this.setupSync(); + } + + private setupSync(): void { + // 创建基础快照 + this.scene.createIncrementalSnapshot(); + + // 定期发送增量 + setInterval(() => { + this.sendIncremental(); + }, this.syncInterval); + + // 接收远程增量 + this.socket.onmessage = (event) => { + this.receiveIncremental(event.data); + }; + } + + private sendIncremental(): void { + const incremental = this.scene.serializeIncremental(); + const stats = IncrementalSerializer.getIncrementalStats(incremental); + + // 只在有变更时发送 + if (stats.totalChanges > 0) { + // 使用二进制格式减少网络传输量 + const binaryData = IncrementalSerializer.serializeIncremental(incremental, { + format: 'binary' + }); + this.socket.send(binaryData); + + // 更新基准 + this.scene.updateIncrementalSnapshot(); + } + } + + private receiveIncremental(data: ArrayBuffer): void { + // 直接应用二进制数据（ArrayBuffer 转 Uint8Array） + const uint8Array = new Uint8Array(data); + this.scene.applyIncremental(uint8Array); + } +} +``` + +## 撤销/重做系统 + +```typescript +class UndoRedoSystem { + private history: IncrementalSnapshot[] = []; + private currentIndex: number = -1; + private maxHistory: number = 50; + + constructor(private scene: Scene) { + // 创建初始快照 + this.scene.createIncrementalSnapshot(); + this.saveState('Initial'); + } + + // 保存当前状态 + public saveState(label: string): void { + const incremental = this.scene.serializeIncremental(); + + // 删除当前位置之后的历史 + this.history = this.history.slice(0, this.currentIndex + 1); + + // 添加新状态 + this.history.push(incremental); + this.currentIndex++; + + // 限制历史记录数量 + if (this.history.length > this.maxHistory) { + this.history.shift(); + this.currentIndex--; + } + + // 更新快照基准 + this.scene.updateIncrementalSnapshot(); + } + + // 撤销 + public undo(): boolean { + if (this.currentIndex > 0) { + this.currentIndex--; + const incremental = this.history[this.currentIndex]; + this.scene.applyIncremental(incremental); + return true; + } + return false; + } + + // 重做 + public redo(): boolean { + if (this.currentIndex < this.history.length - 1) { + this.currentIndex++; + const incremental = this.history[this.currentIndex]; + this.scene.applyIncremental(incremental); + return true; + } + return false; + } + + public canUndo(): boolean { + return this.currentIndex > 0; + } + + public canRedo(): boolean { + return this.currentIndex < this.history.length - 1; + } +} +``` + +## 关卡编辑器 + +```typescript +class LevelEditor { + // 导出关卡 + public exportLevel(scene: Scene, filename: string): void { + const levelData = scene.serialize({ + format: 'json', + pretty: true, + includeMetadata: true + }); + + // 浏览器环境 + const blob = new Blob([levelData], { type: 'application/json' }); + const url = URL.createObjectURL(blob); + const a = document.createElement('a'); + a.href = url; + a.download = filename; + a.click(); + URL.revokeObjectURL(url); + } + + // 导入关卡 + public importLevel(scene: Scene, fileContent: string): void { + scene.deserialize(fileContent, { + strategy: 'replace' + }); + } + + // 验证关卡数据 + public validateLevel(saveData: string): boolean { + const validation = SceneSerializer.validate(saveData); + if (!validation.valid) { + console.error('关卡数据无效:', validation.errors); + return false; + } + return true; + } + + // 获取关卡信息（不完全反序列化） + public getLevelInfo(saveData: string): any { + const info = SceneSerializer.getInfo(saveData); + return info; + } +} +``` + +## 性能优化建议 + +### 1. 选择合适的格式 + +- **开发阶段**：使用JSON格式，便于调试和查看 +- **生产环境**：使用Binary格式，减少30-50%的数据大小 + +### 2. 按需序列化 + +```typescript +// 只序列化需要持久化的组件 +const saveData = scene.serialize({ + format: 'binary', + components: [PlayerComponent, InventoryComponent, QuestComponent] +}); +``` + +### 3. 增量序列化优化 + +```typescript +// 对于高频同步，关闭深度对比以提升性能 +scene.createIncrementalSnapshot({ + deepComponentComparison: false // 只检测组件的添加/删除 +}); +``` + +## 最佳实践 + +### 1. 明确序列化字段 + +```typescript +// 明确标记需要序列化的字段 +@ECSComponent('Player') +@Serializable({ version: 1 }) +class PlayerComponent extends Component { + @Serialize() + public name: string = ''; + + @Serialize() + public level: number = 1; + + // 运行时数据不序列化 + private _cachedSprite: any = null; +} +``` + +### 2. 使用版本控制 + +```typescript +// 为组件指定版本 +@Serializable({ version: 2 }) +class PlayerComponent extends Component { + // 版本2的字段 +} + +// 注册迁移函数确保兼容性 +VersionMigrationManager.registerComponentMigration('Player', 1, 2, migrateV1ToV2); +``` + +### 3. 避免循环引用 + +```typescript +// 不要在组件中直接引用其他实体 +@ECSComponent('Follower') +@Serializable({ version: 1 }) +class FollowerComponent extends Component { + // 存储实体ID而不是实体引用 + @Serialize() + public targetId: number = 0; + + // 通过场景查找目标实体 + public getTarget(scene: Scene): Entity | null { + return scene.entities.findEntityById(this.targetId); + } +} +``` + +### 4. 压缩大数据 + +```typescript +// 对于大型数据结构，使用自定义序列化 +@ECSComponent('LargeData') +@Serializable({ version: 1 }) +class LargeDataComponent extends Component { + @Serialize({ + serializer: (data: LargeObject) => compressData(data), + deserializer: (data: CompressedData) => decompressData(data) + }) + public data: LargeObject; +} +``` + +## 性能对比 + +| 场景 | JSON格式 | Binary格式 | 节省 | +|------|----------|------------|------| +| 小型存档 (100实体) | 50KB | 35KB | 30% | +| 中型存档 (1000实体) | 500KB | 300KB | 40% | +| 大型存档 (10000实体) | 5MB | 2.5MB | 50% | diff --git a/docs/src/content/docs/guide/service-container/advanced.md b/docs/src/content/docs/guide/service-container/advanced.md new file mode 100644 index 00000000..27deae81 --- /dev/null +++ b/docs/src/content/docs/guide/service-container/advanced.md @@ -0,0 +1,208 @@ +--- +title: "高级用法" +description: "Symbol 模式、最佳实践、常见问题" +--- + +## 接口与 Symbol 标识符模式 + +在大型项目或需要跨平台适配的游戏中，推荐使用"接口 + Symbol.for 标识符"模式。 + +### 为什么使用 Symbol.for + +- **跨包共享**: `Symbol.for('key')` 在全局 Symbol 注册表中创建/获取 Symbol +- **接口解耦**: 消费者只依赖接口定义，不依赖具体实现类 +- **可替换实现**: 可以在运行时注入不同的实现（如测试 Mock、不同平台适配） + +### 定义接口和标识符 + +```typescript +// IAudioService.ts +export interface IAudioService { + dispose(): void; + playSound(id: string): void; + playMusic(id: string, loop?: boolean): void; + stopMusic(): void; + setVolume(volume: number): void; + preload(id: string, url: string): Promise; +} + +// 使用 Symbol.for 确保跨包共享 +export const IAudioService = Symbol.for('IAudioService'); +``` + +### 实现接口 + +```typescript +// WebAudioService.ts - Web 平台 +export class WebAudioService implements IAudioService { + private audioContext: AudioContext; + + constructor() { + this.audioContext = new AudioContext(); + } + + playSound(id: string): void { + // Web Audio API 实现 + } + + dispose(): void { + this.audioContext.close(); + } +} + +// WechatAudioService.ts - 微信小游戏平台 +export class WechatAudioService implements IAudioService { + playSound(id: string): void { + // 微信小游戏 API 实现 + } + + dispose(): void { + // 清理 + } +} +``` + +### 注册和使用 + +```typescript +// 根据平台注册不同实现 +if (typeof wx !== 'undefined') { + Core.services.registerInstance(IAudioService, new WechatAudioService()); +} else { + Core.services.registerInstance(IAudioService, new WebAudioService()); +} + +// 业务代码中使用 - 不关心具体实现 +const audio = Core.services.resolve(IAudioService); +audio.playSound('explosion'); +``` + +### Symbol vs Symbol.for + +```typescript +// Symbol() - 每次创建唯一的 Symbol +const sym1 = Symbol('test'); +const sym2 = Symbol('test'); +console.log(sym1 === sym2); // false + +// Symbol.for() - 在全局注册表中共享 +const sym3 = Symbol.for('test'); +const sym4 = Symbol.for('test'); +console.log(sym3 === sym4); // true +``` + +## 循环依赖检测 + +服务容器会自动检测循环依赖： + +```typescript +// A 依赖 B，B 依赖 A +@Injectable() +class ServiceA implements IService { + @InjectProperty(ServiceB) + private b!: ServiceB; + dispose(): void {} +} + +@Injectable() +class ServiceB implements IService { + @InjectProperty(ServiceA) + private a!: ServiceA; + dispose(): void {} +} + +// 解析时会抛出错误 +// Circular dependency detected: ServiceA -> ServiceB -> ServiceA +``` + +## 服务管理 + +```typescript +// 获取所有已注册的服务类型 +const types = Core.services.getRegisteredServices(); + +// 获取所有已实例化的服务实例 +const instances = Core.services.getAll(); + +// 注销单个服务 +Core.services.unregister(MyService); + +// 清空所有服务（会调用每个服务的dispose方法） +Core.services.clear(); +``` + +## 最佳实践 + +### 服务命名 + +服务类名应该以 `Service` 或 `Manager` 结尾： + +```typescript +class PlayerService implements IService {} +class AudioManager implements IService {} +class NetworkService implements IService {} +``` + +### 资源清理 + +始终在 `dispose()` 方法中清理资源： + +```typescript +class ResourceService implements IService { + private resources: Map = new Map(); + + dispose(): void { + for (const resource of this.resources.values()) { + resource.release(); + } + this.resources.clear(); + } +} +``` + +### 避免过度使用 + +不要把所有类都注册为服务，服务应该是： + +- 全局单例或需要共享状态 +- 需要在多处使用 +- 生命周期需要管理 +- 需要依赖注入 + +### 依赖方向 + +保持清晰的依赖方向，避免循环依赖： + +``` +高层服务 -> 中层服务 -> 底层服务 +GameLogic -> DataService -> ConfigService +``` + +### 何时使用单例 vs 瞬时 + +- **单例**: 管理器类、配置、缓存、状态管理 +- **瞬时**: 命令对象、请求处理器、临时任务 + +## 常见问题 + +### 服务未注册错误 + +**问题**: `Error: Service MyService is not registered` + +**解决**: +```typescript +// 确保服务已注册 +Core.services.registerSingleton(MyService); + +// 或者使用tryResolve +const service = Core.services.tryResolve(MyService); +if (!service) { + console.log('Service not found'); +} +``` + +### 循环依赖错误 + +**问题**: `Circular dependency detected` + +**解决**: 重新设计服务依赖关系，引入中间服务或使用事件系统解耦。 diff --git a/docs/src/content/docs/guide/service-container/built-in-services.md b/docs/src/content/docs/guide/service-container/built-in-services.md new file mode 100644 index 00000000..63a65811 --- /dev/null +++ b/docs/src/content/docs/guide/service-container/built-in-services.md @@ -0,0 +1,97 @@ +--- +title: "内置服务" +description: "Core 自动注册的内置服务" +--- + +Core 在初始化时自动注册了以下内置服务： + +## TimerManager + +定时器管理器，负责管理所有游戏定时器： + +```typescript +const timerManager = Core.services.resolve(TimerManager); + +// 创建定时器 +timerManager.schedule(1.0, false, null, (timer) => { + console.log('1秒后执行'); +}); +``` + +## PerformanceMonitor + +性能监控器，监控游戏性能： + +```typescript +const monitor = Core.services.resolve(PerformanceMonitor); + +// 启用性能监控 +monitor.enable(); + +// 获取性能数据 +const fps = monitor.getFPS(); +``` + +## SceneManager + +场景管理器，管理单场景应用的场景生命周期： + +```typescript +const sceneManager = Core.services.resolve(SceneManager); + +// 设置当前场景 +sceneManager.setScene(new GameScene()); + +// 获取当前场景 +const currentScene = sceneManager.currentScene; + +// 延迟切换场景 +sceneManager.loadScene(new MenuScene()); +``` + +## WorldManager + +世界管理器，管理多个独立的 World 实例（高级用例）： + +```typescript +const worldManager = Core.services.resolve(WorldManager); + +// 创建独立的游戏世界 +const gameWorld = worldManager.createWorld('game_room_001', { + name: 'GameRoom', + maxScenes: 5 +}); + +// 在World中创建场景 +const scene = gameWorld.createScene('battle', new BattleScene()); +gameWorld.setSceneActive('battle', true); + +// 更新所有World +worldManager.updateAll(); +``` + +**适用场景**: +- **SceneManager**: 适用于 95% 的游戏（单人游戏、简单多人游戏） +- **WorldManager**: 适用于 MMO 服务器、游戏房间系统等需要完全隔离的多世界应用 + +## PoolManager + +对象池管理器： + +```typescript +const poolManager = Core.services.resolve(PoolManager); + +// 创建对象池 +const bulletPool = poolManager.createPool('bullets', () => new Bullet(), 100); +``` + +## PluginManager + +插件管理器，管理插件的安装和卸载： + +```typescript +const pluginManager = Core.services.resolve(PluginManager); + +// 获取所有已安装的插件 +const plugins = pluginManager.getAllPlugins(); +``` diff --git a/docs/src/content/docs/guide/service-container/dependency-injection.md b/docs/src/content/docs/guide/service-container/dependency-injection.md new file mode 100644 index 00000000..0635fb0b --- /dev/null +++ b/docs/src/content/docs/guide/service-container/dependency-injection.md @@ -0,0 +1,190 @@ +--- +title: "依赖注入" +description: "装饰器和自动依赖注入" +--- + +ECS Framework 提供了装饰器来简化依赖注入。 + +## @Injectable 装饰器 + +标记类为可注入的服务： + +```typescript +import { Injectable, IService } from '@esengine/ecs-framework'; + +@Injectable() +class GameService implements IService { + constructor() { + console.log('GameService created'); + } + + dispose(): void { + console.log('GameService disposed'); + } +} +``` + +## @InjectProperty 装饰器 + +通过属性装饰器注入依赖。注入时机是在构造函数执行后、`onInitialize()` 调用前完成： + +```typescript +import { Injectable, InjectProperty, IService } from '@esengine/ecs-framework'; + +@Injectable() +class PlayerService implements IService { + @InjectProperty(DataService) + private data!: DataService; + + @InjectProperty(GameService) + private game!: GameService; + + dispose(): void { + // 清理资源 + } +} +``` + +### 在 EntitySystem 中使用 + +```typescript +@Injectable() +class CombatSystem extends EntitySystem { + @InjectProperty(TimeService) + private timeService!: TimeService; + + @InjectProperty(AudioService) + private audio!: AudioService; + + constructor() { + super(Matcher.all(Health, Attack)); + } + + onInitialize(): void { + // 此时属性已注入完成，可以安全使用 + console.log('Delta time:', this.timeService.getDeltaTime()); + } + + processEntity(entity: Entity): void { + this.audio.playSound('attack'); + } +} +``` + +> **注意**: 属性声明时使用 `!` 断言（如 `private data!: DataService`），表示该属性会在使用前被注入。 + +## 注册可注入服务 + +使用 `registerInjectable` 自动处理依赖注入： + +```typescript +import { registerInjectable } from '@esengine/ecs-framework'; + +// 注册服务（会自动解析 @InjectProperty 依赖） +registerInjectable(Core.services, PlayerService); + +// 解析时会自动注入属性依赖 +const player = Core.services.resolve(PlayerService); +``` + +## @Updatable 装饰器 + +标记服务为可更新的，使其在每帧自动被调用： + +```typescript +import { Injectable, Updatable, IService, IUpdatable } from '@esengine/ecs-framework'; + +@Injectable() +@Updatable() // 默认优先级为0 +class PhysicsService implements IService, IUpdatable { + update(deltaTime?: number): void { + // 每帧更新物理模拟 + } + + dispose(): void {} +} + +// 指定更新优先级（数值越小越先执行） +@Injectable() +@Updatable(10) +class RenderService implements IService, IUpdatable { + update(deltaTime?: number): void { + // 每帧渲染 + } + + dispose(): void {} +} +``` + +使用 `@Updatable` 装饰器的服务会被 Core 自动调用： + +```typescript +function gameLoop(deltaTime: number) { + Core.update(deltaTime); // 自动更新所有可更新服务 +} +``` + +## 服务间依赖 + +推荐使用 `@InjectProperty` 进行服务间依赖注入： + +```typescript +@Injectable() +class ConfigService implements IService { + private config: any = {}; + + get(key: string) { + return this.config[key]; + } + + dispose(): void { + this.config = {}; + } +} + +@Injectable() +class NetworkService implements IService { + @InjectProperty(ConfigService) + private config!: ConfigService; + + onInitialize(): void { + // 在 onInitialize 中使用注入的服务 + const apiUrl = this.config.get('apiUrl'); + } + + dispose(): void {} +} + +// 注册服务（按依赖顺序） +registerInjectable(Core.services, ConfigService); +registerInjectable(Core.services, NetworkService); +``` + +## @Inject 构造函数装饰器 + +:::caution[兼容性警告] +`@Inject` 构造函数参数装饰器在 **Cocos Creator** 和 **LayaAir** 中可能不被支持，因为这些引擎的打包工具对构造函数参数装饰器的处理可能存在问题。 + +**推荐**: 始终使用 `@InjectProperty` 属性装饰器，它在所有平台上都能正常工作。 +::: + +```typescript +// ⚠️ 不推荐：构造函数注入（Cocos/Laya 可能不支持） +@Injectable() +class NetworkService implements IService { + constructor( + @Inject(ConfigService) private config: ConfigService + ) {} +} + +// ✅ 推荐：属性注入（所有平台兼容） +@Injectable() +class NetworkService implements IService { + @InjectProperty(ConfigService) + private config!: ConfigService; + + onInitialize(): void { + // 在这里使用注入的服务 + } +} +``` diff --git a/docs/src/content/docs/guide/service-container/index.md b/docs/src/content/docs/guide/service-container/index.md new file mode 100644 index 00000000..8431fffd --- /dev/null +++ b/docs/src/content/docs/guide/service-container/index.md @@ -0,0 +1,123 @@ +--- +title: "服务容器概述" +description: "ECS Framework 依赖注入容器" +--- + +服务容器（ServiceContainer）是 ECS Framework 的依赖注入容器，负责管理框架中所有服务的注册、解析和生命周期。 + +## 什么是服务容器 + +服务容器是一个轻量级的依赖注入（DI）容器，它提供了： + +- **服务注册**: 将服务类型注册到容器中 +- **服务解析**: 从容器中获取服务实例 +- **生命周期管理**: 自动管理服务实例的创建和销毁 +- **依赖注入**: 自动解析服务之间的依赖关系 + +## 核心概念 + +### 服务（Service） + +服务是实现了 `IService` 接口的类，必须提供 `dispose()` 方法用于资源清理： + +```typescript +import { IService } from '@esengine/ecs-framework'; + +class MyService implements IService { + constructor() { + // 初始化逻辑 + } + + dispose(): void { + // 清理资源 + } +} +``` + +### 服务标识符 + +服务标识符用于在容器中唯一标识一个服务，支持两种类型： + +- **类构造函数**: 直接使用服务类作为标识符 +- **Symbol**: 使用 Symbol 作为标识符（推荐用于接口抽象） + +```typescript +// 方式1: 使用类作为标识符 +Core.services.registerSingleton(DataService); +const data = Core.services.resolve(DataService); + +// 方式2: 使用 Symbol 作为标识符 +const IFileSystem = Symbol.for('IFileSystem'); +Core.services.registerInstance(IFileSystem, new TauriFileSystem()); +const fs = Core.services.resolve(IFileSystem); +``` + +### 生命周期 + +- **Singleton（单例）**: 整个应用生命周期内只有一个实例 +- **Transient（瞬时）**: 每次解析都创建新的实例 + +## 容器层级 + +ECS Framework 提供了三级服务容器： + +``` +Core.services (应用程序全局) + └─ World.services (World 级别) + └─ Scene.services (Scene 级别) +``` + +```typescript +// Core 级别 +const container = Core.services; + +// World 级别 +const worldContainer = world.services; + +// Scene 级别 +const sceneContainer = scene.services; +``` + +## 基础使用 + +### 注册服务 + +```typescript +// 单例服务 +Core.services.registerSingleton(DataService); + +// 瞬时服务 +Core.services.registerTransient(CommandService); + +// 注册实例 +Core.services.registerInstance(ConfigService, config); + +// 工厂函数 +Core.services.registerSingleton(LoggerService, (container) => { + const logger = new LoggerService(); + logger.setLevel('debug'); + return logger; +}); +``` + +### 解析服务 + +```typescript +// 解析服务（未注册会抛异常） +const dataService = Core.services.resolve(DataService); + +// 尝试解析（未注册返回 null） +const optional = Core.services.tryResolve(OptionalService); + +// 检查是否已注册 +if (Core.services.isRegistered(DataService)) { + // ... +} +``` + +## 下一步 + +- [内置服务](./built-in-services/) - 框架提供的内置服务 +- [依赖注入](./dependency-injection/) - 装饰器和自动注入 +- [PluginServiceRegistry](./plugin-service-registry/) - 插件服务注册表 +- [高级用法](./advanced/) - Symbol 模式、最佳实践 diff --git a/docs/src/content/docs/guide/service-container/plugin-service-registry.md b/docs/src/content/docs/guide/service-container/plugin-service-registry.md new file mode 100644 index 00000000..571de9b5 --- /dev/null +++ b/docs/src/content/docs/guide/service-container/plugin-service-registry.md @@ -0,0 +1,182 @@ +--- +title: "PluginServiceRegistry" +description: "类型安全的插件服务注册表" +--- + +`PluginServiceRegistry` 是基于 `ServiceToken` 的类型安全服务注册表，专门用于跨插件共享服务。 + +## 设计原则 + +1. **类型安全** - 使用 ServiceToken 携带类型信息 +2. **显式依赖** - 通过导入 token 明确表达依赖关系 +3. **可选依赖** - `get` 返回 undefined，`require` 抛异常 +4. **单一职责** - 只负责服务注册和查询，不涉及生命周期管理 +5. **谁定义接口，谁导出 Token** - 各模块定义自己的接口和 Token + +## ServiceToken + +服务令牌用于类型安全的服务注册和获取： + +```typescript +import { createServiceToken, ServiceToken } from '@esengine/ecs-framework'; + +// 定义接口 +interface IAssetManager { + load(path: string): Promise; + unload(path: string): void; +} + +// 创建服务令牌 +const AssetManagerToken = createServiceToken('assetManager'); +``` + +### 为什么使用 ServiceToken + +- **跨包类型安全**: TypeScript 在跨包类型解析时保留泛型类型信息 +- **全局唯一**: 使用 `Symbol.for()` 确保相同名称的令牌在不同模块中引用同一个 Symbol +- **显式依赖**: 通过导入 token 明确表达模块间的依赖关系 + +## 基础使用 + +### 注册服务 + +```typescript +import { PluginServiceRegistry, createServiceToken } from '@esengine/ecs-framework'; + +// 创建注册表 +const registry = new PluginServiceRegistry(); + +// 定义令牌 +interface ILogger { + log(message: string): void; +} +const LoggerToken = createServiceToken('logger'); + +// 注册服务 +const logger: ILogger = { + log: (msg) => console.log(msg) +}; +registry.register(LoggerToken, logger); +``` + +### 获取服务 + +```typescript +// 可选获取（返回 undefined 如果不存在） +const logger = registry.get(LoggerToken); +if (logger) { + logger.log('Hello'); +} + +// 必需获取（抛异常如果不存在） +try { + const logger = registry.require(LoggerToken); + logger.log('Hello'); +} catch (e) { + console.error('Logger not registered'); +} +``` + +### 检查和注销 + +```typescript +// 检查是否已注册 +if (registry.has(LoggerToken)) { + // ... +} + +// 注销服务 +registry.unregister(LoggerToken); + +// 清空所有服务 +registry.clear(); +``` + +## 在插件中使用 + +### 定义模块的服务令牌 + +每个模块应在 `tokens.ts` 中定义自己的接口和令牌： + +```typescript +// packages/asset-system/src/tokens.ts +import { createServiceToken } from '@esengine/ecs-framework'; + +export interface IAssetManager { + load(path: string): Promise; + unload(path: string): void; + getCache(path: string): any | undefined; +} + +export const AssetManagerToken = createServiceToken('assetManager'); +``` + +### 在插件中注册服务 + +```typescript +// packages/asset-system/src/AssetSystemPlugin.ts +import { Core } from '@esengine/ecs-framework'; +import { AssetManagerToken, IAssetManager } from './tokens'; +import { AssetManager } from './AssetManager'; + +export function installAssetSystem() { + const assetManager = new AssetManager(); + + // 注册到 Core 的插件服务注册表 + Core.pluginServices.register(AssetManagerToken, assetManager); +} +``` + +### 在其他插件中使用 + +```typescript +// packages/sprite/src/SpriteSystem.ts +import { Core } from '@esengine/ecs-framework'; +import { AssetManagerToken, IAssetManager } from '@esengine/asset-system'; + +class SpriteSystem extends EntitySystem { + private assetManager!: IAssetManager; + + onInitialize(): void { + // 从插件服务注册表获取 + this.assetManager = Core.pluginServices.require(AssetManagerToken); + } + + async loadSprite(path: string) { + const texture = await this.assetManager.load(path); + // ... + } +} +``` + +## 与 ServiceContainer 的区别 + +| 特性 | ServiceContainer | PluginServiceRegistry | +|------|------------------|----------------------| +| 用途 | 通用依赖注入 | 跨插件服务共享 | +| 标识符 | 类或 Symbol | ServiceToken | +| 生命周期 | Singleton/Transient | 无（由调用者管理） | +| 装饰器支持 | @Injectable, @InjectProperty | 无 | +| 类型安全 | 需要泛型断言 | Token 自带类型 | + +## API 参考 + +### createServiceToken + +```typescript +function createServiceToken(name: string): ServiceToken +``` + +创建服务令牌。使用 `Symbol.for()` 确保跨包共享。 + +### PluginServiceRegistry + +| 方法 | 描述 | +|------|------| +| `register(token, service)` | 注册服务 | +| `get(token): T \| undefined` | 获取服务（可选） | +| `require(token): T` | 获取服务（必需，不存在抛异常） | +| `has(token): boolean` | 检查是否已注册 | +| `unregister(token): boolean` | 注销服务 | +| `clear()` | 清空所有服务 | +| `dispose()` | 释放资源 | diff --git a/docs/src/content/docs/guide/system/best-practices.md b/docs/src/content/docs/guide/system/best-practices.md new file mode 100644 index 00000000..2a995bd3 --- /dev/null +++ b/docs/src/content/docs/guide/system/best-practices.md @@ -0,0 +1,368 @@ +--- +title: "最佳实践" +description: "系统设计最佳实践和复杂示例" +--- + +## 设计原则 + +### 1. 系统单一职责 + +```typescript +// ✅ 好的系统设计 - 职责单一 +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + } +} + +@ECSSystem('Rendering') +class RenderingSystem extends EntitySystem { + constructor() { + super(Matcher.all(Sprite, Transform)); + } +} + +// ❌ 避免的系统设计 - 职责过多 +@ECSSystem('GameSystem') +class GameSystem extends EntitySystem { + // 一个系统处理移动、渲染、音效等多种逻辑 +} +``` + +### 2. 使用 @ECSSystem 装饰器 + +`@ECSSystem` 是系统类必须使用的装饰器，它为系统提供类型标识和元数据管理。 + +| 功能 | 说明 | +|------|------| +| **类型识别** | 提供稳定的系统名称，代码混淆后仍能正确识别 | +| **调试支持** | 在性能监控、日志和调试工具中显示可读的系统名称 | +| **系统管理** | 通过名称查找和管理系统 | +| **序列化支持** | 场景序列化时可以记录系统配置 | + +```typescript +// ✅ 正确的用法 +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + // 系统实现 +} + +// ✅ 推荐：使用描述性的名称 +@ECSSystem('PlayerMovement') +class PlayerMovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Player, Position, Velocity)); + } +} + +// ❌ 错误的用法 - 没有装饰器 +class BadSystem extends EntitySystem { + // 这样定义的系统可能在生产环境出现问题 +} +``` + +### 3. 合理的更新顺序 + +```typescript +// 按逻辑顺序设置系统的更新时序 +@ECSSystem('Input') +class InputSystem extends EntitySystem { + constructor() { + super(); + this.updateOrder = -100; // 最先处理输入 + } +} + +@ECSSystem('Logic') +class GameLogicSystem extends EntitySystem { + constructor() { + super(); + this.updateOrder = 0; // 处理游戏逻辑 + } +} + +@ECSSystem('Render') +class RenderSystem extends EntitySystem { + constructor() { + super(); + this.updateOrder = 100; // 最后进行渲染 + } +} +``` + +### 4. 避免在系统间直接引用 + +```typescript +// ❌ 避免：系统间直接引用 +@ECSSystem('Bad') +class BadSystem extends EntitySystem { + private otherSystem: SomeOtherSystem; // 避免直接引用其他系统 +} + +// ✅ 推荐：通过事件系统通信 +@ECSSystem('Good') +class GoodSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // 通过事件系统与其他系统通信 + this.scene?.eventSystem.emitSync('data_updated', { entities }); + } +} +``` + +### 5. 及时清理资源 + +```typescript +@ECSSystem('Resource') +class ResourceSystem extends EntitySystem { + private resources: Map = new Map(); + + protected onDestroy(): void { + // 清理资源 + for (const [key, resource] of this.resources) { + if (resource.dispose) { + resource.dispose(); + } + } + this.resources.clear(); + } +} +``` + +## 复杂系统示例 + +### 碰撞检测系统 + +```typescript +@ECSSystem('Collision') +class CollisionSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, Collider)); + } + + protected process(entities: readonly Entity[]): void { + // 简单的 n² 碰撞检测 + for (let i = 0; i < entities.length; i++) { + for (let j = i + 1; j < entities.length; j++) { + this.checkCollision(entities[i], entities[j]); + } + } + } + + private checkCollision(entityA: Entity, entityB: Entity): void { + const transformA = entityA.getComponent(Transform); + const transformB = entityB.getComponent(Transform); + const colliderA = entityA.getComponent(Collider); + const colliderB = entityB.getComponent(Collider); + + if (this.isColliding(transformA, colliderA, transformB, colliderB)) { + // 发送碰撞事件 + this.scene?.eventSystem.emitSync('collision', { + entityA, + entityB + }); + } + } + + private isColliding( + transformA: Transform, colliderA: Collider, + transformB: Transform, colliderB: Collider + ): boolean { + // 碰撞检测逻辑 + const dx = transformA.x - transformB.x; + const dy = transformA.y - transformB.y; + const distance = Math.sqrt(dx * dx + dy * dy); + return distance < colliderA.radius + colliderB.radius; + } +} +``` + +### 状态机系统 + +```typescript +enum EntityState { + Idle, + Moving, + Attacking, + Dead +} + +@ECSSystem('StateMachine') +class StateMachineSystem extends EntitySystem { + constructor() { + super(Matcher.all(StateMachine)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const stateMachine = entity.getComponent(StateMachine); + if (stateMachine) { + stateMachine.updateTimer(Time.deltaTime); + this.updateState(entity, stateMachine); + } + } + } + + private updateState(entity: Entity, stateMachine: StateMachine): void { + switch (stateMachine.currentState) { + case EntityState.Idle: + this.handleIdleState(entity, stateMachine); + break; + case EntityState.Moving: + this.handleMovingState(entity, stateMachine); + break; + case EntityState.Attacking: + this.handleAttackingState(entity, stateMachine); + break; + } + } + + private handleIdleState(entity: Entity, sm: StateMachine): void { + // 检查是否有移动输入 + const input = entity.getComponent(InputComponent); + if (input && input.hasMovementInput()) { + sm.changeState(EntityState.Moving); + } + } + + private handleMovingState(entity: Entity, sm: StateMachine): void { + // 检查是否停止移动 + const input = entity.getComponent(InputComponent); + if (!input || !input.hasMovementInput()) { + sm.changeState(EntityState.Idle); + } + } + + private handleAttackingState(entity: Entity, sm: StateMachine): void { + // 攻击动画完成后返回空闲 + if (sm.stateTimer > 0.5) { + sm.changeState(EntityState.Idle); + } + } +} +``` + +### AI 行为系统 + +```typescript +@ECSSystem('AIBehavior') +class AIBehaviorSystem extends EntitySystem { + constructor() { + super(Matcher.all(AIComponent, Transform).none(Dead)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const ai = entity.getComponent(AIComponent)!; + const transform = entity.getComponent(Transform)!; + + switch (ai.state) { + case AIState.Patrol: + this.patrol(entity, ai, transform); + break; + case AIState.Chase: + this.chase(entity, ai, transform); + break; + case AIState.Attack: + this.attack(entity, ai); + break; + } + } + } + + private patrol(entity: Entity, ai: AIComponent, transform: Transform): void { + // 移动到巡逻点 + const target = ai.patrolPoints[ai.currentPatrolIndex]; + const dx = target.x - transform.x; + const dy = target.y - transform.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance < 5) { + // 到达巡逻点，前往下一个 + ai.currentPatrolIndex = (ai.currentPatrolIndex + 1) % ai.patrolPoints.length; + } else { + // 朝巡逻点移动 + const speed = ai.moveSpeed * Time.deltaTime; + transform.x += (dx / distance) * speed; + transform.y += (dy / distance) * speed; + } + + // 检测玩家 + if (this.detectPlayer(entity, ai)) { + ai.state = AIState.Chase; + } + } + + private chase(entity: Entity, ai: AIComponent, transform: Transform): void { + const player = this.findPlayer(); + if (!player) { + ai.state = AIState.Patrol; + return; + } + + const playerTransform = player.getComponent(Transform)!; + const dx = playerTransform.x - transform.x; + const dy = playerTransform.y - transform.y; + const distance = Math.sqrt(dx * dx + dy * dy); + + if (distance < ai.attackRange) { + ai.state = AIState.Attack; + } else if (distance > ai.chaseRange) { + ai.state = AIState.Patrol; + } else { + // 追逐玩家 + const speed = ai.chaseSpeed * Time.deltaTime; + transform.x += (dx / distance) * speed; + transform.y += (dy / distance) * speed; + } + } + + private attack(entity: Entity, ai: AIComponent): void { + ai.attackCooldown -= Time.deltaTime; + if (ai.attackCooldown <= 0) { + // 执行攻击 + this.scene?.eventSystem.emitSync('ai_attack', { attacker: entity }); + ai.attackCooldown = ai.attackInterval; + } + } + + private detectPlayer(entity: Entity, ai: AIComponent): boolean { + // 玩家检测逻辑 + return false; + } + + private findPlayer(): Entity | null { + const result = this.scene?.querySystem.queryByTag(Tags.PLAYER); + return result?.entities[0] ?? null; + } +} +``` + +## 常见问题 + +### 问：系统应该有多大？ + +**答**：遵循单一职责原则。如果一个系统处理多种不相关的逻辑，应该拆分成多个系统。 + +### 问：如何处理系统间的数据共享？ + +**答**： +1. 通过组件共享数据（推荐） +2. 通过事件系统通信 +3. 通过服务容器注入共享服务 + +### 问：什么时候用 CommandBuffer？ + +**答**：当需要在迭代过程中销毁实体时，使用 CommandBuffer。添加/移除组件可以直接操作。 + +### 问：如何优化大量实体的处理？ + +**答**： +1. 使用变更检测，只处理变化的实体 +2. 使用 WorkerEntitySystem 并行处理 +3. 优化 Matcher 条件，减少匹配的实体数量 +4. 考虑使用空间分区（Spatial Partitioning） + +--- + +系统是 ECS 架构的逻辑处理核心，正确设计和使用系统能让你的游戏代码更加模块化、高效和易于维护。 diff --git a/docs/src/content/docs/guide/system/change-detection.md b/docs/src/content/docs/guide/system/change-detection.md new file mode 100644 index 00000000..fbfbfaf5 --- /dev/null +++ b/docs/src/content/docs/guide/system/change-detection.md @@ -0,0 +1,252 @@ +--- +title: "变更检测" +description: "帧级变更检测优化系统性能" +--- + +> **v2.4.0+** + +框架提供了基于 epoch 的帧级变更检测机制，让系统可以只处理发生变化的实体，大幅提升性能。 + +## 核心概念 + +- **Epoch**：全局帧计数器，每帧递增 +- **lastWriteEpoch**：组件最后被修改时的 epoch +- **变更检测**：通过比较 epoch 判断组件是否在指定时间点后发生变化 + +## 标记组件为已修改 + +修改组件数据后，需要标记组件为已变更。有两种方式： + +### 方式 1：通过 Entity 辅助方法（推荐） + +```typescript +// 修改组件后通过 entity.markDirty() 标记 +const pos = entity.getComponent(Position)!; +pos.x = 100; +pos.y = 200; +entity.markDirty(pos); + +// 可以同时标记多个组件 +const vel = entity.getComponent(Velocity)!; +vel.vx = 10; +entity.markDirty(pos, vel); +``` + +### 方式 2：在组件内部封装 + +```typescript +class VelocityComponent extends Component { + private _vx: number = 0; + private _vy: number = 0; + + // 提供修改方法，接收 epoch 参数 + public setVelocity(vx: number, vy: number, epoch: number): void { + this._vx = vx; + this._vy = vy; + this.markDirty(epoch); + } + + public get vx(): number { return this._vx; } + public get vy(): number { return this._vy; } +} + +// 在系统中使用 +const vel = entity.getComponent(VelocityComponent)!; +vel.setVelocity(10, 20, this.currentEpoch); +``` + +## 在系统中使用变更检测 + +EntitySystem 提供了多个变更检测辅助方法： + +### forEachChanged - 遍历变更实体 + +```typescript +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + // 使用 forEachChanged 只处理变更的实体 + // 自动保存 epoch 检查点 + this.forEachChanged(entities, [Velocity], (entity) => { + const pos = this.requireComponent(entity, Position); + const vel = this.requireComponent(entity, Velocity); + + // 只有 Velocity 变化时才更新位置 + pos.x += vel.vx * Time.deltaTime; + pos.y += vel.vy * Time.deltaTime; + }); + } +} +``` + +### filterChanged - 获取变更实体列表 + +```typescript +@ECSSystem('Transform') +class TransformSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, RigidBody)); + } + + protected process(entities: readonly Entity[]): void { + // 使用 filterChanged 获取变更的实体列表 + const changedEntities = this.filterChanged(entities, [RigidBody]); + + for (const entity of changedEntities) { + // 处理物理状态变化的实体 + this.updatePhysics(entity); + } + + // 手动保存 epoch 检查点 + this.saveEpoch(); + } + + protected updatePhysics(entity: Entity): void { + // 物理更新逻辑 + } +} +``` + +### hasChanged - 检查单个实体 + +```typescript +protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + // 检查单个实体的指定组件是否发生变更 + if (this.hasChanged(entity, [Transform])) { + this.updateRenderData(entity); + } + } +} +``` + +## 变更检测 API 参考 + +| 方法 | 说明 | +|------|------| +| `forEachChanged(entities, [Types], callback)` | 遍历指定组件发生变更的实体，自动保存检查点 | +| `filterChanged(entities, [Types])` | 返回指定组件发生变更的实体数组 | +| `hasChanged(entity, [Types])` | 检查单个实体的指定组件是否发生变更 | +| `saveEpoch()` | 手动保存当前 epoch 作为检查点 | +| `lastProcessEpoch` | 获取上次保存的 epoch 检查点 | +| `currentEpoch` | 获取当前场景的 epoch | + +## 使用场景 + +变更检测特别适合以下场景： + +### 1. 脏标记优化 + +只在数据变化时更新渲染： + +```typescript +@ECSSystem('RenderUpdate') +class RenderUpdateSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, Sprite)); + } + + protected process(entities: readonly Entity[]): void { + // 只更新变化的精灵 + this.forEachChanged(entities, [Transform, Sprite], (entity) => { + const transform = this.requireComponent(entity, Transform); + const sprite = this.requireComponent(entity, Sprite); + + this.updateSpriteMatrix(sprite, transform); + }); + } +} +``` + +### 2. 网络同步 + +只发送变化的组件数据： + +```typescript +@ECSSystem('NetworkSync') +class NetworkSyncSystem extends EntitySystem { + constructor() { + super(Matcher.all(NetworkComponent, Transform)); + } + + protected process(entities: readonly Entity[]): void { + // 只同步变化的实体，大幅减少网络流量 + this.forEachChanged(entities, [Transform], (entity) => { + const transform = this.requireComponent(entity, Transform); + const network = this.requireComponent(entity, NetworkComponent); + + this.sendTransformUpdate(network.id, transform); + }); + } + + private sendTransformUpdate(id: string, transform: Transform): void { + // 发送网络更新 + } +} +``` + +### 3. 物理同步 + +只同步位置/速度发生变化的实体： + +```typescript +@ECSSystem('PhysicsSync') +class PhysicsSyncSystem extends EntitySystem { + constructor() { + super(Matcher.all(Transform, RigidBody)); + } + + protected process(entities: readonly Entity[]): void { + // 从物理引擎同步变化的实体 + this.forEachChanged(entities, [RigidBody], (entity) => { + const transform = entity.getComponent(Transform)!; + const rigidBody = entity.getComponent(RigidBody)!; + + // 更新 Transform + transform.position = rigidBody.getPosition(); + transform.rotation = rigidBody.getRotation(); + + // 标记 Transform 已变更 + entity.markDirty(transform); + }); + } +} +``` + +### 4. 缓存失效 + +只在依赖数据变化时重新计算： + +```typescript +@ECSSystem('PathCache') +class PathCacheSystem extends EntitySystem { + constructor() { + super(Matcher.all(PathFinder, Transform)); + } + + protected process(entities: readonly Entity[]): void { + // 只有位置变化时才重新计算路径 + this.forEachChanged(entities, [Transform], (entity) => { + const pathFinder = entity.getComponent(PathFinder)!; + pathFinder.invalidateCache(); + pathFinder.recalculatePath(); + }); + } +} +``` + +## 性能对比 + +| 场景 | 无变更检测 | 有变更检测 | 提升 | +|------|------------|------------|------| +| 1000 实体，10% 变化 | 1000 次处理 | 100 次处理 | 10x | +| 1000 实体，1% 变化 | 1000 次处理 | 10 次处理 | 100x | +| 网络同步 | 全量发送 | 增量发送 | 带宽节省 90%+ | + +:::tip +变更检测最适合"大量实体，少量变化"的场景。如果大部分实体每帧都变化，变更检测的开销可能得不偿失。 +::: diff --git a/docs/src/content/docs/guide/system/command-buffer.md b/docs/src/content/docs/guide/system/command-buffer.md new file mode 100644 index 00000000..47f0e739 --- /dev/null +++ b/docs/src/content/docs/guide/system/command-buffer.md @@ -0,0 +1,172 @@ +--- +title: "命令缓冲区" +description: "使用 CommandBuffer 延迟执行实体操作" +--- + +> **v2.3.0+** + +CommandBuffer 提供了一种延迟执行实体操作的机制。当你需要在迭代过程中销毁实体或进行其他可能影响迭代的操作时，使用 CommandBuffer 可以将这些操作推迟到帧末统一执行。 + +## 基本用法 + +每个 EntitySystem 都内置了 `commands` 属性： + +```typescript +@ECSSystem('Damage') +class DamageSystem extends EntitySystem { + constructor() { + super(Matcher.all(Health, DamageReceiver)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health); + const damage = entity.getComponent(DamageReceiver); + + if (health && damage) { + health.current -= damage.amount; + + // 使用命令缓冲区延迟移除组件 + this.commands.removeComponent(entity, DamageReceiver); + + if (health.current <= 0) { + // 延迟添加死亡标记 + this.commands.addComponent(entity, new Dead()); + // 延迟销毁实体 + this.commands.destroyEntity(entity); + } + } + } + } +} +``` + +## 支持的命令 + +| 方法 | 说明 | +|------|------| +| `addComponent(entity, component)` | 延迟添加组件 | +| `removeComponent(entity, ComponentType)` | 延迟移除组件 | +| `destroyEntity(entity)` | 延迟销毁实体 | +| `setEntityActive(entity, active)` | 延迟设置实体激活状态 | + +## 执行时机 + +命令缓冲区中的命令会在每帧的 `lateUpdate` 阶段之后自动执行。执行顺序与命令入队顺序一致。 + +``` +场景更新流程: +1. onBegin() +2. process() +3. lateProcess() +4. onEnd() +5. flushCommandBuffers() <-- 命令在这里执行 +``` + +## 使用场景 + +CommandBuffer 适用于以下场景： + +### 1. 在迭代中销毁实体 + +避免修改正在遍历的集合： + +```typescript +@ECSSystem('EnemyDeath') +class EnemyDeathSystem extends EntitySystem { + constructor() { + super(Matcher.all(Enemy, Health)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health); + if (health && health.current <= 0) { + // 播放死亡动画、掉落物品等 + this.spawnLoot(entity); + + // 延迟销毁，不影响当前迭代 + this.commands.destroyEntity(entity); + } + } + } + + private spawnLoot(entity: Entity): void { + // 掉落物品逻辑 + } +} +``` + +### 2. 批量延迟操作 + +将多个操作合并到帧末执行： + +```typescript +@ECSSystem('Cleanup') +class CleanupSystem extends EntitySystem { + constructor() { + super(Matcher.all(MarkedForDeletion)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + // 批量收集要删除的实体 + this.commands.destroyEntity(entity); + } + // 所有销毁操作在帧末统一执行 + } +} +``` + +### 3. 跨系统协调 + +一个系统标记，另一个系统响应： + +```typescript +@ECSSystem('Combat') +class CombatSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + if (this.shouldDie(entity)) { + // 标记死亡 + this.commands.addComponent(entity, new Dead()); + } + } + } +} + +@ECSSystem('DeathHandler') +class DeathHandlerSystem extends EntitySystem { + constructor() { + super(Matcher.all(Dead)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + // 处理死亡逻辑 + this.playDeathAnimation(entity); + this.commands.destroyEntity(entity); + } + } +} +``` + +## 注意事项 + +- 命令会跳过已销毁的实体（安全检查） +- 单个命令执行失败不会影响其他命令 +- 命令按入队顺序执行 +- 每次 `flush()` 后命令队列会清空 + +## 直接修改 vs 命令缓冲区 + +| 操作 | 直接修改 | 命令缓冲区 | +|------|----------|------------| +| 添加组件 | ✅ 安全 | ✅ 安全 | +| 移除组件 | ✅ 安全 | ✅ 安全 | +| 销毁实体 | ⚠️ 可能有问题 | ✅ 推荐 | +| 执行时机 | 立即执行 | 帧末执行 | + +:::tip +虽然在 `process` 中添加/移除组件是安全的（因为有快照机制），但如果需要销毁实体，推荐使用命令缓冲区。 +::: diff --git a/docs/src/content/docs/guide/system/index.md b/docs/src/content/docs/guide/system/index.md new file mode 100644 index 00000000..825a1230 --- /dev/null +++ b/docs/src/content/docs/guide/system/index.md @@ -0,0 +1,170 @@ +--- +title: "系统架构" +description: "ECS 系统概述与基本概念" +--- + +在 ECS 架构中，系统（System）是处理业务逻辑的地方。系统负责对拥有特定组件组合的实体执行操作，是 ECS 架构的逻辑处理单元。 + +## 基本概念 + +系统是继承自 `EntitySystem` 抽象基类的具体类，用于： +- 定义实体的处理逻辑（如移动、碰撞检测、渲染等） +- 根据组件组合筛选需要处理的实体 +- 提供生命周期管理和性能监控 +- 管理实体的添加、移除事件 + +## 快速示例 + +```typescript +import { EntitySystem, ECSSystem, Matcher } from '@esengine/ecs-framework'; + +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + // 使用 Matcher 定义需要处理的实体条件 + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const position = entity.getComponent(Position); + const velocity = entity.getComponent(Velocity); + + if (position && velocity) { + position.x += velocity.dx * Time.deltaTime; + position.y += velocity.dy * Time.deltaTime; + } + } + } +} +``` + +## 系统属性和方法 + +### 重要属性 + +```typescript +@ECSSystem('Example') +class ExampleSystem extends EntitySystem { + showSystemInfo(): void { + console.log(`系统名称: ${this.systemName}`); // 系统名称 + console.log(`更新顺序: ${this.updateOrder}`); // 更新时序 + console.log(`是否启用: ${this.enabled}`); // 启用状态 + console.log(`实体数量: ${this.entities.length}`); // 匹配的实体数量 + console.log(`所属场景: ${this.scene?.name}`); // 所属场景 + } +} +``` + +### 实体访问 + +```typescript +protected process(entities: readonly Entity[]): void { + // 方式1：使用参数中的实体列表 + for (const entity of entities) { + // 处理实体 + } + + // 方式2：使用 this.entities 属性（与参数相同） + for (const entity of this.entities) { + // 处理实体 + } +} +``` + +### 控制系统执行 + +```typescript +@ECSSystem('Conditional') +class ConditionalSystem extends EntitySystem { + private shouldProcess = true; + + protected onCheckProcessing(): boolean { + // 返回 false 时跳过本次处理 + return this.shouldProcess && this.entities.length > 0; + } + + public pause(): void { + this.shouldProcess = false; + } + + public resume(): void { + this.shouldProcess = true; + } +} +``` + +## 系统管理 + +### 添加系统到场景 + +框架提供了两种方式添加系统：传入实例或传入类型（自动依赖注入）。 + +```typescript +// 在场景子类中添加系统 +class GameScene extends Scene { + protected initialize(): void { + // 方式1：传入实例 + this.addSystem(new MovementSystem()); + this.addSystem(new RenderSystem()); + + // 方式2：传入类型（自动依赖注入） + this.addEntityProcessor(PhysicsSystem); + + // 设置系统更新顺序 + const movementSystem = this.getSystem(MovementSystem); + if (movementSystem) { + movementSystem.updateOrder = 1; + } + } +} +``` + +### 系统更新顺序 + +系统的执行顺序由 `updateOrder` 属性决定，数值越小越先执行： + +```typescript +@ECSSystem('Input') +class InputSystem extends EntitySystem { + constructor() { + super(Matcher.all(InputComponent)); + this.updateOrder = -100; // 输入系统优先执行 + } +} + +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + constructor() { + super(Matcher.all(RigidBody)); + this.updateOrder = 0; // 默认顺序 + } +} + +@ECSSystem('Render') +class RenderSystem extends EntitySystem { + constructor() { + super(Matcher.all(Sprite, Transform)); + this.updateOrder = 100; // 渲染系统最后执行 + } +} +``` + +#### 稳定排序：addOrder + +当多个系统的 `updateOrder` 相同时，框架使用 `addOrder`（添加顺序）作为第二排序条件： + +```typescript +// 这两个系统 updateOrder 都是默认值 0 +scene.addSystem(new SystemA()); // addOrder = 0，先执行 +scene.addSystem(new SystemB()); // addOrder = 1，后执行 +``` + +## 下一步 + +- [系统类型](/guide/system/types) - 了解不同类型的系统基类 +- [系统生命周期](/guide/system/lifecycle) - 生命周期回调和事件监听 +- [命令缓冲区](/guide/system/command-buffer) - 延迟执行实体操作 +- [系统调度](/guide/system/scheduling) - 声明式系统调度 +- [变更检测](/guide/system/change-detection) - 帧级变更检测优化 +- [最佳实践](/guide/system/best-practices) - 系统设计最佳实践 diff --git a/docs/src/content/docs/guide/system/lifecycle.md b/docs/src/content/docs/guide/system/lifecycle.md new file mode 100644 index 00000000..380f6a9b --- /dev/null +++ b/docs/src/content/docs/guide/system/lifecycle.md @@ -0,0 +1,249 @@ +--- +title: "系统生命周期" +description: "系统生命周期回调、事件监听和依赖注入" +--- + +## 生命周期回调 + +系统提供了完整的生命周期回调： + +```typescript +@ECSSystem('Example') +class ExampleSystem extends EntitySystem { + protected onInitialize(): void { + console.log('系统初始化'); + // 系统被添加到场景时调用，用于初始化资源 + } + + protected onBegin(): void { + // 每帧处理开始前调用 + } + + protected process(entities: readonly Entity[]): void { + // 主要的处理逻辑 + for (const entity of entities) { + // 处理每个实体 + // ✅ 可以安全地在这里添加/移除组件，不会影响当前迭代 + } + } + + protected lateProcess(entities: readonly Entity[]): void { + // 主处理之后的后期处理 + // ✅ 可以安全地在这里添加/移除组件，不会影响当前迭代 + } + + protected onEnd(): void { + // 每帧处理结束后调用 + } + + protected onDestroy(): void { + console.log('系统销毁'); + // 系统从场景移除时调用，用于清理资源 + } +} +``` + +## 实体事件监听 + +系统可以监听实体的添加和移除事件： + +```typescript +@ECSSystem('EnemyManager') +class EnemyManagerSystem extends EntitySystem { + private enemyCount = 0; + + constructor() { + super(Matcher.all(Enemy, Health)); + } + + protected onAdded(entity: Entity): void { + this.enemyCount++; + console.log(`敌人加入战斗，当前敌人数量: ${this.enemyCount}`); + + // 可以在这里为新敌人设置初始状态 + const health = entity.getComponent(Health); + if (health) { + health.current = health.max; + } + } + + protected onRemoved(entity: Entity): void { + this.enemyCount--; + console.log(`敌人被移除，剩余敌人数量: ${this.enemyCount}`); + + // 检查是否所有敌人都被消灭 + if (this.enemyCount === 0) { + this.scene?.eventSystem.emitSync('all_enemies_defeated'); + } + } +} +``` + +### 重要：onAdded/onRemoved 的调用时机 + +:::caution +`onAdded` 和 `onRemoved` 回调是**同步调用**的，会在 `addComponent`/`removeComponent` 返回**之前**立即执行。 +::: + +这意味着： + +```typescript +// ❌ 错误的用法：链式赋值在 onAdded 之后才执行 +const comp = entity.addComponent(new ClickComponent()); +comp.element = this._element; // 此时 onAdded 已经执行完了！ + +// ✅ 正确的用法：通过构造函数传入初始值 +const comp = entity.addComponent(new ClickComponent(this._element)); + +// ✅ 或者使用 createComponent 方法 +const comp = entity.createComponent(ClickComponent, this._element); +``` + +**为什么这样设计？** + +事件驱动设计确保 `onAdded`/`onRemoved` 回调不受系统注册顺序的影响。当组件被添加时，所有监听该组件的系统都会立即收到通知，而不是等到下一帧。 + +**最佳实践：** + +1. 组件的初始值应该通过**构造函数**传入 +2. 不要依赖 `addComponent` 返回后再设置属性 +3. 如果需要在 `onAdded` 中访问组件属性，确保这些属性在构造时已经设置 + +### 在 process/lateProcess 中安全地修改组件 + +在 `process` 或 `lateProcess` 中迭代实体时，可以安全地添加或移除组件，不会影响当前的迭代过程： + +```typescript +@ECSSystem('Damage') +class DamageSystem extends EntitySystem { + constructor() { + super(Matcher.all(Health, DamageReceiver)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const health = entity.getComponent(Health); + const damage = entity.getComponent(DamageReceiver); + + if (health && damage) { + health.current -= damage.amount; + + // ✅ 安全：移除组件不会影响当前迭代 + entity.removeComponent(damage); + + if (health.current <= 0) { + // ✅ 安全：添加组件也不会影响当前迭代 + entity.addComponent(new Dead()); + } + } + } + } +} +``` + +框架会在每次 `process`/`lateProcess` 调用前创建实体列表的快照，确保迭代过程中的组件变化不会导致跳过实体或重复处理。 + +## 事件系统集成 + +系统可以方便地监听和发送事件： + +```typescript +@ECSSystem('GameLogic') +class GameLogicSystem extends EntitySystem { + protected onInitialize(): void { + // 添加事件监听器（系统销毁时自动清理） + this.addEventListener('player_died', this.onPlayerDied.bind(this)); + this.addEventListener('level_complete', this.onLevelComplete.bind(this)); + } + + private onPlayerDied(data: any): void { + console.log('玩家死亡，重新开始游戏'); + // 处理玩家死亡逻辑 + } + + private onLevelComplete(data: any): void { + console.log('关卡完成，加载下一关'); + // 处理关卡完成逻辑 + } + + protected process(entities: readonly Entity[]): void { + // 在处理过程中发送事件 + for (const entity of entities) { + const health = entity.getComponent(Health); + if (health && health.current <= 0) { + this.scene?.eventSystem.emitSync('entity_died', { entity }); + } + } + } +} +``` + +## 性能监控 + +系统内置了性能监控功能： + +```typescript +@ECSSystem('Performance') +class PerformanceSystem extends EntitySystem { + protected onEnd(): void { + // 获取性能数据 + const perfData = this.getPerformanceData(); + if (perfData) { + console.log(`执行时间: ${perfData.executionTime.toFixed(2)}ms`); + } + + // 获取性能统计 + const stats = this.getPerformanceStats(); + if (stats) { + console.log(`平均执行时间: ${stats.averageTime.toFixed(2)}ms`); + } + } + + public resetPerformance(): void { + this.resetPerformanceData(); + } +} +``` + +## 系统依赖注入 + +系统实现了 `IService` 接口，支持通过依赖注入获取其他服务或系统： + +```typescript +import { ECSSystem, Injectable, InjectProperty } from '@esengine/ecs-framework'; + +@Injectable() +@ECSSystem('Physics') +class PhysicsSystem extends EntitySystem { + @InjectProperty(CollisionService) + private collision!: CollisionService; + + constructor() { + super(Matcher.all(Transform, RigidBody)); + } + + protected process(entities: readonly Entity[]): void { + // 使用注入的服务 + this.collision.detectCollisions(entities); + } + + // 实现 IService 接口的 dispose 方法 + public dispose(): void { + // 清理资源 + } +} + +// 使用时传入类型即可，框架会自动注入依赖 +class GameScene extends Scene { + protected initialize(): void { + // 自动依赖注入 + this.addEntityProcessor(PhysicsSystem); + } +} +``` + +注意事项： +- 使用 `@Injectable()` 装饰器标记需要依赖注入的系统 +- 使用 `@InjectProperty()` 装饰器声明依赖 +- 系统必须实现 `dispose()` 方法（IService 接口要求） +- 使用 `addEntityProcessor(类型)` 而不是 `addSystem(new 类型())` 来启用依赖注入 diff --git a/docs/src/content/docs/guide/system/scheduling.md b/docs/src/content/docs/guide/system/scheduling.md new file mode 100644 index 00000000..9200add7 --- /dev/null +++ b/docs/src/content/docs/guide/system/scheduling.md @@ -0,0 +1,182 @@ +--- +title: "系统调度" +description: "声明式系统调度和执行阶段" +--- + +> **v2.4.0+** + +除了使用 `updateOrder` 手动控制执行顺序外，框架还提供了声明式的系统调度机制，让你可以通过依赖关系来定义系统的执行顺序。 + +## 调度装饰器 + +```typescript +import { EntitySystem, ECSSystem, Stage, Before, After, InSet } from '@esengine/ecs-framework'; + +// 使用装饰器声明系统调度 +@ECSSystem('Movement') +@Stage('update') // 在 update 阶段执行 +@After('InputSystem') // 在 InputSystem 之后执行 +@Before('RenderSystem') // 在 RenderSystem 之前执行 +class MovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + // 移动逻辑 + } +} + +// 使用系统集合进行分组 +@ECSSystem('Physics') +@Stage('update') +@InSet('CoreSystems') // 属于 CoreSystems 集合 +class PhysicsSystem extends EntitySystem { + // ... +} + +@ECSSystem('Collision') +@Stage('update') +@After('set:CoreSystems') // 在 CoreSystems 集合的所有系统之后执行 +class CollisionSystem extends EntitySystem { + // ... +} +``` + +## 系统执行阶段 + +框架定义了以下系统执行阶段，按顺序执行： + +| 阶段 | 说明 | 典型用途 | +|------|------|----------| +| `startup` | 启动阶段 | 一次性初始化 | +| `preUpdate` | 更新前阶段 | 输入处理、状态准备 | +| `update` | 主更新阶段（默认） | 核心游戏逻辑 | +| `postUpdate` | 更新后阶段 | 物理、碰撞检测 | +| `cleanup` | 清理阶段 | 资源清理、状态重置 | + +### 阶段使用示例 + +```typescript +@ECSSystem('Input') +@Stage('preUpdate') // 在更新前阶段处理输入 +class InputSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // 读取输入，更新输入组件 + } +} + +@ECSSystem('Movement') +@Stage('update') // 在主更新阶段处理移动 +class MovementSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // 根据输入移动实体 + } +} + +@ECSSystem('Physics') +@Stage('postUpdate') // 在更新后阶段处理物理 +class PhysicsSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // 物理模拟和碰撞检测 + } +} + +@ECSSystem('Cleanup') +@Stage('cleanup') // 在清理阶段重置状态 +class CleanupSystem extends EntitySystem { + protected process(entities: readonly Entity[]): void { + // 清理临时数据 + } +} +``` + +## Fluent API 配置 + +如果不想使用装饰器，也可以使用 Fluent API 在运行时配置调度： + +```typescript +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + super(Matcher.all(Position, Velocity)); + + // 使用 Fluent API 配置调度 + this.stage('update') + .after('InputSystem') + .before('RenderSystem') + .inSet('CoreSystems'); + } +} +``` + +## 系统集合 + +系统集合允许你将相关系统分组，然后基于整个集合定义依赖： + +```typescript +// 定义核心系统集合 +@ECSSystem('Movement') +@InSet('CoreSystems') +class MovementSystem extends EntitySystem { } + +@ECSSystem('Physics') +@InSet('CoreSystems') +class PhysicsSystem extends EntitySystem { } + +@ECSSystem('AI') +@InSet('CoreSystems') +class AISystem extends EntitySystem { } + +// 在核心系统集合之后执行 +@ECSSystem('Render') +@After('set:CoreSystems') +class RenderSystem extends EntitySystem { } + +// 在核心系统集合之前执行 +@ECSSystem('Input') +@Before('set:CoreSystems') +class InputSystem extends EntitySystem { } +``` + +## 循环依赖检测 + +框架会自动检测循环依赖并抛出明确的错误： + +```typescript +// 这会导致循环依赖错误 +@ECSSystem('SystemA') +@Before('SystemB') +class SystemA extends EntitySystem { } + +@ECSSystem('SystemB') +@Before('SystemA') // 错误：A -> B -> A 形成循环 +class SystemB extends EntitySystem { } + +// 错误信息：Cyclic dependency detected: SystemA -> SystemB -> SystemA +``` + +## 调度装饰器参考 + +| 装饰器 | 说明 | 示例 | +|--------|------|------| +| `@Stage(name)` | 指定执行阶段 | `@Stage('update')` | +| `@Before(system)` | 在指定系统之前执行 | `@Before('RenderSystem')` | +| `@After(system)` | 在指定系统之后执行 | `@After('InputSystem')` | +| `@InSet(name)` | 加入系统集合 | `@InSet('CoreSystems')` | +| `@Before('set:name')` | 在集合之前执行 | `@Before('set:UI')` | +| `@After('set:name')` | 在集合之后执行 | `@After('set:Physics')` | + +## updateOrder vs 声明式调度 + +| 特性 | updateOrder | 声明式调度 | +|------|-------------|------------| +| 配置方式 | 手动设置数值 | 声明依赖关系 | +| 可读性 | 需要记住数值含义 | 直接表达意图 | +| 循环检测 | 无 | 自动检测 | +| 重构友好 | 需要手动调整数值 | 自动处理顺序 | +| 适用场景 | 简单项目 | 复杂依赖关系 | + +:::tip +对于小型项目，`updateOrder` 足够使用。当系统数量增多、依赖关系复杂时，推荐使用声明式调度。 +::: diff --git a/docs/src/content/docs/guide/system/types.md b/docs/src/content/docs/guide/system/types.md new file mode 100644 index 00000000..fafb7708 --- /dev/null +++ b/docs/src/content/docs/guide/system/types.md @@ -0,0 +1,200 @@ +--- +title: "系统类型" +description: "EntitySystem、ProcessingSystem、PassiveSystem、IntervalSystem 等系统基类" +--- + +框架提供了几种不同类型的系统基类，适用于不同的使用场景。 + +## EntitySystem - 基础系统 + +最基础的系统类，所有其他系统都继承自它： + +```typescript +import { EntitySystem, ECSSystem, Matcher } from '@esengine/ecs-framework'; + +@ECSSystem('Movement') +class MovementSystem extends EntitySystem { + constructor() { + // 使用 Matcher 定义需要处理的实体条件 + super(Matcher.all(Position, Velocity)); + } + + protected process(entities: readonly Entity[]): void { + for (const entity of entities) { + const position = entity.getComponent(Position); + const velocity = entity.getComponent(Velocity); + + if (position && velocity) { + position.x += velocity.dx * Time.deltaTime; + position.y += velocity.dy * Time.deltaTime; + } + } + } +} +``` + +## ProcessingSystem - 处理系统 + +适用于不需要逐个处理实体的系统： + +```typescript +@ECSSystem('Physics') +class PhysicsSystem extends ProcessingSystem { + constructor() { + super(); // 不需要指定 Matcher + } + + public processSystem(): void { + // 执行物理世界步进 + this.physicsWorld.step(Time.deltaTime); + } +} +``` + +## PassiveSystem - 被动系统 + +被动系统不进行主动处理，主要用于监听实体的添加和移除事件： + +```typescript +@ECSSystem('EntityTracker') +class EntityTrackerSystem extends PassiveSystem { + constructor() { + super(Matcher.all(Health)); + } + + protected onAdded(entity: Entity): void { + console.log(`生命值实体被添加: ${entity.name}`); + } + + protected onRemoved(entity: Entity): void { + console.log(`生命值实体被移除: ${entity.name}`); + } +} +``` + +## IntervalSystem - 间隔系统 + +按固定时间间隔执行的系统： + +```typescript +@ECSSystem('AutoSave') +class AutoSaveSystem extends IntervalSystem { + constructor() { + // 每 5 秒执行一次 + super(5.0, Matcher.all(SaveData)); + } + + protected process(entities: readonly Entity[]): void { + console.log('执行自动保存...'); + // 保存游戏数据 + this.saveGameData(entities); + } + + private saveGameData(entities: readonly Entity[]): void { + // 保存逻辑 + } +} +``` + +## WorkerEntitySystem - 多线程系统 + +基于 Web Worker 的多线程处理系统，适用于计算密集型任务，能够充分利用多核 CPU 性能。 + +Worker 系统提供了真正的并行计算能力，支持 SharedArrayBuffer 优化，并具有自动降级支持。特别适合物理模拟、粒子系统、AI 计算等场景。 + +**详细内容请参考：[Worker 系统](/guide/worker-system)** + +## 实体匹配器 (Matcher) + +Matcher 用于定义系统需要处理哪些实体。它提供了灵活的条件组合： + +### 基本匹配条件 + +```typescript +// 必须同时拥有 Position 和 Velocity 组件 +const matcher1 = Matcher.all(Position, Velocity); + +// 至少拥有 Health 或 Shield 组件之一 +const matcher2 = Matcher.any(Health, Shield); + +// 不能拥有 Dead 组件 +const matcher3 = Matcher.none(Dead); +``` + +### 复合匹配条件 + +```typescript +// 复杂的组合条件 +const complexMatcher = Matcher.all(Position, Velocity) + .any(Player, Enemy) + .none(Dead, Disabled); + +@ECSSystem('Combat') +class CombatSystem extends EntitySystem { + constructor() { + super(complexMatcher); + } +} +``` + +### 特殊匹配条件 + +```typescript +// 按标签匹配 +const tagMatcher = Matcher.byTag(1); // 匹配标签为 1 的实体 + +// 按名称匹配 +const nameMatcher = Matcher.byName("Player"); // 匹配名称为 "Player" 的实体 + +// 单组件匹配 +const componentMatcher = Matcher.byComponent(Health); // 匹配拥有 Health 组件的实体 + +// 不匹配任何实体 +const nothingMatcher = Matcher.nothing(); // 用于只需要生命周期回调的系统 +``` + +### 空匹配器 vs Nothing 匹配器 + +```typescript +// empty() - 空条件，匹配所有实体 +const emptyMatcher = Matcher.empty(); + +// nothing() - 不匹配任何实体，用于只需要生命周期方法的系统 +const nothingMatcher = Matcher.nothing(); + +// 使用场景：只需要 onBegin/onEnd 生命周期的系统 +@ECSSystem('FrameTimer') +class FrameTimerSystem extends EntitySystem { + constructor() { + super(Matcher.nothing()); // 不处理任何实体 + } + + protected onBegin(): void { + // 每帧开始时执行，例如：记录帧开始时间 + console.log('帧开始'); + } + + protected process(entities: readonly Entity[]): void { + // 永远不会被调用，因为没有匹配的实体 + } + + protected onEnd(): void { + // 每帧结束时执行 + console.log('帧结束'); + } +} +``` + +:::tip +更多关于 Matcher 和实体查询的详细用法，请参考 [实体查询系统](/guide/entity-query) 文档。 +::: + +## 系统类型选择指南 + +| 系统类型 | 适用场景 | +|----------|----------| +| `EntitySystem` | 需要逐个处理匹配实体的通用系统 | +| `ProcessingSystem` | 不需要实体列表，只执行全局逻辑 | +| `PassiveSystem` | 只监听实体添加/移除事件 | +| `IntervalSystem` | 按固定时间间隔执行 | +| `WorkerEntitySystem` | 计算密集型任务，需要多线程 | diff --git a/docs/guide/time-and-timers.md b/docs/src/content/docs/guide/time-and-timers.md similarity index 99% rename from docs/guide/time-and-timers.md rename to docs/src/content/docs/guide/time-and-timers.md index 1047f4cf..3e15b986 100644 --- a/docs/guide/time-and-timers.md +++ b/docs/src/content/docs/guide/time-and-timers.md @@ -1,4 +1,6 @@ -# 时间和定时器系统 +--- +title: "时间和定时器系统" +--- ECS 框架提供了完整的时间管理和定时器系统，包括时间缩放、帧时间计算和灵活的定时器调度功能。 diff --git a/docs/guide/worker-system.md b/docs/src/content/docs/guide/worker-system.md similarity index 99% rename from docs/guide/worker-system.md rename to docs/src/content/docs/guide/worker-system.md index ca790e0e..1cded0a2 100644 --- a/docs/guide/worker-system.md +++ b/docs/src/content/docs/guide/worker-system.md @@ -1,4 +1,6 @@ -# Worker系统 +--- +title: "Worker系统" +--- Worker系统（WorkerEntitySystem）是ECS框架中基于Web Worker的多线程处理系统，专为计算密集型任务设计，能够充分利用多核CPU性能，实现真正的并行计算。 diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx new file mode 100644 index 00000000..34084faa --- /dev/null +++ b/docs/src/content/docs/index.mdx @@ -0,0 +1,67 @@ +--- +title: ESEngine +description: 高性能 TypeScript ECS 框架 - 为游戏开发而生 +template: splash +hero: + tagline: 基于 TypeScript 的高性能 ECS 游戏框架，支持多平台、模块化设计 + image: + file: ../../assets/logo.svg + actions: + - text: 快速开始 + link: /guide/getting-started/ + icon: right-arrow + variant: primary + - text: GitHub + link: https://github.com/esengine/esengine + icon: external +--- + +import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components'; + +## 核心特性 + + + + 基于数据驱动的实体组件系统，支持大规模实体处理，缓存友好的内存布局。 + + + 100% TypeScript 编写，完整的类型定义和编译时检查，提供最佳的开发体验。 + + + 内置 AI 行为树系统，提供可视化编辑器，支持自定义节点和实时调试。 + + + 支持浏览器、Node.js、微信小游戏等多平台，可与主流游戏引擎无缝集成。 + + + 核心功能独立打包，按需引入。支持自定义插件扩展，灵活适配不同项目。 + + + 内置性能监控、调试工具、序列化系统等，提供完整的开发工具链。 + + + +## 快速入口 + + + + + + + diff --git a/docs/modules/behavior-tree/advanced-usage.md b/docs/src/content/docs/modules/behavior-tree/advanced-usage.md similarity index 96% rename from docs/modules/behavior-tree/advanced-usage.md rename to docs/src/content/docs/modules/behavior-tree/advanced-usage.md index f190ca5a..e0ac18df 100644 --- a/docs/modules/behavior-tree/advanced-usage.md +++ b/docs/src/content/docs/modules/behavior-tree/advanced-usage.md @@ -1,4 +1,6 @@ -# 高级用法 +--- +title: "高级用法" +--- 本文介绍行为树系统的高级功能和使用技巧。 @@ -303,11 +305,11 @@ const tree = BehaviorTreeBuilder.create('Timeout') ### Cocos Creator集成 -参见[Cocos Creator集成指南](./cocos-integration.md) +参见[Cocos Creator集成指南](./cocos-integration/) ### LayaAir集成 -参见[LayaAir集成指南](./laya-integration.md) +参见[LayaAir集成指南](./laya-integration/) ## 最佳实践 @@ -387,6 +389,6 @@ const tree = BehaviorTreeBuilder.create('AI') ## 下一步 -- 查看[自定义节点执行器](./custom-actions.md)学习如何创建自定义节点 -- 阅读[最佳实践](./best-practices.md)了解行为树设计技巧 -- 参考[编辑器使用指南](./editor-guide.md)学习可视化编辑 +- 查看[自定义节点执行器](./custom-actions/)学习如何创建自定义节点 +- 阅读[最佳实践](./best-practices/)了解行为树设计技巧 +- 参考[编辑器使用指南](./editor-guide/)学习可视化编辑 diff --git a/docs/modules/behavior-tree/asset-management.md b/docs/src/content/docs/modules/behavior-tree/asset-management.md similarity index 97% rename from docs/modules/behavior-tree/asset-management.md rename to docs/src/content/docs/modules/behavior-tree/asset-management.md index 4a4a6ea0..3280fae8 100644 --- a/docs/modules/behavior-tree/asset-management.md +++ b/docs/src/content/docs/modules/behavior-tree/asset-management.md @@ -1,4 +1,6 @@ -# 资产管理 +--- +title: "资产管理" +--- 本文介绍如何加载、管理和复用行为树资产。 @@ -501,6 +503,6 @@ console.log(json); ## 下一步 -- 学习[Cocos Creator 集成](./cocos-integration.md)了解如何在游戏引擎中加载资源 -- 查看[自定义节点执行器](./custom-actions.md)创建自定义行为 -- 阅读[最佳实践](./best-practices.md)优化你的行为树设计 +- 学习[Cocos Creator 集成](./cocos-integration/)了解如何在游戏引擎中加载资源 +- 查看[自定义节点执行器](./custom-actions/)创建自定义行为 +- 阅读[最佳实践](./best-practices/)优化你的行为树设计 diff --git a/docs/modules/behavior-tree/best-practices.md b/docs/src/content/docs/modules/behavior-tree/best-practices.md similarity index 98% rename from docs/modules/behavior-tree/best-practices.md rename to docs/src/content/docs/modules/behavior-tree/best-practices.md index c116b135..d0b87392 100644 --- a/docs/modules/behavior-tree/best-practices.md +++ b/docs/src/content/docs/modules/behavior-tree/best-practices.md @@ -1,4 +1,6 @@ -# 最佳实践 +--- +title: "最佳实践" +--- 本文介绍行为树设计和使用的最佳实践,帮助你构建高效、可维护的AI系统。 @@ -24,7 +26,7 @@ Root Selector ### 2. 单一职责原则 -每个节点应该只做一件事。要实现复杂动作,创建自定义执行器,参见[自定义节点执行器](./custom-actions.md)。 +每个节点应该只做一件事。要实现复杂动作,创建自定义执行器,参见[自定义节点执行器](./custom-actions/)。 ```typescript // 好的设计 - 使用内置节点 @@ -463,6 +465,6 @@ export class SmartUpdate implements INodeExecutor { ## 下一步 -- 学习[自定义节点执行器](./custom-actions.md)扩展行为树功能 -- 探索[高级用法](./advanced-usage.md)了解更多技巧 -- 参考[核心概念](./core-concepts.md)深入理解原理 +- 学习[自定义节点执行器](./custom-actions/)扩展行为树功能 +- 探索[高级用法](./advanced-usage/)了解更多技巧 +- 参考[核心概念](./core-concepts/)深入理解原理 diff --git a/docs/modules/behavior-tree/cocos-integration.md b/docs/src/content/docs/modules/behavior-tree/cocos-integration.md similarity index 97% rename from docs/modules/behavior-tree/cocos-integration.md rename to docs/src/content/docs/modules/behavior-tree/cocos-integration.md index cc28a199..dda7c42d 100644 --- a/docs/modules/behavior-tree/cocos-integration.md +++ b/docs/src/content/docs/modules/behavior-tree/cocos-integration.md @@ -1,4 +1,6 @@ -# Cocos Creator 集成 +--- +title: "Cocos Creator 集成" +--- 本教程将引导你在 Cocos Creator 项目中集成和使用行为树系统。 @@ -6,7 +8,7 @@ - Cocos Creator 3.x 或更高版本 - 基本的 TypeScript 知识 -- 已完成[快速开始](./getting-started.md)教程 +- 已完成[快速开始](./getting-started/)教程 ## 安装 @@ -677,7 +679,7 @@ const updateInterval = sys.isNative ? 0.016 : 0.05; ## 下一步 -- 查看[资产管理](./asset-management.md)了解如何加载和管理行为树资产、使用子树 -- 学习[高级用法](./advanced-usage.md)了解性能优化和调试技巧 -- 阅读[最佳实践](./best-practices.md)优化你的 AI -- 学习[自定义节点执行器](./custom-actions.md)创建自定义行为 +- 查看[资产管理](./asset-management/)了解如何加载和管理行为树资产、使用子树 +- 学习[高级用法](./advanced-usage/)了解性能优化和调试技巧 +- 阅读[最佳实践](./best-practices/)优化你的 AI +- 学习[自定义节点执行器](./custom-actions/)创建自定义行为 diff --git a/docs/modules/behavior-tree/core-concepts.md b/docs/src/content/docs/modules/behavior-tree/core-concepts.md similarity index 97% rename from docs/modules/behavior-tree/core-concepts.md rename to docs/src/content/docs/modules/behavior-tree/core-concepts.md index a4bb088b..c92a49d0 100644 --- a/docs/modules/behavior-tree/core-concepts.md +++ b/docs/src/content/docs/modules/behavior-tree/core-concepts.md @@ -1,4 +1,6 @@ -# 核心概念 +--- +title: "核心概念" +--- 本文介绍行为树系统的核心概念和工作原理。 @@ -190,7 +192,7 @@ const tree = BehaviorTreeBuilder.create('Actions') .build(); ``` -要实现自定义动作,需要创建自定义执行器,参见[自定义节点执行器](./custom-actions.md)。 +要实现自定义动作,需要创建自定义执行器,参见[自定义节点执行器](./custom-actions/)。 #### Condition(条件) @@ -485,7 +487,7 @@ NodeRuntimeState 现在你已经理解了行为树的核心概念,接下来可以: -- 查看[快速开始](./getting-started.md)创建第一个行为树 -- 学习[自定义节点执行器](./custom-actions.md)创建自定义节点 -- 探索[高级用法](./advanced-usage.md)了解更多功能 -- 阅读[最佳实践](./best-practices.md)学习设计模式 +- 查看[快速开始](./getting-started/)创建第一个行为树 +- 学习[自定义节点执行器](./custom-actions/)创建自定义节点 +- 探索[高级用法](./advanced-usage/)了解更多功能 +- 阅读[最佳实践](./best-practices/)学习设计模式 diff --git a/docs/modules/behavior-tree/custom-actions.md b/docs/src/content/docs/modules/behavior-tree/custom-actions.md similarity index 98% rename from docs/modules/behavior-tree/custom-actions.md rename to docs/src/content/docs/modules/behavior-tree/custom-actions.md index 71cc36f4..3f0bbadf 100644 --- a/docs/modules/behavior-tree/custom-actions.md +++ b/docs/src/content/docs/modules/behavior-tree/custom-actions.md @@ -1,4 +1,6 @@ -# 自定义节点执行器 +--- +title: "自定义节点执行器" +--- 本教程介绍如何为项目创建专用的节点执行器，供策划在编辑器中使用。 @@ -1020,6 +1022,6 @@ execute(context: NodeExecutionContext): TaskStatus { ## 下一步 -- 学习[编辑器工作流](./editor-workflow.md)了解如何在编辑器中使用自定义节点 -- 阅读[最佳实践](./best-practices.md)学习行为树设计模式 -- 查看[高级用法](./advanced-usage.md)了解更多功能 +- 学习[编辑器工作流](./editor-workflow/)了解如何在编辑器中使用自定义节点 +- 阅读[最佳实践](./best-practices/)学习行为树设计模式 +- 查看[高级用法](./advanced-usage/)了解更多功能 diff --git a/docs/modules/behavior-tree/editor-guide.md b/docs/src/content/docs/modules/behavior-tree/editor-guide.md similarity index 93% rename from docs/modules/behavior-tree/editor-guide.md rename to docs/src/content/docs/modules/behavior-tree/editor-guide.md index 422a8e9b..50e5cd03 100644 --- a/docs/modules/behavior-tree/editor-guide.md +++ b/docs/src/content/docs/modules/behavior-tree/editor-guide.md @@ -1,4 +1,6 @@ -# 行为树编辑器使用指南 +--- +title: "行为树编辑器使用指南" +--- 行为树编辑器提供了可视化的方式来创建和编辑行为树。 @@ -115,5 +117,5 @@ BehaviorTreeStarter.start(entity, tree); ## 下一步 -- 查看[编辑器工作流](./editor-workflow.md)了解完整的开发流程 -- 查看[自定义节点执行器](./custom-actions.md)学习如何扩展节点 +- 查看[编辑器工作流](./editor-workflow/)了解完整的开发流程 +- 查看[自定义节点执行器](./custom-actions/)学习如何扩展节点 diff --git a/docs/modules/behavior-tree/editor-workflow.md b/docs/src/content/docs/modules/behavior-tree/editor-workflow.md similarity index 95% rename from docs/modules/behavior-tree/editor-workflow.md rename to docs/src/content/docs/modules/behavior-tree/editor-workflow.md index b5dccc86..214937a5 100644 --- a/docs/modules/behavior-tree/editor-workflow.md +++ b/docs/src/content/docs/modules/behavior-tree/editor-workflow.md @@ -1,4 +1,6 @@ -# 编辑器工作流 +--- +title: "编辑器工作流" +--- 本教程介绍如何使用行为树编辑器创建AI，并在游戏中加载使用。 @@ -110,7 +112,7 @@ setInterval(() => { ## 实现自定义执行器 -要扩展行为树的功能，需要创建自定义执行器（详见[自定义节点执行器](./custom-actions.md)）： +要扩展行为树的功能，需要创建自定义执行器（详见[自定义节点执行器](./custom-actions/)）： ```typescript import { @@ -248,6 +250,6 @@ setInterval(() => { ## 下一步 -- 查看[自定义节点执行器](./custom-actions.md)学习如何创建自定义节点 -- 查看[高级用法](./advanced-usage.md)了解性能优化等高级特性 -- 查看[最佳实践](./best-practices.md)优化你的AI设计 +- 查看[自定义节点执行器](./custom-actions/)学习如何创建自定义节点 +- 查看[高级用法](./advanced-usage/)了解性能优化等高级特性 +- 查看[最佳实践](./best-practices/)优化你的AI设计 diff --git a/docs/modules/behavior-tree/getting-started.md b/docs/src/content/docs/modules/behavior-tree/getting-started.md similarity index 95% rename from docs/modules/behavior-tree/getting-started.md rename to docs/src/content/docs/modules/behavior-tree/getting-started.md index 21a516d3..a903a63b 100644 --- a/docs/modules/behavior-tree/getting-started.md +++ b/docs/src/content/docs/modules/behavior-tree/getting-started.md @@ -1,4 +1,6 @@ -# 快速开始 +--- +title: "快速开始" +--- 本教程将引导你在5分钟内创建第一个行为树。 @@ -331,11 +333,11 @@ BehaviorTreeStarter.restart(entity); 现在你已经创建了第一个行为树,接下来可以: -1. 学习[核心概念](./core-concepts.md)深入理解行为树原理 -2. 学习[资产管理](./asset-management.md)了解如何加载和复用行为树、使用子树 -3. 查看[自定义节点执行器](./custom-actions.md)学习如何创建自定义节点 -4. 根据你的场景查看集成教程：[Cocos Creator](./cocos-integration.md) 或 [Node.js](./nodejs-usage.md) -5. 查看[高级用法](./advanced-usage.md)了解更多功能 +1. 学习[核心概念](./core-concepts/)深入理解行为树原理 +2. 学习[资产管理](./asset-management/)了解如何加载和复用行为树、使用子树 +3. 查看[自定义节点执行器](./custom-actions/)学习如何创建自定义节点 +4. 根据你的场景查看集成教程：[Cocos Creator](./cocos-integration/) 或 [Node.js](./nodejs-usage.md) +5. 查看[高级用法](./advanced-usage/)了解更多功能 ## 常见问题 @@ -382,4 +384,4 @@ console.log('活动节点:', Array.from(runtime?.activeNodeIds || [])); 内置的`executeAction`和`executeCondition`节点只是占位符。要实现真正的自定义逻辑,你需要创建自定义执行器: -参见[自定义节点执行器](./custom-actions.md)学习如何创建。 +参见[自定义节点执行器](./custom-actions/)学习如何创建。 diff --git a/docs/modules/behavior-tree/index.md b/docs/src/content/docs/modules/behavior-tree/index.md similarity index 73% rename from docs/modules/behavior-tree/index.md rename to docs/src/content/docs/modules/behavior-tree/index.md index 7bedd632..16a1777d 100644 --- a/docs/modules/behavior-tree/index.md +++ b/docs/src/content/docs/modules/behavior-tree/index.md @@ -1,4 +1,6 @@ -# 行为树系统 +--- +title: "行为树系统" +--- 行为树(Behavior Tree)是一种用于游戏AI和自动化控制的强大工具。本框架提供了基于Runtime执行器架构的行为树系统,具有高性能、类型安全、易于扩展的特点。 @@ -41,29 +43,29 @@ ### 入门教程 -- **[快速开始](./getting-started.md)** - 5分钟上手行为树 -- **[核心概念](./core-concepts.md)** - 理解行为树的基本原理 +- **[快速开始](./getting-started/)** - 5分钟上手行为树 +- **[核心概念](./core-concepts/)** - 理解行为树的基本原理 ### 编辑器使用 -- **[编辑器使用指南](./editor-guide.md)** - 可视化创建行为树 -- **[编辑器工作流](./editor-workflow.md)** - 完整的开发流程 +- **[编辑器使用指南](./editor-guide/)** - 可视化创建行为树 +- **[编辑器工作流](./editor-workflow/)** - 完整的开发流程 ### 资源管理 -- **[资产管理](./asset-management.md)** - 加载、管理和复用行为树资产、使用子树 +- **[资产管理](./asset-management/)** - 加载、管理和复用行为树资产、使用子树 ### 引擎集成 -- **[Cocos Creator 集成](./cocos-integration.md)** - 在 Cocos Creator 中使用行为树 -- **[Laya 引擎集成](./laya-integration.md)** - 在 Laya 中使用行为树 -- **[Node.js 服务端使用](./nodejs-usage.md)** - 在服务器、聊天机器人等场景中使用行为树 +- **[Cocos Creator 集成](./cocos-integration/)** - 在 Cocos Creator 中使用行为树 +- **[Laya 引擎集成](./laya-integration/)** - 在 Laya 中使用行为树 +- **[Node.js 服务端使用](./nodejs-usage/)** - 在服务器、聊天机器人等场景中使用行为树 ### 高级主题 -- **[高级用法](./advanced-usage.md)** - 性能优化、调试技巧 -- **[自定义节点执行器](./custom-actions.md)** - 创建自定义行为节点 -- **[最佳实践](./best-practices.md)** - 行为树设计模式和技巧 +- **[高级用法](./advanced-usage/)** - 性能优化、调试技巧 +- **[自定义节点执行器](./custom-actions/)** - 创建自定义行为节点 +- **[最佳实践](./best-practices/)** - 行为树设计模式和技巧 ## 快速示例 @@ -175,20 +177,20 @@ export class AttackAction implements INodeExecutor { } ``` -详细说明请参见[自定义节点执行器](./custom-actions.md)。 +详细说明请参见[自定义节点执行器](./custom-actions/)。 ## 下一步 建议按照以下顺序学习: -1. 阅读[快速开始](./getting-started.md)了解基础用法 -2. 学习[核心概念](./core-concepts.md)理解行为树原理 -3. 学习[资产管理](./asset-management.md)了解如何加载和复用行为树、使用子树 +1. 阅读[快速开始](./getting-started/)了解基础用法 +2. 学习[核心概念](./core-concepts/)理解行为树原理 +3. 学习[资产管理](./asset-management/)了解如何加载和复用行为树、使用子树 4. 根据你的场景查看集成教程: - - 客户端游戏：[Cocos Creator](./cocos-integration.md) 或 [Laya](./laya-integration.md) - - 服务端应用：[Node.js 服务端使用](./nodejs-usage.md) -5. 尝试[编辑器使用指南](./editor-guide.md)可视化创建行为树 -6. 探索[高级用法](./advanced-usage.md)和[自定义节点执行器](./custom-actions.md)提升技能 + - 客户端游戏：[Cocos Creator](./cocos-integration/) 或 [Laya](./laya-integration.md) + - 服务端应用：[Node.js 服务端使用](./nodejs-usage/) +5. 尝试[编辑器使用指南](./editor-guide/)可视化创建行为树 +6. 探索[高级用法](./advanced-usage/)和[自定义节点执行器](./custom-actions.md)提升技能 ## 获取帮助 diff --git a/docs/modules/behavior-tree/laya-integration.md b/docs/src/content/docs/modules/behavior-tree/laya-integration.md similarity index 97% rename from docs/modules/behavior-tree/laya-integration.md rename to docs/src/content/docs/modules/behavior-tree/laya-integration.md index 0d7e59ab..ce21c71d 100644 --- a/docs/modules/behavior-tree/laya-integration.md +++ b/docs/src/content/docs/modules/behavior-tree/laya-integration.md @@ -1,4 +1,6 @@ -# Laya 引擎集成 +--- +title: "Laya 引擎集成" +--- 本教程将引导你在 Laya 引擎项目中集成和使用行为树系统。 @@ -6,7 +8,7 @@ - LayaAir 3.x 或更高版本 - 基本的 TypeScript 知识 -- 已完成[快速开始](./getting-started.md)教程 +- 已完成[快速开始](./getting-started/)教程 ## 安装 @@ -309,5 +311,5 @@ class AIManager { ## 下一步 -- 查看[高级用法](./advanced-usage.md) -- 学习[最佳实践](./best-practices.md) +- 查看[高级用法](./advanced-usage/) +- 学习[最佳实践](./best-practices/) diff --git a/docs/modules/behavior-tree/nodejs-usage.md b/docs/src/content/docs/modules/behavior-tree/nodejs-usage.md similarity index 98% rename from docs/modules/behavior-tree/nodejs-usage.md rename to docs/src/content/docs/modules/behavior-tree/nodejs-usage.md index d83b21e7..bf91b05d 100644 --- a/docs/modules/behavior-tree/nodejs-usage.md +++ b/docs/src/content/docs/modules/behavior-tree/nodejs-usage.md @@ -1,4 +1,6 @@ -# Node.js 服务端使用 +--- +title: "Node.js 服务端使用" +--- 本文介绍如何在 Node.js 服务端环境（如游戏服务器、机器人、自动化工具）中使用行为树系统。 @@ -575,6 +577,6 @@ function loadAIState(entity: Entity, savedState: any) { ## 下一步 -- 查看[资产管理](./asset-management.md)了解资源加载和子树 -- 学习[自定义节点执行器](./custom-actions.md)创建自定义行为 -- 阅读[最佳实践](./best-practices.md)优化你的服务端AI +- 查看[资产管理](./asset-management/)了解资源加载和子树 +- 学习[自定义节点执行器](./custom-actions/)创建自定义行为 +- 阅读[最佳实践](./best-practices/)优化你的服务端AI diff --git a/docs/modules/blueprint/index.md b/docs/src/content/docs/modules/blueprint/index.md similarity index 99% rename from docs/modules/blueprint/index.md rename to docs/src/content/docs/modules/blueprint/index.md index 6c98c11a..459c68a0 100644 --- a/docs/modules/blueprint/index.md +++ b/docs/src/content/docs/modules/blueprint/index.md @@ -1,4 +1,6 @@ -# 蓝图可视化脚本 (Blueprint) +--- +title: "蓝图可视化脚本 (Blueprint)" +--- `@esengine/blueprint` 提供了一个功能完整的可视化脚本系统，支持节点式编程、事件驱动和蓝图组合。 diff --git a/docs/modules/fsm/index.md b/docs/src/content/docs/modules/fsm/index.md similarity index 99% rename from docs/modules/fsm/index.md rename to docs/src/content/docs/modules/fsm/index.md index 29ddd7f5..1438023a 100644 --- a/docs/modules/fsm/index.md +++ b/docs/src/content/docs/modules/fsm/index.md @@ -1,4 +1,6 @@ -# 状态机 (FSM) +--- +title: "状态机 (FSM)" +--- `@esengine/fsm` 提供了一个类型安全的有限状态机实现，用于角色、AI 或任何需要状态管理的场景。 diff --git a/docs/modules/index.md b/docs/src/content/docs/modules/index.md similarity index 95% rename from docs/modules/index.md rename to docs/src/content/docs/modules/index.md index 59ca09fe..6ef2c8df 100644 --- a/docs/modules/index.md +++ b/docs/src/content/docs/modules/index.md @@ -1,4 +1,7 @@ -# 功能模块 +--- +title: 功能模块 +description: ESEngine 可选功能模块总览 +--- ESEngine 提供了丰富的功能模块，可以按需引入到你的项目中。 diff --git a/docs/modules/network/index.md b/docs/src/content/docs/modules/network/index.md similarity index 98% rename from docs/modules/network/index.md rename to docs/src/content/docs/modules/network/index.md index b9988a6b..f36b4c90 100644 --- a/docs/modules/network/index.md +++ b/docs/src/content/docs/modules/network/index.md @@ -1,4 +1,6 @@ -# 网络同步系统 (Network) +--- +title: "网络同步系统 (Network)" +--- `@esengine/network` 提供基于 TSRPC 的客户端-服务器网络同步解决方案，用于多人游戏的实体同步、输入处理和状态插值。 @@ -103,7 +105,7 @@ networkPlugin.registerPrefab('player', (scene, spawn) => { const identity = entity.addComponent(new NetworkIdentity()); identity.netId = spawn.netId; identity.ownerId = spawn.ownerId; - identity.isLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId; + identity.bIsLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId; entity.addComponent(new NetworkTransform()); return entity; @@ -630,12 +632,12 @@ async function initGame() { const identity = entity.addComponent(new NetworkIdentity()); identity.netId = spawn.netId; identity.ownerId = spawn.ownerId; - identity.isLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId; + identity.bIsLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId; entity.addComponent(new NetworkTransform()); // 如果是本地玩家，添加输入标记 - if (identity.isLocalPlayer) { + if (identity.bIsLocalPlayer) { entity.addComponent(new LocalInputComponent()); } @@ -680,7 +682,7 @@ class LocalInputHandler extends EntitySystem { if (!this._networkPlugin) return; const identity = entity.getComponent(NetworkIdentity)!; - if (!identity.isLocalPlayer) return; + if (!identity.bIsLocalPlayer) return; // 读取键盘输入 let moveX = 0; diff --git a/docs/modules/pathfinding/index.md b/docs/src/content/docs/modules/pathfinding/index.md similarity index 99% rename from docs/modules/pathfinding/index.md rename to docs/src/content/docs/modules/pathfinding/index.md index 088f4d8b..c5f74fc8 100644 --- a/docs/modules/pathfinding/index.md +++ b/docs/src/content/docs/modules/pathfinding/index.md @@ -1,4 +1,6 @@ -# 寻路系统 (Pathfinding) +--- +title: "寻路系统 (Pathfinding)" +--- `@esengine/pathfinding` 提供了完整的 2D 寻路解决方案，包括 A* 算法、网格地图、导航网格和路径平滑。 diff --git a/docs/modules/procgen/index.md b/docs/src/content/docs/modules/procgen/index.md similarity index 99% rename from docs/modules/procgen/index.md rename to docs/src/content/docs/modules/procgen/index.md index a77a737f..60c85c49 100644 --- a/docs/modules/procgen/index.md +++ b/docs/src/content/docs/modules/procgen/index.md @@ -1,4 +1,6 @@ -# 程序化生成 (Procgen) +--- +title: "程序化生成 (Procgen)" +--- `@esengine/procgen` 提供了程序化内容生成的核心工具，包括噪声函数、种子随机数和各种随机工具。 diff --git a/docs/modules/spatial/index.md b/docs/src/content/docs/modules/spatial/index.md similarity index 99% rename from docs/modules/spatial/index.md rename to docs/src/content/docs/modules/spatial/index.md index e21b7a46..7b4c2518 100644 --- a/docs/modules/spatial/index.md +++ b/docs/src/content/docs/modules/spatial/index.md @@ -1,4 +1,6 @@ -# 空间索引系统 (Spatial) +--- +title: "空间索引系统 (Spatial)" +--- `@esengine/spatial` 提供了高效的空间查询和索引功能，包括范围查询、最近邻查询、射线检测和 AOI（兴趣区域）管理。 diff --git a/docs/modules/timer/index.md b/docs/src/content/docs/modules/timer/index.md similarity index 99% rename from docs/modules/timer/index.md rename to docs/src/content/docs/modules/timer/index.md index 50375bc7..ce6820a6 100644 --- a/docs/modules/timer/index.md +++ b/docs/src/content/docs/modules/timer/index.md @@ -1,4 +1,6 @@ -# 定时器系统 (Timer) +--- +title: "定时器系统 (Timer)" +--- `@esengine/timer` 提供了一个灵活的定时器和冷却系统，用于游戏中的延迟执行、重复任务、技能冷却等场景。 diff --git a/docs/src/styles/custom.css b/docs/src/styles/custom.css new file mode 100644 index 00000000..0c994a63 --- /dev/null +++ b/docs/src/styles/custom.css @@ -0,0 +1,238 @@ +/* ESEngine Documentation Theme */ + +:root { + /* Brand colors */ + --sl-color-accent-low: #1a1a2e; + --sl-color-accent: #646cff; + --sl-color-accent-high: #a5b4fc; + + /* Background */ + --sl-color-bg: #0a0a0f; + --sl-color-bg-nav: rgba(10, 10, 15, 0.95); + --sl-color-bg-sidebar: #0f0f14; + + /* Text */ + --sl-color-white: #ffffff; + --sl-color-gray-1: #f8fafc; + --sl-color-gray-2: #e2e8f0; + --sl-color-gray-3: #94a3b8; + --sl-color-gray-4: #64748b; + --sl-color-gray-5: #475569; + --sl-color-gray-6: #1e293b; + + /* Typography */ + --sl-font-system: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + --sl-font-system-mono: 'JetBrains Mono', 'Fira Code', Consolas, monospace; + + /* Layout */ + --sl-content-width: 75rem; + --sl-sidebar-width: 18rem; +} + +/* Navigation bar */ +header.header { + backdrop-filter: blur(12px); + border-bottom: 1px solid rgba(100, 108, 255, 0.1); +} + +/* Sidebar styling */ +.sidebar-content { + background: var(--sl-color-bg-sidebar); +} + +nav.sidebar-content ul li a { + padding: 0.5rem 1rem; + border-radius: 6px; + transition: all 0.2s ease; +} + +nav.sidebar-content ul li a:hover { + background: rgba(100, 108, 255, 0.1); +} + +nav.sidebar-content ul li a[aria-current="page"] { + background: rgba(100, 108, 255, 0.15); + border-left: 3px solid var(--sl-color-accent); + color: var(--sl-color-accent-high); +} + +/* Group labels */ +.sidebar-content .top-level > li > details > summary, +.sidebar-content .top-level > li > a { + font-weight: 600; + text-transform: uppercase; + font-size: 0.75rem; + letter-spacing: 0.05em; + color: var(--sl-color-gray-3); +} + +/* Content area */ +.sl-markdown-content { + font-size: 1rem; + line-height: 1.75; +} + +/* Headings */ +.sl-markdown-content h1 { + font-size: 2rem; + font-weight: 700; + margin-top: 0; + padding-bottom: 0.75rem; + border-bottom: 1px solid var(--sl-color-gray-6); +} + +.sl-markdown-content h2 { + font-size: 1.5rem; + font-weight: 600; + margin-top: 2.5rem; + padding-left: 1rem; + border-left: 3px solid var(--sl-color-accent); + background: linear-gradient(90deg, rgba(100, 108, 255, 0.1) 0%, transparent 100%); +} + +.sl-markdown-content h3 { + font-size: 1.25rem; + font-weight: 600; + margin-top: 2rem; + padding-left: 0.75rem; + border-left: 2px solid var(--sl-color-gray-5); +} + +/* Code blocks */ +.sl-markdown-content pre { + background: #0d0d12 !important; + border: 1px solid var(--sl-color-gray-6); + border-radius: 8px; + padding: 1rem; +} + +.sl-markdown-content code { + font-family: var(--sl-font-system-mono); + font-size: 0.9em; +} + +.sl-markdown-content :not(pre) > code { + background: rgba(100, 108, 255, 0.1); + padding: 0.2em 0.4em; + border-radius: 4px; + color: var(--sl-color-accent-high); +} + +/* Tables */ +.sl-markdown-content table { + width: 100%; + border-collapse: separate; + border-spacing: 0; + border-radius: 8px; + overflow: hidden; + border: 1px solid var(--sl-color-gray-6); +} + +.sl-markdown-content th { + background: var(--sl-color-gray-6); + font-weight: 600; + text-transform: uppercase; + font-size: 0.75rem; + letter-spacing: 0.05em; + padding: 0.75rem 1rem; + text-align: left; +} + +.sl-markdown-content td { + padding: 0.75rem 1rem; + border-top: 1px solid var(--sl-color-gray-6); +} + +.sl-markdown-content tr:nth-child(even) td { + background: rgba(30, 41, 59, 0.3); +} + +/* Callouts / Asides */ +.starlight-aside { + border-radius: 8px; + border-left-width: 4px; + padding: 1rem 1.25rem; +} + +.starlight-aside--note { + background: linear-gradient(90deg, rgba(59, 130, 246, 0.1) 0%, transparent 100%); + border-color: #3b82f6; +} + +.starlight-aside--tip { + background: linear-gradient(90deg, rgba(34, 197, 94, 0.1) 0%, transparent 100%); + border-color: #22c55e; +} + +.starlight-aside--caution { + background: linear-gradient(90deg, rgba(245, 158, 11, 0.1) 0%, transparent 100%); + border-color: #f59e0b; +} + +.starlight-aside--danger { + background: linear-gradient(90deg, rgba(239, 68, 68, 0.1) 0%, transparent 100%); + border-color: #ef4444; +} + +/* Links */ +.sl-markdown-content a { + color: var(--sl-color-accent); + text-decoration: none; + border-bottom: 1px solid transparent; + transition: border-color 0.2s ease; +} + +.sl-markdown-content a:hover { + border-bottom-color: var(--sl-color-accent); +} + +/* Search */ +.search-input { + background: var(--sl-color-gray-6); + border: 1px solid transparent; + border-radius: 8px; + transition: border-color 0.2s ease; +} + +.search-input:focus { + border-color: var(--sl-color-accent); + outline: none; +} + +/* Badge */ +.sl-badge { + font-size: 0.75rem; + font-weight: 600; + padding: 0.25em 0.5em; + border-radius: 4px; +} + +/* Hero section */ +.hero { + text-align: center; + padding: 4rem 0; +} + +.hero h1 { + font-size: 3rem; + font-weight: 800; + background: linear-gradient(135deg, #fff 0%, var(--sl-color-accent-high) 100%); + -webkit-background-clip: text; + -webkit-text-fill-color: transparent; + background-clip: text; +} + +/* Responsive */ +@media (max-width: 768px) { + .sl-markdown-content h1 { + font-size: 1.75rem; + } + + .sl-markdown-content h2 { + font-size: 1.25rem; + } + + .hero h1 { + font-size: 2rem; + } +} diff --git a/docs/src/styles/global.css b/docs/src/styles/global.css new file mode 100644 index 00000000..a461c505 --- /dev/null +++ b/docs/src/styles/global.css @@ -0,0 +1 @@ +@import "tailwindcss"; \ No newline at end of file diff --git a/docs/tsconfig.json b/docs/tsconfig.json new file mode 100644 index 00000000..0649e427 --- /dev/null +++ b/docs/tsconfig.json @@ -0,0 +1,13 @@ +{ + "extends": "astro/tsconfigs/strict", + "include": [ + ".astro/types.d.ts", + "**/*" + ], + "exclude": [ + "dist" + ], + "compilerOptions": { + "jsx": "preserve" + } +} \ No newline at end of file