chore: release packages (#399)

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

README.md

@@ -228,6 +228,7 @@ If you want a complete engine solution with rendering:
 A visual editor built with Tauri for scene management:
 
 - Download from [Releases](https://github.com/esengine/esengine/releases)
+- [Build from source](./packages/editor/editor-app/README.md)
 - Supports behavior tree editing, tilemap painting, visual scripting
 
 ## Project Structure
@@ -281,6 +282,7 @@ pnpm test
 
 - [ECS Framework Guide](./packages/framework/core/README.md)
 - [Behavior Tree Guide](./packages/framework/behavior-tree/README.md)
+- [Editor Setup Guide](./packages/editor/editor-app/README.md) ([中文](./packages/editor/editor-app/README_CN.md))
 - [API Reference](https://esengine.cn/api/README)
 
 ## Community

README_CN.md

@@ -228,6 +228,7 @@ npm install @esengine/world-streaming    # 世界流送
 基于 Tauri 构建的可视化编辑器：
 
 - 从 [Releases](https://github.com/esengine/esengine/releases) 下载
+- [从源码构建](./packages/editor/editor-app/README.md)
 - 支持行为树编辑、Tilemap 绘制、可视化脚本
 
 ## 项目结构
@@ -281,6 +282,7 @@ pnpm test
 
 - [ECS 框架指南](./packages/framework/core/README.md)
 - [行为树指南](./packages/framework/behavior-tree/README.md)
+- [编辑器启动指南](./packages/editor/editor-app/README_CN.md) ([English](./packages/editor/editor-app/README.md))
 - [API 参考](https://esengine.cn/api/README)
 
 ## 社区

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

@@ -71,6 +71,55 @@ class ConfiguredScene extends Scene {
 }
 ```
 
+## Runtime Environment
+
+For networked games, you can configure the runtime environment to distinguish between server and client logic.
+
+### Global Configuration (Recommended)
+
+Set the runtime environment once at the Core level - all Scenes will inherit this setting:
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+
+// Method 1: Set in Core.create()
+Core.create({ runtimeEnvironment: 'server' });
+
+// Method 2: Set static property directly
+Core.runtimeEnvironment = 'server';
+```
+
+### Per-Scene Override
+
+Individual scenes can override the global setting:
+
+```typescript
+const clientScene = new Scene({ runtimeEnvironment: 'client' });
+```
+
+### Environment Types
+
+| Environment | Use Case |
+|-------------|----------|
+| `'standalone'` | Single-player games (default) |
+| `'server'` | Game server, authoritative logic |
+| `'client'` | Game client, rendering/input |
+
+### Checking Environment in Systems
+
+```typescript
+class CollectibleSpawnSystem extends EntitySystem {
+  private checkCollections(): void {
+    // Skip on client - only server handles authoritative logic
+    if (!this.scene.isServer) return;
+
+    // Server-authoritative spawn logic...
+  }
+}
+```
+
+See [System Runtime Decorators](/en/guide/system/index#runtime-environment-decorators) for decorator-based approach.
+
 ### Running a Scene
 
 ```typescript

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

@@ -160,6 +160,53 @@ scene.addSystem(new SystemA()); // addOrder = 0, executes first
 scene.addSystem(new SystemB()); // addOrder = 1, executes second
 ```
 
+## Runtime Environment Decorators
+
+For networked games, you can use decorators to control which environment a system method runs in.
+
+### Available Decorators
+
+| Decorator | Effect |
+|-----------|--------|
+| `@ServerOnly()` | Method only executes on server |
+| `@ClientOnly()` | Method only executes on client |
+| `@NotServer()` | Method skipped on server |
+| `@NotClient()` | Method skipped on client |
+
+### Usage Example
+
+```typescript
+import { EntitySystem, ServerOnly, ClientOnly } from '@esengine/ecs-framework';
+
+class GameSystem extends EntitySystem {
+  @ServerOnly()
+  private spawnEnemies(): void {
+    // Only runs on server - authoritative spawn logic
+  }
+
+  @ClientOnly()
+  private playEffects(): void {
+    // Only runs on client - visual effects
+  }
+}
+```
+
+### Simple Conditional Check
+
+For simple cases, a direct check is often clearer than decorators:
+
+```typescript
+class CollectibleSystem extends EntitySystem {
+  private checkCollections(): void {
+    if (!this.scene.isServer) return;  // Skip on client
+
+    // Server-authoritative logic...
+  }
+}
+```
+
+See [Scene Runtime Environment](/en/guide/scene/index#runtime-environment) for configuration details.
+
 ## Next Steps
 
 - [System Types](/en/guide/system/types) - Learn about different system base classes

docs/src/content/docs/en/modules/network/sync.md

@@ -3,6 +3,102 @@ title: "State Sync"
 description: "Component sync, interpolation, prediction and snapshot buffers"
 ---
 
+## @NetworkEntity Decorator
+
+The `@NetworkEntity` decorator marks components for automatic spawn/despawn broadcasting. When an entity containing this component is created or destroyed, ECSRoom automatically broadcasts the corresponding message to all clients.
+
+### Basic Usage
+
+```typescript
+import { Component, ECSComponent, sync, NetworkEntity } from '@esengine/ecs-framework';
+
+@ECSComponent('Enemy')
+@NetworkEntity('Enemy')
+class EnemyComponent extends Component {
+    @sync('float32') x: number = 0;
+    @sync('float32') y: number = 0;
+    @sync('uint16') health: number = 100;
+}
+```
+
+When adding this component to an entity, ECSRoom automatically broadcasts the spawn message:
+
+```typescript
+// Server-side
+const entity = scene.createEntity('Enemy');
+entity.addComponent(new EnemyComponent()); // Auto-broadcasts spawn
+
+// Destroying auto-broadcasts despawn
+entity.destroy(); // Auto-broadcasts despawn
+```
+
+### Configuration Options
+
+```typescript
+@NetworkEntity('Bullet', {
+    autoSpawn: true,    // Auto-broadcast spawn (default true)
+    autoDespawn: false  // Disable auto-broadcast despawn
+})
+class BulletComponent extends Component { }
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `autoSpawn` | `boolean` | `true` | Auto-broadcast spawn when component is added |
+| `autoDespawn` | `boolean` | `true` | Auto-broadcast despawn when entity is destroyed |
+
+### Initialization Order
+
+When using `@NetworkEntity`, initialize data **before** adding the component:
+
+```typescript
+// ✅ Correct: Initialize first, then add
+const comp = new PlayerComponent();
+comp.playerId = player.id;
+comp.x = 100;
+comp.y = 200;
+entity.addComponent(comp); // Data is correct at spawn
+
+// ❌ Wrong: Add first, then initialize
+const comp = entity.addComponent(new PlayerComponent());
+comp.playerId = player.id; // Data has default values at spawn
+```
+
+### Simplified GameRoom
+
+With `@NetworkEntity`, GameRoom becomes much cleaner:
+
+```typescript
+// No manual callbacks needed
+class GameRoom extends ECSRoom {
+    private setupSystems(): void {
+        // Enemy spawn system (auto-broadcasts spawn)
+        this.addSystem(new EnemySpawnSystem());
+
+        // Enemy AI system
+        const enemyAI = new EnemyAISystem();
+        enemyAI.onDeath((enemy) => {
+            enemy.destroy(); // Auto-broadcasts despawn
+        });
+        this.addSystem(enemyAI);
+    }
+}
+```
+
+### ECSRoom Configuration
+
+You can disable the auto network entity feature in ECSRoom:
+
+```typescript
+class GameRoom extends ECSRoom {
+    constructor() {
+        super({
+            enableAutoNetworkEntity: false // Disable auto-broadcasting
+        });
+    }
+}
+```
+
 ## Component Sync System
 
 ECS component state synchronization based on `@sync` decorator.

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

@@ -71,6 +71,55 @@ class ConfiguredScene extends Scene {
 }
 ```
 
+## 运行时环境
+
+对于网络游戏，你可以配置运行时环境来区分服务端和客户端逻辑。
+
+### 全局配置（推荐）
+
+在 Core 层级设置一次运行时环境，所有场景都会继承此设置：
+
+```typescript
+import { Core } from '@esengine/ecs-framework';
+
+// 方式1：在 Core.create() 中设置
+Core.create({ runtimeEnvironment: 'server' });
+
+// 方式2：直接设置静态属性
+Core.runtimeEnvironment = 'server';
+```
+
+### 单个场景覆盖
+
+个别场景可以覆盖全局设置：
+
+```typescript
+const clientScene = new Scene({ runtimeEnvironment: 'client' });
+```
+
+### 环境类型
+
+| 环境 | 使用场景 |
+|------|----------|
+| `'standalone'` | 单机游戏（默认） |
+| `'server'` | 游戏服务器，权威逻辑 |
+| `'client'` | 游戏客户端，渲染/输入 |
+
+### 在系统中检查环境
+
+```typescript
+class CollectibleSpawnSystem extends EntitySystem {
+  private checkCollections(): void {
+    // 客户端跳过 - 只有服务端处理权威逻辑
+    if (!this.scene.isServer) return;
+
+    // 服务端权威生成逻辑...
+  }
+}
+```
+
+参见 [系统运行时装饰器](/guide/system/index#运行时环境装饰器) 了解基于装饰器的方式。
+
 ### 运行场景
 
 ```typescript

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

@@ -160,6 +160,53 @@ scene.addSystem(new SystemA()); // addOrder = 0，先执行
 scene.addSystem(new SystemB()); // addOrder = 1，后执行
 ```
 
+## 运行时环境装饰器
+
+对于网络游戏，你可以使用装饰器来控制系统方法在哪个环境下执行。
+
+### 可用装饰器
+
+| 装饰器 | 效果 |
+|--------|------|
+| `@ServerOnly()` | 方法仅在服务端执行 |
+| `@ClientOnly()` | 方法仅在客户端执行 |
+| `@NotServer()` | 方法在服务端跳过 |
+| `@NotClient()` | 方法在客户端跳过 |
+
+### 使用示例
+
+```typescript
+import { EntitySystem, ServerOnly, ClientOnly } from '@esengine/ecs-framework';
+
+class GameSystem extends EntitySystem {
+  @ServerOnly()
+  private spawnEnemies(): void {
+    // 仅在服务端运行 - 权威生成逻辑
+  }
+
+  @ClientOnly()
+  private playEffects(): void {
+    // 仅在客户端运行 - 视觉效果
+  }
+}
+```
+
+### 简单条件检查
+
+对于简单场景，直接检查通常比装饰器更清晰：
+
+```typescript
+class CollectibleSystem extends EntitySystem {
+  private checkCollections(): void {
+    if (!this.scene.isServer) return;  // 客户端跳过
+
+    // 服务端权威逻辑...
+  }
+}
+```
+
+参见 [场景运行时环境](/guide/scene/index#运行时环境) 了解配置详情。
+
 ## 下一步
 
 - [系统类型](/guide/system/types) - 了解不同类型的系统基类

docs/src/content/docs/modules/network/sync.md

@@ -3,6 +3,102 @@ title: "状态同步"
 description: "组件同步、插值、预测和快照缓冲区"
 ---
 
+## @NetworkEntity 装饰器
+
+`@NetworkEntity` 装饰器用于标记需要自动广播生成/销毁的组件。当包含此组件的实体被创建或销毁时，ECSRoom 会自动广播相应的消息给所有客户端。
+
+### 基本用法
+
+```typescript
+import { Component, ECSComponent, sync, NetworkEntity } from '@esengine/ecs-framework';
+
+@ECSComponent('Enemy')
+@NetworkEntity('Enemy')
+class EnemyComponent extends Component {
+    @sync('float32') x: number = 0;
+    @sync('float32') y: number = 0;
+    @sync('uint16') health: number = 100;
+}
+```
+
+当添加此组件到实体时，ECSRoom 会自动广播 spawn 消息：
+
+```typescript
+// 服务端
+const entity = scene.createEntity('Enemy');
+entity.addComponent(new EnemyComponent()); // 自动广播 spawn
+
+// 销毁时自动广播 despawn
+entity.destroy(); // 自动广播 despawn
+```
+
+### 配置选项
+
+```typescript
+@NetworkEntity('Bullet', {
+    autoSpawn: true,    // 自动广播生成（默认 true）
+    autoDespawn: false  // 禁用自动广播销毁
+})
+class BulletComponent extends Component { }
+```
+
+| 选项 | 类型 | 默认值 | 描述 |
+|------|------|--------|------|
+| `autoSpawn` | `boolean` | `true` | 添加组件时自动广播 spawn |
+| `autoDespawn` | `boolean` | `true` | 销毁实体时自动广播 despawn |
+
+### 初始化顺序
+
+使用 `@NetworkEntity` 时，应在添加组件**之前**初始化数据：
+
+```typescript
+// ✅ 正确：先初始化，再添加
+const comp = new PlayerComponent();
+comp.playerId = player.id;
+comp.x = 100;
+comp.y = 200;
+entity.addComponent(comp); // spawn 时数据已正确
+
+// ❌ 错误：先添加，再初始化
+const comp = entity.addComponent(new PlayerComponent());
+comp.playerId = player.id; // spawn 时数据是默认值
+```
+
+### 简化 GameRoom
+
+使用 `@NetworkEntity` 后，GameRoom 变得更加简洁：
+
+```typescript
+// 无需手动回调
+class GameRoom extends ECSRoom {
+    private setupSystems(): void {
+        // 敌人生成系统（自动广播 spawn）
+        this.addSystem(new EnemySpawnSystem());
+
+        // 敌人 AI 系统
+        const enemyAI = new EnemyAISystem();
+        enemyAI.onDeath((enemy) => {
+            enemy.destroy(); // 自动广播 despawn
+        });
+        this.addSystem(enemyAI);
+    }
+}
+```
+
+### ECSRoom 配置
+
+可以在 ECSRoom 中禁用自动网络实体功能：
+
+```typescript
+class GameRoom extends ECSRoom {
+    constructor() {
+        super({
+            enableAutoNetworkEntity: false // 禁用自动广播
+        });
+    }
+}
+```
+
 ## 组件同步系统
 
 基于 `@sync` 装饰器的 ECS 组件状态同步。

packages/editor/editor-app/README.md

@@ -0,0 +1,86 @@
+# ESEngine Editor
+
+A cross-platform desktop visual editor built with Tauri 2.x + React 18.
+
+## Prerequisites
+
+Before running the editor, ensure you have the following installed:
+
+- **Node.js** >= 18.x
+- **pnpm** >= 10.x
+- **Rust** >= 1.70 (for Tauri)
+- **Platform-specific dependencies**:
+  - **Windows**: Microsoft Visual Studio C++ Build Tools
+  - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
+  - **Linux**: See [Tauri prerequisites](https://tauri.app/v1/guides/getting-started/prerequisites)
+
+## Quick Start
+
+### 1. Clone and Install
+
+```bash
+git clone https://github.com/esengine/esengine.git
+cd esengine
+pnpm install
+```
+
+### 2. Build Dependencies
+
+From the project root:
+
+```bash
+pnpm build:editor
+```
+
+### 3. Run Editor
+
+```bash
+cd packages/editor/editor-app
+pnpm tauri:dev
+```
+
+## Available Scripts
+
+| Script | Description |
+|--------|-------------|
+| `pnpm tauri:dev` | Run editor in development mode with hot-reload |
+| `pnpm tauri:build` | Build production application |
+| `pnpm build:sdk` | Build editor-runtime SDK |
+
+## Project Structure
+
+```
+editor-app/
+├── src/                    # React application source
+│   ├── components/         # UI components
+│   ├── panels/             # Editor panels
+│   └── services/           # Core services
+├── src-tauri/              # Tauri (Rust) backend
+├── public/                 # Static assets
+└── scripts/                # Build scripts
+```
+
+## Troubleshooting
+
+### Build Errors
+
+```bash
+pnpm clean
+pnpm install
+pnpm build:editor
+```
+
+### Rust/Tauri Errors
+
+```bash
+rustup update
+```
+
+## Documentation
+
+- [ESEngine Documentation](https://esengine.cn/)
+- [Tauri Documentation](https://tauri.app/)
+
+## License
+
+MIT License

packages/editor/editor-app/README_CN.md

@@ -0,0 +1,86 @@
+# ESEngine 编辑器
+
+基于 Tauri 2.x + React 18 构建的跨平台桌面可视化编辑器。
+
+## 环境要求
+
+运行编辑器前，请确保已安装以下环境：
+
+- **Node.js** >= 18.x
+- **pnpm** >= 10.x
+- **Rust** >= 1.70 (Tauri 需要)
+- **平台相关依赖**：
+  - **Windows**: Microsoft Visual Studio C++ Build Tools
+  - **macOS**: Xcode Command Line Tools (`xcode-select --install`)
+  - **Linux**: 参考 [Tauri 环境配置](https://tauri.app/v1/guides/getting-started/prerequisites)
+
+## 快速开始
+
+### 1. 克隆并安装
+
+```bash
+git clone https://github.com/esengine/esengine.git
+cd esengine
+pnpm install
+```
+
+### 2. 构建依赖
+
+在项目根目录执行：
+
+```bash
+pnpm build:editor
+```
+
+### 3. 启动编辑器
+
+```bash
+cd packages/editor/editor-app
+pnpm tauri:dev
+```
+
+## 可用脚本
+
+| 脚本 | 说明 |
+|------|------|
+| `pnpm tauri:dev` | 开发模式运行编辑器（支持热重载）|
+| `pnpm tauri:build` | 构建生产版本应用 |
+| `pnpm build:sdk` | 构建 editor-runtime SDK |
+
+## 项目结构
+
+```
+editor-app/
+├── src/                    # React 应用源码
+│   ├── components/         # UI 组件
+│   ├── panels/             # 编辑器面板
+│   └── services/           # 核心服务
+├── src-tauri/              # Tauri (Rust) 后端
+├── public/                 # 静态资源
+└── scripts/                # 构建脚本
+```
+
+## 常见问题
+
+### 构建错误
+
+```bash
+pnpm clean
+pnpm install
+pnpm build:editor
+```
+
+### Rust/Tauri 错误
+
+```bash
+rustup update
+```
+
+## 文档
+
+- [ESEngine 文档](https://esengine.cn/)
+- [Tauri 文档](https://tauri.app/)
+
+## 许可证
+
+MIT License

packages/editor/editor-app/package.json

@@ -9,7 +9,7 @@
     "build": "npm run build:sdk && tsc && vite build",
     "build:watch": "vite build --watch",
     "tauri": "tauri",
-    "copy-modules": "node ../../scripts/copy-engine-modules.mjs",
+    "copy-modules": "node ../../../scripts/copy-engine-modules.mjs",
     "tauri:dev": "npm run build:sdk && npm run copy-modules && tauri dev",
     "bundle:runtime": "node scripts/bundle-runtime.mjs",
     "tauri:build": "npm run build:sdk && npm run copy-modules && npm run bundle:runtime && tauri build",

packages/editor/editor-app/src-tauri/Cargo.toml

@@ -10,16 +10,16 @@ name = "ecs_editor_lib"
 crate-type = ["staticlib", "cdylib", "rlib"]
 
 [build-dependencies]
-tauri-build = { version = "2.0", features = [] }
+tauri-build = { version = "2", features = [] }
 
 [dependencies]
-tauri = { version = "2.0", features = ["protocol-asset"] }
-tauri-plugin-shell = "2.0"
-tauri-plugin-dialog = "2.0"
-tauri-plugin-fs = "2.0"
+tauri = { version = "2", features = ["protocol-asset"] }
+tauri-plugin-shell = "2"
+tauri-plugin-dialog = "2"
+tauri-plugin-fs = "2"
 tauri-plugin-updater = "2"
-tauri-plugin-http = "2.0"
-tauri-plugin-cli = "2.0"
+tauri-plugin-http = "2"
+tauri-plugin-cli = "2"
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 glob = "0.3"

packages/editor/plugins/behavior-tree-editor/package.json

@@ -30,6 +30,7 @@
   "devDependencies": {
     "@esengine/ecs-framework": "workspace:*",
     "@esengine/engine-core": "workspace:*",
+    "@esengine/asset-system": "workspace:*",
     "@esengine/editor-core": "workspace:*",
     "@esengine/editor-runtime": "workspace:*",
     "@esengine/node-editor": "workspace:*",

packages/editor/plugins/behavior-tree-editor/src/BehaviorTreeRuntimeModule.ts

@@ -0,0 +1,45 @@
+/**
+ * @zh ESEngine 行为树运行时模块
+ * @en ESEngine Behavior Tree Runtime Module
+ *
+ * @zh 纯运行时模块，不依赖 asset-system。资产加载由编辑器在 install 时注册。
+ * @en Pure runtime module, no asset-system dependency. Asset loading is registered by editor during install.
+ */
+
+import type { IScene, ServiceContainer, IComponentRegistry } from '@esengine/ecs-framework';
+import type { IRuntimeModule, SystemContext } from '@esengine/engine-core';
+
+import {
+    BehaviorTreeRuntimeComponent,
+    BehaviorTreeExecutionSystem,
+    BehaviorTreeAssetManager,
+    GlobalBlackboardService,
+    BehaviorTreeSystemToken
+} from '@esengine/behavior-tree';
+
+export class BehaviorTreeRuntimeModule implements IRuntimeModule {
+    registerComponents(registry: IComponentRegistry): void {
+        registry.register(BehaviorTreeRuntimeComponent);
+    }
+
+    registerServices(services: ServiceContainer): void {
+        if (!services.isRegistered(GlobalBlackboardService)) {
+            services.registerSingleton(GlobalBlackboardService);
+        }
+        if (!services.isRegistered(BehaviorTreeAssetManager)) {
+            services.registerSingleton(BehaviorTreeAssetManager);
+        }
+    }
+
+    createSystems(scene: IScene, context: SystemContext): void {
+        const ecsServices = (context as { ecsServices?: ServiceContainer }).ecsServices;
+        const behaviorTreeSystem = new BehaviorTreeExecutionSystem(ecsServices);
+
+        if (context.isEditor) {
+            behaviorTreeSystem.enabled = false;
+        }
+
+        scene.addSystem(behaviorTreeSystem);
+        context.services.register(BehaviorTreeSystemToken, behaviorTreeSystem);
+    }
+}

packages/editor/plugins/behavior-tree-editor/src/index.ts

@@ -30,8 +30,11 @@ import {
     LocaleService,
 } from '@esengine/editor-runtime';
 
-// Runtime imports from @esengine/behavior-tree package
-import { BehaviorTreeRuntimeComponent, BehaviorTreeRuntimeModule } from '@esengine/behavior-tree';
+// Runtime imports
+import { BehaviorTreeRuntimeComponent, BehaviorTreeAssetType } from '@esengine/behavior-tree';
+import { AssetManagerToken } from '@esengine/asset-system';
+import { BehaviorTreeRuntimeModule } from './BehaviorTreeRuntimeModule';
+import { BehaviorTreeLoader } from './runtime/BehaviorTreeLoader';
 
 // Editor components and services
 import { BehaviorTreeService } from './services/BehaviorTreeService';
@@ -71,6 +74,10 @@ export class BehaviorTreeEditorModule implements IEditorModuleLoader {
         // 设置插件上下文
         PluginContext.setServices(services);
 
+        // 注册行为树资产加载器到 AssetManager
+        // Register behavior tree asset loader to AssetManager
+        this.registerAssetLoader();
+
         // 注册服务
         this.registerServices(services);
 
@@ -92,6 +99,22 @@ export class BehaviorTreeEditorModule implements IEditorModuleLoader {
         logger.info('BehaviorTree editor module installed');
     }
 
+    /**
+     * 注册行为树资产加载器
+     * Register behavior tree asset loader
+     */
+    private registerAssetLoader(): void {
+        try {
+            const assetManager = PluginAPI.resolve(AssetManagerToken);
+            if (assetManager) {
+                assetManager.registerLoader(BehaviorTreeAssetType, new BehaviorTreeLoader());
+                logger.info('BehaviorTree asset loader registered');
+            }
+        } catch (error) {
+            logger.warn('Failed to register asset loader:', error);
+        }
+    }
+
     private registerAssetCreationMappings(services: ServiceContainer): void {
         try {
             const fileActionRegistry = services.resolve<FileActionRegistry>(IFileActionRegistry);
@@ -376,7 +399,7 @@ export const BehaviorTreePlugin: IEditorPlugin = {
     editorModule: new BehaviorTreeEditorModule(),
 };
 
-export { BehaviorTreeRuntimeModule };
+// BehaviorTreeRuntimeModule is internal, not re-exported
 
 // Re-exports for editor functionality
 export { PluginContext } from './PluginContext';

packages/editor/plugins/behavior-tree-editor/src/runtime/BehaviorTreeLoader.ts

@@ -0,0 +1,61 @@
+/**
+ * @zh ESEngine 资产加载器
+ * @en ESEngine asset loader
+ * @internal
+ */
+
+import { Core } from '@esengine/ecs-framework';
+import {
+    BehaviorTreeAssetManager,
+    EditorToBehaviorTreeDataConverter,
+    BehaviorTreeAssetType,
+    type BehaviorTreeData
+} from '@esengine/behavior-tree';
+
+/**
+ * @zh 行为树资产接口
+ * @en Behavior tree asset interface
+ * @internal
+ */
+export interface IBehaviorTreeAsset {
+    data: BehaviorTreeData;
+    path: string;
+}
+
+/**
+ * @zh 行为树加载器
+ * @en Behavior tree loader implementing IAssetLoader interface
+ * @internal
+ */
+export class BehaviorTreeLoader {
+    readonly supportedType = BehaviorTreeAssetType;
+    readonly supportedExtensions = ['.btree'];
+    readonly contentType = 'text' as const;
+
+    async parse(content: { text?: string }, context: { metadata: { path: string } }): Promise<IBehaviorTreeAsset> {
+        if (!content.text) {
+            throw new Error('Behavior tree content is empty');
+        }
+
+        const treeData = EditorToBehaviorTreeDataConverter.fromEditorJSON(content.text);
+        const assetPath = context.metadata.path;
+        treeData.id = assetPath;
+
+        const btAssetManager = Core.services.tryResolve(BehaviorTreeAssetManager);
+        if (btAssetManager) {
+            btAssetManager.loadAsset(treeData);
+        }
+
+        return {
+            data: treeData,
+            path: assetPath
+        };
+    }
+
+    dispose(asset: IBehaviorTreeAsset): void {
+        const btAssetManager = Core.services.tryResolve(BehaviorTreeAssetManager);
+        if (btAssetManager && asset.data) {
+            btAssetManager.unloadAsset(asset.data.id);
+        }
+    }
+}

packages/editor/plugins/behavior-tree-editor/tsconfig.build.json

@@ -1,23 +1,15 @@
 {
+    "extends": "../../../../tsconfig.base.json",
     "compilerOptions": {
-        "target": "ES2020",
-        "module": "ES2020",
-        "moduleResolution": "bundler",
-        "lib": ["ES2020", "DOM"],
-        "outDir": "./dist",
-        "rootDir": "./src",
-        "strict": true,
-        "esModuleInterop": true,
-        "allowSyntheticDefaultImports": true,
-        "skipLibCheck": true,
-        "forceConsistentCasingInFileNames": true,
+        "composite": false,
         "declaration": true,
         "declarationMap": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
         "jsx": "react-jsx",
-        "resolveJsonModule": true,
-        "experimentalDecorators": true,
-        "emitDecoratorMetadata": true
+        "skipLibCheck": true,
+        "moduleResolution": "bundler"
     },
     "include": ["src/**/*"],
-    "exclude": ["node_modules", "dist"]
+    "exclude": ["node_modules", "dist", "**/*.test.ts"]
 }

packages/editor/plugins/behavior-tree-editor/tsup.config.ts

@@ -2,6 +2,8 @@ import { defineConfig } from 'tsup';
 import { editorOnlyPreset } from '../../../tools/build-config/src/presets/plugin-tsup';
 
 export default defineConfig({
-    ...editorOnlyPreset(),
+    ...editorOnlyPreset({
+        external: ['@esengine/asset-system']
+    }),
     tsconfig: 'tsconfig.build.json'
 });

packages/editor/plugins/fairygui-editor/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+    "extends": "../../../../tsconfig.base.json",
+    "compilerOptions": {
+        "composite": false,
+        "declaration": true,
+        "declarationMap": true,
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "jsx": "react-jsx"
+    },
+    "include": ["src/**/*"],
+    "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}

packages/editor/plugins/fairygui-editor/tsconfig.json

@@ -1,6 +1,7 @@
 {
-    "extends": "../build-config/tsconfig.json",
+    "extends": "../../../../tsconfig.base.json",
     "compilerOptions": {
+        "composite": true,
         "outDir": "./dist",
         "rootDir": "./src",
         "jsx": "react-jsx",

packages/editor/plugins/fairygui-editor/tsup.config.ts

@@ -5,6 +5,7 @@ export default defineConfig({
     format: ['esm'],
     dts: true,
     clean: true,
+    tsconfig: 'tsconfig.build.json',
     external: [
         'react',
         'react-dom',

packages/framework/behavior-tree/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @esengine/behavior-tree
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+
 ## 2.0.1
 
 ### Patch Changes

packages/framework/behavior-tree/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/behavior-tree",
-    "version": "2.0.1",
+    "version": "4.0.0",
     "description": "ECS-based AI behavior tree system - works with any ECS framework (ESEngine, Cocos, Laya, etc.)",
     "main": "dist/index.js",
     "module": "dist/index.js",

packages/framework/blueprint/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @esengine/blueprint
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+
 ## 2.0.1
 
 ### Patch Changes

packages/framework/blueprint/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/blueprint",
-    "version": "2.0.1",
+    "version": "4.0.0",
     "description": "Visual scripting system - works with any ECS framework (ESEngine, Cocos, Laya, etc.)",
     "main": "dist/index.js",
     "module": "dist/index.js",

packages/framework/core/CHANGELOG.md

@@ -1,5 +1,93 @@
 # @esengine/ecs-framework
 
+## 2.7.0
+
+### Minor Changes
+
+- [#398](https://github.com/esengine/esengine/pull/398) [`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028) Thanks [@esengine](https://github.com/esengine)! - feat(ecs): 添加运行时环境区分机制 | add runtime environment detection
+
+    新增功能：
+    - `Core` 新增静态属性 `runtimeEnvironment`，支持 `'server' | 'client' | 'standalone'`
+    - `Core` 新增 `isServer` / `isClient` 静态只读属性
+    - `ICoreConfig` 新增 `runtimeEnvironment` 配置项
+    - `Scene` 新增 `isServer` / `isClient` 只读属性（默认从 Core 继承，可通过 config 覆盖）
+    - 新增 `@ServerOnly()` / `@ClientOnly()` / `@NotServer()` / `@NotClient()` 方法装饰器
+
+    用于网络游戏中区分服务端权威逻辑和客户端逻辑：
+
+    ```typescript
+    // 方式1: 全局设置（推荐）
+    Core.create({ runtimeEnvironment: 'server' });
+    // 或直接设置静态属性
+    Core.runtimeEnvironment = 'server';
+
+    // 所有场景自动继承
+    const scene = new Scene();
+    console.log(scene.isServer); // true
+
+    // 方式2: 单个场景覆盖（可选）
+    const clientScene = new Scene({ runtimeEnvironment: 'client' });
+
+    // 在系统中检查环境
+    class CollectibleSpawnSystem extends EntitySystem {
+        private checkCollections(): void {
+            if (!this.scene.isServer) return; // 客户端跳过
+            // ... 服务端权威逻辑
+        }
+    }
+    ```
+
+## 2.6.1
+
+### Patch Changes
+
+- [#396](https://github.com/esengine/esengine/pull/396) [`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e) Thanks [@esengine](https://github.com/esengine)! - fix(ecs): COMPONENT_ADDED 事件添加 entity 字段
+
+    修复 `ECSEventType.COMPONENT_ADDED` 事件缺少 `entity` 字段的问题，导致 ECSRoom 的 `@NetworkEntity` 自动广播功能报错。
+
+## 2.6.0
+
+### Minor Changes
+
+- feat(ecs): 添加 @NetworkEntity 装饰器，支持自动广播实体生成/销毁
+
+    ### 新功能
+
+    **@NetworkEntity 装饰器**
+    - 标记组件为网络实体，自动广播 spawn/despawn 消息
+    - 支持 `autoSpawn` 和 `autoDespawn` 配置选项
+    - 通过事件系统（`ECSEventType.COMPONENT_ADDED` / `ECSEventType.ENTITY_DESTROYED`）实现
+
+    **ECSRoom 增强**
+    - 新增 `enableAutoNetworkEntity` 配置选项（默认启用）
+    - 自动监听组件添加和实体销毁事件
+    - 简化 GameRoom 实现，无需手动回调
+
+    ### 改进
+
+    **Entity 事件**
+    - `Entity.destroy()` 现在发出 `entity:destroyed` 事件
+    - `Entity.active` 变化时发出 `entity:enabled` / `entity:disabled` 事件
+    - 使用 `ECSEventType` 常量替代硬编码字符串
+
+    ### 使用示例
+
+    ```typescript
+    import { Component, ECSComponent, sync, NetworkEntity } from '@esengine/ecs-framework';
+
+    @ECSComponent('Enemy')
+    @NetworkEntity('Enemy')
+    class EnemyComponent extends Component {
+        @sync('float32') x: number = 0;
+        @sync('float32') y: number = 0;
+    }
+
+    // 服务端
+    const entity = scene.createEntity('Enemy');
+    entity.addComponent(new EnemyComponent()); // 自动广播 spawn
+    entity.destroy(); // 自动广播 despawn
+    ```
+
 ## 2.5.1
 
 ### Patch Changes

packages/framework/core/package.json

@@ -1,16 +1,18 @@
 {
   "name": "@esengine/ecs-framework",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "description": "用于Laya、Cocos Creator等JavaScript游戏引擎的高性能ECS框架",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
   "unpkg": "dist/index.umd.js",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.cjs",
+      "source": "./src/index.ts"
     }
   },
   "files": [
@@ -50,23 +52,24 @@
     "@babel/plugin-transform-nullish-coalescing-operator": "^7.27.1",
     "@babel/plugin-transform-optional-chaining": "^7.27.1",
     "@babel/preset-env": "^7.28.3",
+    "@eslint/js": "^9.37.0",
+    "@jest/globals": "^29.7.0",
     "@rollup/plugin-babel": "^6.0.4",
     "@rollup/plugin-commonjs": "^28.0.3",
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
-    "@jest/globals": "^29.7.0",
     "@types/jest": "^29.5.14",
     "@types/node": "^20.19.17",
-    "@eslint/js": "^9.37.0",
     "eslint": "^9.37.0",
-    "typescript-eslint": "^8.46.1",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "rimraf": "^5.0.0",
     "rollup": "^4.42.0",
     "rollup-plugin-dts": "^6.2.1",
+    "rollup-plugin-sourcemaps": "^0.6.3",
     "ts-jest": "^29.4.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.46.1"
   },
   "publishConfig": {
     "access": "public",

packages/framework/core/src/Core.ts

@@ -5,7 +5,7 @@ import { Time } from './Utils/Time';
 import { PerformanceMonitor } from './Utils/PerformanceMonitor';
 import { PoolManager } from './Utils/Pool/PoolManager';
 import { DebugManager } from './Utils/Debug';
-import { ICoreConfig, IECSDebugConfig } from './Types';
+import { ICoreConfig, IECSDebugConfig, RuntimeEnvironment } from './Types';
 import { createLogger } from './Utils/Logger';
 import { SceneManager } from './ECS/SceneManager';
 import { IScene } from './ECS/IScene';
@@ -63,6 +63,47 @@ export class Core {
      */
     public static paused = false;
 
+    /**
+     * @zh 运行时环境
+     * @en Runtime environment
+     *
+     * @zh 全局运行时环境设置。所有 Scene 默认继承此值。
+     * 服务端框架（如 @esengine/server）应在启动时设置为 'server'。
+     * 客户端应用应设置为 'client'。
+     * 单机游戏使用默认值 'standalone'。
+     *
+     * @en Global runtime environment setting. All Scenes inherit this value by default.
+     * Server frameworks (like @esengine/server) should set this to 'server' at startup.
+     * Client apps should set this to 'client'.
+     * Standalone games use the default 'standalone'.
+     *
+     * @example
+     * ```typescript
+     * // @zh 服务端启动时设置 | @en Set at server startup
+     * Core.runtimeEnvironment = 'server';
+     *
+     * // @zh 或在 Core.create 时配置 | @en Or configure in Core.create
+     * Core.create({ runtimeEnvironment: 'server' });
+     * ```
+     */
+    public static runtimeEnvironment: RuntimeEnvironment = 'standalone';
+
+    /**
+     * @zh 是否在服务端运行
+     * @en Whether running on server
+     */
+    public static get isServer(): boolean {
+        return Core.runtimeEnvironment === 'server';
+    }
+
+    /**
+     * @zh 是否在客户端运行
+     * @en Whether running on client
+     */
+    public static get isClient(): boolean {
+        return Core.runtimeEnvironment === 'client';
+    }
+
     /**
      * @zh 全局核心实例，可能为null表示Core尚未初始化或已被销毁
      * @en Global core instance, null means Core is not initialized or destroyed
@@ -133,6 +174,11 @@ export class Core {
         this._config = { debug: true, ...config };
         this._serviceContainer = new ServiceContainer();
 
+        // 设置全局运行时环境
+        if (config.runtimeEnvironment) {
+            Core.runtimeEnvironment = config.runtimeEnvironment;
+        }
+
         this._timerManager = new TimerManager();
         this._serviceContainer.registerInstance(TimerManager, this._timerManager);
 

packages/framework/core/src/ECS/Decorators/RuntimeEnvironment.ts

@@ -0,0 +1,188 @@
+/**
+ * @zh 运行时环境装饰器
+ * @en Runtime Environment Decorators
+ *
+ * @zh 提供 @ServerOnly 和 @ClientOnly 装饰器，用于标记只在特定环境执行的方法
+ * @en Provides @ServerOnly and @ClientOnly decorators to mark methods that only execute in specific environments
+ */
+
+import type { EntitySystem } from '../Systems/EntitySystem';
+
+/**
+ * @zh 服务端专用方法装饰器
+ * @en Server-only method decorator
+ *
+ * @zh 被装饰的方法只会在服务端环境执行（scene.isServer === true）。
+ * 在客户端或单机模式下，方法调用会被静默跳过。
+ *
+ * @en Decorated methods only execute in server environment (scene.isServer === true).
+ * In client or standalone mode, method calls are silently skipped.
+ *
+ * @example
+ * ```typescript
+ * class CollectibleSpawnSystem extends EntitySystem {
+ *     @ServerOnly()
+ *     private checkCollections(players: readonly Entity[]): void {
+ *         // 只在服务端执行收集检测
+ *         // Only check collections on server
+ *         for (const entity of this.scene.entities.buffer) {
+ *             // ...
+ *         }
+ *     }
+ * }
+ * ```
+ */
+export function ServerOnly(): MethodDecorator {
+    return function <T>(
+        _target: object,
+        _propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<T>
+    ): TypedPropertyDescriptor<T> | void {
+        const originalMethod = descriptor.value as unknown as (...args: unknown[]) => unknown;
+
+        if (typeof originalMethod !== 'function') {
+            throw new Error(`@ServerOnly can only be applied to methods, not ${typeof originalMethod}`);
+        }
+
+        descriptor.value = function (this: EntitySystem, ...args: unknown[]): unknown {
+            if (!this.scene?.isServer) {
+                return undefined;
+            }
+            return originalMethod.apply(this, args);
+        } as unknown as T;
+
+        return descriptor;
+    };
+}
+
+/**
+ * @zh 客户端专用方法装饰器
+ * @en Client-only method decorator
+ *
+ * @zh 被装饰的方法只会在客户端环境执行（scene.isClient === true）。
+ * 在服务端或单机模式下，方法调用会被静默跳过。
+ *
+ * @en Decorated methods only execute in client environment (scene.isClient === true).
+ * In server or standalone mode, method calls are silently skipped.
+ *
+ * @example
+ * ```typescript
+ * class RenderSystem extends EntitySystem {
+ *     @ClientOnly()
+ *     private updateVisuals(): void {
+ *         // 只在客户端执行渲染逻辑
+ *         // Only update visuals on client
+ *     }
+ * }
+ * ```
+ */
+export function ClientOnly(): MethodDecorator {
+    return function <T>(
+        _target: object,
+        _propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<T>
+    ): TypedPropertyDescriptor<T> | void {
+        const originalMethod = descriptor.value as unknown as (...args: unknown[]) => unknown;
+
+        if (typeof originalMethod !== 'function') {
+            throw new Error(`@ClientOnly can only be applied to methods, not ${typeof originalMethod}`);
+        }
+
+        descriptor.value = function (this: EntitySystem, ...args: unknown[]): unknown {
+            if (!this.scene?.isClient) {
+                return undefined;
+            }
+            return originalMethod.apply(this, args);
+        } as unknown as T;
+
+        return descriptor;
+    };
+}
+
+/**
+ * @zh 非客户端环境方法装饰器
+ * @en Non-client method decorator
+ *
+ * @zh 被装饰的方法在服务端和单机模式下执行，但不在客户端执行。
+ * 用于需要在服务端和单机都运行，但客户端跳过的逻辑。
+ *
+ * @en Decorated methods execute in server and standalone mode, but not on client.
+ * Used for logic that should run on server and standalone, but skip on client.
+ *
+ * @example
+ * ```typescript
+ * class SpawnSystem extends EntitySystem {
+ *     @NotClient()
+ *     private spawnEntities(): void {
+ *         // 服务端和单机模式执行，客户端跳过
+ *         // Execute on server and standalone, skip on client
+ *     }
+ * }
+ * ```
+ */
+export function NotClient(): MethodDecorator {
+    return function <T>(
+        _target: object,
+        _propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<T>
+    ): TypedPropertyDescriptor<T> | void {
+        const originalMethod = descriptor.value as unknown as (...args: unknown[]) => unknown;
+
+        if (typeof originalMethod !== 'function') {
+            throw new Error(`@NotClient can only be applied to methods, not ${typeof originalMethod}`);
+        }
+
+        descriptor.value = function (this: EntitySystem, ...args: unknown[]): unknown {
+            if (this.scene?.isClient) {
+                return undefined;
+            }
+            return originalMethod.apply(this, args);
+        } as unknown as T;
+
+        return descriptor;
+    };
+}
+
+/**
+ * @zh 非服务端环境方法装饰器
+ * @en Non-server method decorator
+ *
+ * @zh 被装饰的方法在客户端和单机模式下执行，但不在服务端执行。
+ * 用于需要在客户端和单机都运行，但服务端跳过的逻辑（如渲染、音效）。
+ *
+ * @en Decorated methods execute in client and standalone mode, but not on server.
+ * Used for logic that should run on client and standalone, but skip on server (like rendering, audio).
+ *
+ * @example
+ * ```typescript
+ * class AudioSystem extends EntitySystem {
+ *     @NotServer()
+ *     private playSound(): void {
+ *         // 客户端和单机模式执行，服务端跳过
+ *         // Execute on client and standalone, skip on server
+ *     }
+ * }
+ * ```
+ */
+export function NotServer(): MethodDecorator {
+    return function <T>(
+        _target: object,
+        _propertyKey: string | symbol,
+        descriptor: TypedPropertyDescriptor<T>
+    ): TypedPropertyDescriptor<T> | void {
+        const originalMethod = descriptor.value as unknown as (...args: unknown[]) => unknown;
+
+        if (typeof originalMethod !== 'function') {
+            throw new Error(`@NotServer can only be applied to methods, not ${typeof originalMethod}`);
+        }
+
+        descriptor.value = function (this: EntitySystem, ...args: unknown[]): unknown {
+            if (this.scene?.isServer) {
+                return undefined;
+            }
+            return originalMethod.apply(this, args);
+        } as unknown as T;
+
+        return descriptor;
+    };
+}

packages/framework/core/src/ECS/Decorators/index.ts

@@ -82,3 +82,14 @@ export {
     hasSchedulingMetadata,
     SCHEDULING_METADATA
 } from './SystemScheduling';
+
+// ============================================================================
+// Runtime Environment Decorators
+// 运行时环境装饰器
+// ============================================================================
+export {
+    ServerOnly,
+    ClientOnly,
+    NotServer,
+    NotClient
+} from './RuntimeEnvironment';

packages/framework/core/src/ECS/Entity.ts

@@ -7,14 +7,7 @@ import { getComponentInstanceTypeName, getComponentTypeName } from './Decorators
 import { generateGUID } from '../Utils/GUID';
 import type { IScene } from './IScene';
 import { EntityHandle, NULL_HANDLE } from './Core/EntityHandle';
-
-/**
- * @zh 组件活跃状态变化接口
- * @en Interface for component active state change
- */
-interface IActiveChangeable {
-    onActiveChanged(): void;
-}
+import { ECSEventType } from './CoreEvents';
 
 /**
  * @zh 比较两个实体的优先级
@@ -482,9 +475,10 @@ export class Entity {
         }
 
         if (this.scene.eventSystem) {
-            this.scene.eventSystem.emitSync('component:added', {
+            this.scene.eventSystem.emitSync(ECSEventType.COMPONENT_ADDED, {
                 timestamp: Date.now(),
                 source: 'Entity',
+                entity: this,
                 entityId: this.id,
                 entityName: this.name,
                 entityTag: this.tag?.toString(),
@@ -639,7 +633,7 @@ export class Entity {
         component.entityId = null;
 
         if (this.scene?.eventSystem) {
-            this.scene.eventSystem.emitSync('component:removed', {
+            this.scene.eventSystem.emitSync(ECSEventType.COMPONENT_REMOVED, {
                 timestamp: Date.now(),
                 source: 'Entity',
                 entityId: this.id,
@@ -770,19 +764,23 @@ export class Entity {
     }
 
     /**
-     * 活跃状态改变时的回调
+     * @zh 活跃状态改变时的回调
+     * @en Callback when active state changes
+     *
+     * @zh 通过事件系统发出 ENTITY_ENABLED 或 ENTITY_DISABLED 事件，
+     * 组件可以通过监听这些事件来响应实体状态变化。
+     * @en Emits ENTITY_ENABLED or ENTITY_DISABLED event through the event system.
+     * Components can listen to these events to respond to entity state changes.
      */
     private onActiveChanged(): void {
-        for (const component of this.components) {
-            if ('onActiveChanged' in component && typeof component.onActiveChanged === 'function') {
-                (component as IActiveChangeable).onActiveChanged();
-            }
-        }
+        if (this.scene?.eventSystem) {
+            const eventType = this._active
+                ? ECSEventType.ENTITY_ENABLED
+                : ECSEventType.ENTITY_DISABLED;
 
-        if (this.scene && this.scene.eventSystem) {
-            this.scene.eventSystem.emitSync('entity:activeChanged', {
+            this.scene.eventSystem.emitSync(eventType, {
                 entity: this,
-                active: this._active
+                scene: this.scene,
             });
         }
     }
@@ -801,6 +799,15 @@ export class Entity {
 
         this._isDestroyed = true;
 
+        // 在清理之前发出销毁事件（组件仍然可访问）
+        if (this.scene?.eventSystem) {
+            this.scene.eventSystem.emitSync(ECSEventType.ENTITY_DESTROYED, {
+                entity: this,
+                entityId: this.id,
+                scene: this.scene,
+            });
+        }
+
         if (this.scene && this.scene.referenceTracker) {
             this.scene.referenceTracker.clearReferencesTo(this.id);
             this.scene.referenceTracker.unregisterEntityScene(this.id);

packages/framework/core/src/ECS/IScene.ts

@@ -12,6 +12,10 @@ import type { ServiceContainer, ServiceType } from '../Core/ServiceContainer';
 import type { TypedQueryBuilder } from './Core/Query/TypedQuery';
 import type { SceneSerializationOptions, SceneDeserializationOptions } from './Serialization/SceneSerializer';
 import type { IncrementalSnapshot, IncrementalSerializationOptions } from './Serialization/IncrementalSerializer';
+import type { RuntimeEnvironment } from '../Types';
+
+// Re-export for convenience
+export type { RuntimeEnvironment };
 
 /**
  * 场景接口定义
@@ -113,6 +117,27 @@ export type IScene = {
      */
     isEditorMode: boolean;
 
+    /**
+     * @zh 运行时环境
+     * @en Runtime environment
+     *
+     * @zh 标识场景运行在服务端、客户端还是单机模式
+     * @en Indicates whether scene runs on server, client, or standalone mode
+     */
+    readonly runtimeEnvironment: RuntimeEnvironment;
+
+    /**
+     * @zh 是否在服务端运行
+     * @en Whether running on server
+     */
+    readonly isServer: boolean;
+
+    /**
+     * @zh 是否在客户端运行
+     * @en Whether running on client
+     */
+    readonly isClient: boolean;
+
     /**
      * 获取系统列表
      */
@@ -395,4 +420,18 @@ export type ISceneConfig = {
      * @default 10
      */
     maxSystemErrorCount?: number;
+
+    /**
+     * @zh 运行时环境
+     * @en Runtime environment
+     *
+     * @zh 用于区分场景运行在服务端、客户端还是单机模式。
+     * 配合 @ServerOnly / @ClientOnly 装饰器使用，可以让系统方法只在特定环境执行。
+     *
+     * @en Used to distinguish whether scene runs on server, client, or standalone mode.
+     * Works with @ServerOnly / @ClientOnly decorators to make system methods execute only in specific environments.
+     *
+     * @default 'standalone'
+     */
+    runtimeEnvironment?: RuntimeEnvironment;
 }

packages/framework/core/src/ECS/Scene.ts

@@ -12,7 +12,7 @@ import type { IComponentRegistry } from './Core/ComponentStorage';
 import { QuerySystem } from './Core/QuerySystem';
 import { TypeSafeEventSystem } from './Core/EventSystem';
 import { ReferenceTracker } from './Core/ReferenceTracker';
-import { IScene, ISceneConfig } from './IScene';
+import { IScene, ISceneConfig, RuntimeEnvironment } from './IScene';
 import { getComponentInstanceTypeName, getSystemInstanceTypeName, getSystemMetadata, getSystemInstanceMetadata } from './Decorators';
 import { TypedQueryBuilder } from './Core/Query/TypedQuery';
 import {
@@ -180,6 +180,48 @@ export class Scene implements IScene {
      */
     public isEditorMode: boolean = false;
 
+    /**
+     * @zh 场景级别的运行时环境覆盖
+     * @en Scene-level runtime environment override
+     *
+     * @zh 如果未设置，则从 Core.runtimeEnvironment 读取
+     * @en If not set, reads from Core.runtimeEnvironment
+     */
+    private _runtimeEnvironmentOverride: RuntimeEnvironment | undefined;
+
+    /**
+     * @zh 获取运行时环境
+     * @en Get runtime environment
+     *
+     * @zh 优先返回场景级别设置，否则返回 Core 全局设置
+     * @en Returns scene-level setting if set, otherwise returns Core global setting
+     */
+    public get runtimeEnvironment(): RuntimeEnvironment {
+        if (this._runtimeEnvironmentOverride) {
+            return this._runtimeEnvironmentOverride;
+        }
+        // 动态导入避免循环依赖
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { Core } = require('../Core') as typeof import('../Core');
+        return Core.runtimeEnvironment;
+    }
+
+    /**
+     * @zh 是否在服务端运行
+     * @en Whether running on server
+     */
+    public get isServer(): boolean {
+        return this.runtimeEnvironment === 'server';
+    }
+
+    /**
+     * @zh 是否在客户端运行
+     * @en Whether running on client
+     */
+    public get isClient(): boolean {
+        return this.runtimeEnvironment === 'client';
+    }
+
     /**
      * 延迟的组件生命周期回调队列
      *
@@ -398,6 +440,11 @@ export class Scene implements IScene {
         this._logger = createLogger('Scene');
         this._maxErrorCount = config?.maxSystemErrorCount ?? 10;
 
+        // 只有显式指定时才覆盖，否则从 Core 读取
+        if (config?.runtimeEnvironment) {
+            this._runtimeEnvironmentOverride = config.runtimeEnvironment;
+        }
+
         if (config?.name) {
             this.name = config.name;
         }

packages/framework/core/src/ECS/Sync/NetworkEntityDecorator.ts

@@ -0,0 +1,147 @@
+/**
+ * @zh 网络实体装饰器
+ * @en Network entity decorator
+ *
+ * @zh 提供 @NetworkEntity 装饰器，用于标记需要自动广播生成/销毁的组件
+ * @en Provides @NetworkEntity decorator to mark components for automatic spawn/despawn broadcasting
+ */
+
+/**
+ * @zh 网络实体元数据的 Symbol 键
+ * @en Symbol key for network entity metadata
+ */
+export const NETWORK_ENTITY_METADATA = Symbol('NetworkEntityMetadata');
+
+/**
+ * @zh 网络实体元数据
+ * @en Network entity metadata
+ */
+export interface NetworkEntityMetadata {
+    /**
+     * @zh 预制体类型名称（用于客户端重建实体）
+     * @en Prefab type name (used by client to reconstruct entity)
+     */
+    prefabType: string;
+
+    /**
+     * @zh 是否自动广播生成
+     * @en Whether to auto-broadcast spawn
+     * @default true
+     */
+    autoSpawn: boolean;
+
+    /**
+     * @zh 是否自动广播销毁
+     * @en Whether to auto-broadcast despawn
+     * @default true
+     */
+    autoDespawn: boolean;
+}
+
+/**
+ * @zh 网络实体装饰器配置选项
+ * @en Network entity decorator options
+ */
+export interface NetworkEntityOptions {
+    /**
+     * @zh 是否自动广播生成
+     * @en Whether to auto-broadcast spawn
+     * @default true
+     */
+    autoSpawn?: boolean;
+
+    /**
+     * @zh 是否自动广播销毁
+     * @en Whether to auto-broadcast despawn
+     * @default true
+     */
+    autoDespawn?: boolean;
+}
+
+/**
+ * @zh 网络实体装饰器
+ * @en Network entity decorator
+ *
+ * @zh 标记组件类为网络实体。当包含此组件的实体被创建或销毁时，
+ * ECSRoom 会自动广播相应的 spawn/despawn 消息给所有客户端。
+ * @en Marks a component class as a network entity. When an entity containing
+ * this component is created or destroyed, ECSRoom will automatically broadcast
+ * the corresponding spawn/despawn messages to all clients.
+ *
+ * @param prefabType - @zh 预制体类型名称 @en Prefab type name
+ * @param options - @zh 可选配置 @en Optional configuration
+ *
+ * @example
+ * ```typescript
+ * import { Component, ECSComponent, NetworkEntity, sync } from '@esengine/ecs-framework';
+ *
+ * @ECSComponent('Enemy')
+ * @NetworkEntity('Enemy')
+ * class EnemyComponent extends Component {
+ *     @sync('float32') x: number = 0;
+ *     @sync('float32') y: number = 0;
+ *     @sync('uint16') health: number = 100;
+ * }
+ *
+ * // 当添加此组件到实体时，ECSRoom 会自动广播 spawn
+ * const enemy = scene.createEntity('Enemy');
+ * enemy.addComponent(new EnemyComponent()); // 自动广播给所有客户端
+ *
+ * // 当实体销毁时，自动广播 despawn
+ * enemy.destroy(); // 自动广播给所有客户端
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // 只自动广播生成，销毁由手动控制
+ * @ECSComponent('Bullet')
+ * @NetworkEntity('Bullet', { autoDespawn: false })
+ * class BulletComponent extends Component {
+ *     @sync('float32') x: number = 0;
+ *     @sync('float32') y: number = 0;
+ * }
+ * ```
+ */
+export function NetworkEntity(prefabType: string, options?: NetworkEntityOptions) {
+    return function <T extends new (...args: any[]) => any>(target: T): T {
+        const metadata: NetworkEntityMetadata = {
+            prefabType,
+            autoSpawn: options?.autoSpawn ?? true,
+            autoDespawn: options?.autoDespawn ?? true,
+        };
+
+        (target as any)[NETWORK_ENTITY_METADATA] = metadata;
+
+        return target;
+    };
+}
+
+/**
+ * @zh 获取组件类的网络实体元数据
+ * @en Get network entity metadata for a component class
+ *
+ * @param componentClass - @zh 组件类或组件实例 @en Component class or instance
+ * @returns @zh 网络实体元数据，如果不存在则返回 null @en Network entity metadata, or null if not exists
+ */
+export function getNetworkEntityMetadata(componentClass: any): NetworkEntityMetadata | null {
+    if (!componentClass) {
+        return null;
+    }
+
+    const constructor = typeof componentClass === 'function'
+        ? componentClass
+        : componentClass.constructor;
+
+    return constructor[NETWORK_ENTITY_METADATA] || null;
+}
+
+/**
+ * @zh 检查组件是否标记为网络实体
+ * @en Check if a component is marked as a network entity
+ *
+ * @param component - @zh 组件类或组件实例 @en Component class or instance
+ * @returns @zh 如果是网络实体返回 true @en Returns true if is a network entity
+ */
+export function isNetworkEntity(component: any): boolean {
+    return getNetworkEntityMetadata(component) !== null;
+}

packages/framework/core/src/ECS/Sync/index.ts

@@ -51,5 +51,15 @@ export {
     hasChanges
 } from './decorators';
 
+// Network Entity Decorator
+export {
+    NetworkEntity,
+    getNetworkEntityMetadata,
+    isNetworkEntity,
+    NETWORK_ENTITY_METADATA,
+    type NetworkEntityMetadata,
+    type NetworkEntityOptions
+} from './NetworkEntityDecorator';
+
 // Encoding
 export * from './encoding';

packages/framework/core/src/ECS/index.ts

@@ -7,7 +7,7 @@ export * from './Utils';
 export * from './Decorators';
 export * from './Components';
 export { Scene } from './Scene';
-export type { IScene, ISceneFactory, ISceneConfig } from './IScene';
+export type { IScene, ISceneFactory, ISceneConfig, RuntimeEnvironment } from './IScene';
 export { SceneManager } from './SceneManager';
 export { World } from './World';
 export type { IWorldConfig } from './World';

packages/framework/core/src/Types/index.ts

@@ -267,6 +267,12 @@ export type IECSDebugConfig = {
     };
 }
 
+/**
+ * @zh 运行时环境类型
+ * @en Runtime environment type
+ */
+export type RuntimeEnvironment = 'server' | 'client' | 'standalone';
+
 /**
  * Core配置接口
  */
@@ -277,6 +283,16 @@ export type ICoreConfig = {
     debugConfig?: IECSDebugConfig;
     /** WorldManager配置 */
     worldManagerConfig?: IWorldManagerConfig;
+    /**
+     * @zh 运行时环境
+     * @en Runtime environment
+     *
+     * @zh 设置后所有 Scene 默认继承此环境。服务端框架应设置为 'server'，客户端应用设置为 'client'。
+     * @en All Scenes inherit this environment by default. Server frameworks should set 'server', client apps should set 'client'.
+     *
+     * @default 'standalone'
+     */
+    runtimeEnvironment?: RuntimeEnvironment;
 }
 
 /**

packages/framework/fsm/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @esengine/fsm
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+    - @esengine/blueprint@4.0.0
+
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+    - @esengine/blueprint@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+    - @esengine/blueprint@3.0.0
+
 ## 2.0.1
 
 ### Patch Changes

packages/framework/fsm/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/fsm",
-    "version": "2.0.1",
+    "version": "4.0.0",
     "description": "Finite State Machine for ECS Framework / ECS 框架的有限状态机",
     "type": "module",
     "main": "./dist/index.js",

packages/framework/network/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @esengine/network
 
+## 5.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+    - @esengine/blueprint@4.0.0
+
+## 4.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+    - @esengine/blueprint@3.0.1
+
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+    - @esengine/blueprint@3.0.0
+
 ## 3.0.1
 
 ### Patch Changes

packages/framework/network/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/network",
-    "version": "3.0.1",
+    "version": "5.0.0",
     "description": "Network synchronization for multiplayer games",
     "esengine": {
         "plugin": true,

packages/framework/pathfinding/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @esengine/pathfinding
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+    - @esengine/blueprint@4.0.0
+
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+    - @esengine/blueprint@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+    - @esengine/blueprint@3.0.0
+
 ## 2.0.1
 
 ### Patch Changes

packages/framework/pathfinding/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/pathfinding",
-    "version": "2.0.1",
+    "version": "4.0.0",
     "description": "寻路系统 | Pathfinding System - A*, Grid, NavMesh",
     "type": "module",
     "main": "./dist/index.js",

packages/framework/procgen/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @esengine/procgen
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+    - @esengine/blueprint@4.0.0
+
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+    - @esengine/blueprint@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+    - @esengine/blueprint@3.0.0
+
 ## 2.0.1
 
 ### Patch Changes

packages/framework/procgen/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/procgen",
-    "version": "2.0.1",
+    "version": "4.0.0",
     "description": "Procedural generation tools for ECS Framework / ECS 框架的程序化生成工具",
     "type": "module",
     "main": "./dist/index.js",

packages/framework/server/CHANGELOG.md

@@ -1,5 +1,60 @@
 # @esengine/server
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+
+## 3.0.0
+
+### Minor Changes
+
+- feat(ecs): 添加 @NetworkEntity 装饰器，支持自动广播实体生成/销毁
+
+    ### 新功能
+
+    **@NetworkEntity 装饰器**
+    - 标记组件为网络实体，自动广播 spawn/despawn 消息
+    - 支持 `autoSpawn` 和 `autoDespawn` 配置选项
+    - 通过事件系统（`ECSEventType.COMPONENT_ADDED` / `ECSEventType.ENTITY_DESTROYED`）实现
+
+    **ECSRoom 增强**
+    - 新增 `enableAutoNetworkEntity` 配置选项（默认启用）
+    - 自动监听组件添加和实体销毁事件
+    - 简化 GameRoom 实现，无需手动回调
+
+    ### 改进
+
+    **Entity 事件**
+    - `Entity.destroy()` 现在发出 `entity:destroyed` 事件
+    - `Entity.active` 变化时发出 `entity:enabled` / `entity:disabled` 事件
+    - 使用 `ECSEventType` 常量替代硬编码字符串
+
+    ### 使用示例
+
+    ```typescript
+    import { Component, ECSComponent, sync, NetworkEntity } from '@esengine/ecs-framework';
+
+    @ECSComponent('Enemy')
+    @NetworkEntity('Enemy')
+    class EnemyComponent extends Component {
+        @sync('float32') x: number = 0;
+        @sync('float32') y: number = 0;
+    }
+
+    // 服务端
+    const entity = scene.createEntity('Enemy');
+    entity.addComponent(new EnemyComponent()); // 自动广播 spawn
+    entity.destroy(); // 自动广播 despawn
+    ```
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+
 ## 2.0.0
 
 ### Minor Changes

packages/framework/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/server",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "description": "Game server framework for ESEngine with file-based routing",
   "type": "module",
   "main": "./dist/index.js",
@@ -51,7 +51,7 @@
   "peerDependencies": {
     "ws": ">=8.0.0",
     "jsonwebtoken": ">=9.0.0",
-    "@esengine/ecs-framework": ">=2.5.1"
+    "@esengine/ecs-framework": ">=2.7.0"
   },
   "peerDependenciesMeta": {
     "jsonwebtoken": {

packages/framework/server/src/ecs/ECSRoom.ts

@@ -20,6 +20,11 @@ import {
     encodeSpawn,
     encodeDespawn,
     initChangeTracker,
+    // Network Entity
+    NETWORK_ENTITY_METADATA,
+    type NetworkEntityMetadata,
+    // Events
+    ECSEventType,
 } from '@esengine/ecs-framework';
 
 import { Room, type RoomOptions } from '../room/Room.js';
@@ -45,11 +50,19 @@ export interface ECSRoomConfig {
      * @en Whether to enable delta sync
      */
     enableDeltaSync: boolean;
+
+    /**
+     * @zh 是否启用自动网络实体广播（基于 @NetworkEntity 装饰器）
+     * @en Whether to enable automatic network entity broadcasting (based on @NetworkEntity decorator)
+     * @default true
+     */
+    enableAutoNetworkEntity: boolean;
 }
 
 const DEFAULT_ECS_CONFIG: ECSRoomConfig = {
     syncInterval: 50, // 20 Hz
     enableDeltaSync: true,
+    enableAutoNetworkEntity: true,
 };
 
 /**
@@ -116,6 +129,12 @@ export abstract class ECSRoom<TState = any, TPlayerData = Record<string, unknown
      */
     private readonly _playerEntities: Map<string, Entity> = new Map();
 
+    /**
+     * @zh 网络实体映射（实体 ID -> prefabType）
+     * @en Network entity mapping (entity ID -> prefabType)
+     */
+    private readonly _networkEntities: Map<number, string> = new Map();
+
     /**
      * @zh 上次同步时间
      * @en Last sync time
@@ -131,6 +150,47 @@ export abstract class ECSRoom<TState = any, TPlayerData = Record<string, unknown
         this.scene = this.world.createScene('game');
         this.world.setSceneActive('game', true);
         this.world.start();
+
+        // 设置自动网络实体广播
+        if (this.ecsConfig.enableAutoNetworkEntity) {
+            this._setupAutoNetworkEntity();
+        }
+    }
+
+    /**
+     * @zh 设置自动网络实体广播
+     * @en Setup automatic network entity broadcasting
+     */
+    private _setupAutoNetworkEntity(): void {
+        // 监听组件添加事件，自动广播 spawn
+        this.scene.eventSystem.on(ECSEventType.COMPONENT_ADDED, (event: any) => {
+            const { entity, component } = event;
+            const metadata: NetworkEntityMetadata | undefined =
+                (component.constructor as any)[NETWORK_ENTITY_METADATA];
+
+            if (metadata?.autoSpawn) {
+                // 避免重复广播同一实体
+                if (!this._networkEntities.has(entity.id)) {
+                    this._networkEntities.set(entity.id, metadata.prefabType);
+                    this.broadcastSpawn(entity, metadata.prefabType);
+                }
+            }
+
+            // 记录需要自动 despawn 的实体
+            if (metadata?.autoDespawn && !this._networkEntities.has(entity.id)) {
+                this._networkEntities.set(entity.id, metadata.prefabType);
+            }
+        });
+
+        // 监听实体销毁事件，自动广播 despawn
+        this.scene.eventSystem.on(ECSEventType.ENTITY_DESTROYED, (event: any) => {
+            const { entityId } = event;
+            if (this._networkEntities.has(entityId)) {
+                const despawnData = encodeDespawn(entityId);
+                this.broadcastBinary(despawnData);
+                this._networkEntities.delete(entityId);
+            }
+        });
     }
 
     // =========================================================================

packages/framework/spatial/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @esengine/spatial
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+    - @esengine/blueprint@4.0.0
+
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+    - @esengine/blueprint@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+    - @esengine/blueprint@3.0.0
+
 ## 2.0.1
 
 ### Patch Changes

packages/framework/spatial/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/spatial",
-    "version": "2.0.1",
+    "version": "4.0.0",
     "description": "Spatial query and indexing system for ECS Framework / ECS 框架的空间查询和索引系统",
     "type": "module",
     "main": "./dist/index.js",

packages/framework/timer/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @esengine/timer
 
+## 4.0.0
+
+### Patch Changes
+
+- Updated dependencies [[`1f3a76a`](https://github.com/esengine/esengine/commit/1f3a76aabea2d3eb8a5eb8b73e29127da57e2028)]:
+    - @esengine/ecs-framework@2.7.0
+    - @esengine/blueprint@4.0.0
+
+## 3.0.1
+
+### Patch Changes
+
+- Updated dependencies [[`04b08f3`](https://github.com/esengine/esengine/commit/04b08f3f073d69beb8f4be399c774bea0acb612e)]:
+    - @esengine/ecs-framework@2.6.1
+    - @esengine/blueprint@3.0.1
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/ecs-framework@2.6.0
+    - @esengine/blueprint@3.0.0
+
 ## 2.0.1
 
 ### Patch Changes

packages/framework/timer/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/timer",
-    "version": "2.0.1",
+    "version": "4.0.0",
     "description": "Timer and cooldown system for ECS Framework / ECS 框架的定时器和冷却系统",
     "type": "module",
     "main": "./dist/index.js",

packages/framework/transaction/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @esengine/transaction
 
+## 2.0.5
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/server@4.0.0
+
+## 2.0.4
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/server@3.0.0
+
 ## 2.0.3
 
 ### Patch Changes

packages/framework/transaction/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/transaction",
-    "version": "2.0.3",
+    "version": "2.0.5",
     "description": "Game transaction system with distributed support | 游戏事务系统，支持分布式事务",
     "type": "module",
     "main": "./dist/index.js",

packages/physics/physics-rapier2d/src/loaders/WeChatRapier2DLoader.ts

@@ -121,9 +121,9 @@ export class WeChatRapier2DLoader implements IWasmLibraryLoader<RapierModule> {
             // 导入 Rapier2D 标准版
             const RAPIER = await import('@esengine/rapier2d');
 
-            // 初始化 WASM - 标准版需要提供 WASM 路径
-            const wasmPath = this._config.minigame?.wasmPath || 'wasm/rapier_wasm2d_bg.wasm';
-            await RAPIER.init(wasmPath);
+            // 初始化 WASM - WASM 已经作为 base64 嵌入到包中
+            // Initialize WASM - WASM is embedded as base64 in the package
+            await RAPIER.init();
 
             return RAPIER;
         } finally {

packages/physics/physics-rapier2d/src/loaders/WebRapier2DLoader.ts

@@ -53,10 +53,9 @@ export class WebRapier2DLoader implements IWasmLibraryLoader<RapierModule> {
         // 动态导入标准版
         const RAPIER = await import('@esengine/rapier2d');
 
-        // 初始化 WASM - 标准版需要提供 WASM 路径
-        // 构建时 WASM 文件会被复制到 wasm/ 目录
-        const wasmPath = this._config.web?.wasmPath || 'wasm/rapier_wasm2d_bg.wasm';
-        await RAPIER.init(wasmPath);
+        // 初始化 WASM - WASM 已经作为 base64 嵌入到包中
+        // Initialize WASM - WASM is embedded as base64 in the package
+        await RAPIER.init();
 
         console.log(`[${this._config.name}] 加载完成`);
         return RAPIER;

packages/physics/rapier2d/package.json

@@ -19,11 +19,13 @@
   ],
   "scripts": {
     "gen:src": "node scripts/gen-src.mjs",
-    "build": "pnpm gen:src && tsup",
-    "clean": "rimraf dist src"
+    "build": "tsup",
+    "build:regen": "pnpm gen:src && tsup",
+    "clean": "rimraf dist"
   },
   "license": "Apache-2.0",
   "devDependencies": {
+    "base64-js": "^1.5.1",
     "rimraf": "^5.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.0.0"

packages/physics/rapier2d/src/control/character_controller.ts

@@ -91,9 +91,8 @@ export class KinematicCharacterController {
      */
     public setUp(vector: Vector) {
         let rawVect = VectorOps.intoRaw(vector);
-        const result = this.raw.setUp(rawVect);
+        return this.raw.setUp(rawVect);
         rawVect.free();
-        return result;
     }
 
     public applyImpulsesToDynamicBodies(): boolean {

packages/physics/rapier2d/src/control/ray_cast_vehicle_controller.ts

@@ -28,9 +28,6 @@ export class DynamicRayCastVehicleController {
         bodies: RigidBodySet,
         colliders: ColliderSet,
     ) {
-        if (typeof RawDynamicRayCastVehicleController === 'undefined') {
-            throw new Error('DynamicRayCastVehicleController is not available in 2D mode');
-        }
         this.raw = new RawDynamicRayCastVehicleController(chassis.handle);
         this.broadPhase = broadPhase;
         this.narrowPhase = narrowPhase;

packages/physics/rapier2d/src/init.ts

@@ -1,60 +1,12 @@
-/**
- * RAPIER initialization module with dynamic WASM loading support.
- * RAPIER 初始化模块，支持动态 WASM 加载。
- */
-
+// @ts-ignore
+import wasmBase64 from "../pkg/rapier_wasm2d_bg.wasm";
 import wasmInit from "../pkg/rapier_wasm2d";
-
-/**
- * Input types for WASM initialization.
- * WASM 初始化的输入类型。
- */
-export type InitInput =
-    | RequestInfo         // URL string or Request object
-    | URL                 // URL object
-    | Response            // Fetch Response object
-    | BufferSource        // ArrayBuffer or TypedArray
-    | WebAssembly.Module; // Pre-compiled module
-
-let initialized = false;
+import base64 from "base64-js";
 
 /**
  * Initializes RAPIER.
  * Has to be called and awaited before using any library methods.
- *
- * 初始化 RAPIER。
- * 必须在使用任何库方法之前调用并等待。
- *
- * @param input - WASM source (required). Can be URL, Response, ArrayBuffer, etc.
- *                WASM 源（必需）。可以是 URL、Response、ArrayBuffer 等。
- *
- * @example
- * // Load from URL | 从 URL 加载
- * await RAPIER.init('wasm/rapier_wasm2d_bg.wasm');
- *
- * @example
- * // Load from fetch response | 从 fetch 响应加载
- * const response = await fetch('wasm/rapier_wasm2d_bg.wasm');
- * await RAPIER.init(response);
- *
- * @example
- * // Load from ArrayBuffer | 从 ArrayBuffer 加载
- * const buffer = await fetch('wasm/rapier_wasm2d_bg.wasm').then(r => r.arrayBuffer());
- * await RAPIER.init(buffer);
  */
-export async function init(input?: InitInput): Promise<void> {
-    if (initialized) {
-        return;
-    }
-
-    await wasmInit(input);
-    initialized = true;
-}
-
-/**
- * Check if RAPIER is already initialized.
- * 检查 RAPIER 是否已初始化。
- */
-export function isInitialized(): boolean {
-    return initialized;
+export async function init() {
+    await wasmInit(base64.toByteArray(wasmBase64 as unknown as string).buffer);
 }

packages/physics/rapier2d/src/math.ts

@@ -28,7 +28,7 @@ export class VectorOps {
     }
 
     // FIXME: type ram: RawVector?
-    public static fromRaw(raw: RawVector): Vector | null {
+    public static fromRaw(raw: RawVector): Vector {
         if (!raw) return null;
 
         let res = VectorOps.new(raw.x, raw.y);
@@ -56,7 +56,7 @@ export class RotationOps {
         return 0.0;
     }
 
-    public static fromRaw(raw: RawRotation): Rotation | null {
+    public static fromRaw(raw: RawRotation): Rotation {
         if (!raw) return null;
 
         let res = raw.angle;

packages/physics/rapier2d/tsup.config.ts

@@ -7,4 +7,7 @@ export default defineConfig({
     sourcemap: true,
     clean: true,
     external: ["../pkg/rapier_wasm2d.js"],
+    loader: {
+        ".wasm": "base64",
+    },
 });

packages/tools/demos/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @esengine/demos
 
+## 1.0.9
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/fsm@4.0.0
+    - @esengine/pathfinding@4.0.0
+    - @esengine/procgen@4.0.0
+    - @esengine/spatial@4.0.0
+    - @esengine/timer@4.0.0
+
+## 1.0.8
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/fsm@3.0.1
+    - @esengine/pathfinding@3.0.1
+    - @esengine/procgen@3.0.1
+    - @esengine/spatial@3.0.1
+    - @esengine/timer@3.0.1
+
+## 1.0.7
+
+### Patch Changes
+
+- Updated dependencies []:
+    - @esengine/fsm@3.0.0
+    - @esengine/pathfinding@3.0.0
+    - @esengine/procgen@3.0.0
+    - @esengine/spatial@3.0.0
+    - @esengine/timer@3.0.0
+
 ## 1.0.6
 
 ### Patch Changes

packages/tools/demos/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@esengine/demos",
-    "version": "1.0.6",
+    "version": "1.0.9",
     "private": true,
     "description": "Demo tests for ESEngine modules documentation",
     "type": "module",

pnpm-lock.yaml

@@ -569,6 +569,9 @@ importers:
         specifier: workspace:*
         version: link:../../../framework/behavior-tree
     devDependencies:
+      '@esengine/asset-system':
+        specifier: workspace:*
+        version: link:../../../engine/asset-system
       '@esengine/build-config':
         specifier: workspace:*
         version: link:../../../tools/build-config
@@ -1489,6 +1492,9 @@ importers:
       rollup-plugin-dts:
         specifier: ^6.2.1
         version: 6.3.0(rollup@4.54.0)(typescript@5.9.3)
+      rollup-plugin-sourcemaps:
+        specifier: ^0.6.3
+        version: 0.6.3(@types/node@20.19.27)(rollup@4.54.0)
       ts-jest:
         specifier: ^29.4.0
         version: 29.4.6(@babel/core@7.28.5)(@jest/transform@29.7.0)(@jest/types@29.6.3)(babel-jest@29.7.0(@babel/core@7.28.5))(jest-util@29.7.0)(jest@29.7.0(@types/node@20.19.27)(ts-node@10.9.2(@swc/core@1.15.7(@swc/helpers@0.5.18))(@swc/wasm@1.15.7)(@types/node@20.19.27)(typescript@5.9.3)))(typescript@5.9.3)
@@ -1861,6 +1867,9 @@ importers:
 
   packages/physics/rapier2d:
     devDependencies:
+      base64-js:
+        specifier: ^1.5.1
+        version: 1.5.1
       rimraf:
         specifier: ^5.0.0
         version: 5.0.10
@@ -4484,6 +4493,12 @@ packages:
       rollup:
         optional: true
 
+  '@rollup/pluginutils@3.1.0':
+    resolution: {integrity: sha512-GksZ6pr6TpIjHm8h9lSQ8pi8BE9VeubNT0OMJ3B5uZJ8pz73NPiqOtCog/x2/QzM1ENChPKxMDhiQuRHsqc+lg==}
+    engines: {node: '>= 8.0.0'}
+    peerDependencies:
+      rollup: ^1.20.0||^2.0.0
+
   '@rollup/pluginutils@5.3.0':
     resolution: {integrity: sha512-5EdhGZtnu3V88ces7s53hhfK5KSASnJZv8Lulpc04cWO3REESroJXg73DFsOmgbU2BhwV0E20bu2IDZb3VKW4Q==}
     engines: {node: '>=14.0.0'}
@@ -5150,6 +5165,9 @@ packages:
   '@types/estree-jsx@1.0.5':
     resolution: {integrity: sha512-52CcUVNFyfb1A2ALocQw/Dd1BQFNmSdkuC3BkZ6iqhdMfQz7JWOFRuJFloOzjk+6WijU56m9oKXFAXc7o3Towg==}
 
+  '@types/estree@0.0.39':
+    resolution: {integrity: sha512-EYNwp3bU+98cpU4lAWYYL7Zz+2gryWH1qbdDTidVd6hkiR6weksdbMadyXKXNPEkQFhXM+hVO9ZygomHXp+AIw==}
+
   '@types/estree@1.0.8':
     resolution: {integrity: sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==}
 
@@ -5791,6 +5809,11 @@ packages:
   asynckit@0.4.0:
     resolution: {integrity: sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==}
 
+  atob@2.1.2:
+    resolution: {integrity: sha512-Wm6ukoaOGJi/73p/cl2GvLjTI5JM1k/O14isD73YML8StrH/7/lRFgmg8nICZgD3bZZvjwCGxtMOD3wWNAu8cg==}
+    engines: {node: '>= 4.5.0'}
+    hasBin: true
+
   axios@1.13.2:
     resolution: {integrity: sha512-VPk9ebNqPcy5lRGuSlKx752IlDatOjT9paPlm8A7yOuW2Fbvp4X3JznJtT4f0GzGLLiWE9W8onz51SqLYwzGaA==}
 
@@ -6434,6 +6457,10 @@ packages:
   decode-named-character-reference@1.2.0:
     resolution: {integrity: sha512-c6fcElNV6ShtZXmsgNgFFV5tVX2PaV4g+MOAkb8eXHvn6sryJBrZa9r0zV6+dtTyoCKxtDy5tyQ5ZwQuidtd+Q==}
 
+  decode-uri-component@0.2.2:
+    resolution: {integrity: sha512-FqUYQ+8o158GyGTrMFJms9qh3CqTKvAqgqsTnkLI8sKu0028orqBhxNMFkFen0zGyg6epACD32pjVk58ngIErQ==}
+    engines: {node: '>=0.10'}
+
   dedent@1.5.3:
     resolution: {integrity: sha512-NHQtfOOW68WD8lgypbLA5oT+Bt0xXJhiYvoR6SmmNXZfpzOGXwdKWmcwG8N7PwVVWV3eF/68nmD9BaJSsTBhyQ==}
     peerDependencies:
@@ -6838,6 +6865,9 @@ packages:
   estree-util-visit@2.0.0:
     resolution: {integrity: sha512-m5KgiH85xAhhW8Wta0vShLcUvOsh3LLPI2YVwcbio1l7E09NTLL1EyMZFM1OyWowoH0skScNbhOPl4kcBgzTww==}
 
+  estree-walker@1.0.1:
+    resolution: {integrity: sha512-1fMXF3YP4pZZVozF8j/ZLfvnR8NSIljt56UhbZ5PeeDmmGHpgpdwQt7ITlGvYaQukCvuBRMLEiKiYC+oeIg4cg==}
+
   estree-walker@2.0.2:
     resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==}
 
@@ -9844,6 +9874,16 @@ packages:
       rollup: ^3.29.4 || ^4
       typescript: ^4.5 || ^5.0
 
+  rollup-plugin-sourcemaps@0.6.3:
+    resolution: {integrity: sha512-paFu+nT1xvuO1tPFYXGe+XnQvg4Hjqv/eIhG8i5EspfYYPBKL57X7iVbfv55aNVASg3dzWvES9dmWsL2KhfByw==}
+    engines: {node: '>=10.0.0'}
+    peerDependencies:
+      '@types/node': '>=10.0.0'
+      rollup: '>=0.31.2'
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+
   rollup@4.54.0:
     resolution: {integrity: sha512-3nk8Y3a9Ea8szgKhinMlGMhGMw89mqule3KWczxhIzqudyHdCIOHw8WJlj/r329fACjKLEh13ZSk7oE22kyeIw==}
     engines: {node: '>=18.0.0', npm: '>=8.0.0'}
@@ -10043,6 +10083,10 @@ packages:
     resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==}
     engines: {node: '>=0.10.0'}
 
+  source-map-resolve@0.6.0:
+    resolution: {integrity: sha512-KXBr9d/fO/bWo97NXsPIAW1bFSBOuCnjbNTBMO7N59hsv5i9yzRDfcYwwt0l04+VqnKC+EwzvJZIP/qkuMgR/w==}
+    deprecated: See https://github.com/lydell/source-map-resolve#deprecated
+
   source-map-support@0.5.13:
     resolution: {integrity: sha512-SHSKFHadjVA5oR4PPqhtAVdcBWwRYVd6g6cAXnIbRiIwc2EhPrTuKUBdSLvlEKyIP3GCf89fltvcZiP9MMFA1w==}
 
@@ -14128,6 +14172,13 @@ snapshots:
     optionalDependencies:
       rollup: 4.54.0
 
+  '@rollup/pluginutils@3.1.0(rollup@4.54.0)':
+    dependencies:
+      '@types/estree': 0.0.39
+      estree-walker: 1.0.1
+      picomatch: 2.3.1
+      rollup: 4.54.0
+
   '@rollup/pluginutils@5.3.0(rollup@4.54.0)':
     dependencies:
       '@types/estree': 1.0.8
@@ -14878,6 +14929,8 @@ snapshots:
     dependencies:
       '@types/estree': 1.0.8
 
+  '@types/estree@0.0.39': {}
+
   '@types/estree@1.0.8': {}
 
   '@types/express-serve-static-core@5.1.0':
@@ -15745,6 +15798,8 @@ snapshots:
 
   asynckit@0.4.0: {}
 
+  atob@2.1.2: {}
+
   axios@1.13.2:
     dependencies:
       follow-redirects: 1.15.11
@@ -16424,6 +16479,8 @@ snapshots:
     dependencies:
       character-entities: 2.0.2
 
+  decode-uri-component@0.2.2: {}
+
   dedent@1.5.3: {}
 
   dedent@1.7.1: {}
@@ -16874,6 +16931,8 @@ snapshots:
       '@types/estree-jsx': 1.0.5
       '@types/unist': 3.0.3
 
+  estree-walker@1.0.1: {}
+
   estree-walker@2.0.2: {}
 
   estree-walker@3.0.3:
@@ -20696,6 +20755,14 @@ snapshots:
     optionalDependencies:
       '@babel/code-frame': 7.27.1
 
+  rollup-plugin-sourcemaps@0.6.3(@types/node@20.19.27)(rollup@4.54.0):
+    dependencies:
+      '@rollup/pluginutils': 3.1.0(rollup@4.54.0)
+      rollup: 4.54.0
+      source-map-resolve: 0.6.0
+    optionalDependencies:
+      '@types/node': 20.19.27
+
   rollup@4.54.0:
     dependencies:
       '@types/estree': 1.0.8
@@ -20990,6 +21057,11 @@ snapshots:
 
   source-map-js@1.2.1: {}
 
+  source-map-resolve@0.6.0:
+    dependencies:
+      atob: 2.1.2
+      decode-uri-component: 0.2.2
+
   source-map-support@0.5.13:
     dependencies:
       buffer-from: 1.1.2