chore(editor): bump version to 1.0.5 (#201)

Co-authored-by: esengine <18465053+esengine@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
+}
+

.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

.eslintrc.json

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

.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/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/ecs-framework
+    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/ecs-framework/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/ecs-framework)
+        - [💬 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/ecs-framework)
+
+  - 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/labeler.yml

@@ -0,0 +1,32 @@
+# 自动标签配置
+# 根据 issue/PR 内容自动打标签
+
+'bug':
+  - '/(bug|错误|崩溃|crash|error|exception|问题)/i'
+
+'enhancement':
+  - '/(feature|功能|enhancement|improve|优化|建议)/i'
+
+'documentation':
+  - '/(doc|文档|readme|guide|tutorial|教程)/i'
+
+'question':
+  - '/(question|疑问|how to|如何|怎么)/i'
+
+'performance':
+  - '/(performance|性能|slow|慢|lag|卡顿|optimize)/i'
+
+'core':
+  - '/(@esengine\/ecs-framework|packages\/core|core package)/i'
+
+'editor':
+  - '/(editor|编辑器|tauri)/i'
+
+'network':
+  - '/(network|网络|multiplayer|多人)/i'
+
+'help wanted':
+  - '/(help wanted|需要帮助|求助)/i'
+
+'good first issue':
+  - '/(good first issue|新手友好|beginner)/i'

.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/ai-batch-analyze-issues.yml

@@ -0,0 +1,73 @@
+name: AI Batch Analyze Issues
+
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: '分析模式'
+        required: true
+        type: choice
+        options:
+          - 'recent' # 最近 10 个 issue
+          - 'open' # 所有打开的 issue
+          - 'all' # 所有 issue（慎用）
+        default: 'recent'
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Install GitHub CLI
+        run: |
+          gh --version || (curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
+          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
+          sudo apt update
+          sudo apt install gh)
+
+      - name: Batch Analyze Issues
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          MODE="${{ github.event.inputs.mode }}"
+
+          # 获取 issue 列表
+          if [ "$MODE" = "recent" ]; then
+            echo "📊 分析最近 10 个 issue..."
+            ISSUES=$(gh issue list --limit 10 --json number --jq '.[].number')
+          elif [ "$MODE" = "open" ]; then
+            echo "📊 分析所有打开的 issue..."
+            ISSUES=$(gh issue list --state open --json number --jq '.[].number')
+          else
+            echo "📊 分析所有 issue（这可能需要很长时间）..."
+            ISSUES=$(gh issue list --state all --limit 100 --json number --jq '.[].number')
+          fi
+
+          # 为每个 issue 添加 AI 分析评论
+          for issue_num in $ISSUES; do
+            echo "🤖 分析 Issue #$issue_num..."
+
+            # 获取 issue 内容
+            ISSUE_BODY=$(gh issue view $issue_num --json body --jq '.body')
+            ISSUE_TITLE=$(gh issue view $issue_num --json title --jq '.title')
+
+            # 添加触发评论
+            gh issue comment $issue_num --body "@ai-helper 请帮我分析这个 issue" || true
+
+            # 避免 API 限制
+            sleep 2
+          done
+
+          echo "✅ 批量分析完成！"
+          echo "查看结果：https://github.com/${{ github.repository }}/issues"

.github/workflows/ai-helper-tip.yml

@@ -0,0 +1,61 @@
+name: AI Helper Tip
+
+# 对所有新创建的 issue 自动回复 AI 助手使用说明（新老用户都适用）
+on:
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  tip:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Post AI Helper Usage Tip
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const message = [
+              "## 🤖 AI 助手可用 | AI Helper Available",
+              "",
+              "**中文说明：**",
+              "",
+              "本项目配备了 AI 智能助手，可以帮助你快速获得解答！",
+              "",
+              "**使用方法：** 在评论中提及 `@ai-helper`，AI 会自动搜索项目代码并提供解决方案。",
+              "",
+              "**示例：**",
+              "```",
+              "@ai-helper 如何创建一个新的 System？",
+              "@ai-helper 这个报错是什么原因？",
+              "```",
+              "",
+              "---",
+              "",
+              "**English:**",
+              "",
+              "This project has an AI assistant to help you get answers quickly!",
+              "",
+              "**How to use:** Mention `@ai-helper` in a comment, and AI will automatically search the codebase and provide solutions.",
+              "",
+              "**Examples:**",
+              "```",
+              "@ai-helper How do I create a new System?",
+              "@ai-helper What causes this error?",
+              "```",
+              "",
+              "---",
+              "",
+              "💡 *AI 助手基于代码库提供建议，复杂问题建议等待维护者回复*",
+              "💡 *AI suggestions are based on the codebase. For complex issues, please wait for maintainer responses*"
+            ].join('\n');
+
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: message
+            });
+
+            console.log('✅ AI helper tip posted successfully');

.github/workflows/ai-issue-helper.yml

@@ -0,0 +1,85 @@
+name: AI Issue Helper
+
+on:
+  issue_comment:
+    types: [created]
+
+permissions:
+  issues: write
+  contents: read
+  models: read
+
+jobs:
+  ai-helper:
+    runs-on: ubuntu-latest
+    # 只在真实用户提到 @ai-helper 时触发，忽略机器人评论
+    if: |
+      contains(github.event.comment.body, '@ai-helper') &&
+      github.event.comment.user.type != 'Bot'
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@v4
+
+      - name: Get Issue Details
+        id: issue
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const issue = await github.rest.issues.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number
+            });
+
+            // 限制长度，避免超过 token 限制
+            const maxLength = 1000;
+            const truncate = (str, max) => {
+              if (!str) return '';
+              return str.length > max ? str.substring(0, max) + '...[内容过长已截断]' : str;
+            };
+
+            core.exportVariable('ISSUE_TITLE', truncate(issue.data.title || '', 200));
+            core.exportVariable('ISSUE_BODY', truncate(issue.data.body || '', maxLength));
+            core.exportVariable('COMMENT_BODY', truncate(context.payload.comment.body || '', 500));
+            core.exportVariable('ISSUE_NUMBER', context.issue.number);
+
+      - name: Create Prompt
+        id: prompt
+        run: |
+          cat > prompt.txt << 'PROMPT_EOF'
+          Issue #${{ env.ISSUE_NUMBER }}
+
+          标题: ${{ env.ISSUE_TITLE }}
+
+          内容: ${{ env.ISSUE_BODY }}
+
+          评论: ${{ env.COMMENT_BODY }}
+
+          请搜索项目代码并提供解决方案。
+          PROMPT_EOF
+
+      - name: AI Analysis
+        uses: actions/ai-inference@v1
+        id: ai
+        with:
+          model: 'gpt-4o'
+          enable-github-mcp: true
+          max-tokens: 1500
+          system-prompt: |
+            你是 ECS Framework (TypeScript ECS 框架) 的 AI 助手。
+            主要代码在 packages/core/src。
+            搜索相关代码后，用中文简洁回答问题，包含问题分析、解决方案和代码引用。
+          prompt-file: prompt.txt
+
+      - name: Post AI Response
+        env:
+          AI_RESPONSE: ${{ steps.ai.outputs.response }}
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: process.env.AI_RESPONSE
+            });

.github/workflows/ai-issue-moderator.yml

@@ -0,0 +1,56 @@
+name: AI Issue Moderator
+
+on:
+  issues:
+    types: [opened]
+  issue_comment:
+    types: [created]
+
+permissions:
+  issues: write
+  contents: read
+  models: read
+
+jobs:
+  moderate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check Content
+        uses: actions/ai-inference@v1
+        id: check
+        with:
+          model: 'gpt-4o-mini'
+          system-prompt: |
+            你是一个内容审查助手。
+            检查内容是否包含：
+            1. 垃圾信息或广告
+            2. 恶意或攻击性内容
+            3. 与项目完全无关的内容
+
+            只返回 "SPAM" 或 "OK"，不要其他内容。
+          prompt: |
+            标题：${{ github.event.issue.title || github.event.comment.body }}
+
+            内容：
+            ${{ github.event.issue.body || github.event.comment.body }}
+
+      - name: Mark as Spam
+        if: contains(steps.check.outputs.response, 'SPAM')
+        uses: actions/github-script@v7
+        with:
+          script: |
+            // 添加 spam 标签
+            github.rest.issues.addLabels({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              labels: ['spam']
+            });
+
+            // 添加评论
+            github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: '🤖 这个内容被 AI 检测为可能的垃圾内容。如果这是误判，请联系维护者。\n\n🤖 This content was detected as potential spam by AI. If this is a false positive, please contact the maintainers.'
+            });

.github/workflows/batch-label-issues.yml

@@ -0,0 +1,160 @@
+name: Batch Label Issues
+
+on:
+  workflow_dispatch:
+    inputs:
+      mode:
+        description: '标签模式'
+        required: true
+        type: choice
+        options:
+          - 'recent' # 最近 20 个 issue
+          - 'open' # 所有打开的 issue
+          - 'unlabeled' # 只处理没有标签的 issue
+          - 'all' # 所有 issue（慎用）
+        default: 'recent'
+
+      skip_labeled:
+        description: '跳过已有标签的 issue'
+        required: false
+        type: boolean
+        default: true
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  batch-label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+
+      - name: Batch Label Issues
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          MODE="${{ github.event.inputs.mode }}"
+          SKIP_LABELED="${{ github.event.inputs.skip_labeled }}"
+
+          echo "📊 开始批量打标签..."
+          echo "模式: $MODE"
+          echo "跳过已标签: $SKIP_LABELED"
+
+          # 获取 issue 列表
+          if [ "$MODE" = "recent" ]; then
+            echo "📋 获取最近 20 个 issue..."
+            ISSUES=$(gh issue list --limit 20 --json number,labels,title,body --jq '.[] | {number, labels: [.labels[].name], title, body}')
+          elif [ "$MODE" = "open" ]; then
+            echo "📋 获取所有打开的 issue..."
+            ISSUES=$(gh issue list --state open --json number,labels,title,body --jq '.[] | {number, labels: [.labels[].name], title, body}')
+          elif [ "$MODE" = "unlabeled" ]; then
+            echo "📋 获取没有标签的 issue..."
+            ISSUES=$(gh issue list --state all --json number,labels,title,body --jq '.[] | select(.labels | length == 0) | {number, labels: [.labels[].name], title, body}')
+          else
+            echo "📋 获取所有 issue（限制 100 个）..."
+            ISSUES=$(gh issue list --state all --limit 100 --json number,labels,title,body --jq '.[] | {number, labels: [.labels[].name], title, body}')
+          fi
+
+          # 临时文件
+          echo "$ISSUES" > /tmp/issues.json
+
+          # 处理每个 issue
+          cat /tmp/issues.json | jq -c '.' | while read -r issue; do
+            ISSUE_NUM=$(echo "$issue" | jq -r '.number')
+            EXISTING_LABELS=$(echo "$issue" | jq -r '.labels | join(",")')
+            TITLE=$(echo "$issue" | jq -r '.title')
+            BODY=$(echo "$issue" | jq -r '.body')
+
+            echo ""
+            echo "🔍 处理 Issue #$ISSUE_NUM: $TITLE"
+            echo "   现有标签: $EXISTING_LABELS"
+
+            # 跳过已有标签的 issue
+            if [ "$SKIP_LABELED" = "true" ] && [ ! -z "$EXISTING_LABELS" ]; then
+              echo "   ⏭️  跳过（已有标签）"
+              continue
+            fi
+
+            # 分析内容并打标签
+            LABELS_TO_ADD=""
+
+            # 检测 bug
+            if echo "$TITLE $BODY" | grep -iE "(bug|错误|崩溃|crash|error|exception|问题|fix)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD bug"
+              echo "   🐛 检测到: bug"
+            fi
+
+            # 检测 feature request
+            if echo "$TITLE $BODY" | grep -iE "(feature|功能|enhancement|improve|优化|建议|新增|添加|add)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD enhancement"
+              echo "   ✨ 检测到: enhancement"
+            fi
+
+            # 检测 question
+            if echo "$TITLE $BODY" | grep -iE "(question|疑问|how to|如何|怎么|为什么|why|咨询|\?|？)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD question"
+              echo "   ❓ 检测到: question"
+            fi
+
+            # 检测 documentation
+            if echo "$TITLE $BODY" | grep -iE "(doc|文档|readme|guide|tutorial|教程|说明)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD documentation"
+              echo "   📖 检测到: documentation"
+            fi
+
+            # 检测 performance
+            if echo "$TITLE $BODY" | grep -iE "(performance|性能|slow|慢|lag|卡顿|optimize|优化)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD performance"
+              echo "   ⚡ 检测到: performance"
+            fi
+
+            # 检测 core
+            if echo "$TITLE $BODY" | grep -iE "(@esengine/ecs-framework|packages/core|core package|核心包)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD core"
+              echo "   🎯 检测到: core"
+            fi
+
+            # 检测 editor
+            if echo "$TITLE $BODY" | grep -iE "(editor|编辑器|tauri)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD editor"
+              echo "   🎨 检测到: editor"
+            fi
+
+            # 检测 network
+            if echo "$TITLE $BODY" | grep -iE "(network|网络|multiplayer|多人|同步)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD network"
+              echo "   🌐 检测到: network"
+            fi
+
+            # 检测 help wanted
+            if echo "$TITLE $BODY" | grep -iE "(help wanted|需要帮助|求助)" > /dev/null; then
+              LABELS_TO_ADD="$LABELS_TO_ADD help wanted"
+              echo "   🆘 检测到: help wanted"
+            fi
+
+            # 添加标签
+            if [ ! -z "$LABELS_TO_ADD" ]; then
+              echo "   ✅ 添加标签: $LABELS_TO_ADD"
+              for label in $LABELS_TO_ADD; do
+                gh issue edit $ISSUE_NUM --add-label "$label" 2>&1 | grep -v "already exists" || true
+              done
+              echo "   💬 添加说明评论..."
+              gh issue comment $ISSUE_NUM --body $'🤖 自动标签系统检测到此 issue 并添加了相关标签。如有误判，请告知维护者。\n\n🤖 Auto-labeling system detected and labeled this issue. Please let maintainers know if this is incorrect.' || true
+            else
+              echo "   ℹ️  未检测到明确类型"
+            fi
+
+            # 避免 API 限制
+            sleep 1
+          done
+
+          echo ""
+          echo "✅ 批量标签完成！"
+          echo "查看结果: https://github.com/${{ github.repository }}/issues"

.github/workflows/ci.yml

@@ -37,6 +37,12 @@ jobs:
     - name: Install dependencies
       run: npm ci
 
+    - name: Type check
+      run: npm run type-check
+
+    - name: Lint check
+      run: npm run lint
+
     - name: Build core package first
       run: npm run build:core
 

.github/workflows/cleanup-dependabot.yml

@@ -0,0 +1,146 @@
+name: Cleanup Old Dependabot PRs
+
+# 手动触发的 workflow，用于清理堆积的 Dependabot PR
+on:
+  workflow_dispatch:
+    inputs:
+      days_old:
+        description: '关闭多少天前创建的 PR（默认 7 天）'
+        required: false
+        default: '7'
+      dry_run:
+        description: '试运行模式（true=仅显示，不关闭）'
+        required: false
+        default: 'true'
+        type: choice
+        options:
+          - 'true'
+          - 'false'
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      issues: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: List and Close Old Dependabot PRs
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const daysOld = parseInt('${{ github.event.inputs.days_old }}') || 7;
+            const dryRun = '${{ github.event.inputs.dry_run }}' === 'true';
+            const cutoffDate = new Date();
+            cutoffDate.setDate(cutoffDate.getDate() - daysOld);
+
+            console.log(`🔍 查找超过 ${daysOld} 天的 Dependabot PR...`);
+            console.log(`📅 截止日期: ${cutoffDate.toISOString()}`);
+            console.log(`🏃 模式: ${dryRun ? '试运行（不会实际关闭）' : '实际执行'}`);
+            console.log('---');
+
+            // 获取所有 Dependabot PR
+            const { data: pulls } = await github.rest.pulls.list({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              state: 'open',
+              per_page: 100
+            });
+
+            const dependabotPRs = pulls.filter(pr =>
+              pr.user.login === 'dependabot[bot]' &&
+              new Date(pr.created_at) < cutoffDate
+            );
+
+            console.log(`📊 找到 ${dependabotPRs.length} 个符合条件的 Dependabot PR`);
+            console.log('');
+
+            if (dependabotPRs.length === 0) {
+              console.log('✅ 没有需要清理的 PR');
+              return;
+            }
+
+            // 按类型分组
+            const byType = {
+              dev: [],
+              prod: [],
+              actions: [],
+              other: []
+            };
+
+            for (const pr of dependabotPRs) {
+              const title = pr.title.toLowerCase();
+              const labels = pr.labels.map(l => l.name);
+
+              let type = 'other';
+              if (title.includes('dev-dependencies') || title.includes('development')) {
+                type = 'dev';
+              } else if (title.includes('production-dependencies')) {
+                type = 'prod';
+              } else if (labels.includes('github-actions')) {
+                type = 'actions';
+              }
+
+              byType[type].push(pr);
+            }
+
+            console.log('📋 PR 分类统计:');
+            console.log(`  🔧 开发依赖: ${byType.dev.length} 个`);
+            console.log(`  📦 生产依赖: ${byType.prod.length} 个`);
+            console.log(`  ⚙️  GitHub Actions: ${byType.actions.length} 个`);
+            console.log(`  ❓ 其他: ${byType.other.length} 个`);
+            console.log('');
+
+            // 处理每个 PR
+            for (const pr of dependabotPRs) {
+              const age = Math.floor((Date.now() - new Date(pr.created_at)) / (1000 * 60 * 60 * 24));
+
+              console.log(`${dryRun ? '🔍' : '🗑️ '} #${pr.number}: ${pr.title}`);
+              console.log(`   创建时间: ${pr.created_at} (${age} 天前)`);
+              console.log(`   链接: ${pr.html_url}`);
+
+              if (!dryRun) {
+                await github.rest.pulls.update({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  pull_number: pr.number,
+                  state: 'closed'
+                });
+
+                await github.rest.issues.createComment({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  issue_number: pr.number,
+                  body: `🤖 **自动关闭旧的 Dependabot PR**
+
+此 PR 已超过 ${daysOld} 天未合并，已被自动关闭以清理积压。
+
+📌 **下一步：**
+- Dependabot 已配置为月度运行，届时会创建新的分组更新
+- 新的 Mergify 规则会智能处理不同类型的依赖更新
+- 开发依赖和 GitHub Actions 会自动合并（即使 CI 失败）
+- 生产依赖需要 CI 通过才会自动合并
+
+如果需要立即应用此更新，请手动更新依赖。
+
+---
+*此操作由仓库维护者手动触发的清理工作流执行*`
+                });
+
+                console.log('   ✅ 已关闭并添加说明');
+              } else {
+                console.log('   ℹ️  试运行模式 - 未执行操作');
+              }
+              console.log('');
+            }
+
+            console.log('---');
+            if (dryRun) {
+              console.log(`✨ 试运行完成！共发现 ${dependabotPRs.length} 个待清理的 PR`);
+              console.log('💡 要实际执行清理，请将 dry_run 参数设为 false 重新运行');
+            } else {
+              console.log(`✅ 清理完成！已关闭 ${dependabotPRs.length} 个 Dependabot PR`);
+            }

.github/workflows/codecov.yml

@@ -0,0 +1,45 @@
+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: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: |
+          cd packages/core
+          npm run test:coverage
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          files: ./packages/core/coverage/coverage-final.json
+          flags: core
+          name: core-coverage
+          fail_ci_if_error: true
+          verbose: true
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: packages/core/coverage/

.github/workflows/codeql.yml

@@ -0,0 +1,41 @@
+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
+
+    - 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,31 @@
+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: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - name: Install commitlint
+        run: |
+          npm install --save-dev @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/issue-labeler.yml

@@ -0,0 +1,23 @@
+name: Issue Labeler
+
+on:
+  issues:
+    types: [opened, edited]
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Label Issues
+        uses: github/issue-labeler@v3.4
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          configuration-path: .github/labeler.yml
+          enable-versioned-regex: 1

.github/workflows/issue-translator.yml

@@ -0,0 +1,28 @@
+name: Issue Translator
+
+on:
+  issue_comment:
+    types: [created]
+  issues:
+    types: [opened]
+
+permissions:
+  issues: write
+
+jobs:
+  translate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Translate Issues
+        uses: tomsun28/issues-translate-action@v2.7
+        with:
+          IS_MODIFY_TITLE: false
+          # 设置为 true 会修改标题，false 只在评论中添加翻译
+          CUSTOM_BOT_NOTE: |
+            <details>
+            <summary>🌏 Translation / 翻译</summary>
+
+            Bot detected the issue body's language is not English, translate it automatically.
+            机器人检测到 issue 内容非英文，自动翻译。
+
+            </details>

.github/workflows/release-editor.yml

@@ -0,0 +1,157 @@
+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: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          cache: 'npm'
+
+      - 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-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: npm ci
+
+      - name: Update version in config files (for manual trigger)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          cd packages/editor-app
+          # 临时更新版本号用于构建（不提交到仓库）
+          npm version ${{ github.event.inputs.version }} --no-git-tag-version
+          node scripts/sync-version.js
+
+      - name: Cache TypeScript build
+        uses: actions/cache@v4
+        with:
+          path: |
+            packages/core/bin
+            packages/editor-core/dist
+            packages/behavior-tree/bin
+          key: ${{ runner.os }}-ts-build-${{ hashFiles('packages/core/src/**', 'packages/editor-core/src/**', 'packages/behavior-tree/src/**') }}
+          restore-keys: |
+            ${{ runner.os }}-ts-build-
+
+      - name: Build core package
+        run: npm run build:core
+
+      - name: Build editor-core package
+        run: |
+          cd packages/editor-core
+          npm run build
+
+      - name: Build behavior-tree package
+        run: |
+          cd packages/behavior-tree
+          npm run build
+
+      - name: Build Tauri app
+        uses: tauri-apps/tauri-action@v0.5
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAURI_SIGNING_PRIVATE_KEY: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY }}
+          TAURI_SIGNING_PRIVATE_KEY_PASSWORD: ${{ secrets.TAURI_SIGNING_PRIVATE_KEY_PASSWORD }}
+        with:
+          projectPath: packages/editor-app
+          tagName: ${{ github.event_name == 'workflow_dispatch' && format('editor-v{0}', github.event.inputs.version) || github.ref_name }}
+          releaseName: 'ECS Editor v${{ github.event.inputs.version || github.ref_name }}'
+          releaseBody: 'See the assets to download this version and install.'
+          releaseDraft: false
+          prerelease: false
+          includeUpdaterJson: true
+          updaterJsonKeepUniversal: false
+          args: ${{ matrix.platform == 'macos-latest' && format('--target {0}', matrix.target) || '' }}
+
+  # 构建成功后，创建 PR 更新版本号
+  update-version-pr:
+    needs: build-tauri
+    if: github.event_name == 'workflow_dispatch' && success()
+    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-app
+          npm version ${{ github.event.inputs.version }} --no-git-tag-version
+          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-app/package.json` → `${{ github.event.inputs.version }}`
+            - ✅ Updated `packages/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,112 @@
+name: Release NPM Packages
+
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: '选择要发布的包'
+        required: true
+        type: choice
+        options:
+          - core
+          - behavior-tree
+          - editor-core
+      version_type:
+        description: '版本更新类型'
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+          - custom
+      custom_version:
+        description: '自定义版本号 (仅当选择 custom 时使用，例如: 2.2.9)'
+        required: false
+        type: string
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release-package:
+    name: Release ${{ github.event.inputs.package }} Package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20.x'
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build core package (if needed)
+        if: ${{ github.event.inputs.package == 'behavior-tree' || github.event.inputs.package == 'editor-core' }}
+        run: |
+          cd packages/core
+          npm run build
+
+      # - name: Run tests
+      #   run: |
+      #     cd packages/${{ github.event.inputs.package }}
+      #     npm run test:ci
+
+      - name: Update version
+        id: version
+        run: |
+          cd packages/${{ github.event.inputs.package }}
+          if [ "${{ github.event.inputs.version_type }}" = "custom" ]; then
+            npm version ${{ github.event.inputs.custom_version }} --no-git-tag-version --allow-same-version
+          else
+            npm version ${{ github.event.inputs.version_type }} --no-git-tag-version
+          fi
+          NEW_VERSION=$(node -p "require('./package.json').version")
+          echo "new_version=$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo "发布版本: $NEW_VERSION"
+
+      - name: Build package
+        run: |
+          cd packages/${{ github.event.inputs.package }}
+          npm run build:npm
+
+      - name: Publish to npm
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          cd packages/${{ github.event.inputs.package }}/dist
+          npm publish --access public
+
+      - name: Create Pull Request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: "chore(${{ github.event.inputs.package }}): release v${{ steps.version.outputs.new_version }}"
+          branch: release/${{ github.event.inputs.package }}-v${{ steps.version.outputs.new_version }}
+          delete-branch: true
+          title: "chore(${{ github.event.inputs.package }}): Release v${{ steps.version.outputs.new_version }}"
+          body: |
+            ## 🚀 Release v${{ steps.version.outputs.new_version }}
+
+            此 PR 更新 `@esengine/${{ github.event.inputs.package }}` 包的版本号
+
+            ### 变更
+            - ✅ 已发布到 npm: [@esengine/${{ github.event.inputs.package }}@${{ steps.version.outputs.new_version }}](https://www.npmjs.com/package/@esengine/${{ github.event.inputs.package }}/v/${{ steps.version.outputs.new_version }})
+            - ✅ 更新 `packages/${{ github.event.inputs.package }}/package.json` → `${{ steps.version.outputs.new_version }}`
+
+            ---
+            *此 PR 由发布工作流自动创建*
+          labels: |
+            release
+            ${{ github.event.inputs.package }}
+            automated pr

.github/workflows/size-limit.yml

@@ -0,0 +1,43 @@
+name: Size Limit
+
+on:
+  pull_request:
+    branches:
+      - master
+      - main
+    paths:
+      - 'packages/core/src/**'
+      - 'packages/core/package.json'
+      - '.size-limit.json'
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  size:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        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 core package
+        run: |
+          cd packages/core
+          npm run build:npm
+
+      - name: Check bundle size
+        uses: andresz1/size-limit-action@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          skip_step: install

.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

.github/workflows/welcome.yml

@@ -0,0 +1,58 @@
+name: Welcome
+
+on:
+  issues:
+    types: [opened]
+  pull_request_target:
+    types: [opened]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  welcome:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Welcome new contributors
+        uses: actions/first-interaction@v1
+        with:
+          repo-token: ${{ secrets.GITHUB_TOKEN }}
+          issue-message: |
+            👋 你好！感谢你提交第一个 issue！
+
+            我们会尽快查看并回复。同时，建议你：
+            - 📚 查看[文档](https://esengine.github.io/ecs-framework/)
+            - 🤖 使用 [AI 文档助手](https://deepwiki.com/esengine/ecs-framework)
+            - 💬 加入 [QQ 交流群](https://jq.qq.com/?_wv=1027&k=29w1Nud6)
+
+            ---
+
+            👋 Hello! Thanks for opening your first issue!
+
+            We'll review it as soon as possible. Meanwhile, you might want to:
+            - 📚 Check the [documentation](https://esengine.github.io/ecs-framework/)
+            - 🤖 Use [AI documentation assistant](https://deepwiki.com/esengine/ecs-framework)
+
+          pr-message: |
+            👋 你好！感谢你提交第一个 Pull Request！
+
+            在我们 Review 之前，请确保：
+            - ✅ 代码遵循项目规范
+            - ✅ 通过所有测试
+            - ✅ 更新了相关文档
+            - ✅ Commit 遵循 [Conventional Commits](https://www.conventionalcommits.org/) 规范
+
+            查看完整的[贡献指南](https://github.com/esengine/ecs-framework/blob/master/CONTRIBUTING.md)。
+
+            ---
+
+            👋 Hello! Thanks for your first Pull Request!
+
+            Before we review, please ensure:
+            - ✅ Code follows project conventions
+            - ✅ All tests pass
+            - ✅ Documentation is updated
+            - ✅ Commits follow [Conventional Commits](https://www.conventionalcommits.org/)
+
+            See the full [Contributing Guide](https://github.com/esengine/ecs-framework/blob/master/CONTRIBUTING.md).

.gitignore

@@ -69,3 +69,12 @@ 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/

.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

.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,133 @@
+# 贡献指南 / 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**: 数学库包
+- **network-client**: 网络客户端包
+- **network-server**: 网络服务端包
+- **network-shared**: 网络共享包
+- **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/ecs-framework/issues/new)。
+
+If you find a bug or have a feature request, please [create an issue](https://github.com/esengine/ecs-framework/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 ECS Framework
 
-   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,12 +1,53 @@
 # ECS Framework
 
 [![CI](https://github.com/esengine/ecs-framework/workflows/CI/badge.svg)](https://github.com/esengine/ecs-framework/actions)
+[![codecov](https://codecov.io/gh/esengine/ecs-framework/graph/badge.svg)](https://codecov.io/gh/esengine/ecs-framework)
 [![npm version](https://badge.fury.io/js/%40esengine%2Fecs-framework.svg)](https://badge.fury.io/js/%40esengine%2Fecs-framework)
+[![npm downloads](https://img.shields.io/npm/dm/@esengine/ecs-framework.svg)](https://www.npmjs.com/package/@esengine/ecs-framework)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@esengine/ecs-framework)](https://bundlephobia.com/package/@esengine/ecs-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)
+[![All Contributors](https://img.shields.io/badge/all_contributors-0-orange.svg?style=flat-square)](#contributors)
 [![GitHub stars](https://img.shields.io/github/stars/esengine/ecs-framework?style=social)](https://github.com/esengine/ecs-framework/stargazers)
+[![DeepWiki](https://img.shields.io/badge/_AI_文档-DeepWiki-6366f1?style=flat&logo=gitbook&logoColor=white)](https://deepwiki.com/esengine/ecs-framework)
 
-一个高性能的 TypeScript ECS (Entity-Component-System) 框架，专为现代游戏开发而设计。
+<div align="center">
+
+  <p>一个高性能的 TypeScript ECS (Entity-Component-System) 框架，专为现代游戏开发而设计。</p>
+
+  <p>A high-performance TypeScript ECS (Entity-Component-System) framework designed for modern game development.</p>
+
+</div>
+
+---
+
+## 📊 项目统计 / Project Stats
+
+<div align="center">
+
+[![Star History Chart](https://api.star-history.com/svg?repos=esengine/ecs-framework&type=Date)](https://star-history.com/#esengine/ecs-framework&Date)
+
+</div>
+
+<div align="center">
+
+<a href="https://github.com/esengine/ecs-framework/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=esengine/ecs-framework" />
+</a>
+
+</div>
+
+### 📈 下载趋势 / Download Trends
+
+<div align="center">
+
+[![NPM Downloads](https://img.shields.io/npm/dt/@esengine/ecs-framework?label=Total%20Downloads&style=for-the-badge&color=blue)](https://www.npmjs.com/package/@esengine/ecs-framework)
+
+[![NPM Trends](https://img.shields.io/npm/dm/@esengine/ecs-framework?label=Monthly%20Downloads&style=for-the-badge&color=success)](https://npmtrends.com/@esengine/ecs-framework)
+
+</div>
+
+---
 
 ## 特性
 
@@ -91,15 +132,75 @@ function gameLoop(deltaTime: number) {
 - **多场景** - 支持 World/Scene 分层架构
 - **时间管理** - 内置定时器和时间控制系统
 
+## 🏗️ 架构设计 / Architecture
+
+```mermaid
+graph TB
+    A[Core 核心] --> B[World 世界]
+    B --> C[Scene 场景]
+    C --> D[EntityManager 实体管理器]
+    C --> E[SystemManager 系统管理器]
+    D --> F[Entity 实体]
+    F --> G[Component 组件]
+    E --> H[EntitySystem 实体系统]
+    E --> I[WorkerSystem 工作线程系统]
+
+    style A fill:#e1f5ff
+    style B fill:#fff3e0
+    style C fill:#f3e5f5
+    style D fill:#e8f5e9
+    style E fill:#fff9c4
+    style F fill:#ffebee
+    style G fill:#e0f2f1
+    style H fill:#fce4ec
+    style I fill:#f1f8e9
+```
+
 ## 平台支持
 
 支持主流游戏引擎和 Web 平台：
 
-- **Cocos Creator** - 内置引擎集成支持，提供[专用调试插件](https://store.cocos.com/app/detail/7823)
-- **Laya 引擎** - 完整的生命周期管理
+- **Cocos Creator**
+- **Laya 引擎**
 - **原生 Web** - 浏览器环境直接运行
 - **小游戏平台** - 微信、支付宝等小游戏
 
+## ECS Framework Editor
+
+跨平台桌面编辑器，提供可视化开发和调试工具。
+
+### 主要功能
+
+- **场景管理** - 可视化场景层级和实体管理
+- **组件检视** - 实时查看和编辑实体组件
+- **性能分析** - 内置 Profiler 监控系统性能
+- **插件系统** - 可扩展的插件架构
+- **远程调试** - 连接运行中的游戏进行实时调试
+- **自动更新** - 支持热更新，自动获取最新版本
+
+### 下载
+
+[![Latest Release](https://img.shields.io/github/v/release/esengine/ecs-framework?label=下载最新版本&style=for-the-badge)](https://github.com/esengine/ecs-framework/releases/latest)
+
+支持 Windows、macOS (Intel & Apple Silicon)
+
+### 截图
+
+<img src="screenshots/main_screetshot.png" alt="ECS Framework Editor" width="800">
+
+<details>
+<summary>查看更多截图</summary>
+
+**性能分析器**
+<img src="screenshots/performance_profiler.png" alt="Performance Profiler" width="600">
+
+**插件管理**
+<img src="screenshots/plugin_manager.png" alt="Plugin Manager" width="600">
+
+**设置界面**
+<img src="screenshots/settings.png" alt="Settings" width="600">
+
+</details>
 
 ## 示例项目
 
@@ -108,6 +209,7 @@ function gameLoop(deltaTime: number) {
 
 ## 文档
 
+- [📚 AI智能文档](https://deepwiki.com/esengine/ecs-framework) - AI助手随时解答你的问题
 - [快速入门](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 文档
@@ -117,11 +219,56 @@ function gameLoop(deltaTime: number) {
 - [路径寻找](https://github.com/esengine/ecs-astar) - A*、BFS、Dijkstra 算法
 - [AI 系统](https://github.com/esengine/BehaviourTree-ai) - 行为树、效用 AI
 
+## 💪 支持项目 / Support the Project
+
+如果这个项目对你有帮助，请考虑：
+
+If this project helps you, please consider:
+
+<div align="center">
+
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-ea4aaa?style=for-the-badge&logo=github)](https://github.com/sponsors/esengine)
+[![Star on GitHub](https://img.shields.io/badge/⭐_Star-on_GitHub-yellow?style=for-the-badge&logo=github)](https://github.com/esengine/ecs-framework)
+
+</div>
+
+- ⭐ 给项目点个 Star
+- 🐛 报告 Bug 或提出新功能
+- 📝 改进文档
+- 💖 成为赞助者
+
 ## 社区与支持
 
 - [问题反馈](https://github.com/esengine/ecs-framework/issues) - Bug 报告和功能建议
+- [讨论区](https://github.com/esengine/ecs-framework/discussions) - 提问、分享想法
 - [QQ 交流群](https://jq.qq.com/?_wv=1027&k=29w1Nud6) - ecs游戏框架交流
 
+## 贡献者 / Contributors
+
+感谢所有为这个项目做出贡献的人！
+
+Thanks goes to these wonderful people:
+
+<!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-disable -->
+<table>
+  <tbody>
+    <tr>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/esengine"><img src="https://avatars.githubusercontent.com/esengine?s=100" width="100px;" alt="esengine"/><br /><sub><b>esengine</b></sub></a><br /><a href="#maintenance-esengine" title="Maintenance">🚧</a> <a href="https://github.com/esengine/ecs-framework/commits?author=esengine" title="Code">💻</a> <a href="#design-esengine" title="Design">🎨</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/foxling"><img src="https://avatars.githubusercontent.com/foxling?s=100" width="100px;" alt="LING YE"/><br /><sub><b>LING YE</b></sub></a><br /><a href="https://github.com/esengine/ecs-framework/commits?author=foxling" title="Code">💻</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://github.com/MirageTank"><img src="https://avatars.githubusercontent.com/MirageTank?s=100" width="100px;" alt="MirageTank"/><br /><sub><b>MirageTank</b></sub></a><br /><a href="https://github.com/esengine/ecs-framework/commits?author=MirageTank" title="Code">💻</a></td>
+    </tr>
+  </tbody>
+</table>
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+
+<!-- ALL-CONTRIBUTORS-LIST:END -->
+
+本项目遵循 [all-contributors](https://github.com/all-contributors/all-contributors) 规范。欢迎任何形式的贡献！
+
 ## 许可证
 
-[MIT](LICENSE) © 2025 ECS Framework
+[MIT](LICENSE) © 2025 ECS Framework

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

@@ -66,6 +66,7 @@ export default defineConfig({
           items: [
             { text: '实体类 (Entity)', link: '/guide/entity' },
             { text: '组件系统 (Component)', link: '/guide/component' },
+            { text: '实体查询系统', link: '/guide/entity-query' },
             {
               text: '系统架构 (System)',
               link: '/guide/system',
@@ -73,13 +74,43 @@ export default defineConfig({
                 { text: 'Worker系统 (多线程)', link: '/guide/worker-system' }
               ]
             },
-            { text: '场景管理 (Scene)', link: '/guide/scene' },
+            {
+              text: '场景管理 (Scene)',
+              link: '/guide/scene',
+              items: [
+                { text: 'SceneManager', link: '/guide/scene-manager' },
+                { text: 'WorldManager', link: '/guide/world-manager' }
+              ]
+            },
+            {
+              text: '行为树系统 (Behavior Tree)',
+              link: '/guide/behavior-tree/',
+              items: [
+                { text: '快速开始', link: '/guide/behavior-tree/getting-started' },
+                { text: '核心概念', link: '/guide/behavior-tree/core-concepts' },
+                { text: '编辑器指南', link: '/guide/behavior-tree/editor-guide' },
+                { text: '编辑器工作流', link: '/guide/behavior-tree/editor-workflow' },
+                { text: '自定义动作组件', link: '/guide/behavior-tree/custom-actions' },
+                { text: 'Cocos Creator集成', link: '/guide/behavior-tree/cocos-integration' },
+                { text: 'Laya引擎集成', link: '/guide/behavior-tree/laya-integration' },
+                { text: '高级用法', link: '/guide/behavior-tree/advanced-usage' },
+                { text: '最佳实践', link: '/guide/behavior-tree/best-practices' }
+              ]
+            },
             { text: '序列化系统 (Serialization)', link: '/guide/serialization' },
             { text: '事件系统 (Event)', link: '/guide/event-system' },
             { text: '时间和定时器 (Time)', link: '/guide/time-and-timers' },
             { text: '日志系统 (Logger)', link: '/guide/logging' }
           ]
         },
+        {
+          text: '高级特性',
+          collapsed: false,
+          items: [
+            { text: '服务容器 (Service Container)', link: '/guide/service-container' },
+            { text: '插件系统 (Plugin System)', link: '/guide/plugin-system' }
+          ]
+        },
         {
           text: '平台适配器',
           link: '/guide/platform-adapter',

docs/guide/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/guide/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/guide/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/guide/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/guide/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/guide/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/guide/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/guide/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/guide/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/ecs-framework/issues)
+- 加入社区讨论
+- 参考文档中的完整代码示例

docs/guide/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/guide/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/guide/component.md

@@ -63,14 +63,14 @@ class Health extends Component {
 - 框架能正确管理组件注册
 
 ```typescript
-// ✅ 正确的用法
+// 正确的用法
 @ECSComponent('Velocity')
 class Velocity extends Component {
   dx: number = 0;
   dy: number = 0;
 }
 
-// ❌ 错误的用法 - 没有装饰器
+// 错误的用法 - 没有装饰器
 class BadComponent extends Component {
   // 这样定义的组件可能在生产环境出现问题
 }
@@ -90,7 +90,7 @@ class ExampleComponent extends Component {
    * 用于初始化资源、建立引用等
    */
   onAddedToEntity(): void {
-    console.log(`组件 ${this.constructor.name} 被添加到实体 ${this.entity.name}`);
+    console.log(`组件 ${this.constructor.name} 已添加，实体ID: ${this.entityId}`);
     this.resource = new SomeResource();
   }
 
@@ -99,7 +99,7 @@ class ExampleComponent extends Component {
    * 用于清理资源、断开引用等
    */
   onRemovedFromEntity(): void {
-    console.log(`组件 ${this.constructor.name} 从实体 ${this.entity.name} 移除`);
+    console.log(`组件 ${this.constructor.name} 已移除`);
     if (this.resource) {
       this.resource.cleanup();
       this.resource = null;
@@ -108,30 +108,58 @@ class ExampleComponent extends Component {
 }
 ```
 
-## 访问实体
+## 组件与实体的关系
 
-组件可以通过 `this.entity` 访问其所属的实体：
+组件存储了所属实体的ID (`entityId`)，而不是直接引用实体对象。这是ECS数据导向设计的体现，避免了循环引用。
+
+在实际使用中，**应该在 System 中处理实体和组件的交互**，而不是在组件内部：
 
 ```typescript
-@ECSComponent('Damage')
-class Damage extends Component {
-  damage: number;
+@ECSComponent('Health')
+class Health extends Component {
+  current: number;
+  max: number;
 
-  constructor(damage: number) {
+  constructor(max: number = 100) {
     super();
-    this.damage = damage;
+    this.max = max;
+    this.current = max;
   }
 
-  // 在组件方法中访问实体和其他组件
-  applyDamage(): void {
-    const health = this.entity.getComponent(Health);
-    if (health) {
-      health.takeDamage(this.damage);
+  isDead(): boolean {
+    return this.current <= 0;
+  }
+}
+
+@ECSComponent('Damage')
+class Damage extends Component {
+  value: number;
+
+  constructor(value: number) {
+    super();
+    this.value = value;
+  }
+}
+
+// 推荐：在 System 中处理逻辑
+class DamageSystem extends EntitySystem {
+  constructor() {
+    super(new Matcher().all(Health, Damage));
+  }
+
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health)!;
+      const damage = entity.getComponent(Damage)!;
+
+      health.current -= damage.value;
 
-      // 如果生命值为0，销毁实体
       if (health.isDead()) {
-        this.entity.destroy();
+        entity.destroy();
       }
+
+      // 应用伤害后移除 Damage 组件
+      entity.removeComponent(damage);
     }
   }
 }
@@ -146,9 +174,27 @@ class Damage extends Component {
 class ExampleComponent extends Component {
   someData: string = "example";
 
-  showComponentInfo(): void {
-    console.log(`组件ID: ${this.id}`);                    // 唯一的组件ID
-    console.log(`所属实体: ${this.entity.name}`);          // 所属实体引用
+  onAddedToEntity(): void {
+    console.log(`组件ID: ${this.id}`);           // 唯一的组件ID
+    console.log(`所属实体ID: ${this.entityId}`); // 所属实体的ID
+  }
+}
+```
+
+如果需要访问实体对象，应该在 System 中进行：
+
+```typescript
+class ExampleSystem extends EntitySystem {
+  constructor() {
+    super(new Matcher().all(ExampleComponent));
+  }
+
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const comp = entity.getComponent(ExampleComponent)!;
+      console.log(`实体名称: ${entity.name}`);
+      console.log(`组件数据: ${comp.someData}`);
+    }
   }
 }
 ```
@@ -245,7 +291,7 @@ class WeaponConfig extends Component {
 ### 1. 保持组件简单
 
 ```typescript
-// ✅ 好的组件设计 - 单一职责
+// 好的组件设计 - 单一职责
 @ECSComponent('Position')
 class Position extends Component {
   x: number = 0;
@@ -258,7 +304,7 @@ class Velocity extends Component {
   dy: number = 0;
 }
 
-// ❌ 避免的组件设计 - 职责过多
+// 避免的组件设计 - 职责过多
 @ECSComponent('GameObject')
 class GameObject extends Component {
   x: number;
@@ -330,16 +376,11 @@ class Inventory extends Component {
 }
 ```
 
-### 4. 避免在组件中存储实体引用
+### 4. 引用其他实体
+
+当组件需要关联其他实体时（如父子关系、跟随目标等），**推荐方式是存储实体ID**，然后在 System 中查找：
 
 ```typescript
-// ❌ 避免：在组件中存储其他实体的引用
-@ECSComponent('BadFollower')
-class BadFollower extends Component {
-  target: Entity; // 直接引用可能导致内存泄漏
-}
-
-// ✅ 推荐：存储实体ID，通过场景查找
 @ECSComponent('Follower')
 class Follower extends Component {
   targetId: number;
@@ -349,11 +390,269 @@ class Follower extends Component {
     super();
     this.targetId = targetId;
   }
+}
 
-  getTarget(): Entity | null {
-    return this.entity.scene?.findEntityById(this.targetId) || null;
+// 在 System 中查找目标实体并处理逻辑
+class FollowerSystem extends EntitySystem {
+  constructor() {
+    super(new Matcher().all(Follower, Position));
+  }
+
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const follower = entity.getComponent(Follower)!;
+      const position = entity.getComponent(Position)!;
+
+      // 通过场景查找目标实体
+      const target = entity.scene?.findEntityById(follower.targetId);
+      if (target) {
+        const targetPos = target.getComponent(Position);
+        if (targetPos) {
+          // 跟随逻辑
+          const dx = targetPos.x - position.x;
+          const dy = targetPos.y - position.y;
+          const distance = Math.sqrt(dx * dx + dy * dy);
+
+          if (distance > follower.followDistance) {
+            // 移动靠近目标
+          }
+        }
+      }
+    }
   }
 }
 ```
 
+这种方式的优势：
+- 组件保持简单，只存储基本数据类型
+- 符合数据导向设计
+- 在 System 中统一处理查找和逻辑
+- 易于理解和维护
+
+**避免在组件中直接存储实体引用**：
+
+```typescript
+// 错误示范：直接存储实体引用
+@ECSComponent('BadFollower')
+class BadFollower extends Component {
+  target: Entity; // 实体销毁后仍持有引用，可能导致内存泄漏
+}
+```
+
+## 高级特性
+
+### EntityRef 装饰器 - 自动引用追踪
+
+框架提供了 `@EntityRef` 装饰器用于**特殊场景**下安全地存储实体引用。这是一个高级特性,一般情况下推荐使用存储ID的方式。
+
+#### 什么时候需要 EntityRef？
+
+在以下场景中,`@EntityRef` 可以简化代码:
+
+1. **父子关系**: 需要在组件中直接访问父实体或子实体
+2. **复杂关联**: 实体之间有多个引用关系
+3. **频繁访问**: 需要在多处访问引用的实体,使用ID查找会有性能开销
+
+#### 核心特性
+
+`@EntityRef` 装饰器通过 **ReferenceTracker** 自动追踪引用关系:
+
+- 当被引用的实体销毁时,所有指向它的 `@EntityRef` 属性自动设为 `null`
+- 防止跨场景引用(会输出警告并拒绝设置)
+- 防止引用已销毁的实体(会输出警告并设为 `null`)
+- 使用 WeakRef 避免内存泄漏(自动GC支持)
+- 组件移除时自动清理引用注册
+
+#### 基本用法
+
+```typescript
+import { Component, ECSComponent, EntityRef, Entity } from '@esengine/ecs-framework';
+
+@ECSComponent('Parent')
+class ParentComponent extends Component {
+  @EntityRef()
+  parent: Entity | null = null;
+}
+
+// 使用示例
+const scene = new Scene();
+const parent = scene.createEntity('Parent');
+const child = scene.createEntity('Child');
+
+const comp = child.addComponent(new ParentComponent());
+comp.parent = parent;
+
+console.log(comp.parent); // Entity { name: 'Parent' }
+
+// 当 parent 被销毁时，comp.parent 自动变为 null
+parent.destroy();
+console.log(comp.parent); // null
+```
+
+#### 多个引用属性
+
+一个组件可以有多个 `@EntityRef` 属性:
+
+```typescript
+@ECSComponent('Combat')
+class CombatComponent extends Component {
+  @EntityRef()
+  target: Entity | null = null;
+
+  @EntityRef()
+  ally: Entity | null = null;
+
+  @EntityRef()
+  lastAttacker: Entity | null = null;
+}
+
+// 使用示例
+const player = scene.createEntity('Player');
+const enemy = scene.createEntity('Enemy');
+const npc = scene.createEntity('NPC');
+
+const combat = player.addComponent(new CombatComponent());
+combat.target = enemy;
+combat.ally = npc;
+
+// enemy 销毁后，只有 target 变为 null，ally 仍然有效
+enemy.destroy();
+console.log(combat.target); // null
+console.log(combat.ally);   // Entity { name: 'NPC' }
+```
+
+#### 安全检查
+
+`@EntityRef` 提供了多重安全检查:
+
+```typescript
+const scene1 = new Scene();
+const scene2 = new Scene();
+
+const entity1 = scene1.createEntity('Entity1');
+const entity2 = scene2.createEntity('Entity2');
+
+const comp = entity1.addComponent(new ParentComponent());
+
+// 跨场景引用会失败
+comp.parent = entity2; // 输出错误日志，comp.parent 为 null
+console.log(comp.parent); // null
+
+// 引用已销毁的实体会失败
+const entity3 = scene1.createEntity('Entity3');
+entity3.destroy();
+comp.parent = entity3; // 输出警告日志，comp.parent 为 null
+console.log(comp.parent); // null
+```
+
+#### 实现原理
+
+`@EntityRef` 使用以下机制实现自动引用追踪:
+
+1. **ReferenceTracker**: Scene 持有一个引用追踪器,记录所有实体引用关系
+2. **WeakRef**: 使用弱引用存储组件,避免循环引用导致内存泄漏
+3. **属性拦截**: 通过 `Object.defineProperty` 拦截 getter/setter
+4. **自动清理**: 实体销毁时,ReferenceTracker 遍历所有引用并设为 null
+
+```typescript
+// 简化的实现原理
+class ReferenceTracker {
+  // entityId -> 引用该实体的所有组件记录
+  private _references: Map<number, Set<{ component: WeakRef<Component>, propertyKey: string }>>;
+
+  // 实体销毁时调用
+  clearReferencesTo(entityId: number): void {
+    const records = this._references.get(entityId);
+    if (records) {
+      for (const record of records) {
+        const component = record.component.deref();
+        if (component) {
+          // 将组件的引用属性设为 null
+          (component as any)[record.propertyKey] = null;
+        }
+      }
+      this._references.delete(entityId);
+    }
+  }
+}
+```
+
+#### 性能考虑
+
+`@EntityRef` 会带来一些性能开销:
+
+- **写入开销**: 每次设置引用时需要更新 ReferenceTracker
+- **内存开销**: ReferenceTracker 需要维护引用映射表
+- **销毁开销**: 实体销毁时需要遍历所有引用并清理
+
+对于大多数场景,这些开销是可以接受的。但如果有**大量实体和频繁的引用变更**,存储ID可能更高效。
+
+#### 最佳实践
+
+```typescript
+// 推荐：适合使用 @EntityRef 的场景 - 父子关系
+@ECSComponent('Transform')
+class Transform extends Component {
+  @EntityRef()
+  parent: Entity | null = null;
+
+  position: { x: number, y: number } = { x: 0, y: 0 };
+
+  // 可以直接访问父实体的组件
+  getWorldPosition(): { x: number, y: number } {
+    if (!this.parent) {
+      return { ...this.position };
+    }
+
+    const parentTransform = this.parent.getComponent(Transform);
+    if (parentTransform) {
+      const parentPos = parentTransform.getWorldPosition();
+      return {
+        x: parentPos.x + this.position.x,
+        y: parentPos.y + this.position.y
+      };
+    }
+
+    return { ...this.position };
+  }
+}
+
+// 不推荐：不适合使用 @EntityRef 的场景 - 大量动态目标
+@ECSComponent('AITarget')
+class AITarget extends Component {
+  @EntityRef()
+  target: Entity | null = null; // 如果目标频繁变化，用ID更好
+
+  updateCooldown: number = 0;
+}
+
+// 推荐：这种场景用ID更好
+@ECSComponent('AITarget')
+class AITargetBetter extends Component {
+  targetId: number | null = null; // 存储ID
+  updateCooldown: number = 0;
+}
+```
+
+#### 调试支持
+
+ReferenceTracker 提供了调试接口:
+
+```typescript
+// 查看某个实体被哪些组件引用
+const references = scene.referenceTracker.getReferencesTo(entity.id);
+console.log(`实体 ${entity.name} 被 ${references.length} 个组件引用`);
+
+// 获取完整的调试信息
+const debugInfo = scene.referenceTracker.getDebugInfo();
+console.log(debugInfo);
+```
+
+#### 总结
+
+- **推荐做法**: 大部分情况使用存储ID + System查找的方式
+- **EntityRef 适用场景**: 父子关系、复杂关联、组件内需要直接访问引用实体的场景
+- **核心优势**: 自动清理、防止悬空引用、代码更简洁
+- **注意事项**: 有性能开销,不适合大量动态引用的场景
+
 组件是 ECS 架构的数据载体，正确设计组件能让你的游戏代码更模块化、可维护和高性能。

docs/guide/entity-query.md

@@ -0,0 +1,501 @@
+# 实体查询系统
+
+实体查询是 ECS 架构的核心功能之一。本指南将介绍如何使用 Matcher 和 QuerySystem 来查询和筛选实体。
+
+## 核心概念
+
+### Matcher - 查询条件描述符
+
+Matcher 是一个链式 API,用于描述实体查询条件。它本身不执行查询,而是作为条件传递给 EntitySystem 或 QuerySystem。
+
+### QuerySystem - 查询执行引擎
+
+QuerySystem 负责实际执行查询,内部使用响应式查询机制自动优化性能。
+
+## 在 EntitySystem 中使用 Matcher
+
+这是最常见的使用方式。EntitySystem 通过 Matcher 自动筛选和处理符合条件的实体。
+
+### 基础用法
+
+```typescript
+import { EntitySystem, Matcher, Entity, Component } from '@esengine/ecs-framework';
+
+class PositionComponent extends Component {
+    public x: number = 0;
+    public y: number = 0;
+}
+
+class VelocityComponent extends Component {
+    public vx: number = 0;
+    public vy: number = 0;
+}
+
+class MovementSystem extends EntitySystem {
+    constructor() {
+        // 方式1: 使用 Matcher.empty().all()
+        super(Matcher.empty().all(PositionComponent, VelocityComponent));
+
+        // 方式2: 直接使用 Matcher.all() (等价)
+        // super(Matcher.all(PositionComponent, VelocityComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        for (const entity of entities) {
+            const pos = entity.getComponent(PositionComponent)!;
+            const vel = entity.getComponent(VelocityComponent)!;
+
+            pos.x += vel.vx;
+            pos.y += vel.vy;
+        }
+    }
+}
+
+// 添加到场景
+scene.addEntityProcessor(new MovementSystem());
+```
+
+### Matcher 链式 API
+
+#### all() - 必须包含所有组件
+
+```typescript
+class HealthSystem extends EntitySystem {
+    constructor() {
+        // 实体必须同时拥有 Health 和 Position 组件
+        super(Matcher.empty().all(HealthComponent, PositionComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理同时拥有两个组件的实体
+    }
+}
+```
+
+#### any() - 至少包含一个组件
+
+```typescript
+class DamageableSystem extends EntitySystem {
+    constructor() {
+        // 实体至少拥有 Health 或 Shield 其中之一
+        super(Matcher.any(HealthComponent, ShieldComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 处理拥有生命值或护盾的实体
+    }
+}
+```
+
+#### none() - 不能包含指定组件
+
+```typescript
+class AliveEntitySystem extends EntitySystem {
+    constructor() {
+        // 实体不能拥有 DeadTag 组件
+        super(Matcher.all(HealthComponent).none(DeadTag));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理活着的实体
+    }
+}
+```
+
+#### 组合条件
+
+```typescript
+class CombatSystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(PositionComponent, HealthComponent)  // 必须有位置和生命
+                .any(WeaponComponent, MagicComponent)      // 至少有武器或魔法
+                .none(DeadTag, FrozenTag)                  // 不能是死亡或冰冻状态
+        );
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 处理可以战斗的活着的实体
+    }
+}
+```
+
+### 按标签查询
+
+```typescript
+class PlayerSystem extends EntitySystem {
+    constructor() {
+        // 查询特定标签的实体
+        super(Matcher.empty().withTag(Tags.PLAYER));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理玩家实体
+    }
+}
+```
+
+### 按名称查询
+
+```typescript
+class BossSystem extends EntitySystem {
+    constructor() {
+        // 查询特定名称的实体
+        super(Matcher.empty().withName('Boss'));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理名为 'Boss' 的实体
+    }
+}
+```
+
+## 直接使用 QuerySystem
+
+如果不需要创建系统,可以直接使用 Scene 的 querySystem 进行查询。
+
+### 基础查询方法
+
+```typescript
+// 获取场景的查询系统
+const querySystem = scene.querySystem;
+
+// 查询拥有所有指定组件的实体
+const result1 = querySystem.queryAll(PositionComponent, VelocityComponent);
+console.log(`找到 ${result1.count} 个移动实体`);
+console.log(`查询耗时: ${result1.executionTime.toFixed(2)}ms`);
+
+// 查询拥有任意指定组件的实体
+const result2 = querySystem.queryAny(WeaponComponent, MagicComponent);
+console.log(`找到 ${result2.count} 个战斗单位`);
+
+// 查询不包含指定组件的实体
+const result3 = querySystem.queryNone(DeadTag);
+console.log(`找到 ${result3.count} 个活着的实体`);
+```
+
+### 按标签查询
+
+```typescript
+const playerResult = querySystem.queryByTag(Tags.PLAYER);
+for (const player of playerResult.entities) {
+    console.log('玩家:', player.name);
+}
+```
+
+### 按名称查询
+
+```typescript
+const bossResult = querySystem.queryByName('Boss');
+if (bossResult.count > 0) {
+    const boss = bossResult.entities[0];
+    console.log('找到Boss:', boss);
+}
+```
+
+### 按单个组件查询
+
+```typescript
+const healthResult = querySystem.queryByComponent(HealthComponent);
+console.log(`有 ${healthResult.count} 个实体拥有生命值`);
+```
+
+## 性能优化
+
+### 自动缓存
+
+QuerySystem 内部使用响应式查询自动缓存结果,相同的查询条件会直接使用缓存:
+
+```typescript
+// 第一次查询,执行实际查询
+const result1 = querySystem.queryAll(PositionComponent);
+console.log('fromCache:', result1.fromCache); // false
+
+// 第二次相同查询,使用缓存
+const result2 = querySystem.queryAll(PositionComponent);
+console.log('fromCache:', result2.fromCache); // true
+```
+
+### 实体变化自动更新
+
+当实体添加/移除组件时,查询缓存会自动更新:
+
+```typescript
+// 查询拥有武器的实体
+const before = querySystem.queryAll(WeaponComponent);
+console.log('之前:', before.count); // 假设为 5
+
+// 给实体添加武器
+const enemy = scene.createEntity('Enemy');
+enemy.addComponent(new WeaponComponent());
+
+// 再次查询,自动包含新实体
+const after = querySystem.queryAll(WeaponComponent);
+console.log('之后:', after.count); // 现在是 6
+```
+
+### 查询性能统计
+
+```typescript
+const stats = querySystem.getStats();
+console.log('总查询次数:', stats.queryStats.totalQueries);
+console.log('缓存命中率:', stats.queryStats.cacheHitRate);
+console.log('缓存大小:', stats.cacheStats.size);
+```
+
+## 实际应用场景
+
+### 场景1: 物理系统
+
+```typescript
+class PhysicsSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(TransformComponent, RigidbodyComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        for (const entity of entities) {
+            const transform = entity.getComponent(TransformComponent)!;
+            const rigidbody = entity.getComponent(RigidbodyComponent)!;
+
+            // 应用重力
+            rigidbody.velocity.y -= 9.8 * Time.deltaTime;
+
+            // 更新位置
+            transform.position.x += rigidbody.velocity.x * Time.deltaTime;
+            transform.position.y += rigidbody.velocity.y * Time.deltaTime;
+        }
+    }
+}
+```
+
+### 场景2: 渲染系统
+
+```typescript
+class RenderSystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(TransformComponent, SpriteComponent)
+                .none(InvisibleTag)  // 排除不可见实体
+        );
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 按 z-order 排序
+        const sorted = entities.slice().sort((a, b) => {
+            const zA = a.getComponent(TransformComponent)!.z;
+            const zB = b.getComponent(TransformComponent)!.z;
+            return zA - zB;
+        });
+
+        // 渲染实体
+        for (const entity of sorted) {
+            const transform = entity.getComponent(TransformComponent)!;
+            const sprite = entity.getComponent(SpriteComponent)!;
+
+            renderer.drawSprite(sprite.texture, transform.position);
+        }
+    }
+}
+```
+
+### 场景3: 碰撞检测
+
+```typescript
+class CollisionSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(TransformComponent, ColliderComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 简单的 O(n²) 碰撞检测
+        for (let i = 0; i < entities.length; i++) {
+            for (let j = i + 1; j < entities.length; j++) {
+                this.checkCollision(entities[i], entities[j]);
+            }
+        }
+    }
+
+    private checkCollision(a: Entity, b: Entity): void {
+        const transA = a.getComponent(TransformComponent)!;
+        const transB = b.getComponent(TransformComponent)!;
+        const colliderA = a.getComponent(ColliderComponent)!;
+        const colliderB = b.getComponent(ColliderComponent)!;
+
+        if (this.isOverlapping(transA, colliderA, transB, colliderB)) {
+            // 触发碰撞事件
+            scene.eventSystem.emit('collision', { entityA: a, entityB: b });
+        }
+    }
+
+    private isOverlapping(...args: any[]): boolean {
+        // 碰撞检测逻辑
+        return false;
+    }
+}
+```
+
+### 场景4: 一次性查询
+
+```typescript
+// 在系统外部执行一次性查询
+class GameManager {
+    private scene: Scene;
+
+    public countEnemies(): number {
+        const result = this.scene.querySystem.queryByTag(Tags.ENEMY);
+        return result.count;
+    }
+
+    public findNearestEnemy(playerPos: Vector2): Entity | null {
+        const enemies = this.scene.querySystem.queryByTag(Tags.ENEMY);
+
+        let nearest: Entity | null = null;
+        let minDistance = Infinity;
+
+        for (const enemy of enemies.entities) {
+            const transform = enemy.getComponent(TransformComponent);
+            if (!transform) continue;
+
+            const distance = Vector2.distance(playerPos, transform.position);
+            if (distance < minDistance) {
+                minDistance = distance;
+                nearest = enemy;
+            }
+        }
+
+        return nearest;
+    }
+}
+```
+
+## 最佳实践
+
+### 1. 优先使用 EntitySystem
+
+```typescript
+// 推荐: 使用 EntitySystem
+class GoodSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(HealthComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 自动获得符合条件的实体,每帧自动更新
+    }
+}
+
+// 不推荐: 在 update 中手动查询
+class BadSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty());
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 每帧手动查询,浪费性能
+        const result = this.scene!.querySystem.queryAll(HealthComponent);
+        for (const entity of result.entities) {
+            // ...
+        }
+    }
+}
+```
+
+### 2. 合理使用 none() 排除条件
+
+```typescript
+// 排除已死亡的敌人
+class EnemyAISystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(EnemyTag, AIComponent)
+                .none(DeadTag)  // 不处理死亡的敌人
+        );
+    }
+}
+```
+
+### 3. 使用标签优化查询
+
+```typescript
+// 不好: 查询所有实体再过滤
+const allEntities = scene.querySystem.getAllEntities();
+const players = allEntities.filter(e => e.hasComponent(PlayerTag));
+
+// 好: 直接按标签查询
+const players = scene.querySystem.queryByTag(Tags.PLAYER).entities;
+```
+
+### 4. 避免过于复杂的查询条件
+
+```typescript
+// 不推荐: 过于复杂
+super(
+    Matcher.empty()
+        .all(A, B, C, D)
+        .any(E, F, G)
+        .none(H, I, J)
+);
+
+// 推荐: 拆分成多个简单系统
+class SystemAB extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(A, B));
+    }
+}
+
+class SystemCD extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(C, D));
+    }
+}
+```
+
+## 注意事项
+
+### 1. 查询结果是只读的
+
+```typescript
+const result = querySystem.queryAll(PositionComponent);
+
+// 不要修改返回的数组
+result.entities.push(someEntity);  // 错误!
+
+// 如果需要修改,先复制
+const mutableArray = [...result.entities];
+mutableArray.push(someEntity);  // 正确
+```
+
+### 2. 组件添加/移除后的查询时机
+
+```typescript
+// 创建实体并添加组件
+const entity = scene.createEntity('Player');
+entity.addComponent(new PositionComponent());
+
+// 立即查询可能获取到新实体
+const result = scene.querySystem.queryAll(PositionComponent);
+// result.entities 包含新创建的实体
+```
+
+### 3. Matcher 是不可变的
+
+```typescript
+const matcher = Matcher.empty().all(PositionComponent);
+
+// 链式调用返回新的 Matcher 实例
+const matcher2 = matcher.any(VelocityComponent);
+
+// matcher 本身不变
+console.log(matcher === matcher2); // false
+```
+
+## 相关 API
+
+- [Matcher](../api/classes/Matcher.md) - 查询条件描述符 API 参考
+- [QuerySystem](../api/classes/QuerySystem.md) - 查询系统 API 参考
+- [EntitySystem](../api/classes/EntitySystem.md) - 实体系统 API 参考
+- [Entity](../api/classes/Entity.md) - 实体 API 参考

docs/guide/getting-started.md

@@ -314,8 +314,8 @@ import { Core, WorldManager } from '@esengine/ecs-framework';
 // 初始化Core
 Core.create({ debug: true });
 
-// 创建世界管理器（手动管理）
-const worldManager = new WorldManager();
+// 从服务容器获取 WorldManager（Core 已自动创建并注册）
+const worldManager = Core.services.resolve(WorldManager);
 
 // 创建多个独立的游戏世界
 const room1 = worldManager.createWorld('room_001');

docs/guide/index.md

@@ -29,4 +29,12 @@
 掌握分级日志系统，用于调试、监控和错误追踪。
 
 ### [平台适配器 (Platform Adapter)](./platform-adapter.md)
-了解如何为不同平台实现和注册平台适配器，支持浏览器、小游戏、Node.js等环境。
+了解如何为不同平台实现和注册平台适配器，支持浏览器、小游戏、Node.js等环境。
+
+## 高级特性
+
+### [服务容器 (Service Container)](./service-container.md)
+掌握依赖注入和服务管理，实现松耦合的架构设计。
+
+### [插件系统 (Plugin System)](./plugin-system.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/plugin-system.md

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

docs/guide/scene-manager.md

@@ -0,0 +1,675 @@
+# SceneManager
+
+SceneManager 是 ECS Framework 提供的轻量级场景管理器，适用于 95% 的游戏应用。它提供简单直观的 API，支持场景切换和延迟加载。
+
+## 适用场景
+
+SceneManager 适合以下场景：
+- 单人游戏
+- 简单多人游戏
+- 移动游戏
+- 需要场景切换的游戏（菜单、游戏、暂停等）
+- 不需要多 World 隔离的项目
+
+## 特点
+
+- 轻量级，零额外开销
+- 简单直观的 API
+- 支持延迟场景切换（避免在当前帧中途切换）
+- 自动管理 ECS 流式 API
+- 自动处理场景生命周期
+- 集成在 Core 中，自动更新
+
+## 基本使用
+
+### 推荐方式：使用 Core 的静态方法
+
+这是最简单和推荐的方式，适合大多数应用：
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// 1. 初始化 Core
+Core.create({ debug: true });
+
+// 2. 创建并设置场景
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 添加系统
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+
+    // 创建初始实体
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Health(100));
+  }
+
+  public onStart(): void {
+    console.log("游戏场景已启动");
+  }
+}
+
+// 3. 设置场景
+Core.setScene(new GameScene());
+
+// 4. 游戏循环（Core.update 会自动更新场景）
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // 自动更新所有服务和场景
+}
+
+// Laya 引擎集成
+Laya.timer.frameLoop(1, this, () => {
+  const deltaTime = Laya.timer.delta / 1000;
+  Core.update(deltaTime);
+});
+
+// Cocos Creator 集成
+update(deltaTime: number) {
+  Core.update(deltaTime);
+}
+```
+
+### 高级方式：直接使用 SceneManager
+
+如果需要更多控制，可以直接使用 SceneManager：
+
+```typescript
+import { Core, SceneManager, Scene } from '@esengine/ecs-framework';
+
+// 初始化 Core
+Core.create({ debug: true });
+
+// 获取 SceneManager（Core 已自动创建并注册）
+const sceneManager = Core.services.resolve(SceneManager);
+
+// 设置场景
+const gameScene = new GameScene();
+sceneManager.setScene(gameScene);
+
+// 游戏循环（仍然使用 Core.update）
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // Core会自动调用sceneManager.update()
+}
+```
+
+**重要**：无论使用哪种方式，游戏循环中都应该只调用 `Core.update()`，它会自动更新 SceneManager 和场景。不需要手动调用 `sceneManager.update()`。
+
+## 场景切换
+
+### 立即切换
+
+使用 `Core.setScene()` 或 `sceneManager.setScene()` 立即切换场景：
+
+```typescript
+// 方式1：使用 Core（推荐）
+Core.setScene(new MenuScene());
+
+// 方式2：使用 SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new MenuScene());
+```
+
+### 延迟切换
+
+使用 `Core.loadScene()` 或 `sceneManager.loadScene()` 延迟切换场景，场景会在下一帧切换：
+
+```typescript
+// 方式1：使用 Core（推荐）
+Core.loadScene(new GameOverScene());
+
+// 方式2：使用 SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.loadScene(new GameOverScene());
+```
+
+在 System 中切换场景时，应该使用延迟切换：
+
+```typescript
+class GameOverSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    const player = entities.find(e => e.name === 'Player');
+    const health = player?.getComponent(Health);
+
+    if (health && health.value <= 0) {
+      // 延迟切换到游戏结束场景（下一帧生效）
+      Core.loadScene(new GameOverScene());
+      // 当前帧继续执行，不会中断当前系统的处理
+    }
+  }
+}
+```
+
+### 完整的场景切换示例
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// 初始化
+Core.create({ debug: true });
+
+// 菜单场景
+class MenuScene extends Scene {
+  protected initialize(): void {
+    this.name = "MenuScene";
+
+    // 监听开始游戏事件
+    this.eventSystem.on('start_game', () => {
+      Core.loadScene(new GameScene());
+    });
+  }
+
+  public onStart(): void {
+    console.log("显示菜单界面");
+  }
+
+  public unload(): void {
+    console.log("菜单场景卸载");
+  }
+}
+
+// 游戏场景
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 创建游戏实体
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Health(100));
+
+    // 监听游戏结束事件
+    this.eventSystem.on('game_over', () => {
+      Core.loadScene(new GameOverScene());
+    });
+  }
+
+  public onStart(): void {
+    console.log("游戏开始");
+  }
+
+  public unload(): void {
+    console.log("游戏场景卸载");
+  }
+}
+
+// 游戏结束场景
+class GameOverScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameOverScene";
+
+    // 监听返回菜单事件
+    this.eventSystem.on('back_to_menu', () => {
+      Core.loadScene(new MenuScene());
+    });
+  }
+
+  public onStart(): void {
+    console.log("显示游戏结束界面");
+  }
+}
+
+// 开始游戏
+Core.setScene(new MenuScene());
+
+// 游戏循环
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // 自动更新场景
+}
+```
+
+## API 参考
+
+### Core 静态方法（推荐）
+
+#### Core.setScene()
+
+立即切换场景。
+
+```typescript
+public static setScene<T extends IScene>(scene: T): T
+```
+
+**参数**：
+- `scene` - 要设置的场景实例
+
+**返回**：
+- 返回设置的场景实例
+
+**示例**：
+```typescript
+const gameScene = Core.setScene(new GameScene());
+console.log(gameScene.name);
+```
+
+#### Core.loadScene()
+
+延迟加载场景（下一帧切换）。
+
+```typescript
+public static loadScene<T extends IScene>(scene: T): void
+```
+
+**参数**：
+- `scene` - 要加载的场景实例
+
+**示例**：
+```typescript
+Core.loadScene(new GameOverScene());
+```
+
+#### Core.scene
+
+获取当前活跃的场景。
+
+```typescript
+public static get scene(): IScene | null
+```
+
+**返回**：
+- 当前场景实例，如果没有场景则返回 null
+
+**示例**：
+```typescript
+const currentScene = Core.scene;
+if (currentScene) {
+  console.log(`当前场景: ${currentScene.name}`);
+}
+```
+
+#### Core.ecsAPI
+
+获取 ECS 流式 API。
+
+```typescript
+public static get ecsAPI(): ECSFluentAPI | null
+```
+
+**返回**：
+- ECS API 实例，如果当前没有场景则返回 null
+
+**示例**：
+```typescript
+const api = Core.ecsAPI;
+if (api) {
+  // 查询实体
+  const enemies = api.find(Enemy, Transform);
+
+  // 发射事件
+  api.emit('game:start', { level: 1 });
+}
+```
+
+### SceneManager 方法（高级）
+
+如果需要直接使用 SceneManager，可以通过服务容器获取：
+
+```typescript
+const sceneManager = Core.services.resolve(SceneManager);
+```
+
+#### setScene()
+
+立即切换场景。
+
+```typescript
+public setScene<T extends IScene>(scene: T): T
+```
+
+#### loadScene()
+
+延迟加载场景。
+
+```typescript
+public loadScene<T extends IScene>(scene: T): void
+```
+
+#### currentScene
+
+获取当前场景。
+
+```typescript
+public get currentScene(): IScene | null
+```
+
+#### api
+
+获取 ECS 流式 API。
+
+```typescript
+public get api(): ECSFluentAPI | null
+```
+
+#### hasScene
+
+检查是否有活跃场景。
+
+```typescript
+public get hasScene(): boolean
+```
+
+#### hasPendingScene
+
+检查是否有待切换的场景。
+
+```typescript
+public get hasPendingScene(): boolean
+```
+
+## 使用 ECS 流式 API
+
+通过 `Core.ecsAPI` 可以方便地访问场景的 ECS 功能：
+
+```typescript
+const api = Core.ecsAPI;
+if (!api) {
+  console.error('没有活跃场景');
+  return;
+}
+
+// 查询实体
+const players = api.find(Player, Transform);
+const enemies = api.find(Enemy, Health, Transform);
+
+// 发射事件
+api.emit('player:scored', { points: 100 });
+
+// 监听事件
+api.on('enemy:died', (data) => {
+  console.log('敌人死亡:', data);
+});
+```
+
+## 最佳实践
+
+### 1. 使用 Core 的静态方法
+
+```typescript
+// 推荐：使用 Core 的静态方法
+Core.setScene(new GameScene());
+Core.loadScene(new MenuScene());
+const currentScene = Core.scene;
+
+// 不推荐：除非有特殊需求，否则不需要直接使用 SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new GameScene());
+```
+
+### 2. 只调用 Core.update()
+
+```typescript
+// 正确：只调用 Core.update()
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // 自动更新所有服务和场景
+}
+
+// 错误：不要手动调用 sceneManager.update()
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);
+  sceneManager.update();  // 重复更新，会导致问题！
+}
+```
+
+### 3. 使用延迟切换避免问题
+
+在 System 中切换场景时，应该使用 `loadScene()` 而不是 `setScene()`：
+
+```typescript
+// 推荐：延迟切换
+class HealthSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health);
+      if (health.value <= 0) {
+        Core.loadScene(new GameOverScene());
+        // 当前帧继续处理其他实体
+      }
+    }
+  }
+}
+
+// 不推荐：立即切换可能导致问题
+class HealthSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health);
+      if (health.value <= 0) {
+        Core.setScene(new GameOverScene());
+        // 场景立即切换，当前帧的其他实体可能无法正常处理
+      }
+    }
+  }
+}
+```
+
+### 4. 场景职责分离
+
+每个场景应该只负责一个特定的游戏状态：
+
+```typescript
+// 好的设计 - 职责清晰
+class MenuScene extends Scene {
+  // 只处理菜单相关逻辑
+}
+
+class GameScene extends Scene {
+  // 只处理游戏玩法逻辑
+}
+
+class PauseScene extends Scene {
+  // 只处理暂停界面逻辑
+}
+
+// 避免的设计 - 职责混乱
+class MegaScene extends Scene {
+  // 包含菜单、游戏、暂停等所有逻辑
+}
+```
+
+### 5. 资源管理
+
+在场景的 `unload()` 方法中清理资源：
+
+```typescript
+class GameScene extends Scene {
+  private textures: Map<string, any> = new Map();
+  private sounds: Map<string, any> = new Map();
+
+  protected initialize(): void {
+    this.loadResources();
+  }
+
+  private loadResources(): void {
+    this.textures.set('player', loadTexture('player.png'));
+    this.sounds.set('bgm', loadSound('bgm.mp3'));
+  }
+
+  public unload(): void {
+    // 清理资源
+    this.textures.clear();
+    this.sounds.clear();
+    console.log('场景资源已清理');
+  }
+}
+```
+
+### 6. 事件驱动的场景切换
+
+使用事件系统来触发场景切换，保持代码解耦：
+
+```typescript
+class GameScene extends Scene {
+  protected initialize(): void {
+    // 监听场景切换事件
+    this.eventSystem.on('goto:menu', () => {
+      Core.loadScene(new MenuScene());
+    });
+
+    this.eventSystem.on('goto:gameover', (data) => {
+      Core.loadScene(new GameOverScene());
+    });
+  }
+}
+
+// 在 System 中触发事件
+class GameLogicSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    if (levelComplete) {
+      this.scene.eventSystem.emitSync('goto:gameover', {
+        score: 1000,
+        level: 5
+      });
+    }
+  }
+}
+```
+
+## 架构层次
+
+SceneManager 在 ECS Framework 中的位置：
+
+```
+Core (全局服务)
+  └── SceneManager (场景管理，自动更新)
+      └── Scene (当前场景)
+          ├── EntitySystem (系统)
+          ├── Entity (实体)
+          └── Component (组件)
+```
+
+## 与 WorldManager 的对比
+
+| 特性 | SceneManager | WorldManager |
+|------|--------------|--------------|
+| 适用场景 | 95% 的游戏应用 | 高级多世界隔离场景 |
+| 复杂度 | 简单 | 复杂 |
+| 场景数量 | 单场景（可切换） | 多 World，每个 World 多场景 |
+| 性能开销 | 最小 | 较高 |
+| 使用方式 | `Core.setScene()` | `worldManager.createWorld()` |
+
+**何时使用 SceneManager**：
+- 单人游戏
+- 简单的多人游戏
+- 移动游戏
+- 场景之间需要切换但不需要同时运行
+
+**何时使用 WorldManager**：
+- MMO 游戏服务器（每个房间一个 World）
+- 游戏大厅系统（每个游戏房间完全隔离）
+- 需要运行多个完全独立的游戏实例
+
+## 完整示例
+
+```typescript
+import { Core, Scene, EntitySystem, Entity, Matcher } from '@esengine/ecs-framework';
+
+// 定义组件
+class Transform {
+  constructor(public x: number, public y: number) {}
+}
+
+class Velocity {
+  constructor(public vx: number, public vy: number) {}
+}
+
+class Health {
+  constructor(public value: number) {}
+}
+
+// 定义系统
+class MovementSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Transform, Velocity));
+  }
+
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const transform = entity.getComponent(Transform);
+      const velocity = entity.getComponent(Velocity);
+
+      if (transform && velocity) {
+        transform.x += velocity.vx;
+        transform.y += velocity.vy;
+      }
+    }
+  }
+}
+
+// 定义场景
+class MenuScene extends Scene {
+  protected initialize(): void {
+    this.name = "MenuScene";
+    console.log("菜单场景初始化");
+  }
+
+  public onStart(): void {
+    console.log("菜单场景启动");
+  }
+}
+
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 添加系统
+    this.addSystem(new MovementSystem());
+
+    // 创建玩家
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Velocity(0, 0));
+    player.addComponent(new Health(100));
+
+    // 创建敌人
+    for (let i = 0; i < 5; i++) {
+      const enemy = this.createEntity(`Enemy_${i}`);
+      enemy.addComponent(new Transform(
+        Math.random() * 800,
+        Math.random() * 600
+      ));
+      enemy.addComponent(new Velocity(
+        Math.random() * 100 - 50,
+        Math.random() * 100 - 50
+      ));
+      enemy.addComponent(new Health(50));
+    }
+  }
+
+  public onStart(): void {
+    console.log('游戏场景启动');
+  }
+
+  public unload(): void {
+    console.log('游戏场景卸载');
+  }
+}
+
+// 初始化
+Core.create({ debug: true });
+
+// 设置初始场景
+Core.setScene(new MenuScene());
+
+// 游戏循环
+let lastTime = 0;
+function gameLoop(currentTime: number) {
+  const deltaTime = (currentTime - lastTime) / 1000;
+  lastTime = currentTime;
+
+  // 只需要调用 Core.update，它会自动更新场景
+  Core.update(deltaTime);
+
+  requestAnimationFrame(gameLoop);
+}
+
+requestAnimationFrame(gameLoop);
+
+// 切换到游戏场景
+setTimeout(() => {
+  Core.loadScene(new GameScene());
+}, 3000);
+```
+
+SceneManager 为大多数游戏提供了简单而强大的场景管理能力。通过 Core 的静态方法，你可以轻松地管理场景切换。如果你需要更高级的多世界隔离功能，请参考 [WorldManager](./world-manager.md) 文档。

docs/guide/scene.md

@@ -11,6 +11,22 @@
 - 事件系统支持
 - 性能监控和调试信息
 
+## 场景管理方式
+
+ECS Framework 提供了两种场景管理方式：
+
+1. **[SceneManager](./scene-manager.md)** - 适用于 95% 的游戏应用
+   - 单人游戏、简单多人游戏、移动游戏
+   - 轻量级，简单直观的 API
+   - 支持场景切换
+
+2. **[WorldManager](./world-manager.md)** - 适用于高级多世界隔离场景
+   - MMO 游戏服务器、游戏房间系统
+   - 多 World 管理，每个 World 可包含多个场景
+   - 完全隔离的独立环境
+
+本文档重点介绍 Scene 类本身的使用方法。关于场景管理器的详细信息，请查看对应的文档。
+
 ## 创建场景
 
 ### 继承 Scene 类
@@ -106,6 +122,13 @@ const scene = new ExampleScene();
 // 场景的 initialize(), begin(), update(), end() 由框架自动调用
 ```
 
+**生命周期方法**：
+
+1. `initialize()` - 场景初始化，设置系统和初始实体
+2. `begin()` / `onStart()` - 场景开始运行
+3. `update()` - 每帧更新（由场景管理器调用）
+4. `end()` / `unload()` - 场景卸载，清理资源
+
 ## 实体管理
 
 ### 创建实体
@@ -247,15 +270,42 @@ class EventScene extends Scene {
   }
 
   public triggerGameEvent(): void {
-    // 发送事件
+    // 发送事件（同步）
     this.eventSystem.emitSync('custom_event', {
       message: "这是自定义事件",
       timestamp: Date.now()
     });
+
+    // 发送事件（异步）
+    this.eventSystem.emit('async_event', {
+      data: "异步事件数据"
+    });
   }
 }
 ```
 
+### 事件系统 API
+
+```typescript
+// 监听事件
+this.eventSystem.on('event_name', callback);
+
+// 监听一次（自动取消订阅）
+this.eventSystem.once('event_name', callback);
+
+// 取消监听
+this.eventSystem.off('event_name', callback);
+
+// 同步发送事件
+this.eventSystem.emitSync('event_name', data);
+
+// 异步发送事件
+this.eventSystem.emit('event_name', data);
+
+// 清除所有事件监听
+this.eventSystem.clear();
+```
+
 ## 场景统计和调试
 
 ### 获取场景统计
@@ -287,176 +337,58 @@ class StatsScene extends Scene {
 }
 ```
 
-## 场景集成到框架
+## 组件查询
 
-ECS Framework 提供了灵活的场景管理架构，适用于不同规模的应用：
-
-### 1. 使用 SceneManager（推荐大多数应用）
-
-适用于 95% 的游戏应用（单人游戏、简单多人游戏、移动游戏等）：
+Scene 提供了强大的组件查询系统：
 
 ```typescript
-import { Core, SceneManager } from '@esengine/ecs-framework';
-
-// 初始化Core（全局服务）
-Core.create({ debug: true });
-
-// 创建场景管理器
-const sceneManager = new SceneManager();
-
-// 创建游戏场景
-class GameScene extends Scene {
+class QueryScene extends Scene {
   protected initialize(): void {
-    this.name = "GameScene";
-    this.addSystem(new MovementSystem());
-    this.addSystem(new RenderSystem());
-  }
-}
-
-// 设置场景
-const gameScene = new GameScene();
-sceneManager.setScene(gameScene);
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 更新全局服务
-  sceneManager.update();        // 更新当前场景
-}
-```
-
-### 2. 场景切换
-
-SceneManager 支持流畅的场景切换：
-
-```typescript
-// 立即切换场景
-const menuScene = new MenuScene();
-sceneManager.setScene(menuScene);
-
-// 延迟切换场景（在下一帧切换）
-const gameScene = new GameScene();
-sceneManager.startSceneTransition(gameScene, false);
-
-// 访问当前场景
-const currentScene = sceneManager.currentScene;
-
-// 访问 ECS API
-const ecsAPI = sceneManager.ecsAPI;
-const entity = ecsAPI?.createEntity('player');
-```
-
-### 3. 使用 WorldManager（高级用例）
-
-适用于需要完全隔离的多世界应用（MMO服务器、游戏房间系统等）：
-
-```typescript
-import { Core, WorldManager } from '@esengine/ecs-framework';
-
-// 初始化Core（全局服务）
-Core.create({ debug: true });
-
-// 创建世界管理器
-const worldManager = new WorldManager();
-
-// 创建多个独立的游戏世界
-const gameWorld = worldManager.createWorld('game', {
-  name: 'MainGame',
-  maxScenes: 5
-});
-
-// 在World中创建场景
-const menuScene = gameWorld.createScene('menu', new MenuScene());
-const gameScene = gameWorld.createScene('game', new GameScene());
-
-// 激活场景
-gameWorld.setSceneActive('menu', true);
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 更新全局服务
-  worldManager.updateAll();    // 更新所有世界
-}
-```
-
-## 多场景管理
-
-在World中可以管理多个场景，通过激活/停用来切换：
-
-```typescript
-class GameWorld extends World {
-  private menuScene: Scene;
-  private gameScene: Scene;
-  private gameOverScene: Scene;
-
-  public initialize(): void {
-    // 创建多个场景
-    this.menuScene = this.createScene('menu', new MenuScene());
-    this.gameScene = this.createScene('game', new GameScene());
-    this.gameOverScene = this.createScene('gameover', new GameOverScene());
-
-    // 设置初始场景
-    this.showMenu();
+    // 创建一些实体
+    for (let i = 0; i < 10; i++) {
+      const entity = this.createEntity(`Entity_${i}`);
+      entity.addComponent(new Transform(i * 10, 0));
+      entity.addComponent(new Velocity(1, 0));
+      if (i % 2 === 0) {
+        entity.addComponent(new Renderer());
+      }
+    }
   }
 
-  public showMenu(): void {
-    this.deactivateAllScenes();
-    this.setSceneActive('menu', true);
-  }
+  public queryEntities(): void {
+    // 通过 QuerySystem 查询
+    const entities = this.querySystem.query([Transform, Velocity]);
+    console.log(`找到 ${entities.length} 个有 Transform 和 Velocity 的实体`);
 
-  public startGame(): void {
-    this.deactivateAllScenes();
-    this.setSceneActive('game', true);
-  }
-
-  public showGameOver(): void {
-    this.deactivateAllScenes();
-    this.setSceneActive('gameover', true);
-  }
-
-  private deactivateAllScenes(): void {
-    this.setSceneActive('menu', false);
-    this.setSceneActive('game', false);
-    this.setSceneActive('gameover', false);
+    // 使用 ECS 流式 API（如果通过 SceneManager）
+    // const api = sceneManager.api;
+    // const entities = api?.find(Transform, Velocity);
   }
 }
 ```
 
-## 架构层次
+## 性能监控
 
-ECS Framework 的架构层次清晰，职责分明：
+Scene 内置了性能监控功能：
 
 ```typescript
-// 架构层次：
-// Core (全局服务) → SceneManager (场景管理) → Scene → EntitySystem → Entity → Component
-// 或
-// Core (全局服务) → WorldManager (世界管理) → World → Scene → EntitySystem → Entity → Component
+class PerformanceScene extends Scene {
+  public showPerformance(): void {
+    // 获取性能数据
+    const perfData = this.performanceMonitor?.getPerformanceData();
+    if (perfData) {
+      console.log('FPS:', perfData.fps);
+      console.log('帧时间:', perfData.frameTime);
+      console.log('实体更新时间:', perfData.entityUpdateTime);
+      console.log('系统更新时间:', perfData.systemUpdateTime);
+    }
 
-// 1. 推荐：使用 SceneManager 管理单场景/场景切换
-import { Core, SceneManager } from '@esengine/ecs-framework';
-
-Core.create({ debug: true });
-const sceneManager = new SceneManager();
-sceneManager.setScene(new GameScene());
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 全局服务
-  sceneManager.update();        // 场景更新
-}
-
-// 2. 高级：使用 WorldManager 管理多世界
-import { Core, WorldManager } from '@esengine/ecs-framework';
-
-Core.create({ debug: true });
-const worldManager = new WorldManager();
-const world = worldManager.createWorld('gameWorld');
-const scene = world.createScene('mainScene', new GameScene());
-world.setSceneActive('mainScene', true);
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 全局服务
-  worldManager.updateAll();    // 所有世界更新
+    // 获取性能报告
+    const report = this.performanceMonitor?.generateReport();
+    if (report) {
+      console.log('性能报告:', report);
+    }
+  }
 }
 ```
 
@@ -465,7 +397,7 @@ function gameLoop(deltaTime: number) {
 ### 1. 场景职责分离
 
 ```typescript
-// ✅ 好的场景设计 - 职责清晰
+// 好的场景设计 - 职责清晰
 class MenuScene extends Scene {
   // 只处理菜单相关逻辑
 }
@@ -478,7 +410,7 @@ class InventoryScene extends Scene {
   // 只处理物品栏逻辑
 }
 
-// ❌ 避免的场景设计 - 职责混乱
+// 避免的场景设计 - 职责混乱
 class MegaScene extends Scene {
   // 包含菜单、游戏、物品栏等所有逻辑
 }
@@ -525,12 +457,25 @@ class ResourceScene extends Scene {
 
   private loadResources(): void {
     // 加载场景所需资源
+    this.textures.set('player', this.loadTexture('player.png'));
+    this.sounds.set('bgm', this.loadSound('bgm.mp3'));
   }
 
   public unload(): void {
     // 清理资源
     this.textures.clear();
     this.sounds.clear();
+    console.log('场景资源已清理');
+  }
+
+  private loadTexture(path: string): any {
+    // 加载纹理
+    return null;
+  }
+
+  private loadSound(path: string): any {
+    // 加载音效
+    return null;
   }
 }
 ```
@@ -571,7 +516,146 @@ class EventHandlingScene extends Scene {
   private onPlayerInput(data: any): void {
     // 处理玩家输入
   }
+
+  public unload(): void {
+    // 清理事件监听
+    this.eventSystem.clear();
+  }
 }
 ```
 
-场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。
+### 5. 初始化顺序
+
+```typescript
+class ProperInitScene extends Scene {
+  protected initialize(): void {
+    // 1. 首先设置场景配置
+    this.name = "GameScene";
+
+    // 2. 然后添加系统（按依赖顺序）
+    this.addSystem(new InputSystem());
+    this.addSystem(new MovementSystem());
+    this.addSystem(new PhysicsSystem());
+    this.addSystem(new RenderSystem());
+
+    // 3. 最后创建实体
+    this.createEntities();
+
+    // 4. 设置事件监听
+    this.setupEvents();
+  }
+
+  private createEntities(): void {
+    // 创建实体
+  }
+
+  private setupEvents(): void {
+    // 设置事件监听
+  }
+}
+```
+
+## 完整示例
+
+```typescript
+import { Scene, EntitySystem, Entity, Matcher } from '@esengine/ecs-framework';
+
+// 定义组件
+class Transform {
+  constructor(public x: number, public y: number) {}
+}
+
+class Velocity {
+  constructor(public vx: number, public vy: number) {}
+}
+
+class Health {
+  constructor(public value: number) {}
+}
+
+// 定义系统
+class MovementSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Transform, Velocity));
+  }
+
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const transform = entity.getComponent(Transform);
+      const velocity = entity.getComponent(Velocity);
+
+      if (transform && velocity) {
+        transform.x += velocity.vx;
+        transform.y += velocity.vy;
+      }
+    }
+  }
+}
+
+// 定义场景
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 添加系统
+    this.addSystem(new MovementSystem());
+
+    // 创建玩家
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Velocity(0, 0));
+    player.addComponent(new Health(100));
+
+    // 创建敌人
+    for (let i = 0; i < 5; i++) {
+      const enemy = this.createEntity(`Enemy_${i}`);
+      enemy.addComponent(new Transform(
+        Math.random() * 800,
+        Math.random() * 600
+      ));
+      enemy.addComponent(new Velocity(
+        Math.random() * 100 - 50,
+        Math.random() * 100 - 50
+      ));
+      enemy.addComponent(new Health(50));
+    }
+
+    // 设置事件监听
+    this.eventSystem.on('player_died', () => {
+      console.log('玩家死亡！');
+    });
+  }
+
+  public onStart(): void {
+    console.log('游戏场景启动');
+  }
+
+  public unload(): void {
+    console.log('游戏场景卸载');
+    this.eventSystem.clear();
+  }
+}
+
+// 使用场景
+// 方式1：通过 SceneManager（推荐）
+import { Core, SceneManager } from '@esengine/ecs-framework';
+
+Core.create({ debug: true });
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new GameScene());
+
+// 方式2：通过 WorldManager（高级用例）
+import { WorldManager } from '@esengine/ecs-framework';
+
+const worldManager = Core.services.resolve(WorldManager);
+const world = worldManager.createWorld('game');
+world.createScene('main', new GameScene());
+world.setSceneActive('main', true);
+```
+
+## 下一步
+
+- 了解 [SceneManager](./scene-manager.md) - 适用于大多数游戏的简单场景管理
+- 了解 [WorldManager](./world-manager.md) - 适用于需要多世界隔离的高级场景
+
+场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。

docs/guide/serialization.md

@@ -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);
 ```
 
@@ -285,7 +298,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 +565,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 +803,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

@@ -0,0 +1,589 @@
+# 服务容器
+
+服务容器（ServiceContainer）是 ECS Framework 的依赖注入容器，负责管理框架中所有服务的注册、解析和生命周期。通过服务容器，你可以实现松耦合的架构设计，提高代码的可测试性和可维护性。
+
+## 概述
+
+### 什么是服务容器
+
+服务容器是一个轻量级的依赖注入（DI）容器，它提供了：
+
+- **服务注册**: 将服务类型注册到容器中
+- **服务解析**: 从容器中获取服务实例
+- **生命周期管理**: 自动管理服务实例的创建和销毁
+- **依赖注入**: 自动解析服务之间的依赖关系
+
+### 核心概念
+
+#### 服务（Service）
+
+服务是实现了 `IService` 接口的类，必须提供 `dispose()` 方法用于资源清理：
+
+```typescript
+import { IService } from '@esengine/ecs-framework';
+
+class MyService implements IService {
+    constructor() {
+        // 初始化逻辑
+    }
+
+    dispose(): void {
+        // 清理资源
+    }
+}
+```
+
+#### 生命周期
+
+服务容器支持两种生命周期：
+
+- **Singleton（单例）**: 整个应用程序生命周期内只有一个实例，所有解析请求返回同一个实例
+- **Transient（瞬时）**: 每次解析都创建新的实例
+
+## 基础使用
+
+### 访问服务容器
+
+Core 类内置了服务容器，可以通过 `Core.services` 访问：
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+
+// 初始化Core
+Core.create({ debug: true });
+
+// 访问服务容器
+const container = Core.services;
+```
+
+### 注册服务
+
+#### 注册单例服务
+
+单例服务在首次解析时创建，之后所有解析请求都返回同一个实例：
+
+```typescript
+class DataService implements IService {
+    private data: Map<string, any> = new Map();
+
+    getData(key: string) {
+        return this.data.get(key);
+    }
+
+    setData(key: string, value: any) {
+        this.data.set(key, value);
+    }
+
+    dispose(): void {
+        this.data.clear();
+    }
+}
+
+// 注册单例服务
+Core.services.registerSingleton(DataService);
+```
+
+#### 注册瞬时服务
+
+瞬时服务每次解析都创建新实例，适用于无状态或短生命周期的服务：
+
+```typescript
+class CommandService implements IService {
+    execute(command: string) {
+        console.log(`Executing: ${command}`);
+    }
+
+    dispose(): void {
+        // 清理资源
+    }
+}
+
+// 注册瞬时服务
+Core.services.registerTransient(CommandService);
+```
+
+#### 注册服务实例
+
+直接注册已创建的实例，自动视为单例：
+
+```typescript
+const config = new ConfigService();
+config.load('./config.json');
+
+// 注册实例
+Core.services.registerInstance(ConfigService, config);
+```
+
+#### 使用工厂函数注册
+
+工厂函数允许你在创建服务时执行自定义逻辑：
+
+```typescript
+Core.services.registerSingleton(LoggerService, (container) => {
+    const logger = new LoggerService();
+    logger.setLevel('debug');
+    return logger;
+});
+```
+
+### 解析服务
+
+#### resolve 方法
+
+解析服务实例，如果服务未注册会抛出异常：
+
+```typescript
+// 解析服务
+const dataService = Core.services.resolve(DataService);
+dataService.setData('player', { name: 'Alice', score: 100 });
+
+// 单例服务，多次解析返回同一个实例
+const same = Core.services.resolve(DataService);
+console.log(same === dataService); // true
+```
+
+#### tryResolve 方法
+
+尝试解析服务，如果未注册返回 null 而不抛出异常：
+
+```typescript
+const optional = Core.services.tryResolve(OptionalService);
+if (optional) {
+    optional.doSomething();
+}
+```
+
+#### isRegistered 方法
+
+检查服务是否已注册：
+
+```typescript
+if (Core.services.isRegistered(DataService)) {
+    const service = Core.services.resolve(DataService);
+}
+```
+
+## 内置服务
+
+Core 在初始化时自动注册了以下内置服务：
+
+### TimerManager
+
+定时器管理器，负责管理所有游戏定时器：
+
+```typescript
+const timerManager = Core.services.resolve(TimerManager);
+
+// 创建定时器
+timerManager.schedule(1.0, false, null, (timer) => {
+    console.log('1秒后执行');
+});
+```
+
+### PerformanceMonitor
+
+性能监控器，监控游戏性能并提供优化建议：
+
+```typescript
+const monitor = Core.services.resolve(PerformanceMonitor);
+
+// 启用性能监控
+monitor.enable();
+
+// 获取性能数据
+const fps = monitor.getFPS();
+```
+
+### SceneManager
+
+场景管理器，管理单场景应用的场景生命周期：
+
+```typescript
+const sceneManager = Core.services.resolve(SceneManager);
+
+// 设置当前场景
+sceneManager.setScene(new GameScene());
+
+// 获取当前场景
+const currentScene = sceneManager.currentScene;
+
+// 延迟切换场景
+sceneManager.loadScene(new MenuScene());
+
+// 更新场景
+sceneManager.update();
+```
+
+### WorldManager
+
+世界管理器，管理多个独立的 World 实例（高级用例）：
+
+```typescript
+const worldManager = Core.services.resolve(WorldManager);
+
+// 创建独立的游戏世界
+const gameWorld = worldManager.createWorld('game_room_001', {
+  name: 'GameRoom',
+  maxScenes: 5
+});
+
+// 在World中创建场景
+const scene = gameWorld.createScene('battle', new BattleScene());
+gameWorld.setSceneActive('battle', true);
+
+// 更新所有World
+worldManager.updateAll();
+```
+
+**适用场景**:
+- SceneManager: 适用于 95% 的游戏（单人游戏、简单多人游戏）
+- WorldManager: 适用于 MMO 服务器、游戏房间系统等需要完全隔离的多世界应用
+
+### PoolManager
+
+对象池管理器，管理所有对象池：
+
+```typescript
+const poolManager = Core.services.resolve(PoolManager);
+
+// 创建对象池
+const bulletPool = poolManager.createPool('bullets', () => new Bullet(), 100);
+```
+
+### PluginManager
+
+插件管理器，管理插件的安装和卸载：
+
+```typescript
+const pluginManager = Core.services.resolve(PluginManager);
+
+// 获取所有已安装的插件
+const plugins = pluginManager.getAllPlugins();
+```
+
+## 依赖注入
+
+ECS Framework 提供了装饰器来简化依赖注入。
+
+### @Injectable 装饰器
+
+标记类为可注入的服务：
+
+```typescript
+import { Injectable, IService } from '@esengine/ecs-framework';
+
+@Injectable()
+class GameService implements IService {
+    constructor() {
+        console.log('GameService created');
+    }
+
+    dispose(): void {
+        console.log('GameService disposed');
+    }
+}
+```
+
+### @Inject 装饰器
+
+在构造函数中注入依赖：
+
+```typescript
+import { Injectable, Inject, IService } from '@esengine/ecs-framework';
+
+@Injectable()
+class PlayerService implements IService {
+    constructor(
+        @Inject(DataService) private data: DataService,
+        @Inject(GameService) private game: GameService
+    ) {
+        // data 和 game 会自动从容器中解析
+    }
+
+    dispose(): void {
+        // 清理资源
+    }
+}
+```
+
+### 注册可注入服务
+
+使用 `registerInjectable` 自动处理依赖注入：
+
+```typescript
+import { registerInjectable } from '@esengine/ecs-framework';
+
+// 注册服务（会自动解析@Inject依赖）
+registerInjectable(Core.services, PlayerService);
+
+// 解析时会自动注入依赖
+const player = Core.services.resolve(PlayerService);
+```
+
+### @Updatable 装饰器
+
+标记服务为可更新的，使其在每帧自动被调用：
+
+```typescript
+import { Injectable, Updatable, IService, IUpdatable } from '@esengine/ecs-framework';
+
+@Injectable()
+@Updatable()  // 默认优先级为0
+class PhysicsService implements IService, IUpdatable {
+    update(deltaTime?: number): void {
+        // 每帧更新物理模拟
+    }
+
+    dispose(): void {
+        // 清理资源
+    }
+}
+
+// 指定更新优先级（数值越小越先执行）
+@Injectable()
+@Updatable(10)
+class RenderService implements IService, IUpdatable {
+    update(deltaTime?: number): void {
+        // 每帧渲染
+    }
+
+    dispose(): void {
+        // 清理资源
+    }
+}
+```
+
+使用 `@Updatable` 装饰器的服务会被 Core 自动调用，无需手动管理：
+
+```typescript
+// Core.update() 会自动调用所有@Updatable服务的update方法
+function gameLoop(deltaTime: number) {
+    Core.update(deltaTime);  // 自动更新所有可更新服务
+}
+```
+
+## 自定义服务
+
+### 创建自定义服务
+
+实现 `IService` 接口并注册到容器：
+
+```typescript
+import { IService } from '@esengine/ecs-framework';
+
+class AudioService implements IService {
+    private sounds: Map<string, HTMLAudioElement> = new Map();
+
+    play(soundId: string) {
+        const sound = this.sounds.get(soundId);
+        if (sound) {
+            sound.play();
+        }
+    }
+
+    load(soundId: string, url: string) {
+        const audio = new Audio(url);
+        this.sounds.set(soundId, audio);
+    }
+
+    dispose(): void {
+        // 停止所有音效并清理
+        for (const sound of this.sounds.values()) {
+            sound.pause();
+            sound.src = '';
+        }
+        this.sounds.clear();
+    }
+}
+
+// 注册自定义服务
+Core.services.registerSingleton(AudioService);
+
+// 使用服务
+const audio = Core.services.resolve(AudioService);
+audio.load('jump', '/sounds/jump.mp3');
+audio.play('jump');
+```
+
+### 服务间依赖
+
+服务可以依赖其他服务：
+
+```typescript
+@Injectable()
+class ConfigService implements IService {
+    private config: any = {};
+
+    get(key: string) {
+        return this.config[key];
+    }
+
+    dispose(): void {
+        this.config = {};
+    }
+}
+
+@Injectable()
+class NetworkService implements IService {
+    constructor(
+        @Inject(ConfigService) private config: ConfigService
+    ) {
+        // 使用配置服务
+        const apiUrl = this.config.get('apiUrl');
+    }
+
+    dispose(): void {
+        // 清理网络连接
+    }
+}
+
+// 注册服务（按依赖顺序）
+registerInjectable(Core.services, ConfigService);
+registerInjectable(Core.services, NetworkService);
+```
+
+## 高级用法
+
+### 服务替换（测试）
+
+在测试中替换真实服务为模拟服务：
+
+```typescript
+// 测试代码
+class MockDataService implements IService {
+    getData(key: string) {
+        return 'mock data';
+    }
+
+    dispose(): void {}
+}
+
+// 注册模拟服务（用于测试）
+Core.services.registerInstance(DataService, new MockDataService());
+```
+
+### 循环依赖检测
+
+服务容器会自动检测循环依赖：
+
+```typescript
+// A 依赖 B，B 依赖 A
+@Injectable()
+class ServiceA implements IService {
+    constructor(@Inject(ServiceB) b: ServiceB) {}
+    dispose(): void {}
+}
+
+@Injectable()
+class ServiceB implements IService {
+    constructor(@Inject(ServiceA) a: ServiceA) {}
+    dispose(): void {}
+}
+
+// 解析时会抛出错误: Circular dependency detected: ServiceA -> ServiceB -> ServiceA
+```
+
+### 获取所有服务
+
+```typescript
+// 获取所有已注册的服务类型
+const types = Core.services.getRegisteredServices();
+
+// 获取所有已实例化的服务实例
+const instances = Core.services.getAll();
+```
+
+### 服务清理
+
+```typescript
+// 注销单个服务
+Core.services.unregister(MyService);
+
+// 清空所有服务（会调用每个服务的dispose方法）
+Core.services.clear();
+```
+
+## 最佳实践
+
+### 服务命名
+
+服务类名应该以 `Service` 或 `Manager` 结尾，清晰表达其职责：
+
+```typescript
+class PlayerService implements IService {}
+class AudioManager implements IService {}
+class NetworkService implements IService {}
+```
+
+### 资源清理
+
+始终在 `dispose()` 方法中清理资源：
+
+```typescript
+class ResourceService implements IService {
+    private resources: Map<string, Resource> = new Map();
+
+    dispose(): void {
+        // 释放所有资源
+        for (const resource of this.resources.values()) {
+            resource.release();
+        }
+        this.resources.clear();
+    }
+}
+```
+
+### 避免过度使用
+
+不要把所有类都注册为服务，服务应该是：
+
+- 全局单例或需要共享状态
+- 需要在多处使用
+- 生命周期需要管理
+- 需要依赖注入
+
+对于简单的工具类或数据类，直接创建实例即可。
+
+### 依赖方向
+
+保持清晰的依赖方向，避免循环依赖：
+
+```
+高层服务 -> 中层服务 -> 底层服务
+GameLogic -> DataService -> ConfigService
+```
+
+## 常见问题
+
+### 服务未注册错误
+
+**问题**: `Error: Service MyService is not registered`
+
+**解决**:
+```typescript
+// 确保服务已注册
+Core.services.registerSingleton(MyService);
+
+// 或者使用tryResolve
+const service = Core.services.tryResolve(MyService);
+if (!service) {
+    console.log('Service not found');
+}
+```
+
+### 循环依赖错误
+
+**问题**: `Circular dependency detected`
+
+**解决**: 重新设计服务依赖关系，引入中间服务或使用事件系统解耦。
+
+### 何时使用单例 vs 瞬时
+
+- **单例**: 管理器类、配置、缓存、状态管理
+- **瞬时**: 命令对象、请求处理器、临时任务
+
+## 相关链接
+
+- [插件系统](./plugin-system.md) - 使用服务容器注册插件服务
+- [快速开始](./getting-started.md) - Core 初始化和基础使用
+- [系统架构](./system.md) - 在系统中使用服务

docs/guide/system.md

@@ -354,14 +354,18 @@ class PerformanceSystem extends EntitySystem {
 
 ### 添加系统到场景
 
+框架提供了两种方式添加系统：传入实例或传入类型（自动依赖注入）。
+
 ```typescript
 // 在场景子类中添加系统
 class GameScene extends Scene {
   protected initialize(): void {
-    // 添加系统
+    // 方式1：传入实例
     this.addSystem(new MovementSystem());
     this.addSystem(new RenderSystem());
-    this.addSystem(new PhysicsSystem());
+
+    // 方式2：传入类型（自动依赖注入）
+    this.addEntityProcessor(PhysicsSystem);
 
     // 设置系统更新顺序
     const movementSystem = this.getSystem(MovementSystem);
@@ -372,6 +376,48 @@ class GameScene extends Scene {
 }
 ```
 
+### 系统依赖注入
+
+系统实现了 `IService` 接口，支持通过依赖注入获取其他服务或系统：
+
+```typescript
+import { ECSSystem, Injectable, Inject } from '@esengine/ecs-framework';
+
+@Injectable()
+@ECSSystem('Physics')
+class PhysicsSystem extends EntitySystem {
+  constructor(
+    @Inject(CollisionService) private collision: CollisionService
+  ) {
+    super(Matcher.all(Transform, RigidBody));
+  }
+
+  protected process(entities: readonly Entity[]): void {
+    // 使用注入的服务
+    this.collision.detectCollisions(entities);
+  }
+
+  // 实现 IService 接口的 dispose 方法
+  public dispose(): void {
+    // 清理资源
+  }
+}
+
+// 使用时传入类型即可，框架会自动注入依赖
+class GameScene extends Scene {
+  protected initialize(): void {
+    // 自动依赖注入
+    this.addEntityProcessor(PhysicsSystem);
+  }
+}
+```
+
+注意事项：
+- 使用 `@Injectable()` 装饰器标记需要依赖注入的系统
+- 在构造函数参数中使用 `@Inject()` 装饰器声明依赖
+- 系统必须实现 `dispose()` 方法（IService 接口要求）
+- 使用 `addEntityProcessor(类型)` 而不是 `addSystem(new 类型())` 来启用依赖注入
+
 ### 系统更新顺序
 
 ```typescript

docs/guide/world-manager.md

@@ -0,0 +1,761 @@
+# WorldManager
+
+WorldManager 是 ECS Framework 提供的高级世界管理器，用于管理多个完全隔离的游戏世界（World）。每个 World 都是独立的 ECS 环境，可以包含多个场景。
+
+## 适用场景
+
+WorldManager 适合以下高级场景：
+- MMO 游戏服务器的多房间管理
+- 游戏大厅系统（每个游戏房间完全隔离）
+- 服务器端的多游戏实例
+- 需要完全隔离的多个游戏环境
+- 需要同时运行多个独立世界的应用
+
+## 特点
+
+- 多 World 管理，每个 World 完全独立
+- 每个 World 可以包含多个 Scene
+- 支持 World 的激活/停用
+- 自动清理空 World
+- World 级别的全局系统
+- 批量操作和查询
+
+## 基本使用
+
+### 初始化
+
+WorldManager 是 Core 的内置服务，通过服务容器获取：
+
+```typescript
+import { Core, WorldManager } from '@esengine/ecs-framework';
+
+// 初始化 Core
+Core.create({ debug: true });
+
+// 从服务容器获取 WorldManager（Core 已自动创建并注册）
+const worldManager = Core.services.resolve(WorldManager);
+```
+
+### 创建 World
+
+```typescript
+// 创建游戏房间 World
+const room1 = worldManager.createWorld('room_001', {
+  name: 'GameRoom_001',
+  maxScenes: 5,
+  debug: true
+});
+
+// 激活 World
+worldManager.setWorldActive('room_001', true);
+
+// 创建更多房间
+const room2 = worldManager.createWorld('room_002', {
+  name: 'GameRoom_002',
+  maxScenes: 5
+});
+
+worldManager.setWorldActive('room_002', true);
+```
+
+### 游戏循环
+
+在游戏循环中更新所有活跃的 World：
+
+```typescript
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);        // 更新全局服务
+  worldManager.updateAll();      // 更新所有活跃的 World
+}
+
+// 启动游戏循环
+let lastTime = 0;
+setInterval(() => {
+  const currentTime = Date.now();
+  const deltaTime = (currentTime - lastTime) / 1000;
+  lastTime = currentTime;
+
+  gameLoop(deltaTime);
+}, 16); // 60 FPS
+```
+
+## World 管理
+
+### 创建 World
+
+```typescript
+// 基本创建
+const world = worldManager.createWorld('worldId');
+
+// 带配置创建
+const world = worldManager.createWorld('worldId', {
+  name: 'MyWorld',
+  maxScenes: 10,
+  autoCleanup: true,
+  debug: true
+});
+```
+
+**配置选项（IWorldConfig）**：
+- `name?: string` - World 名称
+- `maxScenes?: number` - 最大场景数量限制（默认 10）
+- `autoCleanup?: boolean` - 是否自动清理空场景（默认 true）
+- `debug?: boolean` - 是否启用调试模式（默认 false）
+
+### 获取 World
+
+```typescript
+// 通过 ID 获取
+const world = worldManager.getWorld('room_001');
+if (world) {
+  console.log(`World: ${world.name}`);
+}
+
+// 获取所有 World
+const allWorlds = worldManager.getAllWorlds();
+console.log(`共有 ${allWorlds.length} 个 World`);
+
+// 获取所有 World ID
+const worldIds = worldManager.getWorldIds();
+console.log('World 列表:', worldIds);
+
+// 通过名称查找
+const world = worldManager.findWorldByName('GameRoom_001');
+```
+
+### 激活和停用 World
+
+```typescript
+// 激活 World（开始运行和更新）
+worldManager.setWorldActive('room_001', true);
+
+// 停用 World（停止更新但保留数据）
+worldManager.setWorldActive('room_001', false);
+
+// 检查 World 是否激活
+if (worldManager.isWorldActive('room_001')) {
+  console.log('房间正在运行');
+}
+
+// 获取所有活跃的 World
+const activeWorlds = worldManager.getActiveWorlds();
+console.log(`当前有 ${activeWorlds.length} 个活跃 World`);
+```
+
+### 移除 World
+
+```typescript
+// 移除 World（会自动停用并销毁）
+const removed = worldManager.removeWorld('room_001');
+if (removed) {
+  console.log('World 已移除');
+}
+```
+
+## World 中的场景管理
+
+每个 World 可以包含多个 Scene 并独立管理它们的生命周期。
+
+### 创建场景
+
+```typescript
+const world = worldManager.getWorld('room_001');
+if (!world) return;
+
+// 创建场景
+const mainScene = world.createScene('main', new MainScene());
+const uiScene = world.createScene('ui', new UIScene());
+const hudScene = world.createScene('hud', new HUDScene());
+
+// 激活场景
+world.setSceneActive('main', true);
+world.setSceneActive('ui', true);
+world.setSceneActive('hud', false);
+```
+
+### 查询场景
+
+```typescript
+// 获取特定场景
+const mainScene = world.getScene<MainScene>('main');
+if (mainScene) {
+  console.log(`场景名称: ${mainScene.name}`);
+}
+
+// 获取所有场景
+const allScenes = world.getAllScenes();
+console.log(`World 中共有 ${allScenes.length} 个场景`);
+
+// 获取所有场景 ID
+const sceneIds = world.getSceneIds();
+console.log('场景列表:', sceneIds);
+
+// 获取活跃场景数量
+const activeCount = world.getActiveSceneCount();
+console.log(`当前有 ${activeCount} 个活跃场景`);
+
+// 检查场景是否激活
+if (world.isSceneActive('main')) {
+  console.log('主场景正在运行');
+}
+```
+
+### 场景切换
+
+World 支持多场景同时运行，也支持场景切换：
+
+```typescript
+class GameWorld {
+  private world: World;
+
+  constructor(worldManager: WorldManager) {
+    this.world = worldManager.createWorld('game', {
+      name: 'GameWorld',
+      maxScenes: 5
+    });
+
+    // 创建所有场景
+    this.world.createScene('menu', new MenuScene());
+    this.world.createScene('game', new GameScene());
+    this.world.createScene('pause', new PauseScene());
+    this.world.createScene('gameover', new GameOverScene());
+
+    // 激活 World
+    worldManager.setWorldActive('game', true);
+  }
+
+  public showMenu(): void {
+    this.deactivateAllScenes();
+    this.world.setSceneActive('menu', true);
+  }
+
+  public startGame(): void {
+    this.deactivateAllScenes();
+    this.world.setSceneActive('game', true);
+  }
+
+  public pauseGame(): void {
+    // 游戏场景继续存在但停止更新
+    this.world.setSceneActive('game', false);
+    // 显示暂停界面
+    this.world.setSceneActive('pause', true);
+  }
+
+  public resumeGame(): void {
+    this.world.setSceneActive('pause', false);
+    this.world.setSceneActive('game', true);
+  }
+
+  public showGameOver(): void {
+    this.deactivateAllScenes();
+    this.world.setSceneActive('gameover', true);
+  }
+
+  private deactivateAllScenes(): void {
+    const sceneIds = this.world.getSceneIds();
+    sceneIds.forEach(id => this.world.setSceneActive(id, false));
+  }
+}
+```
+
+### 移除场景
+
+```typescript
+// 移除不再需要的场景
+const removed = world.removeScene('oldScene');
+if (removed) {
+  console.log('场景已移除');
+}
+
+// 场景会自动调用 end() 方法进行清理
+```
+
+## 全局系统
+
+World 支持全局系统，这些系统在 World 级别运行，不依赖特定 Scene。
+
+### 定义全局系统
+
+```typescript
+import { IGlobalSystem } from '@esengine/ecs-framework';
+
+// 网络系统（World 级别）
+class NetworkSystem implements IGlobalSystem {
+  readonly name = 'NetworkSystem';
+
+  private connectionId: string;
+
+  constructor(connectionId: string) {
+    this.connectionId = connectionId;
+  }
+
+  initialize(): void {
+    console.log(`网络系统初始化: ${this.connectionId}`);
+    // 建立网络连接
+  }
+
+  update(deltaTime?: number): void {
+    // 处理网络消息，不依赖任何 Scene
+    // 接收和发送网络包
+  }
+
+  destroy(): void {
+    console.log(`网络系统销毁: ${this.connectionId}`);
+    // 关闭网络连接
+  }
+}
+
+// 物理系统（World 级别）
+class PhysicsSystem implements IGlobalSystem {
+  readonly name = 'PhysicsSystem';
+
+  initialize(): void {
+    console.log('物理系统初始化');
+  }
+
+  update(deltaTime?: number): void {
+    // 物理模拟，作用于 World 中所有场景
+  }
+
+  destroy(): void {
+    console.log('物理系统销毁');
+  }
+}
+```
+
+### 使用全局系统
+
+```typescript
+const world = worldManager.getWorld('room_001');
+if (!world) return;
+
+// 添加全局系统
+const networkSystem = world.addGlobalSystem(new NetworkSystem('conn_001'));
+const physicsSystem = world.addGlobalSystem(new PhysicsSystem());
+
+// 获取全局系统
+const network = world.getGlobalSystem(NetworkSystem);
+if (network) {
+  console.log('找到网络系统');
+}
+
+// 移除全局系统
+world.removeGlobalSystem(networkSystem);
+```
+
+## 批量操作
+
+### 更新所有 World
+
+```typescript
+// 更新所有活跃的 World（应该在游戏循环中调用）
+worldManager.updateAll();
+
+// 这会自动更新每个 World 的：
+// 1. 全局系统
+// 2. 所有活跃场景
+```
+
+### 启动和停止
+
+```typescript
+// 启动所有 World
+worldManager.startAll();
+
+// 停止所有 World
+worldManager.stopAll();
+
+// 检查是否正在运行
+if (worldManager.isRunning) {
+  console.log('WorldManager 正在运行');
+}
+```
+
+### 查找 World
+
+```typescript
+// 使用条件查找
+const emptyWorlds = worldManager.findWorlds(world => {
+  return world.sceneCount === 0;
+});
+
+// 查找活跃的 World
+const activeWorlds = worldManager.findWorlds(world => {
+  return world.isActive;
+});
+
+// 查找特定名称的 World
+const world = worldManager.findWorldByName('GameRoom_001');
+```
+
+## 统计和监控
+
+### 获取统计信息
+
+```typescript
+const stats = worldManager.getStats();
+
+console.log(`总 World 数: ${stats.totalWorlds}`);
+console.log(`活跃 World 数: ${stats.activeWorlds}`);
+console.log(`总场景数: ${stats.totalScenes}`);
+console.log(`总实体数: ${stats.totalEntities}`);
+console.log(`总系统数: ${stats.totalSystems}`);
+
+// 查看每个 World 的详细信息
+stats.worlds.forEach(worldInfo => {
+  console.log(`World: ${worldInfo.name}`);
+  console.log(`  场景数: ${worldInfo.sceneCount}`);
+  console.log(`  是否活跃: ${worldInfo.isActive}`);
+});
+```
+
+### 获取详细状态
+
+```typescript
+const status = worldManager.getDetailedStatus();
+
+// 包含所有 World 的详细状态
+status.worlds.forEach(worldStatus => {
+  console.log(`World ID: ${worldStatus.id}`);
+  console.log(`状态:`, worldStatus.status);
+});
+```
+
+## 自动清理
+
+WorldManager 支持自动清理空的 World。
+
+### 配置清理
+
+```typescript
+// 创建带清理配置的 WorldManager
+const worldManager = Core.services.resolve(WorldManager);
+
+// WorldManager 的配置在 Core 中设置：
+// {
+//   maxWorlds: 50,
+//   autoCleanup: true,
+//   cleanupInterval: 30000  // 30 秒
+// }
+```
+
+### 手动清理
+
+```typescript
+// 手动触发清理
+const cleanedCount = worldManager.cleanup();
+console.log(`清理了 ${cleanedCount} 个 World`);
+```
+
+**清理条件**：
+- World 未激活
+- 没有 Scene 或所有 Scene 都是空的
+- 创建时间超过 10 分钟
+
+## API 参考
+
+### WorldManager API
+
+| 方法 | 说明 |
+|------|------|
+| `createWorld(worldId, config?)` | 创建新 World |
+| `removeWorld(worldId)` | 移除 World |
+| `getWorld(worldId)` | 获取 World |
+| `getAllWorlds()` | 获取所有 World |
+| `getWorldIds()` | 获取所有 World ID |
+| `setWorldActive(worldId, active)` | 设置 World 激活状态 |
+| `isWorldActive(worldId)` | 检查 World 是否激活 |
+| `getActiveWorlds()` | 获取所有活跃的 World |
+| `updateAll()` | 更新所有活跃 World |
+| `startAll()` | 启动所有 World |
+| `stopAll()` | 停止所有 World |
+| `findWorlds(predicate)` | 查找满足条件的 World |
+| `findWorldByName(name)` | 根据名称查找 World |
+| `getStats()` | 获取统计信息 |
+| `getDetailedStatus()` | 获取详细状态信息 |
+| `cleanup()` | 清理空 World |
+| `destroy()` | 销毁 WorldManager |
+
+### World API
+
+| 方法 | 说明 |
+|------|------|
+| `createScene(sceneId, sceneInstance?)` | 创建并添加 Scene |
+| `removeScene(sceneId)` | 移除 Scene |
+| `getScene(sceneId)` | 获取 Scene |
+| `getAllScenes()` | 获取所有 Scene |
+| `getSceneIds()` | 获取所有 Scene ID |
+| `setSceneActive(sceneId, active)` | 设置 Scene 激活状态 |
+| `isSceneActive(sceneId)` | 检查 Scene 是否激活 |
+| `getActiveSceneCount()` | 获取活跃 Scene 数量 |
+| `addGlobalSystem(system)` | 添加全局系统 |
+| `removeGlobalSystem(system)` | 移除全局系统 |
+| `getGlobalSystem(type)` | 获取全局系统 |
+| `start()` | 启动 World |
+| `stop()` | 停止 World |
+| `updateGlobalSystems()` | 更新全局系统 |
+| `updateScenes()` | 更新所有激活 Scene |
+| `destroy()` | 销毁 World |
+| `getStatus()` | 获取 World 状态 |
+| `getStats()` | 获取统计信息 |
+
+### 属性
+
+| 属性 | 说明 |
+|------|------|
+| `worldCount` | World 总数 |
+| `activeWorldCount` | 活跃 World 数量 |
+| `isRunning` | 是否正在运行 |
+| `config` | 配置信息 |
+
+## 完整示例
+
+### MMO 游戏房间系统
+
+```typescript
+import { Core, WorldManager, Scene, World } from '@esengine/ecs-framework';
+
+// 初始化
+Core.create({ debug: true });
+const worldManager = Core.services.resolve(WorldManager);
+
+// 房间管理器
+class RoomManager {
+  private worldManager: WorldManager;
+  private rooms: Map<string, World> = new Map();
+
+  constructor(worldManager: WorldManager) {
+    this.worldManager = worldManager;
+  }
+
+  // 创建游戏房间
+  public createRoom(roomId: string, maxPlayers: number): World {
+    const world = this.worldManager.createWorld(roomId, {
+      name: `Room_${roomId}`,
+      maxScenes: 3,
+      debug: true
+    });
+
+    // 创建房间场景
+    world.createScene('lobby', new LobbyScene());
+    world.createScene('game', new GameScene());
+    world.createScene('result', new ResultScene());
+
+    // 添加房间级别的系统
+    world.addGlobalSystem(new NetworkSystem(roomId));
+    world.addGlobalSystem(new RoomLogicSystem(maxPlayers));
+
+    // 激活 World 和初始场景
+    this.worldManager.setWorldActive(roomId, true);
+    world.setSceneActive('lobby', true);
+
+    this.rooms.set(roomId, world);
+    console.log(`房间 ${roomId} 已创建`);
+
+    return world;
+  }
+
+  // 玩家加入房间
+  public joinRoom(roomId: string, playerId: string): boolean {
+    const world = this.rooms.get(roomId);
+    if (!world) {
+      console.log(`房间 ${roomId} 不存在`);
+      return false;
+    }
+
+    // 在大厅场景中创建玩家实体
+    const lobbyScene = world.getScene('lobby');
+    if (lobbyScene) {
+      const player = lobbyScene.createEntity(`Player_${playerId}`);
+      // 添加玩家组件...
+      console.log(`玩家 ${playerId} 加入房间 ${roomId}`);
+      return true;
+    }
+
+    return false;
+  }
+
+  // 开始游戏
+  public startGame(roomId: string): void {
+    const world = this.rooms.get(roomId);
+    if (!world) return;
+
+    // 切换到游戏场景
+    world.setSceneActive('lobby', false);
+    world.setSceneActive('game', true);
+
+    console.log(`房间 ${roomId} 游戏开始`);
+  }
+
+  // 结束游戏
+  public endGame(roomId: string): void {
+    const world = this.rooms.get(roomId);
+    if (!world) return;
+
+    // 切换到结果场景
+    world.setSceneActive('game', false);
+    world.setSceneActive('result', true);
+
+    console.log(`房间 ${roomId} 游戏结束`);
+  }
+
+  // 关闭房间
+  public closeRoom(roomId: string): void {
+    this.worldManager.removeWorld(roomId);
+    this.rooms.delete(roomId);
+    console.log(`房间 ${roomId} 已关闭`);
+  }
+
+  // 获取房间列表
+  public getRoomList(): string[] {
+    return Array.from(this.rooms.keys());
+  }
+
+  // 获取房间统计
+  public getRoomStats(roomId: string) {
+    const world = this.rooms.get(roomId);
+    return world?.getStats();
+  }
+}
+
+// 使用房间管理器
+const roomManager = new RoomManager(worldManager);
+
+// 创建多个游戏房间
+roomManager.createRoom('room_001', 4);
+roomManager.createRoom('room_002', 4);
+roomManager.createRoom('room_003', 2);
+
+// 玩家加入
+roomManager.joinRoom('room_001', 'player_1');
+roomManager.joinRoom('room_001', 'player_2');
+
+// 开始游戏
+roomManager.startGame('room_001');
+
+// 游戏循环
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);
+  worldManager.updateAll();  // 更新所有房间
+}
+
+// 定期清理空房间
+setInterval(() => {
+  const stats = worldManager.getStats();
+  console.log(`当前房间数: ${stats.totalWorlds}`);
+  console.log(`活跃房间数: ${stats.activeWorlds}`);
+
+  worldManager.cleanup();
+}, 60000); // 每分钟清理一次
+```
+
+## 最佳实践
+
+### 1. 合理的 World 粒度
+
+```typescript
+// 推荐：每个独立环境一个 World
+const room1 = worldManager.createWorld('room_1');  // 游戏房间1
+const room2 = worldManager.createWorld('room_2');  // 游戏房间2
+
+// 不推荐：过度使用 World
+const world1 = worldManager.createWorld('ui');     // UI 不需要独立 World
+const world2 = worldManager.createWorld('menu');   // 菜单不需要独立 World
+```
+
+### 2. 使用全局系统处理跨场景逻辑
+
+```typescript
+// 推荐：World 级别的系统
+class NetworkSystem implements IGlobalSystem {
+  update() {
+    // 网络处理不依赖场景
+  }
+}
+
+// 不推荐：在每个场景中重复创建
+class GameScene extends Scene {
+  initialize() {
+    this.addSystem(new NetworkSystem());  // 不应该在场景级别
+  }
+}
+```
+
+### 3. 及时清理不用的 World
+
+```typescript
+// 推荐：玩家离开时清理房间
+function onPlayerLeave(roomId: string) {
+  const world = worldManager.getWorld(roomId);
+  if (world && world.sceneCount === 0) {
+    worldManager.removeWorld(roomId);
+  }
+}
+
+// 或使用自动清理
+worldManager.cleanup();
+```
+
+### 4. 监控资源使用
+
+```typescript
+// 定期检查资源使用情况
+setInterval(() => {
+  const stats = worldManager.getStats();
+
+  if (stats.totalWorlds > 100) {
+    console.warn('World 数量过多，考虑清理');
+    worldManager.cleanup();
+  }
+
+  if (stats.totalEntities > 10000) {
+    console.warn('实体数量过多，检查是否有泄漏');
+  }
+}, 30000);
+```
+
+## 与 SceneManager 的对比
+
+| 特性 | SceneManager | WorldManager |
+|------|--------------|--------------|
+| 适用场景 | 95% 的游戏应用 | 高级多世界隔离场景 |
+| 复杂度 | 简单 | 复杂 |
+| 场景数量 | 单场景（可切换） | 多 World，每个 World 多场景 |
+| 场景隔离 | 无（场景切换） | 完全隔离（每个 World 独立） |
+| 性能开销 | 最小 | 较高 |
+| 全局系统 | 无 | 支持（World 级别） |
+| 使用示例 | 单人游戏、移动游戏 | MMO 服务器、游戏房间系统 |
+
+**何时使用 WorldManager**：
+- MMO 游戏服务器（每个房间一个 World）
+- 游戏大厅系统（每个游戏房间完全隔离）
+- 需要运行多个完全独立的游戏实例
+- 服务器端模拟多个游戏世界
+
+**何时使用 SceneManager**：
+- 单人游戏
+- 简单的多人游戏
+- 移动游戏
+- 场景之间需要切换但不需要同时运行
+
+## 架构层次
+
+WorldManager 在 ECS Framework 中的位置：
+
+```
+Core (全局服务)
+  └── WorldManager (世界管理)
+      ├── World 1 (游戏房间1)
+      │   ├── GlobalSystem (全局系统)
+      │   ├── Scene 1 (场景1)
+      │   │   ├── EntitySystem
+      │   │   ├── Entity
+      │   │   └── Component
+      │   └── Scene 2 (场景2)
+      ├── World 2 (游戏房间2)
+      │   ├── GlobalSystem
+      │   └── Scene 1
+      └── World 3 (游戏房间3)
+```
+
+WorldManager 为需要多世界隔离的高级应用提供了强大的管理能力。如果你的应用不需要多世界隔离，建议使用更简单的 [SceneManager](./scene-manager.md)。

eslint.config.mjs

@@ -0,0 +1,66 @@
+import eslint from '@eslint/js';
+import tseslint from 'typescript-eslint';
+
+export default [
+    eslint.configs.recommended,
+    ...tseslint.configs.recommended,
+    {
+        files: ['packages/**/src/**/*.{ts,tsx,js,jsx}'],
+        languageOptions: {
+            parser: tseslint.parser,
+            parserOptions: {
+                ecmaVersion: 2020,
+                sourceType: 'module'
+            }
+        },
+        rules: {
+            'semi': 'warn',
+            'quotes': 'warn',
+            'indent': 'off',
+            'no-trailing-spaces': 'warn',
+            'eol-last': 'warn',
+            'comma-dangle': 'warn',
+            'object-curly-spacing': 'warn',
+            'array-bracket-spacing': 'warn',
+            'arrow-parens': 'warn',
+            'prefer-const': 'warn',
+            'no-multiple-empty-lines': 'warn',
+            'no-console': 'off',
+            '@typescript-eslint/no-explicit-any': 'warn',
+            '@typescript-eslint/no-unsafe-function-type': 'warn',
+            '@typescript-eslint/no-unsafe-assignment': 'off',
+            '@typescript-eslint/no-unsafe-member-access': 'off',
+            '@typescript-eslint/no-unsafe-call': 'off',
+            '@typescript-eslint/no-unsafe-return': 'off',
+            '@typescript-eslint/no-unsafe-argument': 'off',
+            '@typescript-eslint/explicit-module-boundary-types': 'off',
+            '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+            '@typescript-eslint/no-non-null-assertion': 'off',
+            '@typescript-eslint/no-require-imports': 'warn',
+            '@typescript-eslint/no-this-alias': 'warn',
+            'no-case-declarations': 'warn',
+            'no-prototype-builtins': 'warn',
+            'no-empty': 'warn',
+            'no-useless-catch': 'warn'
+        }
+    },
+    {
+        ignores: [
+            'node_modules/**',
+            '**/node_modules/**',
+            'dist/**',
+            '**/dist/**',
+            'bin/**',
+            '**/bin/**',
+            'build/**',
+            '**/build/**',
+            'coverage/**',
+            '**/coverage/**',
+            'thirdparty/**',
+            'examples/lawn-mower-demo/**',
+            'extensions/**',
+            '**/*.min.js',
+            '**/*.d.ts'
+        ]
+    }
+];

extensions/cocos/cocos-ecs/.creator/asset-template/typescript/Custom Script Template Help Documentation.url

@@ -1,2 +0,0 @@
-[InternetShortcut]
-URL=https://docs.cocos.com/creator/manual/en/scripting/setup.html#custom-script-template

extensions/cocos/cocos-ecs/.gitignore

@@ -1,24 +0,0 @@
-
-#///////////////////////////
-# Cocos Creator 3D Project
-#///////////////////////////
-library/
-temp/
-local/
-build/
-profiles/
-native
-#//////////////////////////
-# NPM
-#//////////////////////////
-node_modules/
-
-#//////////////////////////
-# VSCode
-#//////////////////////////
-.vscode/
-
-#//////////////////////////
-# WebStorm
-#//////////////////////////
-.idea/

extensions/cocos/cocos-ecs/assets/resources.meta

@@ -1,14 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "2a691dda-d56d-4a72-9fef-111a999415db",
-  "files": [],
-  "subMetas": {},
-  "userData": {
-    "isBundle": true,
-    "bundleConfigID": "default",
-    "bundleName": "resources",
-    "priority": 8
-  }
-}

extensions/cocos/cocos-ecs/assets/resources/effects.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "8c25761f-50d6-498b-a95f-d863bf1fbff1",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/resources/materials.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "3a66cbbc-6612-4408-838b-875d0bb2e9a3",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/resources/miner-stamina-ai.bt.json

@@ -1,317 +0,0 @@
-{
-  "nodes": [
-    {
-      "id": "node_15iffhg4p",
-      "type": "root",
-      "name": "根节点",
-      "description": "行为树的根节点，每棵树只能有一个根节点",
-      "children": [
-        "node_o6tsnrxyg"
-      ]
-    },
-    {
-      "id": "node_o6tsnrxyg",
-      "type": "selector",
-      "name": "选择器",
-      "description": "按顺序执行子节点，任一成功则整体成功",
-      "properties": {
-        "abortType": "LowerPriority"
-      },
-      "children": [
-        "node_tljchzbno",
-        "node_txhx0hau5",
-        "node_r9kvcwv8u",
-        "node_520hedw22"
-      ]
-    },
-    {
-      "id": "node_tljchzbno",
-      "type": "conditional-decorator",
-      "name": "休息条件装饰器",
-      "description": "基于条件执行子节点（拖拽条件节点到此装饰器来配置条件）",
-      "properties": {
-        "conditionType": "blackboardCompare",
-        "executeWhenTrue": true,
-        "abortType": "LowerPriority",
-        "shouldReevaluate": true,
-        "variableName": "{{isLowStamina}}",
-        "operator": "equal",
-        "compareValue": "true"
-      },
-      "children": [
-        "node_ulp8qx68h"
-      ],
-      "condition": {
-        "type": "blackboard-value-comparison",
-        "properties": {}
-      }
-    },
-    {
-      "id": "node_txhx0hau5",
-      "type": "conditional-decorator",
-      "name": "存储条件装饰器",
-      "description": "基于条件执行子节点（拖拽条件节点到此装饰器来配置条件）",
-      "properties": {
-        "conditionType": "blackboardCompare",
-        "executeWhenTrue": true,
-        "abortType": "LowerPriority",
-        "shouldReevaluate": true,
-        "variableName": "{{hasOre}}",
-        "operator": "equal",
-        "compareValue": "true"
-      },
-      "children": [
-        "node_dhsz8rgl1"
-      ],
-      "condition": {
-        "type": "blackboard-value-comparison",
-        "properties": {}
-      }
-    },
-    {
-      "id": "node_r9kvcwv8u",
-      "type": "conditional-decorator",
-      "name": "挖矿条件装饰器",
-      "description": "基于条件执行子节点（拖拽条件节点到此装饰器来配置条件）",
-      "properties": {
-        "conditionType": "blackboardCompare",
-        "executeWhenTrue": true,
-        "abortType": "LowerPriority",
-        "shouldReevaluate": true,
-        "variableName": "{{isLowStamina}}",
-        "operator": "equal",
-        "compareValue": "false"
-      },
-      "children": [
-        "node_zguxml6u7"
-      ],
-      "condition": {
-        "type": "blackboard-value-comparison",
-        "properties": {}
-      }
-    },
-    {
-      "id": "node_ulp8qx68h",
-      "type": "sequence",
-      "name": "序列器",
-      "description": "按顺序执行子节点，任一失败则整体失败",
-      "properties": {
-        "abortType": "None"
-      },
-      "children": [
-        "node_0fgq85ovw",
-        "node_9v13vpqyr"
-      ]
-    },
-    {
-      "id": "node_0fgq85ovw",
-      "type": "event-action",
-      "name": "回家休息",
-      "description": "执行已注册的事件处理函数（推荐）",
-      "properties": {
-        "eventName": "go-home-rest",
-        "parameters": "{}"
-      }
-    },
-    {
-      "id": "node_9v13vpqyr",
-      "type": "event-action",
-      "name": "恢复体力",
-      "description": "执行已注册的事件处理函数（推荐）",
-      "properties": {
-        "eventName": "recover-stamina",
-        "parameters": "{}"
-      }
-    },
-    {
-      "id": "node_ui4ja9mlj",
-      "type": "event-action",
-      "name": "前往仓库存储",
-      "description": "执行已注册的事件处理函数（推荐）",
-      "properties": {
-        "eventName": "store-ore",
-        "parameters": "{}"
-      }
-    },
-    {
-      "id": "node_969njccy2",
-      "type": "event-action",
-      "name": "挖掘金矿",
-      "description": "执行已注册的事件处理函数（推荐）",
-      "properties": {
-        "eventName": "mine-gold-ore",
-        "parameters": "{}"
-      }
-    },
-    {
-      "id": "node_520hedw22",
-      "type": "event-action",
-      "name": "默认待机",
-      "description": "执行已注册的事件处理函数（推荐）",
-      "properties": {
-        "eventName": "idle-behavior",
-        "parameters": "{}"
-      }
-    },
-    {
-      "id": "node_o5c7hv5wx",
-      "type": "set-blackboard-value",
-      "name": "设置黑板变量",
-      "description": "设置黑板变量的值",
-      "properties": {
-        "variableName": "{{hasOre}}",
-        "value": "false"
-      }
-    },
-    {
-      "id": "node_zf0sgkqev",
-      "type": "set-blackboard-value",
-      "name": "设置黑板变量",
-      "description": "设置黑板变量的值",
-      "properties": {
-        "variableName": "{{hasOre}}",
-        "value": "true"
-      }
-    },
-    {
-      "id": "node_dhsz8rgl1",
-      "type": "sequence",
-      "name": "序列器",
-      "description": "按顺序执行子节点，任一失败则整体失败",
-      "properties": {
-        "abortType": "None"
-      },
-      "children": [
-        "node_ui4ja9mlj",
-        "node_o5c7hv5wx"
-      ]
-    },
-    {
-      "id": "node_zguxml6u7",
-      "type": "sequence",
-      "name": "序列器",
-      "description": "按顺序执行子节点，任一失败则整体失败",
-      "properties": {
-        "abortType": "None"
-      },
-      "children": [
-        "node_969njccy2",
-        "node_zf0sgkqev"
-      ]
-    }
-  ],
-  "blackboard": [
-    {
-      "name": "unitType",
-      "type": "string",
-      "value": "miner",
-      "description": "单位类型",
-      "group": "基础属性"
-    },
-    {
-      "name": "currentHealth",
-      "type": "number",
-      "value": 100,
-      "description": "当前生命值",
-      "group": "基础属性"
-    },
-    {
-      "name": "maxHealth",
-      "type": "number",
-      "value": 100,
-      "description": "最大生命值",
-      "group": "基础属性"
-    },
-    {
-      "name": "stamina",
-      "type": "number",
-      "value": 100,
-      "description": "当前体力值 - 挖矿会消耗体力",
-      "group": "体力系统"
-    },
-    {
-      "name": "maxStamina",
-      "type": "number",
-      "value": 100,
-      "description": "最大体力值",
-      "group": "体力系统"
-    },
-    {
-      "name": "staminaPercentage",
-      "type": "number",
-      "value": 1,
-      "description": "体力百分比",
-      "group": "体力系统"
-    },
-    {
-      "name": "isLowStamina",
-      "type": "boolean",
-      "value": false,
-      "description": "是否低体力 - 体力低于20%时为true",
-      "group": "体力系统"
-    },
-    {
-      "name": "isResting",
-      "type": "boolean",
-      "value": false,
-      "description": "是否正在休息",
-      "group": "体力系统"
-    },
-    {
-      "name": "homePosition",
-      "type": "vector3",
-      "value": {
-        "x": 0,
-        "y": 0,
-        "z": 0
-      },
-      "description": "家的位置 - 矿工休息的地方",
-      "group": "体力系统"
-    },
-    {
-      "name": "hasOre",
-      "type": "boolean",
-      "value": false,
-      "description": "是否携带矿石",
-      "group": "工作状态"
-    },
-    {
-      "name": "currentCommand",
-      "type": "string",
-      "value": "mine",
-      "description": "当前命令",
-      "group": "工作状态"
-    },
-    {
-      "name": "hasTarget",
-      "type": "boolean",
-      "value": false,
-      "description": "是否有目标",
-      "group": "工作状态"
-    },
-    {
-      "name": "targetPosition",
-      "type": "vector3",
-      "value": {
-        "x": 0,
-        "y": 0,
-        "z": 0
-      },
-      "description": "目标位置",
-      "group": "移动属性"
-    },
-    {
-      "name": "isMoving",
-      "type": "boolean",
-      "value": false,
-      "description": "是否正在移动",
-      "group": "移动属性"
-    }
-  ],
-  "metadata": {
-    "name": "behavior-tree",
-    "created": "2025-06-25T14:06:55.596Z",
-    "version": "1.0",
-    "exportType": "clean"
-  }
-}

extensions/cocos/cocos-ecs/assets/resources/miner-stamina-ai.bt.json.meta

@@ -1,11 +0,0 @@
-{
-  "ver": "2.0.1",
-  "importer": "json",
-  "imported": true,
-  "uuid": "598e1450-8c7a-46c7-9540-398f9809d627",
-  "files": [
-    ".json"
-  ],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/resources/miner-stamina-ai.btree.meta

@@ -1,12 +0,0 @@
-{
-  "ver": "1.0.0",
-  "importer": "*",
-  "imported": true,
-  "uuid": "24c6e7e6-4ff0-4e7b-b470-9468bfa66b5d",
-  "files": [
-    ".btree",
-    ".json"
-  ],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/resources/prefabs.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "2bf3ded8-4054-4d8f-a367-c76b21eaf538",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/resources/prefabs/Panel_Node.prefab.meta

@@ -1,13 +0,0 @@
-{
-  "ver": "1.1.50",
-  "importer": "prefab",
-  "imported": true,
-  "uuid": "51a6e245-2983-4258-be9f-9e21378f7f9f",
-  "files": [
-    ".json"
-  ],
-  "subMetas": {},
-  "userData": {
-    "syncNodeName": "Panel_Node"
-  }
-}

extensions/cocos/cocos-ecs/assets/resources/terrains.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "4fd895f7-6b0f-4357-aa3a-7c2e88ffac9a",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/resources/textures.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "829183be-61a1-4494-bf64-3df359c0e8e7",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scenes.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "240e4a78-e55f-47a8-84de-39220bba1321",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scenes/behaviour-example-scene.scene

@@ -1,757 +0,0 @@
-[
-  {
-    "__type__": "cc.SceneAsset",
-    "_name": "behaviour-example-scene",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_native": "",
-    "scene": {
-      "__id__": 1
-    }
-  },
-  {
-    "__type__": "cc.Scene",
-    "_name": "behaviour-example-scene",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_parent": null,
-    "_children": [
-      {
-        "__id__": 2
-      },
-      {
-        "__id__": 5
-      },
-      {
-        "__id__": 7
-      },
-      {
-        "__id__": 8
-      },
-      {
-        "__id__": 14
-      }
-    ],
-    "_active": true,
-    "_components": [],
-    "_prefab": null,
-    "_lpos": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_lrot": {
-      "__type__": "cc.Quat",
-      "x": 0,
-      "y": 0,
-      "z": 0,
-      "w": 1
-    },
-    "_lscale": {
-      "__type__": "cc.Vec3",
-      "x": 1,
-      "y": 1,
-      "z": 1
-    },
-    "_mobility": 0,
-    "_layer": 1073741824,
-    "_euler": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "autoReleaseAssets": false,
-    "_globals": {
-      "__id__": 16
-    },
-    "_id": "ff354f0b-c2f5-4dea-8ffb-0152d175d11c"
-  },
-  {
-    "__type__": "cc.Node",
-    "_name": "Main Light",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_parent": {
-      "__id__": 1
-    },
-    "_children": [],
-    "_active": true,
-    "_components": [
-      {
-        "__id__": 3
-      }
-    ],
-    "_prefab": null,
-    "_lpos": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_lrot": {
-      "__type__": "cc.Quat",
-      "x": -0.06397656665577071,
-      "y": -0.44608233363525845,
-      "z": -0.8239028751062036,
-      "w": -0.3436591377065261
-    },
-    "_lscale": {
-      "__type__": "cc.Vec3",
-      "x": 1,
-      "y": 1,
-      "z": 1
-    },
-    "_mobility": 0,
-    "_layer": 1073741824,
-    "_euler": {
-      "__type__": "cc.Vec3",
-      "x": -117.894,
-      "y": -194.909,
-      "z": 38.562
-    },
-    "_id": "c0y6F5f+pAvI805TdmxIjx"
-  },
-  {
-    "__type__": "cc.DirectionalLight",
-    "_name": "",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "node": {
-      "__id__": 2
-    },
-    "_enabled": true,
-    "__prefab": null,
-    "_color": {
-      "__type__": "cc.Color",
-      "r": 255,
-      "g": 250,
-      "b": 240,
-      "a": 255
-    },
-    "_useColorTemperature": false,
-    "_colorTemperature": 6550,
-    "_staticSettings": {
-      "__id__": 4
-    },
-    "_visibility": -325058561,
-    "_illuminanceHDR": 65000,
-    "_illuminance": 65000,
-    "_illuminanceLDR": 1.6927083333333335,
-    "_shadowEnabled": false,
-    "_shadowPcf": 0,
-    "_shadowBias": 0.00001,
-    "_shadowNormalBias": 0,
-    "_shadowSaturation": 1,
-    "_shadowDistance": 50,
-    "_shadowInvisibleOcclusionRange": 200,
-    "_csmLevel": 4,
-    "_csmLayerLambda": 0.75,
-    "_csmOptimizationMode": 2,
-    "_csmAdvancedOptions": false,
-    "_csmLayersTransition": false,
-    "_csmTransitionRange": 0.05,
-    "_shadowFixedArea": false,
-    "_shadowNear": 0.1,
-    "_shadowFar": 10,
-    "_shadowOrthoSize": 5,
-    "_id": "597uMYCbhEtJQc0ffJlcgA"
-  },
-  {
-    "__type__": "cc.StaticLightSettings",
-    "_baked": false,
-    "_editorOnly": false,
-    "_castShadow": false
-  },
-  {
-    "__type__": "cc.Node",
-    "_name": "Main Camera",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_parent": {
-      "__id__": 1
-    },
-    "_children": [],
-    "_active": true,
-    "_components": [
-      {
-        "__id__": 6
-      }
-    ],
-    "_prefab": null,
-    "_lpos": {
-      "__type__": "cc.Vec3",
-      "x": -10,
-      "y": 10,
-      "z": 10
-    },
-    "_lrot": {
-      "__type__": "cc.Quat",
-      "x": -0.27781593346944056,
-      "y": -0.36497167621709875,
-      "z": -0.11507512748638377,
-      "w": 0.8811195706053617
-    },
-    "_lscale": {
-      "__type__": "cc.Vec3",
-      "x": 1,
-      "y": 1,
-      "z": 1
-    },
-    "_mobility": 0,
-    "_layer": 1073741824,
-    "_euler": {
-      "__type__": "cc.Vec3",
-      "x": -35,
-      "y": -45,
-      "z": 0
-    },
-    "_id": "c9DMICJLFO5IeO07EPon7U"
-  },
-  {
-    "__type__": "cc.Camera",
-    "_name": "",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "node": {
-      "__id__": 5
-    },
-    "_enabled": true,
-    "__prefab": null,
-    "_projection": 1,
-    "_priority": 0,
-    "_fov": 45,
-    "_fovAxis": 0,
-    "_orthoHeight": 10,
-    "_near": 1,
-    "_far": 1000,
-    "_color": {
-      "__type__": "cc.Color",
-      "r": 51,
-      "g": 51,
-      "b": 51,
-      "a": 255
-    },
-    "_depth": 1,
-    "_stencil": 0,
-    "_clearFlags": 14,
-    "_rect": {
-      "__type__": "cc.Rect",
-      "x": 0,
-      "y": 0,
-      "width": 1,
-      "height": 1
-    },
-    "_aperture": 19,
-    "_shutter": 7,
-    "_iso": 0,
-    "_screenScale": 1,
-    "_visibility": 1822425087,
-    "_targetTexture": null,
-    "_postProcess": null,
-    "_usePostProcess": false,
-    "_cameraType": -1,
-    "_trackingType": 0,
-    "_id": "7dWQTpwS5LrIHnc1zAPUtf"
-  },
-  {
-    "__type__": "cc.Node",
-    "_name": "GameWorld",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_parent": {
-      "__id__": 1
-    },
-    "_children": [],
-    "_active": true,
-    "_components": [],
-    "_prefab": null,
-    "_lpos": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_lrot": {
-      "__type__": "cc.Quat",
-      "x": 0,
-      "y": 0,
-      "z": 0,
-      "w": 1
-    },
-    "_lscale": {
-      "__type__": "cc.Vec3",
-      "x": 1,
-      "y": 1,
-      "z": 1
-    },
-    "_mobility": 0,
-    "_layer": 1073741824,
-    "_euler": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_id": "8b9QorrGZIl64tVv0Z0vRQ"
-  },
-  {
-    "__type__": "cc.Node",
-    "_name": "Canvas",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_parent": {
-      "__id__": 1
-    },
-    "_children": [
-      {
-        "__id__": 9
-      }
-    ],
-    "_active": true,
-    "_components": [
-      {
-        "__id__": 11
-      },
-      {
-        "__id__": 12
-      },
-      {
-        "__id__": 13
-      }
-    ],
-    "_prefab": null,
-    "_lpos": {
-      "__type__": "cc.Vec3",
-      "x": 640,
-      "y": 360,
-      "z": 0
-    },
-    "_lrot": {
-      "__type__": "cc.Quat",
-      "x": 0,
-      "y": 0,
-      "z": 0,
-      "w": 1
-    },
-    "_lscale": {
-      "__type__": "cc.Vec3",
-      "x": 1,
-      "y": 1,
-      "z": 1
-    },
-    "_mobility": 0,
-    "_layer": 1073741824,
-    "_euler": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_id": "4edRVPFLtIz5pR5edsryvx"
-  },
-  {
-    "__type__": "cc.Node",
-    "_name": "Camera",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_parent": {
-      "__id__": 8
-    },
-    "_children": [],
-    "_active": true,
-    "_components": [
-      {
-        "__id__": 10
-      }
-    ],
-    "_prefab": null,
-    "_lpos": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 1000
-    },
-    "_lrot": {
-      "__type__": "cc.Quat",
-      "x": 0,
-      "y": 0,
-      "z": 0,
-      "w": 1
-    },
-    "_lscale": {
-      "__type__": "cc.Vec3",
-      "x": 1,
-      "y": 1,
-      "z": 1
-    },
-    "_mobility": 0,
-    "_layer": 1073741824,
-    "_euler": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_id": "dfyZdh0bxJop4PyQrmHEP6"
-  },
-  {
-    "__type__": "cc.Camera",
-    "_name": "",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "node": {
-      "__id__": 9
-    },
-    "_enabled": true,
-    "__prefab": null,
-    "_projection": 0,
-    "_priority": 1073741824,
-    "_fov": 45,
-    "_fovAxis": 0,
-    "_orthoHeight": 360,
-    "_near": 1,
-    "_far": 2000,
-    "_color": {
-      "__type__": "cc.Color",
-      "r": 0,
-      "g": 0,
-      "b": 0,
-      "a": 255
-    },
-    "_depth": 1,
-    "_stencil": 0,
-    "_clearFlags": 6,
-    "_rect": {
-      "__type__": "cc.Rect",
-      "x": 0,
-      "y": 0,
-      "width": 1,
-      "height": 1
-    },
-    "_aperture": 19,
-    "_shutter": 7,
-    "_iso": 0,
-    "_screenScale": 1,
-    "_visibility": 41943040,
-    "_targetTexture": null,
-    "_postProcess": null,
-    "_usePostProcess": false,
-    "_cameraType": -1,
-    "_trackingType": 0,
-    "_id": "48lLOhLY5Onqokj70aNP+E"
-  },
-  {
-    "__type__": "cc.UITransform",
-    "_name": "",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "node": {
-      "__id__": 8
-    },
-    "_enabled": true,
-    "__prefab": null,
-    "_contentSize": {
-      "__type__": "cc.Size",
-      "width": 1280,
-      "height": 720
-    },
-    "_anchorPoint": {
-      "__type__": "cc.Vec2",
-      "x": 0.5,
-      "y": 0.5
-    },
-    "_id": "c3qBrLTLNImoltQDlZ6coz"
-  },
-  {
-    "__type__": "cc.Canvas",
-    "_name": "",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "node": {
-      "__id__": 8
-    },
-    "_enabled": true,
-    "__prefab": null,
-    "_cameraComponent": {
-      "__id__": 10
-    },
-    "_alignCanvasWithScreen": true,
-    "_id": "9d3SdE3ORAOZ6AG/imW6NO"
-  },
-  {
-    "__type__": "cc.Widget",
-    "_name": "",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "node": {
-      "__id__": 8
-    },
-    "_enabled": true,
-    "__prefab": null,
-    "_alignFlags": 45,
-    "_target": null,
-    "_left": 0,
-    "_right": 0,
-    "_top": 0,
-    "_bottom": 0,
-    "_horizontalCenter": 0,
-    "_verticalCenter": 0,
-    "_isAbsLeft": true,
-    "_isAbsRight": true,
-    "_isAbsTop": true,
-    "_isAbsBottom": true,
-    "_isAbsHorizontalCenter": true,
-    "_isAbsVerticalCenter": true,
-    "_originalWidth": 0,
-    "_originalHeight": 0,
-    "_alignMode": 2,
-    "_lockFlags": 0,
-    "_id": "4a8iJypC1J8pMml467hQ6c"
-  },
-  {
-    "__type__": "cc.Node",
-    "_name": "RTSDemo",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "_parent": {
-      "__id__": 1
-    },
-    "_children": [],
-    "_active": true,
-    "_components": [
-      {
-        "__id__": 15
-      }
-    ],
-    "_prefab": null,
-    "_lpos": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_lrot": {
-      "__type__": "cc.Quat",
-      "x": 0,
-      "y": 0,
-      "z": 0,
-      "w": 1
-    },
-    "_lscale": {
-      "__type__": "cc.Vec3",
-      "x": 1,
-      "y": 1,
-      "z": 1
-    },
-    "_mobility": 0,
-    "_layer": 1073741824,
-    "_euler": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 0,
-      "z": 0
-    },
-    "_id": "89cmsd2gNNsq155xC7mob8"
-  },
-  {
-    "__type__": "c33869Km+9Bb7dw/OyRztvE",
-    "_name": "",
-    "_objFlags": 0,
-    "__editorExtras__": {},
-    "node": {
-      "__id__": 14
-    },
-    "_enabled": true,
-    "__prefab": null,
-    "minerCount": 1,
-    "goldMineCount": 3,
-    "_id": "86AIY7iYlMNqJsDC/+LIMU"
-  },
-  {
-    "__type__": "cc.SceneGlobals",
-    "ambient": {
-      "__id__": 17
-    },
-    "shadows": {
-      "__id__": 18
-    },
-    "_skybox": {
-      "__id__": 19
-    },
-    "fog": {
-      "__id__": 20
-    },
-    "octree": {
-      "__id__": 21
-    },
-    "skin": {
-      "__id__": 22
-    },
-    "lightProbeInfo": {
-      "__id__": 23
-    },
-    "postSettings": {
-      "__id__": 24
-    },
-    "bakedWithStationaryMainLight": false,
-    "bakedWithHighpLightmap": false
-  },
-  {
-    "__type__": "cc.AmbientInfo",
-    "_skyColorHDR": {
-      "__type__": "cc.Vec4",
-      "x": 0.2,
-      "y": 0.5,
-      "z": 0.8,
-      "w": 0.520833125
-    },
-    "_skyColor": {
-      "__type__": "cc.Vec4",
-      "x": 0.2,
-      "y": 0.5,
-      "z": 0.8,
-      "w": 0.520833125
-    },
-    "_skyIllumHDR": 20000,
-    "_skyIllum": 20000,
-    "_groundAlbedoHDR": {
-      "__type__": "cc.Vec4",
-      "x": 0.2,
-      "y": 0.2,
-      "z": 0.2,
-      "w": 1
-    },
-    "_groundAlbedo": {
-      "__type__": "cc.Vec4",
-      "x": 0.2,
-      "y": 0.2,
-      "z": 0.2,
-      "w": 1
-    },
-    "_skyColorLDR": {
-      "__type__": "cc.Vec4",
-      "x": 0.452588,
-      "y": 0.607642,
-      "z": 0.755699,
-      "w": 0
-    },
-    "_skyIllumLDR": 0.8,
-    "_groundAlbedoLDR": {
-      "__type__": "cc.Vec4",
-      "x": 0.618555,
-      "y": 0.577848,
-      "z": 0.544564,
-      "w": 0
-    }
-  },
-  {
-    "__type__": "cc.ShadowsInfo",
-    "_enabled": false,
-    "_type": 0,
-    "_normal": {
-      "__type__": "cc.Vec3",
-      "x": 0,
-      "y": 1,
-      "z": 0
-    },
-    "_distance": 0,
-    "_planeBias": 1,
-    "_shadowColor": {
-      "__type__": "cc.Color",
-      "r": 76,
-      "g": 76,
-      "b": 76,
-      "a": 255
-    },
-    "_maxReceived": 4,
-    "_size": {
-      "__type__": "cc.Vec2",
-      "x": 1024,
-      "y": 1024
-    }
-  },
-  {
-    "__type__": "cc.SkyboxInfo",
-    "_envLightingType": 0,
-    "_envmapHDR": {
-      "__uuid__": "d032ac98-05e1-4090-88bb-eb640dcb5fc1@b47c0",
-      "__expectedType__": "cc.TextureCube"
-    },
-    "_envmap": {
-      "__uuid__": "d032ac98-05e1-4090-88bb-eb640dcb5fc1@b47c0",
-      "__expectedType__": "cc.TextureCube"
-    },
-    "_envmapLDR": {
-      "__uuid__": "6f01cf7f-81bf-4a7e-bd5d-0afc19696480@b47c0",
-      "__expectedType__": "cc.TextureCube"
-    },
-    "_diffuseMapHDR": null,
-    "_diffuseMapLDR": null,
-    "_enabled": true,
-    "_useHDR": true,
-    "_editableMaterial": null,
-    "_reflectionHDR": null,
-    "_reflectionLDR": null,
-    "_rotationAngle": 0
-  },
-  {
-    "__type__": "cc.FogInfo",
-    "_type": 0,
-    "_fogColor": {
-      "__type__": "cc.Color",
-      "r": 200,
-      "g": 200,
-      "b": 200,
-      "a": 255
-    },
-    "_enabled": false,
-    "_fogDensity": 0.3,
-    "_fogStart": 0.5,
-    "_fogEnd": 300,
-    "_fogAtten": 5,
-    "_fogTop": 1.5,
-    "_fogRange": 1.2,
-    "_accurate": false
-  },
-  {
-    "__type__": "cc.OctreeInfo",
-    "_enabled": false,
-    "_minPos": {
-      "__type__": "cc.Vec3",
-      "x": -1024,
-      "y": -1024,
-      "z": -1024
-    },
-    "_maxPos": {
-      "__type__": "cc.Vec3",
-      "x": 1024,
-      "y": 1024,
-      "z": 1024
-    },
-    "_depth": 8
-  },
-  {
-    "__type__": "cc.SkinInfo",
-    "_enabled": true,
-    "_blurRadius": 0.01,
-    "_sssIntensity": 3
-  },
-  {
-    "__type__": "cc.LightProbeInfo",
-    "_giScale": 1,
-    "_giSamples": 1024,
-    "_bounces": 2,
-    "_reduceRinging": 0,
-    "_showProbe": true,
-    "_showWireframe": true,
-    "_showConvex": false,
-    "_data": null,
-    "_lightProbeSphereVolume": 1
-  },
-  {
-    "__type__": "cc.PostSettingsInfo",
-    "_toneMappingType": 0
-  }
-]

extensions/cocos/cocos-ecs/assets/scenes/behaviour-example-scene.scene.meta

@@ -1,11 +0,0 @@
-{
-  "ver": "1.1.50",
-  "importer": "scene",
-  "imported": true,
-  "uuid": "ff354f0b-c2f5-4dea-8ffb-0152d175d11c",
-  "files": [
-    ".json"
-  ],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scenes/scene.scene.meta

@@ -1,11 +0,0 @@
-{
-  "ver": "1.1.50",
-  "importer": "scene",
-  "imported": true,
-  "uuid": "fcbf2917-6d43-4528-8829-7ee089594879",
-  "files": [
-    ".json"
-  ],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "1556cd72-9618-4f9f-b9e7-28152a33bde9",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/RTSDemo.ts

@@ -1,130 +0,0 @@
-import { _decorator, Component, Node, Vec3, Color } from 'cc';
-import { SimplePrefabFactory } from './components/SimplePrefabFactory';
-import { BehaviorTreeComponent } from './components/BehaviorTreeComponent';
-import { StatusUIManager } from './components/StatusUIManager';
-
-const { ccclass, property } = _decorator;
-
-/**
- * 矿工AI演示场景
- */
-@ccclass('SimpleMinerDemo')
-export class SimpleMinerDemo extends Component {
-    
-    @property
-    minerCount: number = 1;
-    
-    @property  
-    goldMineCount: number = 3;
-    
-    private miners: Node[] = [];
-    private goldMines: Node[] = [];
-    private warehouse: Node | null = null;
-    private ground: Node | null = null;
-    private totalOresCollected: number = 0;
-    private warehouseUI: any = null;
-    
-    start() {
-        this.createWorld();
-        this.createWarehouse();
-        this.createGoldMines();
-        this.createMiners();
-    }
-    
-    private createWorld() {
-        this.ground = SimplePrefabFactory.createGround(new Vec3(20, 0.2, 20));
-        this.node.addChild(this.ground);
-        this.ground.setWorldPosition(new Vec3(0, 0, 0));
-    }
-    
-    private createWarehouse() {
-        this.warehouse = SimplePrefabFactory.createBuilding('Warehouse', new Vec3(2, 2, 2), Color.GRAY);
-        this.node.addChild(this.warehouse);
-        this.warehouse.setWorldPosition(new Vec3(0, 1, 0));
-        this.createWarehouseUI();
-    }
-    
-    private createGoldMines() {
-        for (let i = 0; i < this.goldMineCount; i++) {
-            const angle = (i / this.goldMineCount) * Math.PI * 2;
-            const radius = 6 + Math.random() * 2;
-            const position = new Vec3(
-                Math.cos(angle) * radius,
-                0.8,
-                Math.sin(angle) * radius
-            );
-            
-            const goldMine = SimplePrefabFactory.createResource(`GoldMine_${i + 1}`, Color.YELLOW);
-            this.node.addChild(goldMine);
-            goldMine.setWorldPosition(position);
-            goldMine.setScale(new Vec3(1.2, 1.2, 1.2));
-            this.goldMines.push(goldMine);
-        }
-    }
-    
-    private createMiners() {
-        for (let i = 0; i < this.minerCount; i++) {
-            const angle = (i / this.minerCount) * Math.PI * 2;
-            const radius = 3;
-            const position = new Vec3(
-                Math.cos(angle) * radius,
-                1,
-                Math.sin(angle) * radius
-            );
-            
-            const miner = SimplePrefabFactory.createUnit(`Miner_${i + 1}`, Color.BLUE);
-            this.node.addChild(miner);
-            miner.setWorldPosition(position);
-            
-            const behaviorTree = miner.addComponent(BehaviorTreeComponent);
-            behaviorTree.behaviorTreeFile = 'miner-stamina-ai.bt';
-            behaviorTree.debugMode = true;
-            
-            this.scheduleOnce(() => {
-                const blackboard = behaviorTree.getBlackboard();
-                if (blackboard) {
-                    blackboard.setValue('homePosition', position.clone());
-                }
-            }, 0.5);
-            
-            this.miners.push(miner);
-        }
-    }
-    
-    public getAllGoldMines(): Node[] {
-        return this.goldMines.filter(mine => mine && mine.isValid);
-    }
-    
-    public getWarehouse(): Node | null {
-        return this.warehouse;
-    }
-    
-    public mineGoldOre(miner: Node): boolean {
-        this.totalOresCollected++;
-        this.updateWarehouseUI();
-        return true;
-    }
-    
-    public getTotalOresCollected(): number {
-        return this.totalOresCollected;
-    }
-    
-    private createWarehouseUI() {
-        if (!this.warehouse) return;
-        
-        this.warehouseUI = StatusUIManager.createWarehouseUI(this.warehouse);
-        if (this.warehouseUI) {
-            this.updateWarehouseUI();
-        }
-    }
-    
-    private updateWarehouseUI() {
-        if (this.warehouseUI && this.warehouseUI.warehouseCountLabel) {
-            this.warehouseUI.warehouseCountLabel.string = `🏭 总存储: ${this.totalOresCollected}`;
-        }
-    }
-    
-    onDestroy() {
-        this.unscheduleAllCallbacks();
-    }
-} 

extensions/cocos/cocos-ecs/assets/scripts/RTSDemo.ts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "c3386f4a-9bef-416f-b770-fcec91cedbc4",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/components.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "1.2.0",
-  "importer": "directory",
-  "imported": true,
-  "uuid": "d07d95ad-f180-4b6e-9d0a-7248e75ec795",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/components/BehaviorTreeComponent.ts

@@ -1,518 +0,0 @@
-import { Node, resources, JsonAsset, Component, _decorator, Vec3, tween, instantiate, Prefab } from 'cc';
-import { BehaviorTree, BehaviorTreeBuilder, Blackboard, TaskStatus, BehaviorTreeJSONConfig, EventRegistry, IBehaviorTreeContext, ActionResult } from '@esengine/ai';
-import { MinerStatusUI } from './MinerStatusUI';
-import { StatusUIManager } from './StatusUIManager';
-
-const { ccclass, property } = _decorator;
-
-@ccclass('BehaviorTreeComponent')
-export class BehaviorTreeComponent extends Component {
-
-    @property
-    behaviorTreeFile: string = '';
-
-    @property
-    autoStart: boolean = true;
-
-    @property
-    debugMode: boolean = false;
-
-    @property
-    showStatusUI: boolean = true;
-
-    @property(Prefab)
-    statusUIPrefab: Prefab | null = null;
-
-    private behaviorTree: BehaviorTree<any> | null = null;
-    private statusUI: MinerStatusUI | null = null;
-    private blackboard: Blackboard | null = null;
-    private context: any = null;
-    private eventRegistry: EventRegistry | null = null;
-    private isLoaded: boolean = false;
-    private isRunning: boolean = false;
-
-    private actionStates: Map<string, {
-        isExecuting: boolean;
-        startTime: number;
-        duration: number;
-    }> = new Map();
-
-    start() {
-        if (this.autoStart && this.behaviorTreeFile) {
-            this.initialize();
-        }
-
-        if (this.showStatusUI) {
-            this.createStatusUI();
-        }
-    }
-
-    async initialize() {
-        if (!this.behaviorTreeFile) {
-            return;
-        }
-
-        try {
-            await this.loadBehaviorTree();
-            this.isLoaded = true;
-            this.isRunning = true;
-        } catch (error) {
-            // 静默处理
-        }
-    }
-
-    private async loadBehaviorTree(): Promise<void> {
-        return new Promise((resolve, reject) => {
-            let jsonPath = this.behaviorTreeFile;
-            resources.load(jsonPath, JsonAsset, (err, asset) => {
-                if (err) {
-                    reject(err);
-                    return;
-                }
-
-                try {
-                    const treeData = asset.json as BehaviorTreeJSONConfig;
-                    this.buildBehaviorTree(treeData);
-                    resolve();
-                } catch (buildError) {
-                    reject(buildError);
-                }
-            });
-        });
-    }
-
-    private buildBehaviorTree(treeData: BehaviorTreeJSONConfig) {
-        this.eventRegistry = new EventRegistry();
-        this.setupEventHandlers();
-
-        const baseContext = {
-            node: this.node,
-            component: this,
-            eventRegistry: this.eventRegistry
-        };
-
-        const result = BehaviorTreeBuilder.fromBehaviorTreeConfig(treeData, baseContext);
-        this.behaviorTree = result.tree;
-        this.blackboard = result.blackboard;
-        this.context = result.context;
-
-        this.initializeBlackboard();
-    }
-
-    private setupEventHandlers() {
-        if (!this.eventRegistry) return;
-
-        this.eventRegistry.registerAction('go-home-rest', (context, params) => {
-            return this.handleGoHomeRest(context, params);
-        });
-
-        this.eventRegistry.registerAction('recover-stamina', (context, params) => {
-            return this.handleRecoverStamina(context, params);
-        });
-
-        this.eventRegistry.registerAction('store-ore', (context, params) => {
-            return this.handleStoreOre(context, params);
-        });
-
-        this.eventRegistry.registerAction('mine-gold-ore', (context, params) => {
-            return this.handleMineGoldOre(context, params);
-        });
-
-        this.eventRegistry.registerAction('idle-behavior', (context, params) => {
-            return this.handleIdleBehavior(context, params);
-        });
-    }
-
-    private initializeBlackboard() {
-        if (!this.blackboard) return;
-
-        this.blackboard.setValue('stamina', 100);
-        this.blackboard.setValue('staminaPercentage', 1.0);
-        this.blackboard.setValue('isLowStamina', false);
-        this.blackboard.setValue('hasOre', false);
-        this.blackboard.setValue('isResting', false);
-        this.blackboard.setValue('homePosition', this.node.worldPosition);
-    }
-
-
-    private createStatusUI() {
-        if (!this.statusUIPrefab) {
-            this.createSimpleStatusUI();
-            return;
-        }
-
-        const uiNode = instantiate(this.statusUIPrefab);
-        const canvas = this.node.scene?.getChildByName('Canvas');
-        if (canvas) {
-            canvas.addChild(uiNode);
-            this.statusUI = uiNode.getComponent(MinerStatusUI);
-            if (this.statusUI) {
-                this.statusUI.setFollowTarget(this.node);
-            }
-        }
-    }
-
-    private createSimpleStatusUI() {
-        this.statusUI = StatusUIManager.createStatusUIForMiner(this.node);
-    }
-
-    private updateStatusUI() {
-        if (!this.statusUI || !this.blackboard) return;
-
-        const stamina = this.blackboard.getValue('stamina') || 0;
-        const maxStamina = this.blackboard.getValue('maxStamina') || 100;
-        const hasOre = this.blackboard.getValue('hasOre') || false;
-        const isResting = this.blackboard.getValue('isResting') || false;
-
-        // 更新体力
-        this.statusUI.updateStamina(stamina, maxStamina);
-
-        // 更新状态文本
-        let status = '';
-        if (isResting) {
-            status = '😴休息中';
-        } else if (hasOre) {
-            status = '🚚运输中';
-        } else {
-            status = '⛏️挖矿中';
-        }
-        this.statusUI.updateStatus(status);
-
-        // 获取仓库矿石总数
-        const gameManager = this.node.parent?.getComponent('SimpleMinerDemo');
-        const warehouseTotal = (gameManager as any)?.getTotalOresCollected() || 0;
-
-        // 更新矿石数量显示
-        this.statusUI.updateOreCount(hasOre, warehouseTotal);
-
-        // 更新动作进度
-        this.updateActionProgressUI();
-    }
-
-    private updateActionProgressUI() {
-        if (!this.statusUI) return;
-
-        let actionName = '';
-        let progress = 0;
-
-        // 检查当前正在执行的动作
-        for (const [key, state] of this.actionStates.entries()) {
-            if (state.isExecuting) {
-                const elapsed = Date.now() - state.startTime;
-                progress = Math.min(elapsed / state.duration, 1.0);
-
-                switch (key) {
-                    case 'mine-gold-ore':
-                        actionName = '⛏️ 挖掘中';
-                        break;
-                    case 'store-ore':
-                        actionName = '📦 存储中';
-                        break;
-                    case 'recover-stamina':
-                        actionName = '💤 恢复体力';
-                        break;
-                    default:
-                        actionName = key;
-                }
-                break; // 只显示第一个正在执行的动作
-            }
-        }
-
-        // 如果没有正在执行的动作，清空进度显示
-        this.statusUI.updateActionProgress(actionName, progress);
-    }
-
-    // ==================== 行为树事件处理器 ====================
-
-    /**
-     * 清理动作状态 - 当动作被中止时调用
-     */
-    private clearActionState(actionKey: string) {
-        if (this.actionStates.has(actionKey)) {
-            this.actionStates.delete(actionKey);
-
-        }
-    }
-
-    /**
-     * 回家休息 - 包含体力恢复逻辑
-     */
-    private handleGoHomeRest(context: any, params: any): ActionResult {
-        const blackboard = this.blackboard;
-        if (!blackboard) return 'failure';
-
-        // 检查是否已经在家了
-        const homePos = blackboard.getValue('homePosition') || this.node.worldPosition;
-        const distance = Vec3.distance(this.node.worldPosition, homePos);
-
-
-
-        if (distance > 1.0) {
-            // 还没到家，继续移动
-            this.moveToPosition(homePos, 2.0);
-            return 'running';
-        } else {
-            this.clearActionState('mine-gold-ore');
-            this.clearActionState('store-ore');
-            blackboard.setValue('isResting', true);
-            const actionKey = 'go-home-rest';
-            const currentTime = Date.now();
-
-            // 初始化休息状态
-            if (!this.actionStates.has(actionKey)) {
-                this.actionStates.set(actionKey, {
-                    isExecuting: true,
-                    startTime: currentTime,
-                    duration: 2000 // 2秒恢复一次
-                });
-                return 'running';
-            }
-
-            const actionState = this.actionStates.get(actionKey)!;
-            const elapsed = currentTime - actionState.startTime;
-
-            if (elapsed >= actionState.duration) {
-                const currentStamina = blackboard.getValue('stamina');
-                const newStamina = Math.min(100, currentStamina + 10);
-
-                blackboard.setValue('stamina', newStamina);
-                blackboard.setValue('staminaPercentage', newStamina / 100);
-
-                if (newStamina >= 80) {
-                    blackboard.setValue('isResting', false);
-                    blackboard.setValue('isLowStamina', false);
-                    this.actionStates.delete(actionKey);
-                    return 'success';
-                }
-
-                actionState.startTime = currentTime;
-            }
-
-            return 'running';
-        }
-    }
-
-    private handleRecoverStamina(context: any, params: any): ActionResult {
-        return 'success';
-    }
-
-    private handleMineGoldOre(context: any, params: any): ActionResult {
-        const blackboard = this.blackboard;
-        if (!blackboard) return 'failure';
-
-        const hasOre = blackboard.getValue('hasOre');
-        const isLowStamina = blackboard.getValue('isLowStamina');
-        const isResting = blackboard.getValue('isResting');
-
-        if (hasOre || isLowStamina || isResting) {
-            return 'failure';
-        }
-
-        const gameManager = this.node.parent?.getComponent('SimpleMinerDemo');
-        const goldMines = (gameManager as any)?.getAllGoldMines();
-        if (!goldMines?.length) return 'failure';
-
-        let nearestMine = goldMines[0];
-        let minDistance = Vec3.distance(this.node.worldPosition, nearestMine.worldPosition);
-
-        for (const mine of goldMines) {
-            const distance = Vec3.distance(this.node.worldPosition, mine.worldPosition);
-            if (distance < minDistance) {
-                minDistance = distance;
-                nearestMine = mine;
-            }
-        }
-
-        if (minDistance > 2.0) {
-            this.moveToPosition(nearestMine.worldPosition, 2.0);
-            return 'running';
-        } else {
-            const actionKey = 'mine-gold-ore';
-            const currentTime = Date.now();
-
-            if (!this.actionStates.has(actionKey)) {
-                this.actionStates.set(actionKey, {
-                    isExecuting: true,
-                    startTime: currentTime,
-                    duration: 3000
-                });
-                return 'running';
-            }
-
-            const actionState = this.actionStates.get(actionKey)!;
-            const elapsed = currentTime - actionState.startTime;
-
-            if (elapsed >= actionState.duration) {
-                const currentStamina = blackboard.getValue('stamina');
-                const newStamina = Math.max(0, currentStamina - 15);
-
-                blackboard.setValue('stamina', newStamina);
-                blackboard.setValue('staminaPercentage', newStamina / 100);
-                blackboard.setValue('hasOre', true);
-                blackboard.setValue('isLowStamina', newStamina < 20);
-
-                this.actionStates.delete(actionKey);
-                return 'failure';
-            }
-
-            return 'running';
-        }
-    }
-
-    private handleStoreOre(context: any, params: any): ActionResult {
-        const blackboard = this.blackboard;
-        if (!blackboard) return 'failure';
-
-        const hasOre = blackboard.getValue('hasOre');
-        if (!hasOre) {
-            return 'failure';
-        }
-
-        const isLowStamina = blackboard.getValue('isLowStamina');
-        if (isLowStamina) {
-            return 'failure';
-        }
-
-        this.clearActionState('mine-gold-ore');
-        const gameManager = this.node.parent?.getComponent('SimpleMinerDemo');
-        const warehouse = (gameManager as any)?.getWarehouse();
-        if (!warehouse) return 'failure';
-
-        const distance = Vec3.distance(this.node.worldPosition, warehouse.worldPosition);
-
-        if (distance > 2.0) {
-            this.moveToPosition(warehouse.worldPosition, 2.0);
-            return 'running';
-        } else {
-            const actionKey = 'store-ore';
-            const currentTime = Date.now();
-
-            if (!this.actionStates.has(actionKey)) {
-                this.actionStates.set(actionKey, {
-                    isExecuting: true,
-                    startTime: currentTime,
-                    duration: 1500
-                });
-                return 'running';
-            }
-
-            const actionState = this.actionStates.get(actionKey)!;
-            const elapsed = currentTime - actionState.startTime;
-
-            if (elapsed >= actionState.duration) {
-                blackboard.setValue('hasOre', false);
-                (gameManager as any).mineGoldOre(this.node);
-                this.actionStates.delete(actionKey);
-                return 'success';
-            }
-
-            return 'running';
-        }
-    }
-
-    private handleIdleBehavior(context: any, params: any): ActionResult {
-        return 'success';
-    }
-
-    private moveToPosition(targetPos: Vec3, duration: number) {
-        tween(this.node).stop();
-        tween(this.node).to(duration, { worldPosition: targetPos }).start();
-    }
-
-    update(deltaTime: number) {
-        if (this.behaviorTree && this.isRunning) {
-            this.behaviorTree.tick(deltaTime);
-        }
-
-        if (this.showStatusUI) {
-            this.updateStatusUI();
-        }
-    }
-
-    /**
-     * 获取黑板
-     */
-    getBlackboard(): Blackboard | null {
-        return this.blackboard;
-    }
-
-    /**
-     * 获取行为树
-     */
-    getBehaviorTree(): BehaviorTree<any> | null {
-        return this.behaviorTree;
-    }
-
-    /**
-     * 暂停行为树
-     */
-    pause() {
-        this.isRunning = false;
-        if (this.debugMode) {
-
-        }
-    }
-
-    /**
-     * 恢复行为树
-     */
-    resume() {
-        if (this.isLoaded) {
-            this.isRunning = true;
-            if (this.debugMode) {
-
-            }
-        }
-    }
-
-    /**
-     * 停止行为树
-     */
-    stop() {
-        this.isRunning = false;
-        if (this.behaviorTree) {
-            this.behaviorTree.reset();
-        }
-        if (this.debugMode) {
-
-        }
-    }
-
-    /**
-     * 重新加载行为树
-     */
-    async reload() {
-        this.stop();
-        await this.initialize();
-    }
-
-    /**
-     * 重置行为树状态
-     */
-    reset() {
-        if (this.behaviorTree) {
-            this.behaviorTree.reset();
-        }
-        if (this.debugMode) {
-
-        }
-    }
-
-    onDestroy() {
-        this.stop();
-        if (this.eventRegistry) {
-            this.eventRegistry.clear();
-        }
-
-        // 清理UI
-        if (this.statusUI) {
-            this.statusUI.node.destroy();
-            this.statusUI = null;
-        }
-
-        this.behaviorTree = null;
-        this.blackboard = null;
-        this.context = null;
-        this.eventRegistry = null;
-    }
-} 

extensions/cocos/cocos-ecs/assets/scripts/components/BehaviorTreeComponent.ts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "8efd182b-9891-4903-bef2-eb07b5184263",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/components/BehaviorTreeManager.ts

@@ -1,299 +0,0 @@
-import { _decorator, Component, resources, JsonAsset, Vec3 } from 'cc';
-import { BehaviorTree, BehaviorTreeBuilder, Blackboard, BehaviorTreeJSONConfig, ExecutionContext, EventRegistry, ActionResult } from '@esengine/ai';
-import { UnitController } from './UnitController';
-import { RTSBehaviorHandler } from './RTSBehaviorHandler';
-
-const { ccclass, property } = _decorator;
-
-/**
- * 游戏执行上下文接口
- * 继承框架的ExecutionContext，添加游戏特定的属性
- */
-interface GameExecutionContext extends ExecutionContext {
-    unitController: UnitController;
-    gameObject: any;
-    eventRegistry?: EventRegistry;
-    // 确保继承索引签名
-    [key: string]: unknown;
-}
-
-/**
- * 行为树管理器 - 使用@esengine/ai包管理行为树
- */
-@ccclass('BehaviorTreeManager')
-export class BehaviorTreeManager extends Component {
-    
-    @property
-    debugMode: boolean = true;
-    
-    @property
-    tickInterval: number = 0.1; // 行为树更新间隔（秒）- 10fps更新频率，平衡性能和响应性
-    
-    private behaviorTree: BehaviorTree<GameExecutionContext> | null = null;
-    private blackboard: Blackboard | null = null;
-    private context: GameExecutionContext | null = null;
-    private eventRegistry: EventRegistry | null = null;
-    private isLoaded: boolean = false;
-    private isRunning: boolean = false;
-    private lastTickTime: number = 0;
-    private unitController: UnitController | null = null;
-    private currentBehaviorTreeName: string = '';
-    private behaviorHandler: RTSBehaviorHandler | null = null;
-    
-    /**
-     * 初始化行为树
-     */
-    async initializeBehaviorTree(behaviorTreeName: string, unitController: UnitController) {
-        this.currentBehaviorTreeName = behaviorTreeName;
-        this.unitController = unitController;
-        
-        // 获取RTSBehaviorHandler组件
-        this.behaviorHandler = this.getComponent(RTSBehaviorHandler);
-        if (!this.behaviorHandler) {
-            console.error(`BehaviorTreeManager: 未找到RTSBehaviorHandler组件 - ${this.node.name}`);
-            return;
-        }
-        
-        try {
-            await this.loadBehaviorTree(behaviorTreeName);
-            this.setupBlackboard();
-            this.isLoaded = true;
-            this.isRunning = true;
-
-        } catch (error) {
-            console.error(`行为树初始化失败: ${behaviorTreeName}`, error);
-        }
-    }
-    
-    /**
-     * 加载行为树文件
-     */
-    private async loadBehaviorTree(behaviorTreeName: string): Promise<void> {
-        return new Promise((resolve, reject) => {
-            const jsonPath = `${behaviorTreeName}.bt`;
-    
-            
-            resources.load(jsonPath, JsonAsset, (err, asset) => {
-                if (err) {
-                    console.error(`加载行为树文件失败: ${jsonPath}`, err);
-                    reject(err);
-                    return;
-                }
-                
-                try {
-                    const behaviorTreeData = asset.json as BehaviorTreeJSONConfig;
-                    
-                    // 创建执行上下文
-                    this.blackboard = new Blackboard();
-                    this.eventRegistry = this.createEventRegistry();
-                    this.context = {
-                        blackboard: this.blackboard,
-                        unitController: this.unitController!,
-                        gameObject: this.node,
-                        eventRegistry: this.eventRegistry
-                    } as GameExecutionContext;
-                    
-                    // 从JSON数据创建行为树
-                    const buildResult = BehaviorTreeBuilder.fromBehaviorTreeConfig<GameExecutionContext>(behaviorTreeData, this.context);
-                    this.behaviorTree = buildResult.tree;
-                    this.blackboard = buildResult.blackboard;
-                    
-                    resolve();
-                } catch (parseError) {
-                    console.error(`创建行为树失败: ${jsonPath}`, parseError);
-                    reject(parseError);
-                }
-            });
-        });
-    }
-    
-    /**
-     * 创建事件注册表
-     */
-    private createEventRegistry(): EventRegistry {
-        const registry = new EventRegistry();
-        
-        // 注册体力系统矿工行为事件处理器
-        const eventHandlers = {
-            // 矿工体力系统核心行为
-            'mine-gold-ore': (context: any, params?: any) => this.callBehaviorHandler('onMineGoldOre', params),
-            'store-ore': (context: any, params?: any) => this.callBehaviorHandler('onStoreOre', params),
-            'go-home-rest': (context: any, params?: any) => this.callBehaviorHandler('onGoHomeRest', params),
-            'recover-stamina': (context: any, params?: any) => this.callBehaviorHandler('onRecoverStamina', params),
-            'idle-behavior': (context: any, params?: any) => this.callBehaviorHandler('onIdleBehavior', params)
-        };
-        
-        // 将事件处理器注册到EventRegistry
-        Object.entries(eventHandlers).forEach(([eventName, handler]) => {
-            registry.registerAction(eventName, handler);
-        });
-        
-        return registry;
-    }
-    
-    /**
-     * 调用行为处理器的方法
-     */
-    private callBehaviorHandler(methodName: string, params: any = {}): ActionResult {
-        if (!this.behaviorHandler) {
-            console.error(`BehaviorTreeManager: RTSBehaviorHandler未初始化 - ${this.node.name}`);
-            return 'failure';
-        }
-        
-        try {
-            // 直接调用RTSBehaviorHandler的方法
-            const method = (this.behaviorHandler as any)[methodName];
-            if (typeof method === 'function') {
-                const result = method.call(this.behaviorHandler, params);
-                return result || 'success'; // 确保有返回值
-            } else {
-                console.error(`BehaviorTreeManager: 方法不存在: ${methodName}`);
-                return 'failure';
-            }
-        } catch (error) {
-            console.error(`BehaviorTreeManager: 调用方法失败: ${methodName}`, error);
-            return 'failure';
-        }
-    }
-    
-    /**
-     * 设置黑板基础信息
-     */
-    private setupBlackboard() {
-        if (!this.unitController || !this.blackboard) return;
-        
-        // 设置矿工基础信息
-        this.blackboard.setValue('unitType', this.unitController.unitType);
-        this.blackboard.setValue('currentHealth', this.unitController.currentHealth);
-        this.blackboard.setValue('maxHealth', this.unitController.maxHealth);
-        this.blackboard.setValue('currentCommand', 'mine');
-        this.blackboard.setValue('hasOre', false);
-        this.blackboard.setValue('hasTarget', false);
-        this.blackboard.setValue('targetPosition', null);
-        this.blackboard.setValue('isMoving', false);
-        
-        // 设置体力系统信息
-        this.blackboard.setValue('stamina', this.unitController.currentStamina);
-        this.blackboard.setValue('maxStamina', this.unitController.maxStamina);
-        this.blackboard.setValue('staminaPercentage', this.unitController.currentStamina / this.unitController.maxStamina);
-        this.blackboard.setValue('isLowStamina', this.unitController.currentStamina < this.unitController.maxStamina * 0.2);
-        this.blackboard.setValue('isResting', false);
-        this.blackboard.setValue('homePosition', this.unitController.homePosition);
-    }
-    
-    /**
-     * 更新黑板值
-     */
-    updateBlackboardValue(key: string, value: any) {
-        if (this.blackboard) {
-            this.blackboard.setValue(key, value);
-        }
-    }
-    
-    /**
-     * 获取黑板值
-     */
-    getBlackboardValue(key: string): any {
-        return this.blackboard?.getValue(key);
-    }
-    
-    /**
-     * 获取黑板
-     */
-    getBlackboard(): Blackboard | null {
-        return this.blackboard;
-    }
-    
-    /**
-     * 获取行为树
-     */
-    getBehaviorTree(): BehaviorTree<GameExecutionContext> | null {
-        return this.behaviorTree;
-    }
-    
-    /**
-     * 更新行为树
-     */
-    update(deltaTime: number) {
-        if (!this.isLoaded || !this.isRunning || !this.behaviorTree || !this.blackboard) return;
-        
-        // 控制更新频率
-        this.lastTickTime += deltaTime;
-        if (this.lastTickTime < this.tickInterval) return;
-        
-        this.lastTickTime = 0;
-        
-        // 更新矿工状态信息
-        if (this.unitController) {
-            // 基础属性
-            this.blackboard.setValue('currentHealth', this.unitController.currentHealth);
-            this.blackboard.setValue('currentCommand', this.unitController.currentCommand);
-            this.blackboard.setValue('hasTarget', this.unitController.targetPosition && !this.unitController.targetPosition.equals(Vec3.ZERO));
-            this.blackboard.setValue('targetPosition', this.unitController.targetPosition);
-            this.blackboard.setValue('isMoving', this.unitController.targetPosition && !this.unitController.targetPosition.equals(Vec3.ZERO));
-            
-            // 体力系统状态
-            this.blackboard.setValue('stamina', this.unitController.currentStamina);
-            this.blackboard.setValue('maxStamina', this.unitController.maxStamina);
-            this.blackboard.setValue('staminaPercentage', this.unitController.currentStamina / this.unitController.maxStamina);
-            this.blackboard.setValue('isLowStamina', this.unitController.currentStamina < this.unitController.maxStamina * 0.2);
-            this.blackboard.setValue('homePosition', this.unitController.homePosition);
-        }
-        
-        // 执行行为树
-        try {
-            this.behaviorTree.tick(deltaTime);
-        } catch (error) {
-            console.error(`行为树执行错误: ${this.node.name}`, error);
-        }
-    }
-    
-    /**
-     * 暂停行为树
-     */
-    pause() {
-        this.isRunning = false;
-    }
-    
-    /**
-     * 恢复行为树
-     */
-    resume() {
-        if (this.isLoaded) {
-            this.isRunning = true;
-        }
-    }
-    
-    /**
-     * 停止行为树
-     */
-    stop() {
-        this.isRunning = false;
-    }
-    
-    /**
-     * 重新加载行为树
-     */
-    async reloadBehaviorTree() {
-        if (this.currentBehaviorTreeName && this.unitController) {
-            this.stop();
-            await this.initializeBehaviorTree(this.currentBehaviorTreeName, this.unitController);
-        }
-    }
-    
-    /**
-     * 重置行为树
-     */
-    reset() {
-        if (this.behaviorTree) {
-            this.behaviorTree.reset();
-        }
-    }
-    
-    onDestroy() {
-        this.stop();
-        this.behaviorTree = null;
-        this.blackboard = null;
-        this.context = null;
-    }
-} 

extensions/cocos/cocos-ecs/assets/scripts/components/BehaviorTreeManager.ts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "891c88fc-282d-4791-a961-8d85244bfee7",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/components/MinerStatusUI.ts

@@ -1,130 +0,0 @@
-import { Component, _decorator, Label, ProgressBar, Node, UITransform, Canvas, find, Camera, Vec3, director, Color, Layers, Graphics } from 'cc';
-
-const { ccclass, property } = _decorator;
-
-/**
- * 矿工状态UI组件
- */
-@ccclass('MinerStatusUI')
-export class MinerStatusUI extends Component {
-    
-    nameLabel: Label | null = null;
-    statusLabel: Label | null = null;
-    staminaBar: ProgressBar | null = null;
-    actionProgressBar: ProgressBar | null = null;
-    actionLabel: Label | null = null;
-    oreCountLabel: Label | null = null;
-    warehouseCountLabel: Label | null = null;
-    
-    @property
-    followTarget: Node | null = null;
-    
-    @property
-    yOffset: number = 100;
-    
-    private camera: Camera | null = null;
-    private canvas: Canvas | null = null;
-    
-    start() {
-        this.node.layer = Layers.Enum.UI_2D;
-        
-        this.camera = find('Main Camera')?.getComponent(Camera) || director.getScene()?.getComponentInChildren(Camera);
-        this.canvas = find('Canvas')?.getComponent(Canvas) || director.getScene()?.getComponentInChildren(Canvas);
-        
-
-        
-        if (this.nameLabel && this.followTarget) {
-            this.nameLabel.string = this.followTarget.name;
-        }
-        
-        this.updateStamina(100, 100);
-        this.updateStatus('待机中');
-        this.updateActionProgress('', 0);
-    }
-    
-    update() {
-        if (this.followTarget && this.camera && this.canvas) {
-            this.updateUIPosition();
-        }
-    }
-    
-    private updateUIPosition() {
-        if (!this.followTarget || !this.camera || !this.canvas) return;
-        
-        const targetWorldPos = this.followTarget.worldPosition.clone();
-        // 根据目标类型设置不同的Y偏移
-        if (this.followTarget.name.includes('Warehouse')) {
-            targetWorldPos.y += 3.0; // 仓库偏移更高
-        } else {
-            targetWorldPos.y += 2.0; // 矿工偏移
-        }
-        
-        // 将世界坐标直接转换为UI坐标
-        const uiPos = new Vec3();
-        this.camera.convertToUINode(targetWorldPos, this.canvas.node, uiPos);
-        this.node.setPosition(uiPos);
-    }
-    
-    setFollowTarget(target: Node) {
-        this.followTarget = target;
-        if (this.nameLabel) {
-            this.nameLabel.string = target.name;
-        }
-    }
-    
-    updateStamina(current: number, max: number) {
-        if (this.staminaBar) {
-            this.staminaBar.progress = current / max;
-        }
-        
-        if (this.staminaBar) {
-            const percentage = current / max;
-            const fillNode = this.staminaBar.node.getChildByName('Bar');
-            if (fillNode) {
-                const graphics = fillNode.getComponent(Graphics);
-                if (graphics) {
-                    let color: Color;
-                    if (percentage > 0.6) {
-                        color = new Color(0, 255, 0, 255);
-                    } else if (percentage > 0.3) {
-                        color = new Color(255, 255, 0, 255);
-                    } else {
-                        color = new Color(255, 0, 0, 255);
-                    }
-                    
-                    graphics.clear();
-                    graphics.fillColor = color;
-                    graphics.rect(-75, -4, 150 * percentage, 8);
-                    graphics.fill();
-                }
-            }
-        }
-    }
-    
-    updateStatus(status: string) {
-        if (this.statusLabel) {
-            this.statusLabel.string = status;
-        }
-    }
-    
-    updateActionProgress(actionName: string, progress: number) {
-        if (this.actionLabel) {
-            this.actionLabel.string = actionName;
-        }
-        
-        if (this.actionProgressBar) {
-            this.actionProgressBar.progress = Math.max(0, Math.min(1, progress));
-            this.actionProgressBar.node.active = actionName !== '' && progress > 0;
-        }
-    }
-    
-    setVisible(visible: boolean) {
-        this.node.active = visible;
-    }
-    
-    updateOreCount(hasOre: boolean, warehouseTotal: number) {
-        if (this.oreCountLabel) {
-            this.oreCountLabel.string = hasOre ? '💎1' : '💎0';
-        }
-    }
-} 

extensions/cocos/cocos-ecs/assets/scripts/components/MinerStatusUI.ts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "5f877c25-5c26-49c6-bbb5-7ff36323e0a1",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/components/RTSBehaviorHandler.ts

@@ -1,334 +0,0 @@
-import { _decorator, Component, Vec3, Node } from 'cc';
-import { UnitController } from './UnitController';
-
-const { ccclass } = _decorator;
-
-/**
- * 矿工体力系统行为处理器 - 处理挖矿、休息、存储的完整循环
- * 展示体力驱动的工作-休息循环系统
- */
-@ccclass('RTSBehaviorHandler')
-export class RTSBehaviorHandler extends Component {
-    
-    private unitController: UnitController | null = null;
-    private minerDemo: any = null; // MinerDemo组件引用
-    private lastActionTime: number = 0;
-    private actionCooldown: number = 0.5; // 动作冷却时间，避免频繁切换
-    private minerIndex: number = -1; // 矿工索引，用于找到对应的家
-    
-    start() {
-        this.unitController = this.getComponent(UnitController);
-        // 获取场景中的MinerDemo组件
-        this.minerDemo = this.node.parent?.getComponent('MinerDemo');
-        
-        if (!this.unitController) {
-            console.error('RTSBehaviorHandler: 未找到UnitController组件');
-        }
-        if (!this.minerDemo) {
-            console.error('RTSBehaviorHandler: 未找到MinerDemo组件');
-        }
-        
-        // 从节点名称中提取矿工索引
-        const match = this.node.name.match(/Miner_(\d+)/);
-        if (match) {
-            this.minerIndex = parseInt(match[1]) - 1; // 转换为0基索引
-        }
-        
-        this.lastActionTime = Date.now();
-    }
-    
-    /**
-     * 检查动作冷却
-     */
-    private isActionOnCooldown(): boolean {
-        return (Date.now() - this.lastActionTime) < (this.actionCooldown * 1000);
-    }
-    
-    /**
-     * 更新动作时间
-     */
-    private updateActionTime() {
-        this.lastActionTime = Date.now();
-    }
-    
-    /**
-     * 挖掘金矿（永不枯竭）
-     * @param params 事件参数，包含黑板变量值
-     */
-    onMineGoldOre(params: any = {}): string {
-        if (!this.unitController || !this.minerDemo) {
-            return 'failure';
-        }
-        
-        // 检查体力是否充足
-        if (this.unitController.currentStamina < this.unitController.staminaCostPerMining) {
-            return 'failure';
-        }
-        
-        // 检查是否已经携带矿石
-        const hasOre = this.unitController.getBlackboardValue('hasOre');
-        if (hasOre) {
-            return 'failure';
-        }
-        
-        // 动作冷却检查
-        if (this.isActionOnCooldown()) {
-            return 'running';
-        }
-        
-        // 获取所有金矿
-        const goldMines = this.minerDemo.getAllGoldMines();
-        if (goldMines.length === 0) {
-            return 'failure';
-        }
-        
-        // 寻找最近的金矿
-        const currentPos = this.node.worldPosition;
-        let nearestMine: Node | null = null;
-        let minDistance = Infinity;
-        
-        for (const mine of goldMines) {
-            if (!mine || !mine.isValid) continue;
-            
-            const distance = Vec3.distance(currentPos, mine.worldPosition);
-            if (distance < minDistance) {
-                minDistance = distance;
-                nearestMine = mine;
-            }
-        }
-        
-        if (!nearestMine) {
-            return 'failure';
-        }
-        
-        // 检查是否已经到达金矿位置
-        if (minDistance < 2.0) {
-            // 检查是否正在移动
-            const isMoving = this.unitController.getBlackboardValue('isMoving');
-            if (isMoving) {
-                return 'running';
-            }
-            
-            // 消耗体力
-            this.unitController.currentStamina = Math.max(0, this.unitController.currentStamina - this.unitController.staminaCostPerMining);
-            
-            // 设置携带矿石状态
-            this.unitController.setBlackboardValue('hasOre', true);
-            
-            // 通知演示管理器
-            this.minerDemo.mineGoldOre(this.node);
-            
-            // 清除移动目标
-            this.unitController.clearTarget();
-            this.unitController.setBlackboardValue('isMoving', false);
-            
-            this.updateActionTime();
-            return 'success';
-        } else {
-            // 设置移动目标
-            this.unitController.setTarget(nearestMine.worldPosition);
-            return 'running';
-        }
-    }
-    
-    /**
-     * 前往仓库存储矿石
-     * @param params 事件参数，包含黑板变量值
-     */
-    onStoreOre(params: any = {}): string {
-        if (!this.unitController || !this.minerDemo) {
-            return 'failure';
-        }
-        
-        // 检查是否携带矿石
-        const hasOre = this.unitController.getBlackboardValue('hasOre');
-        if (!hasOre) {
-            return 'failure';
-        }
-        
-        // 动作冷却检查
-        if (this.isActionOnCooldown()) {
-            return 'running';
-        }
-        
-        const warehouse = this.minerDemo.getWarehouse();
-        if (!warehouse || !warehouse.isValid) {
-            return 'failure';
-        }
-        
-        // 计算到仓库的距离
-        const currentPos = this.node.worldPosition;
-        const warehousePos = warehouse.worldPosition;
-        const distance = Vec3.distance(currentPos, warehousePos);
-        
-        // 检查是否已经到达仓库
-        if (distance < 2.5) {
-            // 检查是否正在移动
-            const isMoving = this.unitController.getBlackboardValue('isMoving');
-            if (isMoving) {
-                return 'running';
-            }
-            
-            // 清除携带矿石状态
-            this.unitController.setBlackboardValue('hasOre', false);
-            
-            // 清除移动目标
-            this.unitController.clearTarget();
-            this.unitController.setBlackboardValue('isMoving', false);
-            
-            this.updateActionTime();
-            return 'success';
-        } else {
-            // 设置移动目标
-            this.unitController.setTarget(warehousePos);
-            return 'running';
-        }
-    }
-    
-    /**
-     * 回家休息
-     * @param params 事件参数，包含黑板变量值
-     */
-    onGoHomeRest(params: any = {}): string {
-        if (!this.unitController || !this.minerDemo) {
-            return 'failure';
-        }
-        
-        // 动作冷却检查
-        if (this.isActionOnCooldown()) {
-            return 'running';
-        }
-        
-        // 获取矿工的家
-        const home = this.minerDemo.getMinerHome(this.minerIndex);
-        if (!home || !home.isValid) {
-            return 'failure';
-        }
-        
-        // 计算到家的距离
-        const currentPos = this.node.worldPosition;
-        const homePos = home.worldPosition;
-        const distance = Vec3.distance(currentPos, homePos);
-        
-        // 检查是否已经到达家
-        if (distance < 2.0) {
-            // 检查是否正在移动
-            const isMoving = this.unitController.getBlackboardValue('isMoving');
-            if (isMoving) {
-                return 'running';
-            }
-            
-            // 设置休息状态
-            this.unitController.setBlackboardValue('isResting', true);
-            
-            // 清除移动目标
-            this.unitController.clearTarget();
-            this.unitController.setBlackboardValue('isMoving', false);
-            
-            this.updateActionTime();
-            return 'success';
-        } else {
-            // 设置移动目标
-            this.unitController.setTarget(homePos);
-            return 'running';
-        }
-    }
-    
-    /**
-     * 恢复体力
-     * @param params 事件参数，包含黑板变量值
-     */
-    onRecoverStamina(params: any = {}): string {
-        if (!this.unitController) {
-            return 'failure';
-        }
-        
-        // 检查是否在家中
-        const isResting = this.unitController.getBlackboardValue('isResting');
-        if (!isResting) {
-            return 'failure';
-        }
-        
-        // 恢复体力
-        const oldStamina = this.unitController.currentStamina;
-        this.unitController.currentStamina = Math.min(this.unitController.maxStamina, 
-            this.unitController.currentStamina + this.unitController.staminaRecoveryRate * 0.1); // 每次恢复2点体力
-        
-        const isFullyRested = this.unitController.currentStamina >= this.unitController.maxStamina;
-        
-        if (isFullyRested) {
-            // 清除休息状态
-            this.unitController.setBlackboardValue('isResting', false);
-            
-            // 通知演示管理器
-            this.minerDemo.completeRestCycle();
-            
-            this.updateActionTime();
-            return 'success';
-        } else {
-            // 体力还在恢复中
-            return 'running';
-        }
-    }
-    
-    /**
-     * 待机行为
-     * @param params 事件参数，包含黑板变量值
-     */
-    onIdleBehavior(params: any = {}): string {
-        if (!this.unitController) {
-            return 'failure';
-        }
-        
-        // 清除移动目标，确保停止移动
-        this.unitController.clearTarget();
-        this.unitController.setBlackboardValue('isMoving', false);
-        
-
-        
-        return 'success';
-    }
-    
-    /**
-     * 获取矿工状态摘要
-     */
-    getMinerStatus(): string {
-        if (!this.unitController) return 'Unknown';
-        
-        const hasOre = this.unitController.getBlackboardValue('hasOre');
-        const isMoving = this.unitController.getBlackboardValue('isMoving');
-        const isResting = this.unitController.getBlackboardValue('isResting');
-        const stamina = this.unitController.currentStamina;
-        const maxStamina = this.unitController.maxStamina;
-        
-        let status = '';
-        if (isResting) {
-            status = '😴休息中';
-        } else if (hasOre) {
-            status = isMoving ? '🚚运输中' : '📦携带矿石';
-        } else {
-            status = isMoving ? '🚶移动中' : '⛏️挖矿';
-        }
-        
-        return `${status} (体力:${stamina.toFixed(0)}/${maxStamina})`;
-    }
-    
-    /**
-     * 调试信息
-     */
-    getDebugInfo(): any {
-        if (!this.unitController) return {};
-        
-        return {
-            name: this.node.name,
-            hasOre: this.unitController.getBlackboardValue('hasOre'),
-            isMoving: this.unitController.getBlackboardValue('isMoving'),
-            isResting: this.unitController.getBlackboardValue('isResting'),
-            stamina: this.unitController.currentStamina,
-            maxStamina: this.unitController.maxStamina,
-            staminaPercentage: this.unitController.currentStamina / this.unitController.maxStamina,
-            isLowStamina: this.unitController.currentStamina < this.unitController.maxStamina * 0.2,
-            status: this.getMinerStatus()
-        };
-    }
-}

extensions/cocos/cocos-ecs/assets/scripts/components/RTSBehaviorHandler.ts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "739ff9ee-42d5-4542-bb5b-3e7611c729e2",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/components/SimplePrefabFactory.ts

@@ -1,126 +0,0 @@
-import { _decorator, Component, Node, Vec3, MeshRenderer, BoxCollider, RigidBody, Material, Color, primitives, utils } from 'cc';
-
-const { ccclass, property } = _decorator;
-
-/**
- * 简单预制体工厂
- */
-@ccclass('SimplePrefabFactory')
-export class SimplePrefabFactory extends Component {
-    
-    /**
-     * 创建单位节点
-     */
-    static createUnit(name: string, color: Color = Color.WHITE): Node {
-        const unit = new Node(name);
-        
-        // 添加网格渲染器
-        const meshRenderer = unit.addComponent(MeshRenderer);
-        
-        // 创建立方体网格
-        const mesh = utils.createMesh(primitives.box({ width: 1, height: 1, length: 1 }));
-        meshRenderer.mesh = mesh;
-        
-        // 创建材质
-        const material = new Material();
-        material.initialize({ effectName: 'builtin-unlit' });
-        material.setProperty('mainColor', color);
-        meshRenderer.material = material;
-        
-        // 添加碰撞器
-        const collider = unit.addComponent(BoxCollider);
-        collider.size = new Vec3(1, 1, 1);
-        
-        // 添加刚体
-        const rigidBody = unit.addComponent(RigidBody);
-        rigidBody.type = RigidBody.Type.KINEMATIC;
-        
-        return unit;
-    }
-    
-    /**
-     * 创建建筑节点
-     */
-    static createBuilding(name: string, size: Vec3 = new Vec3(2, 2, 2), color: Color = Color.GRAY): Node {
-        const building = new Node(name);
-        
-        // 添加网格渲染器
-        const meshRenderer = building.addComponent(MeshRenderer);
-        
-        // 创建立方体网格
-        const mesh = utils.createMesh(primitives.box({ 
-            width: size.x, 
-            height: size.y, 
-            length: size.z 
-        }));
-        meshRenderer.mesh = mesh;
-        
-        // 创建材质
-        const material = new Material();
-        material.initialize({ effectName: 'builtin-unlit' });
-        material.setProperty('mainColor', color);
-        meshRenderer.material = material;
-        
-        // 添加碰撞器
-        const collider = building.addComponent(BoxCollider);
-        collider.size = size;
-        
-        return building;
-    }
-    
-    /**
-     * 创建资源节点
-     */
-    static createResource(name: string, color: Color = Color.YELLOW): Node {
-        const resource = new Node(name);
-        
-        // 添加网格渲染器
-        const meshRenderer = resource.addComponent(MeshRenderer);
-        
-        // 创建球体网格
-        const mesh = utils.createMesh(primitives.sphere(0.5));
-        meshRenderer.mesh = mesh;
-        
-        // 创建材质
-        const material = new Material();
-        material.initialize({ effectName: 'builtin-unlit' });
-        material.setProperty('mainColor', color);
-        meshRenderer.material = material;
-        
-        // 添加碰撞器
-        const collider = resource.addComponent(BoxCollider);
-        collider.size = new Vec3(1, 1, 1);
-        
-        return resource;
-    }
-    
-    /**
-     * 创建地面节点
-     */
-    static createGround(size: Vec3 = new Vec3(50, 0.1, 50), color: Color = new Color(100, 150, 100, 255)): Node {
-        const ground = new Node('Ground');
-        
-        // 添加网格渲染器
-        const meshRenderer = ground.addComponent(MeshRenderer);
-        
-        // 创建平面网格
-        const mesh = utils.createMesh(primitives.box({ 
-            width: size.x, 
-            height: size.y, 
-            length: size.z 
-        }));
-        meshRenderer.mesh = mesh;
-        
-        // 创建材质
-        const material = new Material();
-        material.initialize({ effectName: 'builtin-unlit' });
-        material.setProperty('mainColor', color);
-        meshRenderer.material = material;
-        
-        // 添加碰撞器
-        const collider = ground.addComponent(BoxCollider);
-        collider.size = size;
-        
-        return ground;
-    }
-} 

extensions/cocos/cocos-ecs/assets/scripts/components/SimplePrefabFactory.ts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "ac45cfc7-cf47-4315-bdf0-ba002b45b4b6",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}

extensions/cocos/cocos-ecs/assets/scripts/components/StatusUIManager.ts

@@ -1,282 +0,0 @@
-import { Component, _decorator, Node, Label, ProgressBar, UITransform, Widget, Canvas, find, director, Color, Sprite, Layers, Graphics } from 'cc';
-import { MinerStatusUI } from './MinerStatusUI';
-
-const { ccclass, property } = _decorator;
-
-/**
- * 状态UI管理器
- * 负责创建和管理游戏对象的状态显示界面
- */
-@ccclass('StatusUIManager')
-export class StatusUIManager extends Component {
-    
-    /**
-     * 为矿工创建状态显示UI
-     */
-    static createStatusUIForMiner(miner: Node): MinerStatusUI | null {
-        const canvas = find('Canvas') || director.getScene()?.getChildByName('Canvas');
-        if (!canvas) {
-            return null;
-        }
-        
-        const uiRoot = new Node(`${miner.name}_StatusUI`);
-        canvas.addChild(uiRoot);
-        
-        const uiTransform = uiRoot.addComponent(UITransform);
-        uiTransform.setContentSize(200, 100);
-        
-        const borderNode = new Node('Border');
-        uiRoot.addChild(borderNode);
-        const borderTransform = borderNode.addComponent(UITransform);
-        borderTransform.setContentSize(202, 102);
-        const borderGraphics = borderNode.addComponent(Graphics);
-        borderGraphics.fillColor = new Color(100, 100, 100, 120);
-        borderGraphics.rect(-101, -51, 202, 102);
-        borderGraphics.fill();
-        
-        const borderWidget = borderNode.addComponent(Widget);
-        borderWidget.isAlignTop = true;
-        borderWidget.isAlignBottom = true;
-        borderWidget.isAlignLeft = true;
-        borderWidget.isAlignRight = true;
-        borderWidget.top = -1;
-        borderWidget.bottom = -1;
-        borderWidget.left = -1;
-        borderWidget.right = -1;
-        borderWidget.updateAlignment();
-        
-        const backgroundNode = new Node('Background');
-        uiRoot.addChild(backgroundNode);
-        const backgroundTransform = backgroundNode.addComponent(UITransform);
-        backgroundTransform.setContentSize(200, 100);
-        const backgroundGraphics = backgroundNode.addComponent(Graphics);
-        backgroundGraphics.fillColor = new Color(0, 0, 0, 100);
-        backgroundGraphics.rect(-100, -50, 200, 100);
-        backgroundGraphics.fill();
-        
-        const statusUI = uiRoot.addComponent(MinerStatusUI);
-        statusUI.setFollowTarget(miner);
-        
-        const nameNode = new Node('NameLabel');
-        uiRoot.addChild(nameNode);
-        const nameTransform = nameNode.addComponent(UITransform);
-        nameTransform.setContentSize(200, 25);
-        const nameLabel = nameNode.addComponent(Label);
-        nameLabel.string = miner.name;
-        nameLabel.fontSize = 16;
-        nameLabel.color = new Color(255, 255, 255, 255);
-        
-        const nameWidget = nameNode.addComponent(Widget);
-        nameWidget.isAlignTop = true;
-        nameWidget.top = 0;
-        nameWidget.isAlignHorizontalCenter = true;
-        nameWidget.updateAlignment();
-        
-        // 创建状态标签
-        const statusNode = new Node('StatusLabel');
-        uiRoot.addChild(statusNode);
-        const statusTransform = statusNode.addComponent(UITransform);
-        statusTransform.setContentSize(200, 20);
-        const statusLabel = statusNode.addComponent(Label);
-        statusLabel.string = '待机中';
-        statusLabel.fontSize = 14;
-        statusLabel.color = new Color(200, 200, 200, 255);
-        
-        // 设置状态标签位置
-        const statusWidget = statusNode.addComponent(Widget);
-        statusWidget.isAlignTop = true;
-        statusWidget.top = 25;
-        statusWidget.isAlignHorizontalCenter = true;
-        statusWidget.updateAlignment();
-        
-        // 创建体力进度条
-        const staminaBarNode = new Node('StaminaBar');
-        uiRoot.addChild(staminaBarNode);
-        const staminaBarTransform = staminaBarNode.addComponent(UITransform);
-        staminaBarTransform.setContentSize(150, 8);
-        const staminaBar = staminaBarNode.addComponent(ProgressBar);
-        staminaBar.progress = 1.0;
-        
-        // 创建体力进度条背景
-        const staminaBgNode = new Node('Background');
-        staminaBarNode.addChild(staminaBgNode);
-        const staminaBgTransform = staminaBgNode.addComponent(UITransform);
-        staminaBgTransform.setContentSize(150, 8);
-        const staminaBgGraphics = staminaBgNode.addComponent(Graphics);
-        staminaBgGraphics.fillColor = new Color(50, 50, 50, 255);
-        staminaBgGraphics.rect(-75, -4, 150, 8);
-        staminaBgGraphics.fill();
-        
-        // 创建体力进度条填充
-        const staminaFillNode = new Node('Bar');
-        staminaBarNode.addChild(staminaFillNode);
-        const staminaFillTransform = staminaFillNode.addComponent(UITransform);
-        staminaFillTransform.setContentSize(150, 8);
-        const staminaFillGraphics = staminaFillNode.addComponent(Graphics);
-        staminaFillGraphics.fillColor = new Color(0, 255, 0, 255);
-        staminaFillGraphics.rect(-75, -4, 150, 8);
-        staminaFillGraphics.fill();
-        
-        // 设置体力进度条位置
-        const staminaWidget = staminaBarNode.addComponent(Widget);
-        staminaWidget.isAlignTop = true;
-        staminaWidget.top = 45;
-        staminaWidget.isAlignHorizontalCenter = true;
-        staminaWidget.updateAlignment();
-        
-        // 创建动作进度条
-        const actionBarNode = new Node('ActionProgressBar');
-        uiRoot.addChild(actionBarNode);
-        const actionBarTransform = actionBarNode.addComponent(UITransform);
-        actionBarTransform.setContentSize(150, 6);
-        const actionBar = actionBarNode.addComponent(ProgressBar);
-        actionBar.progress = 0;
-        actionBarNode.active = false; // 初始隐藏
-        
-        // 创建动作进度条背景
-        const actionBgNode = new Node('Background');
-        actionBarNode.addChild(actionBgNode);
-        const actionBgTransform = actionBgNode.addComponent(UITransform);
-        actionBgTransform.setContentSize(150, 6);
-        const actionBgGraphics = actionBgNode.addComponent(Graphics);
-        actionBgGraphics.fillColor = new Color(50, 50, 50, 255);
-        actionBgGraphics.rect(-75, -3, 150, 6);
-        actionBgGraphics.fill();
-        
-        // 创建动作进度条填充
-        const actionFillNode = new Node('Bar');
-        actionBarNode.addChild(actionFillNode);
-        const actionFillTransform = actionFillNode.addComponent(UITransform);
-        actionFillTransform.setContentSize(150, 6);
-        const actionFillGraphics = actionFillNode.addComponent(Graphics);
-        actionFillGraphics.fillColor = new Color(255, 255, 0, 255);
-        actionFillGraphics.rect(-75, -3, 150, 6);
-        actionFillGraphics.fill();
-        
-        // 设置动作进度条位置
-        const actionWidget = actionBarNode.addComponent(Widget);
-        actionWidget.isAlignTop = true;
-        actionWidget.top = 55;
-        actionWidget.isAlignHorizontalCenter = true;
-        actionWidget.updateAlignment();
-        
-        // 创建动作标签
-        const actionLabelNode = new Node('ActionLabel');
-        uiRoot.addChild(actionLabelNode);
-        const actionLabelTransform = actionLabelNode.addComponent(UITransform);
-        actionLabelTransform.setContentSize(200, 15);
-        const actionLabel = actionLabelNode.addComponent(Label);
-        actionLabel.string = '';
-        actionLabel.fontSize = 12;
-        actionLabel.color = new Color(255, 255, 0, 255);
-        
-        // 设置动作标签位置
-        const actionLabelWidget = actionLabelNode.addComponent(Widget);
-        actionLabelWidget.isAlignTop = true;
-        actionLabelWidget.top = 65;
-        actionLabelWidget.isAlignHorizontalCenter = true;
-        actionLabelWidget.updateAlignment();
-        
-        // 创建矿石数量标签
-        const oreCountNode = new Node('OreCountLabel');
-        uiRoot.addChild(oreCountNode);
-        const oreCountTransform = oreCountNode.addComponent(UITransform);
-        oreCountTransform.setContentSize(100, 15);
-        const oreCountLabel = oreCountNode.addComponent(Label);
-        oreCountLabel.string = '💎0';
-        oreCountLabel.fontSize = 12;
-        oreCountLabel.color = new Color(255, 215, 0, 255); // 金色
-        
-        // 设置矿石数量标签位置（居中显示）
-        const oreCountWidget = oreCountNode.addComponent(Widget);
-        oreCountWidget.isAlignTop = true;
-        oreCountWidget.top = 80;
-        oreCountWidget.isAlignHorizontalCenter = true;
-        oreCountWidget.updateAlignment();
-        
-        statusUI.nameLabel = nameLabel;
-        statusUI.statusLabel = statusLabel;
-        statusUI.staminaBar = staminaBar;
-        statusUI.actionProgressBar = actionBar;
-        statusUI.actionLabel = actionLabel;
-        statusUI.oreCountLabel = oreCountLabel;
-        statusUI.warehouseCountLabel = null;
-        
-        StatusUIManager.setNodeLayerRecursively(uiRoot, Layers.Enum.UI_2D);
-        return statusUI;
-    }
-    
-    /**
-     * 递归设置节点及其子节点的层级
-     */
-    private static setNodeLayerRecursively(node: Node, layer: number) {
-        node.layer = layer;
-        for (const child of node.children) {
-            StatusUIManager.setNodeLayerRecursively(child, layer);
-        }
-    }
-    
-    /**
-     * 从矿工名字中提取索引号
-     */
-    private static extractMinerIndex(minerName: string): number {
-        const match = minerName.match(/Miner_(\d+)/);
-        if (match) {
-            return parseInt(match[1]) - 1;
-        }
-        return 0;
-    }
-    
-    /**
-     * 为仓库创建存储量显示UI
-     */
-    static createWarehouseUI(warehouse: Node): MinerStatusUI | null {
-        const canvas = find('Canvas') || director.getScene()?.getChildByName('Canvas');
-        if (!canvas) {
-            return null;
-        }
-        
-        const uiRoot = new Node(`${warehouse.name}_StorageUI`);
-        canvas.addChild(uiRoot);
-        
-        const uiTransform = uiRoot.addComponent(UITransform);
-        uiTransform.setContentSize(120, 40);
-        
-        const backgroundNode = new Node('Background');
-        uiRoot.addChild(backgroundNode);
-        const backgroundTransform = backgroundNode.addComponent(UITransform);
-        backgroundTransform.setContentSize(120, 40);
-        const backgroundGraphics = backgroundNode.addComponent(Graphics);
-        backgroundGraphics.fillColor = new Color(0, 0, 0, 120);
-        backgroundGraphics.rect(-60, -20, 120, 40);
-        backgroundGraphics.fill();
-        
-        const storageNode = new Node('StorageLabel');
-        uiRoot.addChild(storageNode);
-        const storageTransform = storageNode.addComponent(UITransform);
-        storageTransform.setContentSize(120, 30);
-        const storageLabel = storageNode.addComponent(Label);
-        storageLabel.string = '🏭 总存储: 0';
-        storageLabel.fontSize = 14;
-        storageLabel.color = new Color(255, 255, 255, 255);
-        
-        const storageWidget = storageNode.addComponent(Widget);
-        storageWidget.isAlignHorizontalCenter = true;
-        storageWidget.isAlignVerticalCenter = true;
-        storageWidget.updateAlignment();
-        
-        const statusUI = uiRoot.addComponent(MinerStatusUI);
-        statusUI.setFollowTarget(warehouse);
-        
-        statusUI.nameLabel = null;
-        statusUI.statusLabel = null;
-        statusUI.staminaBar = null;
-        statusUI.actionProgressBar = null;
-        statusUI.actionLabel = null;
-        statusUI.oreCountLabel = null;
-        statusUI.warehouseCountLabel = storageLabel;
-        
-        StatusUIManager.setNodeLayerRecursively(uiRoot, Layers.Enum.UI_2D);
-        return statusUI;
-    }
-} 

extensions/cocos/cocos-ecs/assets/scripts/components/StatusUIManager.ts.meta

@@ -1,9 +0,0 @@
-{
-  "ver": "4.0.24",
-  "importer": "typescript",
-  "imported": true,
-  "uuid": "7478e794-dd80-4661-9421-8e147d33c51e",
-  "files": [],
-  "subMetas": {},
-  "userData": {}
-}