chore: release packages (#358)

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]
+  }
+}

.editorconfig

@@ -0,0 +1,35 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# 所有文件的默认设置
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+# TypeScript/JavaScript 文件
+[*.{ts,tsx,js,jsx,mjs,cjs}]
+indent_style = space
+indent_size = 4
+
+# JSON 文件
+[*.json]
+indent_style = space
+indent_size = 2
+
+# YAML 文件
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+# Markdown 文件
+[*.md]
+trim_trailing_whitespace = false
+indent_size = 2
+
+# 包管理文件
+[{package.json,package-lock.json,tsconfig.json}]
+indent_size = 2

.gitattributes

@@ -0,0 +1,44 @@
+# 自动检测文本文件并规范化换行符
+* text=auto
+
+# 源代码文件强制使用 LF
+*.ts text eol=lf
+*.tsx text eol=lf
+*.js text eol=lf
+*.jsx text eol=lf
+*.mjs text eol=lf
+*.cjs text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+
+# 配置文件强制使用 LF
+.gitignore text eol=lf
+.gitattributes text eol=lf
+.editorconfig text eol=lf
+.prettierrc text eol=lf
+.prettierignore text eol=lf
+.eslintrc.json text eol=lf
+tsconfig.json text eol=lf
+
+# Shell 脚本强制使用 LF
+*.sh text eol=lf
+
+# Windows 批处理文件使用 CRLF
+*.bat text eol=crlf
+*.cmd text eol=crlf
+*.ps1 text eol=crlf
+
+# 二进制文件不转换
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+*.svg binary
+*.woff binary
+*.woff2 binary
+*.ttf binary
+*.eot binary
+*.otf binary

.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,107 @@ 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/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,26 +29,29 @@ 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

.github/workflows/release-changesets.yml

@@ -0,0 +1,70 @@
+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/network" build
+          pnpm --filter "@esengine/cli" 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

@@ -0,0 +1,253 @@
+name: Release Editor App
+
+on:
+  push:
+    tags:
+      - 'editor-v*'
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Release version (e.g., 1.0.0)'
+        required: true
+        default: '1.0.0'
+
+jobs:
+  build-tauri:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: windows-latest
+            target: x86_64-pc-windows-msvc
+            arch: x64
+          - platform: macos-latest
+            target: x86_64-apple-darwin
+            arch: x64
+          - platform: macos-latest
+            target: aarch64-apple-darwin
+            arch: arm64
+
+    runs-on: ${{ matrix.platform }}
+
+    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 Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - name: Rust cache
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: packages/editor/editor-app/src-tauri
+          cache-on-failure: true
+
+      - name: Install dependencies (Ubuntu)
+        if: matrix.platform == 'ubuntu-latest'
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libgtk-3-dev libwebkit2gtk-4.0-dev libappindicator3-dev librsvg2-dev patchelf
+
+      - name: Install frontend dependencies
+        run: pnpm install
+
+      - name: Update version in config files (for manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          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: Install wasm-pack
+        run: cargo install wasm-pack
+
+      # 使用 Turborepo 自动按依赖顺序构建所有包
+      # 这会自动处理：core -> asset-system -> editor-core -> ui -> 等等
+      - name: Build all packages with Turborepo
+        run: pnpm run build
+
+      - name: Copy WASM files to ecs-engine-bindgen
+        shell: bash
+        run: |
+          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/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: true
+          prerelease: false
+          includeUpdaterJson: true
+          updaterJsonKeepUniversal: false
+          args: ${{ matrix.platform == 'macos-latest' && format('--target {0}', matrix.target) || '' }}
+
+      # 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
+    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:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Update version files
+        run: |
+          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
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore(editor): bump version to ${{ github.event.inputs.version }}"
+          branch: release/editor-v${{ github.event.inputs.version }}
+          delete-branch: true
+          title: "chore(editor): Release v${{ github.event.inputs.version }}"
+          body: |
+            ## Release v${{ github.event.inputs.version }}
+
+            This PR updates the editor version after successful release build.
+
+            ### Changes
+            - 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 }})
+
+            ---
+            *This PR was automatically created by the release workflow.*
+          labels: |
+            release
+            editor
+            automated pr

.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/
@@ -69,3 +81,16 @@ docs/.vitepress/dist/
 /demo/.idea/
 /demo/.vscode/
 /demo_wxgame/
+
+# Tauri 构建产物
+**/src-tauri/target/
+**/src-tauri/WixTools/
+**/src-tauri/gen/
+
+# 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

.prettierignore

@@ -0,0 +1,49 @@
+# 依赖和构建输出
+node_modules/
+dist/
+bin/
+build/
+coverage/
+*.min.js
+*.min.css
+
+# 编译输出
+**/*.d.ts
+tsconfig.tsbuildinfo
+
+# 日志
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# 第三方库
+thirdparty/
+examples/lawn-mower-demo/
+extensions/
+
+# 文档生成
+docs/.vitepress/cache/
+docs/.vitepress/dist/
+docs/api/
+
+# 临时文件
+*.tmp
+*.bak
+*.swp
+*~
+
+# 系统文件
+.DS_Store
+Thumbs.db
+
+# 编辑器
+.vscode/
+.idea/
+
+# 其他
+*.backup
+CHANGELOG.md
+LICENSE
+README.md

.prettierrc

@@ -0,0 +1,14 @@
+{
+  "semi": true,
+  "singleQuote": true,
+  "tabWidth": 4,
+  "useTabs": false,
+  "trailingComma": "none",
+  "printWidth": 120,
+  "arrowParens": "always",
+  "endOfLine": "lf",
+  "bracketSpacing": true,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "proseWrap": "preserve"
+}

.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,93 @@
-# 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 |
+| **Network** | Client/server networking with TSRPC | 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,76 +96,201 @@ 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** - 内置引擎集成支持，提供[专用调试插件](https://store.cocos.com/app/detail/7823)
-- **Laya 引擎** - 完整的生命周期管理
-- **原生 Web** - 浏览器环境直接运行
-- **小游戏平台** - 微信、支付宝等小游戏
+    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();
+    }
+}
+```
 
-- [Worker系统演示](https://esengine.github.io/ecs-framework/demos/worker-system/) - 多线程物理系统演示，展示高性能并行计算
-- [割草机演示](https://github.com/esengine/lawn-mower-demo) - 完整的游戏示例
+## Packages
 
-## 文档
+### Framework (Engine-Agnostic)
 
-- [快速入门](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 文档
+These packages have **zero rendering dependencies** and work with any engine:
 
-## 生态系统
+```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/network            # Networking
+```
 
-- [路径寻找](https://github.com/esengine/ecs-astar) - A*、BFS、Dijkstra 算法
-- [AI 系统](https://github.com/esengine/BehaviourTree-ai) - 行为树、效用 AI
+### ESEngine Runtime (Optional)
 
-## 社区与支持
+If you want a complete engine solution with rendering:
 
-- [问题反馈](https://github.com/esengine/ecs-framework/issues) - Bug 报告和功能建议
-- [QQ 交流群](https://jq.qq.com/?_wv=1027&k=29w1Nud6) - ecs游戏框架交流
+| Category | Packages |
+|----------|----------|
+| **Core** | `engine-core`, `asset-system`, `material-system` |
+| **Rendering** | `sprite`, `tilemap`, `particle`, `camera`, `mesh-3d` |
+| **Physics** | `physics-rapier2d` |
+| **Platform** | `platform-web`, `platform-wechat` |
 
-## 许可证
+### Editor (Optional)
 
-[MIT](LICENSE) © 2025 ECS Framework
+A visual editor built with Tauri for scene management:
+
+- Download from [Releases](https://github.com/esengine/esengine/releases)
+- Supports behavior tree editing, tilemap painting, visual scripting
+
+## Project Structure
+
+```
+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
+│   │   └── network/       # Networking
+│   │
+│   ├── engine/            # ESEngine runtime
+│   ├── rendering/         # Rendering modules
+│   ├── physics/           # Physics modules
+│   ├── editor/            # Visual editor
+│   └── rust/              # WASM renderer
+│
+├── docs/                   # Documentation
+└── examples/               # Examples
+```
+
+## Building from Source
+
+```bash
+git clone https://github.com/esengine/esengine.git
+cd esengine
+
+pnpm install
+pnpm build
+
+# Type check framework packages
+pnpm type-check:framework
+
+# Run tests
+pnpm test
+```
+
+## 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)
+
+## 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
+
+## 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,297 @@
+<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* 和导航网格寻路 | 否 |
+| **网络** | 客户端/服务端网络通信 (TSRPC) | 否 |
+
+> 所有框架模块都可以独立使用，无需依赖特定渲染引擎。
+
+## 快速开始
+
+### 使用 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/network            # 网络
+```
+
+### 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/       # 程序化生成
+│   │   └── network/       # 网络
+│   │
+│   ├── 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/.vitepress/config.mjs

@@ -6,9 +6,233 @@ import { fileURLToPath } from 'url'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const corePackageJson = JSON.parse(
-  readFileSync(join(__dirname, '../../packages/core/package.json'), 'utf-8')
+  readFileSync(join(__dirname, '../../packages/framework/core/package.json'), 'utf-8')
 )
 
+// Import i18n messages
+import en from './i18n/en.json' with { type: 'json' }
+import zh from './i18n/zh.json' with { type: 'json' }
+
+// 创建侧边栏配置 | Create sidebar config
+// prefix: 路径前缀，如 '' 或 '/en' | Path prefix like '' or '/en'
+function createSidebar(t, prefix = '') {
+  return {
+    [`${prefix}/guide/`]: [
+      {
+        text: t.sidebar.gettingStarted,
+        items: [
+          { text: t.sidebar.quickStart, link: `${prefix}/guide/getting-started` },
+          { text: t.sidebar.guideOverview, link: `${prefix}/guide/` }
+        ]
+      },
+      {
+        text: t.sidebar.coreConcepts,
+        collapsed: false,
+        items: [
+          { text: t.sidebar.entity, link: `${prefix}/guide/entity` },
+          { text: t.sidebar.hierarchy, link: `${prefix}/guide/hierarchy` },
+          { text: t.sidebar.component, link: `${prefix}/guide/component` },
+          { text: t.sidebar.entityQuery, link: `${prefix}/guide/entity-query` },
+          {
+            text: t.sidebar.system,
+            link: `${prefix}/guide/system`,
+            items: [
+              { text: t.sidebar.workerSystem, link: `${prefix}/guide/worker-system` }
+            ]
+          },
+          {
+            text: t.sidebar.scene,
+            link: `${prefix}/guide/scene`,
+            items: [
+              { text: t.sidebar.sceneManager, link: `${prefix}/guide/scene-manager` },
+              { text: t.sidebar.worldManager, link: `${prefix}/guide/world-manager` },
+              { text: t.sidebar.persistentEntity, link: `${prefix}/guide/persistent-entity` }
+            ]
+          },
+          { text: t.sidebar.serialization, link: `${prefix}/guide/serialization` },
+          { text: t.sidebar.eventSystem, link: `${prefix}/guide/event-system` },
+          { text: t.sidebar.timeAndTimers, link: `${prefix}/guide/time-and-timers` },
+          { text: t.sidebar.logging, link: `${prefix}/guide/logging` }
+        ]
+      },
+      {
+        text: t.sidebar.advancedFeatures,
+        collapsed: false,
+        items: [
+          { text: t.sidebar.serviceContainer, link: `${prefix}/guide/service-container` },
+          { text: t.sidebar.pluginSystem, link: `${prefix}/guide/plugin-system` }
+        ]
+      },
+      {
+        text: t.sidebar.platformAdapters,
+        link: `${prefix}/guide/platform-adapter`,
+        collapsed: false,
+        items: [
+          { text: t.sidebar.browserAdapter, link: `${prefix}/guide/platform-adapter/browser` },
+          { text: t.sidebar.wechatAdapter, link: `${prefix}/guide/platform-adapter/wechat-minigame` },
+          { text: t.sidebar.nodejsAdapter, link: `${prefix}/guide/platform-adapter/nodejs` }
+        ]
+      }
+    ],
+    // 模块总览侧边栏 | Modules overview sidebar
+    [`${prefix}/modules/`]: [
+      {
+        text: t.sidebar.modulesOverview,
+        link: `${prefix}/modules/`,
+        items: [
+          {
+            text: t.sidebar.aiModules,
+            collapsed: false,
+            items: [
+              { text: t.sidebar.behaviorTree, link: `${prefix}/modules/behavior-tree/` },
+              { text: t.sidebar.fsm, link: `${prefix}/modules/fsm/` }
+            ]
+          },
+          {
+            text: t.sidebar.gameplayModules,
+            collapsed: false,
+            items: [
+              { text: t.sidebar.timer, link: `${prefix}/modules/timer/` },
+              { text: t.sidebar.spatial, link: `${prefix}/modules/spatial/` },
+              { text: t.sidebar.pathfinding, link: `${prefix}/modules/pathfinding/` }
+            ]
+          },
+          {
+            text: t.sidebar.toolModules,
+            collapsed: false,
+            items: [
+              { text: t.sidebar.blueprint, link: `${prefix}/modules/blueprint/` },
+              { text: t.sidebar.procgen, link: `${prefix}/modules/procgen/` }
+            ]
+          },
+          {
+            text: t.sidebar.networkModules,
+            collapsed: false,
+            items: [
+              { text: t.sidebar.network, link: `${prefix}/modules/network/` }
+            ]
+          }
+        ]
+      }
+    ],
+    // 行为树模块侧边栏 | Behavior tree module sidebar
+    [`${prefix}/modules/behavior-tree/`]: [
+      {
+        text: t.sidebar.behaviorTree,
+        items: [
+          { text: t.sidebar.btGettingStarted, link: `${prefix}/modules/behavior-tree/getting-started` },
+          { text: t.sidebar.btCoreConcepts, link: `${prefix}/modules/behavior-tree/core-concepts` },
+          { text: t.sidebar.btEditorGuide, link: `${prefix}/modules/behavior-tree/editor-guide` },
+          { text: t.sidebar.btEditorWorkflow, link: `${prefix}/modules/behavior-tree/editor-workflow` },
+          { text: t.sidebar.btCustomActions, link: `${prefix}/modules/behavior-tree/custom-actions` },
+          { text: t.sidebar.btCocosIntegration, link: `${prefix}/modules/behavior-tree/cocos-integration` },
+          { text: t.sidebar.btLayaIntegration, link: `${prefix}/modules/behavior-tree/laya-integration` },
+          { text: t.sidebar.btAdvancedUsage, link: `${prefix}/modules/behavior-tree/advanced-usage` },
+          { text: t.sidebar.btBestPractices, link: `${prefix}/modules/behavior-tree/best-practices` }
+        ]
+      }
+    ],
+    [`${prefix}/examples/`]: [
+      {
+        text: t.sidebar.examples,
+        items: [
+          { text: t.sidebar.examplesOverview, link: `${prefix}/examples/` },
+          { text: t.nav.workerDemo, link: `${prefix}/examples/worker-system-demo` }
+        ]
+      }
+    ],
+    [`${prefix}/api/`]: [
+      {
+        text: t.sidebar.apiReference,
+        items: [
+          { text: t.sidebar.overview, link: `${prefix}/api/README` },
+          {
+            text: t.sidebar.coreClasses,
+            collapsed: false,
+            items: [
+              { text: 'Core', link: `${prefix}/api/classes/Core` },
+              { text: 'Scene', link: `${prefix}/api/classes/Scene` },
+              { text: 'World', link: `${prefix}/api/classes/World` },
+              { text: 'Entity', link: `${prefix}/api/classes/Entity` },
+              { text: 'Component', link: `${prefix}/api/classes/Component` },
+              { text: 'EntitySystem', link: `${prefix}/api/classes/EntitySystem` }
+            ]
+          },
+          {
+            text: t.sidebar.systemClasses,
+            collapsed: true,
+            items: [
+              { text: 'PassiveSystem', link: `${prefix}/api/classes/PassiveSystem` },
+              { text: 'ProcessingSystem', link: `${prefix}/api/classes/ProcessingSystem` },
+              { text: 'IntervalSystem', link: `${prefix}/api/classes/IntervalSystem` }
+            ]
+          },
+          {
+            text: t.sidebar.utilities,
+            collapsed: true,
+            items: [
+              { text: 'Matcher', link: `${prefix}/api/classes/Matcher` },
+              { text: 'Time', link: `${prefix}/api/classes/Time` },
+              { text: 'PerformanceMonitor', link: `${prefix}/api/classes/PerformanceMonitor` },
+              { text: 'DebugManager', link: `${prefix}/api/classes/DebugManager` }
+            ]
+          },
+          {
+            text: t.sidebar.interfaces,
+            collapsed: true,
+            items: [
+              { text: 'IScene', link: `${prefix}/api/interfaces/IScene` },
+              { text: 'IComponent', link: `${prefix}/api/interfaces/IComponent` },
+              { text: 'ISystemBase', link: `${prefix}/api/interfaces/ISystemBase` },
+              { text: 'ICoreConfig', link: `${prefix}/api/interfaces/ICoreConfig` }
+            ]
+          },
+          {
+            text: t.sidebar.decorators,
+            collapsed: true,
+            items: [
+              { text: '@ECSComponent', link: `${prefix}/api/functions/ECSComponent` },
+              { text: '@ECSSystem', link: `${prefix}/api/functions/ECSSystem` }
+            ]
+          },
+          {
+            text: t.sidebar.enums,
+            collapsed: true,
+            items: [
+              { text: 'ECSEventType', link: `${prefix}/api/enumerations/ECSEventType` },
+              { text: 'LogLevel', link: `${prefix}/api/enumerations/LogLevel` }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}
+
+// 创建导航配置 | Create nav config
+// prefix: 路径前缀，如 '' 或 '/en' | Path prefix like '' or '/en'
+function createNav(t, prefix = '') {
+  return [
+    { text: t.nav.home, link: `${prefix}/` },
+    { text: t.nav.quickStart, link: `${prefix}/guide/getting-started` },
+    { text: t.nav.guide, link: `${prefix}/guide/` },
+    { text: t.nav.modules, link: `${prefix}/modules/` },
+    { text: t.nav.api, link: `${prefix}/api/README` },
+    {
+      text: t.nav.examples,
+      items: [
+        { text: t.nav.workerDemo, link: `${prefix}/examples/worker-system-demo` },
+        { text: t.nav.lawnMowerDemo, link: 'https://github.com/esengine/lawn-mower-demo' }
+      ]
+    },
+    { text: t.nav.changelog, link: `${prefix}/changelog` },
+    {
+      text: `v${corePackageJson.version}`,
+      link: 'https://github.com/esengine/esengine/releases'
+    }
+  ]
+}
+
 export default defineConfig({
   vite: {
     plugins: [
@@ -28,162 +252,52 @@ export default defineConfig({
       }
     }
   },
-  title: 'ECS Framework',
-  description: '高性能TypeScript ECS框架 - 为游戏开发而生',
-  lang: 'zh-CN',
+  title: 'ESEngine',
+  appearance: 'force-dark',
+
+  locales: {
+    root: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      description: '高性能 TypeScript ECS 框架 - 为游戏开发而生',
+      themeConfig: {
+        nav: createNav(zh, ''),
+        sidebar: createSidebar(zh, ''),
+        editLink: {
+          pattern: 'https://github.com/esengine/esengine/edit/master/docs/:path',
+          text: zh.common.editOnGithub
+        },
+        outline: {
+          level: [2, 3],
+          label: zh.common.onThisPage
+        }
+      }
+    },
+    en: {
+      label: 'English',
+      lang: 'en',
+      link: '/en/',
+      description: 'High-performance TypeScript ECS Framework for Game Development',
+      themeConfig: {
+        nav: createNav(en, '/en'),
+        sidebar: createSidebar(en, '/en'),
+        editLink: {
+          pattern: 'https://github.com/esengine/esengine/edit/master/docs/:path',
+          text: en.common.editOnGithub
+        },
+        outline: {
+          level: [2, 3],
+          label: en.common.onThisPage
+        }
+      }
+    }
+  },
 
   themeConfig: {
-    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: '系统架构 (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' }
-              ]
-            }
-          ]
-        }
-      ]
-    },
+    siteTitle: 'ESEngine',
 
     socialLinks: [
-      { icon: 'github', link: 'https://github.com/esengine/ecs-framework' }
+      { icon: 'github', link: 'https://github.com/esengine/esengine' }
     ],
 
     footer: {
@@ -191,18 +305,8 @@ export default defineConfig({
       copyright: 'Copyright © 2025 ECS Framework'
     },
 
-    editLink: {
-      pattern: 'https://github.com/esengine/ecs-framework/edit/master/docs/:path',
-      text: '在 GitHub 上编辑此页'
-    },
-
     search: {
       provider: 'local'
-    },
-
-    outline: {
-      level: [2, 3],
-      label: '目录'
     }
   },
 
@@ -211,8 +315,9 @@ export default defineConfig({
     ['link', { rel: 'icon', href: '/favicon.ico' }]
   ],
 
-  base: '/ecs-framework/',
+  base: '/',
   cleanUrls: true,
+  ignoreDeadLinks: true,
 
   markdown: {
     lineNumbers: true,
@@ -221,4 +326,4 @@ export default defineConfig({
       dark: 'github-dark'
     }
   }
-})
+})

docs/.vitepress/i18n/en.json

@@ -0,0 +1,107 @@
+{
+  "nav": {
+    "home": "Home",
+    "quickStart": "Quick Start",
+    "guide": "Guide",
+    "modules": "Modules",
+    "api": "API",
+    "examples": "Examples",
+    "workerDemo": "Worker System Demo",
+    "lawnMowerDemo": "Lawn Mower Demo",
+    "changelog": "Changelog"
+  },
+  "sidebar": {
+    "gettingStarted": "Getting Started",
+    "quickStart": "Quick Start",
+    "guideOverview": "Guide Overview",
+    "coreConcepts": "Core Concepts",
+    "entity": "Entity",
+    "hierarchy": "Hierarchy",
+    "component": "Component",
+    "entityQuery": "Entity Query",
+    "system": "System",
+    "workerSystem": "Worker System (Multithreading)",
+    "scene": "Scene",
+    "sceneManager": "SceneManager",
+    "worldManager": "WorldManager",
+    "persistentEntity": "Persistent Entity",
+    "behaviorTree": "Behavior Tree",
+    "btGettingStarted": "Getting Started",
+    "btCoreConcepts": "Core Concepts",
+    "btEditorGuide": "Editor Guide",
+    "btEditorWorkflow": "Editor Workflow",
+    "btCustomActions": "Custom Actions",
+    "btCocosIntegration": "Cocos Creator Integration",
+    "btLayaIntegration": "Laya Engine Integration",
+    "btAdvancedUsage": "Advanced Usage",
+    "btBestPractices": "Best Practices",
+    "serialization": "Serialization",
+    "eventSystem": "Event System",
+    "timeAndTimers": "Time and Timers",
+    "logging": "Logging",
+    "advancedFeatures": "Advanced Features",
+    "serviceContainer": "Service Container",
+    "pluginSystem": "Plugin System",
+    "platformAdapters": "Platform Adapters",
+    "browserAdapter": "Browser Adapter",
+    "wechatAdapter": "WeChat Mini Game Adapter",
+    "nodejsAdapter": "Node.js Adapter",
+    "examples": "Examples",
+    "examplesOverview": "Examples Overview",
+    "apiReference": "API Reference",
+    "overview": "Overview",
+    "coreClasses": "Core Classes",
+    "systemClasses": "System Classes",
+    "utilities": "Utilities",
+    "interfaces": "Interfaces",
+    "decorators": "Decorators",
+    "enums": "Enums",
+    "modulesOverview": "Modules Overview",
+    "aiModules": "AI Modules",
+    "gameplayModules": "Gameplay",
+    "toolModules": "Tools",
+    "networkModules": "Network",
+    "fsm": "State Machine (FSM)",
+    "fsmOverview": "Overview",
+    "timer": "Timer System",
+    "timerOverview": "Overview",
+    "spatial": "Spatial Index",
+    "spatialOverview": "Overview",
+    "pathfinding": "Pathfinding",
+    "pathfindingOverview": "Overview",
+    "blueprint": "Visual Scripting",
+    "blueprintOverview": "Overview",
+    "procgen": "Procedural Generation",
+    "procgenOverview": "Overview",
+    "network": "Network Sync",
+    "networkOverview": "Overview"
+  },
+  "home": {
+    "title": "ESEngine - High-performance TypeScript ECS Framework",
+    "quickLinks": "Quick Links",
+    "viewDocs": "View Docs",
+    "getStarted": "Get Started",
+    "getStartedDesc": "From installation to your first ECS app, learn the core concepts in 5 minutes.",
+    "aiSystem": "AI System",
+    "behaviorTreeEditor": "Visual Behavior Tree Editor",
+    "behaviorTreeDesc": "Built-in AI behavior tree system with visual editing and real-time debugging.",
+    "coreFeatures": "Core Features",
+    "ecsArchitecture": "High-performance ECS Architecture",
+    "ecsArchitectureDesc": "Data-driven entity component system for large-scale entity processing with cache-friendly memory layout.",
+    "typeSupport": "Full Type Support",
+    "typeSupportDesc": "100% TypeScript with complete type definitions and compile-time checking for the best development experience.",
+    "visualBehaviorTree": "Visual Behavior Tree",
+    "visualBehaviorTreeDesc": "Built-in AI behavior tree system with visual editor, custom nodes, and real-time debugging.",
+    "multiPlatform": "Multi-Platform Support",
+    "multiPlatformDesc": "Support for browsers, Node.js, WeChat Mini Games, and seamless integration with major game engines.",
+    "modularDesign": "Modular Design",
+    "modularDesignDesc": "Core features packaged independently, import only what you need. Support for custom plugin extensions.",
+    "devTools": "Developer Tools",
+    "devToolsDesc": "Built-in performance monitoring, debugging tools, serialization system, and complete development toolchain.",
+    "learnMore": "Learn more →"
+  },
+  "common": {
+    "editOnGithub": "Edit this page on GitHub",
+    "onThisPage": "On this page"
+  }
+}

docs/.vitepress/i18n/index.ts

@@ -0,0 +1,21 @@
+import en from './en.json'
+import zh from './zh.json'
+
+export const messages = { en, zh }
+
+export type Locale = 'en' | 'zh'
+
+export function getLocaleMessages(locale: Locale) {
+  return messages[locale] || messages.en
+}
+
+// Helper to get nested key value
+export function t(messages: typeof en, key: string): string {
+  const keys = key.split('.')
+  let result: any = messages
+  for (const k of keys) {
+    result = result?.[k]
+    if (result === undefined) return key
+  }
+  return result
+}

docs/.vitepress/i18n/zh.json

@@ -0,0 +1,107 @@
+{
+  "nav": {
+    "home": "首页",
+    "quickStart": "快速开始",
+    "guide": "指南",
+    "modules": "模块",
+    "api": "API",
+    "examples": "示例",
+    "workerDemo": "Worker系统演示",
+    "lawnMowerDemo": "割草机演示",
+    "changelog": "更新日志"
+  },
+  "sidebar": {
+    "gettingStarted": "开始使用",
+    "quickStart": "快速开始",
+    "guideOverview": "指南概览",
+    "coreConcepts": "核心概念",
+    "entity": "实体类 (Entity)",
+    "hierarchy": "层级系统 (Hierarchy)",
+    "component": "组件系统 (Component)",
+    "entityQuery": "实体查询系统",
+    "system": "系统架构 (System)",
+    "workerSystem": "Worker系统 (多线程)",
+    "scene": "场景管理 (Scene)",
+    "sceneManager": "SceneManager",
+    "worldManager": "WorldManager",
+    "persistentEntity": "持久化实体 (Persistent Entity)",
+    "behaviorTree": "行为树系统 (Behavior Tree)",
+    "btGettingStarted": "快速开始",
+    "btCoreConcepts": "核心概念",
+    "btEditorGuide": "编辑器指南",
+    "btEditorWorkflow": "编辑器工作流",
+    "btCustomActions": "自定义动作组件",
+    "btCocosIntegration": "Cocos Creator集成",
+    "btLayaIntegration": "Laya引擎集成",
+    "btAdvancedUsage": "高级用法",
+    "btBestPractices": "最佳实践",
+    "serialization": "序列化系统 (Serialization)",
+    "eventSystem": "事件系统 (Event)",
+    "timeAndTimers": "时间和定时器 (Time)",
+    "logging": "日志系统 (Logger)",
+    "advancedFeatures": "高级特性",
+    "serviceContainer": "服务容器 (Service Container)",
+    "pluginSystem": "插件系统 (Plugin System)",
+    "platformAdapters": "平台适配器",
+    "browserAdapter": "浏览器适配器",
+    "wechatAdapter": "微信小游戏适配器",
+    "nodejsAdapter": "Node.js适配器",
+    "examples": "示例",
+    "examplesOverview": "示例概览",
+    "apiReference": "API 参考",
+    "overview": "概述",
+    "coreClasses": "核心类",
+    "systemClasses": "系统类",
+    "utilities": "工具类",
+    "interfaces": "接口",
+    "decorators": "装饰器",
+    "enums": "枚举",
+    "modulesOverview": "模块总览",
+    "aiModules": "AI 模块",
+    "gameplayModules": "游戏逻辑",
+    "toolModules": "工具模块",
+    "networkModules": "网络模块",
+    "fsm": "状态机 (FSM)",
+    "fsmOverview": "概述",
+    "timer": "定时器系统",
+    "timerOverview": "概述",
+    "spatial": "空间索引",
+    "spatialOverview": "概述",
+    "pathfinding": "寻路系统",
+    "pathfindingOverview": "概述",
+    "blueprint": "可视化脚本",
+    "blueprintOverview": "概述",
+    "procgen": "程序化生成",
+    "procgenOverview": "概述",
+    "network": "网络同步",
+    "networkOverview": "概述"
+  },
+  "home": {
+    "title": "ESEngine - 高性能 TypeScript ECS 框架",
+    "quickLinks": "快速入口",
+    "viewDocs": "查看文档",
+    "getStarted": "快速开始",
+    "getStartedDesc": "从安装到创建第一个 ECS 应用，快速了解核心概念。",
+    "aiSystem": "AI 系统",
+    "behaviorTreeEditor": "行为树可视化编辑器",
+    "behaviorTreeDesc": "内置 AI 行为树系统，支持可视化编辑和实时调试。",
+    "coreFeatures": "核心特性",
+    "ecsArchitecture": "高性能 ECS 架构",
+    "ecsArchitectureDesc": "基于数据驱动的实体组件系统，支持大规模实体处理，缓存友好的内存布局。",
+    "typeSupport": "完整类型支持",
+    "typeSupportDesc": "100% TypeScript 编写，完整的类型定义和编译时检查，提供最佳的开发体验。",
+    "visualBehaviorTree": "可视化行为树",
+    "visualBehaviorTreeDesc": "内置 AI 行为树系统，提供可视化编辑器，支持自定义节点和实时调试。",
+    "multiPlatform": "多平台支持",
+    "multiPlatformDesc": "支持浏览器、Node.js、微信小游戏等多平台，可与主流游戏引擎无缝集成。",
+    "modularDesign": "模块化设计",
+    "modularDesignDesc": "核心功能独立打包，按需引入。支持自定义插件扩展，灵活适配不同项目。",
+    "devTools": "开发者工具",
+    "devToolsDesc": "内置性能监控、调试工具、序列化系统等，提供完整的开发工具链。",
+    "learnMore": "了解更多 →"
+  },
+  "common": {
+    "editOnGithub": "在 GitHub 上编辑此页",
+    "onThisPage": "在这个页面上"
+  }
+}

docs/.vitepress/theme/components/FeatureCard.vue

@@ -0,0 +1,93 @@
+<script setup>
+defineProps({
+  title: String,
+  description: String,
+  icon: String,
+  link: String,
+  image: String
+})
+</script>
+
+<template>
+  <a :href="link" class="feature-card">
+    <div class="card-image" v-if="image">
+      <img :src="image" :alt="title" />
+    </div>
+    <div class="card-body">
+      <div class="card-icon" v-if="icon && !image">{{ icon }}</div>
+      <h3 class="card-title">{{ title }}</h3>
+      <p class="card-description">{{ description }}</p>
+    </div>
+  </a>
+</template>
+
+<style scoped>
+.feature-card {
+  display: flex;
+  flex-direction: column;
+  background: var(--es-bg-elevated, #252526);
+  border: 1px solid var(--es-border-default, #3e3e42);
+  border-radius: 4px;
+  overflow: hidden;
+  text-decoration: none;
+  transition: all 0.15s ease;
+}
+
+.feature-card:hover {
+  border-color: var(--es-primary, #007acc);
+  background: var(--es-bg-overlay, #2d2d2d);
+}
+
+.card-image {
+  width: 100%;
+  height: 160px;
+  overflow: hidden;
+  background: linear-gradient(135deg, #1e3a5f 0%, #1e1e1e 100%);
+}
+
+.card-image img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  transition: transform 0.3s ease;
+}
+
+.feature-card:hover .card-image img {
+  transform: scale(1.05);
+}
+
+.card-body {
+  padding: 16px;
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+}
+
+.card-icon {
+  font-size: 1.5rem;
+  margin-bottom: 12px;
+  width: 40px;
+  height: 40px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: var(--es-bg-input, #3c3c3c);
+  border-radius: 4px;
+}
+
+.card-title {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--es-text-inverse, #ffffff);
+  margin: 0 0 8px 0;
+  line-height: 1.3;
+}
+
+.card-description {
+  font-size: 12px;
+  color: var(--es-text-secondary, #9d9d9d);
+  margin: 0;
+  line-height: 1.6;
+  flex: 1;
+}
+</style>

docs/.vitepress/theme/components/ParticleHero.vue

@@ -0,0 +1,422 @@
+<script setup>
+import { onMounted, onUnmounted, ref } from 'vue'
+
+const canvasRef = ref(null)
+let animationId = null
+let particles = []
+let animationStartTime = null
+let glowStartTime = null
+
+// ESEngine 粒子颜色 - VS Code 风格配色（与编辑器统一）
+const colors = ['#569CD6', '#4EC9B0', '#9CDCFE', '#C586C0', '#DCDCAA']
+
+class Particle {
+  constructor(x, y, targetX, targetY) {
+    this.x = x
+    this.y = y
+    this.targetX = targetX
+    this.targetY = targetY
+    this.size = Math.random() * 2 + 1.5
+    this.alpha = Math.random() * 0.5 + 0.5
+    this.color = colors[Math.floor(Math.random() * colors.length)]
+  }
+}
+
+function createParticles(canvas, text, fontSize) {
+  const tempCanvas = document.createElement('canvas')
+  const tempCtx = tempCanvas.getContext('2d')
+  if (!tempCtx) return []
+
+  tempCtx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+  const textMetrics = tempCtx.measureText(text)
+  const textWidth = textMetrics.width
+  const textHeight = fontSize
+
+  tempCanvas.width = textWidth + 40
+  tempCanvas.height = textHeight + 40
+  tempCtx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+  tempCtx.textAlign = 'center'
+  tempCtx.textBaseline = 'middle'
+  tempCtx.fillStyle = '#ffffff'
+  tempCtx.fillText(text, tempCanvas.width / 2, tempCanvas.height / 2)
+
+  const imageData = tempCtx.getImageData(0, 0, tempCanvas.width, tempCanvas.height)
+  const pixels = imageData.data
+  const newParticles = []
+  const gap = 3
+
+  const width = canvas.width / (window.devicePixelRatio || 1)
+  const height = canvas.height / (window.devicePixelRatio || 1)
+  const offsetX = (width - tempCanvas.width) / 2
+  const offsetY = (height - tempCanvas.height) / 2
+
+  for (let y = 0; y < tempCanvas.height; y += gap) {
+    for (let x = 0; x < tempCanvas.width; x += gap) {
+      const index = (y * tempCanvas.width + x) * 4
+      const alpha = pixels[index + 3] || 0
+
+      if (alpha > 128) {
+        const angle = Math.random() * Math.PI * 2
+        const distance = Math.random() * Math.max(width, height)
+
+        newParticles.push(new Particle(
+          width / 2 + Math.cos(angle) * distance,
+          height / 2 + Math.sin(angle) * distance,
+          offsetX + x,
+          offsetY + y
+        ))
+      }
+    }
+  }
+
+  return newParticles
+}
+
+function easeOutQuart(t) {
+  return 1 - Math.pow(1 - t, 4)
+}
+
+function easeOutCubic(t) {
+  return 1 - Math.pow(1 - t, 3)
+}
+
+function animate(canvas, ctx) {
+  const dpr = window.devicePixelRatio || 1
+  const width = canvas.width / dpr
+  const height = canvas.height / dpr
+
+  const currentTime = performance.now()
+  const duration = 2500
+  const glowDuration = 600
+
+  const elapsed = currentTime - animationStartTime
+  const progress = Math.min(elapsed / duration, 1)
+  const easedProgress = easeOutQuart(progress)
+
+  // 透明背景
+  ctx.clearRect(0, 0, width, height)
+
+  // 计算发光进度
+  let glowProgress = 0
+  if (progress >= 1) {
+    if (glowStartTime === null) {
+      glowStartTime = currentTime
+    }
+    glowProgress = Math.min((currentTime - glowStartTime) / glowDuration, 1)
+    glowProgress = easeOutCubic(glowProgress)
+  }
+
+  const text = 'ESEngine'
+  const fontSize = Math.min(width / 4, height / 3, 80)
+  const textY = height / 2
+
+  for (const particle of particles) {
+    const moveProgress = Math.min(easedProgress * 1.2, 1)
+    const currentX = particle.x + (particle.targetX - particle.x) * moveProgress
+    const currentY = particle.y + (particle.targetY - particle.y) * moveProgress
+
+    ctx.beginPath()
+    ctx.arc(currentX, currentY, particle.size, 0, Math.PI * 2)
+    ctx.fillStyle = particle.color
+    ctx.globalAlpha = particle.alpha * (1 - glowProgress * 0.3)
+    ctx.fill()
+  }
+
+  ctx.globalAlpha = 1
+
+  if (glowProgress > 0) {
+    ctx.save()
+    ctx.shadowColor = '#3b9eff'
+    ctx.shadowBlur = 30 * glowProgress
+    ctx.fillStyle = `rgba(255, 255, 255, ${glowProgress})`
+    ctx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillText(text, width / 2, textY)
+    ctx.restore()
+  }
+
+  if (glowProgress >= 1) {
+    const breathe = 0.8 + Math.sin(currentTime / 1000) * 0.2
+    ctx.save()
+    ctx.shadowColor = '#3b9eff'
+    ctx.shadowBlur = 20 * breathe
+    ctx.fillStyle = '#ffffff'
+    ctx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillText(text, width / 2, textY)
+    ctx.restore()
+  }
+
+  animationId = requestAnimationFrame(() => animate(canvas, ctx))
+}
+
+function initCanvas() {
+  const canvas = canvasRef.value
+  if (!canvas) return
+
+  const ctx = canvas.getContext('2d')
+  if (!ctx) return
+
+  const dpr = window.devicePixelRatio || 1
+  const container = canvas.parentElement
+  const width = container.offsetWidth
+  const height = container.offsetHeight
+
+  canvas.width = width * dpr
+  canvas.height = height * dpr
+  canvas.style.width = `${width}px`
+  canvas.style.height = `${height}px`
+  ctx.scale(dpr, dpr)
+
+  const text = 'ESEngine'
+  const fontSize = Math.min(width / 4, height / 3, 80)
+
+  particles = createParticles(canvas, text, fontSize)
+  animationStartTime = performance.now()
+  glowStartTime = null
+
+  if (animationId) {
+    cancelAnimationFrame(animationId)
+  }
+
+  animate(canvas, ctx)
+}
+
+onMounted(() => {
+  initCanvas()
+  window.addEventListener('resize', initCanvas)
+})
+
+onUnmounted(() => {
+  if (animationId) {
+    cancelAnimationFrame(animationId)
+  }
+  window.removeEventListener('resize', initCanvas)
+})
+</script>
+
+<template>
+  <section class="hero-section">
+    <div class="hero-container">
+      <!-- 左侧文字区域 -->
+      <div class="hero-text">
+        <div class="hero-logo">
+          <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <circle cx="16" cy="16" r="14" stroke="#9147ff" stroke-width="2"/>
+            <path d="M10 10h8v2h-6v3h5v2h-5v3h6v2h-8v-12z" fill="#9147ff"/>
+          </svg>
+          <span>ESENGINE</span>
+        </div>
+        <h1 class="hero-title">
+          我们构建框架。<br/>
+          而你将创造游戏。
+        </h1>
+        <p class="hero-description">
+          ESEngine 是一个高性能的 TypeScript ECS 框架，为游戏开发者提供现代化的实体组件系统。
+          无论是 2D 还是 3D 游戏，都能帮助你快速构建可扩展的游戏架构。
+        </p>
+        <div class="hero-actions">
+          <a href="/guide/getting-started" class="btn-primary">开始使用</a>
+          <a href="https://github.com/esengine/esengine" class="btn-secondary" target="_blank">了解更多</a>
+        </div>
+      </div>
+
+      <!-- 右侧粒子动画区域 -->
+      <div class="hero-visual">
+        <div class="visual-container">
+          <canvas ref="canvasRef" class="particle-canvas"></canvas>
+          <div class="visual-label">
+            <span class="label-title">Entity Component System</span>
+            <span class="label-subtitle">High Performance Framework</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.hero-section {
+  background: #0d0d0d;
+  padding: 80px 0;
+  min-height: calc(100vh - 64px);
+  display: flex;
+  align-items: center;
+}
+
+.hero-container {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 48px;
+  display: grid;
+  grid-template-columns: 1fr 1.2fr;
+  gap: 64px;
+  align-items: center;
+}
+
+/* 左侧文字 */
+.hero-text {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+
+.hero-logo {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  color: #ffffff;
+  font-size: 1rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+}
+
+.hero-title {
+  font-size: 3rem;
+  font-weight: 700;
+  color: #ffffff;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.hero-description {
+  font-size: 1.125rem;
+  color: #707070;
+  line-height: 1.7;
+  margin: 0;
+  max-width: 480px;
+}
+
+.hero-actions {
+  display: flex;
+  gap: 16px;
+  margin-top: 8px;
+}
+
+.btn-primary,
+.btn-secondary {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 14px 28px;
+  border-radius: 4px;
+  font-weight: 600;
+  font-size: 0.9375rem;
+  text-decoration: none;
+  transition: all 0.2s ease;
+}
+
+.btn-primary {
+  background: #3b9eff;
+  color: #ffffff;
+  border: 1px solid #3b9eff;
+  border-radius: 6px;
+}
+
+.btn-primary:hover {
+  background: #5aadff;
+  border-color: #5aadff;
+}
+
+.btn-secondary {
+  background: #1a1a1a;
+  color: #a0a0a0;
+  border: 1px solid #2a2a2a;
+  border-radius: 6px;
+}
+
+.btn-secondary:hover {
+  background: #252525;
+  color: #ffffff;
+}
+
+.hero-visual {
+  display: flex;
+  justify-content: center;
+}
+
+.visual-container {
+  position: relative;
+  width: 100%;
+  max-width: 600px;
+  aspect-ratio: 4 / 3;
+  background: linear-gradient(135deg, #1a2a3a 0%, #1a1a1a 50%, #0d0d0d 100%);
+  border-radius: 12px;
+  border: 1px solid #2a2a2a;
+  overflow: hidden;
+  box-shadow: 0 20px 60px rgba(59, 158, 255, 0.1);
+}
+
+.particle-canvas {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.visual-label {
+  position: absolute;
+  bottom: 24px;
+  left: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.label-title {
+  font-size: 1.125rem;
+  font-weight: 600;
+  color: #ffffff;
+}
+
+.label-subtitle {
+  font-size: 0.875rem;
+  color: #737373;
+}
+
+/* 响应式 */
+@media (max-width: 1024px) {
+  .hero-container {
+    grid-template-columns: 1fr;
+    gap: 48px;
+    padding: 0 24px;
+  }
+
+  .hero-section {
+    padding: 48px 0;
+    min-height: auto;
+  }
+
+  .hero-title {
+    font-size: 2.25rem;
+  }
+
+  .hero-description {
+    font-size: 1rem;
+  }
+
+  .visual-container {
+    max-width: 100%;
+    aspect-ratio: 16 / 9;
+  }
+}
+
+@media (max-width: 640px) {
+  .hero-title {
+    font-size: 1.75rem;
+  }
+
+  .hero-actions {
+    flex-direction: column;
+  }
+
+  .btn-primary,
+  .btn-secondary {
+    width: 100%;
+    justify-content: center;
+  }
+}
+</style>

docs/.vitepress/theme/components/ParticleHeroEn.vue

@@ -0,0 +1,422 @@
+<script setup>
+import { onMounted, onUnmounted, ref } from 'vue'
+
+const canvasRef = ref(null)
+let animationId = null
+let particles = []
+let animationStartTime = null
+let glowStartTime = null
+
+// ESEngine particle colors - VS Code style colors (unified with editor)
+const colors = ['#569CD6', '#4EC9B0', '#9CDCFE', '#C586C0', '#DCDCAA']
+
+class Particle {
+  constructor(x, y, targetX, targetY) {
+    this.x = x
+    this.y = y
+    this.targetX = targetX
+    this.targetY = targetY
+    this.size = Math.random() * 2 + 1.5
+    this.alpha = Math.random() * 0.5 + 0.5
+    this.color = colors[Math.floor(Math.random() * colors.length)]
+  }
+}
+
+function createParticles(canvas, text, fontSize) {
+  const tempCanvas = document.createElement('canvas')
+  const tempCtx = tempCanvas.getContext('2d')
+  if (!tempCtx) return []
+
+  tempCtx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+  const textMetrics = tempCtx.measureText(text)
+  const textWidth = textMetrics.width
+  const textHeight = fontSize
+
+  tempCanvas.width = textWidth + 40
+  tempCanvas.height = textHeight + 40
+  tempCtx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+  tempCtx.textAlign = 'center'
+  tempCtx.textBaseline = 'middle'
+  tempCtx.fillStyle = '#ffffff'
+  tempCtx.fillText(text, tempCanvas.width / 2, tempCanvas.height / 2)
+
+  const imageData = tempCtx.getImageData(0, 0, tempCanvas.width, tempCanvas.height)
+  const pixels = imageData.data
+  const newParticles = []
+  const gap = 3
+
+  const width = canvas.width / (window.devicePixelRatio || 1)
+  const height = canvas.height / (window.devicePixelRatio || 1)
+  const offsetX = (width - tempCanvas.width) / 2
+  const offsetY = (height - tempCanvas.height) / 2
+
+  for (let y = 0; y < tempCanvas.height; y += gap) {
+    for (let x = 0; x < tempCanvas.width; x += gap) {
+      const index = (y * tempCanvas.width + x) * 4
+      const alpha = pixels[index + 3] || 0
+
+      if (alpha > 128) {
+        const angle = Math.random() * Math.PI * 2
+        const distance = Math.random() * Math.max(width, height)
+
+        newParticles.push(new Particle(
+          width / 2 + Math.cos(angle) * distance,
+          height / 2 + Math.sin(angle) * distance,
+          offsetX + x,
+          offsetY + y
+        ))
+      }
+    }
+  }
+
+  return newParticles
+}
+
+function easeOutQuart(t) {
+  return 1 - Math.pow(1 - t, 4)
+}
+
+function easeOutCubic(t) {
+  return 1 - Math.pow(1 - t, 3)
+}
+
+function animate(canvas, ctx) {
+  const dpr = window.devicePixelRatio || 1
+  const width = canvas.width / dpr
+  const height = canvas.height / dpr
+
+  const currentTime = performance.now()
+  const duration = 2500
+  const glowDuration = 600
+
+  const elapsed = currentTime - animationStartTime
+  const progress = Math.min(elapsed / duration, 1)
+  const easedProgress = easeOutQuart(progress)
+
+  // Transparent background
+  ctx.clearRect(0, 0, width, height)
+
+  // Calculate glow progress
+  let glowProgress = 0
+  if (progress >= 1) {
+    if (glowStartTime === null) {
+      glowStartTime = currentTime
+    }
+    glowProgress = Math.min((currentTime - glowStartTime) / glowDuration, 1)
+    glowProgress = easeOutCubic(glowProgress)
+  }
+
+  const text = 'ESEngine'
+  const fontSize = Math.min(width / 4, height / 3, 80)
+  const textY = height / 2
+
+  for (const particle of particles) {
+    const moveProgress = Math.min(easedProgress * 1.2, 1)
+    const currentX = particle.x + (particle.targetX - particle.x) * moveProgress
+    const currentY = particle.y + (particle.targetY - particle.y) * moveProgress
+
+    ctx.beginPath()
+    ctx.arc(currentX, currentY, particle.size, 0, Math.PI * 2)
+    ctx.fillStyle = particle.color
+    ctx.globalAlpha = particle.alpha * (1 - glowProgress * 0.3)
+    ctx.fill()
+  }
+
+  ctx.globalAlpha = 1
+
+  if (glowProgress > 0) {
+    ctx.save()
+    ctx.shadowColor = '#3b9eff'
+    ctx.shadowBlur = 30 * glowProgress
+    ctx.fillStyle = `rgba(255, 255, 255, ${glowProgress})`
+    ctx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillText(text, width / 2, textY)
+    ctx.restore()
+  }
+
+  if (glowProgress >= 1) {
+    const breathe = 0.8 + Math.sin(currentTime / 1000) * 0.2
+    ctx.save()
+    ctx.shadowColor = '#3b9eff'
+    ctx.shadowBlur = 20 * breathe
+    ctx.fillStyle = '#ffffff'
+    ctx.font = `bold ${fontSize}px "Segoe UI", Arial, sans-serif`
+    ctx.textAlign = 'center'
+    ctx.textBaseline = 'middle'
+    ctx.fillText(text, width / 2, textY)
+    ctx.restore()
+  }
+
+  animationId = requestAnimationFrame(() => animate(canvas, ctx))
+}
+
+function initCanvas() {
+  const canvas = canvasRef.value
+  if (!canvas) return
+
+  const ctx = canvas.getContext('2d')
+  if (!ctx) return
+
+  const dpr = window.devicePixelRatio || 1
+  const container = canvas.parentElement
+  const width = container.offsetWidth
+  const height = container.offsetHeight
+
+  canvas.width = width * dpr
+  canvas.height = height * dpr
+  canvas.style.width = `${width}px`
+  canvas.style.height = `${height}px`
+  ctx.scale(dpr, dpr)
+
+  const text = 'ESEngine'
+  const fontSize = Math.min(width / 4, height / 3, 80)
+
+  particles = createParticles(canvas, text, fontSize)
+  animationStartTime = performance.now()
+  glowStartTime = null
+
+  if (animationId) {
+    cancelAnimationFrame(animationId)
+  }
+
+  animate(canvas, ctx)
+}
+
+onMounted(() => {
+  initCanvas()
+  window.addEventListener('resize', initCanvas)
+})
+
+onUnmounted(() => {
+  if (animationId) {
+    cancelAnimationFrame(animationId)
+  }
+  window.removeEventListener('resize', initCanvas)
+})
+</script>
+
+<template>
+  <section class="hero-section">
+    <div class="hero-container">
+      <!-- Left text area -->
+      <div class="hero-text">
+        <div class="hero-logo">
+          <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+            <circle cx="16" cy="16" r="14" stroke="#9147ff" stroke-width="2"/>
+            <path d="M10 10h8v2h-6v3h5v2h-5v3h6v2h-8v-12z" fill="#9147ff"/>
+          </svg>
+          <span>ESENGINE</span>
+        </div>
+        <h1 class="hero-title">
+          We build the framework.<br/>
+          You create the game.
+        </h1>
+        <p class="hero-description">
+          ESEngine is a high-performance TypeScript ECS framework for game developers.
+          Whether 2D or 3D games, it helps you build scalable game architecture quickly.
+        </p>
+        <div class="hero-actions">
+          <a href="/en/guide/getting-started" class="btn-primary">Get Started</a>
+          <a href="https://github.com/esengine/esengine" class="btn-secondary" target="_blank">Learn More</a>
+        </div>
+      </div>
+
+      <!-- Right particle animation area -->
+      <div class="hero-visual">
+        <div class="visual-container">
+          <canvas ref="canvasRef" class="particle-canvas"></canvas>
+          <div class="visual-label">
+            <span class="label-title">Entity Component System</span>
+            <span class="label-subtitle">High Performance Framework</span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </section>
+</template>
+
+<style scoped>
+.hero-section {
+  background: #0d0d0d;
+  padding: 80px 0;
+  min-height: calc(100vh - 64px);
+  display: flex;
+  align-items: center;
+}
+
+.hero-container {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 48px;
+  display: grid;
+  grid-template-columns: 1fr 1.2fr;
+  gap: 64px;
+  align-items: center;
+}
+
+/* Left text */
+.hero-text {
+  display: flex;
+  flex-direction: column;
+  gap: 24px;
+}
+
+.hero-logo {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  color: #ffffff;
+  font-size: 1rem;
+  font-weight: 700;
+  letter-spacing: 0.1em;
+}
+
+.hero-title {
+  font-size: 3rem;
+  font-weight: 700;
+  color: #ffffff;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.hero-description {
+  font-size: 1.125rem;
+  color: #707070;
+  line-height: 1.7;
+  margin: 0;
+  max-width: 480px;
+}
+
+.hero-actions {
+  display: flex;
+  gap: 16px;
+  margin-top: 8px;
+}
+
+.btn-primary,
+.btn-secondary {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 14px 28px;
+  border-radius: 4px;
+  font-weight: 600;
+  font-size: 0.9375rem;
+  text-decoration: none;
+  transition: all 0.2s ease;
+}
+
+.btn-primary {
+  background: #3b9eff;
+  color: #ffffff;
+  border: 1px solid #3b9eff;
+  border-radius: 6px;
+}
+
+.btn-primary:hover {
+  background: #5aadff;
+  border-color: #5aadff;
+}
+
+.btn-secondary {
+  background: #1a1a1a;
+  color: #a0a0a0;
+  border: 1px solid #2a2a2a;
+  border-radius: 6px;
+}
+
+.btn-secondary:hover {
+  background: #252525;
+  color: #ffffff;
+}
+
+.hero-visual {
+  display: flex;
+  justify-content: center;
+}
+
+.visual-container {
+  position: relative;
+  width: 100%;
+  max-width: 600px;
+  aspect-ratio: 4 / 3;
+  background: linear-gradient(135deg, #1a2a3a 0%, #1a1a1a 50%, #0d0d0d 100%);
+  border-radius: 12px;
+  border: 1px solid #2a2a2a;
+  overflow: hidden;
+  box-shadow: 0 20px 60px rgba(59, 158, 255, 0.1);
+}
+
+.particle-canvas {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+}
+
+.visual-label {
+  position: absolute;
+  bottom: 24px;
+  left: 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+}
+
+.label-title {
+  font-size: 1.125rem;
+  font-weight: 600;
+  color: #ffffff;
+}
+
+.label-subtitle {
+  font-size: 0.875rem;
+  color: #737373;
+}
+
+/* Responsive */
+@media (max-width: 1024px) {
+  .hero-container {
+    grid-template-columns: 1fr;
+    gap: 48px;
+    padding: 0 24px;
+  }
+
+  .hero-section {
+    padding: 48px 0;
+    min-height: auto;
+  }
+
+  .hero-title {
+    font-size: 2.25rem;
+  }
+
+  .hero-description {
+    font-size: 1rem;
+  }
+
+  .visual-container {
+    max-width: 100%;
+    aspect-ratio: 16 / 9;
+  }
+}
+
+@media (max-width: 640px) {
+  .hero-title {
+    font-size: 1.75rem;
+  }
+
+  .hero-actions {
+    flex-direction: column;
+  }
+
+  .btn-primary,
+  .btn-secondary {
+    width: 100%;
+    justify-content: center;
+  }
+}
+</style>

docs/.vitepress/theme/custom.css

@@ -0,0 +1,595 @@
+:root {
+  color-scheme: dark;
+  --vp-nav-height: 64px;
+
+  --es-bg-base: #1a1a1a;
+  --es-bg-elevated: #222222;
+  --es-bg-overlay: #2a2a2a;
+  --es-bg-input: #333333;
+  --es-bg-inset: #151515;
+  --es-bg-hover: #2a2d2e;
+  --es-bg-active: #37373d;
+  --es-bg-sidebar: #1e1e1e;
+  --es-bg-card: #242424;
+  --es-bg-header: #1e1e1e;
+
+  /* 提高文字对比度 | Improve text contrast */
+  --es-text-primary: #e0e0e0;
+  --es-text-secondary: #b0b0b0;
+  --es-text-tertiary: #888888;
+  --es-text-inverse: #ffffff;
+  --es-text-muted: #c0c0c0;
+  --es-text-dim: #888888;
+
+  --es-font-xs: 11px;
+  --es-font-sm: 12px;
+  --es-font-base: 13px;
+  --es-font-md: 14px;
+  --es-font-lg: 16px;
+
+  --es-border-default: #3a3a3a;
+  --es-border-subtle: #1a1a1a;
+  --es-border-strong: #4a4a4a;
+
+  --es-primary: #3b82f6;
+  --es-primary-hover: #2563eb;
+  --es-success: #4ade80;
+  --es-warning: #f59e0b;
+  --es-error: #ef4444;
+  --es-info: #3b82f6;
+
+  --es-selected: #3d5a80;
+  --es-selected-hover: #4a6a90;
+}
+
+body {
+  background: var(--es-bg-base) !important;
+}
+
+html,
+html.dark {
+  --vp-c-bg: var(--es-bg-base);
+  --vp-c-bg-soft: var(--es-bg-elevated);
+  --vp-c-bg-mute: var(--es-bg-overlay);
+  --vp-c-bg-alt: var(--es-bg-sidebar);
+  --vp-c-text-1: var(--es-text-primary);
+  --vp-c-text-2: var(--es-text-tertiary);
+  --vp-c-text-3: var(--es-text-muted);
+  --vp-c-divider: var(--es-border-default);
+  --vp-c-divider-light: var(--es-border-subtle);
+}
+
+html:not(.dark) {
+  --vp-c-bg: var(--es-bg-base) !important;
+  --vp-c-bg-soft: var(--es-bg-elevated) !important;
+  --vp-c-bg-mute: var(--es-bg-overlay) !important;
+  --vp-c-bg-alt: var(--es-bg-sidebar) !important;
+  --vp-c-text-1: var(--es-text-primary) !important;
+  --vp-c-text-2: var(--es-text-tertiary) !important;
+  --vp-c-text-3: var(--es-text-muted) !important;
+}
+
+.VPNav {
+  background: var(--es-bg-header) !important;
+  border-bottom: 1px solid var(--es-border-subtle) !important;
+}
+
+.VPNav .VPNavBar {
+  background: var(--es-bg-header) !important;
+}
+
+.VPNav .VPNavBar .wrapper {
+  background: var(--es-bg-header) !important;
+}
+
+.VPNav .VPNavBar::before,
+.VPNav .VPNavBar::after {
+  display: none !important;
+}
+
+.VPNavBar {
+  background: var(--es-bg-header) !important;
+}
+
+.VPNavBar::before {
+  display: none !important;
+}
+
+.VPNavBarTitle .title {
+  color: var(--es-text-primary);
+  font-weight: 500;
+  font-size: var(--es-font-base);
+}
+
+.VPNavBarMenuLink {
+  color: var(--es-text-secondary) !important;
+  font-size: var(--es-font-sm) !important;
+  font-weight: 400 !important;
+}
+
+.VPNavBarMenuLink:hover {
+  color: var(--es-text-primary) !important;
+}
+
+.VPNavBarMenuLink.active {
+  color: var(--es-text-primary) !important;
+}
+
+.VPNavBarSearch .DocSearch-Button {
+  background: var(--es-bg-input) !important;
+  border: 1px solid var(--es-border-default) !important;
+  border-radius: 2px;
+  height: 26px;
+}
+
+.VPSidebar {
+  background: var(--es-bg-sidebar) !important;
+  border-right: 1px solid var(--es-border-subtle) !important;
+}
+
+.VPSidebarItem.level-0 > .item {
+  padding: 8px 0 4px 0;
+}
+
+.VPSidebarItem.level-0 > .item > .text {
+  font-weight: 600;
+  font-size: var(--es-font-xs);
+  color: var(--es-text-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.VPSidebarItem .link {
+  padding: 4px 8px;
+  margin: 1px 0;
+  border-radius: 2px;
+  color: var(--es-text-primary);
+  font-size: var(--es-font-sm);
+  transition: all 0.1s ease;
+  border-left: 2px solid transparent;
+}
+
+.VPSidebarItem .link:hover {
+  background: rgba(255, 255, 255, 0.03);
+  color: var(--es-text-inverse);
+}
+
+.VPSidebarItem.is-active > .item > .link {
+  background: var(--es-selected);
+  color: var(--es-text-inverse);
+  border-left: 2px solid var(--es-primary);
+}
+
+.VPSidebarItem.is-active > .item > .link:hover {
+  background: var(--es-selected-hover);
+}
+
+.VPSidebarItem.level-1 .link {
+  padding-left: 20px;
+  font-size: var(--es-font-sm);
+}
+
+.VPSidebarItem.level-2 .link {
+  padding-left: 32px;
+  font-size: var(--es-font-sm);
+}
+
+.VPSidebarItem .caret {
+  color: var(--es-text-secondary);
+}
+
+.VPSidebarItem .caret:hover {
+  color: var(--es-text-primary);
+}
+
+.VPContent {
+  background: var(--es-bg-card) !important;
+  padding-top: 0 !important;
+}
+
+.VPContent.has-sidebar {
+  background: var(--es-bg-card) !important;
+}
+
+/* 首页布局修复 | Home page layout fix */
+.VPPage {
+  padding-top: 0 !important;
+}
+
+.Layout > .VPContent {
+  padding-top: var(--vp-nav-height) !important;
+}
+
+.VPDoc {
+  background: transparent !important;
+}
+
+.VPNavBar .content {
+  background: var(--es-bg-header) !important;
+}
+
+.VPNavBar .content-body {
+  background: var(--es-bg-header) !important;
+}
+
+.VPNavBar .divider {
+  display: none;
+}
+
+.VPLocalNav {
+  background: var(--es-bg-header) !important;
+  border-bottom: 1px solid var(--es-border-subtle) !important;
+}
+
+.VPNavScreenMenu {
+  background: var(--es-bg-base) !important;
+}
+
+.VPNavScreen {
+  background: var(--es-bg-base) !important;
+}
+
+.curtain {
+  display: none !important;
+}
+
+.VPNav .curtain,
+.VPNavBar .curtain {
+  display: none !important;
+}
+
+[class*="curtain"] {
+  display: none !important;
+}
+
+.VPNav > div::before,
+.VPNav > div::after {
+  display: none !important;
+}
+
+.vp-doc {
+  color: var(--es-text-primary);
+}
+
+.vp-doc h1 {
+  font-size: var(--es-font-lg);
+  font-weight: 600;
+  color: var(--es-text-inverse);
+  border-bottom: none;
+  padding-bottom: 0;
+  margin-bottom: 16px;
+  line-height: 1.3;
+}
+
+.vp-doc h2 {
+  font-size: var(--es-font-md);
+  font-weight: 600;
+  color: var(--es-text-inverse);
+  border-bottom: none;
+  padding-bottom: 0;
+  margin-top: 32px;
+  margin-bottom: 12px;
+  padding: 6px 12px;
+  background: var(--es-bg-header);
+  border-left: 3px solid var(--es-primary);
+}
+
+.vp-doc h3 {
+  font-size: var(--es-font-base);
+  font-weight: 600;
+  color: var(--es-text-primary);
+  margin-top: 20px;
+  margin-bottom: 8px;
+}
+
+.vp-doc p {
+  color: var(--es-text-primary);
+  line-height: 1.7;
+  font-size: var(--es-font-base);
+  margin: 12px 0;
+}
+
+.vp-doc ul,
+.vp-doc ol {
+  padding-left: 20px;
+  margin: 12px 0;
+}
+
+.vp-doc li {
+  line-height: 1.7;
+  margin: 4px 0;
+  color: var(--es-text-primary);
+  font-size: var(--es-font-base);
+}
+
+.vp-doc li::marker {
+  color: var(--es-text-secondary);
+}
+
+.vp-doc strong {
+  color: var(--es-text-primary);
+  font-weight: 600;
+}
+
+.vp-doc a {
+  color: var(--es-primary);
+  text-decoration: none;
+}
+
+.vp-doc a:hover {
+  text-decoration: underline;
+}
+
+.VPDocAside {
+  padding-left: 16px;
+  border-left: 1px solid var(--es-border-subtle);
+}
+
+.VPDocAsideOutline {
+  padding: 0;
+  border: none !important;
+}
+
+.VPDocAsideOutline .content {
+  border: none !important;
+  padding-left: 0 !important;
+}
+
+.VPDocAsideOutline .outline-title {
+  font-size: var(--es-font-xs);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  color: var(--es-text-secondary);
+  padding-bottom: 8px;
+}
+
+.VPDocAsideOutline .outline-link {
+  color: var(--es-text-secondary);
+  font-size: var(--es-font-xs);
+  padding: 4px 0;
+  line-height: 1.4;
+  display: block;
+}
+
+.VPDocAsideOutline .outline-link:hover {
+  color: var(--es-text-primary);
+}
+
+.VPDocAsideOutline .outline-link.active {
+  color: var(--es-primary);
+}
+
+.VPDocAsideOutline .outline-marker {
+  display: none;
+}
+
+div[class*='language-'] {
+  background: var(--es-bg-inset) !important;
+  border: 1px solid var(--es-border-default);
+  border-radius: 2px;
+  margin: 12px 0;
+}
+
+.vp-code-group .tabs {
+  background: var(--es-bg-header);
+  border-bottom: 1px solid var(--es-border-subtle);
+}
+
+.vp-doc :not(pre) > code {
+  background: var(--es-bg-input);
+  color: var(--es-primary);
+  padding: 2px 6px;
+  border-radius: 2px;
+  font-size: var(--es-font-xs);
+}
+
+.vp-doc table {
+  display: table;
+  width: 100%;
+  background: transparent;
+  border: none;
+  border-collapse: collapse;
+  margin: 16px 0;
+  font-size: var(--es-font-sm);
+}
+
+.vp-doc tr {
+  border-bottom: 1px solid var(--es-border-subtle);
+  background: transparent;
+}
+
+.vp-doc tr:last-child {
+  border-bottom: none;
+}
+
+.vp-doc tr:hover {
+  background: rgba(255, 255, 255, 0.02);
+}
+
+.vp-doc th {
+  background: var(--es-bg-header);
+  font-weight: 600;
+  font-size: var(--es-font-xs);
+  color: var(--es-text-secondary);
+  text-align: left;
+  padding: 8px 12px;
+  border-bottom: 1px solid var(--es-border-subtle);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+
+.vp-doc td {
+  font-size: var(--es-font-sm);
+  color: var(--es-text-primary);
+  padding: 8px 12px;
+  vertical-align: top;
+  line-height: 1.5;
+}
+
+.vp-doc td:first-child {
+  font-weight: 500;
+  color: var(--es-text-primary);
+  min-width: 100px;
+}
+
+.vp-doc .warning,
+.vp-doc .custom-block.warning {
+  background: rgba(245, 158, 11, 0.08);
+  border: none;
+  border-left: 3px solid var(--es-warning);
+  border-radius: 0 2px 2px 0;
+  padding: 10px 12px;
+  margin: 16px 0;
+}
+
+.vp-doc .warning .custom-block-title,
+.vp-doc .custom-block.warning .custom-block-title {
+  color: var(--es-warning);
+  font-weight: 600;
+  font-size: var(--es-font-xs);
+  margin-bottom: 4px;
+}
+
+.vp-doc .warning p {
+  color: var(--es-text-primary);
+  margin: 0;
+  font-size: var(--es-font-xs);
+}
+
+.vp-doc .tip,
+.vp-doc .custom-block.tip {
+  background: rgba(59, 130, 246, 0.08);
+  border: none;
+  border-left: 3px solid var(--es-primary);
+  border-radius: 0 2px 2px 0;
+  padding: 10px 12px;
+  margin: 16px 0;
+}
+
+.vp-doc .tip .custom-block-title,
+.vp-doc .custom-block.tip .custom-block-title {
+  color: var(--es-primary);
+  font-weight: 600;
+  font-size: var(--es-font-xs);
+  margin-bottom: 4px;
+}
+
+.vp-doc .tip p {
+  color: var(--es-text-primary);
+  margin: 0;
+  font-size: var(--es-font-xs);
+}
+
+.vp-doc .info,
+.vp-doc .custom-block.info {
+  background: rgba(74, 222, 128, 0.08);
+  border: none;
+  border-left: 3px solid var(--es-success);
+  border-radius: 0 2px 2px 0;
+  padding: 10px 12px;
+  margin: 16px 0;
+}
+
+.vp-doc .info .custom-block-title,
+.vp-doc .custom-block.info .custom-block-title {
+  color: var(--es-success);
+  font-weight: 600;
+  font-size: var(--es-font-xs);
+  margin-bottom: 4px;
+}
+
+.vp-doc .danger,
+.vp-doc .custom-block.danger {
+  background: rgba(239, 68, 68, 0.08);
+  border: none;
+  border-left: 3px solid var(--es-error);
+  border-radius: 0 2px 2px 0;
+  padding: 10px 12px;
+  margin: 16px 0;
+}
+
+.vp-doc .danger .custom-block-title,
+.vp-doc .custom-block.danger .custom-block-title {
+  color: var(--es-error);
+  font-weight: 600;
+  font-size: var(--es-font-xs);
+  margin-bottom: 4px;
+}
+
+.vp-doc .card {
+  background: var(--es-bg-sidebar);
+  border: 1px solid var(--es-border-subtle);
+  border-radius: 4px;
+  padding: 12px;
+  margin: 16px 0;
+}
+
+.vp-doc .card-title {
+  font-size: var(--es-font-sm);
+  font-weight: 600;
+  color: var(--es-text-primary);
+  margin-bottom: 6px;
+}
+
+.vp-doc .card-description {
+  font-size: var(--es-font-xs);
+  color: var(--es-text-muted);
+  line-height: 1.5;
+}
+
+.vp-doc .tag {
+  display: inline-block;
+  padding: 2px 8px;
+  background: transparent;
+  border: 1px solid var(--es-border-default);
+  border-radius: 2px;
+  color: var(--es-text-secondary);
+  font-size: var(--es-font-xs);
+  margin-right: 4px;
+  margin-bottom: 4px;
+}
+
+.VPFooter {
+  background: var(--es-bg-sidebar) !important;
+  border-top: 1px solid var(--es-border-subtle) !important;
+}
+
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--es-bg-card);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--es-border-strong);
+  border-radius: 4px;
+  border: 2px solid var(--es-bg-card);
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: #5a5a5a;
+}
+
+::-webkit-scrollbar-corner {
+  background: transparent;
+}
+
+.home-container {
+  max-width: 1000px;
+  margin: 0 auto;
+  padding: 0 16px;
+}
+
+.home-section {
+  padding: 32px 0;
+}
+
+@media (max-width: 960px) {
+  .VPDoc .content {
+    padding: 16px !important;
+  }
+}

docs/.vitepress/theme/index.js

@@ -0,0 +1,14 @@
+import DefaultTheme from 'vitepress/theme'
+import ParticleHero from './components/ParticleHero.vue'
+import ParticleHeroEn from './components/ParticleHeroEn.vue'
+import FeatureCard from './components/FeatureCard.vue'
+import './custom.css'
+
+export default {
+  extends: DefaultTheme,
+  enhanceApp({ app }) {
+    app.component('ParticleHero', ParticleHero)
+    app.component('ParticleHeroEn', ParticleHeroEn)
+    app.component('FeatureCard', FeatureCard)
+  }
+}

docs/architecture/material-system-refactor.md

@@ -0,0 +1,663 @@
+# ESEngine 材质系统统一架构重构方案
+
+## 问题概述
+
+当前 UI 和 Scene (Sprite) 两套渲染系统存在大量代码重复：
+
+| 重复项 | Sprite | UI | 重复度 |
+|--------|--------|----|----|
+| 材质属性覆盖接口 | `MaterialPropertyOverride` | `UIMaterialPropertyOverride` | 100% |
+| 材质方法 (12个) | `SpriteComponent` | `UIRenderComponent` | 100% |
+| ShinyEffect 组件 | `ShinyEffectComponent` | `UIShinyEffectComponent` | 99% |
+| ShinyEffect 系统 | `ShinyEffectSystem` | `UIShinyEffectSystem` | 98% |
+
+**根本原因**：缺乏统一的材质覆盖接口抽象层。
+
+---
+
+## 一、统一材质覆盖接口
+
+### 1.1 定义通用接口
+
+在 `@esengine/material-system` 包中定义统一接口：
+
+```typescript
+// packages/material-system/src/interfaces/IMaterialOverridable.ts
+
+/**
+ * Material property override definition.
+ * 材质属性覆盖定义。
+ */
+export interface MaterialPropertyOverride {
+    type: 'float' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'int';
+    value: number | number[];
+}
+
+export type MaterialOverrides = Record<string, MaterialPropertyOverride>;
+
+/**
+ * Interface for components that support material property overrides.
+ * 支持材质属性覆盖的组件接口。
+ */
+export interface IMaterialOverridable {
+    /** Material GUID for asset reference | 材质资产引用的 GUID */
+    materialGuid: string;
+
+    /** Current material overrides | 当前材质覆盖 */
+    readonly materialOverrides: MaterialOverrides;
+
+    /** Get current material ID | 获取当前材质 ID */
+    getMaterialId(): number;
+
+    /** Set material ID | 设置材质 ID */
+    setMaterialId(id: number): void;
+
+    // Uniform setters
+    setOverrideFloat(name: string, value: number): this;
+    setOverrideVec2(name: string, x: number, y: number): this;
+    setOverrideVec3(name: string, x: number, y: number, z: number): this;
+    setOverrideVec4(name: string, x: number, y: number, z: number, w: number): this;
+    setOverrideColor(name: string, r: number, g: number, b: number, a?: number): this;
+    setOverrideInt(name: string, value: number): this;
+
+    // Uniform getters
+    getOverride(name: string): MaterialPropertyOverride | undefined;
+    removeOverride(name: string): this;
+    clearOverrides(): this;
+    hasOverrides(): boolean;
+}
+```
+
+### 1.2 创建 Mixin 实现
+
+使用 Mixin 模式避免代码重复：
+
+```typescript
+// packages/material-system/src/mixins/MaterialOverridableMixin.ts
+
+import type { MaterialPropertyOverride, MaterialOverrides } from '../interfaces/IMaterialOverridable';
+
+/**
+ * Mixin that provides material override functionality.
+ * 提供材质覆盖功能的 Mixin。
+ */
+export function MaterialOverridableMixin<TBase extends new (...args: any[]) => {}>(Base: TBase) {
+    return class extends Base {
+        materialGuid: string = '';
+        private _materialId: number = 0;
+        private _materialOverrides: MaterialOverrides = {};
+
+        get materialOverrides(): MaterialOverrides {
+            return this._materialOverrides;
+        }
+
+        getMaterialId(): number {
+            return this._materialId;
+        }
+
+        setMaterialId(id: number): void {
+            this._materialId = id;
+        }
+
+        setOverrideFloat(name: string, value: number): this {
+            this._materialOverrides[name] = { type: 'float', value };
+            return this;
+        }
+
+        setOverrideVec2(name: string, x: number, y: number): this {
+            this._materialOverrides[name] = { type: 'vec2', value: [x, y] };
+            return this;
+        }
+
+        setOverrideVec3(name: string, x: number, y: number, z: number): this {
+            this._materialOverrides[name] = { type: 'vec3', value: [x, y, z] };
+            return this;
+        }
+
+        setOverrideVec4(name: string, x: number, y: number, z: number, w: number): this {
+            this._materialOverrides[name] = { type: 'vec4', value: [x, y, z, w] };
+            return this;
+        }
+
+        setOverrideColor(name: string, r: number, g: number, b: number, a: number = 1.0): this {
+            this._materialOverrides[name] = { type: 'color', value: [r, g, b, a] };
+            return this;
+        }
+
+        setOverrideInt(name: string, value: number): this {
+            this._materialOverrides[name] = { type: 'int', value: Math.floor(value) };
+            return this;
+        }
+
+        getOverride(name: string): MaterialPropertyOverride | undefined {
+            return this._materialOverrides[name];
+        }
+
+        removeOverride(name: string): this {
+            delete this._materialOverrides[name];
+            return this;
+        }
+
+        clearOverrides(): this {
+            this._materialOverrides = {};
+            return this;
+        }
+
+        hasOverrides(): boolean {
+            return Object.keys(this._materialOverrides).length > 0;
+        }
+    };
+}
+```
+
+---
+
+## 二、Shader Property 元数据系统
+
+### 2.1 定义属性元数据接口
+
+```typescript
+// packages/material-system/src/interfaces/IShaderProperty.ts
+
+/**
+ * Shader property UI metadata.
+ * 着色器属性 UI 元数据。
+ */
+export interface ShaderPropertyMeta {
+    /** Property type | 属性类型 */
+    type: 'float' | 'vec2' | 'vec3' | 'vec4' | 'color' | 'int' | 'texture';
+
+    /** Display label (supports i18n key) | 显示标签（支持 i18n 键） */
+    label: string;
+
+    /** Property group for organization | 属性分组 */
+    group?: string;
+
+    /** Default value | 默认值 */
+    default?: number | number[] | string;
+
+    // Numeric constraints
+    min?: number;
+    max?: number;
+    step?: number;
+
+    /** UI hints | UI 提示 */
+    hint?: 'range' | 'angle' | 'hdr' | 'normal';
+
+    /** Tooltip description | 工具提示描述 */
+    tooltip?: string;
+
+    /** Whether to hide in inspector | 是否在检查器中隐藏 */
+    hidden?: boolean;
+}
+
+/**
+ * Extended shader definition with property metadata.
+ * 带属性元数据的扩展着色器定义。
+ */
+export interface ShaderAssetDefinition {
+    /** Shader name | 着色器名称 */
+    name: string;
+
+    /** Display name for UI | UI 显示名称 */
+    displayName?: string;
+
+    /** Shader description | 着色器描述 */
+    description?: string;
+
+    /** Vertex shader source (inline or path) | 顶点着色器源（内联或路径）*/
+    vertexSource: string;
+
+    /** Fragment shader source (inline or path) | 片段着色器源（内联或路径）*/
+    fragmentSource: string;
+
+    /** Property metadata for inspector | 检查器属性元数据 */
+    properties?: Record<string, ShaderPropertyMeta>;
+
+    /** Render queue / order | 渲染队列/顺序 */
+    renderQueue?: number;
+
+    /** Preset blend mode | 预设混合模式 */
+    blendMode?: 'alpha' | 'additive' | 'multiply' | 'opaque';
+}
+```
+
+### 2.2 .shader 资产文件格式
+
+```json
+{
+  "$schema": "esengine://schemas/shader.json",
+  "version": 1,
+  "name": "Shiny",
+  "displayName": "闪光效果 | Shiny Effect",
+  "description": "扫光高亮动画着色器 | Sweeping highlight animation shader",
+
+  "vertexSource": "./shaders/sprite.vert",
+  "fragmentSource": "./shaders/shiny.frag",
+
+  "blendMode": "alpha",
+  "renderQueue": 2000,
+
+  "properties": {
+    "u_shinyProgress": {
+      "type": "float",
+      "label": "进度 | Progress",
+      "group": "Animation",
+      "default": 0,
+      "min": 0,
+      "max": 1,
+      "step": 0.01,
+      "hidden": true
+    },
+    "u_shinyWidth": {
+      "type": "float",
+      "label": "宽度 | Width",
+      "group": "Effect",
+      "default": 0.25,
+      "min": 0,
+      "max": 1,
+      "step": 0.01,
+      "tooltip": "闪光带宽度 | Width of the shiny band"
+    },
+    "u_shinyRotation": {
+      "type": "float",
+      "label": "角度 | Rotation",
+      "group": "Effect",
+      "default": 2.25,
+      "min": 0,
+      "max": 6.28,
+      "step": 0.01,
+      "hint": "angle"
+    },
+    "u_shinySoftness": {
+      "type": "float",
+      "label": "柔和度 | Softness",
+      "group": "Effect",
+      "default": 1.0,
+      "min": 0,
+      "max": 1,
+      "step": 0.01
+    },
+    "u_shinyBrightness": {
+      "type": "float",
+      "label": "亮度 | Brightness",
+      "group": "Effect",
+      "default": 1.0,
+      "min": 0,
+      "max": 2,
+      "step": 0.01
+    },
+    "u_shinyGloss": {
+      "type": "float",
+      "label": "光泽度 | Gloss",
+      "group": "Effect",
+      "default": 1.0,
+      "min": 0,
+      "max": 1,
+      "step": 0.01,
+      "tooltip": "0=白色高光, 1=带颜色 | 0=white shine, 1=color-tinted"
+    }
+  }
+}
+```
+
+---
+
+## 三、统一效果组件/系统架构
+
+### 3.1 抽取通用 ShinyEffect 基类
+
+```typescript
+// packages/material-system/src/effects/BaseShinyEffect.ts
+
+import { Component, Property, Serializable, Serialize } from '@esengine/ecs-framework';
+
+/**
+ * Base shiny effect configuration (shared between UI and Sprite).
+ * 基础闪光效果配置（UI 和 Sprite 共享）。
+ */
+export abstract class BaseShinyEffect extends Component {
+    // ============= Effect Parameters =============
+    @Serialize()
+    @Property({ type: 'number', label: 'Width', min: 0, max: 1, step: 0.01 })
+    public width: number = 0.25;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Rotation', min: 0, max: 360, step: 1 })
+    public rotation: number = 129;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Softness', min: 0, max: 1, step: 0.01 })
+    public softness: number = 1.0;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Brightness', min: 0, max: 2, step: 0.01 })
+    public brightness: number = 1.0;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Gloss', min: 0, max: 2, step: 0.01 })
+    public gloss: number = 1.0;
+
+    // ============= Animation Settings =============
+    @Serialize()
+    @Property({ type: 'boolean', label: 'Play' })
+    public play: boolean = true;
+
+    @Serialize()
+    @Property({ type: 'boolean', label: 'Loop' })
+    public loop: boolean = true;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Duration', min: 0.1, step: 0.1 })
+    public duration: number = 2.0;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Loop Delay', min: 0, step: 0.1 })
+    public loopDelay: number = 2.0;
+
+    @Serialize()
+    @Property({ type: 'number', label: 'Initial Delay', min: 0, step: 0.1 })
+    public initialDelay: number = 0;
+
+    // ============= Runtime State =============
+    public progress: number = 0;
+    public elapsedTime: number = 0;
+    public inDelay: boolean = false;
+    public delayRemaining: number = 0;
+    public initialDelayProcessed: boolean = false;
+
+    reset(): void {
+        this.progress = 0;
+        this.elapsedTime = 0;
+        this.inDelay = false;
+        this.delayRemaining = 0;
+        this.initialDelayProcessed = false;
+    }
+
+    start(): void {
+        this.reset();
+        this.play = true;
+    }
+
+    stop(): void {
+        this.play = false;
+    }
+
+    getRotationRadians(): number {
+        return this.rotation * Math.PI / 180;
+    }
+}
+```
+
+### 3.2 通用动画更新逻辑
+
+```typescript
+// packages/material-system/src/effects/ShinyEffectAnimator.ts
+
+import type { BaseShinyEffect } from './BaseShinyEffect';
+import type { IMaterialOverridable } from '../interfaces/IMaterialOverridable';
+import { BuiltInShaders } from '../types';
+
+/**
+ * Shared animator logic for shiny effect.
+ * 闪光效果共享的动画逻辑。
+ */
+export class ShinyEffectAnimator {
+    /**
+     * Update animation state.
+     * 更新动画状态。
+     */
+    static updateAnimation(shiny: BaseShinyEffect, deltaTime: number): void {
+        if (!shiny.initialDelayProcessed && shiny.initialDelay > 0) {
+            shiny.delayRemaining = shiny.initialDelay;
+            shiny.inDelay = true;
+            shiny.initialDelayProcessed = true;
+        }
+
+        if (shiny.inDelay) {
+            shiny.delayRemaining -= deltaTime;
+            if (shiny.delayRemaining <= 0) {
+                shiny.inDelay = false;
+                shiny.elapsedTime = 0;
+            }
+            return;
+        }
+
+        shiny.elapsedTime += deltaTime;
+        shiny.progress = Math.min(shiny.elapsedTime / shiny.duration, 1.0);
+
+        if (shiny.progress >= 1.0) {
+            if (shiny.loop) {
+                shiny.inDelay = true;
+                shiny.delayRemaining = shiny.loopDelay;
+                shiny.progress = 0;
+                shiny.elapsedTime = 0;
+            } else {
+                shiny.play = false;
+                shiny.progress = 1.0;
+            }
+        }
+    }
+
+    /**
+     * Apply material overrides.
+     * 应用材质覆盖。
+     */
+    static applyMaterialOverrides(shiny: BaseShinyEffect, target: IMaterialOverridable): void {
+        if (target.getMaterialId() === 0) {
+            target.setMaterialId(BuiltInShaders.Shiny);
+        }
+
+        target.setOverrideFloat('u_shinyProgress', shiny.progress);
+        target.setOverrideFloat('u_shinyWidth', shiny.width);
+        target.setOverrideFloat('u_shinyRotation', shiny.getRotationRadians());
+        target.setOverrideFloat('u_shinySoftness', shiny.softness);
+        target.setOverrideFloat('u_shinyBrightness', shiny.brightness);
+        target.setOverrideFloat('u_shinyGloss', shiny.gloss);
+    }
+}
+```
+
+---
+
+## 四、Material Inspector 设计
+
+### 4.1 组件架构
+
+```
+MaterialPropertiesEditor (容器组件)
+├── ShaderSelector (着色器选择器)
+├── PropertyGroup (属性分组)
+│   ├── FloatProperty (浮点属性)
+│   ├── VectorProperty (向量属性)
+│   ├── ColorProperty (颜色属性)
+│   └── TextureProperty (纹理属性)
+└── OverrideIndicator (覆盖指示器)
+```
+
+### 4.2 核心组件
+
+```typescript
+// packages/editor-app/src/components/inspectors/material/MaterialPropertiesEditor.tsx
+
+interface MaterialPropertiesEditorProps {
+    /** Target component implementing IMaterialOverridable */
+    target: IMaterialOverridable;
+    /** Current shader definition with property metadata */
+    shaderDef?: ShaderAssetDefinition;
+    /** Callback when property changes */
+    onChange?: (name: string, value: MaterialPropertyOverride) => void;
+}
+
+export const MaterialPropertiesEditor: React.FC<MaterialPropertiesEditorProps> = ({
+    target,
+    shaderDef,
+    onChange
+}) => {
+    // Group properties by their group field
+    const groupedProps = useMemo(() => {
+        if (!shaderDef?.properties) return {};
+
+        const groups: Record<string, Array<[string, ShaderPropertyMeta]>> = {};
+        for (const [name, meta] of Object.entries(shaderDef.properties)) {
+            if (meta.hidden) continue;
+            const group = meta.group || 'Default';
+            if (!groups[group]) groups[group] = [];
+            groups[group].push([name, meta]);
+        }
+        return groups;
+    }, [shaderDef]);
+
+    return (
+        <div className="material-properties-editor">
+            <ShaderSelector
+                currentShaderId={target.getMaterialId()}
+                onSelect={(id) => target.setMaterialId(id)}
+            />
+
+            {Object.entries(groupedProps).map(([group, props]) => (
+                <PropertyGroup key={group} title={group}>
+                    {props.map(([name, meta]) => (
+                        <PropertyField
+                            key={name}
+                            name={name}
+                            meta={meta}
+                            value={target.getOverride(name)?.value ?? meta.default}
+                            onChange={(value) => {
+                                applyOverride(target, name, meta.type, value);
+                                onChange?.(name, target.getOverride(name)!);
+                            }}
+                        />
+                    ))}
+                </PropertyGroup>
+            ))}
+        </div>
+    );
+};
+```
+
+---
+
+## 五、实施计划
+
+### Phase 1: 接口层 (1-2 天)
+
+1. **创建 IMaterialOverridable 接口** (`packages/material-system/src/interfaces/`)
+2. **创建 MaterialOverridableMixin** (`packages/material-system/src/mixins/`)
+3. **导出新接口** (`packages/material-system/src/index.ts`)
+
+### Phase 2: 重构现有组件 (2-3 天)
+
+1. **修改 SpriteComponent**：实现 `IMaterialOverridable`，使用 Mixin
+2. **修改 UIRenderComponent**：实现 `IMaterialOverridable`，使用 Mixin
+3. **删除重复代码**：移除各组件中的重复材质方法
+
+### Phase 3: 统一效果系统 (2-3 天)
+
+1. **创建 BaseShinyEffect** (`packages/material-system/src/effects/`)
+2. **创建 ShinyEffectAnimator** (`packages/material-system/src/effects/`)
+3. **重构 ShinyEffectComponent**：继承 BaseShinyEffect
+4. **重构 UIShinyEffectComponent**：继承 BaseShinyEffect
+5. **重构系统**：使用 ShinyEffectAnimator
+
+### Phase 4: Shader Property 系统 (2-3 天)
+
+1. **定义 ShaderPropertyMeta 接口**
+2. **扩展 ShaderDefinition** 添加 properties 字段
+3. **创建 ShaderLoader** 支持 .shader 文件
+4. **注册内置着色器属性元数据**
+
+### Phase 5: Material Inspector (3-4 天)
+
+1. **创建 MaterialPropertiesEditor 组件**
+2. **创建 PropertyField 组件** (Float, Vector, Color, Texture)
+3. **集成到现有 Inspector 系统**
+4. **支持实时预览**
+
+---
+
+## 六、文件修改清单
+
+| 优先级 | 包 | 文件 | 操作 |
+|--------|-----|------|------|
+| P0 | material-system | `src/interfaces/IMaterialOverridable.ts` | 新建 |
+| P0 | material-system | `src/mixins/MaterialOverridableMixin.ts` | 新建 |
+| P0 | material-system | `src/interfaces/IShaderProperty.ts` | 新建 |
+| P1 | material-system | `src/effects/BaseShinyEffect.ts` | 新建 |
+| P1 | material-system | `src/effects/ShinyEffectAnimator.ts` | 新建 |
+| P1 | sprite | `src/SpriteComponent.ts` | 重构 |
+| P1 | ui | `src/components/UIRenderComponent.ts` | 重构 |
+| P2 | sprite | `src/ShinyEffectComponent.ts` | 重构 |
+| P2 | ui | `src/components/UIShinyEffectComponent.ts` | 重构 |
+| P2 | sprite | `src/systems/ShinyEffectSystem.ts` | 重构 |
+| P2 | ui | `src/systems/render/UIShinyEffectSystem.ts` | 重构 |
+| P3 | material-system | `src/loaders/ShaderLoader.ts` | 扩展 |
+| P3 | editor-app | `src/components/inspectors/material/*` | 新建 |
+
+---
+
+## 七、Transform 组件统一（可选）
+
+### 7.1 现状分析
+
+| 特性 | TransformComponent | UITransformComponent |
+|------|-------------------|---------------------|
+| **坐标系** | 绝对坐标 (position.x/y/z) | 相对锚点坐标 (x/y + anchor) |
+| **尺寸** | ❌ 无 | ✅ width/height + 约束 |
+| **锚点系统** | ❌ 无 | ✅ anchorMin/Max |
+| **3D 支持** | ✅ IVector3 | ❌ 纯 2D |
+| **可见性** | ❌ 无 | ✅ visible, alpha |
+
+### 7.2 结论
+
+**不建议完全合并**，但可提取公共基类：
+
+```typescript
+// packages/engine-core/src/interfaces/ITransformBase.ts
+
+export interface ITransformBase {
+    /** 旋转角度（度） | Rotation in degrees */
+    rotation: number;
+
+    /** X 缩放 | Scale X */
+    scaleX: number;
+
+    /** Y 缩放 | Scale Y */
+    scaleY: number;
+
+    /** 本地到世界矩阵 | Local to world matrix */
+    readonly localToWorldMatrix: Matrix2D;
+
+    /** 是否需要更新 | Dirty flag */
+    isDirty: boolean;
+
+    /** 世界坐标 X | World position X */
+    readonly worldX: number;
+
+    /** 世界坐标 Y | World position Y */
+    readonly worldY: number;
+
+    /** 世界旋转 | World rotation */
+    readonly worldRotation: number;
+
+    /** 世界缩放 X | World scale X */
+    readonly worldScaleX: number;
+
+    /** 世界缩放 Y | World scale Y */
+    readonly worldScaleY: number;
+}
+```
+
+### 7.3 收益
+
+- 渲染系统可以统一处理 `ITransformBase`
+- 减少 SpriteRenderSystem 和 UIRenderSystem 的重复
+- Gizmo 系统可以共享变换操作逻辑
+
+---
+
+## 八、向后兼容性
+
+1. **接口兼容**：现有组件的 API 保持不变
+2. **序列化兼容**：不改变现有序列化格式
+3. **渐进迁移**：可分阶段进行，不影响现有功能

docs/changelog.md

@@ -0,0 +1,293 @@
+# Changelog
+
+本文档记录 `@esengine/ecs-framework` 核心库的版本更新历史。
+
+---
+
+## v2.4.2 (2025-12-25)
+
+### Features
+
+- **IncrementalSerializer 实体过滤**: 增量序列化支持 `entityFilter` 选项 (#335)
+  - 创建快照时可按条件过滤实体
+  - 支持按标签、组件类型等自定义过滤逻辑
+  - 适用于只同步部分实体的场景（如只同步玩家）
+
+```typescript
+// 只快照玩家实体
+const snapshot = IncrementalSerializer.createSnapshot(scene, {
+    entityFilter: (entity) => entity.tag === PLAYER_TAG
+});
+
+// 只快照有特定组件的实体
+const snapshot = IncrementalSerializer.createSnapshot(scene, {
+    entityFilter: (entity) => entity.hasComponent(PlayerMarker)
+});
+```
+
+### Refactor
+
+- 优化 `PlatformWorkerPool` 代码规范，提取为独立模块 (#335)
+- 优化 `WorkerEntitySystem` 实现，改进代码结构 (#334)
+- 代码规范化与依赖清理 (#317)
+- 代码结构优化，添加 `GlobalTypes.ts` 统一类型定义 (#316)
+
+---
+
+## v2.4.1 (2025-12-23)
+
+### Bug Fixes
+
+- 修复 `IntervalSystem` 时间累加 bug，间隔计时更加准确
+- 修复 Cocos Creator 兼容性问题，类型导出更完整
+
+### Documentation
+
+- 新增 `Core.paused` 属性文档说明
+
+---
+
+## v2.4.0 (2025-12-15)
+
+### Features
+
+- **EntityHandle 实体句柄**: 轻量级实体引用抽象 (#304)
+  - 28位索引 + 20位代数（generation）设计，高效复用已销毁实体槽位
+  - `EntityHandleManager` 管理句柄生命周期和有效性验证
+  - 支持句柄转换为实体引用，检测悬空引用
+
+- **SystemScheduler 系统调度器**: 声明式系统调度 (#304)
+  - 新增 `@Stage(name)` 装饰器指定系统执行阶段
+  - 新增 `@Before(SystemClass)` / `@After(SystemClass)` 装饰器声明系统依赖
+  - 新增 `@InSet(setName)` 装饰器将系统归入逻辑分组
+  - 基于拓扑排序自动解析执行顺序，检测循环依赖
+
+- **EpochManager 变更检测**: 帧级变更追踪机制 (#304)
+  - 跟踪组件添加/修改时间戳（epoch）
+  - 支持查询"自上次检查以来变化的组件"
+  - 适用于脏检测、增量更新等优化场景
+
+- **CompiledQuery 编译查询**: 预编译类型安全查询 (#304)
+  - 编译时生成优化的查询逻辑，减少运行时开销
+  - 完整的 TypeScript 类型推断支持
+  - 支持 `With`、`Without`、`Changed` 等查询条件组合
+
+- **PluginServiceRegistry**: 类型安全的插件服务注册表 (#300)
+  - 通过 `Core.pluginServices` 访问
+  - 支持 `ServiceToken<T>` 模式获取服务
+
+- **组件自动注册**: `@ECSComponent` 装饰器增强 (#302)
+  - 装饰器现在自动注册到 `ComponentRegistry`
+  - 解决 `Decorators ↔ ComponentRegistry` 循环依赖
+  - 新建 `ComponentTypeUtils.ts` 作为底层无依赖模块
+
+### API Changes
+
+- `EntitySystem` 添加 `getBefore()` / `getAfter()` / `getSets()` getter 方法
+- `Entity` 添加 `markDirty()` 辅助方法用于手动触发变更检测
+- `IScene` 添加 `epochManager` 属性
+- `CommandBuffer.pendingCount` 修正为返回实际操作数（而非实体数）
+
+### Documentation
+
+- 更新系统调度文档，添加声明式依赖配置章节
+- 更新实体查询文档，添加编译查询使用说明
+
+---
+
+## v2.3.2 (2025-12-08)
+
+### Features
+
+- **微信小游戏 Worker 支持**: 添加对微信小游戏平台 Worker 的完整支持 (#297)
+  - 新增 `workerScriptPath` 配置项，支持预编译 Worker 脚本路径
+  - 修复微信小游戏 Worker 消息格式差异（`res` 直接是数据，无需 `.data`）
+  - 适用于微信小游戏等不支持动态脚本的平台
+
+### New Package
+
+- **@esengine/worker-generator** `v1.0.2`: CLI 工具，从 `WorkerEntitySystem` 子类自动生成 Worker 文件
+  - 自动扫描并提取 `workerProcess` 方法体
+  - 支持 `--wechat` 模式，使用 TypeScript 编译器转换为 ES5 语法
+  - 读取代码中的 `workerScriptPath` 配置，生成到指定路径
+  - 生成 `worker-mapping.json` 映射文件
+
+### Documentation
+
+- 更新 Worker 系统文档，添加微信小游戏支持章节
+- 新增英文版 Worker 系统文档 (`docs/en/guide/worker-system.md`)
+
+---
+
+## v2.3.1 (2025-12-07)
+
+### Bug Fixes
+
+- **类型导出修复**: 修复 v2.3.0 中的类型导出问题
+  - 解决 `ServiceToken` 跨包类型兼容性问题
+  - 修复 `editor-app` 和 `behavior-tree-editor` 中的类型引用
+
+---
+
+## v2.3.0 (2025-12-06) ⚠️ DEPRECATED
+
+> **警告**: 此版本存在类型导出问题，请升级到 v2.3.1 或更高版本。
+>
+> **Warning**: This version has type export issues. Please upgrade to v2.3.1 or later.
+
+### Features
+
+- **持久化实体**: 添加实体跨场景迁移支持 (#285)
+  - 新增 `EEntityLifecyclePolicy` 枚举（`SceneLocal`/`Persistent`）
+  - Entity 添加 `setPersistent()`、`setSceneLocal()`、`isPersistent` API
+  - Scene 添加 `findPersistentEntities()`、`extractPersistentEntities()`、`receiveMigratedEntities()`
+  - `SceneManager.setScene()` 自动处理持久化实体迁移
+  - 适用场景：全局管理器、玩家角色、跨场景状态保持
+
+- **CommandBuffer 延迟命令系统**: 在帧末统一执行实体操作 (#281)
+  - 支持延迟添加/移除组件、销毁实体、设置实体激活状态
+  - 每个系统拥有独立的 `commands` 属性
+  - 避免在迭代过程中修改实体列表，防止迭代问题
+  - Scene 在 `lateUpdate` 后自动刷新所有命令缓冲区
+
+### Performance
+
+- **ReactiveQuery 快照优化**: 优化实体查询迭代性能 (#281)
+  - 添加快照机制，避免每帧拷贝数组
+  - 只在实体列表变化时创建新快照
+  - 静态场景下多个系统共享同一快照
+
+---
+
+## v2.2.21 (2025-12-05)
+
+### Bug Fixes
+
+- **迭代安全修复**: 修复 `process`/`lateProcess` 迭代时组件变化导致跳过实体的问题 (#272)
+  - 在系统处理过程中添加/移除组件不再导致实体被意外跳过
+
+### Performance
+
+- **HierarchySystem 性能优化**: 优化层级系统避免每帧遍历所有实体 (#279)
+  - 使用脏实体集合代替每帧遍历所有实体
+  - 静态场景下 `process()` 从 O(n) 优化为 O(1)
+  - 1000 实体静态场景: 81.79μs → 0.07μs (快 1168 倍)
+  - 10000 实体静态场景: 939.43μs → 0.56μs (快 1677 倍)
+  - 服务端模拟 (100房间 x 100实体): 2.7ms → 1.4ms 每 tick
+
+---
+
+## v2.2.20 (2025-12-04)
+
+### Bug Fixes
+
+- **系统 onAdded 回调修复**: 修复系统 `onAdded` 回调受注册顺序影响的问题 (#270)
+  - 系统初始化时会对已存在的匹配实体触发 `onAdded` 回调
+  - 新增 `matchesEntity(entity)` 方法，用于检查实体是否匹配系统的查询条件
+  - Scene 新增 `notifySystemsEntityAdded/Removed` 方法，确保所有系统都能收到实体变更通知
+
+---
+
+## v2.2.19 (2025-12-03)
+
+### Features
+
+- **系统稳定排序**: 添加系统稳定排序支持 (#257)
+  - 新增 `addOrder` 属性，用于 `updateOrder` 相同时的稳定排序
+  - 确保相同优先级的系统按添加顺序执行
+
+- **模块配置**: 添加 `module.json` 配置文件 (#256)
+  - 定义模块 ID、名称、版本等元信息
+  - 支持模块依赖声明和导出配置
+
+---
+
+## v2.2.18 (2025-11-30)
+
+### Features
+
+- **高级性能分析器**: 实现全新的性能分析 SDK (#248)
+  - `ProfilerSDK`: 统一的性能分析接口
+    - 手动采样标记 (`beginSample`/`endSample`)
+    - 自动作用域测量 (`measure`/`measureAsync`)
+    - 调用层级追踪和调用图生成
+    - 计数器和仪表支持
+  - `AdvancedProfilerCollector`: 高级性能数据收集器
+    - 帧时间统计和历史记录
+    - 内存快照和 GC 检测
+    - 长任务检测 (Long Task API)
+    - 性能报告生成
+  - `DebugManager`: 调试管理器
+    - 统一的调试工具入口
+    - 性能分析器集成
+
+- **属性装饰器增强**: 扩展 `@serialize` 装饰器功能 (#247)
+  - 支持更多序列化选项配置
+
+### Improvements
+
+- **EntitySystem 测试覆盖**: 添加完整的系统测试用例 (#240)
+  - 覆盖实体查询、缓存、生命周期等场景
+
+- **Matcher 增强**: 优化匹配器功能 (#240)
+  - 改进匹配逻辑和性能
+
+---
+
+## v2.2.17 (2025-11-28)
+
+### Features
+
+- **ComponentRegistry 增强**: 添加组件注册表新功能 (#244)
+  - 支持通过名称注册和查询组件类型
+  - 添加组件掩码缓存优化性能
+
+- **序列化装饰器改进**: 增强 `@serialize` 装饰器 (#244)
+  - 支持更灵活的序列化配置
+  - 改进嵌套对象序列化
+
+- **EntitySystem 生命周期**: 新增系统生命周期方法 (#244)
+  - `onSceneStart()`: 场景开始时调用
+  - `onSceneStop()`: 场景停止时调用
+
+---
+
+## v2.2.16 (2025-11-27)
+
+### Features
+
+- **组件生命周期**: 添加组件生命周期回调支持 (#237)
+  - `onDeserialized()`: 组件从场景文件加载或快照恢复后调用，用于恢复运行时数据
+
+- **ServiceContainer 增强**: 改进服务容器功能 (#237)
+  - 支持 `Symbol.for()` 模式的服务标识
+  - 新增 `@InjectProperty` 属性注入装饰器
+  - 改进服务解析和生命周期管理
+
+- **SceneSerializer 增强**: 场景序列化器新功能 (#237)
+  - 支持更多组件类型的序列化
+  - 改进反序列化错误处理
+
+- **属性装饰器扩展**: 扩展 `@serialize` 装饰器 (#238)
+  - 支持 `@range`、`@slider` 等编辑器提示
+  - 支持 `@dropdown`、`@color` 等 UI 类型
+  - 支持 `@asset` 资源引用类型
+
+### Improvements
+
+- **Matcher 测试**: 添加 Matcher 匹配器测试用例 (#240)
+- **EntitySystem 测试**: 添加实体系统完整测试覆盖 (#240)
+
+---
+
+## 版本说明
+
+- **主版本号**: 重大不兼容更新
+- **次版本号**: 新功能添加（向后兼容）
+- **修订版本号**: Bug 修复和小改进
+
+## 相关链接
+
+- [GitHub Releases](https://github.com/esengine/esengine/releases)
+- [NPM Package](https://www.npmjs.com/package/@esengine/ecs-framework)
+- [文档首页](./index.md)

docs/en/changelog.md

@@ -0,0 +1,291 @@
+# Changelog
+
+This document records the version update history of the `@esengine/ecs-framework` core library.
+
+---
+
+## v2.4.2 (2025-12-25)
+
+### Features
+
+- **IncrementalSerializer Entity Filter**: Incremental serialization supports `entityFilter` option (#335)
+  - Filter entities by condition when creating snapshots
+  - Support custom filter logic by tag, component type, etc.
+  - Suitable for scenarios that only sync partial entities (e.g., only sync players)
+
+```typescript
+// Only snapshot player entities
+const snapshot = IncrementalSerializer.createSnapshot(scene, {
+    entityFilter: (entity) => entity.tag === PLAYER_TAG
+});
+
+// Only snapshot entities with specific component
+const snapshot = IncrementalSerializer.createSnapshot(scene, {
+    entityFilter: (entity) => entity.hasComponent(PlayerMarker)
+});
+```
+
+### Refactor
+
+- Optimize `PlatformWorkerPool` code style, extract as standalone module (#335)
+- Optimize `WorkerEntitySystem` implementation, improve code structure (#334)
+- Code standardization and dependency cleanup (#317)
+- Code structure optimization, add `GlobalTypes.ts` for unified type definitions (#316)
+
+---
+
+## v2.4.1 (2025-12-23)
+
+### Bug Fixes
+
+- Fix `IntervalSystem` time accumulation bug, interval timing is now more accurate
+- Fix Cocos Creator compatibility issue, more complete type exports
+
+### Documentation
+
+- Add `Core.paused` property documentation
+
+---
+
+## v2.4.0 (2025-12-15)
+
+### Features
+
+- **EntityHandle**: Lightweight entity reference abstraction (#304)
+  - 28-bit index + 20-bit generation design for efficient reuse of destroyed entity slots
+  - `EntityHandleManager` manages handle lifecycle and validity verification
+  - Support handle-to-entity conversion with dangling reference detection
+
+- **SystemScheduler**: Declarative system scheduling (#304)
+  - New `@Stage(name)` decorator to specify system execution stage
+  - New `@Before(SystemClass)` / `@After(SystemClass)` decorators to declare dependencies
+  - New `@InSet(setName)` decorator to group systems logically
+  - Automatic execution order resolution via topological sort with cycle detection
+
+- **EpochManager**: Frame-level change detection mechanism (#304)
+  - Track component add/modify timestamps (epochs)
+  - Support querying "components changed since last check"
+  - Suitable for dirty checking, incremental updates, and other optimization scenarios
+
+- **CompiledQuery**: Pre-compiled type-safe queries (#304)
+  - Compile-time generated optimized query logic, reducing runtime overhead
+  - Full TypeScript type inference support
+  - Support `With`, `Without`, `Changed` and other query condition combinations
+
+- **PluginServiceRegistry**: Type-safe plugin service registry (#300)
+  - Accessible via `Core.pluginServices`
+  - Support `ServiceToken<T>` pattern for service retrieval
+
+- **Component Auto-Registration**: `@ECSComponent` decorator enhancement (#302)
+  - Decorator now automatically registers to `ComponentRegistry`
+  - Resolved `Decorators ↔ ComponentRegistry` circular dependency
+  - New `ComponentTypeUtils.ts` as low-level dependency-free module
+
+### API Changes
+
+- `EntitySystem` adds `getBefore()` / `getAfter()` / `getSets()` getter methods
+- `Entity` adds `markDirty()` helper method for manual change detection triggering
+- `IScene` adds `epochManager` property
+- `CommandBuffer.pendingCount` corrected to return actual operation count (not entity count)
+
+### Documentation
+
+- Updated system scheduling documentation with declarative dependency configuration
+- Updated entity query documentation with compiled query usage
+
+---
+
+## v2.3.2 (2025-12-08)
+
+### Features
+
+- **WeChat Mini Game Worker Support**: Add complete Worker support for WeChat Mini Game platform (#297)
+  - New `workerScriptPath` config option for pre-compiled Worker script path
+  - Fix WeChat Mini Game Worker message format difference (`res` is data directly, no `.data` wrapper)
+  - Applicable to WeChat Mini Game and other platforms that don't support dynamic scripts
+
+### New Package
+
+- **@esengine/worker-generator** `v1.0.2`: CLI tool to auto-generate Worker files from `WorkerEntitySystem` subclasses
+  - Automatically scan and extract `workerProcess` method body
+  - Support `--wechat` mode, use TypeScript compiler to convert to ES5 syntax
+  - Read `workerScriptPath` config from code, generate to specified path
+  - Generate `worker-mapping.json` mapping file
+
+### Documentation
+
+- Updated Worker system documentation with WeChat Mini Game support section
+- Added English Worker system documentation (`docs/en/guide/worker-system.md`)
+
+---
+
+## v2.3.1 (2025-12-07)
+
+### Bug Fixes
+
+- **Type export fix**: Fix type export issues in v2.3.0
+  - Resolve `ServiceToken` cross-package type compatibility issues
+  - Fix type references in `editor-app` and `behavior-tree-editor`
+
+---
+
+## v2.3.0 (2025-12-06) ⚠️ DEPRECATED
+
+> **Warning**: This version has type export issues. Please upgrade to v2.3.1 or later.
+
+### Features
+
+- **Persistent Entity**: Add entity cross-scene migration support (#285)
+  - New `EEntityLifecyclePolicy` enum (`SceneLocal`/`Persistent`)
+  - Entity adds `setPersistent()`, `setSceneLocal()`, `isPersistent` API
+  - Scene adds `findPersistentEntities()`, `extractPersistentEntities()`, `receiveMigratedEntities()`
+  - `SceneManager.setScene()` automatically handles persistent entity migration
+  - Use cases: global managers, player characters, cross-scene state persistence
+
+- **CommandBuffer Deferred Command System**: Execute entity operations uniformly at end of frame (#281)
+  - Support deferred add/remove components, destroy entities, set entity active state
+  - Each system has its own `commands` property
+  - Avoid modifying entity list during iteration, preventing iteration issues
+  - Scene automatically flushes all command buffers after `lateUpdate`
+
+### Performance
+
+- **ReactiveQuery Snapshot Optimization**: Optimize entity query iteration performance (#281)
+  - Add snapshot mechanism to avoid copying arrays every frame
+  - Only create new snapshots when entity list changes
+  - Multiple systems share the same snapshot in static scenes
+
+---
+
+## v2.2.21 (2025-12-05)
+
+### Bug Fixes
+
+- **Iteration safety fix**: Fix issue where component changes during `process`/`lateProcess` iteration caused entities to be skipped (#272)
+  - Adding/removing components during system processing no longer causes entities to be unexpectedly skipped
+
+### Performance
+
+- **HierarchySystem optimization**: Optimize hierarchy system to avoid iterating all entities every frame (#279)
+  - Use dirty entity set instead of iterating all entities
+  - Static scene `process()` optimized from O(n) to O(1)
+  - 1000 entities static scene: 81.79μs → 0.07μs (1168x faster)
+  - 10000 entities static scene: 939.43μs → 0.56μs (1677x faster)
+  - Server simulation (100 rooms x 100 entities): 2.7ms → 1.4ms per tick
+
+---
+
+## v2.2.20 (2025-12-04)
+
+### Bug Fixes
+
+- **System onAdded callback fix**: Fix issue where system `onAdded` callback was affected by registration order (#270)
+  - System initialization now triggers `onAdded` callback for existing matching entities
+  - Added `matchesEntity(entity)` method to check if an entity matches the system's query condition
+  - Scene added `notifySystemsEntityAdded/Removed` methods to ensure all systems receive entity change notifications
+
+---
+
+## v2.2.19 (2025-12-03)
+
+### Features
+
+- **System stable sorting**: Add stable sorting support for systems (#257)
+  - Added `addOrder` property for stable sorting when `updateOrder` is the same
+  - Ensures systems with same priority execute in add order
+
+- **Module configuration**: Add `module.json` configuration file (#256)
+  - Define module ID, name, version and other metadata
+  - Support module dependency declaration and export configuration
+
+---
+
+## v2.2.18 (2025-11-30)
+
+### Features
+
+- **Advanced Performance Profiler**: Implement new performance analysis SDK (#248)
+  - `ProfilerSDK`: Unified performance analysis interface
+    - Manual sampling markers (`beginSample`/`endSample`)
+    - Automatic scope measurement (`measure`/`measureAsync`)
+    - Call hierarchy tracking and call graph generation
+    - Counter and gauge support
+  - `AdvancedProfilerCollector`: Advanced performance data collector
+    - Frame time statistics and history
+    - Memory snapshots and GC detection
+    - Long task detection (Long Task API)
+    - Performance report generation
+  - `DebugManager`: Debug manager
+    - Unified debug tool entry point
+    - Profiler integration
+
+- **Property decorator enhancement**: Extend `@serialize` decorator functionality (#247)
+  - Support more serialization option configurations
+
+### Improvements
+
+- **EntitySystem test coverage**: Add complete system test cases (#240)
+  - Cover entity query, cache, lifecycle scenarios
+
+- **Matcher enhancement**: Optimize matcher functionality (#240)
+  - Improved matching logic and performance
+
+---
+
+## v2.2.17 (2025-11-28)
+
+### Features
+
+- **ComponentRegistry enhancement**: Add new component registry features (#244)
+  - Support registering and querying component types by name
+  - Add component mask caching for performance optimization
+
+- **Serialization decorator improvements**: Enhance `@serialize` decorator (#244)
+  - Support more flexible serialization configuration
+  - Improved nested object serialization
+
+- **EntitySystem lifecycle**: Add new system lifecycle methods (#244)
+  - `onSceneStart()`: Called when scene starts
+  - `onSceneStop()`: Called when scene stops
+
+---
+
+## v2.2.16 (2025-11-27)
+
+### Features
+
+- **Component lifecycle**: Add component lifecycle callback support (#237)
+  - `onDeserialized()`: Called after component is loaded from scene file or snapshot restore, used to restore runtime data
+
+- **ServiceContainer enhancement**: Improve service container functionality (#237)
+  - Support `Symbol.for()` pattern for service identifiers
+  - Added `@InjectProperty` property injection decorator
+  - Improved service resolution and lifecycle management
+
+- **SceneSerializer enhancement**: New scene serializer features (#237)
+  - Support serialization of more component types
+  - Improved deserialization error handling
+
+- **Property decorator extension**: Extend `@serialize` decorator (#238)
+  - Support `@range`, `@slider` and other editor hints
+  - Support `@dropdown`, `@color` and other UI types
+  - Support `@asset` resource reference type
+
+### Improvements
+
+- **Matcher tests**: Add Matcher test cases (#240)
+- **EntitySystem tests**: Add complete entity system test coverage (#240)
+
+---
+
+## Version Notes
+
+- **Major version**: Breaking changes
+- **Minor version**: New features (backward compatible)
+- **Patch version**: Bug fixes and improvements
+
+## Related Links
+
+- [GitHub Releases](https://github.com/esengine/esengine/releases)
+- [NPM Package](https://www.npmjs.com/package/@esengine/ecs-framework)
+- [Documentation Home](./index.md)

docs/en/guide/entity.md

@@ -0,0 +1,444 @@
+# Entity
+
+In ECS architecture, an Entity is the basic object in the game world. An entity itself does not contain game logic or data - it's just a container that combines different components to achieve various functionalities.
+
+## Basic Concepts
+
+An entity is a lightweight object mainly used for:
+- Serving as a container for components
+- Providing a unique identifier (ID)
+- Managing component lifecycle
+
+::: tip About Parent-Child Hierarchy
+Parent-child hierarchy relationships between entities are managed through `HierarchyComponent` and `HierarchySystem`, not built-in Entity properties. This design follows ECS composition principles - only entities that need hierarchy relationships add this component.
+
+See [Hierarchy System](./hierarchy.md) documentation.
+:::
+
+## Creating Entities
+
+**Important: Entities must be created through Scene, manual creation is not supported!**
+
+Entities must be created through the scene's `createEntity()` method to ensure:
+- Entity is properly added to the scene's entity management system
+- Entity is added to the query system for system use
+- Entity gets the correct scene reference
+- Related lifecycle events are triggered
+
+```typescript
+// Correct way: create entity through scene
+const player = scene.createEntity("Player");
+
+// Wrong way: manually create entity
+// const entity = new Entity("MyEntity", 1); // System cannot manage such entities
+```
+
+## Adding Components
+
+Entities gain functionality by adding components:
+
+```typescript
+import { Component, ECSComponent } from '@esengine/ecs-framework';
+
+// Define 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;
+  }
+}
+
+// Define health component
+@ECSComponent('Health')
+class Health extends Component {
+  current: number = 100;
+  max: number = 100;
+
+  constructor(max: number = 100) {
+    super();
+    this.max = max;
+    this.current = max;
+  }
+}
+
+// Add components to entity
+const player = scene.createEntity("Player");
+player.addComponent(new Position(100, 200));
+player.addComponent(new Health(150));
+```
+
+## Getting Components
+
+```typescript
+// Get component (pass component class, not instance)
+const position = player.getComponent(Position);  // Returns Position | null
+const health = player.getComponent(Health);      // Returns Health | null
+
+// Check if component exists
+if (position) {
+  console.log(`Player position: x=${position.x}, y=${position.y}`);
+}
+
+// Check if entity has a component
+if (player.hasComponent(Position)) {
+  console.log("Player has position component");
+}
+
+// Get all component instances (read-only property)
+const allComponents = player.components;  // readonly Component[]
+
+// Get all components of specified type (supports multiple components of same type)
+const allHealthComponents = player.getComponents(Health);  // Health[]
+
+// Get or create component (creates automatically if not exists)
+const position = player.getOrCreateComponent(Position, 0, 0);  // Pass constructor arguments
+const health = player.getOrCreateComponent(Health, 100);       // Returns existing if present, creates new if not
+```
+
+## Removing Components
+
+```typescript
+// Method 1: Remove by component type
+const removedHealth = player.removeComponentByType(Health);
+if (removedHealth) {
+  console.log("Health component removed");
+}
+
+// Method 2: Remove by component instance
+const healthComponent = player.getComponent(Health);
+if (healthComponent) {
+  player.removeComponent(healthComponent);
+}
+
+// Batch remove multiple component types
+const removedComponents = player.removeComponentsByTypes([Position, Health]);
+
+// Check if component was removed
+if (!player.hasComponent(Health)) {
+  console.log("Health component has been removed");
+}
+```
+
+## Finding Entities
+
+Scene provides multiple ways to find entities:
+
+### Find by Name
+
+```typescript
+// Find single entity
+const player = scene.findEntity("Player");
+// Or use alias method
+const player2 = scene.getEntityByName("Player");
+
+if (player) {
+  console.log("Found player entity");
+}
+```
+
+### Find by ID
+
+```typescript
+// Find by entity ID
+const entity = scene.findEntityById(123);
+```
+
+### Find by Tag
+
+Entities support a tag system for quick categorization and lookup:
+
+```typescript
+// Set tags
+player.tag = 1; // Player tag
+enemy.tag = 2;  // Enemy tag
+
+// Find all entities by tag
+const players = scene.findEntitiesByTag(1);
+const enemies = scene.findEntitiesByTag(2);
+// Or use alias method
+const allPlayers = scene.getEntitiesByTag(1);
+```
+
+## Entity Lifecycle
+
+```typescript
+// Destroy entity
+player.destroy();
+
+// Check if entity is destroyed
+if (player.isDestroyed) {
+  console.log("Entity has been destroyed");
+}
+```
+
+## Entity Events
+
+Component changes on entities trigger events:
+
+```typescript
+// Listen for component added event
+scene.eventSystem.on('component:added', (data) => {
+  console.log('Component added:', data);
+});
+
+// Listen for entity created event
+scene.eventSystem.on('entity:created', (data) => {
+  console.log('Entity created:', data.entityName);
+});
+```
+
+## Performance Optimization
+
+### Batch Entity Creation
+
+The framework provides high-performance batch creation methods:
+
+```typescript
+// Batch create 100 bullet entities (high-performance version)
+const bullets = scene.createEntities(100, "Bullet");
+
+// Add components to each 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()` method will:
+- Batch allocate entity IDs
+- Batch add to entity list
+- Optimize query system updates
+- Reduce system cache clearing times
+
+## Best Practices
+
+### 1. Appropriate Component Granularity
+
+```typescript
+// Good practice: single-purpose components
+@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: overly complex components
+@ECSComponent('Player')
+class Player extends Component {
+  // Avoid including too many unrelated properties in one component
+  x: number;
+  y: number;
+  health: number;
+  inventory: Item[];
+  skills: Skill[];
+}
+```
+
+### 2. Use Decorators
+
+Always use `@ECSComponent` decorator:
+
+```typescript
+@ECSComponent('Transform')
+class Transform extends Component {
+  // Component implementation
+}
+```
+
+### 3. Proper Naming
+
+```typescript
+// Clear entity naming
+const mainCharacter = scene.createEntity("MainCharacter");
+const enemy1 = scene.createEntity("Goblin_001");
+const collectible = scene.createEntity("HealthPotion");
+```
+
+### 4. Timely Cleanup
+
+```typescript
+// Destroy entities that are no longer needed
+if (enemy.getComponent(Health).current <= 0) {
+  enemy.destroy();
+}
+```
+
+## Debugging Entities
+
+The framework provides debugging features to help development:
+
+```typescript
+// Get entity debug info
+const debugInfo = entity.getDebugInfo();
+console.log('Entity info:', debugInfo);
+
+// List all components of entity
+entity.components.forEach(component => {
+  console.log('Component:', component.constructor.name);
+});
+```
+
+Entities are one of the core concepts in ECS architecture. Understanding how to use entities correctly will help you build efficient, maintainable game code.
+
+## Entity Handle (EntityHandle)
+
+Entity handles provide a safe way to reference entities, solving the "referencing destroyed entity" problem.
+
+### Problem Scenario
+
+Suppose your AI system needs to track a target enemy:
+
+```typescript
+// Wrong approach: directly store entity reference
+class AISystem extends EntitySystem {
+    private targetEnemy: Entity | null = null;
+
+    setTarget(enemy: Entity) {
+        this.targetEnemy = enemy;
+    }
+
+    process() {
+        if (this.targetEnemy) {
+            // Dangerous! 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 the wrong entity!
+        }
+    }
+}
+```
+
+### Correct Approach Using Handles
+
+Each entity is automatically assigned a handle when created, accessible via `entity.handle`:
+
+```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) {
+        // Save enemy's handle
+        this.targetHandle = enemy.handle;
+    }
+
+    process() {
+        if (!isValidHandle(this.targetHandle)) {
+            return; // No target
+        }
+
+        // Get entity through handle (automatically checks validity)
+        const enemy = this.scene.findEntityByHandle(this.targetHandle);
+
+        if (!enemy) {
+            // Enemy was destroyed, clear reference
+            this.targetHandle = NULL_HANDLE;
+            return;
+        }
+
+        // Safe operation
+        const health = enemy.getComponent(Health);
+    }
+}
+```
+
+### Complete Example: Skill Target Locking
+
+```typescript
+import {
+    EntitySystem, Entity, EntityHandle, NULL_HANDLE, isValidHandle
+} from '@esengine/ecs-framework';
+
+@ECSSystem('SkillTargeting')
+class SkillTargetingSystem extends EntitySystem {
+    // Store handles for multiple targets
+    private lockedTargets: Map<Entity, EntityHandle> = new Map();
+
+    // Lock target
+    lockTarget(caster: Entity, target: Entity) {
+        this.lockedTargets.set(caster, target.handle);
+    }
+
+    // Get locked target
+    getLockedTarget(caster: Entity): Entity | null {
+        const handle = this.lockedTargets.get(caster);
+
+        if (!handle || !isValidHandle(handle)) {
+            return null;
+        }
+
+        // findEntityByHandle checks if handle is valid
+        const target = this.scene.findEntityByHandle(handle);
+
+        if (!target) {
+            // Target died, clear lock
+            this.lockedTargets.delete(caster);
+        }
+
+        return target;
+    }
+
+    // Cast skill
+    castSkill(caster: Entity) {
+        const target = this.getLockedTarget(caster);
+
+        if (!target) {
+            console.log('Target lost, skill cancelled');
+            return;
+        }
+
+        // Safely deal damage to target
+        const health = target.getComponent(Health);
+        if (health) {
+            health.current -= 10;
+        }
+    }
+}
+```
+
+### Handle vs Entity Reference
+
+| Scenario | Recommended Approach |
+|----------|---------------------|
+| Temporary use within same frame | Use `Entity` reference directly |
+| Cross-frame storage (e.g., AI target, skill target) | Use `EntityHandle` |
+| Needs serialization | Use `EntityHandle` (numeric type) |
+| Network synchronization | Use `EntityHandle` (can be transmitted directly) |
+
+### API Quick Reference
+
+```typescript
+// Get entity's handle
+const handle = entity.handle;
+
+// Check if handle is non-null
+if (isValidHandle(handle)) { ... }
+
+// Get entity through handle (automatically checks validity)
+const entity = scene.findEntityByHandle(handle);
+
+// Check if entity corresponding to handle is alive
+const alive = scene.handleManager.isAlive(handle);
+
+// Null handle constant
+const emptyHandle = NULL_HANDLE;
+```
+
+## Next Steps
+
+- Learn about [Hierarchy System](./hierarchy.md) to establish parent-child relationships
+- Learn about [Component System](./component.md) to add functionality to entities
+- Learn about [Scene Management](./scene.md) to organize and manage entities

docs/en/guide/getting-started.md

@@ -0,0 +1,441 @@
+# 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/en/guide/index.md

@@ -0,0 +1,43 @@
+# Guide
+
+Welcome to the ECS Framework Guide. This guide covers the core concepts and usage of the framework.
+
+## Core Concepts
+
+### [Entity](/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/en/guide/persistent-entity.md

@@ -0,0 +1,360 @@
+# 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/en/guide/scene-manager.md

@@ -0,0 +1,436 @@
+# 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/en/guide/scene.md

@@ -0,0 +1,364 @@
+# Scene Management
+
+In the ECS architecture, a Scene is a container for the game world, responsible for managing the lifecycle of entities, systems, and components. Scenes provide a complete ECS runtime environment.
+
+## Basic Concepts
+
+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:
+
+1. **[SceneManager](./scene-manager)** - Suitable for 95% of game applications
+   - Single-player games, simple multiplayer games, mobile games
+   - Lightweight, simple and intuitive API
+   - Supports scene transitions
+
+2. **[WorldManager](./world-manager)** - Suitable for advanced multi-world isolation scenarios
+   - MMO game servers, game room systems
+   - Multi-World management, each World can contain multiple scenes
+   - Completely isolated independent environments
+
+This document focuses on the usage of the Scene class itself. For detailed information about scene managers, please refer to the corresponding documentation.
+
+## Creating a Scene
+
+### Inheriting the Scene Class
+
+**Recommended: Inherit the Scene class to create custom scenes**
+
+```typescript
+import { Scene, EntitySystem } from '@esengine/ecs-framework';
+
+class GameScene extends Scene {
+  protected initialize(): void {
+    // Set scene name
+    this.name = "GameScene";
+
+    // Add systems
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+    this.addSystem(new PhysicsSystem());
+
+    // Create initial entities
+    this.createInitialEntities();
+  }
+
+  private createInitialEntities(): void {
+    // Create player
+    const player = this.createEntity("Player");
+    player.addComponent(new Position(400, 300));
+    player.addComponent(new Health(100));
+    player.addComponent(new PlayerController());
+
+    // Create enemies
+    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("Game scene started");
+    // Logic when scene starts
+  }
+
+  public unload(): void {
+    console.log("Game scene unloaded");
+    // Cleanup logic when scene unloads
+  }
+}
+```
+
+### Using Scene Configuration
+
+```typescript
+import { ISceneConfig } from '@esengine/ecs-framework';
+
+const config: ISceneConfig = {
+  name: "MainGame",
+  enableEntityDirectUpdate: false
+};
+
+class ConfiguredScene extends Scene {
+  constructor() {
+    super(config);
+  }
+}
+```
+
+## Scene Lifecycle
+
+Scene provides complete lifecycle management:
+
+```typescript
+class ExampleScene extends Scene {
+  protected initialize(): void {
+    // Scene initialization: setup systems and initial entities
+    console.log("Scene initializing");
+  }
+
+  public onStart(): void {
+    // Scene starts running: game logic begins execution
+    console.log("Scene starting");
+  }
+
+  public unload(): void {
+    // Scene unloading: cleanup resources
+    console.log("Scene unloading");
+  }
+}
+
+// Using scenes (lifecycle automatically managed by framework)
+const scene = new ExampleScene();
+// Scene's initialize(), begin(), update(), end() are automatically called by the framework
+```
+
+**Lifecycle Methods**:
+
+1. `initialize()` - Scene initialization, setup systems and initial entities
+2. `begin()` / `onStart()` - Scene starts running
+3. `update()` - Per-frame update (called by scene manager)
+4. `end()` / `unload()` - Scene unloading, cleanup resources
+
+## Entity Management
+
+### Creating Entities
+
+```typescript
+class EntityScene extends Scene {
+  createGameEntities(): void {
+    // Create single entity
+    const player = this.createEntity("Player");
+
+    // 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
+
+```typescript
+class SearchScene extends Scene {
+  findEntities(): void {
+    // Find by name
+    const player = this.findEntity("Player");
+    const player2 = this.getEntityByName("Player"); // Alias method
+
+    // Find by ID
+    const entity = this.findEntityById(123);
+
+    // Find by tag
+    const enemies = this.findEntitiesByTag(2);
+    const enemies2 = this.getEntitiesByTag(2); // Alias method
+
+    if (player) {
+      console.log(`Found player: ${player.name}`);
+    }
+
+    console.log(`Found ${enemies.length} enemies`);
+  }
+}
+```
+
+### Destroying Entities
+
+```typescript
+class DestroyScene extends Scene {
+  cleanupEntities(): void {
+    // Destroy all entities
+    this.destroyAllEntities();
+
+    // Single entity destruction through the entity itself
+    const enemy = this.findEntity("Enemy_1");
+    if (enemy) {
+      enemy.destroy(); // Entity is automatically removed from the scene
+    }
+  }
+}
+```
+
+## System Management
+
+### Adding and Removing Systems
+
+```typescript
+class SystemScene extends Scene {
+  protected initialize(): void {
+    // Add systems
+    const movementSystem = new MovementSystem();
+    this.addSystem(movementSystem);
+
+    // Set system update order
+    movementSystem.updateOrder = 1;
+
+    // Add more systems
+    this.addSystem(new PhysicsSystem());
+    this.addSystem(new RenderSystem());
+  }
+
+  public removeUnnecessarySystems(): void {
+    // Get system
+    const physicsSystem = this.getEntityProcessor(PhysicsSystem);
+
+    // Remove system
+    if (physicsSystem) {
+      this.removeSystem(physicsSystem);
+    }
+  }
+}
+```
+
+## Event System
+
+Scene has a built-in type-safe event system:
+
+```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');
+    // Handle player death
+  }
+
+  private onEnemySpawned(data: any): void {
+    console.log('Enemy spawned event');
+    // Handle enemy spawn
+  }
+
+  private onLevelComplete(data: any): void {
+    console.log('Level complete event');
+    // Handle level completion
+  }
+
+  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"
+    });
+  }
+}
+```
+
+## Best Practices
+
+### 1. 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
+}
+```
+
+### 2. Proper System Organization
+
+```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());
+  }
+}
+```
+
+### 3. 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 {
+    // Load resources needed by the scene
+    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 {
+    // Load texture
+    return null;
+  }
+
+  private loadSound(path: string): any {
+    // Load sound
+    return null;
+  }
+}
+```
+
+## Next Steps
+
+- Learn about [SceneManager](./scene-manager) - Simple scene management for most games
+- Learn about [WorldManager](./world-manager) - For scenarios requiring multi-world isolation
+- Learn about [Persistent Entity](./persistent-entity) - Keep entities across scene transitions (v2.3.0+)
+
+Scene is the core container of the ECS framework. Proper scene management makes your game architecture clearer, more modular, and easier to maintain.

docs/en/guide/time-and-timers.md

@@ -0,0 +1,402 @@
+# Time and Timer System
+
+The ECS framework provides a complete time management and timer system, including time scaling, frame time calculation, and flexible timer scheduling.
+
+## Time Class
+
+The Time class is the core of the framework's time management, providing all game time-related functionality.
+
+### Basic Time Properties
+
+```typescript
+import { Time } from '@esengine/ecs-framework';
+
+class GameSystem extends EntitySystem {
+  protected process(entities: readonly Entity[]): void {
+    // Get frame time (seconds)
+    const deltaTime = Time.deltaTime;
+
+    // Get unscaled frame time
+    const unscaledDelta = Time.unscaledDeltaTime;
+
+    // Get total game time
+    const totalTime = Time.totalTime;
+
+    // Get current frame count
+    const frameCount = Time.frameCount;
+
+    console.log(`Frame ${frameCount}, delta: ${deltaTime}s, total: ${totalTime}s`);
+  }
+}
+```
+
+### Game Pause
+
+The framework provides two pause methods for different scenarios:
+
+#### Core.paused (Recommended)
+
+`Core.paused` is a **true pause** - when set, the entire game loop stops:
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+
+class PauseMenuSystem extends EntitySystem {
+  public pauseGame(): void {
+    // True pause - all systems stop executing
+    Core.paused = true;
+    console.log('Game paused');
+  }
+
+  public resumeGame(): void {
+    // Resume game
+    Core.paused = false;
+    console.log('Game resumed');
+  }
+
+  public togglePause(): void {
+    Core.paused = !Core.paused;
+    console.log(Core.paused ? 'Game paused' : 'Game resumed');
+  }
+}
+```
+
+#### Time.timeScale = 0
+
+`Time.timeScale = 0` only makes `deltaTime` become 0, **systems still execute**:
+
+```typescript
+class SlowMotionSystem extends EntitySystem {
+  public freezeTime(): void {
+    // Time freeze - systems still execute, just deltaTime = 0
+    Time.timeScale = 0;
+  }
+}
+```
+
+#### Comparison
+
+| Feature | `Core.paused = true` | `Time.timeScale = 0` |
+|---------|---------------------|---------------------|
+| System Execution | Completely stopped | Still running |
+| CPU Overhead | Zero | Normal overhead |
+| Time Updates | Stopped | Continues (deltaTime=0) |
+| Timers | Stopped | Continues (but time doesn't advance) |
+| Use Cases | Pause menu, game pause | Slow motion, bullet time effects |
+
+**Recommendations**:
+- Pause menu, true game pause → Use `Core.paused = true`
+- Slow motion, bullet time effects → Use `Time.timeScale`
+
+### Time Scaling
+
+The Time class supports time scaling for slow motion, fast forward, and other effects:
+
+```typescript
+class TimeControlSystem extends EntitySystem {
+  public enableSlowMotion(): void {
+    // Set to slow motion (50% speed)
+    Time.timeScale = 0.5;
+    console.log('Slow motion enabled');
+  }
+
+  public enableFastForward(): void {
+    // Set to fast forward (200% speed)
+    Time.timeScale = 2.0;
+    console.log('Fast forward enabled');
+  }
+
+  public enableBulletTime(): void {
+    // Bullet time effect (10% speed)
+    Time.timeScale = 0.1;
+    console.log('Bullet time enabled');
+  }
+
+  public resumeNormalSpeed(): void {
+    // Resume normal speed
+    Time.timeScale = 1.0;
+    console.log('Normal speed resumed');
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    // deltaTime is affected by timeScale
+    const scaledDelta = Time.deltaTime; // Affected by time scale
+    const realDelta = Time.unscaledDeltaTime; // Not affected by time scale
+
+    for (const entity of entities) {
+      const movement = entity.getComponent(Movement);
+      if (movement) {
+        // Use scaled time for game logic updates
+        movement.update(scaledDelta);
+      }
+
+      const ui = entity.getComponent(UIComponent);
+      if (ui) {
+        // UI animations use real time, not affected by game time scale
+        ui.update(realDelta);
+      }
+    }
+  }
+}
+```
+
+### Time Check Utilities
+
+```typescript
+class CooldownSystem extends EntitySystem {
+  private lastAttackTime = 0;
+  private lastSpawnTime = 0;
+
+  constructor() {
+    super(Matcher.all(Weapon));
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    // Check attack cooldown
+    if (Time.checkEvery(1.5, this.lastAttackTime)) {
+      this.performAttack();
+      this.lastAttackTime = Time.totalTime;
+    }
+
+    // Check spawn interval
+    if (Time.checkEvery(3.0, this.lastSpawnTime)) {
+      this.spawnEnemy();
+      this.lastSpawnTime = Time.totalTime;
+    }
+  }
+
+  private performAttack(): void {
+    console.log('Performing attack!');
+  }
+
+  private spawnEnemy(): void {
+    console.log('Spawning enemy!');
+  }
+}
+```
+
+## Core.schedule Timer System
+
+Core provides powerful timer scheduling functionality for creating one-time or repeating timers.
+
+### Basic Timer Usage
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+
+class GameScene extends Scene {
+  protected initialize(): void {
+    // Create one-time timers
+    this.createOneTimeTimers();
+
+    // Create repeating timers
+    this.createRepeatingTimers();
+
+    // Create timers with context
+    this.createContextTimers();
+  }
+
+  private createOneTimeTimers(): void {
+    // Execute once after 2 seconds
+    Core.schedule(2.0, false, null, (timer) => {
+      console.log('Executed after 2 second delay');
+    });
+
+    // Show tip after 5 seconds
+    Core.schedule(5.0, false, this, (timer) => {
+      const scene = timer.getContext<GameScene>();
+      scene.showTip('Game tip: 5 seconds have passed!');
+    });
+  }
+
+  private createRepeatingTimers(): void {
+    // Execute every second
+    const heartbeatTimer = Core.schedule(1.0, true, null, (timer) => {
+      console.log(`Game heartbeat - Total time: ${Time.totalTime.toFixed(1)}s`);
+    });
+
+    // Save timer reference for later control
+    this.saveTimerReference(heartbeatTimer);
+  }
+
+  private createContextTimers(): void {
+    const gameData = { score: 0, level: 1 };
+
+    // Add score every 2 seconds
+    Core.schedule(2.0, true, gameData, (timer) => {
+      const data = timer.getContext<typeof gameData>();
+      data.score += 10;
+      console.log(`Score increased! Current score: ${data.score}`);
+    });
+  }
+
+  private saveTimerReference(timer: any): void {
+    // Can stop timer later
+    setTimeout(() => {
+      timer.stop();
+      console.log('Timer stopped');
+    }, 10000); // Stop after 10 seconds
+  }
+
+  private showTip(message: string): void {
+    console.log('Tip:', message);
+  }
+}
+```
+
+### Timer Control
+
+```typescript
+class TimerControlExample {
+  private attackTimer: any;
+  private spawnerTimer: any;
+
+  public startCombat(): void {
+    // Start attack timer
+    this.attackTimer = Core.schedule(0.5, true, this, (timer) => {
+      const self = timer.getContext<TimerControlExample>();
+      self.performAttack();
+    });
+
+    // Start enemy spawn timer
+    this.spawnerTimer = Core.schedule(3.0, true, null, (timer) => {
+      this.spawnEnemy();
+    });
+  }
+
+  public stopCombat(): void {
+    // Stop all combat-related timers
+    if (this.attackTimer) {
+      this.attackTimer.stop();
+      console.log('Attack timer stopped');
+    }
+
+    if (this.spawnerTimer) {
+      this.spawnerTimer.stop();
+      console.log('Spawn timer stopped');
+    }
+  }
+
+  public resetAttackTimer(): void {
+    // Reset attack timer
+    if (this.attackTimer) {
+      this.attackTimer.reset();
+      console.log('Attack timer reset');
+    }
+  }
+
+  private performAttack(): void {
+    console.log('Performing attack');
+  }
+
+  private spawnEnemy(): void {
+    console.log('Spawning enemy');
+  }
+}
+```
+
+## Best Practices
+
+### 1. Use Appropriate Time Types
+
+```typescript
+class MovementSystem extends EntitySystem {
+  protected process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const movement = entity.getComponent(Movement);
+
+      // Use scaled time for game logic
+      movement.position.x += movement.velocity.x * Time.deltaTime;
+
+      // Use real time for UI animations (not affected by game pause)
+      const ui = entity.getComponent(UIAnimation);
+      if (ui) {
+        ui.update(Time.unscaledDeltaTime);
+      }
+    }
+  }
+}
+```
+
+### 2. Timer Management
+
+```typescript
+class TimerManager {
+  private timers: any[] = [];
+
+  public createManagedTimer(duration: number, repeats: boolean, callback: () => void): any {
+    const timer = Core.schedule(duration, repeats, null, callback);
+    this.timers.push(timer);
+    return timer;
+  }
+
+  public stopAllTimers(): void {
+    for (const timer of this.timers) {
+      timer.stop();
+    }
+    this.timers = [];
+  }
+
+  public cleanupCompletedTimers(): void {
+    this.timers = this.timers.filter(timer => !timer.isDone);
+  }
+}
+```
+
+### 3. Avoid Too Many Timers
+
+```typescript
+// Avoid: Creating a timer for each entity
+class BadExample extends EntitySystem {
+  protected onAdded(entity: Entity): void {
+    Core.schedule(1.0, true, entity, (timer) => {
+      // One timer per entity - poor performance
+    });
+  }
+}
+
+// Recommended: Manage time uniformly in the system
+class GoodExample extends EntitySystem {
+  private lastUpdateTime = 0;
+
+  protected process(entities: readonly Entity[]): void {
+    // Execute logic once per second
+    if (Time.checkEvery(1.0, this.lastUpdateTime)) {
+      this.processAllEntities(entities);
+      this.lastUpdateTime = Time.totalTime;
+    }
+  }
+
+  private processAllEntities(entities: readonly Entity[]): void {
+    // Batch process all entities
+  }
+}
+```
+
+### 4. Timer Context Usage
+
+```typescript
+interface TimerContext {
+  entityId: number;
+  duration: number;
+  onComplete: () => void;
+}
+
+class ContextualTimerExample {
+  public createEntityTimer(entityId: number, duration: number, onComplete: () => void): void {
+    const context: TimerContext = {
+      entityId,
+      duration,
+      onComplete
+    };
+
+    Core.schedule(duration, false, context, (timer) => {
+      const ctx = timer.getContext<TimerContext>();
+      console.log(`Timer for entity ${ctx.entityId} completed`);
+      ctx.onComplete();
+    });
+  }
+}
+```
+
+The time and timer system is an essential tool in game development. Using these features correctly will make your game logic more precise and controllable.

docs/en/guide/worker-system.md

@@ -0,0 +1,570 @@
+# Worker System
+
+The Worker System (WorkerEntitySystem) is a multi-threaded processing system based on Web Workers in the ECS framework. It's designed for compute-intensive tasks, fully utilizing multi-core CPU performance for true parallel computing.
+
+## Core Features
+
+- **True Parallel Computing**: Execute compute-intensive tasks in background threads using Web Workers
+- **Automatic Load Balancing**: Automatically distribute workload based on CPU core count
+- **SharedArrayBuffer Optimization**: Zero-copy data sharing for improved large-scale computation performance
+- **Graceful Degradation**: Automatic fallback to main thread processing when Workers are not supported
+- **Type Safety**: Full TypeScript support and type checking
+
+## Basic Usage
+
+### Simple Physics System Example
+
+```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,              // Enable Worker parallel processing
+      workerCount: 8,                  // Worker count, auto-limited to hardware capacity
+      entitiesPerWorker: 100,          // Entities per Worker
+      useSharedArrayBuffer: true,      // Enable SharedArrayBuffer optimization
+      entityDataSize: 7,               // Data size per entity
+      maxEntities: 10000,              // Maximum entity count
+      systemConfig: {                  // Configuration passed to Worker
+        gravity: 100,
+        friction: 0.95
+      }
+    });
+  }
+
+  // Data extraction: Convert Entity to serializable data
+  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 processing function: Pure function executed in Worker
+  protected workerProcess(
+    entities: PhysicsData[],
+    deltaTime: number,
+    config: any
+  ): PhysicsData[] {
+    return entities.map(entity => {
+      // Apply gravity
+      entity.vy += config.gravity * deltaTime;
+
+      // Update position
+      entity.x += entity.vx * deltaTime;
+      entity.y += entity.vy * deltaTime;
+
+      // Apply friction
+      entity.vx *= config.friction;
+      entity.vy *= config.friction;
+
+      return entity;
+    });
+  }
+
+  // Apply results: Apply Worker processing results back to 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 optimization support
+  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]
+    };
+  }
+}
+```
+
+## Configuration Options
+
+The Worker system supports rich configuration options:
+
+```typescript
+interface WorkerSystemConfig {
+  /** Enable Worker parallel processing */
+  enableWorker?: boolean;
+  /** Worker count, defaults to CPU core count, auto-limited to system maximum */
+  workerCount?: number;
+  /** Entities per Worker for load distribution control */
+  entitiesPerWorker?: number;
+  /** System configuration data passed to Worker */
+  systemConfig?: any;
+  /** Enable SharedArrayBuffer optimization */
+  useSharedArrayBuffer?: boolean;
+  /** Float32 count per entity in SharedArrayBuffer */
+  entityDataSize?: number;
+  /** Maximum entity count (for SharedArrayBuffer pre-allocation) */
+  maxEntities?: number;
+  /** Pre-compiled Worker script path (for platforms like WeChat Mini Game that don't support dynamic scripts) */
+  workerScriptPath?: string;
+}
+```
+
+### Configuration Recommendations
+
+```typescript
+constructor() {
+  super(matcher, {
+    // Decide based on task complexity
+    enableWorker: this.shouldUseWorker(),
+
+    // Worker count: System auto-limits to hardware capacity
+    workerCount: 8, // Request 8 Workers, actual count limited by CPU cores
+
+    // Entities per Worker (optional)
+    entitiesPerWorker: 200, // Precise load distribution control
+
+    // Enable SharedArrayBuffer for many simple calculations
+    useSharedArrayBuffer: this.entityCount > 1000,
+
+    // Set according to actual data structure
+    entityDataSize: 8, // Ensure it matches data structure
+
+    // Estimated maximum entity count
+    maxEntities: 10000,
+
+    // Global configuration passed to Worker
+    systemConfig: {
+      gravity: 9.8,
+      friction: 0.95,
+      worldBounds: { width: 1920, height: 1080 }
+    }
+  });
+}
+
+private shouldUseWorker(): boolean {
+  // Decide based on entity count and complexity
+  return this.expectedEntityCount > 100;
+}
+
+// Get system info
+getSystemInfo() {
+  const info = this.getWorkerInfo();
+  console.log(`Worker count: ${info.workerCount}/${info.maxSystemWorkerCount}`);
+  console.log(`Entities per Worker: ${info.entitiesPerWorker || 'auto'}`);
+  console.log(`Current mode: ${info.currentMode}`);
+}
+```
+
+## Processing Modes
+
+The Worker system supports two processing modes:
+
+### 1. Traditional Worker Mode
+
+Data is serialized and passed between main thread and Workers:
+
+```typescript
+// Suitable for: Complex computation logic, moderate entity count
+constructor() {
+  super(matcher, {
+    enableWorker: true,
+    useSharedArrayBuffer: false, // Use traditional mode
+    workerCount: 2
+  });
+}
+
+protected workerProcess(entities: EntityData[], deltaTime: number): EntityData[] {
+  // Complex algorithm logic
+  return entities.map(entity => {
+    // AI decisions, pathfinding, etc.
+    return this.complexAILogic(entity, deltaTime);
+  });
+}
+```
+
+### 2. SharedArrayBuffer Mode
+
+Zero-copy data sharing, suitable for many simple calculations:
+
+```typescript
+// Suitable for: Many entities with simple calculations
+constructor() {
+  super(matcher, {
+    enableWorker: true,
+    useSharedArrayBuffer: true, // Enable shared memory
+    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;
+
+      // Read data
+      let x = sharedFloatArray[offset];
+      let y = sharedFloatArray[offset + 1];
+      let vx = sharedFloatArray[offset + 2];
+      let vy = sharedFloatArray[offset + 3];
+
+      // Physics calculations
+      vy += config.gravity * deltaTime;
+      x += vx * deltaTime;
+      y += vy * deltaTime;
+
+      // Write back data
+      sharedFloatArray[offset] = x;
+      sharedFloatArray[offset + 1] = y;
+      sharedFloatArray[offset + 2] = vx;
+      sharedFloatArray[offset + 3] = vy;
+    }
+  };
+}
+```
+
+## Use Cases
+
+The Worker system is particularly suitable for:
+
+### 1. Physics Simulation
+- **Gravity systems**: Gravity calculations for many entities
+- **Collision detection**: Complex collision algorithms
+- **Fluid simulation**: Particle fluid systems
+- **Cloth simulation**: Vertex physics calculations
+
+### 2. AI Computation
+- **Pathfinding**: A*, Dijkstra algorithms
+- **Behavior trees**: Complex AI decision logic
+- **Swarm intelligence**: Boid, fish school algorithms
+- **Neural networks**: Simple AI inference
+
+### 3. Data Processing
+- **Bulk entity updates**: State machines, lifecycle management
+- **Statistical calculations**: Game data analysis
+- **Image processing**: Texture generation, effect calculations
+- **Audio processing**: Sound synthesis, spectrum analysis
+
+## Best Practices
+
+### 1. Worker Function Requirements
+
+```typescript
+// Recommended: Worker processing function is a pure function
+protected workerProcess(entities: PhysicsData[], deltaTime: number, config: any): PhysicsData[] {
+  // Only use parameters and standard JavaScript APIs
+  return entities.map(entity => {
+    // Pure computation logic, no external state dependencies
+    entity.y += entity.velocity * deltaTime;
+    return entity;
+  });
+}
+
+// Avoid: Using external references in Worker function
+protected workerProcess(entities: PhysicsData[], deltaTime: number): PhysicsData[] {
+  // this and external variables are not available in Worker
+  return entities.map(entity => {
+    entity.y += this.someProperty; // Error
+    return entity;
+  });
+}
+```
+
+### 2. Data Design
+
+```typescript
+// Recommended: Reasonable data design
+interface SimplePhysicsData {
+  x: number;
+  y: number;
+  vx: number;
+  vy: number;
+  // Keep data structure simple for easy serialization
+}
+
+// Avoid: Complex nested objects
+interface ComplexData {
+  transform: {
+    position: { x: number; y: number };
+    rotation: { angle: number };
+  };
+  // Complex nested structures increase serialization overhead
+}
+```
+
+### 3. Worker Count Control
+
+```typescript
+// Recommended: Flexible Worker configuration
+constructor() {
+  super(matcher, {
+    // Specify needed Worker count, system auto-limits to hardware capacity
+    workerCount: 8,                     // Request 8 Workers
+    entitiesPerWorker: 100,            // 100 entities per Worker
+    enableWorker: this.shouldUseWorker(), // Conditional enable
+  });
+}
+
+private shouldUseWorker(): boolean {
+  // Decide based on entity count and complexity
+  return this.expectedEntityCount > 100;
+}
+
+// Get actual Worker info
+checkWorkerConfiguration() {
+  const info = this.getWorkerInfo();
+  console.log(`Requested Workers: 8`);
+  console.log(`Actual Workers: ${info.workerCount}`);
+  console.log(`System maximum: ${info.maxSystemWorkerCount}`);
+  console.log(`Entities per Worker: ${info.entitiesPerWorker || 'auto'}`);
+}
+```
+
+### 4. Performance Monitoring
+
+```typescript
+// Recommended: Performance monitoring
+public getPerformanceMetrics(): WorkerPerformanceMetrics {
+  return {
+    ...this.getWorkerInfo(),
+    entityCount: this.entities.length,
+    averageProcessTime: this.getAverageProcessTime(),
+    workerUtilization: this.getWorkerUtilization()
+  };
+}
+```
+
+## Performance Optimization Tips
+
+### 1. Compute Intensity Assessment
+Only use Workers for compute-intensive tasks to avoid thread overhead for simple calculations.
+
+### 2. Data Transfer Optimization
+- Use SharedArrayBuffer to reduce serialization overhead
+- Keep data structures simple and flat
+- Avoid frequent large data transfers
+
+### 3. Degradation Strategy
+Always provide main thread fallback to ensure normal operation in environments without Worker support.
+
+### 4. Memory Management
+Clean up Worker pools and shared buffers promptly to avoid memory leaks.
+
+### 5. Load Balancing
+Use `entitiesPerWorker` parameter to precisely control load distribution, avoiding idle Workers while others are overloaded.
+
+## WeChat Mini Game Support
+
+WeChat Mini Game has special Worker limitations and doesn't support dynamic Worker script creation. ESEngine provides the `@esengine/worker-generator` CLI tool to solve this problem.
+
+### WeChat Mini Game Worker Limitations
+
+| Feature | Browser | WeChat Mini Game |
+|---------|---------|------------------|
+| Dynamic scripts (Blob URL) | Supported | Not supported |
+| Worker count | Multiple | Maximum 1 |
+| Script source | Any | Must be in code package |
+| SharedArrayBuffer | Requires COOP/COEP | Limited support |
+
+### Using Worker Generator CLI
+
+#### 1. Install the Tool
+
+```bash
+pnpm add -D @esengine/worker-generator
+```
+
+#### 2. Configure workerScriptPath
+
+Configure `workerScriptPath` in your WorkerEntitySystem subclass:
+
+```typescript
+@ECSSystem('Physics')
+class PhysicsWorkerSystem extends WorkerEntitySystem<PhysicsData> {
+  constructor() {
+    super(Matcher.all(Position, Velocity, Physics), {
+      enableWorker: true,
+      workerScriptPath: 'workers/physics-worker.js', // Specify Worker file path
+      systemConfig: {
+        gravity: 100,
+        friction: 0.95
+      }
+    });
+  }
+
+  protected workerProcess(
+    entities: PhysicsData[],
+    deltaTime: number,
+    config: any
+  ): PhysicsData[] {
+    // Physics calculation logic
+    return entities.map(entity => {
+      entity.vy += config.gravity * deltaTime;
+      entity.x += entity.vx * deltaTime;
+      entity.y += entity.vy * deltaTime;
+      return entity;
+    });
+  }
+
+  // ... other methods
+}
+```
+
+#### 3. Generate Worker Files
+
+Run the CLI tool to automatically extract `workerProcess` functions and generate WeChat Mini Game compatible Worker files:
+
+```bash
+# Basic usage
+npx esengine-worker-gen --src ./src --wechat
+
+# Full options
+npx esengine-worker-gen \
+  --src ./src \           # Source directory
+  --wechat \              # Generate WeChat Mini Game compatible code
+  --mapping \             # Generate worker-mapping.json
+  --verbose               # Verbose output
+```
+
+The CLI tool will:
+1. Scan source directory for all `WorkerEntitySystem` subclasses
+2. Read each class's `workerScriptPath` configuration
+3. Extract `workerProcess` method body
+4. Convert to ES5 syntax (WeChat Mini Game compatible)
+5. Generate to configured path
+
+#### 4. Configure game.json
+
+Configure workers directory in WeChat Mini Game's `game.json`:
+
+```json
+{
+  "deviceOrientation": "portrait",
+  "workers": "workers"
+}
+```
+
+#### 5. Project Structure
+
+```
+your-game/
+├── game.js
+├── game.json           # Configure "workers": "workers"
+├── src/
+│   └── systems/
+│       └── PhysicsSystem.ts  # workerScriptPath: 'workers/physics-worker.js'
+└── workers/
+    ├── physics-worker.js     # Auto-generated
+    └── worker-mapping.json   # Auto-generated
+```
+
+### Temporarily Disabling Workers
+
+If you need to temporarily disable Workers (e.g., for debugging), there are two ways:
+
+#### Method 1: Configuration Disable
+
+```typescript
+constructor() {
+  super(matcher, {
+    enableWorker: false, // Disable Worker, use main thread processing
+    // ...
+  });
+}
+```
+
+#### Method 2: Platform Adapter Disable
+
+Return Worker not supported in custom platform adapter:
+
+```typescript
+class MyPlatformAdapter implements IPlatformAdapter {
+  isWorkerSupported(): boolean {
+    return false; // Return false to disable Worker
+  }
+  // ...
+}
+```
+
+### Important Notes
+
+1. **Re-run CLI tool after each `workerProcess` modification** to generate new Worker files
+
+2. **Worker functions must be pure functions**, cannot depend on `this` or external variables:
+   ```typescript
+   // Correct: Only use parameters
+   protected workerProcess(entities, deltaTime, config) {
+     return entities.map(e => {
+       e.y += config.gravity * deltaTime;
+       return e;
+     });
+   }
+
+   // Wrong: Using this
+   protected workerProcess(entities, deltaTime, config) {
+     return entities.map(e => {
+       e.y += this.gravity * deltaTime; // Cannot access this in Worker
+       return e;
+     });
+   }
+   ```
+
+3. **Pass configuration data via `systemConfig`**, not class properties
+
+4. **Developer tool warnings can be ignored**:
+   - `getNetworkType:fail not support` - WeChat DevTools internal behavior
+   - `SharedArrayBuffer will require cross-origin isolation` - Development environment warning, won't appear on real devices
+
+## Online Demo
+
+See the complete Worker system demo: [Worker System Demo](https://esengine.github.io/ecs-framework/demos/worker-system/)
+
+The demo showcases:
+- Multi-threaded physics computation
+- Real-time performance comparison
+- SharedArrayBuffer optimization
+- Parallel processing of many entities
+
+The Worker system provides powerful parallel computing capabilities for the ECS framework, allowing you to fully utilize modern multi-core processor performance, offering efficient solutions for complex game logic and compute-intensive tasks.

docs/en/index.md

@@ -0,0 +1,317 @@
+---
+layout: page
+title: ESEngine - High-performance TypeScript ECS Framework
+---
+
+<ParticleHeroEn />
+
+<section class="news-section">
+  <div class="news-container">
+    <div class="news-header">
+      <h2 class="news-title">Quick Links</h2>
+      <a href="/en/guide/" class="news-more">View Docs</a>
+    </div>
+    <div class="news-grid">
+      <a href="/en/guide/getting-started" class="news-card">
+        <div class="news-card-image" style="background: linear-gradient(135deg, #1e3a5f 0%, #1e1e1e 100%);">
+          <div class="news-icon">
+            <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24"><path fill="#4fc1ff" d="M12 3L1 9l4 2.18v6L12 21l7-3.82v-6l2-1.09V17h2V9zm6.82 6L12 12.72L5.18 9L12 5.28zM17 16l-5 2.72L7 16v-3.73L12 15l5-2.73z"/></svg>
+          </div>
+          <span class="news-badge">Quick Start</span>
+        </div>
+        <div class="news-card-content">
+          <h3>Get Started in 5 Minutes</h3>
+          <p>From installation to your first ECS app, learn the core concepts quickly.</p>
+        </div>
+      </a>
+      <a href="/en/guide/behavior-tree/" class="news-card">
+        <div class="news-card-image" style="background: linear-gradient(135deg, #1e3a5f 0%, #1e1e1e 100%);">
+          <div class="news-icon">
+            <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24"><path fill="#4ec9b0" d="M12 2a2 2 0 0 1 2 2a2 2 0 0 1-2 2a2 2 0 0 1-2-2a2 2 0 0 1 2-2m3 20h-1v-7l-2-2l-2 2v7H9v-7.5l-2 2V22H6v-6l3-3l1-3.5c-.3.4-.6.7-1 1L6 9v1H4V8l5-3c.5-.3 1.1-.5 1.7-.5H11c.6 0 1.2.2 1.7.5l5 3v2h-2V9l-3 1.5c-.4-.3-.7-.6-1-1l1 3.5l3 3v6Z"/></svg>
+          </div>
+          <span class="news-badge">AI System</span>
+        </div>
+        <div class="news-card-content">
+          <h3>Visual Behavior Tree Editor</h3>
+          <p>Built-in AI behavior tree system with visual editing and real-time debugging.</p>
+        </div>
+      </a>
+    </div>
+  </div>
+</section>
+
+<section class="features-section">
+  <div class="features-container">
+    <h2 class="features-title">Core Features</h2>
+    <div class="features-grid">
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#4fc1ff" d="M13 2.05v2.02c3.95.49 7 3.85 7 7.93c0 1.45-.39 2.79-1.06 3.95l1.59 1.09A9.94 9.94 0 0 0 22 12c0-5.18-3.95-9.45-9-9.95M12 19c-3.87 0-7-3.13-7-7c0-3.53 2.61-6.43 6-6.92V2.05c-5.06.5-9 4.76-9 9.95c0 5.52 4.47 10 9.99 10c3.31 0 6.24-1.61 8.06-4.09l-1.6-1.1A7.93 7.93 0 0 1 12 19"/><path fill="#4fc1ff" d="M12 6a6 6 0 0 0-6 6c0 3.31 2.69 6 6 6a6 6 0 0 0 0-12m0 10c-2.21 0-4-1.79-4-4s1.79-4 4-4s4 1.79 4 4s-1.79 4-4 4"/></svg>
+        </div>
+        <h3 class="feature-title">High-performance ECS Architecture</h3>
+        <p class="feature-desc">Data-driven entity component system for large-scale entity processing with cache-friendly memory layout.</p>
+        <a href="/en/guide/entity" class="feature-link">Learn more</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#569cd6" d="M3 3h18v18H3zm16.525 13.707c0-.795-.272-1.425-.816-1.89c-.544-.465-1.404-.804-2.58-1.016l-1.704-.296c-.616-.104-1.052-.26-1.308-.468c-.256-.21-.384-.468-.384-.776c0-.392.168-.7.504-.924c.336-.224.8-.336 1.392-.336c.56 0 1.008.124 1.344.372c.336.248.536.584.6 1.008h2.016c-.08-.96-.464-1.716-1.152-2.268c-.688-.552-1.6-.828-2.736-.828c-1.2 0-2.148.3-2.844.9c-.696.6-1.044 1.38-1.044 2.34c0 .76.252 1.368.756 1.824c.504.456 1.308.792 2.412.996l1.704.312c.624.12 1.068.28 1.332.48c.264.2.396.46.396.78c0 .424-.192.756-.576.996c-.384.24-.9.36-1.548.36c-.672 0-1.2-.14-1.584-.42c-.384-.28-.608-.668-.672-1.164H8.868c.048 1.016.46 1.808 1.236 2.376c.776.568 1.796.852 3.06.852c1.24 0 2.22-.292 2.94-.876c.72-.584 1.08-1.364 1.08-2.34z"/></svg>
+        </div>
+        <h3 class="feature-title">Full Type Support</h3>
+        <p class="feature-desc">100% TypeScript with complete type definitions and compile-time checking for the best development experience.</p>
+        <a href="/en/guide/component" class="feature-link">Learn more</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#4ec9b0" d="M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10s10-4.5 10-10S17.5 2 12 2m0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8s8 3.59 8 8s-3.59 8-8 8m-5-8l4-4v3h4v2h-4v3z"/></svg>
+        </div>
+        <h3 class="feature-title">Visual Behavior Tree</h3>
+        <p class="feature-desc">Built-in AI behavior tree system with visual editor, custom nodes, and real-time debugging.</p>
+        <a href="/en/guide/behavior-tree/" class="feature-link">Learn more</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#c586c0" d="M4 6h18V4H4c-1.1 0-2 .9-2 2v11H0v3h14v-3H4zm19 2h-6c-.55 0-1 .45-1 1v10c0 .55.45 1 1 1h6c.55 0 1-.45 1-1V9c0-.55-.45-1-1-1m-1 9h-4v-7h4z"/></svg>
+        </div>
+        <h3 class="feature-title">Multi-Platform Support</h3>
+        <p class="feature-desc">Support for browsers, Node.js, WeChat Mini Games, and seamless integration with major game engines.</p>
+        <a href="/en/guide/platform-adapter" class="feature-link">Learn more</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#dcdcaa" d="M4 3h6v2H4v14h6v2H4c-1.1 0-2-.9-2-2V5c0-1.1.9-2 2-2m9 0h6c1.1 0 2 .9 2 2v14c0 1.1-.9 2-2 2h-6v-2h6V5h-6zm-1 7h4v2h-4z"/></svg>
+        </div>
+        <h3 class="feature-title">Modular Design</h3>
+        <p class="feature-desc">Core features packaged independently, import only what you need. Support for custom plugin extensions.</p>
+        <a href="/en/guide/plugin-system" class="feature-link">Learn more</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#9cdcfe" d="M22.7 19l-9.1-9.1c.9-2.3.4-5-1.5-6.9c-2-2-5-2.4-7.4-1.3L9 6L6 9L1.6 4.7C.4 7.1.9 10.1 2.9 12.1c1.9 1.9 4.6 2.4 6.9 1.5l9.1 9.1c.4.4 1 .4 1.4 0l2.3-2.3c.5-.4.5-1.1.1-1.4"/></svg>
+        </div>
+        <h3 class="feature-title">Developer Tools</h3>
+        <p class="feature-desc">Built-in performance monitoring, debugging tools, serialization system, and complete development toolchain.</p>
+        <a href="/en/guide/logging" class="feature-link">Learn more</a>
+      </div>
+    </div>
+  </div>
+</section>
+
+<style scoped>
+/* Home page specific styles */
+.news-section {
+  background: #0d0d0d;
+  padding: 64px 0;
+  border-top: 1px solid #2a2a2a;
+}
+
+.news-container {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 48px;
+}
+
+.news-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 32px;
+}
+
+.news-title {
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: #ffffff;
+  margin: 0;
+}
+
+.news-more {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 20px;
+  background: #1a1a1a;
+  border: 1px solid #2a2a2a;
+  border-radius: 6px;
+  color: #a0a0a0;
+  font-size: 0.875rem;
+  font-weight: 500;
+  text-decoration: none;
+  transition: all 0.2s;
+}
+
+.news-more:hover {
+  background: #252525;
+  color: #ffffff;
+}
+
+.news-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 24px;
+}
+
+.news-card {
+  display: flex;
+  background: #1f1f1f;
+  border: 1px solid #2a2a2a;
+  border-radius: 12px;
+  overflow: hidden;
+  text-decoration: none;
+  transition: all 0.2s;
+}
+
+.news-card:hover {
+  border-color: #3b9eff;
+}
+
+.news-card-image {
+  width: 200px;
+  min-height: 140px;
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  gap: 12px;
+}
+
+.news-icon {
+  opacity: 0.9;
+}
+
+.news-badge {
+  display: inline-block;
+  padding: 4px 12px;
+  background: transparent;
+  border: 1px solid #3a3a3a;
+  border-radius: 16px;
+  color: #a0a0a0;
+  font-size: 0.75rem;
+  font-weight: 500;
+}
+
+.news-card-content {
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+}
+
+.news-card-content h3 {
+  font-size: 1.125rem;
+  font-weight: 600;
+  color: #ffffff;
+  margin: 0 0 8px 0;
+}
+
+.news-card-content p {
+  font-size: 0.875rem;
+  color: #707070;
+  margin: 0;
+  line-height: 1.6;
+}
+
+.features-section {
+  background: #0d0d0d;
+  padding: 64px 0;
+}
+
+.features-container {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 48px;
+}
+
+.features-title {
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: #ffffff;
+  margin: 0 0 32px 0;
+}
+
+.features-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 20px;
+}
+
+.feature-card {
+  background: #1f1f1f;
+  border: 1px solid #2a2a2a;
+  border-radius: 12px;
+  padding: 24px;
+  transition: all 0.15s ease;
+}
+
+.feature-card:hover {
+  border-color: #3b9eff;
+  background: #252525;
+}
+
+.feature-icon {
+  width: 48px;
+  height: 48px;
+  background: #0d0d0d;
+  border-radius: 10px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 16px;
+}
+
+.feature-title {
+  font-size: 16px;
+  font-weight: 600;
+  color: #ffffff;
+  margin: 0 0 8px 0;
+}
+
+.feature-desc {
+  font-size: 14px;
+  color: #707070;
+  line-height: 1.7;
+  margin: 0 0 16px 0;
+}
+
+.feature-link {
+  font-size: 14px;
+  color: #3b9eff;
+  text-decoration: none;
+  font-weight: 500;
+}
+
+.feature-link:hover {
+  text-decoration: underline;
+}
+
+@media (max-width: 1024px) {
+  .news-container,
+  .features-container {
+    padding: 0 24px;
+  }
+
+  .news-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .features-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (max-width: 768px) {
+  .news-card {
+    flex-direction: column;
+  }
+
+  .news-card-image {
+    width: 100%;
+    min-height: 120px;
+  }
+
+  .features-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>

docs/en/modules/blueprint/index.md

@@ -0,0 +1,404 @@
+# Blueprint Visual Scripting
+
+`@esengine/blueprint` provides a full-featured visual scripting system supporting node-based programming, event-driven execution, and blueprint composition.
+
+## Installation
+
+```bash
+npm install @esengine/blueprint
+```
+
+## Quick Start
+
+```typescript
+import {
+    createBlueprintSystem,
+    createBlueprintComponentData,
+    NodeRegistry,
+    RegisterNode
+} from '@esengine/blueprint';
+
+// Create blueprint system
+const blueprintSystem = createBlueprintSystem(scene);
+
+// Load blueprint asset
+const blueprint = await loadBlueprintAsset('player.bp');
+
+// Create blueprint component data
+const componentData = createBlueprintComponentData();
+componentData.blueprintAsset = blueprint;
+
+// Update in game loop
+function gameLoop(dt: number) {
+    blueprintSystem.process(entities, dt);
+}
+```
+
+## Core Concepts
+
+### Blueprint Asset Structure
+
+Blueprints are saved as `.bp` files:
+
+```typescript
+interface BlueprintAsset {
+    version: number;             // Format version
+    type: 'blueprint';           // Asset type
+    metadata: BlueprintMetadata; // Metadata
+    variables: BlueprintVariable[]; // Variable definitions
+    nodes: BlueprintNode[];      // Node instances
+    connections: BlueprintConnection[]; // Connections
+}
+```
+
+### Node Categories
+
+| Category | Description | Color |
+|----------|-------------|-------|
+| `event` | Event nodes (entry points) | Red |
+| `flow` | Flow control | Gray |
+| `entity` | Entity operations | Blue |
+| `component` | Component access | Cyan |
+| `math` | Math operations | Green |
+| `logic` | Logic operations | Red |
+| `variable` | Variable access | Purple |
+| `time` | Time utilities | Cyan |
+| `debug` | Debug utilities | Gray |
+
+### Pin Types
+
+Nodes connect through pins:
+
+```typescript
+interface BlueprintPinDefinition {
+    name: string;        // Pin name
+    type: PinDataType;   // Data type
+    direction: 'input' | 'output';
+    isExec?: boolean;    // Execution pin
+    defaultValue?: unknown;
+}
+
+type PinDataType =
+    | 'exec'      // Execution flow
+    | 'boolean'   // Boolean
+    | 'number'    // Number
+    | 'string'    // String
+    | 'vector2'   // 2D vector
+    | 'vector3'   // 3D vector
+    | 'entity'    // Entity reference
+    | 'component' // Component reference
+    | 'any';      // Any type
+```
+
+### Variable Scopes
+
+```typescript
+type VariableScope =
+    | 'local'     // Per execution
+    | 'instance'  // Per entity
+    | 'global';   // Shared globally
+```
+
+## Virtual Machine API
+
+### BlueprintVM
+
+The virtual machine executes blueprint graphs:
+
+```typescript
+import { BlueprintVM } from '@esengine/blueprint';
+
+const vm = new BlueprintVM(blueprintAsset, entity, scene);
+
+vm.start();           // Start (triggers BeginPlay)
+vm.tick(deltaTime);   // Update (triggers Tick)
+vm.stop();            // Stop (triggers EndPlay)
+
+vm.pause();
+vm.resume();
+
+// Trigger events
+vm.triggerEvent('EventCollision', { other: otherEntity });
+vm.triggerCustomEvent('OnDamage', { amount: 50 });
+
+// Debug mode
+vm.debug = true;
+```
+
+### Execution Context
+
+```typescript
+interface ExecutionContext {
+    blueprint: BlueprintAsset;
+    entity: Entity;
+    scene: IScene;
+    deltaTime: number;
+    time: number;
+
+    getInput<T>(nodeId: string, pinName: string): T;
+    setOutput(nodeId: string, pinName: string, value: unknown): void;
+    getVariable<T>(name: string): T;
+    setVariable(name: string, value: unknown): void;
+}
+```
+
+### Execution Result
+
+```typescript
+interface ExecutionResult {
+    outputs?: Record<string, unknown>; // Output values
+    nextExec?: string | null;          // Next exec pin
+    delay?: number;                    // Delay execution (ms)
+    yield?: boolean;                   // Pause until next frame
+    error?: string;                    // Error message
+}
+```
+
+## Custom Nodes
+
+### Define Node Template
+
+```typescript
+import { BlueprintNodeTemplate } from '@esengine/blueprint';
+
+const MyNodeTemplate: BlueprintNodeTemplate = {
+    type: 'MyCustomNode',
+    title: 'My Custom Node',
+    category: 'custom',
+    description: 'A custom node example',
+    keywords: ['custom', 'example'],
+    inputs: [
+        { name: 'exec', type: 'exec', direction: 'input', isExec: true },
+        { name: 'value', type: 'number', direction: 'input', defaultValue: 0 }
+    ],
+    outputs: [
+        { name: 'exec', type: 'exec', direction: 'output', isExec: true },
+        { name: 'result', type: 'number', direction: 'output' }
+    ]
+};
+```
+
+### Implement Node Executor
+
+```typescript
+import { INodeExecutor, RegisterNode } from '@esengine/blueprint';
+
+@RegisterNode(MyNodeTemplate)
+class MyNodeExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
+        const value = context.getInput<number>(node.id, 'value');
+        const result = value * 2;
+
+        return {
+            outputs: { result },
+            nextExec: 'exec'
+        };
+    }
+}
+```
+
+### Registration Methods
+
+```typescript
+// Method 1: Decorator
+@RegisterNode(MyNodeTemplate)
+class MyNodeExecutor implements INodeExecutor { ... }
+
+// Method 2: Manual registration
+NodeRegistry.instance.register(MyNodeTemplate, new MyNodeExecutor());
+```
+
+## Node Registry
+
+```typescript
+import { NodeRegistry } from '@esengine/blueprint';
+
+const registry = NodeRegistry.instance;
+
+const allTemplates = registry.getAllTemplates();
+const mathNodes = registry.getTemplatesByCategory('math');
+const results = registry.searchTemplates('add');
+
+if (registry.has('MyCustomNode')) { ... }
+```
+
+## Built-in Nodes
+
+### Event Nodes
+| Node | Description |
+|------|-------------|
+| `EventBeginPlay` | Triggered on blueprint start |
+| `EventTick` | Triggered every frame |
+| `EventEndPlay` | Triggered on blueprint stop |
+| `EventCollision` | Triggered on collision |
+| `EventInput` | Triggered on input |
+| `EventTimer` | Triggered by timer |
+
+### Time Nodes
+| Node | Description |
+|------|-------------|
+| `Delay` | Delay execution |
+| `GetDeltaTime` | Get frame delta |
+| `GetTime` | Get total runtime |
+
+### Math Nodes
+| Node | Description |
+|------|-------------|
+| `Add`, `Subtract`, `Multiply`, `Divide` | Basic operations |
+| `Abs`, `Clamp`, `Lerp`, `Min`, `Max` | Utility functions |
+
+### Debug Nodes
+| Node | Description |
+|------|-------------|
+| `Print` | Print to console |
+
+## Blueprint Composition
+
+### Blueprint Fragments
+
+Encapsulate reusable logic as fragments:
+
+```typescript
+import { createFragment } from '@esengine/blueprint';
+
+const healthFragment = createFragment('HealthSystem', {
+    inputs: [
+        { name: 'damage', type: 'number', internalNodeId: 'input1', internalPinName: 'value' }
+    ],
+    outputs: [
+        { name: 'isDead', type: 'boolean', internalNodeId: 'output1', internalPinName: 'value' }
+    ],
+    graph: { nodes: [...], connections: [...], variables: [...] }
+});
+```
+
+### Compose Blueprints
+
+```typescript
+import { createComposer, FragmentRegistry } from '@esengine/blueprint';
+
+// Register fragments
+FragmentRegistry.instance.register('health', healthFragment);
+FragmentRegistry.instance.register('movement', movementFragment);
+
+// Create composer
+const composer = createComposer('PlayerBlueprint');
+
+// Add fragments to slots
+composer.addFragment(healthFragment, 'slot1', { position: { x: 0, y: 0 } });
+composer.addFragment(movementFragment, 'slot2', { position: { x: 400, y: 0 } });
+
+// Connect slots
+composer.connect('slot1', 'onDeath', 'slot2', 'disable');
+
+// Validate
+const validation = composer.validate();
+if (!validation.isValid) {
+    console.error(validation.errors);
+}
+
+// Compile to blueprint
+const blueprint = composer.compile();
+```
+
+## Trigger System
+
+### Define Trigger Conditions
+
+```typescript
+import { TriggerCondition, TriggerDispatcher } from '@esengine/blueprint';
+
+const lowHealthCondition: TriggerCondition = {
+    type: 'comparison',
+    left: { type: 'variable', name: 'health' },
+    operator: '<',
+    right: { type: 'constant', value: 20 }
+};
+```
+
+### Use Trigger Dispatcher
+
+```typescript
+const dispatcher = new TriggerDispatcher();
+
+dispatcher.register('lowHealth', lowHealthCondition, (context) => {
+    context.triggerEvent('OnLowHealth');
+});
+
+dispatcher.evaluate(context);
+```
+
+## ECS Integration
+
+### Using Blueprint System
+
+```typescript
+import { createBlueprintSystem } from '@esengine/blueprint';
+
+class GameScene {
+    private blueprintSystem: BlueprintSystem;
+
+    initialize() {
+        this.blueprintSystem = createBlueprintSystem(this.scene);
+    }
+
+    update(dt: number) {
+        this.blueprintSystem.process(this.entities, dt);
+    }
+}
+```
+
+### Triggering Blueprint Events
+
+```typescript
+import { triggerBlueprintEvent, triggerCustomBlueprintEvent } from '@esengine/blueprint';
+
+triggerBlueprintEvent(entity, 'Collision', { other: otherEntity });
+triggerCustomBlueprintEvent(entity, 'OnPickup', { item: itemEntity });
+```
+
+## Serialization
+
+### Save Blueprint
+
+```typescript
+import { validateBlueprintAsset } from '@esengine/blueprint';
+
+function saveBlueprint(blueprint: BlueprintAsset, path: string): void {
+    if (!validateBlueprintAsset(blueprint)) {
+        throw new Error('Invalid blueprint structure');
+    }
+    const json = JSON.stringify(blueprint, null, 2);
+    fs.writeFileSync(path, json);
+}
+```
+
+### Load Blueprint
+
+```typescript
+async function loadBlueprint(path: string): Promise<BlueprintAsset> {
+    const json = await fs.readFile(path, 'utf-8');
+    const asset = JSON.parse(json);
+
+    if (!validateBlueprintAsset(asset)) {
+        throw new Error('Invalid blueprint file');
+    }
+
+    return asset;
+}
+```
+
+## Best Practices
+
+1. **Use fragments for reusable logic**
+2. **Choose appropriate variable scopes**
+   - `local`: Temporary calculations
+   - `instance`: Entity state (e.g., health)
+   - `global`: Game-wide state
+3. **Avoid infinite loops** - VM has max steps per frame (default 1000)
+4. **Debug techniques**
+   - Enable `vm.debug = true` for execution logs
+   - Use Print nodes for intermediate values
+5. **Performance optimization**
+   - Pure nodes (`isPure: true`) cache outputs
+   - Avoid heavy computation in Tick

docs/en/modules/fsm/index.md

@@ -0,0 +1,316 @@
+# State Machine (FSM)
+
+`@esengine/fsm` provides a type-safe finite state machine implementation for characters, AI, or any scenario requiring state management.
+
+## Installation
+
+```bash
+npm install @esengine/fsm
+```
+
+## Quick Start
+
+```typescript
+import { createStateMachine } from '@esengine/fsm';
+
+// Define state types
+type PlayerState = 'idle' | 'walk' | 'run' | 'jump';
+
+// Create state machine
+const fsm = createStateMachine<PlayerState>('idle');
+
+// Define states with callbacks
+fsm.defineState('idle', {
+    onEnter: (ctx, from) => console.log(`Entered idle from ${from}`),
+    onExit: (ctx, to) => console.log(`Exiting idle to ${to}`),
+    onUpdate: (ctx, dt) => { /* Update every frame */ }
+});
+
+fsm.defineState('walk', {
+    onEnter: () => console.log('Started walking')
+});
+
+// Manual transition
+fsm.transition('walk');
+
+console.log(fsm.current); // 'walk'
+```
+
+## Core Concepts
+
+### State Configuration
+
+Each state can be configured with the following callbacks:
+
+```typescript
+interface StateConfig<TState, TContext> {
+    name: TState;                                    // State name
+    onEnter?: (context: TContext, from: TState | null) => void;  // Enter callback
+    onExit?: (context: TContext, to: TState) => void;            // Exit callback
+    onUpdate?: (context: TContext, deltaTime: number) => void;   // Update callback
+    tags?: string[];                                 // State tags
+    metadata?: Record<string, unknown>;              // Metadata
+}
+```
+
+### Transition Conditions
+
+Define conditional state transitions:
+
+```typescript
+interface Context {
+    isMoving: boolean;
+    isRunning: boolean;
+    isGrounded: boolean;
+}
+
+const fsm = createStateMachine<PlayerState, Context>('idle', {
+    context: { isMoving: false, isRunning: false, isGrounded: true }
+});
+
+// Define transition conditions
+fsm.defineTransition('idle', 'walk', (ctx) => ctx.isMoving);
+fsm.defineTransition('walk', 'run', (ctx) => ctx.isRunning);
+fsm.defineTransition('walk', 'idle', (ctx) => !ctx.isMoving);
+
+// Automatically evaluate and execute matching transitions
+fsm.evaluateTransitions();
+```
+
+### Transition Priority
+
+When multiple transitions are valid, higher priority executes first:
+
+```typescript
+// Higher priority number = higher priority
+fsm.defineTransition('idle', 'attack', (ctx) => ctx.isAttacking, 10);
+fsm.defineTransition('idle', 'walk', (ctx) => ctx.isMoving, 1);
+
+// If both conditions are met, 'attack' (priority 10) is tried first
+```
+
+## API Reference
+
+### createStateMachine
+
+```typescript
+function createStateMachine<TState extends string, TContext = unknown>(
+    initialState: TState,
+    options?: StateMachineOptions<TContext>
+): IStateMachine<TState, TContext>
+```
+
+**Parameters:**
+- `initialState` - Initial state
+- `options.context` - Context object, accessible in callbacks
+- `options.maxHistorySize` - Maximum history entries (default 100)
+- `options.enableHistory` - Enable history tracking (default true)
+
+### State Machine Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `current` | `TState` | Current state |
+| `previous` | `TState \| null` | Previous state |
+| `context` | `TContext` | Context object |
+| `isTransitioning` | `boolean` | Whether currently transitioning |
+| `currentStateDuration` | `number` | Current state duration (ms) |
+
+### State Machine Methods
+
+#### State Definition
+
+```typescript
+// Define state
+fsm.defineState('idle', {
+    onEnter: (ctx, from) => {},
+    onExit: (ctx, to) => {},
+    onUpdate: (ctx, dt) => {}
+});
+
+// Check if state exists
+fsm.hasState('idle'); // true
+
+// Get state configuration
+fsm.getStateConfig('idle');
+
+// Get all states
+fsm.getStates(); // ['idle', 'walk', ...]
+```
+
+#### Transition Operations
+
+```typescript
+// Define transition
+fsm.defineTransition('idle', 'walk', condition, priority);
+
+// Remove transition
+fsm.removeTransition('idle', 'walk');
+
+// Get transitions from state
+fsm.getTransitionsFrom('idle');
+
+// Check if transition is possible
+fsm.canTransition('walk'); // true/false
+
+// Manual transition
+fsm.transition('walk');
+
+// Force transition (ignore conditions)
+fsm.transition('walk', true);
+
+// Auto-evaluate transition conditions
+fsm.evaluateTransitions();
+```
+
+#### Lifecycle
+
+```typescript
+// Update state machine (calls current state's onUpdate)
+fsm.update(deltaTime);
+
+// Reset state machine
+fsm.reset(); // Reset to current state
+fsm.reset('idle'); // Reset to specified state
+```
+
+#### Event Listeners
+
+```typescript
+// Listen to entering specific state
+const unsubscribe = fsm.onEnter('walk', (from) => {
+    console.log(`Entered walk from ${from}`);
+});
+
+// Listen to exiting specific state
+fsm.onExit('walk', (to) => {
+    console.log(`Exiting walk to ${to}`);
+});
+
+// Listen to any state change
+fsm.onChange((event) => {
+    console.log(`${event.from} -> ${event.to} at ${event.timestamp}`);
+});
+
+// Unsubscribe
+unsubscribe();
+```
+
+#### Debugging
+
+```typescript
+// Get state history
+const history = fsm.getHistory();
+// [{ from: 'idle', to: 'walk', timestamp: 1234567890 }, ...]
+
+// Clear history
+fsm.clearHistory();
+
+// Get debug info
+const info = fsm.getDebugInfo();
+// { current, previous, duration, stateCount, transitionCount, historySize }
+```
+
+## Practical Examples
+
+### Character State Machine
+
+```typescript
+import { createStateMachine } from '@esengine/fsm';
+
+type CharacterState = 'idle' | 'walk' | 'run' | 'jump' | 'fall' | 'attack';
+
+interface CharacterContext {
+    velocity: { x: number; y: number };
+    isGrounded: boolean;
+    isAttacking: boolean;
+    speed: number;
+}
+
+const characterFSM = createStateMachine<CharacterState, CharacterContext>('idle', {
+    context: {
+        velocity: { x: 0, y: 0 },
+        isGrounded: true,
+        isAttacking: false,
+        speed: 0
+    }
+});
+
+// Define states
+characterFSM.defineState('idle', {
+    onEnter: (ctx) => { ctx.speed = 0; }
+});
+
+characterFSM.defineState('walk', {
+    onEnter: (ctx) => { ctx.speed = 100; }
+});
+
+characterFSM.defineState('run', {
+    onEnter: (ctx) => { ctx.speed = 200; }
+});
+
+// Define transitions
+characterFSM.defineTransition('idle', 'walk', (ctx) => Math.abs(ctx.velocity.x) > 0);
+characterFSM.defineTransition('walk', 'idle', (ctx) => ctx.velocity.x === 0);
+characterFSM.defineTransition('walk', 'run', (ctx) => Math.abs(ctx.velocity.x) > 150);
+
+// Jump has highest priority
+characterFSM.defineTransition('idle', 'jump', (ctx) => !ctx.isGrounded, 10);
+characterFSM.defineTransition('walk', 'jump', (ctx) => !ctx.isGrounded, 10);
+
+// Game loop usage
+function gameUpdate(dt: number) {
+    // Update context
+    characterFSM.context.velocity.x = getInputVelocity();
+    characterFSM.context.isGrounded = checkGrounded();
+
+    // Evaluate transitions
+    characterFSM.evaluateTransitions();
+
+    // Update current state
+    characterFSM.update(dt);
+}
+```
+
+### ECS Integration
+
+```typescript
+import { Component, EntitySystem, Matcher } from '@esengine/ecs-framework';
+import { createStateMachine, type IStateMachine } from '@esengine/fsm';
+
+// State machine component
+class FSMComponent extends Component {
+    fsm: IStateMachine<string>;
+
+    constructor(initialState: string) {
+        super();
+        this.fsm = createStateMachine(initialState);
+    }
+}
+
+// State machine system
+class FSMSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(FSMComponent));
+    }
+
+    protected processEntity(entity: Entity, dt: number): void {
+        const fsmComp = entity.getComponent(FSMComponent);
+        fsmComp.fsm.evaluateTransitions();
+        fsmComp.fsm.update(dt);
+    }
+}
+```
+
+## Blueprint Nodes
+
+The FSM module provides blueprint nodes for visual scripting:
+
+- `GetCurrentState` - Get current state
+- `TransitionTo` - Transition to specified state
+- `CanTransition` - Check if transition is possible
+- `IsInState` - Check if in specified state
+- `WasInState` - Check if was ever in specified state
+- `GetStateDuration` - Get state duration
+- `EvaluateTransitions` - Evaluate transition conditions
+- `ResetStateMachine` - Reset state machine

docs/en/modules/index.md

@@ -0,0 +1,54 @@
+# Modules
+
+ESEngine provides a rich set of modules that can be imported as needed.
+
+## Module List
+
+### AI Modules
+
+| Module | Package | Description |
+|--------|---------|-------------|
+| [Behavior Tree](/en/modules/behavior-tree/) | `@esengine/behavior-tree` | AI behavior tree with visual editor |
+| [State Machine](/en/modules/fsm/) | `@esengine/fsm` | Finite state machine for character/AI states |
+
+### Gameplay
+
+| Module | Package | Description |
+|--------|---------|-------------|
+| [Timer](/en/modules/timer/) | `@esengine/timer` | Timer and cooldown system |
+| [Spatial](/en/modules/spatial/) | `@esengine/spatial` | Spatial queries, AOI management |
+| [Pathfinding](/en/modules/pathfinding/) | `@esengine/pathfinding` | A* pathfinding, NavMesh navigation |
+
+### Tools
+
+| Module | Package | Description |
+|--------|---------|-------------|
+| [Blueprint](/en/modules/blueprint/) | `@esengine/blueprint` | Visual scripting system |
+| [Procgen](/en/modules/procgen/) | `@esengine/procgen` | Noise functions, random utilities |
+
+### Network
+
+| Module | Package | Description |
+|--------|---------|-------------|
+| [Network](/en/modules/network/) | `@esengine/network` | Multiplayer game networking |
+
+## Installation
+
+All modules can be installed independently:
+
+```bash
+# Install a single module
+npm install @esengine/behavior-tree
+
+# Or use CLI to add to existing project
+npx @esengine/cli add behavior-tree
+```
+
+## Platform Compatibility
+
+All modules are pure TypeScript and compatible with:
+
+- Cocos Creator 3.x
+- Laya 3.x
+- Node.js
+- Browser

docs/en/modules/network/index.md

@@ -0,0 +1,727 @@
+# Network System
+
+`@esengine/network` provides a TSRPC-based client-server network synchronization solution for multiplayer games, including entity synchronization, input handling, and state interpolation.
+
+## Overview
+
+The network module consists of three packages:
+
+| Package | Description |
+|---------|-------------|
+| `@esengine/network` | Client-side ECS plugin |
+| `@esengine/network-protocols` | Shared protocol definitions |
+| `@esengine/network-server` | Server-side implementation |
+
+## Installation
+
+```bash
+# Client
+npm install @esengine/network
+
+# Server
+npm install @esengine/network-server
+```
+
+## Quick Setup with CLI
+
+We recommend using ESEngine CLI to quickly create a complete game server project:
+
+```bash
+# Create project directory
+mkdir my-game-server && cd my-game-server
+npm init -y
+
+# Initialize Node.js server with CLI
+npx @esengine/cli init -p nodejs
+```
+
+The CLI will generate the following project structure:
+
+```
+my-game-server/
+├── src/
+│   ├── index.ts                    # Entry point
+│   ├── server/
+│   │   └── GameServer.ts           # Network server configuration
+│   └── game/
+│       ├── Game.ts                 # ECS game class
+│       ├── scenes/
+│       │   └── MainScene.ts        # Main scene
+│       ├── components/             # ECS components
+│       │   ├── PositionComponent.ts
+│       │   └── VelocityComponent.ts
+│       └── systems/                # ECS systems
+│           └── MovementSystem.ts
+├── tsconfig.json
+├── package.json
+└── README.md
+```
+
+Start the server:
+
+```bash
+# Development mode (hot reload)
+npm run dev
+
+# Production mode
+npm run start
+```
+
+## Quick Start
+
+### Client
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    NetworkPlugin,
+    NetworkIdentity,
+    NetworkTransform
+} from '@esengine/network';
+
+// Define game scene
+class GameScene extends Scene {
+    initialize(): void {
+        this.name = 'Game';
+        // Network systems are automatically added by NetworkPlugin
+    }
+}
+
+// Initialize Core
+Core.create({ debug: false });
+const scene = new GameScene();
+Core.setScene(scene);
+
+// Install network plugin
+const networkPlugin = new NetworkPlugin();
+await Core.installPlugin(networkPlugin);
+
+// Register prefab factory
+networkPlugin.registerPrefab('player', (scene, spawn) => {
+    const entity = scene.createEntity(`player_${spawn.netId}`);
+
+    const identity = entity.addComponent(new NetworkIdentity());
+    identity.netId = spawn.netId;
+    identity.ownerId = spawn.ownerId;
+    identity.isLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId;
+
+    entity.addComponent(new NetworkTransform());
+    return entity;
+});
+
+// Connect to server
+const success = await networkPlugin.connect('ws://localhost:3000', 'PlayerName');
+if (success) {
+    console.log('Connected!');
+}
+
+// Game loop
+function gameLoop(dt: number) {
+    Core.update(dt);
+}
+
+// Disconnect
+await networkPlugin.disconnect();
+```
+
+### Server
+
+After creating a server project with CLI, the generated code already configures GameServer:
+
+```typescript
+import { GameServer } from '@esengine/network-server';
+
+const server = new GameServer({
+    port: 3000,
+    roomConfig: {
+        maxPlayers: 16,
+        tickRate: 20
+    }
+});
+
+await server.start();
+console.log('Server started on ws://localhost:3000');
+```
+
+## Core Concepts
+
+### Architecture
+
+```
+Client                              Server
+┌────────────────┐                ┌────────────────┐
+│ NetworkPlugin  │◄──── WS ────► │  GameServer    │
+│ ├─ Service     │                │  ├─ Room       │
+│ ├─ SyncSystem  │                │  └─ Players    │
+│ ├─ SpawnSystem │                └────────────────┘
+│ └─ InputSystem │
+└────────────────┘
+```
+
+### Components
+
+#### NetworkIdentity
+
+Network identity component, required for every networked entity:
+
+```typescript
+class NetworkIdentity extends Component {
+    netId: number;           // Network unique ID
+    ownerId: number;         // Owner client ID
+    bIsLocalPlayer: boolean; // Whether local player
+    bHasAuthority: boolean;  // Whether has control authority
+}
+```
+
+#### NetworkTransform
+
+Network transform component for position and rotation sync:
+
+```typescript
+class NetworkTransform extends Component {
+    position: { x: number; y: number };
+    rotation: number;
+    velocity: { x: number; y: number };
+}
+```
+
+### Systems
+
+#### NetworkSyncSystem
+
+Handles server state synchronization and interpolation:
+
+- Receives server state snapshots
+- Stores states in snapshot buffer
+- Performs interpolation for remote entities
+
+#### NetworkSpawnSystem
+
+Handles network entity spawning and despawning:
+
+- Listens for Spawn/Despawn messages
+- Creates entities using registered prefab factories
+- Manages networked entity lifecycle
+
+#### NetworkInputSystem
+
+Handles local player input sending:
+
+- Collects local player input
+- Sends input to server
+- Supports movement and action inputs
+
+## API Reference
+
+### NetworkPlugin
+
+```typescript
+class NetworkPlugin {
+    constructor(config: INetworkPluginConfig);
+
+    // Install plugin
+    install(services: ServiceContainer): void;
+
+    // Connect to server
+    connect(playerName: string, roomId?: string): Promise<void>;
+
+    // Disconnect
+    disconnect(): void;
+
+    // Register prefab factory
+    registerPrefab(prefab: string, factory: PrefabFactory): void;
+
+    // Properties
+    readonly localPlayerId: number | null;
+    readonly isConnected: boolean;
+}
+```
+
+**Configuration:**
+
+| Property | Type | Required | Description |
+|----------|------|----------|-------------|
+| `serverUrl` | `string` | Yes | WebSocket server URL |
+
+### NetworkService
+
+Network service managing WebSocket connections:
+
+```typescript
+class NetworkService {
+    // Connection state
+    readonly state: ENetworkState;
+    readonly isConnected: boolean;
+    readonly clientId: number | null;
+    readonly roomId: string | null;
+
+    // Connection control
+    connect(serverUrl: string): Promise<void>;
+    disconnect(): void;
+
+    // Join room
+    join(playerName: string, roomId?: string): Promise<ResJoin>;
+
+    // Send input
+    sendInput(input: IPlayerInput): void;
+
+    // Event callbacks
+    setCallbacks(callbacks: Partial<INetworkCallbacks>): void;
+}
+```
+
+**Network state enum:**
+
+```typescript
+enum ENetworkState {
+    Disconnected = 'disconnected',
+    Connecting = 'connecting',
+    Connected = 'connected',
+    Joining = 'joining',
+    Joined = 'joined'
+}
+```
+
+**Callbacks interface:**
+
+```typescript
+interface INetworkCallbacks {
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    onJoined?: (clientId: number, roomId: string) => void;
+    onSync?: (msg: MsgSync) => void;
+    onSpawn?: (msg: MsgSpawn) => void;
+    onDespawn?: (msg: MsgDespawn) => void;
+}
+```
+
+### Prefab Factory
+
+```typescript
+type PrefabFactory = (scene: Scene, spawn: MsgSpawn) => Entity;
+```
+
+Register prefab factories for network entity creation:
+
+```typescript
+networkPlugin.registerPrefab('enemy', (scene, spawn) => {
+    const entity = scene.createEntity(`enemy_${spawn.netId}`);
+
+    const identity = entity.addComponent(new NetworkIdentity());
+    identity.netId = spawn.netId;
+    identity.ownerId = spawn.ownerId;
+
+    entity.addComponent(new NetworkTransform());
+    entity.addComponent(new EnemyComponent());
+    return entity;
+});
+```
+
+### Input System
+
+#### NetworkInputSystem
+
+```typescript
+class NetworkInputSystem extends EntitySystem {
+    // Add movement input
+    addMoveInput(x: number, y: number): void;
+
+    // Add action input
+    addActionInput(action: string): void;
+
+    // Clear input
+    clearInput(): void;
+}
+```
+
+Usage example:
+
+```typescript
+// Send input via NetworkPlugin (recommended)
+networkPlugin.sendMoveInput(0, 1);      // Movement
+networkPlugin.sendActionInput('jump');  // Action
+
+// Or use inputSystem directly
+const inputSystem = networkPlugin.inputSystem;
+if (keyboard.isPressed('W')) {
+    inputSystem.addMoveInput(0, 1);
+}
+if (keyboard.isPressed('Space')) {
+    inputSystem.addActionInput('jump');
+}
+```
+
+## State Synchronization
+
+### Snapshot Buffer
+
+Stores server state snapshots for interpolation:
+
+```typescript
+import { createSnapshotBuffer, type IStateSnapshot } from '@esengine/network';
+
+const buffer = createSnapshotBuffer<IStateSnapshot>({
+    maxSnapshots: 30,          // Max snapshots
+    interpolationDelay: 100    // Interpolation delay (ms)
+});
+
+// Add snapshot
+buffer.addSnapshot({
+    time: serverTime,
+    entities: states
+});
+
+// Get interpolated state
+const interpolated = buffer.getInterpolatedState(clientTime);
+```
+
+### Transform Interpolators
+
+#### Linear Interpolator
+
+```typescript
+import { createTransformInterpolator } from '@esengine/network';
+
+const interpolator = createTransformInterpolator();
+
+// Add state
+interpolator.addState(time, { x: 0, y: 0, rotation: 0 });
+
+// Get interpolated result
+const state = interpolator.getInterpolatedState(currentTime);
+```
+
+#### Hermite Interpolator
+
+Uses Hermite splines for smoother interpolation:
+
+```typescript
+import { createHermiteTransformInterpolator } from '@esengine/network';
+
+const interpolator = createHermiteTransformInterpolator({
+    bufferSize: 10
+});
+
+// Add state with velocity
+interpolator.addState(time, {
+    x: 100,
+    y: 200,
+    rotation: 0,
+    vx: 5,
+    vy: 0
+});
+
+// Get smooth interpolated result
+const state = interpolator.getInterpolatedState(currentTime);
+```
+
+### Client Prediction
+
+Implement client-side prediction with server reconciliation:
+
+```typescript
+import { createClientPrediction } from '@esengine/network';
+
+const prediction = createClientPrediction({
+    maxPredictedInputs: 60,
+    reconciliationThreshold: 0.1
+});
+
+// Predict input
+const seq = prediction.predict(inputState, currentState, (state, input) => {
+    // Apply input to state
+    return applyInput(state, input);
+});
+
+// Server reconciliation
+const corrected = prediction.reconcile(
+    serverState,
+    serverSeq,
+    (state, input) => applyInput(state, input)
+);
+```
+
+## Server Side
+
+### GameServer
+
+```typescript
+import { GameServer } from '@esengine/network-server';
+
+const server = new GameServer({
+    port: 3000,
+    roomConfig: {
+        maxPlayers: 16,    // Max players per room
+        tickRate: 20       // Sync rate (Hz)
+    }
+});
+
+// Start server
+await server.start();
+
+// Get room
+const room = server.getOrCreateRoom('room-id');
+
+// Stop server
+await server.stop();
+```
+
+### Room
+
+```typescript
+class Room {
+    readonly id: string;
+    readonly playerCount: number;
+    readonly isFull: boolean;
+
+    // Add player
+    addPlayer(name: string, connection: Connection): IPlayer | null;
+
+    // Remove player
+    removePlayer(clientId: number): void;
+
+    // Get player
+    getPlayer(clientId: number): IPlayer | undefined;
+
+    // Handle input
+    handleInput(clientId: number, input: IPlayerInput): void;
+
+    // Destroy room
+    destroy(): void;
+}
+```
+
+**Player interface:**
+
+```typescript
+interface IPlayer {
+    clientId: number;        // Client ID
+    name: string;            // Player name
+    connection: Connection;  // Connection object
+    netId: number;           // Network entity ID
+}
+```
+
+## Protocol Types
+
+### Message Types
+
+```typescript
+// State sync message
+interface MsgSync {
+    time: number;
+    entities: IEntityState[];
+}
+
+// Entity state
+interface IEntityState {
+    netId: number;
+    pos?: Vec2;
+    rot?: number;
+}
+
+// Spawn message
+interface MsgSpawn {
+    netId: number;
+    ownerId: number;
+    prefab: string;
+    pos: Vec2;
+    rot: number;
+}
+
+// Despawn message
+interface MsgDespawn {
+    netId: number;
+}
+
+// Input message
+interface MsgInput {
+    input: IPlayerInput;
+}
+
+// Player input
+interface IPlayerInput {
+    seq?: number;
+    moveDir?: Vec2;
+    actions?: string[];
+}
+```
+
+### API Types
+
+```typescript
+// Join request
+interface ReqJoin {
+    playerName: string;
+    roomId?: string;
+}
+
+// Join response
+interface ResJoin {
+    clientId: number;
+    roomId: string;
+    playerCount: number;
+}
+```
+
+## Blueprint Nodes
+
+The network module provides blueprint nodes for visual scripting:
+
+- `IsLocalPlayer` - Check if entity is local player
+- `IsServer` - Check if running on server
+- `HasAuthority` - Check if has authority over entity
+- `GetNetworkId` - Get entity's network ID
+- `GetLocalPlayerId` - Get local player ID
+
+## Service Tokens
+
+For dependency injection:
+
+```typescript
+import {
+    NetworkServiceToken,
+    NetworkSyncSystemToken,
+    NetworkSpawnSystemToken,
+    NetworkInputSystemToken
+} from '@esengine/network';
+
+// Get service
+const networkService = services.get(NetworkServiceToken);
+```
+
+## Practical Example
+
+### Complete Multiplayer Client
+
+```typescript
+import { Core, Scene, EntitySystem, Matcher, Entity } from '@esengine/ecs-framework';
+import {
+    NetworkPlugin,
+    NetworkIdentity,
+    NetworkTransform
+} from '@esengine/network';
+
+// Define game scene
+class GameScene extends Scene {
+    initialize(): void {
+        this.name = 'MultiplayerGame';
+        // Network systems are automatically added by NetworkPlugin
+        // Add custom systems
+        this.addSystem(new LocalInputHandler());
+    }
+}
+
+// Initialize
+async function initGame() {
+    Core.create({ debug: false });
+
+    const scene = new GameScene();
+    Core.setScene(scene);
+
+    // Install network plugin
+    const networkPlugin = new NetworkPlugin();
+    await Core.installPlugin(networkPlugin);
+
+    // Register player prefab
+    networkPlugin.registerPrefab('player', (scene, spawn) => {
+        const entity = scene.createEntity(`player_${spawn.netId}`);
+
+        const identity = entity.addComponent(new NetworkIdentity());
+        identity.netId = spawn.netId;
+        identity.ownerId = spawn.ownerId;
+        identity.isLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId;
+
+        entity.addComponent(new NetworkTransform());
+
+        // If local player, add input marker
+        if (identity.isLocalPlayer) {
+            entity.addComponent(new LocalInputComponent());
+        }
+
+        return entity;
+    });
+
+    // Connect to server
+    const success = await networkPlugin.connect('ws://localhost:3000', 'Player1');
+    if (success) {
+        console.log('Connected!');
+    } else {
+        console.error('Connection failed');
+    }
+
+    return networkPlugin;
+}
+
+// Game loop
+function gameLoop(deltaTime: number) {
+    Core.update(deltaTime);
+}
+
+initGame();
+```
+
+### Handling Input
+
+```typescript
+class LocalInputHandler extends EntitySystem {
+    private _networkPlugin: NetworkPlugin | null = null;
+
+    constructor() {
+        super(Matcher.empty().all(NetworkIdentity, LocalInputComponent));
+    }
+
+    protected onAddedToScene(): void {
+        // Get NetworkPlugin reference
+        this._networkPlugin = Core.getPlugin(NetworkPlugin);
+    }
+
+    protected processEntity(entity: Entity, dt: number): void {
+        if (!this._networkPlugin) return;
+
+        const identity = entity.getComponent(NetworkIdentity)!;
+        if (!identity.isLocalPlayer) return;
+
+        // Read keyboard input
+        let moveX = 0;
+        let moveY = 0;
+
+        if (keyboard.isPressed('A')) moveX -= 1;
+        if (keyboard.isPressed('D')) moveX += 1;
+        if (keyboard.isPressed('W')) moveY += 1;
+        if (keyboard.isPressed('S')) moveY -= 1;
+
+        if (moveX !== 0 || moveY !== 0) {
+            this._networkPlugin.sendMoveInput(moveX, moveY);
+        }
+
+        if (keyboard.isJustPressed('Space')) {
+            this._networkPlugin.sendActionInput('jump');
+        }
+    }
+}
+```
+
+## Best Practices
+
+1. **Set appropriate sync rate**: Choose `tickRate` based on game type, action games typically need 20-60 Hz
+
+2. **Use interpolation delay**: Set appropriate `interpolationDelay` to balance latency and smoothness
+
+3. **Client prediction**: Use client-side prediction for local players to reduce input lag
+
+4. **Prefab management**: Register prefab factories for each networked entity type
+
+5. **Authority checks**: Use `bHasAuthority` to check entity control permissions
+
+6. **Connection state**: Monitor connection state changes, handle reconnection
+
+```typescript
+networkService.setCallbacks({
+    onConnected: () => console.log('Connected'),
+    onDisconnected: () => {
+        console.log('Disconnected');
+        // Handle reconnection logic
+    }
+});
+```

docs/en/modules/pathfinding/index.md

@@ -0,0 +1,299 @@
+# Pathfinding System
+
+`@esengine/pathfinding` provides a complete 2D pathfinding solution including A* algorithm, grid maps, navigation meshes, and path smoothing.
+
+## Installation
+
+```bash
+npm install @esengine/pathfinding
+```
+
+## Quick Start
+
+### Grid Map Pathfinding
+
+```typescript
+import { createGridMap, createAStarPathfinder } from '@esengine/pathfinding';
+
+// Create 20x20 grid
+const grid = createGridMap(20, 20);
+
+// Set obstacles
+grid.setWalkable(5, 5, false);
+grid.setWalkable(5, 6, false);
+
+// Create pathfinder
+const pathfinder = createAStarPathfinder(grid);
+
+// Find path
+const result = pathfinder.findPath(0, 0, 15, 15);
+
+if (result.found) {
+    console.log('Path found!');
+    console.log('Path:', result.path);
+    console.log('Cost:', result.cost);
+}
+```
+
+### NavMesh Pathfinding
+
+```typescript
+import { createNavMesh } from '@esengine/pathfinding';
+
+const navmesh = createNavMesh();
+
+// Add polygon areas
+navmesh.addPolygon([
+    { x: 0, y: 0 }, { x: 10, y: 0 },
+    { x: 10, y: 10 }, { x: 0, y: 10 }
+]);
+
+navmesh.addPolygon([
+    { x: 10, y: 0 }, { x: 20, y: 0 },
+    { x: 20, y: 10 }, { x: 10, y: 10 }
+]);
+
+// Auto-build connections
+navmesh.build();
+
+// Find path
+const result = navmesh.findPath(1, 1, 18, 8);
+```
+
+## Core Concepts
+
+### IPathResult
+
+```typescript
+interface IPathResult {
+    readonly found: boolean;        // Path found
+    readonly path: readonly IPoint[];// Path points
+    readonly cost: number;          // Total cost
+    readonly nodesSearched: number; // Nodes searched
+}
+```
+
+### IPathfindingOptions
+
+```typescript
+interface IPathfindingOptions {
+    maxNodes?: number;        // Max search nodes (default 10000)
+    heuristicWeight?: number; // Heuristic weight (>1 faster but may be suboptimal)
+    allowDiagonal?: boolean;  // Allow diagonal movement (default true)
+    avoidCorners?: boolean;   // Avoid corner cutting (default true)
+}
+```
+
+## Heuristic Functions
+
+| Function | Use Case | Description |
+|----------|----------|-------------|
+| `manhattanDistance` | 4-directional | Manhattan distance |
+| `euclideanDistance` | Any direction | Euclidean distance |
+| `chebyshevDistance` | 8-directional | Diagonal cost = 1 |
+| `octileDistance` | 8-directional | Diagonal cost = √2 (default) |
+
+## Grid Map API
+
+### createGridMap
+
+```typescript
+function createGridMap(
+    width: number,
+    height: number,
+    options?: IGridMapOptions
+): GridMap
+```
+
+**Options:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `allowDiagonal` | `boolean` | `true` | Allow diagonal movement |
+| `diagonalCost` | `number` | `√2` | Diagonal movement cost |
+| `avoidCorners` | `boolean` | `true` | Avoid corner cutting |
+| `heuristic` | `HeuristicFunction` | `octileDistance` | Heuristic function |
+
+### Map Operations
+
+```typescript
+// Check/set walkability
+grid.isWalkable(x, y);
+grid.setWalkable(x, y, false);
+
+// Set movement cost (e.g., swamp, sand)
+grid.setCost(x, y, 2);
+
+// Set rectangle region
+grid.setRectWalkable(0, 0, 5, 5, false);
+
+// Load from array (0=walkable, non-0=blocked)
+grid.loadFromArray([
+    [0, 0, 0, 1, 0],
+    [0, 1, 0, 1, 0]
+]);
+
+// Load from string (.=walkable, #=blocked)
+grid.loadFromString(`
+.....
+.#.#.
+`);
+
+// Export and reset
+console.log(grid.toString());
+grid.reset();
+```
+
+## A* Pathfinder API
+
+```typescript
+const pathfinder = createAStarPathfinder(grid);
+
+const result = pathfinder.findPath(
+    startX, startY,
+    endX, endY,
+    { maxNodes: 5000, heuristicWeight: 1.5 }
+);
+
+// Pathfinder is reusable
+pathfinder.findPath(0, 0, 10, 10);
+pathfinder.findPath(5, 5, 15, 15);
+```
+
+## NavMesh API
+
+```typescript
+const navmesh = createNavMesh();
+
+// Add convex polygons
+const id1 = navmesh.addPolygon(vertices1);
+const id2 = navmesh.addPolygon(vertices2);
+
+// Auto-detect shared edges
+navmesh.build();
+
+// Or manually set connections
+navmesh.setConnection(id1, id2, {
+    left: { x: 10, y: 0 },
+    right: { x: 10, y: 10 }
+});
+
+// Query and pathfind
+const polygon = navmesh.findPolygonAt(5, 5);
+navmesh.isWalkable(5, 5);
+const result = navmesh.findPath(1, 1, 18, 8);
+```
+
+## Path Smoothing
+
+### Line of Sight Smoothing
+
+Remove unnecessary waypoints:
+
+```typescript
+import { createLineOfSightSmoother } from '@esengine/pathfinding';
+
+const smoother = createLineOfSightSmoother();
+const smoothedPath = smoother.smooth(result.path, grid);
+```
+
+### Curve Smoothing
+
+Catmull-Rom spline:
+
+```typescript
+import { createCatmullRomSmoother } from '@esengine/pathfinding';
+
+const smoother = createCatmullRomSmoother(5, 0.5);
+const curvedPath = smoother.smooth(result.path, grid);
+```
+
+### Combined Smoothing
+
+```typescript
+import { createCombinedSmoother } from '@esengine/pathfinding';
+
+const smoother = createCombinedSmoother(5, 0.5);
+const finalPath = smoother.smooth(result.path, grid);
+```
+
+### Line of Sight Functions
+
+```typescript
+import { bresenhamLineOfSight, raycastLineOfSight } from '@esengine/pathfinding';
+
+const hasLOS = bresenhamLineOfSight(x1, y1, x2, y2, grid);
+const hasLOS2 = raycastLineOfSight(x1, y1, x2, y2, grid, 0.5);
+```
+
+## Practical Examples
+
+### Dynamic Obstacles
+
+```typescript
+class DynamicPathfinding {
+    private grid: GridMap;
+    private pathfinder: AStarPathfinder;
+    private dynamicObstacles: Set<string> = new Set();
+
+    addDynamicObstacle(x: number, y: number): void {
+        this.dynamicObstacles.add(`${x},${y}`);
+        this.grid.setWalkable(x, y, false);
+    }
+
+    removeDynamicObstacle(x: number, y: number): void {
+        this.dynamicObstacles.delete(`${x},${y}`);
+        this.grid.setWalkable(x, y, true);
+    }
+}
+```
+
+### Terrain Costs
+
+```typescript
+const grid = createGridMap(50, 50);
+
+// Normal ground - cost 1 (default)
+// Sand - cost 2
+for (let y = 10; y < 20; y++) {
+    for (let x = 0; x < 50; x++) {
+        grid.setCost(x, y, 2);
+    }
+}
+
+// Swamp - cost 4
+for (let y = 30; y < 35; y++) {
+    for (let x = 20; x < 30; x++) {
+        grid.setCost(x, y, 4);
+    }
+}
+```
+
+## Blueprint Nodes
+
+- `FindPath` - Find path
+- `FindPathSmooth` - Find and smooth path
+- `IsWalkable` - Check walkability
+- `GetPathLength` - Get path point count
+- `GetPathDistance` - Get total path distance
+- `GetPathPoint` - Get specific path point
+- `MoveAlongPath` - Move along path
+- `HasLineOfSight` - Check line of sight
+
+## Performance Tips
+
+1. **Limit search range**: `{ maxNodes: 1000 }`
+2. **Use heuristic weight**: `{ heuristicWeight: 1.5 }` (faster but may not be optimal)
+3. **Reuse pathfinder instances**
+4. **Use NavMesh for complex terrain**
+5. **Choose appropriate heuristic for movement type**
+
+## Grid vs NavMesh
+
+| Feature | GridMap | NavMesh |
+|---------|---------|---------|
+| Use Case | Regular tile maps | Complex polygon terrain |
+| Memory | Higher (width × height) | Lower (polygon count) |
+| Precision | Grid-aligned | Continuous coordinates |
+| Dynamic Updates | Easy | Requires rebuild |
+| Setup Complexity | Simple | More complex |

docs/en/modules/procgen/index.md

@@ -0,0 +1,396 @@
+# Procedural Generation (Procgen)
+
+`@esengine/procgen` provides core tools for procedural content generation, including noise functions, seeded random numbers, and various random utilities.
+
+## Installation
+
+```bash
+npm install @esengine/procgen
+```
+
+## Quick Start
+
+### Noise Generation
+
+```typescript
+import { createPerlinNoise, createFBM } from '@esengine/procgen';
+
+// Create Perlin noise
+const perlin = createPerlinNoise(12345); // seed
+
+// Sample 2D noise
+const value = perlin.noise2D(x * 0.1, y * 0.1);
+console.log(value); // [-1, 1]
+
+// Use FBM for more natural results
+const fbm = createFBM(perlin, {
+    octaves: 6,
+    persistence: 0.5
+});
+
+const height = fbm.noise2D(x * 0.01, y * 0.01);
+```
+
+### Seeded Random
+
+```typescript
+import { createSeededRandom } from '@esengine/procgen';
+
+// Create deterministic random generator
+const rng = createSeededRandom(42);
+
+// Same seed always produces same sequence
+console.log(rng.next());          // 0.xxx
+console.log(rng.nextInt(1, 100)); // 1-100
+console.log(rng.nextBool(0.3));   // 30% true
+```
+
+### Weighted Random
+
+```typescript
+import { createWeightedRandom, createSeededRandom } from '@esengine/procgen';
+
+const rng = createSeededRandom(42);
+
+const loot = createWeightedRandom([
+    { value: 'common',    weight: 60 },
+    { value: 'uncommon',  weight: 25 },
+    { value: 'rare',      weight: 10 },
+    { value: 'legendary', weight: 5 }
+]);
+
+const drop = loot.pick(rng);
+console.log(drop); // Likely 'common'
+```
+
+## Noise Functions
+
+### Perlin Noise
+
+Classic gradient noise, output range [-1, 1]:
+
+```typescript
+import { createPerlinNoise } from '@esengine/procgen';
+
+const perlin = createPerlinNoise(seed);
+const value2D = perlin.noise2D(x, y);
+const value3D = perlin.noise3D(x, y, z);
+```
+
+### Simplex Noise
+
+Faster than Perlin, less directional bias:
+
+```typescript
+import { createSimplexNoise } from '@esengine/procgen';
+
+const simplex = createSimplexNoise(seed);
+const value = simplex.noise2D(x, y);
+```
+
+### Worley Noise
+
+Cell-based noise for stone, cell textures:
+
+```typescript
+import { createWorleyNoise } from '@esengine/procgen';
+
+const worley = createWorleyNoise(seed);
+const distance = worley.noise2D(x, y);
+```
+
+### FBM (Fractal Brownian Motion)
+
+Layer multiple noise octaves for richer detail:
+
+```typescript
+import { createPerlinNoise, createFBM } from '@esengine/procgen';
+
+const baseNoise = createPerlinNoise(seed);
+
+const fbm = createFBM(baseNoise, {
+    octaves: 6,        // Layer count (more = richer detail)
+    lacunarity: 2.0,   // Frequency multiplier
+    persistence: 0.5,  // Amplitude decay
+    frequency: 1.0,    // Initial frequency
+    amplitude: 1.0     // Initial amplitude
+});
+
+// Standard FBM
+const value = fbm.noise2D(x, y);
+
+// Ridged FBM (for mountains)
+const ridged = fbm.ridged2D(x, y);
+
+// Turbulence
+const turb = fbm.turbulence2D(x, y);
+
+// Billowed (for clouds)
+const cloud = fbm.billowed2D(x, y);
+```
+
+## Seeded Random API
+
+### SeededRandom
+
+Deterministic PRNG based on xorshift128+:
+
+```typescript
+import { createSeededRandom } from '@esengine/procgen';
+
+const rng = createSeededRandom(42);
+```
+
+### Basic Methods
+
+```typescript
+rng.next();              // [0, 1) float
+rng.nextInt(1, 10);      // [min, max] integer
+rng.nextFloat(0, 100);   // [min, max) float
+rng.nextBool();          // 50%
+rng.nextBool(0.3);       // 30%
+rng.reset();             // Reset to initial state
+```
+
+### Distribution Methods
+
+```typescript
+// Normal distribution (Gaussian)
+rng.nextGaussian();          // mean 0, stdDev 1
+rng.nextGaussian(100, 15);   // mean 100, stdDev 15
+
+// Exponential distribution
+rng.nextExponential();       // λ = 1
+rng.nextExponential(0.5);    // λ = 0.5
+```
+
+### Geometry Methods
+
+```typescript
+// Uniform point in circle
+const point = rng.nextPointInCircle(50); // { x, y }
+
+// Point on circle edge
+const edge = rng.nextPointOnCircle(50);  // { x, y }
+
+// Uniform point in sphere
+const point3D = rng.nextPointInSphere(50); // { x, y, z }
+
+// Random direction vector
+const dir = rng.nextDirection2D(); // { x, y }, length 1
+```
+
+## Weighted Random API
+
+### WeightedRandom
+
+Precomputed cumulative weights for efficient selection:
+
+```typescript
+import { createWeightedRandom } from '@esengine/procgen';
+
+const selector = createWeightedRandom([
+    { value: 'apple',  weight: 5 },
+    { value: 'banana', weight: 3 },
+    { value: 'cherry', weight: 2 }
+]);
+
+const result = selector.pick(rng);
+const result2 = selector.pickRandom(); // Uses Math.random
+
+console.log(selector.getProbability(0)); // 0.5 (5/10)
+console.log(selector.size);              // 3
+console.log(selector.totalWeight);       // 10
+```
+
+### Convenience Functions
+
+```typescript
+import { weightedPick, weightedPickFromMap } from '@esengine/procgen';
+
+const item = weightedPick([
+    { value: 'a', weight: 1 },
+    { value: 'b', weight: 2 }
+], rng);
+
+const item2 = weightedPickFromMap({
+    'common': 60,
+    'rare': 30,
+    'epic': 10
+}, rng);
+```
+
+## Shuffle and Sampling
+
+### shuffle / shuffleCopy
+
+Fisher-Yates shuffle:
+
+```typescript
+import { shuffle, shuffleCopy } from '@esengine/procgen';
+
+const arr = [1, 2, 3, 4, 5];
+shuffle(arr, rng);           // In-place
+const shuffled = shuffleCopy(arr, rng); // Copy
+```
+
+### pickOne
+
+```typescript
+import { pickOne } from '@esengine/procgen';
+
+const item = pickOne(['a', 'b', 'c', 'd'], rng);
+```
+
+### sample / sampleWithReplacement
+
+```typescript
+import { sample, sampleWithReplacement } from '@esengine/procgen';
+
+const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+const unique = sample(arr, 3, rng);      // 3 unique
+const withRep = sampleWithReplacement(arr, 5, rng); // 5 with replacement
+```
+
+### randomIntegers
+
+```typescript
+import { randomIntegers } from '@esengine/procgen';
+
+// 5 unique random integers from 1-100
+const nums = randomIntegers(1, 100, 5, rng);
+```
+
+### weightedSample
+
+```typescript
+import { weightedSample } from '@esengine/procgen';
+
+const items = ['A', 'B', 'C', 'D', 'E'];
+const weights = [10, 8, 6, 4, 2];
+const selected = weightedSample(items, weights, 3, rng);
+```
+
+## Practical Examples
+
+### Procedural Terrain
+
+```typescript
+import { createPerlinNoise, createFBM } from '@esengine/procgen';
+
+class TerrainGenerator {
+    private fbm: FBM;
+    private moistureFbm: FBM;
+
+    constructor(seed: number) {
+        const heightNoise = createPerlinNoise(seed);
+        const moistureNoise = createPerlinNoise(seed + 1000);
+
+        this.fbm = createFBM(heightNoise, {
+            octaves: 8,
+            persistence: 0.5,
+            frequency: 0.01
+        });
+
+        this.moistureFbm = createFBM(moistureNoise, {
+            octaves: 4,
+            persistence: 0.6,
+            frequency: 0.02
+        });
+    }
+
+    getHeight(x: number, y: number): number {
+        let height = this.fbm.noise2D(x, y);
+        height += this.fbm.ridged2D(x * 0.5, y * 0.5) * 0.3;
+        return (height + 1) * 0.5; // Normalize to [0, 1]
+    }
+
+    getBiome(x: number, y: number): string {
+        const height = this.getHeight(x, y);
+        const moisture = (this.moistureFbm.noise2D(x, y) + 1) * 0.5;
+
+        if (height < 0.3) return 'water';
+        if (height < 0.4) return 'beach';
+        if (height > 0.8) return 'mountain';
+
+        if (moisture < 0.3) return 'desert';
+        if (moisture > 0.7) return 'forest';
+        return 'grassland';
+    }
+}
+```
+
+### Loot System
+
+```typescript
+import { createSeededRandom, createWeightedRandom } from '@esengine/procgen';
+
+class LootSystem {
+    private rng: SeededRandom;
+    private raritySelector: WeightedRandom<string>;
+
+    constructor(seed: number) {
+        this.rng = createSeededRandom(seed);
+        this.raritySelector = createWeightedRandom([
+            { value: 'common',    weight: 60 },
+            { value: 'uncommon',  weight: 25 },
+            { value: 'rare',      weight: 10 },
+            { value: 'legendary', weight: 5 }
+        ]);
+    }
+
+    generateLoot(count: number): LootItem[] {
+        const loot: LootItem[] = [];
+        for (let i = 0; i < count; i++) {
+            const rarity = this.raritySelector.pick(this.rng);
+            // Get item from rarity table...
+            loot.push(item);
+        }
+        return loot;
+    }
+}
+```
+
+## Blueprint Nodes
+
+### Noise Nodes
+- `SampleNoise2D` - Sample 2D noise
+- `SampleFBM` - Sample FBM noise
+
+### Random Nodes
+- `SeededRandom` - Generate random float
+- `SeededRandomInt` - Generate random integer
+- `WeightedPick` - Weighted random selection
+- `ShuffleArray` - Shuffle array
+- `PickRandom` - Pick random element
+- `SampleArray` - Sample from array
+- `RandomPointInCircle` - Random point in circle
+
+## Best Practices
+
+1. **Use seeds for reproducibility**
+   ```typescript
+   const seed = Date.now();
+   const rng = createSeededRandom(seed);
+   saveSeed(seed);
+   ```
+
+2. **Precompute weighted selectors**
+   ```typescript
+   // Good: Create once, use many times
+   const selector = createWeightedRandom(items);
+   for (let i = 0; i < 1000; i++) {
+       selector.pick(rng);
+   }
+   ```
+
+3. **Choose appropriate noise**
+   - Perlin: Smooth terrain, clouds
+   - Simplex: Performance-critical
+   - Worley: Cell textures, stone
+   - FBM: Natural multi-detail effects
+
+4. **Tune FBM parameters**
+   - `octaves`: More = richer detail, higher cost
+   - `persistence`: 0.5 is common, higher = more high-frequency detail
+   - `lacunarity`: Usually 2, controls frequency growth

docs/en/modules/spatial/index.md

@@ -0,0 +1,322 @@
+# Spatial Index System
+
+`@esengine/spatial` provides efficient spatial querying and indexing, including range queries, nearest neighbor queries, raycasting, and AOI (Area of Interest) management.
+
+## Installation
+
+```bash
+npm install @esengine/spatial
+```
+
+## Quick Start
+
+### Spatial Index
+
+```typescript
+import { createGridSpatialIndex } from '@esengine/spatial';
+
+// Create spatial index (cell size 100)
+const spatialIndex = createGridSpatialIndex<Entity>(100);
+
+// Insert objects
+spatialIndex.insert(player, { x: 100, y: 200 });
+spatialIndex.insert(enemy1, { x: 150, y: 250 });
+spatialIndex.insert(enemy2, { x: 500, y: 600 });
+
+// Find objects within radius
+const nearby = spatialIndex.findInRadius({ x: 100, y: 200 }, 100);
+console.log(nearby); // [player, enemy1]
+
+// Find nearest object
+const nearest = spatialIndex.findNearest({ x: 100, y: 200 });
+console.log(nearest); // enemy1
+
+// Update position
+spatialIndex.update(player, { x: 120, y: 220 });
+```
+
+### AOI (Area of Interest)
+
+```typescript
+import { createGridAOI } from '@esengine/spatial';
+
+// Create AOI manager
+const aoi = createGridAOI<Entity>(100);
+
+// Add observers
+aoi.addObserver(player, { x: 100, y: 100 }, { viewRange: 200 });
+aoi.addObserver(npc, { x: 150, y: 150 }, { viewRange: 150 });
+
+// Listen to enter/exit events
+aoi.addListener((event) => {
+    if (event.type === 'enter') {
+        console.log(`${event.observer} saw ${event.target}`);
+    } else if (event.type === 'exit') {
+        console.log(`${event.target} left ${event.observer}'s view`);
+    }
+});
+
+// Update position (triggers enter/exit events)
+aoi.updatePosition(player, { x: 200, y: 200 });
+
+// Get visible entities
+const visible = aoi.getEntitiesInView(player);
+```
+
+## Core Concepts
+
+### Spatial Index vs AOI
+
+| Feature | SpatialIndex | AOI |
+|---------|--------------|-----|
+| Purpose | General spatial queries | Entity visibility tracking |
+| Events | No event notification | Enter/exit events |
+| Direction | One-way query | Two-way tracking |
+| Use Cases | Collision, range attacks | MMO sync, NPC AI perception |
+
+### IBounds
+
+```typescript
+interface IBounds {
+    readonly minX: number;
+    readonly minY: number;
+    readonly maxX: number;
+    readonly maxY: number;
+}
+```
+
+### IRaycastHit
+
+```typescript
+interface IRaycastHit<T> {
+    readonly target: T;       // Hit object
+    readonly point: IVector2; // Hit point
+    readonly normal: IVector2;// Hit normal
+    readonly distance: number;// Distance from origin
+}
+```
+
+## Spatial Index API
+
+### createGridSpatialIndex
+
+```typescript
+function createGridSpatialIndex<T>(cellSize?: number): GridSpatialIndex<T>
+```
+
+**Choosing cellSize:**
+- Too small: High memory, reduced query efficiency
+- Too large: Many objects per cell, slow iteration
+- Recommended: 1-2x average object spacing
+
+### Management Methods
+
+```typescript
+spatialIndex.insert(entity, position);
+spatialIndex.remove(entity);
+spatialIndex.update(entity, newPosition);
+spatialIndex.clear();
+```
+
+### Query Methods
+
+#### findInRadius
+
+```typescript
+const enemies = spatialIndex.findInRadius(
+    { x: 100, y: 200 },
+    50,
+    (entity) => entity.type === 'enemy' // Optional filter
+);
+```
+
+#### findInRect
+
+```typescript
+import { createBounds } from '@esengine/spatial';
+
+const bounds = createBounds(0, 0, 200, 200);
+const entities = spatialIndex.findInRect(bounds);
+```
+
+#### findNearest
+
+```typescript
+const nearest = spatialIndex.findNearest(
+    playerPosition,
+    500, // maxDistance
+    (entity) => entity.type === 'enemy'
+);
+```
+
+#### findKNearest
+
+```typescript
+const nearestEnemies = spatialIndex.findKNearest(
+    playerPosition,
+    5,    // k
+    500,  // maxDistance
+    (entity) => entity.type === 'enemy'
+);
+```
+
+#### raycast / raycastFirst
+
+```typescript
+const hits = spatialIndex.raycast(origin, direction, maxDistance);
+const firstHit = spatialIndex.raycastFirst(origin, direction, maxDistance);
+```
+
+## AOI API
+
+### createGridAOI
+
+```typescript
+function createGridAOI<T>(cellSize?: number): GridAOI<T>
+```
+
+### Observer Management
+
+```typescript
+// Add observer
+aoi.addObserver(player, position, {
+    viewRange: 200,
+    observable: true  // Can be seen by others
+});
+
+// Remove observer
+aoi.removeObserver(player);
+
+// Update position
+aoi.updatePosition(player, newPosition);
+
+// Update view range
+aoi.updateViewRange(player, 300);
+```
+
+### Query Methods
+
+```typescript
+// Get entities in observer's view
+const visible = aoi.getEntitiesInView(player);
+
+// Get observers who can see entity
+const observers = aoi.getObserversOf(monster);
+
+// Check visibility
+if (aoi.canSee(player, enemy)) { ... }
+```
+
+### Event System
+
+```typescript
+// Global event listener
+aoi.addListener((event) => {
+    switch (event.type) {
+        case 'enter': /* entered view */ break;
+        case 'exit': /* left view */ break;
+    }
+});
+
+// Entity-specific listener
+aoi.addEntityListener(player, (event) => {
+    if (event.type === 'enter') {
+        sendToClient(player, 'entity_enter', event.target);
+    }
+});
+```
+
+## Utility Functions
+
+### Bounds Creation
+
+```typescript
+import {
+    createBounds,
+    createBoundsFromCenter,
+    createBoundsFromCircle
+} from '@esengine/spatial';
+
+const bounds1 = createBounds(0, 0, 100, 100);
+const bounds2 = createBoundsFromCenter({ x: 50, y: 50 }, 100, 100);
+const bounds3 = createBoundsFromCircle({ x: 50, y: 50 }, 50);
+```
+
+### Geometry Checks
+
+```typescript
+import {
+    isPointInBounds,
+    boundsIntersect,
+    boundsIntersectsCircle,
+    distance,
+    distanceSquared
+} from '@esengine/spatial';
+
+if (isPointInBounds(point, bounds)) { ... }
+if (boundsIntersect(boundsA, boundsB)) { ... }
+if (boundsIntersectsCircle(bounds, center, radius)) { ... }
+const dist = distance(pointA, pointB);
+const distSq = distanceSquared(pointA, pointB); // Faster
+```
+
+## Practical Examples
+
+### Range Attack Detection
+
+```typescript
+class CombatSystem {
+    private spatialIndex: ISpatialIndex<Entity>;
+
+    dealAreaDamage(center: IVector2, radius: number, damage: number): void {
+        const targets = this.spatialIndex.findInRadius(
+            center, radius,
+            (entity) => entity.hasComponent(HealthComponent)
+        );
+
+        for (const target of targets) {
+            target.getComponent(HealthComponent).takeDamage(damage);
+        }
+    }
+}
+```
+
+### MMO Sync System
+
+```typescript
+class SyncSystem {
+    private aoi: IAOIManager<Player>;
+
+    constructor() {
+        this.aoi = createGridAOI<Player>(100);
+
+        this.aoi.addListener((event) => {
+            const packet = this.createSyncPacket(event);
+            this.sendToPlayer(event.observer, packet);
+        });
+    }
+
+    onPlayerMove(player: Player, newPosition: IVector2): void {
+        this.aoi.updatePosition(player, newPosition);
+    }
+}
+```
+
+## Blueprint Nodes
+
+### Spatial Query Nodes
+- `FindInRadius`, `FindInRect`, `FindNearest`, `FindKNearest`
+- `Raycast`, `RaycastFirst`
+
+### AOI Nodes
+- `GetEntitiesInView`, `GetObserversOf`, `CanSee`
+- `OnEntityEnterView`, `OnEntityExitView`
+
+## Service Tokens
+
+```typescript
+import { SpatialIndexToken, AOIManagerToken } from '@esengine/spatial';
+
+services.register(SpatialIndexToken, createGridSpatialIndex(100));
+services.register(AOIManagerToken, createGridAOI(100));
+```

docs/en/modules/timer/index.md

@@ -0,0 +1,352 @@
+# Timer System
+
+`@esengine/timer` provides a flexible timer and cooldown system for delayed execution, repeating tasks, skill cooldowns, and more.
+
+## Installation
+
+```bash
+npm install @esengine/timer
+```
+
+## Quick Start
+
+```typescript
+import { createTimerService } from '@esengine/timer';
+
+// Create timer service
+const timerService = createTimerService();
+
+// One-time timer (executes after 1 second)
+const handle = timerService.schedule('myTimer', 1000, () => {
+    console.log('Timer fired!');
+});
+
+// Repeating timer (every 100ms)
+timerService.scheduleRepeating('heartbeat', 100, () => {
+    console.log('Tick');
+});
+
+// Cooldown system (5 second cooldown)
+timerService.startCooldown('skill_fireball', 5000);
+
+if (timerService.isCooldownReady('skill_fireball')) {
+    useFireball();
+    timerService.startCooldown('skill_fireball', 5000);
+}
+
+// Update in game loop
+function gameLoop(deltaTime: number) {
+    timerService.update(deltaTime);
+}
+```
+
+## Core Concepts
+
+### Timer vs Cooldown
+
+| Feature | Timer | Cooldown |
+|---------|-------|----------|
+| Purpose | Delayed code execution | Rate limiting |
+| Callback | Has callback function | No callback |
+| Repeat | Supports repeating | One-time |
+| Query | Query remaining time | Query progress/ready status |
+
+### TimerHandle
+
+Handle object returned when scheduling a timer:
+
+```typescript
+interface TimerHandle {
+    readonly id: string;       // Timer ID
+    readonly isValid: boolean; // Whether valid (not cancelled)
+    cancel(): void;            // Cancel timer
+}
+```
+
+### TimerInfo
+
+Timer information object:
+
+```typescript
+interface TimerInfo {
+    readonly id: string;         // Timer ID
+    readonly remaining: number;  // Remaining time (ms)
+    readonly repeating: boolean; // Whether repeating
+    readonly interval?: number;  // Interval (repeating only)
+}
+```
+
+### CooldownInfo
+
+Cooldown information object:
+
+```typescript
+interface CooldownInfo {
+    readonly id: string;        // Cooldown ID
+    readonly duration: number;  // Total duration (ms)
+    readonly remaining: number; // Remaining time (ms)
+    readonly progress: number;  // Progress (0-1, 0=started, 1=finished)
+    readonly isReady: boolean;  // Whether ready
+}
+```
+
+## API Reference
+
+### createTimerService
+
+```typescript
+function createTimerService(config?: TimerServiceConfig): ITimerService
+```
+
+**Configuration:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `maxTimers` | `number` | `0` | Maximum timer count (0 = unlimited) |
+| `maxCooldowns` | `number` | `0` | Maximum cooldown count (0 = unlimited) |
+
+### Timer API
+
+#### schedule
+
+Schedule a one-time timer:
+
+```typescript
+const handle = timerService.schedule('explosion', 2000, () => {
+    createExplosion();
+});
+
+// Cancel early
+handle.cancel();
+```
+
+#### scheduleRepeating
+
+Schedule a repeating timer:
+
+```typescript
+// Execute every second
+timerService.scheduleRepeating('regen', 1000, () => {
+    player.hp += 5;
+});
+
+// Execute immediately once, then repeat every second
+timerService.scheduleRepeating('tick', 1000, () => {
+    console.log('Tick');
+}, true); // immediate = true
+```
+
+#### cancel / cancelById
+
+Cancel timers:
+
+```typescript
+// Cancel by handle
+handle.cancel();
+// or
+timerService.cancel(handle);
+
+// Cancel by ID
+timerService.cancelById('regen');
+```
+
+#### hasTimer
+
+Check if timer exists:
+
+```typescript
+if (timerService.hasTimer('explosion')) {
+    console.log('Explosion is pending');
+}
+```
+
+#### getTimerInfo
+
+Get timer information:
+
+```typescript
+const info = timerService.getTimerInfo('explosion');
+if (info) {
+    console.log(`Remaining: ${info.remaining}ms`);
+    console.log(`Repeating: ${info.repeating}`);
+}
+```
+
+### Cooldown API
+
+#### startCooldown
+
+Start a cooldown:
+
+```typescript
+timerService.startCooldown('skill_fireball', 5000);
+```
+
+#### isCooldownReady / isOnCooldown
+
+Check cooldown status:
+
+```typescript
+if (timerService.isCooldownReady('skill_fireball')) {
+    castFireball();
+    timerService.startCooldown('skill_fireball', 5000);
+}
+
+if (timerService.isOnCooldown('skill_fireball')) {
+    console.log('On cooldown...');
+}
+```
+
+#### getCooldownProgress / getCooldownRemaining
+
+Get cooldown progress:
+
+```typescript
+// Progress 0-1 (0=started, 1=complete)
+const progress = timerService.getCooldownProgress('skill_fireball');
+console.log(`Progress: ${(progress * 100).toFixed(0)}%`);
+
+// Remaining time (ms)
+const remaining = timerService.getCooldownRemaining('skill_fireball');
+console.log(`Remaining: ${(remaining / 1000).toFixed(1)}s`);
+```
+
+#### getCooldownInfo
+
+Get complete cooldown info:
+
+```typescript
+const info = timerService.getCooldownInfo('skill_fireball');
+if (info) {
+    console.log(`Duration: ${info.duration}ms`);
+    console.log(`Remaining: ${info.remaining}ms`);
+    console.log(`Progress: ${info.progress}`);
+    console.log(`Ready: ${info.isReady}`);
+}
+```
+
+#### resetCooldown / clearAllCooldowns
+
+Reset cooldowns:
+
+```typescript
+// Reset single cooldown
+timerService.resetCooldown('skill_fireball');
+
+// Clear all cooldowns (e.g., on respawn)
+timerService.clearAllCooldowns();
+```
+
+### Lifecycle
+
+#### update
+
+Update timer service (call every frame):
+
+```typescript
+function gameLoop(deltaTime: number) {
+    timerService.update(deltaTime); // deltaTime in ms
+}
+```
+
+#### clear
+
+Clear all timers and cooldowns:
+
+```typescript
+timerService.clear();
+```
+
+### Debug Properties
+
+```typescript
+console.log(timerService.activeTimerCount);
+console.log(timerService.activeCooldownCount);
+const timerIds = timerService.getActiveTimerIds();
+const cooldownIds = timerService.getActiveCooldownIds();
+```
+
+## Practical Examples
+
+### Skill Cooldown System
+
+```typescript
+import { createTimerService, type ITimerService } from '@esengine/timer';
+
+class SkillSystem {
+    private timerService: ITimerService;
+    private skills: Map<string, SkillData> = new Map();
+
+    constructor() {
+        this.timerService = createTimerService();
+    }
+
+    useSkill(skillId: string): boolean {
+        const skill = this.skills.get(skillId);
+        if (!skill) return false;
+
+        if (!this.timerService.isCooldownReady(skillId)) {
+            const remaining = this.timerService.getCooldownRemaining(skillId);
+            console.log(`Skill ${skillId} on cooldown, ${remaining}ms remaining`);
+            return false;
+        }
+
+        this.executeSkill(skill);
+        this.timerService.startCooldown(skillId, skill.cooldown);
+        return true;
+    }
+
+    update(dt: number): void {
+        this.timerService.update(dt);
+    }
+}
+```
+
+### DOT Effects
+
+```typescript
+class EffectSystem {
+    private timerService: ITimerService;
+
+    applyDOT(target: Entity, damage: number, duration: number): void {
+        const dotId = `dot_${target.id}_${Date.now()}`;
+        let elapsed = 0;
+
+        this.timerService.scheduleRepeating(dotId, 1000, () => {
+            elapsed += 1000;
+            target.takeDamage(damage);
+
+            if (elapsed >= duration) {
+                this.timerService.cancelById(dotId);
+            }
+        });
+    }
+}
+```
+
+## Blueprint Nodes
+
+### Cooldown Nodes
+
+- `StartCooldown` - Start cooldown
+- `IsCooldownReady` - Check if cooldown is ready
+- `GetCooldownProgress` - Get cooldown progress
+- `GetCooldownInfo` - Get cooldown info
+- `ResetCooldown` - Reset cooldown
+
+### Timer Nodes
+
+- `HasTimer` - Check if timer exists
+- `CancelTimer` - Cancel timer
+- `GetTimerRemaining` - Get timer remaining time
+
+## Service Token
+
+For dependency injection:
+
+```typescript
+import { TimerServiceToken, createTimerService } from '@esengine/timer';
+
+services.register(TimerServiceToken, createTimerService());
+const timerService = services.get(TimerServiceToken);
+```

docs/guide/component.md

@@ -55,25 +55,92 @@ class Health extends Component {
 }
 ```
 
-### 组件装饰器
+### @ECSComponent 装饰器
 
-**必须使用 `@ECSComponent` 装饰器**，这确保了：
-- 组件在代码混淆后仍能正确识别
-- 提供稳定的类型名称用于序列化和调试
-- 框架能正确管理组件注册
+`@ECSComponent` 是组件类必须使用的装饰器，它为组件提供了类型标识和元数据管理。
+
+#### 为什么必须使用
+
+| 功能 | 说明 |
+|------|------|
+| **类型识别** | 提供稳定的类型名称，代码混淆后仍能正确识别 |
+| **序列化支持** | 序列化/反序列化时使用该名称作为类型标识 |
+| **组件注册** | 自动注册到 ComponentRegistry，分配唯一的位掩码 |
+| **调试支持** | 在调试工具和日志中显示可读的组件名称 |
+
+#### 基本语法
 
 ```typescript
-// 正确的用法
+@ECSComponent(typeName: string)
+```
+
+- `typeName`: 组件的类型名称，建议使用与类名相同或相近的名称
+
+#### 使用示例
+
+```typescript
+// ✅ 正确的用法
 @ECSComponent('Velocity')
 class Velocity extends Component {
   dx: number = 0;
   dy: number = 0;
 }
 
-// 错误的用法 - 没有装饰器
-class BadComponent extends Component {
-  // 这样定义的组件可能在生产环境出现问题
+// ✅ 推荐：类型名与类名保持一致
+@ECSComponent('PlayerController')
+class PlayerController extends Component {
+  speed: number = 5;
 }
+
+// ❌ 错误的用法 - 没有装饰器
+class BadComponent extends Component {
+  // 这样定义的组件可能在生产环境出现问题：
+  // 1. 代码压缩后类名变化，无法正确序列化
+  // 2. 组件未注册到框架，查询和匹配可能失效
+}
+```
+
+#### 与 @Serializable 配合使用
+
+当组件需要支持序列化时，`@ECSComponent` 和 `@Serializable` 需要一起使用：
+
+```typescript
+import { Component, ECSComponent, Serializable, Serialize } from '@esengine/ecs-framework';
+
+@ECSComponent('Player')
+@Serializable({ version: 1 })
+class PlayerComponent extends Component {
+  @Serialize()
+  name: string = '';
+
+  @Serialize()
+  level: number = 1;
+
+  // 不使用 @Serialize() 的字段不会被序列化
+  private _cachedData: any = null;
+}
+```
+
+> **注意**：`@ECSComponent` 的 `typeName` 和 `@Serializable` 的 `typeId` 可以不同。如果 `@Serializable` 没有指定 `typeId`，则默认使用 `@ECSComponent` 的 `typeName`。
+
+#### 组件类型名的唯一性
+
+每个组件的类型名应该是唯一的：
+
+```typescript
+// ❌ 错误：两个组件使用相同的类型名
+@ECSComponent('Health')
+class HealthComponent extends Component { }
+
+@ECSComponent('Health')  // 冲突！
+class EnemyHealthComponent extends Component { }
+
+// ✅ 正确：使用不同的类型名
+@ECSComponent('PlayerHealth')
+class PlayerHealthComponent extends Component { }
+
+@ECSComponent('EnemyHealth')
+class EnemyHealthComponent extends Component { }
 ```
 
 ## 组件生命周期

docs/guide/entity-query.md

@@ -0,0 +1,750 @@
+# 实体查询系统
+
+实体查询是 ECS 架构的核心功能之一。本指南将介绍如何使用 Matcher 和 QuerySystem 来查询和筛选实体。
+
+## 核心概念
+
+### Matcher - 查询条件描述符
+
+Matcher 是一个链式 API,用于描述实体查询条件。它本身不执行查询,而是作为条件传递给 EntitySystem 或 QuerySystem。
+
+### QuerySystem - 查询执行引擎
+
+QuerySystem 负责实际执行查询,内部使用响应式查询机制自动优化性能。
+
+## 在 EntitySystem 中使用 Matcher
+
+这是最常见的使用方式。EntitySystem 通过 Matcher 自动筛选和处理符合条件的实体。
+
+### 基础用法
+
+```typescript
+import { EntitySystem, Matcher, Entity, Component } from '@esengine/ecs-framework';
+
+class PositionComponent extends Component {
+    public x: number = 0;
+    public y: number = 0;
+}
+
+class VelocityComponent extends Component {
+    public vx: number = 0;
+    public vy: number = 0;
+}
+
+class MovementSystem extends EntitySystem {
+    constructor() {
+        // 方式1: 使用 Matcher.empty().all()
+        super(Matcher.empty().all(PositionComponent, VelocityComponent));
+
+        // 方式2: 直接使用 Matcher.all() (等价)
+        // super(Matcher.all(PositionComponent, VelocityComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        for (const entity of entities) {
+            const pos = entity.getComponent(PositionComponent)!;
+            const vel = entity.getComponent(VelocityComponent)!;
+
+            pos.x += vel.vx;
+            pos.y += vel.vy;
+        }
+    }
+}
+
+// 添加到场景
+scene.addEntityProcessor(new MovementSystem());
+```
+
+### Matcher 链式 API
+
+#### all() - 必须包含所有组件
+
+```typescript
+class HealthSystem extends EntitySystem {
+    constructor() {
+        // 实体必须同时拥有 Health 和 Position 组件
+        super(Matcher.empty().all(HealthComponent, PositionComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理同时拥有两个组件的实体
+    }
+}
+```
+
+#### any() - 至少包含一个组件
+
+```typescript
+class DamageableSystem extends EntitySystem {
+    constructor() {
+        // 实体至少拥有 Health 或 Shield 其中之一
+        super(Matcher.any(HealthComponent, ShieldComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 处理拥有生命值或护盾的实体
+    }
+}
+```
+
+#### none() - 不能包含指定组件
+
+```typescript
+class AliveEntitySystem extends EntitySystem {
+    constructor() {
+        // 实体不能拥有 DeadTag 组件
+        super(Matcher.all(HealthComponent).none(DeadTag));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理活着的实体
+    }
+}
+```
+
+#### 组合条件
+
+```typescript
+class CombatSystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(PositionComponent, HealthComponent)  // 必须有位置和生命
+                .any(WeaponComponent, MagicComponent)      // 至少有武器或魔法
+                .none(DeadTag, FrozenTag)                  // 不能是死亡或冰冻状态
+        );
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 处理可以战斗的活着的实体
+    }
+}
+```
+
+#### nothing() - 不匹配任何实体
+
+用于创建只需要生命周期方法（`onBegin`、`onEnd`）但不需要处理实体的系统。
+
+```typescript
+class FrameTimerSystem extends EntitySystem {
+    constructor() {
+        // 不匹配任何实体
+        super(Matcher.nothing());
+    }
+
+    protected onBegin(): void {
+        // 每帧开始时执行
+        Performance.markFrameStart();
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 永远不会被调用，因为没有匹配的实体
+    }
+
+    protected onEnd(): void {
+        // 每帧结束时执行
+        Performance.markFrameEnd();
+    }
+}
+```
+
+#### empty() vs nothing() 的区别
+
+| 方法 | 行为 | 使用场景 |
+|------|------|----------|
+| `Matcher.empty()` | 匹配**所有**实体 | 需要处理场景中所有实体 |
+| `Matcher.nothing()` | 不匹配**任何**实体 | 只需要生命周期回调，不处理实体 |
+
+```typescript
+// empty() - 返回场景中的所有实体
+class AllEntitiesSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty());
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // entities 包含场景中的所有实体
+        console.log(`场景中共有 ${entities.length} 个实体`);
+    }
+}
+
+// nothing() - 不返回任何实体
+class NoEntitiesSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.nothing());
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // entities 永远是空数组，此方法不会被调用
+    }
+}
+```
+
+### 按标签查询
+
+```typescript
+class PlayerSystem extends EntitySystem {
+    constructor() {
+        // 查询特定标签的实体
+        super(Matcher.empty().withTag(Tags.PLAYER));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理玩家实体
+    }
+}
+```
+
+### 按名称查询
+
+```typescript
+class BossSystem extends EntitySystem {
+    constructor() {
+        // 查询特定名称的实体
+        super(Matcher.empty().withName('Boss'));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理名为 'Boss' 的实体
+    }
+}
+```
+
+## 直接使用 QuerySystem
+
+如果不需要创建系统,可以直接使用 Scene 的 querySystem 进行查询。
+
+### 基础查询方法
+
+```typescript
+// 获取场景的查询系统
+const querySystem = scene.querySystem;
+
+// 查询拥有所有指定组件的实体
+const result1 = querySystem.queryAll(PositionComponent, VelocityComponent);
+console.log(`找到 ${result1.count} 个移动实体`);
+console.log(`查询耗时: ${result1.executionTime.toFixed(2)}ms`);
+
+// 查询拥有任意指定组件的实体
+const result2 = querySystem.queryAny(WeaponComponent, MagicComponent);
+console.log(`找到 ${result2.count} 个战斗单位`);
+
+// 查询不包含指定组件的实体
+const result3 = querySystem.queryNone(DeadTag);
+console.log(`找到 ${result3.count} 个活着的实体`);
+```
+
+### 按标签查询
+
+```typescript
+const playerResult = querySystem.queryByTag(Tags.PLAYER);
+for (const player of playerResult.entities) {
+    console.log('玩家:', player.name);
+}
+```
+
+### 按名称查询
+
+```typescript
+const bossResult = querySystem.queryByName('Boss');
+if (bossResult.count > 0) {
+    const boss = bossResult.entities[0];
+    console.log('找到Boss:', boss);
+}
+```
+
+### 按单个组件查询
+
+```typescript
+const healthResult = querySystem.queryByComponent(HealthComponent);
+console.log(`有 ${healthResult.count} 个实体拥有生命值`);
+```
+
+## 性能优化
+
+### 自动缓存
+
+QuerySystem 内部使用响应式查询自动缓存结果,相同的查询条件会直接使用缓存:
+
+```typescript
+// 第一次查询,执行实际查询
+const result1 = querySystem.queryAll(PositionComponent);
+console.log('fromCache:', result1.fromCache); // false
+
+// 第二次相同查询,使用缓存
+const result2 = querySystem.queryAll(PositionComponent);
+console.log('fromCache:', result2.fromCache); // true
+```
+
+### 实体变化自动更新
+
+当实体添加/移除组件时,查询缓存会自动更新:
+
+```typescript
+// 查询拥有武器的实体
+const before = querySystem.queryAll(WeaponComponent);
+console.log('之前:', before.count); // 假设为 5
+
+// 给实体添加武器
+const enemy = scene.createEntity('Enemy');
+enemy.addComponent(new WeaponComponent());
+
+// 再次查询,自动包含新实体
+const after = querySystem.queryAll(WeaponComponent);
+console.log('之后:', after.count); // 现在是 6
+```
+
+### 查询性能统计
+
+```typescript
+const stats = querySystem.getStats();
+console.log('总查询次数:', stats.queryStats.totalQueries);
+console.log('缓存命中率:', stats.queryStats.cacheHitRate);
+console.log('缓存大小:', stats.cacheStats.size);
+```
+
+## 实际应用场景
+
+### 场景1: 物理系统
+
+```typescript
+class PhysicsSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(TransformComponent, RigidbodyComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        for (const entity of entities) {
+            const transform = entity.getComponent(TransformComponent)!;
+            const rigidbody = entity.getComponent(RigidbodyComponent)!;
+
+            // 应用重力
+            rigidbody.velocity.y -= 9.8 * Time.deltaTime;
+
+            // 更新位置
+            transform.position.x += rigidbody.velocity.x * Time.deltaTime;
+            transform.position.y += rigidbody.velocity.y * Time.deltaTime;
+        }
+    }
+}
+```
+
+### 场景2: 渲染系统
+
+```typescript
+class RenderSystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(TransformComponent, SpriteComponent)
+                .none(InvisibleTag)  // 排除不可见实体
+        );
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 按 z-order 排序
+        const sorted = entities.slice().sort((a, b) => {
+            const zA = a.getComponent(TransformComponent)!.z;
+            const zB = b.getComponent(TransformComponent)!.z;
+            return zA - zB;
+        });
+
+        // 渲染实体
+        for (const entity of sorted) {
+            const transform = entity.getComponent(TransformComponent)!;
+            const sprite = entity.getComponent(SpriteComponent)!;
+
+            renderer.drawSprite(sprite.texture, transform.position);
+        }
+    }
+}
+```
+
+### 场景3: 碰撞检测
+
+```typescript
+class CollisionSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(TransformComponent, ColliderComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 简单的 O(n²) 碰撞检测
+        for (let i = 0; i < entities.length; i++) {
+            for (let j = i + 1; j < entities.length; j++) {
+                this.checkCollision(entities[i], entities[j]);
+            }
+        }
+    }
+
+    private checkCollision(a: Entity, b: Entity): void {
+        const transA = a.getComponent(TransformComponent)!;
+        const transB = b.getComponent(TransformComponent)!;
+        const colliderA = a.getComponent(ColliderComponent)!;
+        const colliderB = b.getComponent(ColliderComponent)!;
+
+        if (this.isOverlapping(transA, colliderA, transB, colliderB)) {
+            // 触发碰撞事件
+            scene.eventSystem.emit('collision', { entityA: a, entityB: b });
+        }
+    }
+
+    private isOverlapping(...args: any[]): boolean {
+        // 碰撞检测逻辑
+        return false;
+    }
+}
+```
+
+### 场景4: 一次性查询
+
+```typescript
+// 在系统外部执行一次性查询
+class GameManager {
+    private scene: Scene;
+
+    public countEnemies(): number {
+        const result = this.scene.querySystem.queryByTag(Tags.ENEMY);
+        return result.count;
+    }
+
+    public findNearestEnemy(playerPos: Vector2): Entity | null {
+        const enemies = this.scene.querySystem.queryByTag(Tags.ENEMY);
+
+        let nearest: Entity | null = null;
+        let minDistance = Infinity;
+
+        for (const enemy of enemies.entities) {
+            const transform = enemy.getComponent(TransformComponent);
+            if (!transform) continue;
+
+            const distance = Vector2.distance(playerPos, transform.position);
+            if (distance < minDistance) {
+                minDistance = distance;
+                nearest = enemy;
+            }
+        }
+
+        return nearest;
+    }
+}
+```
+
+## 编译查询 (CompiledQuery)
+
+> **v2.4.0+**
+
+CompiledQuery 是一个轻量级的查询工具，提供类型安全的组件访问和变更检测支持。适合临时查询、工具开发和简单的迭代场景。
+
+### 基本用法
+
+```typescript
+// 创建编译查询
+const query = scene.querySystem.compile(Position, Velocity);
+
+// 类型安全的遍历 - 组件参数自动推断类型
+query.forEach((entity, pos, vel) => {
+    pos.x += vel.vx * deltaTime;
+    pos.y += vel.vy * deltaTime;
+});
+
+// 获取实体数量
+console.log(`匹配实体数: ${query.count}`);
+
+// 获取第一个匹配的实体
+const first = query.first();
+if (first) {
+    const [entity, pos, vel] = first;
+    console.log(`第一个实体: ${entity.name}`);
+}
+```
+
+### 变更检测
+
+CompiledQuery 支持基于 epoch 的变更检测：
+
+```typescript
+class RenderSystem extends EntitySystem {
+    private _query: CompiledQuery<[typeof Transform, typeof Sprite]>;
+    private _lastEpoch = 0;
+
+    protected onInitialize(): void {
+        this._query = this.scene!.querySystem.compile(Transform, Sprite);
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理 Transform 或 Sprite 发生变化的实体
+        this._query.forEachChanged(this._lastEpoch, (entity, transform, sprite) => {
+            this.updateRenderData(entity, transform, sprite);
+        });
+
+        // 保存当前 epoch 作为下次检查的起点
+        this._lastEpoch = this.scene!.epochManager.current;
+    }
+
+    private updateRenderData(entity: Entity, transform: Transform, sprite: Sprite): void {
+        // 更新渲染数据
+    }
+}
+```
+
+### 函数式 API
+
+CompiledQuery 提供了丰富的函数式 API：
+
+```typescript
+const query = scene.querySystem.compile(Position, Health);
+
+// map - 转换实体数据
+const positions = query.map((entity, pos, health) => ({
+    x: pos.x,
+    y: pos.y,
+    healthPercent: health.current / health.max
+}));
+
+// filter - 过滤实体
+const lowHealthEntities = query.filter((entity, pos, health) => {
+    return health.current < health.max * 0.2;
+});
+
+// find - 查找第一个匹配的实体
+const target = query.find((entity, pos, health) => {
+    return health.current > 0 && pos.x > 100;
+});
+
+// toArray - 转换为数组
+const allData = query.toArray();
+for (const [entity, pos, health] of allData) {
+    console.log(`${entity.name}: ${pos.x}, ${pos.y}`);
+}
+
+// any/empty - 检查是否有匹配
+if (query.any()) {
+    console.log('有匹配的实体');
+}
+if (query.empty()) {
+    console.log('没有匹配的实体');
+}
+```
+
+### CompiledQuery vs EntitySystem
+
+| 特性 | CompiledQuery | EntitySystem |
+|------|---------------|--------------|
+| **用途** | 轻量级查询工具 | 完整的系统逻辑 |
+| **生命周期** | 无 | 完整 (onInitialize, onDestroy 等) |
+| **调度集成** | 无 | 支持 @Stage, @Before, @After |
+| **变更检测** | forEachChanged | forEachChanged |
+| **事件监听** | 无 | addEventListener |
+| **命令缓冲** | 无 | this.commands |
+| **类型安全组件** | forEach 参数自动推断 | 需要手动 getComponent |
+| **适用场景** | 临时查询、工具、原型 | 核心游戏逻辑 |
+
+**选择建议**：
+
+- 使用 **EntitySystem** 处理核心游戏逻辑（移动、战斗、AI 等）
+- 使用 **CompiledQuery** 进行一次性查询、工具开发或简单迭代
+
+### CompiledQuery API 参考
+
+| 方法 | 说明 |
+|------|------|
+| `forEach(callback)` | 遍历所有匹配实体，类型安全的组件参数 |
+| `forEachChanged(sinceEpoch, callback)` | 只遍历变更的实体 |
+| `first()` | 获取第一个匹配的实体和组件 |
+| `toArray()` | 转换为 [entity, ...components] 数组 |
+| `map(callback)` | 映射转换 |
+| `filter(predicate)` | 过滤实体 |
+| `find(predicate)` | 查找第一个满足条件的实体 |
+| `any()` | 是否有任何匹配 |
+| `empty()` | 是否没有匹配 |
+| `count` | 匹配的实体数量 |
+| `entities` | 匹配的实体列表（只读） |
+
+## 最佳实践
+
+### 1. 优先使用 EntitySystem
+
+```typescript
+// 推荐: 使用 EntitySystem
+class GoodSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(HealthComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 自动获得符合条件的实体,每帧自动更新
+    }
+}
+
+// 不推荐: 在 update 中手动查询
+class BadSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty());
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 每帧手动查询,浪费性能
+        const result = this.scene!.querySystem.queryAll(HealthComponent);
+        for (const entity of result.entities) {
+            // ...
+        }
+    }
+}
+```
+
+### 2. 合理使用 none() 排除条件
+
+```typescript
+// 排除已死亡的敌人
+class EnemyAISystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(EnemyTag, AIComponent)
+                .none(DeadTag)  // 不处理死亡的敌人
+        );
+    }
+}
+```
+
+### 3. 使用标签优化查询
+
+```typescript
+// 不好: 查询所有实体再过滤
+const allEntities = scene.querySystem.getAllEntities();
+const players = allEntities.filter(e => e.hasComponent(PlayerTag));
+
+// 好: 直接按标签查询
+const players = scene.querySystem.queryByTag(Tags.PLAYER).entities;
+```
+
+### 4. 避免过于复杂的查询条件
+
+```typescript
+// 不推荐: 过于复杂
+super(
+    Matcher.empty()
+        .all(A, B, C, D)
+        .any(E, F, G)
+        .none(H, I, J)
+);
+
+// 推荐: 拆分成多个简单系统
+class SystemAB extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(A, B));
+    }
+}
+
+class SystemCD extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(C, D));
+    }
+}
+```
+
+## 注意事项
+
+### 1. 查询结果是只读的
+
+```typescript
+const result = querySystem.queryAll(PositionComponent);
+
+// 不要修改返回的数组
+result.entities.push(someEntity);  // 错误!
+
+// 如果需要修改,先复制
+const mutableArray = [...result.entities];
+mutableArray.push(someEntity);  // 正确
+```
+
+### 2. 组件添加/移除后的查询时机
+
+```typescript
+// 创建实体并添加组件
+const entity = scene.createEntity('Player');
+entity.addComponent(new PositionComponent());
+
+// 立即查询可能获取到新实体
+const result = scene.querySystem.queryAll(PositionComponent);
+// result.entities 包含新创建的实体
+```
+
+### 3. Matcher 是不可变的
+
+```typescript
+const matcher = Matcher.empty().all(PositionComponent);
+
+// 链式调用返回新的 Matcher 实例
+const matcher2 = matcher.any(VelocityComponent);
+
+// matcher 本身不变
+console.log(matcher === matcher2); // false
+```
+
+## Matcher API 快速参考
+
+### 静态创建方法
+
+| 方法 | 说明 | 示例 |
+|------|------|------|
+| `Matcher.all(...types)` | 必须包含所有指定组件 | `Matcher.all(Position, Velocity)` |
+| `Matcher.any(...types)` | 至少包含一个指定组件 | `Matcher.any(Health, Shield)` |
+| `Matcher.none(...types)` | 不能包含任何指定组件 | `Matcher.none(Dead)` |
+| `Matcher.byTag(tag)` | 按标签查询 | `Matcher.byTag(1)` |
+| `Matcher.byName(name)` | 按名称查询 | `Matcher.byName("Player")` |
+| `Matcher.byComponent(type)` | 按单个组件查询 | `Matcher.byComponent(Health)` |
+| `Matcher.empty()` | 创建空匹配器（匹配所有实体） | `Matcher.empty()` |
+| `Matcher.nothing()` | 不匹配任何实体 | `Matcher.nothing()` |
+| `Matcher.complex()` | 创建复杂查询构建器 | `Matcher.complex()` |
+
+### 链式方法
+
+| 方法 | 说明 | 示例 |
+|------|------|------|
+| `.all(...types)` | 添加必须包含的组件 | `.all(Position)` |
+| `.any(...types)` | 添加可选组件（至少一个） | `.any(Weapon, Magic)` |
+| `.none(...types)` | 添加排除的组件 | `.none(Dead)` |
+| `.exclude(...types)` | `.none()` 的别名 | `.exclude(Disabled)` |
+| `.one(...types)` | `.any()` 的别名 | `.one(Player, Enemy)` |
+| `.withTag(tag)` | 添加标签条件 | `.withTag(1)` |
+| `.withName(name)` | 添加名称条件 | `.withName("Boss")` |
+| `.withComponent(type)` | 添加单组件条件 | `.withComponent(Health)` |
+
+### 实用方法
+
+| 方法 | 说明 |
+|------|------|
+| `.getCondition()` | 获取查询条件（只读） |
+| `.isEmpty()` | 检查是否为空条件 |
+| `.isNothing()` | 检查是否为 nothing 匹配器 |
+| `.clone()` | 克隆匹配器 |
+| `.reset()` | 重置所有条件 |
+| `.toString()` | 获取字符串表示 |
+
+### 常用组合示例
+
+```typescript
+// 基础移动系统
+Matcher.all(Position, Velocity)
+
+// 可攻击的活着的实体
+Matcher.all(Position, Health)
+    .any(Weapon, Magic)
+    .none(Dead, Disabled)
+
+// 所有带标签的敌人
+Matcher.byTag(Tags.ENEMY)
+    .all(AIComponent)
+
+// 只需要生命周期的系统
+Matcher.nothing()
+```
+
+## 相关 API
+
+- [Matcher](../api/classes/Matcher.md) - 查询条件描述符 API 参考
+- [QuerySystem](../api/classes/QuerySystem.md) - 查询系统 API 参考
+- [EntitySystem](../api/classes/EntitySystem.md) - 实体系统 API 参考
+- [Entity](../api/classes/Entity.md) - 实体 API 参考

docs/guide/entity.md

@@ -9,6 +9,12 @@
 - 提供唯一标识（ID）
 - 管理组件的生命周期
 
+::: tip 关于父子层级关系
+实体间的父子层级关系通过 `HierarchyComponent` 和 `HierarchySystem` 管理，而非 Entity 内置属性。这种设计遵循 ECS 组合原则 —— 只有需要层级关系的实体才添加此组件。
+
+详见 [层级系统](./hierarchy.md) 文档。
+:::
+
 ## 创建实体
 
 **重要提示：实体必须通过场景创建，不支持手动创建！**
@@ -285,4 +291,156 @@ entity.components.forEach(component => {
 });
 ```
 
-实体是 ECS 架构的核心概念之一，理解如何正确使用实体将帮助你构建高效、可维护的游戏代码。
+实体是 ECS 架构的核心概念之一，理解如何正确使用实体将帮助你构建高效、可维护的游戏代码。
+
+## 实体句柄 (EntityHandle)
+
+实体句柄是一种安全的实体引用方式，用于解决"引用已销毁实体"的问题。
+
+### 问题场景
+
+假设你的 AI 系统需要追踪一个目标敌人：
+
+```typescript
+// 错误做法：直接存储实体引用
+class AISystem extends EntitySystem {
+    private targetEnemy: Entity | null = null;
+
+    setTarget(enemy: Entity) {
+        this.targetEnemy = enemy;
+    }
+
+    process() {
+        if (this.targetEnemy) {
+            // 危险！敌人可能已被销毁，但引用还在
+            // 更糟糕：这个内存位置可能被新实体复用了
+            const health = this.targetEnemy.getComponent(Health);
+            // 可能操作了错误的实体！
+        }
+    }
+}
+```
+
+### 使用句柄的正确做法
+
+每个实体创建时会自动分配一个句柄，通过 `entity.handle` 获取：
+
+```typescript
+import { EntityHandle, NULL_HANDLE, isValidHandle } from '@esengine/ecs-framework';
+
+class AISystem extends EntitySystem {
+    // 存储句柄而非实体引用
+    private targetHandle: EntityHandle = NULL_HANDLE;
+
+    setTarget(enemy: Entity) {
+        // 保存敌人的句柄
+        this.targetHandle = enemy.handle;
+    }
+
+    process() {
+        if (!isValidHandle(this.targetHandle)) {
+            return; // 没有目标
+        }
+
+        // 通过句柄获取实体（自动检测是否有效）
+        const enemy = this.scene.findEntityByHandle(this.targetHandle);
+
+        if (!enemy) {
+            // 敌人已被销毁，清空引用
+            this.targetHandle = NULL_HANDLE;
+            return;
+        }
+
+        // 安全操作
+        const health = enemy.getComponent(Health);
+    }
+}
+```
+
+### 完整示例：技能目标锁定
+
+```typescript
+import {
+    EntitySystem, Entity, EntityHandle, NULL_HANDLE, isValidHandle
+} from '@esengine/ecs-framework';
+
+@ECSSystem('SkillTargeting')
+class SkillTargetingSystem extends EntitySystem {
+    // 存储多个目标的句柄
+    private lockedTargets: Map<Entity, EntityHandle> = new Map();
+
+    // 锁定目标
+    lockTarget(caster: Entity, target: Entity) {
+        this.lockedTargets.set(caster, target.handle);
+    }
+
+    // 获取锁定的目标
+    getLockedTarget(caster: Entity): Entity | null {
+        const handle = this.lockedTargets.get(caster);
+
+        if (!handle || !isValidHandle(handle)) {
+            return null;
+        }
+
+        // findEntityByHandle 会检查句柄是否有效
+        const target = this.scene.findEntityByHandle(handle);
+
+        if (!target) {
+            // 目标已死亡，清除锁定
+            this.lockedTargets.delete(caster);
+        }
+
+        return target;
+    }
+
+    // 释放技能
+    castSkill(caster: Entity) {
+        const target = this.getLockedTarget(caster);
+
+        if (!target) {
+            console.log('目标丢失，技能取消');
+            return;
+        }
+
+        // 安全地对目标造成伤害
+        const health = target.getComponent(Health);
+        if (health) {
+            health.current -= 10;
+        }
+    }
+}
+```
+
+### 句柄 vs 实体引用
+
+| 场景 | 推荐方式 |
+|-----|---------|
+| 同一帧内临时使用 | 直接用 `Entity` 引用 |
+| 跨帧存储（如 AI 目标、技能目标） | 使用 `EntityHandle` |
+| 需要序列化保存 | 使用 `EntityHandle`（数字类型） |
+| 网络同步 | 使用 `EntityHandle`（可直接传输） |
+
+### API 速查
+
+```typescript
+// 获取实体的句柄
+const handle = entity.handle;
+
+// 检查句柄是否非空
+if (isValidHandle(handle)) { ... }
+
+// 通过句柄获取实体（自动检测有效性）
+const entity = scene.findEntityByHandle(handle);
+
+// 检查句柄对应的实体是否存活
+const alive = scene.handleManager.isAlive(handle);
+
+// 空句柄常量
+const emptyHandle = NULL_HANDLE;
+```
+
+## 下一步
+
+- 了解 [层级系统](./hierarchy.md) 建立实体间的父子关系
+- 了解 [组件系统](./component.md) 为实体添加功能
+- 了解 [场景管理](./scene.md) 组织和管理实体

docs/guide/getting-started.md

@@ -4,7 +4,24 @@
 
 ## 安装
 
-### NPM 安装
+### 使用 CLI（推荐）
+
+在现有项目中添加 ECS 的最简单方式：
+
+```bash
+# 在项目目录中运行
+npx @esengine/cli init
+```
+
+CLI 会自动检测项目类型（Cocos Creator 2.x/3.x、LayaAir 3.x 或 Node.js）并生成相应的集成代码，包括：
+
+- `ECSManager` 组件/脚本 - 负责 ECS 生命周期管理
+- 示例组件和系统 - 帮助快速上手
+- 自动安装依赖
+
+### NPM 手动安装
+
+如果你更喜欢手动配置，可以直接安装：
 
 ```bash
 # 使用 npm
@@ -23,7 +40,6 @@ import { Core } from '@esengine/ecs-framework'
 // 方式1：使用配置对象（推荐）
 const core = Core.create({
   debug: true,                    // 启用调试模式，提供详细的日志和性能监控
-  enableEntitySystems: true,     // 启用实体系统，这是ECS的核心功能
   debugConfig: {                 // 可选：高级调试配置
     enabled: false,               // 是否启用WebSocket调试服务器
     websocketUrl: 'ws://localhost:8080',
@@ -39,12 +55,11 @@ const core = Core.create({
 });
 
 // 方式2：简化创建（向后兼容）
-const core = Core.create(true);  // 等同于 { debug: true, enableEntitySystems: true }
+const core = Core.create(true);  // 等同于 { debug: true }
 
 // 方式3：生产环境配置
 const core = Core.create({
-  debug: false,                 // 生产环境关闭调试
-  enableEntitySystems: true
+  debug: false                   // 生产环境关闭调试
 });
 ```
 
@@ -55,9 +70,6 @@ interface ICoreConfig {
   /** 是否启用调试模式 - 影响日志级别和性能监控 */
   debug?: boolean;
 
-  /** 是否启用实体系统 - 核心ECS功能开关 */
-  enableEntitySystems?: boolean;
-
   /** 高级调试配置 - 用于开发工具集成 */
   debugConfig?: {
     enabled: boolean;                    // 是否启用调试服务器
@@ -338,27 +350,39 @@ function gameLoop(deltaTime: number) {
 
 ## 与游戏引擎集成
 
-### Laya 引擎集成
+### Laya 3.x 引擎集成
+
+推荐使用 `Laya.Script` 组件来管理 ECS 生命周期：
 
 ```typescript
-import { Stage } from "laya/display/Stage";
-import { Laya } from "Laya";
-import { Core } from '@esengine/ecs-framework';
+import { Core, Scene } from '@esengine/ecs-framework';
 
-// 初始化 Laya
-Laya.init(800, 600).then(() => {
-  // 初始化 ECS
-  Core.create(true);
-  Core.setScene(new GameScene());
+const { regClass } = Laya;
 
-  // 启动游戏循环
-  Laya.timer.frameLoop(1, this, () => {
-    const deltaTime = Laya.timer.delta / 1000;
-    Core.update(deltaTime);  // 自动更新全局服务和场景
-  });
-});
+@regClass()
+export class ECSManager extends Laya.Script {
+  private ecsScene = new GameScene();
+
+  onAwake(): void {
+    // 初始化 ECS
+    Core.create({ debug: true });
+    Core.setScene(this.ecsScene);
+  }
+
+  onUpdate(): void {
+    // 自动更新全局服务和场景
+    Core.update(Laya.timer.delta / 1000);
+  }
+
+  onDestroy(): void {
+    // 清理资源
+    Core.destroy();
+  }
+}
 ```
 
+在 Laya IDE 中，将 `ECSManager` 脚本挂载到场景中的节点上即可。
+
 ### Cocos Creator 集成
 
 ```typescript

docs/guide/hierarchy.md

@@ -0,0 +1,437 @@
+# 层级系统
+
+在游戏开发中，实体间的父子层级关系是常见需求。ECS Framework 采用组件化方式管理层级关系，通过 `HierarchyComponent` 和 `HierarchySystem` 实现，完全遵循 ECS 组合原则。
+
+## 设计理念
+
+### 为什么不在 Entity 中内置层级？
+
+传统的游戏对象模型将层级关系内置于实体中。ECS Framework 选择组件化方案的原因：
+
+1. **ECS 组合原则**：层级是一种"功能"，应该通过组件添加，而非所有实体都具备
+2. **按需使用**：只有需要层级关系的实体才添加 `HierarchyComponent`
+3. **数据与逻辑分离**：`HierarchyComponent` 存储数据，`HierarchySystem` 处理逻辑
+4. **序列化友好**：层级关系作为组件数据可以轻松序列化和反序列化
+
+## 基本概念
+
+### HierarchyComponent
+
+存储层级关系数据的组件：
+
+```typescript
+import { HierarchyComponent } from '@esengine/ecs-framework';
+
+// HierarchyComponent 的核心属性
+interface HierarchyComponent {
+    parentId: number | null;      // 父实体 ID，null 表示根实体
+    childIds: number[];           // 子实体 ID 列表
+    depth: number;                // 在层级中的深度（由系统维护）
+    bActiveInHierarchy: boolean;  // 在层级中是否激活（由系统维护）
+}
+```
+
+### HierarchySystem
+
+处理层级逻辑的系统，提供所有层级操作的 API：
+
+```typescript
+import { HierarchySystem } from '@esengine/ecs-framework';
+
+// 获取系统
+const hierarchySystem = scene.getEntityProcessor(HierarchySystem);
+```
+
+## 快速开始
+
+### 添加系统到场景
+
+```typescript
+import { Scene, HierarchySystem } from '@esengine/ecs-framework';
+
+class GameScene extends Scene {
+    protected initialize(): void {
+        // 添加层级系统
+        this.addSystem(new HierarchySystem());
+
+        // 添加其他系统...
+    }
+}
+```
+
+### 建立父子关系
+
+```typescript
+// 创建实体
+const parent = scene.createEntity("Parent");
+const child1 = scene.createEntity("Child1");
+const child2 = scene.createEntity("Child2");
+
+// 获取层级系统
+const hierarchySystem = scene.getEntityProcessor(HierarchySystem);
+
+// 设置父子关系（自动添加 HierarchyComponent）
+hierarchySystem.setParent(child1, parent);
+hierarchySystem.setParent(child2, parent);
+
+// 现在 parent 有两个子实体
+```
+
+### 查询层级
+
+```typescript
+// 获取父实体
+const parentEntity = hierarchySystem.getParent(child1);
+
+// 获取所有子实体
+const children = hierarchySystem.getChildren(parent);
+
+// 获取子实体数量
+const count = hierarchySystem.getChildCount(parent);
+
+// 检查是否有子实体
+const hasKids = hierarchySystem.hasChildren(parent);
+
+// 获取在层级中的深度
+const depth = hierarchySystem.getDepth(child1);  // 返回 1
+```
+
+## API 参考
+
+### 父子关系操作
+
+#### setParent
+
+设置实体的父级：
+
+```typescript
+// 设置父级
+hierarchySystem.setParent(child, parent);
+
+// 移动到根级（无父级）
+hierarchySystem.setParent(child, null);
+```
+
+#### insertChildAt
+
+在指定位置插入子实体：
+
+```typescript
+// 在第一个位置插入
+hierarchySystem.insertChildAt(parent, child, 0);
+
+// 追加到末尾
+hierarchySystem.insertChildAt(parent, child, -1);
+```
+
+#### removeChild
+
+从父级移除子实体（子实体变为根级）：
+
+```typescript
+const success = hierarchySystem.removeChild(parent, child);
+```
+
+#### removeAllChildren
+
+移除所有子实体：
+
+```typescript
+hierarchySystem.removeAllChildren(parent);
+```
+
+### 层级查询
+
+#### getParent / getChildren
+
+```typescript
+const parent = hierarchySystem.getParent(entity);
+const children = hierarchySystem.getChildren(entity);
+```
+
+#### getRoot
+
+获取实体的根节点：
+
+```typescript
+const root = hierarchySystem.getRoot(deepChild);
+```
+
+#### getRootEntities
+
+获取所有根实体（没有父级的实体）：
+
+```typescript
+const roots = hierarchySystem.getRootEntities();
+```
+
+#### isAncestorOf / isDescendantOf
+
+检查祖先/后代关系：
+
+```typescript
+// grandparent -> parent -> child
+const isAncestor = hierarchySystem.isAncestorOf(grandparent, child);  // true
+const isDescendant = hierarchySystem.isDescendantOf(child, grandparent);  // true
+```
+
+### 层级遍历
+
+#### findChild
+
+根据名称查找子实体：
+
+```typescript
+// 直接子级中查找
+const child = hierarchySystem.findChild(parent, "ChildName");
+
+// 递归查找所有后代
+const deepChild = hierarchySystem.findChild(parent, "DeepChild", true);
+```
+
+#### findChildrenByTag
+
+根据标签查找子实体：
+
+```typescript
+// 查找直接子级
+const tagged = hierarchySystem.findChildrenByTag(parent, TAG_ENEMY);
+
+// 递归查找
+const allTagged = hierarchySystem.findChildrenByTag(parent, TAG_ENEMY, true);
+```
+
+#### forEachChild
+
+遍历子实体：
+
+```typescript
+// 遍历直接子级
+hierarchySystem.forEachChild(parent, (child) => {
+    console.log(child.name);
+});
+
+// 递归遍历所有后代
+hierarchySystem.forEachChild(parent, (child) => {
+    console.log(child.name);
+}, true);
+```
+
+### 层级状态
+
+#### isActiveInHierarchy
+
+检查实体在层级中是否激活（考虑所有祖先的激活状态）：
+
+```typescript
+// 如果 parent.active = false，即使 child.active = true
+// isActiveInHierarchy(child) 也会返回 false
+const activeInHierarchy = hierarchySystem.isActiveInHierarchy(child);
+```
+
+#### getDepth
+
+获取实体在层级中的深度（根实体深度为 0）：
+
+```typescript
+const depth = hierarchySystem.getDepth(entity);
+```
+
+### 扁平化层级（用于 UI 渲染）
+
+```typescript
+// 用于实现可展开/折叠的层级树视图
+const expandedIds = new Set([parent.id]);
+
+const flatNodes = hierarchySystem.flattenHierarchy(expandedIds);
+// 返回 [{ entity, depth, bHasChildren, bIsExpanded }, ...]
+```
+
+## 完整示例
+
+### 创建游戏角色层级
+
+```typescript
+import {
+    Scene,
+    HierarchySystem,
+    HierarchyComponent
+} from '@esengine/ecs-framework';
+
+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);
+
+        // 特效（挂载在武器上）
+        const effect = this.createEntity("WeaponEffect");
+        effect.addComponent(new ParticleEmitter());
+        this.hierarchySystem.setParent(effect, weapon);
+
+        // 查询层级信息
+        console.log(`Player 层级深度: ${this.hierarchySystem.getDepth(player)}`);     // 0
+        console.log(`Weapon 层级深度: ${this.hierarchySystem.getDepth(weapon)}`);     // 2
+        console.log(`Effect 层级深度: ${this.hierarchySystem.getDepth(effect)}`);     // 3
+    }
+
+    public equipNewWeapon(weaponName: string): void {
+        const body = this.findEntity("Body");
+        const oldWeapon = this.hierarchySystem.findChild(body!, "Weapon");
+
+        if (oldWeapon) {
+            // 移除旧武器的所有子实体
+            this.hierarchySystem.removeAllChildren(oldWeapon);
+            oldWeapon.destroy();
+        }
+
+        // 创建新武器
+        const newWeapon = this.createEntity("Weapon");
+        newWeapon.addComponent(new Sprite(`${weaponName}.png`));
+        this.hierarchySystem.setParent(newWeapon, body!);
+    }
+}
+```
+
+### 层级变换系统
+
+结合 Transform 组件实现层级变换：
+
+```typescript
+import { EntitySystem, Matcher, HierarchySystem, HierarchyComponent } from '@esengine/ecs-framework';
+
+class HierarchyTransformSystem extends EntitySystem {
+    private hierarchySystem!: HierarchySystem;
+
+    constructor() {
+        super(Matcher.empty().all(Transform, HierarchyComponent));
+    }
+
+    public onAddedToScene(): void {
+        // 获取层级系统引用
+        this.hierarchySystem = this.scene!.getEntityProcessor(HierarchySystem)!;
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 按深度排序，确保父级先更新
+        const sorted = [...entities].sort((a, b) => {
+            return this.hierarchySystem.getDepth(a) - this.hierarchySystem.getDepth(b);
+        });
+
+        for (const entity of sorted) {
+            const transform = entity.getComponent(Transform)!;
+            const parent = this.hierarchySystem.getParent(entity);
+
+            if (parent) {
+                const parentTransform = parent.getComponent(Transform);
+                if (parentTransform) {
+                    // 计算世界坐标
+                    transform.worldX = parentTransform.worldX + transform.localX;
+                    transform.worldY = parentTransform.worldY + transform.localY;
+                }
+            } else {
+                // 根实体，本地坐标即世界坐标
+                transform.worldX = transform.localX;
+                transform.worldY = transform.localY;
+            }
+        }
+    }
+}
+```
+
+## 性能优化
+
+### 缓存机制
+
+`HierarchySystem` 内置了缓存机制：
+
+- `depth` 和 `bActiveInHierarchy` 由系统自动维护
+- 使用 `bCacheDirty` 标记优化更新
+- 层级变化时自动标记所有子级缓存为脏
+
+### 最佳实践
+
+1. **避免深层嵌套**：系统限制最大深度为 32 层
+2. **批量操作**：构建复杂层级时，尽量一次性设置好所有父子关系
+3. **按需添加**：只有真正需要层级关系的实体才添加 `HierarchyComponent`
+4. **缓存系统引用**：避免每次调用都获取 `HierarchySystem`
+
+```typescript
+// 好的做法
+class MySystem extends EntitySystem {
+    private hierarchySystem!: HierarchySystem;
+
+    onAddedToScene() {
+        this.hierarchySystem = this.scene!.getEntityProcessor(HierarchySystem)!;
+    }
+
+    process() {
+        // 使用缓存的引用
+        const parent = this.hierarchySystem.getParent(entity);
+    }
+}
+
+// 避免的做法
+process() {
+    // 每次都获取，性能较差
+    const system = this.scene!.getEntityProcessor(HierarchySystem);
+}
+```
+
+## 迁移指南
+
+如果你之前使用的是旧版 Entity 内置的层级 API，请参考以下迁移指南：
+
+| 旧 API (已移除) | 新 API |
+|----------------|--------|
+| `entity.parent` | `hierarchySystem.getParent(entity)` |
+| `entity.children` | `hierarchySystem.getChildren(entity)` |
+| `entity.addChild(child)` | `hierarchySystem.setParent(child, entity)` |
+| `entity.removeChild(child)` | `hierarchySystem.removeChild(entity, child)` |
+| `entity.findChild(name)` | `hierarchySystem.findChild(entity, name)` |
+| `entity.activeInHierarchy` | `hierarchySystem.isActiveInHierarchy(entity)` |
+
+### 迁移示例
+
+```typescript
+// 旧代码
+const parent = scene.createEntity("Parent");
+const child = scene.createEntity("Child");
+parent.addChild(child);
+const found = parent.findChild("Child");
+
+// 新代码
+const hierarchySystem = scene.getEntityProcessor(HierarchySystem);
+
+const parent = scene.createEntity("Parent");
+const child = scene.createEntity("Child");
+hierarchySystem.setParent(child, parent);
+const found = hierarchySystem.findChild(parent, "Child");
+```
+
+## 下一步
+
+- 了解 [实体类](./entity.md) 的其他功能
+- 了解 [场景管理](./scene.md) 如何组织实体和系统
+- 了解 [组件系统](./component.md) 如何定义和使用组件

docs/guide/index.md

@@ -13,6 +13,9 @@
 ### [系统架构 (System)](./system.md)
 掌握系统的编写方法，实现游戏逻辑的处理。
 
+### [实体查询与 Matcher](./entity-query.md)
+学习使用 Matcher 进行实体筛选和查询，掌握 `all`、`any`、`none`、`nothing` 等匹配条件。
+
 ### [场景管理 (Scene)](./scene.md)
 了解场景的生命周期、系统管理和实体容器功能。
 

docs/guide/logging.md

@@ -238,6 +238,50 @@ class HierarchicalLoggingExample {
 }
 ```
 
+### 集成第三方日志库
+
+通过 `setLoggerFactory` 可以将业务代码中的日志器替换为第三方日志库（如 winston、pino、nestjs Logger 等）。
+
+**说明**: 目前框架内部日志仍使用 ConsoleLogger，自定义日志器仅影响业务代码（如 EntitySystem）。
+
+#### 基本用法
+
+```typescript
+import { setLoggerFactory } from '@esengine/ecs-framework';
+
+setLoggerFactory((name?: string) => {
+  // 返回实现 ILogger 接口的日志器实例
+  return yourLogger;
+});
+```
+
+#### 使用示例
+
+```typescript
+// 集成 Winston
+setLoggerFactory((name?: string) => winston.createLogger({ /* ... */ }));
+
+// 集成 Pino
+setLoggerFactory((name?: string) => pino({ name }));
+
+// 集成 NestJS Logger
+setLoggerFactory((name?: string) => new Logger(name));
+```
+
+#### EntitySystem 中的使用
+
+EntitySystem 会自动使用类名创建日志器:
+
+```typescript
+class PlayerMovementSystem extends EntitySystem {
+  // this.logger 自动使用 'PlayerMovementSystem' 作为名称
+
+  protected process(entities: readonly Entity[]): void {
+    this.logger.info(`处理 ${entities.length} 个玩家实体`);
+  }
+}
+```
+
 ### 自定义输出
 
 ```typescript
@@ -547,4 +591,4 @@ class LoggingConfiguration {
 LoggingConfiguration.setupLogging();
 ```
 
-日志系统是调试和监控应用的重要工具，正确使用日志系统能大大提高开发效率和问题排查能力。
+日志系统是调试和监控应用的重要工具，正确使用日志系统能大大提高开发效率和问题排查能力。

docs/guide/persistent-entity.md

@@ -0,0 +1,360 @@
+# 持久化实体
+
+> **版本**: v2.3.0+
+
+持久化实体（Persistent Entity）是一种可以在场景切换时自动迁移到新场景的特殊实体。适用于需要跨场景保持状态的游戏对象，如玩家、游戏管理器、音频管理器等。
+
+## 基本概念
+
+在 ECS 框架中，实体有两种生命周期策略：
+
+| 策略 | 说明 | 默认 |
+|-----|------|------|
+| `SceneLocal` | 场景本地实体，场景切换时销毁 | ✓ |
+| `Persistent` | 持久化实体，场景切换时自动迁移 | |
+
+## 快速开始
+
+### 创建持久化实体
+
+```typescript
+import { Scene } from '@esengine/ecs-framework';
+
+class GameScene extends Scene {
+  protected initialize(): void {
+    // 创建持久化玩家实体
+    const player = this.createEntity('Player').setPersistent();
+    player.addComponent(new Position(100, 200));
+    player.addComponent(new PlayerData('Hero', 500));
+
+    // 创建普通敌人实体（场景切换时销毁）
+    const enemy = this.createEntity('Enemy');
+    enemy.addComponent(new Position(300, 200));
+    enemy.addComponent(new EnemyAI());
+  }
+}
+```
+
+### 场景切换时的行为
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// 初始场景
+class Level1Scene extends Scene {
+  protected initialize(): void {
+    // 玩家 - 持久化，会迁移到下一个场景
+    const player = this.createEntity('Player').setPersistent();
+    player.addComponent(new Position(0, 0));
+    player.addComponent(new Health(100));
+
+    // 敌人 - 场景本地，切换时销毁
+    const enemy = this.createEntity('Enemy');
+    enemy.addComponent(new Position(100, 100));
+  }
+}
+
+// 目标场景
+class Level2Scene extends Scene {
+  protected initialize(): void {
+    // 新的敌人
+    const enemy = this.createEntity('Boss');
+    enemy.addComponent(new Position(200, 200));
+  }
+
+  public onStart(): void {
+    // 玩家已自动迁移到此场景
+    const player = this.findEntity('Player');
+    console.log(player !== null); // true
+
+    // 位置和血量数据完整保留
+    const position = player?.getComponent(Position);
+    const health = player?.getComponent(Health);
+    console.log(position?.x, position?.y); // 0, 0
+    console.log(health?.value); // 100
+  }
+}
+
+// 切换场景
+Core.create({ debug: true });
+Core.setScene(new Level1Scene());
+
+// 稍后切换到 Level2
+Core.loadScene(new Level2Scene());
+// Player 实体自动迁移，Enemy 实体被销毁
+```
+
+## API 参考
+
+### Entity 方法
+
+#### setPersistent()
+
+将实体标记为持久化，场景切换时不会被销毁。
+
+```typescript
+public setPersistent(): this
+```
+
+**返回**: 返回实体本身，支持链式调用
+
+**示例**:
+```typescript
+const player = scene.createEntity('Player')
+  .setPersistent();
+
+player.addComponent(new Position(100, 200));
+```
+
+#### setSceneLocal()
+
+将实体恢复为场景本地策略（默认）。
+
+```typescript
+public setSceneLocal(): this
+```
+
+**返回**: 返回实体本身，支持链式调用
+
+**示例**:
+```typescript
+// 动态取消持久化
+player.setSceneLocal();
+```
+
+#### isPersistent
+
+检查实体是否为持久化实体。
+
+```typescript
+public get isPersistent(): boolean
+```
+
+**示例**:
+```typescript
+if (entity.isPersistent) {
+  console.log('这是持久化实体');
+}
+```
+
+#### lifecyclePolicy
+
+获取实体的生命周期策略。
+
+```typescript
+public get lifecyclePolicy(): EEntityLifecyclePolicy
+```
+
+**示例**:
+```typescript
+import { EEntityLifecyclePolicy } from '@esengine/ecs-framework';
+
+if (entity.lifecyclePolicy === EEntityLifecyclePolicy.Persistent) {
+  console.log('持久化实体');
+}
+```
+
+### Scene 方法
+
+#### findPersistentEntities()
+
+查找场景中所有持久化实体。
+
+```typescript
+public findPersistentEntities(): Entity[]
+```
+
+**返回**: 持久化实体数组
+
+**示例**:
+```typescript
+const persistentEntities = scene.findPersistentEntities();
+console.log(`场景中有 ${persistentEntities.length} 个持久化实体`);
+```
+
+#### extractPersistentEntities()
+
+提取并从场景中移除所有持久化实体（通常由框架内部调用）。
+
+```typescript
+public extractPersistentEntities(): Entity[]
+```
+
+**返回**: 被提取的持久化实体数组
+
+#### receiveMigratedEntities()
+
+接收迁移过来的实体（通常由框架内部调用）。
+
+```typescript
+public receiveMigratedEntities(entities: Entity[]): void
+```
+
+**参数**:
+- `entities` - 要接收的实体数组
+
+## 使用场景
+
+### 1. 玩家实体跨关卡
+
+```typescript
+class PlayerSetupScene extends Scene {
+  protected initialize(): void {
+    // 玩家在所有关卡中保持状态
+    const player = this.createEntity('Player').setPersistent();
+    player.addComponent(new Transform(0, 0));
+    player.addComponent(new Health(100));
+    player.addComponent(new Inventory());
+    player.addComponent(new PlayerStats());
+  }
+}
+
+class Level1 extends Scene { /* ... */ }
+class Level2 extends Scene { /* ... */ }
+class Level3 extends Scene { /* ... */ }
+
+// 玩家实体会自动在所有关卡间迁移
+Core.setScene(new PlayerSetupScene());
+// ... 游戏进行
+Core.loadScene(new Level1());
+// ... 关卡完成
+Core.loadScene(new Level2());
+// 玩家数据（血量、物品栏、属性）完整保留
+```
+
+### 2. 全局管理器
+
+```typescript
+class BootstrapScene extends Scene {
+  protected initialize(): void {
+    // 音频管理器 - 跨场景保持
+    const audioManager = this.createEntity('AudioManager').setPersistent();
+    audioManager.addComponent(new AudioController());
+
+    // 成就管理器 - 跨场景保持
+    const achievementManager = this.createEntity('AchievementManager').setPersistent();
+    achievementManager.addComponent(new AchievementTracker());
+
+    // 游戏设置 - 跨场景保持
+    const settings = this.createEntity('GameSettings').setPersistent();
+    settings.addComponent(new SettingsData());
+  }
+}
+```
+
+### 3. 动态切换持久化状态
+
+```typescript
+class GameScene extends Scene {
+  protected initialize(): void {
+    // 初始创建为普通实体
+    const companion = this.createEntity('Companion');
+    companion.addComponent(new Transform(0, 0));
+    companion.addComponent(new CompanionAI());
+
+    // 监听招募事件
+    this.eventSystem.on('companion:recruited', () => {
+      // 招募后变为持久化实体
+      companion.setPersistent();
+      console.log('同伴已加入队伍，将跟随玩家跨场景');
+    });
+
+    // 监听解散事件
+    this.eventSystem.on('companion:dismissed', () => {
+      // 解散后恢复为场景本地实体
+      companion.setSceneLocal();
+      console.log('同伴已离队，不再跨场景');
+    });
+  }
+}
+```
+
+## 最佳实践
+
+### 1. 明确标识持久化实体
+
+```typescript
+// 推荐：在创建时立即标记
+const player = this.createEntity('Player').setPersistent();
+
+// 不推荐：创建后再标记（容易遗漏）
+const player = this.createEntity('Player');
+// ... 很多代码 ...
+player.setPersistent(); // 容易忘记
+```
+
+### 2. 合理使用持久化
+
+```typescript
+// ✓ 适合持久化的实体
+const player = this.createEntity('Player').setPersistent();      // 玩家
+const gameManager = this.createEntity('GameManager').setPersistent(); // 全局管理器
+const audioManager = this.createEntity('AudioManager').setPersistent(); // 音频系统
+
+// ✗ 不应持久化的实体
+const bullet = this.createEntity('Bullet'); // 临时对象
+const enemy = this.createEntity('Enemy');   // 关卡特定敌人
+const particle = this.createEntity('Particle'); // 特效粒子
+```
+
+### 3. 检查迁移后的实体
+
+```typescript
+class NewScene extends Scene {
+  public onStart(): void {
+    // 检查预期的持久化实体是否存在
+    const player = this.findEntity('Player');
+    if (!player) {
+      console.error('玩家实体未正确迁移！');
+      // 处理错误情况
+    }
+  }
+}
+```
+
+### 4. 避免循环引用
+
+```typescript
+// ✗ 避免：持久化实体引用场景本地实体
+class BadScene extends Scene {
+  protected initialize(): void {
+    const player = this.createEntity('Player').setPersistent();
+    const enemy = this.createEntity('Enemy');
+
+    // 危险：player 持久化但 enemy 不是
+    // 场景切换后 enemy 被销毁，引用失效
+    player.addComponent(new TargetComponent(enemy));
+  }
+}
+
+// ✓ 推荐：使用 ID 引用或事件系统
+class GoodScene extends Scene {
+  protected initialize(): void {
+    const player = this.createEntity('Player').setPersistent();
+    const enemy = this.createEntity('Enemy');
+
+    // 存储 ID 而非直接引用
+    player.addComponent(new TargetComponent(enemy.id));
+
+    // 或使用事件系统通信
+  }
+}
+```
+
+## 注意事项
+
+1. **已销毁的实体不会迁移**：如果实体在场景切换前被销毁，即使标记为持久化也不会迁移。
+
+2. **组件数据完整保留**：迁移时所有组件及其状态都会保留。
+
+3. **场景引用会更新**：迁移后实体的 `scene` 属性会指向新场景。
+
+4. **查询系统会更新**：迁移的实体会自动注册到新场景的查询系统中。
+
+5. **延迟切换同样生效**：使用 `Core.loadScene()` 延迟切换时，持久化实体同样会迁移。
+
+## 相关文档
+
+- [场景管理](./scene.md) - 了解场景的基本使用
+- [SceneManager](./scene-manager.md) - 了解场景切换
+- [WorldManager](./world-manager.md) - 了解多世界管理

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

@@ -6,409 +6,198 @@
 
 ## 特性支持
 
-- ✅ **Worker**: 支持（通过 `wx.createWorker` 创建，需要配置 game.json）
-- ❌ **SharedArrayBuffer**: 不支持
-- ❌ **Transferable Objects**: 不支持（只支持可序列化对象）
-- ✅ **高精度时间**: 使用 `Date.now()` 或 `wx.getPerformance()`
-- ✅ **设备信息**: 完整的微信小游戏设备信息
+| 特性 | 支持情况 | 说明 |
+|------|----------|------|
+| **Worker** | ✅ 支持 | 需要使用预编译文件，配置 `workerScriptPath` |
+| **SharedArrayBuffer** | ❌ 不支持 | 微信小游戏环境不支持 |
+| **Transferable Objects** | ❌ 不支持 | 只支持可序列化对象 |
+| **高精度时间** | ✅ 支持 | 使用 `wx.getPerformance()` |
+| **设备信息** | ✅ 支持 | 完整的微信小游戏设备信息 |
 
-## 完整实现
+## WorkerEntitySystem 使用方式
 
-```typescript
-import type {
-    IPlatformAdapter,
-    PlatformWorker,
-    WorkerCreationOptions,
-    PlatformConfig,
-    WeChatDeviceInfo
-} from '@esengine/ecs-framework';
+### 重要：微信小游戏 Worker 限制
 
-/**
- * 微信小游戏平台适配器
- * 支持微信小游戏环境
- */
-export class WeChatMiniGameAdapter implements IPlatformAdapter {
-    public readonly name = 'wechat-minigame';
-    public readonly version: string;
-    private systemInfo: any;
+微信小游戏的 Worker 有以下限制：
+- **Worker 脚本必须在代码包内**，不能动态生成
+- **必须在 `game.json` 中配置** `workers` 目录
+- **最多只能创建 1 个 Worker**
 
-    constructor() {
-        // 获取微信小游戏版本信息
-        this.systemInfo = this.getSystemInfo();
-        this.version = this.systemInfo.version || 'unknown';
-    }
+因此，使用 `WorkerEntitySystem` 时有两种方式：
+1. **推荐：使用 CLI 工具自动生成** Worker 文件
+2. 手动创建 Worker 文件
 
-    /**
-     * 检查是否支持Worker
-     */
-    public isWorkerSupported(): boolean {
-        // 微信小游戏支持Worker，通过wx.createWorker创建
-        return typeof wx !== 'undefined' && typeof wx.createWorker === 'function';
-    }
+### 方式一：使用 CLI 工具自动生成（推荐）
 
-    /**
-     * 检查是否支持SharedArrayBuffer（不支持）
-     */
-    public isSharedArrayBufferSupported(): boolean {
-        return false; // 微信小游戏不支持SharedArrayBuffer
-    }
+我们提供了 `@esengine/worker-generator` 工具，可以自动从你的 TypeScript 代码中提取 `workerProcess` 函数并生成微信小游戏兼容的 Worker 文件。
 
-    /**
-     * 获取硬件并发数
-     */
-    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');
-        }
+```bash
+pnpm add -D @esengine/worker-generator
+# 或
+npm install --save-dev @esengine/worker-generator
+```
 
-        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
-    }
+```bash
+# 扫描 src 目录，生成 Worker 文件到 workers 目录
+npx esengine-worker-gen --src ./src --out ./workers --wechat
 
-    /**
-     * 获取高精度时间戳
-     */
-    public getHighResTimestamp(): number {
-        // 尝试使用微信的性能API，否则使用Date.now()
-        if (typeof wx !== 'undefined' && wx.getPerformance) {
-            const performance = wx.getPerformance();
-            return performance.now();
-        }
-        return Date.now();
-    }
+# 查看帮助
+npx esengine-worker-gen --help
+```
 
-    /**
-     * 获取平台配置
-     */
-    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,
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `-s, --src <dir>` | 源代码目录 | `./src` |
+| `-o, --out <dir>` | 输出目录 | `./workers` |
+| `-w, --wechat` | 生成微信小游戏兼容代码 | `false` |
+| `-m, --mapping` | 生成 worker-mapping.json | `true` |
+| `-t, --tsconfig <path>` | TypeScript 配置文件路径 | 自动查找 |
+| `-v, --verbose` | 详细输出 | `false` |
 
-            // 窗口信息
-            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
-        };
-    }
+```
+🔧 ESEngine Worker Generator
 
-    /**
-     * 异步获取完整的平台配置
-     */
-    public async getPlatformConfigAsync(): Promise<PlatformConfig> {
-        // 可以在这里添加异步获取设备性能信息的逻辑
-        const baseConfig = this.getPlatformConfig();
+Source directory: /project/src
+Output directory: /project/workers
+WeChat mode: Yes
 
-        // 尝试获取设备性能信息
-        try {
-            const benchmarkLevel = await this.getBenchmarkLevel();
-            baseConfig.extensions = {
-                ...baseConfig.extensions,
-                benchmarkLevel
-            };
-        } catch (error) {
-            console.warn('获取性能基准失败:', error);
-        }
+Scanning for WorkerEntitySystem classes...
 
-        return baseConfig;
-    }
+✓ Found 1 WorkerEntitySystem class(es):
+  - PhysicsSystem (src/systems/PhysicsSystem.ts)
 
-    /**
-     * 检查是否支持Transferable Objects
-     */
-    private checkTransferableObjectsSupport(): boolean {
-        // 微信小游戏不支持 Transferable Objects
-        // 基础库 2.20.2 之前只支持可序列化的 key-value 对象
-        // 2.20.2 之后支持任意类型数据，但仍然不支持 Transferable Objects
-        return false;
-    }
+Generating Worker files...
 
-    /**
-     * 获取系统信息
-     */
-    private getSystemInfo(): any {
-        if (typeof wx !== 'undefined' && wx.getSystemInfoSync) {
-            try {
-                return wx.getSystemInfoSync();
-            } catch (error) {
-                console.warn('获取微信系统信息失败:', error);
-                return {};
-            }
-        }
-        return {};
-    }
+✓ Successfully generated 1 Worker file(s):
+  - PhysicsSystem -> workers/physics-system-worker.js
 
-    /**
-     * 获取内存限制
-     */
-    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();
+📝 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'
+```
 
-                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);
-            }
-        }
-    }
+```json
+// package.json
+{
+  "scripts": {
+    "build:workers": "esengine-worker-gen --src ./src --out ./workers --wechat",
+    "build": "pnpm build:workers && your-build-command"
+  }
 }
 ```
 
-## 使用方法
+### 方式二：手动创建 Worker 文件
 
-### 1. 复制代码
+如果你不想使用 CLI 工具，也可以手动创建 Worker 文件。
 
-将上述代码复制到你的项目中，例如 `src/platform/WeChatMiniGameAdapter.ts`。
+在项目中创建 `workers/entity-worker.js`：
 
-### 2. 注册适配器
+```javascript
+// workers/entity-worker.js
+// 微信小游戏 WorkerEntitySystem 通用 Worker 模板
 
-```typescript
-import { PlatformManager } from '@esengine/ecs-framework';
-import { WeChatMiniGameAdapter } from './platform/WeChatMiniGameAdapter';
+let sharedFloatArray = null;
 
-// 检查是否在微信小游戏环境
-if (typeof wx !== 'undefined') {
-    const wechatAdapter = new WeChatMiniGameAdapter();
-    PlatformManager.getInstance().registerAdapter(wechatAdapter);
+worker.onMessage(function(e) {
+    const { type, id, entities, deltaTime, systemConfig, startIndex, endIndex, sharedBuffer } = e.data;
+
+    try {
+        // 处理 SharedArrayBuffer 初始化
+        if (type === 'init' && sharedBuffer) {
+            sharedFloatArray = new Float32Array(sharedBuffer);
+            worker.postMessage({ type: 'init', success: true });
+            return;
+        }
+
+        // 处理 SharedArrayBuffer 数据
+        if (type === 'shared' && sharedFloatArray) {
+            processSharedArrayBuffer(startIndex, endIndex, deltaTime, systemConfig);
+            worker.postMessage({ id, result: null });
+            return;
+        }
+
+        // 传统处理方式
+        if (entities) {
+            const result = workerProcess(entities, deltaTime, systemConfig);
+
+            // 处理 Promise 返回值
+            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 });
+    }
+});
+
+/**
+ * 实体处理函数 - 根据你的业务逻辑修改此函数
+ * @param {Array} entities - 实体数据数组
+ * @param {number} deltaTime - 帧间隔时间
+ * @param {Object} systemConfig - 系统配置
+ * @returns {Array} 处理后的实体数据
+ */
+function workerProcess(entities, deltaTime, systemConfig) {
+    // ====== 在这里编写你的处理逻辑 ======
+    // 示例：物理计算
+    return entities.map(function(entity) {
+        // 应用重力
+        entity.vy += (systemConfig.gravity || 100) * deltaTime;
+
+        // 更新位置
+        entity.x += entity.vx * deltaTime;
+        entity.y += entity.vy * deltaTime;
+
+        // 应用摩擦力
+        entity.vx *= (systemConfig.friction || 0.95);
+        entity.vy *= (systemConfig.friction || 0.95);
+
+        return entity;
+    });
+}
+
+/**
+ * SharedArrayBuffer 处理函数（可选）
+ */
+function processSharedArrayBuffer(startIndex, endIndex, deltaTime, systemConfig) {
+    if (!sharedFloatArray) return;
+
+    // ====== 根据需要实现 SharedArrayBuffer 处理逻辑 ======
+    // 注意：微信小游戏不支持 SharedArrayBuffer，此函数通常不会被调用
 }
 ```
 
-### 3. WorkerEntitySystem 使用方式
+### 步骤 2：配置 game.json
 
-微信小游戏适配器与 WorkerEntitySystem 配合使用，自动处理 Worker 脚本创建：
+在 `game.json` 中添加 workers 配置：
 
-#### 基本使用方式（推荐）
+```json
+{
+  "deviceOrientation": "portrait",
+  "showStatusBar": false,
+  "workers": "workers"
+}
+```
+
+### 步骤 3：使用 WorkerEntitySystem
 
 ```typescript
 import { WorkerEntitySystem, Matcher, Entity } from '@esengine/ecs-framework';
@@ -426,13 +215,17 @@ class PhysicsSystem extends WorkerEntitySystem<PhysicsData> {
     constructor() {
         super(Matcher.all(Transform, Velocity), {
             enableWorker: true,
-            workerCount: 1, // 微信小游戏限制只能创建1个Worker
-            systemConfig: { gravity: 100, friction: 0.95 }
+            workerCount: 1,  // 微信小游戏限制只能创建 1 个 Worker
+            workerScriptPath: 'workers/entity-worker.js',  // 指定预编译的 Worker 文件
+            systemConfig: {
+                gravity: 100,
+                friction: 0.95
+            }
         });
     }
 
     protected getDefaultEntityDataSize(): number {
-        return 6; // id, x, y, vx, vy, mass
+        return 6;
     }
 
     protected extractEntityData(entity: Entity): PhysicsData {
@@ -450,20 +243,15 @@ class PhysicsSystem extends WorkerEntitySystem<PhysicsData> {
         };
     }
 
-    // WorkerEntitySystem 会自动将此函数序列化并写入临时文件
+    // 注意：在微信小游戏中，此方法不会被使用
+    // Worker 的处理逻辑在 workers/entity-worker.js 中的 workerProcess 函数里
     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;
         });
     }
@@ -477,201 +265,219 @@ class PhysicsSystem extends WorkerEntitySystem<PhysicsData> {
         velocity.x = result.vx;
         velocity.y = result.vy;
     }
+
+    // SharedArrayBuffer 相关方法（微信小游戏不支持，可省略）
+    protected writeEntityToBuffer(data: PhysicsData, offset: number): void {}
+    protected readEntityFromBuffer(offset: number): PhysicsData | null { return null; }
 }
 ```
 
-#### 使用预先创建的 Worker 文件（可选）
+### 临时禁用 Worker（降级到同步模式）
 
-如果你希望使用预先创建的 Worker 文件：
+如果遇到问题，可以临时禁用 Worker：
 
 ```typescript
-// 1. 在 game.json 中配置 Worker 路径
-/*
-{
-  "workers": "workers"
+class PhysicsSystem extends WorkerEntitySystem<PhysicsData> {
+    constructor() {
+        super(Matcher.all(Transform, Velocity), {
+            enableWorker: false,  // 禁用 Worker，使用主线程同步处理
+            // ... 其他配置
+        });
+    }
 }
-*/
+```
 
-// 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;
+```typescript
+import type {
+    IPlatformAdapter,
+    PlatformWorker,
+    WorkerCreationOptions,
+    PlatformConfig
+} 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.SDKVersion || 'unknown';
+    }
+
+    public isWorkerSupported(): boolean {
+        return typeof wx !== 'undefined' && typeof wx.createWorker === 'function';
+    }
+
+    public isSharedArrayBufferSupported(): boolean {
+        return false;
+    }
+
+    public getHardwareConcurrency(): number {
+        return 1;  // 微信小游戏最多 1 个 Worker
+    }
+
+    public createWorker(scriptPath: string, options: WorkerCreationOptions = {}): PlatformWorker {
+        if (!this.isWorkerSupported()) {
+            throw new Error('微信小游戏环境不支持 Worker');
+        }
+
+        // scriptPath 必须是代码包内的文件路径
+        const worker = wx.createWorker(scriptPath, {
+            useExperimentalWorker: true
         });
 
-        self.postMessage({ id, result: results });
+        return new WeChatWorker(worker);
     }
-};
-*/
 
-// 3. 通过平台适配器直接创建（不推荐，WorkerEntitySystem会自动处理）
-const adapter = PlatformManager.getInstance().getAdapter();
-const worker = adapter.createWorker('workers/physics.js');
+    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,  // 重要：标记不支持动态脚本
+                requiresWorkerInit: false,
+                memoryLimit: 512 * 1024 * 1024,
+                workerNotSupported: false,
+                workerLimitations: [
+                    '最多只能创建 1 个 Worker',
+                    'Worker 脚本必须在代码包内',
+                    '需要在 game.json 中配置 workers 路径',
+                    '需要使用 workerScriptPath 配置'
+                ]
+            },
+            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('获取微信系统信息失败:', error);
+            }
+        }
+        return {};
+    }
+}
+
+/**
+ * 微信 Worker 封装
+ */
+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 已被终止');
+        }
+        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';
+        }
+    }
+}
 ```
 
-### 4. 获取设备信息
+## 注册适配器
 
 ```typescript
-const manager = PlatformManager.getInstance();
-if (manager.hasAdapter()) {
-    const adapter = manager.getAdapter();
-    console.log('微信设备信息:', adapter.getDeviceInfo());
+import { PlatformManager } from '@esengine/ecs-framework';
+import { WeChatMiniGameAdapter } from './platform/WeChatMiniGameAdapter';
+
+// 在游戏启动时注册适配器
+if (typeof wx !== 'undefined') {
+    const adapter = new WeChatMiniGameAdapter();
+    PlatformManager.getInstance().registerAdapter(adapter);
 }
 ```
 
 ## 官方文档参考
 
-在使用微信小游戏 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 限制
 
-微信小游戏的 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 时无需此配置，框架会自动将脚本写入临时文件。
+| 限制项 | 说明 |
+|--------|------|
+| 数量限制 | 最多只能创建 1 个 Worker |
+| 版本要求 | 需要基础库 1.9.90 及以上 |
+| 脚本位置 | 必须在代码包内，不支持动态生成 |
+| 生命周期 | 创建新 Worker 前必须先 terminate() |
 
 ### 内存限制
 
-微信小游戏有严格的内存限制：
-
 - 通常限制在 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('内存使用率过高，建议清理资源');
-                // 触发垃圾回收或资源清理
-            }
-        }
-    }
-}
+wx.onMemoryWarning(() => {
+    console.warn('收到内存警告，开始清理资源');
+    // 清理不必要的资源
+});
 ```
 
 ## 调试技巧
 
 ```typescript
-// 检查微信小游戏环境
-if (typeof wx !== 'undefined') {
-    const adapter = new WeChatMiniGameAdapter();
+// 检查 Worker 配置
+const adapter = PlatformManager.getInstance().getAdapter();
+const config = adapter.getPlatformConfig();
 
-    console.log('微信版本:', adapter.version);
-    console.log('设备信息:', adapter.getDeviceInfo());
-    console.log('平台配置:', adapter.getPlatformConfig());
-
-    // 检查功能支持
-    console.log('Worker支持:', adapter.isWorkerSupported());
-    console.log('SharedArrayBuffer支持:', adapter.isSharedArrayBufferSupported());
-}
+console.log('Worker 支持:', adapter.isWorkerSupported());
+console.log('最大 Worker 数:', config.maxWorkerCount);
+console.log('平台限制:', config.limitations);
 ```
-
-## 微信小游戏特殊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/scene-manager.md

@@ -1,4 +1,4 @@
-# SceneManager
+# SceneManager
 
 SceneManager 是 ECS Framework 提供的轻量级场景管理器，适用于 95% 的游戏应用。它提供简单直观的 API，支持场景切换和延迟加载。
 
@@ -19,6 +19,7 @@ SceneManager 适合以下场景：
 - 自动管理 ECS 流式 API
 - 自动处理场景生命周期
 - 集成在 Core 中，自动更新
+- 支持[持久化实体](./persistent-entity.md)跨场景迁移（v2.3.0+）
 
 ## 基本使用
 
@@ -672,4 +673,9 @@ setTimeout(() => {
 }, 3000);
 ```
 
-SceneManager 为大多数游戏提供了简单而强大的场景管理能力。通过 Core 的静态方法，你可以轻松地管理场景切换。如果你需要更高级的多世界隔离功能，请参考 [WorldManager](./world-manager.md) 文档。
+SceneManager 为大多数游戏提供了简单而强大的场景管理能力。通过 Core 的静态方法，你可以轻松地管理场景切换。
+
+## 相关文档
+
+- [持久化实体](./persistent-entity.md) - 了解如何让实体跨场景保持状态
+- [WorldManager](./world-manager.md) - 了解更高级的多世界隔离功能

docs/guide/scene.md

@@ -1,4 +1,4 @@
-# 场景管理
+# 场景管理
 
 在 ECS 架构中，场景（Scene）是游戏世界的容器，负责管理实体、系统和组件的生命周期。场景提供了完整的 ECS 运行环境。
 
@@ -657,5 +657,6 @@ world.setSceneActive('main', true);
 
 - 了解 [SceneManager](./scene-manager.md) - 适用于大多数游戏的简单场景管理
 - 了解 [WorldManager](./world-manager.md) - 适用于需要多世界隔离的高级场景
+- 了解 [持久化实体](./persistent-entity.md) - 让实体跨场景保持状态（v2.3.0+）
 
 场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。

docs/guide/serialization.md

@@ -14,6 +14,18 @@
 - **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 类型，所有现代浏览器都支持
+
 ## 全量序列化
 
 ### 基础用法
@@ -63,6 +75,7 @@ const binaryData = scene.serialize({
 });
 
 // 保存为文件（Node.js环境）
+// 注意：binaryData 是 Uint8Array 类型，Node.js 的 fs 可以直接写入
 fs.writeFileSync('save.bin', binaryData);
 ```
 
@@ -177,6 +190,106 @@ class CollectionsComponent extends Component {
 }
 ```
 
+### 组件继承与序列化
+
+框架完整支持组件类的继承，子类会自动继承父类的序列化字段，同时可以添加自己的字段。
+
+#### 基础继承
+
+```typescript
+// 基类组件
+@ECSComponent('Collider2DBase')
+@Serializable({ version: 1, typeId: 'Collider2DBase' })
+abstract class Collider2DBase extends Component {
+  @Serialize()
+  public friction: number = 0.5;
+
+  @Serialize()
+  public restitution: number = 0.0;
+
+  @Serialize()
+  public isTrigger: boolean = false;
+}
+
+// 子类组件 - 自动继承父类的序列化字段
+@ECSComponent('BoxCollider2D')
+@Serializable({ version: 1, typeId: 'BoxCollider2D' })
+class BoxCollider2DComponent extends Collider2DBase {
+  @Serialize()
+  public width: number = 1.0;
+
+  @Serialize()
+  public height: number = 1.0;
+}
+
+// 另一个子类组件
+@ECSComponent('CircleCollider2D')
+@Serializable({ version: 1, typeId: 'CircleCollider2D' })
+class CircleCollider2DComponent extends Collider2DBase {
+  @Serialize()
+  public radius: number = 0.5;
+}
+```
+
+#### 继承规则
+
+1. **字段继承**：子类自动继承父类所有被 `@Serialize()` 标记的字段
+2. **独立元数据**：每个子类维护独立的序列化元数据，修改子类不会影响父类或其他子类
+3. **typeId 区分**：使用 `typeId` 选项为每个类指定唯一标识，确保反序列化时能正确识别组件类型
+
+#### 使用 typeId 的重要性
+
+当使用组件继承时，**强烈建议**为每个类设置唯一的 `typeId`：
+
+```typescript
+// ✅ 推荐：明确指定 typeId
+@Serializable({ version: 1, typeId: 'BoxCollider2D' })
+class BoxCollider2DComponent extends Collider2DBase { }
+
+@Serializable({ version: 1, typeId: 'CircleCollider2D' })
+class CircleCollider2DComponent extends Collider2DBase { }
+
+// ⚠️ 不推荐：依赖类名作为 typeId
+// 在代码压缩后类名可能变化，导致反序列化失败
+@Serializable({ version: 1 })
+class BoxCollider2DComponent extends Collider2DBase { }
+```
+
+#### 子类覆盖父类字段
+
+子类可以重新声明父类的字段以修改其序列化选项：
+
+```typescript
+@ECSComponent('SpecialCollider')
+@Serializable({ version: 1, typeId: 'SpecialCollider' })
+class SpecialColliderComponent extends Collider2DBase {
+  // 覆盖父类字段，使用不同的别名
+  @Serialize({ alias: 'fric' })
+  public override friction: number = 0.8;
+
+  @Serialize()
+  public specialProperty: string = '';
+}
+```
+
+#### 忽略继承的字段
+
+使用 `@IgnoreSerialization()` 可以在子类中忽略从父类继承的字段：
+
+```typescript
+@ECSComponent('TriggerOnly')
+@Serializable({ version: 1, typeId: 'TriggerOnly' })
+class TriggerOnlyCollider extends Collider2DBase {
+  // 忽略父类的 friction 和 restitution 字段
+  // 因为 Trigger 不需要物理材质属性
+  @IgnoreSerialization()
+  public override friction: number = 0;
+
+  @IgnoreSerialization()
+  public override restitution: number = 0;
+}
+```
+
 ### 场景自定义数据
 
 除了实体和组件，还可以序列化场景级别的配置数据：
@@ -285,7 +398,7 @@ otherScene.applyIncremental(incremental);
 const jsonData = IncrementalSerializer.serializeIncremental(incremental, { format: 'json' });
 otherScene.applyIncremental(jsonData);
 
-// 从二进制Buffer应用
+// 从二进制Uint8Array应用
 const binaryData = IncrementalSerializer.serializeIncremental(incremental, { format: 'binary' });
 otherScene.applyIncremental(binaryData);
 ```
@@ -552,9 +665,9 @@ class NetworkSync {
   }
 
   private receiveIncremental(data: ArrayBuffer): void {
-    // 直接应用二进制数据
-    const buffer = Buffer.from(data);
-    this.scene.applyIncremental(buffer);
+    // 直接应用二进制数据（ArrayBuffer 转 Uint8Array）
+    const uint8Array = new Uint8Array(data);
+    this.scene.applyIncremental(uint8Array);
   }
 }
 ```
@@ -790,7 +903,7 @@ class LargeDataComponent extends Component {
 
 - [`Scene.createIncrementalSnapshot()`](/api/classes/Scene#createincrementalsnapshot) - 创建基础快照
 - [`Scene.serializeIncremental()`](/api/classes/Scene#serializeincremental) - 获取增量变更
-- [`Scene.applyIncremental()`](/api/classes/Scene#applyincremental) - 应用增量变更（支持IncrementalSnapshot对象、JSON字符串或二进制Buffer）
+- [`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) - 检查是否有快照

docs/guide/service-container.md

@@ -33,6 +33,26 @@ class MyService implements IService {
 }
 ```
 
+#### 服务标识符（ServiceIdentifier）
+
+服务标识符用于在容器中唯一标识一个服务，支持两种类型：
+
+- **类构造函数**: 直接使用服务类作为标识符，适用于具体实现类
+- **Symbol**: 使用 Symbol 作为标识符，适用于接口抽象（推荐用于插件和跨包场景）
+
+```typescript
+// 方式1: 使用类作为标识符
+Core.services.registerSingleton(DataService);
+const data = Core.services.resolve(DataService);
+
+// 方式2: 使用 Symbol 作为标识符（推荐用于接口）
+const IFileSystem = Symbol.for('IFileSystem');
+Core.services.registerInstance(IFileSystem, new TauriFileSystem());
+const fs = Core.services.resolve<IFileSystem>(IFileSystem);
+```
+
+> **提示**: 使用 `Symbol.for()` 而非 `Symbol()` 可确保跨包/跨模块共享同一个标识符。详见[高级用法 - 接口与 Symbol 标识符模式](#接口与-symbol-标识符模式)。
+
 #### 生命周期
 
 服务容器支持两种生命周期：
@@ -44,7 +64,13 @@ class MyService implements IService {
 
 ### 访问服务容器
 
-Core 类内置了服务容器，可以通过 `Core.services` 访问：
+ECS Framework 提供了三级服务容器：
+
+> **版本说明**：World 服务容器功能在 v2.2.13+ 版本中可用
+
+#### Core 级别服务容器
+
+应用程序全局服务容器，可以通过 `Core.services` 访问：
 
 ```typescript
 import { Core } from '@esengine/ecs-framework';
@@ -52,10 +78,53 @@ import { Core } from '@esengine/ecs-framework';
 // 初始化Core
 Core.create({ debug: true });
 
-// 访问服务容器
+// 访问全局服务容器
 const container = Core.services;
 ```
 
+#### World 级别服务容器
+
+每个 World 拥有独立的服务容器，用于管理 World 范围内的服务：
+
+```typescript
+import { World } from '@esengine/ecs-framework';
+
+// 创建 World
+const world = new World({ name: 'GameWorld' });
+
+// 访问 World 级别的服务容器
+const worldContainer = world.services;
+
+// 注册 World 级别的服务
+world.services.registerSingleton(RoomManager);
+```
+
+#### Scene 级别服务容器
+
+每个 Scene 拥有独立的服务容器，用于管理 Scene 范围内的服务：
+
+```typescript
+// 访问 Scene 级别的服务容器
+const sceneContainer = scene.services;
+
+// 注册 Scene 级别的服务
+scene.services.registerSingleton(PhysicsSystem);
+```
+
+#### 服务容器层级
+
+```
+Core.services (应用程序全局)
+  └─ World.services (World 级别)
+      └─ Scene.services (Scene 级别)
+```
+
+不同级别的服务容器是独立的，服务不会自动向上或向下查找。选择合适的容器级别：
+
+- **Core.services**: 应用程序级别的全局服务（配置、插件管理器等）
+- **World.services**: World 级别的服务（房间管理器、多人游戏状态等）
+- **Scene.services**: Scene 级别的服务（ECS 系统、场景特定逻辑等）
+
 ### 注册服务
 
 #### 注册单例服务
@@ -284,21 +353,20 @@ class GameService implements IService {
 }
 ```
 
-### @Inject 装饰器
+### @InjectProperty 装饰器
 
-在构造函数中注入依赖：
+通过属性装饰器注入依赖。注入时机是在构造函数执行后、`onInitialize()` 调用前完成：
 
 ```typescript
-import { Injectable, Inject, IService } from '@esengine/ecs-framework';
+import { Injectable, InjectProperty, IService } from '@esengine/ecs-framework';
 
 @Injectable()
 class PlayerService implements IService {
-    constructor(
-        @Inject(DataService) private data: DataService,
-        @Inject(GameService) private game: GameService
-    ) {
-        // data 和 game 会自动从容器中解析
-    }
+    @InjectProperty(DataService)
+    private data!: DataService;
+
+    @InjectProperty(GameService)
+    private game!: GameService;
 
     dispose(): void {
         // 清理资源
@@ -306,6 +374,35 @@ class PlayerService implements IService {
 }
 ```
 
+在 EntitySystem 中使用属性注入：
+
+```typescript
+@Injectable()
+class CombatSystem extends EntitySystem {
+    @InjectProperty(TimeService)
+    private timeService!: TimeService;
+
+    @InjectProperty(AudioService)
+    private audio!: AudioService;
+
+    constructor() {
+        super(Matcher.all(Health, Attack));
+    }
+
+    onInitialize(): void {
+        // 此时属性已注入完成，可以安全使用
+        console.log('Delta time:', this.timeService.getDeltaTime());
+    }
+
+    processEntity(entity: Entity): void {
+        // 使用注入的服务
+        this.audio.playSound('attack');
+    }
+}
+```
+
+> **注意**: 属性声明时使用 `!` 断言（如 `private data!: DataService`），表示该属性会在使用前被注入。
+
 ### 注册可注入服务
 
 使用 `registerInjectable` 自动处理依赖注入：
@@ -313,10 +410,10 @@ class PlayerService implements IService {
 ```typescript
 import { registerInjectable } from '@esengine/ecs-framework';
 
-// 注册服务（会自动解析@Inject依赖）
+// 注册服务（会自动解析 @InjectProperty 依赖）
 registerInjectable(Core.services, PlayerService);
 
-// 解析时会自动注入依赖
+// 解析时会自动注入属性依赖
 const player = Core.services.resolve(PlayerService);
 ```
 
@@ -444,22 +541,164 @@ registerInjectable(Core.services, NetworkService);
 
 ## 高级用法
 
-### 服务替换（测试）
+### 接口与 Symbol 标识符模式
 
-在测试中替换真实服务为模拟服务：
+在大型项目或需要跨平台适配的游戏中，推荐使用"接口 + Symbol.for 标识符"模式。这种模式实现了真正的依赖倒置，让代码依赖于抽象而非具体实现。
+
+#### 为什么使用 Symbol.for
+
+- **跨包共享**: `Symbol.for('key')` 在全局 Symbol 注册表中创建/获取 Symbol，确保不同包中使用相同的标识符
+- **接口解耦**: 消费者只依赖接口定义，不依赖具体实现类
+- **可替换实现**: 可以在运行时注入不同的实现（如测试 Mock、不同平台适配）
+
+#### 定义接口和标识符
+
+以音频服务为例，游戏需要在不同平台（Web、微信小游戏、原生App）使用不同的音频实现：
 
 ```typescript
-// 测试代码
-class MockDataService implements IService {
-    getData(key: string) {
-        return 'mock data';
-    }
-
-    dispose(): void {}
+// IAudioService.ts - 定义接口和标识符
+export interface IAudioService {
+    dispose(): void;
+    playSound(id: string): void;
+    playMusic(id: string, loop?: boolean): void;
+    stopMusic(): void;
+    setVolume(volume: number): void;
+    preload(id: string, url: string): Promise<void>;
 }
 
-// 注册模拟服务（用于测试）
-Core.services.registerInstance(DataService, new MockDataService());
+// 使用 Symbol.for 确保跨包共享同一个 Symbol
+export const IAudioService = Symbol.for('IAudioService');
+```
+
+#### 实现接口
+
+```typescript
+// WebAudioService.ts - Web 平台实现
+import { IAudioService } from './IAudioService';
+
+export class WebAudioService implements IAudioService {
+    private audioContext: AudioContext;
+    private sounds: Map<string, AudioBuffer> = new Map();
+
+    constructor() {
+        this.audioContext = new AudioContext();
+    }
+
+    playSound(id: string): void {
+        const buffer = this.sounds.get(id);
+        if (buffer) {
+            const source = this.audioContext.createBufferSource();
+            source.buffer = buffer;
+            source.connect(this.audioContext.destination);
+            source.start();
+        }
+    }
+
+    async preload(id: string, url: string): Promise<void> {
+        const response = await fetch(url);
+        const arrayBuffer = await response.arrayBuffer();
+        const audioBuffer = await this.audioContext.decodeAudioData(arrayBuffer);
+        this.sounds.set(id, audioBuffer);
+    }
+
+    // ... 其他方法实现
+
+    dispose(): void {
+        this.audioContext.close();
+        this.sounds.clear();
+    }
+}
+```
+
+```typescript
+// WechatAudioService.ts - 微信小游戏平台实现
+export class WechatAudioService implements IAudioService {
+    private innerAudioContexts: Map<string, WechatMinigame.InnerAudioContext> = new Map();
+
+    playSound(id: string): void {
+        const ctx = this.innerAudioContexts.get(id);
+        if (ctx) {
+            ctx.play();
+        }
+    }
+
+    async preload(id: string, url: string): Promise<void> {
+        const ctx = wx.createInnerAudioContext();
+        ctx.src = url;
+        this.innerAudioContexts.set(id, ctx);
+    }
+
+    // ... 其他方法实现
+
+    dispose(): void {
+        for (const ctx of this.innerAudioContexts.values()) {
+            ctx.destroy();
+        }
+        this.innerAudioContexts.clear();
+    }
+}
+```
+
+#### 注册和使用
+
+```typescript
+import { IAudioService } from './IAudioService';
+import { WebAudioService } from './WebAudioService';
+import { WechatAudioService } from './WechatAudioService';
+
+// 根据平台注册不同实现
+if (typeof wx !== 'undefined') {
+    Core.services.registerInstance(IAudioService, new WechatAudioService());
+} else {
+    Core.services.registerInstance(IAudioService, new WebAudioService());
+}
+
+// 业务代码中使用 - 不关心具体实现
+const audio = Core.services.resolve<IAudioService>(IAudioService);
+await audio.preload('explosion', '/sounds/explosion.mp3');
+audio.playSound('explosion');
+```
+
+#### 跨模块使用
+
+```typescript
+// 在游戏系统中使用
+import { IAudioService } from '@mygame/core';
+
+class CombatSystem extends EntitySystem {
+    private audio: IAudioService;
+
+    initialize(): void {
+        // 获取音频服务，不需要知道具体实现
+        this.audio = this.scene.services.resolve<IAudioService>(IAudioService);
+    }
+
+    onEntityDeath(entity: Entity): void {
+        this.audio.playSound('death');
+    }
+}
+```
+
+#### Symbol vs Symbol.for
+
+```typescript
+// Symbol() - 每次创建唯一的 Symbol
+const sym1 = Symbol('test');
+const sym2 = Symbol('test');
+console.log(sym1 === sym2); // false - 不同的 Symbol
+
+// Symbol.for() - 在全局注册表中共享
+const sym3 = Symbol.for('test');
+const sym4 = Symbol.for('test');
+console.log(sym3 === sym4); // true - 同一个 Symbol
+
+// 跨包场景
+// package-a/index.ts
+export const IMyService = Symbol.for('IMyService');
+
+// package-b/index.ts (不同的包)
+const IMyService = Symbol.for('IMyService');
+// 与 package-a 中的是同一个 Symbol！
 ```
 
 ### 循环依赖检测

docs/guide/system.md

@@ -1,4 +1,4 @@
-# 系统架构
+# 系统架构
 
 在 ECS 架构中，系统（System）是处理业务逻辑的地方。系统负责对拥有特定组件组合的实体执行操作，是 ECS 架构的逻辑处理单元。
 
@@ -157,8 +157,45 @@ const nameMatcher = Matcher.byName("Player"); // 匹配名称为 "Player" 的实
 
 // 单组件匹配
 const componentMatcher = Matcher.byComponent(Health); // 匹配拥有 Health 组件的实体
+
+// 不匹配任何实体
+const nothingMatcher = Matcher.nothing(); // 用于只需要生命周期回调的系统
 ```
 
+### 空匹配器 vs Nothing 匹配器
+
+```typescript
+// empty() - 空条件，匹配所有实体
+const emptyMatcher = Matcher.empty();
+
+// nothing() - 不匹配任何实体，用于只需要生命周期方法的系统
+const nothingMatcher = Matcher.nothing();
+
+// 使用场景：只需要 onBegin/onEnd 生命周期的系统
+@ECSSystem('FrameTimer')
+class FrameTimerSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.nothing()); // 不处理任何实体
+  }
+
+  protected onBegin(): void {
+    // 每帧开始时执行，例如：记录帧开始时间
+    console.log('帧开始');
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    // 永远不会被调用，因为没有匹配的实体
+  }
+
+  protected onEnd(): void {
+    // 每帧结束时执行
+    console.log('帧结束');
+  }
+}
+```
+
+> 💡 **提示**：更多关于 Matcher 和实体查询的详细用法，请参考 [实体查询系统](/guide/entity-query) 文档。
+
 ## 系统生命周期
 
 系统提供了完整的生命周期回调：
@@ -179,11 +216,13 @@ class ExampleSystem extends EntitySystem {
     // 主要的处理逻辑
     for (const entity of entities) {
       // 处理每个实体
+      // ✅ 可以安全地在这里添加/移除组件，不会影响当前迭代
     }
   }
 
   protected lateProcess(entities: readonly Entity[]): void {
     // 主处理之后的后期处理
+    // ✅ 可以安全地在这里添加/移除组件，不会影响当前迭代
   }
 
   protected onEnd(): void {
@@ -233,6 +272,172 @@ class EnemyManagerSystem extends EntitySystem {
 }
 ```
 
+### 重要：onAdded/onRemoved 的调用时机
+
+> ⚠️ **注意**：`onAdded` 和 `onRemoved` 回调是**同步调用**的，会在 `addComponent`/`removeComponent` 返回**之前**立即执行。
+
+这意味着：
+
+```typescript
+// ❌ 错误的用法：链式赋值在 onAdded 之后才执行
+const comp = entity.addComponent(new ClickComponent());
+comp.element = this._element;  // 此时 onAdded 已经执行完了！
+
+// ✅ 正确的用法：通过构造函数传入初始值
+const comp = entity.addComponent(new ClickComponent(this._element));
+
+// ✅ 或者使用 createComponent 方法
+const comp = entity.createComponent(ClickComponent, this._element);
+```
+
+**为什么这样设计？**
+
+事件驱动设计确保 `onAdded`/`onRemoved` 回调不受系统注册顺序的影响。当组件被添加时，所有监听该组件的系统都会立即收到通知，而不是等到下一帧。
+
+**最佳实践：**
+
+1. 组件的初始值应该通过**构造函数**传入
+2. 不要依赖 `addComponent` 返回后再设置属性
+3. 如果需要在 `onAdded` 中访问组件属性，确保这些属性在构造时已经设置
+
+### 在 process/lateProcess 中安全地修改组件
+
+在 `process` 或 `lateProcess` 中迭代实体时，可以安全地添加或移除组件，不会影响当前的迭代过程：
+
+```typescript
+@ECSSystem('Damage')
+class DamageSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Health, DamageReceiver));
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health);
+      const damage = entity.getComponent(DamageReceiver);
+
+      if (health && damage) {
+        health.current -= damage.amount;
+
+        // ✅ 安全：移除组件不会影响当前迭代
+        entity.removeComponent(damage);
+
+        if (health.current <= 0) {
+          // ✅ 安全：添加组件也不会影响当前迭代
+          entity.addComponent(new Dead());
+        }
+      }
+    }
+  }
+}
+```
+
+框架会在每次 `process`/`lateProcess` 调用前创建实体列表的快照，确保迭代过程中的组件变化不会导致跳过实体或重复处理。
+
+## 命令缓冲区 (CommandBuffer)
+
+> **v2.3.0+**
+
+CommandBuffer 提供了一种延迟执行实体操作的机制。当你需要在迭代过程中销毁实体或进行其他可能影响迭代的操作时，使用 CommandBuffer 可以将这些操作推迟到帧末统一执行。
+
+### 基本用法
+
+每个 EntitySystem 都内置了 `commands` 属性：
+
+```typescript
+@ECSSystem('Damage')
+class DamageSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Health, DamageReceiver));
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health);
+      const damage = entity.getComponent(DamageReceiver);
+
+      if (health && damage) {
+        health.current -= damage.amount;
+
+        // 使用命令缓冲区延迟移除组件
+        this.commands.removeComponent(entity, DamageReceiver);
+
+        if (health.current <= 0) {
+          // 延迟添加死亡标记
+          this.commands.addComponent(entity, new Dead());
+          // 延迟销毁实体
+          this.commands.destroyEntity(entity);
+        }
+      }
+    }
+  }
+}
+```
+
+### 支持的命令
+
+| 方法 | 说明 |
+|------|------|
+| `addComponent(entity, component)` | 延迟添加组件 |
+| `removeComponent(entity, ComponentType)` | 延迟移除组件 |
+| `destroyEntity(entity)` | 延迟销毁实体 |
+| `setEntityActive(entity, active)` | 延迟设置实体激活状态 |
+
+### 执行时机
+
+命令缓冲区中的命令会在每帧的 `lateUpdate` 阶段之后自动执行。执行顺序与命令入队顺序一致。
+
+```
+场景更新流程:
+1. onBegin()
+2. process()
+3. lateProcess()
+4. onEnd()
+5. flushCommandBuffers()  <-- 命令在这里执行
+```
+
+### 使用场景
+
+CommandBuffer 适用于以下场景：
+
+1. **在迭代中销毁实体**：避免修改正在遍历的集合
+2. **批量延迟操作**：将多个操作合并到帧末执行
+3. **跨系统协调**：一个系统标记，另一个系统响应
+
+```typescript
+// 示例：敌人死亡系统
+@ECSSystem('EnemyDeath')
+class EnemyDeathSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Enemy, Health));
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health);
+      if (health && health.current <= 0) {
+        // 播放死亡动画、掉落物品等
+        this.spawnLoot(entity);
+
+        // 延迟销毁，不影响当前迭代
+        this.commands.destroyEntity(entity);
+      }
+    }
+  }
+
+  private spawnLoot(entity: Entity): void {
+    // 掉落物品逻辑
+  }
+}
+```
+
+### 注意事项
+
+- 命令会跳过已销毁的实体（安全检查）
+- 单个命令执行失败不会影响其他命令
+- 命令按入队顺序执行
+- 每次 `flush()` 后命令队列会清空
+
 ## 系统属性和方法
 
 ### 重要属性
@@ -420,6 +625,8 @@ class GameScene extends Scene {
 
 ### 系统更新顺序
 
+系统的执行顺序由 `updateOrder` 属性决定，数值越小越先执行：
+
 ```typescript
 @ECSSystem('Input')
 class InputSystem extends EntitySystem {
@@ -446,6 +653,262 @@ class RenderSystem extends EntitySystem {
 }
 ```
 
+#### 稳定排序：addOrder
+
+当多个系统的 `updateOrder` 相同时，框架使用 `addOrder`（添加顺序）作为第二排序条件，确保排序结果稳定可预测：
+
+```typescript
+// 这两个系统 updateOrder 都是默认值 0
+@ECSSystem('SystemA')
+class SystemA extends EntitySystem { /* ... */ }
+
+@ECSSystem('SystemB')
+class SystemB extends EntitySystem { /* ... */ }
+
+// 添加顺序决定了执行顺序
+scene.addSystem(new SystemA()); // addOrder = 0，先执行
+scene.addSystem(new SystemB()); // addOrder = 1，后执行
+```
+
+> **注意**：`addOrder` 由框架在 `addSystem` 时自动设置，无需手动管理。这确保了相同 `updateOrder` 的系统按照添加顺序执行，避免了排序不稳定导致的随机行为。
+
+## 声明式系统调度
+
+> **v2.4.0+**
+
+除了使用 `updateOrder` 手动控制执行顺序外，框架还提供了声明式的系统调度机制，让你可以通过依赖关系来定义系统的执行顺序。
+
+### 调度装饰器
+
+```typescript
+import { EntitySystem, ECSSystem, Stage, Before, After, InSet } from '@esengine/ecs-framework';
+
+// 使用装饰器声明系统调度
+@ECSSystem('Movement')
+@Stage('update')           // 在 update 阶段执行
+@After('InputSystem')      // 在 InputSystem 之后执行
+@Before('RenderSystem')    // 在 RenderSystem 之前执行
+class MovementSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(Position, Velocity));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 移动逻辑
+    }
+}
+
+// 使用系统集合进行分组
+@ECSSystem('Physics')
+@Stage('update')
+@InSet('CoreSystems')      // 属于 CoreSystems 集合
+class PhysicsSystem extends EntitySystem {
+    // ...
+}
+
+@ECSSystem('Collision')
+@Stage('update')
+@After('set:CoreSystems')  // 在 CoreSystems 集合的所有系统之后执行
+class CollisionSystem extends EntitySystem {
+    // ...
+}
+```
+
+### 系统执行阶段
+
+框架定义了以下系统执行阶段，按顺序执行：
+
+| 阶段 | 说明 | 典型用途 |
+|------|------|----------|
+| `startup` | 启动阶段 | 一次性初始化 |
+| `preUpdate` | 更新前阶段 | 输入处理、状态准备 |
+| `update` | 主更新阶段（默认） | 核心游戏逻辑 |
+| `postUpdate` | 更新后阶段 | 物理、碰撞检测 |
+| `cleanup` | 清理阶段 | 资源清理、状态重置 |
+
+### Fluent API 配置
+
+如果不想使用装饰器，也可以使用 Fluent API 在运行时配置调度：
+
+```typescript
+@ECSSystem('Movement')
+class MovementSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(Position, Velocity));
+
+        // 使用 Fluent API 配置调度
+        this.stage('update')
+            .after('InputSystem')
+            .before('RenderSystem')
+            .inSet('CoreSystems');
+    }
+}
+```
+
+### 循环依赖检测
+
+框架会自动检测循环依赖并抛出明确的错误：
+
+```typescript
+// 这会导致循环依赖错误
+@ECSSystem('SystemA')
+@Before('SystemB')
+class SystemA extends EntitySystem { }
+
+@ECSSystem('SystemB')
+@Before('SystemA')  // 错误：A -> B -> A 形成循环
+class SystemB extends EntitySystem { }
+
+// 错误信息：Cyclic dependency detected: SystemA -> SystemB -> SystemA
+```
+
+## 帧级变更检测
+
+> **v2.4.0+**
+
+框架提供了基于 epoch 的帧级变更检测机制，让系统可以只处理发生变化的实体，大幅提升性能。
+
+### 核心概念
+
+- **Epoch**：全局帧计数器，每帧递增
+- **lastWriteEpoch**：组件最后被修改时的 epoch
+- **变更检测**：通过比较 epoch 判断组件是否在指定时间点后发生变化
+
+### 标记组件为已修改
+
+修改组件数据后，需要标记组件为已变更。有两种方式：
+
+**方式 1：通过 Entity 辅助方法（推荐）**
+
+```typescript
+// 修改组件后通过 entity.markDirty() 标记
+const pos = entity.getComponent(Position)!;
+pos.x = 100;
+pos.y = 200;
+entity.markDirty(pos);
+
+// 可以同时标记多个组件
+const vel = entity.getComponent(Velocity)!;
+vel.vx = 10;
+entity.markDirty(pos, vel);
+```
+
+**方式 2：在组件内部封装**
+
+```typescript
+class VelocityComponent extends Component {
+    private _vx: number = 0;
+    private _vy: number = 0;
+
+    // 提供修改方法，接收 epoch 参数
+    public setVelocity(vx: number, vy: number, epoch: number): void {
+        this._vx = vx;
+        this._vy = vy;
+        this.markDirty(epoch);
+    }
+
+    public get vx(): number { return this._vx; }
+    public get vy(): number { return this._vy; }
+}
+
+// 在系统中使用
+const vel = entity.getComponent(VelocityComponent)!;
+vel.setVelocity(10, 20, this.currentEpoch);
+```
+
+### 在系统中使用变更检测
+
+EntitySystem 提供了多个变更检测辅助方法：
+
+```typescript
+@ECSSystem('Physics')
+class PhysicsSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(Position, Velocity));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 方式1：使用 forEachChanged 只处理变更的实体
+        // 自动保存 epoch 检查点
+        this.forEachChanged(entities, [Velocity], (entity) => {
+            const pos = this.requireComponent(entity, Position);
+            const vel = this.requireComponent(entity, Velocity);
+
+            // 只有 Velocity 变化时才更新位置
+            pos.x += vel.vx * Time.deltaTime;
+            pos.y += vel.vy * Time.deltaTime;
+        });
+    }
+}
+
+@ECSSystem('Transform')
+class TransformSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(Transform, RigidBody));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 方式2：使用 filterChanged 获取变更的实体列表
+        const changedEntities = this.filterChanged(entities, [RigidBody]);
+
+        for (const entity of changedEntities) {
+            // 处理物理状态变化的实体
+            this.updatePhysics(entity);
+        }
+
+        // 手动保存 epoch 检查点
+        this.saveEpoch();
+    }
+
+    protected updatePhysics(entity: Entity): void {
+        // 物理更新逻辑
+    }
+}
+```
+
+### 变更检测 API 参考
+
+| 方法 | 说明 |
+|------|------|
+| `forEachChanged(entities, [Types], callback)` | 遍历指定组件发生变更的实体，自动保存检查点 |
+| `filterChanged(entities, [Types])` | 返回指定组件发生变更的实体数组 |
+| `hasChanged(entity, [Types])` | 检查单个实体的指定组件是否发生变更 |
+| `saveEpoch()` | 手动保存当前 epoch 作为检查点 |
+| `lastProcessEpoch` | 获取上次保存的 epoch 检查点 |
+| `currentEpoch` | 获取当前场景的 epoch |
+
+### 使用场景
+
+变更检测特别适合以下场景：
+
+1. **脏标记优化**：只在数据变化时更新渲染
+2. **物理同步**：只同步位置/速度发生变化的实体
+3. **网络同步**：只发送变化的组件数据
+4. **缓存失效**：只在依赖数据变化时重新计算
+
+```typescript
+@ECSSystem('NetworkSync')
+class NetworkSyncSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(NetworkComponent, Transform));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只同步变化的实体，大幅减少网络流量
+        this.forEachChanged(entities, [Transform], (entity) => {
+            const transform = this.requireComponent(entity, Transform);
+            const network = this.requireComponent(entity, NetworkComponent);
+
+            this.sendTransformUpdate(network.id, transform);
+        });
+    }
+
+    private sendTransformUpdate(id: string, transform: Transform): void {
+        // 发送网络更新
+    }
+}
+```
+
 ## 复杂系统示例
 
 ### 碰撞检测系统
@@ -563,9 +1026,28 @@ class GameSystem extends EntitySystem {
 }
 ```
 
-### 2. 使用装饰器
+### 2. 使用 @ECSSystem 装饰器
 
-**必须使用 `@ECSSystem` 装饰器**：
+`@ECSSystem` 是系统类必须使用的装饰器，它为系统提供类型标识和元数据管理。
+
+#### 为什么必须使用
+
+| 功能 | 说明 |
+|------|------|
+| **类型识别** | 提供稳定的系统名称，代码混淆后仍能正确识别 |
+| **调试支持** | 在性能监控、日志和调试工具中显示可读的系统名称 |
+| **系统管理** | 通过名称查找和管理系统 |
+| **序列化支持** | 场景序列化时可以记录系统配置 |
+
+#### 基本语法
+
+```typescript
+@ECSSystem(systemName: string)
+```
+
+- `systemName`: 系统的名称，建议使用描述性的名称
+
+#### 使用示例
 
 ```typescript
 // ✅ 正确的用法
@@ -574,12 +1056,41 @@ class PhysicsSystem extends EntitySystem {
   // 系统实现
 }
 
+// ✅ 推荐：使用描述性的名称
+@ECSSystem('PlayerMovement')
+class PlayerMovementSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Player, Position, Velocity));
+  }
+}
+
 // ❌ 错误的用法 - 没有装饰器
 class BadSystem extends EntitySystem {
-  // 这样定义的系统可能在生产环境出现问题
+  // 这样定义的系统可能在生产环境出现问题：
+  // 1. 代码压缩后类名变化，无法正确识别
+  // 2. 性能监控和调试工具显示不正确的名称
 }
 ```
 
+#### 系统名称的作用
+
+```typescript
+@ECSSystem('Combat')
+class CombatSystem extends EntitySystem {
+  protected onInitialize(): void {
+    // 使用 systemName 属性访问系统名称
+    console.log(`系统 ${this.systemName} 已初始化`);  // 输出: 系统 Combat 已初始化
+  }
+}
+
+// 通过名称查找系统
+const combat = scene.getSystemByName('Combat');
+
+// 性能监控中会显示系统名称
+const perfData = combatSystem.getPerformanceData();
+console.log(`${combatSystem.systemName} 执行时间: ${perfData?.executionTime}ms`);
+```
+
 ### 3. 合理的更新顺序
 
 ```typescript
@@ -647,4 +1158,4 @@ class ResourceSystem extends EntitySystem {
 }
 ```
 
-系统是 ECS 架构的逻辑处理核心，正确设计和使用系统能让你的游戏代码更加模块化、高效和易于维护。
+系统是 ECS 架构的逻辑处理核心，正确设计和使用系统能让你的游戏代码更加模块化、高效和易于维护。

docs/guide/time-and-timers.md

@@ -30,6 +30,64 @@ class GameSystem extends EntitySystem {
 }
 ```
 
+### 游戏暂停
+
+框架提供两种暂停方式，适用于不同场景：
+
+#### Core.paused（推荐）
+
+`Core.paused` 是**真正的暂停**，设置后整个游戏循环停止：
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+
+class PauseMenuSystem extends EntitySystem {
+  public pauseGame(): void {
+    // 真正暂停 - 所有系统停止执行
+    Core.paused = true;
+    console.log('游戏已暂停');
+  }
+
+  public resumeGame(): void {
+    // 恢复游戏
+    Core.paused = false;
+    console.log('游戏已恢复');
+  }
+
+  public togglePause(): void {
+    Core.paused = !Core.paused;
+    console.log(Core.paused ? '游戏已暂停' : '游戏已恢复');
+  }
+}
+```
+
+#### Time.timeScale = 0
+
+`Time.timeScale = 0` 只是让 `deltaTime` 变为 0，**系统仍然在执行**：
+
+```typescript
+class SlowMotionSystem extends EntitySystem {
+  public freezeTime(): void {
+    // 时间冻结 - 系统仍在执行，只是 deltaTime = 0
+    Time.timeScale = 0;
+  }
+}
+```
+
+#### 两种方式对比
+
+| 特性 | `Core.paused = true` | `Time.timeScale = 0` |
+|------|---------------------|---------------------|
+| 系统执行 | ❌ 完全停止 | ✅ 仍在执行 |
+| CPU 开销 | 零 | 正常开销 |
+| Time 更新 | ❌ 停止 | ✅ 继续（deltaTime=0） |
+| 定时器 | ❌ 停止 | ✅ 继续（但时间不走） |
+| 适用场景 | 暂停菜单、游戏暂停 | 慢动作、时间冻结特效 |
+
+**推荐**：
+- 暂停菜单、真正的游戏暂停 → 使用 `Core.paused = true`
+- 慢动作、子弹时间等特效 → 使用 `Time.timeScale`
+
 ### 时间缩放
 
 Time 类支持时间缩放功能，可以实现慢动作、快进等效果：
@@ -48,10 +106,10 @@ class TimeControlSystem extends EntitySystem {
     console.log('快进模式启用');
   }
 
-  public pauseGame(): void {
-    // 暂停游戏（时间静止）
-    Time.timeScale = 0;
-    console.log('游戏暂停');
+  public enableBulletTime(): void {
+    // 子弹时间效果（10%速度）
+    Time.timeScale = 0.1;
+    console.log('子弹时间启用');
   }
 
   public resumeNormalSpeed(): void {

docs/guide/worker-system.md

@@ -145,6 +145,8 @@ interface WorkerSystemConfig {
   entityDataSize?: number;
   /** 最大实体数量（用于预分配SharedArrayBuffer） */
   maxEntities?: number;
+  /** 预编译的Worker脚本路径（用于微信小游戏等不支持动态脚本的平台） */
+  workerScriptPath?: string;
 }
 ```
 
@@ -605,4 +607,166 @@ public getPerformanceMetrics(): WorkerPerformanceMetrics {
 - SharedArrayBuffer优化
 - 大量实体的并行处理
 
+## 微信小游戏支持
+
+微信小游戏对 Worker 有特殊限制，不支持动态创建 Worker 脚本。ESEngine 提供了 `@esengine/worker-generator` CLI 工具来解决这个问题。
+
+### 微信小游戏 Worker 限制
+
+| 特性 | 浏览器 | 微信小游戏 |
+|------|--------|-----------|
+| 动态脚本 (Blob URL) | ✅ 支持 | ❌ 不支持 |
+| Worker 数量 | 多个 | 最多 1 个 |
+| 脚本来源 | 任意 | 必须是代码包内文件 |
+| SharedArrayBuffer | 需要 COOP/COEP | 有限支持 |
+
+### 使用 Worker Generator CLI
+
+#### 1. 安装工具
+
+```bash
+pnpm add -D @esengine/worker-generator
+```
+
+#### 2. 配置 workerScriptPath
+
+在你的 WorkerEntitySystem 子类中配置 `workerScriptPath`：
+
+```typescript
+@ECSSystem('Physics')
+class PhysicsWorkerSystem extends WorkerEntitySystem<PhysicsData> {
+  constructor() {
+    super(Matcher.all(Position, Velocity, Physics), {
+      enableWorker: true,
+      workerScriptPath: 'workers/physics-worker.js', // 指定 Worker 文件路径
+      systemConfig: {
+        gravity: 100,
+        friction: 0.95
+      }
+    });
+  }
+
+  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;
+      return entity;
+    });
+  }
+
+  // ... 其他方法
+}
+```
+
+#### 3. 生成 Worker 文件
+
+运行 CLI 工具自动提取 `workerProcess` 函数并生成兼容微信小游戏的 Worker 文件：
+
+```bash
+# 基本用法
+npx esengine-worker-gen --src ./src --wechat
+
+# 完整选项
+npx esengine-worker-gen \
+  --src ./src \           # 源码目录
+  --wechat \              # 生成微信小游戏兼容代码
+  --mapping \             # 生成 worker-mapping.json
+  --verbose               # 详细输出
+```
+
+CLI 工具会：
+1. 扫描源码目录，找到所有 `WorkerEntitySystem` 子类
+2. 读取每个类的 `workerScriptPath` 配置
+3. 提取 `workerProcess` 方法体
+4. 转换为 ES5 语法（微信小游戏兼容）
+5. 生成到配置的路径
+
+#### 4. 配置 game.json
+
+在微信小游戏的 `game.json` 中配置 workers 目录：
+
+```json
+{
+  "deviceOrientation": "portrait",
+  "workers": "workers"
+}
+```
+
+#### 5. 项目结构
+
+```
+your-game/
+├── game.js
+├── game.json           # 配置 "workers": "workers"
+├── src/
+│   └── systems/
+│       └── PhysicsSystem.ts  # workerScriptPath: 'workers/physics-worker.js'
+└── workers/
+    ├── physics-worker.js     # 自动生成
+    └── worker-mapping.json   # 自动生成
+```
+
+### 临时禁用 Worker
+
+如果需要临时禁用 Worker（例如调试时），有两种方式：
+
+#### 方式 1：配置禁用
+
+```typescript
+constructor() {
+  super(matcher, {
+    enableWorker: false, // 禁用 Worker，使用主线程处理
+    // ...
+  });
+}
+```
+
+#### 方式 2：平台适配器禁用
+
+在自定义平台适配器中返回不支持 Worker：
+
+```typescript
+class MyPlatformAdapter implements IPlatformAdapter {
+  isWorkerSupported(): boolean {
+    return false; // 返回 false 禁用 Worker
+  }
+  // ...
+}
+```
+
+### 注意事项
+
+1. **每次修改 `workerProcess` 后都需要重新运行 CLI 工具**生成新的 Worker 文件
+
+2. **Worker 函数必须是纯函数**，不能依赖 `this` 或外部变量：
+   ```typescript
+   // ✅ 正确：只使用参数
+   protected workerProcess(entities, deltaTime, config) {
+     return entities.map(e => {
+       e.y += config.gravity * deltaTime;
+       return e;
+     });
+   }
+
+   // ❌ 错误：使用 this
+   protected workerProcess(entities, deltaTime, config) {
+     return entities.map(e => {
+       e.y += this.gravity * deltaTime; // Worker 中无法访问 this
+       return e;
+     });
+   }
+   ```
+
+3. **配置数据通过 `systemConfig` 传递**，而不是类属性
+
+4. **开发者工具中的警告可以忽略**：
+   - `getNetworkType:fail not support` - 微信开发者工具内部行为
+   - `SharedArrayBuffer will require cross-origin isolation` - 开发环境警告，真机不会出现
+
 Worker系统为ECS框架提供了强大的并行计算能力，让你能够充分利用现代多核处理器的性能，为复杂的游戏逻辑和计算密集型任务提供了高效的解决方案。

docs/guide/world-manager.md

@@ -435,7 +435,7 @@ const worldManager = Core.services.resolve(WorldManager);
 // {
 //   maxWorlds: 50,
 //   autoCleanup: true,
-//   cleanupInterval: 30000  // 30 秒
+//   cleanupFrameInterval: 1800  // 间隔多少帧清理闲置 World
 // }
 ```
 

docs/index.md

@@ -1,23 +1,317 @@
 ---
-layout: home
+layout: page
+title: ESEngine - 高性能 TypeScript ECS 框架
+---
 
-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
+<ParticleHero />
 
-features:
-  - title: 高性能
-    details: 支持大规模实体处理
-  - title: 类型安全
-    details: 完整的TypeScript支持，编译时类型检查
-  - title: 模块化设计
-    details: 核心功能独立打包，支持多平台
----
+<section class="news-section">
+  <div class="news-container">
+    <div class="news-header">
+      <h2 class="news-title">快速入口</h2>
+      <a href="/guide/" class="news-more">查看文档</a>
+    </div>
+    <div class="news-grid">
+      <a href="/guide/getting-started" class="news-card">
+        <div class="news-card-image" style="background: linear-gradient(135deg, #1e3a5f 0%, #1e1e1e 100%);">
+          <div class="news-icon">
+            <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24"><path fill="#4fc1ff" d="M12 3L1 9l4 2.18v6L12 21l7-3.82v-6l2-1.09V17h2V9zm6.82 6L12 12.72L5.18 9L12 5.28zM17 16l-5 2.72L7 16v-3.73L12 15l5-2.73z"/></svg>
+          </div>
+          <span class="news-badge">快速开始</span>
+        </div>
+        <div class="news-card-content">
+          <h3>5 分钟上手 ESEngine</h3>
+          <p>从安装到创建第一个 ECS 应用，快速了解核心概念。</p>
+        </div>
+      </a>
+      <a href="/guide/behavior-tree/" class="news-card">
+        <div class="news-card-image" style="background: linear-gradient(135deg, #1e3a5f 0%, #1e1e1e 100%);">
+          <div class="news-icon">
+            <svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 24 24"><path fill="#4ec9b0" d="M12 2a2 2 0 0 1 2 2a2 2 0 0 1-2 2a2 2 0 0 1-2-2a2 2 0 0 1 2-2m3 20h-1v-7l-2-2l-2 2v7H9v-7.5l-2 2V22H6v-6l3-3l1-3.5c-.3.4-.6.7-1 1L6 9v1H4V8l5-3c.5-.3 1.1-.5 1.7-.5H11c.6 0 1.2.2 1.7.5l5 3v2h-2V9l-3 1.5c-.4-.3-.7-.6-1-1l1 3.5l3 3v6Z"/></svg>
+          </div>
+          <span class="news-badge">AI 系统</span>
+        </div>
+        <div class="news-card-content">
+          <h3>行为树可视化编辑器</h3>
+          <p>内置 AI 行为树系统，支持可视化编辑和实时调试。</p>
+        </div>
+      </a>
+    </div>
+  </div>
+</section>
+
+<section class="features-section">
+  <div class="features-container">
+    <h2 class="features-title">核心特性</h2>
+    <div class="features-grid">
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#4fc1ff" d="M13 2.05v2.02c3.95.49 7 3.85 7 7.93c0 1.45-.39 2.79-1.06 3.95l1.59 1.09A9.94 9.94 0 0 0 22 12c0-5.18-3.95-9.45-9-9.95M12 19c-3.87 0-7-3.13-7-7c0-3.53 2.61-6.43 6-6.92V2.05c-5.06.5-9 4.76-9 9.95c0 5.52 4.47 10 9.99 10c3.31 0 6.24-1.61 8.06-4.09l-1.6-1.1A7.93 7.93 0 0 1 12 19"/><path fill="#4fc1ff" d="M12 6a6 6 0 0 0-6 6c0 3.31 2.69 6 6 6a6 6 0 0 0 0-12m0 10c-2.21 0-4-1.79-4-4s1.79-4 4-4s4 1.79 4 4s-1.79 4-4 4"/></svg>
+        </div>
+        <h3 class="feature-title">高性能 ECS 架构</h3>
+        <p class="feature-desc">基于数据驱动的实体组件系统，支持大规模实体处理，缓存友好的内存布局。</p>
+        <a href="/guide/entity" class="feature-link">了解更多 →</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#569cd6" d="M3 3h18v18H3zm16.525 13.707c0-.795-.272-1.425-.816-1.89c-.544-.465-1.404-.804-2.58-1.016l-1.704-.296c-.616-.104-1.052-.26-1.308-.468c-.256-.21-.384-.468-.384-.776c0-.392.168-.7.504-.924c.336-.224.8-.336 1.392-.336c.56 0 1.008.124 1.344.372c.336.248.536.584.6 1.008h2.016c-.08-.96-.464-1.716-1.152-2.268c-.688-.552-1.6-.828-2.736-.828c-1.2 0-2.148.3-2.844.9c-.696.6-1.044 1.38-1.044 2.34c0 .76.252 1.368.756 1.824c.504.456 1.308.792 2.412.996l1.704.312c.624.12 1.068.28 1.332.48c.264.2.396.46.396.78c0 .424-.192.756-.576.996c-.384.24-.9.36-1.548.36c-.672 0-1.2-.14-1.584-.42c-.384-.28-.608-.668-.672-1.164H8.868c.048 1.016.46 1.808 1.236 2.376c.776.568 1.796.852 3.06.852c1.24 0 2.22-.292 2.94-.876c.72-.584 1.08-1.364 1.08-2.34z"/></svg>
+        </div>
+        <h3 class="feature-title">完整类型支持</h3>
+        <p class="feature-desc">100% TypeScript 编写，完整的类型定义和编译时检查，提供最佳的开发体验。</p>
+        <a href="/guide/component" class="feature-link">了解更多 →</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#4ec9b0" d="M12 2C6.5 2 2 6.5 2 12s4.5 10 10 10s10-4.5 10-10S17.5 2 12 2m0 18c-4.41 0-8-3.59-8-8s3.59-8 8-8s8 3.59 8 8s-3.59 8-8 8m-5-8l4-4v3h4v2h-4v3z"/></svg>
+        </div>
+        <h3 class="feature-title">可视化行为树</h3>
+        <p class="feature-desc">内置 AI 行为树系统，提供可视化编辑器，支持自定义节点和实时调试。</p>
+        <a href="/guide/behavior-tree/" class="feature-link">了解更多 →</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#c586c0" d="M4 6h18V4H4c-1.1 0-2 .9-2 2v11H0v3h14v-3H4zm19 2h-6c-.55 0-1 .45-1 1v10c0 .55.45 1 1 1h6c.55 0 1-.45 1-1V9c0-.55-.45-1-1-1m-1 9h-4v-7h4z"/></svg>
+        </div>
+        <h3 class="feature-title">多平台支持</h3>
+        <p class="feature-desc">支持浏览器、Node.js、微信小游戏等多平台，可与主流游戏引擎无缝集成。</p>
+        <a href="/guide/platform-adapter" class="feature-link">了解更多 →</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#dcdcaa" d="M4 3h6v2H4v14h6v2H4c-1.1 0-2-.9-2-2V5c0-1.1.9-2 2-2m9 0h6c1.1 0 2 .9 2 2v14c0 1.1-.9 2-2 2h-6v-2h6V5h-6zm-1 7h4v2h-4z"/></svg>
+        </div>
+        <h3 class="feature-title">模块化设计</h3>
+        <p class="feature-desc">核心功能独立打包，按需引入。支持自定义插件扩展，灵活适配不同项目。</p>
+        <a href="/guide/plugin-system" class="feature-link">了解更多 →</a>
+      </div>
+      <div class="feature-card">
+        <div class="feature-icon">
+          <svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 24 24"><path fill="#9cdcfe" d="M22.7 19l-9.1-9.1c.9-2.3.4-5-1.5-6.9c-2-2-5-2.4-7.4-1.3L9 6L6 9L1.6 4.7C.4 7.1.9 10.1 2.9 12.1c1.9 1.9 4.6 2.4 6.9 1.5l9.1 9.1c.4.4 1 .4 1.4 0l2.3-2.3c.5-.4.5-1.1.1-1.4"/></svg>
+        </div>
+        <h3 class="feature-title">开发者工具</h3>
+        <p class="feature-desc">内置性能监控、调试工具、序列化系统等，提供完整的开发工具链。</p>
+        <a href="/guide/logging" class="feature-link">了解更多 →</a>
+      </div>
+    </div>
+  </div>
+</section>
+
+<style scoped>
+/* 首页专用样式 | Home page specific styles */
+.news-section {
+  background: #0d0d0d;
+  padding: 64px 0;
+  border-top: 1px solid #2a2a2a;
+}
+
+.news-container {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 48px;
+}
+
+.news-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 32px;
+}
+
+.news-title {
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: #ffffff;
+  margin: 0;
+}
+
+.news-more {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px;
+  padding: 10px 20px;
+  background: #1a1a1a;
+  border: 1px solid #2a2a2a;
+  border-radius: 6px;
+  color: #a0a0a0;
+  font-size: 0.875rem;
+  font-weight: 500;
+  text-decoration: none;
+  transition: all 0.2s;
+}
+
+.news-more:hover {
+  background: #252525;
+  color: #ffffff;
+}
+
+.news-grid {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 24px;
+}
+
+.news-card {
+  display: flex;
+  background: #1f1f1f;
+  border: 1px solid #2a2a2a;
+  border-radius: 12px;
+  overflow: hidden;
+  text-decoration: none;
+  transition: all 0.2s;
+}
+
+.news-card:hover {
+  border-color: #3b9eff;
+}
+
+.news-card-image {
+  width: 200px;
+  min-height: 140px;
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  padding: 16px;
+  gap: 12px;
+}
+
+.news-icon {
+  opacity: 0.9;
+}
+
+.news-badge {
+  display: inline-block;
+  padding: 4px 12px;
+  background: transparent;
+  border: 1px solid #3a3a3a;
+  border-radius: 16px;
+  color: #a0a0a0;
+  font-size: 0.75rem;
+  font-weight: 500;
+}
+
+.news-card-content {
+  padding: 20px;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+}
+
+.news-card-content h3 {
+  font-size: 1.125rem;
+  font-weight: 600;
+  color: #ffffff;
+  margin: 0 0 8px 0;
+}
+
+.news-card-content p {
+  font-size: 0.875rem;
+  color: #707070;
+  margin: 0;
+  line-height: 1.6;
+}
+
+.features-section {
+  background: #0d0d0d;
+  padding: 64px 0;
+}
+
+.features-container {
+  max-width: 1400px;
+  margin: 0 auto;
+  padding: 0 48px;
+}
+
+.features-title {
+  font-size: 1.5rem;
+  font-weight: 700;
+  color: #ffffff;
+  margin: 0 0 32px 0;
+}
+
+.features-grid {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  gap: 20px;
+}
+
+.feature-card {
+  background: #1f1f1f;
+  border: 1px solid #2a2a2a;
+  border-radius: 12px;
+  padding: 24px;
+  transition: all 0.15s ease;
+}
+
+.feature-card:hover {
+  border-color: #3b9eff;
+  background: #252525;
+}
+
+.feature-icon {
+  width: 48px;
+  height: 48px;
+  background: #0d0d0d;
+  border-radius: 10px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  margin-bottom: 16px;
+}
+
+.feature-title {
+  font-size: 16px;
+  font-weight: 600;
+  color: #ffffff;
+  margin: 0 0 8px 0;
+}
+
+.feature-desc {
+  font-size: 14px;
+  color: #707070;
+  line-height: 1.7;
+  margin: 0 0 16px 0;
+}
+
+.feature-link {
+  font-size: 14px;
+  color: #3b9eff;
+  text-decoration: none;
+  font-weight: 500;
+}
+
+.feature-link:hover {
+  text-decoration: underline;
+}
+
+@media (max-width: 1024px) {
+  .news-container,
+  .features-container {
+    padding: 0 24px;
+  }
+
+  .news-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .features-grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@media (max-width: 768px) {
+  .news-card {
+    flex-direction: column;
+  }
+
+  .news-card-image {
+    width: 100%;
+    min-height: 120px;
+  }
+
+  .features-grid {
+    grid-template-columns: 1fr;
+  }
+}
+</style>

docs/modules/behavior-tree/advanced-usage.md

@@ -0,0 +1,392 @@
+# 高级用法
+
+本文介绍行为树系统的高级功能和使用技巧。
+
+## 全局黑板
+
+全局黑板在所有行为树实例之间共享数据。
+
+### 使用全局黑板
+
+```typescript
+import { GlobalBlackboardService } from '@esengine/behavior-tree';
+import { Core } from '@esengine/ecs-framework';
+
+// 获取全局黑板服务
+const globalBlackboard = Core.services.resolve(GlobalBlackboardService);
+
+// 设置全局变量
+globalBlackboard.setValue('gameState', 'playing');
+globalBlackboard.setValue('playerCount', 4);
+globalBlackboard.setValue('difficulty', 'hard');
+
+// 读取全局变量
+const gameState = globalBlackboard.getValue('gameState');
+const playerCount = globalBlackboard.getValue<number>('playerCount');
+```
+
+### 在自定义执行器中访问全局黑板
+
+```typescript
+import { INodeExecutor, NodeExecutionContext, BindingHelper } from '@esengine/behavior-tree';
+import { GlobalBlackboardService } from '@esengine/behavior-tree';
+import { Core } from '@esengine/ecs-framework';
+
+export class CheckGameState implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const globalBlackboard = Core.services.resolve(GlobalBlackboardService);
+        const gameState = globalBlackboard.getValue('gameState');
+
+        if (gameState === 'paused') {
+            return TaskStatus.Failure;
+        }
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+## 性能优化
+
+### 1. 降低更新频率
+
+对于不需要每帧更新的AI,可以使用冷却装饰器:
+
+```typescript
+// 每0.1秒执行一次
+const ai = BehaviorTreeBuilder.create('ThrottledAI')
+    .cooldown(0.1, 'ThrottleRoot')
+        .selector('MainLogic')
+            // AI逻辑...
+        .end()
+    .end()
+    .build();
+```
+
+### 2. 条件缓存
+
+在自定义执行器中缓存昂贵的条件检查结果:
+
+```typescript
+export class CachedCheck implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { state, runtime, totalTime } = context;
+        const cacheTime = state.lastCheckTime || 0;
+
+        // 如果缓存未过期(1秒内),直接使用缓存结果
+        if (totalTime - cacheTime < 1.0) {
+            return state.cachedResult || TaskStatus.Failure;
+        }
+
+        // 执行昂贵的检查
+        const result = performExpensiveCheck();
+        const status = result ? TaskStatus.Success : TaskStatus.Failure;
+
+        // 缓存结果
+        state.cachedResult = status;
+        state.lastCheckTime = totalTime;
+
+        return status;
+    }
+
+    reset(context: NodeExecutionContext): void {
+        context.state.cachedResult = undefined;
+        context.state.lastCheckTime = undefined;
+    }
+}
+```
+
+### 3. 分帧执行
+
+将大量计算分散到多帧:
+
+```typescript
+export class ProcessLargeDataset implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { state, runtime } = context;
+
+        const data = runtime.getBlackboardValue<any[]>('dataset') || [];
+        let processedIndex = state.processedIndex || 0;
+
+        const batchSize = 100;  // 每帧处理100个
+        const endIndex = Math.min(processedIndex + batchSize, data.length);
+
+        for (let i = processedIndex; i < endIndex; i++) {
+            processItem(data[i]);
+        }
+
+        state.processedIndex = endIndex;
+
+        if (endIndex >= data.length) {
+            return TaskStatus.Success;
+        }
+
+        return TaskStatus.Running;
+    }
+
+    reset(context: NodeExecutionContext): void {
+        context.state.processedIndex = 0;
+    }
+}
+```
+
+## 调试技巧
+
+### 1. 使用日志节点
+
+在关键位置添加日志:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Debug')
+    .log('开始战斗序列', 'StartCombat')
+    .sequence('Combat')
+        .log('检查生命值', 'CheckHealth')
+        .blackboardCompare('health', 0, 'greater')
+        .log('执行攻击', 'Attack')
+    .end()
+    .build();
+```
+
+### 2. 监控黑板状态
+
+```typescript
+const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+
+// 输出所有黑板变量
+console.log('黑板变量:', runtime?.getAllBlackboardVariables());
+
+// 输出活动节点
+console.log('活动节点:', Array.from(runtime?.activeNodeIds || []));
+```
+
+### 3. 在自定义执行器中调试
+
+```typescript
+export class DebugAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { nodeData, runtime, state } = context;
+
+        console.log(`[${nodeData.name}] 开始执行`);
+        console.log('配置:', nodeData.config);
+        console.log('状态:', state);
+        console.log('黑板:', runtime.getAllBlackboardVariables());
+
+        // 执行逻辑...
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+### 4. 性能分析
+
+测量节点执行时间:
+
+```typescript
+export class ProfiledAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const startTime = performance.now();
+
+        // 执行操作
+        doSomething();
+
+        const elapsed = performance.now() - startTime;
+        console.log(`[${context.nodeData.name}] 耗时: ${elapsed.toFixed(2)}ms`);
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+## 常见模式
+
+### 1. 状态机模式
+
+使用行为树实现状态机:
+
+```typescript
+const fsm = BehaviorTreeBuilder.create('StateMachine')
+    .defineBlackboardVariable('currentState', 'idle')
+    .selector('StateSwitch')
+        // Idle状态
+        .sequence('IdleState')
+            .blackboardCompare('currentState', 'idle', 'equals')
+            .log('执行Idle行为', 'IdleBehavior')
+        .end()
+        // Move状态
+        .sequence('MoveState')
+            .blackboardCompare('currentState', 'move', 'equals')
+            .log('执行Move行为', 'MoveBehavior')
+        .end()
+        // Attack状态
+        .sequence('AttackState')
+            .blackboardCompare('currentState', 'attack', 'equals')
+            .log('执行Attack行为', 'AttackBehavior')
+        .end()
+    .end()
+    .build();
+```
+
+状态转换通过修改黑板变量实现:
+
+```typescript
+const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+runtime?.setBlackboardValue('currentState', 'move');
+```
+
+### 2. 优先级队列模式
+
+按优先级执行任务:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('PriorityQueue')
+    .selector('Priorities')
+        // 最高优先级:生存
+        .sequence('Survive')
+            .blackboardCompare('health', 20, 'less')
+            .log('治疗', 'Heal')
+        .end()
+        // 中优先级:战斗
+        .sequence('Combat')
+            .blackboardExists('nearbyEnemy')
+            .log('战斗', 'Fight')
+        .end()
+        // 低优先级:收集资源
+        .sequence('Gather')
+            .log('收集资源', 'CollectResources')
+        .end()
+    .end()
+    .build();
+```
+
+### 3. 并行任务模式
+
+同时执行多个任务:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('ParallelTasks')
+    .parallel('Effects', { successPolicy: 'all' })
+        .log('播放动画', 'PlayAnimation')
+        .log('播放音效', 'PlaySound')
+        .log('生成粒子', 'SpawnParticles')
+    .end()
+    .build();
+```
+
+### 4. 重试模式
+
+失败时重试:
+
+```typescript
+// 使用自定义重试装饰器(参见custom-actions.md中的RetryDecorator示例)
+// 或者使用UntilSuccess装饰器
+const tree = BehaviorTreeBuilder.create('Retry')
+    .untilSuccess('RetryUntilSuccess')
+        .log('尝试操作', 'TryOperation')
+    .end()
+    .build();
+```
+
+### 5. 超时模式
+
+限制任务执行时间:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Timeout')
+    .timeout(5.0, 'TimeLimit')
+        .log('长时间运行的任务', 'LongTask')
+    .end()
+    .build();
+```
+
+## 与游戏引擎集成
+
+### Cocos Creator集成
+
+参见[Cocos Creator集成指南](./cocos-integration.md)
+
+### LayaAir集成
+
+参见[LayaAir集成指南](./laya-integration.md)
+
+## 最佳实践
+
+### 1. 合理使用黑板
+
+```typescript
+// 好的做法:使用类型化的黑板访问
+const health = runtime.getBlackboardValue<number>('health');
+
+// 好的做法:定义所有黑板变量
+const tree = BehaviorTreeBuilder.create('AI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .defineBlackboardVariable('state', 'idle')
+    // ...
+```
+
+### 2. 避免过深的树结构
+
+```typescript
+// 不好:嵌套过深
+.selector()
+    .sequence()
+        .selector()
+            .sequence()
+                .selector()
+                    // 太深了!
+                .end()
+            .end()
+        .end()
+    .end()
+.end()
+
+// 好:使用合理的深度
+.selector()
+    .sequence()
+        .log('Action1')
+        .log('Action2')
+    .end()
+    .sequence()
+        .log('Action3')
+        .log('Action4')
+    .end()
+.end()
+```
+
+### 3. 使用有意义的节点名称
+
+```typescript
+// 好的做法
+.selector('CombatDecision')
+    .sequence('AttackEnemy')
+        .blackboardExists('target', 'HasTarget')
+        .log('执行攻击', 'Attack')
+    .end()
+.end()
+
+// 不好的做法
+.selector('Node1')
+    .sequence('Node2')
+        .blackboardExists('target', 'Node3')
+        .log('Attack', 'Node4')
+    .end()
+.end()
+```
+
+### 4. 模块化设计
+
+将复杂逻辑分解为多个独立的行为树,在需要时组合使用。
+
+### 5. 性能考虑
+
+- 避免在每帧执行昂贵的操作
+- 使用冷却装饰器控制执行频率
+- 缓存计算结果
+- 合理使用并行节点
+
+## 下一步
+
+- 查看[自定义节点执行器](./custom-actions.md)学习如何创建自定义节点
+- 阅读[最佳实践](./best-practices.md)了解行为树设计技巧
+- 参考[编辑器使用指南](./editor-guide.md)学习可视化编辑

docs/modules/behavior-tree/asset-management.md

@@ -0,0 +1,506 @@
+# 资产管理
+
+本文介绍如何加载、管理和复用行为树资产。
+
+## 为什么需要资产管理？
+
+在实际游戏开发中，你可能会遇到以下场景：
+
+1. **多个实体共享同一个行为树** - 100个敌人使用同一套AI逻辑
+2. **动态加载行为树** - 从JSON文件加载行为树配置
+3. **子树复用** - 将常用的行为片段（如"巡逻"、"追击"）做成独立的子树
+4. **运行时切换行为树** - 敌人在不同阶段使用不同的行为树
+
+## BehaviorTreeAssetManager
+
+框架提供了 `BehaviorTreeAssetManager` 服务来统一管理行为树资产。
+
+### 核心概念
+
+- **BehaviorTreeData（行为树数据）**：行为树的定义，可以被多个实体共享
+- **BehaviorTreeRuntimeComponent（运行时组件）**：每个实体独立的运行时状态
+- **AssetManager（资产管理器）**：统一管理所有 BehaviorTreeData
+
+### 基本使用
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeAssetManager,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter
+} from '@esengine/behavior-tree';
+
+// 1. 获取资产管理器（插件已自动注册）
+const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+
+// 2. 创建并注册行为树资产
+const enemyAI = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .selector('MainBehavior')
+        .log('攻击')
+    .end()
+    .build();
+
+assetManager.loadAsset(enemyAI);
+
+// 3. 为多个实体使用同一份资产
+const enemy1 = scene.createEntity('Enemy1');
+const enemy2 = scene.createEntity('Enemy2');
+const enemy3 = scene.createEntity('Enemy3');
+
+// 获取共享的资产
+const sharedTree = assetManager.getAsset('EnemyAI');
+
+if (sharedTree) {
+    BehaviorTreeStarter.start(enemy1, sharedTree);
+    BehaviorTreeStarter.start(enemy2, sharedTree);
+    BehaviorTreeStarter.start(enemy3, sharedTree);
+}
+```
+
+### 资产管理器 API
+
+```typescript
+// 加载资产
+assetManager.loadAsset(treeData);
+
+// 获取资产
+const tree = assetManager.getAsset('TreeID');
+
+// 检查资产是否存在
+if (assetManager.hasAsset('TreeID')) {
+    // ...
+}
+
+// 卸载资产
+assetManager.unloadAsset('TreeID');
+
+// 获取所有资产ID
+const allIds = assetManager.getAllAssetIds();
+
+// 清空所有资产
+assetManager.clearAll();
+```
+
+## 从文件加载行为树
+
+### JSON 格式
+
+行为树可以导出为 JSON 格式：
+
+```json
+{
+    "version": "1.0.0",
+    "metadata": {
+        "name": "EnemyAI",
+        "description": "敌人AI行为树"
+    },
+    "rootNodeId": "root-1",
+    "nodes": [
+        {
+            "id": "root-1",
+            "name": "RootSelector",
+            "nodeType": "Composite",
+            "data": {
+                "compositeType": "Selector"
+            },
+            "children": ["combat-1", "patrol-1"]
+        },
+        {
+            "id": "combat-1",
+            "name": "Combat",
+            "nodeType": "Action",
+            "data": {
+                "actionType": "LogAction",
+                "message": "攻击敌人"
+            },
+            "children": []
+        }
+    ],
+    "blackboard": [
+        {
+            "name": "health",
+            "type": "number",
+            "defaultValue": 100
+        }
+    ]
+}
+```
+
+### 加载 JSON 文件
+
+```typescript
+import {
+    BehaviorTreeAssetSerializer,
+    BehaviorTreeAssetManager
+} from '@esengine/behavior-tree';
+
+async function loadTreeFromFile(filePath: string) {
+    const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+
+    // 1. 读取文件内容
+    const jsonContent = await fetch(filePath).then(res => res.text());
+
+    // 2. 反序列化
+    const treeData = BehaviorTreeAssetSerializer.deserialize(jsonContent);
+
+    // 3. 加载到资产管理器
+    assetManager.loadAsset(treeData);
+
+    return treeData;
+}
+
+// 使用
+const tree = await loadTreeFromFile('/assets/enemy-ai.btree.json');
+BehaviorTreeStarter.start(entity, tree);
+```
+
+## 子树（SubTree）
+
+子树允许你将常用的行为片段做成独立的树，然后在其他树中引用。
+
+### 为什么使用子树？
+
+1. **代码复用** - 避免重复定义相同的行为
+2. **模块化** - 将复杂的行为树拆分成小的可管理单元
+3. **团队协作** - 不同成员可以独立开发不同的子树
+
+### 创建子树
+
+```typescript
+// 1. 创建巡逻子树
+const patrolTree = BehaviorTreeBuilder.create('PatrolBehavior')
+    .sequence('Patrol')
+        .log('选择巡逻点', 'PickWaypoint')
+        .log('移动到巡逻点', 'MoveToWaypoint')
+        .wait(2.0, 'WaitAtWaypoint')
+    .end()
+    .build();
+
+// 2. 创建追击子树
+const chaseTree = BehaviorTreeBuilder.create('ChaseBehavior')
+    .sequence('Chase')
+        .log('锁定目标', 'LockTarget')
+        .log('追击目标', 'ChaseTarget')
+    .end()
+    .build();
+
+// 3. 注册子树到资产管理器
+const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+assetManager.loadAsset(patrolTree);
+assetManager.loadAsset(chaseTree);
+```
+
+### 使用子树
+
+```typescript
+// 在主行为树中使用子树
+const mainTree = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('hasTarget', false)
+
+    .selector('MainBehavior')
+        // 条件：发现目标时执行追击子树
+        .sequence('CombatBranch')
+            .blackboardExists('hasTarget')
+            .subTree('ChaseBehavior', { shareBlackboard: true })
+        .end()
+
+        // 默认：执行巡逻子树
+        .subTree('PatrolBehavior', { shareBlackboard: true })
+    .end()
+    .build();
+
+assetManager.loadAsset(mainTree);
+
+// 启动主行为树
+const enemy = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(enemy, mainTree);
+```
+
+### SubTree 配置选项
+
+```typescript
+.subTree('SubTreeID', {
+    shareBlackboard: true,  // 是否共享黑板（默认true）
+})
+```
+
+- **shareBlackboard: true** - 子树和父树共享黑板变量
+- **shareBlackboard: false** - 子树使用独立的黑板
+
+## 资源预加载
+
+在游戏启动时预加载所有行为树资产：
+
+```typescript
+class BehaviorTreePreloader {
+    private assetManager: BehaviorTreeAssetManager;
+
+    constructor() {
+        this.assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+    }
+
+    async preloadAll() {
+        // 定义所有行为树文件
+        const treeFiles = [
+            '/assets/ai/enemy-ai.btree.json',
+            '/assets/ai/boss-ai.btree.json',
+            '/assets/ai/patrol.btree.json',
+            '/assets/ai/chase.btree.json'
+        ];
+
+        // 并行加载所有文件
+        const loadPromises = treeFiles.map(file => this.loadTree(file));
+        await Promise.all(loadPromises);
+
+        console.log(`已加载 ${this.assetManager.getAssetCount()} 个行为树资产`);
+    }
+
+    private async loadTree(filePath: string) {
+        const jsonContent = await fetch(filePath).then(res => res.text());
+        const treeData = BehaviorTreeAssetSerializer.deserialize(jsonContent);
+        this.assetManager.loadAsset(treeData);
+    }
+}
+
+// 游戏启动时调用
+const preloader = new BehaviorTreePreloader();
+await preloader.preloadAll();
+```
+
+## 运行时切换行为树
+
+敌人在不同阶段使用不同的行为树：
+
+```typescript
+class EnemyAI {
+    private entity: Entity;
+    private assetManager: BehaviorTreeAssetManager;
+
+    constructor(entity: Entity) {
+        this.entity = entity;
+        this.assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+    }
+
+    // 切换到巡逻AI
+    switchToPatrol() {
+        const tree = this.assetManager.getAsset('PatrolAI');
+        if (tree) {
+            BehaviorTreeStarter.stop(this.entity);
+            BehaviorTreeStarter.start(this.entity, tree);
+        }
+    }
+
+    // 切换到战斗AI
+    switchToCombat() {
+        const tree = this.assetManager.getAsset('CombatAI');
+        if (tree) {
+            BehaviorTreeStarter.stop(this.entity);
+            BehaviorTreeStarter.start(this.entity, tree);
+        }
+    }
+
+    // 切换到狂暴模式
+    switchToBerserk() {
+        const tree = this.assetManager.getAsset('BerserkAI');
+        if (tree) {
+            BehaviorTreeStarter.stop(this.entity);
+            BehaviorTreeStarter.start(this.entity, tree);
+        }
+    }
+}
+
+// 使用
+const enemyAI = new EnemyAI(enemyEntity);
+
+// Boss血量低于30%时进入狂暴
+const runtime = enemyEntity.getComponent(BehaviorTreeRuntimeComponent);
+const health = runtime?.getBlackboardValue<number>('health');
+
+if (health && health < 30) {
+    enemyAI.switchToBerserk();
+}
+```
+
+## 内存优化
+
+### 1. 共享行为树数据
+
+```typescript
+// 好的做法：100个敌人共享1份BehaviorTreeData
+const sharedTree = assetManager.getAsset('EnemyAI');
+
+for (let i = 0; i < 100; i++) {
+    const enemy = scene.createEntity(`Enemy${i}`);
+    BehaviorTreeStarter.start(enemy, sharedTree!);  // 共享数据
+}
+
+// 不好的做法：每个敌人创建独立的BehaviorTreeData
+for (let i = 0; i < 100; i++) {
+    const enemy = scene.createEntity(`Enemy${i}`);
+    const tree = BehaviorTreeBuilder.create('EnemyAI')  // 重复创建
+        // ... 节点定义
+        .build();
+    BehaviorTreeStarter.start(enemy, tree);
+}
+```
+
+### 2. 及时卸载不用的资产
+
+```typescript
+// 关卡结束时卸载该关卡的AI
+function onLevelEnd() {
+    assetManager.unloadAsset('Level1BossAI');
+    assetManager.unloadAsset('Level1EnemyAI');
+}
+
+// 加载新关卡的AI
+function onLevelStart() {
+    const boss2AI = await loadTreeFromFile('/assets/level2-boss.btree.json');
+    assetManager.loadAsset(boss2AI);
+}
+```
+
+## 完整示例：多敌人类型的游戏
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    BehaviorTreePlugin,
+    BehaviorTreeAssetManager,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter
+} from '@esengine/behavior-tree';
+
+async function setupGame() {
+    // 1. 初始化
+    Core.create();
+    const plugin = new BehaviorTreePlugin();
+    await Core.installPlugin(plugin);
+
+    const scene = new Scene();
+    plugin.setupScene(scene);
+    Core.setScene(scene);
+
+    const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+
+    // 2. 创建共享的子树
+    const patrolTree = BehaviorTreeBuilder.create('Patrol')
+        .sequence('PatrolLoop')
+            .log('巡逻')
+            .wait(1.0)
+        .end()
+        .build();
+
+    const combatTree = BehaviorTreeBuilder.create('Combat')
+        .sequence('CombatLoop')
+            .log('战斗')
+        .end()
+        .build();
+
+    assetManager.loadAsset(patrolTree);
+    assetManager.loadAsset(combatTree);
+
+    // 3. 创建不同类型敌人的AI
+    const meleeEnemyAI = BehaviorTreeBuilder.create('MeleeEnemyAI')
+        .selector('MeleeBehavior')
+            .sequence('Attack')
+                .blackboardExists('target')
+                .log('近战攻击')
+            .end()
+            .subTree('Patrol')
+        .end()
+        .build();
+
+    const rangedEnemyAI = BehaviorTreeBuilder.create('RangedEnemyAI')
+        .selector('RangedBehavior')
+            .sequence('Attack')
+                .blackboardExists('target')
+                .log('远程攻击')
+            .end()
+            .subTree('Patrol')
+        .end()
+        .build();
+
+    assetManager.loadAsset(meleeEnemyAI);
+    assetManager.loadAsset(rangedEnemyAI);
+
+    // 4. 创建多个敌人实体
+    // 10个近战敌人共享同一份AI
+    const meleeAI = assetManager.getAsset('MeleeEnemyAI')!;
+    for (let i = 0; i < 10; i++) {
+        const enemy = scene.createEntity(`MeleeEnemy${i}`);
+        BehaviorTreeStarter.start(enemy, meleeAI);
+    }
+
+    // 5个远程敌人共享同一份AI
+    const rangedAI = assetManager.getAsset('RangedEnemyAI')!;
+    for (let i = 0; i < 5; i++) {
+        const enemy = scene.createEntity(`RangedEnemy${i}`);
+        BehaviorTreeStarter.start(enemy, rangedAI);
+    }
+
+    console.log(`已创建 15 个敌人，使用 ${assetManager.getAssetCount()} 个行为树资产`);
+
+    // 5. 游戏循环
+    setInterval(() => {
+        Core.update(0.016);
+    }, 16);
+}
+
+setupGame();
+```
+
+## 常见问题
+
+### 如何检查资产是否已加载？
+
+```typescript
+const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+
+if (!assetManager.hasAsset('EnemyAI')) {
+    // 加载资产
+    const tree = await loadTreeFromFile('/assets/enemy-ai.btree.json');
+    assetManager.loadAsset(tree);
+}
+```
+
+### 子树找不到怎么办？
+
+确保子树已经加载到资产管理器中：
+
+```typescript
+// 1. 先加载子树
+const subTree = BehaviorTreeBuilder.create('SubTreeID')
+    // ...
+    .build();
+assetManager.loadAsset(subTree);
+
+// 2. 再加载使用子树的主树
+const mainTree = BehaviorTreeBuilder.create('MainTree')
+    .subTree('SubTreeID')
+    .build();
+```
+
+### 如何导出行为树为 JSON？
+
+```typescript
+import { BehaviorTreeAssetSerializer } from '@esengine/behavior-tree';
+
+const tree = BehaviorTreeBuilder.create('MyTree')
+    // ... 节点定义
+    .build();
+
+// 序列化为JSON字符串
+const json = BehaviorTreeAssetSerializer.serialize(tree);
+
+// 保存到文件或发送到服务器
+console.log(json);
+```
+
+## 下一步
+
+- 学习[Cocos Creator 集成](./cocos-integration.md)了解如何在游戏引擎中加载资源
+- 查看[自定义节点执行器](./custom-actions.md)创建自定义行为
+- 阅读[最佳实践](./best-practices.md)优化你的行为树设计

docs/modules/behavior-tree/best-practices.md

@@ -0,0 +1,468 @@
+# 最佳实践
+
+本文介绍行为树设计和使用的最佳实践,帮助你构建高效、可维护的AI系统。
+
+## 行为树设计原则
+
+### 1. 保持树的层次清晰
+
+将复杂行为分解成清晰的层次结构:
+
+```
+Root Selector
+├── Emergency (高优先级:紧急情况)
+│   ├── FleeFromDanger
+│   └── CallForHelp
+├── Combat (中优先级:战斗)
+│   ├── Attack
+│   └── Defend
+└── Idle (低优先级:空闲)
+    ├── Patrol
+    └── Rest
+```
+
+
+### 2. 单一职责原则
+
+每个节点应该只做一件事。要实现复杂动作,创建自定义执行器,参见[自定义节点执行器](./custom-actions.md)。
+
+```typescript
+// 好的设计 - 使用内置节点
+.sequence('AttackSequence')
+    .blackboardExists('target', 'CheckTarget')
+    .log('瞄准', 'Aim')
+    .log('开火', 'Fire')
+.end()
+```
+
+### 3. 使用描述性名称
+
+节点名称应该清楚地表达其功能:
+
+```typescript
+// 好的命名
+.blackboardCompare('health', 20, 'less', 'CheckHealthLow')
+.log('寻找最近的医疗包', 'FindHealthPack')
+.log('移动到医疗包', 'MoveToHealthPack')
+
+// 不好的命名
+.blackboardCompare('health', 20, 'less', 'C1')
+.log('Do something', 'Action1')
+.log('Move', 'A2')
+```
+
+## 黑板变量管理
+
+### 1. 变量命名规范
+
+使用清晰的命名约定:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('AI')
+    // 状态变量
+    .defineBlackboardVariable('currentState', 'idle')
+    .defineBlackboardVariable('isMoving', false)
+
+    // 目标和引用
+    .defineBlackboardVariable('targetEnemy', null)
+    .defineBlackboardVariable('patrolPoints', [])
+
+    // 配置参数
+    .defineBlackboardVariable('attackRange', 5.0)
+    .defineBlackboardVariable('moveSpeed', 10.0)
+
+    // 临时数据
+    .defineBlackboardVariable('lastAttackTime', 0)
+    .defineBlackboardVariable('searchAttempts', 0)
+    // ...
+    .build();
+```
+
+### 2. 避免过度使用黑板
+
+只在需要跨节点共享的数据才放入黑板。在自定义执行器中使用局部变量:
+
+```typescript
+// 好的做法 - 使用局部变量
+export class CalculateAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        // 局部计算
+        const temp1 = 10;
+        const temp2 = 20;
+        const result = temp1 + temp2;
+
+        // 只保存需要共享的结果
+        context.runtime.setBlackboardValue('calculationResult', result);
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+### 3. 使用类型安全的访问
+
+```typescript
+export class TypeSafeAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { runtime } = context;
+
+        // 使用泛型进行类型安全访问
+        const health = runtime.getBlackboardValue<number>('health');
+        const target = runtime.getBlackboardValue<Entity | null>('target');
+        const state = runtime.getBlackboardValue<string>('currentState');
+
+        if (health !== undefined && health < 30) {
+            runtime.setBlackboardValue('currentState', 'flee');
+        }
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+## 执行器设计
+
+### 1. 保持执行器无状态
+
+状态必须存储在`context.state`中,而不是执行器实例:
+
+```typescript
+// 正确的做法
+export class TimedAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        if (!context.state.startTime) {
+            context.state.startTime = context.totalTime;
+        }
+
+        const elapsed = context.totalTime - context.state.startTime;
+
+        if (elapsed >= 3.0) {
+            return TaskStatus.Success;
+        }
+
+        return TaskStatus.Running;
+    }
+
+    reset(context: NodeExecutionContext): void {
+        context.state.startTime = undefined;
+    }
+}
+```
+
+### 2. 条件应该是无副作用的
+
+条件检查不应该修改状态:
+
+```typescript
+// 好的做法 - 只读检查
+@NodeExecutorMetadata({
+    implementationType: 'IsHealthLow',
+    nodeType: NodeType.Condition,
+    displayName: '检查生命值低',
+    category: '条件',
+    configSchema: {
+        threshold: {
+            type: 'number',
+            default: 30,
+            supportBinding: true
+        }
+    }
+})
+export class IsHealthLow implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const threshold = BindingHelper.getValue<number>(context, 'threshold', 30);
+        const health = context.runtime.getBlackboardValue<number>('health') || 0;
+
+        return health < threshold ? TaskStatus.Success : TaskStatus.Failure;
+    }
+}
+```
+
+### 3. 错误处理
+
+```typescript
+export class SafeAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        try {
+            const resourceId = context.runtime.getBlackboardValue('resourceId');
+
+            if (!resourceId) {
+                console.error('[SafeAction] 资源ID未设置');
+                return TaskStatus.Failure;
+            }
+
+            // 执行操作...
+
+            return TaskStatus.Success;
+
+        } catch (error) {
+            console.error('[SafeAction] 执行失败:', error);
+            context.runtime.setBlackboardValue('lastError', error.message);
+            return TaskStatus.Failure;
+        }
+    }
+}
+```
+
+## 性能优化技巧
+
+### 1. 使用冷却装饰器
+
+避免高频执行昂贵操作:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('ThrottledAI')
+    .cooldown(1.0, 'ThrottleSearch')  // 最多每秒执行一次
+        .log('昂贵的搜索操作', 'ExpensiveSearch')
+    .end()
+    .build();
+```
+
+### 2. 缓存计算结果
+
+```typescript
+export class CachedFindNearest implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { state, runtime, totalTime } = context;
+
+        // 检查缓存是否有效
+        const cacheTime = state.enemyCacheTime || 0;
+
+        if (totalTime - cacheTime < 0.5) {  // 缓存0.5秒
+            const cached = runtime.getBlackboardValue('nearestEnemy');
+            return cached ? TaskStatus.Success : TaskStatus.Failure;
+        }
+
+        // 执行搜索
+        const nearest = findNearestEnemy();
+        runtime.setBlackboardValue('nearestEnemy', nearest);
+        state.enemyCacheTime = totalTime;
+
+        return nearest ? TaskStatus.Success : TaskStatus.Failure;
+    }
+
+    reset(context: NodeExecutionContext): void {
+        context.state.enemyCacheTime = undefined;
+    }
+}
+```
+
+### 3. 使用早期退出
+
+```typescript
+const tree = BehaviorTreeBuilder.create('EarlyExit')
+    .selector('FindTarget')
+        // 先检查缓存的目标
+        .blackboardExists('cachedTarget', 'HasCachedTarget')
+
+        // 没有缓存才进行搜索(需要自定义执行器)
+        .log('执行昂贵的搜索', 'SearchNewTarget')
+    .end()
+    .build();
+```
+
+## 可维护性
+
+### 1. 使用有意义的节点名称
+
+```typescript
+// 好的做法
+const tree = BehaviorTreeBuilder.create('CombatAI')
+    .selector('CombatDecision')
+        .sequence('AttackEnemy')
+            .blackboardExists('target', 'HasTarget')
+            .log('执行攻击', 'Attack')
+        .end()
+    .end()
+    .build();
+
+// 不好的做法
+const tree = BehaviorTreeBuilder.create('AI')
+    .selector('Node1')
+        .sequence('Node2')
+            .blackboardExists('target', 'Node3')
+            .log('Attack', 'Node4')
+        .end()
+    .end()
+    .build();
+```
+
+### 2. 使用编辑器创建复杂树
+
+对于复杂的AI,使用可视化编辑器:
+
+- 更直观的结构
+- 方便非程序员调整
+- 易于版本控制
+- 支持实时调试
+
+
+### 3. 添加注释和文档
+
+```typescript
+// 为行为树添加清晰的注释
+const bossAI = BehaviorTreeBuilder.create('BossAI')
+    .defineBlackboardVariable('phase', 1)  // 1=正常, 2=狂暴, 3=濒死
+
+    .selector('MainBehavior')
+        // 阶段3: 生命值<20%,使用终极技能
+        .sequence('Phase3')
+            .blackboardCompare('phase', 3, 'equals')
+            .log('使用终极技能', 'UltimateAbility')
+        .end()
+
+        // 阶段2: 生命值<50%,进入狂暴
+        .sequence('Phase2')
+            .blackboardCompare('phase', 2, 'equals')
+            .log('进入狂暴模式', 'BerserkMode')
+        .end()
+
+        // 阶段1: 正常战斗
+        .sequence('Phase1')
+            .log('普通攻击', 'NormalAttack')
+        .end()
+    .end()
+    .build();
+```
+
+## 调试技巧
+
+### 1. 使用日志节点
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Debug')
+    .log('开始攻击序列', 'StartAttack')
+    .sequence('Attack')
+        .log('检查目标', 'CheckTarget')
+        .blackboardExists('target')
+        .log('执行攻击', 'DoAttack')
+    .end()
+    .build();
+```
+
+### 2. 在自定义执行器中调试
+
+```typescript
+export class DebugAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { nodeData, runtime, state } = context;
+
+        console.group(`[${nodeData.name}]`);
+        console.log('配置:', nodeData.config);
+        console.log('状态:', state);
+        console.log('黑板:', runtime.getAllBlackboardVariables());
+        console.log('活动节点:', Array.from(runtime.activeNodeIds));
+        console.groupEnd();
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+### 3. 状态可视化
+
+```typescript
+export class VisualizeState implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        if (process.env.NODE_ENV === 'development') {
+            console.group('AI State');
+            console.log('Entity:', context.entity.name);
+            console.log('Health:', context.runtime.getBlackboardValue('health'));
+            console.log('State:', context.runtime.getBlackboardValue('currentState'));
+            console.log('Target:', context.runtime.getBlackboardValue('target'));
+            console.groupEnd();
+        }
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+## 常见反模式
+
+### 1. 过深的嵌套
+
+```typescript
+// 不好 - 太深的嵌套
+.selector()
+    .sequence()
+        .sequence()
+            .sequence()
+                .log('太深了', 'DeepAction')
+            .end()
+        .end()
+    .end()
+.end()
+
+// 好 - 使用合理的深度
+.selector()
+    .sequence()
+        .log('Action1')
+        .log('Action2')
+    .end()
+    .sequence()
+        .log('Action3')
+        .log('Action4')
+    .end()
+.end()
+```
+
+### 2. 在执行器中存储状态
+
+```typescript
+// 错误 - 状态存储在执行器中
+export class BadAction implements INodeExecutor {
+    private startTime = 0;  // 错误!多个节点会共享这个值
+
+    execute(context: NodeExecutionContext): TaskStatus {
+        this.startTime = context.totalTime;  // 错误!
+        return TaskStatus.Success;
+    }
+}
+
+// 正确 - 状态存储在context.state中
+export class GoodAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        if (!context.state.startTime) {
+            context.state.startTime = context.totalTime;  // 正确!
+        }
+        return TaskStatus.Success;
+    }
+}
+```
+
+### 3. 频繁修改黑板
+
+```typescript
+// 不好 - 每帧都修改黑板
+export class FrequentUpdate implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const pos = getCurrentPosition();
+        context.runtime.setBlackboardValue('position', pos);  // 每帧都set
+        context.runtime.setBlackboardValue('velocity', getVelocity());
+        context.runtime.setBlackboardValue('rotation', getRotation());
+        return TaskStatus.Running;
+    }
+}
+
+// 好 - 只在需要时修改
+export class SmartUpdate implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const oldPos = context.runtime.getBlackboardValue('position');
+        const newPos = getCurrentPosition();
+
+        // 只在位置变化时更新
+        if (!positionsEqual(oldPos, newPos)) {
+            context.runtime.setBlackboardValue('position', newPos);
+        }
+
+        return TaskStatus.Running;
+    }
+}
+```
+
+## 下一步
+
+- 学习[自定义节点执行器](./custom-actions.md)扩展行为树功能
+- 探索[高级用法](./advanced-usage.md)了解更多技巧
+- 参考[核心概念](./core-concepts.md)深入理解原理

docs/modules/behavior-tree/cocos-integration.md

@@ -0,0 +1,683 @@
+# Cocos Creator 集成
+
+本教程将引导你在 Cocos Creator 项目中集成和使用行为树系统。
+
+## 前置要求
+
+- Cocos Creator 3.x 或更高版本
+- 基本的 TypeScript 知识
+- 已完成[快速开始](./getting-started.md)教程
+
+## 安装
+
+### 步骤1：安装依赖
+
+在你的 Cocos Creator 项目根目录下：
+
+```bash
+npm install @esengine/ecs-framework @esengine/behavior-tree
+```
+
+### 步骤2：配置 tsconfig.json
+
+确保 `tsconfig.json` 中包含以下配置：
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "moduleResolution": "node"
+  }
+}
+```
+
+## 项目结构
+
+建议的项目结构：
+
+```
+assets/
+├── scripts/
+│   ├── ai/
+│   │   ├── EnemyAIComponent.ts      # AI 组件
+│   │   └── PlayerDetector.ts         # 检测器
+│   ├── systems/
+│   │   └── BehaviorTreeSystem.ts     # 行为树系统
+│   └── Main.ts                        # 主入口
+├── resources/
+│   └── behaviors/
+│       ├── enemy-ai.btree.json        # 行为树资产
+│       └── patrol.btree.json          # 子树资产
+└── types/
+    └── enemy-ai.ts                    # 类型定义
+```
+
+
+## 初始化 ECS 和行为树
+
+### 创建主入口组件
+
+创建 `assets/scripts/Main.ts`：
+
+```typescript
+import { _decorator, Component } from 'cc';
+import { Core, Scene } from '@esengine/ecs-framework';
+import { BehaviorTreePlugin } from '@esengine/behavior-tree';
+
+const { ccclass } = _decorator;
+
+@ccclass('Main')
+export class Main extends Component {
+    async onLoad() {
+        // 初始化 ECS Core
+        Core.create();
+
+        // 安装行为树插件
+        const behaviorTreePlugin = new BehaviorTreePlugin();
+        await Core.installPlugin(behaviorTreePlugin);
+
+        // 创建并设置场景
+        const scene = new Scene();
+        behaviorTreePlugin.setupScene(scene);
+        Core.setScene(scene);
+
+        console.log('ECS 和行为树系统初始化完成');
+    }
+
+    update(deltaTime: number) {
+        // 更新 ECS（会自动更新场景）
+        Core.update(deltaTime);
+    }
+
+    onDestroy() {
+        // 清理资源
+        Core.destroy();
+    }
+}
+```
+
+
+### 添加组件到场景
+
+1. 在场景中创建一个空节点（命名为 `GameManager`）
+2. 添加 `Main` 组件到该节点
+
+
+## 创建 AI 组件
+
+创建 `assets/scripts/ai/EnemyAIComponent.ts`：
+
+```typescript
+import { _decorator, Component, Node } from 'cc';
+import { Core, Entity } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreeRuntimeComponent
+} from '@esengine/behavior-tree';
+
+const { ccclass, property } = _decorator;
+
+@ccclass('EnemyAIComponent')
+export class EnemyAIComponent extends Component {
+    private aiEntity: Entity | null = null;
+
+    async start() {
+        // 创建行为树
+        await this.createBehaviorTree();
+    }
+
+    private async createBehaviorTree() {
+        try {
+            // 获取Core管理的场景
+            const scene = Core.scene;
+            if (!scene) {
+                console.error('场景未初始化');
+                return;
+            }
+
+            // 使用Builder API创建行为树
+            const tree = BehaviorTreeBuilder.create('EnemyAI')
+                .defineBlackboardVariable('cocosNode', this.node)
+                .defineBlackboardVariable('health', 100)
+                .defineBlackboardVariable('playerNode', null)
+                .defineBlackboardVariable('detectionRange', 10)
+                .defineBlackboardVariable('attackRange', 2)
+                .selector('MainBehavior')
+                    .sequence('Combat')
+                        .blackboardExists('playerNode')
+                        .blackboardCompare('health', 30, 'greater')
+                        .log('攻击玩家', 'AttackPlayer')
+                    .end()
+                    .sequence('Flee')
+                        .blackboardCompare('health', 30, 'lessOrEqual')
+                        .log('逃跑', 'RunAway')
+                    .end()
+                    .log('巡逻', 'Patrol')
+                .end()
+                .build();
+
+            // 创建AI实体并启动
+            this.aiEntity = scene.createEntity(`AI_${this.node.name}`);
+            BehaviorTreeStarter.start(this.aiEntity, tree);
+
+            console.log('敌人 AI 已启动');
+        } catch (error) {
+            console.error('初始化行为树失败:', error);
+        }
+    }
+
+    onDestroy() {
+        // 停止 AI
+        if (this.aiEntity) {
+            BehaviorTreeStarter.stop(this.aiEntity);
+        }
+    }
+}
+```
+
+
+## 与 Cocos 节点交互
+
+### 创建自定义执行器
+
+要实现与Cocos节点的交互，需要创建自定义执行器：
+
+```typescript
+import {
+    INodeExecutor,
+    NodeExecutionContext,
+    NodeExecutorMetadata
+} from '@esengine/behavior-tree';
+import { TaskStatus, NodeType } from '@esengine/behavior-tree';
+import { Animation } from 'cc';
+
+@NodeExecutorMetadata({
+    implementationType: 'PlayAnimation',
+    nodeType: NodeType.Action,
+    displayName: '播放动画',
+    description: '播放Cocos节点上的动画',
+    category: 'Cocos',
+    configSchema: {
+        animationName: {
+            type: 'string',
+            default: 'attack'
+        }
+    }
+})
+export class PlayAnimationAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const cocosNode = context.runtime.getBlackboardValue('cocosNode');
+        const animationName = context.nodeData.config.animationName;
+
+        if (!cocosNode) {
+            return TaskStatus.Failure;
+        }
+
+        const animation = cocosNode.getComponent(Animation);
+        if (animation) {
+            animation.play(animationName);
+            return TaskStatus.Success;
+        }
+
+        return TaskStatus.Failure;
+    }
+}
+```
+
+
+## 完整示例：敌人 AI
+
+### 行为树设计
+
+使用编辑器创建 `enemy-ai.btree.json`：
+
+```
+RootSelector
+├── CombatSequence
+│   ├── CheckPlayerInRange (Condition)
+│   ├── CheckHealthGood (Condition)
+│   └── AttackPlayer (Action)
+├── FleeSequence
+│   ├── CheckHealthLow (Condition)
+│   └── RunAway (Action)
+└── PatrolSequence
+    ├── PickWaypoint (Action)
+    ├── MoveToWaypoint (Action)
+    └── Wait (Action)
+```
+
+
+### 黑板变量
+
+定义以下黑板变量：
+
+- `cocosNode`：Node - Cocos 节点引用
+- `health`：Number - 生命值
+- `playerNode`：Object - 玩家节点引用
+- `detectionRange`：Number - 检测范围
+- `attackRange`：Number - 攻击范围
+- `currentWaypoint`：Number - 当前路点索引
+
+
+### 实现检测系统
+
+创建 `assets/scripts/ai/PlayerDetector.ts`：
+
+```typescript
+import { _decorator, Component, Node, Vec3 } from 'cc';
+import { BehaviorTreeRuntimeComponent } from '@esengine/behavior-tree';
+
+const { ccclass, property } = _decorator;
+
+@ccclass('PlayerDetector')
+export class PlayerDetector extends Component {
+    @property(Node)
+    player: Node = null;
+
+    @property
+    detectionRange: number = 10;
+
+    private runtime: BehaviorTreeRuntimeComponent | null = null;
+
+    start() {
+        // 假设AI组件在同一节点上
+        const aiComponent = this.node.getComponent('EnemyAIComponent') as any;
+        if (aiComponent && aiComponent.aiEntity) {
+            this.runtime = aiComponent.aiEntity.getComponent(BehaviorTreeRuntimeComponent);
+        }
+    }
+
+    update(deltaTime: number) {
+        if (!this.runtime || !this.player) {
+            return;
+        }
+
+        // 计算距离
+        const distance = Vec3.distance(this.node.position, this.player.position);
+
+        // 更新黑板
+        this.runtime.setBlackboardValue('playerNode', this.player);
+        this.runtime.setBlackboardValue('playerInRange', distance <= this.detectionRange);
+        this.runtime.setBlackboardValue('distanceToPlayer', distance);
+    }
+}
+```
+
+
+## 资源管理
+
+### 使用 BehaviorTreeAssetManager
+
+框架提供了 `BehaviorTreeAssetManager` 来统一管理行为树资产，避免重复创建：
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeAssetManager,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter
+} from '@esengine/behavior-tree';
+
+// 获取资产管理器（插件已自动注册）
+const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+
+// 创建并注册行为树（只创建一次）
+const enemyAI = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .selector('MainBehavior')
+        .log('攻击')
+    .end()
+    .build();
+
+assetManager.loadAsset(enemyAI);
+
+// 为多个敌人实体使用同一份资产
+for (let i = 0; i < 10; i++) {
+    const enemy = scene.createEntity(`Enemy${i}`);
+    const tree = assetManager.getAsset('EnemyAI')!;
+    BehaviorTreeStarter.start(enemy, tree);  // 10个敌人共享1份数据
+}
+```
+
+### 从 Cocos Creator 资源加载
+
+#### 1. 将行为树 JSON 放入 resources 目录
+
+```
+assets/
+└── resources/
+    └── behaviors/
+        ├── enemy-ai.btree.json
+        └── boss-ai.btree.json
+```
+
+#### 2. 创建资源加载器
+
+创建 `assets/scripts/BehaviorTreeLoader.ts`：
+
+```typescript
+import { resources, JsonAsset } from 'cc';
+import { Core } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeAssetManager,
+    BehaviorTreeAssetSerializer,
+    BehaviorTreeData
+} from '@esengine/behavior-tree';
+
+export class BehaviorTreeLoader {
+    private assetManager: BehaviorTreeAssetManager;
+
+    constructor() {
+        this.assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+    }
+
+    /**
+     * 从 resources 目录加载行为树
+     * @param path 相对于 resources 的路径，不带扩展名
+     * @example await loader.load('behaviors/enemy-ai')
+     */
+    async load(path: string): Promise<BehaviorTreeData | null> {
+        return new Promise((resolve, reject) => {
+            resources.load(path, JsonAsset, (err, jsonAsset) => {
+                if (err) {
+                    console.error(`加载行为树失败: ${path}`, err);
+                    reject(err);
+                    return;
+                }
+
+                try {
+                    // 反序列化 JSON 为 BehaviorTreeData
+                    const jsonStr = JSON.stringify(jsonAsset.json);
+                    const treeData = BehaviorTreeAssetSerializer.deserialize(jsonStr);
+
+                    // 加载到资产管理器
+                    this.assetManager.loadAsset(treeData);
+
+                    console.log(`行为树已加载: ${treeData.name}`);
+                    resolve(treeData);
+                } catch (error) {
+                    console.error(`解析行为树失败: ${path}`, error);
+                    reject(error);
+                }
+            });
+        });
+    }
+
+    /**
+     * 预加载所有行为树
+     */
+    async preloadAll(paths: string[]): Promise<void> {
+        const promises = paths.map(path => this.load(path));
+        await Promise.all(promises);
+        console.log(`已预加载 ${paths.length} 个行为树`);
+    }
+}
+```
+
+#### 3. 在游戏启动时预加载
+
+修改 `Main.ts`：
+
+```typescript
+import { _decorator, Component } from 'cc';
+import { Core, Scene } from '@esengine/ecs-framework';
+import { BehaviorTreePlugin } from '@esengine/behavior-tree';
+import { BehaviorTreeLoader } from './BehaviorTreeLoader';
+
+const { ccclass } = _decorator;
+
+@ccclass('Main')
+export class Main extends Component {
+    private loader: BehaviorTreeLoader | null = null;
+
+    async onLoad() {
+        // 初始化 ECS Core
+        Core.create();
+
+        // 安装行为树插件
+        const behaviorTreePlugin = new BehaviorTreePlugin();
+        await Core.installPlugin(behaviorTreePlugin);
+
+        // 创建场景
+        const scene = new Scene();
+        behaviorTreePlugin.setupScene(scene);
+        Core.setScene(scene);
+
+        // 创建加载器并预加载所有行为树
+        this.loader = new BehaviorTreeLoader();
+        await this.loader.preloadAll([
+            'behaviors/enemy-ai',
+            'behaviors/boss-ai',
+            'behaviors/patrol',  // 子树
+            'behaviors/chase'    // 子树
+        ]);
+
+        console.log('游戏初始化完成');
+    }
+
+    update(deltaTime: number) {
+        Core.update(deltaTime);
+    }
+
+    onDestroy() {
+        Core.destroy();
+    }
+}
+```
+
+#### 4. 在敌人组件中使用
+
+```typescript
+import { _decorator, Component } from 'cc';
+import { Core, Entity } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeAssetManager,
+    BehaviorTreeStarter
+} from '@esengine/behavior-tree';
+
+const { ccclass, property } = _decorator;
+
+@ccclass('EnemyAIComponent')
+export class EnemyAIComponent extends Component {
+    @property
+    aiType: string = 'enemy-ai';  // 在编辑器中配置使用哪个AI
+
+    private aiEntity: Entity | null = null;
+
+    start() {
+        const scene = Core.scene;
+        if (!scene) return;
+
+        // 从资产管理器获取已加载的行为树
+        const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+        const tree = assetManager.getAsset(this.aiType);
+
+        if (tree) {
+            this.aiEntity = scene.createEntity(`AI_${this.node.name}`);
+            BehaviorTreeStarter.start(this.aiEntity, tree);
+
+            // 设置黑板变量
+            const runtime = this.aiEntity.getComponent(BehaviorTreeRuntimeComponent);
+            runtime?.setBlackboardValue('cocosNode', this.node);
+        } else {
+            console.error(`找不到行为树资产: ${this.aiType}`);
+        }
+    }
+
+    onDestroy() {
+        if (this.aiEntity) {
+            BehaviorTreeStarter.stop(this.aiEntity);
+        }
+    }
+}
+```
+
+## 调试
+
+### 可视化调试信息
+
+创建调试组件显示 AI 状态：
+
+```typescript
+import { _decorator, Component, Label } from 'cc';
+import { BehaviorTreeRuntimeComponent } from '@esengine/behavior-tree';
+
+const { ccclass, property } = _decorator;
+
+@ccclass('AIDebugger')
+export class AIDebugger extends Component {
+    @property(Label)
+    debugLabel: Label = null;
+
+    private runtime: BehaviorTreeRuntimeComponent | null = null;
+
+    start() {
+        const aiComponent = this.node.getComponent('EnemyAIComponent') as any;
+        if (aiComponent && aiComponent.aiEntity) {
+            this.runtime = aiComponent.aiEntity.getComponent(BehaviorTreeRuntimeComponent);
+        }
+    }
+
+    update() {
+        if (!this.runtime || !this.debugLabel) {
+            return;
+        }
+
+        const health = this.runtime.getBlackboardValue('health');
+        const playerNode = this.runtime.getBlackboardValue('playerNode');
+
+        this.debugLabel.string = `Health: ${health}\nHas Target: ${playerNode ? 'Yes' : 'No'}`;
+    }
+}
+```
+
+
+## 性能优化
+
+### 1. 限制行为树数量
+
+合理控制同时运行的行为树数量：
+
+```typescript
+class AIManager {
+    private activeAIs: Entity[] = [];
+    private maxAIs: number = 20;
+
+    addAI(entity: Entity, tree: BehaviorTreeData) {
+        if (this.activeAIs.length >= this.maxAIs) {
+            // 移除最远的AI
+            const furthest = this.findFurthestAI();
+            if (furthest) {
+                BehaviorTreeStarter.stop(furthest);
+                this.activeAIs = this.activeAIs.filter(e => e !== furthest);
+            }
+        }
+
+        BehaviorTreeStarter.start(entity, tree);
+        this.activeAIs.push(entity);
+    }
+
+    removeAI(entity: Entity) {
+        BehaviorTreeStarter.stop(entity);
+        this.activeAIs = this.activeAIs.filter(e => e !== entity);
+    }
+
+    private findFurthestAI(): Entity | null {
+        // 根据距离找到最远的AI
+        // 实现细节略
+        return this.activeAIs[0];
+    }
+}
+```
+
+### 2. 使用冷却装饰器
+
+对于不需要每帧更新的AI，使用冷却装饰器：
+
+```typescript
+const tree = BehaviorTreeBuilder.create('ThrottledAI')
+    .cooldown(0.2, 'ThrottleRoot')  // 每0.2秒执行一次
+        .selector('MainBehavior')
+            // AI逻辑...
+        .end()
+    .end()
+    .build();
+```
+
+### 3. 缓存计算结果
+
+在自定义执行器中缓存昂贵的计算：
+
+```typescript
+export class CachedFindTarget implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { state, runtime, totalTime } = context;
+        const cacheTime = state.lastFindTime || 0;
+
+        if (totalTime - cacheTime < 1.0) {
+            const cached = runtime.getBlackboardValue('target');
+            return cached ? TaskStatus.Success : TaskStatus.Failure;
+        }
+
+        const target = findNearestTarget();
+        runtime.setBlackboardValue('target', target);
+        state.lastFindTime = totalTime;
+
+        return target ? TaskStatus.Success : TaskStatus.Failure;
+    }
+}
+```
+
+## 多平台注意事项
+
+### 性能考虑
+
+不同平台的性能差异：
+
+- **Web平台**: 受浏览器性能限制，建议减少同时运行的AI数量
+- **原生平台**: 性能较好，可以运行更多AI
+- **小游戏平台**: 内存受限，注意控制行为树数量和复杂度
+
+### 平台适配
+
+```typescript
+import { sys } from 'cc';
+
+// 根据平台调整AI数量
+const maxAIs = sys.isNative ? 50 : (sys.isBrowser ? 20 : 30);
+
+// 根据平台调整更新频率
+const updateInterval = sys.isNative ? 0.016 : 0.05;
+```
+
+## 常见问题
+
+### 行为树无法加载？
+
+检查：
+1. 资源路径是否正确（相对于 `resources` 目录）
+2. 文件是否已添加到项目中
+3. 检查控制台错误信息
+
+### AI 不执行？
+
+确保：
+1. `Main` 组件的 `update` 方法被调用
+2. `Scene.update()` 在每帧被调用
+3. 行为树已通过 `BehaviorTreeStarter.start()` 启动
+
+### 黑板变量不更新？
+
+检查：
+1. 变量名拼写是否正确
+2. 是否在正确的时机更新变量
+3. 使用 `BehaviorTreeRuntimeComponent.getBlackboardValue()` 和 `setBlackboardValue()` 方法
+
+## 下一步
+
+- 查看[资产管理](./asset-management.md)了解如何加载和管理行为树资产、使用子树
+- 学习[高级用法](./advanced-usage.md)了解性能优化和调试技巧
+- 阅读[最佳实践](./best-practices.md)优化你的 AI
+- 学习[自定义节点执行器](./custom-actions.md)创建自定义行为

docs/modules/behavior-tree/core-concepts.md

@@ -0,0 +1,491 @@
+# 核心概念
+
+本文介绍行为树系统的核心概念和工作原理。
+
+## 什么是行为树?
+
+行为树(Behavior Tree)是一种用于控制AI和自动化系统的决策结构。它通过树状层次结构组织任务,从根节点开始逐层执行,直到找到合适的行为。
+
+### 与状态机的对比
+
+传统状态机:
+- 基于状态和转换
+- 状态之间的转换复杂
+- 难以扩展和维护
+- 不便于复用
+
+行为树:
+- 基于任务和层次结构
+- 模块化、易于复用
+- 可视化编辑
+- 灵活的决策逻辑
+
+
+## 树结构
+
+行为树由节点组成,形成树状结构:
+
+```
+Root (根节点)
+├── Selector (选择器)
+│   ├── Sequence (序列)
+│   │   ├── Condition (条件)
+│   │   └── Action (动作)
+│   └── Action (动作)
+└── Sequence (序列)
+    ├── Action (动作)
+    └── Wait (等待)
+```
+
+每个节点都有:
+- 父节点(除了根节点)
+- 零个或多个子节点
+- 执行状态
+- 返回结果
+
+
+## 节点类型
+
+### 复合节点(Composite)
+
+复合节点有多个子节点,按特定规则执行它们。
+
+#### Selector(选择器)
+
+按顺序尝试执行子节点,直到某个子节点成功。
+
+```typescript
+const tree = BehaviorTreeBuilder.create('FindFood')
+    .selector('FindFoodSelector')
+        .log('尝试吃附近的食物', 'EatNearby')
+        .log('搜索食物', 'SearchFood')
+        .log('放弃', 'GiveUp')
+    .end()
+    .build();
+```
+
+执行逻辑:
+1. 尝试第一个子节点
+2. 如果返回Success,选择器成功
+3. 如果返回Failure,尝试下一个子节点
+4. 如果返回Running,选择器返回Running
+5. 所有子节点都失败时,选择器失败
+
+
+#### Sequence(序列)
+
+按顺序执行所有子节点,直到某个子节点失败。
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Attack')
+    .sequence('AttackSequence')
+        .blackboardExists('target')  // 检查是否有目标
+        .log('瞄准', 'Aim')
+        .log('开火', 'Fire')
+    .end()
+    .build();
+```
+
+执行逻辑:
+1. 依次执行子节点
+2. 如果子节点返回Failure,序列失败
+3. 如果子节点返回Running,序列返回Running
+4. 如果子节点返回Success,继续下一个子节点
+5. 所有子节点都成功时,序列成功
+
+
+#### Parallel(并行)
+
+同时执行多个子节点。
+
+```typescript
+const tree = BehaviorTreeBuilder.create('PlayEffects')
+    .parallel('Effects', {
+        successPolicy: 'all',  // 所有任务都要成功
+        failurePolicy: 'one'   // 任一失败则失败
+    })
+        .log('播放动画', 'PlayAnimation')
+        .log('播放音效', 'PlaySound')
+        .log('生成粒子', 'SpawnEffect')
+    .end()
+    .build();
+```
+
+策略类型:
+- `successPolicy: 'all'`: 所有子节点都成功才成功
+- `successPolicy: 'one'`: 任意一个子节点成功就成功
+- `failurePolicy: 'all'`: 所有子节点都失败才失败
+- `failurePolicy: 'one'`: 任意一个子节点失败就失败
+
+
+### 装饰器节点(Decorator)
+
+装饰器节点只有一个子节点,用于修改子节点的行为或结果。
+
+#### Inverter(反转)
+
+反转子节点的结果:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('CheckSafe')
+    .inverter('NotHasEnemy')
+        .blackboardExists('enemy')
+    .end()
+    .build();
+```
+
+#### Repeater(重复)
+
+重复执行子节点:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Jump3Times')
+    .repeater(3, 'RepeatJump')
+        .log('跳跃', 'Jump')
+    .end()
+    .build();
+```
+
+#### Cooldown(冷却)
+
+限制子节点的执行频率:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('UseSkill')
+    .cooldown(5.0, 'SkillCooldown')
+        .log('使用特殊技能', 'UseSpecialAbility')
+    .end()
+    .build();
+```
+
+#### Timeout(超时)
+
+限制子节点的执行时间:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('TimedTask')
+    .timeout(10.0, 'TaskTimeout')
+        .log('长时间运行的任务', 'ComplexTask')
+    .end()
+    .build();
+```
+
+
+### 叶节点(Leaf)
+
+叶节点没有子节点,执行具体的任务。
+
+#### Action(动作)
+
+执行具体操作。内置动作节点包括:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Actions')
+    .sequence()
+        .wait(2.0)  // 等待2秒
+        .log('Hello', 'LogAction')  // 输出日志
+        .setBlackboardValue('score', 100)  // 设置黑板值
+        .modifyBlackboardValue('score', 'add', 10)  // 修改黑板值
+    .end()
+    .build();
+```
+
+要实现自定义动作,需要创建自定义执行器,参见[自定义节点执行器](./custom-actions.md)。
+
+#### Condition(条件)
+
+检查条件。内置条件节点包括:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Conditions')
+    .selector()
+        .blackboardExists('player')  // 检查变量是否存在
+        .blackboardCompare('health', 50, 'greater')  // 比较变量值
+        .randomProbability(0.5)  // 50%概率
+    .end()
+    .build();
+```
+
+#### Wait(等待)
+
+等待指定时间:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('WaitExample')
+    .wait(2.0, 'Wait2Seconds')
+    .build();
+```
+
+
+## 任务状态
+
+每个节点执行后返回以下状态之一:
+
+### Success(成功)
+
+任务成功完成。
+
+```typescript
+// 内置节点会根据逻辑自动返回Success
+.log('任务完成')  // 总是返回Success
+.blackboardCompare('score', 100, 'greater')  // 条件满足时返回Success
+```
+
+### Failure(失败)
+
+任务执行失败。
+
+```typescript
+.blackboardCompare('score', 100, 'greater')  // 条件不满足返回Failure
+.blackboardExists('nonExistent')  // 变量不存在返回Failure
+```
+
+### Running(运行中)
+
+任务需要多帧完成,仍在执行中。
+
+```typescript
+.wait(3.0)  // 等待过程中返回Running,3秒后返回Success
+```
+
+### Invalid(无效)
+
+节点未初始化或已重置。通常不需要手动处理此状态。
+
+
+## 黑板系统
+
+黑板(Blackboard)是行为树的数据存储系统,用于在节点之间共享数据。
+
+### 本地黑板
+
+每个行为树实例都有自己的本地黑板:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .defineBlackboardVariable('state', 'idle')
+    // ...
+    .build();
+```
+
+### 支持的数据类型
+
+黑板支持以下数据类型:
+- String：字符串
+- Number：数字
+- Boolean：布尔值
+- Vector2：二维向量
+- Vector3：三维向量
+- Object：对象引用
+- Array：数组
+
+示例:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Variables')
+    .defineBlackboardVariable('name', 'Enemy')  // 字符串
+    .defineBlackboardVariable('count', 0)  // 数字
+    .defineBlackboardVariable('isActive', true)  // 布尔值
+    .defineBlackboardVariable('position', { x: 0, y: 0 })  // 对象(也可用于Vector2)
+    .defineBlackboardVariable('velocity', { x: 0, y: 0, z: 0 })  // 对象(也可用于Vector3)
+    .defineBlackboardVariable('items', [])  // 数组
+    .build();
+```
+
+### 读写变量
+
+通过`BehaviorTreeRuntimeComponent`访问黑板:
+
+```typescript
+const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+
+// 读取变量
+const health = runtime?.getBlackboardValue('health');
+const target = runtime?.getBlackboardValue('target');
+
+// 写入变量
+runtime?.setBlackboardValue('health', 50);
+runtime?.setBlackboardValue('lastAttackTime', Date.now());
+
+// 获取所有变量
+const allVars = runtime?.getAllBlackboardVariables();
+```
+
+也可以使用内置节点操作黑板:
+
+```typescript
+const tree = BehaviorTreeBuilder.create('BlackboardOps')
+    .sequence()
+        .setBlackboardValue('score', 100)  // 设置值
+        .modifyBlackboardValue('score', 'add', 10)  // 增加10
+        .blackboardCompare('score', 110, 'equals')  // 检查是否等于110
+    .end()
+    .build();
+```
+
+### 全局黑板
+
+所有行为树实例共享的黑板,通过`GlobalBlackboardService`访问:
+
+```typescript
+import { GlobalBlackboardService } from '@esengine/behavior-tree';
+import { Core } from '@esengine/ecs-framework';
+
+const globalBlackboard = Core.services.resolve(GlobalBlackboardService);
+
+// 设置全局变量
+globalBlackboard.setValue('gameState', 'playing');
+globalBlackboard.setValue('difficulty', 5);
+
+// 读取全局变量
+const gameState = globalBlackboard.getValue('gameState');
+```
+
+在自定义执行器中访问全局黑板:
+
+```typescript
+import { GlobalBlackboardService } from '@esengine/behavior-tree';
+import { Core } from '@esengine/ecs-framework';
+
+export class CheckGameState implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const globalBlackboard = Core.services.resolve(GlobalBlackboardService);
+        const gameState = globalBlackboard.getValue('gameState');
+
+        if (gameState === 'paused') {
+            return TaskStatus.Failure;
+        }
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+
+## 执行流程
+
+### 初始化
+
+```typescript
+// 1. 初始化Core和插件
+Core.create();
+const plugin = new BehaviorTreePlugin();
+await Core.installPlugin(plugin);
+
+// 2. 创建场景
+const scene = new Scene();
+plugin.setupScene(scene);
+Core.setScene(scene);
+
+// 3. 构建行为树
+const tree = BehaviorTreeBuilder.create('AI')
+    // ... 定义节点
+    .build();
+
+// 4. 创建实体并启动
+const entity = scene.createEntity('AIEntity');
+BehaviorTreeStarter.start(entity, tree);
+```
+
+### 更新循环
+
+```typescript
+// 每帧更新
+gameLoop(() => {
+    const deltaTime = getDeltaTime();
+    Core.update(deltaTime);  // Core会自动更新场景和所有行为树
+});
+```
+
+### 执行顺序
+
+```
+1. 从根节点开始
+2. 根节点执行其逻辑(通常是Selector或Sequence)
+3. 根节点的子节点按顺序执行
+4. 每个子节点可能有自己的子节点
+5. 叶节点执行具体操作并返回状态
+6. 状态向上传播到父节点
+7. 父节点根据策略决定如何处理子节点的状态
+8. 最终根节点返回整体状态
+```
+
+### 执行示例
+
+```typescript
+const tree = BehaviorTreeBuilder.create('Example')
+    .selector('Root')  // 1. 执行选择器
+        .sequence('Branch1')  // 2. 尝试第一个分支
+            .blackboardCompare('ready', true, 'equals', 'CheckReady')  // 3. 条件失败
+        .end()  // 4. 序列失败,选择器继续下一个分支
+        .sequence('Branch2')  // 5. 尝试第二个分支
+            .blackboardCompare('active', true, 'equals', 'CheckActive')  // 6. 条件成功
+            .log('执行动作', 'DoAction')  // 7. 动作成功
+        .end()  // 8. 序列成功,选择器成功
+    .end()  // 9. 整个树成功
+    .build();
+```
+
+执行流程图:
+
+```
+Root(Selector)
+  → Branch1(Sequence)
+    → CheckReady: Failure
+  → Branch1 fails
+  → Branch2(Sequence)
+    → CheckActive: Success
+    → DoAction: Success
+  → Branch2 succeeds
+→ Root succeeds
+```
+
+
+## Runtime架构
+
+本框架的行为树采用Runtime执行器架构:
+
+### 核心组件
+
+- **BehaviorTreeData**: 纯数据结构,描述行为树的结构和配置
+- **BehaviorTreeRuntimeComponent**: 运行时组件,管理执行状态和黑板
+- **BehaviorTreeExecutionSystem**: 执行系统,驱动行为树运行
+- **INodeExecutor**: 节点执行器接口,定义节点的执行逻辑
+- **NodeExecutionContext**: 执行上下文,包含执行所需的所有信息
+
+### 架构特点
+
+1. **数据与逻辑分离**: BehaviorTreeData是纯数据,执行逻辑在执行器中
+2. **无状态执行器**: 执行器实例可以在多个节点间共享,状态存储在Runtime中
+3. **类型安全**: 通过TypeScript类型系统保证类型安全
+4. **高性能**: 避免不必要的对象创建,优化内存使用
+
+### 数据流
+
+```
+BehaviorTreeBuilder
+  ↓ (构建)
+BehaviorTreeData
+  ↓ (加载到)
+BehaviorTreeAssetManager
+  ↓ (读取)
+BehaviorTreeExecutionSystem
+  ↓ (执行)
+INodeExecutor.execute(context)
+  ↓ (返回)
+TaskStatus
+  ↓ (更新)
+NodeRuntimeState
+```
+
+
+## 下一步
+
+现在你已经理解了行为树的核心概念,接下来可以:
+
+- 查看[快速开始](./getting-started.md)创建第一个行为树
+- 学习[自定义节点执行器](./custom-actions.md)创建自定义节点
+- 探索[高级用法](./advanced-usage.md)了解更多功能
+- 阅读[最佳实践](./best-practices.md)学习设计模式

docs/modules/behavior-tree/editor-guide.md

@@ -0,0 +1,119 @@
+# 行为树编辑器使用指南
+
+行为树编辑器提供了可视化的方式来创建和编辑行为树。
+
+## 启动编辑器
+
+```bash
+cd packages/editor-app
+npm run tauri:dev
+```
+
+## 基本操作
+
+### 打开行为树编辑器
+
+通过以下方式打开行为树编辑器窗口：
+
+1. 在资产浏览器中双击 `.btree` 文件
+2. 菜单栏：`窗口` → 选择行为树编辑器相关插件
+
+### 创建新行为树
+
+在行为树编辑器窗口的工具栏中点击"新建"按钮（加号图标）
+
+### 保存行为树
+
+在行为树编辑器窗口的工具栏中点击"保存"按钮（磁盘图标）
+
+### 添加节点
+
+从左侧节点面板拖拽节点到画布：
+- 复合节点：Selector、Sequence、Parallel
+- 装饰器：Inverter、Repeater、UntilFail等
+- 动作节点：ExecuteAction、Wait等
+- 条件节点：Condition
+
+### 连接节点
+
+拖拽父节点底部的连接点到子节点顶部建立连接
+
+### 删除节点
+
+选中节点后按 `Delete` 或 `Backspace` 键
+
+### 编辑属性
+
+点击节点后在右侧属性面板中编辑节点参数
+
+## 黑板变量
+
+在黑板面板中管理共享数据：
+
+1. 点击"添加变量"按钮
+2. 输入变量名、选择类型并设置默认值
+3. 在节点中通过变量名引用黑板变量
+
+支持的变量类型：
+- String：字符串
+- Number：数字
+- Boolean：布尔值
+- Vector2：二维向量
+- Vector3：三维向量
+- Object：对象引用
+- Array：数组
+
+## 导出运行时资产
+
+### 导出步骤
+
+1. 点击工具栏的"导出"按钮
+2. 选择导出模式：
+   - 当前文件：仅导出当前打开的行为树
+   - 工作区导出：导出项目中所有行为树
+3. 选择资产输出路径
+4. 选择TypeScript类型定义输出路径
+5. 为每个文件选择导出格式：
+   - 二进制：.btree.bin（默认，文件更小，加载更快）
+   - JSON：.btree.json（可读性好，便于调试）
+6. 点击"导出"按钮
+
+### 加载运行时资产
+
+编辑器导出的文件是编辑器格式，包含UI布局信息。当前版本中，从编辑器导出的资产可以使用Builder API在代码中重新构建，或者等待资产加载系统的完善。
+
+推荐使用Builder API创建行为树：
+
+```typescript
+import { BehaviorTreeBuilder, BehaviorTreeStarter } from '@esengine/behavior-tree';
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// 使用Builder创建行为树
+const tree = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('MainBehavior')
+        .sequence('AttackBranch')
+            .blackboardCompare('health', 50, 'greater')
+            .log('攻击玩家', 'Attack')
+        .end()
+        .log('逃离战斗', 'Flee')
+    .end()
+    .build();
+
+// 启动行为树
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, tree);
+```
+
+## 支持的操作
+
+- `Delete` / `Backspace`：删除选中的节点或连线
+- `Ctrl` + 点击：多选节点
+- 框选：拖拽空白区域进行框选
+- 拖拽画布：按住鼠标中键或空格键拖拽
+
+## 下一步
+
+- 查看[编辑器工作流](./editor-workflow.md)了解完整的开发流程
+- 查看[自定义节点执行器](./custom-actions.md)学习如何扩展节点

docs/modules/behavior-tree/editor-workflow.md

@@ -0,0 +1,253 @@
+# 编辑器工作流
+
+本教程介绍如何使用行为树编辑器创建AI，并在游戏中加载使用。
+
+## 完整流程
+
+```
+1. 启动编辑器
+2. 创建行为树并定义黑板变量
+3. 添加和配置节点
+4. 导出JSON文件
+5. 在游戏中加载并使用
+```
+
+## 使用编辑器创建
+
+### 启动编辑器
+
+```bash
+cd packages/editor-app
+npm run tauri:dev
+```
+
+### 基本操作
+
+1. **创建行为树**：`文件` → `新建项目` → 创建行为树文件
+2. **定义黑板变量**：在黑板面板中添加共享变量
+3. **添加节点**：从节点面板拖拽到画布
+4. **连接节点**：拖拽连接点建立父子关系
+5. **配置属性**：选中节点后在属性面板编辑
+6. **导出**：`文件` → `导出` → `JSON格式`
+
+### 示例：敌人AI的黑板变量
+
+在编辑器黑板面板中定义：
+
+```
+health: Number = 100
+target: Object = null
+moveSpeed: Number = 5.0
+attackRange: Number = 2.0
+```
+
+### 示例：行为树结构
+
+```
+Root: Selector
+├── Combat Sequence
+│   ├── CheckHasTarget (Condition)
+│   ├── CheckInAttackRange (Condition)
+│   └── ExecuteAttack (Action)
+├── Patrol Sequence
+│   ├── MoveToNextPatrolPoint (Action)
+│   └── Wait 2s
+└── Idle (Action)
+```
+
+## 在游戏中使用
+
+### 使用Builder API创建
+
+推荐使用Builder API在代码中创建行为树：
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    BehaviorTreePlugin,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreeRuntimeComponent
+} from '@esengine/behavior-tree';
+
+// 初始化
+Core.create();
+const plugin = new BehaviorTreePlugin();
+await Core.installPlugin(plugin);
+
+const scene = new Scene();
+plugin.setupScene(scene);
+Core.setScene(scene);
+
+// 使用Builder创建行为树
+const tree = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .defineBlackboardVariable('moveSpeed', 5.0)
+    .selector('MainBehavior')
+        .sequence('AttackBranch')
+            .blackboardExists('target')
+            .blackboardCompare('health', 30, 'greater')
+            .log('攻击目标', 'Attack')
+        .end()
+        .log('巡逻', 'Patrol')
+    .end()
+    .build();
+
+// 创建实体并启动行为树
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, tree);
+
+// 访问和修改黑板
+const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+runtime?.setBlackboardValue('target', someTarget);
+
+// 游戏循环
+setInterval(() => {
+    Core.update(0.016); // 60 FPS
+}, 16);
+```
+
+## 实现自定义执行器
+
+要扩展行为树的功能，需要创建自定义执行器（详见[自定义节点执行器](./custom-actions.md)）：
+
+```typescript
+import {
+    INodeExecutor,
+    NodeExecutionContext,
+    BindingHelper,
+    NodeExecutorMetadata
+} from '@esengine/behavior-tree';
+import { TaskStatus, NodeType } from '@esengine/behavior-tree';
+
+@NodeExecutorMetadata({
+    implementationType: 'AttackAction',
+    nodeType: NodeType.Action,
+    displayName: '攻击目标',
+    description: '对目标造成伤害',
+    category: '战斗',
+    configSchema: {
+        damage: {
+            type: 'number',
+            default: 10,
+            supportBinding: true
+        }
+    }
+})
+export class AttackAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const damage = BindingHelper.getValue<number>(context, 'damage', 10);
+        const target = context.runtime.getBlackboardValue('target');
+
+        if (!target) {
+            return TaskStatus.Failure;
+        }
+
+        // 执行攻击逻辑
+        performAttack(context.entity, target, damage);
+        return TaskStatus.Success;
+    }
+
+    reset(context: NodeExecutionContext): void {
+        // 清理状态
+    }
+}
+```
+
+## 调试技巧
+
+### 1. 使用日志节点
+
+在行为树中添加Log节点输出调试信息：
+
+```typescript
+const tree = BehaviorTreeBuilder.create('DebugAI')
+    .log('开始战斗序列', 'StartCombat')
+    .sequence('Combat')
+        .blackboardCompare('health', 0, 'greater')
+        .log('执行攻击', 'Attack')
+    .end()
+    .build();
+```
+
+### 2. 监控黑板状态
+
+```typescript
+const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+console.log('黑板变量:', runtime?.getAllBlackboardVariables());
+console.log('活动节点:', Array.from(runtime?.activeNodeIds || []));
+```
+
+### 3. 在自定义执行器中调试
+
+```typescript
+export class DebugAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const { nodeData, runtime, state } = context;
+
+        console.group(`[${nodeData.name}]`);
+        console.log('配置:', nodeData.config);
+        console.log('状态:', state);
+        console.log('黑板:', runtime.getAllBlackboardVariables());
+        console.groupEnd();
+
+        return TaskStatus.Success;
+    }
+}
+```
+
+## 完整示例
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    BehaviorTreePlugin,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreeRuntimeComponent
+} from '@esengine/behavior-tree';
+
+// 初始化
+Core.create();
+const plugin = new BehaviorTreePlugin();
+await Core.installPlugin(plugin);
+
+const scene = new Scene();
+plugin.setupScene(scene);
+Core.setScene(scene);
+
+// 使用Builder API构建行为树
+const tree = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('hasTarget', false)
+    .selector('Root')
+        .sequence('Combat')
+            .blackboardCompare('hasTarget', true, 'equals')
+            .log('攻击玩家', 'Attack')
+        .end()
+        .log('空闲', 'Idle')
+    .end()
+    .build();
+
+// 创建实体并启动
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, tree);
+
+// 模拟发现目标
+setTimeout(() => {
+    const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+    runtime?.setBlackboardValue('hasTarget', true);
+}, 2000);
+
+// 游戏循环
+setInterval(() => {
+    Core.update(0.016);
+}, 16);
+```
+
+## 下一步
+
+- 查看[自定义节点执行器](./custom-actions.md)学习如何创建自定义节点
+- 查看[高级用法](./advanced-usage.md)了解性能优化等高级特性
+- 查看[最佳实践](./best-practices.md)优化你的AI设计

docs/modules/behavior-tree/getting-started.md

@@ -0,0 +1,385 @@
+# 快速开始
+
+本教程将引导你在5分钟内创建第一个行为树。
+
+## 安装
+
+```bash
+npm install @esengine/behavior-tree
+```
+
+## 第一个行为树
+
+让我们创建一个简单的AI行为树,实现"巡逻-发现敌人-攻击"的逻辑。
+
+### 步骤1: 导入依赖
+
+```typescript
+import { Core, Scene, Entity } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreePlugin
+} from '@esengine/behavior-tree';
+```
+
+### 步骤2: 初始化Core并安装插件
+
+```typescript
+Core.create();
+const plugin = new BehaviorTreePlugin();
+await Core.installPlugin(plugin);
+```
+
+### 步骤3: 创建场景并设置行为树系统
+
+```typescript
+const scene = new Scene();
+plugin.setupScene(scene);
+Core.setScene(scene);
+```
+
+### 步骤4: 构建行为树数据
+
+```typescript
+const guardAITree = BehaviorTreeBuilder.create('GuardAI')
+    // 定义黑板变量
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('hasEnemy', false)
+    .defineBlackboardVariable('patrolPoint', 0)
+
+    // 根选择器
+    .selector('RootSelector')
+        // 分支1: 如果发现敌人且生命值高,则攻击
+        .selector('CombatBranch')
+            .blackboardExists('hasEnemy', 'CheckEnemy')
+            .blackboardCompare('health', 30, 'greater', 'CheckHealth')
+            .log('守卫正在攻击敌人', 'Attack')
+        .end()
+
+        // 分支2: 如果生命值低,则逃跑
+        .selector('FleeBranch')
+            .blackboardCompare('health', 30, 'lessOrEqual', 'CheckLowHealth')
+            .log('守卫生命值过低,正在逃跑', 'Flee')
+        .end()
+
+        // 分支3: 默认巡逻
+        .selector('PatrolBranch')
+            .modifyBlackboardValue('patrolPoint', 'add', 1, 'IncrementPatrol')
+            .log('守卫正在巡逻', 'Patrol')
+            .wait(2.0, 'WaitAtPoint')
+        .end()
+    .end()
+    .build();
+```
+
+### 步骤5: 创建实体并启动行为树
+
+```typescript
+// 创建守卫实体
+const guardEntity = scene.createEntity('Guard');
+
+// 启动行为树
+BehaviorTreeStarter.start(guardEntity, guardAITree);
+```
+
+### 步骤6: 运行游戏循环
+
+```typescript
+// 模拟游戏循环
+setInterval(() => {
+    Core.update(0.1);  // 传入deltaTime(秒)
+}, 100);  // 每100ms更新一次
+```
+
+### 步骤7: 模拟游戏事件
+
+```typescript
+// 5秒后模拟发现敌人
+setTimeout(() => {
+    const runtime = guardEntity.getComponent(BehaviorTreeRuntimeComponent);
+    runtime?.setBlackboardValue('hasEnemy', true);
+    console.log('发现敌人!');
+}, 5000);
+
+// 10秒后模拟受伤
+setTimeout(() => {
+    const runtime = guardEntity.getComponent(BehaviorTreeRuntimeComponent);
+    runtime?.setBlackboardValue('health', 20);
+    console.log('守卫受伤!');
+}, 10000);
+```
+
+## 完整代码
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreePlugin,
+    BehaviorTreeRuntimeComponent
+} from '@esengine/behavior-tree';
+
+async function main() {
+    // 1. 创建核心并安装插件
+    Core.create();
+    const plugin = new BehaviorTreePlugin();
+    await Core.installPlugin(plugin);
+
+    // 2. 创建场景
+    const scene = new Scene();
+    plugin.setupScene(scene);
+    Core.setScene(scene);
+
+    // 3. 构建行为树数据
+    const guardAITree = BehaviorTreeBuilder.create('GuardAI')
+        .defineBlackboardVariable('health', 100)
+        .defineBlackboardVariable('hasEnemy', false)
+        .defineBlackboardVariable('patrolPoint', 0)
+        .selector('RootSelector')
+            .selector('CombatBranch')
+                .blackboardExists('hasEnemy')
+                .blackboardCompare('health', 30, 'greater')
+                .log('守卫正在攻击敌人')
+            .end()
+            .selector('FleeBranch')
+                .blackboardCompare('health', 30, 'lessOrEqual')
+                .log('守卫生命值过低,正在逃跑')
+            .end()
+            .selector('PatrolBranch')
+                .modifyBlackboardValue('patrolPoint', 'add', 1)
+                .log('守卫正在巡逻')
+                .wait(2.0)
+            .end()
+        .end()
+        .build();
+
+    // 4. 创建守卫实体并启动行为树
+    const guardEntity = scene.createEntity('Guard');
+    BehaviorTreeStarter.start(guardEntity, guardAITree);
+
+    // 5. 运行游戏循环
+    setInterval(() => {
+        Core.update(0.1);
+    }, 100);
+
+    // 6. 模拟游戏事件
+    setTimeout(() => {
+        const runtime = guardEntity.getComponent(BehaviorTreeRuntimeComponent);
+        runtime?.setBlackboardValue('hasEnemy', true);
+        console.log('发现敌人!');
+    }, 5000);
+
+    setTimeout(() => {
+        const runtime = guardEntity.getComponent(BehaviorTreeRuntimeComponent);
+        runtime?.setBlackboardValue('health', 20);
+        console.log('守卫受伤!');
+    }, 10000);
+}
+
+main();
+```
+
+## 运行结果
+
+运行程序后,你会看到类似的输出:
+
+```
+守卫正在巡逻
+守卫正在巡逻
+守卫正在巡逻
+发现敌人!
+守卫正在攻击敌人
+守卫正在攻击敌人
+守卫受伤!
+守卫生命值过低,正在逃跑
+```
+
+## 理解代码
+
+### 黑板变量
+
+```typescript
+.defineBlackboardVariable('health', 100)
+.defineBlackboardVariable('hasEnemy', false)
+.defineBlackboardVariable('patrolPoint', 0)
+```
+
+黑板用于在节点之间共享数据。这里定义了三个变量:
+- `health`: 守卫的生命值
+- `hasEnemy`: 是否发现敌人
+- `patrolPoint`: 当前巡逻点编号
+
+### 选择器节点
+
+```typescript
+.selector('RootSelector')
+    // 分支1
+    // 分支2
+    // 分支3
+.end()
+```
+
+选择器按顺序尝试执行子节点,直到某个子节点返回成功。类似于编程中的 `if-else if-else`。
+
+### 条件节点
+
+```typescript
+.blackboardExists('hasEnemy')  // 检查变量是否存在
+.blackboardCompare('health', 30, 'greater')  // 比较变量值
+```
+
+条件节点用于检查黑板变量的值。
+
+### 动作节点
+
+```typescript
+.log('守卫正在攻击敌人')  // 输出日志
+.wait(2.0)  // 等待2秒
+.modifyBlackboardValue('patrolPoint', 'add', 1)  // 修改黑板值
+```
+
+动作节点执行具体的操作。
+
+### Runtime组件
+
+```typescript
+const runtime = guardEntity.getComponent(BehaviorTreeRuntimeComponent);
+runtime?.setBlackboardValue('hasEnemy', true);
+runtime?.getBlackboardValue('health');
+```
+
+通过`BehaviorTreeRuntimeComponent`访问和修改黑板变量。
+
+## 常见任务状态
+
+行为树的每个节点返回以下状态之一:
+
+- **Success**: 任务成功完成
+- **Failure**: 任务执行失败
+- **Running**: 任务正在执行,需要在后续帧继续
+- **Invalid**: 无效状态(未初始化或已重置)
+
+## 内置节点
+
+### 复合节点
+
+- `sequence()` - 序列节点,按顺序执行所有子节点
+- `selector()` - 选择器节点,按顺序尝试子节点直到成功
+- `parallel()` - 并行节点,同时执行多个子节点
+- `parallelSelector()` - 并行选择器
+- `randomSequence()` - 随机序列
+- `randomSelector()` - 随机选择器
+
+### 装饰器节点
+
+- `inverter()` - 反转子节点结果
+- `repeater(count)` - 重复执行子节点
+- `alwaysSucceed()` - 总是返回成功
+- `alwaysFail()` - 总是返回失败
+- `untilSuccess()` - 重复直到成功
+- `untilFail()` - 重复直到失败
+- `conditional(key, value, operator)` - 条件装饰器
+- `cooldown(time)` - 冷却装饰器
+- `timeout(time)` - 超时装饰器
+
+### 动作节点
+
+- `wait(duration)` - 等待指定时间
+- `log(message)` - 输出日志
+- `setBlackboardValue(key, value)` - 设置黑板值
+- `modifyBlackboardValue(key, operation, value)` - 修改黑板值
+- `executeAction(actionName)` - 执行自定义动作
+
+### 条件节点
+
+- `blackboardExists(key)` - 检查变量是否存在
+- `blackboardCompare(key, value, operator)` - 比较黑板值
+- `randomProbability(probability)` - 随机概率
+- `executeCondition(conditionName)` - 执行自定义条件
+
+## 控制行为树
+
+### 启动
+
+```typescript
+BehaviorTreeStarter.start(entity, treeData);
+```
+
+### 停止
+
+```typescript
+BehaviorTreeStarter.stop(entity);
+```
+
+### 暂停和恢复
+
+```typescript
+BehaviorTreeStarter.pause(entity);
+// ... 一段时间后
+BehaviorTreeStarter.resume(entity);
+```
+
+### 重启
+
+```typescript
+BehaviorTreeStarter.restart(entity);
+```
+
+## 下一步
+
+现在你已经创建了第一个行为树,接下来可以:
+
+1. 学习[核心概念](./core-concepts.md)深入理解行为树原理
+2. 学习[资产管理](./asset-management.md)了解如何加载和复用行为树、使用子树
+3. 查看[自定义节点执行器](./custom-actions.md)学习如何创建自定义节点
+4. 根据你的场景查看集成教程：[Cocos Creator](./cocos-integration.md) 或 [Node.js](./nodejs-usage.md)
+5. 查看[高级用法](./advanced-usage.md)了解更多功能
+
+## 常见问题
+
+### 为什么行为树不执行?
+
+确保:
+1. 已经安装了 `BehaviorTreePlugin`
+2. 调用了 `plugin.setupScene(scene)`
+3. 调用了 `BehaviorTreeStarter.start(entity, treeData)`
+4. 在游戏循环中调用了 `Core.update(deltaTime)`
+
+### 如何访问黑板变量?
+
+```typescript
+const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+
+// 读取
+const health = runtime?.getBlackboardValue('health');
+
+// 写入
+runtime?.setBlackboardValue('health', 50);
+
+// 获取所有变量
+const allVars = runtime?.getAllBlackboardVariables();
+```
+
+### 如何调试行为树?
+
+使用日志节点:
+
+```typescript
+.log('到达这个节点', 'DebugLog')
+```
+
+或者在代码中监控黑板:
+
+```typescript
+const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+console.log('黑板变量:', runtime?.getAllBlackboardVariables());
+console.log('活动节点:', Array.from(runtime?.activeNodeIds || []));
+```
+
+### 如何使用自定义逻辑?
+
+内置的`executeAction`和`executeCondition`节点只是占位符。要实现真正的自定义逻辑,你需要创建自定义执行器:
+
+参见[自定义节点执行器](./custom-actions.md)学习如何创建。

docs/modules/behavior-tree/index.md

@@ -0,0 +1,197 @@
+# 行为树系统
+
+行为树(Behavior Tree)是一种用于游戏AI和自动化控制的强大工具。本框架提供了基于Runtime执行器架构的行为树系统,具有高性能、类型安全、易于扩展的特点。
+
+## 什么是行为树?
+
+行为树是一种层次化的任务执行结构,由多个节点组成,每个节点负责特定的任务。行为树特别适合于:
+
+- 游戏AI(敌人、NPC行为)
+- 状态机的替代方案
+- 复杂的决策逻辑
+- 可视化的行为设计
+
+## 核心特性
+
+### Runtime执行器架构
+- 数据与逻辑分离
+- 无状态执行器设计
+- 高性能执行
+- 类型安全
+
+### 可视化编辑器
+- 图形化节点编辑
+- 实时预览和调试
+- 拖拽式节点创建
+- 属性连接和绑定
+
+### 灵活的黑板系统
+- 本地黑板(单个行为树)
+- 全局黑板(所有行为树共享)
+- 类型安全的变量访问
+- 支持属性绑定
+
+### 插件系统
+- 自动注册机制
+- 装饰器声明元数据
+- 支持多语言
+- 易于扩展
+
+## 文档导航
+
+### 入门教程
+
+- **[快速开始](./getting-started.md)** - 5分钟上手行为树
+- **[核心概念](./core-concepts.md)** - 理解行为树的基本原理
+
+### 编辑器使用
+
+- **[编辑器使用指南](./editor-guide.md)** - 可视化创建行为树
+- **[编辑器工作流](./editor-workflow.md)** - 完整的开发流程
+
+### 资源管理
+
+- **[资产管理](./asset-management.md)** - 加载、管理和复用行为树资产、使用子树
+
+### 引擎集成
+
+- **[Cocos Creator 集成](./cocos-integration.md)** - 在 Cocos Creator 中使用行为树
+- **[Laya 引擎集成](./laya-integration.md)** - 在 Laya 中使用行为树
+- **[Node.js 服务端使用](./nodejs-usage.md)** - 在服务器、聊天机器人等场景中使用行为树
+
+### 高级主题
+
+- **[高级用法](./advanced-usage.md)** - 性能优化、调试技巧
+- **[自定义节点执行器](./custom-actions.md)** - 创建自定义行为节点
+- **[最佳实践](./best-practices.md)** - 行为树设计模式和技巧
+
+## 快速示例
+
+### 使用Builder创建
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreePlugin
+} from '@esengine/behavior-tree';
+
+// 初始化
+Core.create();
+const plugin = new BehaviorTreePlugin();
+await Core.installPlugin(plugin);
+
+const scene = new Scene();
+plugin.setupScene(scene);
+Core.setScene(scene);
+
+// 创建行为树
+const enemyAI = BehaviorTreeBuilder.create('EnemyAI')
+    .defineBlackboardVariable('health', 100)
+    .defineBlackboardVariable('target', null)
+    .selector('MainBehavior')
+        // 如果生命值高,则攻击
+        .sequence('AttackBranch')
+            .blackboardCompare('health', 50, 'greater')
+            .log('攻击玩家', 'Attack')
+        .end()
+        // 否则逃跑
+        .log('逃离战斗', 'Flee')
+    .end()
+    .build();
+
+// 启动AI
+const entity = scene.createEntity('Enemy');
+BehaviorTreeStarter.start(entity, enemyAI);
+```
+
+### 使用编辑器创建
+
+1. 打开行为树编辑器
+2. 创建新的行为树资产
+3. 拖拽节点到画布
+4. 配置节点属性和连接
+5. 保存并在代码中使用
+
+## 架构说明
+
+### Runtime执行器架构
+
+本框架采用Runtime执行器架构,将节点定义和执行逻辑分离:
+
+**核心组件:**
+- `BehaviorTreeData`: 纯数据结构,描述行为树
+- `BehaviorTreeRuntimeComponent`: 运行时组件,管理状态和黑板
+- `BehaviorTreeExecutionSystem`: 执行系统,驱动行为树运行
+- `INodeExecutor`: 节点执行器接口
+- `NodeExecutionContext`: 执行上下文
+
+**优势:**
+- 数据与逻辑分离,易于序列化
+- 执行器无状态,可复用
+- 类型安全,编译时检查
+- 高性能执行
+
+### 自定义执行器
+
+创建自定义节点非常简单:
+
+```typescript
+import {
+    INodeExecutor,
+    NodeExecutionContext,
+    BindingHelper,
+    NodeExecutorMetadata
+} from '@esengine/behavior-tree';
+import { TaskStatus, NodeType } from '@esengine/behavior-tree';
+
+@NodeExecutorMetadata({
+    implementationType: 'AttackAction',
+    nodeType: NodeType.Action,
+    displayName: '攻击',
+    description: '攻击目标',
+    category: '战斗',
+    configSchema: {
+        damage: {
+            type: 'number',
+            default: 10,
+            supportBinding: true
+        }
+    }
+})
+export class AttackAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const damage = BindingHelper.getValue<number>(context, 'damage', 10);
+        const target = context.runtime.getBlackboardValue('target');
+
+        if (!target) {
+            return TaskStatus.Failure;
+        }
+
+        console.log(`造成 ${damage} 点伤害`);
+        return TaskStatus.Success;
+    }
+}
+```
+
+详细说明请参见[自定义节点执行器](./custom-actions.md)。
+
+## 下一步
+
+建议按照以下顺序学习:
+
+1. 阅读[快速开始](./getting-started.md)了解基础用法
+2. 学习[核心概念](./core-concepts.md)理解行为树原理
+3. 学习[资产管理](./asset-management.md)了解如何加载和复用行为树、使用子树
+4. 根据你的场景查看集成教程:
+   - 客户端游戏：[Cocos Creator](./cocos-integration.md) 或 [Laya](./laya-integration.md)
+   - 服务端应用：[Node.js 服务端使用](./nodejs-usage.md)
+5. 尝试[编辑器使用指南](./editor-guide.md)可视化创建行为树
+6. 探索[高级用法](./advanced-usage.md)和[自定义节点执行器](./custom-actions.md)提升技能
+
+## 获取帮助
+
+- 提交 [Issue](https://github.com/esengine/esengine/issues)
+- 加入社区讨论
+- 参考文档中的完整代码示例

docs/modules/behavior-tree/laya-integration.md

@@ -0,0 +1,313 @@
+# Laya 引擎集成
+
+本教程将引导你在 Laya 引擎项目中集成和使用行为树系统。
+
+## 前置要求
+
+- LayaAir 3.x 或更高版本
+- 基本的 TypeScript 知识
+- 已完成[快速开始](./getting-started.md)教程
+
+## 安装
+
+在你的 Laya 项目根目录下：
+
+```bash
+npm install @esengine/ecs-framework @esengine/behavior-tree
+```
+
+## 项目结构
+
+建议的项目结构：
+
+```
+src/
+├── ai/
+│   ├── EnemyAI.ts
+│   └── BossAI.ts
+├── systems/
+│   └── AISystem.ts
+└── Main.ts
+resources/
+└── behaviors/
+    ├── enemy.btree.json
+    └── boss.btree.json
+```
+
+
+## 初始化
+
+### 在Main.ts中初始化
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import { BehaviorTreePlugin } from '@esengine/behavior-tree';
+
+export class Main {
+    constructor() {
+        Laya.init(1280, 720).then(() => {
+            this.initECS();
+            this.startGame();
+        });
+    }
+
+    private async initECS() {
+        // 初始化 ECS
+        Core.create();
+
+        // 安装行为树插件
+        const btPlugin = new BehaviorTreePlugin();
+        await Core.installPlugin(btPlugin);
+
+        // 创建并设置场景
+        const scene = new Scene();
+        btPlugin.setupScene(scene);
+        Core.setScene(scene);
+
+        // 启动更新循环
+        Laya.timer.frameLoop(1, this, this.update);
+    }
+
+    private update() {
+        // Core.update会自动更新场景
+        Core.update(Laya.timer.delta / 1000);
+    }
+
+    private startGame() {
+        // 加载场景
+    }
+}
+
+new Main();
+```
+
+
+## 创建AI组件
+
+```typescript
+import { Core, Entity } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreeRuntimeComponent
+} from '@esengine/behavior-tree';
+
+export class EnemyAI extends Laya.Script {
+    private aiEntity: Entity;
+
+    onEnable() {
+        this.createBehaviorTree();
+    }
+
+    private createBehaviorTree() {
+        // 获取Core管理的场景
+        const scene = Core.scene;
+        if (!scene) {
+            console.error('场景未初始化');
+            return;
+        }
+
+        const sprite = this.owner as Laya.Sprite;
+
+        // 使用Builder API创建行为树
+        const tree = BehaviorTreeBuilder.create('EnemyAI')
+            .defineBlackboardVariable('layaSprite', sprite)
+            .defineBlackboardVariable('health', 100)
+            .defineBlackboardVariable('position', { x: sprite.x, y: sprite.y })
+            .selector('MainBehavior')
+                .sequence('Combat')
+                    .blackboardCompare('health', 30, 'greater')
+                    .log('攻击', 'Attack')
+                .end()
+                .log('巡逻', 'Patrol')
+            .end()
+            .build();
+
+        // 创建AI实体并启动
+        this.aiEntity = scene.createEntity(`AI_${sprite.name}`);
+        BehaviorTreeStarter.start(this.aiEntity, tree);
+    }
+
+    onDisable() {
+        // 停止AI
+        if (this.aiEntity) {
+            BehaviorTreeStarter.stop(this.aiEntity);
+        }
+    }
+}
+```
+
+
+## 与Laya节点交互
+
+要实现与Laya节点的交互，需要创建自定义执行器。下面展示一个完整示例。
+
+## 完整示例
+
+创建一个使用自定义执行器的敌人AI系统：
+
+```typescript
+import {
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    INodeExecutor,
+    NodeExecutionContext,
+    NodeExecutorMetadata,
+    BehaviorTreeRuntimeComponent
+} from '@esengine/behavior-tree';
+import { TaskStatus, NodeType } from '@esengine/behavior-tree';
+import { Core, Entity } from '@esengine/ecs-framework';
+
+// 自定义移动执行器
+@NodeExecutorMetadata({
+    implementationType: 'MoveToTarget',
+    nodeType: NodeType.Action,
+    displayName: '移动到目标',
+    category: 'Laya',
+    configSchema: {
+        speed: {
+            type: 'number',
+            default: 50,
+            supportBinding: true
+        }
+    }
+})
+export class MoveToTargetAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const sprite = context.runtime.getBlackboardValue('layaSprite');
+        const targetPos = context.runtime.getBlackboardValue('targetPosition');
+        const speed = context.nodeData.config.speed;
+
+        if (!sprite || !targetPos) {
+            return TaskStatus.Failure;
+        }
+
+        const dx = targetPos.x - sprite.x;
+        const dy = targetPos.y - sprite.y;
+        const distance = Math.sqrt(dx * dx + dy * dy);
+
+        if (distance < 10) {
+            return TaskStatus.Success;
+        }
+
+        sprite.x += (dx / distance) * speed * context.deltaTime;
+        sprite.y += (dy / distance) * speed * context.deltaTime;
+
+        return TaskStatus.Running;
+    }
+}
+
+export class SimpleEnemyAI extends Laya.Script {
+    public player: Laya.Sprite;
+
+    private aiEntity: Entity;
+
+    onEnable() {
+        this.buildAI();
+    }
+
+    private buildAI() {
+        const scene = Core.scene;
+        if (!scene) {
+            console.error('场景未初始化');
+            return;
+        }
+
+        const sprite = this.owner as Laya.Sprite;
+
+        const tree = BehaviorTreeBuilder.create('EnemyAI')
+            .defineBlackboardVariable('layaSprite', sprite)
+            .defineBlackboardVariable('health', 100)
+            .defineBlackboardVariable('player', this.player)
+            .defineBlackboardVariable('targetPosition', { x: 0, y: 0 })
+            .selector('MainBehavior')
+                .sequence('Attack')
+                    .blackboardExists('player')
+                    .log('攻击玩家', 'DoAttack')
+                .end()
+                .log('巡逻', 'Patrol')
+            .end()
+            .build();
+
+        this.aiEntity = scene.createEntity(`AI_${sprite.name}`);
+        BehaviorTreeStarter.start(this.aiEntity, tree);
+
+        // 可以在帧更新中修改黑板
+        Laya.timer.frameLoop(1, this, () => {
+            const runtime = this.aiEntity?.getComponent(BehaviorTreeRuntimeComponent);
+            if (runtime && this.player) {
+                runtime.setBlackboardValue('targetPosition', {
+                    x: this.player.x,
+                    y: this.player.y
+                });
+            }
+        });
+    }
+
+    onDisable() {
+        if (this.aiEntity) {
+            BehaviorTreeStarter.stop(this.aiEntity);
+        }
+        Laya.timer.clearAll(this);
+    }
+}
+```
+
+
+## 性能优化
+
+### 使用冷却装饰器
+
+对于不需要每帧更新的AI，使用冷却装饰器：
+
+```typescript
+const tree = BehaviorTreeBuilder.create('ThrottledAI')
+    .cooldown(0.2, 'ThrottleRoot')  // 每0.2秒执行一次
+        .selector('MainBehavior')
+            // AI逻辑...
+        .end()
+    .end()
+    .build();
+```
+
+### 限制同时运行的AI数量
+
+```typescript
+class AIManager {
+    private activeAIs: Entity[] = [];
+    private maxAIs: number = 20;
+
+    addAI(entity: Entity, tree: BehaviorTreeData) {
+        if (this.activeAIs.length >= this.maxAIs) {
+            const furthest = this.activeAIs.shift();
+            if (furthest) {
+                BehaviorTreeStarter.stop(furthest);
+            }
+        }
+
+        BehaviorTreeStarter.start(entity, tree);
+        this.activeAIs.push(entity);
+    }
+}
+```
+
+## 常见问题
+
+### 资源加载失败？
+
+确保：
+1. 资源路径正确
+2. 资源已添加到项目中
+3. 使用 `Laya.loader.load()` 加载
+
+### AI不执行？
+
+检查：
+1. `onUpdate()` 是否被调用
+2. `Scene.update()` 是否执行
+3. 行为树是否已启动
+
+## 下一步
+
+- 查看[高级用法](./advanced-usage.md)
+- 学习[最佳实践](./best-practices.md)

docs/modules/behavior-tree/nodejs-usage.md

@@ -0,0 +1,580 @@
+# Node.js 服务端使用
+
+本文介绍如何在 Node.js 服务端环境（如游戏服务器、机器人、自动化工具）中使用行为树系统。
+
+## 使用场景
+
+行为树不仅适用于游戏客户端AI，在服务端也有广泛应用：
+
+1. **游戏服务器** - NPC AI逻辑、副本关卡脚本
+2. **聊天机器人** - 对话流程控制、智能回复
+3. **自动化测试** - 测试用例执行流程
+4. **工作流引擎** - 业务流程自动化
+5. **爬虫系统** - 数据采集流程控制
+
+## 基础设置
+
+### 安装
+
+```bash
+npm install @esengine/ecs-framework @esengine/behavior-tree
+```
+
+### TypeScript 配置
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "moduleResolution": "node",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  }
+}
+```
+
+## 快速开始
+
+### 简单的游戏服务器 NPC
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    BehaviorTreePlugin,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreeRuntimeComponent
+} from '@esengine/behavior-tree';
+
+async function startServer() {
+    // 1. 初始化 ECS Core
+    Core.create();
+
+    // 2. 安装行为树插件
+    const plugin = new BehaviorTreePlugin();
+    await Core.installPlugin(plugin);
+
+    // 3. 创建场景
+    const scene = new Scene();
+    plugin.setupScene(scene);
+    Core.setScene(scene);
+
+    // 4. 创建 NPC 行为树
+    const npcAI = BehaviorTreeBuilder.create('MerchantNPC')
+        .defineBlackboardVariable('mood', 'friendly')
+        .defineBlackboardVariable('goldAmount', 1000)
+
+        .selector('NPCBehavior')
+            // 如果玩家触发对话
+            .sequence('Dialogue')
+                .blackboardExists('playerRequest')
+                .log('NPC: 欢迎光临！')
+            .end()
+
+            // 默认行为：闲置
+            .sequence('Idle')
+                .log('NPC: 正在整理商品...')
+                .wait(5.0)
+            .end()
+        .end()
+        .build();
+
+    // 5. 创建 NPC 实体
+    const npc = scene.createEntity('Merchant');
+    BehaviorTreeStarter.start(npc, npcAI);
+
+    // 6. 启动游戏循环（20 TPS）
+    setInterval(() => {
+        Core.update(0.05);  // 50ms = 1/20秒
+    }, 50);
+
+    // 7. 模拟玩家交互
+    setTimeout(() => {
+        const runtime = npc.getComponent(BehaviorTreeRuntimeComponent);
+        runtime?.setBlackboardValue('playerRequest', 'buy_sword');
+        console.log('玩家发起交易请求');
+    }, 3000);
+
+    console.log('游戏服务器已启动');
+}
+
+startServer();
+```
+
+## 实战示例：聊天机器人
+
+创建一个基于行为树的智能聊天机器人：
+
+```typescript
+import { Core, Scene, Entity } from '@esengine/ecs-framework';
+import {
+    BehaviorTreePlugin,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreeRuntimeComponent,
+    INodeExecutor,
+    NodeExecutionContext,
+    TaskStatus,
+    NodeType,
+    NodeExecutorMetadata
+} from '@esengine/behavior-tree';
+
+// 1. 创建自定义节点：回复消息
+@NodeExecutorMetadata({
+    implementationType: 'SendMessage',
+    nodeType: NodeType.Action,
+    displayName: '发送消息',
+    configSchema: {
+        message: { type: 'string', default: '' }
+    }
+})
+class SendMessageAction implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const message = context.nodeData.config['message'] as string;
+        const userMessage = context.runtime.getBlackboardValue<string>('userMessage');
+
+        console.log(`[机器人回复]: ${message}`);
+        console.log(`   回复给: ${userMessage}`);
+
+        return TaskStatus.Success;
+    }
+}
+
+// 2. 创建自定义节点：匹配关键词
+@NodeExecutorMetadata({
+    implementationType: 'MatchKeyword',
+    nodeType: NodeType.Condition,
+    displayName: '匹配关键词',
+    configSchema: {
+        keyword: { type: 'string', default: '' }
+    }
+})
+class MatchKeywordCondition implements INodeExecutor {
+    execute(context: NodeExecutionContext): TaskStatus {
+        const keyword = context.nodeData.config['keyword'] as string;
+        const userMessage = context.runtime.getBlackboardValue<string>('userMessage') || '';
+
+        return userMessage.includes(keyword) ? TaskStatus.Success : TaskStatus.Failure;
+    }
+}
+
+// 3. 创建聊天机器人类
+class ChatBot {
+    private botEntity: Entity;
+    private runtime: BehaviorTreeRuntimeComponent | null = null;
+
+    constructor(scene: Scene) {
+        // 创建机器人行为树
+        const botBehavior = BehaviorTreeBuilder.create('ChatBotAI')
+            .defineBlackboardVariable('userMessage', '')
+            .defineBlackboardVariable('userName', 'Guest')
+
+            .selector('ResponseSelector')
+                // 问候语
+                .sequence('Greeting')
+                    .executeCondition('MatchKeyword', { keyword: '你好' })
+                    .executeAction('SendMessage', { message: '你好！我是智能助手，有什么可以帮你的吗？' })
+                .end()
+
+                // 帮助请求
+                .sequence('Help')
+                    .executeCondition('MatchKeyword', { keyword: '帮助' })
+                    .executeAction('SendMessage', { message: '我可以帮你回答问题、查询信息。试试问我一些问题吧！' })
+                .end()
+
+                // 查询天气
+                .sequence('Weather')
+                    .executeCondition('MatchKeyword', { keyword: '天气' })
+                    .executeAction('SendMessage', { message: '今天天气不错，晴天，温度适宜。' })
+                .end()
+
+                // 查询时间
+                .sequence('Time')
+                    .executeCondition('MatchKeyword', { keyword: '时间' })
+                    .executeAction('SendMessage', { message: `现在时间是 ${new Date().toLocaleString()}` })
+                .end()
+
+                // 默认回复
+                .executeAction('SendMessage', { message: '抱歉，我还不太理解你的意思。可以换个方式问我吗？' })
+            .end()
+            .build();
+
+        // 创建实体并启动
+        this.botEntity = scene.createEntity('ChatBot');
+        BehaviorTreeStarter.start(this.botEntity, botBehavior);
+        this.runtime = this.botEntity.getComponent(BehaviorTreeRuntimeComponent);
+    }
+
+    // 处理用户消息
+    async handleMessage(userName: string, message: string) {
+        if (this.runtime) {
+            this.runtime.setBlackboardValue('userName', userName);
+            this.runtime.setBlackboardValue('userMessage', message);
+        }
+
+        // 等待一帧让行为树执行
+        await new Promise(resolve => setTimeout(resolve, 100));
+    }
+}
+
+// 4. 主程序
+async function main() {
+    // 初始化
+    Core.create();
+    const plugin = new BehaviorTreePlugin();
+    await Core.installPlugin(plugin);
+
+    const scene = new Scene();
+    plugin.setupScene(scene);
+    Core.setScene(scene);
+
+    // 注册自定义节点
+    const system = scene.getSystem(BehaviorTreeExecutionSystem);
+    if (system) {
+        const registry = system.getExecutorRegistry();
+        registry.register('SendMessage', new SendMessageAction());
+        registry.register('MatchKeyword', new MatchKeywordCondition());
+    }
+
+    // 创建聊天机器人
+    const bot = new ChatBot(scene);
+
+    // 启动更新循环
+    setInterval(() => {
+        Core.update(0.1);
+    }, 100);
+
+    // 模拟用户对话
+    console.log('\n=== 聊天机器人测试 ===\n');
+
+    await bot.handleMessage('Alice', '你好');
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    await bot.handleMessage('Bob', '现在几点了？');
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    await bot.handleMessage('Charlie', '今天天气怎么样');
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    await bot.handleMessage('David', '你能帮我做什么');
+    await new Promise(resolve => setTimeout(resolve, 200));
+
+    await bot.handleMessage('Eve', '你好吗？');
+}
+
+main();
+```
+
+## 实战示例：多人游戏服务器
+
+### 房间管理系统
+
+```typescript
+import { Core, Scene, Entity } from '@esengine/ecs-framework';
+import {
+    BehaviorTreePlugin,
+    BehaviorTreeBuilder,
+    BehaviorTreeStarter,
+    BehaviorTreeAssetManager
+} from '@esengine/behavior-tree';
+
+// 游戏房间
+class GameRoom {
+    private scene: Scene;
+    private assetManager: BehaviorTreeAssetManager;
+    private monsters: Entity[] = [];
+
+    constructor(roomId: string) {
+        // 创建房间场景
+        this.scene = new Scene();
+        const plugin = new BehaviorTreePlugin();
+        plugin.setupScene(this.scene);
+
+        this.assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+
+        // 初始化房间
+        this.spawnMonsters();
+        console.log(`房间 ${roomId} 已创建，怪物数量: ${this.monsters.length}`);
+    }
+
+    private spawnMonsters() {
+        // 从资产管理器获取怪物AI（所有房间共享）
+        const monsterAI = this.assetManager.getAsset('MonsterAI');
+        if (!monsterAI) return;
+
+        // 生成10个怪物
+        for (let i = 0; i < 10; i++) {
+            const monster = this.scene.createEntity(`Monster_${i}`);
+            BehaviorTreeStarter.start(monster, monsterAI);
+            this.monsters.push(monster);
+        }
+    }
+
+    update(deltaTime: number) {
+        this.scene.update(deltaTime);
+    }
+
+    destroy() {
+        this.monsters.forEach(m => m.destroy());
+        this.monsters = [];
+    }
+}
+
+// 房间管理器
+class RoomManager {
+    private rooms: Map<string, GameRoom> = new Map();
+
+    createRoom(roomId: string): GameRoom {
+        const room = new GameRoom(roomId);
+        this.rooms.set(roomId, room);
+        return room;
+    }
+
+    getRoom(roomId: string): GameRoom | undefined {
+        return this.rooms.get(roomId);
+    }
+
+    destroyRoom(roomId: string) {
+        const room = this.rooms.get(roomId);
+        if (room) {
+            room.destroy();
+            this.rooms.delete(roomId);
+        }
+    }
+
+    update(deltaTime: number) {
+        this.rooms.forEach(room => room.update(deltaTime));
+    }
+}
+
+// 主程序
+async function startGameServer() {
+    // 初始化
+    Core.create();
+    const plugin = new BehaviorTreePlugin();
+    await Core.installPlugin(plugin);
+
+    // 预加载怪物AI（所有房间共享）
+    const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+    const monsterAI = BehaviorTreeBuilder.create('MonsterAI')
+        .defineBlackboardVariable('health', 100)
+        .selector('Behavior')
+            .log('攻击玩家')
+        .end()
+        .build();
+    assetManager.loadAsset(monsterAI);
+
+    // 创建房间管理器
+    const roomManager = new RoomManager();
+
+    // 模拟房间创建
+    roomManager.createRoom('room_1');
+    roomManager.createRoom('room_2');
+
+    // 服务器主循环（60 TPS）
+    setInterval(() => {
+        roomManager.update(1/60);
+    }, 1000 / 60);
+
+    console.log('游戏服务器已启动');
+}
+
+startGameServer();
+```
+
+## 性能优化
+
+### 1. 控制更新频率
+
+```typescript
+// 不同类型的AI使用不同的更新频率
+class AIManager {
+    private importantAIs: Entity[] = [];  // Boss等重要AI，60 TPS
+    private normalAIs: Entity[] = [];     // 普通敌人，20 TPS
+    private backgroundAIs: Entity[] = [];  // 背景NPC，5 TPS
+
+    update() {
+        // 重要AI每帧更新
+        this.updateAIs(this.importantAIs, 1/60);
+
+        // 普通AI每3帧更新一次
+        if (frameCount % 3 === 0) {
+            this.updateAIs(this.normalAIs, 3/60);
+        }
+
+        // 背景AI每12帧更新一次
+        if (frameCount % 12 === 0) {
+            this.updateAIs(this.backgroundAIs, 12/60);
+        }
+    }
+}
+```
+
+### 2. 资源管理
+
+```typescript
+// 使用资产管理器避免重复创建
+const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+
+// 预加载所有AI
+const enemyAI = BehaviorTreeBuilder.create('EnemyAI').build();
+const bossAI = BehaviorTreeBuilder.create('BossAI').build();
+
+assetManager.loadAsset(enemyAI);
+assetManager.loadAsset(bossAI);
+
+// 创建1000个敌人，但只使用1份BehaviorTreeData
+for (let i = 0; i < 1000; i++) {
+    const enemy = scene.createEntity(`Enemy${i}`);
+    const ai = assetManager.getAsset('EnemyAI')!;
+    BehaviorTreeStarter.start(enemy, ai);
+}
+```
+
+### 3. 使用对象池
+
+```typescript
+class EntityPool {
+    private pool: Entity[] = [];
+    private active: Entity[] = [];
+
+    spawn(scene: Scene, treeId: string): Entity {
+        let entity = this.pool.pop();
+
+        if (!entity) {
+            entity = scene.createEntity();
+            const tree = assetManager.getAsset(treeId)!;
+            BehaviorTreeStarter.start(entity, tree);
+        } else {
+            BehaviorTreeStarter.restart(entity);
+        }
+
+        this.active.push(entity);
+        return entity;
+    }
+
+    recycle(entity: Entity) {
+        BehaviorTreeStarter.pause(entity);
+        const index = this.active.indexOf(entity);
+        if (index >= 0) {
+            this.active.splice(index, 1);
+            this.pool.push(entity);
+        }
+    }
+}
+```
+
+## 最佳实践
+
+### 1. 使用环境变量控制调试
+
+```typescript
+const DEBUG = process.env.NODE_ENV === 'development';
+
+const aiTree = BehaviorTreeBuilder.create('AI')
+    .selector('Main')
+        .when(DEBUG, builder =>
+            builder.log('调试信息：开始AI逻辑')
+        )
+        // AI 逻辑...
+    .end()
+    .build();
+```
+
+### 2. 错误处理
+
+```typescript
+try {
+    const tree = BehaviorTreeBuilder.create('AI')
+        // ... 构建逻辑
+        .build();
+
+    assetManager.loadAsset(tree);
+    BehaviorTreeStarter.start(entity, tree);
+} catch (error) {
+    console.error('启动AI失败:', error);
+    // 使用默认AI或进行降级处理
+}
+```
+
+### 3. 监控和日志
+
+```typescript
+// 定期输出AI状态
+setInterval(() => {
+    const assetManager = Core.services.resolve(BehaviorTreeAssetManager);
+    const count = assetManager.getAssetCount();
+    const entities = scene.getEntitiesFor(Matcher.empty().all(BehaviorTreeRuntimeComponent));
+
+    console.log(`[AI监控] 行为树资产: ${count}, 活跃实体: ${entities.length}`);
+}, 10000);
+```
+
+## 常见问题
+
+### 如何与 Express/Koa 等框架集成？
+
+```typescript
+import express from 'express';
+import { Core, Scene } from '@esengine/ecs-framework';
+
+const app = express();
+const scene = new Scene();
+
+// 在单独的循环中更新ECS
+setInterval(() => {
+    Core.update(0.016);
+}, 16);
+
+app.post('/npc/:id/interact', (req, res) => {
+    const npcId = req.params.id;
+    const npc = scene.findEntity(npcId);
+
+    if (npc) {
+        const runtime = npc.getComponent(BehaviorTreeRuntimeComponent);
+        runtime?.setBlackboardValue('playerRequest', req.body);
+
+        res.json({ success: true });
+    } else {
+        res.status(404).json({ error: 'NPC not found' });
+    }
+});
+
+app.listen(3000);
+```
+
+### 如何持久化行为树状态？
+
+```typescript
+// 保存状态
+function saveAIState(entity: Entity) {
+    const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+    if (runtime) {
+        return {
+            treeId: runtime.treeId,
+            blackboard: runtime.getAllBlackboardVariables(),
+            activeNodes: Array.from(runtime.activeNodeIds)
+        };
+    }
+}
+
+// 恢复状态
+function loadAIState(entity: Entity, savedState: any) {
+    const runtime = entity.getComponent(BehaviorTreeRuntimeComponent);
+    if (runtime) {
+        // 恢复黑板变量
+        Object.entries(savedState.blackboard).forEach(([key, value]) => {
+            runtime.setBlackboardValue(key, value);
+        });
+    }
+}
+```
+
+## 下一步
+
+- 查看[资产管理](./asset-management.md)了解资源加载和子树
+- 学习[自定义节点执行器](./custom-actions.md)创建自定义行为
+- 阅读[最佳实践](./best-practices.md)优化你的服务端AI

docs/modules/blueprint/index.md

@@ -0,0 +1,507 @@
+# 蓝图可视化脚本 (Blueprint)
+
+`@esengine/blueprint` 提供了一个功能完整的可视化脚本系统，支持节点式编程、事件驱动和蓝图组合。
+
+## 安装
+
+```bash
+npm install @esengine/blueprint
+```
+
+## 快速开始
+
+```typescript
+import {
+    createBlueprintSystem,
+    createBlueprintComponentData,
+    NodeRegistry,
+    RegisterNode
+} from '@esengine/blueprint';
+
+// 创建蓝图系统
+const blueprintSystem = createBlueprintSystem(scene);
+
+// 加载蓝图资产
+const blueprint = await loadBlueprintAsset('player.bp');
+
+// 创建蓝图组件数据
+const componentData = createBlueprintComponentData();
+componentData.blueprintAsset = blueprint;
+
+// 在游戏循环中更新
+function gameLoop(dt: number) {
+    blueprintSystem.process(entities, dt);
+}
+```
+
+## 核心概念
+
+### 蓝图资产结构
+
+蓝图保存为 `.bp` 文件，包含以下结构：
+
+```typescript
+interface BlueprintAsset {
+    version: number;           // 格式版本
+    type: 'blueprint';         // 资产类型
+    metadata: BlueprintMetadata; // 元数据
+    variables: BlueprintVariable[]; // 变量定义
+    nodes: BlueprintNode[];    // 节点实例
+    connections: BlueprintConnection[]; // 连接
+}
+```
+
+### 节点类型
+
+节点按功能分为以下类别：
+
+| 类别 | 说明 | 颜色 |
+|------|------|------|
+| `event` | 事件节点（入口点） | 红色 |
+| `flow` | 流程控制 | 灰色 |
+| `entity` | 实体操作 | 蓝色 |
+| `component` | 组件访问 | 青色 |
+| `math` | 数学运算 | 绿色 |
+| `logic` | 逻辑运算 | 红色 |
+| `variable` | 变量访问 | 紫色 |
+| `time` | 时间工具 | 青色 |
+| `debug` | 调试工具 | 灰色 |
+
+### 引脚类型
+
+节点通过引脚连接：
+
+```typescript
+interface BlueprintPinDefinition {
+    name: string;        // 引脚名称
+    type: PinDataType;   // 数据类型
+    direction: 'input' | 'output';
+    isExec?: boolean;    // 是否是执行引脚
+    defaultValue?: unknown;
+}
+
+// 支持的数据类型
+type PinDataType =
+    | 'exec'      // 执行流
+    | 'boolean'   // 布尔值
+    | 'number'    // 数字
+    | 'string'    // 字符串
+    | 'vector2'   // 2D 向量
+    | 'vector3'   // 3D 向量
+    | 'entity'    // 实体引用
+    | 'component' // 组件引用
+    | 'any';      // 任意类型
+```
+
+### 变量作用域
+
+```typescript
+type VariableScope =
+    | 'local'     // 每次执行独立
+    | 'instance'  // 每个实体独立
+    | 'global';   // 全局共享
+```
+
+## 虚拟机 API
+
+### BlueprintVM
+
+蓝图虚拟机负责执行蓝图图：
+
+```typescript
+import { BlueprintVM } from '@esengine/blueprint';
+
+// 创建 VM
+const vm = new BlueprintVM(blueprintAsset, entity, scene);
+
+// 启动（触发 BeginPlay）
+vm.start();
+
+// 每帧更新（触发 Tick）
+vm.tick(deltaTime);
+
+// 停止（触发 EndPlay）
+vm.stop();
+
+// 暂停/恢复
+vm.pause();
+vm.resume();
+
+// 触发事件
+vm.triggerEvent('EventCollision', { other: otherEntity });
+vm.triggerCustomEvent('OnDamage', { amount: 50 });
+
+// 调试模式
+vm.debug = true;
+```
+
+### 执行上下文
+
+```typescript
+interface ExecutionContext {
+    blueprint: BlueprintAsset;  // 蓝图资产
+    entity: Entity;             // 当前实体
+    scene: IScene;              // 当前场景
+    deltaTime: number;          // 帧间隔时间
+    time: number;               // 总运行时间
+
+    // 获取输入值
+    getInput<T>(nodeId: string, pinName: string): T;
+
+    // 设置输出值
+    setOutput(nodeId: string, pinName: string, value: unknown): void;
+
+    // 变量访问
+    getVariable<T>(name: string): T;
+    setVariable(name: string, value: unknown): void;
+}
+```
+
+### 执行结果
+
+```typescript
+interface ExecutionResult {
+    outputs?: Record<string, unknown>; // 输出值
+    nextExec?: string | null;          // 下一个执行引脚
+    delay?: number;                    // 延迟执行（毫秒）
+    yield?: boolean;                   // 暂停到下一帧
+    error?: string;                    // 错误信息
+}
+```
+
+## 自定义节点
+
+### 定义节点模板
+
+```typescript
+import { BlueprintNodeTemplate } from '@esengine/blueprint';
+
+const MyNodeTemplate: BlueprintNodeTemplate = {
+    type: 'MyCustomNode',
+    title: 'My Custom Node',
+    category: 'custom',
+    description: 'A custom node example',
+    keywords: ['custom', 'example'],
+    inputs: [
+        { name: 'exec', type: 'exec', direction: 'input', isExec: true },
+        { name: 'value', type: 'number', direction: 'input', defaultValue: 0 }
+    ],
+    outputs: [
+        { name: 'exec', type: 'exec', direction: 'output', isExec: true },
+        { name: 'result', type: 'number', direction: 'output' }
+    ]
+};
+```
+
+### 实现节点执行器
+
+```typescript
+import { INodeExecutor, RegisterNode } from '@esengine/blueprint';
+
+@RegisterNode(MyNodeTemplate)
+class MyNodeExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
+        // 获取输入
+        const value = context.getInput<number>(node.id, 'value');
+
+        // 执行逻辑
+        const result = value * 2;
+
+        // 返回结果
+        return {
+            outputs: { result },
+            nextExec: 'exec'  // 继续执行
+        };
+    }
+}
+```
+
+### 使用装饰器注册
+
+```typescript
+// 方式 1: 使用装饰器
+@RegisterNode(MyNodeTemplate)
+class MyNodeExecutor implements INodeExecutor { ... }
+
+// 方式 2: 手动注册
+NodeRegistry.instance.register(MyNodeTemplate, new MyNodeExecutor());
+```
+
+## 节点注册表
+
+```typescript
+import { NodeRegistry } from '@esengine/blueprint';
+
+// 获取单例
+const registry = NodeRegistry.instance;
+
+// 获取所有模板
+const allTemplates = registry.getAllTemplates();
+
+// 按类别获取
+const mathNodes = registry.getTemplatesByCategory('math');
+
+// 搜索节点
+const results = registry.searchTemplates('add');
+
+// 检查是否存在
+if (registry.has('MyCustomNode')) { ... }
+```
+
+## 内置节点
+
+### 事件节点
+
+| 节点 | 说明 |
+|------|------|
+| `EventBeginPlay` | 蓝图启动时触发 |
+| `EventTick` | 每帧触发 |
+| `EventEndPlay` | 蓝图停止时触发 |
+| `EventCollision` | 碰撞时触发 |
+| `EventInput` | 输入事件触发 |
+| `EventTimer` | 定时器触发 |
+| `EventMessage` | 自定义消息触发 |
+
+### 时间节点
+
+| 节点 | 说明 |
+|------|------|
+| `Delay` | 延迟执行 |
+| `GetDeltaTime` | 获取帧间隔 |
+| `GetTime` | 获取运行时间 |
+
+### 数学节点
+
+| 节点 | 说明 |
+|------|------|
+| `Add` | 加法 |
+| `Subtract` | 减法 |
+| `Multiply` | 乘法 |
+| `Divide` | 除法 |
+| `Abs` | 绝对值 |
+| `Clamp` | 限制范围 |
+| `Lerp` | 线性插值 |
+| `Min` / `Max` | 最小/最大值 |
+
+### 调试节点
+
+| 节点 | 说明 |
+|------|------|
+| `Print` | 打印到控制台 |
+
+## 蓝图组合
+
+### 蓝图片段
+
+将可复用的逻辑封装为片段：
+
+```typescript
+import { createFragment } from '@esengine/blueprint';
+
+const healthFragment = createFragment('HealthSystem', {
+    inputs: [
+        { name: 'damage', type: 'number', internalNodeId: 'input1', internalPinName: 'value' }
+    ],
+    outputs: [
+        { name: 'isDead', type: 'boolean', internalNodeId: 'output1', internalPinName: 'value' }
+    ],
+    graph: {
+        nodes: [...],
+        connections: [...],
+        variables: [...]
+    }
+});
+```
+
+### 组合蓝图
+
+```typescript
+import { createComposer, FragmentRegistry } from '@esengine/blueprint';
+
+// 注册片段
+FragmentRegistry.instance.register('health', healthFragment);
+FragmentRegistry.instance.register('movement', movementFragment);
+
+// 创建组合器
+const composer = createComposer('PlayerBlueprint');
+
+// 添加片段到槽位
+composer.addFragment(healthFragment, 'slot1', { position: { x: 0, y: 0 } });
+composer.addFragment(movementFragment, 'slot2', { position: { x: 400, y: 0 } });
+
+// 连接槽位
+composer.connect('slot1', 'onDeath', 'slot2', 'disable');
+
+// 验证
+const validation = composer.validate();
+if (!validation.isValid) {
+    console.error(validation.errors);
+}
+
+// 编译成蓝图
+const blueprint = composer.compile();
+```
+
+## 触发器系统
+
+### 定义触发条件
+
+```typescript
+import { TriggerCondition, TriggerDispatcher } from '@esengine/blueprint';
+
+const lowHealthCondition: TriggerCondition = {
+    type: 'comparison',
+    left: { type: 'variable', name: 'health' },
+    operator: '<',
+    right: { type: 'constant', value: 20 }
+};
+```
+
+### 使用触发器分发器
+
+```typescript
+const dispatcher = new TriggerDispatcher();
+
+// 注册触发器
+dispatcher.register('lowHealth', lowHealthCondition, (context) => {
+    context.triggerEvent('OnLowHealth');
+});
+
+// 每帧评估
+dispatcher.evaluate(context);
+```
+
+## 与 ECS 集成
+
+### 使用蓝图系统
+
+```typescript
+import { createBlueprintSystem } from '@esengine/blueprint';
+
+class GameScene {
+    private blueprintSystem: BlueprintSystem;
+
+    initialize() {
+        this.blueprintSystem = createBlueprintSystem(this.scene);
+    }
+
+    update(dt: number) {
+        // 处理所有带蓝图组件的实体
+        this.blueprintSystem.process(this.entities, dt);
+    }
+}
+```
+
+### 触发蓝图事件
+
+```typescript
+import { triggerBlueprintEvent, triggerCustomBlueprintEvent } from '@esengine/blueprint';
+
+// 触发内置事件
+triggerBlueprintEvent(entity, 'Collision', { other: otherEntity });
+
+// 触发自定义事件
+triggerCustomBlueprintEvent(entity, 'OnPickup', { item: itemEntity });
+```
+
+## 实际示例
+
+### 玩家控制蓝图
+
+```typescript
+// 定义输入处理节点
+const InputMoveTemplate: BlueprintNodeTemplate = {
+    type: 'InputMove',
+    title: 'Get Movement Input',
+    category: 'input',
+    inputs: [],
+    outputs: [
+        { name: 'direction', type: 'vector2', direction: 'output' }
+    ],
+    isPure: true
+};
+
+@RegisterNode(InputMoveTemplate)
+class InputMoveExecutor implements INodeExecutor {
+    execute(node: BlueprintNode, context: ExecutionContext): ExecutionResult {
+        const input = context.scene.services.get(InputServiceToken);
+        const direction = {
+            x: input.getAxis('horizontal'),
+            y: input.getAxis('vertical')
+        };
+        return { outputs: { direction } };
+    }
+}
+```
+
+### 状态切换逻辑
+
+```typescript
+// 在蓝图中实现状态机逻辑
+const stateBlueprint = createEmptyBlueprint('PlayerState');
+
+// 添加状态变量
+stateBlueprint.variables.push({
+    name: 'currentState',
+    type: 'string',
+    defaultValue: 'idle',
+    scope: 'instance'
+});
+
+// 在 Tick 事件中检查状态转换
+// ... 通过节点连接实现
+```
+
+## 序列化
+
+### 保存蓝图
+
+```typescript
+import { validateBlueprintAsset } from '@esengine/blueprint';
+
+function saveBlueprint(blueprint: BlueprintAsset, path: string): void {
+    if (!validateBlueprintAsset(blueprint)) {
+        throw new Error('Invalid blueprint structure');
+    }
+    const json = JSON.stringify(blueprint, null, 2);
+    fs.writeFileSync(path, json);
+}
+```
+
+### 加载蓝图
+
+```typescript
+async function loadBlueprint(path: string): Promise<BlueprintAsset> {
+    const json = await fs.readFile(path, 'utf-8');
+    const asset = JSON.parse(json);
+
+    if (!validateBlueprintAsset(asset)) {
+        throw new Error('Invalid blueprint file');
+    }
+
+    return asset;
+}
+```
+
+## 最佳实践
+
+1. **使用片段复用逻辑**
+   - 将通用逻辑封装为片段
+   - 通过组合器构建复杂蓝图
+
+2. **合理使用变量作用域**
+   - `local`: 临时计算结果
+   - `instance`: 实体状态（如生命值）
+   - `global`: 游戏全局状态
+
+3. **避免无限循环**
+   - VM 有每帧最大执行步数限制（默认 1000）
+   - 使用 Delay 节点打断长执行链
+
+4. **调试技巧**
+   - 启用 `vm.debug = true` 查看执行日志
+   - 使用 Print 节点输出中间值
+
+5. **性能优化**
+   - 纯节点（`isPure: true`）的输出会被缓存
+   - 避免在 Tick 中执行重计算

docs/modules/fsm/index.md

@@ -0,0 +1,337 @@
+# 状态机 (FSM)
+
+`@esengine/fsm` 提供了一个类型安全的有限状态机实现，用于角色、AI 或任何需要状态管理的场景。
+
+## 安装
+
+```bash
+npm install @esengine/fsm
+```
+
+## 快速开始
+
+```typescript
+import { createStateMachine } from '@esengine/fsm';
+
+// 定义状态类型
+type PlayerState = 'idle' | 'walk' | 'run' | 'jump';
+
+// 创建状态机
+const fsm = createStateMachine<PlayerState>('idle');
+
+// 定义状态和回调
+fsm.defineState('idle', {
+    onEnter: (ctx, from) => console.log(`从 ${from} 进入 idle`),
+    onExit: (ctx, to) => console.log(`从 idle 退出到 ${to}`),
+    onUpdate: (ctx, dt) => { /* 每帧更新 */ }
+});
+
+fsm.defineState('walk', {
+    onEnter: () => console.log('开始行走')
+});
+
+// 手动切换状态
+fsm.transition('walk');
+
+console.log(fsm.current); // 'walk'
+```
+
+## 核心概念
+
+### 状态配置
+
+每个状态可以配置以下回调：
+
+```typescript
+interface StateConfig<TState, TContext> {
+    name: TState;                                    // 状态名称
+    onEnter?: (context: TContext, from: TState | null) => void;  // 进入回调
+    onExit?: (context: TContext, to: TState) => void;            // 退出回调
+    onUpdate?: (context: TContext, deltaTime: number) => void;   // 更新回调
+    tags?: string[];                                 // 状态标签
+    metadata?: Record<string, unknown>;              // 元数据
+}
+```
+
+### 转换条件
+
+可以定义带条件的状态转换：
+
+```typescript
+interface Context {
+    isMoving: boolean;
+    isRunning: boolean;
+    isGrounded: boolean;
+}
+
+const fsm = createStateMachine<PlayerState, Context>('idle', {
+    context: { isMoving: false, isRunning: false, isGrounded: true }
+});
+
+// 定义转换条件
+fsm.defineTransition('idle', 'walk', (ctx) => ctx.isMoving);
+fsm.defineTransition('walk', 'run', (ctx) => ctx.isRunning);
+fsm.defineTransition('walk', 'idle', (ctx) => !ctx.isMoving);
+
+// 自动评估并执行满足条件的转换
+fsm.evaluateTransitions();
+```
+
+### 转换优先级
+
+当多个转换条件同时满足时，优先级高的先执行：
+
+```typescript
+// 优先级数字越大越优先
+fsm.defineTransition('idle', 'attack', (ctx) => ctx.isAttacking, 10);
+fsm.defineTransition('idle', 'walk', (ctx) => ctx.isMoving, 1);
+
+// 如果同时满足，会先尝试 attack（优先级 10）
+```
+
+## API 参考
+
+### createStateMachine
+
+```typescript
+function createStateMachine<TState extends string, TContext = unknown>(
+    initialState: TState,
+    options?: StateMachineOptions<TContext>
+): IStateMachine<TState, TContext>
+```
+
+**参数：**
+- `initialState` - 初始状态
+- `options.context` - 上下文对象，在回调中可访问
+- `options.maxHistorySize` - 最大历史记录数（默认 100）
+- `options.enableHistory` - 是否启用历史记录（默认 true）
+
+### 状态机属性
+
+| 属性 | 类型 | 描述 |
+|------|------|------|
+| `current` | `TState` | 当前状态 |
+| `previous` | `TState \| null` | 上一个状态 |
+| `context` | `TContext` | 上下文对象 |
+| `isTransitioning` | `boolean` | 是否正在转换中 |
+| `currentStateDuration` | `number` | 当前状态持续时间（毫秒） |
+
+### 状态机方法
+
+#### 状态定义
+
+```typescript
+// 定义状态
+fsm.defineState('idle', {
+    onEnter: (ctx, from) => {},
+    onExit: (ctx, to) => {},
+    onUpdate: (ctx, dt) => {}
+});
+
+// 检查状态是否存在
+fsm.hasState('idle'); // true
+
+// 获取状态配置
+fsm.getStateConfig('idle');
+
+// 获取所有状态
+fsm.getStates(); // ['idle', 'walk', ...]
+```
+
+#### 转换操作
+
+```typescript
+// 定义转换
+fsm.defineTransition('idle', 'walk', condition, priority);
+
+// 移除转换
+fsm.removeTransition('idle', 'walk');
+
+// 获取从某状态出发的所有转换
+fsm.getTransitionsFrom('idle');
+
+// 检查是否可以转换
+fsm.canTransition('walk'); // true/false
+
+// 手动转换
+fsm.transition('walk');
+
+// 强制转换（忽略条件）
+fsm.transition('walk', true);
+
+// 自动评估转换条件
+fsm.evaluateTransitions();
+```
+
+#### 生命周期
+
+```typescript
+// 更新状态机（调用当前状态的 onUpdate）
+fsm.update(deltaTime);
+
+// 重置状态机
+fsm.reset(); // 重置到当前状态
+fsm.reset('idle'); // 重置到指定状态
+```
+
+#### 事件监听
+
+```typescript
+// 监听进入特定状态
+const unsubscribe = fsm.onEnter('walk', (from) => {
+    console.log(`从 ${from} 进入 walk`);
+});
+
+// 监听退出特定状态
+fsm.onExit('walk', (to) => {
+    console.log(`从 walk 退出到 ${to}`);
+});
+
+// 监听任意状态变化
+fsm.onChange((event) => {
+    console.log(`${event.from} -> ${event.to} at ${event.timestamp}`);
+});
+
+// 取消订阅
+unsubscribe();
+```
+
+#### 调试
+
+```typescript
+// 获取状态历史
+const history = fsm.getHistory();
+// [{ from: 'idle', to: 'walk', timestamp: 1234567890 }, ...]
+
+// 清除历史
+fsm.clearHistory();
+
+// 获取调试信息
+const info = fsm.getDebugInfo();
+// { current, previous, duration, stateCount, transitionCount, historySize }
+```
+
+## 实际示例
+
+### 角色状态机
+
+```typescript
+import { createStateMachine } from '@esengine/fsm';
+
+type CharacterState = 'idle' | 'walk' | 'run' | 'jump' | 'fall' | 'attack';
+
+interface CharacterContext {
+    velocity: { x: number; y: number };
+    isGrounded: boolean;
+    isAttacking: boolean;
+    speed: number;
+}
+
+const characterFSM = createStateMachine<CharacterState, CharacterContext>('idle', {
+    context: {
+        velocity: { x: 0, y: 0 },
+        isGrounded: true,
+        isAttacking: false,
+        speed: 0
+    }
+});
+
+// 定义状态
+characterFSM.defineState('idle', {
+    onEnter: (ctx) => {
+        ctx.speed = 0;
+    },
+    onUpdate: (ctx, dt) => {
+        // 播放待机动画
+    }
+});
+
+characterFSM.defineState('walk', {
+    onEnter: (ctx) => {
+        ctx.speed = 100;
+    }
+});
+
+characterFSM.defineState('run', {
+    onEnter: (ctx) => {
+        ctx.speed = 200;
+    }
+});
+
+characterFSM.defineState('jump', {
+    onEnter: (ctx) => {
+        ctx.velocity.y = -300;
+        ctx.isGrounded = false;
+    }
+});
+
+// 定义转换
+characterFSM.defineTransition('idle', 'walk', (ctx) => Math.abs(ctx.velocity.x) > 0);
+characterFSM.defineTransition('walk', 'idle', (ctx) => ctx.velocity.x === 0);
+characterFSM.defineTransition('walk', 'run', (ctx) => Math.abs(ctx.velocity.x) > 150);
+characterFSM.defineTransition('run', 'walk', (ctx) => Math.abs(ctx.velocity.x) <= 150);
+
+// 跳跃有最高优先级
+characterFSM.defineTransition('idle', 'jump', (ctx) => !ctx.isGrounded, 10);
+characterFSM.defineTransition('walk', 'jump', (ctx) => !ctx.isGrounded, 10);
+characterFSM.defineTransition('run', 'jump', (ctx) => !ctx.isGrounded, 10);
+
+characterFSM.defineTransition('jump', 'fall', (ctx) => ctx.velocity.y > 0);
+characterFSM.defineTransition('fall', 'idle', (ctx) => ctx.isGrounded);
+
+// 游戏循环中使用
+function gameUpdate(dt: number) {
+    // 更新上下文
+    characterFSM.context.velocity.x = getInputVelocity();
+    characterFSM.context.isGrounded = checkGrounded();
+
+    // 评估状态转换
+    characterFSM.evaluateTransitions();
+
+    // 更新当前状态
+    characterFSM.update(dt);
+}
+```
+
+### 与 ECS 集成
+
+```typescript
+import { Component, EntitySystem, Matcher } from '@esengine/ecs-framework';
+import { createStateMachine, type IStateMachine } from '@esengine/fsm';
+
+// 状态机组件
+class FSMComponent extends Component {
+    fsm: IStateMachine<string>;
+
+    constructor(initialState: string) {
+        super();
+        this.fsm = createStateMachine(initialState);
+    }
+}
+
+// 状态机系统
+class FSMSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.all(FSMComponent));
+    }
+
+    protected processEntity(entity: Entity, dt: number): void {
+        const fsmComp = entity.getComponent(FSMComponent);
+        fsmComp.fsm.evaluateTransitions();
+        fsmComp.fsm.update(dt);
+    }
+}
+```
+
+## 蓝图节点
+
+FSM 模块提供了可视化脚本支持的蓝图节点：
+
+- `GetCurrentState` - 获取当前状态
+- `TransitionTo` - 转换到指定状态
+- `CanTransition` - 检查是否可以转换
+- `IsInState` - 检查是否在指定状态
+- `WasInState` - 检查是否曾在指定状态
+- `GetStateDuration` - 获取状态持续时间
+- `EvaluateTransitions` - 评估转换条件
+- `ResetStateMachine` - 重置状态机

docs/modules/index.md

@@ -0,0 +1,54 @@
+# 功能模块
+
+ESEngine 提供了丰富的功能模块，可以按需引入到你的项目中。
+
+## 模块列表
+
+### AI 模块
+
+| 模块 | 包名 | 描述 |
+|------|------|------|
+| [行为树](/modules/behavior-tree/) | `@esengine/behavior-tree` | AI 行为树系统，支持可视化编辑 |
+| [状态机](/modules/fsm/) | `@esengine/fsm` | 有限状态机，用于角色/AI 状态管理 |
+
+### 游戏逻辑
+
+| 模块 | 包名 | 描述 |
+|------|------|------|
+| [定时器](/modules/timer/) | `@esengine/timer` | 定时器和冷却系统 |
+| [空间索引](/modules/spatial/) | `@esengine/spatial` | 空间查询、AOI 兴趣区域管理 |
+| [寻路系统](/modules/pathfinding/) | `@esengine/pathfinding` | A* 寻路、NavMesh 导航网格 |
+
+### 工具模块
+
+| 模块 | 包名 | 描述 |
+|------|------|------|
+| [可视化脚本](/modules/blueprint/) | `@esengine/blueprint` | 蓝图可视化脚本系统 |
+| [程序化生成](/modules/procgen/) | `@esengine/procgen` | 噪声函数、随机工具 |
+
+### 网络模块
+
+| 模块 | 包名 | 描述 |
+|------|------|------|
+| [网络同步](/modules/network/) | `@esengine/network` | 多人游戏网络同步 |
+
+## 安装
+
+所有模块都可以独立安装：
+
+```bash
+# 安装单个模块
+npm install @esengine/behavior-tree
+
+# 或使用 CLI 添加到现有项目
+npx @esengine/cli add behavior-tree
+```
+
+## 平台兼容性
+
+所有功能模块都是纯 TypeScript 实现，兼容：
+
+- Cocos Creator 3.x
+- Laya 3.x
+- Node.js
+- 浏览器

docs/modules/network/index.md

@@ -0,0 +1,727 @@
+# 网络同步系统 (Network)
+
+`@esengine/network` 提供基于 TSRPC 的客户端-服务器网络同步解决方案，用于多人游戏的实体同步、输入处理和状态插值。
+
+## 概述
+
+网络模块由三个包组成：
+
+| 包名 | 描述 |
+|------|------|
+| `@esengine/network` | 客户端 ECS 插件 |
+| `@esengine/network-protocols` | 共享协议定义 |
+| `@esengine/network-server` | 服务器端实现 |
+
+## 安装
+
+```bash
+# 客户端
+npm install @esengine/network
+
+# 服务器端
+npm install @esengine/network-server
+```
+
+## 使用 CLI 快速创建服务端
+
+推荐使用 ESEngine CLI 快速创建完整的游戏服务端项目：
+
+```bash
+# 创建项目目录
+mkdir my-game-server && cd my-game-server
+npm init -y
+
+# 使用 CLI 初始化 Node.js 服务端
+npx @esengine/cli init -p nodejs
+```
+
+CLI 会自动生成以下项目结构：
+
+```
+my-game-server/
+├── src/
+│   ├── index.ts                    # 入口文件
+│   ├── server/
+│   │   └── GameServer.ts           # 网络服务器配置
+│   └── game/
+│       ├── Game.ts                 # ECS 游戏主类
+│       ├── scenes/
+│       │   └── MainScene.ts        # 主场景
+│       ├── components/             # ECS 组件
+│       │   ├── PositionComponent.ts
+│       │   └── VelocityComponent.ts
+│       └── systems/                # ECS 系统
+│           └── MovementSystem.ts
+├── tsconfig.json
+├── package.json
+└── README.md
+```
+
+启动服务端：
+
+```bash
+# 开发模式（热重载）
+npm run dev
+
+# 生产模式
+npm run start
+```
+
+## 快速开始
+
+### 客户端
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+import {
+    NetworkPlugin,
+    NetworkIdentity,
+    NetworkTransform
+} from '@esengine/network';
+
+// 定义游戏场景
+class GameScene extends Scene {
+    initialize(): void {
+        this.name = 'Game';
+        // 网络系统由 NetworkPlugin 自动添加
+    }
+}
+
+// 初始化 Core
+Core.create({ debug: false });
+const scene = new GameScene();
+Core.setScene(scene);
+
+// 安装网络插件
+const networkPlugin = new NetworkPlugin();
+await Core.installPlugin(networkPlugin);
+
+// 注册预制体工厂
+networkPlugin.registerPrefab('player', (scene, spawn) => {
+    const entity = scene.createEntity(`player_${spawn.netId}`);
+
+    const identity = entity.addComponent(new NetworkIdentity());
+    identity.netId = spawn.netId;
+    identity.ownerId = spawn.ownerId;
+    identity.isLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId;
+
+    entity.addComponent(new NetworkTransform());
+    return entity;
+});
+
+// 连接服务器
+const success = await networkPlugin.connect('ws://localhost:3000', 'PlayerName');
+if (success) {
+    console.log('Connected!');
+}
+
+// 游戏循环
+function gameLoop(dt: number) {
+    Core.update(dt);
+}
+
+// 断开连接
+await networkPlugin.disconnect();
+```
+
+### 服务器端
+
+使用 CLI 创建服务端项目后，默认生成的代码已经配置好了 GameServer：
+
+```typescript
+import { GameServer } from '@esengine/network-server';
+
+const server = new GameServer({
+    port: 3000,
+    roomConfig: {
+        maxPlayers: 16,
+        tickRate: 20
+    }
+});
+
+await server.start();
+console.log('Server started on ws://localhost:3000');
+```
+
+## 核心概念
+
+### 架构
+
+```
+客户端                              服务器
+┌────────────────┐                ┌────────────────┐
+│ NetworkPlugin  │◄──── WS ────► │  GameServer    │
+│ ├─ Service     │                │  ├─ Room       │
+│ ├─ SyncSystem  │                │  └─ Players    │
+│ ├─ SpawnSystem │                └────────────────┘
+│ └─ InputSystem │
+└────────────────┘
+```
+
+### 组件
+
+#### NetworkIdentity
+
+网络标识组件，每个网络同步的实体必须拥有：
+
+```typescript
+class NetworkIdentity extends Component {
+    netId: number;           // 网络唯一 ID
+    ownerId: number;         // 所有者客户端 ID
+    bIsLocalPlayer: boolean; // 是否为本地玩家
+    bHasAuthority: boolean;  // 是否有权限控制
+}
+```
+
+#### NetworkTransform
+
+网络变换组件，用于位置和旋转同步：
+
+```typescript
+class NetworkTransform extends Component {
+    position: { x: number; y: number };
+    rotation: number;
+    velocity: { x: number; y: number };
+}
+```
+
+### 系统
+
+#### NetworkSyncSystem
+
+处理服务器状态同步和插值：
+
+- 接收服务器状态快照
+- 将状态存入快照缓冲区
+- 对远程实体进行插值平滑
+
+#### NetworkSpawnSystem
+
+处理实体的网络生成和销毁：
+
+- 监听 Spawn/Despawn 消息
+- 使用注册的预制体工厂创建实体
+- 管理网络实体的生命周期
+
+#### NetworkInputSystem
+
+处理本地玩家输入的网络发送：
+
+- 收集本地玩家输入
+- 发送输入到服务器
+- 支持移动和动作输入
+
+## API 参考
+
+### NetworkPlugin
+
+```typescript
+class NetworkPlugin {
+    constructor(config: INetworkPluginConfig);
+
+    // 安装插件
+    install(services: ServiceContainer): void;
+
+    // 连接服务器
+    connect(playerName: string, roomId?: string): Promise<void>;
+
+    // 断开连接
+    disconnect(): void;
+
+    // 注册预制体工厂
+    registerPrefab(prefab: string, factory: PrefabFactory): void;
+
+    // 属性
+    readonly localPlayerId: number | null;
+    readonly isConnected: boolean;
+}
+```
+
+**配置选项：**
+
+| 属性 | 类型 | 必需 | 描述 |
+|------|------|------|------|
+| `serverUrl` | `string` | 是 | WebSocket 服务器地址 |
+
+### NetworkService
+
+网络服务，管理 WebSocket 连接：
+
+```typescript
+class NetworkService {
+    // 连接状态
+    readonly state: ENetworkState;
+    readonly isConnected: boolean;
+    readonly clientId: number | null;
+    readonly roomId: string | null;
+
+    // 连接控制
+    connect(serverUrl: string): Promise<void>;
+    disconnect(): void;
+
+    // 加入房间
+    join(playerName: string, roomId?: string): Promise<ResJoin>;
+
+    // 发送输入
+    sendInput(input: IPlayerInput): void;
+
+    // 事件回调
+    setCallbacks(callbacks: Partial<INetworkCallbacks>): void;
+}
+```
+
+**网络状态枚举：**
+
+```typescript
+enum ENetworkState {
+    Disconnected = 'disconnected',
+    Connecting = 'connecting',
+    Connected = 'connected',
+    Joining = 'joining',
+    Joined = 'joined'
+}
+```
+
+**回调接口：**
+
+```typescript
+interface INetworkCallbacks {
+    onConnected?: () => void;
+    onDisconnected?: () => void;
+    onJoined?: (clientId: number, roomId: string) => void;
+    onSync?: (msg: MsgSync) => void;
+    onSpawn?: (msg: MsgSpawn) => void;
+    onDespawn?: (msg: MsgDespawn) => void;
+}
+```
+
+### 预制体工厂
+
+```typescript
+type PrefabFactory = (scene: Scene, spawn: MsgSpawn) => Entity;
+```
+
+注册预制体工厂用于网络实体的创建：
+
+```typescript
+networkPlugin.registerPrefab('enemy', (scene, spawn) => {
+    const entity = scene.createEntity(`enemy_${spawn.netId}`);
+
+    const identity = entity.addComponent(new NetworkIdentity());
+    identity.netId = spawn.netId;
+    identity.ownerId = spawn.ownerId;
+
+    entity.addComponent(new NetworkTransform());
+    entity.addComponent(new EnemyComponent());
+    return entity;
+});
+```
+
+### 输入系统
+
+#### NetworkInputSystem
+
+```typescript
+class NetworkInputSystem extends EntitySystem {
+    // 添加移动输入
+    addMoveInput(x: number, y: number): void;
+
+    // 添加动作输入
+    addActionInput(action: string): void;
+
+    // 清除输入
+    clearInput(): void;
+}
+```
+
+使用示例：
+
+```typescript
+// 通过 NetworkPlugin 发送输入（推荐）
+networkPlugin.sendMoveInput(0, 1);      // 移动
+networkPlugin.sendActionInput('jump');  // 动作
+
+// 或直接使用 inputSystem
+const inputSystem = networkPlugin.inputSystem;
+if (keyboard.isPressed('W')) {
+    inputSystem.addMoveInput(0, 1);
+}
+if (keyboard.isPressed('Space')) {
+    inputSystem.addActionInput('jump');
+}
+```
+
+## 状态同步
+
+### 快照缓冲区
+
+用于存储服务器状态快照并进行插值：
+
+```typescript
+import { createSnapshotBuffer, type IStateSnapshot } from '@esengine/network';
+
+const buffer = createSnapshotBuffer<IStateSnapshot>({
+    maxSnapshots: 30,          // 最大快照数
+    interpolationDelay: 100    // 插值延迟 (ms)
+});
+
+// 添加快照
+buffer.addSnapshot({
+    time: serverTime,
+    entities: states
+});
+
+// 获取插值状态
+const interpolated = buffer.getInterpolatedState(clientTime);
+```
+
+### 变换插值器
+
+#### 线性插值器
+
+```typescript
+import { createTransformInterpolator } from '@esengine/network';
+
+const interpolator = createTransformInterpolator();
+
+// 添加状态
+interpolator.addState(time, { x: 0, y: 0, rotation: 0 });
+
+// 获取插值结果
+const state = interpolator.getInterpolatedState(currentTime);
+```
+
+#### Hermite 插值器
+
+使用 Hermite 样条实现更平滑的插值：
+
+```typescript
+import { createHermiteTransformInterpolator } from '@esengine/network';
+
+const interpolator = createHermiteTransformInterpolator({
+    bufferSize: 10
+});
+
+// 添加带速度的状态
+interpolator.addState(time, {
+    x: 100,
+    y: 200,
+    rotation: 0,
+    vx: 5,
+    vy: 0
+});
+
+// 获取平滑的插值结果
+const state = interpolator.getInterpolatedState(currentTime);
+```
+
+### 客户端预测
+
+实现客户端预测和服务器校正：
+
+```typescript
+import { createClientPrediction } from '@esengine/network';
+
+const prediction = createClientPrediction({
+    maxPredictedInputs: 60,
+    reconciliationThreshold: 0.1
+});
+
+// 预测输入
+const seq = prediction.predict(inputState, currentState, (state, input) => {
+    // 应用输入到状态
+    return applyInput(state, input);
+});
+
+// 服务器校正
+const corrected = prediction.reconcile(
+    serverState,
+    serverSeq,
+    (state, input) => applyInput(state, input)
+);
+```
+
+## 服务器端
+
+### GameServer
+
+```typescript
+import { GameServer } from '@esengine/network-server';
+
+const server = new GameServer({
+    port: 3000,
+    roomConfig: {
+        maxPlayers: 16,    // 房间最大玩家数
+        tickRate: 20       // 同步频率 (Hz)
+    }
+});
+
+// 启动服务器
+await server.start();
+
+// 获取房间
+const room = server.getOrCreateRoom('room-id');
+
+// 停止服务器
+await server.stop();
+```
+
+### Room
+
+```typescript
+class Room {
+    readonly id: string;
+    readonly playerCount: number;
+    readonly isFull: boolean;
+
+    // 添加玩家
+    addPlayer(name: string, connection: Connection): IPlayer | null;
+
+    // 移除玩家
+    removePlayer(clientId: number): void;
+
+    // 获取玩家
+    getPlayer(clientId: number): IPlayer | undefined;
+
+    // 处理输入
+    handleInput(clientId: number, input: IPlayerInput): void;
+
+    // 销毁房间
+    destroy(): void;
+}
+```
+
+**玩家接口：**
+
+```typescript
+interface IPlayer {
+    clientId: number;    // 客户端 ID
+    name: string;        // 玩家名称
+    connection: Connection;  // 连接对象
+    netId: number;       // 网络实体 ID
+}
+```
+
+## 协议类型
+
+### 消息类型
+
+```typescript
+// 状态同步消息
+interface MsgSync {
+    time: number;
+    entities: IEntityState[];
+}
+
+// 实体状态
+interface IEntityState {
+    netId: number;
+    pos?: Vec2;
+    rot?: number;
+}
+
+// 生成消息
+interface MsgSpawn {
+    netId: number;
+    ownerId: number;
+    prefab: string;
+    pos: Vec2;
+    rot: number;
+}
+
+// 销毁消息
+interface MsgDespawn {
+    netId: number;
+}
+
+// 输入消息
+interface MsgInput {
+    input: IPlayerInput;
+}
+
+// 玩家输入
+interface IPlayerInput {
+    seq?: number;
+    moveDir?: Vec2;
+    actions?: string[];
+}
+```
+
+### API 类型
+
+```typescript
+// 加入请求
+interface ReqJoin {
+    playerName: string;
+    roomId?: string;
+}
+
+// 加入响应
+interface ResJoin {
+    clientId: number;
+    roomId: string;
+    playerCount: number;
+}
+```
+
+## 蓝图节点
+
+网络模块提供了可视化脚本支持的蓝图节点：
+
+- `IsLocalPlayer` - 检查实体是否为本地玩家
+- `IsServer` - 检查是否运行在服务器端
+- `HasAuthority` - 检查是否有权限控制实体
+- `GetNetworkId` - 获取实体的网络 ID
+- `GetLocalPlayerId` - 获取本地玩家 ID
+
+## 服务令牌
+
+用于依赖注入：
+
+```typescript
+import {
+    NetworkServiceToken,
+    NetworkSyncSystemToken,
+    NetworkSpawnSystemToken,
+    NetworkInputSystemToken
+} from '@esengine/network';
+
+// 获取服务
+const networkService = services.get(NetworkServiceToken);
+```
+
+## 实际示例
+
+### 完整的多人游戏客户端
+
+```typescript
+import { Core, Scene, EntitySystem, Matcher, Entity } from '@esengine/ecs-framework';
+import {
+    NetworkPlugin,
+    NetworkIdentity,
+    NetworkTransform
+} from '@esengine/network';
+
+// 定义游戏场景
+class GameScene extends Scene {
+    initialize(): void {
+        this.name = 'MultiplayerGame';
+        // 网络系统由 NetworkPlugin 自动添加
+        // 添加自定义系统
+        this.addSystem(new LocalInputHandler());
+    }
+}
+
+// 初始化
+async function initGame() {
+    Core.create({ debug: false });
+
+    const scene = new GameScene();
+    Core.setScene(scene);
+
+    // 安装网络插件
+    const networkPlugin = new NetworkPlugin();
+    await Core.installPlugin(networkPlugin);
+
+    // 注册玩家预制体
+    networkPlugin.registerPrefab('player', (scene, spawn) => {
+        const entity = scene.createEntity(`player_${spawn.netId}`);
+
+        const identity = entity.addComponent(new NetworkIdentity());
+        identity.netId = spawn.netId;
+        identity.ownerId = spawn.ownerId;
+        identity.isLocalPlayer = spawn.ownerId === networkPlugin.networkService.localClientId;
+
+        entity.addComponent(new NetworkTransform());
+
+        // 如果是本地玩家，添加输入标记
+        if (identity.isLocalPlayer) {
+            entity.addComponent(new LocalInputComponent());
+        }
+
+        return entity;
+    });
+
+    // 连接服务器
+    const success = await networkPlugin.connect('ws://localhost:3000', 'Player1');
+    if (success) {
+        console.log('已连接!');
+    } else {
+        console.error('连接失败');
+    }
+
+    return networkPlugin;
+}
+
+// 游戏循环
+function gameLoop(deltaTime: number) {
+    Core.update(deltaTime);
+}
+
+initGame();
+```
+
+### 处理输入
+
+```typescript
+class LocalInputHandler extends EntitySystem {
+    private _networkPlugin: NetworkPlugin | null = null;
+
+    constructor() {
+        super(Matcher.empty().all(NetworkIdentity, LocalInputComponent));
+    }
+
+    protected onAddedToScene(): void {
+        // 获取 NetworkPlugin 引用
+        this._networkPlugin = Core.getPlugin(NetworkPlugin);
+    }
+
+    protected processEntity(entity: Entity, dt: number): void {
+        if (!this._networkPlugin) return;
+
+        const identity = entity.getComponent(NetworkIdentity)!;
+        if (!identity.isLocalPlayer) return;
+
+        // 读取键盘输入
+        let moveX = 0;
+        let moveY = 0;
+
+        if (keyboard.isPressed('A')) moveX -= 1;
+        if (keyboard.isPressed('D')) moveX += 1;
+        if (keyboard.isPressed('W')) moveY += 1;
+        if (keyboard.isPressed('S')) moveY -= 1;
+
+        if (moveX !== 0 || moveY !== 0) {
+            this._networkPlugin.sendMoveInput(moveX, moveY);
+        }
+
+        if (keyboard.isJustPressed('Space')) {
+            this._networkPlugin.sendActionInput('jump');
+        }
+    }
+}
+```
+
+## 最佳实践
+
+1. **合理设置同步频率**：根据游戏类型选择合适的 `tickRate`，动作游戏通常需要 20-60 Hz
+
+2. **使用插值延迟**：设置适当的 `interpolationDelay` 来平衡延迟和平滑度
+
+3. **客户端预测**：对于本地玩家使用客户端预测减少输入延迟
+
+4. **预制体管理**：为每种网络实体类型注册对应的预制体工厂
+
+5. **权限检查**：使用 `bHasAuthority` 检查是否有权限修改实体
+
+6. **连接状态**：监听连接状态变化，处理断线重连
+
+```typescript
+networkService.setCallbacks({
+    onConnected: () => console.log('已连接'),
+    onDisconnected: () => {
+        console.log('已断开');
+        // 处理重连逻辑
+    }
+});
+```