chore: release packages (#393)

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

.all-contributorsrc

@@ -0,0 +1,62 @@
+{
+    "projectName": "ecs-framework",
+    "projectOwner": "esengine",
+    "repoType": "github",
+    "repoHost": "https://github.com",
+    "files": ["README.md"],
+    "imageSize": 100,
+    "commit": true,
+    "commitConvention": "angular",
+    "contributors": [
+        {
+            "login": "yhh",
+            "name": "Frank Huang",
+            "avatar_url": "https://avatars.githubusercontent.com/u/145575?v=4",
+            "profile": "https://github.com/yhh",
+            "contributions": ["code"]
+        }
+    ],
+    "contributorsPerLine": 7,
+    "contributorsSortAlphabetically": false,
+    "badgeTemplate": "[![All Contributors](https://img.shields.io/badge/all_contributors-<%= contributors.length %>-orange.svg?style=flat-square)](#contributors)",
+    "contributorTemplate": "<a href=\"<%= contributor.profile %>\"><img src=\"<%= contributor.avatar_url %>\" width=\"<%= options.imageSize %>px;\" alt=\"<%= contributor.name %>\"/><br /><sub><b><%= contributor.name %></b></sub></a>",
+    "types": {
+        "code": {
+            "symbol": "💻",
+            "description": "Code",
+            "link": "[<%= symbol %>](<%= url %> \"Code\")"
+        },
+        "doc": {
+            "symbol": "📖",
+            "description": "Documentation",
+            "link": "[<%= symbol %>](<%= url %> \"Documentation\")"
+        },
+        "test": {
+            "symbol": "⚠️",
+            "description": "Tests",
+            "link": "[<%= symbol %>](<%= url %> \"Tests\")"
+        },
+        "bug": {
+            "symbol": "🐛",
+            "description": "Bug reports",
+            "link": "[<%= symbol %>](<%= url %> \"Bug reports\")"
+        },
+        "example": {
+            "symbol": "💡",
+            "description": "Examples",
+            "link": "[<%= symbol %>](<%= url %> \"Examples\")"
+        },
+        "design": {
+            "symbol": "🎨",
+            "description": "Design",
+            "link": "[<%= symbol %>](<%= url %> \"Design\")"
+        },
+        "ideas": {
+            "symbol": "🤔",
+            "description": "Ideas & Planning",
+            "link": "[<%= symbol %>](<%= url %> \"Ideas & Planning\")"
+        }
+    },
+    "skipCi": true
+}
+

.changeset/README.md

@@ -0,0 +1,8 @@
+# Changesets
+
+Hello and welcome! This folder has been automatically generated by `@changesets/cli`, a build tool that works
+with multi-package repos, or single-package repos to help you version and publish your code. You can
+find the full documentation for it [in our repository](https://github.com/changesets/changesets)
+
+We have a quick list of common questions to get you started engaging with this project in
+[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

.changeset/config.json

@@ -0,0 +1,57 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    { "repo": "esengine/esengine" }
+  ],
+  "commit": false,
+  "fixed": [],
+  "linked": [
+    ["@esengine/ecs-framework", "@esengine/ecs-framework-math"]
+  ],
+  "access": "public",
+  "baseBranch": "master",
+  "updateInternalDependencies": "patch",
+  "ignore": [
+    "@esengine/engine-core",
+    "@esengine/runtime-core",
+    "@esengine/asset-system",
+    "@esengine/material-system",
+    "@esengine/ecs-engine-bindgen",
+    "@esengine/script-runtime",
+    "@esengine/platform-common",
+    "@esengine/platform-web",
+    "@esengine/platform-wechat",
+    "@esengine/sprite",
+    "@esengine/camera",
+    "@esengine/particle",
+    "@esengine/tilemap",
+    "@esengine/mesh-3d",
+    "@esengine/effect",
+    "@esengine/audio",
+    "@esengine/fairygui",
+    "@esengine/physics-rapier2d",
+    "@esengine/rapier2d",
+    "@esengine/world-streaming",
+    "@esengine/editor-core",
+    "@esengine/editor-runtime",
+    "@esengine/editor-app",
+    "@esengine/sprite-editor",
+    "@esengine/camera-editor",
+    "@esengine/particle-editor",
+    "@esengine/tilemap-editor",
+    "@esengine/mesh-3d-editor",
+    "@esengine/fairygui-editor",
+    "@esengine/physics-rapier2d-editor",
+    "@esengine/behavior-tree-editor",
+    "@esengine/blueprint-editor",
+    "@esengine/asset-system-editor",
+    "@esengine/material-editor",
+    "@esengine/shader-editor",
+    "@esengine/world-streaming-editor",
+    "@esengine/node-editor",
+    "@esengine/sdk",
+    "@esengine/worker-generator",
+    "@esengine/engine"
+  ]
+}

.coderabbit.yaml

@@ -0,0 +1,36 @@
+# CodeRabbit 配置文件
+# https://docs.coderabbit.ai/configuration
+
+language: "zh-CN" # 使用中文评论
+reviews:
+  # 审查级别
+  profile: "chill" # "chill" 或 "strict" 或 "assertive"
+
+  # 自动审查设置
+  auto_review:
+    enabled: true
+    drafts: false # 草稿 PR 不自动审查
+    base_branches:
+      - master
+      - main
+
+  # 审查内容
+  request_changes_workflow: false # 不阻止 PR 合并
+  high_level_summary: true # 生成高层次摘要
+  poem: false # 不生成诗歌（可以改为 true 增加趣味）
+  review_status: true # 显示审查状态
+
+  # 忽略的文件
+  path_filters:
+    - "!**/*.md" # 不审查 markdown
+    - "!**/package-lock.json" # 不审查 lock 文件
+    - "!**/dist/**" # 不审查构建输出
+    - "!**/*.min.js" # 不审查压缩文件
+
+# 聊天设置
+chat:
+  auto_reply: true # 自动回复问题
+
+# 提交建议
+suggestions:
+  enabled: true # 启用代码建议

.commitlintrc.json

@@ -0,0 +1,29 @@
+{
+  "extends": ["@commitlint/config-conventional"],
+  "rules": {
+    "type-enum": [
+      2,
+      "always",
+      [
+        "feat",
+        "fix",
+        "docs",
+        "style",
+        "refactor",
+        "perf",
+        "test",
+        "build",
+        "ci",
+        "chore",
+        "revert"
+      ]
+    ],
+    "scope-enum": [
+      0
+    ],
+    "scope-empty": [0],
+    "subject-empty": [2, "never"],
+    "subject-case": [0],
+    "header-max-length": [2, "always", 100]
+  }
+}

.eslintrc.json

@@ -1,45 +0,0 @@
-{
-  "root": true,
-  "parser": "@typescript-eslint/parser",
-  "parserOptions": {
-    "ecmaVersion": 2020,
-    "sourceType": "module",
-    "project": "./tsconfig.json"
-  },
-  "plugins": [
-    "@typescript-eslint"
-  ],
-  "extends": [
-    "eslint:recommended",
-    "plugin:@typescript-eslint/recommended"
-  ],
-  "rules": {
-    "semi": ["error", "always"],
-    "quotes": ["error", "single", { "avoidEscape": true }],
-    "indent": ["error", 4, { "SwitchCase": 1 }],
-    "no-trailing-spaces": "error",
-    "eol-last": ["error", "always"],
-    "comma-dangle": ["error", "none"],
-    "object-curly-spacing": ["error", "always"],
-    "array-bracket-spacing": ["error", "never"],
-    "arrow-parens": ["error", "always"],
-    "no-multiple-empty-lines": ["error", { "max": 2, "maxEOF": 1 }],
-    "no-console": "off",
-    "@typescript-eslint/no-explicit-any": "off",
-    "@typescript-eslint/explicit-module-boundary-types": "off",
-    "@typescript-eslint/no-unused-vars": ["warn", { "argsIgnorePattern": "^_" }],
-    "@typescript-eslint/no-non-null-assertion": "off"
-  },
-  "ignorePatterns": [
-    "node_modules/",
-    "dist/",
-    "bin/",
-    "build/",
-    "coverage/",
-    "thirdparty/",
-    "examples/lawn-mower-demo/",
-    "extensions/",
-    "*.min.js",
-    "*.d.ts"
-  ]
-}

.github/FUNDING.yml

@@ -9,4 +9,4 @@ community_bridge: # Replace with a single Community Bridge project-name e.g., cl
 liberapay: # Replace with a single Liberapay username
 issuehunt: # Replace with a single IssueHunt username
 otechie: # Replace with a single Otechie username
-custom: ['https://github.com/esengine/ecs-framework/blob/master/sponsor/alipay.jpg', 'https://github.com/esengine/ecs-framework/blob/master/sponsor/wechatpay.png'] # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']
+custom: ['https://github.com/esengine/esengine/blob/master/sponsor/alipay.jpg', 'https://github.com/esengine/esengine/blob/master/sponsor/wechatpay.png'] # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,130 @@
+name: 🐛 Bug Report / 错误报告
+description: Report a bug or issue / 报告一个错误或问题
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢你提交 Bug 报告！请填写以下信息帮助我们更快定位问题。
+        Thanks for reporting a bug! Please fill in the information below to help us locate the issue faster.
+
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题描述 / Bug Description
+      description: 清晰简洁地描述遇到的问题 / A clear and concise description of the bug
+      placeholder: 例如：当我创建超过1000个实体时，游戏卡顿严重...
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: 复现步骤 / Steps to Reproduce
+      description: 如何复现这个问题？/ How can we reproduce this issue?
+      placeholder: |
+        1. 创建场景
+        2. 添加 1000 个实体
+        3. 运行游戏
+        4. 观察卡顿
+      value: |
+        1.
+        2.
+        3.
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: 期望行为 / Expected Behavior
+      description: 你期望发生什么？/ What did you expect to happen?
+      placeholder: 游戏应该流畅运行，FPS 保持在 60...
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: 实际行为 / Actual Behavior
+      description: 实际发生了什么？/ What actually happened?
+      placeholder: FPS 降到 20，游戏严重卡顿...
+    validations:
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: 版本 / Version
+      description: 使用的 @esengine/ecs-framework 版本 / Version of @esengine/ecs-framework
+      placeholder: 例如 / e.g., 2.2.8
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: 平台 / Platform
+      description: 在哪个平台遇到问题？/ Which platform did you encounter the issue?
+      multiple: true
+      options:
+        - Web / 浏览器
+        - Cocos Creator
+        - Laya Engine
+        - WeChat Mini Game / 微信小游戏
+        - Other / 其他
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: 环境信息 / Environment
+      description: |
+        相关环境信息 / Relevant environment information
+        例如：操作系统、浏览器版本、Node.js 版本等
+      placeholder: |
+        - OS: Windows 11
+        - Browser: Chrome 120
+        - Node.js: 20.10.0
+      value: |
+        - OS:
+        - Browser:
+        - Node.js:
+    validations:
+      required: false
+
+  - type: textarea
+    id: code
+    attributes:
+      label: 代码示例 / Code Sample
+      description: 如果可能，提供最小可复现代码 / If possible, provide minimal reproducible code
+      render: typescript
+      placeholder: |
+        import { Core, Scene, Entity } from '@esengine/ecs-framework';
+
+        // 你的代码 / Your code here
+    validations:
+      required: false
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: 错误日志 / Error Logs
+      description: 相关的错误日志或截图 / Relevant error logs or screenshots
+      render: shell
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: 检查清单 / Checklist
+      options:
+        - label: 我已经搜索过类似的 issue / I have searched for similar issues
+          required: true
+        - label: 我使用的是最新版本 / I am using the latest version
+          required: false
+        - label: 我愿意提交 PR 修复此问题 / I am willing to submit a PR to fix this issue
+          required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,17 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 📚 文档 / Documentation
+    url: https://esengine.github.io/ecs-framework/
+    about: 查看完整文档和教程 / View full documentation and tutorials
+
+  - name: 🤖 AI 文档助手 / AI Documentation Assistant
+    url: https://deepwiki.com/esengine/esengine
+    about: 使用 AI 助手快速找到答案 / Use AI assistant to quickly find answers
+
+  - name: 💬 QQ 交流群 / QQ Group
+    url: https://jq.qq.com/?_wv=1027&k=29w1Nud6
+    about: 加入社区交流群 / Join the community group
+
+  - name: 🌟 GitHub Discussions
+    url: https://github.com/esengine/esengine/discussions
+    about: 参与社区讨论 / Join community discussions

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,90 @@
+name: ✨ Feature Request / 功能建议
+description: Suggest a new feature or enhancement / 建议新功能或改进
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢你的功能建议！请详细描述你的想法。
+        Thanks for your feature suggestion! Please describe your idea in detail.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: 问题描述 / Problem Description
+      description: 这个功能解决什么问题？/ What problem does this feature solve?
+      placeholder: 当我需要...的时候，现在很不方便，因为... / When I need to..., it's inconvenient because...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: 建议的解决方案 / Proposed Solution
+      description: 你希望如何实现这个功能？/ How would you like this feature to work?
+      placeholder: 可以添加一个新的 API，例如... / Could add a new API, for example...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 其他方案 / Alternatives
+      description: 你考虑过哪些替代方案？/ What alternatives have you considered?
+      placeholder: 也可以通过...来实现，但是... / Could also achieve this by..., but...
+    validations:
+      required: false
+
+  - type: textarea
+    id: examples
+    attributes:
+      label: 使用示例 / Usage Example
+      description: 展示这个功能如何使用 / Show how this feature would be used
+      render: typescript
+      placeholder: |
+        // 理想的 API 设计 / Ideal API design
+        const pool = new ComponentPool(MyComponent, { size: 100 });
+        const component = pool.acquire();
+    validations:
+      required: false
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: 影响范围 / Scope
+      description: 这个功能主要影响哪个部分？/ Which part does this feature mainly affect?
+      options:
+        - Core / 核心框架
+        - Performance / 性能
+        - API Design / API 设计
+        - Developer Experience / 开发体验
+        - Documentation / 文档
+        - Editor / 编辑器
+        - Other / 其他
+    validations:
+      required: true
+
+  - type: dropdown
+    id: priority
+    attributes:
+      label: 优先级 / Priority
+      description: 你认为这个功能有多重要？/ How important do you think this feature is?
+      options:
+        - High / 高 - 非常需要这个功能
+        - Medium / 中 - 有会更好
+        - Low / 低 - 可有可无
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: 检查清单 / Checklist
+      options:
+        - label: 我已经搜索过类似的功能请求 / I have searched for similar feature requests
+          required: true
+        - label: 这个功能不会破坏现有 API / This feature won't break existing APIs
+          required: false
+        - label: 我愿意提交 PR 实现此功能 / I am willing to submit a PR to implement this feature
+          required: false

.github/ISSUE_TEMPLATE/question.yml

@@ -0,0 +1,64 @@
+name: ❓ Question / 问题咨询
+description: Ask a question about using the framework / 询问框架使用问题
+title: "[Question]: "
+labels: ["question"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        💡 提示：如果是简单问题，可以先查看：
+        - [📚 文档](https://esengine.github.io/ecs-framework/)
+        - [📖 AI 文档助手](https://deepwiki.com/esengine/esengine)
+        - [💬 QQ 交流群](https://jq.qq.com/?_wv=1027&k=29w1Nud6)
+
+        💡 Tip: For simple questions, please check first:
+        - [📚 Documentation](https://esengine.github.io/ecs-framework/)
+        - [📖 AI Documentation](https://deepwiki.com/esengine/esengine)
+
+  - type: textarea
+    id: question
+    attributes:
+      label: 你的问题 / Your Question
+      description: 清晰描述你的问题 / Describe your question clearly
+      placeholder: 如何在 Cocos Creator 中使用 ECS Framework？
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: 背景信息 / Context
+      description: 提供更多上下文帮助理解问题 / Provide more context to help understand
+      placeholder: |
+        我正在开发一个多人在线游戏...
+        我尝试过...但是...
+    validations:
+      required: false
+
+  - type: textarea
+    id: code
+    attributes:
+      label: 相关代码 / Related Code
+      description: 如果适用，提供相关代码片段 / If applicable, provide relevant code snippet
+      render: typescript
+    validations:
+      required: false
+
+  - type: input
+    id: version
+    attributes:
+      label: 版本 / Version
+      description: 使用的框架版本 / Framework version you're using
+      placeholder: 例如 / e.g., 2.2.8
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: 检查清单 / Checklist
+      options:
+        - label: 我已经查看过文档 / I have checked the documentation
+          required: true
+        - label: 我已经搜索过类似问题 / I have searched for similar questions
+          required: true

.github/codeql/codeql-config.yml

@@ -0,0 +1,13 @@
+name: "CodeQL Config"
+
+# Paths to exclude from analysis
+paths-ignore:
+  - thirdparty
+  - "**/node_modules"
+  - "**/dist"
+  - "**/bin"
+  - "**/tests"
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "**/test"
+  - "**/__tests__"

.github/labels.yml

@@ -0,0 +1,95 @@
+# GitHub Labels 配置
+# 可以使用 https://github.com/Financial-Times/github-label-sync 来同步标签
+
+# Size Labels (PR 大小)
+- name: 'size/XS'
+  color: '00ff00'
+  description: '极小的改动 (< 10 行)'
+
+- name: 'size/S'
+  color: '00ff00'
+  description: '小改动 (10-100 行)'
+
+- name: 'size/M'
+  color: 'ffff00'
+  description: '中等改动 (100-500 行)'
+
+- name: 'size/L'
+  color: 'ff9900'
+  description: '大改动 (500-1000 行)'
+
+- name: 'size/XL'
+  color: 'ff0000'
+  description: '超大改动 (> 1000 行)'
+
+# Type Labels
+- name: 'bug'
+  color: 'd73a4a'
+  description: '错误或问题'
+
+- name: 'enhancement'
+  color: 'a2eeef'
+  description: '新功能或改进'
+
+- name: 'documentation'
+  color: '0075ca'
+  description: '文档相关'
+
+- name: 'question'
+  color: 'd876e3'
+  description: '问题咨询'
+
+- name: 'performance'
+  color: 'ff6b6b'
+  description: '性能相关'
+
+# Scope Labels
+- name: 'core'
+  color: '5319e7'
+  description: '核心包相关'
+
+- name: 'editor'
+  color: '5319e7'
+  description: '编辑器相关'
+
+- name: 'network'
+  color: '5319e7'
+  description: '网络相关'
+
+# Status Labels
+- name: 'stale'
+  color: 'ededed'
+  description: '长时间无活动'
+
+- name: 'wip'
+  color: 'fbca04'
+  description: '进行中'
+
+- name: 'help wanted'
+  color: '008672'
+  description: '需要帮助'
+
+- name: 'good first issue'
+  color: '7057ff'
+  description: '适合新手'
+
+- name: 'quick-review'
+  color: '00ff00'
+  description: '小改动，快速 Review'
+
+- name: 'automerge'
+  color: 'bfdadc'
+  description: '自动合并'
+
+- name: 'pinned'
+  color: 'c2e0c6'
+  description: '置顶，不会被标记为 stale'
+
+- name: 'security'
+  color: 'ee0701'
+  description: '安全相关，高优先级'
+
+# Dependencies
+- name: 'dependencies'
+  color: '0366d6'
+  description: '依赖更新'

.github/workflows/ci.yml

@@ -6,79 +6,108 @@ on:
     paths:
       - 'packages/**'
       - 'package.json'
-      - 'package-lock.json'
+      - 'pnpm-lock.yaml'
       - 'tsconfig.json'
+      - 'turbo.json'
       - 'jest.config.*'
       - '.github/workflows/ci.yml'
   pull_request:
     branches: [ master, main, develop ]
-    paths:
-      - 'packages/**'
-      - 'package.json'
-      - 'package-lock.json'
-      - 'tsconfig.json'
-      - 'jest.config.*'
-      - '.github/workflows/ci.yml'
+    # Run on all PRs to satisfy branch protection, but skip build if no code changes
 
 jobs:
-  test:
+  # Check if we need to run the full CI
+  check-changes:
     runs-on: ubuntu-latest
-    
+    outputs:
+      should-run: ${{ steps.filter.outputs.code }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            code:
+              - 'packages/**'
+              - 'package.json'
+              - 'pnpm-lock.yaml'
+              - 'tsconfig.json'
+              - 'turbo.json'
+              - 'jest.config.*'
+
+  ci:
+    needs: check-changes
+    if: needs.check-changes.outputs.should-run == 'true'
+    runs-on: ubuntu-latest
+    env:
+      TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }}
+      TURBO_TEAM: ${{ vars.TURBO_TEAM }}
+
     steps:
     - name: Checkout code
       uses: actions/checkout@v4
 
+    - name: Install pnpm
+      uses: pnpm/action-setup@v4
+
     - name: Setup Node.js
       uses: actions/setup-node@v4
       with:
         node-version: '20.x'
-        cache: 'npm'
+        cache: 'pnpm'
 
     - name: Install dependencies
-      run: npm ci
+      run: pnpm install --no-frozen-lockfile
 
-    - name: Build core package first
-      run: npm run build:core
+    # 构建 framework 包 (可独立发布的通用库，无外部依赖)
+    - name: Build framework packages
+      run: |
+        pnpm --filter @esengine/ecs-framework build
+        pnpm --filter @esengine/ecs-framework-math build
+        pnpm --filter @esengine/behavior-tree build
+        pnpm --filter @esengine/blueprint build
+        pnpm --filter @esengine/fsm build
+        pnpm --filter @esengine/timer build
+        pnpm --filter @esengine/spatial build
+        pnpm --filter @esengine/procgen build
+        pnpm --filter @esengine/pathfinding build
+        pnpm --filter @esengine/network-protocols build
+        pnpm --filter @esengine/rpc build
+        pnpm --filter @esengine/network build
 
+    # 类型检查 (仅 framework 包)
+    - name: Type check (framework packages)
+      run: pnpm run type-check:framework
+
+    # Lint 检查 (仅 framework 包)
+    - name: Lint check (framework packages)
+      run: pnpm run lint:framework
+
+    # 测试 (仅 framework 包)
     - name: Run tests with coverage
-      run: npm run test:ci
+      run: pnpm run test:ci:framework
 
     - name: Upload coverage to Codecov
       uses: codecov/codecov-action@v4
+      continue-on-error: true
       with:
         file: ./coverage/lcov.info
         flags: unittests
         name: codecov-umbrella
         fail_ci_if_error: false
 
-  build:
-    runs-on: ubuntu-latest
-    needs: test
-    
-    steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '20.x'
-        cache: 'npm'
-
-    - name: Install dependencies
-      run: npm ci
-
-    - name: Build project
-      run: npm run build
-
-    - name: Build npm package
-      run: npm run build:npm
+    # 构建 npm 包 (core 和 math)
+    - name: Build npm packages
+      run: |
+        pnpm run build:npm:core
+        pnpm run build:npm:math
 
+    # 上传构建产物
     - name: Upload build artifacts
       uses: actions/upload-artifact@v4
       with:
         name: build-artifacts
         path: |
-          bin/
-          dist/
-        retention-days: 7 
+          packages/framework/**/dist/
+          packages/framework/**/bin/
+        retention-days: 7

.github/workflows/codecov.yml

@@ -0,0 +1,49 @@
+name: Code Coverage
+
+on:
+  push:
+    branches: [ master, main ]
+  pull_request:
+    branches: [ master, main ]
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Run tests with coverage
+        run: |
+          cd packages/framework/core
+          pnpm run test:coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        continue-on-error: true
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./packages/framework/core/coverage/coverage-final.json
+          flags: core
+          name: core-coverage
+          fail_ci_if_error: false
+          verbose: true
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: packages/framework/core/coverage/

.github/workflows/codeql.yml

@@ -0,0 +1,42 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "master", "main" ]
+  pull_request:
+    branches: [ "master", "main" ]
+  schedule:
+    - cron: '0 0 * * 1' # 每周一运行
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'javascript' ]
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v3
+      with:
+        languages: ${{ matrix.language }}
+        queries: security-and-quality
+        config-file: ./.github/codeql/codeql-config.yml
+
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v3
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v3
+      with:
+        category: "/language:${{matrix.language}}"

.github/workflows/commitlint.yml

@@ -0,0 +1,34 @@
+name: Commit Lint
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  commitlint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'pnpm'
+
+      - name: Install commitlint
+        run: |
+          pnpm add -D @commitlint/config-conventional @commitlint/cli
+
+      - name: Validate PR commits
+        run: npx commitlint --from ${{ github.event.pull_request.base.sha }} --to ${{ github.event.pull_request.head.sha }} --verbose

.github/workflows/docs.yml

@@ -29,31 +29,34 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20.x'
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Setup Pages
         uses: actions/configure-pages@v4
 
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install
 
       - name: Build core package
-        run: npm run build:core
+        run: pnpm run build:core
 
       - name: Generate API documentation
-        run: npm run docs:api
+        run: pnpm run docs:api
 
       - name: Build documentation
-        run: npm run docs:build
+        run: pnpm run docs:build
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/.vitepress/dist
+          path: docs/dist
 
   deploy:
     environment:

.github/workflows/release-changesets.yml

@@ -0,0 +1,73 @@
+name: Release (Changesets)
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - '.changeset/**'
+      - 'packages/*/package.json'
+      - 'packages/*/*/package.json'
+      - 'packages/*/*/*/package.json'
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+jobs:
+  release:
+    name: Release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      id-token: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Build framework packages
+        run: |
+          # Only build packages managed by Changesets (not in ignore list)
+          pnpm --filter "@esengine/ecs-framework" build
+          pnpm --filter "@esengine/ecs-framework-math" build
+          pnpm --filter "@esengine/behavior-tree" build
+          pnpm --filter "@esengine/blueprint" build
+          pnpm --filter "@esengine/fsm" build
+          pnpm --filter "@esengine/timer" build
+          pnpm --filter "@esengine/spatial" build
+          pnpm --filter "@esengine/procgen" build
+          pnpm --filter "@esengine/pathfinding" build
+          pnpm --filter "@esengine/network-protocols" build
+          pnpm --filter "@esengine/rpc" build
+          pnpm --filter "@esengine/network" build
+          pnpm --filter "@esengine/server" build
+          pnpm --filter "@esengine/cli" build
+          pnpm --filter "create-esengine-server" build
+
+      - name: Create Release Pull Request or Publish
+        id: changesets
+        uses: changesets/action@v1
+        with:
+          version: pnpm changeset:version
+          publish: pnpm changeset:publish
+          title: 'chore: release packages'
+          commit: 'chore: release packages'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/release-editor.yml

@@ -33,11 +33,14 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
           node-version: '20.x'
-          cache: 'npm'
+          cache: 'pnpm'
 
       - name: Install Rust stable
         uses: dtolnay/rust-toolchain@stable
@@ -47,7 +50,7 @@ jobs:
       - name: Rust cache
         uses: Swatinem/rust-cache@v2
         with:
-          workspaces: packages/editor-app/src-tauri
+          workspaces: packages/editor/editor-app/src-tauri
           cache-on-failure: true
 
       - name: Install dependencies (Ubuntu)
@@ -57,55 +60,154 @@ jobs:
           sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libappindicator3-dev librsvg2-dev patchelf
 
       - name: Install frontend dependencies
-        run: npm ci
+        run: pnpm install
 
       - name: Update version in config files (for manual trigger)
         if: github.event_name == 'workflow_dispatch'
         run: |
-          cd packages/editor-app
-          # 临时更新版本号用于构建（不提交到仓库）
-          npm version ${{ github.event.inputs.version }} --no-git-tag-version
+          cd packages/editor/editor-app
+          node -e "const pkg=require('./package.json'); pkg.version='${{ github.event.inputs.version }}'; require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2)+'\n')"
           node scripts/sync-version.js
 
-      - name: Cache TypeScript build
-        uses: actions/cache@v4
-        with:
-          path: |
-            packages/core/bin
-            packages/editor-core/dist
-          key: ${{ runner.os }}-ts-build-${{ hashFiles('packages/core/src/**', 'packages/editor-core/src/**') }}
-          restore-keys: |
-            ${{ runner.os }}-ts-build-
+      - name: Install wasm-pack
+        run: cargo install wasm-pack
 
-      - name: Build core package
-        run: npm run build:core
+      # 使用 Turborepo 自动按依赖顺序构建所有包
+      # 这会自动处理：core -> asset-system -> editor-core -> ui -> 等等
+      - name: Build all packages with Turborepo
+        run: pnpm run build
 
-      - name: Build editor-core package
+      - name: Copy WASM files to ecs-engine-bindgen
+        shell: bash
         run: |
-          cd packages/editor-core
-          npm run build
+          mkdir -p packages/engine/ecs-engine-bindgen/src/wasm
+          cp packages/rust/engine/pkg/es_engine.js packages/engine/ecs-engine-bindgen/src/wasm/
+          cp packages/rust/engine/pkg/es_engine.d.ts packages/engine/ecs-engine-bindgen/src/wasm/
+          cp packages/rust/engine/pkg/es_engine_bg.wasm packages/engine/ecs-engine-bindgen/src/wasm/
+          cp packages/rust/engine/pkg/es_engine_bg.wasm.d.ts packages/engine/ecs-engine-bindgen/src/wasm/
+
+      - name: Bundle runtime files for Tauri
+        run: |
+          cd packages/editor/editor-app
+          node scripts/bundle-runtime.mjs
 
       - name: Build Tauri app
+        id: tauri
         uses: tauri-apps/tauri-action@v0.5
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
           TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
         with:
-          projectPath: packages/editor-app
+          projectPath: packages/editor/editor-app
           tagName: ${{ github.event_name == 'workflow_dispatch' && format('editor-v{0}', github.event.inputs.version) || github.ref_name }}
           releaseName: 'ECS Editor v${{ github.event.inputs.version || github.ref_name }}'
           releaseBody: 'See the assets to download this version and install.'
-          releaseDraft: false
+          releaseDraft: true
           prerelease: false
           includeUpdaterJson: true
           updaterJsonKeepUniversal: false
           args: ${{ matrix.platform == 'macos-latest' && format('--target {0}', matrix.target) || '' }}
 
-  # 构建成功后，创建 PR 更新版本号
-  update-version-pr:
+      # Windows 构建上传 artifact 供 SignPath 签名
+      - name: Upload Windows artifacts for signing
+        if: matrix.platform == 'windows-latest'
+        uses: actions/upload-artifact@v4
+        with:
+          name: windows-unsigned
+          path: |
+            packages/editor/editor-app/src-tauri/target/release/bundle/nsis/*.exe
+            packages/editor/editor-app/src-tauri/target/release/bundle/msi/*.msi
+          retention-days: 1
+
+  # SignPath 代码签名（Windows）
+  # SignPath OSS code signing for Windows
+  #
+  # 配置步骤 | Setup Steps:
+  # 1. 在 SignPath 门户创建项目 | Create project in SignPath portal
+  # 2. 导入 .signpath/artifact-configuration.xml | Import artifact configuration
+  # 3. 使用 'test-signing' 策略测试 | Use 'test-signing' policy for testing
+  #    生产环境改为 'release-signing' | Change to 'release-signing' for production
+  # 4. 配置 GitHub Secrets | Configure GitHub Secrets:
+  #    - SIGNPATH_API_TOKEN: API token from SignPath
+  #    - SIGNPATH_ORGANIZATION_ID: Your organization ID
+  #
+  # 文档 | Documentation: https://about.signpath.io/documentation/trusted-build-systems/github
+  sign-windows:
     needs: build-tauri
-    if: github.event_name == 'workflow_dispatch' && success()
+    runs-on: ubuntu-latest
+    # 只有在构建成功时才运行 | Only run on successful build
+    if: success()
+
+    steps:
+      - name: Check SignPath configuration
+        id: check-signpath
+        run: |
+          if [ -n "${{ secrets.SIGNPATH_API_TOKEN }}" ] && [ -n "${{ secrets.SIGNPATH_ORGANIZATION_ID }}" ]; then
+            echo "enabled=true" >> $GITHUB_OUTPUT
+            echo "SignPath is configured, proceeding with code signing"
+          else
+            echo "enabled=false" >> $GITHUB_OUTPUT
+            echo "SignPath secrets not configured, skipping code signing"
+            echo "To enable: add SIGNPATH_API_TOKEN and SIGNPATH_ORGANIZATION_ID secrets"
+          fi
+
+      - name: Checkout
+        if: steps.check-signpath.outputs.enabled == 'true'
+        uses: actions/checkout@v4
+
+      - name: Get artifact ID
+        if: steps.check-signpath.outputs.enabled == 'true'
+        id: get-artifact
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          # 获取 windows-unsigned artifact 的 ID
+          ARTIFACT_ID=$(gh api \
+            -H "Accept: application/vnd.github+json" \
+            "/repos/${{ github.repository }}/actions/runs/${{ github.run_id }}/artifacts" \
+            --jq '.artifacts[] | select(.name == "windows-unsigned") | .id')
+
+          if [ -z "$ARTIFACT_ID" ]; then
+            echo "Error: Could not find artifact 'windows-unsigned'"
+            exit 1
+          fi
+
+          echo "artifact-id=$ARTIFACT_ID" >> $GITHUB_OUTPUT
+          echo "Found artifact ID: $ARTIFACT_ID"
+
+      - name: Submit to SignPath for code signing
+        if: steps.check-signpath.outputs.enabled == 'true'
+        id: signpath
+        uses: signpath/github-action-submit-signing-request@v1
+        with:
+          api-token: ${{ secrets.SIGNPATH_API_TOKEN }}
+          organization-id: ${{ secrets.SIGNPATH_ORGANIZATION_ID }}
+          project-slug: 'ecs-framework'
+          signing-policy-slug: 'test-signing'
+          artifact-configuration-slug: 'initial'
+          github-artifact-id: ${{ steps.get-artifact.outputs.artifact-id }}
+          wait-for-completion: true
+          wait-for-completion-timeout-in-seconds: 600
+          output-artifact-directory: './signed'
+
+      - name: Upload signed artifacts to release
+        if: steps.check-signpath.outputs.enabled == 'true'
+        uses: softprops/action-gh-release@v1
+        with:
+          files: ./signed/*
+          tag_name: ${{ github.event_name == 'workflow_dispatch' && format('editor-v{0}', github.event.inputs.version) || github.ref_name }}
+          # 保持 Draft 状态，需要手动发布 | Keep as draft, require manual publish
+          draft: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  # 构建成功后，创建 PR 更新版本号
+  # Create PR to update version after successful build
+  update-version-pr:
+    needs: [build-tauri, sign-windows]
+    # 即使签名跳过也要运行 | Run even if signing is skipped
+    if: github.event_name == 'workflow_dispatch' && !failure()
     runs-on: ubuntu-latest
 
     steps:
@@ -119,8 +221,8 @@ jobs:
 
       - name: Update version files
         run: |
-          cd packages/editor-app
-          npm version ${{ github.event.inputs.version }} --no-git-tag-version
+          cd packages/editor/editor-app
+          node -e "const pkg=require('./package.json'); pkg.version='${{ github.event.inputs.version }}'; require('fs').writeFileSync('./package.json', JSON.stringify(pkg, null, 2)+'\n')"
           node scripts/sync-version.js
 
       - name: Create Pull Request
@@ -132,16 +234,16 @@ jobs:
           delete-branch: true
           title: "chore(editor): Release v${{ github.event.inputs.version }}"
           body: |
-            ## 🚀 Release v${{ github.event.inputs.version }}
+            ## Release v${{ github.event.inputs.version }}
 
             This PR updates the editor version after successful release build.
 
             ### Changes
-            - ✅ Updated `packages/editor-app/package.json` → `${{ github.event.inputs.version }}`
-            - ✅ Updated `packages/editor-app/src-tauri/tauri.conf.json` → `${{ github.event.inputs.version }}`
+            - Updated `packages/editor/editor-app/package.json` → `${{ github.event.inputs.version }}`
+            - Updated `packages/editor/editor-app/src-tauri/tauri.conf.json` → `${{ github.event.inputs.version }}`
 
             ### Release
-            - 📦 [GitHub Release](https://github.com/${{ github.repository }}/releases/tag/editor-v${{ github.event.inputs.version }})
+            - [GitHub Release](https://github.com/${{ github.repository }}/releases/tag/editor-v${{ github.event.inputs.version }})
 
             ---
             *This PR was automatically created by the release workflow.*

.github/workflows/release.yml

@@ -0,0 +1,225 @@
+name: Release NPM Packages
+
+on:
+  # Tag trigger: supports v* and {package}-v* formats
+  push:
+    tags:
+      - 'v*'
+      - 'core-v*'
+      - 'behavior-tree-v*'
+      - 'editor-core-v*'
+      - 'node-editor-v*'
+      - 'blueprint-v*'
+      - 'tilemap-v*'
+      - 'physics-rapier2d-v*'
+      - 'worker-generator-v*'
+
+  # Manual trigger option
+  workflow_dispatch:
+    inputs:
+      package:
+        description: 'Select package to publish'
+        required: true
+        type: choice
+        options:
+          - core
+          - behavior-tree
+          - editor-core
+          - node-editor
+          - blueprint
+          - tilemap
+          - physics-rapier2d
+          - worker-generator
+      version_type:
+        description: 'Version bump type'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release-package:
+    name: Release Package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Parse tag or input
+        id: parse
+        run: |
+          if [ "${{ github.event_name }}" = "push" ]; then
+            # Parse package and version from tag
+            TAG="${GITHUB_REF#refs/tags/}"
+            echo "tag=$TAG" >> $GITHUB_OUTPUT
+
+            # Parse format: v1.0.0 or package-v1.0.0
+            if [[ "$TAG" =~ ^v([0-9]+\.[0-9]+\.[0-9]+.*)$ ]]; then
+              PACKAGE="core"
+              VERSION="${BASH_REMATCH[1]}"
+            elif [[ "$TAG" =~ ^([a-z-]+)-v([0-9]+\.[0-9]+\.[0-9]+.*)$ ]]; then
+              PACKAGE="${BASH_REMATCH[1]}"
+              VERSION="${BASH_REMATCH[2]}"
+            else
+              echo "::error::Invalid tag format: $TAG"
+              echo "Expected: v1.0.0 or package-v1.0.0"
+              exit 1
+            fi
+
+            echo "package=$PACKAGE" >> $GITHUB_OUTPUT
+            echo "version=$VERSION" >> $GITHUB_OUTPUT
+            echo "mode=tag" >> $GITHUB_OUTPUT
+            echo "Package: $PACKAGE"
+            echo "Version: $VERSION"
+          else
+            # Manual trigger: read from package.json and bump version
+            PACKAGE="${{ github.event.inputs.package }}"
+            echo "package=$PACKAGE" >> $GITHUB_OUTPUT
+            echo "mode=manual" >> $GITHUB_OUTPUT
+            echo "version_type=${{ github.event.inputs.version_type }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install
+
+      - name: Verify version (tag mode)
+        if: steps.parse.outputs.mode == 'tag'
+        run: |
+          PACKAGE="${{ steps.parse.outputs.package }}"
+          EXPECTED_VERSION="${{ steps.parse.outputs.version }}"
+
+          # Get version from package.json
+          ACTUAL_VERSION=$(node -p "require('./packages/$PACKAGE/package.json').version")
+
+          if [ "$EXPECTED_VERSION" != "$ACTUAL_VERSION" ]; then
+            echo "::error::Version mismatch!"
+            echo "Tag version: $EXPECTED_VERSION"
+            echo "package.json version: $ACTUAL_VERSION"
+            echo ""
+            echo "Please update packages/$PACKAGE/package.json to version $EXPECTED_VERSION before tagging."
+            exit 1
+          fi
+
+          echo "Version verified: $EXPECTED_VERSION"
+
+      - name: Bump version (manual mode)
+        if: steps.parse.outputs.mode == 'manual'
+        id: bump
+        run: |
+          PACKAGE="${{ steps.parse.outputs.package }}"
+          cd packages/$PACKAGE
+
+          CURRENT=$(node -p "require('./package.json').version")
+          IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
+
+          case "${{ steps.parse.outputs.version_type }}" in
+            major) NEW_VERSION="$((MAJOR+1)).0.0" ;;
+            minor) NEW_VERSION="$MAJOR.$((MINOR+1)).0" ;;
+            patch) NEW_VERSION="$MAJOR.$MINOR.$((PATCH+1))" ;;
+          esac
+
+          # Update package.json
+          node -e "const fs=require('fs'); const pkg=JSON.parse(fs.readFileSync('package.json')); pkg.version='$NEW_VERSION'; fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2)+'\n')"
+
+          echo "version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "Bumped version: $CURRENT -> $NEW_VERSION"
+
+      - name: Set final version
+        id: version
+        run: |
+          if [ "${{ steps.parse.outputs.mode }}" = "tag" ]; then
+            echo "value=${{ steps.parse.outputs.version }}" >> $GITHUB_OUTPUT
+          else
+            echo "value=${{ steps.bump.outputs.version }}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Build core package (if needed)
+        if: ${{ steps.parse.outputs.package != 'core' && steps.parse.outputs.package != 'node-editor' && steps.parse.outputs.package != 'worker-generator' }}
+        run: |
+          cd packages/framework/core
+          pnpm run build
+
+      - name: Build node-editor package (if needed for blueprint)
+        if: ${{ steps.parse.outputs.package == 'blueprint' }}
+        run: |
+          cd packages/node-editor
+          pnpm run build
+
+      - name: Build package
+        run: |
+          cd packages/${{ steps.parse.outputs.package }}
+          pnpm run build:npm
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          cd packages/${{ steps.parse.outputs.package }}/dist
+          pnpm publish --access public --no-git-checks
+
+      - name: Create GitHub Release (tag mode)
+        if: steps.parse.outputs.mode == 'tag'
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ steps.parse.outputs.tag }}
+          name: "${{ steps.parse.outputs.package }} v${{ steps.version.outputs.value }}"
+          make_latest: false
+          body: |
+            ## @esengine/${{ steps.parse.outputs.package }} v${{ steps.version.outputs.value }}
+
+            **NPM**: [@esengine/${{ steps.parse.outputs.package }}@${{ steps.version.outputs.value }}](https://www.npmjs.com/package/@esengine/${{ steps.parse.outputs.package }}/v/${{ steps.version.outputs.value }})
+
+            ```bash
+            npm install @esengine/${{ steps.parse.outputs.package }}@${{ steps.version.outputs.value }}
+            ```
+
+            ---
+            *Auto-released by GitHub Actions*
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Create Pull Request (manual mode)
+        if: steps.parse.outputs.mode == 'manual'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore(${{ steps.parse.outputs.package }}): release v${{ steps.version.outputs.value }}"
+          branch: release/${{ steps.parse.outputs.package }}-v${{ steps.version.outputs.value }}
+          delete-branch: true
+          title: "chore(${{ steps.parse.outputs.package }}): Release v${{ steps.version.outputs.value }}"
+          body: |
+            ## Release v${{ steps.version.outputs.value }}
+
+            This PR updates `@esengine/${{ steps.parse.outputs.package }}` package version.
+
+            ### Changes
+            - Published to npm: [@esengine/${{ steps.parse.outputs.package }}@${{ steps.version.outputs.value }}](https://www.npmjs.com/package/@esengine/${{ steps.parse.outputs.package }}/v/${{ steps.version.outputs.value }})
+            - Updated `packages/${{ steps.parse.outputs.package }}/package.json` to `${{ steps.version.outputs.value }}`
+
+            ---
+            *This PR was automatically created by the release workflow*
+          labels: |
+            release
+            ${{ steps.parse.outputs.package }}
+            automated pr

.github/workflows/stale.yml

@@ -0,0 +1,60 @@
+name: Stale Issues and PRs
+
+on:
+  schedule:
+    - cron: '0 0 * * *'  # 每天运行一次
+  workflow_dispatch:  # 允许手动触发
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Stale Bot
+        uses: actions/stale@v9
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+
+          # Issue 配置
+          stale-issue-message: |
+            这个 issue 已经 60 天没有活动了，将在 14 天后自动关闭。
+            如果这个问题仍然存在，请留言说明情况。
+
+            This issue has been inactive for 60 days and will be closed in 14 days.
+            If this issue is still relevant, please leave a comment.
+          close-issue-message: |
+            由于长时间无活动，这个 issue 已被自动关闭。
+            如需重新打开，请留言说明。
+
+            This issue has been automatically closed due to inactivity.
+            Please comment if you'd like to reopen it.
+          days-before-issue-stale: 60
+          days-before-issue-close: 14
+          stale-issue-label: 'stale'
+          exempt-issue-labels: 'pinned,security,enhancement,help wanted'
+
+          # PR 配置
+          stale-pr-message: |
+            这个 PR 已经 30 天没有活动了，将在 7 天后自动关闭。
+            如果你还在处理这个 PR，请更新一下。
+
+            This PR has been inactive for 30 days and will be closed in 7 days.
+            If you're still working on it, please update it.
+          close-pr-message: |
+            由于长时间无活动，这个 PR 已被自动关闭。
+            如需继续，请重新打开或创建新的 PR。
+
+            This PR has been automatically closed due to inactivity.
+            Please reopen or create a new PR to continue.
+          days-before-pr-stale: 30
+          days-before-pr-close: 7
+          stale-pr-label: 'stale'
+          exempt-pr-labels: 'pinned,security,wip'
+
+          # 其他配置
+          operations-per-run: 100
+          remove-stale-when-updated: true
+          ascending: true

.gitignore

@@ -16,6 +16,10 @@ dist/
 *.tmp
 *.temp
 .cache/
+.build-cache/
+
+# Turborepo
+.turbo/
 
 # IDE 配置
 .idea/
@@ -44,13 +48,21 @@ logs/
 .env.test.local
 .env.production.local
 
+# 代码签名证书（敏感文件）
+certs/
+*.pfx
+*.p12
+*.cer
+*.pem
+*.key
+
 # 测试覆盖率
 coverage/
 *.lcov
 
-# 包管理器锁文件（保留npm的，忽略其他的）
+# 包管理器锁文件（忽略yarn，保留pnpm）
 yarn.lock
-pnpm-lock.yaml
+package-lock.json
 
 # 文档生成
 docs/api/
@@ -78,3 +90,7 @@ docs/.vitepress/dist/
 # Tauri 捆绑输出
 **/src-tauri/target/release/bundle/
 **/src-tauri/target/debug/bundle/
+
+# Rust 构建产物
+**/engine-shared/target/
+external/

.gitmodules

@@ -4,27 +4,12 @@
 [submodule "thirdparty/admin-backend"]
 	path = thirdparty/admin-backend
 	url = https://github.com/esengine/admin-backend.git
-[submodule "extensions/cocos/cocos-ecs/extensions/cocos-ecs-extension"]
-	path = extensions/cocos/cocos-ecs/extensions/cocos-ecs-extension
-	url = https://github.com/esengine/cocos-ecs-extension.git
-[submodule "extensions/cocos/cocos-ecs/extensions/behaviour-tree"]
-	path = extensions/cocos/cocos-ecs/extensions/behaviour-tree
-	url = https://github.com/esengine/behaviour-tree.git
-[submodule "extensions/cocos/cocos-ecs/extensions/cocos-terrain-gen"]
-	path = extensions/cocos/cocos-ecs/extensions/cocos-terrain-gen
-	url = https://github.com/esengine/cocos-terrain-gen.git
-[submodule "extensions/cocos/cocos-ecs/extensions/mvvm-designer"]
-	path = extensions/cocos/cocos-ecs/extensions/mvvm-designer
-	url = https://github.com/esengine/mvvm-designer.git
 [submodule "thirdparty/mvvm-ui-framework"]
 	path = thirdparty/mvvm-ui-framework
 	url = https://github.com/esengine/mvvm-ui-framework.git
 [submodule "thirdparty/cocos-nexus"]
 	path = thirdparty/cocos-nexus
 	url = https://github.com/esengine/cocos-nexus.git
-[submodule "extensions/cocos/cocos-ecs/extensions/utilityai_designer"]
-	path = extensions/cocos/cocos-ecs/extensions/utilityai_designer
-	url = https://github.com/esengine/utilityai_designer.git
 [submodule "thirdparty/ecs-astar"]
 	path = thirdparty/ecs-astar
 	url = https://github.com/esengine/ecs-astar.git

.npmrc

@@ -0,0 +1,2 @@
+link-workspace-packages=true
+prefer-workspace-packages=true

.size-limit.json

@@ -0,0 +1,25 @@
+[
+  {
+    "name": "@esengine/ecs-framework (ESM)",
+    "path": "packages/core/dist/esm/index.js",
+    "import": "*",
+    "limit": "50 KB",
+    "webpack": false,
+    "gzip": true
+  },
+  {
+    "name": "@esengine/ecs-framework (UMD)",
+    "path": "packages/core/dist/umd/ecs-framework.js",
+    "limit": "60 KB",
+    "webpack": false,
+    "gzip": true
+  },
+  {
+    "name": "Core Runtime (Tree-shaking)",
+    "path": "packages/core/dist/esm/index.js",
+    "import": "{ Core, Scene, Entity, Component }",
+    "limit": "30 KB",
+    "webpack": false,
+    "gzip": true
+  }
+]

CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# 贡献指南 / Contributing Guide
+
+感谢你对 ECS Framework 的关注！
+
+Thank you for your interest in contributing to ECS Framework!
+
+## Commit 规范 / Commit Convention
+
+本项目使用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。
+
+This project follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+### 格式 / Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+### 类型 / Types
+
+- **feat**: 新功能 / New feature
+- **fix**: 错误修复 / Bug fix
+- **docs**: 文档变更 / Documentation changes
+- **style**: 代码格式（不影响代码运行） / Code style changes
+- **refactor**: 重构（既不是新功能也不是修复） / Code refactoring
+- **perf**: 性能优化 / Performance improvements
+- **test**: 测试相关 / Test changes
+- **build**: 构建系统或依赖变更 / Build system changes
+- **ci**: CI 配置变更 / CI configuration changes
+- **chore**: 其他变更 / Other changes
+
+### 范围 / Scope
+
+- **core**: 核心包 @esengine/ecs-framework
+- **math**: 数学库包
+- **editor**: 编辑器
+- **docs**: 文档
+
+### 示例 / Examples
+
+```bash
+# 新功能
+feat(core): add component pooling system
+
+# 错误修复
+fix(core): fix entity deletion memory leak
+
+# 破坏性变更
+feat(core): redesign system lifecycle
+
+BREAKING CHANGE: System.initialize() now requires Scene parameter
+```
+
+## 自动发布 / Automatic Release
+
+本项目使用 Semantic Release 自动发布。
+
+This project uses Semantic Release for automatic publishing.
+
+### 版本规则 / Versioning Rules
+
+根据你的 commit 类型，版本号会自动更新：
+
+Based on your commit type, the version will be automatically updated:
+
+- `feat`: 增加 **minor** 版本 (0.x.0)
+- `fix`, `perf`, `refactor`: 增加 **patch** 版本 (0.0.x)
+- `BREAKING CHANGE`: 增加 **major** 版本 (x.0.0)
+
+### 发布流程 / Release Process
+
+1. 提交代码到 `master` 分支 / Push commits to `master` branch
+2. GitHub Actions 自动运行测试 / GitHub Actions runs tests automatically
+3. Semantic Release 分析 commits / Semantic Release analyzes commits
+4. 自动更新版本号 / Version is automatically updated
+5. 自动生成 CHANGELOG.md / CHANGELOG.md is automatically generated
+6. 自动发布到 npm / Package is automatically published to npm
+7. 自动创建 GitHub Release / GitHub Release is automatically created
+
+## 开发流程 / Development Workflow
+
+1. Fork 本仓库 / Fork this repository
+2. 创建特性分支 / Create a feature branch
+   ```bash
+   git checkout -b feat/my-feature
+   ```
+3. 提交你的变更 / Commit your changes
+   ```bash
+   git commit -m "feat(core): add new feature"
+   ```
+4. 推送到你的 Fork / Push to your fork
+   ```bash
+   git push origin feat/my-feature
+   ```
+5. 创建 Pull Request / Create a Pull Request
+
+## 本地测试 / Local Testing
+
+```bash
+# 安装依赖
+npm install
+
+# 运行测试
+npm test
+
+# 构建
+npm run build
+
+# 代码检查
+npm run lint
+
+# 代码格式化
+npm run format
+```
+
+## 问题反馈 / Issue Reporting
+
+如果你发现了 bug 或有新功能建议，请[创建 Issue](https://github.com/esengine/esengine/issues/new)。
+
+If you find a bug or have a feature request, please [create an issue](https://github.com/esengine/esengine/issues/new).
+
+## 许可证 / License
+
+通过贡献代码，你同意你的贡献将遵循 MIT 许可证。
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

LICENSE

@@ -1,201 +1,21 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+MIT License
 
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+Copyright (c) 2025 ESEngine Contributors
 
-   1. Definitions.
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,49 +1,98 @@
-# ECS Framework
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/esengine/esengine/master/docs/public/logo.svg" alt="ESEngine" width="180">
+  <br>
+  ESEngine
+</h1>
 
-[![CI](https://github.com/esengine/ecs-framework/workflows/CI/badge.svg)](https://github.com/esengine/ecs-framework/actions)
-[![npm version](https://badge.fury.io/js/%40esengine%2Fecs-framework.svg)](https://badge.fury.io/js/%40esengine%2Fecs-framework)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![GitHub stars](https://img.shields.io/github/stars/esengine/ecs-framework?style=social)](https://github.com/esengine/ecs-framework/stargazers)
+<p align="center">
+  <strong>Modular Game Framework for TypeScript</strong>
+</p>
 
-一个高性能的 TypeScript ECS (Entity-Component-System) 框架，专为现代游戏开发而设计。
+<p align="center">
+  <a href="https://www.npmjs.com/package/@esengine/ecs-framework"><img src="https://img.shields.io/npm/v/@esengine/ecs-framework?style=flat-square&color=blue" alt="npm"></a>
+  <a href="https://github.com/esengine/esengine/actions"><img src="https://img.shields.io/github/actions/workflow/status/esengine/esengine/ci.yml?branch=master&style=flat-square" alt="build"></a>
+  <a href="https://github.com/esengine/esengine/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license"></a>
+  <a href="https://github.com/esengine/esengine/stargazers"><img src="https://img.shields.io/github/stars/esengine/esengine?style=flat-square" alt="stars"></a>
+  <img src="https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
+</p>
 
-## 特性
+<p align="center">
+  <b>English</b> | <a href="./README_CN.md">中文</a>
+</p>
 
-- **高性能** - 针对大规模实体优化，支持SoA存储和批量处理
-- **多线程计算** - Worker系统支持真正的并行处理，充分利用多核CPU性能
-- **类型安全** - 完整的TypeScript支持，编译时类型检查
-- **现代架构** - 支持多World、多Scene的分层架构设计
-- **开发友好** - 内置调试工具和性能监控
-- **跨平台** - 支持Cocos Creator、Laya引擎和Web平台
+<p align="center">
+  <a href="https://esengine.cn/">Documentation</a> ·
+  <a href="https://esengine.cn/api/README">API Reference</a> ·
+  <a href="./examples/">Examples</a>
+</p>
 
-## 安装
+---
+
+## What is ESEngine?
+
+ESEngine is a collection of **engine-agnostic game development modules** for TypeScript. Use them with Cocos Creator, Laya, Phaser, PixiJS, or any JavaScript game engine.
+
+The core is a high-performance **ECS (Entity-Component-System)** framework, accompanied by optional modules for AI, networking, physics, and more.
 
 ```bash
 npm install @esengine/ecs-framework
 ```
 
-## 快速开始
+## Features
+
+| Module | Description | Engine Required |
+|--------|-------------|:---------------:|
+| **ECS Core** | Entity-Component-System framework with reactive queries | No |
+| **Behavior Tree** | AI behavior trees with visual editor support | No |
+| **Blueprint** | Visual scripting system | No |
+| **FSM** | Finite state machine | No |
+| **Timer** | Timer and cooldown systems | No |
+| **Spatial** | Spatial indexing and queries (QuadTree, Grid) | No |
+| **Pathfinding** | A* and navigation mesh pathfinding | No |
+| **Procgen** | Procedural generation (noise, random, sampling) | No |
+| **RPC** | High-performance RPC communication framework | No |
+| **Server** | Game server framework with rooms, auth, rate limiting | No |
+| **Network** | Client networking with prediction, AOI, delta compression | No |
+| **Transaction** | Game transaction system with Redis/Memory storage | No |
+| **World Streaming** | Open world chunk loading and streaming | No |
+
+> All framework modules can be used standalone with any rendering engine.
+
+## Quick Start
+
+### Using CLI (Recommended)
+
+The easiest way to add ECS to your existing project:
+
+```bash
+# In your project directory
+npx @esengine/cli init
+```
+
+The CLI automatically detects your project type (Cocos Creator 2.x/3.x, LayaAir 3.x, or Node.js) and generates the necessary integration code.
+
+### Manual Setup
 
 ```typescript
-import { Core, Scene, Component, EntitySystem, ECSComponent, ECSSystem, Matcher, Time } from '@esengine/ecs-framework';
+import {
+    Core, Scene, Entity, Component, EntitySystem,
+    Matcher, Time, ECSComponent, ECSSystem
+} from '@esengine/ecs-framework';
 
-// 定义组件
+// Define components (data only)
 @ECSComponent('Position')
 class Position extends Component {
-    constructor(public x = 0, public y = 0) {
-        super();
-    }
+    x = 0;
+    y = 0;
 }
 
 @ECSComponent('Velocity')
 class Velocity extends Component {
-    constructor(public dx = 0, public dy = 0) {
-        super();
-    }
+    dx = 0;
+    dy = 0;
 }
 
-// 创建系统
+// Define system (logic)
 @ECSSystem('Movement')
 class MovementSystem extends EntitySystem {
     constructor() {
@@ -52,112 +101,210 @@ class MovementSystem extends EntitySystem {
 
     protected process(entities: readonly Entity[]): void {
         for (const entity of entities) {
-            const position = entity.getComponent(Position)!;
-            const velocity = entity.getComponent(Velocity)!;
-
-            position.x += velocity.dx * Time.deltaTime;
-            position.y += velocity.dy * Time.deltaTime;
+            const pos = entity.getComponent(Position);
+            const vel = entity.getComponent(Velocity);
+            pos.x += vel.dx * Time.deltaTime;
+            pos.y += vel.dy * Time.deltaTime;
         }
     }
 }
 
-// 创建场景并启动
-class GameScene extends Scene {
-    protected initialize(): void {
-        this.addSystem(new MovementSystem());
-
-        const player = this.createEntity("Player");
-        player.addComponent(new Position(100, 100));
-        player.addComponent(new Velocity(50, 0));
-    }
-}
-
-// 启动游戏
+// Initialize
 Core.create();
-Core.setScene(new GameScene());
+const scene = new Scene();
+scene.addSystem(new MovementSystem());
 
-// 游戏循环中更新
-function gameLoop(deltaTime: number) {
-    Core.update(deltaTime);
+const player = scene.createEntity('Player');
+player.addComponent(new Position());
+player.addComponent(new Velocity());
+
+Core.setScene(scene);
+
+// Integrate with your game loop
+function gameLoop(currentTime: number) {
+    Core.update(currentTime / 1000);
+    requestAnimationFrame(gameLoop);
+}
+requestAnimationFrame(gameLoop);
+```
+
+## Using with Other Engines
+
+ESEngine's framework modules are designed to work alongside your preferred rendering engine:
+
+### With Cocos Creator
+
+```typescript
+import { Component as CCComponent, _decorator } from 'cc';
+import { Core, Scene, Matcher, EntitySystem } from '@esengine/ecs-framework';
+import { BehaviorTreeExecutionSystem } from '@esengine/behavior-tree';
+
+const { ccclass } = _decorator;
+
+@ccclass('GameManager')
+export class GameManager extends CCComponent {
+    private ecsScene!: Scene;
+
+    start() {
+        Core.create();
+        this.ecsScene = new Scene();
+
+        // Add ECS systems
+        this.ecsScene.addSystem(new BehaviorTreeExecutionSystem());
+        this.ecsScene.addSystem(new MyGameSystem());
+
+        Core.setScene(this.ecsScene);
+    }
+
+    update(dt: number) {
+        Core.update(dt);
+    }
 }
 ```
 
-## 核心特性
+### With Laya 3.x
 
-- **实体查询** - 使用 Matcher API 进行高效的实体过滤
-- **事件系统** - 类型安全的事件发布/订阅机制
-- **性能优化** - SoA 存储优化，支持大规模实体处理
-- **多线程支持** - Worker系统实现真正的并行计算，充分利用多核CPU
-- **多场景** - 支持 World/Scene 分层架构
-- **时间管理** - 内置定时器和时间控制系统
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import { FSMSystem } from '@esengine/fsm';
 
-## 平台支持
+const { regClass } = Laya;
 
-支持主流游戏引擎和 Web 平台：
+@regClass()
+export class ECSManager extends Laya.Script {
+    private ecsScene = new Scene();
 
-- **Cocos Creator**
-- **Laya 引擎**
-- **原生 Web** - 浏览器环境直接运行
-- **小游戏平台** - 微信、支付宝等小游戏
+    onAwake(): void {
+        Core.create();
+        this.ecsScene.addSystem(new FSMSystem());
+        Core.setScene(this.ecsScene);
+    }
 
-## ECS Framework Editor
+    onUpdate(): void {
+        Core.update(Laya.timer.delta / 1000);
+    }
 
-跨平台桌面编辑器，提供可视化开发和调试工具。
+    onDestroy(): void {
+        Core.destroy();
+    }
+}
+```
 
-### 主要功能
+## Packages
 
-- **场景管理** - 可视化场景层级和实体管理
-- **组件检视** - 实时查看和编辑实体组件
-- **性能分析** - 内置 Profiler 监控系统性能
-- **插件系统** - 可扩展的插件架构
-- **远程调试** - 连接运行中的游戏进行实时调试
-- **自动更新** - 支持热更新，自动获取最新版本
+### Framework (Engine-Agnostic)
 
-### 下载
+These packages have **zero rendering dependencies** and work with any engine:
 
-[![Latest Release](https://img.shields.io/github/v/release/esengine/ecs-framework?label=下载最新版本&style=for-the-badge)](https://github.com/esengine/ecs-framework/releases/latest)
+```bash
+npm install @esengine/ecs-framework      # Core ECS
+npm install @esengine/behavior-tree      # AI behavior trees
+npm install @esengine/blueprint          # Visual scripting
+npm install @esengine/fsm                # State machines
+npm install @esengine/timer              # Timers & cooldowns
+npm install @esengine/spatial            # Spatial indexing
+npm install @esengine/pathfinding        # Pathfinding
+npm install @esengine/procgen            # Procedural generation
+npm install @esengine/rpc                # RPC framework
+npm install @esengine/server             # Game server
+npm install @esengine/network            # Client networking
+npm install @esengine/transaction        # Transaction system
+npm install @esengine/world-streaming    # World streaming
+```
 
-支持 Windows、macOS (Intel & Apple Silicon)
+### ESEngine Runtime (Optional)
 
-### 截图
+If you want a complete engine solution with rendering:
 
-<img src="screenshots/main_screetshot.png" alt="ECS Framework Editor" width="800">
+| Category | Packages |
+|----------|----------|
+| **Core** | `engine-core`, `asset-system`, `material-system` |
+| **Rendering** | `sprite`, `tilemap`, `particle`, `camera`, `mesh-3d` |
+| **Physics** | `physics-rapier2d` |
+| **Platform** | `platform-web`, `platform-wechat` |
 
-<details>
-<summary>查看更多截图</summary>
+### Editor (Optional)
 
-**性能分析器**
-<img src="screenshots/performance_profiler.png" alt="Performance Profiler" width="600">
+A visual editor built with Tauri for scene management:
 
-**插件管理**
-<img src="screenshots/plugin_manager.png" alt="Plugin Manager" width="600">
+- Download from [Releases](https://github.com/esengine/esengine/releases)
+- Supports behavior tree editing, tilemap painting, visual scripting
 
-**设置界面**
-<img src="screenshots/settings.png" alt="Settings" width="600">
+## Project Structure
 
-</details>
+```
+esengine/
+├── packages/
+│   ├── framework/          # Engine-agnostic modules (NPM publishable)
+│   │   ├── core/          # ECS Framework
+│   │   ├── math/          # Math utilities
+│   │   ├── behavior-tree/ # AI behavior trees
+│   │   ├── blueprint/     # Visual scripting
+│   │   ├── fsm/           # Finite state machine
+│   │   ├── timer/         # Timer system
+│   │   ├── spatial/       # Spatial queries
+│   │   ├── pathfinding/   # Pathfinding
+│   │   ├── procgen/       # Procedural generation
+│   │   ├── rpc/           # RPC framework
+│   │   ├── server/        # Game server
+│   │   ├── network/       # Client networking
+│   │   ├── transaction/   # Transaction system
+│   │   └── world-streaming/ # World streaming
+│   │
+│   ├── engine/            # ESEngine runtime
+│   ├── rendering/         # Rendering modules
+│   ├── physics/           # Physics modules
+│   ├── editor/            # Visual editor
+│   └── rust/              # WASM renderer
+│
+├── docs/                   # Documentation
+└── examples/               # Examples
+```
 
-## 示例项目
+## Building from Source
 
-- [Worker系统演示](https://esengine.github.io/ecs-framework/demos/worker-system/) - 多线程物理系统演示，展示高性能并行计算
-- [割草机演示](https://github.com/esengine/lawn-mower-demo) - 完整的游戏示例
+```bash
+git clone https://github.com/esengine/esengine.git
+cd esengine
 
-## 文档
+pnpm install
+pnpm build
 
-- [快速入门](https://esengine.github.io/ecs-framework/guide/getting-started.html) - 详细教程和平台集成
-- [完整指南](https://esengine.github.io/ecs-framework/guide/) - ECS 概念和使用指南
-- [API 参考](https://esengine.github.io/ecs-framework/api/) - 完整 API 文档
+# Type check framework packages
+pnpm type-check:framework
 
-## 生态系统
+# Run tests
+pnpm test
+```
 
-- [路径寻找](https://github.com/esengine/ecs-astar) - A*、BFS、Dijkstra 算法
-- [AI 系统](https://github.com/esengine/BehaviourTree-ai) - 行为树、效用 AI
+## Documentation
 
-## 社区与支持
+- [ECS Framework Guide](./packages/framework/core/README.md)
+- [Behavior Tree Guide](./packages/framework/behavior-tree/README.md)
+- [API Reference](https://esengine.cn/api/README)
 
-- [问题反馈](https://github.com/esengine/ecs-framework/issues) - Bug 报告和功能建议
-- [QQ 交流群](https://jq.qq.com/?_wv=1027&k=29w1Nud6) - ecs游戏框架交流
+## Community
 
-## 许可证
+- [GitHub Issues](https://github.com/esengine/esengine/issues) - Bug reports and feature requests
+- [GitHub Discussions](https://github.com/esengine/esengine/discussions) - Questions and ideas
+- [Discord](https://discord.gg/gCAgzXFW) - Chat with the community
 
-[MIT](LICENSE) © 2025 ECS Framework
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting a pull request.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+ESEngine is licensed under the [MIT License](LICENSE). Free for personal and commercial use.
+
+---
+
+<p align="center">
+  Made with care by the ESEngine community
+</p>

README_CN.md

@@ -0,0 +1,311 @@
+<h1 align="center">
+  <img src="https://raw.githubusercontent.com/esengine/esengine/master/docs/public/logo.svg" alt="ESEngine" width="180">
+  <br>
+  ESEngine
+</h1>
+
+<p align="center">
+  <strong>TypeScript 模块化游戏框架</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@esengine/ecs-framework"><img src="https://img.shields.io/npm/v/@esengine/ecs-framework?style=flat-square&color=blue" alt="npm"></a>
+  <a href="https://github.com/esengine/esengine/actions"><img src="https://img.shields.io/github/actions/workflow/status/esengine/esengine/ci.yml?branch=master&style=flat-square" alt="build"></a>
+  <a href="https://github.com/esengine/esengine/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license"></a>
+  <a href="https://github.com/esengine/esengine/stargazers"><img src="https://img.shields.io/github/stars/esengine/esengine?style=flat-square" alt="stars"></a>
+  <img src="https://img.shields.io/badge/TypeScript-5.0+-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
+</p>
+
+<p align="center">
+  <a href="./README.md">English</a> | <b>中文</b>
+</p>
+
+<p align="center">
+  <a href="https://esengine.cn/">文档</a> ·
+  <a href="https://esengine.cn/api/README">API 参考</a> ·
+  <a href="./examples/">示例</a>
+</p>
+
+---
+
+## ESEngine 是什么？
+
+ESEngine 是一套**引擎无关的游戏开发模块**，可与 Cocos Creator、Laya、Phaser、PixiJS 等任何 JavaScript 游戏引擎配合使用。
+
+核心是一个高性能的 **ECS（实体-组件-系统）** 框架，配套 AI、网络、物理等可选模块。
+
+```bash
+npm install @esengine/ecs-framework
+```
+
+## 功能模块
+
+| 模块 | 描述 | 需要渲染引擎 |
+|------|------|:----------:|
+| **ECS 核心** | 实体-组件-系统框架，支持响应式查询 | 否 |
+| **行为树** | AI 行为树，支持可视化编辑 | 否 |
+| **蓝图** | 可视化脚本系统 | 否 |
+| **状态机** | 有限状态机 | 否 |
+| **定时器** | 定时器和冷却系统 | 否 |
+| **空间索引** | 空间查询（四叉树、网格） | 否 |
+| **寻路** | A* 和导航网格寻路 | 否 |
+| **程序化生成** | 噪声、随机、采样等生成算法 | 否 |
+| **RPC** | 高性能 RPC 通信框架 | 否 |
+| **服务端** | 游戏服务器框架，支持房间、认证、速率限制 | 否 |
+| **网络** | 客户端网络，支持预测、AOI、增量压缩 | 否 |
+| **事务系统** | 游戏事务系统，支持 Redis/内存存储 | 否 |
+| **世界流送** | 开放世界分块加载和流送 | 否 |
+
+> 所有框架模块都可以独立使用，无需依赖特定渲染引擎。
+
+## 快速开始
+
+### 使用 CLI（推荐）
+
+在现有项目中添加 ECS 的最简单方式：
+
+```bash
+# 在项目目录中运行
+npx @esengine/cli init
+```
+
+CLI 会自动检测项目类型（Cocos Creator 2.x/3.x、LayaAir 3.x 或 Node.js）并生成相应的集成代码。
+
+### 手动配置
+
+```typescript
+import {
+    Core, Scene, Entity, Component, EntitySystem,
+    Matcher, Time, ECSComponent, ECSSystem
+} from '@esengine/ecs-framework';
+
+// 定义组件（纯数据）
+@ECSComponent('Position')
+class Position extends Component {
+    x = 0;
+    y = 0;
+}
+
+@ECSComponent('Velocity')
+class Velocity extends Component {
+    dx = 0;
+    dy = 0;
+}
+
+// 定义系统（逻辑）
+@ECSSystem('Movement')
+class MovementSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(Position, Velocity));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        for (const entity of entities) {
+            const pos = entity.getComponent(Position);
+            const vel = entity.getComponent(Velocity);
+            pos.x += vel.dx * Time.deltaTime;
+            pos.y += vel.dy * Time.deltaTime;
+        }
+    }
+}
+
+// 初始化
+Core.create();
+const scene = new Scene();
+scene.addSystem(new MovementSystem());
+
+const player = scene.createEntity('Player');
+player.addComponent(new Position());
+player.addComponent(new Velocity());
+
+Core.setScene(scene);
+
+// 集成到你的游戏循环
+function gameLoop(currentTime: number) {
+    Core.update(currentTime / 1000);
+    requestAnimationFrame(gameLoop);
+}
+requestAnimationFrame(gameLoop);
+```
+
+## 与其他引擎配合使用
+
+ESEngine 的框架模块设计为可与你喜欢的渲染引擎配合使用：
+
+### 与 Cocos Creator 配合
+
+```typescript
+import { Component as CCComponent, _decorator } from 'cc';
+import { Core, Scene, Matcher, EntitySystem } from '@esengine/ecs-framework';
+import { BehaviorTreeExecutionSystem } from '@esengine/behavior-tree';
+
+const { ccclass } = _decorator;
+
+@ccclass('GameManager')
+export class GameManager extends CCComponent {
+    private ecsScene!: Scene;
+
+    start() {
+        Core.create();
+        this.ecsScene = new Scene();
+
+        // 添加 ECS 系统
+        this.ecsScene.addSystem(new BehaviorTreeExecutionSystem());
+        this.ecsScene.addSystem(new MyGameSystem());
+
+        Core.setScene(this.ecsScene);
+    }
+
+    update(dt: number) {
+        Core.update(dt);
+    }
+}
+```
+
+### 与 Laya 3.x 配合
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import { FSMSystem } from '@esengine/fsm';
+
+const { regClass } = Laya;
+
+@regClass()
+export class ECSManager extends Laya.Script {
+    private ecsScene = new Scene();
+
+    onAwake(): void {
+        Core.create();
+        this.ecsScene.addSystem(new FSMSystem());
+        Core.setScene(this.ecsScene);
+    }
+
+    onUpdate(): void {
+        Core.update(Laya.timer.delta / 1000);
+    }
+
+    onDestroy(): void {
+        Core.destroy();
+    }
+}
+```
+
+## 包列表
+
+### 框架包（引擎无关）
+
+这些包**零渲染依赖**，可与任何引擎配合使用：
+
+```bash
+npm install @esengine/ecs-framework      # ECS 核心
+npm install @esengine/behavior-tree      # AI 行为树
+npm install @esengine/blueprint          # 可视化脚本
+npm install @esengine/fsm                # 状态机
+npm install @esengine/timer              # 定时器和冷却
+npm install @esengine/spatial            # 空间索引
+npm install @esengine/pathfinding        # 寻路
+npm install @esengine/procgen            # 程序化生成
+npm install @esengine/rpc                # RPC 框架
+npm install @esengine/server             # 游戏服务器
+npm install @esengine/network            # 客户端网络
+npm install @esengine/transaction        # 事务系统
+npm install @esengine/world-streaming    # 世界流送
+```
+
+### ESEngine 运行时（可选）
+
+如果你需要完整的引擎解决方案：
+
+| 分类 | 包名 |
+|------|------|
+| **核心** | `engine-core`, `asset-system`, `material-system` |
+| **渲染** | `sprite`, `tilemap`, `particle`, `camera`, `mesh-3d` |
+| **物理** | `physics-rapier2d` |
+| **平台** | `platform-web`, `platform-wechat` |
+
+### 编辑器（可选）
+
+基于 Tauri 构建的可视化编辑器：
+
+- 从 [Releases](https://github.com/esengine/esengine/releases) 下载
+- 支持行为树编辑、Tilemap 绘制、可视化脚本
+
+## 项目结构
+
+```
+esengine/
+├── packages/
+│   ├── framework/          # 引擎无关模块（可发布到 NPM）
+│   │   ├── core/          # ECS 框架
+│   │   ├── math/          # 数学工具
+│   │   ├── behavior-tree/ # AI 行为树
+│   │   ├── blueprint/     # 可视化脚本
+│   │   ├── fsm/           # 有限状态机
+│   │   ├── timer/         # 定时器系统
+│   │   ├── spatial/       # 空间查询
+│   │   ├── pathfinding/   # 寻路
+│   │   ├── procgen/       # 程序化生成
+│   │   ├── rpc/           # RPC 框架
+│   │   ├── server/        # 游戏服务器
+│   │   ├── network/       # 客户端网络
+│   │   ├── transaction/   # 事务系统
+│   │   └── world-streaming/ # 世界流送
+│   │
+│   ├── engine/            # ESEngine 运行时
+│   ├── rendering/         # 渲染模块
+│   ├── physics/           # 物理模块
+│   ├── editor/            # 可视化编辑器
+│   └── rust/              # WASM 渲染器
+│
+├── docs/                   # 文档
+└── examples/               # 示例
+```
+
+## 从源码构建
+
+```bash
+git clone https://github.com/esengine/esengine.git
+cd esengine
+
+pnpm install
+pnpm build
+
+# 框架包类型检查
+pnpm type-check:framework
+
+# 运行测试
+pnpm test
+```
+
+## 文档
+
+- [ECS 框架指南](./packages/framework/core/README.md)
+- [行为树指南](./packages/framework/behavior-tree/README.md)
+- [API 参考](https://esengine.cn/api/README)
+
+## 社区
+
+- [QQ 交流群](https://jq.qq.com/?_wv=1027&k=29w1Nud6) - 中文社区
+- [Discord](https://discord.gg/gCAgzXFW) - 国际社区
+- [GitHub Issues](https://github.com/esengine/esengine/issues) - Bug 反馈和功能建议
+- [GitHub Discussions](https://github.com/esengine/esengine/discussions) - 问题和想法
+
+## 贡献
+
+欢迎贡献代码！提交 PR 前请阅读贡献指南。
+
+1. Fork 仓库
+2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
+3. 提交修改 (`git commit -m 'Add amazing feature'`)
+4. 推送分支 (`git push origin feature/amazing-feature`)
+5. 发起 Pull Request
+
+## 许可证
+
+ESEngine 基于 [MIT 协议](LICENSE) 开源，个人和商业使用均免费。
+
+---
+
+<p align="center">
+  由 ESEngine 社区用心打造
+</p>

SECURITY.md

@@ -1,13 +1,71 @@
+# Security Policy / 安全政策
+
+**English** | [中文](#安全政策-1)
+
+## Supported Versions
+
+We provide security updates for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.x.x   | :white_check_mark: |
+| 1.x.x   | :x:                |
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability, please report it through the following channels:
+
+### Reporting Channels
+
+- **GitHub Security Advisories**: [Report a vulnerability](https://github.com/esengine/esengine/security/advisories/new) (Recommended)
+- **Email**: security@esengine.dev
+
+### Reporting Guidelines
+
+1. **Do NOT** report security vulnerabilities in public issues
+2. Provide a detailed description of the vulnerability, including:
+   - Affected versions
+   - Steps to reproduce
+   - Potential impact
+   - Suggested fix (if available)
+
+### Response Timeline
+
+- **Acknowledgment**: Within 72 hours
+- **Initial Assessment**: Within 1 week
+- **Fix Release**: Typically within 2-4 weeks, depending on severity
+
+### Process
+
+1. We will confirm the existence and severity of the vulnerability
+2. Develop and test a fix
+3. Release a security update
+4. Publicly disclose the vulnerability details after the fix is released
+
+## Security Best Practices
+
+When using ESEngine, please follow these security recommendations:
+
+- Always use the latest stable version
+- Regularly update dependencies
+- Disable debug mode in production
+- Validate all external input data
+- Do not store sensitive information on the client side
+
+---
+
 # 安全政策
 
+[English](#security-policy--安全政策) | **中文**
+
 ## 支持的版本
 
 我们为以下版本提供安全更新：
 
 | 版本    | 支持状态           |
 | ------- | ------------------ |
-| 2.0.x   | :white_check_mark: |
-| 1.0.x   | :x:                |
+| 2.x.x   | :white_check_mark: |
+| 1.x.x   | :x:                |
 
 ## 报告漏洞
 
@@ -15,10 +73,10 @@
 
 ### 报告渠道
 
-- **邮箱**: [安全邮箱将在实际部署时提供]
-- **GitHub**: 创建私有安全报告（推荐）
+- **GitHub 安全公告**: [报告漏洞](https://github.com/esengine/esengine/security/advisories/new)（推荐）
+- **邮箱**: security@esengine.dev
 
-### 报告流程
+### 报告指南
 
 1. **不要**在公开的 issue 中报告安全漏洞
 2. 提供详细的漏洞描述，包括：
@@ -40,9 +98,9 @@
 3. 发布安全更新
 4. 在修复发布后，会在相关渠道公布漏洞详情
 
-### 安全最佳实践
+## 安全最佳实践
 
-使用 ECS Framework 时，请遵循以下安全建议：
+使用 ESEngine 时，请遵循以下安全建议：
 
 - 始终使用最新的稳定版本
 - 定期更新依赖项
@@ -50,4 +108,6 @@
 - 验证所有外部输入数据
 - 不要在客户端存储敏感信息
 
-感谢您帮助保持 ECS Framework 的安全性！
+感谢您帮助保持 ESEngine 的安全性！
+
+Thank you for helping keep ESEngine secure!

codecov.yml

@@ -0,0 +1,53 @@
+# Codecov 配置文件
+# https://docs.codecov.com/docs/codecov-yaml
+
+coverage:
+  status:
+    # 项目整体覆盖率要求
+    project:
+      default:
+        target: auto
+        threshold: 1%
+        base: auto
+        
+    # 补丁覆盖率要求（针对 PR 中的新代码）
+    patch:
+      default:
+        target: 50%  # 降低补丁覆盖率要求到 50%
+        threshold: 5%
+        base: auto
+        
+  # 精确度设置
+  precision: 2
+  round: down
+  range: "70...100"
+
+# 注释设置
+comment:
+  layout: "reach,diff,flags,tree,files"
+  behavior: default
+  require_changes: false
+  require_base: false
+  require_head: true
+
+# 忽略的文件/目录
+ignore:
+  - "tests/**/*"
+  - "**/*.test.ts"
+  - "**/*.spec.ts"
+  - "**/test/**/*"
+  - "**/tests/**/*"
+  - "bin/**/*"
+  - "dist/**/*"
+  - "node_modules/**/*"
+
+# 标志组
+flags:
+  core:
+    paths:
+      - packages/core/src/
+    carryforward: true
+
+# GitHub Checks 配置
+github_checks:
+  annotations: true

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

docs/.vitepress/config.mjs

@@ -1,225 +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/core/package.json'), 'utf-8')
-)
-
-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: 'ECS Framework',
-  description: '高性能TypeScript ECS框架 - 为游戏开发而生',
-  lang: 'zh-CN',
-
-  themeConfig: {
-    nav: [
-      { text: '首页', link: '/' },
-      { text: '快速开始', link: '/guide/getting-started' },
-      { text: '指南', link: '/guide/' },
-      { text: 'API', link: '/api/README' },
-      {
-        text: '示例',
-        items: [
-          { text: 'Worker系统演示', link: '/examples/worker-system-demo' },
-          { text: '割草机演示', link: 'https://github.com/esengine/lawn-mower-demo' }
-        ]
-      },
-      {
-        text: `v${corePackageJson.version}`,
-        link: 'https://github.com/esengine/ecs-framework/releases'
-      }
-    ],
-
-    sidebar: {
-      '/guide/': [
-        {
-          text: '开始使用',
-          items: [
-            { text: '快速开始', link: '/guide/getting-started' },
-            { text: '指南概览', link: '/guide/' }
-          ]
-        },
-        {
-          text: '核心概念',
-          collapsed: false,
-          items: [
-            { text: '实体类 (Entity)', link: '/guide/entity' },
-            { text: '组件系统 (Component)', link: '/guide/component' },
-            { text: '实体查询系统', link: '/guide/entity-query' },
-            {
-              text: '系统架构 (System)',
-              link: '/guide/system',
-              items: [
-                { text: 'Worker系统 (多线程)', link: '/guide/worker-system' }
-              ]
-            },
-            {
-              text: '场景管理 (Scene)',
-              link: '/guide/scene',
-              items: [
-                { text: 'SceneManager', link: '/guide/scene-manager' },
-                { text: 'WorldManager', link: '/guide/world-manager' }
-              ]
-            },
-            { text: '序列化系统 (Serialization)', link: '/guide/serialization' },
-            { text: '事件系统 (Event)', link: '/guide/event-system' },
-            { text: '时间和定时器 (Time)', link: '/guide/time-and-timers' },
-            { text: '日志系统 (Logger)', link: '/guide/logging' }
-          ]
-        },
-        {
-          text: '高级特性',
-          collapsed: false,
-          items: [
-            { text: '服务容器 (Service Container)', link: '/guide/service-container' },
-            { text: '插件系统 (Plugin System)', link: '/guide/plugin-system' }
-          ]
-        },
-        {
-          text: '平台适配器',
-          link: '/guide/platform-adapter',
-          collapsed: false,
-          items: [
-            { text: '浏览器适配器', link: '/guide/platform-adapter/browser' },
-            { text: '微信小游戏适配器', link: '/guide/platform-adapter/wechat-minigame' },
-            { text: 'Node.js适配器', link: '/guide/platform-adapter/nodejs' }
-          ]
-        }
-      ],
-      '/examples/': [
-        {
-          text: '示例',
-          items: [
-            { text: '示例概览', link: '/examples/' },
-            { text: 'Worker系统演示', link: '/examples/worker-system-demo' }
-          ]
-        }
-      ],
-      '/api/': [
-        {
-          text: 'API 参考',
-          items: [
-            { text: '概述', link: '/api/README' },
-            {
-              text: '核心类',
-              collapsed: false,
-              items: [
-                { text: 'Core', link: '/api/classes/Core' },
-                { text: 'Scene', link: '/api/classes/Scene' },
-                { text: 'World', link: '/api/classes/World' },
-                { text: 'Entity', link: '/api/classes/Entity' },
-                { text: 'Component', link: '/api/classes/Component' },
-                { text: 'EntitySystem', link: '/api/classes/EntitySystem' }
-              ]
-            },
-            {
-              text: '系统类',
-              collapsed: true,
-              items: [
-                { text: 'PassiveSystem', link: '/api/classes/PassiveSystem' },
-                { text: 'ProcessingSystem', link: '/api/classes/ProcessingSystem' },
-                { text: 'IntervalSystem', link: '/api/classes/IntervalSystem' }
-              ]
-            },
-            {
-              text: '工具类',
-              collapsed: true,
-              items: [
-                { text: 'Matcher', link: '/api/classes/Matcher' },
-                { text: 'Time', link: '/api/classes/Time' },
-                { text: 'PerformanceMonitor', link: '/api/classes/PerformanceMonitor' },
-                { text: 'DebugManager', link: '/api/classes/DebugManager' }
-              ]
-            },
-            {
-              text: '接口',
-              collapsed: true,
-              items: [
-                { text: 'IScene', link: '/api/interfaces/IScene' },
-                { text: 'IComponent', link: '/api/interfaces/IComponent' },
-                { text: 'ISystemBase', link: '/api/interfaces/ISystemBase' },
-                { text: 'ICoreConfig', link: '/api/interfaces/ICoreConfig' }
-              ]
-            },
-            {
-              text: '装饰器',
-              collapsed: true,
-              items: [
-                { text: '@ECSComponent', link: '/api/functions/ECSComponent' },
-                { text: '@ECSSystem', link: '/api/functions/ECSSystem' }
-              ]
-            },
-            {
-              text: '枚举',
-              collapsed: true,
-              items: [
-                { text: 'ECSEventType', link: '/api/enumerations/ECSEventType' },
-                { text: 'LogLevel', link: '/api/enumerations/LogLevel' }
-              ]
-            }
-          ]
-        }
-      ]
-    },
-
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/esengine/ecs-framework' }
-    ],
-
-    footer: {
-      message: 'Released under the MIT License.',
-      copyright: 'Copyright © 2025 ECS Framework'
-    },
-
-    editLink: {
-      pattern: 'https://github.com/esengine/ecs-framework/edit/master/docs/:path',
-      text: '在 GitHub 上编辑此页'
-    },
-
-    search: {
-      provider: 'local'
-    },
-
-    outline: {
-      level: [2, 3],
-      label: '目录'
-    }
-  },
-
-  head: [
-    ['meta', { name: 'theme-color', content: '#646cff' }],
-    ['link', { rel: 'icon', href: '/favicon.ico' }]
-  ],
-
-  base: '/ecs-framework/',
-  cleanUrls: true,
-
-  markdown: {
-    lineNumbers: true,
-    theme: {
-      light: 'github-light',
-      dark: 'github-dark'
-    }
-  }
-})

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).

docs/astro.config.mjs

@@ -0,0 +1,345 @@
+// @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: '实体',
+              translations: { en: 'Entity' },
+              items: [
+                { label: '概述', slug: 'guide/entity', translations: { en: 'Overview' } },
+                { label: '组件操作', slug: 'guide/entity/component-operations', translations: { en: 'Component Operations' } },
+                { label: '实体句柄', slug: 'guide/entity/entity-handle', translations: { en: 'Entity Handle' } },
+                { label: '生命周期', slug: 'guide/entity/lifecycle', translations: { en: 'Lifecycle' } },
+              ],
+            },
+            { 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: '场景',
+              translations: { en: 'Scene' },
+              items: [
+                { label: '概述', slug: 'guide/scene', translations: { en: 'Overview' } },
+                { label: '生命周期', slug: 'guide/scene/lifecycle', translations: { en: 'Lifecycle' } },
+                { label: '实体管理', slug: 'guide/scene/entity-management', translations: { en: 'Entity Management' } },
+                { label: '系统管理', slug: 'guide/scene/system-management', translations: { en: 'System Management' } },
+                { label: '事件系统', slug: 'guide/scene/events', translations: { en: 'Events' } },
+                { label: '调试与监控', slug: 'guide/scene/debugging', translations: { en: 'Debugging' } },
+                { label: '最佳实践', slug: 'guide/scene/best-practices', translations: { en: 'Best Practices' } },
+              ],
+            },
+            {
+              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: '插件系统',
+              translations: { en: 'Plugin System' },
+              items: [
+                { label: '概述', slug: 'guide/plugin-system', translations: { en: 'Overview' } },
+                { label: '插件开发', slug: 'guide/plugin-system/development', translations: { en: 'Development' } },
+                { label: '服务与系统', slug: 'guide/plugin-system/services-systems', translations: { en: 'Services & Systems' } },
+                { label: '依赖管理', slug: 'guide/plugin-system/dependencies', translations: { en: 'Dependencies' } },
+                { label: '插件管理', slug: 'guide/plugin-system/management', translations: { en: 'Management' } },
+                { label: '示例插件', slug: 'guide/plugin-system/examples', translations: { en: 'Examples' } },
+                { label: '最佳实践', slug: 'guide/plugin-system/best-practices', translations: { en: 'Best Practices' } },
+              ],
+            },
+            {
+              label: 'Worker 系统',
+              translations: { en: 'Worker System' },
+              items: [
+                { label: '概述', slug: 'guide/worker-system', translations: { en: 'Overview' } },
+                { label: '配置选项', slug: 'guide/worker-system/configuration', translations: { en: 'Configuration' } },
+                { label: '完整示例', slug: 'guide/worker-system/examples', translations: { en: 'Examples' } },
+                { label: '微信小游戏', slug: 'guide/worker-system/wechat', translations: { en: 'WeChat' } },
+                { label: '最佳实践', slug: 'guide/worker-system/best-practices', translations: { en: 'Best Practices' } },
+              ],
+            },
+          ],
+        },
+        {
+          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: '行为树',
+              translations: { en: 'Behavior Tree' },
+              items: [
+                { label: '概述', slug: 'modules/behavior-tree', translations: { en: 'Overview' } },
+                { label: '快速开始', slug: 'modules/behavior-tree/getting-started', translations: { en: 'Getting Started' } },
+                { label: '核心概念', slug: 'modules/behavior-tree/core-concepts', translations: { en: 'Core Concepts' } },
+                { label: '编辑器指南', slug: 'modules/behavior-tree/editor-guide', translations: { en: 'Editor Guide' } },
+                { label: '编辑器工作流', slug: 'modules/behavior-tree/editor-workflow', translations: { en: 'Editor Workflow' } },
+                { label: '资产管理', slug: 'modules/behavior-tree/asset-management', translations: { en: 'Asset Management' } },
+                { label: '自定义节点', slug: 'modules/behavior-tree/custom-actions', translations: { en: 'Custom Actions' } },
+                { label: '高级用法', slug: 'modules/behavior-tree/advanced-usage', translations: { en: 'Advanced Usage' } },
+                { label: '最佳实践', slug: 'modules/behavior-tree/best-practices', translations: { en: 'Best Practices' } },
+                { label: 'Cocos 集成', slug: 'modules/behavior-tree/cocos-integration', translations: { en: 'Cocos Integration' } },
+                { label: 'Laya 集成', slug: 'modules/behavior-tree/laya-integration', translations: { en: 'Laya Integration' } },
+                { label: 'Node.js 使用', slug: 'modules/behavior-tree/nodejs-usage', translations: { en: 'Node.js Usage' } },
+              ],
+            },
+            {
+              label: '状态机',
+              translations: { en: 'FSM' },
+              items: [
+                { label: '概述', slug: 'modules/fsm', translations: { en: 'Overview' } },
+                { label: 'API 参考', slug: 'modules/fsm/api', translations: { en: 'API Reference' } },
+                { label: '实际示例', slug: 'modules/fsm/examples', translations: { en: 'Examples' } },
+              ],
+            },
+            {
+              label: '定时器',
+              translations: { en: 'Timer' },
+              items: [
+                { label: '概述', slug: 'modules/timer', translations: { en: 'Overview' } },
+                { label: 'API 参考', slug: 'modules/timer/api', translations: { en: 'API Reference' } },
+                { label: '实际示例', slug: 'modules/timer/examples', translations: { en: 'Examples' } },
+                { label: '最佳实践', slug: 'modules/timer/best-practices', translations: { en: 'Best Practices' } },
+              ],
+            },
+            {
+              label: '空间索引',
+              translations: { en: 'Spatial' },
+              items: [
+                { label: '概述', slug: 'modules/spatial', translations: { en: 'Overview' } },
+                { label: '空间索引 API', slug: 'modules/spatial/spatial-index', translations: { en: 'Spatial Index API' } },
+                { label: 'AOI 兴趣区域', slug: 'modules/spatial/aoi', translations: { en: 'AOI' } },
+                { label: '实际示例', slug: 'modules/spatial/examples', translations: { en: 'Examples' } },
+                { label: '工具与优化', slug: 'modules/spatial/utilities', translations: { en: 'Utilities' } },
+              ],
+            },
+            {
+              label: '寻路',
+              translations: { en: 'Pathfinding' },
+              items: [
+                { label: '概述', slug: 'modules/pathfinding', translations: { en: 'Overview' } },
+                { label: '网格地图 API', slug: 'modules/pathfinding/grid-map', translations: { en: 'Grid Map API' } },
+                { label: '导航网格 API', slug: 'modules/pathfinding/navmesh', translations: { en: 'NavMesh API' } },
+                { label: '路径平滑', slug: 'modules/pathfinding/smoothing', translations: { en: 'Path Smoothing' } },
+                { label: '实际示例', slug: 'modules/pathfinding/examples', translations: { en: 'Examples' } },
+              ],
+            },
+            {
+              label: '蓝图',
+              translations: { en: 'Blueprint' },
+              items: [
+                { label: '概述', slug: 'modules/blueprint', translations: { en: 'Overview' } },
+                { label: '虚拟机 API', slug: 'modules/blueprint/vm', translations: { en: 'VM API' } },
+                { label: '自定义节点', slug: 'modules/blueprint/custom-nodes', translations: { en: 'Custom Nodes' } },
+                { label: '内置节点', slug: 'modules/blueprint/nodes', translations: { en: 'Built-in Nodes' } },
+                { label: '蓝图组合', slug: 'modules/blueprint/composition', translations: { en: 'Composition' } },
+                { label: '实际示例', slug: 'modules/blueprint/examples', translations: { en: 'Examples' } },
+              ],
+            },
+            {
+              label: '程序生成',
+              translations: { en: 'Procgen' },
+              items: [
+                { label: '概述', slug: 'modules/procgen', translations: { en: 'Overview' } },
+                { label: '噪声函数', slug: 'modules/procgen/noise', translations: { en: 'Noise Functions' } },
+                { label: '种子随机数', slug: 'modules/procgen/random', translations: { en: 'Seeded Random' } },
+                { label: '采样工具', slug: 'modules/procgen/sampling', translations: { en: 'Sampling' } },
+                { label: '实际示例', slug: 'modules/procgen/examples', translations: { en: 'Examples' } },
+              ],
+            },
+            {
+              label: 'RPC 通信',
+              translations: { en: 'RPC' },
+              items: [
+                { label: '概述', slug: 'modules/rpc', translations: { en: 'Overview' } },
+                { label: '服务端', slug: 'modules/rpc/server', translations: { en: 'Server' } },
+                { label: '客户端', slug: 'modules/rpc/client', translations: { en: 'Client' } },
+                { label: '编解码', slug: 'modules/rpc/codec', translations: { en: 'Codec' } },
+              ],
+            },
+            {
+              label: '网络同步',
+              translations: { en: 'Network' },
+              items: [
+                { label: '概述', slug: 'modules/network', translations: { en: 'Overview' } },
+                { label: '客户端', slug: 'modules/network/client', translations: { en: 'Client' } },
+                { label: '服务器', slug: 'modules/network/server', translations: { en: 'Server' } },
+                { label: '认证系统', slug: 'modules/network/auth', translations: { en: 'Authentication' } },
+                { label: '速率限制', slug: 'modules/network/rate-limit', translations: { en: 'Rate Limiting' } },
+                { label: '状态同步', slug: 'modules/network/sync', translations: { en: 'State Sync' } },
+                { label: '客户端预测', slug: 'modules/network/prediction', translations: { en: 'Prediction' } },
+                { label: 'AOI 兴趣区域', slug: 'modules/network/aoi', translations: { en: 'AOI' } },
+                { label: '增量压缩', slug: 'modules/network/delta', translations: { en: 'Delta Compression' } },
+                { label: 'API 参考', slug: 'modules/network/api', translations: { en: 'API Reference' } },
+              ],
+            },
+            {
+              label: '事务系统',
+              translations: { en: 'Transaction' },
+              items: [
+                { label: '概述', slug: 'modules/transaction', translations: { en: 'Overview' } },
+                { label: '核心概念', slug: 'modules/transaction/core', translations: { en: 'Core Concepts' } },
+                { label: '存储层', slug: 'modules/transaction/storage', translations: { en: 'Storage Layer' } },
+                { label: '操作', slug: 'modules/transaction/operations', translations: { en: 'Operations' } },
+                { label: '分布式事务', slug: 'modules/transaction/distributed', translations: { en: 'Distributed' } },
+              ],
+            },
+            {
+              label: '世界流式加载',
+              translations: { en: 'World Streaming' },
+              items: [
+                { label: '概述', slug: 'modules/world-streaming', translations: { en: 'Overview' } },
+                { label: '区块管理', slug: 'modules/world-streaming/chunk-manager', translations: { en: 'Chunk Manager' } },
+                { label: '流式系统', slug: 'modules/world-streaming/streaming-system', translations: { en: 'Streaming System' } },
+                { label: '序列化', slug: 'modules/world-streaming/serialization', translations: { en: 'Serialization' } },
+                { label: '实际示例', slug: 'modules/world-streaming/examples', translations: { en: 'Examples' } },
+              ],
+            },
+          ],
+        },
+        {
+          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/transaction', link: 'https://github.com/esengine/esengine/blob/master/packages/framework/transaction/CHANGELOG.md', attrs: { target: '_blank' } },
+            { label: '@esengine/rpc', link: 'https://github.com/esengine/esengine/blob/master/packages/framework/rpc/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()],
+  },
+});

docs/guide/component.md

@@ -1,658 +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` 装饰器**，这确保了：
-- 组件在代码混淆后仍能正确识别
-- 提供稳定的类型名称用于序列化和调试
-- 框架能正确管理组件注册
-
-```typescript
-// 正确的用法
-@ECSComponent('Velocity')
-class Velocity extends Component {
-  dx: number = 0;
-  dy: number = 0;
-}
-
-// 错误的用法 - 没有装饰器
-class BadComponent 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<number, Set<{ component: WeakRef<Component>, 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 架构的数据载体，正确设计组件能让你的游戏代码更模块化、可维护和高性能。

docs/guide/entity-query.md

@@ -1,501 +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 {
-        // 处理可以战斗的活着的实体
-    }
-}
-```
-
-### 按标签查询
-
-```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;
-    }
-}
-```
-
-## 最佳实践
-
-### 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
-```
-
-## 相关 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 参考

docs/guide/entity.md

@@ -1,288 +0,0 @@
-# 实体类
-
-在 ECS 架构中，实体（Entity）是游戏世界中的基本对象。实体本身不包含游戏逻辑或数据，它只是一个容器，用来组合不同的组件来实现各种功能。
-
-## 基本概念
-
-实体是一个轻量级的对象，主要用于：
-- 作为组件的容器
-- 提供唯一标识（ID）
-- 管理组件的生命周期
-
-## 创建实体
-
-**重要提示：实体必须通过场景创建，不支持手动创建！**
-
-实体必须通过场景的 `createEntity()` 方法来创建，这样才能确保：
-- 实体被正确添加到场景的实体管理系统中
-- 实体被添加到查询系统中，供系统使用
-- 实体获得正确的场景引用
-- 触发相关的生命周期事件
-
-```typescript
-// 正确的方式：通过场景创建实体
-const player = scene.createEntity("Player");
-
-// ❌ 错误的方式：手动创建实体
-// const entity = new Entity("MyEntity", 1); // 这样创建的实体系统无法管理
-```
-
-## 添加组件
-
-实体通过添加组件来获得功能：
-
-```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 = 100;
-  max: number = 100;
-
-  constructor(max: number = 100) {
-    super();
-    this.max = max;
-    this.current = max;
-  }
-}
-
-// 给实体添加组件
-const player = scene.createEntity("Player");
-player.addComponent(new Position(100, 200));
-player.addComponent(new Health(150));
-```
-
-## 获取组件
-
-```typescript
-// 获取组件（传入组件类，不是实例）
-const position = player.getComponent(Position);  // 返回 Position | null
-const health = player.getComponent(Health);      // 返回 Health | null
-
-// 检查组件是否存在
-if (position) {
-  console.log(`玩家位置: x=${position.x}, y=${position.y}`);
-}
-
-// 检查是否有某个组件
-if (player.hasComponent(Position)) {
-  console.log("玩家有位置组件");
-}
-
-// 获取所有组件实例（只读属性）
-const allComponents = player.components;  // readonly Component[]
-
-// 获取指定类型的所有组件（支持同类型多组件）
-const allHealthComponents = player.getComponents(Health);  // Health[]
-
-// 获取或创建组件（如果不存在则自动创建）
-const position = player.getOrCreateComponent(Position, 0, 0);  // 传入构造参数
-const health = player.getOrCreateComponent(Health, 100);       // 如果存在则返回现有的，不存在则创建新的
-```
-
-## 移除组件
-
-```typescript
-// 方式1：通过组件类型移除
-const removedHealth = player.removeComponentByType(Health);
-if (removedHealth) {
-  console.log("健康组件已被移除");
-}
-
-// 方式2：通过组件实例移除
-const healthComponent = player.getComponent(Health);
-if (healthComponent) {
-  player.removeComponent(healthComponent);
-}
-
-// 批量移除多种组件类型
-const removedComponents = player.removeComponentsByTypes([Position, Health]);
-
-// 检查组件是否被移除
-if (!player.hasComponent(Health)) {
-  console.log("健康组件已被移除");
-}
-```
-
-## 实体查找
-
-场景提供了多种方式来查找实体：
-
-### 通过名称查找
-
-```typescript
-// 查找单个实体
-const player = scene.findEntity("Player");
-// 或使用别名方法
-const player2 = scene.getEntityByName("Player");
-
-if (player) {
-  console.log("找到玩家实体");
-}
-```
-
-### 通过 ID 查找
-
-```typescript
-// 通过实体 ID 查找
-const entity = scene.findEntityById(123);
-```
-
-### 通过标签查找
-
-实体支持标签系统，用于快速分类和查找：
-
-```typescript
-// 设置标签
-player.tag = 1; // 玩家标签
-enemy.tag = 2;  // 敌人标签
-
-// 通过标签查找所有相关实体
-const players = scene.findEntitiesByTag(1);
-const enemies = scene.findEntitiesByTag(2);
-// 或使用别名方法
-const allPlayers = scene.getEntitiesByTag(1);
-```
-
-
-## 实体生命周期
-
-```typescript
-// 销毁实体
-player.destroy();
-
-// 检查实体是否已销毁
-if (player.isDestroyed) {
-  console.log("实体已被销毁");
-}
-```
-
-## 实体事件
-
-实体的组件变化会触发事件：
-
-```typescript
-// 监听组件添加事件
-scene.eventSystem.on('component:added', (data) => {
-  console.log('组件已添加:', data);
-});
-
-// 监听实体创建事件
-scene.eventSystem.on('entity:created', (data) => {
-  console.log('实体已创建:', data.entityName);
-});
-```
-
-## 性能优化
-
-
-### 批量创建实体
-
-框架提供了高性能的批量创建方法：
-
-```typescript
-// 批量创建 100 个子弹实体（高性能版本）
-const bullets = scene.createEntities(100, "Bullet");
-
-// 为每个子弹添加组件
-bullets.forEach((bullet, index) => {
-  bullet.addComponent(new Position(Math.random() * 800, Math.random() * 600));
-  bullet.addComponent(new Velocity(Math.random() * 100 - 50, Math.random() * 100 - 50));
-});
-```
-
-`createEntities()` 方法会：
-- 批量分配实体 ID
-- 批量添加到实体列表
-- 优化查询系统更新
-- 减少系统缓存清理次数
-
-## 最佳实践
-
-### 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('Player')
-class Player extends Component {
-  // 避免在一个组件中包含太多不相关的属性
-  x: number;
-  y: number;
-  health: number;
-  inventory: Item[];
-  skills: Skill[];
-}
-```
-
-### 2. 使用装饰器
-
-始终使用 `@ECSComponent` 装饰器：
-
-```typescript
-@ECSComponent('Transform')
-class Transform extends Component {
-  // 组件实现
-}
-```
-
-### 3. 合理命名
-
-```typescript
-// 清晰的实体命名
-const mainCharacter = scene.createEntity("MainCharacter");
-const enemy1 = scene.createEntity("Goblin_001");
-const collectible = scene.createEntity("HealthPotion");
-```
-
-### 4. 及时清理
-
-```typescript
-// 不再需要的实体应该及时销毁
-if (enemy.getComponent(Health).current <= 0) {
-  enemy.destroy();
-}
-```
-
-## 调试实体
-
-框架提供了调试功能来帮助开发：
-
-```typescript
-// 获取实体调试信息
-const debugInfo = entity.getDebugInfo();
-console.log('实体信息:', debugInfo);
-
-// 列出实体的所有组件
-entity.components.forEach(component => {
-  console.log('组件:', component.constructor.name);
-});
-```
-
-实体是 ECS 架构的核心概念之一，理解如何正确使用实体将帮助你构建高效、可维护的游戏代码。

docs/guide/platform-adapter/wechat-minigame.md

@@ -1,677 +0,0 @@
-# 微信小游戏适配器
-
-## 概述
-
-微信小游戏平台适配器专为微信小游戏环境设计，处理微信小游戏的特殊限制和API。
-
-## 特性支持
-
-- ✅ **Worker**: 支持（通过 `wx.createWorker` 创建，需要配置 game.json）
-- ❌ **SharedArrayBuffer**: 不支持
-- ❌ **Transferable Objects**: 不支持（只支持可序列化对象）
-- ✅ **高精度时间**: 使用 `Date.now()` 或 `wx.getPerformance()`
-- ✅ **设备信息**: 完整的微信小游戏设备信息
-
-## 完整实现
-
-```typescript
-import type {
-    IPlatformAdapter,
-    PlatformWorker,
-    WorkerCreationOptions,
-    PlatformConfig,
-    WeChatDeviceInfo
-} from '@esengine/ecs-framework';
-
-/**
- * 微信小游戏平台适配器
- * 支持微信小游戏环境
- */
-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.version || 'unknown';
-    }
-
-    /**
-     * 检查是否支持Worker
-     */
-    public isWorkerSupported(): boolean {
-        // 微信小游戏支持Worker，通过wx.createWorker创建
-        return typeof wx !== 'undefined' && typeof wx.createWorker === 'function';
-    }
-
-    /**
-     * 检查是否支持SharedArrayBuffer（不支持）
-     */
-    public isSharedArrayBufferSupported(): boolean {
-        return false; // 微信小游戏不支持SharedArrayBuffer
-    }
-
-    /**
-     * 获取硬件并发数
-     */
-    public getHardwareConcurrency(): number {
-        // 微信小游戏官方限制：最多只能创建 1 个 Worker
-        return 1;
-    }
-
-    /**
-     * 创建Worker
-     * @param script 脚本内容或文件路径
-     * @param options Worker创建选项
-     */
-    public createWorker(script: string, options: WorkerCreationOptions = {}): PlatformWorker {
-        if (!this.isWorkerSupported()) {
-            throw new Error('微信小游戏不支持Worker');
-        }
-
-        try {
-            return new WeChatWorker(script, options);
-        } catch (error) {
-            throw new Error(`创建微信Worker失败: ${(error as Error).message}`);
-        }
-    }
-
-    /**
-     * 创建SharedArrayBuffer（不支持）
-     */
-    public createSharedArrayBuffer(length: number): SharedArrayBuffer | null {
-        return null; // 微信小游戏不支持SharedArrayBuffer
-    }
-
-    /**
-     * 获取高精度时间戳
-     */
-    public getHighResTimestamp(): number {
-        // 尝试使用微信的性能API，否则使用Date.now()
-        if (typeof wx !== 'undefined' && wx.getPerformance) {
-            const performance = wx.getPerformance();
-            return performance.now();
-        }
-        return Date.now();
-    }
-
-    /**
-     * 获取平台配置
-     */
-    public getPlatformConfig(): PlatformConfig {
-        return {
-            maxWorkerCount: 1, // 微信小游戏最多支持 1 个 Worker
-            supportsModuleWorker: false, // 不支持模块Worker
-            supportsTransferableObjects: this.checkTransferableObjectsSupport(),
-            maxSharedArrayBufferSize: 0,
-            workerScriptPrefix: '',
-            limitations: {
-                noEval: true, // 微信小游戏限制eval使用
-                requiresWorkerInit: false,
-                memoryLimit: this.getMemoryLimit(),
-                workerNotSupported: false,
-                workerLimitations: [
-                    '最多只能创建 1 个 Worker',
-                    '创建新Worker前必须先调用 Worker.terminate()',
-                    'Worker脚本必须为项目内相对路径',
-                    '需要在 game.json 中配置 workers 路径',
-                    '使用 worker.onMessage() 而不是 self.onmessage',
-                    '需要基础库 1.9.90 及以上版本'
-                ]
-            },
-            extensions: {
-                platform: 'wechat-minigame',
-                systemInfo: this.systemInfo,
-                appId: this.systemInfo.host?.appId || 'unknown'
-            }
-        };
-    }
-
-    /**
-     * 获取微信小游戏设备信息
-     */
-    public getDeviceInfo(): WeChatDeviceInfo {
-        return {
-            // 设备基础信息
-            brand: this.systemInfo.brand,
-            model: this.systemInfo.model,
-            platform: this.systemInfo.platform,
-            system: this.systemInfo.system,
-            benchmarkLevel: this.systemInfo.benchmarkLevel,
-            cpuType: this.systemInfo.cpuType,
-            memorySize: this.systemInfo.memorySize,
-            deviceAbi: this.systemInfo.deviceAbi,
-            abi: this.systemInfo.abi,
-
-            // 窗口信息
-            screenWidth: this.systemInfo.screenWidth,
-            screenHeight: this.systemInfo.screenHeight,
-            screenTop: this.systemInfo.screenTop,
-            windowWidth: this.systemInfo.windowWidth,
-            windowHeight: this.systemInfo.windowHeight,
-            pixelRatio: this.systemInfo.pixelRatio,
-            statusBarHeight: this.systemInfo.statusBarHeight,
-            safeArea: this.systemInfo.safeArea,
-
-            // 应用信息
-            version: this.systemInfo.version,
-            language: this.systemInfo.language,
-            theme: this.systemInfo.theme,
-            SDKVersion: this.systemInfo.SDKVersion,
-            enableDebug: this.systemInfo.enableDebug,
-            fontSizeSetting: this.systemInfo.fontSizeSetting,
-            host: this.systemInfo.host
-        };
-    }
-
-    /**
-     * 异步获取完整的平台配置
-     */
-    public async getPlatformConfigAsync(): Promise<PlatformConfig> {
-        // 可以在这里添加异步获取设备性能信息的逻辑
-        const baseConfig = this.getPlatformConfig();
-
-        // 尝试获取设备性能信息
-        try {
-            const benchmarkLevel = await this.getBenchmarkLevel();
-            baseConfig.extensions = {
-                ...baseConfig.extensions,
-                benchmarkLevel
-            };
-        } catch (error) {
-            console.warn('获取性能基准失败:', error);
-        }
-
-        return baseConfig;
-    }
-
-    /**
-     * 检查是否支持Transferable Objects
-     */
-    private checkTransferableObjectsSupport(): boolean {
-        // 微信小游戏不支持 Transferable Objects
-        // 基础库 2.20.2 之前只支持可序列化的 key-value 对象
-        // 2.20.2 之后支持任意类型数据，但仍然不支持 Transferable Objects
-        return false;
-    }
-
-    /**
-     * 获取系统信息
-     */
-    private getSystemInfo(): any {
-        if (typeof wx !== 'undefined' && wx.getSystemInfoSync) {
-            try {
-                return wx.getSystemInfoSync();
-            } catch (error) {
-                console.warn('获取微信系统信息失败:', error);
-                return {};
-            }
-        }
-        return {};
-    }
-
-    /**
-     * 获取内存限制
-     */
-    private getMemoryLimit(): number {
-        // 微信小游戏通常有内存限制
-        const memorySize = this.systemInfo.memorySize;
-        if (memorySize) {
-            // 解析内存大小字符串（如 "4GB"）
-            const match = memorySize.match(/(\d+)([GM]B)?/i);
-            if (match) {
-                const value = parseInt(match[1], 10);
-                const unit = match[2]?.toUpperCase();
-
-                if (unit === 'GB') {
-                    return value * 1024 * 1024 * 1024;
-                } else if (unit === 'MB') {
-                    return value * 1024 * 1024;
-                }
-            }
-        }
-
-        // 默认限制为512MB
-        return 512 * 1024 * 1024;
-    }
-
-    /**
-     * 异步获取设备性能基准
-     */
-    private async getBenchmarkLevel(): Promise<number> {
-        return new Promise((resolve) => {
-            if (typeof wx !== 'undefined' && wx.getDeviceInfo) {
-                wx.getDeviceInfo({
-                    success: (res: any) => {
-                        resolve(res.benchmarkLevel || 0);
-                    },
-                    fail: () => {
-                        resolve(0);
-                    }
-                });
-            } else {
-                resolve(this.systemInfo.benchmarkLevel || 0);
-            }
-        });
-    }
-}
-
-/**
- * 微信Worker封装
- */
-class WeChatWorker implements PlatformWorker {
-    private _state: 'running' | 'terminated' = 'running';
-    private worker: any;
-    private scriptPath: string;
-    private isTemporaryFile: boolean = false;
-
-    constructor(script: string, options: WorkerCreationOptions = {}) {
-        if (typeof wx === 'undefined' || typeof wx.createWorker !== 'function') {
-            throw new Error('微信小游戏不支持Worker');
-        }
-
-        try {
-            // 判断 script 是文件路径还是脚本内容
-            if (this.isFilePath(script)) {
-                // 直接使用文件路径
-                this.scriptPath = script;
-                this.isTemporaryFile = false;
-                this.worker = wx.createWorker(this.scriptPath, {
-                    useExperimentalWorker: true // 启用实验性Worker获得更好性能
-                });
-            } else {
-                // 微信小游戏不支持动态脚本内容，只能使用文件路径
-                // 将脚本内容写入文件系统
-                this.scriptPath = this.writeScriptToFile(script, options.name);
-                this.isTemporaryFile = true;
-                this.worker = wx.createWorker(this.scriptPath, {
-                    useExperimentalWorker: true
-                });
-            }
-        } catch (error) {
-            throw new Error(`创建微信Worker失败: ${(error as Error).message}`);
-        }
-    }
-
-    /**
-     * 判断是否为文件路径
-     */
-    private isFilePath(script: string): boolean {
-        // 简单判断：如果包含 .js 后缀且不包含换行符或分号，认为是文件路径
-        return script.endsWith('.js') &&
-               !script.includes('\n') &&
-               !script.includes(';') &&
-               script.length < 200; // 文件路径通常不会太长
-    }
-
-    /**
-     * 将脚本内容写入文件系统
-     * 注意：微信小游戏不支持blob URL，只能使用文件系统
-     */
-    private writeScriptToFile(script: string, name?: string): string {
-        const fs = wx.getFileSystemManager();
-        const fileName = name ? `worker-${name}.js` : `worker-${Date.now()}.js`;
-        const filePath = `${wx.env.USER_DATA_PATH}/${fileName}`;
-
-        try {
-            fs.writeFileSync(filePath, script, 'utf8');
-            return filePath;
-        } catch (error) {
-            throw new Error(`写入Worker脚本文件失败: ${(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已被终止');
-        }
-
-        try {
-            // 微信小游戏 Worker 只支持可序列化对象，忽略 transfer 参数
-            this.worker.postMessage(message);
-        } catch (error) {
-            throw new Error(`发送消息到微信Worker失败: ${(error as Error).message}`);
-        }
-    }
-
-    public onMessage(handler: (event: { data: any }) => void): void {
-        // 微信小游戏使用 onMessage 方法，不是 onmessage 属性
-        this.worker.onMessage((res: any) => {
-            handler({ data: res });
-        });
-    }
-
-    public onError(handler: (error: ErrorEvent) => void): void {
-        // 注意：微信小游戏 Worker 的错误处理可能与标准不同
-        if (this.worker.onError) {
-            this.worker.onError(handler);
-        }
-    }
-
-    public terminate(): void {
-        if (this._state === 'running') {
-            try {
-                this.worker.terminate();
-                this._state = 'terminated';
-
-                // 清理临时脚本文件
-                this.cleanupScriptFile();
-            } catch (error) {
-                console.error('终止微信Worker失败:', error);
-            }
-        }
-    }
-
-    /**
-     * 清理临时脚本文件
-     */
-    private cleanupScriptFile(): void {
-        // 只清理临时创建的文件，不清理用户提供的文件路径
-        if (this.scriptPath && this.isTemporaryFile) {
-            try {
-                const fs = wx.getFileSystemManager();
-                fs.unlinkSync(this.scriptPath);
-            } catch (error) {
-                console.warn('清理Worker脚本文件失败:', error);
-            }
-        }
-    }
-}
-```
-
-## 使用方法
-
-### 1. 复制代码
-
-将上述代码复制到你的项目中，例如 `src/platform/WeChatMiniGameAdapter.ts`。
-
-### 2. 注册适配器
-
-```typescript
-import { PlatformManager } from '@esengine/ecs-framework';
-import { WeChatMiniGameAdapter } from './platform/WeChatMiniGameAdapter';
-
-// 检查是否在微信小游戏环境
-if (typeof wx !== 'undefined') {
-    const wechatAdapter = new WeChatMiniGameAdapter();
-    PlatformManager.getInstance().registerAdapter(wechatAdapter);
-}
-```
-
-### 3. WorkerEntitySystem 使用方式
-
-微信小游戏适配器与 WorkerEntitySystem 配合使用，自动处理 Worker 脚本创建：
-
-#### 基本使用方式（推荐）
-
-```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<PhysicsData> {
-    constructor() {
-        super(Matcher.all(Transform, Velocity), {
-            enableWorker: true,
-            workerCount: 1, // 微信小游戏限制只能创建1个Worker
-            systemConfig: { gravity: 100, friction: 0.95 }
-        });
-    }
-
-    protected getDefaultEntityDataSize(): number {
-        return 6; // id, x, y, vx, vy, mass
-    }
-
-    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
-        };
-    }
-
-    // WorkerEntitySystem 会自动将此函数序列化并写入临时文件
-    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;
-    }
-}
-```
-
-#### 使用预先创建的 Worker 文件（可选）
-
-如果你希望使用预先创建的 Worker 文件：
-
-```typescript
-// 1. 在 game.json 中配置 Worker 路径
-/*
-{
-  "workers": "workers"
-}
-*/
-
-// 2. 创建 workers/physics.js 文件
-// workers/physics.js 内容：
-/*
-// 微信小游戏 Worker 使用标准的 self.onmessage
-self.onmessage = function(e) {
-    const { type, id, entities, deltaTime, systemConfig } = e.data;
-
-    if (entities) {
-        // 处理物理计算
-        const results = entities.map(entity => {
-            entity.vy += systemConfig.gravity * deltaTime;
-            entity.x += entity.vx * deltaTime;
-            entity.y += entity.vy * deltaTime;
-            return entity;
-        });
-
-        self.postMessage({ id, result: results });
-    }
-};
-*/
-
-// 3. 通过平台适配器直接创建（不推荐，WorkerEntitySystem会自动处理）
-const adapter = PlatformManager.getInstance().getAdapter();
-const worker = adapter.createWorker('workers/physics.js');
-```
-
-### 4. 获取设备信息
-
-```typescript
-const manager = PlatformManager.getInstance();
-if (manager.hasAdapter()) {
-    const adapter = manager.getAdapter();
-    console.log('微信设备信息:', adapter.getDeviceInfo());
-}
-```
-
-## 官方文档参考
-
-在使用微信小游戏 Worker 之前，建议先阅读官方文档：
-
-- [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)
-- [Worker.terminate API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.terminate.html)
-
-## 重要注意事项
-
-### Worker 限制和配置
-
-微信小游戏的 Worker 有以下限制：
-
-- **数量限制**: 最多只能创建 1 个 Worker
-- **版本要求**: 需要基础库 1.9.90 及以上版本
-- **脚本支持**: 不支持 blob URL，只能使用文件路径或写入文件系统
-- **文件路径**: Worker 脚本路径必须为绝对路径，但不能以 "/" 开头
-- **生命周期**: 创建新 Worker 前必须先调用 `Worker.terminate()` 终止当前 Worker
-- **消息处理**: Worker 内使用标准的 `self.onmessage`，主线程使用 `worker.onMessage()`
-- **实验性功能**: 支持 `useExperimentalWorker` 选项获得更好的 iOS 性能
-
-#### Worker 配置（可选）
-
-如果使用预先创建的 Worker 文件，需要在 `game.json` 中添加 workers 配置：
-
-```json
-{
-  "deviceOrientation": "portrait",
-  "showStatusBar": false,
-  "workers": "workers",
-  "subpackages": []
-}
-```
-
-**注意**: 使用 WorkerEntitySystem 时无需此配置，框架会自动将脚本写入临时文件。
-
-### 内存限制
-
-微信小游戏有严格的内存限制：
-
-- 通常限制在 256MB - 512MB
-- 需要及时释放不用的资源
-- 避免内存泄漏
-
-### API 限制
-
-- 不支持 `eval()` 函数
-- 不支持 `Function` 构造器
-- DOM API 受限
-- 文件系统 API 受限
-
-## 性能优化建议
-
-### 1. 分帧处理
-
-```typescript
-class FramedProcessor {
-    private tasks: (() => void)[] = [];
-    private isProcessing = false;
-
-    public addTask(task: () => void): void {
-        this.tasks.push(task);
-        if (!this.isProcessing) {
-            this.processNextFrame();
-        }
-    }
-
-    private processNextFrame(): void {
-        this.isProcessing = true;
-        const startTime = Date.now();
-        const frameTime = 16; // 16ms per frame
-
-        while (this.tasks.length > 0 && Date.now() - startTime < frameTime) {
-            const task = this.tasks.shift();
-            if (task) task();
-        }
-
-        if (this.tasks.length > 0) {
-            setTimeout(() => this.processNextFrame(), 0);
-        } else {
-            this.isProcessing = false;
-        }
-    }
-}
-```
-
-### 2. 内存管理
-
-```typescript
-class MemoryManager {
-    private static readonly MAX_MEMORY = 256 * 1024 * 1024; // 256MB
-
-    public static checkMemoryUsage(): void {
-        if (typeof wx !== 'undefined' && wx.getPerformance) {
-            const performance = wx.getPerformance();
-            const memoryInfo = performance.getEntries().find(
-                (entry: any) => entry.entryType === 'memory'
-            );
-
-            if (memoryInfo && memoryInfo.usedJSHeapSize > this.MAX_MEMORY * 0.8) {
-                console.warn('内存使用率过高，建议清理资源');
-                // 触发垃圾回收或资源清理
-            }
-        }
-    }
-}
-```
-
-## 调试技巧
-
-```typescript
-// 检查微信小游戏环境
-if (typeof wx !== 'undefined') {
-    const adapter = new WeChatMiniGameAdapter();
-
-    console.log('微信版本:', adapter.version);
-    console.log('设备信息:', adapter.getDeviceInfo());
-    console.log('平台配置:', adapter.getPlatformConfig());
-
-    // 检查功能支持
-    console.log('Worker支持:', adapter.isWorkerSupported());
-    console.log('SharedArrayBuffer支持:', adapter.isSharedArrayBufferSupported());
-}
-```
-
-## 微信小游戏特殊API
-
-```typescript
-// 获取设备性能等级
-if (typeof wx !== 'undefined' && wx.getDeviceInfo) {
-    wx.getDeviceInfo({
-        success: (res) => {
-            console.log('设备性能等级:', res.benchmarkLevel);
-        }
-    });
-}
-
-// 监听内存警告
-if (typeof wx !== 'undefined' && wx.onMemoryWarning) {
-    wx.onMemoryWarning(() => {
-        console.warn('收到内存警告，开始清理资源');
-        // 清理不必要的资源
-    });
-}
-```

docs/guide/plugin-system.md

@@ -1,643 +0,0 @@
-# 插件系统
-
-插件系统允许你以模块化的方式扩展 ECS Framework 的功能。通过插件，你可以封装特定功能（如网络同步、物理引擎、调试工具等），并在多个项目中复用。
-
-## 概述
-
-### 什么是插件
-
-插件是实现了 `IPlugin` 接口的类，可以在运行时动态安装到框架中。插件可以：
-
-- 注册自定义服务到服务容器
-- 添加系统到场景
-- 注册自定义组件
-- 扩展框架功能
-
-### 插件的优势
-
-- **模块化**: 将功能封装为独立模块，提高代码可维护性
-- **可复用**: 同一个插件可以在多个项目中使用
-- **解耦**: 核心框架与扩展功能分离
-- **热插拔**: 运行时动态安装和卸载插件
-
-## 快速开始
-
-### 创建第一个插件
-
-创建一个简单的调试插件：
-
-```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');
-
-        // 可以在这里注册服务、添加系统等
-    }
-
-    uninstall(): void {
-        console.log('Debug plugin uninstalled');
-        // 清理资源
-    }
-}
-```
-
-### 安装插件
-
-使用 `Core.installPlugin()` 安装插件：
-
-```typescript
-import { Core } from '@esengine/ecs-framework';
-
-// 初始化Core
-Core.create({ debug: true });
-
-// 安装插件
-await Core.installPlugin(new DebugPlugin());
-
-// 检查插件是否已安装
-if (Core.isPluginInstalled('debug-plugin')) {
-    console.log('Debug plugin is running');
-}
-```
-
-### 卸载插件
-
-```typescript
-// 卸载插件
-await Core.uninstallPlugin('debug-plugin');
-```
-
-### 获取插件实例
-
-```typescript
-// 获取已安装的插件
-const plugin = Core.getPlugin('debug-plugin');
-if (plugin) {
-    console.log(`Plugin version: ${plugin.version}`);
-}
-```
-
-## 插件开发
-
-### IPlugin 接口
-
-所有插件必须实现 `IPlugin` 接口：
-
-```typescript
-export interface IPlugin {
-    // 插件唯一名称
-    readonly name: string;
-
-    // 插件版本（建议遵循semver规范）
-    readonly version: string;
-
-    // 依赖的其他插件（可选）
-    readonly dependencies?: readonly string[];
-
-    // 安装插件时调用
-    install(core: Core, services: ServiceContainer): void | Promise<void>;
-
-    // 卸载插件时调用
-    uninstall(): void | Promise<void>;
-}
-```
-
-### 插件生命周期
-
-#### install 方法
-
-在插件安装时调用，用于初始化插件：
-
-```typescript
-class MyPlugin implements IPlugin {
-    readonly name = 'my-plugin';
-    readonly version = '1.0.0';
-
-    install(core: Core, services: ServiceContainer): void {
-        // 1. 注册服务
-        services.registerSingleton(MyService);
-
-        // 2. 访问当前场景
-        const scene = core.scene;
-        if (scene) {
-            // 3. 添加系统
-            scene.addSystem(new MySystem());
-        }
-
-        // 4. 其他初始化逻辑
-        console.log('Plugin initialized');
-    }
-
-    uninstall(): void {
-        // 清理逻辑
-    }
-}
-```
-
-#### uninstall 方法
-
-在插件卸载时调用，用于清理资源：
-
-```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 {
-        // 清理服务
-        if (this.myService) {
-            this.myService.dispose();
-            this.myService = undefined;
-        }
-
-        // 移除事件监听器
-        // 释放其他资源
-    }
-}
-```
-
-### 异步插件
-
-插件的 `install` 和 `uninstall` 方法都支持异步：
-
-```typescript
-class AsyncPlugin implements IPlugin {
-    readonly name = 'async-plugin';
-    readonly version = '1.0.0';
-
-    async install(core: Core, services: ServiceContainer): Promise<void> {
-        // 异步加载资源
-        const config = await fetch('/plugin-config.json').then(r => r.json());
-
-        // 使用加载的配置初始化服务
-        const service = new MyService(config);
-        services.registerInstance(MyService, service);
-    }
-
-    async uninstall(): Promise<void> {
-        // 异步清理
-        await this.saveState();
-    }
-
-    private async saveState() {
-        // 保存插件状态
-    }
-}
-
-// 使用
-await Core.installPlugin(new AsyncPlugin());
-```
-
-### 注册服务
-
-插件可以向服务容器注册自己的服务：
-
-```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 {
-        // 注册网络服务
-        services.registerSingleton(NetworkService);
-
-        // 解析并使用服务
-        const network = services.resolve(NetworkService);
-        network.connect('ws://localhost:8080');
-    }
-
-    uninstall(): void {
-        // 服务容器会自动调用服务的dispose方法
-    }
-}
-```
-
-### 添加系统
-
-插件可以向场景添加自定义系统：
-
-```typescript
-import { EntitySystem, Matcher } from '@esengine/ecs-framework';
-
-class PhysicsSystem extends EntitySystem {
-    constructor() {
-        super(Matcher.empty().all(PhysicsBody));
-    }
-
-    protected process(entities: readonly Entity[]): void {
-        // 物理模拟逻辑
-    }
-}
-
-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 {
-        // 移除系统
-        if (this.physicsSystem) {
-            const scene = Core.scene;
-            if (scene) {
-                scene.removeSystem(this.physicsSystem);
-            }
-            this.physicsSystem = undefined;
-        }
-    }
-}
-```
-
-## 依赖管理
-
-### 声明依赖
-
-插件可以声明对其他插件的依赖：
-
-```typescript
-class AdvancedPhysicsPlugin implements IPlugin {
-    readonly name = 'advanced-physics';
-    readonly version = '2.0.0';
-
-    // 声明依赖基础物理插件
-    readonly dependencies = ['physics-plugin'] as const;
-
-    install(core: Core, services: ServiceContainer): void {
-        // 可以安全地使用physics-plugin提供的服务
-        const physicsService = services.resolve(PhysicsService);
-        // ...
-    }
-
-    uninstall(): void {
-        // 清理
-    }
-}
-```
-
-### 依赖检查
-
-框架会自动检查依赖关系，如果依赖未满足会抛出错误：
-
-```typescript
-// 错误：physics-plugin 未安装
-try {
-    await Core.installPlugin(new AdvancedPhysicsPlugin());
-} catch (error) {
-    console.error(error); // Plugin advanced-physics has unmet dependencies: physics-plugin
-}
-
-// 正确：先安装依赖
-await Core.installPlugin(new PhysicsPlugin());
-await Core.installPlugin(new AdvancedPhysicsPlugin());
-```
-
-### 卸载顺序
-
-框架会检查依赖关系，防止卸载被其他插件依赖的插件：
-
-```typescript
-await Core.installPlugin(new PhysicsPlugin());
-await Core.installPlugin(new AdvancedPhysicsPlugin());
-
-// 错误：physics-plugin 被 advanced-physics 依赖
-try {
-    await Core.uninstallPlugin('physics-plugin');
-} catch (error) {
-    console.error(error); // Cannot uninstall plugin physics-plugin: it is required by advanced-physics
-}
-
-// 正确：先卸载依赖它的插件
-await Core.uninstallPlugin('advanced-physics');
-await Core.uninstallPlugin('physics-plugin');
-```
-
-## 插件管理
-
-### 通过 Core 管理
-
-Core 类提供了便捷的插件管理方法：
-
-```typescript
-// 安装插件
-await Core.installPlugin(myPlugin);
-
-// 卸载插件
-await Core.uninstallPlugin('plugin-name');
-
-// 检查插件是否已安装
-if (Core.isPluginInstalled('plugin-name')) {
-    // ...
-}
-
-// 获取插件实例
-const plugin = Core.getPlugin('plugin-name');
-```
-
-### 通过 PluginManager 管理
-
-也可以直接使用 PluginManager 服务：
-
-```typescript
-const pluginManager = Core.services.resolve(PluginManager);
-
-// 获取所有插件
-const allPlugins = pluginManager.getAllPlugins();
-console.log(`Total plugins: ${allPlugins.length}`);
-
-// 获取插件元数据
-const metadata = pluginManager.getMetadata('my-plugin');
-if (metadata) {
-    console.log(`State: ${metadata.state}`);
-    console.log(`Installed at: ${new Date(metadata.installedAt!)}`);
-}
-
-// 获取所有插件元数据
-const allMetadata = pluginManager.getAllMetadata();
-for (const meta of allMetadata) {
-    console.log(`${meta.name} v${meta.version} - ${meta.state}`);
-}
-```
-
-## 实用插件示例
-
-### 网络同步插件
-
-```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) {
-        // 处理网络消息
-    }
-
-    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 {
-        // 注册网络服务
-        services.registerSingleton(NetworkSyncService);
-
-        // 自动连接
-        const network = services.resolve(NetworkSyncService);
-        network.connect('ws://localhost:8080');
-    }
-
-    uninstall(): void {
-        // 服务会自动dispose
-    }
-}
-```
-
-### 性能分析插件
-
-```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();
-
-        // 定期输出性能报告
-        const timer = services.resolve(TimerManager);
-        timer.schedule(5.0, true, null, () => {
-            this.printReport(monitor);
-        });
-    }
-
-    uninstall(): void {
-        // 清理
-    }
-
-    private printReport(monitor: PerformanceMonitor) {
-        console.log('=== Performance Report ===');
-        console.log(`FPS: ${monitor.getFPS()}`);
-        console.log(`Memory: ${monitor.getMemoryUsage()} MB`);
-    }
-}
-```
-
-## 最佳实践
-
-### 命名规范
-
-- 插件名称使用小写字母和连字符：`my-awesome-plugin`
-- 版本号遵循语义化版本规范：`1.0.0`
-
-```typescript
-class MyPlugin implements IPlugin {
-    readonly name = 'my-awesome-plugin';  // 好
-    readonly version = '1.0.0';           // 好
-}
-```
-
-### 清理资源
-
-始终在 `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 {
-        // 添加定时器
-        this.timerId = setInterval(() => {
-            // ...
-        }, 1000);
-
-        // 添加事件监听
-        this.listener = () => {};
-        window.addEventListener('resize', this.listener);
-    }
-
-    uninstall(): void {
-        // 清理定时器
-        if (this.timerId) {
-            clearInterval(this.timerId);
-            this.timerId = undefined;
-        }
-
-        // 移除事件监听
-        if (this.listener) {
-            window.removeEventListener('resize', this.listener);
-            this.listener = undefined;
-        }
-    }
-}
-```
-
-### 错误处理
-
-在插件中妥善处理错误，避免影响整个应用：
-
-```typescript
-class MyPlugin implements IPlugin {
-    readonly name = 'my-plugin';
-    readonly version = '1.0.0';
-
-    async install(core: Core, services: ServiceContainer): Promise<void> {
-        try {
-            // 可能失败的操作
-            await this.loadConfig();
-        } catch (error) {
-            console.error('Failed to load plugin config:', error);
-            throw error; // 重新抛出，让框架知道安装失败
-        }
-    }
-
-    async uninstall(): Promise<void> {
-        try {
-            await this.cleanup();
-        } catch (error) {
-            console.error('Failed to cleanup plugin:', error);
-            // 即使清理失败也不应该阻止卸载
-        }
-    }
-
-    private async loadConfig() {
-        // 加载配置
-    }
-
-    private async cleanup() {
-        // 清理
-    }
-}
-```
-
-### 配置化
-
-允许用户配置插件行为：
-
-```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 {
-        // 清理
-    }
-}
-
-// 使用
-const plugin = new NetworkPlugin({
-    serverUrl: 'ws://localhost:8080',
-    autoReconnect: true,
-    timeout: 5000
-});
-
-await Core.installPlugin(plugin);
-```
-
-## 常见问题
-
-### 插件安装失败
-
-**问题**: 插件安装时抛出错误
-
-**原因**:
-- 依赖未满足
-- install 方法中有异常
-- 服务注册冲突
-
-**解决**:
-1. 检查依赖是否已安装
-2. 查看错误日志
-3. 确保服务名称不冲突
-
-### 插件卸载后仍有副作用
-
-**问题**: 卸载插件后，插件的功能仍在运行
-
-**原因**: uninstall 方法中未正确清理资源
-
-**解决**: 确保在 uninstall 中清理：
-- 定时器
-- 事件监听器
-- WebSocket连接
-- 系统引用
-
-### 何时使用插件
-
-**适合使用插件**:
-- 可选功能（调试工具、性能分析）
-- 第三方集成（网络库、物理引擎）
-- 跨项目复用的功能模块
-
-**不适合使用插件**:
-- 核心游戏逻辑
-- 简单的工具类
-- 项目特定的功能
-
-## 相关链接
-
-- [服务容器](./service-container.md) - 在插件中使用服务容器
-- [系统架构](./system.md) - 在插件中添加系统
-- [快速开始](./getting-started.md) - Core 初始化和基础使用

docs/guide/scene-manager.md

@@ -1,675 +0,0 @@
-# SceneManager
-
-SceneManager 是 ECS Framework 提供的轻量级场景管理器，适用于 95% 的游戏应用。它提供简单直观的 API，支持场景切换和延迟加载。
-
-## 适用场景
-
-SceneManager 适合以下场景：
-- 单人游戏
-- 简单多人游戏
-- 移动游戏
-- 需要场景切换的游戏（菜单、游戏、暂停等）
-- 不需要多 World 隔离的项目
-
-## 特点
-
-- 轻量级，零额外开销
-- 简单直观的 API
-- 支持延迟场景切换（避免在当前帧中途切换）
-- 自动管理 ECS 流式 API
-- 自动处理场景生命周期
-- 集成在 Core 中，自动更新
-
-## 基本使用
-
-### 推荐方式：使用 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<T extends IScene>(scene: T): T
-```
-
-**参数**：
-- `scene` - 要设置的场景实例
-
-**返回**：
-- 返回设置的场景实例
-
-**示例**：
-```typescript
-const gameScene = Core.setScene(new GameScene());
-console.log(gameScene.name);
-```
-
-#### Core.loadScene()
-
-延迟加载场景（下一帧切换）。
-
-```typescript
-public static loadScene<T extends IScene>(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<T extends IScene>(scene: T): T
-```
-
-#### loadScene()
-
-延迟加载场景。
-
-```typescript
-public loadScene<T extends IScene>(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<string, any> = new Map();
-  private sounds: Map<string, any> = 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 的静态方法，你可以轻松地管理场景切换。如果你需要更高级的多世界隔离功能，请参考 [WorldManager](./world-manager.md) 文档。

docs/guide/scene.md

@@ -1,661 +0,0 @@
-# 场景管理
-
-在 ECS 架构中，场景（Scene）是游戏世界的容器，负责管理实体、系统和组件的生命周期。场景提供了完整的 ECS 运行环境。
-
-## 基本概念
-
-场景是 ECS 框架的核心容器，提供：
-- 实体的创建、管理和销毁
-- 系统的注册和执行调度
-- 组件的存储和查询
-- 事件系统支持
-- 性能监控和调试信息
-
-## 场景管理方式
-
-ECS Framework 提供了两种场景管理方式：
-
-1. **[SceneManager](./scene-manager.md)** - 适用于 95% 的游戏应用
-   - 单人游戏、简单多人游戏、移动游戏
-   - 轻量级，简单直观的 API
-   - 支持场景切换
-
-2. **[WorldManager](./world-manager.md)** - 适用于高级多世界隔离场景
-   - MMO 游戏服务器、游戏房间系统
-   - 多 World 管理，每个 World 可包含多个场景
-   - 完全隔离的独立环境
-
-本文档重点介绍 Scene 类本身的使用方法。关于场景管理器的详细信息，请查看对应的文档。
-
-## 创建场景
-
-### 继承 Scene 类
-
-**推荐做法：继承 Scene 类来创建自定义场景**
-
-```typescript
-import { Scene, EntitySystem } from '@esengine/ecs-framework';
-
-class GameScene extends Scene {
-  protected initialize(): void {
-    // 设置场景名称
-    this.name = "GameScene";
-
-    // 添加系统
-    this.addSystem(new MovementSystem());
-    this.addSystem(new RenderSystem());
-    this.addSystem(new PhysicsSystem());
-
-    // 创建初始实体
-    this.createInitialEntities();
-  }
-
-  private createInitialEntities(): void {
-    // 创建玩家
-    const player = this.createEntity("Player");
-    player.addComponent(new Position(400, 300));
-    player.addComponent(new Health(100));
-    player.addComponent(new PlayerController());
-
-    // 创建敌人
-    for (let i = 0; i < 5; i++) {
-      const enemy = this.createEntity(`Enemy_${i}`);
-      enemy.addComponent(new Position(Math.random() * 800, Math.random() * 600));
-      enemy.addComponent(new Health(50));
-      enemy.addComponent(new EnemyAI());
-    }
-  }
-
-  public onStart(): void {
-    console.log("游戏场景已启动");
-    // 场景启动时的逻辑
-  }
-
-  public unload(): void {
-    console.log("游戏场景已卸载");
-    // 场景卸载时的清理逻辑
-  }
-}
-```
-
-### 使用场景配置
-
-```typescript
-import { ISceneConfig } from '@esengine/ecs-framework';
-
-const config: ISceneConfig = {
-  name: "MainGame",
-  enableEntityDirectUpdate: false
-};
-
-class ConfiguredScene extends Scene {
-  constructor() {
-    super(config);
-  }
-}
-```
-
-## 场景生命周期
-
-场景提供了完整的生命周期管理：
-
-```typescript
-class ExampleScene extends Scene {
-  protected initialize(): void {
-    // 场景初始化：设置系统和初始实体
-    console.log("场景初始化");
-  }
-
-  public onStart(): void {
-    // 场景开始运行：游戏逻辑开始执行
-    console.log("场景开始运行");
-  }
-
-  public unload(): void {
-    // 场景卸载：清理资源
-    console.log("场景卸载");
-  }
-}
-
-// 使用场景（由框架自动管理生命周期）
-const scene = new ExampleScene();
-// 场景的 initialize(), begin(), update(), end() 由框架自动调用
-```
-
-**生命周期方法**：
-
-1. `initialize()` - 场景初始化，设置系统和初始实体
-2. `begin()` / `onStart()` - 场景开始运行
-3. `update()` - 每帧更新（由场景管理器调用）
-4. `end()` / `unload()` - 场景卸载，清理资源
-
-## 实体管理
-
-### 创建实体
-
-```typescript
-class EntityScene extends Scene {
-  createGameEntities(): void {
-    // 创建单个实体
-    const player = this.createEntity("Player");
-
-    // 批量创建实体（高性能）
-    const bullets = this.createEntities(100, "Bullet");
-
-    // 为批量创建的实体添加组件
-    bullets.forEach((bullet, index) => {
-      bullet.addComponent(new Position(index * 10, 100));
-      bullet.addComponent(new Velocity(Math.random() * 200 - 100, -300));
-    });
-  }
-}
-```
-
-### 查找实体
-
-```typescript
-class SearchScene extends Scene {
-  findEntities(): void {
-    // 按名称查找
-    const player = this.findEntity("Player");
-    const player2 = this.getEntityByName("Player"); // 别名方法
-
-    // 按 ID 查找
-    const entity = this.findEntityById(123);
-
-    // 按标签查找
-    const enemies = this.findEntitiesByTag(2);
-    const enemies2 = this.getEntitiesByTag(2); // 别名方法
-
-    if (player) {
-      console.log(`找到玩家: ${player.name}`);
-    }
-
-    console.log(`找到 ${enemies.length} 个敌人`);
-  }
-}
-```
-
-### 销毁实体
-
-```typescript
-class DestroyScene extends Scene {
-  cleanupEntities(): void {
-    // 销毁所有实体
-    this.destroyAllEntities();
-
-    // 单个实体的销毁通过实体本身
-    const enemy = this.findEntity("Enemy_1");
-    if (enemy) {
-      enemy.destroy(); // 实体会自动从场景中移除
-    }
-  }
-}
-```
-
-## 系统管理
-
-### 添加和移除系统
-
-```typescript
-class SystemScene extends Scene {
-  protected initialize(): void {
-    // 添加系统
-    const movementSystem = new MovementSystem();
-    this.addSystem(movementSystem);
-
-    // 设置系统更新顺序
-    movementSystem.updateOrder = 1;
-
-    // 添加更多系统
-    this.addSystem(new PhysicsSystem());
-    this.addSystem(new RenderSystem());
-  }
-
-  public removeUnnecessarySystems(): void {
-    // 获取系统
-    const physicsSystem = this.getEntityProcessor(PhysicsSystem);
-
-    // 移除系统
-    if (physicsSystem) {
-      this.removeSystem(physicsSystem);
-    }
-  }
-}
-```
-
-### 系统访问
-
-```typescript
-class SystemAccessScene extends Scene {
-  public pausePhysics(): void {
-    const physicsSystem = this.getEntityProcessor(PhysicsSystem);
-    if (physicsSystem) {
-      physicsSystem.enabled = false;
-    }
-  }
-
-  public getAllSystems(): EntitySystem[] {
-    return this.systems; // 获取所有系统
-  }
-}
-```
-
-## 事件系统
-
-场景内置了类型安全的事件系统：
-
-```typescript
-class EventScene extends Scene {
-  protected initialize(): void {
-    // 监听事件
-    this.eventSystem.on('player_died', this.onPlayerDied.bind(this));
-    this.eventSystem.on('enemy_spawned', this.onEnemySpawned.bind(this));
-    this.eventSystem.on('level_complete', this.onLevelComplete.bind(this));
-  }
-
-  private onPlayerDied(data: any): void {
-    console.log('玩家死亡事件');
-    // 处理玩家死亡
-  }
-
-  private onEnemySpawned(data: any): void {
-    console.log('敌人生成事件');
-    // 处理敌人生成
-  }
-
-  private onLevelComplete(data: any): void {
-    console.log('关卡完成事件');
-    // 处理关卡完成
-  }
-
-  public triggerGameEvent(): void {
-    // 发送事件（同步）
-    this.eventSystem.emitSync('custom_event', {
-      message: "这是自定义事件",
-      timestamp: Date.now()
-    });
-
-    // 发送事件（异步）
-    this.eventSystem.emit('async_event', {
-      data: "异步事件数据"
-    });
-  }
-}
-```
-
-### 事件系统 API
-
-```typescript
-// 监听事件
-this.eventSystem.on('event_name', callback);
-
-// 监听一次（自动取消订阅）
-this.eventSystem.once('event_name', callback);
-
-// 取消监听
-this.eventSystem.off('event_name', callback);
-
-// 同步发送事件
-this.eventSystem.emitSync('event_name', data);
-
-// 异步发送事件
-this.eventSystem.emit('event_name', data);
-
-// 清除所有事件监听
-this.eventSystem.clear();
-```
-
-## 场景统计和调试
-
-### 获取场景统计
-
-```typescript
-class StatsScene extends Scene {
-  public showStats(): void {
-    const stats = this.getStats();
-    console.log(`实体数量: ${stats.entityCount}`);
-    console.log(`系统数量: ${stats.processorCount}`);
-    console.log('组件存储统计:', stats.componentStorageStats);
-  }
-
-  public showDebugInfo(): void {
-    const debugInfo = this.getDebugInfo();
-    console.log('场景调试信息:', debugInfo);
-
-    // 显示所有实体信息
-    debugInfo.entities.forEach(entity => {
-      console.log(`实体 ${entity.name}(${entity.id}): ${entity.componentCount} 个组件`);
-      console.log('组件类型:', entity.componentTypes);
-    });
-
-    // 显示所有系统信息
-    debugInfo.processors.forEach(processor => {
-      console.log(`系统 ${processor.name}: 处理 ${processor.entityCount} 个实体`);
-    });
-  }
-}
-```
-
-## 组件查询
-
-Scene 提供了强大的组件查询系统：
-
-```typescript
-class QueryScene extends Scene {
-  protected initialize(): void {
-    // 创建一些实体
-    for (let i = 0; i < 10; i++) {
-      const entity = this.createEntity(`Entity_${i}`);
-      entity.addComponent(new Transform(i * 10, 0));
-      entity.addComponent(new Velocity(1, 0));
-      if (i % 2 === 0) {
-        entity.addComponent(new Renderer());
-      }
-    }
-  }
-
-  public queryEntities(): void {
-    // 通过 QuerySystem 查询
-    const entities = this.querySystem.query([Transform, Velocity]);
-    console.log(`找到 ${entities.length} 个有 Transform 和 Velocity 的实体`);
-
-    // 使用 ECS 流式 API（如果通过 SceneManager）
-    // const api = sceneManager.api;
-    // const entities = api?.find(Transform, Velocity);
-  }
-}
-```
-
-## 性能监控
-
-Scene 内置了性能监控功能：
-
-```typescript
-class PerformanceScene extends Scene {
-  public showPerformance(): void {
-    // 获取性能数据
-    const perfData = this.performanceMonitor?.getPerformanceData();
-    if (perfData) {
-      console.log('FPS:', perfData.fps);
-      console.log('帧时间:', perfData.frameTime);
-      console.log('实体更新时间:', perfData.entityUpdateTime);
-      console.log('系统更新时间:', perfData.systemUpdateTime);
-    }
-
-    // 获取性能报告
-    const report = this.performanceMonitor?.generateReport();
-    if (report) {
-      console.log('性能报告:', report);
-    }
-  }
-}
-```
-
-## 最佳实践
-
-### 1. 场景职责分离
-
-```typescript
-// 好的场景设计 - 职责清晰
-class MenuScene extends Scene {
-  // 只处理菜单相关逻辑
-}
-
-class GameScene extends Scene {
-  // 只处理游戏玩法逻辑
-}
-
-class InventoryScene extends Scene {
-  // 只处理物品栏逻辑
-}
-
-// 避免的场景设计 - 职责混乱
-class MegaScene extends Scene {
-  // 包含菜单、游戏、物品栏等所有逻辑
-}
-```
-
-### 2. 合理的系统组织
-
-```typescript
-class OrganizedScene extends Scene {
-  protected initialize(): void {
-    // 按功能和依赖关系添加系统
-    this.addInputSystems();
-    this.addLogicSystems();
-    this.addRenderSystems();
-  }
-
-  private addInputSystems(): void {
-    this.addSystem(new InputSystem());
-  }
-
-  private addLogicSystems(): void {
-    this.addSystem(new MovementSystem());
-    this.addSystem(new PhysicsSystem());
-    this.addSystem(new CollisionSystem());
-  }
-
-  private addRenderSystems(): void {
-    this.addSystem(new RenderSystem());
-    this.addSystem(new UISystem());
-  }
-}
-```
-
-### 3. 资源管理
-
-```typescript
-class ResourceScene extends Scene {
-  private textures: Map<string, any> = new Map();
-  private sounds: Map<string, any> = new Map();
-
-  protected initialize(): void {
-    this.loadResources();
-  }
-
-  private loadResources(): void {
-    // 加载场景所需资源
-    this.textures.set('player', this.loadTexture('player.png'));
-    this.sounds.set('bgm', this.loadSound('bgm.mp3'));
-  }
-
-  public unload(): void {
-    // 清理资源
-    this.textures.clear();
-    this.sounds.clear();
-    console.log('场景资源已清理');
-  }
-
-  private loadTexture(path: string): any {
-    // 加载纹理
-    return null;
-  }
-
-  private loadSound(path: string): any {
-    // 加载音效
-    return null;
-  }
-}
-```
-
-### 4. 事件处理规范
-
-```typescript
-class EventHandlingScene extends Scene {
-  protected initialize(): void {
-    // 集中管理事件监听
-    this.setupEventListeners();
-  }
-
-  private setupEventListeners(): void {
-    this.eventSystem.on('game_pause', this.onGamePause.bind(this));
-    this.eventSystem.on('game_resume', this.onGameResume.bind(this));
-    this.eventSystem.on('player_input', this.onPlayerInput.bind(this));
-  }
-
-  private onGamePause(): void {
-    // 暂停游戏逻辑
-    this.systems.forEach(system => {
-      if (system instanceof GameLogicSystem) {
-        system.enabled = false;
-      }
-    });
-  }
-
-  private onGameResume(): void {
-    // 恢复游戏逻辑
-    this.systems.forEach(system => {
-      if (system instanceof GameLogicSystem) {
-        system.enabled = true;
-      }
-    });
-  }
-
-  private onPlayerInput(data: any): void {
-    // 处理玩家输入
-  }
-
-  public unload(): void {
-    // 清理事件监听
-    this.eventSystem.clear();
-  }
-}
-```
-
-### 5. 初始化顺序
-
-```typescript
-class ProperInitScene extends Scene {
-  protected initialize(): void {
-    // 1. 首先设置场景配置
-    this.name = "GameScene";
-
-    // 2. 然后添加系统（按依赖顺序）
-    this.addSystem(new InputSystem());
-    this.addSystem(new MovementSystem());
-    this.addSystem(new PhysicsSystem());
-    this.addSystem(new RenderSystem());
-
-    // 3. 最后创建实体
-    this.createEntities();
-
-    // 4. 设置事件监听
-    this.setupEvents();
-  }
-
-  private createEntities(): void {
-    // 创建实体
-  }
-
-  private setupEvents(): void {
-    // 设置事件监听
-  }
-}
-```
-
-## 完整示例
-
-```typescript
-import { 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 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));
-    }
-
-    // 设置事件监听
-    this.eventSystem.on('player_died', () => {
-      console.log('玩家死亡！');
-    });
-  }
-
-  public onStart(): void {
-    console.log('游戏场景启动');
-  }
-
-  public unload(): void {
-    console.log('游戏场景卸载');
-    this.eventSystem.clear();
-  }
-}
-
-// 使用场景
-// 方式1：通过 SceneManager（推荐）
-import { Core, SceneManager } from '@esengine/ecs-framework';
-
-Core.create({ debug: true });
-const sceneManager = Core.services.resolve(SceneManager);
-sceneManager.setScene(new GameScene());
-
-// 方式2：通过 WorldManager（高级用例）
-import { WorldManager } from '@esengine/ecs-framework';
-
-const worldManager = Core.services.resolve(WorldManager);
-const world = worldManager.createWorld('game');
-world.createScene('main', new GameScene());
-world.setSceneActive('main', true);
-```
-
-## 下一步
-
-- 了解 [SceneManager](./scene-manager.md) - 适用于大多数游戏的简单场景管理
-- 了解 [WorldManager](./world-manager.md) - 适用于需要多世界隔离的高级场景
-
-场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。

docs/guide/serialization.md

@@ -1,823 +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<string, ComponentType>;
-}
-```
-
-### 高级装饰器
-
-#### 字段序列化选项
-
-```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<string, number> = new Map();
-
-  // Set序列化
-  @SerializeAsSet()
-  public acquiredSkills: Set<string> = new Set();
-
-  constructor() {
-    super();
-    this.inventory.set('gold', 100);
-    this.inventory.set('silver', 50);
-    this.acquiredSkills.add('attack');
-    this.acquiredSkills.add('defense');
-  }
-}
-```
-
-### 场景自定义数据
-
-除了实体和组件，还可以序列化场景级别的配置数据：
-
-```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()` - 获取迁移路径
-
-序列化系统是构建完整游戏的重要基础设施，合理使用可以实现强大的功能，如存档系统、网络同步、关卡编辑器等。

docs/guide/service-container.md

@@ -1,589 +0,0 @@
-# 服务容器
-
-服务容器（ServiceContainer）是 ECS Framework 的依赖注入容器，负责管理框架中所有服务的注册、解析和生命周期。通过服务容器，你可以实现松耦合的架构设计，提高代码的可测试性和可维护性。
-
-## 概述
-
-### 什么是服务容器
-
-服务容器是一个轻量级的依赖注入（DI）容器，它提供了：
-
-- **服务注册**: 将服务类型注册到容器中
-- **服务解析**: 从容器中获取服务实例
-- **生命周期管理**: 自动管理服务实例的创建和销毁
-- **依赖注入**: 自动解析服务之间的依赖关系
-
-### 核心概念
-
-#### 服务（Service）
-
-服务是实现了 `IService` 接口的类，必须提供 `dispose()` 方法用于资源清理：
-
-```typescript
-import { IService } from '@esengine/ecs-framework';
-
-class MyService implements IService {
-    constructor() {
-        // 初始化逻辑
-    }
-
-    dispose(): void {
-        // 清理资源
-    }
-}
-```
-
-#### 生命周期
-
-服务容器支持两种生命周期：
-
-- **Singleton（单例）**: 整个应用程序生命周期内只有一个实例，所有解析请求返回同一个实例
-- **Transient（瞬时）**: 每次解析都创建新的实例
-
-## 基础使用
-
-### 访问服务容器
-
-Core 类内置了服务容器，可以通过 `Core.services` 访问：
-
-```typescript
-import { Core } from '@esengine/ecs-framework';
-
-// 初始化Core
-Core.create({ debug: true });
-
-// 访问服务容器
-const container = Core.services;
-```
-
-### 注册服务
-
-#### 注册单例服务
-
-单例服务在首次解析时创建，之后所有解析请求都返回同一个实例：
-
-```typescript
-class DataService implements IService {
-    private data: Map<string, any> = 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');
-    }
-}
-```
-
-### @Inject 装饰器
-
-在构造函数中注入依赖：
-
-```typescript
-import { Injectable, Inject, IService } from '@esengine/ecs-framework';
-
-@Injectable()
-class PlayerService implements IService {
-    constructor(
-        @Inject(DataService) private data: DataService,
-        @Inject(GameService) private game: GameService
-    ) {
-        // data 和 game 会自动从容器中解析
-    }
-
-    dispose(): void {
-        // 清理资源
-    }
-}
-```
-
-### 注册可注入服务
-
-使用 `registerInjectable` 自动处理依赖注入：
-
-```typescript
-import { registerInjectable } from '@esengine/ecs-framework';
-
-// 注册服务（会自动解析@Inject依赖）
-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<string, HTMLAudioElement> = 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);
-```
-
-## 高级用法
-
-### 服务替换（测试）
-
-在测试中替换真实服务为模拟服务：
-
-```typescript
-// 测试代码
-class MockDataService implements IService {
-    getData(key: string) {
-        return 'mock data';
-    }
-
-    dispose(): void {}
-}
-
-// 注册模拟服务（用于测试）
-Core.services.registerInstance(DataService, new MockDataService());
-```
-
-### 循环依赖检测
-
-服务容器会自动检测循环依赖：
-
-```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<string, Resource> = 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) - 在系统中使用服务

docs/guide/system.md

@@ -1,650 +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 组件的实体
-```
-
-## 系统生命周期
-
-系统提供了完整的生命周期回调：
-
-```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');
-    }
-  }
-}
-```
-
-## 系统属性和方法
-
-### 重要属性
-
-```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 类型())` 来启用依赖注入
-
-### 系统更新顺序
-
-```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; // 渲染系统最后执行
-  }
-}
-```
-
-## 复杂系统示例
-
-### 碰撞检测系统
-
-```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` 装饰器**：
-
-```typescript
-// ✅ 正确的用法
-@ECSSystem('Physics')
-class PhysicsSystem extends EntitySystem {
-  // 系统实现
-}
-
-// ❌ 错误的用法 - 没有装饰器
-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<string, any> = new Map();
-
-  protected onDestroy(): void {
-    // 清理资源
-    for (const [key, resource] of this.resources) {
-      if (resource.dispose) {
-        resource.dispose();
-      }
-    }
-    this.resources.clear();
-  }
-}
-```
-
-系统是 ECS 架构的逻辑处理核心，正确设计和使用系统能让你的游戏代码更加模块化、高效和易于维护。

docs/guide/worker-system.md

@@ -1,608 +0,0 @@
-# Worker系统
-
-Worker系统（WorkerEntitySystem）是ECS框架中基于Web Worker的多线程处理系统，专为计算密集型任务设计，能够充分利用多核CPU性能，实现真正的并行计算。
-
-## 核心特性
-
-- **真正的并行计算**：利用Web Worker在后台线程执行计算密集型任务
-- **自动负载均衡**：根据CPU核心数自动分配工作负载
-- **SharedArrayBuffer优化**：零拷贝数据共享，提升大规模计算性能
-- **降级支持**：不支持Worker时自动回退到主线程处理
-- **类型安全**：完整的TypeScript支持和类型检查
-
-## 基本用法
-
-### 简单的物理系统示例
-
-```typescript
-interface PhysicsData {
-  id: number;
-  x: number;
-  y: number;
-  vx: number;
-  vy: number;
-  mass: number;
-  radius: number;
-}
-
-@ECSSystem('Physics')
-class PhysicsWorkerSystem extends WorkerEntitySystem<PhysicsData> {
-  constructor() {
-    super(Matcher.all(Position, Velocity, Physics), {
-      enableWorker: true,              // 启用Worker并行处理
-      workerCount: 8,                  // Worker数量，系统会自动限制在硬件支持范围内
-      entitiesPerWorker: 100,          // 每个Worker处理的实体数量
-      useSharedArrayBuffer: true,      // 启用SharedArrayBuffer优化
-      entityDataSize: 7,               // 每个实体数据大小
-      maxEntities: 10000,              // 最大实体数量
-      systemConfig: {                  // 传递给Worker的配置
-        gravity: 100,
-        friction: 0.95
-      }
-    });
-  }
-
-  // 数据提取：将Entity转换为可序列化的数据
-  protected extractEntityData(entity: Entity): PhysicsData {
-    const position = entity.getComponent(Position);
-    const velocity = entity.getComponent(Velocity);
-    const physics = entity.getComponent(Physics);
-
-    return {
-      id: entity.id,
-      x: position.x,
-      y: position.y,
-      vx: velocity.x,
-      vy: velocity.y,
-      mass: physics.mass,
-      radius: physics.radius
-    };
-  }
-
-  // Worker处理函数：纯函数，在Worker中执行
-  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;
-    });
-  }
-
-  // 结果应用：将Worker处理结果应用回Entity
-  protected applyResult(entity: Entity, result: PhysicsData): void {
-    const position = entity.getComponent(Position);
-    const velocity = entity.getComponent(Velocity);
-
-    position.x = result.x;
-    position.y = result.y;
-    velocity.x = result.vx;
-    velocity.y = result.vy;
-  }
-
-  // SharedArrayBuffer优化支持
-  protected getDefaultEntityDataSize(): number {
-    return 7; // id, x, y, vx, vy, mass, radius
-  }
-
-  protected writeEntityToBuffer(entityData: PhysicsData, offset: number): void {
-    if (!this.sharedFloatArray) return;
-
-    this.sharedFloatArray[offset + 0] = entityData.id;
-    this.sharedFloatArray[offset + 1] = entityData.x;
-    this.sharedFloatArray[offset + 2] = entityData.y;
-    this.sharedFloatArray[offset + 3] = entityData.vx;
-    this.sharedFloatArray[offset + 4] = entityData.vy;
-    this.sharedFloatArray[offset + 5] = entityData.mass;
-    this.sharedFloatArray[offset + 6] = entityData.radius;
-  }
-
-  protected readEntityFromBuffer(offset: number): PhysicsData | null {
-    if (!this.sharedFloatArray) return null;
-
-    return {
-      id: this.sharedFloatArray[offset + 0],
-      x: this.sharedFloatArray[offset + 1],
-      y: this.sharedFloatArray[offset + 2],
-      vx: this.sharedFloatArray[offset + 3],
-      vy: this.sharedFloatArray[offset + 4],
-      mass: this.sharedFloatArray[offset + 5],
-      radius: this.sharedFloatArray[offset + 6]
-    };
-  }
-}
-```
-
-## 配置选项
-
-Worker系统支持丰富的配置选项：
-
-```typescript
-interface WorkerSystemConfig {
-  /** 是否启用Worker并行处理 */
-  enableWorker?: boolean;
-  /** Worker数量，默认为CPU核心数，自动限制在系统最大值内 */
-  workerCount?: number;
-  /** 每个Worker处理的实体数量，用于控制负载分布 */
-  entitiesPerWorker?: number;
-  /** 系统配置数据，会传递给Worker */
-  systemConfig?: any;
-  /** 是否使用SharedArrayBuffer优化 */
-  useSharedArrayBuffer?: boolean;
-  /** 每个实体在SharedArrayBuffer中占用的Float32数量 */
-  entityDataSize?: number;
-  /** 最大实体数量（用于预分配SharedArrayBuffer） */
-  maxEntities?: number;
-}
-```
-
-### 配置建议
-
-```typescript
-constructor() {
-  super(matcher, {
-    // 根据任务复杂度决定是否启用
-    enableWorker: this.shouldUseWorker(),
-
-    // Worker数量：系统会自动限制在硬件支持范围内
-    workerCount: 8, // 请求8个Worker，实际数量受CPU核心数限制
-
-    // 每个Worker处理的实体数量（可选）
-    entitiesPerWorker: 200, // 精确控制负载分布
-
-    // 大量简单计算时启用SharedArrayBuffer
-    useSharedArrayBuffer: this.entityCount > 1000,
-
-    // 根据实际数据结构设置
-    entityDataSize: 8, // 确保与数据结构匹配
-
-    // 预估最大实体数量
-    maxEntities: 10000,
-
-    // 传递给Worker的全局配置
-    systemConfig: {
-      gravity: 9.8,
-      friction: 0.95,
-      worldBounds: { width: 1920, height: 1080 }
-    }
-  });
-}
-
-private shouldUseWorker(): boolean {
-  // 根据实体数量和计算复杂度决定
-  return this.expectedEntityCount > 100;
-}
-
-// 获取系统信息
-getSystemInfo() {
-  const info = this.getWorkerInfo();
-  console.log(`Worker数量: ${info.workerCount}/${info.maxSystemWorkerCount}`);
-  console.log(`每Worker实体数: ${info.entitiesPerWorker || '自动分配'}`);
-  console.log(`当前模式: ${info.currentMode}`);
-}
-```
-
-## 处理模式
-
-Worker系统支持两种处理模式：
-
-### 1. 传统Worker模式
-
-数据通过序列化在主线程和Worker间传递：
-
-```typescript
-// 适用于：复杂计算逻辑，实体数量适中
-constructor() {
-  super(matcher, {
-    enableWorker: true,
-    useSharedArrayBuffer: false, // 使用传统模式
-    workerCount: 2
-  });
-}
-
-protected workerProcess(entities: EntityData[], deltaTime: number): EntityData[] {
-  // 复杂的算法逻辑
-  return entities.map(entity => {
-    // AI决策、路径规划等复杂计算
-    return this.complexAILogic(entity, deltaTime);
-  });
-}
-```
-
-### 2. SharedArrayBuffer模式
-
-零拷贝数据共享，适合大量简单计算：
-
-```typescript
-// 适用于：大量实体的简单计算
-constructor() {
-  super(matcher, {
-    enableWorker: true,
-    useSharedArrayBuffer: true, // 启用共享内存
-    entityDataSize: 6,
-    maxEntities: 10000
-  });
-}
-
-protected getSharedArrayBufferProcessFunction(): SharedArrayBufferProcessFunction {
-  return function(sharedFloatArray: Float32Array, startIndex: number, endIndex: number, deltaTime: number, config: any) {
-    const entitySize = 6;
-    for (let i = startIndex; i < endIndex; i++) {
-      const offset = i * entitySize;
-
-      // 读取数据
-      let x = sharedFloatArray[offset];
-      let y = sharedFloatArray[offset + 1];
-      let vx = sharedFloatArray[offset + 2];
-      let vy = sharedFloatArray[offset + 3];
-
-      // 物理计算
-      vy += config.gravity * deltaTime;
-      x += vx * deltaTime;
-      y += vy * deltaTime;
-
-      // 写回数据
-      sharedFloatArray[offset] = x;
-      sharedFloatArray[offset + 1] = y;
-      sharedFloatArray[offset + 2] = vx;
-      sharedFloatArray[offset + 3] = vy;
-    }
-  };
-}
-```
-
-## 完整示例：粒子物理系统
-
-一个包含碰撞检测的完整粒子物理系统：
-
-```typescript
-interface ParticleData {
-  id: number;
-  x: number;
-  y: number;
-  dx: number;
-  dy: number;
-  mass: number;
-  radius: number;
-  bounce: number;
-  friction: number;
-}
-
-@ECSSystem('ParticlePhysics')
-class ParticlePhysicsWorkerSystem extends WorkerEntitySystem<ParticleData> {
-  constructor() {
-    super(Matcher.all(Position, Velocity, Physics, Renderable), {
-      enableWorker: true,
-      workerCount: 6,                  // 请求6个Worker，自动限制在CPU核心数内
-      entitiesPerWorker: 150,          // 每个Worker处理150个粒子
-      useSharedArrayBuffer: true,
-      entityDataSize: 9,
-      maxEntities: 5000,
-      systemConfig: {
-        gravity: 100,
-        canvasWidth: 800,
-        canvasHeight: 600,
-        groundFriction: 0.98
-      }
-    });
-  }
-
-  protected extractEntityData(entity: Entity): ParticleData {
-    const position = entity.getComponent(Position);
-    const velocity = entity.getComponent(Velocity);
-    const physics = entity.getComponent(Physics);
-    const renderable = entity.getComponent(Renderable);
-
-    return {
-      id: entity.id,
-      x: position.x,
-      y: position.y,
-      dx: velocity.dx,
-      dy: velocity.dy,
-      mass: physics.mass,
-      radius: renderable.size,
-      bounce: physics.bounce,
-      friction: physics.friction
-    };
-  }
-
-  protected workerProcess(
-    entities: ParticleData[],
-    deltaTime: number,
-    config: any
-  ): ParticleData[] {
-    const result = entities.map(e => ({ ...e }));
-
-    // 基础物理更新
-    for (const particle of result) {
-      // 应用重力
-      particle.dy += config.gravity * deltaTime;
-
-      // 更新位置
-      particle.x += particle.dx * deltaTime;
-      particle.y += particle.dy * deltaTime;
-
-      // 边界碰撞
-      if (particle.x <= particle.radius) {
-        particle.x = particle.radius;
-        particle.dx = -particle.dx * particle.bounce;
-      } else if (particle.x >= config.canvasWidth - particle.radius) {
-        particle.x = config.canvasWidth - particle.radius;
-        particle.dx = -particle.dx * particle.bounce;
-      }
-
-      if (particle.y <= particle.radius) {
-        particle.y = particle.radius;
-        particle.dy = -particle.dy * particle.bounce;
-      } else if (particle.y >= config.canvasHeight - particle.radius) {
-        particle.y = config.canvasHeight - particle.radius;
-        particle.dy = -particle.dy * particle.bounce;
-        particle.dx *= config.groundFriction;
-      }
-
-      // 空气阻力
-      particle.dx *= particle.friction;
-      particle.dy *= particle.friction;
-    }
-
-    // 粒子间碰撞检测（O(n²)算法）
-    for (let i = 0; i < result.length; i++) {
-      for (let j = i + 1; j < result.length; j++) {
-        const p1 = result[i];
-        const p2 = result[j];
-
-        const dx = p2.x - p1.x;
-        const dy = p2.y - p1.y;
-        const distance = Math.sqrt(dx * dx + dy * dy);
-        const minDistance = p1.radius + p2.radius;
-
-        if (distance < minDistance && distance > 0) {
-          // 分离粒子
-          const nx = dx / distance;
-          const ny = dy / distance;
-          const overlap = minDistance - distance;
-
-          p1.x -= nx * overlap * 0.5;
-          p1.y -= ny * overlap * 0.5;
-          p2.x += nx * overlap * 0.5;
-          p2.y += ny * overlap * 0.5;
-
-          // 弹性碰撞
-          const relativeVelocityX = p2.dx - p1.dx;
-          const relativeVelocityY = p2.dy - p1.dy;
-          const velocityAlongNormal = relativeVelocityX * nx + relativeVelocityY * ny;
-
-          if (velocityAlongNormal > 0) continue;
-
-          const restitution = (p1.bounce + p2.bounce) * 0.5;
-          const impulseScalar = -(1 + restitution) * velocityAlongNormal / (1/p1.mass + 1/p2.mass);
-
-          p1.dx -= impulseScalar * nx / p1.mass;
-          p1.dy -= impulseScalar * ny / p1.mass;
-          p2.dx += impulseScalar * nx / p2.mass;
-          p2.dy += impulseScalar * ny / p2.mass;
-        }
-      }
-    }
-
-    return result;
-  }
-
-  protected applyResult(entity: Entity, result: ParticleData): void {
-    if (!entity?.enabled) return;
-
-    const position = entity.getComponent(Position);
-    const velocity = entity.getComponent(Velocity);
-
-    if (position && velocity) {
-      position.set(result.x, result.y);
-      velocity.set(result.dx, result.dy);
-    }
-  }
-
-  protected getDefaultEntityDataSize(): number {
-    return 9;
-  }
-
-  protected writeEntityToBuffer(data: ParticleData, offset: number): void {
-    if (!this.sharedFloatArray) return;
-
-    this.sharedFloatArray[offset + 0] = data.id;
-    this.sharedFloatArray[offset + 1] = data.x;
-    this.sharedFloatArray[offset + 2] = data.y;
-    this.sharedFloatArray[offset + 3] = data.dx;
-    this.sharedFloatArray[offset + 4] = data.dy;
-    this.sharedFloatArray[offset + 5] = data.mass;
-    this.sharedFloatArray[offset + 6] = data.radius;
-    this.sharedFloatArray[offset + 7] = data.bounce;
-    this.sharedFloatArray[offset + 8] = data.friction;
-  }
-
-  protected readEntityFromBuffer(offset: number): ParticleData | null {
-    if (!this.sharedFloatArray) return null;
-
-    return {
-      id: this.sharedFloatArray[offset + 0],
-      x: this.sharedFloatArray[offset + 1],
-      y: this.sharedFloatArray[offset + 2],
-      dx: this.sharedFloatArray[offset + 3],
-      dy: this.sharedFloatArray[offset + 4],
-      mass: this.sharedFloatArray[offset + 5],
-      radius: this.sharedFloatArray[offset + 6],
-      bounce: this.sharedFloatArray[offset + 7],
-      friction: this.sharedFloatArray[offset + 8]
-    };
-  }
-
-  // 性能监控
-  public getPerformanceInfo(): {
-    enabled: boolean;
-    workerCount: number;
-    entitiesPerWorker?: number;
-    maxSystemWorkerCount: number;
-    entityCount: number;
-    isProcessing: boolean;
-    currentMode: string;
-  } {
-    const workerInfo = this.getWorkerInfo();
-    return {
-      ...workerInfo,
-      entityCount: this.entities.length
-    };
-  }
-}
-```
-
-## 适用场景
-
-Worker系统特别适合以下场景：
-
-### 1. 物理模拟
-- **重力系统**：大量实体的重力计算
-- **碰撞检测**：复杂的碰撞算法
-- **流体模拟**：粒子流体系统
-- **布料模拟**：顶点物理计算
-
-### 2. AI计算
-- **路径寻找**：A*、Dijkstra等算法
-- **行为树**：复杂的AI决策逻辑
-- **群体智能**：鸟群、鱼群算法
-- **神经网络**：简单的AI推理
-
-### 3. 数据处理
-- **大量实体更新**：状态机、生命周期管理
-- **统计计算**：游戏数据分析
-- **图像处理**：纹理生成、效果计算
-- **音频处理**：音效合成、频谱分析
-
-## 最佳实践
-
-### 1. Worker函数要求
-
-```typescript
-// ✅ 推荐：Worker处理函数是纯函数
-protected workerProcess(entities: PhysicsData[], deltaTime: number, config: any): PhysicsData[] {
-  // 只使用参数和标准JavaScript API
-  return entities.map(entity => {
-    // 纯计算逻辑，不依赖外部状态
-    entity.y += entity.velocity * deltaTime;
-    return entity;
-  });
-}
-
-// ❌ 避免：在Worker函数中使用外部引用
-protected workerProcess(entities: PhysicsData[], deltaTime: number): PhysicsData[] {
-  // this 和外部变量在Worker中不可用
-  return entities.map(entity => {
-    entity.y += this.someProperty; // ❌ 错误
-    return entity;
-  });
-}
-```
-
-### 2. 数据设计
-
-```typescript
-// ✅ 推荐：合理的数据设计
-interface SimplePhysicsData {
-  x: number;
-  y: number;
-  vx: number;
-  vy: number;
-  // 保持数据结构简单，便于序列化
-}
-
-// ❌ 避免：复杂的嵌套对象
-interface ComplexData {
-  transform: {
-    position: { x: number; y: number };
-    rotation: { angle: number };
-  };
-  // 复杂嵌套结构增加序列化开销
-}
-```
-
-### 3. Worker数量控制
-
-```typescript
-// ✅ 推荐：灵活的Worker配置
-constructor() {
-  super(matcher, {
-    // 直接指定需要的Worker数量，系统会自动限制在硬件支持范围内
-    workerCount: 8,                     // 请求8个Worker
-    entitiesPerWorker: 100,            // 每个Worker处理100个实体
-    enableWorker: this.shouldUseWorker(), // 条件启用
-  });
-}
-
-private shouldUseWorker(): boolean {
-  // 根据实体数量和复杂度决定是否使用Worker
-  return this.expectedEntityCount > 100;
-}
-
-// 获取实际使用的Worker信息
-checkWorkerConfiguration() {
-  const info = this.getWorkerInfo();
-  console.log(`请求Worker数量: 8`);
-  console.log(`实际Worker数量: ${info.workerCount}`);
-  console.log(`系统最大支持: ${info.maxSystemWorkerCount}`);
-  console.log(`每Worker实体数: ${info.entitiesPerWorker || '自动分配'}`);
-}
-```
-
-### 4. 性能监控
-
-```typescript
-// ✅ 推荐：性能监控
-public getPerformanceMetrics(): WorkerPerformanceMetrics {
-  return {
-    ...this.getWorkerInfo(),
-    entityCount: this.entities.length,
-    averageProcessTime: this.getAverageProcessTime(),
-    workerUtilization: this.getWorkerUtilization()
-  };
-}
-```
-
-## 性能优化建议
-
-### 1. 计算密集度评估
-只对计算密集型任务使用Worker，避免在简单计算上增加线程开销。
-
-### 2. 数据传输优化
-- 使用SharedArrayBuffer减少序列化开销
-- 保持数据结构简单和扁平
-- 避免频繁的大数据传输
-
-### 3. 降级策略
-始终提供主线程回退方案，确保在不支持Worker的环境中正常运行。
-
-### 4. 内存管理
-及时清理Worker池和共享缓冲区，避免内存泄漏。
-
-### 5. 负载均衡
-使用 `entitiesPerWorker` 参数精确控制负载分布，避免某些Worker空闲而其他Worker过载。
-
-## 在线演示
-
-查看完整的Worker系统演示：[Worker系统演示](https://esengine.github.io/ecs-framework/demos/worker-system/)
-
-该演示展示了：
-- 多线程物理计算
-- 实时性能对比
-- SharedArrayBuffer优化
-- 大量实体的并行处理
-
-Worker系统为ECS框架提供了强大的并行计算能力，让你能够充分利用现代多核处理器的性能，为复杂的游戏逻辑和计算密集型任务提供了高效的解决方案。

docs/guide/world-manager.md

@@ -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<MainScene>('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,
-//   cleanupInterval: 30000  // 30 秒
-// }
-```
-
-### 手动清理
-
-```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<string, World> = 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)。

docs/index.md

@@ -1,23 +0,0 @@
----
-layout: home
-
-hero:
-  name: "ECS Framework"
-  text: "高性能ECS框架"
-  tagline: "为Javascript游戏开发而设计"
-  actions:
-    - theme: brand
-      text: 快速开始
-      link: /guide/getting-started
-    - theme: alt
-      text: 查看示例
-      link: https://github.com/esengine/lawn-mower-demo
-
-features:
-  - title: 高性能
-    details: 支持大规模实体处理
-  - title: 类型安全
-    details: 完整的TypeScript支持，编译时类型检查
-  - title: 模块化设计
-    details: 核心功能独立打包，支持多平台
----

docs/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@esengine/docs",
+  "private": true,
+  "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"
+  }
+}

docs/public/CNAME

@@ -0,0 +1 @@
+esengine.cn

docs/public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill-rule="evenodd" d="M81 36 64 0 47 36l-1 2-9-10a6 6 0 0 0-9 9l10 10h-2L0 64l36 17h2L28 91a6 6 0 1 0 9 9l9-10 1 2 17 36 17-36v-2l9 10a6 6 0 1 0 9-9l-9-9 2-1 36-17-36-17-2-1 9-9a6 6 0 1 0-9-9l-9 10v-2Zm-17 2-2 5c-4 8-11 15-19 19l-5 2 5 2c8 4 15 11 19 19l2 5 2-5c4-8 11-15 19-19l5-2-5-2c-8-4-15-11-19-19l-2-5Z" clip-rule="evenodd"/><path d="M118 19a6 6 0 0 0-9-9l-3 3a6 6 0 1 0 9 9l3-3Zm-96 4c-2 2-6 2-9 0l-3-3a6 6 0 1 1 9-9l3 3c3 2 3 6 0 9Zm0 82c-2-2-6-2-9 0l-3 3a6 6 0 1 0 9 9l3-3c3-2 3-6 0-9Zm96 4a6 6 0 0 1-9 9l-3-3a6 6 0 1 1 9-9l3 3Z"/><style>path{fill:#000}@media (prefers-color-scheme:dark){path{fill:#fff}}</style></svg>

docs/public/logo.svg

@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <defs>
+    <!-- Dark gradient background -->
+    <linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#2d2d2d"/>
+      <stop offset="100%" style="stop-color:#1a1a1a"/>
+    </linearGradient>
+
+    <!-- Clean white text -->
+    <linearGradient id="whiteGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#ffffff"/>
+      <stop offset="100%" style="stop-color:#e8e8e8"/>
+    </linearGradient>
+
+    <!-- Subtle inner shadow -->
+    <filter id="innerShadow">
+      <feOffset dx="0" dy="2"/>
+      <feGaussianBlur stdDeviation="1" result="offset-blur"/>
+      <feComposite operator="out" in="SourceGraphic" in2="offset-blur" result="inverse"/>
+      <feFlood flood-color="black" flood-opacity="0.2" result="color"/>
+      <feComposite operator="in" in="color" in2="inverse" result="shadow"/>
+      <feComposite operator="over" in="shadow" in2="SourceGraphic"/>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="512" height="512" fill="url(#bgGrad)"/>
+
+  <!-- Subtle border -->
+  <rect x="1" y="1" width="510" height="510" fill="none" stroke="#3d3d3d" stroke-width="2"/>
+
+  <!-- ES Text -->
+  <g filter="url(#innerShadow)">
+    <!-- E -->
+    <polygon points="72,120 72,392 240,392 240,340 140,340 140,282 220,282 220,230 140,230 140,172 240,172 240,120"
+             fill="url(#whiteGrad)"/>
+
+    <!-- S -->
+    <path d="M 280 172 Q 280 120 340 120 L 420 120 Q 450 120 450 160 L 450 186 L 398 186 L 398 168 Q 398 158 384 158 L 350 158 Q 320 158 320 188 Q 320 218 350 218 L 400 218 Q 450 218 450 274 L 450 332 Q 450 392 390 392 L 310 392 Q 270 392 270 340 L 270 314 L 322 314 L 322 340 Q 322 354 340 354 L 384 354 Q 404 354 404 324 L 404 290 Q 404 260 380 260 L 330 260 Q 280 260 280 208 Z"
+          fill="url(#whiteGrad)"/>
+  </g>
+
+  <!-- Accent line -->
+  <rect x="72" y="424" width="368" height="4" fill="#ffffff" opacity="0.6"/>
+</svg>

docs/src/assets/logo.svg

@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
+  <defs>
+    <!-- Dark gradient background -->
+    <linearGradient id="bgGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#2d2d2d"/>
+      <stop offset="100%" style="stop-color:#1a1a1a"/>
+    </linearGradient>
+
+    <!-- Clean white text -->
+    <linearGradient id="whiteGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#ffffff"/>
+      <stop offset="100%" style="stop-color:#e8e8e8"/>
+    </linearGradient>
+
+    <!-- Subtle inner shadow -->
+    <filter id="innerShadow">
+      <feOffset dx="0" dy="2"/>
+      <feGaussianBlur stdDeviation="1" result="offset-blur"/>
+      <feComposite operator="out" in="SourceGraphic" in2="offset-blur" result="inverse"/>
+      <feFlood flood-color="black" flood-opacity="0.2" result="color"/>
+      <feComposite operator="in" in="color" in2="inverse" result="shadow"/>
+      <feComposite operator="over" in="shadow" in2="SourceGraphic"/>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="512" height="512" fill="url(#bgGrad)"/>
+
+  <!-- Subtle border -->
+  <rect x="1" y="1" width="510" height="510" fill="none" stroke="#3d3d3d" stroke-width="2"/>
+
+  <!-- ES Text -->
+  <g filter="url(#innerShadow)">
+    <!-- E -->
+    <polygon points="72,120 72,392 240,392 240,340 140,340 140,282 220,282 220,230 140,230 140,172 240,172 240,120"
+             fill="url(#whiteGrad)"/>
+
+    <!-- S -->
+    <path d="M 280 172 Q 280 120 340 120 L 420 120 Q 450 120 450 160 L 450 186 L 398 186 L 398 168 Q 398 158 384 158 L 350 158 Q 320 158 320 188 Q 320 218 350 218 L 400 218 Q 450 218 450 274 L 450 332 Q 450 392 390 392 L 310 392 Q 270 392 270 340 L 270 314 L 322 314 L 322 340 Q 322 354 340 354 L 384 354 Q 404 354 404 324 L 404 290 Q 404 260 380 260 L 330 260 Q 280 260 280 208 Z"
+          fill="url(#whiteGrad)"/>
+  </g>
+
+  <!-- Accent line -->
+  <rect x="72" y="424" width="368" height="4" fill="#ffffff" opacity="0.6"/>
+</svg>

docs/src/components/Head.astro

@@ -0,0 +1,20 @@
+---
+import type { Props } from '@astrojs/starlight/props';
+import Default from '@astrojs/starlight/components/Head.astro';
+---
+
+<Default {...Astro.props}><slot /></Default>
+
+<!-- Preload fonts -->
+<link rel="preconnect" href="https://fonts.googleapis.com" />
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+<link
+  href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500&display=swap"
+  rel="stylesheet"
+/>
+
+<!-- Force dark mode -->
+<script is:inline>
+  document.documentElement.dataset.theme = 'dark';
+  localStorage.setItem('starlight-theme', 'dark');
+</script>

docs/src/components/ThemeSelect.astro

@@ -0,0 +1,3 @@
+---
+// Empty component to disable theme selection (dark mode only)
+---

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() }),
+};

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` 目录。
+:::

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

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.

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<number, Set<{ component: WeakRef<Component>, 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

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

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 |

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

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) |

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

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
+```

docs/src/content/docs/en/guide/entity/component-operations.md

@@ -0,0 +1,273 @@
+---
+title: "Component Operations"
+description: "Detailed guide to adding, getting, and removing entity components"
+---
+
+Entities gain functionality by adding components. This section details all component operation APIs.
+
+## Adding Components
+
+### addComponent
+
+Add an already-created component instance:
+
+```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;
+    }
+}
+
+const player = scene.createEntity("Player");
+const position = new Position(100, 200);
+player.addComponent(position);
+```
+
+### createComponent
+
+Pass the component type and constructor arguments directly—the entity creates the instance (recommended):
+
+```typescript
+// Create and add component
+const position = player.createComponent(Position, 100, 200);
+const health = player.createComponent(Health, 150);
+
+// Equivalent to:
+// const position = new Position(100, 200);
+// player.addComponent(position);
+```
+
+### addComponents
+
+Add multiple components at once:
+
+```typescript
+const components = player.addComponents([
+    new Position(100, 200),
+    new Health(150),
+    new Velocity(0, 0)
+]);
+```
+
+:::note[Important Notes]
+- An entity cannot have two components of the same type—an exception will be thrown
+- The entity must be added to a scene before adding components
+:::
+
+## Getting Components
+
+### getComponent
+
+Get a component of a specific type:
+
+```typescript
+// Returns Position | null
+const position = player.getComponent(Position);
+
+if (position) {
+    position.x += 10;
+    position.y += 20;
+}
+```
+
+### hasComponent
+
+Check if an entity has a specific component type:
+
+```typescript
+if (player.hasComponent(Position)) {
+    const position = player.getComponent(Position)!;
+    // Use ! because we confirmed it exists
+}
+```
+
+### getComponents
+
+Get all components of a specific type (for multi-component scenarios):
+
+```typescript
+const allHealthComponents = player.getComponents(Health);
+```
+
+### getComponentByType
+
+Get components with inheritance support using `instanceof` checking:
+
+```typescript
+// Find CompositeNodeComponent or any subclass
+const composite = entity.getComponentByType(CompositeNodeComponent);
+if (composite) {
+    // composite could be SequenceNode, SelectorNode, etc.
+}
+```
+
+Difference from `getComponent()`:
+
+| Method | Lookup Method | Performance | Use Case |
+|--------|---------------|-------------|----------|
+| `getComponent` | Exact type match (bitmask) | High | Known exact type |
+| `getComponentByType` | `instanceof` check | Lower | Need inheritance support |
+
+### getOrCreateComponent
+
+Get or create a component—automatically creates if it doesn't exist:
+
+```typescript
+// Ensure entity has Position component
+const position = player.getOrCreateComponent(Position, 0, 0);
+position.x = 100;
+
+// If exists, returns existing component
+// If not, creates new component with (0, 0) args
+```
+
+### components Property
+
+Get all entity components (read-only):
+
+```typescript
+const allComponents = player.components;  // readonly Component[]
+
+allComponents.forEach(component => {
+    console.log(component.constructor.name);
+});
+```
+
+## Removing Components
+
+### removeComponent
+
+Remove by component instance:
+
+```typescript
+const healthComponent = player.getComponent(Health);
+if (healthComponent) {
+    player.removeComponent(healthComponent);
+}
+```
+
+### removeComponentByType
+
+Remove by component type:
+
+```typescript
+const removedHealth = player.removeComponentByType(Health);
+if (removedHealth) {
+    console.log("Health component removed");
+}
+```
+
+### removeComponentsByTypes
+
+Remove multiple component types at once:
+
+```typescript
+const removedComponents = player.removeComponentsByTypes([
+    Position,
+    Health,
+    Velocity
+]);
+```
+
+### removeAllComponents
+
+Remove all components:
+
+```typescript
+player.removeAllComponents();
+```
+
+## Change Detection
+
+### markDirty
+
+Mark components as modified for frame-level change detection:
+
+```typescript
+const pos = entity.getComponent(Position)!;
+pos.x = 100;
+entity.markDirty(pos);
+
+// Or mark multiple components
+const vel = entity.getComponent(Velocity)!;
+entity.markDirty(pos, vel);
+```
+
+Use with reactive queries:
+
+```typescript
+// Query for components modified this frame
+const changedQuery = scene.createReactiveQuery({
+    all: [Position],
+    changed: [Position]  // Only match modified this frame
+});
+
+for (const entity of changedQuery.getEntities()) {
+    // Handle entities with position changes
+}
+```
+
+## Component Mask
+
+Each entity maintains a component bitmask for efficient `hasComponent` checks:
+
+```typescript
+// Get component mask (internal use)
+const mask = entity.componentMask;
+```
+
+## Complete Example
+
+```typescript
+import { Component, ECSComponent, Scene } from '@esengine/ecs-framework';
+
+@ECSComponent('Position')
+class Position extends Component {
+    constructor(public x = 0, public y = 0) { super(); }
+}
+
+@ECSComponent('Health')
+class Health extends Component {
+    constructor(public current = 100, public max = 100) { super(); }
+}
+
+// Create entity and add components
+const player = scene.createEntity("Player");
+player.createComponent(Position, 100, 200);
+player.createComponent(Health, 150, 150);
+
+// Get and modify component
+const position = player.getComponent(Position);
+if (position) {
+    position.x += 10;
+    player.markDirty(position);
+}
+
+// Get or create component
+const velocity = player.getOrCreateComponent(Velocity, 0, 0);
+
+// Check component existence
+if (player.hasComponent(Health)) {
+    const health = player.getComponent(Health)!;
+    health.current -= 10;
+}
+
+// Remove component
+player.removeComponentByType(Velocity);
+
+// List all components
+console.log(player.components.map(c => c.constructor.name));
+```
+
+## Next Steps
+
+- [Entity Handle](/en/guide/entity/entity-handle/) - Safe cross-frame entity references
+- [Component System](/en/guide/component/) - Component definition and lifecycle

docs/src/content/docs/en/guide/entity/entity-handle.md

@@ -0,0 +1,265 @@
+---
+title: "Entity Handle"
+description: "Using EntityHandle to safely reference entities and avoid referencing destroyed entities"
+---
+
+Entity handles (EntityHandle) provide a safe way to reference entities, solving the "referencing destroyed entities" problem.
+
+## The Problem
+
+Imagine your AI system needs to track a target enemy:
+
+```typescript
+// ❌ Wrong: Storing entity reference directly
+class AISystem extends EntitySystem {
+    private targetEnemy: Entity | null = null;
+
+    setTarget(enemy: Entity) {
+        this.targetEnemy = enemy;
+    }
+
+    process() {
+        if (this.targetEnemy) {
+            // Danger! Enemy might be destroyed but reference still exists
+            // Worse: This memory location might be reused by a new entity
+            const health = this.targetEnemy.getComponent(Health);
+            // Might operate on wrong entity!
+        }
+    }
+}
+```
+
+## What is EntityHandle
+
+EntityHandle is a numeric entity identifier containing:
+- **Index**: Entity's position in the array
+- **Generation**: Number of times the entity slot has been reused
+
+When an entity is destroyed, even if its index is reused by a new entity, the generation increases, invalidating old handles.
+
+```typescript
+import { EntityHandle, NULL_HANDLE, isValidHandle } from '@esengine/ecs-framework';
+
+// Each entity gets a handle when created
+const handle: EntityHandle = entity.handle;
+
+// Null handle constant
+const emptyHandle = NULL_HANDLE;
+
+// Check if handle is non-null
+if (isValidHandle(handle)) {
+    // Handle is valid
+}
+```
+
+## The Correct Approach
+
+```typescript
+import { EntityHandle, NULL_HANDLE, isValidHandle } from '@esengine/ecs-framework';
+
+class AISystem extends EntitySystem {
+    // ✅ Store handle instead of entity reference
+    private targetHandle: EntityHandle = NULL_HANDLE;
+
+    setTarget(enemy: Entity) {
+        this.targetHandle = enemy.handle;
+    }
+
+    process() {
+        if (!isValidHandle(this.targetHandle)) {
+            return; // No target
+        }
+
+        // Get entity via handle (auto-validates)
+        const enemy = this.scene.findEntityByHandle(this.targetHandle);
+
+        if (!enemy) {
+            // Enemy destroyed, clear reference
+            this.targetHandle = NULL_HANDLE;
+            return;
+        }
+
+        // Safe operation
+        const health = enemy.getComponent(Health);
+        if (health) {
+            // Deal damage to enemy
+        }
+    }
+}
+```
+
+## API Reference
+
+### Getting Handle
+
+```typescript
+// Get handle from entity
+const handle = entity.handle;
+```
+
+### Validating Handle
+
+```typescript
+import { isValidHandle, NULL_HANDLE } from '@esengine/ecs-framework';
+
+// Check if handle is non-null
+if (isValidHandle(handle)) {
+    // ...
+}
+
+// Check if entity is alive
+const alive = scene.handleManager.isAlive(handle);
+```
+
+### Getting Entity by Handle
+
+```typescript
+// Returns Entity | null
+const entity = scene.findEntityByHandle(handle);
+
+if (entity) {
+    // Entity exists and is valid
+}
+```
+
+## Complete Example: Skill Target Locking
+
+```typescript
+import {
+    EntitySystem,
+    Entity,
+    EntityHandle,
+    NULL_HANDLE,
+    isValidHandle
+} from '@esengine/ecs-framework';
+
+@ECSSystem('SkillTargeting')
+class SkillTargetingSystem extends EntitySystem {
+    // Store multiple target handles
+    private lockedTargets: Map<number, EntityHandle> = new Map();
+
+    // Lock target
+    lockTarget(casterId: number, target: Entity) {
+        this.lockedTargets.set(casterId, target.handle);
+    }
+
+    // Get locked target
+    getLockedTarget(casterId: number): Entity | null {
+        const handle = this.lockedTargets.get(casterId);
+
+        if (!handle || !isValidHandle(handle)) {
+            return null;
+        }
+
+        const target = this.scene.findEntityByHandle(handle);
+
+        if (!target) {
+            // Target dead, clear lock
+            this.lockedTargets.delete(casterId);
+        }
+
+        return target;
+    }
+
+    // Cast skill
+    castSkill(caster: Entity) {
+        const target = this.getLockedTarget(caster.id);
+
+        if (!target) {
+            console.log('Target lost, skill cancelled');
+            return;
+        }
+
+        const health = target.getComponent(Health);
+        if (health) {
+            health.current -= 10;
+        }
+    }
+
+    // Clear target for specific caster
+    clearTarget(casterId: number) {
+        this.lockedTargets.delete(casterId);
+    }
+}
+```
+
+## Usage Guidelines
+
+| Scenario | Recommended Approach |
+|----------|---------------------|
+| Same-frame temporary use | Direct `Entity` reference |
+| Cross-frame storage (AI target, skill target) | Use `EntityHandle` |
+| Serialization/save | Use `EntityHandle` (numeric type) |
+| Network sync | Use `EntityHandle` (directly transferable) |
+
+## Performance Considerations
+
+- EntityHandle is a numeric type with small memory footprint
+- `findEntityByHandle` is O(1) operation
+- Safer and more reliable than checking `entity.isDestroyed` every frame
+
+## Common Patterns
+
+### Optional Target Reference
+
+```typescript
+class FollowComponent extends Component {
+    private _targetHandle: EntityHandle = NULL_HANDLE;
+
+    setTarget(target: Entity | null) {
+        this._targetHandle = target?.handle ?? NULL_HANDLE;
+    }
+
+    getTarget(scene: IScene): Entity | null {
+        if (!isValidHandle(this._targetHandle)) {
+            return null;
+        }
+        return scene.findEntityByHandle(this._targetHandle);
+    }
+
+    hasTarget(): boolean {
+        return isValidHandle(this._targetHandle);
+    }
+}
+```
+
+### Multi-Target Tracking
+
+```typescript
+class MultiTargetComponent extends Component {
+    private targets: EntityHandle[] = [];
+
+    addTarget(target: Entity) {
+        this.targets.push(target.handle);
+    }
+
+    removeTarget(target: Entity) {
+        const index = this.targets.indexOf(target.handle);
+        if (index >= 0) {
+            this.targets.splice(index, 1);
+        }
+    }
+
+    getValidTargets(scene: IScene): Entity[] {
+        const valid: Entity[] = [];
+        const stillValid: EntityHandle[] = [];
+
+        for (const handle of this.targets) {
+            const entity = scene.findEntityByHandle(handle);
+            if (entity) {
+                valid.push(entity);
+                stillValid.push(handle);
+            }
+        }
+
+        // Clean up invalid handles
+        this.targets = stillValid;
+        return valid;
+    }
+}
+```
+
+## Next Steps
+
+- [Lifecycle](/en/guide/entity/lifecycle/) - Entity destruction and persistence
+- [Entity Reference](/en/guide/component/entity-ref/) - Entity reference decorators in components

docs/src/content/docs/en/guide/entity/index.md

@@ -0,0 +1,174 @@
+---
+title: "Entity Overview"
+description: "Basic concepts and usage of entities in ECS architecture"
+---
+
+In ECS architecture, an Entity is a fundamental object in the game world. Entities contain no game logic or data themselves—they are simply containers that combine different components to achieve various functionalities.
+
+## Basic Concepts
+
+An entity is a lightweight object primarily used for:
+- Acting as a container for components
+- Providing unique identifiers (ID and persistentId)
+- Managing component lifecycles
+
+:::tip[About Parent-Child Hierarchy]
+Parent-child 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 the [Hierarchy System](/en/guide/hierarchy/) documentation for details.
+:::
+
+## Creating Entities
+
+**Entities must be created through the scene, not manually.**
+
+```typescript
+// Correct: Create entity through scene
+const player = scene.createEntity("Player");
+
+// ❌ Wrong: Manual creation
+// const entity = new Entity("MyEntity", 1);
+```
+
+Creating through the scene ensures:
+- Entity is properly added to the scene's entity management system
+- Entity is added to the query system for use by systems
+- Entity gets the correct scene reference
+- Related lifecycle events are triggered
+
+### Batch Creation
+
+The framework provides high-performance batch creation:
+
+```typescript
+// Batch create 100 bullet entities
+const bullets = scene.createEntities(100, "Bullet");
+
+bullets.forEach((bullet, index) => {
+    bullet.createComponent(Position, Math.random() * 800, Math.random() * 600);
+    bullet.createComponent(Velocity, Math.random() * 100, Math.random() * 100);
+});
+```
+
+`createEntities()` batches ID allocation, optimizes query system updates, and reduces system cache clearing.
+
+## Entity Identifiers
+
+Each entity has three types of identifiers:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `number` | Runtime unique identifier for fast lookups |
+| `persistentId` | `string` | GUID for maintaining reference consistency during serialization |
+| `handle` | `EntityHandle` | Lightweight handle, see [Entity Handle](/en/guide/entity/entity-handle/) |
+
+```typescript
+const entity = scene.createEntity("Player");
+
+console.log(entity.id);           // 1
+console.log(entity.persistentId); // "a1b2c3d4-..."
+console.log(entity.handle);       // Numeric handle
+```
+
+## Entity Properties
+
+### Name and Tag
+
+```typescript
+// Name - for debugging and lookup
+entity.name = "Player";
+
+// Tag - for fast categorization and querying
+entity.tag = 1;  // Player tag
+enemy.tag = 2;   // Enemy tag
+```
+
+### State Control
+
+```typescript
+// Enable/disable state
+entity.enabled = false;
+
+// Active state
+entity.active = false;
+
+// Update order (lower values have higher priority)
+entity.updateOrder = 10;
+```
+
+## Finding Entities
+
+The scene provides multiple ways to find entities:
+
+```typescript
+// Find by name
+const player = scene.findEntity("Player");
+// Or use alias
+const player2 = scene.getEntityByName("Player");
+
+// Find by ID
+const entity = scene.findEntityById(123);
+
+// Find all entities by tag
+const enemies = scene.findEntitiesByTag(2);
+// Or use alias
+const allEnemies = scene.getEntitiesByTag(2);
+
+// Find by handle
+const entity = scene.findEntityByHandle(handle);
+```
+
+## Entity Events
+
+Entity changes trigger events:
+
+```typescript
+// Listen for component additions
+scene.eventSystem.on('component:added', (data) => {
+    console.log(`${data.entityName} added ${data.componentType}`);
+});
+
+// Listen for component removals
+scene.eventSystem.on('component:removed', (data) => {
+    console.log(`${data.entityName} removed ${data.componentType}`);
+});
+
+// Listen for entity creation
+scene.eventSystem.on('entity:created', (data) => {
+    console.log(`Entity created: ${data.entityName}`);
+});
+
+// Listen for active state changes
+scene.eventSystem.on('entity:activeChanged', (data) => {
+    console.log(`${data.entity.name} active: ${data.active}`);
+});
+```
+
+## Debugging
+
+```typescript
+// Get entity debug info
+const debugInfo = entity.getDebugInfo();
+console.log(debugInfo);
+// {
+//   name: "Player",
+//   id: 1,
+//   persistentId: "a1b2c3d4-...",
+//   enabled: true,
+//   active: true,
+//   destroyed: false,
+//   componentCount: 3,
+//   componentTypes: ["Position", "Health", "Velocity"],
+//   ...
+// }
+
+// Entity string representation
+console.log(entity.toString());
+// "Entity[Player:1:a1b2c3d4]"
+```
+
+## Next Steps
+
+- [Component Operations](/en/guide/entity/component-operations/) - Add, get, and remove components
+- [Entity Handle](/en/guide/entity/entity-handle/) - Safe entity reference method
+- [Lifecycle](/en/guide/entity/lifecycle/) - Destruction and persistence

docs/src/content/docs/en/guide/entity/lifecycle.md

@@ -0,0 +1,238 @@
+---
+title: "Lifecycle"
+description: "Entity lifecycle management, destruction, and persistence"
+---
+
+Entity lifecycle includes three phases: creation, runtime, and destruction. This section covers how to properly manage entity lifecycles.
+
+## Destroying Entities
+
+### Basic Destruction
+
+```typescript
+// Destroy entity
+player.destroy();
+
+// Check if entity is destroyed
+if (player.isDestroyed) {
+    console.log("Entity has been destroyed");
+}
+```
+
+When destroying an entity:
+1. All components are removed (triggering `onRemovedFromEntity` callbacks)
+2. Entity is removed from query systems
+3. Entity is removed from scene entity list
+4. All reference tracking is cleaned up
+
+### Conditional Destruction
+
+```typescript
+// Common pattern: Destroy when health depleted
+const health = enemy.getComponent(Health);
+if (health && health.current <= 0) {
+    enemy.destroy();
+}
+```
+
+### Destruction Safety
+
+Destruction is idempotent—multiple calls won't cause errors:
+
+```typescript
+player.destroy();
+player.destroy();  // Safe, no error
+```
+
+## Persistent Entities
+
+By default, entities are destroyed during scene transitions. Persistence allows entities to survive across scenes.
+
+### Setting Persistence
+
+```typescript
+// Method 1: Chain call
+const player = scene.createEntity('Player')
+    .setPersistent()
+    .createComponent(PlayerComponent);
+
+// Method 2: Separate call
+player.setPersistent();
+
+// Check persistence
+if (player.isPersistent) {
+    console.log("This is a persistent entity");
+}
+```
+
+### Removing Persistence
+
+```typescript
+// Restore to scene-local entity
+player.setSceneLocal();
+```
+
+### Lifecycle Policies
+
+Entities have two lifecycle policies:
+
+| Policy | Description |
+|--------|-------------|
+| `SceneLocal` | Default, destroyed with scene |
+| `Persistent` | Survives scene transitions |
+
+```typescript
+import { EEntityLifecyclePolicy } from '@esengine/ecs-framework';
+
+// Get current policy
+const policy = entity.lifecyclePolicy;
+
+if (policy === EEntityLifecyclePolicy.Persistent) {
+    // Persistent entity
+}
+```
+
+### Use Cases
+
+Persistent entities are suitable for:
+- Player characters
+- Global managers
+- UI entities
+- Game state that needs to survive scene transitions
+
+```typescript
+// Player character
+const player = scene.createEntity('Player')
+    .setPersistent();
+
+// Game manager
+const gameManager = scene.createEntity('GameManager')
+    .setPersistent()
+    .createComponent(GameStateComponent);
+
+// Score manager
+const scoreManager = scene.createEntity('ScoreManager')
+    .setPersistent()
+    .createComponent(ScoreComponent);
+```
+
+## Scene Transition Behavior
+
+```typescript
+// Scene manager switches scenes
+sceneManager.loadScene('Level2');
+
+// During transition:
+// 1. SceneLocal entities are destroyed
+// 2. Persistent entities migrate to new scene
+// 3. New scene entities are created
+```
+
+:::caution[Note]
+Persistent entities automatically migrate to the new scene during transitions, but other non-persistent entities they reference may be destroyed. Use [EntityHandle](/en/guide/entity/entity-handle/) to safely handle this situation.
+:::
+
+## Reference Cleanup
+
+The framework provides reference tracking that automatically cleans up references when entities are destroyed:
+
+```typescript
+// Reference tracker cleans up all references to this entity on destruction
+scene.referenceTracker?.clearReferencesTo(entity.id);
+```
+
+Using the `@entityRef` decorator handles this automatically:
+
+```typescript
+class FollowComponent extends Component {
+    @entityRef()
+    targetId: number | null = null;
+}
+
+// When target is destroyed, targetId is automatically set to null
+```
+
+See [Component References](/en/guide/component/entity-ref/) for details.
+
+## Best Practices
+
+### 1. Destroy Unneeded Entities Promptly
+
+```typescript
+// Destroy bullets that fly off screen
+if (position.x < 0 || position.x > screenWidth) {
+    bullet.destroy();
+}
+```
+
+### 2. Use Object Pools Instead of Frequent Create/Destroy
+
+```typescript
+class BulletPool {
+    private pool: Entity[] = [];
+
+    acquire(scene: Scene): Entity {
+        if (this.pool.length > 0) {
+            const bullet = this.pool.pop()!;
+            bullet.enabled = true;
+            return bullet;
+        }
+        return scene.createEntity('Bullet');
+    }
+
+    release(bullet: Entity) {
+        bullet.enabled = false;
+        this.pool.push(bullet);
+    }
+}
+```
+
+### 3. Use Persistence Sparingly
+
+Only use persistence for entities that truly need to survive scene transitions—too many persistent entities increase memory usage.
+
+### 4. Clean Up References Before Destruction
+
+```typescript
+// Notify related systems before destruction
+const aiSystem = scene.getSystem(AISystem);
+aiSystem?.clearTarget(enemy.id);
+
+enemy.destroy();
+```
+
+## Lifecycle Events
+
+You can listen to entity destruction events:
+
+```typescript
+// Method 1: Through event system
+scene.eventSystem.on('entity:destroyed', (data) => {
+    console.log(`Entity ${data.entityName} destroyed`);
+});
+
+// Method 2: In component
+class MyComponent extends Component {
+    onRemovedFromEntity() {
+        console.log('Component removed, entity may be destroying');
+        // Clean up resources
+    }
+}
+```
+
+## Debugging
+
+```typescript
+// Get entity status
+const debugInfo = entity.getDebugInfo();
+console.log({
+    destroyed: debugInfo.destroyed,
+    enabled: debugInfo.enabled,
+    active: debugInfo.active
+});
+```
+
+## Next Steps
+
+- [Component Operations](/en/guide/entity/component-operations/) - Adding and removing components
+- [Scene Management](/en/guide/scene/) - Scene switching and management

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<void> {
+  console.log(`Saving game to slot ${data.saveSlot}`);
+  await this.saveGameData(data.saveSlot);
+  console.log('Game saved');
+}
+
+// Emit async event
+public async triggerSave(): Promise<void> {
+  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);
+    }
+  }
+}
+```

docs/src/content/docs/en/guide/getting-started.md

@@ -0,0 +1,443 @@
+---
+title: "Quick Start"
+---
+
+This guide will help you get started with ECS Framework, from installation to creating your first ECS application.
+
+## Installation
+
+### Using CLI (Recommended)
+
+The easiest way to add ECS to your existing project:
+
+```bash
+# In your project directory
+npx @esengine/cli init
+```
+
+The CLI automatically detects your project type (Cocos Creator 2.x/3.x, LayaAir 3.x, or Node.js) and generates the necessary integration code, including:
+
+- `ECSManager` component/script - Manages ECS lifecycle
+- Example components and systems - Helps you get started quickly
+- Automatic dependency installation
+
+### Manual NPM Installation
+
+If you prefer manual configuration:
+
+```bash
+# Using npm
+npm install @esengine/ecs-framework
+```
+
+## Initialize Core
+
+### Basic Initialization
+
+The core of ECS Framework is the `Core` class, a singleton that manages the entire framework lifecycle.
+
+```typescript
+import { Core } from '@esengine/ecs-framework'
+
+// Method 1: Using config object (recommended)
+const core = Core.create({
+  debug: true,                    // Enable debug mode for detailed logs and performance monitoring
+  debugConfig: {                 // Optional: Advanced debug configuration
+    enabled: false,               // Whether to enable WebSocket debug server
+    websocketUrl: 'ws://localhost:8080',
+    debugFrameRate: 30,          // Debug data send frame rate
+    channels: {
+      entities: true,
+      systems: true,
+      performance: true,
+      components: true,
+      scenes: true
+    }
+  }
+});
+
+// Method 2: Simplified creation (backward compatible)
+const core = Core.create(true);  // Equivalent to { debug: true }
+
+// Method 3: Production environment configuration
+const core = Core.create({
+  debug: false                   // Disable debug in production
+});
+```
+
+### Core Configuration Details
+
+```typescript
+interface ICoreConfig {
+  /** Enable debug mode - affects log level and performance monitoring */
+  debug?: boolean;
+
+  /** Advanced debug configuration - for dev tools integration */
+  debugConfig?: {
+    enabled: boolean;                    // Enable debug server
+    websocketUrl: string;               // WebSocket server URL
+    autoReconnect?: boolean;            // Auto reconnect
+    debugFrameRate?: 60 | 30 | 15;     // Debug data send frame rate
+    channels: {                         // Data channel configuration
+      entities: boolean;                // Entity data
+      systems: boolean;                 // System data
+      performance: boolean;             // Performance data
+      components: boolean;              // Component data
+      scenes: boolean;                  // Scene data
+    };
+  };
+}
+```
+
+### Core Instance Management
+
+Core uses singleton pattern, accessible via static property after creation:
+
+```typescript
+// Create instance
+const core = Core.create(true);
+
+// Get created instance
+const instance = Core.Instance;  // Returns current instance, null if not created
+```
+
+### Game Loop Integration
+
+**Important**: Before creating entities and systems, you need to understand how to integrate ECS Framework into your game engine.
+
+`Core.update(deltaTime)` is the framework heartbeat, must be called every frame. It handles:
+- Updating the built-in Time class
+- Updating all global managers (timers, object pools, etc.)
+- Updating all entity systems in all scenes
+- Processing entity creation and destruction
+- Collecting performance data (in debug mode)
+
+See engine integration examples: [Game Engine Integration](#game-engine-integration)
+
+## Create Your First ECS Application
+
+### 1. Define Components
+
+Components are pure data containers that store entity state:
+
+```typescript
+import { Component, ECSComponent } from '@esengine/ecs-framework'
+
+// Position component
+@ECSComponent('Position')
+class Position extends Component {
+  x: number = 0
+  y: number = 0
+
+  constructor(x: number = 0, y: number = 0) {
+    super()
+    this.x = x
+    this.y = y
+  }
+}
+
+// Velocity component
+@ECSComponent('Velocity')
+class Velocity extends Component {
+  dx: number = 0
+  dy: number = 0
+
+  constructor(dx: number = 0, dy: number = 0) {
+    super()
+    this.dx = dx
+    this.dy = dy
+  }
+}
+
+// Sprite component
+@ECSComponent('Sprite')
+class Sprite extends Component {
+  texture: string = ''
+  width: number = 32
+  height: number = 32
+
+  constructor(texture: string, width: number = 32, height: number = 32) {
+    super()
+    this.texture = texture
+    this.width = width
+    this.height = height
+  }
+}
+```
+
+### 2. Create Entity Systems
+
+Systems contain game logic and process entities with specific components. ECS Framework provides Matcher-based entity filtering:
+
+```typescript
+import { EntitySystem, Matcher, Time, ECSSystem } from '@esengine/ecs-framework'
+
+// Movement system - handles position and velocity
+@ECSSystem('MovementSystem')
+class MovementSystem extends EntitySystem {
+
+  constructor() {
+    // Use Matcher to define target entities: must have both Position and Velocity
+    super(Matcher.empty().all(Position, Velocity))
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    // process method receives all matching entities
+    for (const entity of entities) {
+      const position = entity.getComponent(Position)!
+      const velocity = entity.getComponent(Velocity)!
+
+      // Update position (using framework's Time class)
+      position.x += velocity.dx * Time.deltaTime
+      position.y += velocity.dy * Time.deltaTime
+
+      // Boundary check example
+      if (position.x < 0) position.x = 0
+      if (position.y < 0) position.y = 0
+    }
+  }
+}
+
+// Render system - handles visible objects
+@ECSSystem('RenderSystem')
+class RenderSystem extends EntitySystem {
+
+  constructor() {
+    // Must have Position and Sprite, optional Velocity (for direction)
+    super(Matcher.empty().all(Position, Sprite).any(Velocity))
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const position = entity.getComponent(Position)!
+      const sprite = entity.getComponent(Sprite)!
+      const velocity = entity.getComponent(Velocity) // May be null
+
+      // Flip sprite based on velocity direction (optional logic)
+      let flipX = false
+      if (velocity && velocity.dx < 0) {
+        flipX = true
+      }
+
+      // Render logic (pseudocode here)
+      this.drawSprite(sprite.texture, position.x, position.y, sprite.width, sprite.height, flipX)
+    }
+  }
+
+  private drawSprite(texture: string, x: number, y: number, width: number, height: number, flipX: boolean = false) {
+    // Actual render implementation depends on your game engine
+    const direction = flipX ? '<-' : '->'
+    console.log(`Render ${texture} at (${x.toFixed(1)}, ${y.toFixed(1)}) direction: ${direction}`)
+  }
+}
+```
+
+
+### 3. Create Scene
+
+Recommended to extend Scene class for custom scenes:
+
+```typescript
+import { Scene } from '@esengine/ecs-framework'
+
+// Recommended: Extend Scene for custom scene
+class GameScene extends Scene {
+
+  initialize(): void {
+    // Scene initialization logic
+    this.name = "MainScene";
+
+    // Add systems to scene
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+  }
+
+  onStart(): void {
+    // Logic when scene starts running
+    console.log("Game scene started");
+  }
+
+  unload(): void {
+    // Cleanup logic when scene unloads
+    console.log("Game scene unloaded");
+  }
+}
+
+// Create and set scene
+const gameScene = new GameScene();
+Core.setScene(gameScene);
+```
+
+### 4. Create Entities
+
+```typescript
+// Create player entity
+const player = gameScene.createEntity("Player");
+player.addComponent(new Position(100, 100));
+player.addComponent(new Velocity(50, 30));  // Move 50px/sec (x), 30px/sec (y)
+player.addComponent(new Sprite("player.png", 64, 64));
+```
+
+## Scene Management
+
+Core has built-in scene management, very simple to use:
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// Initialize Core
+Core.create({ debug: true });
+
+// Create and set scene
+class GameScene extends Scene {
+  initialize(): void {
+    this.name = "GamePlay";
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+  }
+}
+
+const gameScene = new GameScene();
+Core.setScene(gameScene);
+
+// Game loop (auto-updates scene)
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // Auto-updates global services and scene
+}
+
+// Switch scenes
+Core.loadScene(new MenuScene());  // Delayed switch (next frame)
+Core.setScene(new GameScene());   // Immediate switch
+
+// Access current scene
+const currentScene = Core.scene;
+
+// Using fluent API
+const player = Core.ecsAPI?.createEntity('Player')
+  .addComponent(Position, 100, 100)
+  .addComponent(Velocity, 50, 0);
+```
+
+### Advanced: Using WorldManager for Multi-World
+
+Only for complex server-side applications (MMO game servers, game room systems, etc.):
+
+```typescript
+import { Core, WorldManager } from '@esengine/ecs-framework';
+
+// Initialize Core
+Core.create({ debug: true });
+
+// Get WorldManager from service container (Core auto-creates and registers it)
+const worldManager = Core.services.resolve(WorldManager);
+
+// Create multiple independent game worlds
+const room1 = worldManager.createWorld('room_001');
+const room2 = worldManager.createWorld('room_002');
+
+// Create scenes in each world
+const gameScene1 = room1.createScene('game', new GameScene());
+const gameScene2 = room2.createScene('game', new GameScene());
+
+// Activate scenes
+room1.setSceneActive('game', true);
+room2.setSceneActive('game', true);
+
+// Game loop (need to manually update worlds)
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);       // Update global services
+  worldManager.updateAll();     // Manually update all worlds
+}
+```
+
+## Game Engine Integration
+
+### Laya 3.x Engine Integration
+
+Using `Laya.Script` component to manage ECS lifecycle is recommended:
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+const { regClass } = Laya;
+
+@regClass()
+export class ECSManager extends Laya.Script {
+  private ecsScene = new GameScene();
+
+  onAwake(): void {
+    // Initialize ECS
+    Core.create({ debug: true });
+    Core.setScene(this.ecsScene);
+  }
+
+  onUpdate(): void {
+    // Auto-updates global services and scene
+    Core.update(Laya.timer.delta / 1000);
+  }
+
+  onDestroy(): void {
+    // Cleanup resources
+    Core.destroy();
+  }
+}
+```
+
+In Laya IDE, attach the `ECSManager` script to a node in your scene.
+
+### Cocos Creator Integration
+
+```typescript
+import { Component, _decorator } from 'cc';
+import { Core } from '@esengine/ecs-framework';
+
+const { ccclass } = _decorator;
+
+@ccclass('ECSGameManager')
+export class ECSGameManager extends Component {
+  onLoad() {
+    // Initialize ECS
+    Core.create(true);
+    Core.setScene(new GameScene());
+  }
+
+  update(deltaTime: number) {
+    // Auto-updates global services and scene
+    Core.update(deltaTime);
+  }
+
+  onDestroy() {
+    // Cleanup resources
+    Core.destroy();
+  }
+}
+```
+
+
+## Next Steps
+
+You've successfully created your first ECS application! Next you can:
+
+- Check the complete [API Documentation](/api/README)
+- Explore more [practical examples](/examples/)
+
+## FAQ
+
+### Why isn't my system executing?
+
+Ensure:
+1. System is added to scene: `this.addSystem(system)` (in Scene's initialize method)
+2. Scene is set: `Core.setScene(scene)`
+3. Game loop is calling: `Core.update(deltaTime)`
+
+### How to debug ECS applications?
+
+Enable debug mode:
+
+```typescript
+Core.create({ debug: true })
+
+// Get debug data
+const debugData = Core.getDebugData()
+console.log(debugData)
+```

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)!;
+    }
+}
+```

docs/src/content/docs/en/guide/index.md

@@ -0,0 +1,45 @@
+---
+title: "Guide"
+---
+
+Welcome to the ECS Framework Guide. This guide covers the core concepts and usage of the framework.
+
+## Core Concepts
+
+### [Entity](/guide/entity)
+Learn the basics of ECS architecture - how to use entities, lifecycle management, and best practices.
+
+### [Component](/guide/component)
+Learn how to create and use components for modular game feature design.
+
+### [System](/guide/system)
+Master system development to implement game logic processing.
+
+### [Entity Query & Matcher](/guide/entity-query)
+Learn to use Matcher for entity filtering and queries with `all`, `any`, `none`, `nothing` conditions.
+
+### [Scene](/guide/scene)
+Understand scene lifecycle, system management, and entity container features.
+
+### [Event System](/guide/event-system)
+Master the type-safe event system for component communication and system coordination.
+
+### [Serialization](/guide/serialization)
+Master serialization for scenes, entities, and components. Supports full and incremental serialization for game saves, network sync, and more.
+
+### [Time and Timers](/guide/time-and-timers)
+Learn time management and timer systems for precise game logic timing control.
+
+### [Logging](/guide/logging)
+Master the leveled logging system for debugging, monitoring, and error tracking.
+
+### [Platform Adapter](/guide/platform-adapter)
+Learn how to implement and register platform adapters for browsers, mini-games, Node.js, and more.
+
+## Advanced Features
+
+### [Service Container](/guide/service-container)
+Master dependency injection and service management for loosely-coupled architecture.
+
+### [Plugin System](/guide/plugin-system)
+Learn how to develop and use plugins to extend framework functionality.

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();
+    }
+  }
+}
+```

docs/src/content/docs/en/guide/persistent-entity.md

@@ -0,0 +1,364 @@
+---
+title: "persistent-entity"
+---
+
+# Persistent Entity
+
+> **Version**: v2.3.0+
+
+Persistent Entity is a special type of entity that automatically migrates to the new scene during scene transitions. It is suitable for game objects that need to maintain state across scenes, such as players, game managers, audio managers, etc.
+
+## Basic Concepts
+
+In the ECS framework, entities have two lifecycle policies:
+
+| Policy | Description | Default |
+|--------|-------------|---------|
+| `SceneLocal` | Scene-local entity, destroyed when scene changes | ✓ |
+| `Persistent` | Persistent entity, automatically migrates during scene transitions | |
+
+## Quick Start
+
+### Creating a Persistent Entity
+
+```typescript
+import { Scene } from '@esengine/ecs-framework';
+
+class GameScene extends Scene {
+  protected initialize(): void {
+    // Create a persistent player entity
+    const player = this.createEntity('Player').setPersistent();
+    player.addComponent(new Position(100, 200));
+    player.addComponent(new PlayerData('Hero', 500));
+
+    // Create a normal enemy entity (destroyed when scene changes)
+    const enemy = this.createEntity('Enemy');
+    enemy.addComponent(new Position(300, 200));
+    enemy.addComponent(new EnemyAI());
+  }
+}
+```
+
+### Behavior During Scene Transitions
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// Initial scene
+class Level1Scene extends Scene {
+  protected initialize(): void {
+    // Player - persistent, will migrate to the next scene
+    const player = this.createEntity('Player').setPersistent();
+    player.addComponent(new Position(0, 0));
+    player.addComponent(new Health(100));
+
+    // Enemy - scene-local, destroyed when scene changes
+    const enemy = this.createEntity('Enemy');
+    enemy.addComponent(new Position(100, 100));
+  }
+}
+
+// Target scene
+class Level2Scene extends Scene {
+  protected initialize(): void {
+    // New enemy
+    const enemy = this.createEntity('Boss');
+    enemy.addComponent(new Position(200, 200));
+  }
+
+  public onStart(): void {
+    // Player has automatically migrated to this scene
+    const player = this.findEntity('Player');
+    console.log(player !== null); // true
+
+    // Position and health data are fully preserved
+    const position = player?.getComponent(Position);
+    const health = player?.getComponent(Health);
+    console.log(position?.x, position?.y); // 0, 0
+    console.log(health?.value); // 100
+  }
+}
+
+// Switch scenes
+Core.create({ debug: true });
+Core.setScene(new Level1Scene());
+
+// Later switch to Level2
+Core.loadScene(new Level2Scene());
+// Player entity migrates automatically, Enemy entity is destroyed
+```
+
+## API Reference
+
+### Entity Methods
+
+#### setPersistent()
+
+Marks the entity as persistent, preventing destruction during scene transitions.
+
+```typescript
+public setPersistent(): this
+```
+
+**Returns**: Returns the entity itself for method chaining
+
+**Example**:
+```typescript
+const player = scene.createEntity('Player')
+  .setPersistent();
+
+player.addComponent(new Position(100, 200));
+```
+
+#### setSceneLocal()
+
+Restores the entity to scene-local policy (default).
+
+```typescript
+public setSceneLocal(): this
+```
+
+**Returns**: Returns the entity itself for method chaining
+
+**Example**:
+```typescript
+// Dynamically cancel persistence
+player.setSceneLocal();
+```
+
+#### isPersistent
+
+Checks if the entity is persistent.
+
+```typescript
+public get isPersistent(): boolean
+```
+
+**Example**:
+```typescript
+if (entity.isPersistent) {
+  console.log('This is a persistent entity');
+}
+```
+
+#### lifecyclePolicy
+
+Gets the entity's lifecycle policy.
+
+```typescript
+public get lifecyclePolicy(): EEntityLifecyclePolicy
+```
+
+**Example**:
+```typescript
+import { EEntityLifecyclePolicy } from '@esengine/ecs-framework';
+
+if (entity.lifecyclePolicy === EEntityLifecyclePolicy.Persistent) {
+  console.log('Persistent entity');
+}
+```
+
+### Scene Methods
+
+#### findPersistentEntities()
+
+Finds all persistent entities in the scene.
+
+```typescript
+public findPersistentEntities(): Entity[]
+```
+
+**Returns**: Array of persistent entities
+
+**Example**:
+```typescript
+const persistentEntities = scene.findPersistentEntities();
+console.log(`Scene has ${persistentEntities.length} persistent entities`);
+```
+
+#### extractPersistentEntities()
+
+Extracts and removes all persistent entities from the scene (typically called internally by the framework).
+
+```typescript
+public extractPersistentEntities(): Entity[]
+```
+
+**Returns**: Array of extracted persistent entities
+
+#### receiveMigratedEntities()
+
+Receives migrated entities (typically called internally by the framework).
+
+```typescript
+public receiveMigratedEntities(entities: Entity[]): void
+```
+
+**Parameters**:
+- `entities` - Array of entities to receive
+
+## Use Cases
+
+### 1. Player Entity Across Levels
+
+```typescript
+class PlayerSetupScene extends Scene {
+  protected initialize(): void {
+    // Player maintains state across all levels
+    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 { /* ... */ }
+
+// Player entity automatically migrates between all levels
+Core.setScene(new PlayerSetupScene());
+// ... game progresses
+Core.loadScene(new Level1());
+// ... level complete
+Core.loadScene(new Level2());
+// Player data (health, inventory, stats) fully preserved
+```
+
+### 2. Global Managers
+
+```typescript
+class BootstrapScene extends Scene {
+  protected initialize(): void {
+    // Audio manager - persists across scenes
+    const audioManager = this.createEntity('AudioManager').setPersistent();
+    audioManager.addComponent(new AudioController());
+
+    // Achievement manager - persists across scenes
+    const achievementManager = this.createEntity('AchievementManager').setPersistent();
+    achievementManager.addComponent(new AchievementTracker());
+
+    // Game settings - persists across scenes
+    const settings = this.createEntity('GameSettings').setPersistent();
+    settings.addComponent(new SettingsData());
+  }
+}
+```
+
+### 3. Dynamically Toggling Persistence
+
+```typescript
+class GameScene extends Scene {
+  protected initialize(): void {
+    // Initially created as a normal entity
+    const companion = this.createEntity('Companion');
+    companion.addComponent(new Transform(0, 0));
+    companion.addComponent(new CompanionAI());
+
+    // Listen for recruitment event
+    this.eventSystem.on('companion:recruited', () => {
+      // After recruitment, become persistent
+      companion.setPersistent();
+      console.log('Companion joined the party, will follow player across scenes');
+    });
+
+    // Listen for dismissal event
+    this.eventSystem.on('companion:dismissed', () => {
+      // After dismissal, restore to scene-local
+      companion.setSceneLocal();
+      console.log('Companion left the party, will no longer persist across scenes');
+    });
+  }
+}
+```
+
+## Best Practices
+
+### 1. Clearly Identify Persistent Entities
+
+```typescript
+// Recommended: Mark immediately when creating
+const player = this.createEntity('Player').setPersistent();
+
+// Not recommended: Marking after creation (easy to forget)
+const player = this.createEntity('Player');
+// ... lots of code ...
+player.setPersistent(); // Easy to forget
+```
+
+### 2. Use Persistence Appropriately
+
+```typescript
+// ✓ Entities suitable for persistence
+const player = this.createEntity('Player').setPersistent();      // Player
+const gameManager = this.createEntity('GameManager').setPersistent(); // Global manager
+const audioManager = this.createEntity('AudioManager').setPersistent(); // Audio system
+
+// ✗ Entities that should NOT be persistent
+const bullet = this.createEntity('Bullet'); // Temporary objects
+const enemy = this.createEntity('Enemy');   // Level-specific enemies
+const particle = this.createEntity('Particle'); // Effect particles
+```
+
+### 3. Check Migrated Entities
+
+```typescript
+class NewScene extends Scene {
+  public onStart(): void {
+    // Check if expected persistent entities exist
+    const player = this.findEntity('Player');
+    if (!player) {
+      console.error('Player entity did not migrate correctly!');
+      // Handle error case
+    }
+  }
+}
+```
+
+### 4. Avoid Circular References
+
+```typescript
+// ✗ Avoid: Persistent entity referencing scene-local entity
+class BadScene extends Scene {
+  protected initialize(): void {
+    const player = this.createEntity('Player').setPersistent();
+    const enemy = this.createEntity('Enemy');
+
+    // Dangerous: player is persistent but enemy is not
+    // After scene change, enemy is destroyed, reference becomes invalid
+    player.addComponent(new TargetComponent(enemy));
+  }
+}
+
+// ✓ Recommended: Use ID references or event system
+class GoodScene extends Scene {
+  protected initialize(): void {
+    const player = this.createEntity('Player').setPersistent();
+    const enemy = this.createEntity('Enemy');
+
+    // Store ID instead of direct reference
+    player.addComponent(new TargetComponent(enemy.id));
+
+    // Or use event system for communication
+  }
+}
+```
+
+## Important Notes
+
+1. **Destroyed entities will not migrate**: If an entity is destroyed before scene transition, it will not migrate even if marked as persistent.
+
+2. **Component data is fully preserved**: All components and their state are preserved during migration.
+
+3. **Scene reference is updated**: After migration, the entity's `scene` property will point to the new scene.
+
+4. **Query system is updated**: Migrated entities are automatically registered in the new scene's query system.
+
+5. **Delayed transitions also work**: Persistent entities migrate when using `Core.loadScene()` for delayed transitions as well.
+
+## Related Documentation
+
+- [Scene](./scene) - Learn the basics of scenes
+- [SceneManager](./scene-manager) - Learn about scene transitions
+- [WorldManager](./world-manager) - Learn about multi-world management

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<PlatformConfig>;
+}
+```
+
+### 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');
+}
+```

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
+<!-- Set in HTML -->
+<meta http-equiv="Cross-Origin-Opener-Policy" content="same-origin">
+<meta http-equiv="Cross-Origin-Embedder-Policy" content="require-corp">
+```
+
+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());
+```

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!));
+```

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 <dir>` | Source code directory | `./src` |
+| `-o, --out <dir>` | Output directory | `./workers` |
+| `-w, --wechat` | Generate WeChat Mini Game compatible code | `false` |
+| `-m, --mapping` | Generate worker-mapping.json | `true` |
+| `-t, --tsconfig <path>` | 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<PhysicsData> {
+    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<PhysicsData> {
+    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);
+```

docs/src/content/docs/en/guide/plugin-system/best-practices.md

@@ -0,0 +1,151 @@
+---
+title: "Best Practices"
+description: "Plugin design guidelines and common issues"
+---
+
+## Naming Convention
+
+```typescript
+class MyPlugin implements IPlugin {
+  // Use lowercase letters and hyphens
+  readonly name = 'my-awesome-plugin';  // OK
+
+  // Follow semantic versioning
+  readonly version = '1.0.0';           // OK
+}
+```
+
+## 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 {
+    // Clear 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
+
+```typescript
+class MyPlugin implements IPlugin {
+  readonly name = 'my-plugin';
+  readonly version = '1.0.0';
+
+  async install(core: Core, services: ServiceContainer): Promise<void> {
+    try {
+      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<void> {
+    try {
+      await this.cleanup();
+    } catch (error) {
+      console.error('Failed to cleanup plugin:', error);
+      // Don't block uninstall even if cleanup fails
+    }
+  }
+
+  private async loadConfig() { /* ... */ }
+  private async 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 {}
+}
+
+// Usage
+const plugin = new NetworkPlugin({
+  serverUrl: 'ws://localhost:8080',
+  autoReconnect: true,
+  timeout: 5000
+});
+
+await Core.installPlugin(plugin);
+```
+
+## Common Issues
+
+### Plugin Installation Failed
+
+**Causes**:
+- Dependencies not satisfied
+- Exception in install method
+- Service registration conflict
+
+**Solutions**:
+1. Check if dependencies are installed
+2. Review error logs
+3. Ensure service names don't conflict
+
+### Side Effects After Uninstall
+
+**Cause**: Resources not properly cleaned in uninstall
+
+**Solution**: Ensure uninstall cleans up:
+- Timers
+- Event listeners
+- WebSocket connections
+- System references
+
+### When to Use Plugins
+
+| Good for Plugins | Not Good for Plugins |
+|------------------|---------------------|
+| Optional features (debug tools, profiling) | Core game logic |
+| Third-party integration (network libs, physics) | Simple utilities |
+| Cross-project reusable modules | Project-specific features |

docs/src/content/docs/en/guide/plugin-system/dependencies.md

@@ -0,0 +1,106 @@
+---
+title: "Dependency Management"
+description: "Declare and check plugin dependencies"
+---
+
+## 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 from physics-plugin
+    const physicsService = services.resolve(PhysicsService);
+    // ...
+  }
+
+  uninstall(): void {
+    // Cleanup
+  }
+}
+```
+
+## Dependency Checking
+
+The framework automatically checks dependencies and throws an error if not satisfied:
+
+```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 dependencies to prevent uninstalling plugins required by others:
+
+```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');
+```
+
+## Dependency Graph Example
+
+```
+physics-plugin (base)
+    ↑
+advanced-physics (depends on physics-plugin)
+    ↑
+game-physics (depends on advanced-physics)
+```
+
+Install order: `physics-plugin` → `advanced-physics` → `game-physics`
+
+Uninstall order: `game-physics` → `advanced-physics` → `physics-plugin`
+
+## Multiple Dependencies
+
+```typescript
+class GamePlugin implements IPlugin {
+  readonly name = 'game';
+  readonly version = '1.0.0';
+
+  // Declare multiple dependencies
+  readonly dependencies = [
+    'physics-plugin',
+    'network-plugin',
+    'audio-plugin'
+  ] as const;
+
+  install(core: Core, services: ServiceContainer): void {
+    // All dependencies are available
+    const physics = services.resolve(PhysicsService);
+    const network = services.resolve(NetworkService);
+    const audio = services.resolve(AudioService);
+  }
+
+  uninstall(): void {}
+}
+```

docs/src/content/docs/en/guide/plugin-system/development.md

@@ -0,0 +1,139 @@
+---
+title: "Plugin Development"
+description: "IPlugin interface and lifecycle"
+---
+
+## 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<void>;
+
+  // Called when plugin is uninstalled
+  uninstall(): void | Promise<void>;
+}
+```
+
+## Lifecycle Methods
+
+### install Method
+
+Called when the plugin is installed, used for initialization:
+
+```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
+    console.log('Plugin initialized');
+  }
+
+  uninstall(): void {
+    // Cleanup logic
+  }
+}
+```
+
+### uninstall Method
+
+Called when the plugin is uninstalled, used for cleanup:
+
+```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 {
+    // Cleanup service
+    if (this.myService) {
+      this.myService.dispose();
+      this.myService = undefined;
+    }
+
+    // Remove event listeners
+    // Release other resources
+  }
+}
+```
+
+## Async Plugins
+
+Both `install` and `uninstall` methods support async:
+
+```typescript
+class AsyncPlugin implements IPlugin {
+  readonly name = 'async-plugin';
+  readonly version = '1.0.0';
+
+  async install(core: Core, services: ServiceContainer): Promise<void> {
+    // Async load resources
+    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<void> {
+    // Async cleanup
+    await this.saveState();
+  }
+
+  private async saveState() {
+    // Save plugin state
+  }
+}
+
+// Usage
+await Core.installPlugin(new AsyncPlugin());
+```
+
+## Lifecycle Flow
+
+```
+Install: Core.installPlugin(plugin)
+  ↓
+Dependency check: Verify dependencies are satisfied
+  ↓
+Call install(): Register services, add systems
+  ↓
+State update: Mark as installed
+
+Uninstall: Core.uninstallPlugin(name)
+  ↓
+Dependency check: Verify not required by other plugins
+  ↓
+Call uninstall(): Cleanup resources
+  ↓
+State update: Remove from plugin list
+```

docs/src/content/docs/en/guide/plugin-system/examples.md

@@ -0,0 +1,188 @@
+---
+title: "Example Plugins"
+description: "Complete plugin implementation 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();
+
+    // Periodic 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`);
+  }
+}
+```
+
+## Debug Tools Plugin
+
+```typescript
+class DebugToolsPlugin implements IPlugin {
+  readonly name = 'debug-tools';
+  readonly version = '1.0.0';
+  private debugUI?: DebugUI;
+
+  install(core: Core, services: ServiceContainer): void {
+    // Create debug UI
+    this.debugUI = new DebugUI();
+    this.debugUI.mount(document.body);
+
+    // Register hotkey
+    window.addEventListener('keydown', this.handleKeyDown);
+
+    // Add debug system
+    const scene = core.scene;
+    if (scene) {
+      scene.addSystem(new DebugRenderSystem());
+    }
+  }
+
+  uninstall(): void {
+    // Remove UI
+    if (this.debugUI) {
+      this.debugUI.unmount();
+      this.debugUI = undefined;
+    }
+
+    // Remove event listener
+    window.removeEventListener('keydown', this.handleKeyDown);
+  }
+
+  private handleKeyDown = (e: KeyboardEvent) => {
+    if (e.key === 'F12') {
+      this.debugUI?.toggle();
+    }
+  };
+}
+```
+
+## Audio Plugin
+
+```typescript
+class AudioPlugin implements IPlugin {
+  readonly name = 'audio';
+  readonly version = '1.0.0';
+
+  constructor(private config: { volume: number }) {}
+
+  install(core: Core, services: ServiceContainer): void {
+    const audioService = new AudioService(this.config);
+    services.registerInstance(AudioService, audioService);
+
+    // Add audio system
+    const scene = core.scene;
+    if (scene) {
+      scene.addSystem(new AudioSystem());
+    }
+  }
+
+  uninstall(): void {
+    // Stop all audio
+    const audio = Core.services.resolve(AudioService);
+    audio.stopAll();
+  }
+}
+
+// Usage
+await Core.installPlugin(new AudioPlugin({ volume: 0.8 }));
+```
+
+## Input Manager Plugin
+
+```typescript
+class InputPlugin implements IPlugin {
+  readonly name = 'input';
+  readonly version = '1.0.0';
+  private inputManager?: InputManager;
+
+  install(core: Core, services: ServiceContainer): void {
+    this.inputManager = new InputManager();
+    services.registerInstance(InputManager, this.inputManager);
+
+    // Bind default keys
+    this.inputManager.bind('jump', ['Space', 'KeyW']);
+    this.inputManager.bind('attack', ['MouseLeft', 'KeyJ']);
+
+    // Add input system
+    const scene = core.scene;
+    if (scene) {
+      scene.addSystem(new InputSystem());
+    }
+  }
+
+  uninstall(): void {
+    if (this.inputManager) {
+      this.inputManager.dispose();
+      this.inputManager = undefined;
+    }
+  }
+}
+```

docs/src/content/docs/en/guide/plugin-system/index.md

@@ -0,0 +1,85 @@
+---
+title: "Plugin System"
+description: "Extend ECS Framework in a modular way"
+---
+
+The plugin system allows you to extend ECS Framework functionality in a modular way. Through plugins, you can encapsulate specific features (like network sync, physics engines, debug tools) and reuse them across multiple projects.
+
+## 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
+
+## Plugin Benefits
+
+| Benefit | Description |
+|---------|-------------|
+| **Modular** | Encapsulate functionality as independent modules |
+| **Reusable** | Use the same plugin across multiple projects |
+| **Decoupled** | Separate core framework from extensions |
+| **Hot-swappable** | Dynamically install and uninstall at runtime |
+
+## Quick Start
+
+### Create a 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');
+  }
+
+  uninstall(): void {
+    console.log('Debug plugin uninstalled');
+  }
+}
+```
+
+### Install a Plugin
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+
+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');
+}
+```
+
+### Uninstall a Plugin
+
+```typescript
+await Core.uninstallPlugin('debug-plugin');
+```
+
+### Get Plugin Instance
+
+```typescript
+const plugin = Core.getPlugin('debug-plugin');
+if (plugin) {
+  console.log(`Plugin version: ${plugin.version}`);
+}
+```
+
+## Next Steps
+
+- [Development](./development/) - IPlugin interface and lifecycle
+- [Services & Systems](./services-systems/) - Register services and add systems
+- [Dependencies](./dependencies/) - Declare and check dependencies
+- [Management](./management/) - Manage via Core and PluginManager
+- [Examples](./examples/) - Complete examples
+- [Best Practices](./best-practices/) - Design guidelines

docs/src/content/docs/en/guide/plugin-system/management.md

@@ -0,0 +1,93 @@
+---
+title: "Plugin Management"
+description: "Manage plugins via Core and PluginManager"
+---
+
+## Via Core
+
+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');
+```
+
+## 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}`);
+}
+```
+
+## API Reference
+
+### Core Static Methods
+
+| Method | Description |
+|--------|-------------|
+| `installPlugin(plugin)` | Install plugin |
+| `uninstallPlugin(name)` | Uninstall plugin |
+| `isPluginInstalled(name)` | Check if installed |
+| `getPlugin(name)` | Get plugin instance |
+
+### PluginManager Methods
+
+| Method | Description |
+|--------|-------------|
+| `getAllPlugins()` | Get all plugins |
+| `getMetadata(name)` | Get plugin metadata |
+| `getAllMetadata()` | Get all plugin metadata |
+
+## Plugin States
+
+```typescript
+enum PluginState {
+  Pending = 'pending',
+  Installing = 'installing',
+  Installed = 'installed',
+  Uninstalling = 'uninstalling',
+  Failed = 'failed'
+}
+```
+
+## Metadata Information
+
+```typescript
+interface PluginMetadata {
+  name: string;
+  version: string;
+  state: PluginState;
+  dependencies?: string[];
+  installedAt?: number;
+  error?: Error;
+}
+```

docs/src/content/docs/en/guide/plugin-system/services-systems.md

@@ -0,0 +1,133 @@
+---
+title: "Services & Systems"
+description: "Register services and add systems in plugins"
+---
+
+## 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 will auto-call service's dispose method
+  }
+}
+```
+
+## Service Registration Methods
+
+| Method | Description |
+|--------|-------------|
+| `registerSingleton(Type)` | Register singleton service |
+| `registerInstance(Type, instance)` | Register existing instance |
+| `registerTransient(Type)` | Create new instance per resolve |
+
+## 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;
+    }
+  }
+}
+```
+
+## Combined Usage
+
+```typescript
+class GamePlugin implements IPlugin {
+  readonly name = 'game-plugin';
+  readonly version = '1.0.0';
+  private systems: EntitySystem[] = [];
+
+  install(core: Core, services: ServiceContainer): void {
+    // 1. Register services
+    services.registerSingleton(ScoreService);
+    services.registerSingleton(AudioService);
+
+    // 2. Add systems
+    const scene = core.scene;
+    if (scene) {
+      const systems = [
+        new InputSystem(),
+        new MovementSystem(),
+        new ScoringSystem()
+      ];
+
+      systems.forEach(system => {
+        scene.addSystem(system);
+        this.systems.push(system);
+      });
+    }
+  }
+
+  uninstall(): void {
+    // Remove all systems
+    const scene = Core.scene;
+    if (scene) {
+      this.systems.forEach(system => {
+        scene.removeSystem(system);
+      });
+    }
+    this.systems = [];
+  }
+}
+```

docs/src/content/docs/en/guide/scene-manager.md

@@ -0,0 +1,440 @@
+---
+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.
+
+## Use Cases
+
+SceneManager is suitable for:
+- Single-player games
+- Simple multiplayer games
+- Mobile games
+- Games requiring scene transitions (menu, game, pause, etc.)
+- Projects that don't need multi-World isolation
+
+## Features
+
+- Lightweight, zero extra overhead
+- Simple and intuitive API
+- Supports delayed scene transitions (avoids switching mid-frame)
+- Automatic ECS fluent API management
+- Automatic scene lifecycle handling
+- Integrated with Core, auto-updated
+- Supports [Persistent Entity](./persistent-entity) migration across scenes (v2.3.0+)
+
+## Basic Usage
+
+### Recommended: Using Core's Static Methods
+
+This is the simplest and recommended approach, suitable for most applications:
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// 1. Initialize Core
+Core.create({ debug: true });
+
+// 2. Create and set scene
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // Add systems
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+
+    // Create initial entities
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Health(100));
+  }
+
+  public onStart(): void {
+    console.log("Game scene started");
+  }
+}
+
+// 3. Set scene
+Core.setScene(new GameScene());
+
+// 4. Game loop (Core.update automatically updates the scene)
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // Automatically updates all services and scenes
+}
+
+// Laya engine integration
+Laya.timer.frameLoop(1, this, () => {
+  const deltaTime = Laya.timer.delta / 1000;
+  Core.update(deltaTime);
+});
+
+// Cocos Creator integration
+update(deltaTime: number) {
+  Core.update(deltaTime);
+}
+```
+
+### Advanced: Using SceneManager Directly
+
+If you need more control, you can use SceneManager directly:
+
+```typescript
+import { Core, SceneManager, Scene } from '@esengine/ecs-framework';
+
+// Initialize Core
+Core.create({ debug: true });
+
+// Get SceneManager (already auto-created and registered by Core)
+const sceneManager = Core.services.resolve(SceneManager);
+
+// Set scene
+const gameScene = new GameScene();
+sceneManager.setScene(gameScene);
+
+// Game loop (still use Core.update)
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // Core automatically calls sceneManager.update()
+}
+```
+
+**Important**: Regardless of which approach you use, you should only call `Core.update()` in the game loop. It automatically updates SceneManager and scenes. You don't need to manually call `sceneManager.update()`.
+
+## Scene Transitions
+
+### Immediate Transition
+
+Use `Core.setScene()` or `sceneManager.setScene()` to immediately switch scenes:
+
+```typescript
+// Method 1: Using Core (recommended)
+Core.setScene(new MenuScene());
+
+// Method 2: Using SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new MenuScene());
+```
+
+### Delayed Transition
+
+Use `Core.loadScene()` or `sceneManager.loadScene()` for delayed scene transition, which takes effect on the next frame:
+
+```typescript
+// Method 1: Using Core (recommended)
+Core.loadScene(new GameOverScene());
+
+// Method 2: Using SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.loadScene(new GameOverScene());
+```
+
+When switching scenes from within a System, use delayed transitions:
+
+```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) {
+      // Delayed transition to game over scene (takes effect next frame)
+      Core.loadScene(new GameOverScene());
+      // Current frame continues execution, won't interrupt current system processing
+    }
+  }
+}
+```
+
+## API Reference
+
+### Core Static Methods (Recommended)
+
+#### Core.setScene()
+
+Immediately switch scenes.
+
+```typescript
+public static setScene<T extends IScene>(scene: T): T
+```
+
+**Parameters**:
+- `scene` - The scene instance to set
+
+**Returns**:
+- Returns the set scene instance
+
+**Example**:
+```typescript
+const gameScene = Core.setScene(new GameScene());
+console.log(gameScene.name);
+```
+
+#### Core.loadScene()
+
+Delayed scene loading (switches on next frame).
+
+```typescript
+public static loadScene<T extends IScene>(scene: T): void
+```
+
+**Parameters**:
+- `scene` - The scene instance to load
+
+**Example**:
+```typescript
+Core.loadScene(new GameOverScene());
+```
+
+#### Core.scene
+
+Get the currently active scene.
+
+```typescript
+public static get scene(): IScene | null
+```
+
+**Returns**:
+- Current scene instance, or null if no scene
+
+**Example**:
+```typescript
+const currentScene = Core.scene;
+if (currentScene) {
+  console.log(`Current scene: ${currentScene.name}`);
+}
+```
+
+### SceneManager Methods (Advanced)
+
+If you need to use SceneManager directly, get it through the service container:
+
+```typescript
+const sceneManager = Core.services.resolve(SceneManager);
+```
+
+#### setScene()
+
+Immediately switch scenes.
+
+```typescript
+public setScene<T extends IScene>(scene: T): T
+```
+
+#### loadScene()
+
+Delayed scene loading.
+
+```typescript
+public loadScene<T extends IScene>(scene: T): void
+```
+
+#### currentScene
+
+Get the current scene.
+
+```typescript
+public get currentScene(): IScene | null
+```
+
+#### hasScene
+
+Check if there's an active scene.
+
+```typescript
+public get hasScene(): boolean
+```
+
+#### hasPendingScene
+
+Check if there's a pending scene transition.
+
+```typescript
+public get hasPendingScene(): boolean
+```
+
+## Best Practices
+
+### 1. Use Core's Static Methods
+
+```typescript
+// Recommended: Use Core's static methods
+Core.setScene(new GameScene());
+Core.loadScene(new MenuScene());
+const currentScene = Core.scene;
+
+// Not recommended: Don't directly use SceneManager unless you have special needs
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new GameScene());
+```
+
+### 2. Only Call Core.update()
+
+```typescript
+// Correct: Only call Core.update()
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // Automatically updates all services and scenes
+}
+
+// Incorrect: Don't manually call sceneManager.update()
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);
+  sceneManager.update();  // Duplicate update, will cause issues!
+}
+```
+
+### 3. Use Delayed Transitions to Avoid Issues
+
+When switching scenes from within a System, use `loadScene()` instead of `setScene()`:
+
+```typescript
+// Recommended: Delayed transition
+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());
+        // Current frame continues processing other entities
+      }
+    }
+  }
+}
+
+// Not recommended: Immediate transition may cause issues
+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());
+        // Scene switches immediately, other entities in current frame may not process correctly
+      }
+    }
+  }
+}
+```
+
+### 4. Scene Responsibility Separation
+
+Each scene should be responsible for only one specific game state:
+
+```typescript
+// Good design - clear responsibilities
+class MenuScene extends Scene {
+  // Only handles menu-related logic
+}
+
+class GameScene extends Scene {
+  // Only handles gameplay logic
+}
+
+class PauseScene extends Scene {
+  // Only handles pause screen logic
+}
+
+// Avoid this design - mixed responsibilities
+class MegaScene extends Scene {
+  // Contains menu, game, pause, and all other logic
+}
+```
+
+### 5. Resource Management
+
+Clean up resources in the scene's `unload()` method:
+
+```typescript
+class GameScene extends Scene {
+  private textures: Map<string, any> = new Map();
+  private sounds: Map<string, any> = 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 {
+    // Cleanup resources
+    this.textures.clear();
+    this.sounds.clear();
+    console.log('Scene resources cleaned up');
+  }
+}
+```
+
+### 6. Event-Driven Scene Transitions
+
+Use the event system to trigger scene transitions, keeping code decoupled:
+
+```typescript
+class GameScene extends Scene {
+  protected initialize(): void {
+    // Listen to scene transition events
+    this.eventSystem.on('goto:menu', () => {
+      Core.loadScene(new MenuScene());
+    });
+
+    this.eventSystem.on('goto:gameover', (data) => {
+      Core.loadScene(new GameOverScene());
+    });
+  }
+}
+
+// Trigger events in System
+class GameLogicSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    if (levelComplete) {
+      this.scene.eventSystem.emitSync('goto:gameover', {
+        score: 1000,
+        level: 5
+      });
+    }
+  }
+}
+```
+
+## Architecture Overview
+
+SceneManager's position in ECS Framework:
+
+```
+Core (Global Services)
+  └── SceneManager (Scene Management, auto-updated)
+      └── Scene (Current Scene)
+          ├── EntitySystem (Systems)
+          ├── Entity (Entities)
+          └── Component (Components)
+```
+
+## Comparison with WorldManager
+
+| Feature | SceneManager | WorldManager |
+|---------|--------------|--------------|
+| Use Case | 95% of game applications | Advanced multi-world isolation scenarios |
+| Complexity | Simple | Complex |
+| Scene Count | Single scene (switchable) | Multiple Worlds, each with multiple scenes |
+| Performance Overhead | Minimal | Higher |
+| Usage | `Core.setScene()` | `worldManager.createWorld()` |
+
+**When to use SceneManager**:
+- Single-player games
+- Simple multiplayer games
+- Mobile games
+- Scenes that need transitions but don't need to run simultaneously
+
+**When to use WorldManager**:
+- MMO game servers (one World per room)
+- Game lobby systems (complete isolation per game room)
+- Need to run multiple completely independent game instances
+
+## Related Documentation
+
+- [Persistent Entity](./persistent-entity) - Learn how to keep entities across scene transitions
+- [WorldManager](./world-manager) - Learn about advanced multi-world isolation features
+
+SceneManager provides simple yet powerful scene management capabilities for most games. Through Core's static methods, you can easily manage scene transitions.

docs/src/content/docs/en/guide/scene/best-practices.md

@@ -0,0 +1,179 @@
+---
+title: "Best Practices"
+description: "Scene design patterns and complete examples"
+---
+
+## Scene Responsibility Separation
+
+```typescript
+// Good scene design - clear responsibilities
+class MenuScene extends Scene {
+  // Only handles menu-related logic
+}
+
+class GameScene extends Scene {
+  // Only handles gameplay logic
+}
+
+class InventoryScene extends Scene {
+  // Only handles inventory logic
+}
+
+// Avoid this design - mixed responsibilities
+class MegaScene extends Scene {
+  // Contains menu, game, inventory, and all other logic
+}
+```
+
+## Resource Management
+
+```typescript
+class ResourceScene extends Scene {
+  private textures: Map<string, any> = new Map();
+  private sounds: Map<string, any> = new Map();
+
+  protected initialize(): void {
+    this.loadResources();
+  }
+
+  private loadResources(): void {
+    this.textures.set('player', this.loadTexture('player.png'));
+    this.sounds.set('bgm', this.loadSound('bgm.mp3'));
+  }
+
+  public unload(): void {
+    // Cleanup resources
+    this.textures.clear();
+    this.sounds.clear();
+    console.log('Scene resources cleaned up');
+  }
+
+  private loadTexture(path: string): any { return null; }
+  private loadSound(path: string): any { return null; }
+}
+```
+
+## Initialization Order
+
+```typescript
+class ProperInitScene extends Scene {
+  protected initialize(): void {
+    // 1. First set scene configuration
+    this.name = "GameScene";
+
+    // 2. Then add systems (by dependency order)
+    this.addSystem(new InputSystem());
+    this.addSystem(new MovementSystem());
+    this.addSystem(new PhysicsSystem());
+    this.addSystem(new RenderSystem());
+
+    // 3. Create entities last
+    this.createEntities();
+
+    // 4. Setup event listeners
+    this.setupEvents();
+  }
+
+  private createEntities(): void { /* ... */ }
+  private setupEvents(): void { /* ... */ }
+}
+```
+
+## Complete Example
+
+```typescript
+import { Scene, EntitySystem, Entity, Matcher } from '@esengine/ecs-framework';
+
+// Define components
+class Transform {
+  constructor(public x: number, public y: number) {}
+}
+
+class Velocity {
+  constructor(public vx: number, public vy: number) {}
+}
+
+class Health {
+  constructor(public value: number) {}
+}
+
+// Define system
+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;
+      }
+    }
+  }
+}
+
+// Define scene
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // Add systems
+    this.addSystem(new MovementSystem());
+
+    // Create player
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Velocity(0, 0));
+    player.addComponent(new Health(100));
+
+    // Create enemies
+    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));
+    }
+
+    // Setup event listeners
+    this.eventSystem.on('player_died', () => {
+      console.log('Player died!');
+    });
+  }
+
+  public onStart(): void {
+    console.log('Game scene started');
+  }
+
+  public unload(): void {
+    console.log('Game scene unloaded');
+    this.eventSystem.clear();
+  }
+}
+
+// Use scene
+import { Core, SceneManager } from '@esengine/ecs-framework';
+
+Core.create({ debug: true });
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new GameScene());
+```
+
+## Design Principles
+
+| Principle | Description |
+|-----------|-------------|
+| Single Responsibility | Each scene handles one game state |
+| Resource Cleanup | Clean up all resources in `unload()` |
+| System Order | Add systems: Input → Logic → Render |
+| Event Decoupling | Use event system for scene communication |
+| Layered Initialization | Config → Systems → Entities → Events |

docs/src/content/docs/en/guide/scene/debugging.md

@@ -0,0 +1,124 @@
+---
+title: "Debugging & Monitoring"
+description: "Scene statistics, performance monitoring and debugging"
+---
+
+Scene includes complete debugging and performance monitoring features.
+
+## Scene Statistics
+
+```typescript
+class StatsScene extends Scene {
+  public showStats(): void {
+    const stats = this.getStats();
+    console.log(`Entity count: ${stats.entityCount}`);
+    console.log(`System count: ${stats.processorCount}`);
+    console.log('Component storage stats:', stats.componentStorageStats);
+  }
+}
+```
+
+## Debug Information
+
+```typescript
+public showDebugInfo(): void {
+  const debugInfo = this.getDebugInfo();
+  console.log('Scene debug info:', debugInfo);
+
+  // Display all entity info
+  debugInfo.entities.forEach(entity => {
+    console.log(`Entity ${entity.name}(${entity.id}): ${entity.componentCount} components`);
+    console.log('Component types:', entity.componentTypes);
+  });
+
+  // Display all system info
+  debugInfo.processors.forEach(processor => {
+    console.log(`System ${processor.name}: processing ${processor.entityCount} entities`);
+  });
+}
+```
+
+## Performance Monitoring
+
+```typescript
+class PerformanceScene extends Scene {
+  public showPerformance(): void {
+    // Get performance data
+    const perfData = this.performanceMonitor?.getPerformanceData();
+    if (perfData) {
+      console.log('FPS:', perfData.fps);
+      console.log('Frame time:', perfData.frameTime);
+      console.log('Entity update time:', perfData.entityUpdateTime);
+      console.log('System update time:', perfData.systemUpdateTime);
+    }
+
+    // Get performance report
+    const report = this.performanceMonitor?.generateReport();
+    if (report) {
+      console.log('Performance report:', report);
+    }
+  }
+}
+```
+
+## API Reference
+
+### getStats()
+
+Returns scene statistics:
+
+```typescript
+interface SceneStats {
+  entityCount: number;
+  processorCount: number;
+  componentStorageStats: ComponentStorageStats;
+}
+```
+
+### getDebugInfo()
+
+Returns detailed debug information:
+
+```typescript
+interface DebugInfo {
+  entities: EntityDebugInfo[];
+  processors: ProcessorDebugInfo[];
+}
+
+interface EntityDebugInfo {
+  id: number;
+  name: string;
+  componentCount: number;
+  componentTypes: string[];
+}
+
+interface ProcessorDebugInfo {
+  name: string;
+  entityCount: number;
+}
+```
+
+### performanceMonitor
+
+Performance monitor interface:
+
+```typescript
+interface PerformanceMonitor {
+  getPerformanceData(): PerformanceData;
+  generateReport(): string;
+}
+
+interface PerformanceData {
+  fps: number;
+  frameTime: number;
+  entityUpdateTime: number;
+  systemUpdateTime: number;
+}
+```
+
+## Debugging Tips
+
+1. **Debug mode** - Enable with `Core.create({ debug: true })`
+2. **Performance analysis** - Call `getStats()` periodically
+3. **Memory monitoring** - Check `componentStorageStats` for issues
+4. **System performance** - Use `performanceMonitor` to identify slow systems

docs/src/content/docs/en/guide/scene/entity-management.md

@@ -0,0 +1,125 @@
+---
+title: "Entity Management"
+description: "Entity creation, finding and destruction in scenes"
+---
+
+Scene provides complete entity management APIs for creating, finding, and destroying entities.
+
+## Creating Entities
+
+### Single Entity
+
+```typescript
+class EntityScene extends Scene {
+  createGameEntities(): void {
+    // Create named entity
+    const player = this.createEntity("Player");
+    player.addComponent(new Position(400, 300));
+    player.addComponent(new Health(100));
+  }
+}
+```
+
+### Batch Creation
+
+```typescript
+class EntityScene extends Scene {
+  createBullets(): void {
+    // Batch create entities (high performance)
+    const bullets = this.createEntities(100, "Bullet");
+
+    // Add components to batch-created entities
+    bullets.forEach((bullet, index) => {
+      bullet.addComponent(new Position(index * 10, 100));
+      bullet.addComponent(new Velocity(Math.random() * 200 - 100, -300));
+    });
+  }
+}
+```
+
+## Finding Entities
+
+### By Name
+
+```typescript
+// Find by name (returns first match)
+const player = this.findEntity("Player");
+const player2 = this.getEntityByName("Player"); // Alias
+
+if (player) {
+  console.log(`Found player: ${player.name}`);
+}
+```
+
+### By ID
+
+```typescript
+// Find by unique ID
+const entity = this.findEntityById(123);
+
+if (entity) {
+  console.log(`Found entity: ${entity.id}`);
+}
+```
+
+### By Tag
+
+```typescript
+// Find by tag (returns array)
+const enemies = this.findEntitiesByTag(2);
+const enemies2 = this.getEntitiesByTag(2); // Alias
+
+console.log(`Found ${enemies.length} enemies`);
+```
+
+## Destroying Entities
+
+### Single Entity
+
+```typescript
+const enemy = this.findEntity("Enemy_1");
+if (enemy) {
+  enemy.destroy(); // Entity is automatically removed from scene
+}
+```
+
+### All Entities
+
+```typescript
+// Destroy all entities in scene
+this.destroyAllEntities();
+```
+
+## Entity Queries
+
+Scene provides a component query system:
+
+```typescript
+class QueryScene extends Scene {
+  protected initialize(): void {
+    // Create test entities
+    for (let i = 0; i < 10; i++) {
+      const entity = this.createEntity(`Entity_${i}`);
+      entity.addComponent(new Transform(i * 10, 0));
+      entity.addComponent(new Velocity(1, 0));
+    }
+  }
+
+  public queryEntities(): void {
+    // Query through QuerySystem
+    const entities = this.querySystem.query([Transform, Velocity]);
+    console.log(`Found ${entities.length} entities with Transform and Velocity`);
+  }
+}
+```
+
+## API Reference
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `createEntity(name)` | `Entity` | Create single entity |
+| `createEntities(count, prefix)` | `Entity[]` | Batch create entities |
+| `findEntity(name)` | `Entity \| undefined` | Find by name |
+| `findEntityById(id)` | `Entity \| undefined` | Find by ID |
+| `findEntitiesByTag(tag)` | `Entity[]` | Find by tag |
+| `destroyAllEntities()` | `void` | Destroy all entities |

docs/src/content/docs/en/guide/scene/events.md

@@ -0,0 +1,122 @@
+---
+title: "Event System"
+description: "Scene's built-in type-safe event system"
+---
+
+Scene includes a built-in type-safe event system for decoupled communication within scenes.
+
+## Basic Usage
+
+### Listening to Events
+
+```typescript
+class EventScene extends Scene {
+  protected initialize(): void {
+    // Listen to events
+    this.eventSystem.on('player_died', this.onPlayerDied.bind(this));
+    this.eventSystem.on('enemy_spawned', this.onEnemySpawned.bind(this));
+    this.eventSystem.on('level_complete', this.onLevelComplete.bind(this));
+  }
+
+  private onPlayerDied(data: any): void {
+    console.log('Player died event');
+  }
+
+  private onEnemySpawned(data: any): void {
+    console.log('Enemy spawned event');
+  }
+
+  private onLevelComplete(data: any): void {
+    console.log('Level complete event');
+  }
+}
+```
+
+### Sending Events
+
+```typescript
+public triggerGameEvent(): void {
+  // Send event (synchronous)
+  this.eventSystem.emitSync('custom_event', {
+    message: "This is a custom event",
+    timestamp: Date.now()
+  });
+
+  // Send event (asynchronous)
+  this.eventSystem.emit('async_event', {
+    data: "Async event data"
+  });
+}
+```
+
+## API Reference
+
+| Method | Description |
+|--------|-------------|
+| `on(event, callback)` | Listen to event |
+| `once(event, callback)` | Listen once (auto-unsubscribe) |
+| `off(event, callback)` | Stop listening |
+| `emitSync(event, data)` | Send event (synchronous) |
+| `emit(event, data)` | Send event (asynchronous) |
+| `clear()` | Clear all event listeners |
+
+## Event Handling Patterns
+
+### Centralized Event Management
+
+```typescript
+class EventHandlingScene extends Scene {
+  protected initialize(): void {
+    this.setupEventListeners();
+  }
+
+  private setupEventListeners(): void {
+    this.eventSystem.on('game_pause', this.onGamePause.bind(this));
+    this.eventSystem.on('game_resume', this.onGameResume.bind(this));
+    this.eventSystem.on('player_input', this.onPlayerInput.bind(this));
+  }
+
+  private onGamePause(): void {
+    // Pause game logic
+    this.systems.forEach(system => {
+      if (system instanceof GameLogicSystem) {
+        system.enabled = false;
+      }
+    });
+  }
+
+  private onGameResume(): void {
+    // Resume game logic
+    this.systems.forEach(system => {
+      if (system instanceof GameLogicSystem) {
+        system.enabled = true;
+      }
+    });
+  }
+
+  private onPlayerInput(data: any): void {
+    // Handle player input
+  }
+}
+```
+
+### Cleanup Event Listeners
+
+Clean up event listeners on scene unload to avoid memory leaks:
+
+```typescript
+public unload(): void {
+  // Clear all event listeners
+  this.eventSystem.clear();
+}
+```
+
+## Use Cases
+
+| Category | Example Events |
+|----------|----------------|
+| Game State | `game_start`, `game_pause`, `game_over` |
+| Player Actions | `player_died`, `player_jump`, `player_attack` |
+| Enemy Actions | `enemy_spawned`, `enemy_killed` |
+| Level Progress | `level_start`, `level_complete` |
+| UI Interaction | `button_click`, `menu_open` |

docs/src/content/docs/en/guide/scene/index.md

@@ -0,0 +1,91 @@
+---
+title: "Scene"
+description: "Core container of ECS framework, managing entity, system and component lifecycles"
+---
+
+In the ECS architecture, a Scene is a container for the game world, responsible for managing the lifecycle of entities, systems, and components.
+
+## Core Features
+
+Scene is the core container of the ECS framework, providing:
+- Entity creation, management, and destruction
+- System registration and execution scheduling
+- Component storage and querying
+- Event system support
+- Performance monitoring and debugging information
+
+## Scene Management Options
+
+ECS Framework provides two scene management approaches:
+
+| Manager | Use Case | Features |
+|---------|----------|----------|
+| **SceneManager** | 95% of games | Lightweight, scene transitions |
+| **WorldManager** | MMO servers, room systems | Multi-World, full isolation |
+
+## Quick Start
+
+### Inherit Scene Class
+
+```typescript
+import { Scene, EntitySystem } from '@esengine/ecs-framework';
+
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // Add systems
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+
+    // Create initial entities
+    const player = this.createEntity("Player");
+    player.addComponent(new Position(400, 300));
+    player.addComponent(new Health(100));
+  }
+
+  public onStart(): void {
+    console.log("Game scene started");
+  }
+
+  public unload(): void {
+    console.log("Game scene unloaded");
+  }
+}
+```
+
+### Using Scene Configuration
+
+```typescript
+import { ISceneConfig } from '@esengine/ecs-framework';
+
+const config: ISceneConfig = {
+  name: "MainGame",
+  enableEntityDirectUpdate: false
+};
+
+class ConfiguredScene extends Scene {
+  constructor() {
+    super(config);
+  }
+}
+```
+
+### Running a Scene
+
+```typescript
+import { Core, SceneManager } from '@esengine/ecs-framework';
+
+Core.create({ debug: true });
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new GameScene());
+```
+
+## Next Steps
+
+- [Lifecycle](./lifecycle/) - Scene lifecycle methods
+- [Entity Management](./entity-management/) - Create, find, destroy entities
+- [System Management](./system-management/) - System control
+- [Events](./events/) - Scene event communication
+- [Debugging](./debugging/) - Performance and debugging
+- [Best Practices](./best-practices/) - Scene design patterns

docs/src/content/docs/en/guide/scene/lifecycle.md

@@ -0,0 +1,103 @@
+---
+title: "Scene Lifecycle"
+description: "Scene lifecycle methods and execution order"
+---
+
+Scene provides complete lifecycle management for proper resource initialization and cleanup.
+
+## Lifecycle Methods
+
+```typescript
+class ExampleScene extends Scene {
+  protected initialize(): void {
+    // 1. Scene initialization: setup systems and initial entities
+    console.log("Scene initializing");
+  }
+
+  public onStart(): void {
+    // 2. Scene starts running: game logic begins execution
+    console.log("Scene starting");
+  }
+
+  public update(deltaTime: number): void {
+    // 3. Per-frame update (called by scene manager)
+  }
+
+  public unload(): void {
+    // 4. Scene unloading: cleanup resources
+    console.log("Scene unloading");
+  }
+}
+```
+
+## Execution Order
+
+| Phase | Method | Description |
+|-------|--------|-------------|
+| Initialize | `initialize()` | Setup systems and initial entities |
+| Start | `begin()` / `onStart()` | Scene starts running |
+| Update | `update()` | Per-frame update (auto-called) |
+| End | `end()` / `unload()` | Cleanup resources |
+
+## Lifecycle Example
+
+```typescript
+class GameScene extends Scene {
+  private resourcesLoaded = false;
+
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 1. Add systems (by dependency order)
+    this.addSystem(new InputSystem());
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+
+    // 2. Create initial entities
+    this.createPlayer();
+    this.createEnemies();
+
+    // 3. Setup event listeners
+    this.setupEvents();
+  }
+
+  public onStart(): void {
+    this.resourcesLoaded = true;
+    console.log("Scene resources loaded, game starting");
+  }
+
+  public unload(): void {
+    // Cleanup event listeners
+    this.eventSystem.clear();
+
+    // Cleanup other resources
+    this.resourcesLoaded = false;
+    console.log("Scene resources cleaned up");
+  }
+
+  private createPlayer(): void {
+    const player = this.createEntity("Player");
+    player.addComponent(new Position(400, 300));
+  }
+
+  private createEnemies(): void {
+    for (let i = 0; i < 5; i++) {
+      const enemy = this.createEntity(`Enemy_${i}`);
+      enemy.addComponent(new Position(Math.random() * 800, Math.random() * 600));
+    }
+  }
+
+  private setupEvents(): void {
+    this.eventSystem.on('player_died', () => {
+      console.log('Player died');
+    });
+  }
+}
+```
+
+## Notes
+
+1. **initialize() called once** - For initial state setup
+2. **onStart() on scene activation** - May be called multiple times
+3. **unload() must cleanup resources** - Avoid memory leaks
+4. **update() managed by framework** - No manual calls needed

docs/src/content/docs/en/guide/scene/system-management.md

@@ -0,0 +1,115 @@
+---
+title: "System Management"
+description: "System addition, removal and control in scenes"
+---
+
+Scene manages system registration, execution order, and lifecycle.
+
+## Adding Systems
+
+```typescript
+class SystemScene extends Scene {
+  protected initialize(): void {
+    // Add system
+    const movementSystem = new MovementSystem();
+    this.addSystem(movementSystem);
+
+    // Set system update order (lower runs first)
+    movementSystem.updateOrder = 1;
+
+    // Add more systems
+    this.addSystem(new PhysicsSystem());
+    this.addSystem(new RenderSystem());
+  }
+}
+```
+
+## Getting Systems
+
+```typescript
+// Get system of specific type
+const physicsSystem = this.getEntityProcessor(PhysicsSystem);
+
+if (physicsSystem) {
+  console.log("Found physics system");
+}
+```
+
+## Removing Systems
+
+```typescript
+public removeUnnecessarySystems(): void {
+  const physicsSystem = this.getEntityProcessor(PhysicsSystem);
+
+  if (physicsSystem) {
+    this.removeSystem(physicsSystem);
+  }
+}
+```
+
+## Controlling Systems
+
+### Enable/Disable Systems
+
+```typescript
+public pausePhysics(): void {
+  const physicsSystem = this.getEntityProcessor(PhysicsSystem);
+  if (physicsSystem) {
+    physicsSystem.enabled = false; // Disable system
+  }
+}
+
+public resumePhysics(): void {
+  const physicsSystem = this.getEntityProcessor(PhysicsSystem);
+  if (physicsSystem) {
+    physicsSystem.enabled = true; // Enable system
+  }
+}
+```
+
+### Get All Systems
+
+```typescript
+public getAllSystems(): EntitySystem[] {
+  return this.systems; // Get all registered systems
+}
+```
+
+## System Organization Best Practice
+
+Group systems by function:
+
+```typescript
+class OrganizedScene extends Scene {
+  protected initialize(): void {
+    // Add systems by function and dependencies
+    this.addInputSystems();
+    this.addLogicSystems();
+    this.addRenderSystems();
+  }
+
+  private addInputSystems(): void {
+    this.addSystem(new InputSystem());
+  }
+
+  private addLogicSystems(): void {
+    this.addSystem(new MovementSystem());
+    this.addSystem(new PhysicsSystem());
+    this.addSystem(new CollisionSystem());
+  }
+
+  private addRenderSystems(): void {
+    this.addSystem(new RenderSystem());
+    this.addSystem(new UISystem());
+  }
+}
+```
+
+## API Reference
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `addSystem(system)` | `void` | Add system to scene |
+| `removeSystem(system)` | `void` | Remove system from scene |
+| `getEntityProcessor(Type)` | `T \| undefined` | Get system by type |
+| `systems` | `EntitySystem[]` | Get all systems |

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<string, number> = new Map();
+
+  // Set serialization
+  @SerializeAsSet()
+  public acquiredSkills: Set<string> = 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 |

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 |

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<string, ComponentType>;
+}
+```
+
+### 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